diff options
Diffstat (limited to 'docs/source/appendix/CHAPTER_TextRtlil.rst')
| -rw-r--r-- | docs/source/appendix/CHAPTER_TextRtlil.rst | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/docs/source/appendix/CHAPTER_TextRtlil.rst b/docs/source/appendix/CHAPTER_TextRtlil.rst new file mode 100644 index 000000000..dc3d72230 --- /dev/null +++ b/docs/source/appendix/CHAPTER_TextRtlil.rst @@ -0,0 +1,298 @@ +.. _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 :numref:`Sec. %s <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 :numref:`Sec. %s <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 :numref:`Sec. %s <sec:rtlil_memory>` for an overview of memory cells, and +:numref:`Sec. %s <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 :numref:`Chap. %s +<chapter:celllib>` 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 :numref:`Sec. %s <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> |