Merge pull request #4635 from YosysHQ/krys/pr_docs_ci

Remove make docs race conditions (and other docs fixes)

.github/workflows/prepare-docs.yml

@@ -1,12 +1,32 @@
 name: Build docs artifact with Verific
 
-on: push
+on: [push, pull_request]
 
 jobs:
+  check_docs_rebuild:
+    runs-on: ubuntu-latest
+    outputs:
+      skip_check: ${{ steps.skip_check.outputs.should_skip }}
+      docs_export: ${{ steps.docs_var.outputs.docs_export }}
+    env:
+      docs_export: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          paths_ignore: '["**/README.md"]'
+          # don't cancel in case we're updating docs
+          cancel_others: 'false'
+          # only run on push *or* pull_request, not both
+          concurrent_skipping: ${{ env.docs_export && 'never' || 'same_content_newer'}}
+      - id: docs_var
+        run: echo "docs_export=${{ env.docs_export }}" >> $GITHUB_OUTPUT
+
   prepare-docs:
     # docs builds are needed for anything on main, any tagged versions, and any tag
     # or branch starting with docs-preview
-    if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }}
+    needs: check_docs_rebuild
+    if: ${{ needs.check_docs_rebuild.outputs.should_skip != 'true' }}
     runs-on: [self-hosted, linux, x64, fast]
     steps:
       - name: Checkout Yosys
@@ -44,7 +64,13 @@ jobs:
             docs/source/_images
             docs/source/code_examples
 
+      - name: Test build docs
+        shell: bash
+        run: |
+          make -C docs html -j${{ env.procs }} TARGETS= EXTRA_TARGETS=
+
       - name: Trigger RTDs build
+        if: ${{ needs.check_docs_rebuild.outputs.docs_export == 'true' }}
         uses: dfm/rtds-action@v1.1.0
         with:
           webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}

backends/functional/cxx.cc

@@ -246,6 +246,8 @@ struct FunctionalCxxBackend : public Backend
 	{
 		//   |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|
 		log("\n");
+		log("TODO: add help message\n");
+		log("\n");
     }
 
 	void printCxx(std::ostream &stream, std::string, Module *module)

backends/functional/test_generic.cc

@@ -122,6 +122,8 @@ struct FunctionalTestGeneric : public Pass
 	{
 		//   |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|
 		log("\n");
+		log("TODO: add help message\n");
+		log("\n");
     }
 
 	void execute(std::vector<std::string> args, RTLIL::Design *design) override

docs/Makefile

