riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs: Fix warnings 

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-01-18 13:49:34 +13:00
parent d4368b9e58
commit abec2f4a04
No known key found for this signature in database
15 changed files with 90 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/source/appendix/auxlibs.rst
View File

@ -29,8 +29,7 @@ ezSAT
The files in ``libs/ezsat`` provide a library for simplifying generating CNF
formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT
library is written by C. Wolf. It is used by the `sat` pass (see
:doc:`/cmd/sat`).
library is written by C. Wolf. It is used by the `sat` pass.
fst
---
@ -78,4 +77,4 @@ SubCircuit
The files in ``libs/subcircuit`` provide a library for solving the subcircuit
isomorphism problem. It is written by C. Wolf and based on the Ullmann Subgraph
Isomorphism Algorithm :cite:p:`UllmannSubgraphIsomorphism`. It is used by the
extract pass (see :doc:`../cmd/extract`).
`extract` pass.

4
docs/source/cmd/index_techlibs.rst
View File

@ -1,5 +1,9 @@
techlibs
------------------
.. TODO:: disambiguate `synth_intel` and `synth_intel_alm`
(MAX10, Cyclone IV) and (Cyclone V, Arria V, Cyclone 10 GX) respectively
.. autocmdgroup:: techlibs
:members:

23
docs/source/code_examples/macro_commands/prep.ys Normal file
View File

@ -0,0 +1,23 @@
#start:The following commands are executed by this synthesis command:
#end:$
begin:
hierarchy -check [-top <top> | -auto-top]
coarse:
proc [-ifx]
flatten (if -flatten)
future
opt_expr -keepdc
opt_clean
check
opt -noff -keepdc
wreduce -keepdc [-memx]
memory_dff (if -rdff)
memory_memx (if -memx)
opt_clean
memory_collect
opt -noff -keepdc -fast
check:
stat
check

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.

8
docs/source/using_yosys/more_scripting/interactive_investigation.rst
View File

@ -323,9 +323,9 @@ tools).
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`.
- :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a
- :cmd:ref:`show`.
- :cmd:ref:`dump`.
- :cmd:ref:`add` and :cmd:ref:`delete` can be used to modify and reorganize a
design dynamically.
The code used is included in the Yosys code base under
@ -358,7 +358,7 @@ reorganizing a module in Yosys and checking the resulting circuit.
.. figure:: /_images/code_examples/scrambler/scrambler_p02.*
:class: width-helper invert-helper
Analyzing the resulting circuit with :doc:`/cmd/eval`:
Analyzing the resulting circuit with :cmd:ref:`eval`:
.. todo:: replace inline code

10
docs/source/using_yosys/more_scripting/load_design.rst
View File

@ -1,9 +1,11 @@
Loading a design
~~~~~~~~~~~~~~~~
.. TODO:: fill out this page better
keyword: Frontends
- :doc:`/cmd/read_verilog`
- :doc:`/cmd/index_frontends`
.. todo:: include ``read_verilog <<EOF``, also other methods of loading designs
@ -37,12 +39,6 @@ keyword: Frontends
Others:
- :doc:`/cmd/read`
- `GHDL plugin`_ for VHDL
- :doc:`/cmd/read_rtlil` (direct textual representation of Yosys internal state)
- :doc:`/cmd/read_aiger`
- :doc:`/cmd/read_blif`
- :doc:`/cmd/read_json`
- :doc:`/cmd/read_liberty`
.. _GHDL plugin: https://github.com/ghdl/ghdl-yosys-plugin

6
docs/source/using_yosys/more_scripting/selections.rst
View File

@ -93,7 +93,7 @@ Special patterns can be used to select by object property or type. For example:
A:blabla`
- select all `$add` cells from the module foo: :yoscrypt:`select foo/t:$add`
A complete list of pattern expressions can be found in :doc:`/cmd/select`.
A complete list of pattern expressions can be found in :cmd:ref:`select`.
Operations on selections
~~~~~~~~~~~~~~~~~~~~~~~~
@ -141,7 +141,7 @@ Some of the special ``%``-codes:
- ``%i``: intersection of top two elements on stack -- pop 2, push 1
- ``%n``: inverse of top element on stack -- pop 1, push 1
See :doc:`/cmd/select` for the full list.
See :cmd:ref:`select` for the full list.
Expanding selections
^^^^^^^^^^^^^^^^^^^^
@ -354,7 +354,7 @@ boolean operations such as intersection (``%i``) and difference (``%d``) are
powerful tools for extracting the relevant portions of the circuit under
investigation.
Again, see :doc:`/cmd/select` for full documentation of these expressions.
Again, see :cmd:ref:`select` for full documentation of these expressions.
Incremental selection
^^^^^^^^^^^^^^^^^^^^^

2
docs/source/using_yosys/synthesis/fsm.rst
View File

@ -10,7 +10,7 @@ other commands:
:start-after: #end:
:caption: Passes called by `fsm`
See also :doc:`/cmd/fsm`.
See also :doc:`/cmd/index_passes_fsm`.
The algorithms used for FSM detection and extraction are influenced by a more
general reported technique :cite:p:`fsmextract`.

