rggen-systemrdl 0.1.0

data/notes/systemrdl_to_rggen_mapping.md

@@ -0,0 +1,264 @@
+# SystemRDL → RgGen Mapping: Design Notes
+
+This document records confirmed design decisions for the SystemRDL front-end to RgGen
+register-map conversion. The SystemRDL support is an add-on feature; perfect coverage is a
+non-goal. Deferred / not-yet-supported items are tracked separately in `systemrdl_to_rggen_TODO.md`.
+
+## Scope
+- Root `addrmap` → RgGen register_block
+- `regfile` → RgGen register_file
+- `reg` → RgGen register
+- `field` → RgGen bit_field
+- Nested `addrmap` → RgGen `external` region on the enclosing map; the addrmap is also converted
+  to its own register_block through the normal flow (see "External components" below).
+- External `reg`/`regfile` → ERROR in the first release (deferred; see "External components").
+- `mem` → RgGen `external` register (region reservation only; see "mem" below).
+
+## Layer correspondence
+
+| SystemRDL              | RgGen                          |
+| ---------------------- | ------------------------------ |
+| root `addrmap`         | register_block                 |
+| `regfile`              | register_file                  |
+| `reg`                  | register                       |
+| `field`                | bit_field                      |
+| nested `addrmap`       | `external` region + its own register_block |
+| external `reg`/`regfile` | ERROR (first release; deferred)          |
+| `mem`                  | `external` register (region reservation only) |
+
+## Array handling & name conversion
+- `reg`, `regfile`, and `addrmap` can be arrays. **`field` is never an array**: in a
+  field declaration `foo[4]` specifies bit WIDTH (and `foo[7:0]` specifies msb:lsb), NOT an array
+  subscript. So the flatten/`__`-subscript handling below does not apply to fields; a field's
+  `[...]` maps to bit_assignment `lsb`/`width` instead (see field layer).
+- Arrays are flattened into individual elements. No reconstruction back into RgGen
+  `size` / `sequence_size`.
+- Subscripts are rendered into the name with a double-underscore `__` separator:
+  - `foo[0]` → `foo__0`
+  - multi-dimensional `foo[1][0]` → `foo__1__0` (all dimensions use `__`, consistently)
+- Conversion-time validation: any SystemRDL instance name (all layers, arrayed or not) that
+  itself contains `__` is an ERROR. This reserves `__` exclusively as the array-expansion
+  separator, eliminating name-collision ambiguity at its root (rather than merely
+  lowering collision probability).
+  - SystemRDL lexical rules (spec 5.1.1) permit `__` in identifiers; this restriction is an
+    extra constraint imposed only when using the RgGen-conversion add-on feature.
+- Post-conversion duplicate-name detection is delegated to RgGen's existing validation; the
+  converter does NOT re-implement duplicate checking.
+
+## addrmap (root) → register_block
+
+| RgGen register_block | SystemRDL addrmap        | Conversion / notes |
+| -------------------- | ------------------------ | ------------------ |
+| `name`               | instance name (`name`)   | Apply `__` restriction check. Root addrmap is non-arrayed, so no subscript conversion normally. |
+| `byte_size`          | addrmap occupied size    | Uses the occupied-size value provided by the gem directly (front-end fix requested; see feedback). The converter does not compute it from child placement. |
+| `bus_width`          | —                        | No corresponding concept in SystemRDL. Not mapped; deferred to RgGen config. |
+| `protocol`           | —                        | No corresponding concept in SystemRDL. Not mapped; deferred to RgGen config. |
+| `comment`            | `desc` property          | Used directly. `display_name` (SystemRDL `name` property) is a short label, not used for comment. |
+
+### addrmap: properties that cause an ERROR
+These SystemRDL properties have no corresponding concept in RgGen. If encountered, the converter
+errors out rather than silently ignoring them (silent drop would change the design intent).
+- `sharedextbus` — combines multiple external components into a single bus interface (creates a
+  single set of control signals for the whole addrmap instead of per-component). Only meaningful
+  when the addrmap contains external components. This is about external-component bus-interface
+  generation, NOT the 13.5 multiple-view/bridge feature. RgGen has no feature to combine external
+  interfaces into one, so this is a **permanent ERROR** (independent of the external-scope
+  decision): even once external components are supported, RgGen still cannot merge their
+  interfaces, so `sharedextbus` remains unsupported.
+- bridge / multiple-view related properties (spec 13.5) in general — e.g. `bridge`. No RgGen concept.
+- `bigendian` / `littleendian` — ERROR if either is explicitly true. Even `littleendian` is an
+  error: although RgGen is also little-endian, its word-placement model for registers spanning
+  multiple words differs from SystemRDL 17.3.2 (Byte ordering), so passing `littleendian` through
+  by name would misplace words. If neither is specified, pass through using RgGen's default
+  (little-endian).
+  - Residual caveat: for registers that span multiple words (`regwidth > accesswidth`), the
+    word-placement model differs from SystemRDL 17.3.2 (Byte ordering). This difference is a
+    confirmed property of the conversion, not a maybe. The converter does NOT detect or correct
+    it; instead, the README states this word-ordering difference as a documented limitation of
+    the add-on conversion.
+- `rsvdset` / `rsvdsetX` — control the read value of reserved / unassigned regions (whether
+  unassigned bits read as 1, or as X/undefined). RgGen has no mechanism to specify the read value
+  of unassigned regions, so there is nowhere to map these. ERROR if set.
+- `msb0` — ERROR if set (true). `msb0` reverses bit numbering so that `regwidth-1` is the least
+  significant bit (spec 13.4.1), the opposite of the default `lsb0` mode. RgGen assumes `lsb0`
+  numbering; under `msb0` the field `lsb`/`msb` positions would be interpreted in reverse and
+  would be misplaced, so the mode cannot be represented. (`lsb0` is the default and needs no
+  action; it is not an error. `msb0` and `lsb0` are mutually exclusive per spec 13.4.1.)
+  Inference of `msb0` from the first field's explicit bit indices (spec 13.4.2) is unsupported by
+  the front-end, so only an explicitly set `msb0` property reaches the converter.
+
+### addrmap: properties that are IGNORED (safe to drop)
+- `errextbus` — indicates the (external) addrmap instance has an error input. RgGen's
+  `rggen_bus_if` has an error input by default, so RgGen always satisfies the `errextbus`
+  behavior. Ignoring the property therefore does not lose design intent (unlike the error-listed
+  properties above).
+- `accesswidth` — IGNORED. RgGen derives access width from its `bus_width` (RgGen config, not
+  mapped from SystemRDL). Safe to ignore: if `accesswidth` disagrees with `bus_width`, the
+  resulting addresses violate RgGen's `address % bus_width == 0` rule and are caught by the later
+  address check.
+
+## reg → register
+
+| RgGen register   | SystemRDL reg           | Conversion / notes |
+| ---------------- | ----------------------- | ------------------ |
+| `name`           | instance name (`name`)  | Apply `__` restriction check; arrayed regs are flattened with `__` subscript conversion into individual registers. |
+| `offset_address` | `address` property      | Direct copy. Both RgGen `offset_address` and SystemRDL `address` are offsets from the block start, so they coincide and `address` is used as-is. |
+| `size`           | (basically unused)      | Arrays are flattened, so repetition `size` is not used. First release: single element. |
+| `type`           | (fixed `default`)       | Normal regs map to `default`. See register-type notes below. |
+| `comment`        | `desc` property         | Used directly. |
+
+### register-type notes
+- `default` — normal reg. Supported (fixed for first release).
+- `external` — an external `reg` (`Reg#external` = true) is NOT supported in the first release →
+  ERROR. See the "External components" section (deferred design in `external_reg_regfile_mapping.md`).
+- `indirect` — **permanently not applicable.** RgGen `indirect` multiplexes multiple registers
+  at one address, selected by index bit fields. SystemRDL has NO indirect-access mechanism, and
+  SystemRDL `alias` is a DIFFERENT concept (a second name/address onto the same storage, not
+  index-based multiplexing). `indirect` can therefore never be produced by the conversion.
+- `reserved` / `maskable` / `rw` — SystemRDL-side trigger for these is TBD; not used in first release.
+
+### reg: properties that cause an ERROR
+These SystemRDL reg properties have no corresponding concept in RgGen. If encountered, the
+converter errors out rather than silently ignoring them.
+- `shared` — shared component (spec 13.5, bridges / multiple-view address maps). RgGen has a
+  single-address-space-per-block model with no multiple-view/shared-storage concept, so there is
+  nowhere to map this. Even once the front-end supports it, the converter must error.
+
+### reg: properties that are IGNORED (safe to drop)
+- `errextbus` — indicates the (external) regfile has an error input. Same rationale as the
+  addrmap `errextbus`: RgGen's `rggen_bus_if` has an error input by default, so ignoring it loses
+  no design intent.
+- `accesswidth` — IGNORED (same rationale as addrmap: bus_width is RgGen config; a mismatch is
+  caught by the later `address % bus_width == 0` check).
+
+## regfile → register_file
+
+| RgGen register_file | SystemRDL regfile        | Conversion / notes |
+| ------------------- | ------------------------ | ------------------ |
+| `name`              | instance name (`name`)   | Apply `__` restriction check; arrayed regfiles are flattened with `__` subscript conversion. |
+| `offset_address`    | `address` property       | Direct copy (offset from the parent). |
+| `size`              | (not used)               | Arrays are flattened, so repetition `size` is not used. |
+| `comment`           | `desc` property          | Used directly. |
+
+### regfile: properties handled like addrmap/reg
+- `sharedextbus` — ERROR (no RgGen feature to merge external interfaces; same as addrmap).
+- `errextbus` — IGNORED (rggen_bus_if has an error input by default; same as addrmap/reg).
+- `accesswidth` — IGNORED (same as addrmap/reg; bus_width is RgGen config, mismatch caught by the address check).
+- `external` — an external regfile is NOT supported in the first release → ERROR. See the
+  "External components" section (deferred design in `external_reg_regfile_mapping.md`).
+
+## field → bit_field
+
+Bit positions are resolved by the front-end during elaboration, so the model's `msb` / `lsb`
+give the final positions.
+
+| RgGen bit_field                  | SystemRDL field         | Conversion / notes |
+| -------------------------------- | ----------------------- | ------------------ |
+| `name`                           | instance name (`name`)  | Apply `__` restriction check. No subscript conversion (fields are not arrays). |
+| `bit_assignment` `lsb`           | `lsb`                   | Direct copy (front-end-assigned). |
+| `bit_assignment` `width`         | field width (model accessor) | Use a `width` accessor on the model (front-end fix requested; see feedback) rather than computing `msb - lsb + 1` on the converter side. |
+| `bit_assignment` `sequence_size` / `step` | —              | Not used; fields are not arrays. |
+| `initial_value`                  | `reset` property        | Maps the reset value (constant only). If `reset` is absent, `initial_value` is left unset — the converter does NOT substitute 0; RgGen's own validation errors if a type that requires an initial value has none. A `reset` given as a reference (to another field) is unsupported → ERROR. A user-defined `resetsignal` is unsupported → ERROR. See field error list below. |
+| `type`                           | (sw/hw/onread/onwrite/hwset/hwclr/swwe/swwel/we/swacc/singlepulse/… combination) | Main conversion. See `bit_field_type_mapping.md` for the full RgGen-type ← SystemRDL-property table and the cross-cutting property policies. |
+| `reference`                      | instance reference (e.g. `next`, swwe/swwel/hwclr/hwset target) | Only SystemRDL **instance** references map to RgGen `reference`. **Property** references → ERROR. Mask-purpose references (`rc`/`w0c`/`w1c`/`wc`) are not specifiable from SystemRDL. See `bit_field_type_mapping.md`. |
+| `comment`                        | `desc` property         | Used directly. |
+
+### field: properties / values that cause an ERROR
+- `reset` given as a **reference** (to another field's value) rather than a constant — RgGen
+  `initial_value` accepts a constant value only and has no dynamic/reference reset, so a
+  reference reset cannot be represented. ERROR.
+- `resetsignal` (user-defined reset signal) — RgGen does not support user-defined reset signals,
+  so specifying `resetsignal` is unsupported. ERROR.
+- Properties/values with no corresponding RgGen feature — ERROR if used: `wel`, `swmod`, `anded`,
+  `ored`, `xored`, `hwenable`, `hwmask`, `paritycheck`, `ruser` (onread=ruser),
+  `wuser` (onwrite=wuser), and `hw = rw1` / `hw = w1` (hardware-side write-once).
+- Property reference used anywhere — ERROR. SystemRDL references come in two kinds: instance
+  references and property references (e.g. `other->prop`). RgGen supports instance references
+  only. (Applies wherever a reference is used: `ro`/next, rwl/rwe swwe/swwel, rwc/rws hwclr/hwset,
+  etc.)
+- Combinations that fit no named RgGen type — ERROR in the first release (`custom` is not used
+  yet; see `bit_field_type_mapping.md`).
+
+### field: checks delegated to RgGen core (not done by the converter)
+- Bit-field overlap — two or more fields at the same bit position in a register (SystemRDL allows
+  this when read/write are mutually exclusive). The converter does NOT detect this; it just emits
+  each field's `bit_assignment`, and RgGen's own bit_assignment validation rejects the overlap
+  (RgGen has no merged read-only+write-only field — `rowo` is not supported). Listed here so the
+  behavior is documented, but it is not a converter-side error.
+
+### field: precedence handling
+Handled per a project-level "precedence ignore mode" flag (see rggen/rggen-systemrdl
+`notes/precedence_handling_policy.md`). RgGen fixes hardware precedence; the SystemRDL default is
+`sw`. The flag is set via RgGen configuration, not per-field/per-register.
+- Ignore mode OFF (default): field with effective `precedence=sw` → ERROR; `precedence=hw` →
+  accepted. (Elaboration cannot tell an explicit value from a defaulted one, so `sw` is rejected
+  regardless; users set `default precedence = hw;` at a scope.)
+- Ignore mode ON: `precedence` is not consulted; all fields generated with hw precedence, no
+  diagnostic.
+
+## External components
+
+### Nested addrmap → external region
+
+A nested (non-root) `addrmap` instance represents an independent implementation boundary.
+(`AddrMap` has no `external` property; external/internal does not apply to an addrmap itself, so
+the trigger is structural: any addrmap below the root counts.)
+
+For a nested addrmap, the only thing this conversion does is reserve its address region on the
+enclosing map as an RgGen `external` register (its `address`/`size` come from the model).
+
+The addrmap's own contents do NOT need a special carve-out step here: an addrmap is itself an RTL
+generation unit with its own definition, so running that definition through the normal
+register_block conversion (the same path used for the root addrmap) produces its register_block.
+
+`bridge` is NOT part of the trigger; it only indicates whether the external boundary involves
+bus/protocol conversion.
+
+### External reg / external regfile → ERROR (first release)
+
+An external `reg` (`Reg#external` = true) and an external `regfile` (`RegFile#external` = true)
+are NOT supported in the first release and are ERRORs. Silently dropping them would lose design
+intent, so the converter errors out rather than ignoring the external boundary.
+
+The conversion scheme worked out for them — reserve the region on the enclosing map and wrap the
+contents in a separately-converted register_block (RgGen cannot generate at reg/regfile
+granularity, so the wrapping is required) — is recorded separately in
+`external_reg_regfile_mapping.md` for when the feature is picked up later.
+
+
+## mem → external register
+
+A SystemRDL `mem` is mapped to an RgGen `external` register. `external` is exactly the RgGen
+construct intended for this purpose: it reserves an address region whose contents are provided by
+a user implementation. The memory contents are therefore not generated by RgGen (and not by the
+converter); the converter only reserves the region.
+
+Because the contents are a user implementation, a `mem` is NOT handled like the "External
+components" above: it produces no carved-out register_block, only the region reservation on the
+enclosing map.
+
+| RgGen external | SystemRDL mem          | Conversion / notes |
+| -------------- | ---------------------- | ------------------ |
+| `name`         | instance name (`name`) | Apply `__` restriction check; arrayed mems are flattened with `__` subscript conversion. |
+| `offset_address` | `address` property   | Direct copy (offset from the parent), same as reg/regfile. |
+| `size`         | model `size` (byte size), converted | Element count in `bus_width` units; see below. |
+| `comment`      | `desc` property        | Used directly. |
+
+### mem: size calculation
+RgGen's `external` `size` is an element count expressed in `bus_width` units (how many
+`bus_width`-wide accesses the region occupies), NOT a byte size. The front-end already provides
+the mem's occupied byte size as the model's `size`, so the converter does not compute it from
+`memwidth`/`mementries`; it only converts that byte size into `bus_width` units:
+
+```
+size = byte_size / (bus_width / 8)
+```
+
+where `byte_size` is the model's `size` (the front-end computes it from `entry_width` — `memwidth`
+rounded up to a power-of-two number of bits — times `mementries`).
+
+- `bus_width` is an RgGen config value, not taken from SystemRDL (same policy as `accesswidth`,
+  which is IGNORED elsewhere).
+- If `byte_size` is not an integer multiple of `bus_width / 8`, the region cannot be expressed as
+  a whole number of `bus_width`-wide elements → ERROR.
+

