Writing extensions ================== .. todo:: check text is coherent This chapter contains some bits and pieces of information about programming yosys extensions. Don't be afraid to ask questions on the YosysHQ Slack. 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. .. literalinclude:: ../temp/GettingStarted :language: none :caption: guidelines/GettingStarted .. literalinclude:: ../temp/CodingStyle :language: none :caption: guidelines/CodingStyle 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/code_examples/stubnets/stubnets.cc``. .. literalinclude:: /code_examples/stubnets/stubnets.cc :language: c++ :linenos: :caption: docs/source/code_examples/stubnets/stubnets.cc .. literalinclude:: /code_examples/stubnets/Makefile :language: makefile :linenos: :caption: docs/source/code_examples/stubnets/Makefile .. literalinclude:: /code_examples/stubnets/test.v :language: verilog :linenos: :caption: docs/source/code_examples/stubnets/test.v Quick guide ----------- See also: ``docs/resources/PRESENTATION_Prog/*``. Program components and data formats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See :doc:`/yosys_internals/formats/rtlil_rep` document for more information about the internal data storage format used in Yosys and the classes that it provides. This document will focus on the much simpler version of RTLIL left after the commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``): .. figure:: /_images/internals/simplified_rtlil.* :class: width-helper :name: fig:Simplified_RTLIL Simplified RTLIL entity-relationship diagram without memories and processes It is possible to only work on this simpler version: .. code:: c++ for (RTLIL::Module *module : design->selected_modules() { if (module->has_memories_warn() || module->has_processes_warn()) continue; .... } When trying to understand what a command does, creating a small test case to look at the output of :cmd:ref:`dump` and :cmd:ref:`show` before and after the command has been executed can be helpful. The :doc:`/using_yosys/more_scripting/selections` document has more information on using these commands. Creating modules from scratch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. todo:: add/expand supporting text, also use files in docs/resources/PRESENTATION_Prog Let's create the following module using the RTLIL API: .. literalinclude:: ../../resources/PRESENTATION_Prog/absval_ref.v :language: Verilog :caption: docs/resources/PRESENTATION_Prog/absval_ref.v .. code:: C++ RTLIL::Module *module = new RTLIL::Module; module->name = "\\absval"; RTLIL::Wire *a = module->addWire("\\a", 4); a->port_input = true; a->port_id = 1; RTLIL::Wire *y = module->addWire("\\y", 4); y->port_output = true; y->port_id = 2; RTLIL::Wire *a_inv = module->addWire(NEW_ID, 4); module->addNeg(NEW_ID, a, a_inv, true); module->addMux(NEW_ID, a, a_inv, RTLIL::SigSpec(a, 1, 3), y); module->fixup_ports(); Modifying modules ~~~~~~~~~~~~~~~~~ Most commands modify existing modules, not create new ones. When modifying existing modules, stick to the following DOs and DON'Ts: - Do not remove wires. Simply disconnect them and let a successive :cmd:ref:`clean` command worry about removing it. - Use ``module->fixup_ports()`` after changing the ``port_*`` properties of wires. - You can safely remove cells or change the ``connections`` property of a cell, but be careful when changing the size of the ``SigSpec`` connected to a cell port. - Use the ``SigMap`` helper class (see next section) when you need a unique handle for each signal bit. Using the SigMap helper class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Consider the following module: .. code:: Verilog module test(input a, output x, y); assign x = a, y = a; endmodule In this case ``a``, ``x``, and ``y`` are all different names for the same signal. However: .. code:: C++ RTLIL::SigSpec a(module->wire("\\a")), x(module->wire("\\x")), y(module->wire("\\y")); log("%d %d %d\n", a == x, x == y, y == a); // will print "0 0 0" The ``SigMap`` helper class can be used to map all such aliasing signals to a unique signal from the group (usually the wire that is directly driven by a cell or port). .. code:: C++ SigMap sigmap(module); log("%d %d %d\n", sigmap(a) == sigmap(x), sigmap(x) == sigmap(y), sigmap(y) == sigmap(a)); // will print "1 1 1" Printing log messages ~~~~~~~~~~~~~~~~~~~~~ The ``log()`` function is a ``printf()``-like function that can be used to create log messages. Use ``log_signal()`` to create a C-string for a SigSpec object: .. code:: C++ log("Mapped signal x: %s\n", log_signal(sigmap(x))); The pointer returned by ``log_signal()`` is automatically freed by the log framework at a later time. Use ``log_id()`` to create a C-string for an ``RTLIL::IdString``: .. code:: C++ log("Name of this module: %s\n", log_id(module->name)); Use ``log_header()`` and ``log_push()``/``log_pop()`` to structure log messages: .. code:: C++ log_header(design, "Doing important stuff!\n"); log_push(); for (int i = 0; i < 10; i++) log("Log message #%d.\n", i); log_pop(); Error handling ~~~~~~~~~~~~~~ Use ``log_error()`` to report a non-recoverable error: .. code:: C++ if (design->modules.count(module->name) != 0) log_error("A module with the name %s already exists!\n", RTLIL::id2cstr(module->name)); Use ``log_cmd_error()`` to report a recoverable error: .. code:: C++ if (design->selection_stack.back().empty()) log_cmd_error("This command can't operator on an empty selection!\n"); Use ``log_assert()`` and ``log_abort()`` instead of ``assert()`` and ``abort()``. Creating a command ~~~~~~~~~~~~~~~~~~ Simply create a global instance of a class derived from ``Pass`` to create a new yosys command: .. code:: C++ #include "kernel/yosys.h" USING_YOSYS_NAMESPACE struct MyPass : public Pass { MyPass() : Pass("my_cmd", "just a simple test") { } virtual void execute(std::vector args, RTLIL::Design *design) { log("Arguments to my_cmd:\n"); for (auto &arg : args) log(" %s\n", arg.c_str()); log("Modules in current design:\n"); for (auto mod : design->modules()) log(" %s (%d wires, %d cells)\n", log_id(mod), GetSize(mod->wires()), GetSize(mod->cells())); } } MyPass; Creating a plugin ~~~~~~~~~~~~~~~~~ Yosys can be extended by adding additional C++ code to the Yosys code base, or by loading plugins into Yosys. Use the following command to compile a Yosys plugin: .. code:: yosys-config --exec --cxx --cxxflags --ldflags \ -o my_cmd.so -shared my_cmd.cc --ldlibs Or shorter: .. code:: yosys-config --build my_cmd.so my_cmd.cc Load the plugin using the yosys ``-m`` option: .. code:: yosys -m ./my_cmd.so -p 'my_cmd foo bar'