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.)
7 --snip-- only the lines below this mark are included in the yosys manual --snip--
12 Outline of a Yosys command
13 --------------------------
15 Here is a the C++ code for a "hello_world" Yosys command (hello.cc):
17 #include "kernel/yosys.h"
20 PRIVATE_NAMESPACE_BEGIN
22 struct HelloWorldPass : public Pass {
23 HelloWorldPass() : Pass("hello_world") { }
24 virtual void execute(vector<string>, Design*) {
25 log("Hello World!\n");
31 This can be built into a Yosys module using the following command:
33 yosys-config --exec --cxx --cxxflags --ldflags -o hello.so -shared hello.cc --ldlibs
35 And then executed using the following command:
37 yosys -m hello.so -p hello_world
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.
47 1. Yosys Container Classes
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:
53 - dict<K, T> and pool<T> are about 2x faster than the std containers
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()).
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.)
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
66 - the method .count(key, iterator) is like .count(key) but only
67 considers elements that can be reached via the iterator.
69 - iterators can be compared. it1 < it2 means that the position of t2
70 can be reached via t1 but not vice versa.
72 - dict<K, T> and pool<T> will have the same order of iteration across
73 all compilers, standard libraries and architectures.
75 In addition to dict<K, T> and pool<T> there is also an idict<K> that
76 creates a bijective map from K to the integers. For example:
79 log("%d\n", si("hello")); // will print 42
80 log("%d\n", si("world")); // will print 43
81 log("%d\n", si.at("world")); // will print 43
82 log("%d\n", si.at("dummy")); // will throw exception
83 log("%s\n", si[42].c_str())); // will print hello
84 log("%s\n", si[43].c_str())); // will print world
85 log("%s\n", si[44].c_str())); // will throw exception
87 It is not possible to remove elements from an idict.
89 2. Standard STL data types
91 In Yosys we use std::vector<T> and std::string whenever applicable. When
92 dict<K, T> and pool<T> are not suitable then std::map<K, T> and std::set<T>
95 The types std::vector<T> and std::string are also available as vector<T>
96 and string in the Yosys namespace.
100 The current design (essentially a collection of modules, each defined by a
101 netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h,
102 automatically included by kernel/yosys.h). You should glance over at least
103 the declarations for the following types in kernel/rtlil.h:
106 This is a handle for an identifier (e.g. cell or wire name).
107 It feels a lot like a std::string, but is only a single int
108 in size. (The actual string is stored in a global lookup
112 A single signal bit. I.e. either a constant (0, 1, x, z) or
113 a single bit from a wire.
116 Essentially a vector of SigBits.
120 The building blocks of the netlist in a module.
124 The module is a container with connected cells and wires
125 in it. The design is a container with modules in it.
127 All this types are also available without the RTLIL:: prefix in the Yosys
130 4. SigMap and other Helper Classes
132 There are a couple of additional helper classes that are in wide use
133 in Yosys. Most importantly there is SigMap (declared in kernel/sigtools.h).
135 When a design has many wires in it that are connected to each other, then a
136 single signal bit can have multiple valid names. The SigMap object can be used
137 to map SigSpecs or SigBits to unique SigSpecs and SigBits that consitently
138 only use one wire from such a group of connected wires. For example:
140 SigBit a = module->addWire(NEW_ID);
141 SigBit b = module->addWire(NEW_ID);
142 module->connect(a, b);
144 log("%d\n", a == b); // will print 0
146 SigMap sigmap(module);
147 log("%d\n", sigmap(a) == sigmap(b)); // will print 1
153 The following yosys commands are a good starting point if you are looking for examples
154 of how to use the Yosys API:
156 manual/CHAPTER_Prog/stubnets.cc
157 passes/opt/wreduce.cc
158 passes/techmap/maccmap.cc
161 Notes on the existing codebase
162 ------------------------------
164 For historical reasons not all parts of Yosys adhere to the current coding
165 style. When adding code to existing parts of the system, adhere to this guide
166 for the new code instead of trying to mimic the style of the surrounding code.
177 - Yosys code is using tabs for indentation. Tabs are 8 characters.
179 - A continuation of a statement in the following line is indented by
182 - Lines are as long as you want them to be. A good rule of thumb is
183 to break lines at about column 150.
185 - Opening braces can be put on the same or next line as the statement
186 opening the block (if, switch, for, while, do). Put the opening brace
187 on its own line for larger blocks, especially blocks that contains
190 - Otherwise stick to the Linux Kernel Coding Stlye:
191 https://www.kernel.org/doc/Documentation/CodingStyle
197 Yosys is written in C++11. At the moment only constructs supported by
198 gcc 4.6 are allowed in Yosys code. This will change in future releases.
200 In general Yosys uses "int" instead of "size_t". To avoid compiler
201 warnings for implicit type casts, always use "GetSize(foobar)" instead
202 of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
204 Use range-based for loops whenever applicable.
207 --snap-- only the lines above this mark are included in the yosys manual --snap--
210 Creating the Visual Studio Template Project
211 ===========================================
213 1. Create an empty Visual C++ Win32 Console App project
215 Microsoft Visual Studio Express 2013 for Windows Desktop
216 Open New Project Wizard (File -> New Project..)
218 Project Name: YosysVS
219 Solution Name: YosysVS
220 [X] Create directory for solution
221 [ ] Add to source control
223 [X] Console applications
227 2. Open YosysVS Project Properties
229 Select Configuration: All Configurations
231 C/C++ -> General -> Additional Include Directories
234 C/C++ -> Preprocessor -> Preprocessor Definitions
235 Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
237 3. Resulting file system tree:
241 YosysVS/YosysVS/YosysVS.vcxproj
242 YosysVS/YosysVS/YosysVS.vcxproj.filters
245 YosysVS/YosysVS.v12.suo
247 4. Zip YosysVS as YosysVS-Tpl-v1.zip
251 Checklist for adding internal cell types
252 ========================================
254 Things to do right away:
256 - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
257 - Add to InternalCellChecker::check() in kernel/rtlil.cc
258 - Add to techlibs/common/simlib.v
259 - Add to techlibs/common/techmap.v
261 Things to do after finalizing the cell interface:
263 - Add support to kernel/satgen.h for the new cell type
264 - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
265 - Maybe add support to the verilog backend for dumping such cells as expression
269 Checklist for creating Yosys releases
270 =====================================
272 Update the CHANGELOG file:
279 Run all tests with "make config-{clang,gcc,gcc-4.6}":
291 make purge gen_issues gen_samples
292 make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
293 chromium-browser report.html
296 Then with default config setting:
299 ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
300 ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
301 ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
305 - sanity check the figures in the appnotes and presentation
306 - if there are any odd things -> investigate
307 - make cosmetic changes to the .tex files if necessary
310 Also with default config setting:
312 cd ~yosys/techlibs/cmos
315 cd ~yosys/techlibs/xilinx/example_sim_counter
318 cd ~yosys/techlibs/xilinx/example_mojo_counter
322 Finally if a current verific library is available:
325 cat frontends/verific/build_amd64.txt
326 - follow instructions
329 ../../yosys test_navre.ys
334 - create branch yosys-x.y.z-rc and push to github
335 - contact the usual suspects per mail and ask them to test
336 - post on the reddit and ask people to test
337 - commit KISS fixes to the -rc branch if necessary
342 - set YOSYS_VER to x.y.z in Makefile
343 - update version string in CHANGELOG
344 git commit -am "Yosys x.y.z"
347 - post changelog on github
348 - post short release note on reddit
349 - delete -rc branch from github
352 Updating the website:
358 - update pdf files on the website
363 git commit -am update
369 git merge {release-tag}
370 - set version to x.y.z+ in Makefile
371 - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG
372 git commit --amend -am "Yosys x.y.z+"