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