@@ -238,7 +238,7 @@ Makefile-%: FORCE
 	$(MAKE) -C $(@D) $(*F)
 
 CODE_EXAMPLES := $(wildcard source/code_examples/*/Makefile)
-TEST_EXAMPLES := $(addsuffix -all,$(CODE_EXAMPLES))
+TEST_EXAMPLES := $(addsuffix -examples,$(CODE_EXAMPLES))
 CLEAN_EXAMPLES := $(addsuffix -clean,$(CODE_EXAMPLES))
 test-examples: $(TEST_EXAMPLES)
 clean-examples: $(CLEAN_EXAMPLES)

docs/source/code_examples/.gitignore

@@ -1,2 +1,5 @@
 *.dot
 *.pdf
+*.out
+*.log
+*.stat

docs/source/code_examples/extensions/Makefile

@@ -2,9 +2,10 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots test0.log test1.log test2.log
+all: dots examples
 dots: test1.dot
+examples: test0.log test1.log test2.log
 
 CXXFLAGS=$(shell $(YOSYS)-config --cxxflags)
 DATDIR=$(shell $(YOSYS)-config --datdir)

docs/source/code_examples/fifo/Makefile

@@ -10,8 +10,10 @@ MAPDOT_NAMES += rdata_map_ffs rdata_map_luts rdata_map_cells
 DOTS := $(addsuffix .dot,$(DOT_NAMES))
 MAPDOTS := $(addsuffix .dot,$(MAPDOT_NAMES))
 
-all: dots fifo.out fifo.stat
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS) $(MAPDOTS)
+examples: fifo.out fifo.stat
 
 $(DOTS) fifo.out: fifo.v fifo.ys
 	$(YOSYS) fifo.ys -l fifo.out -Q -T
@@ -22,3 +24,4 @@ $(MAPDOTS) fifo.stat: fifo.v fifo_map.ys
 .PHONY: clean
 clean:
 	rm -f *.dot
+	rm -f fifo.out fifo.stat

docs/source/code_examples/fifo/fifo.out

@@ -1,425 +0,0 @@
-
--- Executing script file `fifo.ys' --
-$ yosys fifo.v
-
--- Parsing `fifo.v' using frontend ` -vlog2k' --
-
-1. Executing Verilog-2005 frontend: fifo.v
-Parsing Verilog input from `fifo.v' to AST representation.
-Storing AST representation for module `$abstract\addr_gen'.
-Storing AST representation for module `$abstract\fifo'.
-Successfully finished Verilog frontend.
-echo on
-
-yosys> hierarchy -top addr_gen
-
-2. Executing HIERARCHY pass (managing design hierarchy).
-
-3. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'.
-Generating RTLIL representation for module `\addr_gen'.
-
-3.1. Analyzing design hierarchy..
-Top module:  \addr_gen
-
-3.2. Analyzing design hierarchy..
-Top module:  \addr_gen
-Removing unused module `$abstract\fifo'.
-Removing unused module `$abstract\addr_gen'.
-Removed 2 unused modules.
-
-yosys> select -module addr_gen
-
-yosys [addr_gen]> select -list
-addr_gen
-addr_gen/$1\addr[7:0]
-addr_gen/$add$fifo.v:19$3_Y
-addr_gen/$eq$fifo.v:16$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:19$3
-addr_gen/$eq$fifo.v:16$2
-addr_gen/$proc$fifo.v:0$4
-addr_gen/$proc$fifo.v:12$1
-
-yosys [addr_gen]> select t:*
-
-yosys [addr_gen]*> select -list
-addr_gen/$add$fifo.v:19$3
-addr_gen/$eq$fifo.v:16$2
-
-yosys [addr_gen]*> select -set new_cells %
-
-yosys [addr_gen]*> select -clear
-
-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
-
-6. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_hier.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> proc -noopt
-
-7. Executing PROC pass (convert processes to netlists).
-
-yosys> proc_clean
-
-7.1. Executing PROC_CLEAN pass (remove empty switches from decision trees).
-Cleaned up 0 empty switches.
-
-yosys> proc_rmdead
-
-7.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees).
-Marked 2 switch rules as full_case in process $proc$fifo.v:12$1 in module addr_gen.
-Removed a total of 0 dead cases.
-
-yosys> proc_prune
-
-7.3. Executing PROC_PRUNE pass (remove redundant assignments in processes).
-Removed 0 redundant assignments.
-Promoted 1 assignment to connection.
-
-yosys> proc_init
-
-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
-
-7.5. Executing PROC_ARST pass (detect async resets in processes).
-Found async reset \rst in `\addr_gen.$proc$fifo.v:12$1'.
-
-yosys> proc_rom
-
-7.6. Executing PROC_ROM pass (convert switches to ROMs).
-Converted 0 switches.
-<suppressed ~2 debug messages>
-
-yosys> proc_mux
-
-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:12$1'.
-     1/1: $0\addr[7:0]
-
-yosys> proc_dlatch
-
-7.8. Executing PROC_DLATCH pass (convert process syncs to latches).
-
-yosys> proc_dff
-
-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:12$1'.
-  created $adff cell `$procdff$10' with positive edge clock and positive level reset.
-
-yosys> proc_memwr
-
-7.10. Executing PROC_MEMWR pass (convert process memory writes to cells).
-
-yosys> proc_clean
-
-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:12$1'.
-Removing empty process `addr_gen.$proc$fifo.v:12$1'.
-Cleaned up 2 empty switches.
-
-yosys> select -set new_cells t:$mux t:*dff
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix addr_gen_proc
-
-8. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_proc.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> opt_expr
-
-9. Executing OPT_EXPR pass (perform const folding).
-Optimizing module addr_gen.
-
-yosys> clean
-Removed 0 unused cells and 4 unused wires.
-
-yosys> select -set new_cells t:$eq
-
-yosys> show -color cornflowerblue @new_cells -notitle -format dot -prefix addr_gen_clean
-
-10. Generating Graphviz representation of design.
-Writing dot description to `addr_gen_clean.dot'.
-Dumping module addr_gen to page 1.
-
-yosys> design -reset
-
-yosys> read_verilog 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'.
-Successfully finished Verilog frontend.
-
-yosys> hierarchy -check -top fifo
-
-12. Executing HIERARCHY pass (managing design hierarchy).
-
-12.1. Analyzing design hierarchy..
-Top module:  \fifo
-Used module:     \addr_gen
-Parameter \MAX_DATA = 256
-
-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'.
-
-12.3. Analyzing design hierarchy..
-Top module:  \fifo
-Used module:     $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000
-
-12.4. Analyzing design hierarchy..
-Top module:  \fifo
-Used module:     $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000
-Removing unused module `\addr_gen'.
-Removed 1 unused modules.
-
-yosys> proc
-
-13. Executing PROC pass (convert processes to netlists).
-
-yosys> proc_clean
-
-13.1. Executing PROC_CLEAN pass (remove empty switches from decision trees).
-Cleaned up 0 empty switches.
-
-yosys> proc_rmdead
-
-13.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees).
-Marked 2 switch rules as full_case in process $proc$fifo.v:62$24 in module fifo.
-Marked 1 switch rules as full_case in process $proc$fifo.v:36$16 in module fifo.
-Marked 2 switch rules as full_case in process $proc$fifo.v:12$32 in module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.
-Removed a total of 0 dead cases.
-
-yosys> proc_prune
-
-13.3. Executing PROC_PRUNE pass (remove redundant assignments in processes).
-Removed 0 redundant assignments.
-Promoted 6 assignments to connections.
-
-yosys> proc_init
-
-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'.
-  Set init value: \addr = 8'00000000
-
-yosys> proc_arst
-
-13.5. Executing PROC_ARST pass (detect async resets in processes).
-Found async reset \rst in `\fifo.$proc$fifo.v:62$24'.
-Found async reset \rst in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-
-yosys> proc_rom
-
-13.6. Executing PROC_ROM pass (convert switches to ROMs).
-Converted 0 switches.
-<suppressed ~5 debug messages>
-
-yosys> proc_mux
-
-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:62$24'.
-     1/1: $0\count[8:0]
-Creating decoders for process `\fifo.$proc$fifo.v:36$16'.
-     1/3: $1$memwr$\data$fifo.v:38$15_EN[7:0]$22
-     2/3: $1$memwr$\data$fifo.v:38$15_DATA[7:0]$21
-     3/3: $1$memwr$\data$fifo.v:38$15_ADDR[7:0]$20
-Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'.
-Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-     1/1: $0\addr[7:0]
-
-yosys> proc_dlatch
-
-13.8. Executing PROC_DLATCH pass (convert process syncs to latches).
-
-yosys> proc_dff
-
-13.9. Executing PROC_DFF pass (convert process syncs to FFs).
-Creating register for signal `\fifo.\count' using process `\fifo.$proc$fifo.v:62$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:36$16'.
-  created $dff cell `$procdff$56' with positive edge clock.
-Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_ADDR' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$57' with positive edge clock.
-Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_DATA' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$58' with positive edge clock.
-Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_EN' using process `\fifo.$proc$fifo.v:36$16'.
-  created $dff cell `$procdff$59' with positive edge clock.
-Creating register for signal `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.\addr' using process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-  created $adff cell `$procdff$60' with positive edge clock and positive level reset.
-
-yosys> proc_memwr
-
-13.10. Executing PROC_MEMWR pass (convert process memory writes to cells).
-
-yosys> proc_clean
-
-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:62$24'.
-Removing empty process `fifo.$proc$fifo.v:62$24'.
-Found and cleaned up 1 empty switch in `\fifo.$proc$fifo.v:36$16'.
-Removing empty process `fifo.$proc$fifo.v:36$16'.
-Removing empty process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'.
-Found and cleaned up 2 empty switches in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-Removing empty process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'.
-Cleaned up 5 empty switches.
-
-yosys> opt_expr -keepdc
-
-13.12. Executing OPT_EXPR pass (perform const folding).
-Optimizing module fifo.
-Optimizing module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.
-
-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*
-
-14. Generating Graphviz representation of design.
-Writing dot description to `rdata_proc.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> flatten
-
-15. Executing FLATTEN pass (flatten design).
-Deleting now unused module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.
-<suppressed ~2 debug messages>
-
-yosys> clean
-Removed 3 unused cells and 25 unused wires.
-
-yosys> select -set rdata_path o:rdata %ci*
-
-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
-
-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
-
-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).
-
-yosys> select -set new_cells t:$adffe
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_adffe o:rdata %ci*
-
-18. Generating Graphviz representation of design.
-Writing dot description to `rdata_adffe.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> wreduce
-
-19. Executing WREDUCE pass (reducing word size of cells).
-Removed top 31 bits (of 32) from port B of cell fifo.$add$fifo.v:66$27 ($add).
-Removed top 23 bits (of 32) from port Y of cell fifo.$add$fifo.v:66$27 ($add).
-Removed top 31 bits (of 32) from port B of cell fifo.$sub$fifo.v:68$30 ($sub).
-Removed top 23 bits (of 32) from port Y of cell fifo.$sub$fifo.v:68$30 ($sub).
-Removed top 1 bits (of 2) from port B of cell fifo.$auto$opt_dff.cc:195:make_patterns_logic$66 ($ne).
-Removed cell fifo.$flatten\fifo_writer.$procmux$53 ($mux).
-Removed top 31 bits (of 32) from port B of cell fifo.$flatten\fifo_writer.$add$fifo.v:19$34 ($add).
-Removed top 24 bits (of 32) from port Y of cell fifo.$flatten\fifo_writer.$add$fifo.v:19$34 ($add).
-Removed cell fifo.$flatten\fifo_reader.$procmux$53 ($mux).
-Removed top 31 bits (of 32) from port B of cell fifo.$flatten\fifo_reader.$add$fifo.v:19$34 ($add).
-Removed top 24 bits (of 32) from port Y of cell fifo.$flatten\fifo_reader.$add$fifo.v:19$34 ($add).
-Removed top 23 bits (of 32) from wire fifo.$add$fifo.v:66$27_Y.
-Removed top 24 bits (of 32) from wire fifo.$flatten\fifo_reader.$add$fifo.v:19$34_Y.
-
-yosys> show -notitle -format dot -prefix rdata_wreduce o:rdata %ci*
-
-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
-
-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.
-<suppressed ~1 debug messages>
-
-yosys> memory_dff
-
-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.
-
-yosys> select -set new_cells t:$memrd_v2
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_memrdv2 o:rdata %ci*
-
-23. Generating Graphviz representation of design.
-Writing dot description to `rdata_memrdv2.dot'.
-Dumping selected parts of module fifo to page 1.
-
-yosys> alumacc
-
-24. Executing ALUMACC pass (create $alu and $macc cells).
-Extracting $alu and $macc cells in module fifo:
-  creating $macc model for $add$fifo.v:66$27 ($add).
-  creating $macc model for $flatten\fifo_reader.$add$fifo.v:19$34 ($add).
-  creating $macc model for $flatten\fifo_writer.$add$fifo.v:19$34 ($add).
-  creating $macc model for $sub$fifo.v:68$30 ($sub).
-  creating $alu model for $macc $sub$fifo.v:68$30.
-  creating $alu model for $macc $flatten\fifo_writer.$add$fifo.v:19$34.
-  creating $alu model for $macc $flatten\fifo_reader.$add$fifo.v:19$34.
-  creating $alu model for $macc $add$fifo.v:66$27.
-  creating $alu cell for $add$fifo.v:66$27: $auto$alumacc.cc:485:replace_alu$80
-  creating $alu cell for $flatten\fifo_reader.$add$fifo.v:19$34: $auto$alumacc.cc:485:replace_alu$83
-  creating $alu cell for $flatten\fifo_writer.$add$fifo.v:19$34: $auto$alumacc.cc:485:replace_alu$86
-  creating $alu cell for $sub$fifo.v:68$30: $auto$alumacc.cc:485:replace_alu$89
-  created 4 $alu and 0 $macc cells.
-
-yosys> select -set new_cells t:$alu t:$macc
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_alumacc o:rdata %ci*
-
-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
-
-26. Executing MEMORY_COLLECT pass (generating $mem cells).
-
-yosys> select -set new_cells t:$mem_v2
-
-yosys> select -set rdata_path @new_cells %ci*:-$mem_v2[WR_DATA,WR_ADDR,WR_EN] @new_cells %co* %%
-
-yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_coarse @rdata_path
-
-27. Generating Graphviz representation of design.
-Writing dot description to `rdata_coarse.dot'.
-Dumping selected parts of module fifo to page 1.

docs/source/code_examples/fifo/fifo.stat

@@ -1,57 +0,0 @@
-
-yosys> stat
-
-2. Printing statistics.
-
-=== fifo ===
-
-   Number of wires:                 28
-   Number of wire bits:            219
-   Number of public wires:           9
-   Number of public wire bits:      45
-   Number of memories:               1
-   Number of memory bits:         2048
-   Number of processes:              3
-   Number of cells:                  9
-     $add                            1
-     $logic_and                      2
-     $logic_not                      2
-     $memrd                          1
-     $sub                            1
-     addr_gen                        2
-
-=== addr_gen ===
-
-   Number of wires:                  8
-   Number of wire bits:             60
-   Number of public wires:           4
-   Number of public wire bits:      11
-   Number of memories:               0
-   Number of memory bits:            0
-   Number of processes:              2
-   Number of cells:                  2
-     $add                            1
-     $eq                             1
-
-
-yosys> stat -top fifo
-
-17. Printing statistics.
-
-=== fifo ===
-
-   Number of wires:                 94
-   Number of wire bits:            260
-   Number of public wires:          94
-   Number of public wire bits:     260
-   Number of memories:               0
-   Number of memory bits:            0
-   Number of processes:              0
-   Number of cells:                138
-     $scopeinfo                      2
-     SB_CARRY                       26
-     SB_DFF                         26
-     SB_DFFER                       25
-     SB_LUT4                        58
-     SB_RAM40_4K                     1
-

docs/source/code_examples/intro/Makefile

@@ -4,8 +4,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = counter_00.dot counter_01.dot counter_02.dot counter_03.dot
 
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
 $(DOTS): counter.v counter.ys mycells.lib
 	$(YOSYS) counter.ys

docs/source/code_examples/macc/Makefile

@@ -4,8 +4,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = macc_simple_xmap.dot macc_xilinx_xmap.dot
 
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
 macc_simple_xmap.dot: macc_simple_*.v macc_simple_test.ys
 	$(YOSYS) macc_simple_test.ys

docs/source/code_examples/opt/Makefile

@@ -6,13 +6,13 @@ DOT_NAMES = opt_share opt_muxtree opt_merge opt_expr
 
 DOTS := $(addsuffix .dot,$(DOT_NAMES))
 
-all: dots
+.PHONY: all dots examples
+all: dots examples
 dots: $(DOTS)
+examples:
 
-%_full.dot: %.ys
+%.dot: %.ys
 	$(YOSYS) $<
-
-%.dot: %_full.dot
 	gvpack -u -o $@ $*_full.dot
 
 .PHONY: clean

docs/source/code_examples/scrambler/Makefile

@@ -2,9 +2,10 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots
+all: dots examples
 dots: scrambler_p01.dot scrambler_p02.dot
+examples:
 
 scrambler_p01.dot scrambler_p02.dot: scrambler.ys scrambler.v
 	$(YOSYS) scrambler.ys

docs/source/code_examples/selections/Makefile

@@ -11,14 +11,15 @@ MEMDEMO_DOTS := $(addsuffix .dot,$(MEMDEMO))
 SUBMOD = submod_00 submod_01 submod_02 submod_03
 SUBMOD_DOTS := $(addsuffix .dot,$(SUBMOD))
 
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots
+all: dots examples
 dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS)
+examples: sumprod.out
 
 select.dot: select.v select.ys
 	$(YOSYS) select.ys
 
-$(SUMPROD_DOTS): sumprod.v sumprod.ys
+$(SUMPROD_DOTS) sumprod.out: sumprod.v sumprod.ys
 	$(YOSYS) sumprod.ys
 
 $(MEMDEMO_DOTS): memdemo.v memdemo.ys
@@ -30,3 +31,4 @@ $(SUBMOD_DOTS): memdemo.v submod.ys
 .PHONY: clean
 clean:
 	rm -rf *.dot
+	rm -f sumprod.out

docs/source/code_examples/selections/sumprod.out

@@ -1,38 +0,0 @@
-
-
-  attribute \src "sumprod.v:4.21-4.25"
-  wire width 8 output 5 \prod
-
-  attribute \src "sumprod.v:10.17-10.26"
-  cell $mul $mul$sumprod.v:10$4
-    parameter \A_SIGNED 0
-    parameter \A_WIDTH 8
-    parameter \B_SIGNED 0
-    parameter \B_WIDTH 8
-    parameter \Y_WIDTH 8
-    connect \A $mul$sumprod.v:10$3_Y
-    connect \B \c
-    connect \Y \prod
-  end
-
-
-  attribute \src "sumprod.v:10.17-10.22"
-  wire width 8 $mul$sumprod.v:10$3_Y
-
-  attribute \src "sumprod.v:3.21-3.22"
-  wire width 8 input 3 \c
-
-  attribute \src "sumprod.v:4.21-4.25"
-  wire width 8 output 5 \prod
-
-  attribute \src "sumprod.v:10.17-10.26"
-  cell $mul $mul$sumprod.v:10$4
-    parameter \A_SIGNED 0
-    parameter \A_WIDTH 8
-    parameter \B_SIGNED 0
-    parameter \B_WIDTH 8
-    parameter \Y_WIDTH 8
-    connect \A $mul$sumprod.v:10$3_Y
-    connect \B \c
-    connect \Y \prod
-  end

docs/source/code_examples/show/Makefile

@@ -8,9 +8,10 @@ EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE))
 CMOS = cmos_00 cmos_01
 CMOS_DOTS := $(addsuffix .dot,$(CMOS))
 
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots example.out
+all: dots examples
 dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
+examples: example.out
 
 splice.dot: splice.v
 	$(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v
@@ -27,3 +28,4 @@ $(CMOS_DOTS): cmos.v cmos.ys
 .PHONY: clean
 clean:
 	rm -rf *.dot
+	rm -f example.out

docs/source/code_examples/show/example.out

@@ -1,54 +0,0 @@
-
--- Executing script file `example_lscd.ys' --
-
-1. Executing Verilog-2005 frontend: example.v
-Parsing Verilog input from `example.v' to AST representation.
-Generating RTLIL representation for module `\example'.
-Successfully finished Verilog frontend.
-echo on
-
-yosys> ls
-
-1 modules:
-  example
-
-yosys> cd example
-
-yosys [example]> ls
-
-8 wires:
-  $0\y[1:0]
-  $add$example.v:5$2_Y
-  $ternary$example.v:5$3_Y
-  a
-  b
-  c
-  clk
-  y
-
-2 cells:
-  $add$example.v:5$2
-  $ternary$example.v:5$3
-
-1 processes:
-  $proc$example.v:3$1
-
-yosys [example]> dump $2
-
-
-  attribute \src "example.v:5.22-5.27"
-  cell $add $add$example.v:5$2
-    parameter \Y_WIDTH 2
-    parameter \B_WIDTH 1
-    parameter \A_WIDTH 1
-    parameter \B_SIGNED 0
-    parameter \A_SIGNED 0
-    connect \Y $add$example.v:5$2_Y
-    connect \B \b
-    connect \A \a
-  end
-
-yosys [example]> cd ..
-
-yosys> echo off
-echo off

docs/source/code_examples/stubnets/Makefile

@@ -1,6 +1,7 @@
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots
+all: dots examples
 dots:
+examples:
 
 .PHONY: test
 test: stubnets.so

docs/source/code_examples/synth_flow/Makefile

@@ -9,9 +9,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = $(addsuffix .dot,$(DOT_TARGETS))
 
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots
+all: dots examples
 dots: $(DOTS)
+examples:
 
 %.dot: %.v %.ys
 	$(YOSYS) -p 'script $*.ys; show -notitle -prefix $* -format dot'

docs/source/code_examples/techmap/Makefile

@@ -2,9 +2,10 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-.PHONY: all dots
+.PHONY: all dots examples
-all: dots
+all: dots examples
 dots: red_or3x1.dot sym_mul.dot mymul.dot mulshift.dot addshift.dot
+examples:
 
 red_or3x1.dot: red_or3x1_*
 	$(YOSYS) red_or3x1_test.ys

docs/source/yosys_internals/extending_yosys/index.rst

@@ -10,5 +10,6 @@ of interest for developers looking to customise Yosys builds.
 
    extensions
    build_verific
+   functional_ir
    test_suites
 

passes/cmds/example_dt.cc

@@ -27,6 +27,8 @@ struct ExampleDtPass : public Pass
 	{
 		//   |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|
 		log("\n");
+		log("TODO: add help message\n");
+		log("\n");
     }