mirror of
https://github.com/YosysHQ/yosys
synced 2025-04-26 18:45:34 +00:00
Docs: tidying
- Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width.
This commit is contained in:
Krystine Sherwin
parent
a7e1c6e530
commit
9878e69d6c
18 changed files with 348 additions and 255 deletions
|
|
@ -23,8 +23,8 @@ representation that closely resembles the structure of the original Verilog
|
|||
code. The Verilog frontend consists of three components, the Preprocessor, the
|
||||
Lexer and the Parser.
|
||||
|
||||
The source code to the Verilog frontend can be found in ``frontends/verilog/``
|
||||
in the Yosys source tree.
|
||||
The source code to the Verilog frontend can be found in
|
||||
:file:`frontends/verilog/` in the Yosys source tree.
|
||||
|
||||
The Verilog preprocessor
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -37,20 +37,19 @@ It is implemented as a C++ function that is passed a file descriptor as input
|
|||
and returns the pre-processed Verilog code as a ``std::string``.
|
||||
|
||||
The source code to the Verilog Preprocessor can be found in
|
||||
``frontends/verilog/preproc.cc`` in the Yosys source tree.
|
||||
:file:`frontends/verilog/preproc.cc` in the Yosys source tree.
|
||||
|
||||
The Verilog lexer
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Verilog Lexer is written using the lexer generator flex. Its source code
|
||||
can be found in ``frontends/verilog/verilog_lexer.l`` in the Yosys source tree.
|
||||
The Verilog Lexer is written using the lexer generator flex. Its source code can
|
||||
be found in :file:`frontends/verilog/verilog_lexer.l` in the Yosys source tree.
|
||||
The lexer does little more than identifying all keywords and literals recognised
|
||||
by the Yosys Verilog frontend.
|
||||
|
||||
The lexer keeps track of the current location in the Verilog source code
|
||||
using some global variables. These variables are used by the constructor
|
||||
of AST nodes to annotate each node with the source code location it
|
||||
originated from.
|
||||
The lexer keeps track of the current location in the Verilog source code using
|
||||
some global variables. These variables are used by the constructor of AST nodes
|
||||
to annotate each node with the source code location it originated from.
|
||||
|
||||
Finally the lexer identifies and handles special comments such as "``// synopsys
|
||||
translate_off``" and "``// synopsys full_case``". (It is recommended to use
|
||||
|
|
@ -62,10 +61,11 @@ The Verilog parser
|
|||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Verilog Parser is written using the parser generator bison. Its source code
|
||||
can be found in ``frontends/verilog/verilog_parser.y`` in the Yosys source tree.
|
||||
can be found in :file:`frontends/verilog/verilog_parser.y` in the Yosys source
|
||||
tree.
|
||||
|
||||
It generates an AST using the ``AST::AstNode`` data structure defined in
|
||||
``frontends/ast/ast.h``. An ``AST::AstNode`` object has the following
|
||||
:file:`frontends/ast/ast.h`. An ``AST::AstNode`` object has the following
|
||||
properties:
|
||||
|
||||
.. list-table:: AST node types with their corresponding Verilog constructs.
|
||||
|
|
@ -77,7 +77,8 @@ properties:
|
|||
* - AST_NONE
|
||||
- This Node type should never be used.
|
||||
* - AST_DESIGN
|
||||
- This node type is used for the top node of the AST tree. It has no corresponding Verilog construct.
|
||||
- This node type is used for the top node of the AST tree. It has no
|
||||
corresponding Verilog construct.
|
||||
* - AST_MODULE, AST_TASK, AST_FUNCTION
|
||||
- ``module``, ``task`` and ``function``
|
||||
* - AST_WIRE
|
||||
|
|
@ -99,9 +100,11 @@ properties:
|
|||
* - AST_CELLTYPE
|
||||
- The type of cell in cell instantiation
|
||||
* - AST_IDENTIFIER
|
||||
- An Identifier (signal name in expression or cell/task/etc. name in other contexts)
|
||||
- An Identifier (signal name in expression or cell/task/etc. name in other
|
||||
contexts)
|
||||
* - AST_PREFIX
|
||||
- Construct an identifier in the form <prefix>[<index>].<suffix> (used only in advanced generate constructs)
|
||||
- Construct an identifier in the form <prefix>[<index>].<suffix> (used
|
||||
only in advanced generate constructs)
|
||||
* - AST_FCALL, AST_TCALL
|
||||
- Call to function or task
|
||||
* - AST_TO_SIGNED, AST_TO_UNSIGNED
|
||||
|
|
@ -113,7 +116,8 @@ properties:
|
|||
* - AST_REDUCE_AND, AST_REDUCE_OR, AST_REDUCE_XOR, AST_REDUCE_XNOR
|
||||
- The unary reduction operators ``~``, ``&``, ``|``, ``^`` and ``~^``
|
||||
* - AST_REDUCE_BOOL
|
||||
- Conversion from multi-bit value to boolean value (equivalent to AST_REDUCE_OR)
|
||||
- Conversion from multi-bit value to boolean value (equivalent to
|
||||
AST_REDUCE_OR)
|
||||
* - AST_SHIFT_LEFT, AST_SHIFT_RIGHT, AST_SHIFT_SLEFT, AST_SHIFT_SRIGHT
|
||||
- The shift operators ``<<``, ``>>``, ``<<<`` and ``>>>``
|
||||
* - AST_LT, AST_LE, AST_EQ, AST_NE, AST_GE, AST_GT
|
||||
|
|
@ -127,7 +131,8 @@ properties:
|
|||
* - AST_TERNARY
|
||||
- The ternary ``?:``-operator
|
||||
* - AST_MEMRD AST_MEMWR
|
||||
- Read and write memories. These nodes are generated by the AST simplifier for writes/reads to/from Verilog arrays.
|
||||
- Read and write memories. These nodes are generated by the AST simplifier
|
||||
for writes/reads to/from Verilog arrays.
|
||||
* - AST_ASSIGN
|
||||
- An ``assign`` statement
|
||||
* - AST_CELL
|
||||
|
|
@ -139,13 +144,16 @@ properties:
|
|||
* - AST_BLOCK
|
||||
- A ``begin``-``end``-block
|
||||
* - AST_ASSIGN_EQ. AST_ASSIGN_LE
|
||||
- Blocking (``=``) and nonblocking (``<=``) assignments within an ``always``- or ``initial``-block
|
||||
- Blocking (``=``) and nonblocking (``<=``) assignments within an
|
||||
``always``- or ``initial``-block
|
||||
* - AST_CASE. AST_COND, AST_DEFAULT
|
||||
- The ``case`` (``if``) statements, conditions within a case and the default case respectively
|
||||
- The ``case`` (``if``) statements, conditions within a case and the
|
||||
default case respectively
|
||||
* - AST_FOR
|
||||
- A ``for``-loop with an ``always``- or ``initial``-block
|
||||
* - AST_GENVAR, AST_GENBLOCK, AST_GENFOR, AST_GENIF
|
||||
- The ``genvar`` and ``generate`` keywords and ``for`` and ``if`` within a generate block.
|
||||
- The ``genvar`` and ``generate`` keywords and ``for`` and ``if`` within a
|
||||
generate block.
|
||||
* - AST_POSEDGE, AST_NEGEDGE, AST_EDGE
|
||||
- Event conditions for ``always`` blocks.
|
||||
|
||||
|
|
@ -295,7 +303,7 @@ correct intermediate values whenever one of the previously assigned signals is
|
|||
used in an expression.
|
||||
|
||||
Unfortunately the generation of a correct
|
||||
``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree for behavioural code is a
|
||||
``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree for behavioural code is a
|
||||
non-trivial task. The AST frontend solves the problem using the approach
|
||||
described on the following pages. The following example illustrates what the
|
||||
algorithm is supposed to do. Consider the following Verilog code:
|
||||
|
|
@ -371,7 +379,7 @@ expressions after the initial assignment. The signal ``out2`` is assigned using
|
|||
nonblocking assignments and therefore is not substituted on the right-hand-side
|
||||
expressions.
|
||||
|
||||
The ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree must be interpreted the
|
||||
The ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree must be interpreted the
|
||||
following way:
|
||||
|
||||
- On each case level (the body of the process is the root case), first the
|
||||
|
|
@ -388,7 +396,7 @@ following way:
|
|||
objects within a ``RTLIL::CaseRule`` is preserved with respect to the
|
||||
original AST and Verilog code.
|
||||
|
||||
- The whole ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree describes an
|
||||
- The whole ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree describes an
|
||||
asynchronous circuit. I.e. the decision tree formed by the switches can be
|
||||
seen independently for each assigned signal. Whenever one assigned signal
|
||||
changes, all signals that depend on the changed signals are to be updated.
|
||||
|
|
@ -403,11 +411,11 @@ the original Verilog code has been translated into the synchronization type
|
|||
(posedge) and signal (``\clock``) for the ``RTLIL::SyncRule`` object. In the
|
||||
case of this simple example the ``RTLIL::SyncRule`` object is later simply
|
||||
transformed into a set of d-type flip-flops and the
|
||||
``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree to a decision tree using
|
||||
``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree to a decision tree using
|
||||
multiplexers.
|
||||
|
||||
In more complex examples (e.g. asynchronous resets) the part of the
|
||||
``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the asynchronous
|
||||
``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree that describes the asynchronous
|
||||
reset must first be transformed to the correct ``RTLIL::SyncRule`` objects. This
|
||||
is done by the ``proc_arst`` pass.
|
||||
|
||||
|
|
@ -583,7 +591,7 @@ Note how this step always overrides a previous assignment to the old temporary
|
|||
variable. Other than nonblocking assignments, the old assignment could still
|
||||
have an effect somewhere in the design, as there have been calls to
|
||||
``AST::AstNode::genRTLIL()`` with a
|
||||
``subst_rvalue_from``/ ``subst_rvalue_to``-tuple that contained the
|
||||
``subst_rvalue_from``/\ ``subst_rvalue_to``-tuple that contained the
|
||||
right-hand-side of the old assignment.
|
||||
|
||||
The proc pass
|
||||
|
|
@ -609,17 +617,17 @@ from a behavioural model to an RTL representation is performed by the
|
|||
and the top-level ``RTLIL::SwitchRule`` has been removed.
|
||||
|
||||
- | :cmd:ref:`proc_mux`
|
||||
| This pass converts the ``RTLIL::CaseRule``/ ``RTLIL::SwitchRule``-tree to a
|
||||
| This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to a
|
||||
tree of multiplexers per written signal. After this, the ``RTLIL::Process``
|
||||
structure only contains the ``RTLIL::SyncRule`` s that describe the output
|
||||
registers.
|
||||
|
||||
- | :cmd:ref:`proc_dff`
|
||||
| This pass replaces the ``RTLIL::SyncRule`` s to d-type flip-flops (with
|
||||
| This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with
|
||||
asynchronous resets if necessary).
|
||||
|
||||
- | :cmd:ref:`proc_dff`
|
||||
| This pass replaces the ``RTLIL::MemWriteAction`` s with ``$memwr`` cells.
|
||||
| This pass replaces the ``RTLIL::MemWriteAction``\ s with ``$memwr`` cells.
|
||||
|
||||
- | :cmd:ref:`proc_clean`
|
||||
| A final call to :cmd:ref:`proc_clean` removes the now empty
|
||||
|
|
@ -636,18 +644,13 @@ Second it improves flexibility. This scheme can easily be extended to support
|
|||
other types of storage-elements, such as sr-latches or d-latches, without having
|
||||
to extend the actual Verilog frontend.
|
||||
|
||||
Synthesizing Verilog arrays
|
||||
---------------------------
|
||||
|
||||
.. todo::
|
||||
.. todo:: Synthesizing Verilog arrays
|
||||
|
||||
Add some information on the generation of ``$memrd`` and ``$memwr`` cells and
|
||||
how they are processed in the memory pass.
|
||||
|
||||
Synthesizing parametric designs
|
||||
-------------------------------
|
||||
|
||||
.. todo::
|
||||
.. todo:: Synthesizing parametric designs
|
||||
|
||||
Add some information on the ``RTLIL::Module::derive()`` method and how it is
|
||||
used to synthesize parametric modules via the hierarchy pass.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue