Dealing with files emitted by addResource / HGLDD in firtool (original) (raw)

Using a modern chisel Version like 6.7.0, calls to addResource will emit a firrtl.transforms.BlackBoxInlineAnno inside the chirrtl (or firrtl?) file. When lowered to Verilog using a fairly new firtool, it appears to be transformed into // ----- 8< ----- FILE "path-to-file" ----- 8< -----. I think this is done in EmitHGLDD.cpp.
Is there an “official” way to deal with these magic comments. So for example, is there a pass that finds these embedded files and creates proper files out of them? I also did not find any up to date documentation, so feel free to redirect me

Hey @RerikOp! One of the challenges we ran into with firtool is the fact that you often don’t just want to create Verilog output files, but other parts in the compiler pipeline may create additional files as collateral. This includes JSON files with metadata, the HGLDD debug info outputs, file lists, etc. The --verilog output mode in firtool produces a single output stream, mainly for the sake of using llvm-lit and FileCheck to test the output. Since the compiler still really wants to create separate files, the only option we had in --verilog mode was to add the ----- 8< ----- separation lines between logical files, and essentially just create a concatenated output.

You are probably looking for the --split-verilog option, which treats the path passed to -o as a directory name and then creates separate files in there. This allows the compiler to properly create all the other collateral files. Within CIRCT we treat the simple --verilog option more as a debugging tool for the compiler and not something that’s useful in practice.

RerikOp April 29, 2025, 10:20pm 3

Oh well, that was easier than expected. It did not cross my mind that --split-verilog would help me to, well, split my verilog file But jokes aside, maybe a little hint in the help text that this flag is required if you are using collaterals and want valid verilog output would be nice. Additionally, it appears that it actually outputs SystemVerilog, so maybe that is relevant information for some as well. If time permits, I would offer to create a pull request to add a little more detail to the --help section, do you think my points are valid? I feel like a good help section goes a long way as it is usually less likely to be forgotten about (contrary to docs that are just so far away from actual code)

Yeah that would be very helpful! Anything that makes it easier to pick up the tool and get it to do work in useful way is very valuable Thanks!