data/notes/systemrdl_to_rggen_todo.md

@@ -0,0 +1,34 @@
+# SystemRDL → RgGen Mapping: TODO
+
+Not-yet-supported / deferred items. Confirmed design decisions live in
+`systemrdl_to_rggen_mapping.md`.
+
+## Deferred
+
+### SystemRDL `alias` handling (scope decision)
+- RgGen `alias` register support is tracked in rggen/rggen#287. The original proposal there
+  includes field-level attribute overrides (N:1 decoder-to-bitfield connection, per-field access
+  attribute arrays).
+- Current stance: full support is not worth the RTL-generation complexity. If implemented at all,
+  scope is limited to address multiplexing and register-level r/w switching only. Field-level
+  attribute re-assignment will NOT be done.
+- Consequence for SystemRDL conversion: SystemRDL `alias` per spec 10.5.1 rule (e) allows
+  per-field overrides of `sw`/`onread`/`onwrite`/`rclr`/`rset`/`woclr`/`woset`. Because the
+  intended RgGen scope stops at register-level r/w, SystemRDL alias inputs that vary attributes
+  per field cannot be fully represented → such inputs are out of scope (not supported / not
+  losslessly convertible). Note this is separate from RgGen `indirect`, which is permanently
+  not applicable (see mapping notes).
+
+## Open dependencies
+
+### `counter` / `intr` field types
+- SystemRDL has `counter` and `intr`, but the front-end does not support them yet → out of
+  first-release scope. The RgGen target type is deferred (not decided now); record only as
+  "unsupported, front-end does not support them yet".
+
+### `custom` bit_field type (held)
+- First release does not use RgGen `custom`. Property combinations that fit no named RgGen type
+  are errors in v1. Using `custom` to catch such combinations is possible but the verification
+  cost (confirming each combination is faithfully representable) is too high for v1 → future work.
+
+

