CodingReadme

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