hdl-diagram

The hdl-diagram RST directive can be used to generate a diagram from HDL code and include it in your documentation.

.. hdl-diagram:: file.v
   :type: XXXXX
   :module: XXXX
   :flatten:

Note

The verilog-diagram directive is kept as an alias of this directive for compatibility purposes.

Options

:type: - Verilog Diagram Types;

  • yosys-blackbox - Netlist rendered by Yosys.

  • yosys-aig - Verilog file run through aigmap before image is generated directly in Yosys.

  • netlistsvg - Render output with netlistsvg

:module: - Which module to diagram.

:flatten: - Use the Yosys flatten command before generating the image.

Input Formats

This directive supports 3 input formats: Verilog code, nMigen code, and RTLIL.

Verilog

19module top (
20	input  clk,
21	output o
22);
23	reg [2:0] counter = 0;
24	always @(posedge clk)
25		counter <= counter + 1;
26	assign o = counter[2];
27endmodule
1.. hdl-diagram:: ../code/verilog/counter.v
2   :type: netlistsvg
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-hdl-diagrams/checkouts/latest/docs/code/verilog/counter.v

nMigen

21from nmigen import *
22from nmigen.back import rtlil
23
24
25class Counter(Elaboratable):
26    def __init__(self, width):
27        self.v = Signal(width, reset=2**width-1)
28        self.o = Signal()
29
30    def elaborate(self, platform):
31        m = Module()
32        m.d.sync += self.v.eq(self.v + 1)
33        m.d.comb += self.o.eq(self.v[-1])
34        return m
35
36
37ctr = Counter(width=16)
38print(rtlil.convert(ctr, ports=[ctr.o]))
1.. hdl-diagram:: ../code/nmigen/counter.py
2   :type: netlistsvg
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-hdl-diagrams/checkouts/latest/docs/code/nmigen/counter.py

Note

As hdl-diagram expects the nMigen script to write RTLIL code to stdout, make sure to include the following lines of code.

1from nmigen.back import rtlil
2print(rtlil.convert(..., ports=[...]))

RTLIL

 1attribute \generator "nMigen"
 2attribute \top 1
 3attribute \nmigen.hierarchy "top"
 4module \top
 5  attribute \src "counter.py:9"
 6  wire width 1 output 0 \o
 7  attribute \src "/usr/local/lib/python3.7/site-packages/nmigen/hdl/ir.py:526"
 8  wire width 1 input 1 \clk
 9  attribute \src "/usr/local/lib/python3.7/site-packages/nmigen/hdl/ir.py:526"
10  wire width 1 input 2 \rst
11  attribute \src "counter.py:8"
12  wire width 16 \v
13  attribute \src "counter.py:8"
14  wire width 16 \v$next
15  attribute \src "counter.py:13"
16  wire width 17 $1
17  attribute \src "counter.py:13"
18  wire width 17 $2
19  attribute \src "counter.py:13"
20  cell $add $3
21    parameter \A_SIGNED 1'0
22    parameter \A_WIDTH 5'10000
23    parameter \B_SIGNED 1'0
24    parameter \B_WIDTH 1'1
25    parameter \Y_WIDTH 5'10001
26    connect \A \v
27    connect \B 1'1
28    connect \Y $2
29  end
30  connect $1 $2
31  process $group_0
32    assign \v$next \v
33    assign \v$next $1 [15:0]
34    attribute \src "/usr/local/lib/python3.7/site-packages/nmigen/hdl/xfrm.py:530"
35    switch \rst
36      case 1'1
37        assign \v$next 16'1111111111111111
38    end
39    sync init
40      update \v 16'1111111111111111
41    sync posedge \clk
42      update \v \v$next
43  end
44  process $group_1
45    assign \o 1'0
46    assign \o \v [15]
47    sync init
48  end
49end
1.. hdl-diagram:: ../code/rtlil/counter.il
2   :type: netlistsvg
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-hdl-diagrams/checkouts/latest/docs/code/rtlil/counter.il

Diagram Types

Yosys BlackBox Diagram

RST Directive

1.. hdl-diagram:: ../code/verilog/dff.v
2   :type: yosys-bb

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-hdl-diagrams/checkouts/latest/docs/code/verilog/dff.v

Yosys AIG Diagram

RST Directive

1.. hdl-diagram:: ../code/verilog/dff.v
2   :type: yosys-aig

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-hdl-diagrams/checkouts/latest/docs/code/verilog/dff.v

NetlistSVG Diagram

RST Directive

1.. hdl-diagram:: ../code/verilog/dff.v
2   :type: netlistsvg

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-hdl-diagrams/checkouts/latest/docs/code/verilog/dff.v