| name | read-dfg |
| description | Inspect DFG .json or .dot debug artifacts produced by the compiler. Use this when debugging signal drivers, dependencies, fanout, op behavior, pass-to-pass changes, dead code, or node identity questions. Prefer tools/dfg_inspect.py and correlate with runtime tracing when structure alone is not enough. |
Use tools/dfg_inspect.py for JSON and dot -Tsvg for DOT.
Common locations:
tests/<name>/work/static/debug_output/<top>/
tests/<name>/work/custom-sim/debug_output/<top>/
Key idea:
- Use DFG JSON for static structure and lowering state.
- Use
trace-dfg-runtime when you need to know what happened at simulation time.
Useful commands:
python3 tools/dfg_inspect.py <file> node <id-or-name> [--details]
python3 tools/dfg_inspect.py <file> nodes [--op OP] [--name PATTERN] [--at FILE:LINE]
python3 tools/dfg_inspect.py <file> deps <id-or-name> [--op OP] [--depth N] [--details]
python3 tools/dfg_inspect.py <file> uses <id-or-name> [--op OP] [--depth N] [--details]
python3 tools/dfg_inspect.py <file> neighborhood <id-or-name> --fanin N --fanout N
python3 tools/dfg_inspect.py <file> diff <other.json> [--node ID-OR-NAME] [--cone] [--details]
Still useful when they fit:
python3 tools/dfg_inspect.py <file> driver <name>
python3 tools/dfg_inspect.py <file> cone <name> [--depth N]
python3 tools/dfg_inspect.py <file> mux <name>
python3 tools/dfg_inspect.py <file> mux-case <id-or-name> <case_val>
python3 tools/dfg_inspect.py <file> const_driven [value]
python3 tools/dfg_inspect.py <file> group <prefix>
python3 tools/dfg_inspect.py <file> search <pattern>
When debugging:
- Start with
node --details for the suspicious signal or node.
- Use
deps to walk backward through the inputs that determine the value.
- Use
uses to see downstream impact and to find the first consumer that changes across passes.
- Use
neighborhood when the issue is local and you want one compact view.
- Use
nodes --op OP or nodes --at FILE:LINE when you know the operation kind or source location but not the exact name.
- Use
diff on adjacent passes first. Add --node or --cone once the suspect area is known.
- If the static graph looks correct but the runtime value is wrong, switch to
trace-dfg-runtime.
Notes:
- Newer DFG JSON carries richer type data, named inputs,
instance_path, full_name, and stable debug_id values. Prefer those when present.
- Existing checked-in JSON artifacts may predate that schema. If metadata is missing, regenerate artifacts with a fresh compiler build.