From 794ad381c6dcaad52554fe93f502760e517ca91d Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 22 Jan 2024 11:10:02 +1300 Subject: [PATCH] Docs: scripting_intro/show_intro Adds two new `show` commands to `fifo.ys` for demo purposes. Mention referencing named selections with `@`. Also adds a note to `example_synth` to point to the show intro. --- docs/source/code_examples/fifo/fifo.out | 112 ++++++++------- docs/source/code_examples/fifo/fifo.ys | 2 + docs/source/getting_started/example_synth.rst | 3 +- .../getting_started/scripting_intro.rst | 134 ++++++++++++------ 4 files changed, 157 insertions(+), 94 deletions(-) diff --git a/docs/source/code_examples/fifo/fifo.out b/docs/source/code_examples/fifo/fifo.out index d18fce14b..85cf14f9c 100644 --- a/docs/source/code_examples/fifo/fifo.out +++ b/docs/source/code_examples/fifo/fifo.out @@ -54,78 +54,86 @@ 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 -format dot -prefix addr_gen_show addr_gen + +4. Generating Graphviz representation of design. +Writing dot description to `addr_gen_show.dot'. +Dumping module addr_gen to page 1. + +yosys> show -format dot -prefix new_cells_show -notitle @new_cells + +5. Generating Graphviz representation of design. +Writing dot description to `new_cells_show.dot'. +Dumping selected parts of module addr_gen to page 1. yosys> show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier -4. Generating Graphviz representation of design. +6. Generating Graphviz representation of design. Writing dot description to `addr_gen_hier.dot'. Dumping module addr_gen to page 1. yosys> proc -noopt -5. Executing PROC pass (convert processes to netlists). +7. Executing PROC pass (convert processes to netlists). yosys> proc_clean -5.1. Executing PROC_CLEAN pass (remove empty switches from decision trees). +7.1. Executing PROC_CLEAN pass (remove empty switches from decision trees). Cleaned up 0 empty switches. yosys> proc_rmdead -5.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees). +7.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees). Marked 2 switch rules as full_case in process $proc$fifo.v:13$1 in module addr_gen. Removed a total of 0 dead cases. yosys> proc_prune -5.3. Executing PROC_PRUNE pass (remove redundant assignments in processes). +7.3. Executing PROC_PRUNE pass (remove redundant assignments in processes). Removed 0 redundant assignments. Promoted 1 assignment to connection. yosys> proc_init -5.4. Executing PROC_INIT pass (extract init attributes). +7.4. Executing PROC_INIT pass (extract init attributes). Found init rule in `\addr_gen.$proc$fifo.v:0$4'. Set init value: \addr = 8'00000000 yosys> proc_arst -5.5. Executing PROC_ARST pass (detect async resets in processes). +7.5. Executing PROC_ARST pass (detect async resets in processes). Found async reset \rst in `\addr_gen.$proc$fifo.v:13$1'. yosys> proc_rom -5.6. Executing PROC_ROM pass (convert switches to ROMs). +7.6. Executing PROC_ROM pass (convert switches to ROMs). Converted 0 switches. yosys> proc_mux -5.7. Executing PROC_MUX pass (convert decision trees to multiplexers). +7.7. Executing PROC_MUX pass (convert decision trees to multiplexers). Creating decoders for process `\addr_gen.$proc$fifo.v:0$4'. Creating decoders for process `\addr_gen.$proc$fifo.v:13$1'. 1/1: $0\addr[7:0] yosys> proc_dlatch -5.8. Executing PROC_DLATCH pass (convert process syncs to latches). +7.8. Executing PROC_DLATCH pass (convert process syncs to latches). yosys> proc_dff -5.9. Executing PROC_DFF pass (convert process syncs to FFs). +7.9. Executing PROC_DFF pass (convert process syncs to FFs). Creating register for signal `\addr_gen.\addr' using process `\addr_gen.$proc$fifo.v:13$1'. created $adff cell `$procdff$10' with positive edge clock and positive level reset. yosys> proc_memwr -5.10. Executing PROC_MEMWR pass (convert process memory writes to cells). +7.10. Executing PROC_MEMWR pass (convert process memory writes to cells). yosys> proc_clean -5.11. Executing PROC_CLEAN pass (remove empty switches from decision trees). +7.11. Executing PROC_CLEAN pass (remove empty switches from decision trees). Removing empty process `addr_gen.$proc$fifo.v:0$4'. Found and cleaned up 2 empty switches in `\addr_gen.$proc$fifo.v:13$1'. Removing empty process `addr_gen.$proc$fifo.v:13$1'. @@ -135,13 +143,13 @@ yosys> select -set new_cells t:$mux t:*dff yosys> show -color maroon3 @new_cells -notitle -format dot -prefix addr_gen_proc -6. Generating Graphviz representation of design. +8. Generating Graphviz representation of design. Writing dot description to `addr_gen_proc.dot'. Dumping module addr_gen to page 1. yosys> opt_expr -7. Executing OPT_EXPR pass (perform const folding). +9. Executing OPT_EXPR pass (perform const folding). Optimizing module addr_gen. yosys> clean @@ -151,7 +159,7 @@ yosys> select -set new_cells t:$eq yosys> show -color cornflowerblue @new_cells -notitle -format dot -prefix addr_gen_clean -8. Generating Graphviz representation of design. +10. Generating Graphviz representation of design. Writing dot description to `addr_gen_clean.dot'. Dumping module addr_gen to page 1. @@ -159,7 +167,7 @@ yosys> design -reset yosys> read_verilog fifo.v -9. Executing Verilog-2005 frontend: fifo.v +11. Executing Verilog-2005 frontend: fifo.v Parsing Verilog input from `fifo.v' to AST representation. Generating RTLIL representation for module `\addr_gen'. Generating RTLIL representation for module `\fifo'. @@ -167,24 +175,24 @@ Successfully finished Verilog frontend. yosys> hierarchy -check -top fifo -10. Executing HIERARCHY pass (managing design hierarchy). +12. Executing HIERARCHY pass (managing design hierarchy). -10.1. Analyzing design hierarchy.. +12.1. Analyzing design hierarchy.. Top module: \fifo Used module: \addr_gen Parameter \MAX_DATA = 256 -10.2. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'. +12.2. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'. Parameter \MAX_DATA = 256 Generating RTLIL representation for module `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000'. Parameter \MAX_DATA = 256 Found cached RTLIL representation for module `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000'. -10.3. Analyzing design hierarchy.. +12.3. Analyzing design hierarchy.. Top module: \fifo Used module: $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000 -10.4. Analyzing design hierarchy.. +12.4. Analyzing design hierarchy.. Top module: \fifo Used module: $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000 Removing unused module `\addr_gen'. @@ -192,16 +200,16 @@ Removed 1 unused modules. yosys> proc -11. Executing PROC pass (convert processes to netlists). +13. Executing PROC pass (convert processes to netlists). yosys> proc_clean -11.1. Executing PROC_CLEAN pass (remove empty switches from decision trees). +13.1. Executing PROC_CLEAN pass (remove empty switches from decision trees). Cleaned up 0 empty switches. yosys> proc_rmdead -11.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees). +13.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees). Marked 2 switch rules as full_case in process $proc$fifo.v:64$24 in module fifo. Marked 1 switch rules as full_case in process $proc$fifo.v:38$16 in module fifo. Marked 2 switch rules as full_case in process $proc$fifo.v:13$32 in module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000. @@ -209,13 +217,13 @@ Removed a total of 0 dead cases. yosys> proc_prune -11.3. Executing PROC_PRUNE pass (remove redundant assignments in processes). +13.3. Executing PROC_PRUNE pass (remove redundant assignments in processes). Removed 0 redundant assignments. Promoted 6 assignments to connections. yosys> proc_init -11.4. Executing PROC_INIT pass (extract init attributes). +13.4. Executing PROC_INIT pass (extract init attributes). Found init rule in `\fifo.$proc$fifo.v:0$31'. Set init value: \count = 9'000000000 Found init rule in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'. @@ -223,19 +231,19 @@ Found init rule in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000 yosys> proc_arst -11.5. Executing PROC_ARST pass (detect async resets in processes). +13.5. Executing PROC_ARST pass (detect async resets in processes). Found async reset \rst in `\fifo.$proc$fifo.v:64$24'. Found async reset \rst in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:13$32'. yosys> proc_rom -11.6. Executing PROC_ROM pass (convert switches to ROMs). +13.6. Executing PROC_ROM pass (convert switches to ROMs). Converted 0 switches. yosys> proc_mux -11.7. Executing PROC_MUX pass (convert decision trees to multiplexers). +13.7. Executing PROC_MUX pass (convert decision trees to multiplexers). Creating decoders for process `\fifo.$proc$fifo.v:0$31'. Creating decoders for process `\fifo.$proc$fifo.v:64$24'. 1/1: $0\count[8:0] @@ -249,11 +257,11 @@ Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'000000000000000000 yosys> proc_dlatch -11.8. Executing PROC_DLATCH pass (convert process syncs to latches). +13.8. Executing PROC_DLATCH pass (convert process syncs to latches). yosys> proc_dff -11.9. Executing PROC_DFF pass (convert process syncs to FFs). +13.9. Executing PROC_DFF pass (convert process syncs to FFs). Creating register for signal `\fifo.\count' using process `\fifo.$proc$fifo.v:64$24'. created $adff cell `$procdff$55' with positive edge clock and positive level reset. Creating register for signal `\fifo.\rdata' using process `\fifo.$proc$fifo.v:38$16'. @@ -269,11 +277,11 @@ Creating register for signal `$paramod\addr_gen\MAX_DATA=s32'0000000000000000000 yosys> proc_memwr -11.10. Executing PROC_MEMWR pass (convert process memory writes to cells). +13.10. Executing PROC_MEMWR pass (convert process memory writes to cells). yosys> proc_clean -11.11. Executing PROC_CLEAN pass (remove empty switches from decision trees). +13.11. Executing PROC_CLEAN pass (remove empty switches from decision trees). Removing empty process `fifo.$proc$fifo.v:0$31'. Found and cleaned up 2 empty switches in `\fifo.$proc$fifo.v:64$24'. Removing empty process `fifo.$proc$fifo.v:64$24'. @@ -286,7 +294,7 @@ Cleaned up 5 empty switches. yosys> opt_expr -keepdc -11.12. Executing OPT_EXPR pass (perform const folding). +13.12. Executing OPT_EXPR pass (perform const folding). Optimizing module fifo. Optimizing module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000. @@ -294,13 +302,13 @@ yosys> select -set new_cells t:$memrd yosys> show -color maroon3 c:fifo_reader -color cornflowerblue @new_cells -notitle -format dot -prefix rdata_proc o:rdata %ci* -12. Generating Graphviz representation of design. +14. Generating Graphviz representation of design. Writing dot description to `rdata_proc.dot'. Dumping selected parts of module fifo to page 1. yosys> flatten -13. Executing FLATTEN pass (flatten design). +15. Executing FLATTEN pass (flatten design). Deleting now unused module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000. @@ -313,13 +321,13 @@ yosys> select -set new_cells @rdata_path o:rdata %ci3 %d i:* %d yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_flat @rdata_path -14. Generating Graphviz representation of design. +16. Generating Graphviz representation of design. Writing dot description to `rdata_flat.dot'. Dumping selected parts of module fifo to page 1. yosys> opt_dff -15. Executing OPT_DFF pass (perform DFF optimizations). +17. Executing OPT_DFF pass (perform DFF optimizations). Adding EN signal on $procdff$55 ($adff) from module fifo (D = $0\count[8:0], Q = \count). Adding EN signal on $flatten\fifo_writer.$procdff$60 ($adff) from module fifo (D = $flatten\fifo_writer.$procmux$51_Y, Q = \fifo_writer.addr). Adding EN signal on $flatten\fifo_reader.$procdff$60 ($adff) from module fifo (D = $flatten\fifo_reader.$procmux$51_Y, Q = \fifo_reader.addr). @@ -328,13 +336,13 @@ yosys> select -set new_cells t:$adffe yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_adffe o:rdata %ci* -16. Generating Graphviz representation of design. +18. Generating Graphviz representation of design. Writing dot description to `rdata_adffe.dot'. Dumping selected parts of module fifo to page 1. yosys> wreduce -17. Executing WREDUCE pass (reducing word size of cells). +19. Executing WREDUCE pass (reducing word size of cells). Removed top 31 bits (of 32) from port B of cell fifo.$add$fifo.v:68$27 ($add). Removed top 23 bits (of 32) from port Y of cell fifo.$add$fifo.v:68$27 ($add). Removed top 31 bits (of 32) from port B of cell fifo.$sub$fifo.v:70$30 ($sub). @@ -353,20 +361,20 @@ yosys> select -set new_cells t:$add %co t:$add %d yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_wreduce o:rdata %ci* -18. Generating Graphviz representation of design. +20. Generating Graphviz representation of design. Writing dot description to `rdata_wreduce.dot'. Dumping selected parts of module fifo to page 1. yosys> opt_clean -19. Executing OPT_CLEAN pass (remove unused cells and wires). +21. Executing OPT_CLEAN pass (remove unused cells and wires). Finding unused cells or wires in module \fifo.. Removed 0 unused cells and 4 unused wires. yosys> memory_dff -20. Executing MEMORY_DFF pass (merging $dff cells to $memrd). +22. Executing MEMORY_DFF pass (merging $dff cells to $memrd). Checking read port `\data'[0] in module `\fifo': merging output FF to cell. Write port 0: non-transparent. @@ -374,13 +382,13 @@ yosys> select -set new_cells t:$memrd_v2 yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_memrdv2 o:rdata %ci* -21. Generating Graphviz representation of design. +23. Generating Graphviz representation of design. Writing dot description to `rdata_memrdv2.dot'. Dumping selected parts of module fifo to page 1. yosys> alumacc -22. Executing ALUMACC pass (create $alu and $macc cells). +24. Executing ALUMACC pass (create $alu and $macc cells). Extracting $alu and $macc cells in module fifo: creating $macc model for $add$fifo.v:68$27 ($add). creating $macc model for $flatten\fifo_reader.$add$fifo.v:20$34 ($add). @@ -400,13 +408,13 @@ yosys> select -set new_cells t:$alu t:$macc yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_alumacc o:rdata %ci* -23. Generating Graphviz representation of design. +25. Generating Graphviz representation of design. Writing dot description to `rdata_alumacc.dot'. Dumping selected parts of module fifo to page 1. yosys> memory_collect -24. Executing MEMORY_COLLECT pass (generating $mem cells). +26. Executing MEMORY_COLLECT pass (generating $mem cells). yosys> select -set new_cells t:$mem_v2 @@ -414,6 +422,6 @@ yosys> select -set rdata_path @new_cells %ci*:-$mem_v2[WR_DATA,WR_ADDR,WR_EN] @n yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_coarse @rdata_path -25. Generating Graphviz representation of design. +27. Generating Graphviz representation of design. Writing dot description to `rdata_coarse.dot'. Dumping selected parts of module fifo to page 1. diff --git a/docs/source/code_examples/fifo/fifo.ys b/docs/source/code_examples/fifo/fifo.ys index 0584285ea..b6e0e34ed 100644 --- a/docs/source/code_examples/fifo/fifo.ys +++ b/docs/source/code_examples/fifo/fifo.ys @@ -15,6 +15,8 @@ select t:* select -list select -set new_cells % select -clear +show -format dot -prefix addr_gen_show addr_gen +show -format dot -prefix new_cells_show -notitle @new_cells 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 811c39a28..db7511c76 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -247,7 +247,8 @@ 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` command only works with a single module, so you may need to call it with -:yoscrypt:`show fifo`. +:yoscrypt:`show fifo`. :ref:`show_intro` section in +:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`. .. figure:: /_images/code_examples/fifo/rdata_proc.* :class: width-helper diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index d4d809fbd..6e75a3bcc 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -43,6 +43,8 @@ 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. +.. _select_intro: + Selections intro ^^^^^^^^^^^^^^^^ @@ -70,16 +72,19 @@ cells, regardless of their type. The active selection is now shown as gives us the ``$add`` and ``$eq`` cells, which we want to highlight for the :ref:`addr_gen_hier` image. +.. _select_new_cells: + 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. +selection, indicated by the ``%`` symbol. We can then use this named selection +by referring to it as ``@new_cells``, which we will see later. 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 @@ -90,53 +95,100 @@ 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`. +.. _show_intro: + The show command ~~~~~~~~~~~~~~~~ -.. TODO:: scripting_intro/show section +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` +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. -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 -different stages of the yosys tool flow. +.. figure:: /_images/code_examples/fifo/addr_gen_show.* + :class: width-helper + :name: addr_gen_show + Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy` + +.. note:: + + The :cmd:ref:`show` command requires a working installation of `GraphViz`_ + and `xdot`_ for displaying the actual circuit diagrams. + .. _GraphViz: http://www.graphviz.org/ - .. _xdot: https://github.com/jrfonseca/xdot.py -.. literalinclude:: /code_examples/show/example.ys - :language: yoscrypt - :caption: docs/source/code_examples/show/example.ys +This is the first :yoscrypt:`show` command we called in ``fifo.ys``, :ref:`as we +saw above `. If we look at the log output for this image we see the +following: -.. literalinclude:: /code_examples/show/example.v - :language: Verilog - :caption: docs/source/code_examples/show/example.v +.. literalinclude:: /code_examples/fifo/fifo.out + :language: doscon + :start-at: -prefix addr_gen_show + :end-before: yosys> show -.. role:: yoscrypt(code) - :language: yoscrypt +Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output +a ``.dot`` file rather than opening it for display. The :yoscrypt:`-prefix +addr_gen_show` option indicates we want the file to be called `addr_gen_show.*`. +Remember, we do this in ``fifo.ys`` because we need to store the image for +displaying in the documentation you're reading. But if you just want to display +the images locally you can skip these two options. The ``-format`` option +internally calls the ``dot`` command line program from GraphViz to convert to +formats other than ``.dot``. Check `GraphViz output docs`_ for more on +available formats. -.. figure:: /_images/code_examples/show/example_first.* +.. _GraphViz output docs: https://graphviz.org/docs/outputs/ + +.. note:: + + If you are using a POSIX based version of Yosys (such as for Mac or Linux), + xdot will be opened in the background and Yosys can continue to be used. If + it it still open, future calls to :yoscrypt:`show` will use the same xdot + instance. + +The ``addr_gen`` at the end tells it we only want the ``addr_gen`` module, just +like when we called :yoscrypt:`select -module addr_gen` in :ref:`select_intro`. +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` 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: + +.. figure:: /_images/code_examples/fifo/new_cells_show.* :class: width-helper - - ``example_first`` - shown after :yoscrypt:`read_verilog example.v` + :name: new_cells_show -.. figure:: /_images/code_examples/show/example_second.* + Calling :yoscrypt:`show -notitle @new_cells` + +We could have gotten the same output with :yoscrypt:`show -notitle t:$add t:$eq` +if we didn't have the named selection. By adding the :yoscrypt:`-notitle` flag +there we can also get rid of the ``addr_gen`` title that would have been +automatically added. The last two images were both added for this introduction. +The next image is the first one we saw in :doc:`/getting_started/example_synth`: +showing the full ``addr_gen`` module while also highlighting ``@new_cells`` and +the two ``PROC`` blocks. To achieve this highlight, we make use of the +:yoscrypt:`-color` option: + +.. figure:: /_images/code_examples/fifo/addr_gen_hier.* :class: width-helper - - ``example_second`` - shown after :yoscrypt:`proc` -.. figure:: /_images/code_examples/show/example_third.* - :class: width-helper - - ``example_third`` - shown after :yoscrypt:`opt` + Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle` -A circuit diagram is generated for the design in its current state. Various -options can be used to change the appearance of the circuit diagram, set the -name and format for the output file, and so forth. When called without any -special options, it saves the circuit diagram in a temporary file and launches -``xdot`` to display the diagram. Subsequent calls to show re-use the ``xdot`` -instance (if still running). +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 + `. Color names for the ```` portion can be found on the +`GraphViz color docs`_. Unlike the final :cmd:ref:`show` parameter which can +have be any selection string, the ```` 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]`` +as its final parameter it can be any selection string. Any selections that are +not the final parameter, such as those used in options, must be a single +expression instead. -For more information on the :cmd:ref:`show` command, including a guide on what -the different symbols represent, see :ref:`interactive_show` and the -:doc:`/using_yosys/more_scripting/interactive_investigation` page. +.. _GraphViz color docs: https://graphviz.org/doc/info/colors + +.. seealso:: :ref:`interactive_show` on the + :doc:`/using_yosys/more_scripting/interactive_investigation` page.