mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-04-27 02:45:52 +00:00
Code Activity

Docs: Fix warnings

Browse source 
Changes a bunch of :doc:`/cmd/*` to :cmd:ref:`*` with the intention of changing it later to something that replicates the previous effect of displaying the commands `short_help`.
This commit is contained in:
Krystine Sherwin 2025-03-21 10:26:11 +13:00
parent 11af1a275b
commit 49907914c4
No known key found for this signature in database
15 changed files with 90 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

61
docs/source/getting_started/example_synth.rst
View file

@ -70,7 +70,7 @@ 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
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: begin:
:end-before: flatten:
@ -143,7 +143,7 @@ line refers to the line numbers of the start/end of the corresponding ``always
@`` block. In the case of an ``initial`` block, we instead see the ``PROC``
referring to line 0.
To handle these, let us now introduce the next command: :doc:`/cmd/proc`. `proc`
To handle these, let us now introduce the next command: :cmd:ref:`proc`. `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 `proc`,
these sub-commands work to convert the behavioral logic of processes into
@ -188,7 +188,7 @@ opt_expr <adv_opt_expr>`.
.. note::
:doc:`/cmd/clean` can also be called with two semicolons after any command,
:cmd:ref:`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 `clean` before inspecting intermediate
@ -215,8 +215,8 @@ Note that if we tried to run this command now then we would get an error. This
is because we already removed all of the modules other than ``addr_gen``. We
could restart our shell session, but instead let's use two new commands:
- :doc:`/cmd/design`, and
- :doc:`/cmd/read_verilog`.
- :cmd:ref:`design`, and
- :cmd:ref:`read_verilog`.
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
@ -251,7 +251,7 @@ our design won't run into this issue, we can skip the ``-defer``.
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 `show` command only works
you can do so with :cmd:ref:`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 `show`.
@ -283,7 +283,7 @@ Flattening
At this stage of a synthesis flow there are a few other commands we could run.
In `synth_ice40` we get these:
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: flatten:
:end-before: coarse:
@ -355,7 +355,7 @@ Part 1
In the iCE40 flow, we start with the following commands:
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: coarse:
:end-before: wreduce
@ -371,7 +371,7 @@ wasting time on something we know is 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 `opt` and `fsm` are macro commands which are explored in
:cmd:ref:`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.
@ -403,7 +403,7 @@ Part 2
The next group of commands performs a series of optimizations:
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-at: wreduce
:end-before: t:$mul
@ -411,7 +411,7 @@ The next group of commands performs a series of optimizations:
:caption: ``coarse`` section (part 2)
:name: synth_coarse2
First up is :doc:`/cmd/wreduce`. If we run this we get the following:
First up is :cmd:ref:`wreduce`. If we run this we get the following:
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
@ -432,7 +432,7 @@ the schematic and see the output of that cell has now changed.
``rdata`` output after `wreduce`
The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`.
The next two (new) commands are :cmd:ref:`peepopt` and :cmd:ref:`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
@ -440,7 +440,7 @@ 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
:doc:`/cmd/memory_dff`.
:cmd:ref:`memory_dff`.
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
@ -475,7 +475,7 @@ will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40
-dsp`. While our example has nothing that could be mapped to DSPs we can still
take a quick look at the commands here and describe what they do.
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-at: t:$mul
:end-before: alumacc
@ -514,7 +514,7 @@ Part 4
That brings us to the fourth and final part for the iCE40 synthesis flow:
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-at: alumacc
:end-before: map_ram:
@ -543,7 +543,7 @@ 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`. `memory` is another
The other new command in this part is :cmd:ref:`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: `memory_collect`. Up until this point,
@ -594,7 +594,7 @@ Memory blocks
Mapping to hard memory blocks uses a combination of `memory_libmap` and
`techmap`.
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: map_ram:
:end-before: map_ffram:
@ -636,7 +636,7 @@ into flip flops (the ``logic fallback``) with `memory_map`.
.. |techlibs/ice40/brams_map.v| replace:: :file:`techlibs/ice40/brams_map.v`
.. _techlibs/ice40/brams_map.v: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams_map.v
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: map_ffram:
:end-before: map_gates:
@ -671,7 +671,7 @@ an explosion in cells as multi-bit `$mux` and `$adffe` are replaced with
single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the `$alu` is replaced with
primitive `$_OR_` and `$_NOT_` gates and a `$lut` cell.
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: map_gates:
:end-before: map_ffs:
@ -700,7 +700,7 @@ 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.
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: map_ffs:
:end-before: map_luts:
@ -725,7 +725,7 @@ LUTs
`abc`. For more on what these do, and what the difference between these two
commands are, refer to :doc:`/using_yosys/synthesis/abc`.
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: map_luts:
:end-before: map_cells:
@ -742,7 +742,7 @@ commands are, refer to :doc:`/using_yosys/synthesis/abc`.
Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4``
cells.
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: map_cells:
:end-before: check:
@ -784,19 +784,18 @@ Final steps
The next section of the iCE40 synth flow performs some sanity checking and final
tidy up:
.. literalinclude:: /cmd/synth_ice40.rst
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
:language: yoscrypt
:start-after: check:
:end-before: blif:
:dedent:
:name: check
:caption: ``check`` section
The new commands here are:
- :doc:`/cmd/autoname`,
- :doc:`/cmd/stat`, and
- :doc:`/cmd/blackbox`.
- :cmd:ref:`autoname`,
- :cmd:ref:`stat`, and
- :cmd:ref:`blackbox`.
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
@ -835,9 +834,9 @@ Synthesis output
The iCE40 synthesis flow has the following output modes available:
- :doc:`/cmd/write_blif`,
- :doc:`/cmd/write_edif`, and
- :doc:`/cmd/write_json`.
- `write_blif`,
- `write_edif`, and
- `write_json`.
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
@ -848,4 +847,4 @@ is beyond the scope of this documentation.
.. _nextpnr: https://github.com/YosysHQ/nextpnr
.. seealso:: :doc:`/cmd/synth_ice40`
.. seealso:: :cmd:ref:`synth_ice40`

4
docs/source/getting_started/scripting_intro.rst
View file

@ -122,7 +122,7 @@ module.
Detailed documentation of the select framework can be found under
:doc:`/using_yosys/more_scripting/selections` or in the command reference at
:doc:`/cmd/select`.
:cmd:ref:`select`.
.. _show_intro:
@ -219,7 +219,7 @@ those used in options, must be a single expression instead.
.. _GraphViz color docs: https://graphviz.org/doc/info/colors
For all of the options available to `show`, check the command reference at
:doc:`/cmd/show`.
:cmd:ref:`show`.
.. seealso:: :ref:`interactive_show` on the
:doc:`/using_yosys/more_scripting/interactive_investigation` page.