Sphinx Verilog Diagrams

sphinx-verilog-diagrams is an extension to Sphinx to make it easier to write nice documentation from Verilog files.

You use the .. verilog-diagram RST directive to generate various styles of diagrams from verilog code.

Usage Examples

Single DFF

Verilog Code

RST Directive

1
2
3
4
.. literalinclude:: verilog/dff.v
   :language: verilog
   :linenos:
   :caption: verilog/dff.v

Result

verilog/dff.v
1
2
3
4
5
// Single flip-flip test.
module top(input clk, input di, output do);
  always @( posedge clk )
    do <= di;
endmodule // top

Yosys BlackBox Diagram

RST Directive

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

Result

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

Yosys AIG Diagram

RST Directive

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

Result

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

NetlistSVG Diagram

RST Directive

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

Result

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

Combinational Full Adder

Verilog Code

RST Directive

1
2
3
4
.. literalinclude:: verilog/adder.v
   :language: verilog
   :linenos:
   :caption: verilog/adder.v

Result

verilog/adder.v
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
module ADDER (
	a, b, cin,
	sum, cout
);
	input wire a;
	input wire b;
	input wire cin;

	output wire sum;
	output wire cout;

	// Full adder combinational logic
	assign sum = a ^ b ^ cin;
	assign cout = ((a ^ b) & cin) | (a & b);
endmodule

Yosys BlackBox Diagram

RST Directive

1
2
3
.. verilog-diagram:: verilog/adder.v
   :type: yosys-bb
   :module: ADDER

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/adder.v

Yosys AIG Diagram

RST Directive

1
2
3
.. verilog-diagram:: verilog/adder.v
   :type: yosys-aig
   :module: ADDER

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/adder.v

NetlistSVG Diagram

RST Directive

1
2
3
.. verilog-diagram:: verilog/adder.v
   :type: netlistsvg
   :module: ADDER

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/adder.v

NetlistSVG Demos

CARRY4 defined directly

Verilog Code

verilog/carry4-whole.v
1
2
3
4
5
6
7
module CARRY4(output [3:0] CO, O, input CI, CYINIT, input [3:0] DI, S);
  assign O = S ^ {CO[2:0], CI | CYINIT};
  assign CO[0] = S[0] ? CI | CYINIT : DI[0];
  assign CO[1] = S[1] ? CO[0] : DI[1];
  assign CO[2] = S[2] ? CO[1] : DI[2];
  assign CO[3] = S[3] ? CO[2] : DI[3];
endmodule

RST Directive

1
2
3
4
.. verilog-diagram:: verilog/carry4-whole.v
   :type: netlistsvg
   :module: CARRY4
   :caption: carry4-whole.v

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/carry4-whole.v

carry4-whole.v

CARRY4 defined by components

Verilog Code

verilog/carry4-bits.v
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
`include "muxcy.v"
`include "xorcy.v"

module CARRY4(output [3:0] CO, O, input CI, CYINIT, input [3:0] DI, S);
   wire CIN = CI | CYINIT;

   MUXCY muxcy0 (.O(CO[0]), .CI(CIN),   .DI(DI[0]), .S(S[0]));
   MUXCY muxcy1 (.O(CO[1]), .CI(CO[0]), .DI(DI[1]), .S(S[1]));
   MUXCY muxcy2 (.O(CO[2]), .CI(CO[1]), .DI(DI[2]), .S(S[2]));
   MUXCY muxcy3 (.O(CO[3]), .CI(CO[2]), .DI(DI[3]), .S(S[3]));

   XORCY xorcy0 (.O(O[0]), .CI(CIN),   .LI(S[0]));
   XORCY xorcy1 (.O(O[1]), .CI(CO[0]), .LI(S[1]));
   XORCY xorcy2 (.O(O[2]), .CI(CO[1]), .LI(S[2]));
   XORCY xorcy3 (.O(O[3]), .CI(CO[2]), .LI(S[3]));
endmodule
verilog/muxcy.v
1
2
3
module MUXCY(output O, input CI, DI, S);
  assign O = S ? CI : DI;
endmodule
verilog/xorcy.v
1
2
3
module XORCY(output O, input CI, LI);
  assign O = CI ^ LI;
endmodule

Bits of CARRY4

1
2
3
4
.. verilog-diagram:: verilog/muxcy.v
   :type: netlistsvg
   :caption: muxcy.v
   :module: MUXCY

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/muxcy.v

muxcy.v

1
2
3
4
.. verilog-diagram:: verilog/xorcy.v
   :type: netlistsvg
   :caption: xorcy.v
   :module: XORCY

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/xorcy.v

xorcy.v

RST Directive

1
2
3
4
.. verilog-diagram:: verilog/carry4-bits.v
   :type: netlistsvg
   :module: CARRY4
   :caption: carry4-bits.v without flatten

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/carry4-bits.v

carry4-bits.v without flatten

RST Directive

1
2
3
4
5
.. verilog-diagram:: verilog/carry4-bits.v
   :type: netlistsvg
   :module: CARRY4
   :flatten:
   :caption: carry4-bits.v with flatten

Result

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-verilog-diagrams/checkouts/latest/docs/verilog/carry4-bits.v

carry4-bits.v with flatten