Skip to content

Explain the SSA CFG and IR dumps - #332

Merged
jserv merged 1 commit into
masterfrom
docs
Sep 7, 2026
Merged

Explain the SSA CFG and IR dumps#332
jserv merged 1 commit into
masterfrom
docs

Conversation

@jserv

@jserv jserv commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

The Intermediate Representation section described '--dump-ir' with a line-by-line table that no longer matched the compiler: the table still showed 'call @fib, 1' and temporaries from an older numbering, and it never mentioned that the option emits two dumps, one before optimization and one after register allocation.

Rewrite the section around tests/fib.c and split it in two. The control-flow half now carries a rendered figure, docs/fib-cfg.png, built from real '--dot' output by keeping the fib and main clusters and dropping the run-specific pointer values from the labels; the shell recipe that produced it is included, so the image can be regenerated. The prose walks fib block by block: the entry and exit blocks, the empty blocks that only forward a branch, and the push/call/retval shape of a call. It also says where a phi does appear, since fib itself needs none.

The textual half is refreshed against current output and states what has already run when each dump is taken. That matters for reading them: inlining and phi unwinding precede the first dump, whose printer then elides the unwound copies and the SSA subscripts, so '--dot' is the only view showing either.


Summary by cubic

Fixes the Intermediate Representation docs so they match the compiler's actual output: the old line-by-line table showed stale temporaries and a single dump, and the new text splits the section into control-flow graph and instruction dump halves, adds a rendered figure from real --dot output, and states what has already run before each dump.

Bug Fixes

  • Replaces the outdated IR table with examples from current compiler output.
  • Adds docs/fib-cfg.png and the shell recipe to regenerate it.
  • Clarifies that --dump-ir emits two dumps and that --dot is the only view showing phis and SSA subscripts.

Written for commit 3058742. Summary will update on new commits.

Review in cubic

The Intermediate Representation section described '--dump-ir' with a
line-by-line table that no longer matched the compiler: the table still
showed 'call @fib, 1' and temporaries from an older numbering, and it
never mentioned that the option emits two dumps, one before optimization
and one after register allocation.

Rewrite the section around tests/fib.c and split it in two. The
control-flow half now carries a rendered figure, docs/fib-cfg.png, built
from real '--dot' output by keeping the fib and main clusters and
dropping the run-specific pointer values from the labels; the shell
recipe that produced it is included, so the image can be regenerated.
The prose walks fib block by block: the entry and exit blocks, the empty
blocks that only forward a branch, and the push/call/retval shape of a
call. It also says where a phi does appear, since fib itself needs none.

The textual half is refreshed against current output and states what has
already run when each dump is taken. That matters for reading them:
inlining and phi unwinding precede the first dump, whose printer then
elides the unwound copies and the SSA subscripts, so '--dot' is the only
view showing either.
@jserv
jserv merged commit 8d55734 into master Sep 7, 2026
30 checks passed
@jserv
jserv deleted the docs branch September 7, 2026 11:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant