Learning nmigen

• 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/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.

2. Create a file called "tb_up_counter.py" containing the testbench from "Testing a counter".

3. 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):

4. 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.

5. Generate GTKWave .vcd file by running the testbench script.

6. Launch GTKWave. Now you should be able to inspect the signals and check counter behaviour (although the test bench also does this).

7. 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:

Now you can improve your understanding with the nMigen, verilog, and block diagram views side-by-side!