peakrdl-busdecoder 0.7.2__tar.gz → 0.7.3__tar.gz

{peakrdl_busdecoder-0.7.2 → peakrdl_busdecoder-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peakrdl-busdecoder
-Version: 0.7.2
+Version: 0.7.3
 Summary: Generate a SystemVerilog bus decoder from SystemRDL for splitting CPU interfaces to multiple sub-address spaces
 Author: Arnav Sacheti
 License: LGPLv3

{peakrdl_busdecoder-0.7.2 → peakrdl_busdecoder-0.7.3}/docs/api.rst

@@ -13,7 +13,7 @@ Below is a simple example that demonstrates how to generate a SystemVerilog
 implementation from SystemRDL source.
 
 .. code-block:: python
-    :emphasize-lines: 2-4, 29-33
+    :emphasize-lines: 3-5, 25-30
 
     import sys
 

peakrdl_busdecoder-0.7.3/docs/architecture.rst

@@ -0,0 +1,90 @@
+Bus Decoder Architecture
+========================
+
+The generated RTL is a pure bus-routing layer. It accepts a single CPU interface
+on the slave side and fans transactions out to a set of child interfaces on the
+master side. No register storage or field logic is generated.
+
+Although you do not need to know the inner workings to use the exporter, the
+sections below explain the structure of the generated module and how it maps to
+SystemRDL hierarchy.
+
+
+CPU Interface Adapter
+---------------------
+Each supported CPU interface protocol (APB3, APB4, AXI4-Lite) provides a small
+adapter that translates the external bus protocol into internal request/response
+signals. These internal signals are then used by the address decoder and fanout
+logic.
+
+If you write a custom CPU interface, it must implement the internal signals
+described in :ref:`cpuif_protocol`.
+
+
+Address Decode
+--------------
+The address decoder computes per-child select signals based on address ranges.
+The decode boundary is controlled by ``max_decode_depth``:
+
+* ``0``: Decode down to addressable leaves, including registers and external memories
+* ``1`` (default): Decode only top-level children
+* ``N``: Decode down to depth ``N`` from the top-level
+
+This allows you to choose whether the bus decoder routes to large blocks (e.g.,
+child addrmaps) or to smaller sub-blocks.
+
+Port collection, target naming, select generation, and fanout/fanin use the same
+decode-boundary decision. A container whose addressable children are all external
+remains an early boundary, preserving the existing treatment of opaque blocks.
+
+When the decode boundary is a register, read requests select it only if a
+present field is software-readable; write requests select it only if a present
+field is software-writable. This separates legal read-only/write-only register
+overlaps at one address. A disallowed direction returns a local unmapped error.
+Block targets remain opaque address regions and forward both directions.
+
+Decode bounds and downstream addresses are relative to the exported addrmap,
+including when the Python API exports an inner addrmap with a nonzero system
+base address. Array stride gaps select no child and return a local error rather
+than waiting indefinitely for a downstream response.
+
+
+Fanout to Child Interfaces
+--------------------------
+For each decoded child, the bus decoder drives a master-side CPU interface.
+All address, data, and control signals are forwarded to the selected child.
+
+Arrayed children can be kept as arrays or unrolled into discrete interfaces using
+``--unroll``. This only affects port structure and naming; decode semantics are
+unchanged.
+
+Target naming
+~~~~~~~~~~~~~
+A target keeps its local SystemRDL instance name when that name is unique among
+the decoded targets. Uniqueness is checked after converting to uppercase, since
+package constants and array-count localparams use uppercase identifiers.
+
+When local names collide, the exporter uses the target's complete path relative
+to the exported top-level addrmap, replacing hierarchy separators with
+underscores. For example, ``blk_a.ctrl`` and ``blk_b.ctrl`` become
+``blk_a_ctrl`` and ``blk_b_ctrl``. Existing unique local names are reserved first.
+If flattened paths still collide with each other or with a reserved name,
+``__2``, ``__3``, and so on are appended until the name is unique. These names
+are allocated in sorted relative-path order, independently of traversal order.
+Array indices are not part of this base identifier.
+
+The same resolved identifier is used for APB3, APB4, and AXI4-Lite interface and
+flat master ports, their fanout and fanin references, interface-array
+intermediate signals, ``<MODULE>_<TARGET>_ADDR_WIDTH`` package constants, and
+``N_<TARGET>S`` array-count localparams. The internal select structures retain
+their hierarchical member paths; they are not flattened to match the ports.
+
+
+Fanin and Error Handling
+------------------------
+Read and write responses are muxed back from the selected child to the slave
+interface. If no child is selected for a transaction, the decoder generates an
+error response on the slave interface.
+
+The exact error signaling depends on the chosen CPU interface protocol (e.g.,
+``PSLVERR`` for APB, ``RRESP/BRESP`` for AXI4-Lite).

{peakrdl_busdecoder-0.7.2 → peakrdl_busdecoder-0.7.3}/docs/limitations.rst

@@ -17,15 +17,9 @@ If a register is wider than its ``accesswidth`` (a multi-word register), its
 ``accesswidth`` must match the CPU interface data width. Multi-word registers
 with a smaller accesswidth are not supported.
 
-
-Fields Spanning Sub-Words
--------------------------
-If a field spans multiple sub-words of a wide register:
-
-* Software-writable fields must have write buffering enabled
-* Fields with ``onread`` side-effects must have read buffering enabled
-
-These rules are enforced to avoid ambiguous multi-word access behavior.
+Field storage, read side-effects and multi-word access atomicity are owned by
+the downstream register block. The decoder does not require field read/write
+buffering properties; it forwards each bus transfer independently.
 
 
 External Boundary References

{peakrdl_busdecoder-0.7.2 → peakrdl_busdecoder-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "peakrdl-busdecoder"
-version = "0.7.2"
+version = "0.7.3"
 requires-python = ">=3.10"
 dependencies = [
     "jinja2~=3.1",

peakrdl_busdecoder-0.7.3/spec/audit-docs.md

@@ -0,0 +1,60 @@
+# Documentation vs. Formal Specification Audit
+
+This audit evaluates the consistency and completeness of the documentation (`docs/**/*.rst`, `README.md`) against the formal specification (`spec/busdecoder.md`, `spec/systemrdl.md`, `spec/peakrdl.md`).
+
+Every finding is assigned an ID (`DOC-FINDING-*`), categorized as **Compliant**, **Divergent** (doc contradicts formal spec), **Incomplete** (doc omits critical formal rule), or **Stale** (doc contains obsolete copy-paste).
+
+## Follow-up status
+
+The findings below retain the original audit evidence, not current source line numbers. The field-buffering restriction has been removed from `docs/limitations.rst` and the exporter; downstream blocks own field atomicity. The decoder's default-miss implementation now covers array stride gaps, preserving the documented unmapped-error contract rather than documenting the deadlock as supported behavior. Local submap addressing and direction-specific register routing are covered by the follow-up implementation and RTL conformance sweeps. Depth-policy and Avalon support observations remain separate, unresolved items; this patch does not add Avalon support.
+
+---
+
+## 1. Compliance Matrix
+
+| Requirement | Doc Location | Documented Claim | Formal Spec | Status | Action Needed |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **BD-ARCH-PURE-ROUTER** | `docs/index.rst:7-9` | *"strictly a bus-routing layer that decodes addresses and forwards requests to child blocks"* | BD-ARCH-PURE-ROUTER | **Compliant** | None. |
+| **BD-ARCH-LOCAL-ADDR** | `docs/cpuif/introduction.rst:19-22` | *"The busdecoder exporter will always generate its address decoding logic using local address offsets."* | BD-ARCH-LOCAL-ADDR | **Compliant** | None. |
+| **BD-CFG-CPUIF** | `docs/index.rst:21` | Lists `apb3`, `apb4`, `axi4-lite` + flat variants | BD-CFG-CPUIF | **Compliant** | None. |
+| **BD-CFG-DATA-WIDTH** | `docs/cpuif/introduction.rst:10-13` | *"equal to the widest accesswidth encountered in the design. If the exported addrmap contains only external components... default to 32 bits"* | BD-CFG-DATA-WIDTH | **Incomplete** | Doc fails to note that only *internal* registers are scanned; child addrmaps (which are implicitly external) are ignored even if their inner registers have wider accesswidth. |
+| **BD-CFG-MAX-DEPTH** | `docs/architecture.rst:19-24` | `0`: all levels; `1`: top-level children; `N`: depth $N$ | BD-CFG-MAX-DEPTH | **Incomplete** | Doc does not define whether leaves at depth $< N$ are preserved or dropped when $N > 1$. |
+| **BD-DEC-UNMAPPED-ERROR** | `docs/architecture.rst:39-44`, `docs/cpuif/apb.rst:12-15` | Unmapped addresses complete with error response (PSLVERR / RRESP) | BD-DEC-UNMAPPED-ERROR | **Compliant** | None. |
+| **BD-DEC-GAP-ERROR** | Not documented | — | BD-DEC-GAP-ERROR | **Divergent** | Docs imply all unmapped addresses error; neither docs nor RTL handle stride gaps in arrays. |
+| **BD-AXIL-COUPLED-WRITE** | `docs/cpuif/axi4lite.rst:29-31` | *"AW and W channels must be asserted together for writes"* | BD-AXIL-COUPLED-WRITE | **Compliant** | None. |
+| **BD-AXIL-NO-DECERR** | `docs/architecture.rst:44` | Mentions `RRESP/BRESP` | BD-AXIL-NO-DECERR | **Incomplete** | Doc omits that only `SLVERR` (`2'b10`) is returned, never `DECERR` (`2'b11`). |
+| **Field Buffering** | `docs/limitations.rst:24-29` | Multi-word registers with fields spanning subwords must enable write/read buffering UDPs | N/A (regblock copy-paste) | **Stale / Erroneous** | BusDecoder does not synthesize fields or storage; read/write buffering UDPs are meaningless for a pure decoder. |
+| **Avalon-MM** | `hdl-src/avalon_mm_intf.sv` | Interface file exists in repo | BD-CFG-CPUIF | **Omission** | Avalon-MM interface definition exists in source tree but is completely absent from docs and unreferenced by the exporter. |
+
+---
+
+## 2. Detailed Findings
+
+### DOC-FINDING-01: Stale Limitations Carried Over from PeakRDL-regblock
+- **Location:** `docs/limitations.rst:24-29`
+- **Text:**
+  > Software-writable fields that span across multiple software-accessible sub-words must have write double-buffering enabled.
+  > Fields that have an onread side-effect and span across multiple software-accessible sub-words must have read double-buffering enabled.
+- **Problem:** PeakRDL-BusDecoder is a bus routing layer (`BD-ARCH-PURE-ROUTER`). It does not generate registers, flip-flops, or field logic. Demanding write/read double-buffering UDPs on a bus decoder is a verbatim copy-paste error from `PeakRDL-regblock`.
+- **Required Change:** Delete lines 24–29 of `docs/limitations.rst` and the corresponding check in `src/peakrdl_busdecoder/validate_design.py:126-143`.
+
+### DOC-FINDING-02: Silent Failure Mode in Array Stride Gaps
+- **Location:** `docs/cpuif/apb.rst:12-15`, `docs/architecture.rst:39-44`
+- **Problem:** The documentation states:
+  > An unmapped address completes with an error in the first access cycle. The decoder asserts PREADY and PSLVERR together only when PSEL and PENABLE are high...
+  However, for an array with `stride > size`, an address falling in the gap matches the outer array bound in the generated `if` statement, but matches no loop body `if` branch. The decoder defaults all selects to 0 and asserts `cpuif_err = 0`. On APB, this leaves `PREADY = 0` forever, **hanging the bus** rather than returning `PSLVERR`.
+- **Required Change:** Document the stride gap behavior and add a fallback error assignment in `decode_logic_gen.py`.
+
+### DOC-FINDING-03: Ambiguous Depth Semantics for Mixed Hierarchies
+- **Location:** `docs/architecture.rst:19-24`
+- **Problem:** The documentation specifies:
+  > - 0: Decode all the way down to leaf registers
+  > - 1: Decode only top-level children
+  > - N: Decode down to depth N from the top-level
+  In a design where one branch terminates in a register at depth 1 while another branch contains sub-addrmaps down to depth 3, the behavior of `--max-decode-depth 2` on the shallow branch is unspecified in the documentation.
+- **Required Change:** Clarify that decode targets are collected at depth $N$, or at the first leaf encountered along a branch if depth $< N$.
+
+### DOC-FINDING-04: Undocumented Omission of Avalon-MM CPUIF
+- **Location:** `docs/index.rst:21`, `hdl-src/avalon_mm_intf.sv`
+- **Problem:** The repository ships an `avalon_mm_intf.sv` SystemVerilog interface file in `hdl-src/`, but neither `docs/index.rst` nor `src/peakrdl_busdecoder/cpuif/` implement an Avalon-MM adapter class. Users reading `hdl-src/` reasonably expect Avalon-MM support.
+- **Required Change:** Either document Avalon-MM as a roadmap item / unimplemented interface template, or remove `avalon_mm_intf.sv` from the active source tree.

peakrdl_busdecoder-0.7.3/spec/audit-impl.md

@@ -0,0 +1,128 @@
+# Implementation vs. Specification Audit
+
+This audit evaluates the actual Python codebase (`src/peakrdl_busdecoder/**`) and generated SystemVerilog templates against the formal specification (`spec/busdecoder.md`, `spec/systemrdl.md`, `spec/peakrdl.md`) and the project documentation.
+
+Every finding is assigned an ID (`IMPL-FINDING-*`), categorized by severity (**Critical** = functional bug / bus deadlock, **Major** = spec violation, **Minor** = non-fatal inconsistency, **Deadweight** = dead/obsolete code).
+
+The detailed findings preserve pre-fix evidence and historical line numbers. The follow-up patch implements findings 01–05; the table tracks current status. This is finite-design RTL conformance testing, not an unbounded proof of every SystemRDL design or AXI temporal behavior.
+
+Verification: `PYTHONPATH=src uv run pytest tests -q` completed with **306 passed, 1 skipped**, including cocotb and standalone Verilator regressions. `uv run ruff check src/peakrdl_busdecoder tests/formal` passed. RTL sweeps cover sparse arrays, both directions, idle/setup/access phases, child stalls/errors, readback and local offsets, exported submaps, wide fields, and both RO/WO declaration orders. Naming/depth runtime tests cover APB3/APB4/AXI4-Lite, flat/interface ports, collisions and depth-zero external memories.
+
+---
+
+## 1. Compliance Summary Table
+
+| Spec ID | Impl Location | Status | Summary of Divergence |
+| :--- | :--- | :--- | :--- |
+| **BD-DEC-GAP-ERROR** | `module_tmpl.sv`, `decode_logic_gen.py` | **IMPLEMENTED** | Active requests default to error; both scalar and array-element hits clear error. Idle stays zero. Oracle sweeps cover every address in the sparse-array fixture. |
+| **BD-CFG-MAX-DEPTH** | `design_state.py:is_decode_boundary`, `listener.py:should_skip_node` | **BOUNDARY CONSISTENCY VERIFIED** | Collector and RTL generators share one boundary decision, including external memory leaves at depth 0. Existing early boundaries for containers with all-external children and positive-depth shallow-leaf semantics are unchanged; the proposed shallow-leaf-preservation requirement remains outside these fixes. |
+| **BD-NAME-PORTS** | `design_state.py:get_target_name`, `cpuif/interface.py`, `package_tmpl.sv` | **VERIFIED FOR REGRESSION CASES** | Shared target identifiers preserve unique local names and disambiguate collisions using relative paths plus deterministic suffixes, including uppercase and flattened-path collisions. Behavioral compile/runtime regressions passed across all six built-in protocol/style combinations. |
+| **BD-ARCH-LOCAL-ADDR** | `decode_logic_gen.py`, `cpuif/base_cpuif.py`, protocol fanout generators | **IMPLEMENTED** | Bounds, subtraction and truncation decisions use offsets relative to the exported top; a nonzero-base exported submap exercises non-power-of-two targets. |
+| **BD-DEC-EXCLUSIVITY** | `decode_logic_gen.py:_access_predicate` | **IMPLEMENTED** | Register selects are direction-filtered for scalar and array targets. Both declaration orders of overlapping RO/WO registers are exercised; denied directions return a local error. |
+| **BD-CFG-DATA-WIDTH** | `design_scanner.py` | **SCOPED CONTRACT** | Inference intentionally stops at external boundaries, matching BD-CFG-DATA-WIDTH's internal-scope rule. A deeper opaque block's width is not inferred; this is not a general width-conversion implementation. |
+| **BD-AXIL-NO-DECERR** | `axi4_lite_tmpl.sv:51, 56` | **COMPLIANT** | Correctly maps all error paths to `SLVERR` (`2'b10`). |
+| **BD-APB-ENABLE-GATE** | `apb3_cpuif.py:53`, `apb4_cpuif.py:53` | **COMPLIANT** | Master PENABLE is strictly ANDed with target select signal. |
+| **Field buffering checks** | `validate_design.py`, `docs/limitations.rst` | **REMOVED** | Field atomicity belongs to the downstream block. The RTL sweep exports a writable/onread 64-bit field with 32-bit accesswidth without buffering UDPs. |
+
+---
+
+## 2. Detailed Findings and Recommended Changes
+
+### IMPL-FINDING-01: Array Stride Gap Causes Bus Deadlock (CRITICAL)
+- **Files:** `src/peakrdl_busdecoder/decode_logic_gen.py:112-159`, `src/peakrdl_busdecoder/module_tmpl.sv:65-90`
+- **Specification:** `BD-DEC-GAP-ERROR`
+- **Evidence:**
+  In `tests/cocotb_lib/rdl/array_only.rdl`:
+  ```systemrdl
+  dummy_regs dummy_regs[4] @0x00 += 0x80; // size = 4, stride = 0x80
+  ```
+  The generated SystemVerilog decode logic in `module_tmpl.sv` is:
+  ```systemverilog
+  always_comb begin
+      cpuif_wr_sel = '{default: '0};
+      if (cpuif_req && cpuif_wr_en) begin
+          for (int i0 = 0; i0 < 4; i0++) begin
+              if ((cpuif_wr_addr >= 9'(9'h0+(i0*9'h80))) && (cpuif_wr_addr < 9'(9'h4+(i0*9'h80)))) begin
+                  cpuif_wr_sel.dummy_regs[i0] = 1'b1;
+              end
+          end
+      end
+  end
+  ```
+- **Consequence:**
+  If an access is made to address `0x10` (inside the stride gap $[0x04, 0x80)$):
+  1. The `if (cpuif_wr_addr >= ...)` condition inside the loop evaluates to `0` for all $i_0 \in [0, 3]$.
+  2. All select signals remain `0`.
+  3. `cpuif_wr_sel.cpuif_err` remains `0` (the unmapped fallback `else` branch is outside the loop or omitted).
+  4. On APB, `PREADY` is generated as `cpuif_wr_ack | cpuif_rd_ack`. Because neither a child nor the unmapped error handler is selected, `PREADY` stays `0` indefinitely.
+  5. **The bus hangs permanently.**
+- **Required Fix:**
+  Add a reduction check across array element hits: if the address falls within the overall array bounds $[0, 4 \times 0x80)$ but matches no element, explicitly assert `cpuif_<flavor>_sel.cpuif_err = 1'b1;`.
+
+---
+
+### IMPL-FINDING-02: Non-Relative Address Decode on Sub-Addrmap Exports (MAJOR)
+- **Files:** `src/peakrdl_busdecoder/decode_logic_gen.py:45-48`
+- **Specification:** `BD-ARCH-LOCAL-ADDR`
+- **Evidence:**
+  ```python
+  l_bound = SVInt(
+      node.raw_absolute_address,
+      addr_width,
+  )
+  ```
+  `node.raw_absolute_address` returns the byte offset from the *root of the compilation unit*, not the root of the exported addrmap.
+- **Consequence:**
+  If a user passes an inner sub-addrmap to `BusDecoderExporter.export(sub_node, ...)` via the Python API, where `sub_node` is at offset `0x1000` in the parent chip map:
+  - The generated decoder will expect incoming addresses to start at `0x1000`.
+  - But `BD-ARCH-LOCAL-ADDR` and `docs/cpuif/introduction.rst:19-22` state:
+    > *"The busdecoder exporter will always generate its address decoding logic using local address offsets."*
+  - The generated decoder will reject all valid local accesses in $[0, \text{size}(\text{sub\_node}))$.
+- **Required Fix:**
+  Replace `node.raw_absolute_address` with the relative offset from `self._ds.top_node`:
+  ```python
+  rel_addr = node.raw_absolute_address - self._ds.top_node.raw_absolute_address
+  l_bound = SVInt(rel_addr, addr_width)
+  ```
+
+---
+
+### IMPL-FINDING-03: Port Name Collisions at Deep Hierarchies (IMPLEMENTED; VERIFICATION PENDING)
+- **Files:** `src/peakrdl_busdecoder/design_state.py`, `src/peakrdl_busdecoder/cpuif/interface.py`, `src/peakrdl_busdecoder/cpuif/base_cpuif.py`, `src/peakrdl_busdecoder/cpuif/fanin_intermediate_gen.py`, the APB3/APB4/AXI4-Lite CPU adapters, and `src/peakrdl_busdecoder/package_tmpl.sv`
+- **Specification:** `BD-NAME-PORTS`, `BD-NAME-PACKAGE`
+- **Original defect:** At decode depth 2, `blk_a.ctrl` and `blk_b.ctrl` both emitted `m_apb_ctrl`. The same local-name-only construction also collided in flat ports, package address-width constants, array-count localparams, and interface-array response intermediates.
+- **Implemented resolution:**
+  - `DesignState` allocates a shared target identifier before rendering either package or module. Identity is the path relative to the exported top, independent of array indices and Python node wrappers.
+  - Unique local names are preserved. Uniqueness is checked after uppercase conversion so package constants and array-count localparams remain distinct as well.
+  - Conflicting local names use the flattened full relative path: `blk_a_ctrl` and `blk_b_ctrl`. Unique legacy names are reserved before allocating qualified names.
+  - Flattened-path or uppercase collisions receive deterministic `__2`, `__3`, ... suffixes in sorted relative-path order.
+  - All APB3/APB4/AXI4-Lite flat/interface declarations and references, fanout width references, fanin intermediates, package constants, and array-count localparams use that identifier. Package constants are emitted once per rolled target identity.
+  - Hierarchical select-structure member paths remain unchanged.
+  - Port collection and RTL listeners share `DesignState.is_decode_boundary`; depth-zero external memory leaves therefore receive both declarations and resolved names rather than a dictionary fallback.
+- **Regression coverage:** `tests/formal/test_target_naming.py` compiles and runs generated RTL for duplicate `ctrl` targets under two blocks at depth 2, scalar and rolled-array targets, all three protocols, and both flat and interface ports. It also exercises uppercase and flattened-path collisions, preservation of an existing unique name, and depth-zero external memory alongside internal register leaves. The tests use independently driven target responses and hardcoded public port/constant names, not generated-source string assertions.
+- **Verification status:** These regressions were added but not executed during fix 4. Runtime/compile compliance remains pending the integration verification run.
+
+---
+
+### IMPL-FINDING-04: Sub-Word Buffering Validations are Deadweight (DEADWEIGHT)
+- **Files:** `src/peakrdl_busdecoder/validate_design.py:126-143`
+- **Specification:** `BD-ARCH-PURE-ROUTER`
+- **Evidence:**
+  `DesignValidator` checks whether software-writable fields spanning multiple subwords have `rdl_write_buffering` UDPs, and whether on-read fields have `rdl_read_buffering`.
+- **Consequence:**
+  This check blocks valid SystemRDL designs from generating a bus decoder simply because they contain wide fields, even though a bus decoder never handles subword slicing (it merely forwards transfers to the downstream register block that owns the fields).
+- **Required Fix:**
+  Delete lines 126–143 of `validate_design.py`.
+
+---
+
+### IMPL-FINDING-05: Missing Independent Read/Write Decode for Overlapping Registers (MINOR)
+- **Files:** `src/peakrdl_busdecoder/decode_logic_gen.py:94-131`
+- **Specification:** `BD-DEC-EXCLUSIVITY`, SystemRDL Clause 10.1-h
+- **Evidence:**
+  SystemRDL 2.0 explicitly permits two registers to occupy the same address offset if one is read-only and the other is write-only.
+  However, `DecodeLogicGenerator` treats read and write decoding identically (`enter_AddressableComponent` does not check `is_sw_readable` or `is_sw_writable`). It emits an `if ... else if ...` ladder based on tree order alone.
+- **Consequence:**
+  In a design with legal RO/WO overlapping registers, a read request will hit whichever register is visited first, even if that register is write-only!
+- **Required Fix:**
+  In `DecodeLogicGenerator.cpuif_addr_predicate()`, gate read decoding with `node.has_sw_readable` and write decoding with `node.has_sw_writable`.

peakrdl_busdecoder-0.7.3/spec/busdecoder.md

@@ -0,0 +1,218 @@
+# PeakRDL-BusDecoder — Formal Specification
+
+This specification defines the behavior, interface contracts, protocol invariants, and address-decoding mathematics of the **PeakRDL-BusDecoder** generator.
+
+Every normative statement is assigned a unique identifier `BD-*`. Downstream audits and verification harnesses reference these identifiers directly.
+
+---
+
+## 1. Top-Level Architectural Contract
+
+```
+                     +---------------------------------------+
+                     |         PeakRDL-BusDecoder            |
+                     |                                       |
+  Slave CPUIF        |  +-------------+   +---------------+  |   Master CPUIF 0
+  (APB3/4, AXI4-L) ===> | Slave CPUIF |-->| Write Decoder |--===> (Child 0)
+                     |  |  Adapter    |   +---------------+  |
+                     |  |             |                      |   Master CPUIF 1
+                     |  |             |   +---------------+  |===> (Child 1)
+                     |  |             |-->| Read Decoder  |--+
+                     |  |             |   +---------------+  |   ...
+                     |  |             |<--| Readback Mux  |--+   Master CPUIF K-1
+                     |  +-------------+   +---------------+  |===> (Child K-1)
+                     +---------------------------------------+
+```
+
+- **BD-ARCH-PURE-ROUTER**: The generated RTL shall be a pure routing and bus-translation layer containing no software register storage, no field-level logic, and no flip-flops unless required by protocol pipelining.
+- **BD-ARCH-LOCAL-ADDR**: The decoder shall operate strictly on addresses relative to the root of the exported address map. The base address of the exported root addrmap within the system interconnect is defined to be 0.
+- **BD-ARCH-SV-STD**: Generated RTL shall conform to IEEE 1800-2012 SystemVerilog and synthesize without errors on major EDA toolchains.
+
+---
+
+## 2. Configuration and Exporter Parameters
+
+- **BD-CFG-CPUIF**: The exporter shall support the following standard CPU interface targets:
+  - `apb3`: AMBA APB v3 using SystemVerilog interface (`apb3_intf.sv`).
+  - `apb3-flat`: AMBA APB v3 flattened into discrete scalar/vector ports.
+  - `apb4`: AMBA APB v4 using SystemVerilog interface (`apb4_intf.sv`).
+  - `apb4-flat`: AMBA APB v4 flattened into discrete scalar/vector ports.
+  - `axi4-lite`: AMBA AXI4-Lite using SystemVerilog interface (`axi4lite_intf.sv`).
+  - `axi4-lite-flat`: AMBA AXI4-Lite flattened into discrete scalar/vector ports.
+  - Plugin interfaces registered via entry points under `peakrdl_busdecoder.cpuif`.
+- **BD-CFG-DEFAULT-CPUIF**: If unspecified, the CPU interface shall default to `apb4`.
+- **BD-CFG-DATA-WIDTH**:
+  - The CPU interface data bus width $W_{\text{data}}$ shall be inferred as the maximum `accesswidth` of any register reachable within the internal scope of the exported addrmap.
+  - If no internal register exists (e.g. only external blocks), $W_{\text{data}}$ shall default to 32 bits and emit a warning.
+  - All master interfaces shall have data width equal to $W_{\text{data}}$.
+- **BD-CFG-ADDR-WIDTH**:
+  - The minimum address width $W_{\text{addr,min}}$ shall satisfy:
+    $$W_{\text{addr,min}} = \max\left( \lceil\log_2(\text{size}(c_{\text{top}}))\rceil,\; \lceil\log_2(W_{\text{data}} / 8)\rceil + 1 \right)$$
+  - The user may override $W_{\text{addr}} \ge W_{\text{addr,min}}$. If the user specifies $W_{\text{addr}} < W_{\text{addr,min}}$, export shall abort with a fatal error.
+- **BD-CFG-MAX-DEPTH**:
+  - `max_decode_depth = 0`: The decoder shall descend to leaf registers ($\text{RegNode}$) across all nested blocks.
+  - `max_decode_depth = 1` (default): The decoder shall decode only immediate children of the top-level addrmap.
+  - `max_decode_depth = N` ($N > 1$): The decoder shall decode children positioned at depth $N$ in the instance tree.
+  - Leaves occurring at depth $< N$ shall also be preserved as decode targets. *(Formal requirement; see Audit for current divergence).*
+- **BD-CFG-UNROLL**:
+  - When `cpuif_unroll = false` (default), arrayed children shall be exported as SystemVerilog interface arrays (`[dim0][dim1]...` or `[N]`) and iterated procedurally with `for` loops.
+  - When `cpuif_unroll = true`, arrayed children shall be expanded into distinct scalar master interfaces with index suffixes `_<idx0>_<idx1>`.
+- **BD-CFG-PARAMETRIZE**:
+  - When `--parametrize` is asserted, root-level RDL parameters that control array dimensions shall be extracted and emitted as SystemVerilog module parameters.
+  - The module parameter default value shall be the elaborated maximum.
+  - Package constant `<MODULE>_MAX_<PARAM>` shall be defined.
+  - Runtime range assertion `assert (PARAM >= 0 && PARAM <= MAX)` shall be emitted.
+
+---
+
+## 3. Child Interface Target Set ($\mathcal{T}$)
+
+Let $c_{\text{top}}$ be the exported addrmap. A component instance $t$ belongs to the decode target set $\mathcal{T}$ if and only if:
+
+1. $t \in \mathcal{A} \land t \ne c_{\text{top}}$.
+2. $t$ is an ancestor of no other target $t' \in \mathcal{T}$ (targets are mutually disjoint subtrees).
+3. Selection rule:
+   - If $\text{max\_decode\_depth} = 0$: $t \in \text{RegNode} \lor (t \in \text{MemNode} \land \text{virtual\_regs}(t) = \emptyset) \lor (t.\text{external} \land \text{is\_leaf}(t))$.
+   - If $\text{max\_decode\_depth} = N \ge 1$: $\text{depth}(t) = N \lor (\text{depth}(t) < N \land t \in \text{RegNode})$.
+
+Each target $t \in \mathcal{T}$ defines:
+- A local address span within $c_{\text{top}}$:
+  - If scalar: $S(t) = [\text{rel\_offset}(t),\; \text{rel\_offset}(t) + \text{size}(t))$.
+  - If arrayed: for element $\vec{j}$, $S(t, \vec{j}) = [\text{elem\_rel\_offset}(t, \vec{j}),\; \text{elem\_rel\_offset}(t, \vec{j}) + \text{size}(t))$.
+- A master port on the generated decoder.
+- Master address width $W_{\text{addr}}(t) = \max(\lceil\log_2(\text{size}(t))\rceil, 1)$.
+
+---
+
+## 4. Address Decoding Formal Model
+
+Let $A \in [0, 2^{W_{\text{addr}}} - 1]$ be the incoming transaction byte address, and $D \in \{\text{READ}, \text{WRITE}\}$ the transaction flavor.
+
+### 4.1 Target Match Predicate
+For target $t \in \mathcal{T}$ and element index tuple $\vec{j}$:
+
+$$\text{match}(t, \vec{j}, A) \iff A \ge \text{elem\_rel\_offset}(t, \vec{j}) \;\land\; A < \text{elem\_rel\_offset}(t, \vec{j}) + \text{size}(t)$$
+
+$$\text{match}(t, A) \iff \exists \vec{j} \in \prod_{m=0}^{k-1} [0, d_m-1] : \text{match}(t, \vec{j}, A)$$
+
+### 4.2 Select Signal Requirements
+Let $\text{sel}_{D}(t, \vec{j}) \in \{0, 1\}$ denote the select signal asserted by the decoder for flavor $D$, and $\text{err}_{D} \in \{0, 1\}$ the unmapped error signal.
+
+- **BD-DEC-SOUNDNESS (No Spurious Select):**
+  $$\text{sel}_{D}(t, \vec{j}) = 1 \implies \text{match}(t, \vec{j}, A)$$
+- **BD-DEC-EXCLUSIVITY (At Most One Select):**
+  $$\sum_{t \in \mathcal{T}} \sum_{\vec{j}} \text{sel}_{D}(t, \vec{j}) \le 1$$
+  *(If legal RO/WO overlap exists at address $A$, the read decoder selects the readable register and the write decoder selects the writable register independently).*
+- **BD-DEC-COMPLETENESS (Mapped Hit):**
+  For an active request of direction $D$, each select is asserted exactly when its element matches and permits that direction:
+  $$\text{sel}_{D}(t,\vec{j}) = \text{match}(t,\vec{j},A) \land \text{permits}(t,D).$$
+  For register targets, `permits(READ)` is `has_sw_readable` and `permits(WRITE)` is `has_sw_writable`, considering present fields. Blocks are routed as opaque regions in both directions; the downstream block enforces its own permissions.
+- **BD-DEC-UNMAPPED-ERROR (Error on Miss):**
+  For an active request, including an access with no direction-permitted register:
+  $$\text{err}_{D} = \neg\bigvee_{t,\vec{j}}\text{sel}_{D}(t,\vec{j}).$$
+  This default-miss invariant also applies inside nested arrays and to parameter-disabled elements. When idle, both selects and error remain zero.
+- **BD-DEC-IDLE:**
+  When no transaction of flavor $D$ is requested, all select and error signals for flavor $D$ shall be 0:
+  $$\neg \text{req}_D \implies \forall t, \vec{j}: \text{sel}_{D}(t, \vec{j}) = 0 \;\land\; \text{err}_{D} = 0$$
+- **BD-DEC-GAP-ERROR:**
+  For any address $A$ that falls within an array's total span $[\text{raw\_offset}(t), \text{raw\_offset}(t) + \text{total\_size}(t))$ but does not satisfy $\text{match}(t, \vec{j}, A)$ for any element $\vec{j}$ (an array stride gap), the decoder shall assert $\text{err}_D = 1$ and all selects 0.
+
+### 4.3 Master Address Forwarding
+For selected target $t$ and element index $\vec{j}$:
+- **BD-FWD-ADDR-LOCAL**: The master address driven to child $t$ shall be the byte offset relative to element $(t, \vec{j})$:
+  $$A_{\text{master}}(t) = A - \text{elem\_rel\_offset}(t, \vec{j})$$
+- **BD-FWD-ADDR-TRUNC**: If $\text{size}(t) = 2^p$ and $\text{elem\_rel\_offset}(t, \vec{j}) \equiv 0 \pmod{2^p}$ for all $\vec{j}$, the decoder may implement $A_{\text{master}}(t)$ as bit-truncation:
+  $$A_{\text{master}}(t) = A[p-1:0]$$
+  Otherwise, subtractive arithmetic must be emitted.
+
+---
+
+## 5. Protocol Handshake and Invariant Specifications
+
+### 5.1 Internal CPUIF Interface Protocol
+All protocol adapters convert slave transactions into the internal CPUIF signals:
+- Request: `cpuif_req`, `cpuif_wr_en`, `cpuif_rd_en`, `cpuif_wr_addr`, `cpuif_rd_addr`, `cpuif_wr_data`, `cpuif_wr_byte_en`.
+- Response: `cpuif_wr_ack`, `cpuif_wr_err`, `cpuif_rd_ack`, `cpuif_rd_err`, `cpuif_rd_data`.
+
+**Invariants:**
+- **BD-PROTO-SINGLE-FLIGHT**: At most one transaction (read or write) shall be in flight through the internal CPUIF at any clock cycle:
+  $$\text{cpuif\_req} \implies (\text{cpuif\_wr\_en} \oplus \text{cpuif\_rd\_en})$$
+- **BD-PROTO-REQ-STABLE**: Once asserted, `cpuif_req`, `cpuif_wr_en`, `cpuif_rd_en`, addresses, and write data shall remain stable until the qualifying acknowledgment (`cpuif_wr_ack` or `cpuif_rd_ack`) is asserted.
+- **BD-PROTO-ACK-STROBE**: Acknowledgments `cpuif_wr_ack` and `cpuif_rd_ack` shall be single-cycle pulses.
+- **BD-PROTO-ACK-DATA**: Read data `cpuif_rd_data` and error flag `cpuif_rd_err` are valid and sampled on the cycle of `cpuif_rd_ack`.
+
+---
+
+### 5.2 APB3 and APB4 Adapter Semantics
+
+Let $P$ be the slave APB interface ($s\_apb$) and $M_t$ the master APB interface for target $t$.
+
+#### Request Phase Mapping
+- `cpuif_req = s_apb.PSEL`
+- `cpuif_wr_en = s_apb.PSEL & s_apb.PWRITE`
+- `cpuif_rd_en = s_apb.PSEL & ~s_apb.PWRITE`
+- `cpuif_wr_addr = s_apb.PADDR`
+- `cpuif_rd_addr = s_apb.PADDR`
+- `cpuif_wr_data = s_apb.PWDATA`
+- APB4: `cpuif_wr_byte_en = s_apb.PSTRB`
+
+#### Master Forwarding Rules
+- **BD-APB-SEL-GATE**: For each target $t$:
+  $$M_t.\text{PSEL} = \text{sel}_{\text{wr}}(t) \lor \text{sel}_{\text{rd}}(t)$$
+- **BD-APB-ENABLE-GATE**:
+  $$M_t.\text{PENABLE} = (\text{sel}_{\text{wr}}(t) \lor \text{sel}_{\text{rd}}(t)) \land s\_apb.\text{PENABLE}$$
+  *(Crucial bugfix from v0.7.0b3/v0.7.1: unselected master PENABLE must be forced low to prevent spurious downstream state transitions).*
+- **BD-APB-BROADCAST**:
+  $M_t.\text{PWRITE} = s\_apb.\text{PWRITE}$, $M_t.\text{PWDATA} = s\_apb.\text{PWDATA}$, $M_t.\text{PPROT} = s\_apb.\text{PPROT}$, $M_t.\text{PSTRB} = s\_apb.\text{PSTRB}$.
+
+#### Response and Error Timing
+- **BD-APB-MAPPED-RESP**: When $\text{sel}(t) = 1$:
+  $$s\_apb.\text{PREADY} = M_t.\text{PREADY}$$
+  $$s\_apb.\text{PSLVERR} = M_t.\text{PSLVERR}$$
+  $$s\_apb.\text{PRDATA} = M_t.\text{PRDATA} \quad (\text{if read})$$
+- **BD-APB-UNMAPPED-RESP**: When $\text{err}_{\text{wr}} = 1 \lor \text{err}_{\text{rd}} = 1$:
+  - Setup cycle ($s\_apb.\text{PSEL} = 1 \land s\_apb.\text{PENABLE} = 0$):
+    $$s\_apb.\text{PREADY} = 0, \quad s\_apb.\text{PSLVERR} = 0$$
+  - Access cycle ($s\_apb.\text{PSEL} = 1 \land s\_apb.\text{PENABLE} = 1$):
+    $$s\_apb.\text{PREADY} = 1, \quad s\_apb.\text{PSLVERR} = 1$$
+  - This guarantees a standard 2-cycle unmapped APB error termination without hanging the bus.
+
+---
+
+### 5.3 AXI4-Lite Adapter Semantics
+
+Let $AXI$ be the slave AXI4-Lite interface.
+
+- **BD-AXIL-COUPLED-WRITE**: The write channel adapter shall require `AWVALID` and `WVALID` to be asserted together:
+  $$\text{axi\_wr\_valid} = \text{AWVALID} \land \text{WVALID}$$
+  $$\text{AWREADY} = \text{axi\_wr\_valid}, \quad \text{WREADY} = \text{axi\_wr\_valid}$$
+- **BD-AXIL-DECOUPLED-ERR**: If `AWVALID ^ WVALID` occurs, the adapter shall immediately terminate the invalid request with `BVALID = 1` and `BRESP = 2'b10` (`SLVERR`).
+- **BD-AXIL-READ-CHANNEL**:
+  $$\text{ARREADY} = \text{ARVALID}$$
+  $$\text{RVALID} = \text{cpuif\_rd\_ack} \lor \text{cpuif\_rd\_sel.cpuif\_err}$$
+  $$\text{RRESP} = (\text{cpuif\_rd\_err} \lor \text{cpuif\_rd\_sel.cpuif\_err}) \;?\; 2'b10 : 2'b00$$
+- **BD-AXIL-WRITE-CHANNEL**:
+  $$\text{BVALID} = \text{cpuif\_wr\_ack} \lor \text{cpuif\_wr\_sel.cpuif\_err} \lor \text{axi\_wr\_invalid}$$
+  $$\text{BRESP} = (\text{cpuif\_wr\_err} \lor \text{cpuif\_wr\_sel.cpuif\_err} \lor \text{axi\_wr\_invalid}) \;?\; 2'b10 : 2'b00$$
+- **BD-AXIL-NO-DECERR**: All error responses on AXI4-Lite shall be signaled as `SLVERR` (`2'b10`). `DECERR` (`2'b11`) is never emitted.
+
+---
+
+## 6. Naming and Structural Contracts
+
+- **BD-NAME-KW-FILTER**: Any identifier matching a SystemVerilog keyword shall be appended with an underscore `_`.
+- **BD-NAME-PACKAGE**:
+  - The generated package shall be named `<package_name>.sv`.
+  - Constants emitted:
+    - `<MODULE>_DATA_WIDTH`
+    - `<MODULE>_MIN_ADDR_WIDTH`
+    - `<MODULE>_SIZE`
+    - `<MODULE>_<TARGET>_ADDR_WIDTH` for every target.
+    - `<MODULE>_MAX_<PARAM>` for extracted RDL parameters.
+- **BD-NAME-PORTS**:
+  - Slave ports: prefixed with `s_apb_` or `s_axil_`.
+  - Master ports: prefixed with `m_apb_<target>_` or `m_axil_<target>_`.
+  - Port disambiguation: when targets share names across hierarchies or nested arrays, port names must uniquely identify the target. *(Formal requirement; see Audit for collision risks).*
+- **BD-STRUCT-SEL**:
+  - The select typedef `cpuif_sel_t` shall reflect the hierarchy down to each target.
+  - An explicit `logic cpuif_err;` field shall be included at the root level of `cpuif_sel_t`.