From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Sun, 10 Oct 2021 10:54:32 +0000 (+0100)
Subject: Added basic tutorial for generating verilog, vcd, dot diagram
X-Git-Tag: opf_rfc_ls005_v1~3667
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=d2574c9f02f98145aa12612dec108c0c8aa290ca;p=libreriscv.git

Added basic tutorial for generating verilog, vcd, dot diagram
---

diff --git a/docs/learning_nmigen.mdwn b/docs/learning_nmigen.mdwn
index 4f7ae97b6..14e7bffa1 100644
--- a/docs/learning_nmigen.mdwn
+++ b/docs/learning_nmigen.mdwn
@@ -9,3 +9,51 @@
 * <https://github.com/kbob/nmigen-examples>
 * <https://vivonomicon.com/2020/04/14/learning-fpga-design-with-nmigen/54>
 * <https://www.youtube.com/watch?v=yDJNwxY05-s>
+
+# Sanity Check (*You'll need it*) Tutorial - Simulation Waveforms, Verilog, Block Diagram
+
+## Testbench, GTKWave, Verilog Output 
+
+* nMigen code for counter and testbench here: <https://nmigen.info/nmigen/latest/start.html>
+
+1. Create a file called "up_counter.py" containing the 16-bit up counter code from "Implementing a counter" section.
+1. Create a file called "tb_up_counter.py" containing the testbench from "Testing a counter".
+1. To the testbench file, add the import statement for the counter module (better get used to separating your sim/stimulus and module classes from the beginning):
+
+    from up_counter import UpCounter
+
+1. Create a file called "conv_to_verilog.py" and copy the code from "Converting a counter" section. Also add the import statement as with the testbench.
+
+1. Generate GTKWave .vcd file by running:
+
+    $python3 tb_up_counter.py
+
+1. Launch GTKWave by calling:
+
+    $gtkwave up_counter.vcd
+
+1. Now you should be able to inspect the signals and check counter behaviour (although the test bench also does this).
+
+1. To generate the verilog equivalent, call the file we created earlier. The script will create a up_counter.v verilog file.
+
+    $python3 conv_to_verilog.py
+
+## Block Digram with Yosys
+
+1. Open yosys in interactive mode and load the generated verilog file. Calling "show" should generate the diagram .dot file (as a temp file "~/.yosys_show.dot") and open it using xdot. *You may need to install xdot separately with apt*. Xdot is **interactive** (you can click on blocks and nodes!).
+
+    $yosys
+    yosys> read_verilog up_counter.v
+    yosys> show
+
+1. Outside of Yosys, you can run xdot directly:
+
+    $xdot ~/.yosys_show.dot
+
+1. If you want to generate a static image, you can use graphviz's "dot" command to generate an image (for example PNG).
+
+    $dot ~/.yosys_show.dot -Tpng -o up_counter.png
+
+1. Now you can improve your understanding with the nMigen, verilog, and block diagram views side-by-side!
+
+[[!img nmigen_verilog_tb.png ]]
\ No newline at end of file
diff --git a/docs/nmigen_verilog_tb.png b/docs/nmigen_verilog_tb.png
new file mode 100644
index 000000000..ae36a68a0
Binary files /dev/null and b/docs/nmigen_verilog_tb.png differ