docs: restructuring images directory

see also previous commit
Also updates `scripting_intro.rst` to use literal includes, and uses individual image outputs to avoid the intermediary `.tex` file to join them all.

docs/.gitignore

@@ -1,12 +1,9 @@
 /build/
 /source/cmd
 /source/temp
-/source/_images/*.log
-/source/_images/*.aux
-/source/_images/*.pdf
-/source/_images/*.svg
 /source/_images/**/*.log
 /source/_images/**/*.aux
 /source/_images/**/*.pdf
 /source/_images/**/*.svg
 /source/_images/**/*.dot
+/source/_images/code_examples

docs/source/_images/Makefile

@@ -1,62 +1,46 @@
-all: resources dots tex svg tidy
+all: examples all_tex tidy
 
-RES_LIST:= PRESENTATION_Intro/ PRESENTATION_ExSyn/ PRESENTATION_ExAdv/ PRESENTATION_ExOth/
-RES_DIRS:= $(addprefix ../../resources/,$(RES_LIST))
-.PHONY: resources
-resources: $(RES_DIRS)
-FORCE:
-../../resources/%: FORCE
-	@$(MAKE) -C $@
-	@mkdir -p res/$*
-	@cp --update -t res/$* $@*.dot
-
-TEX_SOURCE:= $(wildcard *.tex)
-DOT_LOC:= ../APPNOTE_011_Design_Investigation
-DOT_SOURCE:= $(wildcard $(DOT_LOC)/*.dot)
-
-RES_DOTS:= $(wildcard res/*/*.dot)
-RES_DIRS:= $(sort $(dir $(RES_DOTS)))
-RES_PDF:= $(RES_DOTS:%.dot=%.pdf)
+# set a fake time in pdf generation to prevent unnecessary differences in output
+FAKETIME := TZ='Z' faketime -f '2022-01-01 00:00:00 x0,001'
 
-TEX_SOURCE+= 011/example_out.tex
-011/example_out.pdf: 011/example_00.pdf 011/example_01.pdf 011/example_02.pdf
-TEX_SOURCE+= 011/select_prod.tex
-011/select_prod.pdf: 011/sumprod_02.pdf 011/sumprod_03.pdf 011/sumprod_04.pdf 011/sumprod_05.pdf
-TEX_SOURCE+= 011/splitnets_libfile.tex
-011/splitnets_libfile.pdf: 011/cmos_00.pdf 011/cmos_01.pdf
-TEX_SOURCE+= 011/submod_dots.tex
-011/submod_dots.pdf: 011/submod_00.pdf 011/submod_01.pdf 011/submod_02.pdf 011/submod_03.pdf
+# find all code example makefiles
+.PHONY: examples
+CODE_EXAMPLES := ../code_examples/*/Makefile
+examples: $(CODE_EXAMPLES)
 
-TEX_PDF:= $(patsubst %.tex,%.pdf,$(TEX_SOURCE))
-DOT_PDF:= $(addprefix 011/,$(notdir $(patsubst %.dot,%.pdf,$(DOT_SOURCE))))
-SVG_OUTPUT:= $(patsubst %.pdf,%.svg,$(TEX_PDF) $(DOT_PDF) $(RES_PDF))
+# target to convert specified dot file(s)
+.PHONY: convert
+TARG_DOT ?=
+convert: $(TARG_DOT:.dot=.pdf) $(TARG_DOT:.dot=.svg)
 
-dots: $(DOT_PDF) $(RES_PDF)
-tex: $(TEX_PDF)
-svg: $(SVG_OUTPUT)
-
-011/%.pdf: $(DOT_LOC)/%.dot
-	TZ='Z' faketime -f '2022-01-01 00:00:00 x0,001' dot -Tpdf -o $@ $<
+# use empty FORCE target because .PHONY ignores % expansion, using find allows
+# us to generate everything in one pass, since we don't know all of the possible
+# outputs until the sub-makes run
+FORCE:
+../%/Makefile: FORCE
+	@make -C $(@D) dots
+	@mkdir -p $*
+	@find $(@D) -name *.dot -exec cp -u {} -t $* \;
+	@find $* -name *.dot -printf "%p " | xargs -i make --no-print-directory convert TARG_DOT="{}"
 
-res/%.pdf: res/%.dot
-	TZ='Z' faketime -f '2022-01-01 00:00:00 x0,001' dot -Tpdf -o $@ $<
+# find and build all tex files
+.PHONY: all_tex
+TEX_FILES := $(wildcard **/*.tex)
+all_tex: $(TEX_FILES:.tex=.pdf) $(TEX_FILES:.tex=.svg)
 
-011/%.pdf: 011/%.tex
-	cd 011 && TZ='Z' faketime -f '2022-01-01 00:00:00 x0,001' pdflatex $(<F) --interaction=nonstopmode
+%.pdf: %.dot
+	$(FAKETIME) dot -Tpdf -o $@ $<
 
 %.pdf: %.tex
