6. Programming Yosys extensions

This chapter contains some bits and pieces of information about programming yosys extensions. Also consult the section on programming in the “Yosys Presentation” (can be downloaded from the Yosys website as PDF) and don’t be afraid to ask questions on the YosysHQ Slack.

6.1. Guidelines

The guidelines directory contains notes on various aspects of Yosys development. The files GettingStarted and CodingStyle may be of particular interest, and are reproduced here.

Listing 6.1 guidelines/GettingStarted
Getting Started

Outline of a Yosys command

Here is a the C++ code for a "hello_world" Yosys command (hello.cc):

	#include "kernel/yosys.h"


	struct HelloWorldPass : public Pass {
		HelloWorldPass() : Pass("hello_world") { }
		void execute(vector<string>, Design*) override {
			log("Hello World!\n");
	} HelloWorldPass;


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

Or short:

	yosys-config --build hello.so hello.cc

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<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 a
replacement for std::unordered_set<T>. The main characteristics 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 and remove operations (similar to std::vector<T> on push_back()).

	- some iterators are invalidated by erase(). specifically, iterators
	  that have not passed the erased element yet are invalidated. (erase()
	  itself returns valid iterator to the next element.)

	- no iterators are invalidated by insert(). elements are inserted at
	  begin(). i.e. only a new iterator that starts at begin() will see the
	  inserted elements.

	- the method .count(key, iterator) is like .count(key) but only
	  considers elements that can be reached via the iterator.

	- iterators can be compared. it1 < it2 means that the position of t2
	  can be reached via t1 but not vice versa.

	- the method .sort() can be used to sort the elements in the container
	  the container stays sorted until elements are added or removed.

	- dict<K, T> and pool<T> will have the same order of iteration across
	  all compilers, standard libraries and architectures.

In addition to dict<K, T> and pool<T> there is also an idict<K> that
creates a bijective map from K to the integers. For example:

	idict<string, 42> si;
	log("%d\n", si("hello"));      // will print 42
	log("%d\n", si("world"));      // will print 43
	log("%d\n", si.at("world"));   // will print 43
	log("%d\n", si.at("dummy"));   // will throw exception
	log("%s\n", si[42].c_str()));  // will print hello
	log("%s\n", si[43].c_str()));  // will print world
	log("%s\n", si[44].c_str()));  // will throw exception

It is not possible to remove elements from an idict.

Finally mfp<K> implements a merge-find set data structure (aka. disjoint-set or
union-find) over the type K ("mfp" = merge-find-promote).

  2. Standard STL data types

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:

		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

		A single signal bit. I.e. either a constant state (0, 1,
		x, z) or a single bit from a wire.

		Essentially a vector of SigBits.

		The building blocks of the netlist in a module.

		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 consistently
only use one wire from such 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

Using the RTLIL Netlist Format

In the RTLIL netlist format the cell ports contain SigSpecs that point to the
Wires. There are no references in the other direction. This has two direct

(1) It is very easy to go from cells to wires but hard to go in the other way.

(2) There is no danger in removing cells from the netlists, but removing wires
can break the netlist format when there are still references to the wire
somewhere in the netlist.

The solution to (1) is easy: Create custom indexes that allow you to make fast
lookups for the wire-to-cell direction. You can either use existing generic
index structures to do that (such as the ModIndex class) or write your own
index. For many application it is simplest to construct a custom index. For

	SigMap sigmap(module);
	dict<SigBit, Cell*> sigbit_to_driver_index;

	for (auto cell : module->cells())
		for (auto &conn : cell->connections())
			if (cell->output(conn.first))
				for (auto bit : sigmap(conn.second))
					sigbit_to_driver_index[bit] = cell;

Regarding (2): There is a general theme in Yosys that you don't remove wires
from the design. You can rename them, unconnect them, but you do not actually remove
the Wire object from the module. Instead you let the "clean" command take care
of the dangling wires. On the other hand it is safe to remove cells (as long as
you make sure this does not invalidate a custom index you are using in your code).

