Skip to main content

Generate diagrams from HDL in Sphinx.

Project description

PyPI PyPI version Documentation Build Status codecov

Sphinx Extension which generates various types of diagrams from HDL code, supporting Verilog, nMigen and RTLIL.

sphinxcontrib-hdl-diagrams is a Sphinx extension to make it easier to write nice documentation from HDL source files. It primarily uses Yosys to read the source files and generate the diagrams.

Check out the documentation for examples.

Installation

Python 3.5+ is required.

pip install sphinxcontrib-hdl-diagrams

Or,

python3 -m pip install sphinxcontrib-hdl-diagrams

Sphinx Integration

In your conf.py, add the following lines.

extensions = [
    ...,
    'sphinxcontrib_hdl_diagrams',
]

Non-Python Dependencies

These dependencies can be either installed on your system or install using the conda environment.yml file with;

conda XXXX

Required

By default, verilog-diagram uses the yowasp-yosys package provided in PyPI. It can be installed by running pip install -r requirements.txt. However, you could also use Yosys that is installed on your system, or point to the specific Yosys binary using verilog_diagram_yosys variable in the Sphinx conf.py file:

To use Yosys that is available in your system, use the following setting:

verilog_diagram_yosys = "system"

If you want to point to the specific Yosys binary, provide the path to the program:

verilog_diagram_yosys = "<path-to-Yosys>"

Optional

Usage

hdl-diagram

The hdl-diagram RST directive can be used to generate a diagram from Verilog code and include it in your documentation. Check out the examples to see how to use it.

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

Options

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

Example

Here is a diagram of a 4-bit carry chain.

4-bit carry chain

no-license

This extension also provides the no-license directive which can be used to include code blocks from a file, but omitting the license header at the top of the file. It behaves like the literalinclude directive, but the lines option is overridden to only show the lines after the license header.

.. no-license:: verilog/dff.v
   :language: verilog
   :linenos:
   :caption: verilog/dff.v

Example

Here is a comparison between the literalinclude and no-license directives.

.. literalinclude:: verilog/dff.v
   :language: verilog
   :caption: verilog/dff.v
/*
 * Copyright (C) 2020-2021  The SymbiFlow Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

// Single flip-flip test.
module top(input clk, input di, output do);
  always @( posedge clk )
    do <= di;
endmodule // top
.. no-license:: verilog/dff.v
   :language: verilog
   :caption: verilog/dff.v
// Single flip-flip test.
module top(input clk, input di, output do);
  always @( posedge clk )
    do <= di;
endmodule // top

Licence

Apache 2.0

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-hdl-diagrams-0.0.post148.tar.gz (13.9 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file sphinxcontrib-hdl-diagrams-0.0.post148.tar.gz.

File metadata

  • Download URL: sphinxcontrib-hdl-diagrams-0.0.post148.tar.gz
  • Upload date:
  • Size: 13.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.6.4 pkginfo/1.7.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

File hashes

Hashes for sphinxcontrib-hdl-diagrams-0.0.post148.tar.gz
Algorithm Hash digest
SHA256 1253a2cb50ee42369b41e82f0375d907d9980968e74fcb24a68a30489ef619ce
MD5 c2d7fbac9d2436adedecf364ee4a22b8
BLAKE2b-256 8c015c6800faf89032c5a5c9eef6172ddb6066dc0521019b1c610b0f2d68998a

See more details on using hashes here.

File details

Details for the file sphinxcontrib_hdl_diagrams-0.0.post148-py3-none-any.whl.

File metadata

  • Download URL: sphinxcontrib_hdl_diagrams-0.0.post148-py3-none-any.whl
  • Upload date:
  • Size: 13.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.6.4 pkginfo/1.7.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

File hashes

Hashes for sphinxcontrib_hdl_diagrams-0.0.post148-py3-none-any.whl
Algorithm Hash digest
SHA256 c1f8231f0100dc3cb6d13b797c00fd1be36aa37c53dbad2d1d82f8bf9e041bb8
MD5 6dcc28dd7ac891d7e4948e25a148db43
BLAKE2b-256 5b3382a0d6d0f1397b035e1c0a27133fd34cc4631b9613c341659a18dfece712

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page