Switching example synth to fifo

Fifo code based on SBY quick start.
Instead of showing the full design we are (currently) focusing on a single output (rdata), using `%ci*` to get the subcircuit it relies on.

docs/source/code_examples/fifo/Makefile

@@ -0,0 +1,16 @@
+PROGRAM_PREFIX :=
+
+YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
+
+DOTS = addr_gen_hier.dot addr_gen_proc.dot
+DOTS += rdata_proc.dot rdata_flat.dot
+DOTS += fifo_flat.dot fifo_synth.dot
+
+dots: $(DOTS) fifo.out
+
+$(DOTS) fifo.out: fifo.v fifo.ys
+	$(YOSYS) fifo.ys -l fifo.out -Q
+
+.PHONY: clean
+clean:
+	rm -f *.dot

docs/source/code_examples/fifo/fifo.v

@@ -0,0 +1,73 @@
+// address generator/counter
+module addr_gen 
+#(  parameter MAX_DATA=256
+) ( input en, clk, rst,
+	output reg [AWIDTH-1:0] addr
+);
+	localparam AWIDTH = $clog2(MAX_DATA);
+
+	initial addr <= 0;
+
+	// async reset
+	// increment address when enabled
+	always @(posedge clk or posedge rst)
+		if (rst)
+			addr <= 0;
+		else if (en) begin
+			if (addr == MAX_DATA-1)
+				addr <= 0;
+			else
+				addr <= addr + 1;
+		end
+endmodule //addr_gen
+
+// Define our top level fifo entity
+module fifo 
+#(  parameter MAX_DATA=256
+) ( input wen, ren, clk, rst,
+	input [7:0] wdata,
+	output reg [7:0] rdata,
+	output reg [AWIDTH:0] count
+);
+	localparam AWIDTH = $clog2(MAX_DATA);
+
+	// fifo storage
+	// sync read before write
+	wire [AWIDTH-1:0] waddr, raddr;
+	reg [7:0] data [MAX_DATA-1:0];
+	always @(posedge clk) begin
+		if (wen)
+			data[waddr] <= wdata;
+		rdata <= data[raddr];
+	end // storage
+
+	// addr_gen for both write and read addresses
+	addr_gen #(.MAX_DATA(MAX_DATA))
+	fifo_writer (
+		.en     (wen),
+		.clk    (clk),
+		.rst    (rst),
+		.addr   (waddr)
+	);
+
+	addr_gen #(.MAX_DATA(MAX_DATA))
+	fifo_reader (
+		.en     (ren),
+		.clk    (clk),
+		.rst    (rst),
+		.addr   (raddr)
+	);
+
+	// status signals
+	initial count <= 0;
+
+	always @(posedge clk or posedge rst) begin
+		if (rst)
+			count <= 0;
+		else if (wen && !ren)
+			count <= count + 1;
+		else if (ren && !wen)
+			count <= count - 1;
+	end
+
+endmodule

docs/source/code_examples/fifo/fifo.ys

@@ -0,0 +1,39 @@
+# ========================================================
+# throw in some extra text to match what we expect if we were opening an
+# interactive terminal
+log $ yosys fifo.v
+log 
+log -- Parsing `fifo.v' using frontend ` -vlog2k' --
+read_verilog -defer fifo.v
+
+# turn command echoes on to use the log output as a console session
+echo on
+hierarchy -top addr_gen
+show -notitle -format dot -prefix addr_gen_hier
+
+# ========================================================
+proc
+show -notitle -format dot -prefix addr_gen_proc
+
+# ========================================================
+design -reset
+read_verilog fifo.v
+hierarchy -check -top fifo
+proc
+show -notitle -format dot -prefix rdata_proc o:rdata %ci*
+
+# ========================================================
+
+flatten
+show -notitle -format dot -prefix rdata_flat o:rdata %ci*
+
+# ========================================================
+
+opt_clean
+show -notitle -format dot -prefix fifo_flat
+
+design -reset
+read_verilog fifo.v
+synth_ice40 -dsp -top fifo
+show -notitle -format dot -prefix fifo_synth
+stat