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 "GetSize(foobar)" instead
  65 of "foobar.size()". (GetSize() is defined by kernel/yosys.h)
  66
  67 Use range-based for loops whenever applicable.
  68
  69
  70
  71 Creating the Visual Studio Template Project
  72 ===========================================
  73
  74 1. Create an empty Visual C++ Win32 Console App project
  75
  76         Microsoft Visual Studio Express 2013 for Windows Desktop
  77         Open New Project Wizard (File -> New Project..)
  78
  79         Project Name: YosysVS
  80         Solution Name: YosysVS
  81         [X] Create directory for solution
  82         [ ] Add to source control
  83
  84         [X] Console applications
  85         [X] Empty Projcect
  86         [ ] SDL checks
  87
  88 2. Open YosysVS Project Properties
  89
  90         Select Configuration: All Configurations
  91
  92         C/C++ -> General -> Additional Include Directories
  93                 Add: ..\yosys
  94
  95         C/C++ -> Preprocessor -> Preprocessor Definitions
  96                 Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
  97
  98 3. Resulting file system tree:
  99
 100         YosysVS/
 101         YosysVS/YosysVS
 102         YosysVS/YosysVS/YosysVS.vcxproj
 103         YosysVS/YosysVS/YosysVS.vcxproj.filters
 104         YosysVS/YosysVS.sdf
 105         YosysVS/YosysVS.sln
 106         YosysVS/YosysVS.v12.suo
 107
 108 4. Zip YosysVS as YosysVS-Tpl-v1.zip
 109
 110
 111
 112 Checklist for adding internal cell types
 113 ========================================
 114
 115 Things to do right away:
 116
 117         - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
 118         - Add to InternalCellChecker::check() in kernel/rtlil.cc
 119         - Add to techlibs/common/simlib.v
 120         - Add to techlibs/common/techmap.v
 121
 122 Things to do after finalizing the cell interface:
 123
 124         - Add support to kernel/satgen.h for the new cell type
 125         - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
 126         - Maybe add support to the verilog backend for dumping such cells as expression
 127
 128
 129
 130 Checklist for creating Yosys releases
 131 =====================================
 132
 133 Update the CHANGELOG file:
 134
 135         cd ~yosys
 136         gitk &
 137         vi CHANGELOG
 138
 139
 140 Run all tests with "make config-{clang-debug,gcc-debug,gcc-4.6,release}":
 141
 142         cd ~yosys
 143         make clean
 144         make test vloghtb
 145         make install
 146
 147         cd ~yosys-bigsim
 148         make clean
 149         make full
 150
 151         cd ~vloghammer
 152         make purge
 153         make gen_issues gen_samples
 154         make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" FULL=1 world
 155         chromium-browser report.html
 156
 157
 158 Then with default config setting:
 159
 160         cd ~yosys
 161         ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
 162         ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
 163
 164         cd ~yosys
 165         make manual
 166         - sanity check the figures in the appnotes and presentation
 167             - if there are any odd things -> investigate
 168             - make cosmetic changes to the .tex files if necessary
 169
 170
 171 Also with default config setting:
 172
 173         cd ~yosys/techlibs/cmos
 174         bash testbench.sh
 175
 176         cd ~yosys/techlibs/xilinx/example_sim_counter
 177         bash run_sim.sh
 178
 179         cd ~yosys/techlibs/xilinx/example_mojo_counter
 180         bash example.sh
 181
 182
 183 Finally if a current verific library is available:
 184
 185         cd ~yosys
 186         cat frontends/verific/build_amd64.txt
 187         - follow instructions
 188
 189         cd frontends/verific
 190         ../../yosys test_navre.ys
 191
 192
 193 Release candiate:
 194
 195         - create branch yosys-x.y.z-rc and push to github
 196         - contact the usual suspects per mail and ask them to test
 197         - post on the reddit and ask people to test
 198         - commit KISS fixes to the -rc branch if necessary
 199
 200
 201 Release:
 202
 203         - set YOSYS_VER to x.y.z in Makefile
 204         - update version string in CHANGELOG
 205         git commit -am "Yosys x.y.z"
 206
 207         - push tag to github
 208         - post changelog on github
 209         - post short release note on reddit
 210         - delete -rc branch from github
 211
 212
 213 Updating the website:
 214
 215         cd ~yosys
 216         make manual
 217         make install
 218
 219         - update pdf files on the website
 220
 221         cd ~yosys-web
 222         make update_cmd
 223         make update_show
 224         git commit -am update
 225         make push
 226
 227
 228 In master branch:
 229
 230         git merge {release-tag}
 231         - set version to x.y.z+ in Makefile
 232         - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG
 233         git commit --amend -am "Yosys x.y.z+"
 234
 235