Add circt-tblgen, generate FIRRTL intrinsics docs #9454

fabianschuiki · 2026-01-15T02:00:27Z

Add a circt-tblgen tool identical to how MLIR has this set up. This needs to be pulled in by the root cmake file to ensure that the interesting CIRCT_TABLEGEN_EXE and CIRCT_TABLEGEN_TARGET variables are visible to the rest of the project.

Having a custom TableGen in CIRCT allows us to be more fancy about how we generate code from tables. As a first example, add a backend to generate the code to register lowerings for FIRRTL intrinsics, and a backend to generate Markdown documentation snippets from the same table.

I have only migrated two intrinsics over into the table to not pollute the PR with a purely mechanical change. Once this lands we can follow up with a PR that moves all intrinsics into that table. This then enforces that every supported FIRRTL intrinsic has corresponding documentation.

I'm sure we can find a lot more uses for circt-tblgen :-)

Add a `circt-tblgen` tool identical to how MLIR has this set up. This needs to be pulled in by the root cmake file to ensure that the interesting `CIRCT_TABLEGEN_EXE` and `CIRCT_TABLEGEN_TARGET` variables are visible to the rest of the project. Having a custom TableGen in CIRCT allows us to be more fancy about how we generate code from tables. As a first example, add a backend to generate the code to register lowerings for FIRRTL intrinsics, and a backend to generate Markdown documentation snippets from the same table. I have only migrated two intrinsics over into the table to not pollute the PR with a purely mechanical change. Once this lands we can follow up with a PR that moves all intrinsics into that table. This then enforces that every supported FIRRTL intrinsic has corresponding documentation. I'm sure we can find a lot more uses for circt-tblgen :-)

dtzSiFive

This is really neat, thanks for putting this together!

I've left some feedback.

I have not carefully reviewed the CMake portion, and I recall it being quite .. involved, having previously poked at use in the MLIR-built-and-installed-standalone flow I use for packaging.

One possibly useful litmus test -- possibly after this PR -- is to see how well this can be used from a downstream project. Especially from an install (not just a build tree as often used).

Anyway when we move forward with this let's see if we can't be sure to follow-up promptly-ish (I'll help!) so we get everything moved over quickly (and don't have things mid-transition for too long). Not eagerly converting things, especially while under review, is a good call for now 👍 .

dtzSiFive · 2026-01-15T19:10:45Z

lib/Dialect/FIRRTL/FIRRTLIntrinsics.td

+// lowering code, as well as fragments for the dialect documentation.
+class FIRRTLIntrinsic {
+  // The mnemonic for the intrinsic, e.g. "circt.sizeof". This should use the
+  // form with dots. A second mnemonic with only underscores will be generated


I think we standardized on the underscore format, actually, and that's what the user-facing documentation uses today. I'm not sure offhand if there's any utility in keeping the dot variant in today's flows, but I'd want to triple-check where that was ever used, to be honest.

I'm open to arguments the other way, but regardless of which format we decide on I don't think it makes much sense to actually support both other than as a transition detail / legacy support.
(right? WDYT?)

My concrete suggestion was to make the underscore version the primary format, but we can't produce the dot format easily from that (which may have underscores as well), so that might be something that "goes along with" removing supporting both.

Good points! I've had a similar reaction: let's make the underscore the default -- and then I realized that the dot format needs to be the default because we can't get that from the underscore format. But since this is now generated, I think once we've migrated everything over and we have officially removed support for ".", we can just tweak the few lines here?

dtzSiFive · 2026-01-15T19:14:53Z

lib/Dialect/FIRRTL/FIRRTLIntrinsics.td

+
+    | Argument | Type | Description                                |
+    | -------- | ---- | ------------------------------------------ |
+    | i        | Any  | value whose type's size is to be returned  |


It'd be super neat to auto-generate these tables! 🙃

Something like how arguments / results / parameters are defined for MLIR instructions, maybe? Just brainstorming.

That said, I don't know how well we could auto-generate (for example) the check/convert snippets for the majority of cases, from a programmatic / table description. A few likely will still make more sense done manually or at least via escape-hatch "just use this code as the check or convert part".

Maybe we could or otherwise could basically provide the same "interface" as currently given when adding an intrinsic re:what's needed to derive from one of the Conversion helpers.

Just moving this over verbatim is a great start, can't help but getting excited about where things might be able to go! 😁

It's valuable to not overdo things in that direction too hastily, probably, but curious what you think.

This would be so cool to autogenerate! The snippets in the converter that handle the different flavors of arguments are a bit tricky though, as you say. Maybe we gradually increase how much of this we autogenerate over time?

dtzSiFive · 2026-01-15T19:16:25Z

tools/circt-tblgen/FIRRTLIntrinsicsGen.cpp

+struct IntrinsicDef {
+  const Record *def;
+  StringRef mnemonic;
+  std::string altMnemonic;


SmallString's instead of std::string ?

Had that initially, and then I remember that there are on the order of 100 of these that get allocated, and SmallString was giving off that strong premature optimization smell 🤣 . I'm happy to switch this to SmallString though if you want 😁

Nah, keep it.

I haven't looked at this closely enough 🙃 and let's go with your preference. Hence the question mark 😉 .

Thing I argue for most directly is avoiding a bunch of temporary std::string allocations on the way to constructing the final thing, which is only even a tiny bit relevant re:converter. And the fact that in practice it's unlikely these names will be very long.

I wonder how much the common sort of "SSO" gets us, anyway...

Just beating the good practices drum 😉 .

dtzSiFive · 2026-01-15T19:16:40Z

tools/circt-tblgen/FIRRTLIntrinsicsGen.cpp

+    mnemonic = def->getValueAsString("mnemonic");
+    description = def->getValueAsOptionalString("description").value_or("");
+
+    // Determine the alternative mnemonic by replacing any unsavory characters


"unsavory characters" 🤣 ❤️

fabianschuiki requested review from dtzSiFive, rwy7 and youngar January 15, 2026 02:00

fabianschuiki requested review from darthscsi and seldridge as code owners January 15, 2026 02:00

fabianschuiki changed the title ~~Add circt-tblgen, generate FIRRTL intrinsic docs~~ Add circt-tblgen, generate FIRRTL intrinsics docs Jan 15, 2026

fabianschuiki force-pushed the fschuiki/tablegen branch 2 times, most recently from e0a3254 to c8888f3 Compare January 15, 2026 18:20

fabianschuiki force-pushed the fschuiki/tablegen branch from c8888f3 to df04281 Compare January 15, 2026 18:46

dtzSiFive reviewed Jan 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add circt-tblgen, generate FIRRTL intrinsics docs #9454

Add circt-tblgen, generate FIRRTL intrinsics docs #9454

fabianschuiki commented Jan 15, 2026

Uh oh!

dtzSiFive left a comment

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

fabianschuiki Jan 15, 2026

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

fabianschuiki Jan 15, 2026

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

fabianschuiki Jan 15, 2026 •

edited

Loading

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

dtzSiFive Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add circt-tblgen, generate FIRRTL intrinsics docs #9454

Are you sure you want to change the base?

Add circt-tblgen, generate FIRRTL intrinsics docs #9454

Conversation

fabianschuiki commented Jan 15, 2026

Uh oh!

dtzSiFive left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fabianschuiki Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fabianschuiki Jan 15, 2026 •

edited

Loading