跳转到主要内容

从Sphinx生成HDL图表。

项目描述

PyPI PyPI version Documentation Build Status codecov

Sphinx扩展,可以从HDL代码生成各种类型的图表,支持Verilog、nMigen和RTLIL。

sphinxcontrib-hdl-diagrams 是一个 Sphinx 扩展,用于简化从 HDL 源文件编写良好文档的过程。它主要使用 Yosys 来读取源文件并生成图表。

请查看文档以获取示例。

安装

需要 Python 3.5+。

pip install sphinxcontrib-hdl-diagrams

或者,

python3 -m pip install sphinxcontrib-hdl-diagrams

Sphinx 集成

在你的 conf.py 中添加以下行。

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

非 Python 依赖项

这些依赖项可以安装在你的系统上,或者使用 conda environment.yml 文件安装;

conda XXXX

必需

默认情况下,verilog-diagram 使用 PyPI 中提供的 yowasp-yosys 包。可以通过运行 pip install -r requirements.txt 来安装。然而,你也可以使用系统中安装的 Yosys,或者通过 Sphinx conf.py 文件中的 verilog_diagram_yosys 变量指向特定的 Yosys 可执行文件。

要使用系统中可用的 Yosys,使用以下设置

verilog_diagram_yosys = "system"

如果你想指向特定的 Yosys 可执行文件,请提供程序的路径

verilog_diagram_yosys = "<path-to-Yosys>"

可选

用法

hdl-diagram

可以使用 hdl-diagram RST 指令从 Verilog 代码生成图表并将其包含在文档中。查看示例以了解如何使用它。

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

选项

:type: - HDL 图表类型;

  • yosys-blackbox - 由 Yosys 渲染的网表。

  • yosys-aig - 在 Yosys 中直接生成图像之前,通过 aigmap 运行的 Verilog 文件。

  • netlistsvg - 使用 netlistsvg 渲染输出。

:module: - 要绘制哪个模块。

:flatten: - 在生成图像之前使用 Yosys 的 flatten 命令。

示例

这是一个 4 位进位链的图表。

4-bit carry chain

no-license

此扩展还提供了 no-license 指令,可以用于包含来自文件的代码块,但省略文件顶部的许可证头部。它的行为类似于 literalinclude 指令,但 lines 选项被覆盖,以仅显示许可证头部之后的行。

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

示例

以下是 literalincludeno-license 指令的比较。

.. 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://apache.ac.cn/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

许可证

Apache 2.0

项目详情


下载文件

下载适合您平台的文件。如果您不确定该选择哪个,请了解更多关于 安装包 的信息。

源代码分发

sphinxcontrib-hdl-diagrams-0.0.post160.tar.gz (15.4 kB 查看哈希值)

上传时间 源码

构建版本

sphinxcontrib_hdl_diagrams-0.0.post160-py3-none-any.whl (13.7 kB 查看哈希值)

上传时间 Python 3

支持者