path: root/CodingReadme
diff options
authorClifford Wolf <>2014-12-30 19:39:17 +0100
committerClifford Wolf <>2014-12-30 19:39:17 +0100
commiteceecfeb8cf13f9afc200ab7eb7e93ff8f2acac4 (patch)
tree196a5b75d89dd1cde678afb8a95c37c4e1107003 /CodingReadme
parent4606addfefc3edcc625e27cbbf9b11cc9d93594f (diff)
Added more information to CodingReadme
Diffstat (limited to 'CodingReadme')
1 files changed, 110 insertions, 6 deletions
diff --git a/CodingReadme b/CodingReadme
index 03de3fc1..bdadf821 100644
--- a/CodingReadme
+++ b/CodingReadme
@@ -4,19 +4,123 @@ Getting Started
-Reading List
+Outline of a Yosys command
+Here is a the C++ code for a "hello_world" Yosys command (
+ #include "kernel/yosys.h"
+ struct HelloWorldPass : public Pass {
+ HelloWorldPass() : Pass("hello_world") { }
+ virtual void execute(vector<string>, Design*) {
+ log("Hello World!\n");
+ }
+ } HelloWorldPass;
+This can be built into a Yosys module using the following command:
+ yosys-config --exec --cxx --cxxflags --ldflags -o -shared --ldlibs
+And then executed using the following command:
+ yosys -m -p hello_world
+Yosys Data Structures
+Here is a short list of data structures that you should make yourself familiar
+with before you write C++ code for Yosys. The following data structures are all
+defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used.
+ 1. Yosys Container Classes
+Yosys uses dict<K, T> and pool<T> as main container classes. dict<K, T> is
+essentially a replacement for std::unordered_map<K, T> and pool<T> is
+essentially a replacement for std::unordered_set<T>. The main differences are:
+ - dict<K, T> and pool<T> are about 2x faster than the std containers
+ - references to elements in a dict<K, T> or pool<T> are invalidated by
+ insert operations (just like you are used from std::vector<T>).
+ - dict<K, T> and pool<T> will have the same order of iteration across
+ all compilers and architectures.
+ 2. Standard STL data types
-To write Yosys C++ code you need to know at least the following classes in kernel/rtlil.h:
+In Yosys we use std::vector<T> and std::string whenever applicable. When
+dict<K, T> and pool<T> are not suitable then std::map<K, T> and std::set<T>
+are used instead.
+The types std::vector<T> and std::string are also available as vector<T>
+and string in the Yosys namespace.
+ 3. RTLIL objects
+The current design (essentially a collection of modules, each defined by a
+netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h,
+automatically included by kernel/yosys.h). You should glance over at least
+the declarations for the following types in kernel/rtlil.h:
+ RTLIL::IdString
+ This is a handle for an identifier (e.g. cell or wire name).
+ It feels a lot like a std::string, but is only a single int
+ in size. (The actual string is stored in a global lookup
+ table.)
+ RTLIL::SigBit
+ A single signal bit. I.e. either a constant (0, 1, x, z) or
+ a single bit from a wire.
+ RTLIL::SigSpec
+ Essentially a vector of SigBits.
+ The building blocks of the netlist in a module.
- RTLIL::SigSpec
+ RTLIL::Design
+ The module is a container with connected cells and wires
+ in it. The design is a container with modules in it.
+All this types are also available without the RTLIL:: prefix in the Yosys
+ 4. SigMap and other Helper Classes
+There are a couple of additional helper classes that are in wide use
+in Yosys. Most importantly there is SigMap (declared in kernel.sigtools.h).
+When a design has many wires in it that are connected to each other, then
+a single signal bit can have multiple valid names. The SigMap object can
+be used to map SigSpecs or SigBits to unique SigSpecs and SigBits that
+consitently only uses one wire from a group of connected wires. For example:
+ SigBit a = module->addWire(NEW_ID);
+ SigBit b = module->addWire(NEW_ID);
+ module->connect(a, b);
+ log("%d\n", a == b); // will print 0
+ SigMap sigmap(module);
+ log("%d\n", sigmap(a) == sigmap(b)); // will print 1
+Example Code
The following yosys commands are a good starting point if you are looking for examples
of how to use the Yosys API:
+ manual/CHAPTER_Prog/
@@ -25,7 +129,7 @@ Notes on the existing codebase
For historical reasons not all parts of Yosys adhere to the current coding
-styles. When adding code to existing parts of the system, adhere to this guide
+style. When adding code to existing parts of the system, adhere to this guide
for the new code instead of trying to mimic the style of the surrounding code.
@@ -62,7 +166,7 @@ gcc 4.6 is allowed in Yosys code. This will change in future releases.
In general Yosys uses "int" instead of "size_t". To avoid compiler
warnings for implicit type casts, always use "GetSize(foobar)" instead
-of "foobar.size()". (GetSize() is defined by kernel/yosys.h)
+of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
Use range-based for loops whenever applicable.