mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-06-06 14:13:23 +00:00
Code Activity

Docs: tidying

Browse source 
- 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 2024-01-30 13:31:00 +13:00
parent a7e1c6e530
commit 9878e69d6c
No known key found for this signature in database
18 changed files with 348 additions and 255 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/source/yosys_internals/extending_yosys/abc_flow.rst
View file

@ -22,7 +22,7 @@ guide to the syntax:
By convention, all delays in ``specify`` blocks are in integer picoseconds.
Files containing ``specify`` blocks should be read with the ``-specify`` option
to ``read_verilog`` so that they aren't skipped.
to :cmd:ref:`read_verilog` so that they aren't skipped.
LUTs
^^^^
@ -41,9 +41,9 @@ DFFs
DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has
some specific requirements for this to be valid: - the DFF must initialise to
zero (consider using ``dfflegalize`` to ensure this). - the DFF cannot have any
asynchronous resets/sets (see the simplification idiom and the Boxes section for
what to do here).
zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot
have any asynchronous resets/sets (see the simplification idiom and the Boxes
section for what to do here).
It is worth noting that in pure ``abc9`` mode, only the setup and arrival times
are passed to ABC9 (specifically, they are modelled as buffers with the given
@ -59,7 +59,7 @@ mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and
:cmd:ref:`synth_quicklogic` for the PolarPro3.
DFFs are usually specified to have setup constraints against the clock on the
input signals, and an arrival time for the Q output.
input signals, and an arrival time for the ``Q`` output.
Boxes
^^^^^

41
docs/source/yosys_internals/extending_yosys/extensions.rst
View file

@ -6,7 +6,7 @@ Writing extensions
.. todo:: check text is coherent
.. todo:: update to use ``/code_examples/extensions/test*.log``
.. todo:: update to use :file:`/code_examples/extensions/test*.log`
This chapter contains some bits and pieces of information about programming
yosys extensions. Don't be afraid to ask questions on the YosysHQ Slack.
@ -21,7 +21,11 @@ Quick guide
-----------
Code examples from this section are included in the
``docs/code_examples/extensions/`` directory of the Yosys source code.
|code_examples/extensions|_ directory of the Yosys source code.
.. |code_examples/extensions| replace:: :file:`docs/source/code_examples/extensions`
.. _code_examples/extensions: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/extensions
Program components and data formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -31,7 +35,7 @@ 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``):
commands :cmd:ref:`proc` and :cmd:ref:`memory` (or :yoscrypt:`memory -nomap`):
.. figure:: /_images/internals/simplified_rtlil.*
:class: width-helper
@ -41,6 +45,8 @@ commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``):
It is possible to only work on this simpler version:
.. todo:: consider replacing inline code
.. code:: c++
for (RTLIL::Module *module : design->selected_modules() {
@ -66,10 +72,10 @@ with, and lists off the current design's modules.
.. literalinclude:: /code_examples/extensions/my_cmd.cc
:language: c++
:lines: 1, 4, 6, 7-20
:caption: Example command :yoscrypt:`my_cmd` from ``my_cmd.cc``
:caption: Example command :yoscrypt:`my_cmd` from :file:`my_cmd.cc`
Note that we are making a global instance of a class derived from
``Yosys::Pass``, which we get by including ``kernel/yosys.h``.
``Yosys::Pass``, which we get by including :file:`kernel/yosys.h`.
Compiling to a plugin
~~~~~~~~~~~~~~~~~~~~~
@ -80,6 +86,8 @@ to create plugins.
The following command compiles our example :yoscrypt:`my_cmd` to a Yosys plugin:
.. todo:: replace inline code
.. code:: shell
yosys-config --exec --cxx --cxxflags --ldflags \
@ -120,7 +128,7 @@ We'll do the same as before and format it as a a ``Yosys::Pass``.
.. literalinclude:: /code_examples/extensions/my_cmd.cc
:language: c++
:lines: 23-47
:caption: :yoscrypt:`test1` - creating the absval module, from ``my_cmd.cc``
:caption: :yoscrypt:`test1` - creating the absval module, from :file:`my_cmd.cc`
.. code:: shell-session
@ -160,7 +168,7 @@ Consider the following module:
.. literalinclude:: /code_examples/extensions/sigmap_test.v
:language: Verilog
:caption: sigmap_test.v
:caption: :file:`sigmap_test.v`
In this case ``a``, ``x``, and ``y`` are all different names for the same
signal. However:
@ -204,7 +212,10 @@ Use ``log_id()`` to create a C-string for an ``RTLIL::IdString``:
log("Name of this module: %s\n", log_id(module->name));
Use ``log_header()`` and ``log_push()``/``log_pop()`` to structure log messages:
Use ``log_header()`` and ``log_push()``/\ ``log_pop()`` to structure log
messages:
.. todo:: replace inline code
.. code:: C++
@ -219,6 +230,8 @@ Error handling
Use ``log_error()`` to report a non-recoverable error:
.. todo:: replace inline code
.. code:: C++
if (design->modules.count(module->name) != 0)
@ -238,20 +251,22 @@ The "stubnets" example module
------------------------------
The following is the complete code of the "stubnets" example module. It is
included in the Yosys source distribution as
``docs/source/code_examples/stubnets/stubnets.cc``.
included in the Yosys source distribution under |code_examples/stubnets|_.
.. |code_examples/stubnets| replace:: :file:`docs/source/code_examples/stubnets`
.. _code_examples/stubnets: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/stubnets
.. literalinclude:: /code_examples/stubnets/stubnets.cc
:language: c++
:linenos:
:caption: docs/source/code_examples/stubnets/stubnets.cc
:caption: :file:`stubnets.cc`
.. literalinclude:: /code_examples/stubnets/Makefile
:language: makefile
:linenos:
:caption: docs/source/code_examples/stubnets/Makefile
:caption: :file:`Makefile`
.. literalinclude:: /code_examples/stubnets/test.v
:language: verilog
:linenos:
:caption: docs/source/code_examples/stubnets/test.v
:caption: :file:`test.v`

1
docs/source/yosys_internals/flow/index.rst
View file

@ -1,7 +1,6 @@
Internal flow
=============
A (usually short) synthesis script controls Yosys.
These scripts contain three types of commands:

73
docs/source/yosys_internals/flow/verilog_frontend.rst
View file

@ -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.

45
docs/source/yosys_internals/formats/cell_library.rst
View file

@ -9,8 +9,11 @@ Internal cell library
.. todo:: less academic, also check formatting consistency
Most of the passes in Yosys operate on netlists, i.e. they only care about the
RTLIL::Wire and RTLIL::Cell objects in an RTLIL::Module. This chapter discusses
the cell types used by Yosys to represent a behavioural design internally.
``RTLIL::Wire`` and ``RTLIL::Cell`` objects in an ``RTLIL::Module``. This
chapter discusses the cell types used by Yosys to represent a behavioural design
internally.
.. TODO:: is this chapter split preserved
This chapter is split in two parts. In the first part the internal RTL cells are
covered. These cells are used to represent the design on a coarse grain level.
@ -33,7 +36,7 @@ parameters in sync with the size of the signals connected to the inputs and
outputs.
Simulation models for the RTL cells can be found in the file
``techlibs/common/simlib.v`` in the Yosys source tree.
:file:`techlibs/common/simlib.v` in the Yosys source tree.
Unary operators
~~~~~~~~~~~~~~~
@ -42,8 +45,8 @@ All unary RTL cells have one input port ``\A`` and one output port ``\Y``. They
also have the following parameters:
``\A_SIGNED``
Set to a non-zero value if the input ``\A`` is signed and therefore
should be sign-extended when needed.
Set to a non-zero value if the input ``\A`` is signed and therefore should be
sign-extended when needed.
``\A_WIDTH``
The width of the input port ``\A``.
@ -110,7 +113,7 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port
:name: tab:CellLib_binary
======================= ============= ======================= =========
Verilog Cell Type Verilog Cell Type
Verilog Cell Type Verilog Cell Type
======================= ============= ======================= =========
:verilog:`Y = A & B` $and :verilog:`Y = A < B` $lt
:verilog:`Y = A | B` $or :verilog:`Y = A <= B` $le
@ -124,7 +127,7 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port
:verilog:`Y = A || B` $logic_or :verilog:`Y = A / B` $div
:verilog:`Y = A === B` $eqx :verilog:`Y = A % B` $mod
:verilog:`Y = A !== B` $nex ``N/A`` $divfloor
:verilog:`Y = A ** B` $pow ``N/A`` $modfoor
:verilog:`Y = A ** B` $pow ``N/A`` $modfloor
======================= ============= ======================= =========
The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl``
@ -141,7 +144,7 @@ positions are filled with undef (x) bits, and corresponds to the Verilog indexed
part-select expression.
For the binary cells that output a logical value (``$logic_and``, ``$logic_or``,
``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt)``, when
``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when
the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and
only the least significant bit varies.
@ -334,11 +337,11 @@ cells.
Memories
~~~~~~~~
Memories are either represented using RTLIL::Memory objects, ``$memrd_v2``,
Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``,
``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone.
In the first alternative the RTLIL::Memory objects hold the general metadata for
the memory (bit width, size in number of words, etc.) and for each port a
In the first alternative the ``RTLIL::Memory`` objects hold the general metadata
for the memory (bit width, size in number of words, etc.) and for each port a
``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having
individual cells for read and write ports has the advantage that they can be
consolidated using resource sharing passes. In some cases this drastically
@ -353,7 +356,7 @@ address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input
parameters:
``\MEMID``
The name of the RTLIL::Memory object that is associated with this read
The name of the ``RTLIL::Memory`` object that is associated with this read
port.
``\ABITS``
@ -413,7 +416,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``
``\DATA``. They also have the following parameters:
``\MEMID``
The name of the RTLIL::Memory object that is associated with this write
The name of the ``RTLIL::Memory`` object that is associated with this write
port.
``\ABITS``
@ -452,7 +455,7 @@ to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for
synthesis to succeed.
``\MEMID``
The name of the RTLIL::Memory object that is associated with this
The name of the ``RTLIL::Memory`` object that is associated with this
initialization cell.
``\ABITS``
@ -468,9 +471,9 @@ synthesis to succeed.
The cell with the higher integer value in this parameter wins an
initialization conflict.
The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass (i.e.~its
various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and
The HDL frontend models a memory using ``RTLIL::Memory`` objects and
asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass
(i.e. its various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and
``$memwr_v2`` cells making them synchronous, then converts them to a single
``$mem_v2`` cell and (optionally) maps this cell type to ``$dff`` cells for the
individual words and multiplexer-based address decoders for the read and write
@ -480,7 +483,7 @@ is left in the design.
The ``$mem_v2`` cell provides the following parameters:
``\MEMID``
The name of the original RTLIL::Memory object that became this
The name of the original ``RTLIL::Memory`` object that became this
``$mem_v2`` cell.
``\SIZE``
@ -1145,8 +1148,8 @@ mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass.
The combinatorial logic cells can be mapped to physical cells from a Liberty
file via ABC using the abc pass.
Add information about ``$slice`` and ``$concat`` cells.
.. todo:: Add information about ``$slice`` and ``$concat`` cells.
Add information about ``$lut`` and ``$sop`` cells.
.. todo:: Add information about ``$lut`` and ``$sop`` cells.
Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells.
.. todo:: Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells.

2
docs/source/yosys_internals/formats/index.rst
View file

@ -1,6 +1,8 @@
Internal formats
================
.. todo:: brief overview for the internal formats index
.. toctree::
:maxdepth: 3

55
docs/source/yosys_internals/techmap.rst
View file

@ -12,6 +12,13 @@ Yosys' internal cell types (such as ``$or``) as well as user-defined cell types.
file.
- Generate blocks and recursion are powerful tools for writing map files.
Code examples used in this document are included in the Yosys code base under
|code_examples/techmap|_.
.. |code_examples/techmap| replace:: :file:`docs/source/code_examples/techmap`
.. _code_examples/techmap: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/techmap
Mapping OR3X1
~~~~~~~~~~~~~
@ -24,31 +31,32 @@ Mapping OR3X1
.. literalinclude:: /code_examples/techmap/red_or3x1_map.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/red_or3x1_map.v``
:caption: :file:`red_or3x1_map.v`
.. figure:: /_images/code_examples/techmap/red_or3x1.*
:class: width-helper
.. literalinclude:: /code_examples/techmap/red_or3x1_test.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/techmap/red_or3x1_test.ys``
:caption: :file:`red_or3x1_test.ys`
.. literalinclude:: /code_examples/techmap/red_or3x1_test.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/red_or3x1_test.v``
:caption: :file:`red_or3x1_test.v`
Conditional techmap
~~~~~~~~~~~~~~~~~~~
- In some cases only cells with certain properties should be substituted.
- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module
in the map file for a certain set of parameters.
- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it
is non-zero then the module is disabled for this set of parameters.
- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module in the map
file for a certain set of parameters.
- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it is non-zero
then the module is disabled for this set of parameters.
- Example use-cases:
- coarse-grain cell types that only operate on certain bit widths
- memory resources for different memory geometries (width, depth, ports, etc.)
- memory resources for different memory geometries (width, depth, ports,
etc.)
Example:
@ -57,22 +65,22 @@ Example:
.. literalinclude:: /code_examples/techmap/sym_mul_map.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/sym_mul_map.v``
:caption: :file:`sym_mul_map.v`
.. literalinclude:: /code_examples/techmap/sym_mul_test.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/sym_mul_test.v``
:caption: :file:`sym_mul_test.v`
.. literalinclude:: /code_examples/techmap/sym_mul_test.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/techmap/sym_mul_test.ys``
:caption: :file:`sym_mul_test.ys`
Scripting in map modules
~~~~~~~~~~~~~~~~~~~~~~~~
- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts
in the context of the replacement module.
- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts in the
context of the replacement module.
- The wire that comes first in alphabetical oder is interpreted as string (must
be connected to constants) that is executed as script. Then the wire is
removed. Repeat.
@ -96,15 +104,15 @@ Example:
.. literalinclude:: /code_examples/techmap/mymul_map.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/mymul_map.v``
:caption: :file:`mymul_map.v`
.. literalinclude:: /code_examples/techmap/mymul_test.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/mymul_test.v``
:caption: :file:`mymul_test.v`
.. literalinclude:: /code_examples/techmap/mymul_test.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/techmap/mymul_test.ys``
:caption: :file:`mymul_test.ys`
Handling constant inputs
~~~~~~~~~~~~~~~~~~~~~~~~
@ -126,15 +134,15 @@ Example:
.. literalinclude:: /code_examples/techmap/mulshift_map.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/mulshift_map.v``
:caption: :file:`mulshift_map.v`
.. literalinclude:: /code_examples/techmap/mulshift_test.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/mulshift_test.v``
:caption: :file:`mulshift_test.v`
.. literalinclude:: /code_examples/techmap/mulshift_test.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/techmap/mulshift_test.ys``
:caption: :file:`mulshift_test.ys`
Handling shorted inputs
~~~~~~~~~~~~~~~~~~~~~~~
@ -143,7 +151,8 @@ Handling shorted inputs
``_TECHMAP_CONNMAP_<port-name>_`` can be used to handle shorted inputs.
- Each bit of the port correlates to an ``_TECHMAP_BITS_CONNMAP_`` bits wide
number in ``_TECHMAP_CONNMAP_<port-name>_``.
- Each unique signal bit is assigned its own number. Identical fields in the ``_TECHMAP_CONNMAP_<port-name>_`` parameters mean shorted signal bits.
- Each unique signal bit is assigned its own number. Identical fields in the
``_TECHMAP_CONNMAP_<port-name>_`` parameters mean shorted signal bits.
- The numbers 0-3 are reserved for ``0``, ``1``, ``x``, and ``z`` respectively.
- Example use-cases:
@ -157,15 +166,15 @@ Example:
.. literalinclude:: /code_examples/techmap/addshift_map.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/addshift_map.v``
:caption: :file:`addshift_map.v`
.. literalinclude:: /code_examples/techmap/addshift_test.v
:language: verilog
:caption: ``docs/source/code_examples/techmap/addshift_test.v``
:caption: :file:`addshift_test.v`
.. literalinclude:: /code_examples/techmap/addshift_test.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/techmap/addshift_test.ys``
:caption: :file:`addshift_test.ys`
Notes on using techmap
~~~~~~~~~~~~~~~~~~~~~~