Move (most of) ExOth and ExAdv slides

docs/images/Makefile

@@ -1,6 +1,6 @@
 all: resources dots tex svg tidy
 
-RES_LIST:= PRESENTATION_Intro/ PRESENTATION_ExSyn/
+RES_LIST:= PRESENTATION_Intro/ PRESENTATION_ExSyn/ PRESENTATION_ExAdv/ PRESENTATION_ExOth/
 RES_DIRS:= $(addprefix ../resources/,$(RES_LIST))
 .PHONY: resources
 resources: $(RES_DIRS)

docs/resources/PRESENTATION_ExAdv/.gitignore

@@ -0,0 +1,2 @@
+*.dot
+*.pdf

docs/resources/PRESENTATION_ExAdv/Makefile

@@ -0,0 +1,29 @@
+YOSYS = ../../../yosys
+
+all: select.pdf red_or3x1.pdf sym_mul.pdf mymul.pdf mulshift.pdf addshift.pdf \
+		macc_simple_xmap.pdf macc_xilinx_xmap.pdf
+
+select.pdf: select.v select.ys
+	$(YOSYS) select.ys
+
+red_or3x1.pdf: red_or3x1_*
+	$(YOSYS) red_or3x1_test.ys
+
+sym_mul.pdf: sym_mul_*
+	$(YOSYS) sym_mul_test.ys
+
+mymul.pdf: mymul_*
+	$(YOSYS) mymul_test.ys
+
+mulshift.pdf: mulshift_*
+	$(YOSYS) mulshift_test.ys
+
+addshift.pdf: addshift_*
+	$(YOSYS) addshift_test.ys
+
+macc_simple_xmap.pdf: macc_simple_*.v macc_simple_test.ys
+	$(YOSYS) macc_simple_test.ys
+
+macc_xilinx_xmap.pdf: macc_xilinx_*.v macc_xilinx_test.ys
+	$(YOSYS) macc_xilinx_test.ys
+

docs/resources/PRESENTATION_ExAdv/addshift_map.v

@@ -0,0 +1,20 @@
+module \$add (A, B, Y);
+  parameter A_SIGNED = 0;
+  parameter B_SIGNED = 0;
+  parameter A_WIDTH = 1;
+  parameter B_WIDTH = 1;
+  parameter Y_WIDTH = 1;
+
+  input [A_WIDTH-1:0] A;
+  input [B_WIDTH-1:0] B;
+  output [Y_WIDTH-1:0] Y;
+
+  parameter _TECHMAP_BITS_CONNMAP_ = 0;
+  parameter _TECHMAP_CONNMAP_A_ = 0;
+  parameter _TECHMAP_CONNMAP_B_ = 0;
+
+  wire _TECHMAP_FAIL_ = A_WIDTH != B_WIDTH || B_WIDTH < Y_WIDTH ||
+                        _TECHMAP_CONNMAP_A_ != _TECHMAP_CONNMAP_B_;
+
+  assign Y = A << 1;
+endmodule

docs/resources/PRESENTATION_ExAdv/addshift_test.v

@@ -0,0 +1,5 @@
+module test (A, B, X, Y);
+input [7:0] A, B;
+output [7:0] X = A + B;
+output [7:0] Y = A + A;
+endmodule

docs/resources/PRESENTATION_ExAdv/addshift_test.ys

@@ -0,0 +1,6 @@
+read_verilog addshift_test.v
+hierarchy -check -top test
+
+techmap -map addshift_map.v;;
+
+show -prefix addshift -format pdf -notitle

docs/resources/PRESENTATION_ExAdv/macc_simple_test.v

@@ -0,0 +1,6 @@
+module test(a, b, c, d, y);
+input [15:0] a, b;
+input [31:0] c, d;
+output [31:0] y;
+assign y = a * b + c + d;
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_simple_test.ys

@@ -0,0 +1,37 @@
+read_verilog macc_simple_test.v
+hierarchy -check -top test;;
+
+show -prefix macc_simple_test_00a -format pdf -notitle -lib macc_simple_xmap.v
+
+extract -constports -map macc_simple_xmap.v;;
+show -prefix macc_simple_test_00b -format pdf -notitle -lib macc_simple_xmap.v
+
+#################################################
+
+design -reset
+read_verilog macc_simple_test_01.v
+hierarchy -check -top test;;
+
+show -prefix macc_simple_test_01a -format pdf -notitle -lib macc_simple_xmap.v
+
+extract -map macc_simple_xmap.v;;
+show -prefix macc_simple_test_01b -format pdf -notitle -lib macc_simple_xmap.v
+
+#################################################
+
+design -reset
+read_verilog macc_simple_test_02.v
+hierarchy -check -top test;;
+
+show -prefix macc_simple_test_02a -format pdf -notitle -lib macc_simple_xmap.v
+
+extract -map macc_simple_xmap.v;;
+show -prefix macc_simple_test_02b -format pdf -notitle -lib macc_simple_xmap.v
+
+#################################################
+
+design -reset
+read_verilog macc_simple_xmap.v
+hierarchy -check -top macc_16_16_32;;
+
+show -prefix macc_simple_xmap -format pdf -notitle

docs/resources/PRESENTATION_ExAdv/macc_simple_test_01.v

@@ -0,0 +1,6 @@
+module test(a, b, c, d, x, y);
+input [15:0] a, b, c, d;
+input [31:0] x;
+output [31:0] y;
+assign y = a*b + c*d + x;
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_simple_test_02.v

@@ -0,0 +1,6 @@
+module test(a, b, c, d, x, y);
+input [15:0] a, b, c, d;
+input [31:0] x;
+output [31:0] y;
+assign y = a*b + (c*d + x);
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_simple_xmap.v

@@ -0,0 +1,6 @@
+module macc_16_16_32(a, b, c, y);
+input [15:0] a, b;
+input [31:0] c;
+output [31:0] y;
+assign y = a*b + c;
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_xilinx_swap_map.v

