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 - dict<K, T> and pool<T> will have the same order of iteration across
67 all compilers and architectures.
69 2. Standard STL data types
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>
75 The types std::vector<T> and std::string are also available as vector<T>
76 and string in the Yosys namespace.
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:
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
92 A single signal bit. I.e. either a constant (0, 1, x, z) or
93 a single bit from a wire.
96 Essentially a vector of SigBits.
100 The building blocks of the netlist in a module.
104 The module is a container with connected cells and wires
105 in it. The design is a container with modules in it.
107 All this types are also available without the RTLIL:: prefix in the Yosys
110 4. SigMap and other Helper Classes
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).
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:
120 SigBit a = module->addWire(NEW_ID);
121 SigBit b = module->addWire(NEW_ID);
122 module->connect(a, b);
124 log("%d\n", a == b); // will print 0
126 SigMap sigmap(module);
127 log("%d\n", sigmap(a) == sigmap(b)); // will print 1
133 The following yosys commands are a good starting point if you are looking for examples
134 of how to use the Yosys API:
136 manual/CHAPTER_Prog/stubnets.cc
137 passes/opt/wreduce.cc
138 passes/techmap/maccmap.cc
141 Notes on the existing codebase
142 ------------------------------
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.
157 - Yosys code is using tabs for indentation. Tabs are 8 characters.
159 - A continuation of a statement in the following line is indented by
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.
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
170 - Otherwise stick to the Linux Kernel Coding Stlye:
171 https://www.kernel.org/doc/Documentation/CodingStyle
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.
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)
184 Use range-based for loops whenever applicable.
187 --snap-- only the lines above this mark are included in the yosys manual --snap--
190 Creating the Visual Studio Template Project
191 ===========================================
193 1. Create an empty Visual C++ Win32 Console App project
195 Microsoft Visual Studio Express 2013 for Windows Desktop
196 Open New Project Wizard (File -> New Project..)
198 Project Name: YosysVS
199 Solution Name: YosysVS
200 [X] Create directory for solution
201 [ ] Add to source control
203 [X] Console applications
207 2. Open YosysVS Project Properties
209 Select Configuration: All Configurations
211 C/C++ -> General -> Additional Include Directories
214 C/C++ -> Preprocessor -> Preprocessor Definitions
215 Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
217 3. Resulting file system tree:
221 YosysVS/YosysVS/YosysVS.vcxproj
222 YosysVS/YosysVS/YosysVS.vcxproj.filters
225 YosysVS/YosysVS.v12.suo
227 4. Zip YosysVS as YosysVS-Tpl-v1.zip
231 Checklist for adding internal cell types
232 ========================================
234 Things to do right away:
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
241 Things to do after finalizing the cell interface:
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
249 Checklist for creating Yosys releases
250 =====================================
252 Update the CHANGELOG file:
259 Run all tests with "make config-{clang,gcc,gcc-4.6}":
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
276 Then with default config setting:
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
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
290 Also with default config setting:
292 cd ~yosys/techlibs/cmos
295 cd ~yosys/techlibs/xilinx/example_sim_counter
298 cd ~yosys/techlibs/xilinx/example_mojo_counter
302 Finally if a current verific library is available:
305 cat frontends/verific/build_amd64.txt
306 - follow instructions
309 ../../yosys test_navre.ys
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
322 - set YOSYS_VER to x.y.z in Makefile
323 - update version string in CHANGELOG
324 git commit -am "Yosys x.y.z"
327 - post changelog on github
328 - post short release note on reddit
329 - delete -rc branch from github
332 Updating the website:
338 - update pdf files on the website
343 git commit -am update
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+"