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 Or short:
  36
  37         yosys-config --build hello.so hello.cc
  38
  39 And then executed using the following command:
  40
  41         yosys -m hello.so -p hello_world
  42
  43
  44 Yosys Data Structures
  45 ---------------------
  46
  47 Here is a short list of data structures that you should make yourself familiar
  48 with before you write C++ code for Yosys. The following data structures are all
  49 defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used.
  50
  51   1. Yosys Container Classes
  52
  53 Yosys uses dict<K, T> and pool<T> as main container classes. dict<K, T> is
  54 essentially a replacement for std::unordered_map<K, T> and pool<T> is a
  55 replacement for std::unordered_set<T>. The main characteristics are:
  56
  57         - dict<K, T> and pool<T> are about 2x faster than the std containers
  58
  59         - references to elements in a dict<K, T> or pool<T> are invalidated by
  60           insert and remove operations (similar to std::vector<T> on push_back()).
  61
  62         - some iterators are invalidated by erase(). specifically, iterators
  63           that have not passed the erased element yet are invalidated. (erase()
  64           itself returns valid iterator to the next element.)
  65
  66         - no iterators are invalidated by insert(). elements are inserted at
  67           begin(). i.e. only a new iterator that starts at begin() will see the
  68           inserted elements.
  69
  70         - the method .count(key, iterator) is like .count(key) but only
  71           considers elements that can be reached via the iterator.
  72
  73         - iterators can be compared. it1 < it2 means that the position of t2
  74           can be reached via t1 but not vice versa.
  75
  76         - the method .sort() can be used to sort the elements in the container
  77           the container stays sorted until elements are added or removed.
  78
  79         - dict<K, T> and pool<T> will have the same order of iteration across
  80           all compilers, standard libraries and architectures.
  81
  82 In addition to dict<K, T> and pool<T> there is also an idict<K> that
  83 creates a bijective map from K to the integers. For example:
  84
  85         idict<string, 42> si;
  86         log("%d\n", si("hello"));      // will print 42
  87         log("%d\n", si("world"));      // will print 43
  88         log("%d\n", si.at("world"));   // will print 43
  89         log("%d\n", si.at("dummy"));   // will throw exception
  90         log("%s\n", si[42].c_str()));  // will print hello
  91         log("%s\n", si[43].c_str()));  // will print world
  92         log("%s\n", si[44].c_str()));  // will throw exception
  93
  94 It is not possible to remove elements from an idict.
  95
  96   2. Standard STL data types
  97
  98 In Yosys we use std::vector<T> and std::string whenever applicable. When
  99 dict<K, T> and pool<T> are not suitable then std::map<K, T> and std::set<T>
 100 are used instead.
 101
 102 The types std::vector<T> and std::string are also available as vector<T>
 103 and string in the Yosys namespace.
 104
 105   3. RTLIL objects
 106
 107 The current design (essentially a collection of modules, each defined by a
 108 netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h,
 109 automatically included by kernel/yosys.h). You should glance over at least
 110 the declarations for the following types in kernel/rtlil.h:
 111
 112         RTLIL::IdString
 113                 This is a handle for an identifier (e.g. cell or wire name).
 114                 It feels a lot like a std::string, but is only a single int
 115                 in size. (The actual string is stored in a global lookup
 116                 table.)
 117
 118         RTLIL::SigBit
 119                 A single signal bit. I.e. either a constant state (0, 1,
 120                 x, z) or a single bit from a wire.
 121
 122         RTLIL::SigSpec
 123                 Essentially a vector of SigBits.
 124
 125         RTLIL::Wire
 126         RTLIL::Cell
 127                 The building blocks of the netlist in a module.
 128
 129         RTLIL::Module
 130         RTLIL::Design
 131                 The module is a container with connected cells and wires
 132                 in it. The design is a container with modules in it.
 133
 134 All this types are also available without the RTLIL:: prefix in the Yosys
 135 namespace.
 136
 137   4. SigMap and other Helper Classes
 138
 139 There are a couple of additional helper classes that are in wide use
 140 in Yosys. Most importantly there is SigMap (declared in kernel/sigtools.h).
 141
 142 When a design has many wires in it that are connected to each other, then a
 143 single signal bit can have multiple valid names. The SigMap object can be used
 144 to map SigSpecs or SigBits to unique SigSpecs and SigBits that consistently
 145 only use one wire from such a group of connected wires. For example:
 146
 147         SigBit a = module->addWire(NEW_ID);
 148         SigBit b = module->addWire(NEW_ID);
 149         module->connect(a, b);
 150
 151         log("%d\n", a == b); // will print 0
 152
 153         SigMap sigmap(module);
 154         log("%d\n", sigmap(a) == sigmap(b)); // will print 1
 155
 156
 157 Using the RTLIL Netlist Format
 158 ------------------------------
 159
 160 In the RTLIL netlist format the cell ports contain SigSpecs that point to the
 161 Wires. There are no references in the other direction. This has two direct
 162 consequences:
 163
 164 (1) It is very easy to go from cells to wires but hard to go in the other way.
 165
 166 (2) There is no danger in removing cells from the netlists, but removing wires
 167 can break the netlist format when there are still references to the wire
 168 somewhere in the netlist.
 169
 170 The solution to (1) is easy: Create custom indexes that allow you to make fast
 171 lookups for the wire-to-cell direction. You can either use existing generic
 172 index structures to do that (such as the ModIndex class) or write your own
 173 index. For many application it is simplest to construct a custom index. For
 174 example:
 175
 176         SigMap sigmap(module);
 177         dict<SigBit, Cell*> sigbit_to_driver_index;
 178
 179         for (auto cell : module->cells())
 180                 for (auto &conn : cell->connections())
 181                         if (cell->output(conn.first))
 182                                 for (auto bit : sigmap(conn.second))
 183                                         sigbit_to_driver_index[bit] = cell;
 184
 185 Regarding (2): There is a general theme in Yosys that you don't remove wires
 186 from the design. You can rename them, unconnect them, but you do not actually remove
 187 the Wire object from the module. Instead you let the "clean" command take care
 188 of the dangling wires. On the other hand it is safe to remove cells (as long as
 189 you make sure this does not invalidate a custom index you are using in your code).
 190
 191
 192 Example Code
 193 ------------
 194
 195 The following yosys commands are a good starting point if you are looking for examples
 196 of how to use the Yosys API:
 197
 198         manual/CHAPTER_Prog/stubnets.cc
 199         manual/PRESENTATION_Prog/my_cmd.cc
 200
 201
 202 Notes on the existing codebase
 203 ------------------------------
 204
 205 For historical reasons not all parts of Yosys adhere to the current coding
 206 style. When adding code to existing parts of the system, adhere to this guide
 207 for the new code instead of trying to mimic the style of the surrounding code.
 208
 209
 210
 211 Coding Style
 212 ============
 213
 214
 215 Formatting of code
 216 ------------------
 217
 218 - Yosys code is using tabs for indentation. Tabs are 8 characters.
 219
 220 - A continuation of a statement in the following line is indented by
 221   two additional tabs.
 222
 223 - Lines are as long as you want them to be. A good rule of thumb is
 224   to break lines at about column 150.
 225
 226 - Opening braces can be put on the same or next line as the statement
 227   opening the block (if, switch, for, while, do). Put the opening brace
 228   on its own line for larger blocks, especially blocks that contains
 229   blank lines.
 230
 231 - Otherwise stick to the Linux Kernel Coding Stlye:
 232     https://www.kernel.org/doc/Documentation/CodingStyle
 233
 234
 235 C++ Langugage
 236 -------------
 237
 238 Yosys is written in C++11. At the moment only constructs supported by
 239 gcc 4.6 are allowed in Yosys code. This will change in future releases.
 240
 241 In general Yosys uses "int" instead of "size_t". To avoid compiler
 242 warnings for implicit type casts, always use "GetSize(foobar)" instead
 243 of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
 244
 245 Use range-based for loops whenever applicable.
 246
 247
 248 --snap-- only the lines above this mark are included in the yosys manual --snap--
 249
 250
 251 Creating the Visual Studio Template Project
 252 ===========================================
 253
 254 1. Create an empty Visual C++ Win32 Console App project
 255
 256         Microsoft Visual Studio Express 2013 for Windows Desktop
 257         Open New Project Wizard (File -> New Project..)
 258
 259         Project Name: YosysVS
 260         Solution Name: YosysVS
 261         [X] Create directory for solution
 262         [ ] Add to source control
 263
 264         [X] Console applications
 265         [X] Empty Projcect
 266         [ ] SDL checks
 267
 268 2. Open YosysVS Project Properties
 269
 270         Select Configuration: All Configurations
 271
 272         C/C++ -> General -> Additional Include Directories
 273                 Add: ..\yosys
 274
 275         C/C++ -> Preprocessor -> Preprocessor Definitions
 276                 Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
 277
 278 3. Resulting file system tree:
 279
 280         YosysVS/
 281         YosysVS/YosysVS
 282         YosysVS/YosysVS/YosysVS.vcxproj
 283         YosysVS/YosysVS/YosysVS.vcxproj.filters
 284         YosysVS/YosysVS.sdf
 285         YosysVS/YosysVS.sln
 286         YosysVS/YosysVS.v12.suo
 287
 288 4. Zip YosysVS as YosysVS-Tpl-v1.zip
 289
 290
 291
 292 Checklist for adding internal cell types
 293 ========================================
 294
 295 Things to do right away:
 296
 297         - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
 298         - Add to InternalCellChecker::check() in kernel/rtlil.cc
 299         - Add to techlibs/common/simlib.v
 300         - Add to techlibs/common/techmap.v
 301
 302 Things to do after finalizing the cell interface:
 303
 304         - Add support to kernel/satgen.h for the new cell type
 305         - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
 306         - Maybe add support to the verilog backend for dumping such cells as expression
 307
 308
 309
 310 Checklist for creating Yosys releases
 311 =====================================
 312
 313 Update the CHANGELOG file:
 314
 315         cd ~yosys
 316         gitk &
 317         vi CHANGELOG
 318
 319
 320 Update and check documentation:
 321
 322         cd ~yosys
 323         make update-manual
 324         make manual
 325         - sanity check the figures in the appnotes and presentation
 326             - if there are any odd things -> investigate
 327             - make cosmetic changes to the .tex files if necessary
 328
 329         cd ~yosys
 330         vi README CodingReadme
 331         - is the information provided in those file still up to date
 332
 333
 334 Then with default config setting:
 335
 336         cd ~yosys
 337         make vgtest
 338
 339         cd ~yosys
 340         ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
 341         ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
 342         ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
 343         ./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v
 344
 345         cd ~yosys/techlibs/cmos
 346         bash testbench.sh
 347
 348         cd ~yosys/techlibs/xilinx/example_basys3
 349         bash run.sh
 350
 351
 352 Test building plugins with various of the standard passes:
 353
 354         yosys-config --build test.so equiv_simple.cc
 355         - also check the code examples in CodingReadme
 356
 357
 358 And if a version of the verific library is currently available:
 359
 360         cd ~yosys
 361         cat frontends/verific/build_amd64.txt
 362         - follow instructions
 363
 364         cd frontends/verific
 365         ../../yosys test_navre.ys
 366
 367
 368 Finally run all tests with "make config-{clang,gcc,gcc-4.6}":
 369
 370         cd ~yosys
 371         make clean
 372         make test
 373         make vloghtb
 374         make install
 375
 376         cd ~yosys-bigsim
 377         make clean
 378         make full
 379
 380         cd ~vloghammer
 381         make purge gen_issues gen_samples
 382         make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
 383         chromium-browser report.html
 384
 385
 386 Release:
 387
 388         - set YOSYS_VER to x.y.z in Makefile
 389         - update version string in CHANGELOG
 390         git commit -am "Yosys x.y.z"
 391
 392         - push tag to github
 393         - post changelog on github
 394         - post short release note on reddit
 395
 396
 397 Updating the website:
 398
 399         cd ~yosys
 400         make manual
 401         make install
 402
 403         - update pdf files on the website
 404
 405         cd ~yosys-web
 406         make update_cmd
 407         make update_show
 408         git commit -am update
 409         make push
 410