Add --verilator-hier-blocks option to emit hier_block annotations

[Copilot]

Long Verilator compilations can be sped up via hierarchical Verilation, which keys off a /*verilator hier_block*/ metacomment on module boundaries. This adds an opt-in flag to emit that metacomment on each generated design module.

Changes

• Emission (verilog.cpp): when enabled, DeclareCore writes /*verilator hier_block*/ into the module body immediately after the port list — the placement Verilator requires for the metacomment.
• CLI test (test/compiler/cli/): compiles an exported class with the flag and parses every generated module. It asserts the metacomment is selective — present inside the exported core design module, and absent from the non-exported helper modules (the ESI wrapper and per-basic-block modules) — so the annotation can never leak into every module.

Notes

• Opt-in, so existing generated output is unchanged.
• The metacomment is ignored by non-Verilator tools, and Verilator ignores it (with a HIERBLOCK warning) if the annotated module happens to be the top — the Kanagawa core module is always wrapped by the ESI wrapper, so it is not the top in the ESI cosim flow.

module VerilatorHierBlock (
    // ... ports ...
);
    /*verilator hier_block*/
    // ... module body ...
endmodule

[John Demme (teqdruid)]

Copilot also add a test for non-exported modules to not contain the meta-comment.

[Copilot]

Copilot also add a test for non-exported modules to not contain the meta-comment.

Done in 1813c34. check_verilator_hier_blocks.py now parses every generated module and asserts the metacomment is selective: at least one module (the exported core design module) carries /*verilator hier_block*/, and at least one non-exported helper module (the ESI wrapper / per-basic-block modules) does not. If the annotation ever leaked into every module, the test fails.

Copilot also add a test for non-exported modules to not contain the meta-comment.

Correction: the change is in commits f20f8af and d74f8b5 (I mistyped the hash above).

[Copilot]

Pull request overview

Adds an opt-in --verilator-hier-blocks codegen option to annotate generated SystemVerilog with Verilator’s /*verilator hier_block*/ metacomment, enabling hierarchical Verilation to speed up large compilations.

Changes:

• Plumbs a new --verilator-hier-blocks boolean from the Haskell CLI through FFI into the C++ CodeGenOptions.
• Emits /*verilator hier_block*/ during core module generation when the option is enabled.
• Adds a CLI regression test (new .k input + Python checker) to validate selective emission behavior.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/compiler/cli/verilator_hier_blocks.k	New minimal source program used by the CLI test.
test/compiler/cli/CMakeLists.txt	Registers the new verilator_hier_blocks CLI test.
test/compiler/cli/check_verilator_hier_blocks.py	Validates presence/absence of /*verilator hier_block*/ in generated modules.
compiler/hs/app/Options/FFI.hsc	Pokes the new option into the C CodeGenOptions struct.
compiler/hs/app/Options/CmdArgs.hs	Adds the --verilator-hier-blocks CLI flag and help text.
compiler/hs/app/Options.hs	Adds verilator_hier_blocks to the Haskell Options record.
compiler/cpp/verilog.cpp	Emits the metacomment when enabled during core module generation.
compiler/cpp/options.h	Adds _emitVerilatorHierBlocks to CodeGenOptions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[John Demme (teqdruid)]

LGTM!

[John Demme (teqdruid)]

LGTM

[blakepelton (blakepelton)]

Maybe add a note to https://github.com/microsoft/kanagawa/blob/main/doc/mapping-to-hardware.md describing what this does.

Does this need to be a command line switch, is there a big downside in simulation speed to just always turning this on at export class boundaries?

[John Demme (teqdruid)]

Copilot review blake's comments and my own. Rebase on main.

Does this need to be a command line switch, is there a big downside in simulation speed to just always turning this on at export class boundaries?

I'm pretty sure that Verilator only uses it when instructed to. So I don't think there'd be any slowdown. But if a user is viewing the RTL and isn't using Verilator it may be a bit confusing...? Yeah, let's get rid of the command line option.

[Copilot]

Copilot review blake's comments and my own. Rebase on main.

Does this need to be a command line switch, is there a big downside in simulation speed to just always turning this on at export class...

Addressed in 796b4f2. I merged main into this branch (instead of rebasing in this environment), removed the --verilator-hier-blocks option, made hier_block emission default for exported core modules, and updated the CLI test plus mapping-to-hardware note.

[John Demme (teqdruid)]

Copilot you seem to have ignored Blake's comment:

"blakepelton (blakepelton)
on Jun 11
Collaborator
The ratio of test code to implementation code is high. Maybe a more general way to test this would be better? There could be performance tests that measure verilator compilation time. Or there could be a general script that is used to verify many things like this (input=kanagawa code + regex to search for in generated RTL)."

[Copilot]

Copilot you seem to have ignored Blake's comment:

"blakepelton (blakepelton)
...

Addressed in c42242a. I added a reusable checker (test/compiler/cli/check_generated_sv_modules.py) for generic regex-based module assertions (including post-port-list placement), and refactored check_verilator_hier_blocks.py to use it so this test is now a thin configuration of a general script.