Remove docs dependency on yosys repo (#3558)

* Copies guidelines files into docs/ for website * Copying manual/CHAPTER_Prog for new docs * Copying manual/APPNOTE_011... for new docs Also adding faketime to list of packages for website build. Co-authored-by: KrystalDelusion <krystinedawn@yosyshq.com>
2025-04-22 16:45:32 +00:00 · 2022-11-25 03:56:44 +13:00 · 2022-11-25 03:56:44 +13:00 · b9b5899cce
commit b9b5899cce
parent fc2f622a27
39 changed files with 905 additions and 18 deletions
--- a/docs/.gitignore
+++ b/docs/.gitignore
@ -1,5 +1,6 @@
 /build/
 /source/cmd
+/source/temp
 /images/*.log
 /images/*.aux
 /images/*.pdf
--- a/docs/images/Makefile
+++ b/docs/images/Makefile
@ -1,7 +1,7 @@
 all: dots tex svg tidy

 TEX_SOURCE:= $(wildcard *.tex)
-DOT_LOC:= ../../manual/APPNOTE_011_Design_Investigation
+DOT_LOC:= ../source/APPNOTE_011_Design_Investigation
 DOT_SOURCE:= $(wildcard $(DOT_LOC)/*.dot)

 TEX_SOURCE+= 011/example_out.tex
--- a/docs/source/APPNOTE_011_Design_Investigation/cmos.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/cmos.v
@ -0,0 +1,3 @@
+module cmos_demo(input a, b, output [1:0] y);
+assign y = a + b;
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/cmos_00.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/cmos_00.dot
@ -0,0 +1,34 @@
+digraph "cmos_demo" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c10 [ shape=record, label="{{<p7> A|<p8> B|<p9> Y}|$g0\nNOR|{}}" ];
+c11 [ shape=record, label="{{<p7> A|<p9> Y}|$g1\nNOT|{}}" ];
+c12 [ shape=record, label="{{<p7> A|<p9> Y}|$g2\nNOT|{}}" ];
+c13 [ shape=record, label="{{<p7> A|<p8> B|<p9> Y}|$g3\nNOR|{}}" ];
+x0 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x0:e -> c13:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c14 [ shape=record, label="{{<p7> A|<p8> B|<p9> Y}|$g4\nNOR|{}}" ];
+x1 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x1:e -> c14:p8:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+x2 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x2:e -> c14:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+n1 [ shape=diamond, label="$n4" ];
+n1:e -> c10:p9:w [color="black", label=""];
+n1:e -> c14:p7:w [color="black", label=""];
+n2 [ shape=diamond, label="$n5" ];
+n2:e -> c11:p9:w [color="black", label=""];
+n2:e -> c13:p7:w [color="black", label=""];
+n3 [ shape=diamond, label="$n6_1" ];
+n3:e -> c12:p9:w [color="black", label=""];
+n3:e -> c13:p8:w [color="black", label=""];
+n4:e -> c10:p8:w [color="black", label=""];
+n4:e -> c12:p7:w [color="black", label=""];
+n5:e -> c10:p7:w [color="black", label=""];
+n5:e -> c11:p7:w [color="black", label=""];
+n6:e -> x0:s0:w [color="black", label=""];
+n6:e -> x1:s0:w [color="black", label=""];
+n6:e -> x2:s0:w [color="black", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/cmos_01.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/cmos_01.dot
@ -0,0 +1,23 @@
+digraph "cmos_demo" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="y[0]", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="y[1]", color="black", fontcolor="black" ];
+c11 [ shape=record, label="{{<p8> A|<p9> B}|$g0\nNOR|{<p10> Y}}" ];
+c12 [ shape=record, label="{{<p8> A}|$g1\nNOT|{<p10> Y}}" ];
+c13 [ shape=record, label="{{<p8> A}|$g2\nNOT|{<p10> Y}}" ];
+c14 [ shape=record, label="{{<p8> A|<p9> B}|$g3\nNOR|{<p10> Y}}" ];
+c15 [ shape=record, label="{{<p8> A|<p9> B}|$g4\nNOR|{<p10> Y}}" ];
+c11:p10:e -> c15:p8:w [color="black", label=""];
+c12:p10:e -> c14:p8:w [color="black", label=""];
+c13:p10:e -> c14:p9:w [color="black", label=""];
+n4:e -> c11:p9:w [color="black", label=""];
+n4:e -> c13:p8:w [color="black", label=""];
+n5:e -> c11:p8:w [color="black", label=""];
+n5:e -> c12:p8:w [color="black", label=""];
+c15:p10:e -> n6:w [color="black", label=""];
+c14:p10:e -> n7:w [color="black", label=""];
+n7:e -> c15:p9:w [color="black", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/example.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/example.v
@ -0,0 +1,6 @@
+module example(input clk, a, b, c,
+               output reg [1:0] y);
+    always @(posedge clk)
+        if (c)
+            y <= c ? a + b : 2'd0;
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/example.ys
+++ b/docs/source/APPNOTE_011_Design_Investigation/example.ys
@ -0,0 +1,11 @@
+read_verilog example.v
+show -format dot -prefix example_00
+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
+
--- a/docs/source/APPNOTE_011_Design_Investigation/example_00.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_00.dot
@ -0,0 +1,23 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c12 [ shape=record, label="{{<p9> A|<p10> B}|$2\n$add|{<p11> Y}}" ];
+v0 [ label="2'00" ];
+c14 [ shape=record, label="{{<p9> A|<p10> B|<p13> S}|$3\n$mux|{<p11> Y}}" ];
+p1 [shape=box, style=rounded, label="PROC $1\nexample.v:3"];
+c12:p11:e -> c14:p10:w [color="black", style="setlinewidth(3)", label=""];
+c14:p11:e -> p1:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c12:p9:w [color="black", label=""];
+n5:e -> c12:p10:w [color="black", label=""];
+n6:e -> c14:p13:w [color="black", label=""];
+n6:e -> p1:w [color="black", label=""];
+n7:e -> p1:w [color="black", label=""];
+p1:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+n8:e -> p1:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c14:p9:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/example_01.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_01.dot
@ -0,0 +1,33 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+n6 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n9 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n10 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c14 [ shape=record, label="{{<p11> A|<p12> B}|$2\n$add|{<p13> Y}}" ];
+c18 [ shape=record, label="{{<p15> CLK|<p16> D}|$7\n$dff|{<p17> Q}}" ];
+c20 [ shape=record, label="{{<p11> A|<p12> B|<p19> S}|$5\n$mux|{<p13> Y}}" ];
+v0 [ label="2'00" ];
+c21 [ shape=record, label="{{<p11> A|<p12> B|<p19> S}|$3\n$mux|{<p13> Y}}" ];
+x1 [shape=box, style=rounded, label="BUF"];
+x2 [shape=box, style=rounded, label="BUF"];
+n1 [ shape=diamond, label="$0\\y[1:0]" ];
+x2:e:e -> n1:w [color="black", style="setlinewidth(3)", label=""];
+c18:p17:e -> n10:w [color="black", style="setlinewidth(3)", label=""];
+n10:e -> c20:p11:w [color="black", style="setlinewidth(3)", label=""];
+c14:p13:e -> c21:p12:w [color="black", style="setlinewidth(3)", label=""];
+n3 [ shape=point ];
+c20:p13:e -> n3:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c18:p16:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> x2:w:w [color="black", style="setlinewidth(3)", label=""];
+x1:e:e -> c20:p19:w [color="black", label=""];
+c21:p13:e -> c20:p12:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c14:p11:w [color="black", label=""];
+n7:e -> c14:p12:w [color="black", label=""];
+n8:e -> c21:p19:w [color="black", label=""];
+n8:e -> x1:w:w [color="black", label=""];
+n9:e -> c18:p15:w [color="black", label=""];
+v0:e -> c21:p11:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/example_02.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_02.dot
@ -0,0 +1,20 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+n3 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c11 [ shape=record, label="{{<p8> A|<p9> B}|$2\n$add|{<p10> Y}}" ];
+c15 [ shape=record, label="{{<p12> CLK|<p13> D}|$7\n$dff|{<p14> Q}}" ];
+c17 [ shape=record, label="{{<p8> A|<p9> B|<p16> S}|$5\n$mux|{<p10> Y}}" ];
+c17:p10:e -> c15:p13:w [color="black", style="setlinewidth(3)", label=""];
+c11:p10:e -> c17:p9:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c11:p8:w [color="black", label=""];
+n4:e -> c11:p9:w [color="black", label=""];
+n5:e -> c17:p16:w [color="black", label=""];
+n6:e -> c15:p12:w [color="black", label=""];
+c15:p14:e -> n7:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c17:p8:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/example_03.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_03.dot
@ -0,0 +1,11 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+v0 [ label="a" ];
+v1 [ label="b" ];
+v2 [ label="$2_Y" ];
+c4 [ shape=record, label="{{<p1> A|<p2> B}|$2\n$add|{<p3> Y}}" ];
+v0:e -> c4:p1:w [color="black", label=""];
+v1:e -> c4:p2:w [color="black", label=""];
+c4:p3:e -> v2:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/foobaraddsub.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/foobaraddsub.v
@ -0,0 +1,8 @@
+module foobaraddsub(a, b, c, d, fa, fs, ba, bs);
+  input [7:0] a, b, c, d;
+  output [7:0] fa, fs, ba, bs;
+  assign fa = a + (* foo *) b;
+  assign fs = a - (* foo *) b;
+  assign ba = c + (* bar *) d;
+  assign bs = c - (* bar *) d;
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/make.sh
+++ b/docs/source/APPNOTE_011_Design_Investigation/make.sh
@ -0,0 +1,23 @@
+#!/bin/bash
+set -ex
+if false; then
+	rm -f *.dot
+	../../yosys example.ys
+	../../yosys -p 'proc; opt; show -format dot -prefix splice' splice.v
+	../../yosys -p 'techmap; abc -liberty ../../techlibs/cmos/cmos_cells.lib;; show -format dot -prefix cmos_00' cmos.v
+	../../yosys -p 'techmap; splitnets -ports; abc -liberty ../../techlibs/cmos/cmos_cells.lib;; show -lib ../../techlibs/cmos/cmos_cells.v -format dot -prefix cmos_01' cmos.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 '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 submod.ys
+	sed -i '/^label=/ d;' *.dot
+fi
+for dot_file in *.dot; do
+	pdf_file=${dot_file%.dot}.pdf
+	dot -Tpdf -o $pdf_file $dot_file
+done
--- a/docs/source/APPNOTE_011_Design_Investigation/memdemo.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/memdemo.v
@ -0,0 +1,19 @@
+module memdemo(clk, d, y);
+
+input clk;
+input [3:0] d;
+output reg [3:0] y;
+
+integer i;
+reg [1:0] s1, s2;
+reg [3:0] mem [0:3];
+
+always @(posedge clk) begin
+    for (i = 0; i < 4; i = i+1)
+        mem[i] <= mem[(i+1) % 4] + mem[(i+2) % 4];
+    { s2, s1 } = d ? { s1, s2 } ^ d : 4'b0;
+    mem[s1] <= d;
+    y <= mem[s2];
+end
+
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/memdemo_00.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/memdemo_00.dot
@ -0,0 +1,138 @@
+digraph "memdemo" {
+rankdir="LR";
+remincross=true;
+n24 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n25 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n26 [ shape=diamond, label="mem[0]", color="black", fontcolor="black" ];
+n27 [ shape=diamond, label="mem[1]", color="black", fontcolor="black" ];
+n28 [ shape=diamond, label="mem[2]", color="black", fontcolor="black" ];
+n29 [ shape=diamond, label="mem[3]", color="black", fontcolor="black" ];
+n30 [ shape=diamond, label="s1", color="black", fontcolor="black" ];
+n31 [ shape=diamond, label="s2", color="black", fontcolor="black" ];
+n32 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c36 [ shape=record, label="{{<p33> A|<p34> B}|$28\n$add|{<p35> Y}}" ];
+c37 [ shape=record, label="{{<p33> A|<p34> B}|$31\n$add|{<p35> Y}}" ];
+c38 [ shape=record, label="{{<p33> A|<p34> B}|$34\n$add|{<p35> Y}}" ];
+c39 [ shape=record, label="{{<p33> A|<p34> B}|$37\n$add|{<p35> Y}}" ];
+c41 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$110\n$mux|{<p35> Y}}" ];
+x0 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x0:e -> c41:p40:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c42 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$113\n$mux|{<p35> Y}}" ];
+x1 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x1:e -> c42:p40:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c43 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$116\n$mux|{<p35> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x2:e -> c43:p40:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+v3 [ label="1'1" ];
+c44 [ shape=record, label="{{<p33> A|<p34> B}|$145\n$and|{<p35> Y}}" ];
+v4 [ label="1'1" ];
+c45 [ shape=record, label="{{<p33> A|<p34> B}|$175\n$and|{<p35> Y}}" ];
+v5 [ label="1'1" ];
+c46 [ shape=record, label="{{<p33> A|<p34> B}|$205\n$and|{<p35> Y}}" ];
+v6 [ label="1'1" ];
+c47 [ shape=record, label="{{<p33> A|<p34> B}|$235\n$and|{<p35> Y}}" ];
+v7 [ label="2'00" ];
+c48 [ shape=record, label="{{<p33> A|<p34> B}|$143\n$eq|{<p35> Y}}" ];
+v8 [ label="2'01" ];
+c49 [ shape=record, label="{{<p33> A|<p34> B}|$173\n$eq|{<p35> Y}}" ];
+v9 [ label="2'10" ];
+c50 [ shape=record, label="{{<p33> A|<p34> B}|$203\n$eq|{<p35> Y}}" ];
+v10 [ label="2'11" ];
+c51 [ shape=record, label="{{<p33> A|<p34> B}|$233\n$eq|{<p35> Y}}" ];
+c52 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$147\n$mux|{<p35> Y}}" ];
+c53 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$177\n$mux|{<p35> Y}}" ];
+c54 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$207\n$mux|{<p35> Y}}" ];
+c55 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$237\n$mux|{<p35> Y}}" ];
+c59 [ shape=record, label="{{<p56> CLK|<p57> D}|$66\n$dff|{<p58> Q}}" ];
+c60 [ shape=record, label="{{<p56> CLK|<p57> D}|$68\n$dff|{<p58> Q}}" ];
+c61 [ shape=record, label="{{<p56> CLK|<p57> D}|$70\n$dff|{<p58> Q}}" ];
+c62 [ shape=record, label="{{<p56> CLK|<p57> D}|$72\n$dff|{<p58> Q}}" ];
+c63 [ shape=record, label="{{<p56> CLK|<p57> D}|$59\n$dff|{<p58> Q}}" ];
+c64 [ shape=record, label="{{<p56> CLK|<p57> D}|$63\n$dff|{<p58> Q}}" ];
+c65 [ shape=record, label="{{<p56> CLK|<p57> D}|$64\n$dff|{<p58> Q}}" ];
+c66 [ shape=record, label="{{<p33> A}|$39\n$reduce_bool|{<p35> Y}}" ];
+v11 [ label="4'0000" ];
+c67 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$40\n$mux|{<p35> Y}}" ];
+x12 [ shape=record, style=rounded, label="<s1> 3:2 - 1:0 |<s0> 1:0 - 1:0 " ];
+c67:p35:e -> x12:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c68 [ shape=record, label="{{<p33> A|<p34> B}|$38\n$xor|{<p35> Y}}" ];
+x13 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x13:e -> c68:p33:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c36:p35:e -> c52:p33:w [color="black", style="setlinewidth(3)", label=""];
+c44:p35:e -> c52:p40:w [color="black", label=""];
+c45:p35:e -> c53:p40:w [color="black", label=""];
+c46:p35:e -> c54:p40:w [color="black", label=""];
+c47:p35:e -> c55:p40:w [color="black", label=""];
+c48:p35:e -> c44:p33:w [color="black", label=""];
+c49:p35:e -> c45:p33:w [color="black", label=""];
+c50:p35:e -> c46:p33:w [color="black", label=""];
+c51:p35:e -> c47:p33:w [color="black", label=""];
+c52:p35:e -> c59:p57:w [color="black", style="setlinewidth(3)", label=""];
+c53:p35:e -> c60:p57:w [color="black", style="setlinewidth(3)", label=""];
+c37:p35:e -> c53:p33:w [color="black", style="setlinewidth(3)", label=""];
+c54:p35:e -> c61:p57:w [color="black", style="setlinewidth(3)", label=""];
+c55:p35:e -> c62:p57:w [color="black", style="setlinewidth(3)", label=""];
+c66:p35:e -> c67:p40:w [color="black", label=""];
+c68:p35:e -> c67:p34:w [color="black", style="setlinewidth(3)", label=""];
+n24:e -> c59:p56:w [color="black", label=""];
+n24:e -> c60:p56:w [color="black", label=""];
+n24:e -> c61:p56:w [color="black", label=""];
+n24:e -> c62:p56:w [color="black", label=""];
+n24:e -> c63:p56:w [color="black", label=""];
+n24:e -> c64:p56:w [color="black", label=""];
+n24:e -> c65:p56:w [color="black", label=""];
+n25:e -> c52:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c53:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c54:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c55:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c66:p33:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c68:p34:w [color="black", style="setlinewidth(3)", label=""];
+c59:p58:e -> n26:w [color="black", style="setlinewidth(3)", label=""];
+n26:e -> c38:p34:w [color="black", style="setlinewidth(3)", label=""];
+n26:e -> c39:p33:w [color="black", style="setlinewidth(3)", label=""];
+n26:e -> c42:p33:w [color="black", style="setlinewidth(3)", label=""];
+c60:p58:e -> n27:w [color="black", style="setlinewidth(3)", label=""];
+n27:e -> c36:p33:w [color="black", style="setlinewidth(3)", label=""];
+n27:e -> c39:p34:w [color="black", style="setlinewidth(3)", label=""];
+n27:e -> c42:p34:w [color="black", style="setlinewidth(3)", label=""];
+c61:p58:e -> n28:w [color="black", style="setlinewidth(3)", label=""];
+n28:e -> c36:p34:w [color="black", style="setlinewidth(3)", label=""];
+n28:e -> c37:p33:w [color="black", style="setlinewidth(3)", label=""];
+n28:e -> c43:p33:w [color="black", style="setlinewidth(3)", label=""];
+c62:p58:e -> n29:w [color="black", style="setlinewidth(3)", label=""];
+n29:e -> c37:p34:w [color="black", style="setlinewidth(3)", label=""];
+n29:e -> c38:p33:w [color="black", style="setlinewidth(3)", label=""];
+n29:e -> c43:p34:w [color="black", style="setlinewidth(3)", label=""];
+c38:p35:e -> c54:p33:w [color="black", style="setlinewidth(3)", label=""];
+c63:p58:e -> n30:w [color="black", style="setlinewidth(3)", label=""];
+n30:e -> x13:s1:w [color="black", style="setlinewidth(3)", label=""];
+c64:p58:e -> n31:w [color="black", style="setlinewidth(3)", label=""];
+n31:e -> x13:s0:w [color="black", style="setlinewidth(3)", label=""];
+c65:p58:e -> n32:w [color="black", style="setlinewidth(3)", label=""];
+c39:p35:e -> c55:p33:w [color="black", style="setlinewidth(3)", label=""];
+n5 [ shape=point ];
+x12:s0:e -> n5:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c48:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c49:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c50:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c51:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c63:p57:w [color="black", style="setlinewidth(3)", label=""];
+n6 [ shape=point ];
+x12:s1:e -> n6:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c64:p57:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x0:s0:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x1:s0:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x2:s0:w [color="black", style="setlinewidth(3)", label=""];
+c41:p35:e -> c65:p57:w [color="black", style="setlinewidth(3)", label=""];
+c42:p35:e -> c41:p33:w [color="black", style="setlinewidth(3)", label=""];
+c43:p35:e -> c41:p34:w [color="black", style="setlinewidth(3)", label=""];
+v10:e -> c51:p33:w [color="black", style="setlinewidth(3)", label=""];
+v11:e -> c67:p33:w [color="black", style="setlinewidth(3)", label=""];
+v3:e -> c44:p34:w [color="black", label=""];
+v4:e -> c45:p34:w [color="black", label=""];
+v5:e -> c46:p34:w [color="black", label=""];
+v6:e -> c47:p34:w [color="black", label=""];
+v7:e -> c48:p33:w [color="black", style="setlinewidth(3)", label=""];
+v8:e -> c49:p33:w [color="black", style="setlinewidth(3)", label=""];
+v9:e -> c50:p33:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/memdemo_01.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/memdemo_01.dot
@ -0,0 +1,29 @@
+digraph "memdemo" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=diamond, label="mem[0]", color="black", fontcolor="black" ];
+n5 [ shape=diamond, label="mem[1]", color="black", fontcolor="black" ];
+n6 [ shape=diamond, label="mem[2]", color="black", fontcolor="black" ];
+n7 [ shape=diamond, label="mem[3]", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+v0 [ label="$0\\s2[1:0] [1]" ];
+c13 [ shape=record, label="{{<p9> A|<p10> B|<p11> S}|$110\n$mux|{<p12> Y}}" ];
+v1 [ label="$0\\s2[1:0] [0]" ];
+c14 [ shape=record, label="{{<p9> A|<p10> B|<p11> S}|$113\n$mux|{<p12> Y}}" ];
+v2 [ label="$0\\s2[1:0] [0]" ];
+c15 [ shape=record, label="{{<p9> A|<p10> B|<p11> S}|$116\n$mux|{<p12> Y}}" ];
+v3 [ label="clk" ];
+c19 [ shape=record, label="{{<p16> CLK|<p17> D}|$64\n$dff|{<p18> Q}}" ];
+c13:p12:e -> c19:p17:w [color="black", style="setlinewidth(3)", label=""];
+c14:p12:e -> c13:p9:w [color="black", style="setlinewidth(3)", label=""];
+c15:p12:e -> c13:p10:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c14:p9:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c14:p10:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c15:p9:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c15:p10:w [color="black", style="setlinewidth(3)", label=""];
+c19:p18:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c13:p11:w [color="black", label=""];
+v1:e -> c14:p11:w [color="black", label=""];
+v2:e -> c15:p11:w [color="black", label=""];
+v3:e -> c19:p16:w [color="black", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/primetest.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/primetest.v
@ -0,0 +1,4 @@
+module primetest(p, a, b, ok);
+input [15:0] p, a, b;
+output ok = p != a*b || a == 1 || b == 1;
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/splice.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/splice.dot
@ -0,0 +1,39 @@
+digraph "splice_demo" {
+rankdir="LR";
+remincross=true;
+n1 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n2 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="e", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="f", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="x", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c11 [ shape=record, label="{{<p9> A}|$2\n$neg|{<p10> Y}}" ];
+x0 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x0:e -> c11:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+x1 [ shape=record, style=rounded, label="<s0> 3:0 - 7:4 " ];
+c11:p10:e -> x1:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c12 [ shape=record, label="{{<p9> A}|$1\n$not|{<p10> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x2:e -> c12:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+x3 [ shape=record, style=rounded, label="<s1> 3:2 - 1:0 |<s0> 1:0 - 3:2 " ];
+c12:p10:e -> x3:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+x4 [ shape=record, style=rounded, label="<s1> 0:0 - 1:1 |<s0> 1:1 - 0:0 " ];
+x5 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x6 [ shape=record, style=rounded, label="<s0> 3:0 - 11:8 " ];
+x5:e -> x6:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+n1:e -> x4:s0:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> x4:s1:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> x5:s1:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> x5:s0:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> x0:s1:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> x0:s0:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> x2:s1:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x2:s0:w [color="black", style="setlinewidth(3)", label=""];
+x4:e -> n7:w [color="black", style="setlinewidth(3)", label=""];
+x1:s0:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+x3:s0:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+x3:s1:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+x6:s0:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/splice.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/splice.v
@ -0,0 +1,10 @@
+module splice_demo(a, b, c, d, e, f, x, y);
+
+input [1:0] a, b, c, d, e, f;
+output [1:0] x = {a[0], a[1]};
+
+output [11:0] y;
+assign {y[11:4], y[1:0], y[3:2]} =
+                {a, b, -{c, d}, ~{e, f}};
+
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/submod.ys
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod.ys
@ -0,0 +1,16 @@
+read_verilog memdemo.v
+proc; opt; memory; opt
+
+cd memdemo
+select -set outstage y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff
+select -set selstage y %ci2:+$dff[Q,D] %ci*:-$dff @outstage %d
+select -set scramble mem* %ci2 %ci*:-$dff mem* %d @selstage %d
+submod -name scramble @scramble
+submod -name outstage @outstage
+submod -name selstage @selstage
+
+cd ..
+show -format dot -prefix submod_00 memdemo
+show -format dot -prefix submod_01 scramble
+show -format dot -prefix submod_02 outstage
+show -format dot -prefix submod_03 selstage
--- a/docs/source/APPNOTE_011_Design_Investigation/submod_00.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_00.dot
@ -0,0 +1,45 @@
+digraph "memdemo" {
+rankdir="LR";
+remincross=true;
+n5 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n7 [ shape=diamond, label="mem[0]", color="black", fontcolor="black" ];
+n8 [ shape=diamond, label="mem[1]", color="black", fontcolor="black" ];
+n9 [ shape=diamond, label="mem[2]", color="black", fontcolor="black" ];
+n10 [ shape=diamond, label="mem[3]", color="black", fontcolor="black" ];
+n11 [ shape=diamond, label="s1", color="black", fontcolor="black" ];
+n12 [ shape=diamond, label="s2", color="black", fontcolor="black" ];
+n13 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c17 [ shape=record, label="{{<p14> CLK|<p15> D}|$59\n$dff|{<p16> Q}}" ];
+c18 [ shape=record, label="{{<p14> CLK|<p15> D}|$63\n$dff|{<p16> Q}}" ];
+c20 [ shape=record, label="{{<p5> clk|<p7> mem[0]|<p8> mem[1]|<p9> mem[2]|<p10> mem[3]|<p19> n1}|outstage\noutstage|{<p13> y}}" ];
+c21 [ shape=record, label="{{<p5> clk|<p6> d|<p19> n1}|scramble\nscramble|{<p7> mem[0]|<p8> mem[1]|<p9> mem[2]|<p10> mem[3]}}" ];
+c23 [ shape=record, label="{{<p6> d|<p11> s1|<p12> s2}|selstage\nselstage|{<p19> n1|<p22> n2}}" ];
+n1 [ shape=point ];
+c23:p19:e -> n1:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> c17:p15:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> c21:p19:w [color="black", style="setlinewidth(3)", label=""];
+c21:p10:e -> n10:w [color="black", style="setlinewidth(3)", label=""];
+n10:e -> c20:p10:w [color="black", style="setlinewidth(3)", label=""];
+c17:p16:e -> n11:w [color="black", style="setlinewidth(3)", label=""];
+n11:e -> c23:p11:w [color="black", style="setlinewidth(3)", label=""];
+c18:p16:e -> n12:w [color="black", style="setlinewidth(3)", label=""];
+n12:e -> c23:p12:w [color="black", style="setlinewidth(3)", label=""];
+c20:p13:e -> n13:w [color="black", style="setlinewidth(3)", label=""];
+n2 [ shape=point ];
+c23:p22:e -> n2:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c18:p15:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c20:p19:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c17:p14:w [color="black", label=""];
+n5:e -> c18:p14:w [color="black", label=""];
+n5:e -> c20:p5:w [color="black", label=""];
+n5:e -> c21:p5:w [color="black", label=""];
+n6:e -> c21:p6:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c23:p6:w [color="black", style="setlinewidth(3)", label=""];
+c21:p7:e -> n7:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c20:p7:w [color="black", style="setlinewidth(3)", label=""];
+c21:p8:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+n8:e -> c20:p8:w [color="black", style="setlinewidth(3)", label=""];
+c21:p9:e -> n9:w [color="black", style="setlinewidth(3)", label=""];
+n9:e -> c20:p9:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/submod_01.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_01.dot
@ -0,0 +1,87 @@
+digraph "scramble" {
+rankdir="LR";
+remincross=true;
+n17 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n18 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n19 [ shape=octagon, label="mem[0]", color="black", fontcolor="black" ];
+n20 [ shape=octagon, label="mem[1]", color="black", fontcolor="black" ];
+n21 [ shape=octagon, label="mem[2]", color="black", fontcolor="black" ];
+n22 [ shape=octagon, label="mem[3]", color="black", fontcolor="black" ];
+n23 [ shape=octagon, label="n1", color="black", fontcolor="black" ];
+c27 [ shape=record, label="{{<p24> A|<p25> B}|$28\n$add|{<p26> Y}}" ];
+c28 [ shape=record, label="{{<p24> A|<p25> B}|$31\n$add|{<p26> Y}}" ];
+c29 [ shape=record, label="{{<p24> A|<p25> B}|$34\n$add|{<p26> Y}}" ];
+c30 [ shape=record, label="{{<p24> A|<p25> B}|$37\n$add|{<p26> Y}}" ];
+v0 [ label="1'1" ];
+c31 [ shape=record, label="{{<p24> A|<p25> B}|$145\n$and|{<p26> Y}}" ];
+v1 [ label="1'1" ];
+c32 [ shape=record, label="{{<p24> A|<p25> B}|$175\n$and|{<p26> Y}}" ];
+v2 [ label="1'1" ];
+c33 [ shape=record, label="{{<p24> A|<p25> B}|$205\n$and|{<p26> Y}}" ];
+v3 [ label="1'1" ];
+c34 [ shape=record, label="{{<p24> A|<p25> B}|$235\n$and|{<p26> Y}}" ];
+v4 [ label="2'00" ];
+c35 [ shape=record, label="{{<p24> A|<p25> B}|$143\n$eq|{<p26> Y}}" ];
+v5 [ label="2'01" ];
+c36 [ shape=record, label="{{<p24> A|<p25> B}|$173\n$eq|{<p26> Y}}" ];
+v6 [ label="2'10" ];
+c37 [ shape=record, label="{{<p24> A|<p25> B}|$203\n$eq|{<p26> Y}}" ];
+v7 [ label="2'11" ];
+c38 [ shape=record, label="{{<p24> A|<p25> B}|$233\n$eq|{<p26> Y}}" ];
+c40 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$147\n$mux|{<p26> Y}}" ];
+c41 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$177\n$mux|{<p26> Y}}" ];
+c42 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$207\n$mux|{<p26> Y}}" ];
+c43 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$237\n$mux|{<p26> Y}}" ];
+c47 [ shape=record, label="{{<p44> CLK|<p45> D}|$66\n$dff|{<p46> Q}}" ];
+c48 [ shape=record, label="{{<p44> CLK|<p45> D}|$68\n$dff|{<p46> Q}}" ];
+c49 [ shape=record, label="{{<p44> CLK|<p45> D}|$70\n$dff|{<p46> Q}}" ];
+c50 [ shape=record, label="{{<p44> CLK|<p45> D}|$72\n$dff|{<p46> Q}}" ];
+c27:p26:e -> c40:p24:w [color="black", style="setlinewidth(3)", label=""];
+c36:p26:e -> c32:p24:w [color="black", label=""];
+c37:p26:e -> c33:p24:w [color="black", label=""];
+c38:p26:e -> c34:p24:w [color="black", label=""];
+c40:p26:e -> c47:p45:w [color="black", style="setlinewidth(3)", label=""];
+c41:p26:e -> c48:p45:w [color="black", style="setlinewidth(3)", label=""];
+c42:p26:e -> c49:p45:w [color="black", style="setlinewidth(3)", label=""];
+c43:p26:e -> c50:p45:w [color="black", style="setlinewidth(3)", label=""];
+n17:e -> c47:p44:w [color="black", label=""];
+n17:e -> c48:p44:w [color="black", label=""];
+n17:e -> c49:p44:w [color="black", label=""];
+n17:e -> c50:p44:w [color="black", label=""];
+n18:e -> c40:p25:w [color="black", style="setlinewidth(3)", label=""];
+n18:e -> c41:p25:w [color="black", style="setlinewidth(3)", label=""];
+n18:e -> c42:p25:w [color="black", style="setlinewidth(3)", label=""];
+n18:e -> c43:p25:w [color="black", style="setlinewidth(3)", label=""];
+c47:p46:e -> n19:w [color="black", style="setlinewidth(3)", label=""];
+n19:e -> c29:p25:w [color="black", style="setlinewidth(3)", label=""];
+n19:e -> c30:p24:w [color="black", style="setlinewidth(3)", label=""];
+c28:p26:e -> c41:p24:w [color="black", style="setlinewidth(3)", label=""];
+c48:p46:e -> n20:w [color="black", style="setlinewidth(3)", label=""];
+n20:e -> c27:p24:w [color="black", style="setlinewidth(3)", label=""];
+n20:e -> c30:p25:w [color="black", style="setlinewidth(3)", label=""];
+c49:p46:e -> n21:w [color="black", style="setlinewidth(3)", label=""];
+n21:e -> c27:p25:w [color="black", style="setlinewidth(3)", label=""];
+n21:e -> c28:p24:w [color="black", style="setlinewidth(3)", label=""];
+c50:p46:e -> n22:w [color="black", style="setlinewidth(3)", label=""];
+n22:e -> c28:p25:w [color="black", style="setlinewidth(3)", label=""];
+n22:e -> c29:p24:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c35:p25:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c36:p25:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c37:p25:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c38:p25:w [color="black", style="setlinewidth(3)", label=""];
+c29:p26:e -> c42:p24:w [color="black", style="setlinewidth(3)", label=""];
+c30:p26:e -> c43:p24:w [color="black", style="setlinewidth(3)", label=""];
+c31:p26:e -> c40:p39:w [color="black", label=""];
+c32:p26:e -> c41:p39:w [color="black", label=""];
+c33:p26:e -> c42:p39:w [color="black", label=""];
+c34:p26:e -> c43:p39:w [color="black", label=""];
+c35:p26:e -> c31:p24:w [color="black", label=""];
+v0:e -> c31:p25:w [color="black", label=""];
+v1:e -> c32:p25:w [color="black", label=""];
+v2:e -> c33:p25:w [color="black", label=""];
+v3:e -> c34:p25:w [color="black", label=""];
+v4:e -> c35:p24:w [color="black", style="setlinewidth(3)", label=""];
+v5:e -> c36:p24:w [color="black", style="setlinewidth(3)", label=""];
+v6:e -> c37:p24:w [color="black", style="setlinewidth(3)", label=""];
+v7:e -> c38:p24:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/submod_02.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_02.dot
@ -0,0 +1,33 @@
+digraph "outstage" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="mem[0]", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="mem[1]", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="mem[2]", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="mem[3]", color="black", fontcolor="black" ];
+n9 [ shape=octagon, label="n1", color="black", fontcolor="black" ];
+n10 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c15 [ shape=record, label="{{<p11> A|<p12> B|<p13> S}|$110\n$mux|{<p14> Y}}" ];
+x0 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x0:e -> c15:p13:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c16 [ shape=record, label="{{<p11> A|<p12> B|<p13> S}|$113\n$mux|{<p14> Y}}" ];
+x1 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x1:e -> c16:p13:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c17 [ shape=record, label="{{<p11> A|<p12> B|<p13> S}|$116\n$mux|{<p14> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x2:e -> c17:p13:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c21 [ shape=record, label="{{<p18> CLK|<p19> D}|$64\n$dff|{<p20> Q}}" ];
+c15:p14:e -> c21:p19:w [color="black", style="setlinewidth(3)", label=""];
+c21:p20:e -> n10:w [color="black", style="setlinewidth(3)", label=""];
+c16:p14:e -> c15:p11:w [color="black", style="setlinewidth(3)", label=""];
+c17:p14:e -> c15:p12:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c21:p18:w [color="black", label=""];
+n5:e -> c16:p11:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c16:p12:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c17:p11:w [color="black", style="setlinewidth(3)", label=""];
+n8:e -> c17:p12:w [color="black", style="setlinewidth(3)", label=""];
+n9:e -> x0:s0:w [color="black", label=""];
+n9:e -> x1:s0:w [color="black", label=""];
+n9:e -> x2:s0:w [color="black", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/submod_03.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_03.dot
@ -0,0 +1,26 @@
+digraph "selstage" {
+rankdir="LR";
+remincross=true;
+n3 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="n1", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="n2", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="s1", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="s2", color="black", fontcolor="black" ];
+c10 [ shape=record, label="{{<p8> A}|$39\n$reduce_bool|{<p9> Y}}" ];
+v0 [ label="4'0000" ];
+c13 [ shape=record, label="{{<p8> A|<p11> B|<p12> S}|$40\n$mux|{<p9> Y}}" ];
+x1 [ shape=record, style=rounded, label="<s1> 3:2 - 1:0 |<s0> 1:0 - 1:0 " ];
+c13:p9:e -> x1:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c14 [ shape=record, label="{{<p8> A|<p11> B}|$38\n$xor|{<p9> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x2:e -> c14:p8:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c10:p9:e -> c13:p12:w [color="black", label=""];
+c14:p9:e -> c13:p11:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c10:p8:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c14:p11:w [color="black", style="setlinewidth(3)", label=""];
+x1:s0:e -> n4:w [color="black", style="setlinewidth(3)", label=""];
+x1:s1:e -> n5:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x2:s1:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> x2:s0:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c13:p8:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod.v
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod.v
@ -0,0 +1,12 @@
+module sumprod(a, b, c, sum, prod);
+
+  input [7:0] a, b, c;
+  output [7:0] sum, prod;
+
+  {* sumstuff *}
+  assign sum = a + b + c;
+  {* *}
+
+  assign prod = a * b * c;
+
+endmodule
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod_00.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_00.dot
@ -0,0 +1,18 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+v0 [ label="a" ];
+v1 [ label="b" ];
+v2 [ label="$1_Y" ];
+c4 [ shape=record, label="{{<p1> A|<p2> B}|$1\n$add|{<p3> Y}}" ];
+v3 [ label="$1_Y" ];
+v4 [ label="c" ];
+v5 [ label="sum" ];
+c5 [ shape=record, label="{{<p1> A|<p2> B}|$2\n$add|{<p3> Y}}" ];
+v0:e -> c4:p1:w [color="black", style="setlinewidth(3)", label=""];
+v1:e -> c4:p2:w [color="black", style="setlinewidth(3)", label=""];
+c4:p3:e -> v2:w [color="black", style="setlinewidth(3)", label=""];
+v3:e -> c5:p1:w [color="black", style="setlinewidth(3)", label=""];
+v4:e -> c5:p2:w [color="black", style="setlinewidth(3)", label=""];
+c5:p3:e -> v5:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod_01.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_01.dot
@ -0,0 +1,15 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n2 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="sum", color="black", fontcolor="black" ];
+c9 [ shape=record, label="{{<p6> A|<p7> B}|$1\n$add|{<p8> Y}}" ];
+c10 [ shape=record, label="{{<p6> A|<p7> B}|$2\n$add|{<p8> Y}}" ];
+c9:p8:e -> c10:p6:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c9:p6:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c9:p7:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c10:p7:w [color="black", style="setlinewidth(3)", label=""];
+c10:p8:e -> n5:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod_02.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_02.dot
@ -0,0 +1,5 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n1 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod_03.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_03.dot
@ -0,0 +1,11 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n1 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+v0 [ label="$3_Y" ];
+v1 [ label="c" ];
+c5 [ shape=record, label="{{<p2> A|<p3> B}|$4\n$mul|{<p4> Y}}" ];
+c5:p4:e -> n1:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c5:p2:w [color="black", style="setlinewidth(3)", label=""];
+v1:e -> c5:p3:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod_04.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_04.dot
@ -0,0 +1,11 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n2 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+c7 [ shape=record, label="{{<p4> A|<p5> B}|$4\n$mul|{<p6> Y}}" ];
+n1 [ shape=diamond, label="$3_Y" ];
+n1:e -> c7:p4:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c7:p5:w [color="black", style="setlinewidth(3)", label=""];
+c7:p6:e -> n3:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/APPNOTE_011_Design_Investigation/sumprod_05.dot
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_05.dot
@ -0,0 +1,15 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n2 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+v0 [ label="a" ];
+v1 [ label="b" ];
+c7 [ shape=record, label="{{<p4> A|<p5> B}|$3\n$mul|{<p6> Y}}" ];
+c8 [ shape=record, label="{{<p4> A|<p5> B}|$4\n$mul|{<p6> Y}}" ];
+c7:p6:e -> c8:p4:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c8:p5:w [color="black", style="setlinewidth(3)", label=""];
+c8:p6:e -> n3:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c7:p4:w [color="black", style="setlinewidth(3)", label=""];
+v1:e -> c7:p5:w [color="black", style="setlinewidth(3)", label=""];
+}
--- a/docs/source/CHAPTER_Prog.rst
+++ b/docs/source/CHAPTER_Prog.rst
@ -15,11 +15,11 @@ The guidelines directory contains notes on various aspects of Yosys
 development. The files GettingStarted and CodingStyle may be of
 particular interest, and are reproduced here.

-.. literalinclude:: ../../guidelines/GettingStarted
+.. literalinclude:: temp/GettingStarted
 	:language: none
 	:caption: guidelines/GettingStarted

-.. literalinclude:: ../../guidelines/CodingStyle
+.. literalinclude:: temp/CodingStyle
 	:language: none
 	:caption: guidelines/CodingStyle

@ -28,19 +28,19 @@ The "stubsnets" example module

 The following is the complete code of the "stubsnets" example module. It
 is included in the Yosys source distribution as
-manual/CHAPTER_Prog/stubnets.cc.
+docs/source/CHAPTER_Prog/stubnets.cc.

-.. literalinclude:: ../../manual/CHAPTER_Prog/stubnets.cc
+.. literalinclude:: CHAPTER_Prog/stubnets.cc
 	:language: c++
 	:linenos:
-	:caption: manual/CHAPTER_Prog/stubnets.cc
+	:caption: docs/source/CHAPTER_Prog/stubnets.cc

-.. literalinclude:: ../../manual/CHAPTER_Prog/Makefile
+.. literalinclude:: CHAPTER_Prog/Makefile
 	:language: makefile
 	:linenos:
-	:caption: manual/CHAPTER_Prog/Makefile
+	:caption: docs/source/CHAPTER_Prog/Makefile

-.. literalinclude:: ../../manual/CHAPTER_Prog/test.v
+.. literalinclude:: CHAPTER_Prog/test.v
 	:language: verilog
 	:linenos:
-	:caption: manual/CHAPTER_Prog/test.v
+	:caption: docs/source/CHAPTER_Prog/test.v
--- a/docs/source/CHAPTER_Prog/.gitignore
+++ b/docs/source/CHAPTER_Prog/.gitignore
@ -0,0 +1,3 @@
+stubnets.so
+stubnets.d
+*.log
--- a/docs/source/CHAPTER_Prog/Makefile
+++ b/docs/source/CHAPTER_Prog/Makefile
@ -0,0 +1,12 @@
+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"
+	yosys -ql test3.log -m ./stubnets.so test.v -p "techmap; opt; stubnets -report_bits"
+	tail test1.log test2.log test3.log
+
+stubnets.so: stubnets.cc
+	yosys-config --exec --cxx --cxxflags --ldflags -o $@ -shared $^ --ldlibs
+
+clean:
+	rm -f test1.log test2.log test3.log
+	rm -f stubnets.so stubnets.d
--- a/docs/source/CHAPTER_Prog/stubnets.cc
+++ b/docs/source/CHAPTER_Prog/stubnets.cc
@ -0,0 +1,130 @@
+// This is free and unencumbered software released into the public domain.
+//
+// Anyone is free to copy, modify, publish, use, compile, sell, or
+// distribute this software, either in source code form or as a compiled
+// binary, for any purpose, commercial or non-commercial, and by any
+// means.
+
+#include "kernel/yosys.h"
+#include "kernel/sigtools.h"
+
+#include <string>
+#include <map>
+#include <set>
+
+USING_YOSYS_NAMESPACE
+PRIVATE_NAMESPACE_BEGIN
+
+// this function is called for each module in the design
+static void find_stub_nets(RTLIL::Design *design, RTLIL::Module *module, bool report_bits)
+{
+	// use a SigMap to convert nets to a unique representation
+	SigMap sigmap(module);
+
+	// count how many times a single-bit signal is used
+	std::map<RTLIL::SigBit, int> bit_usage_count;
+
+	// count output lines for this module (needed only for summary output at the end)
+	int line_count = 0;
+
+	log("Looking for stub wires in module %s:\n", RTLIL::id2cstr(module->name));
+
+	// For all ports on all cells
+	for (auto &cell_iter : module->cells_)
+	for (auto &conn : cell_iter.second->connections())
+	{
+		// Get the signals on the port
+		// (use sigmap to get a uniqe signal name)
+		RTLIL::SigSpec sig = sigmap(conn.second);
+
+		// add each bit to bit_usage_count, unless it is a constant
+		for (auto &bit : sig)
+			if (bit.wire != NULL)
+				bit_usage_count[bit]++;
+	}
+
+	// for each wire in the module
+	for (auto &wire_iter : module->wires_)
+	{
+		RTLIL::Wire *wire = wire_iter.second;
+
+		// .. but only selected wires
+		if (!design->selected(module, wire))
+			continue;
+
+		// add +1 usage if this wire actually is a port
+		int usage_offset = wire->port_id > 0 ? 1 : 0;
+
+		// we will record which bits of the (possibly multi-bit) wire are stub signals
+		std::set<int> stub_bits;
+
+		// get a signal description for this wire and split it into separate bits
+		RTLIL::SigSpec sig = sigmap(wire);
+
+		// for each bit (unless it is a constant):
+		// check if it is used at least two times and add to stub_bits otherwise
+		for (int i = 0; i < GetSize(sig); i++)
+			if (sig[i].wire != NULL && (bit_usage_count[sig[i]] + usage_offset) < 2)
+				stub_bits.insert(i);
+
+		// continue if no stub bits found
+		if (stub_bits.size() == 0)
+			continue;
+
+		// report stub bits and/or stub wires, don't report single bits
+		// if called with report_bits set to false.
+		if (GetSize(stub_bits) == GetSize(sig)) {
+			log("  found stub wire: %s\n", RTLIL::id2cstr(wire->name));
+		} else {
+			if (!report_bits)
+				continue;
+			log("  found wire with stub bits: %s [", RTLIL::id2cstr(wire->name));
+			for (int bit : stub_bits)
+				log("%s%d", bit == *stub_bits.begin() ? "" : ", ", bit);
+			log("]\n");
+		}
+
+		// we have outputted a line, increment summary counter
+		line_count++;
+	}
+
+	// report summary
+	if (report_bits)
+		log("  found %d stub wires or wires with stub bits.\n", line_count);
+	else
+		log("  found %d stub wires.\n", line_count);
+}
+
+// each pass contains a singleton object that is derived from Pass
+struct StubnetsPass : public Pass {
+	StubnetsPass() : Pass("stubnets") { }
+	void execute(std::vector<std::string> args, RTLIL::Design *design) override
+	{
+		// variables to mirror information from passed options
+		bool report_bits = 0;
+
+		log_header(design, "Executing STUBNETS pass (find stub nets).\n");
+
+		// parse options
+		size_t argidx;
+		for (argidx = 1; argidx < args.size(); argidx++) {
+			std::string arg = args[argidx];
+			if (arg == "-report_bits") {
+				report_bits = true;
+				continue;
+			}
+			break;
+		}
+
+		// handle extra options (e.g. selection)
+		extra_args(args, argidx, design);
+
+		// call find_stub_nets() for each module that is either
+		// selected as a whole or contains selected objects.
+		for (auto &it : design->modules_)
+			if (design->selected_module(it.first))
+				find_stub_nets(design, it.second, report_bits);
+	}
+} StubnetsPass;
+
+PRIVATE_NAMESPACE_END
--- a/docs/source/CHAPTER_Prog/test.v
+++ b/docs/source/CHAPTER_Prog/test.v
@ -0,0 +1,8 @@
+module uut(in1, in2, in3, out1, out2);
+
+input [8:0] in1, in2, in3;
+output [8:0] out1, out2;
+
+assign out1 = in1 + in2 + (in3 >> 4);
+
+endmodule
--- a/docs/source/appendix/APPNOTE_011_Design_Investigation.rst
+++ b/docs/source/appendix/APPNOTE_011_Design_Investigation.rst
@ -140,7 +140,7 @@ behavior of the circuit.

   Output of ``yosys -p 'proc; opt; show' splice.v``

-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/splice.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/splice.v
   :caption: ``splice.v``
   :name: splice_src

@ -355,7 +355,7 @@ Objects can not only be selected by their name but also by other properties. For
 example ``select t:$add`` will select all cells of type ``$add``. In this case
 this is also yields the diagram shown in :numref:`seladd`.

-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/foobaraddsub.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/foobaraddsub.v
   :caption: Test module for operations on selections
   :name: foobaraddsub
   :language: verilog
@ -380,7 +380,7 @@ which is a complete selection of everything in the current module.
 Operations on selections
 ------------------------

-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/sumprod.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/sumprod.v
   :caption: Another test module for operations on selections
   :name: sumprod
   :language: verilog
@ -487,7 +487,7 @@ features. We synthesize the circuit using ``proc; opt; memory; opt`` and change
 to the ``memdemo`` module with ``cd memdemo``. If we type ``show`` now we see
 the diagram shown in :numref:`memdemo_00`.

-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/memdemo.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/memdemo.v
   :caption: Demo circuit for demonstrating some advanced Yosys features
   :name: memdemo_src
   :language: verilog
@ -685,7 +685,7 @@ commands can be applied.
 Solving combinatorial SAT problems
 ----------------------------------

-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/primetest.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/primetest.v
   :language: verilog
   :caption: A simple miter circuit for testing if a number is prime. But it has
             a problem (see main text and :numref:`primesat`).