Yosys RTL

The simplified data flow

Rectangles represent program modules and ellipses internal data structures that are used to exchange design data between the program modules.

Design data is read in using one of the frontend modules. The high-level HDL frontends for Verilog and VHDL code generate an abstract syntax tree (AST) that is then passed to the AST frontend. The AST Frontend then compiles the AST to Yosys’s main internal data format, the RTL Intermediate Language (RTLIL). The design data may then be transformed using a series of passes that all operate on the RTLIL representation of the design.

Finally the design in RTLIL representation is converted back to text by one of the backends, namely the Verilog Backend for generating Verilog netlists and the RTLIL Backend for writing the RTLIL data in the same format that is understood by the RTLIL Frontend.

With the exception of the AST Frontend, which is called by the high-level HDL frontends and can’t be called directly by the user, all program modules are called by the user (usually using a synthesis script that contains text commands for Yosys).

The RTL Intermediate Language (RTLIL)

All frontends, passes and backends in Yosys operate on a design in RTLIL representation. The only exception are the high-level frontends that use the AST representation as an intermediate step before generating RTLIL data.

The RTLIL::Design is the root object of the RTLIL data structure. There is always one “current design” in memory which passes operate on, frontends add data to and backends convert to exportable formats. But in some cases passes internally generate additional RTLIL::Design objects. For example when a pass is reading an auxiliary Verilog file such as a cell library, it might create an additional RTLIL::Design object and call the Verilog frontend with this other object to parse the cell library.

There is only one active RTLIL::Design object that is used by all frontends, passes and backends called by the user, e.g. using a synthesis script. The RTLIL::Design then contains zero to many RTLIL::Module objects. This corresponds to modules in Verilog or entities in VHDL. Each module in turn contains objects from three different categories:

RTLIL::Cell and RTLIL::Wire objects represent classical netlist data.

RTLIL::Process objects represent the decision trees (if-then-else statements, etc.) and synchronization declarations (clock signals and sensitivity) from Verilog always and VHDL process blocks.

RTLIL::Memory objects represent addressable memories (arrays).

Usually the output of the synthesis procedure is a netlist, i.e. all RTLIL::Process and RTLIL::Memory objects must be replaced by RTLIL::Cell and RTLIL::Wire objects by synthesis passes.

RTLIL identifiers

All identifiers in RTLIL (such as module names, port names, signal names, cell types, etc.) follow the following naming convention: they must either start with a backslash () or a dollar sign ($).

反斜杠开头的标识符是公共可见的标识符，来源于HDL输入文件。$开头的是自动生成的标识符，后端文件会将所有以$符号开头的标识符转换为不与以反斜杠开头的标识符发生冲突的标识符。

Whitespace and control characters (any character with an ASCII code 32 or less) are not allowed in RTLIL identifiers; most frontends and backends cannot support these characters in identifiers.

All RTLIL identifiers are case sensitive.

RTLIL::Design and RTLIL::Module

The RTLIL::Design object is basically just a container for RTLIL::Module objects. In addition to a list of RTLIL::Module objects the RTLIL::Design also keeps a list of selected objects, i.e. the objects that passes should operate on.

Verilog and VHDL both support parametric modules (known as “generic entities” in VHDL). The RTLIL format does not support parametric modules itself. Instead each module contains a callback function into the AST frontend to generate a parametrized variation of the RTLIL::Module as needed. This callback then returns the auto-generated name of the parametrized variation of the module.

RTLIL::Cell and RTLIL::Wire

A module contains zero to many RTLIL::Cell and RTLIL::Wire objects. Objects of these types are used to model netlists. Usually the goal of all synthesis efforts is to convert all modules to a state where the functionality of the module is implemented only by cells from a given cell library and wires to connect these cells with each other. Note that module ports are just wires with a special property.

Module包含Cell，Wire对象，这些对象将用于Model Netlist。

The connections of ports to wires are coded by assigning an RTLIL::SigSpec to each cell port.

RTLIL::SigSpec

A “signal” is everything that can be applied to a cell port. I.e.

The RTLIL::SigSpec data type is used to represent signals. The RTLIL::Cell object contains one RTLIL::SigSpec for each cell port.

RTLIL::Process

When a high-level HDL frontend processes behavioural code it splits it up into data path logic and an RTLIL::Process
that models the control logic of the behavioural code.

An RTLIL::Process is a container for zero or more RTLIL::SyncRule objects and exactly one RTLIL::CaseRule object, which is called the root case. An RTLIL::SyncRule object contains an (optional) synchronization condition (signal and edge-type), zero or more assignments (RTLIL::SigSig), and zero or more memory writes(RTLIL::MemWriteAction).

An RTLIL::CaseRule is a container for zero or more assignments (RTLIL::SigSig) and zero or more RTLIL::SwitchRule objects. An RTLIL::SwitchRule objects is a container for zero or more RTLIL::CaseRule objects.

RTLIL::Memory

For every array (memory) in the HDL code an RTLIL::Memory object is created.