From 14b7c581fa97e914441c059095705fac8e4a9dbc Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 18 Jan 2024 15:33:59 +1300 Subject: [PATCH] Docs: reworking scripting_intro Now comes *after* example_synth, with references back to it. Includes some minor adjustment to the `fifo.ys` script to better demonstrate the `select` command. Still needs an updated section on `show`. Also includes some other minor updates. --- docs/source/code_examples/fifo/fifo.out | 31 +++- docs/source/code_examples/fifo/fifo.ys | 7 +- docs/source/getting_started/example_synth.rst | 3 + docs/source/getting_started/index.rst | 2 +- .../getting_started/scripting_intro.rst | 169 ++++++++---------- docs/source/using_yosys/synthesis/opt.rst | 2 + docs/source/using_yosys/yosys_flows.rst | 38 ++-- docs/source/yosys_internals/flow/overview.rst | 7 +- 8 files changed, 139 insertions(+), 120 deletions(-) diff --git a/docs/source/code_examples/fifo/fifo.out b/docs/source/code_examples/fifo/fifo.out index 30236a7ab..d18fce14b 100644 --- a/docs/source/code_examples/fifo/fifo.out +++ b/docs/source/code_examples/fifo/fifo.out @@ -27,7 +27,36 @@ Removing unused module `$abstract\fifo'. Removing unused module `$abstract\addr_gen'. Removed 2 unused modules. -yosys> select -set new_cells t:* +yosys> select -module addr_gen + +yosys [addr_gen]> select -list +addr_gen +addr_gen/$1\addr[7:0] +addr_gen/$add$fifo.v:20$3_Y +addr_gen/$eq$fifo.v:17$2_Y +addr_gen/$0\addr[7:0] +addr_gen/addr +addr_gen/rst +addr_gen/clk +addr_gen/en +addr_gen/$add$fifo.v:20$3 +addr_gen/$eq$fifo.v:17$2 +addr_gen/$proc$fifo.v:0$4 +addr_gen/$proc$fifo.v:13$1 + +yosys [addr_gen]> select t:* + +yosys [addr_gen]*> select -list +addr_gen/$add$fifo.v:20$3 +addr_gen/$eq$fifo.v:17$2 + +yosys [addr_gen]*> select -set new_cells % + +yosys [addr_gen]*> select -clear + +yosys> select -list addr_gen/t:* +addr_gen/$add$fifo.v:20$3 +addr_gen/$eq$fifo.v:17$2 yosys> show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier diff --git a/docs/source/code_examples/fifo/fifo.ys b/docs/source/code_examples/fifo/fifo.ys index b89361e75..0584285ea 100644 --- a/docs/source/code_examples/fifo/fifo.ys +++ b/docs/source/code_examples/fifo/fifo.ys @@ -9,7 +9,12 @@ read_verilog -defer fifo.v # turn command echoes on to use the log output as a console session echo on hierarchy -top addr_gen -select -set new_cells t:* +select -module addr_gen +select -list +select t:* +select -list +select -set new_cells % +select -clear show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier # ======================================================== diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index e1cc257db..811c39a28 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -86,6 +86,8 @@ start mapping to hardware we will still need to load them later. Yosys from the source directory, this will be the ``share`` folder in the same directory. +.. _addr_gen_example: + The addr_gen module ^^^^^^^^^^^^^^^^^^^ @@ -115,6 +117,7 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy :start-at: yosys> hierarchy -top addr_gen :end-before: yosys> select :caption: :yoscrypt:`hierarchy -top addr_gen` output + :name: hierarchy_output Our ``addr_gen`` circuit now looks like this: diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index a3c4a265b..51628c67f 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -7,5 +7,5 @@ Getting started with Yosys :maxdepth: 3 installation - scripting_intro example_synth + scripting_intro diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index 4ce038e91..d4d809fbd 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -1,116 +1,91 @@ Scripting in Yosys ------------------ -.. TODO:: logical consistency, esp with example_synth +On the previous page we went through a synthesis script, running each command in +the interactive Yosys shell. On this page, we will be introducing the script +file format and how you can make your own synthesis scripts. -Yosys reads and processes commands from synthesis scripts, command line -arguments and an interactive command prompt. Yosys commands consist of a command -name and an optional whitespace separated list of arguments. Commands are -terminated using the newline character or a semicolon (;). Empty lines and lines -starting with the hash sign (#) are ignored. Also see :doc:`example_synth`. +Yosys script files typically use the ``.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`. As with the interactive shell, each command consists of +the command name, and an optional whitespace separated list of arguments. +Commands are terminated with the newline character, or by a semicolon (;). +Empty lines, and lines starting with the hash sign (#), are ignored. -The command :cmd:ref:`help` can be used to access the command reference manual, -with ``help `` providing details for a specific command. ``yosys -H`` -or ``yosys -h `` will do the same outside of an interactive prompt. -The entire reference manual is also available here at :doc:`/cmd_ref`. +The synthesis starter script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Example commands -~~~~~~~~~~~~~~~~ +.. role:: yoscrypt(code) + :language: yoscrypt -Commands for design navigation and investigation: +All of the images and console output used in +:doc:`/getting_started/example_synth` were generated by Yosys, using Yosys +script files found in ``docs/source/code_examples/fifo``. If you haven't +already, let's take a look at some of those script files now. -.. code-block:: yoscrypt +.. literalinclude:: /code_examples/fifo/fifo.ys + :language: yoscrypt + :lineno-match: + :start-at: echo on + :end-before: design -reset + :caption: A section of ``fifo.ys``, generating the images used for :ref:`addr_gen_example` + :name: fifo-ys - cd # a shortcut for 'select -module ' - ls # list modules or objects in modules - dump # print parts of the design in RTLIL format - show # generate schematics using graphviz - select # modify and view the list of selected objects +The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`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 +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. -Commands for executing scripts or entering interactive mode: - -.. code-block:: yoscrypt - - shell # enter interactive command mode - history # show last interactive commands - script # execute commands from script file - tcl # execute a TCL script file - -Commands for reading and elaborating the design: - -.. code-block:: yoscrypt - - read_rtlil # read modules from RTLIL file - read_verilog # read modules from Verilog file - hierarchy # check, expand and clean up design hierarchy - - -Commands for high-level synthesis: - -.. code-block:: yoscrypt - - proc # translate processes to netlists - fsm # extract and optimize finite state machines - memory # translate memories to basic cells - opt # perform simple optimizations - - -Commands for technology mapping: - -.. code-block:: yoscrypt - - techmap # generic technology mapper - abc # use ABC for technology mapping - dfflibmap # technology mapping of flip-flops - hilomap # technology mapping of constant hi- and/or lo-drivers - iopadmap # technology mapping of i/o pads (or buffers) - flatten # flatten design - -Commands for writing the results: - -.. code-block:: yoscrypt - - write_blif # write design to BLIF file - write_btor # write design to BTOR file - write_edif # write design to EDIF netlist file - write_rtlil # write design to RTLIL file - write_spice # write design to SPICE netlist file - write_verilog # write design to Verilog file - - -Script-Commands for standard synthesis tasks: - -.. code-block:: yoscrypt - - synth # generic synthesis script - synth_xilinx # synthesis for Xilinx FPGAs - - -Commands for model checking: - -.. code-block:: yoscrypt - - sat # solve a SAT problem in the circuit - miter # automatically create a miter circuit - scc # detect strongly connected components (logic loops) +We briefly touched on :cmd:ref:`select` when it came up in +:cmd:ref:`synth_ice40`, but let's look at it more now. Selections intro -~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^ -.. todo:: reorder text for logical consistency +The :cmd:ref:`select` command is used to modify and view the list of selected +objects: -Most commands can operate not only on the entire design but also specifically on -selected parts of the design. For example the command :cmd:ref:`dump` will print -all selected objects in the current design while ``dump foobar`` will only print -the module ``foobar`` and ``dump *`` will print the entire design regardless of -the current selection. +.. literalinclude:: /code_examples/fifo/fifo.out + :language: doscon + :start-at: yosys> select + :end-before: yosys> show -.. code:: yoscrypt +When we call :yoscrypt:`select -module addr_gen` we are changing the currently +active selection from the whole design, to just the ``addr_gen`` module. Notice +how this changes the ``yosys`` at the start of each command to ``yosys +[addr_gen]``? This indicates that any commands we run at this point will *only* +operate on the ``addr_gen`` module. When we then call :yoscrypt:`select -list` +we get a list of all objects in the ``addr_gen`` module, including the module +itself, as well as all of the wires, inputs, outputs, processes, and cells. - dump */t:$add %x:+[A] */w:* %i +Next we perform another selection, :yoscrypt:`select t:*`. The ``t:`` part +signifies we are matching on the *cell type*, and the ``*`` means to match +anything. For this (very simple) selection, we are trying to find all of the +cells, regardless of their type. The active selection is now shown as +``[addr_gen]*``, indicating some sub-selection of the ``addr_gen`` module. This +gives us the ``$add`` and ``$eq`` cells, which we want to highlight for the +:ref:`addr_gen_hier` image. + +We can assign a name to a selection with :yoscrypt:`select -set`. In our case +we are using the name ``new_cells``, and telling it to use the current +selection, indicated by the ``%`` symbol. Then we clear the selection so that +the following commands can operate on the full design. While we split that out +for this document, we could have done the same thing in a single line by calling +:yoscrypt:`select -set new_cells addr_gen/t:*`. If we know we only have the one +module in our design, we can even skip the `addr_gen/` part. Looking further +down :ref:`the fifo.ys code ` we can see this with :yoscrypt:`select +-set new_cells t:$mux t:*dff`. We can also see in that command that selections +don't have to be limited to a single 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 +``addr_gen`` module. -The selection mechanism is very powerful. For example the command above will -print all wires that are connected to the ``\A`` port of a ``$add`` cell. 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`. @@ -118,6 +93,8 @@ Detailed documentation of the select framework can be found under The show command ~~~~~~~~~~~~~~~~ +.. TODO:: scripting_intro/show section + The :cmd:ref:`show` command requires a working installation of `GraphViz`_ and `xdot`_ for generating the actual circuit diagrams. Below is an example of how this command can be used, showing the changes in the generated circuit at diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index fb75c9fa1..0ba108131 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -26,6 +26,8 @@ to run this pass after each major step in the synthesis script. As listed in Constant folding and simple expression rewriting - :cmd:ref:`opt_expr` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index` + This pass performs constant folding on the internal combinational cell types described in :doc:`/yosys_internals/formats/cell_library`. This means a cell with all constant inputs is replaced with the constant value this cell drives. diff --git a/docs/source/using_yosys/yosys_flows.rst b/docs/source/using_yosys/yosys_flows.rst index 040ef5a4c..5bca90ade 100644 --- a/docs/source/using_yosys/yosys_flows.rst +++ b/docs/source/using_yosys/yosys_flows.rst @@ -4,7 +4,7 @@ Flows, command types, and order Command order ------------- -.. TODO:: check text is coherent +.. todo:: More surrounding text (esp as it relates to command order) Intro to coarse-grain synthesis ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -42,6 +42,8 @@ The extract pass .. todo:: add/expand supporting text, also mention custom pattern matching and pmgen +Example code can be found in ``docs/source/code_examples/macc/``. + .. literalinclude:: /code_examples/macc/macc_simple_test.ys :language: yoscrypt :lines: 1-2 @@ -62,15 +64,15 @@ The extract pass .. literalinclude:: /code_examples/macc/macc_simple_test.v :language: verilog - :caption: ``docs/source/code_examples/macc/macc_simple_test.v`` + :caption: ``macc_simple_test.v`` .. literalinclude:: /code_examples/macc/macc_simple_xmap.v :language: verilog - :caption: ``docs/source/code_examples/macc/macc_simple_xmap.v`` + :caption: ``macc_simple_xmap.v`` .. literalinclude:: /code_examples/macc/macc_simple_test_01.v :language: verilog - :caption: ``docs/source/code_examples/macc/macc_simple_test_01.v`` + :caption: ``macc_simple_test_01.v`` .. figure:: /_images/code_examples/macc/macc_simple_test_01a.* :class: width-helper @@ -80,7 +82,7 @@ The extract pass .. literalinclude:: /code_examples/macc/macc_simple_test_02.v :language: verilog - :caption: ``docs/source/code_examples/macc/macc_simple_test_02.v`` + :caption: ``macc_simple_test_02.v`` .. figure:: /_images/code_examples/macc/macc_simple_test_02a.* :class: width-helper @@ -95,14 +97,15 @@ Often a coarse-grain element has a constant bit-width, but can be used to implement operations with a smaller bit-width. For example, a 18x25-bit multiplier can also be used to implement 16x20-bit multiplication. -A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method: +A way of mapping such elements in coarse grain synthesis is the +wrap-extract-unwrap method: wrap Identify candidate-cells in the circuit and wrap them in a cell with a constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same parameters as the original cell, so the information about the original width - of the ports is preserved. Then use the ``connwrappers`` command to connect up - the bit-extended in- and outputs of the wrapper cells. + of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to + connect up the bit-extended in- and outputs of the wrapper cells. extract Now all operations are encoded using the same bit-width as the coarse grain @@ -117,7 +120,8 @@ Example: DSP48_MACC This section details an example that shows how to map MACC operations of arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder -(such as the Xilinx DSP48 cells). +(such as the Xilinx DSP48 cells). Source code can be found in +``docs/source/code_examples/macc/``. Preconditioning: ``macc_xilinx_swap_map.v`` @@ -127,27 +131,27 @@ Make sure ``A`` is the smaller port on all multipliers .. literalinclude:: /code_examples/macc/macc_xilinx_swap_map.v :language: verilog - :caption: ``docs/source/code_examples/macc/macc_xilinx_swap_map.v`` + :caption: ``macc_xilinx_swap_map.v`` Wrapping multipliers: ``macc_xilinx_wrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v :language: verilog :lines: 1-46 - :caption: ``docs/source/code_examples/macc/macc_xilinx_wrap_map.v`` + :caption: ``macc_xilinx_wrap_map.v`` Wrapping adders: ``macc_xilinx_wrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v :language: verilog :lines: 48-89 - :caption: ``docs/source/code_examples/macc/macc_xilinx_wrap_map.v`` + :caption: ``macc_xilinx_wrap_map.v`` Extract: ``macc_xilinx_xmap.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_xmap.v :language: verilog - :caption: ``docs/source/code_examples/macc/macc_xilinx_xmap.v`` + :caption: ``macc_xilinx_xmap.v`` ... simply use the same wrapping commands on this module as on the design to create a template for the :cmd:ref:`extract` command. @@ -157,19 +161,19 @@ Unwrapping multipliers: ``macc_xilinx_unwrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v :language: verilog :lines: 1-30 - :caption: ``docs/source/code_examples/macc/macc_xilinx_unwrap_map.v`` + :caption: ``$__mul_wrapper`` module in ``macc_xilinx_unwrap_map.v`` Unwrapping adders: ``macc_xilinx_unwrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v :language: verilog :lines: 32-61 - :caption: ``docs/source/code_examples/macc/macc_xilinx_unwrap_map.v`` + :caption: ``$__add_wrapper`` module in ``macc_xilinx_unwrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_test.v :language: verilog :lines: 1-6 - :caption: ``test1`` of ``docs/source/code_examples/macc/macc_xilinx_test.v`` + :caption: ``test1`` of ``macc_xilinx_test.v`` .. figure:: /_images/code_examples/macc/macc_xilinx_test1a.* :class: width-helper @@ -180,7 +184,7 @@ Unwrapping adders: ``macc_xilinx_unwrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_test.v :language: verilog :lines: 8-13 - :caption: ``test2`` of ``docs/source/code_examples/macc/macc_xilinx_test.v`` + :caption: ``test2`` of ``macc_xilinx_test.v`` .. figure:: /_images/code_examples/macc/macc_xilinx_test2a.* :class: width-helper diff --git a/docs/source/yosys_internals/flow/overview.rst b/docs/source/yosys_internals/flow/overview.rst index ae07e6f1f..f7589df03 100644 --- a/docs/source/yosys_internals/flow/overview.rst +++ b/docs/source/yosys_internals/flow/overview.rst @@ -16,12 +16,11 @@ language. The AST Frontend then compiles the AST to Yosys's main internal data format, the RTL Intermediate Language (RTLIL). A more detailed description of this format is -given in the next section. - -.. TODO:: what next section +given in :doc:`/yosys_internals/formats/rtlil_rep`. There is also a text representation of the RTLIL data structure that can be -parsed using the RTLIL Frontend. +parsed using the RTLIL Frontend which is described in +:doc:`/yosys_internals/formats/rtlil_text`. The design data may then be transformed using a series of passes that all operate on the RTLIL representation of the design.