CodingReadme

   1
   2 This file contains some very brief documentation on things like programming APIs.
   3 Also consult the Yosys manual and the section about programming in the presentation.
   4 (Both can be downloaded as PDF from the yosys webpage.)
   5
   6
   7 --snip-- only the lines below this mark are included in the yosys manual --snip--
   8 Getting Started
   9 ===============
  10
  11
  12 Outline of a Yosys command
  13 --------------------------
  14
  15 Here is a the C++ code for a "hello_world" Yosys command (hello.cc):
  16
  17         #include "kernel/yosys.h"
  18
  19         USING_YOSYS_NAMESPACE
  20         PRIVATE_NAMESPACE_BEGIN
  21
  22         struct HelloWorldPass : public Pass {
  23                 HelloWorldPass() : Pass("hello_world") { }
  24                 virtual void execute(vector<string>, Design*) {
  25                         log("Hello World!\n");
  26                 }
  27         } HelloWorldPass;
  28
  29         PRIVATE_NAMESPACE_END
  30
  31 This can be built into a Yosys module using the following command:
  32
  33         yosys-config --exec --cxx --cxxflags --ldflags -o hello.so -shared hello.cc --ldlibs
  34
  35 And then executed using the following command:
  36
  37         yosys -m hello.so -p hello_world
  38
  39
  40 Yosys Data Structures
  41 ---------------------
  42
  43 Here is a short list of data structures that you should make yourself familiar
  44 with before you write C++ code for Yosys. The following data structures are all
  45 defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used.
  46
  47   1. Yosys Container Classes
  48
  49 Yosys uses dict<K, T> and pool<T> as main container classes. dict<K, T> is
  50 essentially a replacement for std::unordered_map<K, T> and pool<T> is a
  51 replacement for std::unordered_set<T>. The main characteristics are:
  52
  53         - dict<K, T> and pool<T> are about 2x faster than the std containers
  54
  55         - references to elements in a dict<K, T> or pool<T> are invalidated by
  56           insert and remove operations (similar to std::vector<T> on push_back()).
  57
  58         - some iterators are invalidated by erase(). specifically, iterators
  59           that have not passed the erased element yet are invalidated. (erase()
  60           itself returns valid iterator to the next element.)
  61
  62         - no iterators are invalidated by insert(). elements are inserted at
  63           begin(). i.e. only a new iterator that starts at begin() will see the
  64           inserted elements.
  65
  66         - the method .count(key, iterator) is like .count(key) but only
  67           considers elements that can be reached via the iterator.
  68
  69         - iterators can be compared. it1 < it2 means that the position of t2
  70           can be reached via t1 but not vice versa.
  71
  72         - dict<K, T> and pool<T> will have the same order of iteration across
  73           all compilers, standard libraries and architectures.
  74
  75   2. Standard STL data types
  76
  77 In Yosys we use std::vector<T> and std::string whenever applicable. When
  78 dict<K, T> and pool<T> are not suitable then std::map<K, T> and std::set<T>
  79 are used instead.
  80
  81 The types std::vector<T> and std::string are also available as vector<T>
  82 and string in the Yosys namespace.
  83
  84   3. RTLIL objects
  85
  86 The current design (essentially a collection of modules, each defined by a
  87 netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h,
  88 automatically included by kernel/yosys.h). You should glance over at least
  89 the declarations for the following types in kernel/rtlil.h:
  90
  91         RTLIL::IdString
  92                 This is a handle for an identifier (e.g. cell or wire name).
  93                 It feels a lot like a std::string, but is only a single int
  94                 in size. (The actual string is stored in a global lookup
  95                 table.)
  96
  97         RTLIL::SigBit
  98                 A single signal bit. I.e. either a constant (0, 1, x, z) or
  99                 a single bit from a wire.
 100
 101         RTLIL::SigSpec
 102                 Essentially a vector of SigBits.
 103
 104         RTLIL::Wire
 105         RTLIL::Cell
 106                 The building blocks of the netlist in a module.
 107
 108         RTLIL::Module
 109         RTLIL::Design
 110                 The module is a container with connected cells and wires
 111                 in it. The design is a container with modules in it.
 112
 113 All this types are also available without the RTLIL:: prefix in the Yosys
 114 namespace.
 115
 116   4. SigMap and other Helper Classes
 117
 118 There are a couple of additional helper classes that are in wide use
 119 in Yosys. Most importantly there is SigMap (declared in kernel/sigtools.h).
 120
 121 When a design has many wires in it that are connected to each other, then a
 122 single signal bit can have multiple valid names. The SigMap object can be used
 123 to map SigSpecs or SigBits to unique SigSpecs and SigBits that consitently
 124 only use one wire from such a group of connected wires. For example:
 125
 126         SigBit a = module->addWire(NEW_ID);
 127         SigBit b = module->addWire(NEW_ID);
 128         module->connect(a, b);
 129
 130         log("%d\n", a == b); // will print 0
 131
 132         SigMap sigmap(module);
 133         log("%d\n", sigmap(a) == sigmap(b)); // will print 1
 134
 135
 136 Example Code
 137 ------------
 138
 139 The following yosys commands are a good starting point if you are looking for examples
 140 of how to use the Yosys API:
 141
 142         manual/CHAPTER_Prog/stubnets.cc
 143         passes/opt/wreduce.cc
 144         passes/techmap/maccmap.cc
 145
 146
 147 Notes on the existing codebase
 148 ------------------------------
 149
 150 For historical reasons not all parts of Yosys adhere to the current coding
 151 style. When adding code to existing parts of the system, adhere to this guide
 152 for the new code instead of trying to mimic the style of the surrounding code.
 153
 154
 155
 156 Coding Style
 157 ============
 158
 159
 160 Formatting of code
 161 ------------------
 162
 163 - Yosys code is using tabs for indentation. Tabs are 8 characters.
 164
 165 - A continuation of a statement in the following line is indented by
 166   two additional tabs.
 167
 168 - Lines are as long as you want them to be. A good rule of thumb is
 169   to break lines at about column 150.
 170
 171 - Opening braces can be put on the same or next line as the statement
 172   opening the block (if, switch, for, while, do). Put the opening brace
 173   on its own line for larger blocks, especially blocks that contains
 174   blank lines.
 175
 176 - Otherwise stick to the Linux Kernel Coding Stlye:
 177     https://www.kernel.org/doc/Documentation/CodingStyle
 178
 179
 180 C++ Langugage
 181 -------------
 182
 183 Yosys is written in C++11. At the moment only constructs supported by
 184 gcc 4.6 are allowed in Yosys code. This will change in future releases.
 185
 186 In general Yosys uses "int" instead of "size_t". To avoid compiler
 187 warnings for implicit type casts, always use "GetSize(foobar)" instead
 188 of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
 189
 190 Use range-based for loops whenever applicable.
 191
 192
 193 --snap-- only the lines above this mark are included in the yosys manual --snap--
 194
 195
 196 Creating the Visual Studio Template Project
 197 ===========================================
 198
 199 1. Create an empty Visual C++ Win32 Console App project
 200
 201         Microsoft Visual Studio Express 2013 for Windows Desktop
 202         Open New Project Wizard (File -> New Project..)
 203
 204         Project Name: YosysVS
 205         Solution Name: YosysVS
 206         [X] Create directory for solution
 207         [ ] Add to source control
 208
 209         [X] Console applications
 210         [X] Empty Projcect
 211         [ ] SDL checks
 212
 213 2. Open YosysVS Project Properties
 214
 215         Select Configuration: All Configurations
 216
 217         C/C++ -> General -> Additional Include Directories
 218                 Add: ..\yosys
 219
 220         C/C++ -> Preprocessor -> Preprocessor Definitions
 221                 Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
 222
 223 3. Resulting file system tree:
 224
 225         YosysVS/
 226         YosysVS/YosysVS
 227         YosysVS/YosysVS/YosysVS.vcxproj
 228         YosysVS/YosysVS/YosysVS.vcxproj.filters
 229         YosysVS/YosysVS.sdf
 230         YosysVS/YosysVS.sln
 231         YosysVS/YosysVS.v12.suo
 232
 233 4. Zip YosysVS as YosysVS-Tpl-v1.zip
 234
 235
 236
 237 Checklist for adding internal cell types
 238 ========================================
 239
 240 Things to do right away:
 241
 242         - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
 243         - Add to InternalCellChecker::check() in kernel/rtlil.cc
 244         - Add to techlibs/common/simlib.v
 245         - Add to techlibs/common/techmap.v
 246
 247 Things to do after finalizing the cell interface:
 248
 249         - Add support to kernel/satgen.h for the new cell type
 250         - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
 251         - Maybe add support to the verilog backend for dumping such cells as expression
 252
 253
 254
 255 Checklist for creating Yosys releases
 256 =====================================
 257
 258 Update the CHANGELOG file:
 259
 260         cd ~yosys
 261         gitk &
 262         vi CHANGELOG
 263
 264
 265 Run all tests with "make config-{clang,gcc,gcc-4.6}":
 266
 267         cd ~yosys
 268         make clean
 269         make test vloghtb
 270         make install
 271
 272         cd ~yosys-bigsim
 273         make clean
 274         make full
 275
 276         cd ~vloghammer
 277         make purge gen_issues gen_samples
 278         make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
 279         chromium-browser report.html
 280
 281
 282 Then with default config setting:
 283
 284         cd ~yosys
 285         ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
 286         ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
 287         ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
 288
 289         cd ~yosys
 290         make manual
 291         - sanity check the figures in the appnotes and presentation
 292             - if there are any odd things -> investigate
 293             - make cosmetic changes to the .tex files if necessary
 294
 295
 296 Also with default config setting:
 297
 298         cd ~yosys/techlibs/cmos
 299         bash testbench.sh
 300
 301         cd ~yosys/techlibs/xilinx/example_sim_counter
 302         bash run_sim.sh
 303
 304         cd ~yosys/techlibs/xilinx/example_mojo_counter
 305         bash example.sh
 306
 307
 308 Finally if a current verific library is available:
 309
 310         cd ~yosys
 311         cat frontends/verific/build_amd64.txt
 312         - follow instructions
 313
 314         cd frontends/verific
 315         ../../yosys test_navre.ys
 316
 317
 318 Release candiate:
 319
 320         - create branch yosys-x.y.z-rc and push to github
 321         - contact the usual suspects per mail and ask them to test
 322         - post on the reddit and ask people to test
 323         - commit KISS fixes to the -rc branch if necessary
 324
 325
 326 Release:
 327
 328         - set YOSYS_VER to x.y.z in Makefile
 329         - update version string in CHANGELOG
 330         git commit -am "Yosys x.y.z"
 331
 332         - push tag to github
 333         - post changelog on github
 334         - post short release note on reddit
 335         - delete -rc branch from github
 336
 337
 338 Updating the website:
 339
 340         cd ~yosys
 341         make manual
 342         make install
 343
 344         - update pdf files on the website
 345
 346         cd ~yosys-web
 347         make update_cmd
 348         make update_show
 349         git commit -am update
 350         make push
 351
 352
 353 In master branch:
 354
 355         git merge {release-tag}
 356         - set version to x.y.z+ in Makefile
 357         - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG
 358         git commit --amend -am "Yosys x.y.z+"
 359
 360