rggen-systemrdl 0.1.0

data/notes/bit_field_type_mapping.md

@@ -0,0 +1,105 @@
+# bit_field type mapping (RgGen type ← SystemRDL field properties)
+
+Confirmed mapping from SystemRDL field property combinations to RgGen bit_field types.
+Reference: RgGen RTL templates at
+rggen/rggen-systemverilog `lib/rggen/systemverilog/rtl/bit_field/type`.
+
+## Baseline conventions
+- `sw` reaching the converter is one of rw / r / w / rw1 / w1 (sw=na and all invalid sw/hw combos
+  in Table 12 are errored by the front-end; see systemrdl notes/implicit_constraints.md).
+- SystemRDL "Error – meaningless" combos and SW-write-loss combos (sw∈{w,rw} & hw∈{w,rw} without
+  we/wel) are errored by the front-end; the converter assumes inputs already passed those checks.
+- HW-update principle: RgGen `rw`/`ro`/`wo` (plain storage) have NO hardware update path, so for
+  those, hw ∈ {r, na}. Fields where HW writes the value (hw=rw/w) map to HW-input-capable types
+  (`rohw`, `row1trg`, ...) or are unrepresentable — never to plain rw/ro/wo.
+- "Other properties not allowed" on a type means: if any property outside that type's listed set
+  is present, the field does NOT map to that type (→ another type, or error if none fits).
+
+## Type table
+The combinations below list the distinguishing properties per type. Full per-property conditions
+(including which properties must be absent) are in `bit_field_type_matrix.md`; they are not
+repeated here.
+
+### Basic access (no side effects)
+| RgGen type | SystemRDL combination | Notes |
+| ---------- | --------------------- | ----- |
+| `rw`   | sw=rw, hw∈{r,na} | Plain storage. |
+| `ro` (ext) | sw=r, hw drives value (hw=rw/w) | Value comes from hardware. |
+| `ro` (ref) | sw=r, hw=r/na, `next` = another field | Value comes from the referenced field (`reference` = the `next` target). |
+| `rof`  | sw=r, hw=na | Returns fixed `initial_value` (constant). hw=na only (not r). |
+| `wo`   | sw=w, hw=r | Write-only storage. |
+| `rohw` | sw=r, hw∈{rw,w}, `we` required (true or another field) | HW value taken in under `we` (valid). |
+| `rwhw` | sw=rw, hw∈{rw,w}, `we` required (true or another field) | read/write version of `rohw`; HW value taken in under `we` (valid). `we` avoids the SW-write-loss error. |
+| `rowo` | — NOT SUPPORTED | Would require merging two fields (sw=r + sw=w) at the same bit position. Bit-field overlap is an ERROR (see below). |
+
+### Read side-effect
+| RgGen type | SystemRDL combination | Notes |
+| ---------- | --------------------- | ----- |
+| `rc`   | sw=r, onread=rclr, hwset=true | `reference`(mask) NOT specifiable (SystemRDL has no mask). |
+| `rs`   | sw=r, onread=rset, hwclr=true | `rs` takes NO reference. |
+| `wrc`  | sw=rw, hw∈{r,na}, onread=rclr | |
+| `wrs`  | sw=rw, hw∈{r,na}, onread=rset | |
+
+### Write side-effect: clear / set / toggle
+Polarity: SystemRDL woclr/woset (write-ONE) → RgGen w1c/w1s; wzc/wzs (write-ZERO) → w0c/w0s;
+wot/wzt (toggle) → w1t/w0t. clear-family needs hwset=true; set-family needs hwclr=true;
+toggle-family takes neither.
+| RgGen type | SystemRDL combination | Notes |
+| ---------- | --------------------- | ----- |
+| `w0c`  | sw=rw, hw∈{r,na}, onwrite=wzc,  hwset=true | mask NOT specifiable. |
+| `w1c`  | sw=rw, hw∈{r,na}, onwrite=woclr, hwset=true | mask NOT specifiable. |
+| `w0s`  | sw=rw, hw∈{r,na}, onwrite=wzs,  hwclr=true | |
+| `w1s`  | sw=rw, hw∈{r,na}, onwrite=woset, hwclr=true | |
+| `w0t`  | sw=rw, hw∈{r,na}, onwrite=wzt  | |
+| `w1t`  | sw=rw, hw∈{r,na}, onwrite=wot  | |
+| `wc`   | sw=rw, hw∈{r,na}, onwrite=wclr, hwset=true | mask NOT specifiable. |
+| `ws`   | sw=rw, hw∈{r,na}, onwrite=wset, hwclr=true | |
+| `woc`  | sw=w, hw=r, onwrite=wclr, hwset=true | write-only version of wc. |
+| `wos`  | sw=w, hw=r, onwrite=wset, hwclr=true | write-only version of ws. |
+
+### Write + read combined (all: sw=rw, hw∈{r,na})
+| RgGen type | SystemRDL combination |
+| ---------- | --------------------- |
+| `w0crs` | onwrite=wzc,  onread=rset |
+| `w1crs` | onwrite=woclr, onread=rset |
+| `wcrs`  | onwrite=wclr, onread=rset |
+| `w0src` | onwrite=wzs,  onread=rclr |
+| `w1src` | onwrite=woset, onread=rclr |
+| `wsrc`  | onwrite=wset, onread=rclr |
+
+### Read/write with control signal (signal = true → external input; = other field → reference)
+| RgGen type | SystemRDL combination | Notes |
+| ---------- | --------------------- | ----- |
+| `rwl`  | sw=rw, swwel (=true or other field) | lock, active-low. |
+| `rwe`  | sw=rw, swwe  (=true or other field) | enable, active-high. |
+| `rwc`  | sw=rw, hw∈{r,na}, hwclr (=true or other field) | clear. |
+| `rws`  | sw=rw, hw∈{r,na}, hwset (=true or other field) | set. |
+
+### Trigger output
+| RgGen type | SystemRDL combination | Notes |
+| ---------- | --------------------- | ----- |
+| `rwtrg`  | `rw` combination + swacc=true  | |
+| `rotrg`  | `ro` combination + swacc=true  | |
+| `wotrg`  | `wo` combination + swacc=true  | |
+| `rowotrg`| — NOT GENERATED | `rowo` is not supported (bit-field overlap is an error). |
+| `w1trg`  | sw=rw, hw∈{r,na}, singlepulse=true | width=1/reset=0 etc. guaranteed by front-end. |
+| `w0trg`  | — NOT GENERATED | singlepulse requires write-1, so write-0 trigger has no SystemRDL source. |
+| `row0trg`| — NOT GENERATED | follows w0trg. |
+| `row1trg`| — NOT GENERATED | would need sw=rw + hw=rw/w + singlepulse, but sw=rw/w means value write in SystemRDL, so this combination is not expressible. (Also likely errored by front-end SW-write-loss.) |
+
+### Write once
+| RgGen type | SystemRDL combination | Notes |
+| ---------- | --------------------- | ----- |
+| `w1`  | sw=rw1, hw∈{r,na} | |
+| `wo1` | sw=w1, hw=r | |
+
+### Special / not generated
+| RgGen type | Status |
+| ---------- | ------ |
+| `counter`  | Front-end does NOT support SystemRDL `counter` yet → out of first-release scope (target type deferred; see TODO). |
+| `reserved` | SystemRDL has no equivalent concept → never generated from SystemRDL. |
+| `custom`   | First release: NOT used (held/deferred). Combinations that fit no named type are errors; using `custom` to catch them is future work (verification cost too high for v1). |
+
+## Mask reference
+RgGen types whose `reference` means a read/write data mask (`rc`, `w0c`, `w1c`, `wc`) cannot
+receive that mask from SystemRDL (no mask concept in SystemRDL) → such fields are reference-less.