2
docs/source/using_yosys/synthesis/memory.rst
View File

@ -26,7 +26,7 @@ Some quick notes:
decoder logic and registers.
For more information about `memory`, such as disabling certain sub commands, see
:doc:`/cmd/memory`.
:doc:`/cmd/index_passes_memory`.
Example
-------

8
docs/source/using_yosys/synthesis/opt.rst
View File

@ -11,8 +11,8 @@ The `opt` macro command
The Yosys pass `opt` runs a number of simple optimizations. This includes
removing unused signals and cells and const folding. It is recommended to run
this pass after each major step in the synthesis script. As listed in
:doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
this pass after each major step in the synthesis script. This macro command
calls the following ``opt_*`` commands:
.. literalinclude:: /code_examples/macro_commands/opt.ys
:language: yoscrypt
@ -226,7 +226,5 @@ Other optimizations
.. todo:: more on the other optimizations
- :doc:`/cmd/wreduce`
- :doc:`/cmd/peepopt`
- :doc:`/cmd/share`
- Check :doc:`/cmd/index_passes_opt` for more.
- `abc` and `abc9`, see also: :doc:`abc`.

2
docs/source/using_yosys/synthesis/proc.rst
View File

@ -17,7 +17,7 @@ commands in a sensible order:
After all the ``proc_*`` commands, `opt_expr` is called. This can be disabled by
calling :yoscrypt:`proc -noopt`. For more information about `proc`, such as
disabling certain sub commands, see :doc:`/cmd/proc`.
disabling certain sub commands, see :doc:`/cmd/index_passes_proc`.
Many commands can not operate on modules with "processess" in them. Usually a
call to `proc` is the first command in the actual synthesis procedure after

33
docs/source/using_yosys/synthesis/synth.rst
View File

@ -6,44 +6,23 @@ Synth commands
Packaged ``synth_*`` commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following is a list of all synth commands included in Yosys for different
platforms. Each command runs a script of sub commands specific to the platform
being targeted. Note that not all of these scripts are actively maintained and
may not be up-to-date.
- :doc:`/cmd/synth_achronix`
- :doc:`/cmd/synth_anlogic`
- :doc:`/cmd/synth_coolrunner2`
- :doc:`/cmd/synth_easic`
- :doc:`/cmd/synth_ecp5`
- :doc:`/cmd/synth_efinix`
- :doc:`/cmd/synth_fabulous`
- :doc:`/cmd/synth_gatemate`
- :doc:`/cmd/synth_gowin`
- :doc:`/cmd/synth_greenpak4`
- :doc:`/cmd/synth_ice40`
- :doc:`/cmd/synth_intel` (MAX10, Cyclone IV)
- :doc:`/cmd/synth_intel_alm` (Cyclone V, Arria V, Cyclone 10 GX)
- :doc:`/cmd/synth_lattice`
- :doc:`/cmd/synth_nexus`
- :doc:`/cmd/synth_quicklogic`
- :doc:`/cmd/synth_sf2`
- :doc:`/cmd/synth_xilinx`
A list of all synth commands included in Yosys for different platforms can be
found under :doc:`/cmd/index_techlibs`. Each command runs a script of sub
commands specific to the platform being targeted. Note that not all of these
scripts are actively maintained and may not be up-to-date.
General synthesis
~~~~~~~~~~~~~~~~~
In addition to the above hardware-specific synth commands, there is also
:doc:`/cmd/prep`. This command is limited to coarse-grain synthesis, without
:cmd:ref:`prep`. This command is limited to coarse-grain synthesis, without
getting into any architecture-specific mappings or optimizations. Among other
things, this is useful for design verification.
The following commands are executed by the `prep` command:
.. literalinclude:: /cmd/prep.rst
.. literalinclude:: /code_examples/macro_commands/prep.ys
:start-at: begin:
:end-before: .. only:: latex
:dedent:
:doc:`/getting_started/example_synth` covers most of these commands and what
they do.

6
docs/source/using_yosys/synthesis/techmap_synth.rst
View File

@ -33,9 +33,9 @@ reader may find this map file as :file:`techlibs/common/techmap.v` in the Yosys
source tree.
Additional features have been added to techmap to allow for conditional mapping
of cells (see :doc:`/cmd/techmap`). This can for example be useful if the target
architecture supports hardware multipliers for certain bit-widths but not for
others.
of cells (see :doc:`/cmd/index_passes_techmap`). This can for example be useful
if the target architecture supports hardware multipliers for certain bit-widths
but not for others.
A usual synthesis flow would first use the techmap pass to directly map some RTL
cells to coarse-grain cells provided by the target architecture (if any) and

5
docs/util/newcmdref.py
View File

@ -305,7 +305,10 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
return False
def get_sourcename(self) -> str:
return self.object.source_file
try:
return self.object.source_file
except AttributeError:
return super().get_sourcename()
def format_name(self) -> str:
return self.object.name