sync_up: Added Dmitry, Sadoon

[libreriscv.git] / docs / learning_nmigen.mdwn

diff --git a/docs/learning_nmigen.mdwn b/docs/learning_nmigen.mdwn
index 14e7bffa150d003fcb9489f24f6efd401c4e7775..746d675d8eecf9c29f8f84aa9e2341924dbfd127 100644 (file)
--- a/docs/learning_nmigen.mdwn
+++ b/docs/learning_nmigen.mdwn
@@ -1,11 +1,12 @@
 # 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>
@@ -14,46 +15,48 @@
 
 ## Testbench, GTKWave, Verilog Output 
 
-* nMigen code for counter and testbench here: <https://nmigen.info/nmigen/latest/start.html>
+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 for the counter module (better get used to separating your sim/stimulus and module classes from the beginning):
 
-    from up_counter import UpCounter
+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:
+1. Generate GTKWave .vcd file by running the testbench script.
 
-    $python3 tb_up_counter.py
+1. Launch GTKWave. Now you should be able to inspect the signals and check counter behaviour (although the test bench also does this).
 
-1. Launch GTKWave by calling:
+1. To generate the verilog equivalent, call the file we created earlier. The script will create a up_counter.v verilog file.
 
-    $gtkwave up_counter.vcd
+Commands:
 
-1. Now you should be able to inspect the signals and check counter behaviour (although the test bench also does this).
+    $ python3 tb_up_counter.py
+    $ gtkwave up_counter.vcd &
+    $ python3 conv_to_verilog.py
 
-1. To generate the verilog equivalent, call the file we created earlier. The script will create a up_counter.v verilog file.
+## Block Digram with Yosys
 
-    $python3 conv_to_verilog.py
+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).
 
-## Block Digram with Yosys
+*You may need to install xdot separately with apt*. Xdot is **interactive** (you can click on blocks and nodes!).
 
-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 commands:
 
-    $yosys
+    $ yosys
     yosys> read_verilog up_counter.v
     yosys> show
 
-1. Outside of Yosys, you can run xdot directly:
-
-    $xdot ~/.yosys_show.dot
+Outside of Yosys, commands for diagram (SVG format for static images also supported):
 
-1. If you want to generate a static image, you can use graphviz's "dot" command to generate an image (for example PNG).
+    $ xdot ~/.yosys_show.dot
+    $ dot ~/.yosys_show.dot -Tpng -o up_counter.png
 
-    $dot ~/.yosys_show.dot -Tpng -o up_counter.png
+Here's a sight to behold:
 
-1. Now you can improve your understanding with the nMigen, verilog, and block diagram views side-by-side!
+[[!img nmigen_verilog_tb.png size="600x"]]
 
-[[!img nmigen_verilog_tb.png ]]
\ No newline at end of file
+Now you can improve your understanding with the nMigen, verilog, and block diagram views side-by-side!