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

Move (most of) ExOth and ExAdv slides

Browse source
This commit is contained in:
Krystine Sherwin 2023-08-07 12:58:40 +12:00
parent 7ab051778e
commit 8ade2182b0
No known key found for this signature in database
49 changed files with 828 additions and 1027 deletions
Download patch file Download diff file Expand all files Collapse all files

249
docs/source/using_yosys/more_scripting/selections.rst
View file

@ -1,6 +1,251 @@
Selections
~~~~~~~~~~
----------
.. TODO: copypaste
Most Yosys commands make use of the "selection framework" of Yosys. It can be
used to apply commands only to part of the design. For example:
.. code:: yoscrypt
delete # will delete the whole design, but
delete foobar # will only delete the module foobar.
The ``select`` command can be used to create a selection for subsequent
commands. For example:
.. code:: yoscrypt
select foobar # select the module foobar
delete # delete selected objects
select -clear # reset selection (select whole design)
See :doc:`/cmd/select`
Also :doc:`/cmd/show` and :doc:`/cmd/dump`
How to make a selection
~~~~~~~~~~~~~~~~~~~~~~~
Selection by object name
^^^^^^^^^^^^^^^^^^^^^^^^
The easiest way to select objects is by object name. This is usually only done
in synthesis scripts that are hand-tailored for a specific design.
.. code:: yoscrypt
select foobar # select module foobar
select foo* # select all modules whose names start with foo
select foo*/bar* # select all objects matching bar* from modules matching foo*
select */clk # select objects named clk from all modules
Module and design context
^^^^^^^^^^^^^^^^^^^^^^^^^
Commands can be executed in *module/* or *design/* context. Until now
all commands have been executed in design context. The ``cd`` command can be
used to switch to module context.
In module context all commands only effect the active module. Objects in the
module are selected without the ``<module_name>/`` prefix. For example:
.. code:: yoscrypt
cd foo # switch to module foo
delete bar # delete object foo/bar
cd mycpu # switch to module mycpu
dump reg_* # print details on all objects whose names start with reg_
cd .. # switch back to design
Note: Most synthesis scripts never switch to module context. But it is a very
powerful tool for interactive design investigation.
Selecting by object property or type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Special patterns can be used to select by object property or type. For example:
.. code:: yoscrypt
select w:reg_* # select all wires whose names start with reg_
select a:foobar # select all objects with the attribute foobar set
select a:foobar=42 # select all objects with the attribute foobar set to 42
select A:blabla # select all modules with the attribute blabla set
select foo/t:$add # select all $add cells from the module foo
A complete list of this pattern expressions can be found in the command
reference to the ``select`` command.
Combining selection
^^^^^^^^^^^^^^^^^^^
When more than one selection expression is used in one statement, then they are
pushed on a stack. The final elements on the stack are combined into a union:
.. code:: yoscrypt
select t:$dff r:WIDTH>1 # all cells of type $dff and/or with a parameter WIDTH > 1
Special ``%``-commands can be used to combine the elements on the stack:
.. code:: yoscrypt
select t:$dff r:WIDTH>1 %i # all cells of type $dff *AND* with a parameter WIDTH > 1
Examples for ``%``-codes (see :doc:`/cmd/select` for full list):
- ``%u``: union of top two elements on stack -- pop 2, push 1
- ``%d``: difference of top two elements on stack -- pop 2, push 1
- ``%i``: intersection of top two elements on stack -- pop 2, push 1
- ``%n``: inverse of top element on stack -- pop 1, push 1
Expanding selections
^^^^^^^^^^^^^^^^^^^^
Selections of cells and wires can be expanded along connections using
``%``-codes for selecting input cones (``%ci``), output cones (``%co``), or
both (``%x``).
.. code:: yoscrypt
# select all wires that are inputs to $add cells
select t:$add %ci w:* %i
Additional constraints such as port names can be specified.
.. code:: yoscrypt
# select all wires that connect a "Q" output with a "D" input
select c:* %co:+[Q] w:* %i c:* %ci:+[D] w:* %i %i
# select the multiplexer tree that drives the signal 'state'
select state %ci*:+$mux,$pmux[A,B,Y]
See :doc:`/cmd/select` for full documentation of these expressions.
Incremental selection
^^^^^^^^^^^^^^^^^^^^^
Sometimes a selection can most easily be described by a series of add/delete
operations. The commands ``select -add`` and ``select -del`` respectively add or
remove objects from the current selection instead of overwriting it.
.. code:: yoscrypt
select -none # start with an empty selection
select -add reg_* # select a bunch of objects
select -del reg_42 # but not this one
select -add state %ci # and add more stuff
Within a select expression the token ``%`` can be used to push the previous selection
on the stack.
.. code:: yoscrypt
select t:$add t:$sub # select all $add and $sub cells
select % %ci % %d # select only the input wires to those cells
Creating selection variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Selections can be stored under a name with the ``select -set <name>``
command. The stored selections can be used in later select expressions
using the syntax ``@<name>``.
.. code:: yoscrypt
select -set cone_a state_a %ci*:-$dff # set @cone_a to the input cone of state_a
select -set cone_b state_b %ci*:-$dff # set @cone_b to the input cone of state_b
select @cone_a @cone_b %i # select the objects that are in both cones
Remember that select expressions can also be used directly as arguments to most
commands. Some commands also except a single select argument to some options.
In those cases selection variables must be used to capture more complex selections.
.. code:: yoscrypt
dump @cone_a @cone_b
select -set cone_ab @cone_a @cone_b %i
show -color red @cone_ab -color magenta @cone_a -color blue @cone_b
Example:
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/select.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/select.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/select.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/select.ys``
.. figure:: ../../../images/res/PRESENTATION_ExAdv/select.*
:class: width-helper
Interactive Design Investigation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yosys can also be used to investigate designs (or netlists created from other
tools).
- The selection mechanism, especially patterns such as ``%ci`` and ``%co``,
can be used to figure out how parts of the design are connected.
- Commands such as ``submod``, ``expose``, and ``splice`` can be used to
transform the design into an equivalent design that is easier to analyse.
- Commands such as ``eval`` and ``sat`` can be used to investigate the behavior
of the circuit.
- :doc:`/cmd/show`.
- :doc:`/cmd/dump`.
Reorganizing a module
^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ../../../resources/PRESENTATION_ExOth/scrambler.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExOth/scrambler.v``
.. code:: yoscrypt
read_verilog scrambler.v
hierarchy; proc;;
cd scrambler
submod -name xorshift32 \
xs %c %ci %D %c %ci:+[D] %D \
%ci*:-$dff xs %co %ci %d
.. figure:: ../../../images/res/PRESENTATION_ExOth/scrambler_p01.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExOth/scrambler_p02.*
:class: width-helper
Analysis of circuit behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: text
> read_verilog scrambler.v
> hierarchy; proc;; cd scrambler
> submod -name xorshift32 xs %c %ci %D %c %ci:+[D] %D %ci*:-$dff xs %co %ci %d
> cd xorshift32
> rename n2 in
> rename n1 out
> eval -set in 1 -show out
Eval result: \out = 270369.
> eval -set in 270369 -show out
Eval result: \out = 67634689.
> sat -set out 632435482
Signal Name Dec Hex Bin
-------------------- ---------- ---------- -------------------------------------
\in 745495504 2c6f5bd0 00101100011011110101101111010000
\out 632435482 25b2331a 00100101101100100011001100011010

271
docs/source/yosys_internals/flow/command_ordering.rst Normal file
View file

@ -0,0 +1,271 @@
Command ordering
----------------
.. TODO: copypaste
Intro to coarse-grain synthesis
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In coarse-grain synthesis the target architecture has cells of the same
complexity or larger complexity than the internal RTL representation.
For example:
.. code:: verilog
wire [15:0] a, b;
wire [31:0] c, y;
assign y = a * b + c;
This circuit contains two cells in the RTL representation: one multiplier and
one adder. In some architectures this circuit can be implemented using
a single circuit element, for example an FPGA DSP core. Coarse grain synthesis
is this mapping of groups of circuit elements to larger components.
Fine-grain synthesis would be matching the circuit elements to smaller
components, such as LUTs, gates, or half- and full-adders.
The extract pass
~~~~~~~~~~~~~~~~
- Like the ``techmap`` pass, the ``extract`` pass is called with a map file. It
compares the circuits inside the modules of the map file with the design and
looks for sub-circuits in the design that match any of the modules in the map
file.
- If a match is found, the ``extract`` pass will replace the matching subcircuit
with an instance of the module from the map file.
- In a way the ``extract`` pass is the inverse of the techmap pass.
.. TODO: copypaste
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_00a.*
:class: width-helper
before `extract`
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_00b.*
:class: width-helper
after `extract`
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_test.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_xmap.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_xmap.v``
.. code:: yoscrypt
read_verilog macc_simple_test.v
hierarchy -check -top test
extract -map macc_simple_xmap.v;;
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_test_01.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_test_01.v``
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_01a.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_01b.*
:class: width-helper
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_test_02.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_test_02.v``
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_02a.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_02b.*
:class: width-helper
The wrap-extract-unwrap method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Often a coarse-grain element has a constant bit-width, but can be used to
implement operations with a smaller bit-width. For example, a 18x25-bit multiplier
can also be used to implement 16x20-bit multiplication.
A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method:
wrap
Identify candidate-cells in the circuit and wrap them in a cell with a constant
wider bit-width using ``techmap``. The wrappers use the same parameters as the original cell, so
the information about the original width of the ports is preserved.
Then use the ``connwrappers`` command to connect up the bit-extended in- and
outputs of the wrapper cells.
extract
Now all operations are encoded using the same bit-width as the coarse grain
element. The ``extract`` command can be used to replace circuits with cells
of the target architecture.
unwrap
The remaining wrapper cell can be unwrapped using ``techmap``.
Example: DSP48_MACC
~~~~~~~~~~~~~~~~~~~
This section details an example that shows how to map MACC operations of
arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder
(such as the Xilinx DSP48 cells).
Preconditioning: ``macc_xilinx_swap_map.v``
Make sure ``A`` is the smaller port on all multipliers
.. TODO: copypaste
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_swap_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_swap_map.v``
Wrapping multipliers: ``macc_xilinx_wrap_map.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v
:language: verilog
:lines: 1-46
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v``
Wrapping adders: ``macc_xilinx_wrap_map.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v
:language: verilog
:lines: 48-89
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v``
Extract: ``macc_xilinx_xmap.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v``
... simply use the same wrapping commands on this module as on the design to create a template for the ``extract`` command.
Unwrapping multipliers: ``macc_xilinx_unwrap_map.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v
:language: verilog
:lines: 1-30
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v``
Unwrapping adders: ``macc_xilinx_unwrap_map.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v
:language: verilog
:lines: 32-61
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_test.v
:language: verilog
:lines: 1-6
:caption: ``test1`` of ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_test.v``
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1a.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1b.*
:class: width-helper
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_test.v
:language: verilog
:lines: 8-13
:caption: ``test2`` of ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_test.v``
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2a.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2b.*
:class: width-helper
Wrapping in ``test1``:
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1b.*
:class: width-helper
.. code:: yoscrypt
techmap -map macc_xilinx_wrap_map.v
connwrappers -unsigned $__mul_wrapper \
Y Y_WIDTH \
-unsigned $__add_wrapper \
Y Y_WIDTH ;;
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1c.*
:class: width-helper
Wrapping in ``test2``:
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2b.*
:class: width-helper
.. code:: yoscrypt
techmap -map macc_xilinx_wrap_map.v
connwrappers -unsigned $__mul_wrapper \
Y Y_WIDTH \
-unsigned $__add_wrapper \
Y Y_WIDTH ;;
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2c.*
:class: width-helper
Extract in ``test1``:
.. code:: yoscrypt
design -push
read_verilog macc_xilinx_xmap.v
techmap -map macc_xilinx_swap_map.v
techmap -map macc_xilinx_wrap_map.v;;
design -save __macc_xilinx_xmap
design -pop
extract -constports -ignore_parameters \
-map %__macc_xilinx_xmap \
-swap $__add_wrapper A,B ;;
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1c.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1d.*
:class: width-helper
Extract in ``test2``:
.. code:: yoscrypt
design -push
read_verilog macc_xilinx_xmap.v
techmap -map macc_xilinx_swap_map.v
techmap -map macc_xilinx_wrap_map.v;;
design -save __macc_xilinx_xmap
design -pop
extract -constports -ignore_parameters \
-map %__macc_xilinx_xmap \
-swap $__add_wrapper A,B ;;
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2c.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2d.*
:class: width-helper
Unwrap in ``test2``:
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2d.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2e.*
:class: width-helper
.. code:: yoscrypt
techmap -map macc_xilinx_unwrap_map.v ;;

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

@ -17,4 +17,6 @@ This scripts contain three types of commands:
overview
control_and_data
verilog_frontend
command_ordering
model_checking

106
docs/source/yosys_internals/flow/model_checking.rst Normal file
View file

@ -0,0 +1,106 @@
Symbolic model checking
-----------------------
.. TODO: copypaste
.. note::
While it is possible to perform model checking directly in Yosys, it
is highly recommended to use SBY or EQY for formal hardware verification.
Symbolic Model Checking (SMC) is used to formally prove that a circuit has (or
has not) a given property.
One application is Formal Equivalence Checking: Proving that two circuits are
identical. For example this is a very useful feature when debugging custom
passes in Yosys.
Other applications include checking if a module conforms to interface standards.
The ``sat`` command in Yosys can be used to perform Symbolic Model Checking.
Checking techmap
~~~~~~~~~~~~~~~~
Remember the following example from :doc:`/getting_started/typical_phases`?
.. literalinclude:: ../../../resources/PRESENTATION_ExSyn/techmap_01_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExSyn/techmap_01_map.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExSyn/techmap_01.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExSyn/techmap_01.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExSyn/techmap_01.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExSyn/techmap_01.ys``
Lets see if it is correct..
.. code:: yoscrypt
# read test design
read_verilog techmap_01.v
hierarchy -top test
# create two version of the design: test_orig and test_mapped
copy test test_orig
rename test test_mapped
# apply the techmap only to test_mapped
techmap -map techmap_01_map.v test_mapped
# create a miter circuit to test equivalence
miter -equiv -make_assert -make_outputs test_orig test_mapped miter
flatten miter
# run equivalence check
sat -verify -prove-asserts -show-inputs -show-outputs miter
Result:
.. code::
Solving problem with 945 variables and 2505 clauses..
SAT proof finished - no model found: SUCCESS!
AXI4 Stream Master
~~~~~~~~~~~~~~~~~~
The following AXI4 Stream Master has a bug. But the bug is not exposed if the
slave keeps ``tready`` asserted all the time. (Something a test bench might do.)
Symbolic Model Checking can be used to expose the bug and find a sequence of
values for ``tready`` that yield the incorrect behavior.
.. literalinclude:: ../../../resources/PRESENTATION_ExOth/axis_master.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExOth/axis_master.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExOth/axis_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExOth/axis_test.v``
.. code:: yoscrypt
read_verilog -sv axis_master.v axis_test.v
hierarchy -top axis_test
proc; flatten;;
sat -seq 50 -prove-asserts
Result with unmodified ``axis_master.v``:
.. code::
Solving problem with 159344 variables and 442126 clauses..
SAT proof finished - model found: FAIL!
Result with fixed ``axis_master.v``:
.. code::
Solving problem with 159144 variables and 441626 clauses..
SAT proof finished - no model found: SUCCESS!

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

@ -31,7 +31,7 @@ provided implementation.
When no map file is provided, techmap uses a built-in map file that maps the
Yosys RTL cell types to the internal gate library used by Yosys. The curious
reader may find this map file as techlibs/common/techmap.v in the Yosys source
reader may find this map file as `techlibs/common/techmap.v` in the Yosys source
tree.
Additional features have been added to techmap to allow for conditional mapping
@ -105,3 +105,186 @@ reporting bugs in the tools involved. When the information in the Liberty file
used by Yosys and ABC are not part of the sensitive information, the additional
tool yosys-filterlib (see :ref:`sec:filterlib`) can be used to strip the
sensitive information from the Liberty file.
Techmap by example
------------------
.. TODO: copypaste
As a quick recap, the ``techmap`` command replaces cells in the design with
implementations given as Verilog code (called "map files"). It can replace
Yosys' internal cell types (such as ``$or``) as well as user-defined cell
types.
- Verilog parameters are used extensively to customize the internal cell types.
- Additional special parameters are used by techmap to communicate meta-data to
the map files.
- Special wires are used to instruct techmap how to handle a module in the map
file.
- Generate blocks and recursion are powerful tools for writing map files.
Mapping OR3X1
~~~~~~~~~~~~~
.. note::
This is a simple example for demonstration only. Techmap shouldn't be used
to implement basic logic optimization.
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/red_or3x1_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/red_or3x1_map.v``
.. figure:: ../../images/res/PRESENTATION_ExAdv/red_or3x1.*
:class: width-helper
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/red_or3x1_test.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/red_or3x1_test.ys``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/red_or3x1_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/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.
- Example use-cases:
- coarse-grain cell types that only operate on certain bit widths
- memory resources for different memory geometries (width, depth, ports, etc.)
Example:
.. figure:: ../../images/res/PRESENTATION_ExAdv/sym_mul.*
:class: width-helper
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/sym_mul_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/sym_mul_map.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/sym_mul_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/sym_mul_test.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/sym_mul_test.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/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 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.
- You can even call techmap recursively!
- Example use-cases:
- Using always blocks in map module: call ``proc``
- Perform expensive optimizations (such as ``freduce``) on cells where
this is known to work well.
- Interacting with custom commands.
.. note:: PROTIP:
Commands such as ``shell``, ``show -pause``, and ``dump`` can be use
in the ``_TECHMAP_DO_*`` scripts for debugging map modules.
Example:
.. figure:: ../../images/res/PRESENTATION_ExAdv/mymul.*
:class: width-helper
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mymul_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/mymul_map.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mymul_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/mymul_test.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mymul_test.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/mymul_test.ys``
Handling constant inputs
~~~~~~~~~~~~~~~~~~~~~~~~
- The special parameters ``_TECHMAP_CONSTMSK_<port-name>_`` and
``_TECHMAP_CONSTVAL_<port-name>_`` can be used to handle constant input values
to cells.
- The former contains 1-bits for all constant input bits on the port.
- The latter contains the constant bits or undef (x) for non-constant bits.
- Example use-cases:
- Converting arithmetic (for example multiply to shift).
- Identify constant addresses or enable bits in memory interfaces.
Example:
.. figure:: ../../images/res/PRESENTATION_ExAdv/mulshift.*
:class: width-helper
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mulshift_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/mulshift_map.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mulshift_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/mulshift_test.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mulshift_test.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/mulshift_test.ys``
Handling shorted inputs
~~~~~~~~~~~~~~~~~~~~~~~
- The special parameters ``_TECHMAP_BITS_CONNMAP_`` and
``_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.
- The numbers 0-3 are reserved for ``0``, ``1``, ``x``, and ``z`` respectively.
- Example use-cases:
- Detecting shared clock or control signals in memory interfaces.
- In some cases this can be used for for optimization.
Example:
.. figure:: ../../images/res/PRESENTATION_ExAdv/addshift.*
:class: width-helper
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/addshift_map.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/addshift_map.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/addshift_test.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/addshift_test.v``
.. literalinclude:: ../../resources/PRESENTATION_ExAdv/addshift_test.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/addshift_test.ys``
Notes on using techmap
~~~~~~~~~~~~~~~~~~~~~~
- Don't use positional cell parameters in map modules.
- You can use the ``$__``-prefix for internal cell types to avoid
collisions with the user-namespace. But always use two underscores or the
internal consistency checker will trigger on this cells.
- Techmap has two major use cases:
- Creating good logic-level representation of arithmetic functions. This
also means using dedicated hardware resources such as half- and full-adder
cells in ASICS or dedicated carry logic in FPGAs.
- Mapping of coarse-grain resources such as block memory or DSP cells.