From eceecfeb8cf13f9afc200ab7eb7e93ff8f2acac4 Mon Sep 17 00:00:00 2001 From: Clifford Wolf Date: Tue, 30 Dec 2014 19:39:17 +0100 Subject: [PATCH] Added more information to CodingReadme --- CodingReadme | 116 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 110 insertions(+), 6 deletions(-) diff --git a/CodingReadme b/CodingReadme index 03de3fc17..bdadf821d 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 (hello.cc): + + #include "kernel/yosys.h" + + USING_YOSYS_NAMESPACE + PRIVATE_NAMESPACE_BEGIN + + struct HelloWorldPass : public Pass { + HelloWorldPass() : Pass("hello_world") { } + virtual void execute(vector, Design*) { + log("Hello World!\n"); + } + } HelloWorldPass; + + PRIVATE_NAMESPACE_END + +This can be built into a Yosys module using the following command: + + yosys-config --exec --cxx --cxxflags --ldflags -o hello.so -shared hello.cc --ldlibs + +And then executed using the following command: + + yosys -m hello.so -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 and pool as main container classes. dict is +essentially a replacement for std::unordered_map and pool is +essentially a replacement for std::unordered_set. The main differences are: + + - dict and pool are about 2x faster than the std containers + + - references to elements in a dict or pool are invalidated by + insert operations (just like you are used from std::vector). + + - dict and pool 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 and std::string whenever applicable. When +dict and pool are not suitable then std::map and std::set +are used instead. + +The types std::vector and std::string are also available as vector +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. RTLIL::Wire RTLIL::Cell + The building blocks of the netlist in a module. + RTLIL::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 +namespace. + + 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/stubnets.cc passes/opt/wreduce.cc passes/techmap/maccmap.cc @@ -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. -- 2.30.2