@@ -0,0 +1,28 @@
+(* techmap_celltype = "$mul" *)
+module mul_swap_ports (A, B, Y);
+
+parameter A_SIGNED = 0;
+parameter B_SIGNED = 0;
+parameter A_WIDTH = 1;
+parameter B_WIDTH = 1;
+parameter Y_WIDTH = 1;
+
+input [A_WIDTH-1:0] A;
+input [B_WIDTH-1:0] B;
+output [Y_WIDTH-1:0] Y;
+
+wire _TECHMAP_FAIL_ = A_WIDTH <= B_WIDTH;
+
+\$mul #(
+	.A_SIGNED(B_SIGNED),
+	.B_SIGNED(A_SIGNED),
+	.A_WIDTH(B_WIDTH),
+	.B_WIDTH(A_WIDTH),
+	.Y_WIDTH(Y_WIDTH)
+) _TECHMAP_REPLACE_ (
+	.A(B),
+	.B(A),
+	.Y(Y)
+);
+
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_xilinx_test.v

@@ -0,0 +1,13 @@
+module test1(a, b, c, d, e, f, y);
+    input [19:0] a, b, c;
+    input [15:0] d, e, f;
+    output [41:0] y;
+    assign y = a*b + c*d + e*f;
+endmodule
+
+module test2(a, b, c, d, e, f, y);
+    input [19:0] a, b, c;
+    input [15:0] d, e, f;
+    output [41:0] y;
+    assign y = a*b + (c*d + e*f);
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_xilinx_test.ys

@@ -0,0 +1,43 @@
+read_verilog macc_xilinx_test.v
+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
+
+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
+
+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
+
+design -push
+read_verilog macc_xilinx_xmap.v
+techmap -map macc_xilinx_swap_map.v
+techmap -map macc_xilinx_wrap_map.v;;
+design -save __macc_xilinx_xmap
+design -pop
+
+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
+
+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
+
+design -load __macc_xilinx_xmap
+show -prefix macc_xilinx_xmap -format pdf -notitle
+

docs/resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v

@@ -0,0 +1,61 @@
+module \$__mul_wrapper (A, B, Y);
+
+parameter A_SIGNED = 0;
+parameter B_SIGNED = 0;
+parameter A_WIDTH = 1;
+parameter B_WIDTH = 1;
+parameter Y_WIDTH = 1;
+
+input [17:0] A;
+input [24:0] B;
+output [47:0] Y;
+
+wire [A_WIDTH-1:0] A_ORIG = A;
+wire [B_WIDTH-1:0] B_ORIG = B;
+wire [Y_WIDTH-1:0] Y_ORIG;
+assign Y = Y_ORIG;
+
+\$mul #(
+	.A_SIGNED(A_SIGNED),
+	.B_SIGNED(B_SIGNED),
+	.A_WIDTH(A_WIDTH),
+	.B_WIDTH(B_WIDTH),
+	.Y_WIDTH(Y_WIDTH)
+) _TECHMAP_REPLACE_ (
+	.A(A_ORIG),
+	.B(B_ORIG),
+	.Y(Y_ORIG)
+);
+
+endmodule
+
+module \$__add_wrapper (A, B, Y);
+
+parameter A_SIGNED = 0;
+parameter B_SIGNED = 0;
+parameter A_WIDTH = 1;
+parameter B_WIDTH = 1;
+parameter Y_WIDTH = 1;
+
+input [47:0] A;
+input [47:0] B;
+output [47:0] Y;
+
+wire [A_WIDTH-1:0] A_ORIG = A;
+wire [B_WIDTH-1:0] B_ORIG = B;
+wire [Y_WIDTH-1:0] Y_ORIG;
+assign Y = Y_ORIG;
+
+\$add #(
+	.A_SIGNED(A_SIGNED),
+	.B_SIGNED(B_SIGNED),
+	.A_WIDTH(A_WIDTH),
+	.B_WIDTH(B_WIDTH),
+	.Y_WIDTH(Y_WIDTH)
+) _TECHMAP_REPLACE_ (
+	.A(A_ORIG),
+	.B(B_ORIG),
+	.Y(Y_ORIG)
+);
+
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v

@@ -0,0 +1,89 @@
+(* techmap_celltype = "$mul" *)
+module mul_wrap (A, B, Y);
+
+parameter A_SIGNED = 0;
+parameter B_SIGNED = 0;
+parameter A_WIDTH = 1;
+parameter B_WIDTH = 1;
+parameter Y_WIDTH = 1;
+
+input [A_WIDTH-1:0] A;
+input [B_WIDTH-1:0] B;
+output [Y_WIDTH-1:0] Y;
+
+wire [17:0] A_18 = A;
+wire [24:0] B_25 = B;
+wire [47:0] Y_48;
+assign Y = Y_48;
+
+wire [1023:0] _TECHMAP_DO_ = "proc; clean";
+
+reg _TECHMAP_FAIL_;
+initial begin
+	_TECHMAP_FAIL_ <= 0;
+	if (A_SIGNED || B_SIGNED)
+		_TECHMAP_FAIL_ <= 1;
+	if (A_WIDTH < 4 || B_WIDTH < 4)
+		_TECHMAP_FAIL_ <= 1;
+	if (A_WIDTH > 18 || B_WIDTH > 25)
+		_TECHMAP_FAIL_ <= 1;
+	if (A_WIDTH*B_WIDTH < 100)
+		_TECHMAP_FAIL_ <= 1;
+end
+
+\$__mul_wrapper #(
+	.A_SIGNED(A_SIGNED),
+	.B_SIGNED(B_SIGNED),
+	.A_WIDTH(A_WIDTH),
+	.B_WIDTH(B_WIDTH),
+	.Y_WIDTH(Y_WIDTH)
+) _TECHMAP_REPLACE_ (
+	.A(A_18),
+	.B(B_25),
+	.Y(Y_48)
+);
+
+endmodule
+
+(* techmap_celltype = "$add" *)
+module add_wrap (A, B, Y);
+
+parameter A_SIGNED = 0;
+parameter B_SIGNED = 0;
+parameter A_WIDTH = 1;
+parameter B_WIDTH = 1;
+parameter Y_WIDTH = 1;
+
+input [A_WIDTH-1:0] A;
+input [B_WIDTH-1:0] B;
+output [Y_WIDTH-1:0] Y;
+
+wire [47:0] A_48 = A;
+wire [47:0] B_48 = B;
+wire [47:0] Y_48;
+assign Y = Y_48;
+
+wire [1023:0] _TECHMAP_DO_ = "proc; clean";
+
+reg _TECHMAP_FAIL_;
+initial begin
+	_TECHMAP_FAIL_ <= 0;
+	if (A_SIGNED || B_SIGNED)
+		_TECHMAP_FAIL_ <= 1;
+	if (A_WIDTH < 10 && B_WIDTH < 10)
+		_TECHMAP_FAIL_ <= 1;
+end
+
+\$__add_wrapper #(
+	.A_SIGNED(A_SIGNED),
+	.B_SIGNED(B_SIGNED),
+	.A_WIDTH(A_WIDTH),
+	.B_WIDTH(B_WIDTH),
+	.Y_WIDTH(Y_WIDTH)
+) _TECHMAP_REPLACE_ (
+	.A(A_48),
+	.B(B_48),
+	.Y(Y_48)
+);
+
+endmodule