data/notes/bit_field_type_matrix.md

@@ -0,0 +1,80 @@
+# bit_field type decision matrix (SystemRDL properties → RgGen type)
+
+One consolidated table. Left columns are SystemRDL input properties (what the converter reads to
+decide the type). The right column is the resulting RgGen type. Types that can take a reference
+are split into multiple rows so each row's property combination is unambiguous.
+
+Legend:
+- Empty cell = property must NOT be set (if set, the field maps to a different type or errors).
+- A value (e.g. `rw`, `rclr`, `true`, `ref`) = required value in that cell.
+- In a signal/reference cell (`next`, swwe, swwel, hwclr, hwset, we): `true` = external input;
+  `ref` = reference to another field instance. (`next` takes only `ref`, not `true`.)
+- `r/na` = either r or na.
+- `rw/w` = hw writes the value; read side (rw vs w) is NOT distinguished (the hw output port is
+  generated either way; whether user logic observes it is the user's concern).
+
+| RgGen type | sw   | hw    | next | onread | onwrite | hwset | hwclr | swwe | swwel | we   | swacc | singlepulse |
+| ---------- | ---- | ----- | ---- | ------ | ------- | ----- | ----- | ---- | ----- | ---- | ----- | ----------- |
+| `rw`       | rw   | r/na  |      |        |         |       |       |      |       |      |       |             |
+| `ro` (ext)  | r | rw/w |    |     |         |       |       |      |       |      |       |             |
+| `ro` (ref)  | r | r/na | ref |    |         |       |       |      |       |      |       |             | 
+| `rof`      | r    | na    |      |        |         |       |       |      |       |      |       |             |
+| `wo`       | w    | r     |      |        |         |       |       |      |       |      |       |             |
+| `rohw` (ext) | r  | rw/w  |      |        |         |       |       |      |       | true |       |             |
+| `rohw` (ref) | r  | rw/w  |      |        |         |       |       |      |       | ref  |       |             |
+| `rwhw` (ext) | rw | rw/w  |      |        |         |       |       |      |       | true |       |             |
+| `rwhw` (ref) | rw | rw/w  |      |        |         |       |       |      |       | ref  |       |             |
+| `rc`       | r    | r/na  |      | rclr   |         | true  |       |      |       |      |       |             |
+| `rs`       | r    | r/na  |      | rset   |         |       | true  |      |       |      |       |             |
+| `wrc`      | rw   | r/na  |      | rclr   |         |       |       |      |       |      |       |             |
+| `wrs`      | rw   | r/na  |      | rset   |         |       |       |      |       |      |       |             |
+| `w0c`      | rw   | r/na  |      |        | wzc     | true  |       |      |       |      |       |             |
+| `w1c`      | rw   | r/na  |      |        | woclr   | true  |       |      |       |      |       |             |
+| `w0s`      | rw   | r/na  |      |        | wzs     |       | true  |      |       |      |       |             |
+| `w1s`      | rw   | r/na  |      |        | woset   |       | true  |      |       |      |       |             |
+| `w0t`      | rw   | r/na  |      |        | wzt     |       |       |      |       |      |       |             |
+| `w1t`      | rw   | r/na  |      |        | wot     |       |       |      |       |      |       |             |
+| `wc`       | rw   | r/na  |      |        | wclr    | true  |       |      |       |      |       |             |
+| `ws`       | rw   | r/na  |      |        | wset    |       | true  |      |       |      |       |             |
+| `woc`      | w    | r     |      |        | wclr    | true  |       |      |       |      |       |             |
+| `wos`      | w    | r     |      |        | wset    |       | true  |      |       |      |       |             |
+| `w0crs`    | rw   | r/na  |      | rset   | wzc     |       |       |      |       |      |       |             |
+| `w1crs`    | rw   | r/na  |      | rset   | woclr   |       |       |      |       |      |       |             |
+| `wcrs`     | rw   | r/na  |      | rset   | wclr    |       |       |      |       |      |       |             |
+| `w0src`    | rw   | r/na  |      | rclr   | wzs     |       |       |      |       |      |       |             |
+| `w1src`    | rw   | r/na  |      | rclr   | woset   |       |       |      |       |      |       |             |
+| `wsrc`     | rw   | r/na  |      | rclr   | wset    |       |       |      |       |      |       |             |
+| `rwl` (ext) | rw  | r/na  |      |        |         |       |       |      | true  |      |       |             |
+| `rwl` (ref) | rw  | r/na  |      |        |         |       |       |      | ref   |      |       |             |
+| `rwe` (ext) | rw  | r/na  |      |        |         |       |       | true |       |      |       |             |
+| `rwe` (ref) | rw  | r/na  |      |        |         |       |       | ref  |       |      |       |             |
+| `rwc` (ext) | rw  | r/na  |      |        |         |       | true  |      |       |      |       |             |
+| `rwc` (ref) | rw  | r/na  |      |        |         |       | ref   |      |       |      |       |             |
+| `rws` (ext) | rw  | r/na  |      |        |         | true  |       |      |       |      |       |             |
+| `rws` (ref) | rw  | r/na  |      |        |         | ref   |       |      |       |      |       |             |
+| `rwtrg`    | rw   | r/na  |      |        |         |       |       |      |       |      | true  |             |
+| `rotrg` (ext) | r  | rw/w  |      |        |         |       |       |      |       |      | true  |             |
+| `rotrg` (ref) | r  | r/na  | ref  |        |         |       |       |      |       |      | true  |             |
+| `wotrg`    | w    | r     |      |        |         |       |       |      |       |      | true  |             |
+| `w1trg`    | rw   | r/na  |      |        |         |       |       |      |       |      |       | true        |
+| `w1`       | rw1  | r/na  |      |        |         |       |       |      |       |      |       |             |
+| `wo1`      | w1   | r     |      |        |         |       |       |      |       |      |       |             |
+
+## General error rules (apply to all types)
+- `hw = rw1` or `hw = w1` (write-once on the hardware side) — RgGen has no corresponding concept.
+  ERROR for every type. (The hw column values in the table above are limited to r / na / rw / w;
+  rw1/w1 on hw are always rejected.)
+
+## Not generated / not supported (no row above)
+- `w0trg`, `row0trg`, `row1trg` — not expressible in SystemRDL.
+- `rowo`, `rowotrg` — not supported; bit-field overlap is an error.
+- `counter`, `intr` — front-end does not support them yet.
+- `reserved`, `indirect` — no SystemRDL equivalent.
+- `custom` — held for v1.
+
+## Reference (RgGen output) per type
+- `ro` (ref) / `rotrg` (ref): reference = the `next` target field.
+- `rwl`/`rwe`/`rwc`/`rws` (ref rows): reference = the swwel/swwe/hwclr/hwset target field.
+- `rohw`/`rwhw` (ref rows): reference = the `we` target field (valid signal source).
+- `rc`/`w0c`/`w1c`/`wc`: RgGen reference means a data mask; NOT settable from SystemRDL → no reference.
+- All other types: no reference.

data/notes/external_reg_regfile_mapping.md

@@ -0,0 +1,37 @@
+# External reg / regfile → RgGen: Deferred Design Notes
+
+This document records the conversion approach that was worked out for external `reg`/`regfile`,
+so it is available when the feature is picked up later. The key point is that RgGen cannot
+generate at reg/regfile granularity, so the contents must be wrapped in a register_block. (This
+is unlike a nested addrmap, which is itself an RTL generation unit and maps directly to a
+register_block without wrapping — see `systemrdl_to_rggen_mapping.md`.)
+
+Note: the RgGen "External + child block reference" extension (rggen/rggen#291) is NOT a
+prerequisite for this. #291 lets the user name the child register_block and avoid entering its
+size by hand, but external reg/regfile can also be converted without it by computing the region
+size in the converter (the same size-calculation approach used for `mem`).
+
+## Trigger
+
+Each of the following is an independent implementation boundary handled the same way:
+- an external `reg` (`Reg#external` = true),
+- an external `regfile` (`RegFile#external` = true).
+
+## Two outputs
+
+Each such subtree produces TWO outputs:
+1. On the enclosing map, reserve its address region as an RgGen `external` register. Its `address`
+   and `size` come from the model (`address`/`size`).
+2. Synthesize a NEW register_block that wraps the reg/regfile, and place the reg/regfile inside
+   it. Unlike a nested addrmap (which is itself a register_block and goes through the normal
+   conversion flow), a reg/regfile cannot itself become a register_block — RgGen cannot generate
+   at reg/regfile granularity — so an enclosing register_block hierarchy has to be created for it.
+   The synthesized block is what lets RgGen actually generate the contents.
+
+## Rules for the synthesized wrapping register_block
+
+- Name: the ancestor instance names joined with `__` (e.g. regfile `foo[2]` containing external
+  reg `bar` → `foo__0__bar`). Array subscripts also use `__`, so the separator is uniform.
+- Addresses inside the synthesized block are re-based to a 0 offset (it is an independent block).
+- `bridge` is NOT part of the trigger; it only indicates whether the external boundary involves
+  bus/protocol conversion.

data/notes/interrupt_aggregation_policy.md

@@ -0,0 +1,50 @@
+# Interrupt Aggregation and Port Generation Policy
+
+This document records the implementation policy for how interrupt outputs are aggregated and exposed at module boundaries in generated RTL. The SystemRDL specification fixes register-level aggregation but is silent on how the resulting `intr`/`halt` outputs are surfaced at the boundary of `addrmap` modules. The choices below are implementation decisions and not behavior mandated by the specification.
+
+## Scope
+
+The decisions here govern the backend (RTL generator). The elaborator's responsibility is to produce the elaborated model in which `intr` fields, their `enable`/`mask` (and `haltenable`/`haltmask`) bindings, and the `next` connections among interrupt registers are all preserved. The behavior described below is how the backend then translates that model into module ports and aggregation logic.
+
+## Register-Level Aggregation (Specification-Mandated)
+
+SystemRDL 10.8 specifies that a register containing one or more `intr` fields implicitly has an `intr` register property representing the inclusive OR of all interrupt bits in the register after any field `enable`/`mask` logic. If `haltenable`/`haltmask` is specified on at least one field, the register also has a `halt` property representing the OR of those bits after haltenable/haltmask. The `intr` property is always present on an interrupt register (10.8.1 b); the `halt` property is present only when haltenable or haltmask exists (10.8.1 c). These are register-level outputs in the SystemRDL sense: they exist as values that the language permits to be referenced on the right-hand side of an assignment.
+
+This document does not modify the register-level aggregation rule; it follows the specification.
+
+## Boundary Port Exposure (Implementation Policy)
+
+SystemRDL does not specify how a register's `intr`/`halt` output is realized at an `addrmap` module's HDL boundary. The specification merely makes the aggregated value a referenceable property; whether and how it becomes an external port is left to the implementation.
+
+### Decision
+
+For every register that has an `intr` output (and likewise for `halt`), the enclosing `addrmap` module exposes that register's `intr` output as a port on the module boundary. The same applies to `halt`. Aggregation stops at the register level; the `addrmap` module does not perform additional OR-reduction across multiple registers.
+
+When an `addrmap` is instantiated inside another `addrmap`, the child `addrmap` is treated as an external component (per 13.4.1 c-4: "addrmap instances are always considered external"). The child module's per-register `intr`/`halt` ports appear on the parent's interface to the child instance. Aggregation across registers, or across child `addrmap` instances, is performed by user-written aggregation registers in the parent (the pattern shown in the specification's 17.2 example).
+
+### Rationale
+
+This policy keeps the backend's behavior close to what the specification actually says, without adding implementation-defined aggregation rules:
+
+- The specification defines aggregation only at the register level. Per-register boundary exposure preserves that granularity; aggregating further at the `addrmap` level would introduce an `intr`/`halt` semantics that the specification does not describe.
+- Typical CSR designs have only a small number of interrupt registers per `addrmap`, so the per-register port count is manageable in practice and does not produce unwieldy module interfaces.
+- Per-register ports allow multiple categories of interrupts (e.g. priority levels, error vs. event, distinct CPU targets) to be exposed independently. An `addrmap`-level aggregated port would be limited to a single `intr` and a single `halt`, constraining the designer to that one categorization.
+- Hierarchical aggregation through nested `addrmap`s is consistent with how SystemRDL itself handles cross-block interrupt aggregation: by user-written aggregation registers connecting lower-level `intr` outputs via `next`. The boundary behavior chosen here lines up with that pattern: each register's `intr` is available as a port; aggregation across registers (whether within an `addrmap` or across `addrmap`s) is the user's responsibility, expressed via aggregation registers and `next` references.
+
+### Status
+
+The register-level aggregation (10.8) is specification-mandated and is followed. The boundary exposure policy -- per-register ports, no `addrmap`-level aggregation -- is an implementation choice that the specification does not constrain. Other tools may make different choices (for example, exposing only the top-level aggregated output, or providing both per-register and `addrmap`-level outputs). Behavior may therefore differ across tools at the boundary, even when the SystemRDL input is the same.
+
+If a use case requires `addrmap`-level aggregation in addition to per-register exposure, this policy can be extended without contradicting the specification, because the specification does not forbid additional `addrmap`-level outputs; it simply does not require them.
+
+## Final Interrupt Pin to the Outside
+
+The SystemRDL specification does not describe how a chip-level interrupt pin is produced from the per-register `intr` outputs. Within a SystemRDL design, the only mechanism for combining interrupts across registers is the user-written aggregation register (see 17.2 example).
+
+Under this policy, the final external interrupt pin is the `intr` port of a register that aggregates the relevant lower-level `intr` signals via `next`. When that register is contained directly in the top-level `addrmap`, its `intr` port appears on the top-level module's boundary and constitutes the chip-level interrupt output. There is no separate "top-level interrupt pin" mechanism; the final pin is simply a register-level `intr` port on the top module, just like any other register's `intr` port.
+
+## Comparison with Other Implementations
+
+PeakRDL-regblock follows the same register-level boundary policy described above (per-register `intr`/`halt` outputs at the module boundary; no `addrmap`-level aggregation). This is the most direct reading of the specification and tends to be the convergent choice across implementations that prioritize specification fidelity.
+
+Implementations that perform `addrmap`-level aggregation, or that expose only a single top-level interrupt port, exist in some tools as a generation option, but they go beyond what the specification describes.

data/notes/precedence_handling_policy.md

@@ -0,0 +1,38 @@
+# Precedence Handling Policy
+
+This document records how RgGen handles the SystemRDL `precedence` property, which is silent on the spec's part regarding its compatibility with implementations that fix software/hardware precedence rather than making it per-field configurable.
+
+## Background
+
+SystemRDL defines the `precedence` field property (clause 9.10) to control which side wins when software and hardware attempt to write the same field on the same cycle:
+
+- `precedence = sw` (the default) -- software takes precedence over hardware.
+- `precedence = hw` -- hardware takes precedence over software.
+
+RgGen, by contrast, fixes hardware-side precedence in all field types. The rationale is that software writes are inherently retryable by the host -- the host can read the field back and re-issue the write if it sees the value did not stick -- whereas hardware writes typically signal a time-sensitive event (an error capture, a completion notification, a state transition) that has no comparable retry mechanism. Granting hardware precedence is therefore the safer default: the side that cannot easily recover from being overwritten is the side that wins.
+
+This creates a mismatch between the SystemRDL default (`sw`) and RgGen's fixed behavior (`hw`). A SystemRDL file that omits `precedence` is, by the spec's default, requesting software precedence -- the opposite of what RgGen will actually produce. Silently accepting such input would invert the field's semantics without notice.
+
+A further complication: by the time SystemRDL elaboration completes, the origin of a property value -- whether it was written explicitly by the user or filled in from the default -- is generally lost. The elaborated model only carries the final value. RgGen therefore cannot distinguish "the user wrote `precedence = sw`" from "the user omitted `precedence` and the default of `sw` was applied"; both reach the backend as `precedence = sw`.
+
+This rules out any policy that depends on telling explicit and defaulted values apart. The handling must work purely from the effective value as it appears in the elaborated model.
+
+## Solution: A `precedence` Ignore Mode
+
+RgGen introduces a configuration flag, the `precedence` ignore mode, that selects between two behaviors. The flag is set at the project level via RgGen configuration; it is not a SystemRDL property and cannot be changed per-field or per-register.
+
+### Ignore Mode On
+
+The `precedence` property is treated as something RgGen does not implement. The elaborated value of `precedence` on each field is simply not consulted by the RtL generator; every field is generated with hardware precedence regardless of what its `precedence` value happens to be.
+
+No diagnostic is emitted. A SystemRDL file may contain `precedence = sw`, `precedence = hw`, or omit the property entirely; in all cases the generated RTL is the same.
+
+This mode silently sets aside whatever the SystemRDL source requests via `precedence`. It is therefore not the default: making the silent override the default would build a hidden inversion of semantics into the standard behavior. Users select this mode explicitly when they accept that trade-off in exchange for being able to process SystemRDL files that omit `precedence` without further annotation.
+
+### Ignore Mode Off (Default)
+
+The elaborated value of `precedence` is checked on every field. If it is `sw`, the field is rejected as an error; if it is `hw`, it is accepted.
+
+Because elaboration cannot distinguish an explicit value from a defaulted one, this mode rejects every field whose `precedence` is `sw` for any reason, including fields where the user simply omitted the property. As a practical consequence, the SystemRDL source must set `precedence = hw` explicitly on every field that should be accepted -- typically via `default precedence = hw;` at the addrmap or register scope, which sets the scope-wide default rather than requiring per-field annotation.
+
+This mode is the default. The reason is that any disagreement between the SystemRDL request and RgGen's actual behavior is surfaced as an explicit error rather than being silently overridden. A SystemRDL file is processed only when its `precedence` settings are consistent with the hardware-precedence model that RgGen produces; otherwise the user is required to acknowledge the mismatch, either by adding `default precedence = hw;` (matching RgGen's behavior at the source level) or by explicitly selecting ignore mode on (accepting the override). The default refuses to perform a silent semantic inversion.

data/notes/systemrdl_rggen_gap_analysis.md

@@ -0,0 +1,132 @@
+# SystemRDL vs RgGen Gap Analysis
+
+A comparison of SystemRDL 2.0 against RgGen ([wiki](https://github.com/rggen/rggen/wiki/Register-Map-Specifications)). This document organizes each SystemRDL feature by its handling policy in RgGen -- mapped, not supported, or already implemented -- as a reference for SystemRDL input support.
+
+---
+
+## 1. Already Supported in RgGen
+
+SystemRDL concepts for which RgGen already provides equivalent or near-equivalent functionality. SystemRDL input can be mapped directly.
+
+| SystemRDL Concept             | RgGen Equivalent                            | Notes                                                                                                                                       |
+| ----------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `regfile` component           | `register_file`                             | Hierarchical grouping                                                                                                                       |
+| `external reg`                | `external` register type                    | Single external register                                                                                                                    |
+| `encode` (enumeration)        | `label`                                     | Named enumerated values                                                                                                                     |
+| `counter` (basic)             | `counter` bit field type                    | RgGen has a counter type (up/down/clear). NOTE: SystemRDL conversion does not support it yet — the front-end (systemrdl elaborator) does not handle `counter`, so it is out of current scope.       |
+| `swacc`                       | `rwtrg` / `rotrg` / `wotrg`                 | Read/write trigger outputs (via `swacc=true`). `swmod` has no faithful target → error. See matrix.                                          |
+| `singlepulse`                 | `w1trg`                                     | Write-1 pulse. `w0trg` is not generated (singlepulse triggers on write-1). See matrix.                                                      |
+| `errextbus`                   | Error input on `rggen_bus_if` (default)     | rggen_bus_if has an error input by default, so an explicit `errextbus` needs no action → ignored.                                           |
+| Register arrays               | `size` + `step`                             | Multi-dimensional supported (front-end array flattening applies; see systemrdl_to_rggen_mapping.md)                                         |
+
+---
+
+## 2. Mapping Strategy for SystemRDL Bit Field Types
+
+The detailed and authoritative mapping from SystemRDL field property combinations to RgGen bit
+field types now lives in dedicated notes:
+
+- [bit_field_type_matrix.md](bit_field_type_matrix.md) — the full decision matrix (every
+  SystemRDL property column vs. each RgGen type), used as the converter's dispatch reference.
+- [bit_field_type_mapping.md](bit_field_type_mapping.md) — a per-type migration guide describing
+  each RgGen type's distinguishing properties and reference semantics.
+
+Cross-cutting property policies and the full list of properties/structures that are rejected as
+errors are in [systemrdl_to_rggen_mapping.md](systemrdl_to_rggen_mapping.md) (field layer).
+
+---
+
+## 3. Implementation Plan
+
+Features for which an implementation plan or handling policy has been defined. Some are tracked as issues for future implementation; others have their handling policy documented in a separate notes file.
+
+| Feature                                                                | Issue                                                | Status         |
+| ---------------------------------------------------------------------- | ---------------------------------------------------- | -------------- |
+| **Alias register type**                                                | rggen/rggen#287                                      | Filed          |
+| **Interrupt support** (trigger extension + block-level aggregation)    | rggen/rggen#290                                      | Filed. NOTE: SystemRDL conversion does not support `intr` yet — front-end does not handle it, so out of current scope. |
+| **External + child block reference**                                   | rggen/rggen#291                                      | Filed          |
+| **Counter saturate/wrap boundary behavior** (spec-level specification) | rggen/rggen#292                                      | Filed          |
+| **User-Defined Properties (UDP)**                                      | See [udp_handling_policy.md](udp_handling_policy.md) | Policy defined |
+| **`precedence` property handling**                                     | See [precedence_handling_policy.md](precedence_handling_policy.md); conversion behavior summarized in [systemrdl_to_rggen_mapping.md](systemrdl_to_rggen_mapping.md) | Policy defined |
+
+### Mapping Coverage by Issue
+
+| SystemRDL Feature                       | Corresponding RgGen Extension                                                     |
+| --------------------------------------- | --------------------------------------------------------------------------------- |
+| `alias` keyword                         | rggen/rggen#287 alias register type                                               |
+| `intr` field property + sticky variants | rggen/rggen#290 (existing `w1c` family + trigger + aggregation)                   |
+| Trigger mode (level/edge)               | rggen/rggen#290 `trigger` option                                                  |
+| Interrupt aggregation (OR output)       | rggen/rggen#290 block-level `interrupt` attribute                                 |
+| `external regfile { ... }`              | External + child block reference                                                  |
+| `mem` component                         | External + child block reference (mementries x memwidth normalized to byte_size)  |
+| `incrsaturate` / `decrsaturate`         | Counter saturate/wrap boundary behavior (this feature)                            |
+
+---
+
+## 4. Resolved on the SystemRDL Parser / Elaborator Side
+
+Language constructs that exist in SystemRDL but are resolved at elaboration time. By the time data reaches the RgGen internal model, these are already materialized, so RgGen DSL does not need equivalent mechanisms.
+
+| SystemRDL Feature                                                                                             | Resolution Strategy                                  |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `default` keyword scope inheritance                                                                           | Expanded to each field during elaboration            |
+| Dynamic property assignment (`inst->prop = value;`)                                                           | Final values resolved during elaboration             |
+| Parameterized components (`#(WIDTH = 8)`)                                                                     | Instantiated with concrete values during elaboration |
+| Addressing (`@` explicit address, `%=` alignment, `alignment` property, compact / regalign / fullalign modes) | Concrete addresses finalized during elaboration      |
+| Mixed anonymous/named definitions                                                                             | Uniquified during elaboration                        |
+
+---
+
+## 5. Not Supported
+
+Features that exist in SystemRDL but are deliberately not supported in RgGen. **All items in this section are rejected with an explicit error during SystemRDL input processing.**
+
+### 5.1 Out of Scope (Beyond CSR Tool Responsibility)
+
+| Feature                                                     | Reason                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal` component                                          | RgGen does not have a first-class signal concept. HW access properties (`we`, `wel`, `hwclr`, `hwset`, `swwe`, `swwel`, etc.) can be expressed via the boolean form (auto-generated external ports) or field references (internal control), covering practical use cases without an explicit signal declaration. |
+| Reset signals (`resetsignal`, `field_reset`, `cpuif_reset`) | Uniformly rejected. RgGen targets a single reset domain (`i_rst_n`); supporting signal-based reset specifications would entail multiple reset domains and the associated RDC (Reset Domain Crossing) analysis, which is beyond CSR tool scope. Only constant reset values via `initial_value` are supported.     |
+| Counter `overflow` / `underflow` output                     | HW-to-HW event signals, outside CSR domain                                                                                                                                                                                                                                                                       |
+| Counter `incrthreshold` / `decrthreshold`                   | Same as above                                                                                                                                                                                                                                                                                                    |
+| `constraint` block                                          | Verification-specific syntax with limited demand                                                                                                                                                                                                                                                                 |
+
+### 5.2 No Corresponding Feature
+
+| Feature                                  | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Field overlap within a register (10.1 d) | RgGen does not have a mechanism to place multiple fields at overlapping bit positions within a register. The SystemRDL exception for read-only / write-only pairs is rejected (no `rowo`). See [systemrdl_to_rggen_mapping.md](systemrdl_to_rggen_mapping.md).                                                                                                                                                                                                                                                                                                                    |
+| Register address not aligned to bus width | RgGen does not support placing a register at an address that is not a multiple of the configured bus width. The constraint `(address % bus_width) == 0` applies to every register, whether its address was assigned via `@` or by automatic allocation. |
+| `sharedextbus`                           | Combines multiple external components into a single bus interface. RgGen has no feature to merge external interfaces, so the intent cannot be represented → rejected as error. See [systemrdl_to_rggen_mapping.md](systemrdl_to_rggen_mapping.md). |
+
+### 5.3 Low Usage Frequency
+
+| Feature                                            | Notes                                                                                                   |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `anded` / `ored` / `xored` (field-level reduction) | Rare in practice; no RgGen feature → rejected as error. Interrupt aggregation use case is covered by rggen/rggen#290 |
+| `swmod` (as a standalone property)                 | No faithful RgGen target → rejected as error. (`swacc` IS supported: it drives `rwtrg`/`rotrg`/`wotrg`; see [bit_field_type_matrix.md](bit_field_type_matrix.md).) |
+| `hwenable` / `hwmask` (bit-level HW write control) | Rare in practice; no RgGen feature → rejected as error. Per-bit control can be expressed by splitting into separate fields with `rwe`/`rwl` |
+| `bridge` addrmap (multi-view)                      | Limited real-world use                                                                                  |
+| `struct` definition and usage                      | Used only within SystemRDL source (UDP types, component parameters, struct members) and does not survive elaboration. Rare in practical CSR descriptions. |
+
+Note: For `hwenable` / `hwmask`, equivalent semantics can be expressed using `rwe` / `rwl`.
+
+### 5.4 High Parser Implementation Cost
+
+| Feature                                                                                             | Notes                                                                                                                                                                                                                                                     |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Preprocessor (Perl-embedded templates, Verilog-style `` `include `` / `` `define `` / `` `ifdef ``) | Implementing these in the SystemRDL parser carries a high cost, particularly for tracking token positions through template expansion to produce meaningful error messages. The core register modeling concern is far removed from preprocessor semantics. |
+
+---
+
+## 6. Architecturally Unnecessary
+
+SystemRDL properties that exist because SystemRDL is a description language only, and have no role in RgGen's integrated spec + RTL/RAL generation architecture. Some are automatically resolved by RgGen's own mechanisms; others have no corresponding concept and are simply ignored.
+
+| Feature                                              | RgGen Resolution                                                                                                                  |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `hdl_path` / `hdl_path_slice` / `hdl_path_gate` etc. | Automatically embedded during RAL generation, based on RgGen's own RTL hierarchy                                                  |
+| `donttest` / `dontcompare` / `internal`              | Handled standardly on the RAL generation side                                                                                     |
+| `name`                                               | Descriptive display name for documentation; RgGen has no corresponding concept and silently ignores the property                  |
+
+**Input handling**: Silently discard (no warning needed). User-provided HDL paths would not match RgGen's generated RTL hierarchy anyway.