Documentation for SystemVerilog projects that use Bender. One command makes a web site that joins the text a person wrote with the facts that the RTL gives.
Open the example site — the documentation of the datamover accelerator.
- A block diagram of each module, with the child instances, the generate
blocks, the interfaces and the signals between them. The colours separate the
data path from the control plane: a stream or a bus is a wide green line with
the direction of the data, a control signal is amber and dashed and shows
which module controls what, and a flag or status signal is violet. The FSM
and the assignments of the module appear as one
internal logicnode, thus a control net that ends in analwaysblock is visible. A module with no submodule shows its boundary as a symbol. The overview shows each top with the same diagram. - A page for each module: the ports with the resolved type and width, the parameter values, the clocks, the resets and the parent modules.
- The comment above the module. Markdown, reStructuredText and the Doxygen commands each render. A name in the comment becomes a link to that module.
- The Markdown and the reStructuredText of the repository, in the same site. A page with the name of a module attaches to that module.
- The code of each file, with the colours and a line number.
- Graphs of the hierarchy, the source files and the Bender packages, and one search over all of them.
slang elaborates the design: the macros expand, the parameters resolve and the widths are calculated. Nothing is guessed from the source text.
Copy this into a terminal. Remove the lines for the tools that you have.
# The tools. Graphviz is the only line that changes with the operating system.
curl -LsSf https://astral.sh/uv/install.sh | sh # uv
curl https://pulp-platform.github.io/bender/init -sSf | sh # bender
sudo apt install -y graphviz # macOS: brew install graphviz
uv tool install rtldoc # or: pipx install rtldoc
# The design. Use the path of any repository that has a Bender.yml.
cd ~/my-bender-project
bender checkout # only if the dependencies are not there yet
rtldoc gen --openThe tool finds the nearest Bender.yml, elaborates each module of the root
package, writes .rtldoc/ and opens it in the browser. It adds that
directory to your .gitignore. A simulator is not necessary.
uv tool upgrade rtldoc gets a later version. To read or change the code,
clone this repository and install that directory:
uv tool install --force ~/rtldoc.
In the site: Overview gives the tops and their block diagrams, Hierarchy
gives the structure,
Files gives the compile order and the code, and a module page gives the ports
and the block diagram. Push / to search.
| Command | Function |
|---|---|
rtldoc gen |
Makes the documentation in .rtldoc/ |
rtldoc open |
Opens it. Makes it first if it is not available |
rtldoc serve |
Makes it, then serves it on http://localhost:8080 |
rtldoc doctor |
Shows the status of the necessary programs |
rtldoc init |
Writes an optional rtldoc.yml |
If a run fails, rtldoc doctor shows which program is missing. gen stops
with exit code 3 when bender is not available, and with 4 when bender cannot
resolve the dependencies. It then shows the message from bender.
Write the site to a directory that your host serves:
.PHONY: docs
docs:
rtldoc gen -o public
rtldoc check public --min-modules 20 --require-graphscheck gives exit code 1 if the result is not complete. Use it in your pipeline,
because a design that no longer elaborates gives an empty site and no error.
--want-module, --min-interfaces and --max-diagnostics make the condition
stronger. rtldoc check --help gives each option.
In Python, the same two steps are rtldoc.build_documentation(root, out)
and rtldoc.check_site(out).
Then let your CI job run make docs and publish public/. Each CI system
publishes in a different way, thus this repository gives no configuration. The
pages workflow of this repository is one example
for GitHub Pages.
Settings are not necessary. rtldoc.yml in the project root can give:
output: .rtldoc
name: My Design # The title. The default is the directory name
tops: [my_testbench_top] # More top modules
docs: [manual] # More directories with text. `false` reads none
sources: false # Makes no page for the code
conventions: # The naming rules of this code base, for the graphs
control: ["^csr_"] # More rules for a control signal (regex)
flags: ["^sts_"] # More rules for a flag or status signalThe common names (ctrl, cfg, en, flags, status, busy, done, …)
colour without rules. conventions adds the rules of your code base, because
each project names these signals in its own way.
The tool shows the code of the root package only. The code of a dependency has another licence, thus it stays in its own repository.
git clone https://github.com/lionnus/rtldoc && cd rtldoc
uv sync --extra dev
uv run pytest # A substitute for bender, thus the tests run anywhere
uv run ruff check .Each module has one subject: bender reads the project, extract elaborates it,
comments and markup read the text, schematic, graphs and dot draw,
render writes the site. A module imports from a lower layer only;
tests/test_architecture.py holds that rule and
the docstring of rtldoc/__init__.py gives the
layers.
A tag makes a release: rtldoc/__init__.py gives the version, and
git tag v0.2.0 && git push origin v0.2.0 starts the
release workflow. That workflow runs the tests
again, builds the wheel, and publishes it to PyPI. PyPI trusts the workflow
through OpenID Connect, thus there is no token.
Then open a pull request. CI runs ruff, the tests on Python 3.9 to 3.13, and
the coverage measurement. It then makes the documentation of two real designs,
opope and
datamover, with the true
bender, and examines the result. New code needs tests: pyproject.toml gives
the minimum coverage, and CI stops below it.
IMPROVEMENTS.md gives the design of the tool, the known
limitations, and the ideas for later work.
Apache-2.0. See LICENSE.
The IBM Plex fonts in rtldoc/assets/fonts have the SIL Open Font License
1.1. See rtldoc/assets/fonts/OFL.txt.