mirror of
https://github.com/YosysHQ/yosys
synced 2025-10-31 03:32:29 +00:00
Docs: Move rtlil_text (back) to appendix
This commit is contained in:
Krystine Sherwin
parent
1374fc2e2b
commit
46580cebb3
5 changed files with 56 additions and 62 deletions
|
|
@ -1,13 +1,59 @@
|
|||
Internal formats
|
||||
================
|
||||
|
||||
.. todo:: brief overview for the internal formats index
|
||||
Yosys uses two different internal formats. The first is used to store an
|
||||
abstract syntax tree (AST) of a Verilog input file. This format is simply called
|
||||
AST and is generated by the Verilog Frontend. This data structure is consumed by
|
||||
a subsystem called AST Frontend [1]_. This AST Frontend then generates a design
|
||||
in Yosys' main internal format, the
|
||||
Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does
|
||||
that by first performing a number of simplifications within the AST
|
||||
representation and then generating RTLIL from the simplified AST data structure.
|
||||
|
||||
The RTLIL representation is used by all passes as input and outputs. This has
|
||||
the following advantages over using different representational formats between
|
||||
different passes:
|
||||
|
||||
- The passes can be rearranged in a different order and passes can be removed
|
||||
or inserted.
|
||||
|
||||
- Passes can simply pass-thru the parts of the design they don't change without
|
||||
the need to convert between formats. In fact Yosys passes output the same
|
||||
data structure they received as input and performs all changes in place.
|
||||
|
||||
- All passes use the same interface, thus reducing the effort required to
|
||||
understand a pass when reading the Yosys source code, e.g. when adding
|
||||
additional features.
|
||||
|
||||
The RTLIL representation is basically a netlist representation with the
|
||||
following additional features:
|
||||
|
||||
- An internal cell library with fixed-function cells to represent RTL datapath
|
||||
and register cells as well as logical gate-level cells (single-bit gates and
|
||||
registers).
|
||||
|
||||
- Support for multi-bit values that can use individual bits from wires as well
|
||||
as constant bits to represent coarse-grain netlists.
|
||||
|
||||
- Support for basic behavioural constructs (if-then-else structures and
|
||||
multi-case switches with a sensitivity list for updating the outputs).
|
||||
|
||||
- Support for multi-port memories.
|
||||
|
||||
The use of RTLIL also has the disadvantage of having a very powerful format
|
||||
between all passes, even when doing gate-level synthesis where the more advanced
|
||||
features are not needed. In order to reduce complexity for passes that operate
|
||||
on a low-level representation, these passes check the features used in the input
|
||||
RTLIL and fail to run when unsupported high-level constructs are used. In such
|
||||
cases a pass that transforms the higher-level constructs to lower-level
|
||||
constructs must be called from the synthesis script first.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 3
|
||||
|
||||
overview
|
||||
rtlil_rep
|
||||
rtlil_text
|
||||
cell_library
|
||||
rtlil_rep
|
||||
|
||||
.. [1]
|
||||
In Yosys the term pass is only used to refer to commands that operate on the
|
||||
RTLIL data structure.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,53 +0,0 @@
|
|||
Format overview
|
||||
===============
|
||||
|
||||
Yosys uses two different internal formats. The first is used to store an
|
||||
abstract syntax tree (AST) of a Verilog input file. This format is simply called
|
||||
AST and is generated by the Verilog Frontend. This data structure is consumed by
|
||||
a subsystem called AST Frontend [1]_. This AST Frontend then generates a design
|
||||
in Yosys' main internal format, the
|
||||
Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does
|
||||
that by first performing a number of simplifications within the AST
|
||||
representation and then generating RTLIL from the simplified AST data structure.
|
||||
|
||||
The RTLIL representation is used by all passes as input and outputs. This has
|
||||
the following advantages over using different representational formats between
|
||||
different passes:
|
||||
|
||||
- The passes can be rearranged in a different order and passes can be removed
|
||||
or inserted.
|
||||
|
||||
- Passes can simply pass-thru the parts of the design they don't change without
|
||||
the need to convert between formats. In fact Yosys passes output the same
|
||||
data structure they received as input and performs all changes in place.
|
||||
|
||||
- All passes use the same interface, thus reducing the effort required to
|
||||
understand a pass when reading the Yosys source code, e.g. when adding
|
||||
additional features.
|
||||
|
||||
The RTLIL representation is basically a netlist representation with the
|
||||
following additional features:
|
||||
|
||||
- An internal cell library with fixed-function cells to represent RTL datapath
|
||||
and register cells as well as logical gate-level cells (single-bit gates and
|
||||
registers).
|
||||
|
||||
- Support for multi-bit values that can use individual bits from wires as well
|
||||
as constant bits to represent coarse-grain netlists.
|
||||
|
||||
- Support for basic behavioural constructs (if-then-else structures and
|
||||
multi-case switches with a sensitivity list for updating the outputs).
|
||||
|
||||
- Support for multi-port memories.
|
||||
|
||||
The use of RTLIL also has the disadvantage of having a very powerful format
|
||||
between all passes, even when doing gate-level synthesis where the more advanced
|
||||
features are not needed. In order to reduce complexity for passes that operate
|
||||
on a low-level representation, these passes check the features used in the input
|
||||
RTLIL and fail to run when unsupported high-level constructs are used. In such
|
||||
cases a pass that transforms the higher-level constructs to lower-level
|
||||
constructs must be called from the synthesis script first.
|
||||
|
||||
.. [1]
|
||||
In Yosys the term pass is only used to refer to commands that operate on the
|
||||
RTLIL data structure.
|
||||
|
|
@ -1,297 +0,0 @@
|
|||
.. _chapter:textrtlil:
|
||||
|
||||
RTLIL text representation
|
||||
-------------------------
|
||||
|
||||
This appendix documents the text representation of RTLIL in extended Backus-Naur
|
||||
form (EBNF).
|
||||
|
||||
The grammar is not meant to represent semantic limitations. That is, the grammar
|
||||
is "permissive", and later stages of processing perform more rigorous checks.
|
||||
|
||||
The grammar is also not meant to represent the exact grammar used in the RTLIL
|
||||
frontend, since that grammar is specific to processing by lex and yacc, is even
|
||||
more permissive, and is somewhat less understandable than simple EBNF notation.
|
||||
|
||||
Finally, note that all statements (rules ending in ``-stmt``) terminate in an
|
||||
end-of-line. Because of this, a statement cannot be broken into multiple lines.
|
||||
|
||||
Lexical elements
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Characters
|
||||
^^^^^^^^^^
|
||||
|
||||
An RTLIL file is a stream of bytes. Strictly speaking, a "character" in an RTLIL
|
||||
file is a single byte. The lexer treats multi-byte encoded characters as
|
||||
consecutive single-byte characters. While other encodings *may* work, UTF-8 is
|
||||
known to be safe to use. Byte order marks at the beginning of the file will
|
||||
cause an error.
|
||||
|
||||
ASCII spaces (32) and tabs (9) separate lexer tokens.
|
||||
|
||||
A ``nonws`` character, used in identifiers, is any character whose encoding
|
||||
consists solely of bytes above ASCII space (32).
|
||||
|
||||
An ``eol`` is one or more consecutive ASCII newlines (10) and carriage returns
|
||||
(13).
|
||||
|
||||
Identifiers
|
||||
^^^^^^^^^^^
|
||||
|
||||
There are two types of identifiers in RTLIL:
|
||||
|
||||
- Publically visible identifiers
|
||||
- Auto-generated identifiers
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<id> ::= <public-id> | <autogen-id>
|
||||
<public-id> ::= \ <nonws>+
|
||||
<autogen-id> ::= $ <nonws>+
|
||||
|
||||
Values
|
||||
^^^^^^
|
||||
|
||||
A *value* consists of a width in bits and a bit representation, most
|
||||
significant bit first. Bits may be any of:
|
||||
|
||||
- ``0``: A logic zero value
|
||||
- ``1``: A logic one value
|
||||
- ``x``: An unknown logic value (or don't care in case patterns)
|
||||
- ``z``: A high-impedance value (or don't care in case patterns)
|
||||
- ``m``: A marked bit (internal use only)
|
||||
- ``-``: A don't care value
|
||||
|
||||
An *integer* is simply a signed integer value in decimal format. **Warning:**
|
||||
Integer constants are limited to 32 bits. That is, they may only be in the range
|
||||
:math:`[-2147483648, 2147483648)`. Integers outside this range will result in an
|
||||
error.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<value> ::= <decimal-digit>+ ' <binary-digit>*
|
||||
<decimal-digit> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
|
||||
<binary-digit> ::= 0 | 1 | x | z | m | -
|
||||
<integer> ::= -? <decimal-digit>+
|
||||
|
||||
Strings
|
||||
^^^^^^^
|
||||
|
||||
A string is a series of characters delimited by double-quote characters. Within
|
||||
a string, any character except ASCII NUL (0) may be used. In addition, certain
|
||||
escapes can be used:
|
||||
|
||||
- ``\n``: A newline
|
||||
- ``\t``: A tab
|
||||
- ``\ooo``: A character specified as a one, two, or three digit octal value
|
||||
|
||||
All other characters may be escaped by a backslash, and become the following
|
||||
character. Thus:
|
||||
|
||||
- ``\\``: A backslash
|
||||
- ``\"``: A double-quote
|
||||
- ``\r``: An 'r' character
|
||||
|
||||
Comments
|
||||
^^^^^^^^
|
||||
|
||||
A comment starts with a ``#`` character and proceeds to the end of the line. All
|
||||
comments are ignored.
|
||||
|
||||
File
|
||||
~~~~
|
||||
|
||||
A file consists of an optional autoindex statement followed by zero or more
|
||||
modules.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<file> ::= <autoidx-stmt>? <module>*
|
||||
|
||||
Autoindex statements
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The autoindex statement sets the global autoindex value used by Yosys when it
|
||||
needs to generate a unique name, e.g. ``flattenN``. The N part is filled with
|
||||
the value of the global autoindex value, which is subsequently incremented. This
|
||||
global has to be dumped into RTLIL, otherwise e.g. dumping and running a pass
|
||||
would have different properties than just running a pass on a warm design.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<autoidx-stmt> ::= autoidx <integer> <eol>
|
||||
|
||||
Modules
|
||||
^^^^^^^
|
||||
|
||||
Declares a module, with zero or more attributes, consisting of zero or more
|
||||
wires, memories, cells, processes, and connections.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<module> ::= <attr-stmt>* <module-stmt> <module-body> <module-end-stmt>
|
||||
<module-stmt> ::= module <id> <eol>
|
||||
<module-body> ::= (<param-stmt>
|
||||
| <wire>
|
||||
| <memory>
|
||||
| <cell>
|
||||
| <process>)*
|
||||
<param-stmt> ::= parameter <id> <constant>? <eol>
|
||||
<constant> ::= <value> | <integer> | <string>
|
||||
<module-end-stmt> ::= end <eol>
|
||||
|
||||
Attribute statements
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Declares an attribute with the given identifier and value.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<attr-stmt> ::= attribute <id> <constant> <eol>
|
||||
|
||||
Signal specifications
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A signal is anything that can be applied to a cell port, i.e. a constant value,
|
||||
all bits or a selection of bits from a wire, or concatenations of those.
|
||||
|
||||
**Warning:** When an integer constant is a sigspec, it is always 32 bits wide,
|
||||
2's complement. For example, a constant of :math:`-1` is the same as
|
||||
``32'11111111111111111111111111111111``, while a constant of :math:`1` is the
|
||||
same as ``32'1``.
|
||||
|
||||
See :ref:`sec:rtlil_sigspec` for an overview of signal specifications.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<sigspec> ::= <constant>
|
||||
| <wire-id>
|
||||
| <sigspec> [ <integer> (:<integer>)? ]
|
||||
| { <sigspec>* }
|
||||
|
||||
Connections
|
||||
^^^^^^^^^^^
|
||||
|
||||
Declares a connection between the given signals.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<conn-stmt> ::= connect <sigspec> <sigspec> <eol>
|
||||
|
||||
Wires
|
||||
^^^^^
|
||||
|
||||
Declares a wire, with zero or more attributes, with the given identifier and
|
||||
options in the enclosing module.
|
||||
|
||||
See :ref:`sec:rtlil_cell_wire` for an overview of wires.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<wire> ::= <attr-stmt>* <wire-stmt>
|
||||
<wire-stmt> ::= wire <wire-option>* <wire-id> <eol>
|
||||
<wire-id> ::= <id>
|
||||
<wire-option> ::= width <integer>
|
||||
| offset <integer>
|
||||
| input <integer>
|
||||
| output <integer>
|
||||
| inout <integer>
|
||||
| upto
|
||||
| signed
|
||||
|
||||
Memories
|
||||
^^^^^^^^
|
||||
|
||||
Declares a memory, with zero or more attributes, with the given identifier and
|
||||
options in the enclosing module.
|
||||
|
||||
See :ref:`sec:rtlil_memory` for an overview of memory cells, and
|
||||
:ref:`sec:memcells` for details about memory cell types.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<memory> ::= <attr-stmt>* <memory-stmt>
|
||||
<memory-stmt> ::= memory <memory-option>* <id> <eol>
|
||||
<memory-option> ::= width <integer>
|
||||
| size <integer>
|
||||
| offset <integer>
|
||||
|
||||
Cells
|
||||
^^^^^
|
||||
|
||||
Declares a cell, with zero or more attributes, with the given identifier and
|
||||
type in the enclosing module.
|
||||
|
||||
Cells perform functions on input signals. See
|
||||
:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<cell> ::= <attr-stmt>* <cell-stmt> <cell-body-stmt>* <cell-end-stmt>
|
||||
<cell-stmt> ::= cell <cell-type> <cell-id> <eol>
|
||||
<cell-id> ::= <id>
|
||||
<cell-type> ::= <id>
|
||||
<cell-body-stmt> ::= parameter (signed | real)? <id> <constant> <eol>
|
||||
| connect <id> <sigspec> <eol>
|
||||
<cell-end-stmt> ::= end <eol>
|
||||
|
||||
|
||||
Processes
|
||||
^^^^^^^^^
|
||||
|
||||
Declares a process, with zero or more attributes, with the given identifier in
|
||||
the enclosing module. The body of a process consists of zero or more
|
||||
assignments, exactly one switch, and zero or more syncs.
|
||||
|
||||
See :ref:`sec:rtlil_process` for an overview of processes.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<process> ::= <attr-stmt>* <proc-stmt> <process-body> <proc-end-stmt>
|
||||
<proc-stmt> ::= process <id> <eol>
|
||||
<process-body> ::= <assign-stmt>* <switch>? <assign-stmt>* <sync>*
|
||||
<assign-stmt> ::= assign <dest-sigspec> <src-sigspec> <eol>
|
||||
<dest-sigspec> ::= <sigspec>
|
||||
<src-sigspec> ::= <sigspec>
|
||||
<proc-end-stmt> ::= end <eol>
|
||||
|
||||
Switches
|
||||
^^^^^^^^
|
||||
|
||||
Switches test a signal for equality against a list of cases. Each case specifies
|
||||
a comma-separated list of signals to check against. If there are no signals in
|
||||
the list, then the case is the default case. The body of a case consists of zero
|
||||
or more switches and assignments. Both switches and cases may have zero or more
|
||||
attributes.
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<switch> ::= <switch-stmt> <case>* <switch-end-stmt>
|
||||
<switch-stmt> := <attr-stmt>* switch <sigspec> <eol>
|
||||
<case> ::= <attr-stmt>* <case-stmt> <case-body>
|
||||
<case-stmt> ::= case <compare>? <eol>
|
||||
<compare> ::= <sigspec> (, <sigspec>)*
|
||||
<case-body> ::= (<switch> | <assign-stmt>)*
|
||||
<switch-end-stmt> ::= end <eol>
|
||||
|
||||
Syncs
|
||||
^^^^^
|
||||
|
||||
Syncs update signals with other signals when an event happens. Such an event may
|
||||
be:
|
||||
|
||||
- An edge or level on a signal
|
||||
- Global clock ticks
|
||||
- Initialization
|
||||
- Always
|
||||
|
||||
.. code:: BNF
|
||||
|
||||
<sync> ::= <sync-stmt> <update-stmt>*
|
||||
<sync-stmt> ::= sync <sync-type> <sigspec> <eol>
|
||||
| sync global <eol>
|
||||
| sync init <eol>
|
||||
| sync always <eol>
|
||||
<sync-type> ::= low | high | posedge | negedge | edge
|
||||
<update-stmt> ::= update <dest-sigspec> <src-sigspec> <eol>
|
||||
Loading…
Add table
Add a link
Reference in a new issue