mirror of
https://github.com/YosysHQ/yosys
synced 2025-07-27 06:27:57 +00:00
Revert "Add groups to command reference"
This commit is contained in:
N. Engelhardt
GitHub
parent
2223d7848b
commit
81f87ce6ed
124 changed files with 474 additions and 2035 deletions
|
|
@ -18,8 +18,3 @@
|
|||
.literal-block-wrapper .code-block-caption .caption-number {
|
||||
padding-right: 0.5em
|
||||
}
|
||||
|
||||
/* Don't double shrink text in a literal in an optionlist */
|
||||
kbd .option>.literal {
|
||||
font-size: revert;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -29,7 +29,8 @@ 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.
|
||||
library is written by C. Wolf. It is used by the `sat` pass (see
|
||||
:doc:`/cmd/sat`).
|
||||
|
||||
fst
|
||||
---
|
||||
|
|
@ -77,4 +78,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.
|
||||
extract pass (see :doc:`../cmd/extract`).
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
Writing output files
|
||||
--------------------
|
||||
|
||||
.. autocmdgroup:: backends
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Formal verification
|
||||
-------------------
|
||||
|
||||
.. autocmdgroup:: formal
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Reading input files
|
||||
-------------------
|
||||
|
||||
.. autocmdgroup:: frontends
|
||||
:members:
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
Internal commands for developers
|
||||
--------------------------------
|
||||
|
||||
.. autocmdgroup:: internal
|
||||
:members:
|
||||
|
||||
Writing command help
|
||||
--------------------
|
||||
|
||||
- use `chformal` as an example
|
||||
- generated help content below
|
||||
|
||||
.. _chformal autocmd:
|
||||
|
||||
.. autocmd:: chformal
|
||||
:noindex:
|
||||
|
||||
The ``formatted_help()`` method
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``PrettyHelp::get_current()``
|
||||
- ``PrettyHelp::set_group()``
|
||||
|
||||
+ used with ``.. autocmdgroup:: <group>``
|
||||
+ can assign group and return false
|
||||
+ if no group is set, will try to use ``source_location`` and assign group
|
||||
from path to source file
|
||||
|
||||
- return value
|
||||
|
||||
+ true means help content added to current ``PrettyHelp``
|
||||
+ false to use ``Pass::help()``
|
||||
|
||||
- adding content
|
||||
|
||||
+ help content is a list of ``ContentListing`` nodes, each one having a type,
|
||||
body, and its own list of children ``ContentListing``\ s
|
||||
+ ``PrettyHelp::get_root()`` returns the root ``ContentListing`` (``type="root"``)
|
||||
+ ``ContentListing::{usage, option, codeblock, paragraph}`` each add a
|
||||
``ContentListing`` to the current node, with type the same as the method
|
||||
|
||||
* the first argument is the body of the new node
|
||||
* ``usage`` shows how to call the command (i.e. its "signature")
|
||||
* ``paragraph`` content is formatted as a paragraph of text with line breaks
|
||||
added automatically
|
||||
* ``codeblock`` content is displayed verbatim, use line breaks as desired;
|
||||
takes an optional ``language`` argument for assigning the language in RST
|
||||
output for code syntax highlighting (use ``yoscrypt`` for yosys script
|
||||
syntax highlighting)
|
||||
* ``option`` lists a single option for the command, usually starting with a
|
||||
dash (``-``); takes an optional second argument which adds a paragraph
|
||||
node as a means of description
|
||||
|
||||
+ ``ContentListing::open_usage`` creates and returns a new usage node, can be
|
||||
used to e.g. add text/options specific to a given usage of the command
|
||||
+ ``ContentListing::open_option`` creates and returns a new option node, can
|
||||
be used to e.g. add multiple paragraphs to an option's description
|
||||
+ paragraphs are treated as raw RST, allowing for inline formatting and
|
||||
references as if it were written in the RST file itself
|
||||
|
||||
.. literalinclude:: /generated/chformal.cc
|
||||
:language: c++
|
||||
:start-at: bool formatted_help()
|
||||
:end-before: void execute
|
||||
:caption: ``ChformalPass::formatted_help()`` from :file:`passes/cmds/chformal.cc`
|
||||
|
||||
Dumping command help to json
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- `help -dump-cells-json cmds.json`
|
||||
|
||||
+ generates a ``ContentListing`` for each command registered in Yosys
|
||||
+ tries to parse unformatted ``Pass::help()`` output if
|
||||
``Pass::formatted_help()`` is unimplemented or returns false
|
||||
|
||||
* if a line starts with four spaces followed by the name of the command then
|
||||
a space, it is parsed as a signature (usage node)
|
||||
* if a line is indented and starts with a dash (``-``), it is parsed as an
|
||||
option
|
||||
* anything else is parsed as a codeblock and added to either the root node
|
||||
or the current option depending on the indentation
|
||||
|
||||
+ dictionary of command name to ``ContentListing``
|
||||
|
||||
* uses ``ContentListing::to_json()`` recursively for each node in root
|
||||
* root node used for source location of class definition
|
||||
* includes flags set during pass constructor (e.g. ``experimental_flag`` set
|
||||
by ``Pass::experimental()``)
|
||||
* also title (``short_help`` argument in ``Pass::Pass``), group, and class
|
||||
name
|
||||
|
||||
+ dictionary of group name to list of commands in that group
|
||||
|
||||
- used by sphinx autodoc to generate help content
|
||||
|
||||
.. literalinclude:: /generated/cmds.json
|
||||
:language: json
|
||||
:start-at: "chformal": {
|
||||
:end-before: "chparam": {
|
||||
:caption: `chformal` in generated :file:`cmds.json`
|
||||
|
||||
.. note:: Synthesis command scripts are special cased
|
||||
|
||||
If the final block of help output starts with the string `"The following
|
||||
commands are executed by this synthesis command:\n"`, then the rest of the
|
||||
code block is formatted as ``yoscrypt`` (e.g. `synth_ice40`). The caveat
|
||||
here is that if the ``script()`` calls ``run()`` on any commands *prior* to
|
||||
the first ``check_label`` then the auto detection will break and revert to
|
||||
unformatted code (e.g. `synth_fabulous`).
|
||||
|
||||
Command line rendering
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- if ``Pass::formatted_help()`` returns true, will call
|
||||
``PrettyHelp::log_help()``
|
||||
|
||||
+ traverse over the children of the root node and render as plain text
|
||||
+ effectively the reverse of converting unformatted ``Pass::help()`` text
|
||||
+ lines are broken at 80 characters while maintaining indentation (controlled
|
||||
by ``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`)
|
||||
+ each line is broken into words separated by spaces, if a given word starts
|
||||
and ends with backticks they will be stripped
|
||||
|
||||
- if it returns false it will call ``Pass::help()`` which should call ``log()``
|
||||
directly to print and format help text
|
||||
|
||||
+ if ``Pass::help()`` is not overridden then a default message about missing
|
||||
help will be displayed
|
||||
|
||||
.. literalinclude:: /generated/chformal.log
|
||||
:lines: 2-
|
||||
|
||||
RST generated from autocmd
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- below is the raw RST output from ``autocmd`` (``YosysCmdDocumenter`` class in
|
||||
:file:`docs/util/cmd_documenter.py`) for `chformal` command
|
||||
- heading will be rendered as a subheading of the most recent heading (see
|
||||
`chformal autocmd`_ above rendered under `Writing command help`_)
|
||||
- ``.. cmd:def:: <cmd>`` line is indexed for cross references with ``:cmd:ref:``
|
||||
directive (`chformal autocmd`_ above uses ``:noindex:`` option so that
|
||||
`chformal` still links to the correct location)
|
||||
|
||||
+ ``:title:`` option controls text that appears when hovering over the
|
||||
`chformal` link
|
||||
|
||||
- commands with warning flags (experimental or internal) add a ``.. warning``
|
||||
block before any of the help content
|
||||
- if a command has no ``source_location`` the ``.. note`` at the bottom will
|
||||
instead link to :doc:`/cmd/index_other`
|
||||
|
||||
.. autocmd_rst:: chformal
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Yosys kernel commands
|
||||
---------------------
|
||||
|
||||
.. autocmdgroup:: kernel
|
||||
:members:
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
:orphan:
|
||||
|
||||
Other commands
|
||||
==============
|
||||
|
||||
Unknown source location
|
||||
|
||||
.. autocmdgroup:: unknown
|
||||
:members:
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
Passes
|
||||
------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
/cmd/index_passes_hierarchy
|
||||
/cmd/index_passes_proc
|
||||
/cmd/index_passes_fsm
|
||||
/cmd/index_passes_memory
|
||||
/cmd/index_passes_opt
|
||||
/cmd/index_passes_techmap
|
||||
/cmd/index_passes_*
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Design modification
|
||||
-------------------
|
||||
|
||||
.. autocmdgroup:: passes/cmds
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Equivalence checking
|
||||
--------------------
|
||||
|
||||
.. autocmdgroup:: passes/equiv
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
FSM handling
|
||||
------------
|
||||
|
||||
.. autocmdgroup:: passes/fsm
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Working with hierarchy
|
||||
----------------------
|
||||
|
||||
.. autocmdgroup:: passes/hierarchy
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Memory handling
|
||||
---------------
|
||||
|
||||
.. autocmdgroup:: passes/memory
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Optimization passes
|
||||
-------------------
|
||||
|
||||
.. autocmdgroup:: passes/opt
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Converting process blocks
|
||||
-------------------------
|
||||
|
||||
.. autocmdgroup:: passes/proc
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Simulating circuits
|
||||
-------------------
|
||||
|
||||
.. autocmdgroup:: passes/sat
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Design status
|
||||
-------------
|
||||
|
||||
.. autocmdgroup:: passes/status
|
||||
:members:
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
Technology mapping
|
||||
------------------
|
||||
|
||||
.. seealso:: :doc:`/cmd/index_techlibs`
|
||||
|
||||
.. autocmdgroup:: passes/techmap
|
||||
:members:
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
Technology libraries
|
||||
====================
|
||||
|
||||
Listed in alphabetical order.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
/cmd/index_techlibs_common
|
||||
/cmd/index_techlibs_*
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Achronix
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/achronix
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Anlogic
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/anlogic
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Generic
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/common
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
CoolRunner-II
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/coolrunner2
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
eASIC
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/easic
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
ECP5
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/ecp5
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
FABulous
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/fabulous
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Gatemate
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/gatemate
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Gowin
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/gowin
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
GreenPAK4
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/greenpak4
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
iCE40
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/ice40
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Intel (MAX10, Cyclone IV)
|
||||
-------------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/intel
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Intel ALM (Cyclone V, Arria V, Cyclone 10 GX)
|
||||
---------------------------------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/intel_alm
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Lattice
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/lattice
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Lattice Nexus
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/nexus
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Microchip
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/microchip
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Microchip - SmartFusion2/IGLOO2
|
||||
-----------------------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/sf2
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
NanoXplore
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/nanoxplore
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
QuickLogic
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/quicklogic
|
||||
:members:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
Xilinx
|
||||
------------------
|
||||
|
||||
.. autocmdgroup:: techlibs/xilinx
|
||||
:members:
|
||||
|
|
@ -1,3 +1,5 @@
|
|||
.. _cmd_ref:
|
||||
|
||||
================================================================================
|
||||
Command line reference
|
||||
================================================================================
|
||||
|
|
@ -5,31 +7,10 @@ Command line reference
|
|||
.. literalinclude:: /generated/yosys
|
||||
:start-at: Usage
|
||||
|
||||
.. _cmd_ref:
|
||||
|
||||
Command reference
|
||||
-----------------
|
||||
|
||||
.. todo:: Can we warn on command groups that aren't included anywhere?
|
||||
|
||||
:ref:`List of all commands<cmd-cmd>`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Command reference
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
/appendix/env_vars
|
||||
/cmd/index_frontends
|
||||
/cmd/index_backends
|
||||
/cmd/index_kernel
|
||||
/cmd/index_formal
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
/cmd/index_passes
|
||||
/cmd/index_techlibs
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
/cmd/index_internal
|
||||
/appendix/env_vars
|
||||
/cmd/*
|
||||
|
|
|
|||
|
|
@ -1,23 +0,0 @@
|
|||
#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
|
||||
|
|
@ -43,12 +43,8 @@ html_static_path = ['_static', "_images"]
|
|||
# default to no highlight
|
||||
highlight_language = 'none'
|
||||
|
||||
# default single quotes to attempt auto reference, or fallback to yoscrypt
|
||||
# default single quotes to attempt auto reference, or fallback to code
|
||||
default_role = 'autoref'
|
||||
rst_prolog = """
|
||||
.. role:: yoscrypt(code)
|
||||
:language: yoscrypt
|
||||
"""
|
||||
|
||||
extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
|
||||
|
||||
|
|
@ -110,14 +106,12 @@ latex_elements = {
|
|||
|
||||
# custom cmd-ref parsing/linking
|
||||
sys.path += [os.path.dirname(__file__) + "/../"]
|
||||
extensions.append('util.custom_directives')
|
||||
extensions.append('util.cmdref')
|
||||
|
||||
# use autodocs
|
||||
extensions.append('sphinx.ext.autodoc')
|
||||
extensions.append('util.cell_documenter')
|
||||
extensions.append('util.cellref')
|
||||
cells_json = Path(__file__).parent / 'generated' / 'cells.json'
|
||||
extensions.append('util.cmd_documenter')
|
||||
cmds_json = Path(__file__).parent / 'generated' / 'cmds.json'
|
||||
|
||||
from sphinx.application import Sphinx
|
||||
def setup(app: Sphinx) -> None:
|
||||
|
|
|
|||
|
|
@ -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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
:language: yoscrypt
|
||||
:start-after: begin:
|
||||
:end-before: flatten:
|
||||
|
|
@ -143,8 +143,8 @@ 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: :cmd:title:`proc`.
|
||||
`proc` is a macro command like `synth_ice40`. Rather than modifying the design
|
||||
To handle these, let us now introduce the next command: :doc:`/cmd/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
|
||||
multiplexers and registers. Let's see what happens when we run it. For now, we
|
||||
|
|
@ -188,7 +188,7 @@ opt_expr <adv_opt_expr>`.
|
|||
|
||||
.. note::
|
||||
|
||||
:cmd:title:`clean` can also be called with two semicolons after any command,
|
||||
: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 `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:
|
||||
|
||||
- :cmd:title:`design`, and
|
||||
- :cmd:title:`read_verilog`.
|
||||
- :doc:`/cmd/design`, and
|
||||
- :doc:`/cmd/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 :cmd:title:`show`. Note that the `show` command only works
|
||||
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 `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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:
|
||||
:cmd:title:`fsm`. Both `opt` and `fsm` are macro commands which are explored in
|
||||
: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.
|
||||
|
||||
|
|
@ -403,7 +403,7 @@ Part 2
|
|||
|
||||
The next group of commands performs a series of optimizations:
|
||||
|
||||
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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 :cmd:title:`wreduce`. If we run this we get the following:
|
||||
First up is :doc:`/cmd/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 :cmd:title:`peepopt` and :cmd:title:`share`.
|
||||
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
|
||||
|
|
@ -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
|
||||
:cmd:title:`memory_dff`.
|
||||
:doc:`/cmd/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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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 :cmd:title:`memory`. `memory` is another
|
||||
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: `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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
: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:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
:language: yoscrypt
|
||||
:start-after: map_cells:
|
||||
:end-before: check:
|
||||
|
|
@ -784,18 +784,19 @@ Final steps
|
|||
The next section of the iCE40 synth flow performs some sanity checking and final
|
||||
tidy up:
|
||||
|
||||
.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
|
||||
.. literalinclude:: /cmd/synth_ice40.rst
|
||||
:language: yoscrypt
|
||||
:start-after: check:
|
||||
:end-before: blif:
|
||||
:dedent:
|
||||
:name: check
|
||||
:caption: ``check`` section
|
||||
|
||||
The new commands here are:
|
||||
|
||||
- :cmd:title:`autoname`,
|
||||
- :cmd:title:`stat`, and
|
||||
- :cmd:title:`blackbox`.
|
||||
- :doc:`/cmd/autoname`,
|
||||
- :doc:`/cmd/stat`, and
|
||||
- :doc:`/cmd/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
|
||||
|
|
@ -834,9 +835,9 @@ Synthesis output
|
|||
|
||||
The iCE40 synthesis flow has the following output modes available:
|
||||
|
||||
- `write_blif`,
|
||||
- `write_edif`, and
|
||||
- `write_json`.
|
||||
- :doc:`/cmd/write_blif`,
|
||||
- :doc:`/cmd/write_edif`, and
|
||||
- :doc:`/cmd/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
|
||||
|
|
@ -847,4 +848,4 @@ is beyond the scope of this documentation.
|
|||
|
||||
.. _nextpnr: https://github.com/YosysHQ/nextpnr
|
||||
|
||||
.. seealso:: :cmd:title:`synth_ice40`
|
||||
.. seealso:: :doc:`/cmd/synth_ice40`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
:cmd:title:`select`.
|
||||
:doc:`/cmd/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
|
||||
:cmd:title:`show`.
|
||||
:doc:`/cmd/show`.
|
||||
|
||||
.. seealso:: :ref:`interactive_show` on the
|
||||
:doc:`/using_yosys/more_scripting/interactive_investigation` page.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Yosys Open SYnthesis Suite
|
|||
Yosys is an open source framework for RTL synthesis. To learn more about Yosys,
|
||||
see :doc:`/introduction`. For a quick guide on how to get started using Yosys,
|
||||
check out :doc:`/getting_started/index`. For the complete list of commands
|
||||
available, go to :ref:`cmd_ref`.
|
||||
available, go to :ref:`commandindex`.
|
||||
|
||||
.. todo:: look into command ref improvements
|
||||
|
||||
|
|
|
|||
|
|
@ -323,10 +323,10 @@ 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.
|
||||
- :cmd:title:`show`.
|
||||
- :cmd:title:`dump`.
|
||||
- :cmd:title:`add` and :cmd:title:`delete` can be used to modify and reorganize
|
||||
a design dynamically.
|
||||
- :doc:`/cmd/show`.
|
||||
- :doc:`/cmd/dump`.
|
||||
- :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a
|
||||
design dynamically.
|
||||
|
||||
The code used is included in the Yosys code base under
|
||||
|code_examples/scrambler|_.
|
||||
|
|
@ -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 :cmd:title:`eval`:
|
||||
Analyzing the resulting circuit with :doc:`/cmd/eval`:
|
||||
|
||||
.. todo:: replace inline code
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,9 @@
|
|||
Loading a design
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. TODO:: fill out this page better
|
||||
|
||||
keyword: Frontends
|
||||
|
||||
- :doc:`/cmd/index_frontends`
|
||||
- :doc:`/cmd/read_verilog`
|
||||
|
||||
.. todo:: include ``read_verilog <<EOF``, also other methods of loading designs
|
||||
|
||||
|
|
@ -31,14 +29,20 @@ keyword: Frontends
|
|||
|
||||
.. note::
|
||||
|
||||
The Verific frontend for Yosys, which provides the `verific` command,
|
||||
requires Yosys to be built with Verific. For full functionality, custom
|
||||
modifications to the Verific source code from YosysHQ are required, but
|
||||
limited useability can be achieved with some stock Verific builds. Check
|
||||
The Verific frontend for Yosys, which provides the :cmd:ref:`verific`
|
||||
command, requires Yosys to be built with Verific. For full functionality,
|
||||
custom modifications to the Verific source code from YosysHQ are required,
|
||||
but limited useability can be achieved with some stock Verific builds. Check
|
||||
:doc:`/yosys_internals/extending_yosys/build_verific` for more.
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 :cmd:title:`select`.
|
||||
A complete list of pattern expressions can be found in :doc:`/cmd/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 :cmd:title:`select` for the full list.
|
||||
See :doc:`/cmd/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 :cmd:title:`select` for full documentation of these expressions.
|
||||
Again, see :doc:`/cmd/select` for full documentation of these expressions.
|
||||
|
||||
Incremental selection
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ other commands:
|
|||
:start-after: #end:
|
||||
:caption: Passes called by `fsm`
|
||||
|
||||
See also :doc:`/cmd/index_passes_fsm`.
|
||||
See also :doc:`/cmd/fsm`.
|
||||
|
||||
The algorithms used for FSM detection and extraction are influenced by a more
|
||||
general reported technique :cite:p:`fsmextract`.
|
||||
|
|
|
|||
|
|
@ -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/index_passes_memory`.
|
||||
:doc:`/cmd/memory`.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -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. This macro command
|
||||
calls the following ``opt_*`` commands:
|
||||
this pass after each major step in the synthesis script. As listed in
|
||||
:doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
|
||||
|
||||
.. literalinclude:: /code_examples/macro_commands/opt.ys
|
||||
:language: yoscrypt
|
||||
|
|
@ -233,5 +233,7 @@ Other optimizations
|
|||
|
||||
.. todo:: more on the other optimizations
|
||||
|
||||
- Check :doc:`/cmd/index_passes_opt` for more.
|
||||
- :doc:`/cmd/wreduce`
|
||||
- :doc:`/cmd/peepopt`
|
||||
- :doc:`/cmd/share`
|
||||
- `abc` and `abc9`, see also: :doc:`abc`.
|
||||
|
|
|
|||
|
|
@ -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/index_passes_proc`.
|
||||
disabling certain sub commands, see :doc:`/cmd/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
|
||||
|
|
|
|||
|
|
@ -6,23 +6,44 @@ Synth commands
|
|||
Packaged ``synth_*`` commands
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
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`
|
||||
|
||||
General synthesis
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the above hardware-specific synth commands, there is also
|
||||
:cmd:title:`prep`. This command is limited to coarse-grain synthesis, without
|
||||
:doc:`/cmd/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:: /code_examples/macro_commands/prep.ys
|
||||
.. literalinclude:: /cmd/prep.rst
|
||||
:start-at: begin:
|
||||
:end-before: .. only:: latex
|
||||
:dedent:
|
||||
|
||||
:doc:`/getting_started/example_synth` covers most of these commands and what
|
||||
they do.
|
||||
|
|
|
|||
|
|
@ -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/index_passes_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/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
|
||||
|
|
|
|||
|
|
@ -138,7 +138,7 @@ Previously, the interface to implement hashing on custom types was just
|
|||
independently and then ad-hoc combined with the hash function with some xorshift
|
||||
operations thrown in to mix bits together somewhat. A plugin can stay compatible
|
||||
with both versions prior and after the break by implementing both interfaces
|
||||
based on the existance and value of ``YS_HASHING_VERSION``.
|
||||
based on the existance and value of `YS_HASHING_VERSION`.
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: Example hash compatibility wrapper
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ Verilog Attributes and non-standard features
|
|||
- The ``keep_hierarchy`` attribute on cells and modules keeps the `flatten`
|
||||
command from flattening the indicated cells and modules.
|
||||
|
||||
- The ``gate_cost_equivalent`` attribute on a module can be used to specify
|
||||
- The `gate_cost_equivalent` attribute on a module can be used to specify
|
||||
the estimated cost of the module as a number of basic gate instances. See
|
||||
the help message of command `keep_hierarchy` which interprets this
|
||||
attribute.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue