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
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
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
Diagram Types¶
Yosys BlackBox Diagram¶
RST Directive¶
1.. hdl-diagram:: ../code/verilog/dff.v
2 :type: yosys-bb
Result¶
Yosys AIG Diagram¶
RST Directive¶
1.. hdl-diagram:: ../code/verilog/dff.v
2 :type: yosys-aig
Result¶
NetlistSVG Diagram¶
RST Directive¶
1.. hdl-diagram:: ../code/verilog/dff.v
2 :type: netlistsvg