[debug] Add circt_debug_* intrinsics for Chisel type metadata by fkhaidari · Pull Request #5276 · chipsalliance/chisel

fkhaidari · 2026-04-20T16:40:21Z

Hi! This PR adds source-level debug info collection for Chisel
Based on @rameloni's Tywaves work (#4015, #4224), but using intrinsics
instead of annotations as @fabianschuiki suggested in that thread.

Emits four intrinsics during elaboration:

circt_debug_var -- type + ctor params per signal
circt_debug_subfield -- aggregate hierarchy
circt_debug_moduleinfo -- module-level metadata (class, ctor params)
circt_debug_enumdef -- ChiselEnum definitions

Fully opt-in via --emit-debug-type-info. Without the flag, FIRRTL
output is bit-identical to main.

Companion CIRCT PR (intrinsic lowering + debug dialect extensions)
is in progress at [fkhaidari/circt#1] and will be submitted upstream
later

cc @fabianschuiki @rameloni @jackkoenig @seldridge

Contributor Checklist

Did you add Scaladoc to every public function/method?
Did you add at least one test demonstrating the PR?
Did you delete any extraneous printlns/debugging code?
Did you specify the type of improvement?
Did you add appropriate documentation in docs/src?
Did you request a desired merge strategy?
Did you add text to be included in the Release Notes for this change?

Type of Improvement

Feature (or new API)

Desired Merge Strategy

Rebase: You will rebase the PR onto master and it will be merged with a merge commit.

Release Notes

Add opt-in ChiselStage flag withDebug = true that emits circt_debug_*
intrinsics preserving Chisel-level type and parameter metadata in FIRRTL.

Reviewer Checklist (only modified by reviewer)

Did you add the appropriate labels? (Select the most appropriate one based on the "Type of Improvement")
Did you mark the proper milestone (Bug fix: 3.6.x, 5.x, or 6.x depending on impact, API modification or big change: 7.0)?
Did you review?
Did you check whether all relevant Contributor checkboxes have been checked?
Did you do one of the following when ready to merge:
- Squash: You/ the contributor Enable auto-merge (squash) and clean up the commit message.
- Merge: Ensure that contributor has cleaned up their commit history, then merge with Create a merge commit.

linux-foundation-easycla · 2026-04-20T16:40:29Z

The committers listed above are authorized under a signed CLA.

✅ login: fkhaidari / name: fkhaidari (2aa674c)

jackkoenig

Thank you for this contribution.

A few comments, I'm okay moving forward using runtime reflection but I think we should discuss how we might do this in a much more robust way using static reflection (aka macros) in Scala 3.

jackkoenig · 2026-05-07T22:38:49Z

+// Scala 3 has no runtime mirror to pick a primary out of multiple ctors,
+// so emit params only for single-ctor classes.
+private[debug] object CtorParamsPlatform extends LazyLogging {
+
+  def ctorParams(obj: Any): Seq[(String, String)] = {
+    val cls = obj.getClass
+    val ctors = cls.getDeclaredConstructors
+    if (ctors.length != 1) {
+      if (ctors.length > 1)
+        logger.warn(s"ctorParams: ${cls.getName} has ${ctors.length} constructors; omitting `params`")
+      Seq.empty
+    } else {


I think for Scala 3 we'll eventually want to do this with static reflection (aka macros) rather than runtime reflection which, as you note, can't get the information needed.

Future work.

Agreed -- the multi-ctor case here are exactly the kind of thing typeclass derivation would solve cleanly

jackkoenig · 2026-05-07T22:42:37Z

+  implicit val rw: json.ReadWriter[ClassParam] = json
+    .readwriter[ujson.Value]
+    .bimap(
+      p =>
+        ujson.Obj(
+          "name" -> p.name,
+          "typeName" -> p.typeName,
+          "value" -> p.value.getOrElse(ujson.Null)
+        ),
+      j =>
+        ClassParam(
+          j("name").str,
+          j("typeName").str,
+          j.obj.get("value").filterNot(_ == ujson.Null)
+        )
+    )


Suggested change

implicit val rw: json.ReadWriter[ClassParam] = json

.readwriter[ujson.Value]

.bimap(

p =>

ujson.Obj(

"name" -> p.name,

"typeName" -> p.typeName,

"value" -> p.value.getOrElse(ujson.Null)

),

j =>

ClassParam(

j("name").str,

j("typeName").str,

j.obj.get("value").filterNot(_ == ujson.Null)

)

)

implicit val rw: json.ReadWriter[ClassParam] = json.macroRW

Is this not the same as the macro-derived serializer?

No -- macroRW array-wraps Option[T], which is okay in general, but feels less semantically clean here: downstream consumers would have to unwrap a one-element array to get the value. The manual bimap produces a flatter value

// macroRW {"name":"x","typeName":"String","value":["hi"]} {"name":"y","typeName":"Long","value":[42]} // manual bimap (this PR) {"name":"x","typeName":"String","value":"hi"} {"name":"y","typeName":"Long","value":42}

jackkoenig · 2026-05-07T22:47:26Z

+      case _: chisel3.Bits | _: chisel3.Clock | _: chisel3.Reset => true
+      case _: chisel3.experimental.Analog => true
+      case _: chisel3.Vec[_] | _: chisel3.EnumType => true
+      case _                                       => target.getClass.getName == "chisel3.util.MixedVec"


This feels a bit sketchy, what is this trying to accomplish? Is the problem that MixedVec has it's argument as private?

If that's the case, I think we have a really tricky usability issue since may arbitrarily make their arguments private or constructors private...

The string-name check is a build-graph constraint: chisel3.util.MixedVec lives in the chisel module, which dependsOn(coreModule) -- and chisel3.debug.* is in core/. Importing it from there cycles the graph (verified, doesn't compile)

I could add a marker trait in core (e.g. private[chisel3] trait OmitDebugCtorParams) that MixedVec extends, so the matcher becomes case _: OmitDebugCtorParams => true. Not sure that's actually less sketchy though -- happy to go either way.

jackkoenig · 2026-05-07T22:59:37Z

+  `toString` will slow or OOM the compile. Avoid expensive `toString`s in
+  classes you expect to feed into debug metadata. Cycles in the object graph
+  are detected via identity tracking and printed as `toString` rather than
+  recursed into.


Thank you for describing these limitations. I must confess these make me pretty nervous about the stability of this feature. I'm not opposed to moving forward with the limitations in mind, but I think we should mark this experimental (not using the experimental package, that was a bit of a failed experiment). I'll add some suggestions of how to warn users a bit.

I think looking into how to do this with static reflection (aka macros, especially typeclass derivation in Scala 3) is the more robust way forward.

Agreed on both fronts. I'll apply your experimental warnings/scaladoc suggestions in the next push so users see the caveat right at the entry points. And yes, moving the runtime reflection to typeclass derivation (Scala 3 macros) is the right long-term direction

jackkoenig · 2026-05-07T23:01:31Z

 ```
+
+## Debug type-info intrinsics
+


Suggested change

:::warning

This feature is experimental and subject to change.

See [Notes on reflection](#notes-on-reflection) below for limitations.

:::

jackkoenig · 2026-05-07T23:01:48Z

+
+  override val options: Seq[ShellOption[Unit]] = Seq(
+    new ShellOption[Unit](
+      longOption = "with-debug-intrinsics",


Suggested change

longOption = "with-debug-intrinsics",

longOption = "with-experimental-debug-intrinsics",

jackkoenig · 2026-05-07T23:02:04Z

+import firrtl.options.{HasShellOptions, ShellOption, Unserializable}
+
+/** Opt-in toggle for [[chisel3.stage.phases.AddDebugIntrinsics]].
+  * Activate with `--with-debug-intrinsics` or by adding this annotation.


Suggested change

* Activate with `--with-debug-intrinsics` or by adding this annotation.

* Activate with `--with-debug-intrinsics` or by adding this annotation.

*

* @note This API is experimental and subject to change.

jackkoenig · 2026-05-07T23:02:45Z

+import firrtl.options.{Dependency, Phase}
+import firrtl.{annoSeqToSeq, seqToAnnoSeq, AnnotationSeq}
+
+/** No-op unless [[chisel3.debug.EmitDebugIntrinsicsAnnotation]] is present. */


Suggested change

/** No-op unless [[chisel3.debug.EmitDebugIntrinsicsAnnotation]] is present. */

/** No-op unless [[chisel3.debug.EmitDebugIntrinsicsAnnotation]] is present.

*

* @note This API is experimental and subject to change.

*/

@rameloni

Introduce an opt-in pass that injects CIRCT debug intrinsics carrying Chisel-level type and constructor-parameter metadata through to FIRRTL, so downstream tooling (waveform viewers, debuggers) can recover Bundle field names, Vec shapes, ChiselEnum types and module parameters that are otherwise lost during conversion. The DebugIntrinsics emitter walks the elaborated circuit and appends four kinds of secret intrinsics: - circt_debug_moduleinfo per module (typeName + ctor params) - circt_debug_var per top-level signal, port or memory - circt_debug_subfield per Bundle/Vec element, linked by parent - circt_debug_enumdef per ChiselEnum type (emitted once) Constructor parameters are extracted via runtime reflection and serialised to JSON. Booleans round-trip as native JSON bools; all numeric types (Byte / Short / Int / Long / Float / Double) serialise uniformly as JSON strings -- JSON has no NaN/Infinity literals and Double-backed parsers lose precision on Long > 2^53, so a single string shape avoids both pitfalls and gives downstream sinks one attribute mapping to write. JDK and Scala stdlib classes are not recursed into during nested ctor extraction; their constructors are implementation details and produce no user-meaningful parameters. User toString output embedded in the params payload is capped at 4 KiB to bound emission size against pathological implementations. Emission is disabled by default and activated by adding EmitDebugIntrinsicsAnnotation to the annotation seq programmatically, or by passing `--with-debug-intrinsics` on the CLI to any circt.stage.ChiselStage entry point. Either form schedules the new AddDebugIntrinsics phase between Elaborate and Convert; the phase is a no-op without the annotation. After consuming it, the phase strips EmitDebugIntrinsicsAnnotation from the seq so a second pass over the same annotations does not double-emit intrinsics. Includes unit tests for moduleinfo / var / subfield / enumdef emission across scalar, Bundle, Vec, ChiselEnum, memory and hierarchy cases, plus a docs section in docs/src/explanations/intrinsics.md. Based on work of @rameloni Signed-off-by: fkhaidari <khaidari.fg@gmail.com>

fkhaidari · 2026-05-08T11:45:44Z

@jackkoenig, thank you for your review!

fkhaidari force-pushed the fk-sc/debug-info branch 20 times, most recently from a6036bf to d8ed90a Compare April 27, 2026 01:46

fkhaidari force-pushed the fk-sc/debug-info branch from d8ed90a to 61414ba Compare May 6, 2026 17:08

jackkoenig added the Feature New feature, will be included in release notes label May 6, 2026

fkhaidari mentioned this pull request May 7, 2026

[debug][firrtl] Carry Chisel source-level types through the pipeline llvm/circt#10410

Open

jackkoenig reviewed May 7, 2026

View reviewed changes

fkhaidari force-pushed the fk-sc/debug-info branch from 61414ba to 8b4eadc Compare May 8, 2026 11:18

fkhaidari force-pushed the fk-sc/debug-info branch from 8b4eadc to 2aa674c Compare May 8, 2026 11:43

fkhaidari requested a review from jackkoenig May 8, 2026 11:45

+:::warning
+This feature is experimental and subject to change.
+See [Notes on reflection](#notes-on-reflection) below for limitations.
+:::

	longOption = "with-debug-intrinsics",
	longOption = "with-experimental-debug-intrinsics",

Conversation

fkhaidari commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contributor Checklist

Type of Improvement

Desired Merge Strategy

Release Notes

Reviewer Checklist (only modified by reviewer)

Uh oh!

linux-foundation-easycla Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jackkoenig 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!

fkhaidari May 8, 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!

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!

Choose a reason for hiding this comment

Uh oh!

fkhaidari commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fkhaidari commented Apr 20, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Apr 20, 2026 •

edited

Loading

fkhaidari May 8, 2026 •

edited

Loading