data/notes/udp_handling_policy.md

@@ -0,0 +1,181 @@
+# UDP Handling Policy for rggen-systemrdl
+
+## Background
+
+SystemRDL provides a User-Defined Property (UDP) mechanism (Section 15 of the SystemRDL 2.0 specification) that allows tools and users to extend the language with custom properties beyond the standard set. In practice, UDPs are widely used by various SystemRDL tools to implement features that are not covered by the standard:
+
+- PeakRDL-regblock uses UDPs such as `buffer_writes`, `wbuffer_trigger`, and others to express features like write-buffered registers, read-buffered registers, signed fields, and fixed-point fields.
+- Commercial EDA tools define their own UDPs for vendor-specific features such as encrypted registers, TMR registers, and shadow registers.
+- Internal company conventions often introduce custom UDPs to capture domain-specific requirements.
+
+Since UDPs are vendor-specific and not portable across tools, any SystemRDL adapter must define a clear policy for how to handle them. This document describes the UDP handling policy adopted by rggen-systemrdl.
+
+## Design Principles
+
+### 1. Core Adapter Handles SystemRDL Standard Only
+
+The core of rggen-systemrdl is responsible for converting only the SystemRDL standard range (properties defined in the language specification). It does not interpret any UDP semantics on its own.
+
+This keeps the core adapter:
+
+- Simple and focused on the standard
+- Independent of any vendor-specific UDP definition
+- Free from the lock-in problems associated with UDP-based extensions
+
+### 2. UDP Handling via User-Defined Hooks (Plugins)
+
+When the conversion process encounters a node that has any UDP attached, the entire conversion of that node is delegated to a user-defined hook. The hook is responsible for producing the corresponding RgGen data structure for that node.
+
+This delegation model:
+
+- Respects the SystemRDL property model, where UDPs may interact with other properties in arbitrary ways
+- Keeps the core adapter's responsibility cleanly separated from UDP semantics
+- Allows users to extend support for any UDP without modifying the core
+- Makes the lock-in implications of using a UDP explicit and opt-in
+
+Hooks are registered via the plugin mechanism that RgGen already uses for extension, following the existing RgGen conventions for plugin authoring.
+
+### 3. Hierarchy-Independent Judgment
+
+UDP detection and hook delegation are determined independently at each hierarchy level (addrmap, regfile, reg, field, etc.). The presence of a UDP at one level does not change the conversion behavior of other levels.
+
+This is consistent with the SystemRDL scoping rules: a lower component cannot reference properties of its enclosing component, so a UDP at one hierarchy level cannot legitimately alter the semantics of another level.
+
+Concretely:
+
+- If a register has a UDP but its fields do not, the register conversion is delegated to a hook, while the fields are converted by the default mechanism.
+- If a field has a UDP but its parent register does not, the register conversion uses the default mechanism, while the field conversion is delegated.
+- Each level makes its own decision based only on its own UDPs.
+
+In the rare case where a UDP is intended to affect multiple hierarchy levels, the plugin may need to express claim conditions that look beyond a single node (for example, to claim a field based on a UDP attached to its parent register). Allowing plugins to define such cross-hierarchy claim conditions is technically possible but is considered a low-priority extension: well-designed UDPs respect the SystemRDL scoping rules, and the common case is fully covered by hierarchy-independent judgment.
+
+### 4. Single Active UDP Plugin
+
+Only one UDP plugin may be active at a time. If multiple UDP plugins are loaded simultaneously, rggen-systemrdl rejects the configuration with an error at startup.
+
+This constraint reflects the practical reality that a given SystemRDL codebase typically targets a single tool (such as PeakRDL) or a single internal convention, and therefore needs exactly one UDP plugin. Allowing multiple UDP plugins would introduce the need for conflict resolution between competing claims on the same node, with no clear benefit for any realistic use case.
+
+If a user genuinely needs to combine multiple UDP sets, the recommended approach is to write a combined plugin that handles both sets coherently. This keeps the single-plugin invariant intact while allowing flexibility for unusual situations.
+
+### 5. Strict by Default
+
+The default behavior when a UDP is encountered but no hook is registered to handle it is to raise an error. This prevents silent fallback to ill-defined behavior and forces users to make explicit decisions about UDP support.
+
+A configuration option may allow this behavior to be relaxed (e.g., to warn or ignore unknown UDPs), but the default is strict.
+
+## Conversion Flow
+
+For each node in the elaborated SystemRDL hierarchy, the conversion proceeds as follows:
+
+1. Check whether the node has any UDP attached to it.
+2. If no UDP is present, perform the default conversion:
+   - Translate standard SystemRDL properties to the corresponding RgGen data structure.
+   - Recursively process child nodes using the same procedure.
+3. If a UDP is present, look up a registered hook that matches the node:
+   - If a matching hook is found, delegate the conversion of this node entirely to the hook.
+   - If no matching hook is found, raise an error (in strict mode) or fall back to the configured alternative behavior.
+
+The hook receives:
+
+- The SystemRDL node, with full access to its standard properties, UDP values, and children.
+- A conversion context that provides access to the default conversion routine, so the hook can choose to invoke the default conversion for child nodes if desired.
+
+The hook is expected to return a fully constructed RgGen data structure for the node it handled. The hook is responsible for processing child nodes as appropriate, either by invoking the default conversion via the context or by implementing custom handling.
+
+## Plugin Architecture
+
+UDP handlers are organized as plugins, separate from the rggen-systemrdl core. This means:
+
+- The core adapter ships without any built-in UDP knowledge.
+- Support for specific UDPs (e.g., PeakRDL UDPs, vendor-specific UDPs, internal company UDPs) is provided by independent plugins.
+- Users can install only the UDP plugins they need, and the dependencies between rggen-systemrdl and any specific UDP definition are made explicit.
+
+Each plugin declares:
+
+- Which UDPs it handles (by name and optionally by combination)
+- The conditions under which it applies (e.g., component type, presence of related UDPs)
+- The conversion logic that produces RgGen data structures
+
+This structure allows the community to contribute UDP support for various tools and conventions without burdening the core adapter with vendor-specific code.
+
+## Plugin Registration
+
+Plugins register UDP hooks following the conventions of the RgGen plugin system. A hook registration declares:
+
+- A matching condition that determines when the hook applies to a node
+- A conversion routine that produces the RgGen data structure for that node
+
+The exact API is determined at implementation time, but the general shape follows RgGen's existing plugin patterns.
+
+## Behavior on Unknown UDPs
+
+When a UDP is encountered but no plugin provides a matching hook, the configured behavior applies:
+
+- **error** (default): Raise an error indicating that the UDP is not supported, with location information from the SystemRDL source.
+- **warn**: Emit a warning and proceed without applying the UDP's semantics. The default conversion is used as if the UDP were absent.
+- **ignore**: Silently proceed without applying the UDP's semantics.
+
+The `warn` and `ignore` modes are provided for cases such as bulk migration from existing SystemRDL codebases, where a complete UDP handler set may not yet be available. They should be used with awareness that the resulting RgGen data may not reflect the original intent.
+
+## Rationale for the "Whole-Node Delegation" Choice
+
+When a UDP is present at a given node, the adapter delegates the entire conversion of that node, rather than performing a partial conversion and asking the hook to augment it. This choice is motivated by the way SystemRDL is structured:
+
+- SystemRDL defines behavior through combinations of properties, and UDPs may participate in those combinations in arbitrary ways.
+- A UDP may change how standard properties at the same level should be interpreted (e.g., `buffer_writes` changes how SW writes to the register are realized).
+- A partial conversion would force the hook to reconcile a half-formed result with the UDP's semantics, leading to complex and error-prone hook implementations.
+
+By delegating the whole node, the hook has full control and is responsible for producing a coherent result. If the hook wishes to use the default conversion as a starting point, it may do so explicitly by invoking the conversion context.
+
+## Implications and Trade-offs
+
+### Lock-In Awareness
+
+A SystemRDL file that uses UDPs is, in effect, tool-specific. By making UDP handling explicit through plugins and requiring opt-in, this policy makes the lock-in implications visible to the user. Users adopting a UDP-based feature are also adopting the plugin (and its maintenance burden) needed to interpret that UDP.
+
+This is preferable to silent compatibility shims that hide the lock-in.
+
+### Migration Path
+
+For users migrating SystemRDL files that use vendor-specific UDPs (e.g., PeakRDL UDPs) to rggen-systemrdl:
+
+1. They can either install a community-provided plugin that supports those UDPs, or
+2. They can write their own plugin to interpret their UDPs in the way they prefer, or
+3. They can modify the SystemRDL source to remove UDP usage and rewrite the equivalent behavior using RgGen's native facilities.
+
+The third option is encouraged as the long-term path, since it removes the SystemRDL-induced lock-in entirely.
+
+### No Built-In UDP Knowledge in the Core
+
+rggen-systemrdl itself does not ship with any UDP definitions or handlers. This is intentional:
+
+- Bundling specific vendor UDP support would implicitly endorse those vendors' design choices.
+- It would also tie the core to the maintenance lifecycle of those vendors' tools.
+- The plugin model lets each community of users maintain the UDP handlers they need, independently from the core's release schedule.
+
+## Open Questions
+
+The following aspects are deferred to implementation and may be revisited as the adapter evolves:
+
+- The exact shape of the plugin registration API
+- Whether plugins can introduce new RgGen types or are limited to existing ones
+- The precise interface through which hooks invoke the default conversion on child nodes
+
+The following extension is acknowledged but considered low priority:
+
+- Allowing plugins to define claim conditions that span multiple hierarchy levels (for example, claiming a field based on a UDP attached to its parent register). This would extend the adapter's reach to UDPs that intentionally violate SystemRDL's scoping conventions, but the common case is fully covered by hierarchy-independent judgment, so this is not a near-term priority.
+
+## Summary
+
+| Aspect | Decision |
+| --- | --- |
+| Core adapter scope | SystemRDL standard range only |
+| UDP handling | Delegated to user-defined hooks via plugins |
+| Delegation granularity | Whole-node delegation when a UDP is present |
+| Hierarchy treatment | Independent judgment at each level |
+| Number of active UDP plugins | One at a time; multiple loaded plugins cause a startup error |
+| Default behavior on unknown UDP | Error (strict by default) |
+| UDP definitions in core | None; all UDP support is plugin-provided |
+| Cross-hierarchy claim by plugins | Low-priority extension; not in scope for initial implementation |
+
+This policy keeps the rggen-systemrdl core simple, principled, and aligned with RgGen's overall design philosophy of explicit type-based safety, while leaving the door open for the community to provide UDP support through the plugin mechanism.

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: rggen-systemrdl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Taichi Ishitani
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: systemrdl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: SystemRDL loader plugin for RgGen
+email:
+- rggen@googlegroups.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rggen/systemrdl.rb
+- lib/rggen/systemrdl/converter/addrmap.rb
+- lib/rggen/systemrdl/converter/base.rb
+- lib/rggen/systemrdl/converter/field.rb
+- lib/rggen/systemrdl/converter/mem.rb
+- lib/rggen/systemrdl/converter/reg.rb
+- lib/rggen/systemrdl/converter/regfile.rb
+- lib/rggen/systemrdl/global/ignore_precedence.rb
+- lib/rggen/systemrdl/loader.rb
+- lib/rggen/systemrdl/version.rb
+- notes/bit_field_type_mapping.md
+- notes/bit_field_type_matrix.md
+- notes/external_reg_regfile_mapping.md
+- notes/interrupt_aggregation_policy.md
+- notes/precedence_handling_policy.md
+- notes/systemrdl_rggen_gap_analysis.md
+- notes/systemrdl_to_rggen_mapping.md
+- notes/systemrdl_to_rggen_todo.md
+- notes/udp_handling_policy.md
+homepage: https://github.com/rggen/rggen-systemrdl
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/rggen/rggen/issues
+  mailing_list_uri: https://groups.google.com/d/forum/rggen
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/rggen/rggen-systemrdl
+  wiki_uri: https://github.com/rggen/rggen/wiki
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: rggen-systemrdl-0.1.0
+test_files: []