-	pdflatex $< --interaction=nonstopmode
+	cd $(@D) && $(FAKETIME) pdflatex $(<F) --interaction=nonstopmode
 
 %.svg: %.pdf
 	pdf2svg $< $@
 
 .PHONY: clean tidy
 tidy:
-	rm -f *.log
-	rm -f *.aux
-	rm -f  011/*.log 011/*.aux
+	rm -f  **/*.log **/*.aux
+
 clean: tidy
-	rm -f *.pdf
-	rm -f *.svg
-	rm -f 011/*.pdf 011/*.svg
-	rm -rf $(RES_DIRS)
+	rm -rf code_examples
+	rm -f **/*.pdf **/*.svg

docs/source/appendix/primer.rst

@@ -23,7 +23,7 @@ circuit to a functionally equivalent low-level representation of a circuit.
 :numref:`Figure %s <fig:Basics_abstractions>` lists the different levels of
 abstraction and how they relate to different kinds of synthesis.
 
-.. figure:: /_images/basics_abstractions.*
+.. figure:: /_images/primer/basics_abstractions.*
 	:class: width-helper
 	:name: fig:Basics_abstractions
 
@@ -498,7 +498,7 @@ Then the synthesizable description is transformed to lower-level representations
 using a series of tools and the results are again verified using simulation.
 This process is illustrated in :numref:`Fig. %s <fig:Basics_flow>`.
 
-.. figure:: /_images/basics_flow.*
+.. figure:: /_images/primer/basics_flow.*
 	:class: width-helper
 	:name: fig:Basics_flow
 
@@ -597,7 +597,7 @@ Let's consider the following BNF (in Bison syntax):
    assign_stmt: TOK_ASSIGN TOK_IDENTIFIER TOK_EQ expr TOK_SEMICOLON;
    expr: TOK_IDENTIFIER | TOK_NUMBER | expr TOK_PLUS expr;
 
-.. figure:: /_images/basics_parsetree.*
+.. figure:: /_images/primer/basics_parsetree.*
 	:class: width-helper
 	:name: fig:Basics_parsetree
 
@@ -626,7 +626,7 @@ Usually the AST is then converted into yet another representation that is more
 suitable for further processing. In compilers this is often an assembler-like
 three-address-code intermediate representation. :cite:p:`Dragonbook`
 
-.. figure:: /_images/basics_ast.*
+.. figure:: /_images/primer/basics_ast.*
 	:class: width-helper
 	:name: fig:Basics_ast
 

docs/source/code_examples/intro/Makefile

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

docs/source/code_examples/macc/Makefile

@@ -1,12 +1,14 @@
 PROGRAM_PREFIX :=
 
-YOSYS ?= ../../../$(PROGRAM_PREFIX)yosys
+YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-all: macc_simple_xmap.pdf macc_xilinx_xmap.pdf
+DOTS = macc_simple_xmap.dot macc_xilinx_xmap.dot
 
-macc_simple_xmap.pdf: macc_simple_*.v macc_simple_test.ys
+dots: $(DOTS)
+
+macc_simple_xmap.dot: macc_simple_*.v macc_simple_test.ys
 	$(YOSYS) macc_simple_test.ys
 
-macc_xilinx_xmap.pdf: macc_xilinx_*.v macc_xilinx_test.ys
+macc_xilinx_xmap.dot: macc_xilinx_*.v macc_xilinx_test.ys
 	$(YOSYS) macc_xilinx_test.ys
 

docs/source/code_examples/macc/macc_xilinx_test.ys

@@ -3,21 +3,21 @@ read_verilog -lib -icells macc_xilinx_unwrap_map.v
 read_verilog -lib -icells macc_xilinx_xmap.v
 hierarchy -check ;;
 
-show -prefix macc_xilinx_test1a -format pdf -notitle test1
-show -prefix macc_xilinx_test2a -format pdf -notitle test2
+show -prefix macc_xilinx_test1a -format dot -notitle test1
+show -prefix macc_xilinx_test2a -format dot -notitle test2
 
 techmap -map macc_xilinx_swap_map.v;;
 
-show -prefix macc_xilinx_test1b -format pdf -notitle test1
-show -prefix macc_xilinx_test2b -format pdf -notitle test2
+show -prefix macc_xilinx_test1b -format dot -notitle test1
+show -prefix macc_xilinx_test2b -format dot -notitle test2
 
 techmap -map macc_xilinx_wrap_map.v
 
 connwrappers -unsigned $__mul_wrapper Y Y_WIDTH \
              -unsigned $__add_wrapper Y Y_WIDTH;;
 
-show -prefix macc_xilinx_test1c -format pdf -notitle test1
-show -prefix macc_xilinx_test2c -format pdf -notitle test2
+show -prefix macc_xilinx_test1c -format dot -notitle test1
+show -prefix macc_xilinx_test2c -format dot -notitle test2
 
 design -push
 read_verilog macc_xilinx_xmap.v
@@ -30,14 +30,14 @@ extract -constports -ignore_parameters \
         -map %__macc_xilinx_xmap       \
         -swap $__add_wrapper A,B ;;
 
-show -prefix macc_xilinx_test1d -format pdf -notitle test1
-show -prefix macc_xilinx_test2d -format pdf -notitle test2
+show -prefix macc_xilinx_test1d -format dot -notitle test1
+show -prefix macc_xilinx_test2d -format dot -notitle test2
 
 techmap -map macc_xilinx_unwrap_map.v;;
 
-show -prefix macc_xilinx_test1e -format pdf -notitle test1
-show -prefix macc_xilinx_test2e -format pdf -notitle test2
+show -prefix macc_xilinx_test1e -format dot -notitle test1
+show -prefix macc_xilinx_test2e -format dot -notitle test2
 
 design -load __macc_xilinx_xmap
-show -prefix macc_xilinx_xmap -format pdf -notitle
+show -prefix macc_xilinx_xmap -format dot -notitle
 

docs/source/code_examples/scrambler/Makefile

@@ -1,8 +1,8 @@
 PROGRAM_PREFIX :=
 
-YOSYS ?= ../../../$(PROGRAM_PREFIX)yosys
+YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-all: scrambler_p01.dot scrambler_p02.dot
+dots: scrambler_p01.dot scrambler_p02.dot
 
 scrambler_p01.dot scrambler_p02.dot: scrambler.ys scrambler.v
 	$(YOSYS) scrambler.ys

docs/source/code_examples/selections/Makefile

@@ -11,22 +11,22 @@ MEMDEMO_DOTS := $(addsuffix .dot,$(MEMDEMO))
 SUBMOD = submod_00 submod_01 submod_02 submod_03
 SUBMOD_DOTS := $(addsuffix .dot,$(SUBMOD))
 
-all: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS)
+dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS)
 
 select.dot: select.v select.ys
 	$(YOSYS) select.ys
 
 $(SUMPROD_DOTS): sumprod.v
-	$(YOSYS) -p 'opt; cd sumprod; select a:sumstuff; show -format dot -prefix sumprod_00' sumprod.v
-	$(YOSYS) -p 'opt; cd sumprod; select a:sumstuff %x; show -format dot -prefix sumprod_01' sumprod.v
-	$(YOSYS) -p 'opt; cd sumprod; select prod; show -format dot -prefix sumprod_02' sumprod.v
-	$(YOSYS) -p 'opt; cd sumprod; select prod %ci; show -format dot -prefix sumprod_03' sumprod.v
-	$(YOSYS) -p 'opt; cd sumprod; select prod %ci2; show -format dot -prefix sumprod_04' sumprod.v
-	$(YOSYS) -p 'opt; cd sumprod; select prod %ci3; show -format dot -prefix sumprod_05' sumprod.v
+	$(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select a:sumstuff; show -format dot -prefix sumprod_00'
+	$(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select a:sumstuff %x; show -format dot -prefix sumprod_01'
+	$(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod; show -format dot -prefix sumprod_02'
+	$(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod %ci; show -format dot -prefix sumprod_03'
+	$(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod %ci2; show -format dot -prefix sumprod_04'
+	$(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod %ci3; show -format dot -prefix sumprod_05'
 
 $(MEMDEMO_DOTS): memdemo.v
-	$(YOSYS) -p 'proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_00' memdemo.v
-	$(YOSYS) -p 'proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_01 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff' memdemo.v
+	$(YOSYS) -p 'read_verilog memdemo.v; proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_00'
+	$(YOSYS) -p 'read_verilog memdemo.v; proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_01 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff'
 
 $(SUBMOD_DOTS): submod.ys memdemo.v
 	$(YOSYS) submod.ys

docs/source/code_examples/show/Makefile

@@ -2,16 +2,16 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-EXAMPLE = example_00 example_01 example_02 example_03
+EXAMPLE = example_00 example_01 example_02
 EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE))
 
 CMOS = cmos_00 cmos_01
 CMOS_DOTS := $(addsuffix .dot,$(CMOS))
 
-all: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
+dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
 
 splice.dot: splice.v
-	$(YOSYS) -p 'proc; opt; show -format dot -prefix splice' splice.v
+	$(YOSYS) -p 'read_verilog splice.v; proc; opt; show -format dot -prefix splice'
 
 $(EXAMPLE_DOTS): example.v example.ys
 	$(YOSYS) example.ys

docs/source/code_examples/show/example.ys

@@ -4,8 +4,3 @@ proc
 show -format dot -prefix example_01
 opt
 show -format dot -prefix example_02
-
-cd example
-select t:$add
-show -format dot -prefix example_03
-

docs/source/code_examples/stubnets/Makefile

@@ -1,3 +1,5 @@
+dots:
+
 test: stubnets.so
 	yosys -ql test1.log -m ./stubnets.so test.v -p "stubnets"
 	yosys -ql test2.log -m ./stubnets.so test.v -p "opt; stubnets"