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

• New flag --verilator-hier-blocks (default off): plumbed through the Haskell frontend (Options.hs, CmdArgs.hs, FFI.hsc) and C++ backend (options.h → CodeGenOptions._emitVerilatorHierBlocks), mirroring the existing no_verilog_header flag.
• 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

[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.

[teqdruid]

LGTM!

[teqdruid]

LGTM

[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?

[blakepelton]

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).