docs/resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v

@@ -0,0 +1,10 @@
+module DSP48_MACC (a, b, c, y);
+
+input [17:0] a;
+input [24:0] b;
+input [47:0] c;
+output [47:0] y;
+
+assign y = a*b + c;
+
+endmodule

docs/resources/PRESENTATION_ExAdv/mulshift_map.v

@@ -0,0 +1,26 @@
+module MYMUL(A, B, Y);
+    parameter WIDTH = 1;
+    input [WIDTH-1:0] A, B;
+    output reg [WIDTH-1:0] Y;
+
+    parameter _TECHMAP_CONSTVAL_A_ = WIDTH'bx;
+    parameter _TECHMAP_CONSTVAL_B_ = WIDTH'bx;
+
+    reg _TECHMAP_FAIL_;
+    wire [1023:0] _TECHMAP_DO_ = "proc; clean";
+
+    integer i;
+    always @* begin
+    	_TECHMAP_FAIL_ <= 1;
+        for (i = 0; i < WIDTH; i=i+1) begin
+            if (_TECHMAP_CONSTVAL_A_ === WIDTH'd1 << i) begin
+	        _TECHMAP_FAIL_ <= 0;
+                Y <= B << i;
+	    end
+            if (_TECHMAP_CONSTVAL_B_ === WIDTH'd1 << i) begin
+	        _TECHMAP_FAIL_ <= 0;
+                Y <= A << i;
+	    end
+	end
+    end
+endmodule

docs/resources/PRESENTATION_ExAdv/mulshift_test.v

@@ -0,0 +1,5 @@
+module test (A, X, Y);
+input [7:0] A;
+output [7:0] X = A * 8'd 6;
+output [7:0] Y = A * 8'd 8;
+endmodule

docs/resources/PRESENTATION_ExAdv/mulshift_test.ys

@@ -0,0 +1,7 @@
+read_verilog mulshift_test.v
+hierarchy -check -top test
+
+techmap -map sym_mul_map.v \
+        -map mulshift_map.v;;
+
+show -prefix mulshift -format pdf -notitle -lib sym_mul_cells.v

docs/resources/PRESENTATION_ExAdv/mymul_map.v

@@ -0,0 +1,15 @@
+module MYMUL(A, B, Y);
+    parameter WIDTH = 1;
+    input [WIDTH-1:0] A, B;
+    output reg [WIDTH-1:0] Y;
+
+    wire [1023:0] _TECHMAP_DO_ = "proc; clean";
+
+    integer i;
+    always @* begin
+        Y = 0;
+        for (i = 0; i < WIDTH; i=i+1)
+            if (A[i])
+                Y = Y + (B << i);
+    end
+endmodule

docs/resources/PRESENTATION_ExAdv/mymul_test.v

@@ -0,0 +1,4 @@
+module test(A, B, Y);
+    input  [1:0] A, B;
+    output [1:0] Y = A * B;
+endmodule

docs/resources/PRESENTATION_ExAdv/mymul_test.ys

@@ -0,0 +1,15 @@
+read_verilog mymul_test.v
+hierarchy -check -top test
+
+techmap -map sym_mul_map.v \
+        -map mymul_map.v;;
+
+rename test test_mapped
+read_verilog mymul_test.v
+miter -equiv test test_mapped miter
+flatten miter
+
+sat -verify -prove trigger 0 miter
+
+splitnets -ports test_mapped/A
+show -prefix mymul -format pdf -notitle test_mapped

docs/resources/PRESENTATION_ExAdv/red_or3x1_cells.v

@@ -0,0 +1,5 @@
+module OR3X1(A, B, C, Y);
+    input A, B, C;
+    output Y;
+    assign Y = A | B | C;
+endmodule

docs/resources/PRESENTATION_ExAdv/red_or3x1_map.v

@@ -0,0 +1,48 @@
+module \$reduce_or (A, Y);
+
+    parameter A_SIGNED = 0;
+    parameter A_WIDTH = 0;
+    parameter Y_WIDTH = 0;
+
+    input [A_WIDTH-1:0] A;
+    output [Y_WIDTH-1:0] Y;
+
+    function integer min;
+        input integer a, b;
+        begin
+            if (a < b)
+                min = a;
+            else
+                min = b;
+        end
+    endfunction
+
+    genvar i;
+    generate begin
+        if (A_WIDTH == 0) begin
+            assign Y = 0;
+        end
+        if (A_WIDTH == 1) begin
+            assign Y = A;
+        end
+        if (A_WIDTH == 2) begin
+            wire ybuf;
+            OR3X1 g (.A(A[0]), .B(A[1]), .C(1'b0), .Y(ybuf));
+            assign Y = ybuf;
+        end
+        if (A_WIDTH == 3) begin
+            wire ybuf;
+            OR3X1 g (.A(A[0]), .B(A[1]), .C(A[2]), .Y(ybuf));
+            assign Y = ybuf;
+        end
+        if (A_WIDTH > 3) begin
+            localparam next_stage_sz = (A_WIDTH+2) / 3;
+            wire [next_stage_sz-1:0] next_stage;
+            for (i = 0; i < next_stage_sz; i = i+1) begin
+                localparam bits = min(A_WIDTH - 3*i, 3);
+                assign next_stage[i] = |A[3*i +: bits];
+            end
+            assign Y = |next_stage;
+        end
+    end endgenerate
+endmodule

docs/resources/PRESENTATION_ExAdv/red_or3x1_test.v

@@ -0,0 +1,5 @@
+module test (A, Y);
+    input [6:0] A;
+    output Y;
+    assign Y = |A;
+endmodule

docs/resources/PRESENTATION_ExAdv/red_or3x1_test.ys

@@ -0,0 +1,7 @@
+read_verilog red_or3x1_test.v
+hierarchy -check -top test
+
+techmap -map red_or3x1_map.v;;
+
+splitnets -ports
+show -prefix red_or3x1 -format pdf -notitle -lib red_or3x1_cells.v

docs/resources/PRESENTATION_ExAdv/select.v

@@ -0,0 +1,15 @@
+module test(clk, s, a, y);
+    input clk, s;
+    input [15:0] a;
+    output [15:0] y;
+    reg [15:0] b, c;
+
+    always @(posedge clk) begin
+        b <= a;
+        c <= b;
+    end
+
+    wire [15:0] state_a = (a ^ b) + c;
+    wire [15:0] state_b = (a ^ b) - c;
+    assign y = !s ? state_a : state_b;
+endmodule

docs/resources/PRESENTATION_ExAdv/select.ys

@@ -0,0 +1,10 @@
+read_verilog select.v
+hierarchy -check -top test
+proc; opt
+cd test
+select -set cone_a state_a %ci*:-$dff
+select -set cone_b state_b %ci*:-$dff
+select -set cone_ab @cone_a @cone_b %i
+show -prefix select -format pdf -notitle \
+     -color red @cone_ab -color magenta @cone_a \
+     -color blue @cone_b

docs/resources/PRESENTATION_ExAdv/sym_mul_cells.v

@@ -0,0 +1,6 @@
+module MYMUL(A, B, Y);
+    parameter WIDTH = 1;
+    input [WIDTH-1:0] A, B;
+    output [WIDTH-1:0] Y;
+    assign Y = A * B;
+endmodule

docs/resources/PRESENTATION_ExAdv/sym_mul_map.v

@@ -0,0 +1,15 @@
+module \$mul (A, B, Y);
+    parameter A_SIGNED = 0;
+    parameter B_SIGNED = 0;
+    parameter A_WIDTH = 1;
+    parameter B_WIDTH = 1;
+    parameter Y_WIDTH = 1;
+
+    input [A_WIDTH-1:0] A;
+    input [B_WIDTH-1:0] B;
+    output [Y_WIDTH-1:0] Y;
+
+    wire _TECHMAP_FAIL_ = A_WIDTH != B_WIDTH || B_WIDTH != Y_WIDTH;
+
+    MYMUL #( .WIDTH(Y_WIDTH) ) g ( .A(A), .B(B), .Y(Y) );
+endmodule

docs/resources/PRESENTATION_ExAdv/sym_mul_test.v

@@ -0,0 +1,5 @@
+module test(A, B, C, Y1, Y2);
+    input   [7:0] A, B, C;
+    output  [7:0] Y1 = A * B;
+    output [15:0] Y2 = A * C;
+endmodule

docs/resources/PRESENTATION_ExAdv/sym_mul_test.ys

@@ -0,0 +1,6 @@
+read_verilog sym_mul_test.v
+hierarchy -check -top test
+
+techmap -map sym_mul_map.v;;
+
+show -prefix sym_mul -format pdf -notitle -lib sym_mul_cells.v

docs/resources/PRESENTATION_ExOth/.gitignore

@@ -0,0 +1,3 @@
+*.dot
+*.pdf
+*.log

docs/resources/PRESENTATION_ExOth/Makefile

@@ -0,0 +1,17 @@
+YOSYS = ../../../yosys
+
+all: scrambler_p01.pdf scrambler_p02.pdf equiv.log axis_test.log
+
+scrambler_p01.pdf: scrambler.ys scrambler.v
+	$(YOSYS) scrambler.ys
+
+scrambler_p02.pdf: scrambler_p01.pdf
+
+equiv.log: equiv.ys
+	$(YOSYS) -l equiv.log_new equiv.ys
+	mv equiv.log_new equiv.log
+
+axis_test.log: axis_test.ys axis_master.v axis_test.v
+	$(YOSYS) -l axis_test.log_new axis_test.ys
+	mv axis_test.log_new axis_test.log
+

docs/resources/PRESENTATION_ExOth/axis_master.v

@@ -0,0 +1,27 @@
+module axis_master(aclk, aresetn, tvalid, tready, tdata);
+    input aclk, aresetn, tready;
+    output reg tvalid;
+    output reg [7:0] tdata;
+
+    reg [31:0] state;
+    always @(posedge aclk) begin
+        if (!aresetn) begin
+	    state <= 314159265;
+	    tvalid <= 0;
+	    tdata <= 'bx;
+	end else begin
+	    if (tvalid && tready)
+	    	tvalid <= 0;
+	    if (!tvalid || !tready) begin
+	    //             ^- should not be inverted!
+                state = state ^ state << 13;
+                state = state ^ state >> 7;
+                state = state ^ state << 17;
+		if (state[9:8] == 0) begin
+		    tvalid <= 1;
+		    tdata <= state;
+		end
+	    end
+	end
+    end
+endmodule

docs/resources/PRESENTATION_ExOth/axis_test.v

@@ -0,0 +1,27 @@
+module axis_test(aclk, tready);
+    input aclk, tready;
+    wire aresetn, tvalid;
+    wire [7:0] tdata;
+
+    integer counter = 0;
+    reg aresetn = 0;
+
+    axis_master uut (aclk, aresetn, tvalid, tready, tdata);
+
+    always @(posedge aclk) begin
+    	if (aresetn && tready && tvalid) begin
+	    if (counter == 0) assert(tdata ==  19);
+	    if (counter == 1) assert(tdata ==  99);
+	    if (counter == 2) assert(tdata ==   1);
+	    if (counter == 3) assert(tdata == 244);
+	    if (counter == 4) assert(tdata == 133);
+	    if (counter == 5) assert(tdata == 209);
+	    if (counter == 6) assert(tdata == 241);
+	    if (counter == 7) assert(tdata == 137);
+	    if (counter == 8) assert(tdata == 176);
+	    if (counter == 9) assert(tdata ==   6);
+	    counter <= counter + 1;
+	end
+	aresetn <= 1;
+    end
+endmodule

docs/resources/PRESENTATION_ExOth/axis_test.ys

@@ -0,0 +1,5 @@
+read_verilog -sv axis_master.v axis_test.v
+hierarchy -top axis_test
+
+proc; flatten;;
+sat -falsify -seq 50 -prove-asserts

docs/resources/PRESENTATION_ExOth/equiv.ys

@@ -0,0 +1,17 @@
+# read test design
+read_verilog ../PRESENTATION_ExSyn/techmap_01.v
+hierarchy -top test
+
+# create two version of the design: test_orig and test_mapped
+copy test test_orig
+rename test test_mapped
+
+# apply the techmap only to test_mapped
+techmap -map ../PRESENTATION_ExSyn/techmap_01_map.v test_mapped
+
+# create a miter circuit to test equivalence
+miter -equiv -make_assert -make_outputs test_orig test_mapped miter
+flatten miter
+
+# run equivalence check
+sat -verify -prove-asserts -show-inputs -show-outputs miter

docs/resources/PRESENTATION_ExOth/scrambler.v

@@ -0,0 +1,14 @@
+module scrambler(
+        input clk, rst, in_bit,
+        output reg out_bit
+);
+    reg [31:0] xs;
+    always @(posedge clk) begin
+    	if (rst)
+	    xs = 1;
+        xs = xs ^ (xs << 13);
+        xs = xs ^ (xs >> 17);
+        xs = xs ^ (xs << 5);
+        out_bit <= in_bit ^ xs[0];
+    end
+endmodule

docs/resources/PRESENTATION_ExOth/scrambler.ys

@@ -0,0 +1,23 @@
+
+read_verilog scrambler.v
+
+hierarchy; proc;;
+
+cd scrambler
+submod -name xorshift32 xs %c %ci %D %c %ci:+[D] %D %ci*:-$dff xs %co %ci %d
+cd ..
+
+show -prefix scrambler_p01 -format pdf -notitle scrambler
+show -prefix scrambler_p02 -format pdf -notitle xorshift32
+
+echo on
+
+cd xorshift32
+rename n2 in
+rename n1 out
+
+eval -set in 1 -show out
+eval -set in 270369 -show out
+
+sat -set out 632435482
+

docs/source/using_yosys/more_scripting/selections.rst

@@ -1,6 +1,251 @@
 Selections
-~~~~~~~~~~
+----------
+
+.. TODO: copypaste
+
+
+Most Yosys commands make use of the "selection framework" of Yosys. It can be
+used to apply commands only to part of the design. For example:
+
+.. code:: yoscrypt
+
+    delete                # will delete the whole design, but
+
+    delete foobar         # will only delete the module foobar.
+
+The ``select`` command can be used to create a selection for subsequent
+commands. For example:
+
+.. code:: yoscrypt
+
+    select foobar         # select the module foobar
+    delete                # delete selected objects
+    select -clear         # reset selection (select whole design)
 
 See :doc:`/cmd/select`
 
-Also :doc:`/cmd/show` and :doc:`/cmd/dump`
+How to make a selection
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Selection by object name
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The easiest way to select objects is by object name. This is usually only done
+in synthesis scripts that are hand-tailored for a specific design.
+
+.. code:: yoscrypt
+
+    select foobar         # select module foobar
+    select foo*           # select all modules whose names start with foo
+    select foo*/bar*      # select all objects matching bar* from modules matching foo*
+    select */clk          # select objects named clk from all modules
+
+Module and design context
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Commands can be executed in *module/* or *design/* context. Until now
+all commands have been executed in design context. The ``cd`` command can be
+used to switch to module context.
+
+In module context all commands only effect the active module. Objects in the
+module are selected without the ``<module_name>/`` prefix. For example:
+
+.. code:: yoscrypt
+
+    cd foo                # switch to module foo
+    delete bar            # delete object foo/bar
+
+    cd mycpu              # switch to module mycpu
+    dump reg_*            # print details on all objects whose names start with reg_
+
+    cd ..                 # switch back to design
+
+Note: Most synthesis scripts never switch to module context. But it is a very
+powerful tool for interactive design investigation.
+
+Selecting by object property or type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Special patterns can be used to select by object property or type. For example:
+
+.. code:: yoscrypt
+
+    select w:reg_*        # select all wires whose names start with reg_
+    select a:foobar       # select all objects with the attribute foobar set
+    select a:foobar=42    # select all objects with the attribute foobar set to 42
+    select A:blabla       # select all modules with the attribute blabla set
+    select foo/t:$add     # select all $add cells from the module foo
+
+A complete list of this pattern expressions can be found in the command
+reference to the ``select`` command.
+
+Combining selection
+^^^^^^^^^^^^^^^^^^^
+
+When more than one selection expression is used in one statement, then they are
+pushed on a stack. The final elements on the stack are combined into a union:
+
+.. code:: yoscrypt
+
+    select t:$dff r:WIDTH>1     # all cells of type $dff and/or with a parameter WIDTH > 1
+
+Special ``%``-commands can be used to combine the elements on the stack:
+
+.. code:: yoscrypt
+
+    select t:$dff r:WIDTH>1 %i  # all cells of type $dff *AND* with a parameter WIDTH > 1
+
+Examples for ``%``-codes (see :doc:`/cmd/select` for full list):
+
+- ``%u``: union of top two elements on stack -- pop 2, push 1
+- ``%d``: difference of top two elements on stack -- pop 2, push 1
+- ``%i``: intersection of top two elements on stack -- pop 2, push 1
+- ``%n``: inverse of top element on stack -- pop 1, push 1
+
+Expanding selections
+^^^^^^^^^^^^^^^^^^^^
+
+Selections of cells and wires can be expanded along connections using
+``%``-codes for selecting input cones (``%ci``), output cones (``%co``), or
+both (``%x``).
+
+.. code:: yoscrypt
+
+    # select all wires that are inputs to $add cells
+    select t:$add %ci w:* %i
+
+Additional constraints such as port names can be specified.
+
+.. code:: yoscrypt
+
+    # select all wires that connect a "Q" output with a "D" input
+    select c:* %co:+[Q] w:* %i c:* %ci:+[D] w:* %i %i
+
+    # select the multiplexer tree that drives the signal 'state'
+    select state %ci*:+$mux,$pmux[A,B,Y]
+
+See :doc:`/cmd/select` for full documentation of these expressions.
+
+Incremental selection
+^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes a selection can most easily be described by a series of add/delete
+operations. The commands ``select -add`` and ``select -del`` respectively add or
+remove objects from the current selection instead of overwriting it.
+
+.. code:: yoscrypt
+
+    select -none            # start with an empty selection
+    select -add reg_*       # select a bunch of objects
+    select -del reg_42      # but not this one
+    select -add state %ci   # and add more stuff
+
+Within a select expression the token ``%`` can be used to push the previous selection
+on the stack.
+
+.. code:: yoscrypt
+
+    select t:$add t:$sub    # select all $add and $sub cells
+    select % %ci % %d       # select only the input wires to those cells
+
+Creating selection variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Selections can be stored under a name with the ``select -set <name>``
+command. The stored selections can be used in later select expressions
+using the syntax ``@<name>``.
+
+.. code:: yoscrypt
+
+    select -set cone_a state_a %ci*:-$dff  # set @cone_a to the input cone of state_a
+    select -set cone_b state_b %ci*:-$dff  # set @cone_b to the input cone of state_b
+    select @cone_a @cone_b %i              # select the objects that are in both cones
+
+Remember that select expressions can also be used directly as arguments to most
+commands. Some commands also except a single select argument to some options.
+In those cases selection variables must be used to capture more complex selections.
+
+.. code:: yoscrypt
+
+    dump @cone_a @cone_b
+
+    select -set cone_ab @cone_a @cone_b %i
+    show -color red @cone_ab -color magenta @cone_a -color blue @cone_b
+
+Example:
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/select.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/select.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/select.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExAdv/select.ys``
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/select.*
+    :class: width-helper
+
+Interactive Design Investigation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yosys can also be used to investigate designs (or netlists created from other
+tools).
+
+- The selection mechanism, especially patterns such as ``%ci`` and ``%co``,
+  can be used to figure out how parts of the design are connected.
+- Commands such as ``submod``, ``expose``, and ``splice`` can be used to
+  transform the design into an equivalent design that is easier to analyse.
+- Commands such as ``eval`` and ``sat`` can be used to investigate the behavior
+  of the circuit.
+- :doc:`/cmd/show`.
+- :doc:`/cmd/dump`.
+
+Reorganizing a module
+^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExOth/scrambler.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExOth/scrambler.v``
+
+
+.. code:: yoscrypt
+
+    read_verilog scrambler.v
+
+    hierarchy; proc;;
+
+    cd scrambler
+    submod -name xorshift32 \
+            xs %c %ci %D %c %ci:+[D] %D \
+            %ci*:-$dff xs %co %ci %d
+
+.. figure:: ../../../images/res/PRESENTATION_ExOth/scrambler_p01.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExOth/scrambler_p02.*
+    :class: width-helper
+
+Analysis of circuit behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: text
+
+    > read_verilog scrambler.v
+    > hierarchy; proc;; cd scrambler
+    > submod -name xorshift32 xs %c %ci %D %c %ci:+[D] %D %ci*:-$dff xs %co %ci %d
+
+    > cd xorshift32
+    > rename n2 in
+    > rename n1 out
+
+    > eval -set in 1 -show out
+    Eval result: \out = 270369.
+
+    > eval -set in 270369 -show out
+    Eval result: \out = 67634689.
+
+    > sat -set out 632435482
+    Signal Name                 Dec        Hex                                   Bin
+    -------------------- ---------- ---------- -------------------------------------
+    \in                   745495504   2c6f5bd0      00101100011011110101101111010000
+    \out                  632435482   25b2331a      00100101101100100011001100011010

docs/source/yosys_internals/flow/command_ordering.rst

@@ -0,0 +1,271 @@
+Command ordering
+----------------
+
+.. TODO: copypaste
+
+Intro to coarse-grain synthesis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In coarse-grain synthesis the target architecture has cells of the same
+complexity or larger complexity than the internal RTL representation.
+
+For example:
+
+.. code:: verilog
+
+	wire [15:0] a, b;
+	wire [31:0] c, y;
+	assign y = a * b + c;
+
+This circuit contains two cells in the RTL representation: one multiplier and
+one adder. In some architectures this circuit can be implemented using
+a single circuit element, for example an FPGA DSP core. Coarse grain synthesis
+is this mapping of groups of circuit elements to larger components.
+
+Fine-grain synthesis would be matching the circuit elements to smaller
+components, such as LUTs, gates, or half- and full-adders.
+
+The extract pass
+~~~~~~~~~~~~~~~~
+
+- Like the ``techmap`` pass, the ``extract`` pass is called with a map file. It
+  compares the circuits inside the modules of the map file with the design and
+  looks for sub-circuits in the design that match any of the modules in the map
+  file.
+- If a match is found, the ``extract`` pass will replace the matching subcircuit
+  with an instance of the module from the map file.
+- In a way the ``extract`` pass is the inverse of the techmap pass.
+
+.. TODO: copypaste
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_00a.*
+    :class: width-helper
+    
+    before `extract`
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_00b.*
+    :class: width-helper
+    
+    after `extract`
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_test.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_xmap.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_xmap.v``
+
+.. code:: yoscrypt
+
+    read_verilog macc_simple_test.v
+    hierarchy -check -top test
+
+    extract -map macc_simple_xmap.v;;
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_test_01.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_test_01.v``
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_01a.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_01b.*
+    :class: width-helper
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_simple_test_02.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_simple_test_02.v``
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_02a.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_simple_test_02b.*
+    :class: width-helper
+
+The wrap-extract-unwrap method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Often a coarse-grain element has a constant bit-width, but can be used to
+implement operations with a smaller bit-width. For example, a 18x25-bit multiplier
+can also be used to implement 16x20-bit multiplication.
+
+A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method:
+
+wrap
+  Identify candidate-cells in the circuit and wrap them in a cell with a constant
+  wider bit-width using ``techmap``. The wrappers use the same parameters as the original cell, so
+  the information about the original width of the ports is preserved.
+  Then use the ``connwrappers`` command to connect up the bit-extended in- and
+  outputs of the wrapper cells.
+
+extract
+  Now all operations are encoded using the same bit-width as the coarse grain
+  element. The ``extract`` command can be used to replace circuits with cells
+  of the target architecture.
+
+unwrap
+  The remaining wrapper cell can be unwrapped using ``techmap``.
+
+Example: DSP48_MACC
+~~~~~~~~~~~~~~~~~~~
+
+This section details an example that shows how to map MACC operations of
+arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder
+(such as the Xilinx DSP48 cells).
+
+Preconditioning: ``macc_xilinx_swap_map.v``
+
+Make sure ``A`` is the smaller port on all multipliers
+
+.. TODO: copypaste
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_swap_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_swap_map.v``
+
+Wrapping multipliers: ``macc_xilinx_wrap_map.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v
+   :language: verilog
+   :lines: 1-46
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v``
+
+Wrapping adders: ``macc_xilinx_wrap_map.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v
+   :language: verilog
+   :lines: 48-89
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_wrap_map.v``
+
+Extract: ``macc_xilinx_xmap.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v``
+
+... simply use the same wrapping commands on this module as on the design to create a template for the ``extract`` command.
+
+Unwrapping multipliers: ``macc_xilinx_unwrap_map.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v
+   :language: verilog
+   :lines: 1-30
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v``
+
+Unwrapping adders: ``macc_xilinx_unwrap_map.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v
+   :language: verilog
+   :lines: 32-61
+   :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_unwrap_map.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_test.v
+   :language: verilog
+   :lines: 1-6
+   :caption: ``test1`` of ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_test.v``
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1a.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1b.*
+    :class: width-helper
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/macc_xilinx_test.v
+   :language: verilog
+   :lines: 8-13
+   :caption: ``test2`` of ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_test.v``
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2a.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2b.*
+    :class: width-helper
+
+Wrapping in ``test1``:
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1b.*
+    :class: width-helper
+
+.. code:: yoscrypt
+
+    techmap -map macc_xilinx_wrap_map.v
+
+    connwrappers -unsigned $__mul_wrapper \
+                                Y Y_WIDTH \
+                -unsigned $__add_wrapper \
+                                Y Y_WIDTH ;;
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1c.*
+    :class: width-helper
+
+Wrapping in ``test2``:
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2b.*
+    :class: width-helper
+
+.. code:: yoscrypt
+
+    techmap -map macc_xilinx_wrap_map.v
+
+    connwrappers -unsigned $__mul_wrapper \
+                                Y Y_WIDTH \
+                 -unsigned $__add_wrapper \
+                                Y Y_WIDTH ;;
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2c.*
+    :class: width-helper
+
+Extract in ``test1``:
+
+.. code:: yoscrypt
+
+    design -push
+    read_verilog macc_xilinx_xmap.v
+    techmap -map macc_xilinx_swap_map.v
+    techmap -map macc_xilinx_wrap_map.v;;
+    design -save __macc_xilinx_xmap
+    design -pop
+
+    extract -constports -ignore_parameters \
+            -map %__macc_xilinx_xmap       \
+            -swap $__add_wrapper A,B ;;
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1c.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test1d.*
+    :class: width-helper
+
+Extract in ``test2``:
+
+.. code:: yoscrypt
+
+    design -push
+    read_verilog macc_xilinx_xmap.v
+    techmap -map macc_xilinx_swap_map.v
+    techmap -map macc_xilinx_wrap_map.v;;
+    design -save __macc_xilinx_xmap
+    design -pop
+
+    extract -constports -ignore_parameters \
+            -map %__macc_xilinx_xmap       \
+            -swap $__add_wrapper A,B ;;
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2c.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2d.*
+    :class: width-helper
+
+Unwrap in ``test2``:
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2d.*
+    :class: width-helper
+
+.. figure:: ../../../images/res/PRESENTATION_ExAdv/macc_xilinx_test2e.*
+    :class: width-helper
+
+.. code:: yoscrypt
+
+    techmap -map macc_xilinx_unwrap_map.v ;;

docs/source/yosys_internals/flow/index.rst

@@ -17,4 +17,6 @@ This scripts contain three types of commands:
 	overview
 	control_and_data
 	verilog_frontend
+	command_ordering
+	model_checking
 

docs/source/yosys_internals/flow/model_checking.rst

@@ -0,0 +1,106 @@
+Symbolic model checking
+-----------------------
+
+.. TODO: copypaste
+
+.. note:: 
+    
+    While it is possible to perform model checking directly in Yosys, it 
+    is highly recommended to use SBY or EQY for formal hardware verification.
+
+Symbolic Model Checking (SMC) is used to formally prove that a circuit has (or
+has not) a given property.
+
+One application is Formal Equivalence Checking: Proving that two circuits are
+identical. For example this is a very useful feature when debugging custom
+passes in Yosys.
+
+Other applications include checking if a module conforms to interface standards.
+
+The ``sat`` command in Yosys can be used to perform Symbolic Model Checking.
+
+Checking techmap
+~~~~~~~~~~~~~~~~
+
+Remember the following example from :doc:`/getting_started/typical_phases`?
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExSyn/techmap_01_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExSyn/techmap_01_map.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExSyn/techmap_01.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExSyn/techmap_01.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExSyn/techmap_01.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExSyn/techmap_01.ys``
+
+Lets see if it is correct..
+
+.. code:: yoscrypt
+
+    # read test design
+    read_verilog techmap_01.v
+    hierarchy -top test
+
+    # create two version of the design: test_orig and test_mapped
+    copy test test_orig
+    rename test test_mapped
+
+    # apply the techmap only to test_mapped
+    techmap -map techmap_01_map.v test_mapped
+
+    # create a miter circuit to test equivalence
+    miter -equiv -make_assert -make_outputs test_orig test_mapped miter
+    flatten miter
+
+    # run equivalence check
+    sat -verify -prove-asserts -show-inputs -show-outputs miter
+
+Result:
+
+.. code::
+
+    Solving problem with 945 variables and 2505 clauses..
+    SAT proof finished - no model found: SUCCESS!
+
+AXI4 Stream Master
+~~~~~~~~~~~~~~~~~~
+
+The following AXI4 Stream Master has a bug. But the bug is not exposed if the
+slave keeps ``tready`` asserted all the time. (Something a test bench might do.)
+
+Symbolic Model Checking can be used to expose the bug and find a sequence of
+values for ``tready`` that yield the incorrect behavior.
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExOth/axis_master.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExOth/axis_master.v``
+
+.. literalinclude:: ../../../resources/PRESENTATION_ExOth/axis_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExOth/axis_test.v``
+
+
+.. code:: yoscrypt
+
+    read_verilog -sv axis_master.v axis_test.v
+    hierarchy -top axis_test
+
+    proc; flatten;;
+    sat -seq 50 -prove-asserts
+
+Result with unmodified ``axis_master.v``:
+
+.. code::
+
+    Solving problem with 159344 variables and 442126 clauses..
+    SAT proof finished - model found: FAIL!
+
+Result with fixed ``axis_master.v``:
+
+.. code::
+
+    Solving problem with 159144 variables and 441626 clauses..
+    SAT proof finished - no model found: SUCCESS!

docs/source/yosys_internals/techmap.rst

@@ -31,7 +31,7 @@ provided implementation.
 
 When no map file is provided, techmap uses a built-in map file that maps the
 Yosys RTL cell types to the internal gate library used by Yosys. The curious
-reader may find this map file as techlibs/common/techmap.v in the Yosys source
+reader may find this map file as `techlibs/common/techmap.v` in the Yosys source
 tree.
 
 Additional features have been added to techmap to allow for conditional mapping
@@ -105,3 +105,186 @@ reporting bugs in the tools involved. When the information in the Liberty file
 used by Yosys and ABC are not part of the sensitive information, the additional
 tool yosys-filterlib (see :ref:`sec:filterlib`) can be used to strip the
 sensitive information from the Liberty file.
+
+Techmap by example
+------------------
+
+.. TODO: copypaste
+
+As a quick recap, the ``techmap`` command replaces cells in the design with
+implementations given as Verilog code (called "map files"). It can replace
+Yosys' internal cell types (such as ``$or``) as well as user-defined cell
+types.
+
+- Verilog parameters are used extensively to customize the internal cell types.
+- Additional special parameters are used by techmap to communicate meta-data to
+  the map files.
+- Special wires are used to instruct techmap how to handle a module in the map
+  file.
+- Generate blocks and recursion are powerful tools for writing map files.
+
+Mapping OR3X1
+~~~~~~~~~~~~~
+
+.. note::
+
+    This is a simple example for demonstration only.  Techmap shouldn't be used
+    to implement basic logic optimization.
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/red_or3x1_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/red_or3x1_map.v``
+
+.. figure:: ../../images/res/PRESENTATION_ExAdv/red_or3x1.*
+    :class: width-helper
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/red_or3x1_test.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExAdv/red_or3x1_test.ys``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/red_or3x1_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/red_or3x1_test.v``
+
+Conditional techmap
+~~~~~~~~~~~~~~~~~~~
+
+- In some cases only cells with certain properties should be substituted.
+- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module
+  in the map file for a certain set of parameters.
+- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it
+  is non-zero then the module is disabled for this set of parameters.
+- Example use-cases:
+
+    - coarse-grain cell types that only operate on certain bit widths
+    - memory resources for different memory geometries (width, depth, ports, etc.)
+
+Example:
+
+.. figure:: ../../images/res/PRESENTATION_ExAdv/sym_mul.*
+    :class: width-helper
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/sym_mul_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/sym_mul_map.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/sym_mul_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/sym_mul_test.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/sym_mul_test.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExAdv/sym_mul_test.ys``
+
+
+Scripting in map modules
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts
+  in the context of the replacement module.
+- The wire that comes first in alphabetical oder is interpreted as string (must
+  be connected to constants) that is executed as script. Then the wire is
+  removed. Repeat.
+- You can even call techmap recursively!
+- Example use-cases:
+
+    - Using always blocks in map module: call ``proc``
+    - Perform expensive optimizations (such as ``freduce``) on cells where
+      this is known to work well.
+    - Interacting with custom commands.
+
+.. note:: PROTIP: 
+    Commands such as ``shell``, ``show -pause``, and ``dump`` can be use
+    in the ``_TECHMAP_DO_*`` scripts for debugging map modules.
+
+Example:
+
+.. figure:: ../../images/res/PRESENTATION_ExAdv/mymul.*
+    :class: width-helper
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mymul_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/mymul_map.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mymul_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/mymul_test.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mymul_test.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExAdv/mymul_test.ys``
+
+Handling constant inputs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The special parameters ``_TECHMAP_CONSTMSK_<port-name>_`` and
+  ``_TECHMAP_CONSTVAL_<port-name>_`` can be used to handle constant input values
+  to cells.
+- The former contains 1-bits for all constant input bits on the port.
+- The latter contains the constant bits or undef (x) for non-constant bits.
+- Example use-cases:
+
+    - Converting arithmetic (for example multiply to shift).
+    - Identify constant addresses or enable bits in memory interfaces.
+
+Example:
+
+.. figure:: ../../images/res/PRESENTATION_ExAdv/mulshift.*
+    :class: width-helper
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mulshift_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/mulshift_map.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mulshift_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/mulshift_test.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/mulshift_test.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExAdv/mulshift_test.ys``
+
+Handling shorted inputs
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- The special parameters ``_TECHMAP_BITS_CONNMAP_`` and
+  ``_TECHMAP_CONNMAP_<port-name>_`` can be used to handle shorted inputs.
+- Each bit of the port correlates to an ``_TECHMAP_BITS_CONNMAP_`` bits wide
+  number in ``_TECHMAP_CONNMAP_<port-name>_``.
+- Each unique signal bit is assigned its own number. Identical fields in the ``_TECHMAP_CONNMAP_<port-name>_`` parameters mean shorted signal bits.
+- The numbers 0-3 are reserved for ``0``, ``1``, ``x``, and ``z`` respectively.
+- Example use-cases:
+
+    - Detecting shared clock or control signals in memory interfaces.
+    - In some cases this can be used for for optimization.
+
+Example:
+
+.. figure:: ../../images/res/PRESENTATION_ExAdv/addshift.*
+    :class: width-helper
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/addshift_map.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/addshift_map.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/addshift_test.v
+   :language: verilog
+   :caption: ``docs/resources/PRESENTATION_ExAdv/addshift_test.v``
+
+.. literalinclude:: ../../resources/PRESENTATION_ExAdv/addshift_test.ys
+   :language: yoscrypt
+   :caption: ``docs/resources/PRESENTATION_ExAdv/addshift_test.ys``
+
+Notes on using techmap
+~~~~~~~~~~~~~~~~~~~~~~
+
+- Don't use positional cell parameters in map modules.
+- You can use the ``$__``-prefix for internal cell types to avoid
+  collisions with the user-namespace. But always use two underscores or the
+  internal consistency checker will trigger on this cells.
+- Techmap has two major use cases:
+
+    - Creating good logic-level representation of arithmetic functions. This
+      also means using dedicated hardware resources such as half- and full-adder
+      cells in ASICS or dedicated carry logic in FPGAs.
+    - Mapping of coarse-grain resources such as block memory or DSP cells.