mirror of
https://github.com/YosysHQ/yosys
synced 2025-06-06 14:13:23 +00:00
Docs: Shorten cmd:ref
This commit is contained in:
Krystine Sherwin
parent
e4ec3717bc
commit
829e02ec5b
22 changed files with 296 additions and 297 deletions
|
|
@ -2,9 +2,9 @@ Synthesis starter
|
|||
-----------------
|
||||
|
||||
This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis
|
||||
script - :cmd:ref:`synth_ice40`. We will take a simple design through each
|
||||
script - `synth_ice40`. We will take a simple design through each
|
||||
step, looking at the commands being called and what they do to the design. While
|
||||
:cmd:ref:`synth_ice40` is specific to the iCE40 platform, most of the operations
|
||||
`synth_ice40` is specific to the iCE40 platform, most of the operations
|
||||
we will be discussing are common across the majority of FPGA synthesis scripts.
|
||||
Thus, this document will provide a good foundational understanding of how
|
||||
synthesis in Yosys is performed, regardless of the actual architecture being
|
||||
|
|
@ -59,8 +59,8 @@ can run each of the commands individually for a better sense of how each part
|
|||
contributes to the flow. We will also start with just a single module;
|
||||
``addr_gen``.
|
||||
|
||||
At the bottom of the :cmd:ref:`help` output for
|
||||
:cmd:ref:`synth_ice40` is the complete list of commands called by this script.
|
||||
At the bottom of the `help` output for
|
||||
`synth_ice40` is the complete list of commands called by this script.
|
||||
Let's start with the section labeled ``begin``:
|
||||
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
|
|
@ -105,8 +105,8 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy
|
|||
|
||||
.. note::
|
||||
|
||||
:cmd:ref:`hierarchy` should always be the first command after the design has
|
||||
been read. By specifying the top module, :cmd:ref:`hierarchy` will also set
|
||||
`hierarchy` should always be the first command after the design has
|
||||
been read. By specifying the top module, `hierarchy` will also set
|
||||
the ``(* top *)`` attribute on it. This is used by other commands that need
|
||||
to know which module is the top.
|
||||
|
||||
|
|
@ -125,7 +125,7 @@ Our ``addr_gen`` circuit now looks like this:
|
|||
:class: width-helper invert-helper
|
||||
:name: addr_gen_hier
|
||||
|
||||
``addr_gen`` module after :cmd:ref:`hierarchy`
|
||||
``addr_gen`` module after `hierarchy`
|
||||
|
||||
Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted
|
||||
from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted
|
||||
|
|
@ -137,9 +137,9 @@ second line refers to the line numbers of the start/end of the corresponding
|
|||
``PROC`` referring to line 0.
|
||||
|
||||
To handle these, let us now introduce the next command: :doc:`/cmd/proc`.
|
||||
:cmd:ref:`proc` is a macro command like :cmd:ref:`synth_ice40`. Rather than
|
||||
`proc` is a macro command like `synth_ice40`. Rather than
|
||||
modifying the design directly, it instead calls a series of other commands. In
|
||||
the case of :cmd:ref:`proc`, these sub-commands work to convert the behavioral
|
||||
the case of `proc`, these sub-commands work to convert the behavioral
|
||||
logic of processes into multiplexers and registers. Let's see what happens when
|
||||
we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some
|
||||
automatic optimizations which would normally happen.
|
||||
|
|
@ -160,8 +160,8 @@ Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire,
|
|||
generated from the initial assignment of 0 to the ``addr`` wire. However, this
|
||||
initial assignment is not synthesizable, so this will need to be cleaned up
|
||||
before we can generate the physical hardware. We can do this now by calling
|
||||
:cmd:ref:`clean`. We're also going to call :cmd:ref:`opt_expr` now, which would
|
||||
normally be called at the end of :cmd:ref:`proc`. We can call both commands at
|
||||
`clean`. We're also going to call `opt_expr` now, which would
|
||||
normally be called at the end of `proc`. We can call both commands at
|
||||
the same time by separating them with a colon and space: :yoscrypt:`opt_expr;
|
||||
clean`.
|
||||
|
||||
|
|
@ -175,7 +175,7 @@ You may also notice that the highlighted `$eq` cell input of ``255`` has
|
|||
changed to ``8'11111111``. Constant values are presented in the format
|
||||
``<bit_width>'<bits>``, with 32-bit values instead using the decimal number.
|
||||
This indicates that the constant input has been reduced from 32-bit wide to
|
||||
8-bit wide. This is a side-effect of running :cmd:ref:`opt_expr`, which
|
||||
8-bit wide. This is a side-effect of running `opt_expr`, which
|
||||
performs constant folding and simple expression rewriting. For more on why
|
||||
this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section
|
||||
on opt_expr <adv_opt_expr>`.
|
||||
|
|
@ -185,7 +185,7 @@ on opt_expr <adv_opt_expr>`.
|
|||
:doc:`/cmd/clean` can also be called with two semicolons after any command,
|
||||
for example we could have called :yoscrypt:`opt_expr;;` instead of
|
||||
:yoscrypt:`opt_expr; clean`. You may notice some scripts will end each line
|
||||
with ``;;``. It is beneficial to run :cmd:ref:`clean` before inspecting
|
||||
with ``;;``. It is beneficial to run `clean` before inspecting
|
||||
intermediate products to remove disconnected parts of the circuit which have
|
||||
been left over, and in some cases can reduce the processing required in
|
||||
subsequent commands.
|
||||
|
|
@ -202,7 +202,7 @@ The full example
|
|||
|
||||
Let's now go back and check on our full design by using :yoscrypt:`hierarchy
|
||||
-check -top fifo`. By passing the ``-check`` option there we are also telling
|
||||
the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox
|
||||
the `hierarchy` command that if the design includes any non-blackbox
|
||||
modules without an implementation it should return an error.
|
||||
|
||||
Note that if we tried to run this command now then we would get an error. This
|
||||
|
|
@ -221,15 +221,15 @@ could restart our shell session, but instead let's use two new commands:
|
|||
Notice how this time we didn't see any of those ``$abstract`` modules? That's
|
||||
because when we ran ``yosys fifo.v``, the first command Yosys called was
|
||||
:yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells
|
||||
:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual
|
||||
compilation to a later :cmd:ref:`hierarchy` command. This is useful in cases
|
||||
`read_verilog` only read the abstract syntax tree and defer actual
|
||||
compilation to a later `hierarchy` command. This is useful in cases
|
||||
where the default parameters of modules yield invalid code which is not
|
||||
synthesizable. This is why Yosys defers compilation automatically and is one of
|
||||
the reasons why hierarchy should always be the first command after loading the
|
||||
design. If we know that our design won't run into this issue, we can skip the
|
||||
``-defer``.
|
||||
|
||||
.. todo:: :cmd:ref:`hierarchy` failure modes
|
||||
.. todo:: `hierarchy` failure modes
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -243,19 +243,19 @@ design. If we know that our design won't run into this issue, we can skip the
|
|||
interactive terminal. :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal
|
||||
session but will return an error code rather than exiting gracefully.
|
||||
|
||||
We can also run :cmd:ref:`proc` now to finish off the full :ref:`synth_begin`.
|
||||
We can also run `proc` now to finish off the full :ref:`synth_begin`.
|
||||
Because the design schematic is quite large, we will be showing just the data
|
||||
path for the ``rdata`` output. If you would like to see the entire design for
|
||||
yourself, you can do so with :doc:`/cmd/show`. Note that the :cmd:ref:`show`
|
||||
yourself, you can do so with :doc:`/cmd/show`. Note that the `show`
|
||||
command only works with a single module, so you may need to call it with
|
||||
:yoscrypt:`show fifo`. :ref:`show_intro` section in
|
||||
:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`.
|
||||
:doc:`/getting_started/scripting_intro` has more on how to use `show`.
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/rdata_proc.*
|
||||
:class: width-helper invert-helper
|
||||
:name: rdata_proc
|
||||
|
||||
``rdata`` output after :cmd:ref:`proc`
|
||||
``rdata`` output after `proc`
|
||||
|
||||
The highlighted ``fifo_reader`` block contains an instance of the
|
||||
:ref:`addr_gen_proc` that we looked at earlier. Notice how the type is shown as
|
||||
|
|
@ -276,7 +276,7 @@ Flattening
|
|||
~~~~~~~~~~
|
||||
|
||||
At this stage of a synthesis flow there are a few other commands we could run.
|
||||
In :cmd:ref:`synth_ice40` we get these:
|
||||
In `synth_ice40` we get these:
|
||||
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
:language: yoscrypt
|
||||
|
|
@ -286,7 +286,7 @@ In :cmd:ref:`synth_ice40` we get these:
|
|||
:name: synth_flatten
|
||||
:caption: ``flatten`` section
|
||||
|
||||
First off is :cmd:ref:`flatten`. Flattening the design like this can allow for
|
||||
First off is `flatten`. Flattening the design like this can allow for
|
||||
optimizations between modules which would otherwise be missed. Let's run
|
||||
:yoscrypt:`flatten;;` on our design.
|
||||
|
||||
|
|
@ -310,19 +310,19 @@ The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from
|
|||
earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can
|
||||
also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr`
|
||||
and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire
|
||||
merging happened during the call to :cmd:ref:`clean` which we can see in the
|
||||
merging happened during the call to `clean` which we can see in the
|
||||
:ref:`flat_clean`.
|
||||
|
||||
.. note::
|
||||
|
||||
:cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a
|
||||
`flatten` and `clean` would normally be combined into a
|
||||
single :yoterm:`yosys> flatten;;` output, but they appear separately here as
|
||||
a side effect of using :cmd:ref:`echo` for generating the terminal style
|
||||
a side effect of using `echo` for generating the terminal style
|
||||
output.
|
||||
|
||||
Depending on the target architecture, this stage of synthesis might also see
|
||||
commands such as :cmd:ref:`tribuf` with the ``-logic`` option and
|
||||
:cmd:ref:`deminout`. These remove tristate and inout constructs respectively,
|
||||
commands such as `tribuf` with the ``-logic`` option and
|
||||
`deminout`. These remove tristate and inout constructs respectively,
|
||||
replacing them with logic suitable for mapping to an FPGA. Since we do not have
|
||||
any such constructs in our example running these commands does not change our
|
||||
design.
|
||||
|
|
@ -342,7 +342,7 @@ optimizations and other transformations done previously.
|
|||
|
||||
.. note::
|
||||
|
||||
While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in
|
||||
While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in
|
||||
the :ref:`synth_begin`, some synthesis scripts will instead include these in
|
||||
this section.
|
||||
|
||||
|
|
@ -359,8 +359,8 @@ In the iCE40 flow, we start with the following commands:
|
|||
:caption: ``coarse`` section (part 1)
|
||||
:name: synth_coarse1
|
||||
|
||||
We've already come across :cmd:ref:`opt_expr`, and :cmd:ref:`opt_clean` is the
|
||||
same as :cmd:ref:`clean` but with more verbose output. The :cmd:ref:`check`
|
||||
We've already come across `opt_expr`, and `opt_clean` is the
|
||||
same as `clean` but with more verbose output. The `check`
|
||||
pass identifies a few obvious problems which will cause errors later. Calling
|
||||
it here lets us fail faster rather than wasting time on something we know is
|
||||
impossible.
|
||||
|
|
@ -368,13 +368,13 @@ impossible.
|
|||
Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple
|
||||
optimizations on the design. This command also ensures that only a specific
|
||||
subset of FF types are included, in preparation for the next command:
|
||||
:doc:`/cmd/fsm`. Both :cmd:ref:`opt` and :cmd:ref:`fsm` are macro commands
|
||||
:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands
|
||||
which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and
|
||||
:doc:`/using_yosys/synthesis/fsm` respectively.
|
||||
|
||||
Up until now, the data path for ``rdata`` has remained the same since
|
||||
:ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change.
|
||||
Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff``
|
||||
:ref:`rdata_flat`. However the next call to `opt` does cause a change.
|
||||
Specifically, the call to `opt_dff` without the ``-nodffe -nosdff``
|
||||
options is able to fold one of the `$mux` cells into the `$adff` to form an
|
||||
`$adffe` cell; highlighted below:
|
||||
|
||||
|
|
@ -382,13 +382,13 @@ options is able to fold one of the `$mux` cells into the `$adff` to form an
|
|||
:language: doscon
|
||||
:start-at: yosys> opt_dff
|
||||
:end-before: yosys> select
|
||||
:caption: output of :cmd:ref:`opt_dff`
|
||||
:caption: output of `opt_dff`
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/rdata_adffe.*
|
||||
:class: width-helper invert-helper
|
||||
:name: rdata_adffe
|
||||
|
||||
``rdata`` output after :cmd:ref:`opt_dff`
|
||||
``rdata`` output after `opt_dff`
|
||||
|
||||
.. seealso:: Advanced usage docs for
|
||||
|
||||
|
|
@ -414,26 +414,26 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following:
|
|||
:language: doscon
|
||||
:start-at: yosys> wreduce
|
||||
:end-before: yosys> select
|
||||
:caption: output of :cmd:ref:`wreduce`
|
||||
:caption: output of `wreduce`
|
||||
|
||||
Looking at the data path for ``rdata``, the most relevant of these width
|
||||
reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``.
|
||||
That is the `$add` cell incrementing the fifo_reader address. We can look at
|
||||
the schematic and see the output of that cell has now changed.
|
||||
|
||||
.. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean`
|
||||
.. todo:: pending bugfix in `wreduce` and/or `opt_clean`
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/rdata_wreduce.*
|
||||
:class: width-helper invert-helper
|
||||
:name: rdata_wreduce
|
||||
|
||||
``rdata`` output after :cmd:ref:`wreduce`
|
||||
``rdata`` output after `wreduce`
|
||||
|
||||
The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`.
|
||||
Neither of these affect our design, and they're explored in more detail in
|
||||
:doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap
|
||||
-map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by
|
||||
converting them to LUTs instead. The usage of :cmd:ref:`techmap` is explored
|
||||
converting them to LUTs instead. The usage of `techmap` is explored
|
||||
more in :doc:`/using_yosys/synthesis/techmap_synth`.
|
||||
|
||||
Our next command to run is
|
||||
|
|
@ -443,15 +443,15 @@ Our next command to run is
|
|||
:language: doscon
|
||||
:start-at: yosys> memory_dff
|
||||
:end-before: yosys> select
|
||||
:caption: output of :cmd:ref:`memory_dff`
|
||||
:caption: output of `memory_dff`
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/rdata_memrdv2.*
|
||||
:class: width-helper invert-helper
|
||||
:name: rdata_memrdv2
|
||||
|
||||
``rdata`` output after :cmd:ref:`memory_dff`
|
||||
``rdata`` output after `memory_dff`
|
||||
|
||||
As the title suggests, :cmd:ref:`memory_dff` has merged the output `$dff` into
|
||||
As the title suggests, `memory_dff` has merged the output `$dff` into
|
||||
the `$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has
|
||||
also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous
|
||||
memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
|
||||
|
|
@ -466,7 +466,7 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
|
|||
Part 3
|
||||
^^^^^^
|
||||
|
||||
The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for
|
||||
The third part of the `synth_ice40` flow is a series of commands for
|
||||
mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP
|
||||
blocks and will only be performed if called with the ``-dsp`` flag:
|
||||
:yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be
|
||||
|
|
@ -483,24 +483,24 @@ what they do.
|
|||
|
||||
:yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting
|
||||
only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map
|
||||
+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map
|
||||
+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map
|
||||
`$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40
|
||||
``SB_MAC16``. Any multipliers which aren't compatible with conversion to
|
||||
``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype`
|
||||
``$__MUL16X16`` are relabelled to ``$__soft_mul`` before `chtype`
|
||||
changes them back to `$mul`.
|
||||
|
||||
During the mul2dsp conversion, some of the intermediate signals are marked with
|
||||
the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict
|
||||
the following commands to only operate on the cells and wires used for these
|
||||
signals. :cmd:ref:`setattr` removes the now unnecessary ``mul2dsp`` attribute.
|
||||
:cmd:ref:`opt_expr` we've already come across for const folding and simple
|
||||
signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute.
|
||||
`opt_expr` we've already come across for const folding and simple
|
||||
expression rewriting, the ``-fine`` option just enables more fine-grain
|
||||
optimizations. Then we perform width reduction a final time and clear the
|
||||
selection.
|
||||
|
||||
.. todo:: ``ice40_dsp`` is pmgen
|
||||
|
||||
Finally we have :cmd:ref:`ice40_dsp`: similar to the :cmd:ref:`memory_dff`
|
||||
Finally we have `ice40_dsp`: similar to the `memory_dff`
|
||||
command we saw in the previous section, this merges any surrounding registers
|
||||
into the ``SB_MAC16`` cell. This includes not just the input/output registers,
|
||||
but also pipeline registers and even a post-adder where applicable: turning a
|
||||
|
|
@ -525,40 +525,40 @@ That brings us to the fourth and final part for the iCE40 synthesis flow:
|
|||
Where before each type of arithmetic operation had its own cell, e.g. `$add`,
|
||||
we now want to extract these into `$alu` and `$macc` cells which can help
|
||||
identify opportunities for reusing logic. We do this by running
|
||||
:cmd:ref:`alumacc`, which we can see produce the following changes in our
|
||||
`alumacc`, which we can see produce the following changes in our
|
||||
example design:
|
||||
|
||||
.. literalinclude:: /code_examples/fifo/fifo.out
|
||||
:language: doscon
|
||||
:start-at: yosys> alumacc
|
||||
:end-before: yosys> select
|
||||
:caption: output of :cmd:ref:`alumacc`
|
||||
:caption: output of `alumacc`
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/rdata_alumacc.*
|
||||
:class: width-helper invert-helper
|
||||
:name: rdata_alumacc
|
||||
|
||||
``rdata`` output after :cmd:ref:`alumacc`
|
||||
``rdata`` output after `alumacc`
|
||||
|
||||
Once these cells have been inserted, the call to :cmd:ref:`opt` can combine
|
||||
Once these cells have been inserted, the call to `opt` can combine
|
||||
cells which are now identical but may have been missed due to e.g. the
|
||||
difference between `$add` and `$sub`.
|
||||
|
||||
The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is
|
||||
The other new command in this part is :doc:`/cmd/memory`. `memory` is
|
||||
another macro command which we examine in more detail in
|
||||
:doc:`/using_yosys/synthesis/memory`. For this document, let us focus just on
|
||||
the step most relevant to our example: :cmd:ref:`memory_collect`. Up until this
|
||||
the step most relevant to our example: `memory_collect`. Up until this
|
||||
point, our memory reads and our memory writes have been totally disjoint cells;
|
||||
operating on the same memory only in the abstract. :cmd:ref:`memory_collect`
|
||||
operating on the same memory only in the abstract. `memory_collect`
|
||||
combines all of the reads and writes for a memory block into a single cell.
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/rdata_coarse.*
|
||||
:class: width-helper invert-helper
|
||||
:name: rdata_coarse
|
||||
|
||||
``rdata`` output after :cmd:ref:`memory_collect`
|
||||
``rdata`` output after `memory_collect`
|
||||
|
||||
Looking at the schematic after running :cmd:ref:`memory_collect` we see that our
|
||||
Looking at the schematic after running `memory_collect` we see that our
|
||||
`$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the
|
||||
same name that we used in :ref:`fifo-v`. Where before we had a single set of
|
||||
signals for address and enable, we now have one set for reading (``RD_*``) and
|
||||
|
|
@ -592,8 +592,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify
|
|||
Memory blocks
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and
|
||||
:cmd:ref:`techmap`.
|
||||
Mapping to hard memory blocks uses a combination of `memory_libmap` and
|
||||
`techmap`.
|
||||
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
:language: yoscrypt
|
||||
|
|
@ -619,7 +619,7 @@ As a result, extra logic is added so that the generated circuit matches the
|
|||
behaviour of the verilog. :ref:`no_rw_check` describes how we could change our
|
||||
verilog to match our hardware instead.
|
||||
|
||||
If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see
|
||||
If we run `memory_libmap` under the `debug` command we can see
|
||||
candidates which were identified for mapping, along with the costs of each and
|
||||
what logic requires emulation.
|
||||
|
||||
|
|
@ -628,9 +628,9 @@ what logic requires emulation.
|
|||
:lines: 2, 6-
|
||||
|
||||
The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_,
|
||||
with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using
|
||||
with the mapping to ``SB_RAM40_4K`` done by `techmap` using
|
||||
|techlibs/ice40/brams_map.v|_. Any leftover memory cells are then converted
|
||||
into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
|
||||
into flip flops (the ``logic fallback``) with `memory_map`.
|
||||
|
||||
.. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt`
|
||||
.. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams.txt
|
||||
|
|
@ -654,7 +654,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
|
|||
.. note::
|
||||
|
||||
The visual clutter on the ``RDATA`` output port (highlighted) is an
|
||||
unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In
|
||||
unfortunate side effect of `opt_clean` on the swizzled data bits. In
|
||||
connecting the `$mux` input port directly to ``RDATA`` to reduce the number
|
||||
of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually
|
||||
complex.
|
||||
|
|
@ -667,7 +667,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
|
|||
Arithmetic
|
||||
^^^^^^^^^^
|
||||
|
||||
Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees
|
||||
Uses `techmap` to map basic arithmetic logic to hardware. This sees
|
||||
somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are
|
||||
replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the
|
||||
:cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a
|
||||
|
|
@ -693,11 +693,11 @@ replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the
|
|||
Flip-flops
|
||||
^^^^^^^^^^
|
||||
|
||||
Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and
|
||||
then use :cmd:ref:`techmap` to map them. In our example, this converts the
|
||||
Convert FFs to the types supported in hardware with `dfflegalize`, and
|
||||
then use `techmap` to map them. In our example, this converts the
|
||||
`$_DFFE_PP0P_` cells to ``SB_DFFER``.
|
||||
|
||||
We also run :cmd:ref:`simplemap` here to convert any remaining cells which could
|
||||
We also run `simplemap` here to convert any remaining cells which could
|
||||
not be mapped to hardware into gate-level primitives. This includes optimizing
|
||||
`$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it
|
||||
instead with an `$_AND_` cell.
|
||||
|
|
@ -722,9 +722,9 @@ instead with an `$_AND_` cell.
|
|||
LUTs
|
||||
^^^^
|
||||
|
||||
:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive
|
||||
`abc` and `techmap` are used to map LUTs; converting primitive
|
||||
cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow
|
||||
uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and
|
||||
uses `abc9` rather than `abc`. For more on what these do, and
|
||||
what the difference between these two commands are, refer to
|
||||
:doc:`/using_yosys/synthesis/abc`.
|
||||
|
||||
|
|
@ -742,7 +742,7 @@ what the difference between these two commands are, refer to
|
|||
|
||||
``rdata`` output after :ref:`map_luts`
|
||||
|
||||
Finally we use :cmd:ref:`techmap` to map the generic `$lut` cells to iCE40
|
||||
Finally we use `techmap` to map the generic `$lut` cells to iCE40
|
||||
``SB_LUT4`` cells.
|
||||
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
|
|
@ -769,12 +769,12 @@ Other cells
|
|||
|
||||
The following commands may also be used for mapping other cells:
|
||||
|
||||
:cmd:ref:`hilomap`
|
||||
`hilomap`
|
||||
Some architectures require special driver cells for driving a constant hi or
|
||||
lo value. This command replaces simple constants with instances of such
|
||||
driver cells.
|
||||
|
||||
:cmd:ref:`iopadmap`
|
||||
`iopadmap`
|
||||
Top-level input/outputs must usually be implemented using special I/O-pad
|
||||
cells. This command inserts such cells to the design.
|
||||
|
||||
|
|
@ -801,27 +801,27 @@ The new commands here are:
|
|||
- :doc:`/cmd/stat`, and
|
||||
- :doc:`/cmd/blackbox`.
|
||||
|
||||
The output from :cmd:ref:`stat` is useful for checking resource utilization;
|
||||
The output from `stat` is useful for checking resource utilization;
|
||||
providing a list of cells used in the design and the number of each, as well as
|
||||
the number of other resources used such as wires and processes. For this
|
||||
design, the final call to :cmd:ref:`stat` should look something like the
|
||||
design, the final call to `stat` should look something like the
|
||||
following:
|
||||
|
||||
.. literalinclude:: /code_examples/fifo/fifo.stat
|
||||
:language: doscon
|
||||
:start-at: yosys> stat -top fifo
|
||||
|
||||
Note that the :yoscrypt:`-top fifo` here is optional. :cmd:ref:`stat` will
|
||||
Note that the :yoscrypt:`-top fifo` here is optional. `stat` will
|
||||
automatically use the module with the ``top`` attribute set, which ``fifo`` was
|
||||
when we called :cmd:ref:`hierarchy`. If no module is marked ``top``, then stats
|
||||
when we called `hierarchy`. If no module is marked ``top``, then stats
|
||||
will be shown for each module selected.
|
||||
|
||||
The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we
|
||||
have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes.
|
||||
The `stat` output is also useful as a kind of sanity-check: Since we
|
||||
have already run `proc`, we wouldn't expect there to be any processes.
|
||||
We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw
|
||||
a high number of flip-flops being used we might suspect something was wrong.
|
||||
|
||||
If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog
|
||||
If we instead called `stat` immediately after :yoscrypt:`read_verilog
|
||||
fifo.v` we would see something very different:
|
||||
|
||||
.. literalinclude:: /code_examples/fifo/fifo.stat
|
||||
|
|
@ -845,7 +845,7 @@ The iCE40 synthesis flow has the following output modes available:
|
|||
|
||||
As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
|
||||
our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can
|
||||
then read the design back into Yosys with :cmd:ref:`read_json`, but make sure
|
||||
then read the design back into Yosys with `read_json`, but make sure
|
||||
you use :yoscrypt:`design -reset` or open a new interactive terminal first. The
|
||||
JSON output we get can also be loaded into `nextpnr`_ to do place and route; but
|
||||
that is beyond the scope of this documentation.
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ A C++ compiler with C++17 support is required as well as some standard tools
|
|||
such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline,
|
||||
libffi, Tcl and zlib; are optional but enabled by default (see
|
||||
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
|
||||
:cmd:ref:`show` command to display schematics.
|
||||
`show` command to display schematics.
|
||||
|
||||
Installing all prerequisites for Ubuntu 20.04:
|
||||
|
||||
|
|
@ -185,8 +185,8 @@ directories:
|
|||
``passes/``
|
||||
This directory contains a subdirectory for each pass or group of passes. For
|
||||
example as of this writing the directory :file:`passes/hierarchy/` contains the
|
||||
code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and
|
||||
:cmd:ref:`uniquify`.
|
||||
code for three passes: `hierarchy`, `submod`, and
|
||||
`uniquify`.
|
||||
|
||||
``techlibs/``
|
||||
This directory contains simulation models and standard implementations for
|
||||
|
|
|
|||
|
|
@ -7,8 +7,7 @@ file format and how you can make your own synthesis scripts.
|
|||
|
||||
Yosys script files typically use the :file:`.ys` extension and contain a set of
|
||||
commands for Yosys to run sequentially. These commands are the same ones we
|
||||
were using on the previous page like :cmd:ref:`read_verilog` and
|
||||
:cmd:ref:`hierarchy`.
|
||||
were using on the previous page like `read_verilog` and `hierarchy`.
|
||||
|
||||
Script parsing
|
||||
~~~~~~~~~~~~~~
|
||||
|
|
@ -39,9 +38,9 @@ Another special character that can be used in Yosys scripts is the bang ``!``.
|
|||
Anything after the bang will be executed as a shell command. This can only be
|
||||
terminated with a new line. Any semicolons, hashes, or other special characters
|
||||
will be passed to the shell. If an error code is returned from the shell it
|
||||
will be raised by Yosys. :cmd:ref:`exec` provides a much more flexible way of
|
||||
executing commands, allowing the output to be logged and more control over when
|
||||
to generate errors.
|
||||
will be raised by Yosys. `exec` provides a much more flexible way of executing
|
||||
commands, allowing the output to be logged and more control over when to
|
||||
generate errors.
|
||||
|
||||
The synthesis starter script
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -62,7 +61,7 @@ already, let's take a look at some of those script files now.
|
|||
:caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example`
|
||||
:name: fifo-ys
|
||||
|
||||
The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable
|
||||
The first command there, :yoscrypt:`echo on`, uses `echo` to enable
|
||||
command echoes on. This is how we generated the code listing for
|
||||
:ref:`hierarchy_output`. Turning command echoes on prints the ``yosys>
|
||||
hierarchy -top addr_gen`` line, making the output look the same as if it were an
|
||||
|
|
@ -70,15 +69,15 @@ interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the
|
|||
command we were demonstrating, including the output text and an image of the
|
||||
design schematic after running it.
|
||||
|
||||
We briefly touched on :cmd:ref:`select` when it came up in
|
||||
:cmd:ref:`synth_ice40`, but let's look at it more now.
|
||||
We briefly touched on `select` when it came up in
|
||||
`synth_ice40`, but let's look at it more now.
|
||||
|
||||
.. _select_intro:
|
||||
|
||||
Selections intro
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The :cmd:ref:`select` command is used to modify and view the list of selected
|
||||
The `select` command is used to modify and view the list of selected
|
||||
objects:
|
||||
|
||||
.. literalinclude:: /code_examples/fifo/fifo.out
|
||||
|
|
@ -119,7 +118,7 @@ statement.
|
|||
|
||||
Many commands also support an optional ``[selection]`` argument which can be
|
||||
used to override the currently selected objects. We could, for example, call
|
||||
:yoscrypt:`clean addr_gen` to have :cmd:ref:`clean` operate on *just* the
|
||||
:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the
|
||||
``addr_gen`` module.
|
||||
|
||||
Detailed documentation of the select framework can be found under
|
||||
|
|
@ -131,9 +130,9 @@ Detailed documentation of the select framework can be found under
|
|||
Displaying schematics
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
While the :cmd:ref:`select` command is very useful, sometimes nothing beats
|
||||
being able to see a design for yourself. This is where :cmd:ref:`show` comes
|
||||
in. Note that this document is just an introduction to the :cmd:ref:`show`
|
||||
While the `select` command is very useful, sometimes nothing beats
|
||||
being able to see a design for yourself. This is where `show` comes
|
||||
in. Note that this document is just an introduction to the `show`
|
||||
command, only covering the basics. For more information, including a guide on
|
||||
what the different symbols represent, see :ref:`interactive_show` and the
|
||||
:doc:`/using_yosys/more_scripting/interactive_investigation` page.
|
||||
|
|
@ -142,11 +141,11 @@ what the different symbols represent, see :ref:`interactive_show` and the
|
|||
:class: width-helper invert-helper
|
||||
:name: addr_gen_show
|
||||
|
||||
Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy`
|
||||
Calling :yoscrypt:`show addr_gen` after `hierarchy`
|
||||
|
||||
.. note::
|
||||
|
||||
The :cmd:ref:`show` command requires a working installation of `GraphViz`_
|
||||
The `show` command requires a working installation of `GraphViz`_
|
||||
and `xdot`_ for displaying the actual circuit diagrams.
|
||||
|
||||
.. _GraphViz: http://www.graphviz.org/
|
||||
|
|
@ -161,7 +160,7 @@ we see the following:
|
|||
:start-at: -prefix addr_gen_show
|
||||
:end-before: yosys> show
|
||||
|
||||
Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output
|
||||
Calling `show` with :yoscrypt:`-format dot` tells it we want to output
|
||||
a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix
|
||||
addr_gen_show` option indicates we want the file to be called
|
||||
:file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we
|
||||
|
|
@ -186,7 +185,7 @@ That last parameter doesn't have to be a module name, it can be any valid
|
|||
selection string. Remember when we :ref:`assigned a name to a
|
||||
selection<select_new_cells>` and called it ``new_cells``? We saw in the
|
||||
:yoscrypt:`select -list` output that it contained two cells, an `$add` and an
|
||||
`$eq`. We can call :cmd:ref:`show` on that selection just as easily:
|
||||
`$eq`. We can call `show` on that selection just as easily:
|
||||
|
||||
.. figure:: /_images/code_examples/fifo/new_cells_show.*
|
||||
:class: width-helper invert-helper
|
||||
|
|
@ -208,10 +207,10 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the
|
|||
|
||||
Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle`
|
||||
|
||||
As described in the the :cmd:ref:`help` output for :cmd:ref:`show` (or by
|
||||
clicking on the :cmd:ref:`show` link), colors are specified as :yoscrypt:`-color
|
||||
As described in the the `help` output for `show` (or by
|
||||
clicking on the `show` link), colors are specified as :yoscrypt:`-color
|
||||
<color> <object>`. Color names for the ``<color>`` portion can be found on the
|
||||
`GraphViz color docs`_. Unlike the final :cmd:ref:`show` parameter which can
|
||||
`GraphViz color docs`_. Unlike the final `show` parameter which can
|
||||
have be any selection string, the ``<object>`` part must be a single selection
|
||||
expression or named selection. That means while we can use ``@new_cells``, we
|
||||
couldn't use ``t:$eq t:$add``. In general, if a command lists ``[selection]``
|
||||
|
|
@ -221,7 +220,7 @@ expression instead.
|
|||
|
||||
.. _GraphViz color docs: https://graphviz.org/doc/info/colors
|
||||
|
||||
For all of the options available to :cmd:ref:`show`, check the command reference
|
||||
For all of the options available to `show`, check the command reference
|
||||
at :doc:`/cmd/show`.
|
||||
|
||||
.. seealso:: :ref:`interactive_show` on the
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue