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
37 yosys-config --build hello.so hello.cc
39 And then executed using the following command:
41 yosys -m hello.so -p hello_world
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.
51 1. Yosys Container Classes
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:
57 - dict<K, T> and pool<T> are about 2x faster than the std containers
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()).
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.)
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
70 - the method .count(key, iterator) is like .count(key) but only
71 considers elements that can be reached via the iterator.
73 - iterators can be compared. it1 < it2 means that the position of t2
74 can be reached via t1 but not vice versa.
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.
79 - dict<K, T> and pool<T> will have the same order of iteration across
80 all compilers, standard libraries and architectures.
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:
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
94 It is not possible to remove elements from an idict.
96 2. Standard STL data types
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>
102 The types std::vector<T> and std::string are also available as vector<T>
103 and string in the Yosys namespace.
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:
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
119 A single signal bit. I.e. either a constant state (0, 1,
120 x, z) or a single bit from a wire.
123 Essentially a vector of SigBits.
127 The building blocks of the netlist in a module.
131 The module is a container with connected cells and wires
132 in it. The design is a container with modules in it.
134 All this types are also available without the RTLIL:: prefix in the Yosys
137 4. SigMap and other Helper Classes
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).
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:
147 SigBit a = module->addWire(NEW_ID);
148 SigBit b = module->addWire(NEW_ID);
149 module->connect(a, b);
151 log("%d\n", a == b); // will print 0
153 SigMap sigmap(module);
154 log("%d\n", sigmap(a) == sigmap(b)); // will print 1
160 The following yosys commands are a good starting point if you are looking for examples
161 of how to use the Yosys API:
163 manual/CHAPTER_Prog/stubnets.cc
164 manual/PRESENTATION_Prog/my_cmd.cc
167 Notes on the existing codebase
168 ------------------------------
170 For historical reasons not all parts of Yosys adhere to the current coding
171 style. When adding code to existing parts of the system, adhere to this guide
172 for the new code instead of trying to mimic the style of the surrounding code.
183 - Yosys code is using tabs for indentation. Tabs are 8 characters.
185 - A continuation of a statement in the following line is indented by
188 - Lines are as long as you want them to be. A good rule of thumb is
189 to break lines at about column 150.
191 - Opening braces can be put on the same or next line as the statement
192 opening the block (if, switch, for, while, do). Put the opening brace
193 on its own line for larger blocks, especially blocks that contains
196 - Otherwise stick to the Linux Kernel Coding Stlye:
197 https://www.kernel.org/doc/Documentation/CodingStyle
203 Yosys is written in C++11. At the moment only constructs supported by
204 gcc 4.6 are allowed in Yosys code. This will change in future releases.
206 In general Yosys uses "int" instead of "size_t". To avoid compiler
207 warnings for implicit type casts, always use "GetSize(foobar)" instead
208 of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
210 Use range-based for loops whenever applicable.
213 --snap-- only the lines above this mark are included in the yosys manual --snap--
216 Creating the Visual Studio Template Project
217 ===========================================
219 1. Create an empty Visual C++ Win32 Console App project
221 Microsoft Visual Studio Express 2013 for Windows Desktop
222 Open New Project Wizard (File -> New Project..)
224 Project Name: YosysVS
225 Solution Name: YosysVS
226 [X] Create directory for solution
227 [ ] Add to source control
229 [X] Console applications
233 2. Open YosysVS Project Properties
235 Select Configuration: All Configurations
237 C/C++ -> General -> Additional Include Directories
240 C/C++ -> Preprocessor -> Preprocessor Definitions
241 Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
243 3. Resulting file system tree:
247 YosysVS/YosysVS/YosysVS.vcxproj
248 YosysVS/YosysVS/YosysVS.vcxproj.filters
251 YosysVS/YosysVS.v12.suo
253 4. Zip YosysVS as YosysVS-Tpl-v1.zip
257 Checklist for adding internal cell types
258 ========================================
260 Things to do right away:
262 - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
263 - Add to InternalCellChecker::check() in kernel/rtlil.cc
264 - Add to techlibs/common/simlib.v
265 - Add to techlibs/common/techmap.v
267 Things to do after finalizing the cell interface:
269 - Add support to kernel/satgen.h for the new cell type
270 - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
271 - Maybe add support to the verilog backend for dumping such cells as expression
275 Checklist for creating Yosys releases
276 =====================================
278 Update the CHANGELOG file:
285 Run all tests with "make config-{clang,gcc,gcc-4.6}":
298 make purge gen_issues gen_samples
299 make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
300 chromium-browser report.html
303 Then with default config setting:
309 ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
310 ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
311 ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
315 - sanity check the figures in the appnotes and presentation
316 - if there are any odd things -> investigate
317 - make cosmetic changes to the .tex files if necessary
320 Also with default config setting:
322 cd ~yosys/techlibs/cmos
325 cd ~yosys/techlibs/xilinx/example_basys3
329 Test building plugins with various of the standard passes:
331 yosys-config --build test.so equiv_simple.cc
334 Finally if a current verific library is available:
337 cat frontends/verific/build_amd64.txt
338 - follow instructions
341 ../../yosys test_navre.ys
346 - create branch yosys-x.y.z-rc and push to github
347 - contact the usual suspects per mail and ask them to test
348 - post on the reddit and ask people to test
349 - commit KISS fixes to the -rc branch if necessary
354 - set YOSYS_VER to x.y.z in Makefile
355 - update version string in CHANGELOG
356 git commit -am "Yosys x.y.z"
359 - post changelog on github
360 - post short release note on reddit
361 - delete -rc branch from github
364 Updating the website:
370 - update pdf files on the website
375 git commit -am update
381 git merge {release-tag}
382 - set version to x.y.z+ in Makefile
383 - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG
384 git commit --amend -am "Yosys x.y.z+"