-
Notifications
You must be signed in to change notification settings - Fork 855
/
techmap.rst
191 lines (140 loc) · 6.29 KB
/
techmap.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
Techmap by example
------------------
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.
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/main/docs/source/code_examples/techmap
Mapping OR3X1
~~~~~~~~~~~~~
.. todo:: add/expand supporting text
.. note::
This is a simple example for demonstration only. Techmap shouldn't be used
to implement basic logic optimization.
.. literalinclude:: /code_examples/techmap/red_or3x1_map.v
:language: verilog
: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: :file:`red_or3x1_test.ys`
.. literalinclude:: /code_examples/techmap/red_or3x1_test.v
:language: verilog
: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.
- 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/code_examples/techmap/sym_mul.*
:class: width-helper
.. literalinclude:: /code_examples/techmap/sym_mul_map.v
:language: verilog
:caption: :file:`sym_mul_map.v`
.. literalinclude:: /code_examples/techmap/sym_mul_test.v
:language: verilog
:caption: :file:`sym_mul_test.v`
.. literalinclude:: /code_examples/techmap/sym_mul_test.ys
:language: yoscrypt
: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 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 used in the
``_TECHMAP_DO_*`` scripts for debugging map modules.
Example:
.. figure:: /_images/code_examples/techmap/mymul.*
:class: width-helper
.. literalinclude:: /code_examples/techmap/mymul_map.v
:language: verilog
:caption: :file:`mymul_map.v`
.. literalinclude:: /code_examples/techmap/mymul_test.v
:language: verilog
:caption: :file:`mymul_test.v`
.. literalinclude:: /code_examples/techmap/mymul_test.ys
:language: yoscrypt
:caption: :file:`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/code_examples/techmap/mulshift.*
:class: width-helper
.. literalinclude:: /code_examples/techmap/mulshift_map.v
:language: verilog
:caption: :file:`mulshift_map.v`
.. literalinclude:: /code_examples/techmap/mulshift_test.v
:language: verilog
:caption: :file:`mulshift_test.v`
.. literalinclude:: /code_examples/techmap/mulshift_test.ys
:language: yoscrypt
:caption: :file:`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/code_examples/techmap/addshift.*
:class: width-helper
.. literalinclude:: /code_examples/techmap/addshift_map.v
:language: verilog
:caption: :file:`addshift_map.v`
.. literalinclude:: /code_examples/techmap/addshift_test.v
:language: verilog
:caption: :file:`addshift_test.v`
.. literalinclude:: /code_examples/techmap/addshift_test.ys
:language: yoscrypt
:caption: :file:`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 these 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.