Sphinx HDL Diagrams
Sphinx HDL Diagrams

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

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

nMigen

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
from nmigen import *
from nmigen.back import rtlil


class Counter(Elaboratable):
    def __init__(self, width):
        self.v = Signal(width, reset=2**width-1)
        self.o = Signal()

    def elaborate(self, platform):
        m = Module()
        m.d.sync += self.v.eq(self.v + 1)
        m.d.comb += self.o.eq(self.v[-1])
        return m


ctr = Counter(width=16)
print(rtlil.convert(ctr, ports=[ctr.o]))
1
2
.. hdl-diagram:: ../code/nmigen/counter.py
   :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.

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

RTLIL

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

Result

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