bug 1048, ls011: Add Fixed Load Shifted Post-Update section

[libreriscv.git] / docs / learning_nmigen.mdwn

diff --git a/docs/learning_nmigen.mdwn b/docs/learning_nmigen.mdwn
index 4f7ae97b69c624da6e6e1aedbd04ce768a6f767d..746d675d8eecf9c29f8f84aa9e2341924dbfd127 100644 (file)
--- a/docs/learning_nmigen.mdwn
+++ b/docs/learning_nmigen.mdwn
@@ -1,11 +1,62 @@
 # Learning nmigen
 
-* links to community <https://nmigen.info/nmigen/latest/tutorial.html>
-* Useful counter tutorial (gtkwave and verilog) for latest nmigen <https://nmigen.info/nmigen/latest/start.html>
+* Link to the mail thread: <http://lists.libre-soc.org/pipermail/libre-soc-dev/2021-October/003858.html>
+* Links to community <https://gitlab.com/nmigen/nmigen/blob/master/docs/tutorial.rst>
+* Useful counter tutorial (gtkwave and verilog) for latest nmigen
+  <https://gitlab.com/nmigen/nmigen/blob/master/docs/start.rst>
 * Robert Baruch's nmigen tutorials are really good:
   <https://github.com/RobertBaruch/nmigen-tutorial>
 * <https://github.com/GuzTech/ulx3s-nmigen-examples>
-* <https://github.com/icebreaker-fpga/icebreaker-nmigen-examples>
 * <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://gitlab.com/nmigen/nmigen/blob/master/docs/start.rst>
+
+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 "from up_counter import UpCounter" for the counter module (better get used to separating your sim/stimulus and module classes from the beginning):
+
+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 the testbench script.
+
+1. Launch GTKWave. 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.
+
+Commands:
+
+    $ python3 tb_up_counter.py
+    $ gtkwave up_counter.vcd &
+    $ python3 conv_to_verilog.py
+
+## Block Digram with Yosys
+
+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. For multi-level modules, you can specify the level of hierarchy by specifying the name of the module. For example "show top" will display the diagram of the top-level (without the underlying the details of the sub-modules).
+
+*You may need to install xdot separately with apt*. Xdot is **interactive** (you can click on blocks and nodes!).
+
+Yosys commands:
+
+    $ yosys
+    yosys> read_verilog up_counter.v
+    yosys> show
+
+Outside of Yosys, commands for diagram (SVG format for static images also supported):
+
+    $ xdot ~/.yosys_show.dot
+    $ dot ~/.yosys_show.dot -Tpng -o up_counter.png
+
+Here's a sight to behold:
+
+[[!img nmigen_verilog_tb.png size="600x"]]
+
+Now you can improve your understanding with the nMigen, verilog, and block diagram views side-by-side!