Example Code

The following yosys commands are a good starting point if you are looking for examples
of how to use the Yosys API:


Script Passes

The ScriptPass base class can be used to implement passes that just call other passes,
like a script. Examples for such passes are:


In some cases it is easier to implement such a pass as regular pass, for example when
ScriptPass doesn't provide the type of flow control desired. (But many of the
script passes in Yosys that don't use ScriptPass simply predate the ScriptPass base
class.) Examples for such passes are:


Whether they use the ScriptPass base-class or not, a pass should always either
call other passes without doing any non-trivial work itself, or should implement
a non-trivial algorithm but not call any other passes. The reason for this is that
this helps containing complexity in individual passes and simplifies debugging the
entire system.

Exceptions to this rule should be rare and limited to cases where calling other
passes is optional and only happens when requested by the user (such as for
example `techmap -autoproc`), or where it is about commands that are "top-level
commands" in their own right, not components to be used in regular synthesis
flows (such as the `bugpoint` command).

A pass that would "naturally" call other passes and also do some work itself
should be re-written in one of two ways:

1) It could be re-written as script pass with the parts that are not calls
to other passes factored out into individual new passes. Usually in those
cases the new sub passes share the same prefix as the top-level script pass.

2) It could be re-written so that it already expects the design in a certain
state, expecting the calling script to set up this state before calling the
pass in questions.

Many back-ends are examples for the 2nd approach. For example, `write_aiger`
does not convert the design into AIG representation, but expects the design
to be already in this form, and prints an `Unsupported cell type` error
message otherwise.

Notes on the existing codebase

For historical reasons not all parts of Yosys adhere to the current coding
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.
Listing 6.2 guidelines/CodingStyle
Coding Style

Formatting of code

- Yosys code is using tabs for indentation. Tabs are 8 characters.

- A continuation of a statement in the following line is indented by
  two additional tabs.

- Lines are as long as you want them to be. A good rule of thumb is
  to break lines at about column 150.

- Opening braces can be put on the same or next line as the statement
  opening the block (if, switch, for, while, do). Put the opening brace
  on its own line for larger blocks, especially blocks that contains
  blank lines.

- Otherwise stick to the Linux Kernel Coding Style:

C++ Language

Yosys is written in C++11.

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 in kernel/yosys.h)

Use range-based for loops whenever applicable.

6.2. The “stubsnets” example module

The following is the complete code of the “stubsnets” example module. It is included in the Yosys source distribution as docs/source/CHAPTER_Prog/stubnets.cc.

