Hierarchy Rendering

Use rb hier to see a design's hierarchy as text or diagram source. Use rb hier-query when a script or agent needs one structural answer.

Install the renderer

rb hier runs the rtl-buddy-view executable, which the rtl-buddy-sch distribution provides:

uv tool install rtl-buddy-sch
rb tool-check --explain rtl-buddy-view

Use --tool /absolute/path/to/rtl-buddy-view to pin a development build. Optional dependencies:

• Graphviz dot, to convert DOT to SVG or PNG.
• pyslang, for --frontend slang.

See Installation for tool setup. If an older rtl-buddy-view package conflicts with rtl-buddy-sch, see Known Issues.

Render a hierarchy

Run from a directory where rtl_buddy can find the configuration, or pass -c:

rb hier demo_top
rb hier demo_top --format mermaid -o demo_top.mmd
rb hier demo_top --format dot | dot -Tsvg -o demo_top.svg
rb hier demo_top --format json -o demo_top.hier.json
rb hier demo_top -c design/demo_top/models.yaml

The positional name selects a model from models.yaml. rtl_buddy builds a stripped, deduplicated filelist from it and passes the model name to the renderer as the top.

Format	Use
tree	Terminal inspection (default).
dot	Graphviz input for diagrams.
mermaid	Mermaid source for Markdown.
json	Structured data for downstream tools.

Without -o the output goes to stdout and can be piped. With -o the renderer writes the file.

Render a testbench hierarchy

--view tb shows the hierarchy above and around the DUT:

rb hier basic_traffic --view tb

Here the positional name is a test from tests.yaml, not a model. The test supplies the DUT model and testbench top. Tests with the same (model, testbench) reuse one generated hierarchy artefact.

Render a block diagram

For sibling dataflow instead of an instantiation tree, generate block-diagram DOT:

rb hier demo_top --format dot --block-diagram | dot -Tsvg -o demo_top_block.svg

This needs rtl-buddy-sch >= 0.8.0; older renderers fail with an upgrade message. It applies only to DOT output.

Trim a figure for a document

Three options strip detail from a DOT or Mermaid figure:

rb hier demo_top --format dot --block-diagram --params none --prune-flags | dot -Tsvg -o demo_top.svg
rb hier demo_top --format mermaid --clock-colors clock-colors.json -o demo_top.mmd

• --params none drops the parameter rows from every instance box, overriding // rbsch: params= pragmas. --params all, the default, shows every override the pragmas allow.
• --prune-flags drops root-port flags that no edge lands on, typically clock and reset ports. It works only with --format dot --block-diagram.
• --clock-colors pins a colour to named clocks of the clock-domain annotations, so a clock keeps its colour across a set of figures. Other clocks get the remaining swatches. The file is:

{"schema_version": "1.0", "clocks": {"clk_a": "blue", "clk_b": "#dcfce7"}}

A colour is a swatch name (blue, green, yellow, pink, purple, orange, cyan) or #rrggbb. To keep a colour with the RTL instead, put a // rbsch: clock color=blue pragma on the clock port; the file wins where both name a clock.

These options need rtl-buddy-sch >= 0.12.0; older renderers fail with an upgrade message. rtl_buddy refuses a combination the renderer would ignore: --params or --clock-colors with tree or json output, --prune-flags without a block diagram, and --clock-colors without clock-domain annotations.

Query hierarchy data

rb hier-query answers a focused question without rendering the whole hierarchy:

rb hier-query demo_top find-module axi_arbiter
rb hier-query demo_top subtree demo_top.u_fabric --format tree
rb hier-query demo_top instances-of axi_arbiter
rb hier-query demo_top port-connections demo_top.u_fabric.u_arb0
rb hier-query demo_top source-snippet demo_top.u_fabric.u_arb0 --context 4

• find-module and instances-of take a module name. The other verbs take a dot-separated instance path starting at the model's root module (top: in models.yaml, default the model name).
• Results are JSON, except source-snippet, which prints source text with line numbers by default.
• A lookup miss or parse failure exits 1 and prints the viewer diagnostic to stderr. An empty instances-of result is a valid answer and exits 0.

Select a parser and annotations

Pass --frontend slang for SystemVerilog the default parser cannot elaborate. The renderer validates frontend names.

Domain overlays are JSON maps keyed by hierarchical instance path:

rb hier demo_top --format dot --clock-legend | dot -Tsvg -o clocks.svg
rb hier demo_top --format dot --rdc-annotations resets.json | dot -Tsvg -o resets.svg

rtl_buddy resolves annotation paths from the current directory and checks that the files exist before starting the renderer. --clock-legend applies only to DOT output.

Find outputs and diagnose failures

Outputs are anchored to the primary config's directory, not the shell's current directory. A model render writes:

<models.yaml directory>/artefacts/hier/<model>/
├── hier.f
└── hier.log

A testbench render writes to artefacts/hier/<model>/tb/<testbench>/ under the tests.yaml directory. hier.f is the generated filelist and hier.log holds the renderer's stderr. Queries also write query.log.

rb hier exits with the renderer's exit code. For a parse, elaboration, or output failure, read hier.log. If the executable is not found, run rb tool-check --explain rtl-buddy-view.

For interactive browsing, rb hub start --serve-viewer --model <name> serves the same JSON hierarchy. See Hub.