CodingReadme

   1
   2
   3 Getting Started
   4 ===============
   5
   6
   7 Reading List
   8 ------------
   9
  10 To write Yosys C++ code you need to know at least the following classes in kernel/rtlil.h:
  11
  12         RTLIL::Wire
  13         RTLIL::Cell
  14         RTLIL::Module
  15         RTLIL::SigSpec
  16
  17 The following yosys commands are a good starting point if you are looking for examples
  18 of how to use the Yosys API:
  19
  20         passes/opt/wreduce.cc
  21         passes/techmap/maccmap.cc
  22
  23
  24 Notes on the existing codebase
  25 ------------------------------
  26
  27 For historical reasons not all parts of Yosys adhere to the current coding
  28 styles.  When adding code to existing parts of the system, adhere to this guide
  29 for the new code instead of trying to mimic the style of the surrounding code.
  30
  31
  32
  33 Coding Style
  34 ============
  35
  36
  37 Formatting of code
  38 ------------------
  39
  40 - Yosys code is using tabs for indentation. Tabs are 8 characters.
  41
  42 - A continuation of a statement in the following line is indented by
  43   two additional tabs.
  44
  45 - Lines are as long as you want them to be. A good rule of thumb is
  46   to break lines at about column 150.
  47
  48 - Opening braces can be put on the same or next line as the statement
  49   opening the block (if, switch, for, while, do). Put the opening brace
  50   on its own line for larger blocks, especially blocks that contains
  51   blank lines.
  52
  53 - Otherwise stick to the Linux Kernel Coding Stlye:
  54     https://www.kernel.org/doc/Documentation/CodingStyle
  55
  56
  57 C++ Langugage
  58 -------------
  59
  60 Yosys is written in C++11. At the moment only constructs supported by
  61 gcc 4.6 is allowed in Yosys code. This will change in future releases.
  62
  63 In general Yosys uses "int" instead of "size_t". To avoid compiler
  64 warnings for implicit type casts, always use "SIZE(foobar)" instead
  65 of "foobar.size()". (the macro SIZE() is defined by kernel/yosys.h)
  66
  67 Use range-based for loops whenever applicable.
  68
  69
  70
  71 Checklist for adding internal cell types
  72 ========================================
  73
  74 Things to do right away:
  75
  76         - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
  77         - Add to InternalCellChecker::check() in kernel/rtlil.cc
  78         - Add to techlibs/common/simlib.v
  79         - Add to techlibs/common/techmap.v
  80
  81 Things to do after finalizing the cell interface:
  82
  83         - Add support to kernel/satgen.h for the new cell type
  84         - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
  85         - Maybe add support to the verilog backend for dumping such cells as expression
  86
  87
  88
  89 Checklist for creating Yosys releases
  90 =====================================
  91
  92 Update the CHANGELOG file:
  93
  94         cd ~yosys
  95         gitk &
  96         vi CHANGELOG
  97
  98
  99 Run all tests with "make config-{clang-debug,gcc-debug,gcc-4.6,release}":
 100
 101         cd ~yosys
 102         make clean
 103         make test vloghtb
 104         make install
 105
 106         cd ~yosys-bigsim
 107         make clean
 108         make full
 109
 110         cd ~vloghammer
 111         make purge
 112         make gen_issues gen_samples
 113         make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" FULL=1 world
 114         chromium-browser report.html
 115
 116
 117 Then with default config setting:
 118
 119         cd ~yosys
 120         ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
 121         ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
 122
 123         cd ~yosys
 124         make manual
 125         - sanity check the figures in the appnotes and presentation
 126             - if there are any odd things -> investigate
 127             - make cosmetic changes to the .tex files if necessary
 128
 129
 130 Also with default config setting:
 131
 132         cd ~yosys/techlibs/cmos
 133         bash testbench.sh
 134
 135         cd ~yosys/techlibs/xilinx/example_sim_counter
 136         bash run_sim.sh
 137
 138         cd ~yosys/techlibs/xilinx/example_mojo_counter
 139         bash example.sh
 140
 141
 142 Finally if a current verific library is available:
 143
 144         cd ~yosys
 145         cat frontends/verific/build_amd64.txt
 146         - follow instructions
 147
 148         cd frontends/verific
 149         ../../yosys test_navre.ys
 150
 151
 152 Release candiate:
 153
 154         - create branch yosys-x.y.z-rc and push to github
 155         - contact the usual suspects per mail and ask them to test
 156         - post on the reddit and ask people to test
 157         - commit KISS fixes to the -rc branch if necessary
 158
 159
 160 Release:
 161
 162         - set YOSYS_VER to x.y.z in Makefile
 163         - update version string in CHANGELOG
 164         git commit -am "Yosys x.y.z"
 165
 166         - push tag to github
 167         - post changelog on github
 168         - post short release note on reddit
 169         - delete -rc branch from github
 170
 171
 172 Updating the website:
 173
 174         cd ~yosys
 175         make manual
 176         make install
 177
 178         - update pdf files on the website
 179
 180         cd ~yosys-web
 181         make update_cmd
 182         make update_show
 183         git commit -am update
 184         make push
 185
 186
 187 In master branch:
 188
 189         git merge {release-tag}
 190         - set version to x.y.z+ in Makefile
 191         - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG
 192         git commit --amend -am "Yosys x.y.z+"
 193
 194