Listing 6.3 docs/source/CHAPTER_Prog/stubnets.cc
  1// This is free and unencumbered software released into the public domain.
  3// Anyone is free to copy, modify, publish, use, compile, sell, or
  4// distribute this software, either in source code form or as a compiled
  5// binary, for any purpose, commercial or non-commercial, and by any
  6// means.
  8#include "kernel/yosys.h"
  9#include "kernel/sigtools.h"
 11#include <string>
 12#include <map>
 13#include <set>
 18// this function is called for each module in the design
 19static void find_stub_nets(RTLIL::Design *design, RTLIL::Module *module, bool report_bits)
 21	// use a SigMap to convert nets to a unique representation
 22	SigMap sigmap(module);
 24	// count how many times a single-bit signal is used
 25	std::map<RTLIL::SigBit, int> bit_usage_count;
 27	// count output lines for this module (needed only for summary output at the end)
 28	int line_count = 0;
 30	log("Looking for stub wires in module %s:\n", RTLIL::id2cstr(module->name));
 32	// For all ports on all cells
 33	for (auto &cell_iter : module->cells_)
 34	for (auto &conn : cell_iter.second->connections())
 35	{
 36		// Get the signals on the port
 37		// (use sigmap to get a uniqe signal name)
 38		RTLIL::SigSpec sig = sigmap(conn.second);
 40		// add each bit to bit_usage_count, unless it is a constant
 41		for (auto &bit : sig)
 42			if (bit.wire != NULL)
 43				bit_usage_count[bit]++;
 44	}
 46	// for each wire in the module
 47	for (auto &wire_iter : module->wires_)
 48	{
 49		RTLIL::Wire *wire = wire_iter.second;
 51		// .. but only selected wires
 52		if (!design->selected(module, wire))
 53			continue;
 55		// add +1 usage if this wire actually is a port
 56		int usage_offset = wire->port_id > 0 ? 1 : 0;
 58		// we will record which bits of the (possibly multi-bit) wire are stub signals
 59		std::set<int> stub_bits;
 61		// get a signal description for this wire and split it into separate bits
 62		RTLIL::SigSpec sig = sigmap(wire);
 64		// for each bit (unless it is a constant):
 65		// check if it is used at least two times and add to stub_bits otherwise
 66		for (int i = 0; i < GetSize(sig); i++)
 67			if (sig[i].wire != NULL && (bit_usage_count[sig[i]] + usage_offset) < 2)
 68				stub_bits.insert(i);
 70		// continue if no stub bits found
 71		if (stub_bits.size() == 0)
 72			continue;
 74		// report stub bits and/or stub wires, don't report single bits
 75		// if called with report_bits set to false.
 76		if (GetSize(stub_bits) == GetSize(sig)) {
 77			log("  found stub wire: %s\n", RTLIL::id2cstr(wire->name));
 78		} else {
 79			if (!report_bits)
 80				continue;
 81			log("  found wire with stub bits: %s [", RTLIL::id2cstr(wire->name));
 82			for (int bit : stub_bits)
 83				log("%s%d", bit == *stub_bits.begin() ? "" : ", ", bit);
 84			log("]\n");
 85		}
 87		// we have outputted a line, increment summary counter
 88		line_count++;
 89	}
 91	// report summary
 92	if (report_bits)
 93		log("  found %d stub wires or wires with stub bits.\n", line_count);
 94	else
 95		log("  found %d stub wires.\n", line_count);
 98// each pass contains a singleton object that is derived from Pass
 99struct StubnetsPass : public Pass {
100	StubnetsPass() : Pass("stubnets") { }
101	void execute(std::vector<std::string> args, RTLIL::Design *design) override
102	{
103		// variables to mirror information from passed options
104		bool report_bits = 0;
106		log_header(design, "Executing STUBNETS pass (find stub nets).\n");
108		// parse options
109		size_t argidx;
110		for (argidx = 1; argidx < args.size(); argidx++) {
111			std::string arg = args[argidx];
112			if (arg == "-report_bits") {
113				report_bits = true;
114				continue;
115			}
116			break;
117		}
119		// handle extra options (e.g. selection)
120		extra_args(args, argidx, design);
122		// call find_stub_nets() for each module that is either
123		// selected as a whole or contains selected objects.
124		for (auto &it : design->modules_)
125			if (design->selected_module(it.first))
126				find_stub_nets(design, it.second, report_bits);
127	}
128} StubnetsPass;
Listing 6.4 docs/source/CHAPTER_Prog/Makefile
 1test: stubnets.so
 2	yosys -ql test1.log -m ./stubnets.so test.v -p "stubnets"
 3	yosys -ql test2.log -m ./stubnets.so test.v -p "opt; stubnets"
 4	yosys -ql test3.log -m ./stubnets.so test.v -p "techmap; opt; stubnets -report_bits"
 5	tail test1.log test2.log test3.log
 7stubnets.so: stubnets.cc
 8	yosys-config --exec --cxx --cxxflags --ldflags -o $@ -shared $^ --ldlibs
11	rm -f test1.log test2.log test3.log
12	rm -f stubnets.so stubnets.d
Listing 6.5 docs/source/CHAPTER_Prog/test.v
1module uut(in1, in2, in3, out1, out2);
3input [8:0] in1, in2, in3;
4output [8:0] out1, out2;
6assign out1 = in1 + in2 + (in3 >> 4);