cocotbext-ral 0.5.2__tar.gz

cocotbext_ral-0.5.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cocotbext-ral contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cocotbext_ral-0.5.2/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include cocotbext *.py

cocotbext_ral-0.5.2/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: cocotbext-ral
+Version: 0.5.2
+Summary: Python-native Register Abstraction Layer (RAL) for cocotb with a data-driven runtime architecture
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/stephencoTT/cocotbext-ral
+Project-URL: Issues, https://github.com/stephencoTT/cocotbext-ral/issues
+Keywords: cocotb,ral,register model,verification,eda
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: cocotb
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: cocotb
+Requires-Dist: cocotb>=1.8.0; extra == "cocotb"
+Requires-Dist: cocotbext-axi>=0.1.16; extra == "cocotb"
+Provides-Extra: rdl
+Requires-Dist: systemrdl-compiler>=1.15; extra == "rdl"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: cocotbext-ral[cocotb,dev,rdl]; extra == "all"
+Dynamic: license-file
+
+# cocotbext-ral
+
+A Python-native Register Abstraction Layer (RAL) for [cocotb](https://www.cocotb.org/).
+
+`cocotbext-ral` provides UVM-like register modeling, access-type-aware prediction, and automated checking -- all in pure Python, designed for cocotb hardware verification.
+
+## Features
+
+- **Runtime-backed architecture** with clean separation of register spec vs mutable state
+- **Full access-type coverage**: RW, RO, WO, W1C, W1S, RCLR, RSET
+- **Smart volatile inference**: RO, RCLR, RSET fields default to volatile (overridable)
+- **Safe field writes** that reject unsafe read-modify-write sequences
+- **Backdoor resolution** that scales to replicated blocks and chiplets
+- **Transaction logging** with detailed per-transaction file output
+- **Pure-Python core** -- model, predictor, and policies work without cocotb
+
+## Architecture
+
+```
+RegisterModel (spec)
+        |
+    RuntimeState (per-instance mutable state)
+        |
+RuntimePredictor + AccessPolicy
+        |
+RuntimeRAL -> SafeRuntimeRAL -> IntegratedRuntimeRAL
+                                       |          |
+                                  Backdoor    Transaction Log
+```
+
+## Installation
+
+```bash
+pip install cocotbext-ral
+```
+
+Optional extras:
+
+```bash
+pip install cocotbext-ral[cocotb]   # cocotb + cocotbext-axi
+pip install cocotbext-ral[rdl]      # SystemRDL compiler
+pip install cocotbext-ral[all]      # Everything
+```
+
+## Quick start
+
+### With cocotb simulation
+
+```python
+import cocotb
+from cocotbext.axi import AxiLiteMaster, AxiLiteBus
+from cocotbext.ral import IntegratedRuntimeRAL
+from cocotbext.ral.adapters import load_json
+
+@cocotb.test()
+async def test_registers(dut):
+    model = load_json("registers.json")
+
+    ral = IntegratedRuntimeRAL("my_ip", model, dut_handle=dut, txn_log=True)
+    master = AxiLiteMaster(AxiLiteBus.from_prefix(dut, "s_axil"), dut.clk, dut.rst)
+    ral.attach_master(master, protocol="axil", interface="dut.s_axil")
+
+    # Write and read with automatic prediction checking
+    await ral.write("CTRL", 0x01)
+    val = await ral.read("CTRL")
+
+    # Field-level access with RMW safety
+    await ral.write_field("CTRL", "enable", 1)
+    en = await ral.read_field("CTRL", "enable")
+
+    # Check results
+    ral.raise_on_errors()
+    ral.close_txn_log()
+```
+
+### Standalone (no cocotb)
+
+The core model, predictor, and policy layers have zero dependencies:
+
+```python
+from cocotbext.ral import RegisterModel, Register, RegisterField, SwAccess
+from cocotbext.ral.runtime_predictor import RuntimePredictor
+
+model = RegisterModel("my_ip")
+reg = Register("CTRL", address=0x0, size_bits=32, fields=[
+    RegisterField("enable", lsb=0, msb=0, reset_value=0, sw_access=SwAccess.RW),
+    RegisterField("irq", lsb=8, msb=15, reset_value=0xFF, sw_access=SwAccess.W1C),
+])
+model.add_register(reg, hierarchical_name="block.CTRL")
+
+pred = RuntimePredictor(model)
+pred.predict_write(0x0, 0x01)
+result = pred.predict_read(0x0, 0x01)
+assert result.passed
+```
+
+## API classes
+
+| Class | Description |
+|---|---|
+| `IntegratedRuntimeRAL` | **Recommended.** Runtime state + RMW safety + backdoor + transaction log |
+| `SafeRuntimeRAL` | Runtime state + RMW safety checks |
+| `RuntimeRAL` | Runtime state-backed prediction |
+| `RuntimePredictor` | Standalone prediction engine (no cocotb needed) |
+| `RuntimeState` | Per-instance mutable register state |
+| `AccessPolicy` | Per-field read/write behavior |
+| `TransactionLogger` | Detailed file-based transaction logging |
+| `BackdoorResolver` | HDL path resolution (base, Prefix, Mapping variants) |
+| `RegisterModel` | Structural register specification |
+
+## Register loading
+
+```python
+from cocotbext.ral.adapters import load_json, load_rdl
+
+model = load_json("registers.json")                        # RDL-generated JSON
+model = load_rdl("regs.rdl", top_name="my_ip", incdir=[])  # SystemRDL source
+```
+
+## Access types
+
+| SwAccess | Write behavior | Read behavior | Volatile by default |
+|---|---|---|---|
+| `RW` | Update value | Check prediction | No |
+| `RO` | Ignored | Not checked | Yes |
+| `WO` | Update value | Not checked | No |
+| `W1C` | Clear written-1 bits | Check prediction | No |
+| `W1S` | Set written-1 bits | Check prediction | No |
+| `RCLR` | Ignored | Clears to 0 after read | Yes |
+| `RSET` | Ignored | Sets to all-1s after read | Yes |
+
+Aliases: `WOCLR`=`W1C`, `WOSET`=`W1S`, `RC`=`RCLR`, `RS`=`RSET`
+
+## Transaction logging
+
+Enable detailed per-transaction file output:
+
+```python
+# Default filename (register_txns.log)
+ral = IntegratedRuntimeRAL("ip", model, txn_log=True)
+
+# Custom path
+ral = IntegratedRuntimeRAL("ip", model, txn_log="my_regs.log")
+
+# Phase annotations
+ral.set_txn_phase("Phase 1: Reset value check")
+await ral.write(addr, value)
+
+# Summary and close
+ral.close_txn_log()
+```
+
+Each transaction entry includes: model path, address, data, protocol, interface HDL path, status (PASS/FAIL/SKIP), mirror state, per-field breakdown, and RMW safety assessment.
+
+## Testing
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+146 tests covering: register model (including search / group helpers), runtime predictor (all access types), access policies, RMW safety, backdoor resolvers, runtime state, volatile policy, debug helpers, checker, JSON loader, transaction logger, and RuntimeRAL construction / reset / check-toggle helpers.
+
+## Documentation
+
+Read in this order:
+
+1. [Quick Start](docs/START_GUIDE.md) -- 10-step walkthrough covering all access types and the common flows.
+2. [Architecture](docs/ARCHITECTURE.md) -- layer-by-layer design and the rationale behind each decision.
+3. API reference (pick what you need):
+   - [Core Model](docs/api/CORE_MODEL.md) -- `RegisterModel`, `Register`, `RegisterField`, `SwAccess`.
+   - [Runtime API](docs/api/RUNTIME_API.md) -- `IntegratedRuntimeRAL`, `SafeRuntimeRAL`, mirror update modes, RMW logging, search / bulk APIs.
+   - [Integration and Loaders](docs/api/INTEGRATION_AND_LOADERS.md) -- JSON/RDL loaders, backdoor resolvers, transaction logging.
+
+## License
+
+MIT

cocotbext_ral-0.5.2/README.md

@@ -0,0 +1,177 @@
+# cocotbext-ral
+
+A Python-native Register Abstraction Layer (RAL) for [cocotb](https://www.cocotb.org/).
+
+`cocotbext-ral` provides UVM-like register modeling, access-type-aware prediction, and automated checking -- all in pure Python, designed for cocotb hardware verification.
+
+## Features
+
+- **Runtime-backed architecture** with clean separation of register spec vs mutable state
+- **Full access-type coverage**: RW, RO, WO, W1C, W1S, RCLR, RSET
+- **Smart volatile inference**: RO, RCLR, RSET fields default to volatile (overridable)
+- **Safe field writes** that reject unsafe read-modify-write sequences
+- **Backdoor resolution** that scales to replicated blocks and chiplets
+- **Transaction logging** with detailed per-transaction file output
+- **Pure-Python core** -- model, predictor, and policies work without cocotb
+
+## Architecture
+
+```
+RegisterModel (spec)
+        |
+    RuntimeState (per-instance mutable state)
+        |
+RuntimePredictor + AccessPolicy
+        |
+RuntimeRAL -> SafeRuntimeRAL -> IntegratedRuntimeRAL
+                                       |          |
+                                  Backdoor    Transaction Log
+```
+
+## Installation
+
+```bash
+pip install cocotbext-ral
+```
+
+Optional extras:
+
+```bash
+pip install cocotbext-ral[cocotb]   # cocotb + cocotbext-axi
+pip install cocotbext-ral[rdl]      # SystemRDL compiler
+pip install cocotbext-ral[all]      # Everything
+```
+
+## Quick start
+
+### With cocotb simulation
+
+```python
+import cocotb
+from cocotbext.axi import AxiLiteMaster, AxiLiteBus
+from cocotbext.ral import IntegratedRuntimeRAL
+from cocotbext.ral.adapters import load_json
+
+@cocotb.test()
+async def test_registers(dut):
+    model = load_json("registers.json")
+
+    ral = IntegratedRuntimeRAL("my_ip", model, dut_handle=dut, txn_log=True)
+    master = AxiLiteMaster(AxiLiteBus.from_prefix(dut, "s_axil"), dut.clk, dut.rst)
+    ral.attach_master(master, protocol="axil", interface="dut.s_axil")
+
+    # Write and read with automatic prediction checking
+    await ral.write("CTRL", 0x01)
+    val = await ral.read("CTRL")
+
+    # Field-level access with RMW safety
+    await ral.write_field("CTRL", "enable", 1)
+    en = await ral.read_field("CTRL", "enable")
+
+    # Check results
+    ral.raise_on_errors()
+    ral.close_txn_log()
+```
+
+### Standalone (no cocotb)
+
+The core model, predictor, and policy layers have zero dependencies:
+
+```python
+from cocotbext.ral import RegisterModel, Register, RegisterField, SwAccess
+from cocotbext.ral.runtime_predictor import RuntimePredictor
+
+model = RegisterModel("my_ip")
+reg = Register("CTRL", address=0x0, size_bits=32, fields=[
+    RegisterField("enable", lsb=0, msb=0, reset_value=0, sw_access=SwAccess.RW),
+    RegisterField("irq", lsb=8, msb=15, reset_value=0xFF, sw_access=SwAccess.W1C),
+])
+model.add_register(reg, hierarchical_name="block.CTRL")
+
+pred = RuntimePredictor(model)
+pred.predict_write(0x0, 0x01)
+result = pred.predict_read(0x0, 0x01)
+assert result.passed
+```
+
+## API classes
+
+| Class | Description |
+|---|---|
+| `IntegratedRuntimeRAL` | **Recommended.** Runtime state + RMW safety + backdoor + transaction log |
+| `SafeRuntimeRAL` | Runtime state + RMW safety checks |
+| `RuntimeRAL` | Runtime state-backed prediction |
+| `RuntimePredictor` | Standalone prediction engine (no cocotb needed) |
+| `RuntimeState` | Per-instance mutable register state |
+| `AccessPolicy` | Per-field read/write behavior |
+| `TransactionLogger` | Detailed file-based transaction logging |
+| `BackdoorResolver` | HDL path resolution (base, Prefix, Mapping variants) |
+| `RegisterModel` | Structural register specification |
+
+## Register loading
+
+```python
+from cocotbext.ral.adapters import load_json, load_rdl
+
+model = load_json("registers.json")                        # RDL-generated JSON
+model = load_rdl("regs.rdl", top_name="my_ip", incdir=[])  # SystemRDL source
+```
+
+## Access types
+
+| SwAccess | Write behavior | Read behavior | Volatile by default |
+|---|---|---|---|
+| `RW` | Update value | Check prediction | No |
+| `RO` | Ignored | Not checked | Yes |
+| `WO` | Update value | Not checked | No |
+| `W1C` | Clear written-1 bits | Check prediction | No |
+| `W1S` | Set written-1 bits | Check prediction | No |
+| `RCLR` | Ignored | Clears to 0 after read | Yes |
+| `RSET` | Ignored | Sets to all-1s after read | Yes |
+
+Aliases: `WOCLR`=`W1C`, `WOSET`=`W1S`, `RC`=`RCLR`, `RS`=`RSET`
+
+## Transaction logging
+
+Enable detailed per-transaction file output:
+
+```python
+# Default filename (register_txns.log)
+ral = IntegratedRuntimeRAL("ip", model, txn_log=True)
+
+# Custom path
+ral = IntegratedRuntimeRAL("ip", model, txn_log="my_regs.log")
+
+# Phase annotations
+ral.set_txn_phase("Phase 1: Reset value check")
+await ral.write(addr, value)
+
+# Summary and close
+ral.close_txn_log()
+```
+
+Each transaction entry includes: model path, address, data, protocol, interface HDL path, status (PASS/FAIL/SKIP), mirror state, per-field breakdown, and RMW safety assessment.
+
+## Testing
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+146 tests covering: register model (including search / group helpers), runtime predictor (all access types), access policies, RMW safety, backdoor resolvers, runtime state, volatile policy, debug helpers, checker, JSON loader, transaction logger, and RuntimeRAL construction / reset / check-toggle helpers.
+
+## Documentation
+
+Read in this order:
+
+1. [Quick Start](docs/START_GUIDE.md) -- 10-step walkthrough covering all access types and the common flows.
+2. [Architecture](docs/ARCHITECTURE.md) -- layer-by-layer design and the rationale behind each decision.
+3. API reference (pick what you need):
+   - [Core Model](docs/api/CORE_MODEL.md) -- `RegisterModel`, `Register`, `RegisterField`, `SwAccess`.
+   - [Runtime API](docs/api/RUNTIME_API.md) -- `IntegratedRuntimeRAL`, `SafeRuntimeRAL`, mirror update modes, RMW logging, search / bulk APIs.
+   - [Integration and Loaders](docs/api/INTEGRATION_AND_LOADERS.md) -- JSON/RDL loaders, backdoor resolvers, transaction logging.
+
+## License
+
+MIT

cocotbext_ral-0.5.2/cocotbext/ral/__init__.py

@@ -0,0 +1,22 @@
+"""Cocotb Register Abstraction Layer (RAL).
+
+Generic, reusable RAL with zero Quasar-specific dependencies.
+"""
+
+from .version import __version__
+from .register_model import RegisterField, Register, RegisterBlock, RegisterModel, SwAccess, Memory
+from .runtime_predictor import RuntimePredictor, PredictionResult, FieldResult
+from .state import RuntimeState, RegisterState, FieldState
+from .checker import Checker
+
+# Runtime-backed RAL APIs.
+from .runtime_ral import RuntimeRAL
+from .safe_runtime_ral import SafeRuntimeRAL
+from .integrated_runtime_ral import IntegratedRuntimeRAL
+from .transaction_logger import TransactionLogger
+
+# Cocotb-dependent classes.
+try:
+    from .monitor import ApbRalMonitor, AxiLiteRalMonitor, AxiRalMonitor
+except ImportError:
+    pass

cocotbext_ral-0.5.2/cocotbext/ral/access_policy.py

@@ -0,0 +1,66 @@
+"""Field access policy helpers for the runtime path.
+
+Supports common SystemRDL-style semantics including RW, RO, WO, W1C, W1S,
+RCLR, and RSET.
+"""
+
+from dataclasses import dataclass
+
+from .register_model import RegisterField, SwAccess
+from .state import FieldState
+from .volatile_policy import check_allowed as _volatile_check_allowed
+
+
+@dataclass(frozen=True)
+class AccessPolicy:
+    """Behavioral policy for a field's software-visible access semantics."""
+
+    sw_access: SwAccess
+
+    def apply_write(self, field: RegisterField, state: FieldState, write_value: int) -> None:
+        """Apply a software write to runtime field state."""
+        value = write_value & field.mask
+
+        if self.sw_access == SwAccess.RW:
+            state.mirrored = value
+        elif self.sw_access == SwAccess.WO:
+            state.mirrored = value
+        elif self.sw_access == SwAccess.W1C:
+            state.mirrored &= ~value
+            state.mirrored &= field.mask
+        elif self.sw_access == SwAccess.W1S:
+            state.mirrored |= value
+            state.mirrored &= field.mask
+        elif self.sw_access in (SwAccess.RO, SwAccess.RCLR, SwAccess.RSET):
+            return
+
+        state.desired = state.mirrored
+        state.dirty = False
+
+    def apply_read_side_effect(self, field: RegisterField, state: FieldState) -> None:
+        """Apply any state change caused by reading the field."""
+        if self.sw_access == SwAccess.RCLR:
+            state.mirrored = 0
+            state.desired = 0
+        elif self.sw_access == SwAccess.RSET:
+            state.mirrored = field.mask
+            state.desired = field.mask
+
+    def check_on_read(self, field: RegisterField, state: FieldState) -> bool:
+        """Return True if the field should be checked on reads."""
+        if not _volatile_check_allowed(field, state):
+            return False
+        return self.sw_access in (
+            SwAccess.RW,
+            SwAccess.W1C,
+            SwAccess.W1S,
+            SwAccess.RCLR,
+            SwAccess.RSET,
+        )
+
+
+class PolicyRegistry:
+    """Minimal registry from field spec to runtime policy object."""
+
+    def policy_for(self, field: RegisterField) -> AccessPolicy:
+        return AccessPolicy(field.sw_access)

cocotbext_ral-0.5.2/cocotbext/ral/adapters/__init__.py

@@ -0,0 +1,6 @@
+from .json_loader import load_json
+
+try:
+    from .rdl_loader import load_rdl
+except ImportError:
+    pass

cocotbext_ral-0.5.2/cocotbext/ral/adapters/json_loader.py

@@ -0,0 +1,133 @@
+"""Load a RegisterModel from RDL-generated JSON.
+
+Parses the hierarchical JSON format produced by create_reg_json.py
+(addrmap -> regfile -> reg -> field) into the RAL RegisterModel.
+"""
+
+import json
+from typing import Union
+from pathlib import Path
+
+from ..register_model import (
+    Memory,
+    RegisterField,
+    Register,
+    RegisterBlock,
+    RegisterModel,
+    SwAccess,
+)
+
+
+def _map_sw_access(sw_access_str: str, woclr: int) -> SwAccess:
+    """Map JSON sw_access string + woclr flag to SwAccess enum."""
+    sw = sw_access_str.lower()
+    if sw == "rw" and woclr:
+        return SwAccess.WOCLR
+    if sw == "rw":
+        return SwAccess.RW
+    if sw == "r":
+        return SwAccess.RO
+    if sw == "w":
+        return SwAccess.WO
+    # Default to RW for unknown access types
+    return SwAccess.RW
+
+
+def _parse_node(
+    node: dict,
+    model: RegisterModel,
+    base_address: int,
+    name_prefix: str,
+):
+    """Recursively walk the JSON hierarchy, accumulating addresses and names."""
+    node_type = node.get("type", "")
+    inst_name = node.get("inst_name", "")
+    addr_offset = node.get("addr_offset", 0)
+    current_address = base_address + addr_offset
+
+    # Build hierarchical name
+    if name_prefix:
+        current_name = f"{name_prefix}.{inst_name}"
+    else:
+        current_name = inst_name
+
+    if node_type == "reg":
+        # Parse fields
+        fields = []
+        for child in node.get("children", []):
+            if child.get("type") == "field":
+                reset_val = child.get("reset", 0)
+                if not isinstance(reset_val, (int, float)):
+                    reset_val = 0
+                reset_val = int(reset_val)
+
+                sw_access = _map_sw_access(
+                    child.get("sw_access", "rw"),
+                    child.get("woclr", 0),
+                )
+                field = RegisterField(
+                    name=child["inst_name"],
+                    lsb=child["lsb"],
+                    msb=child["msb"],
+                    reset_value=reset_val,
+                    sw_access=sw_access,
+                )
+                fields.append(field)
+
+        reg = Register(
+            name=inst_name,
+            address=current_address,
+            size_bits=node.get("regsize", 32),
+            fields=fields,
+            description=node.get("desc", ""),
+        )
+        model.add_register(reg, hierarchical_name=current_name)
+        return
+
+    if node_type == "mem":
+        # Parse memory regions (SRAM, apertures, FIFOs, etc.)
+        memwidth = node.get("memwidth", 32)
+        mementries = node.get("mementries", 0)
+        size_bytes = (memwidth * mementries) // 8
+        mem = Memory(
+            name=inst_name,
+            base_address=current_address,
+            size_bytes=size_bytes,
+            description=node.get("desc", ""),
+        )
+        mem.hierarchical_name = current_name
+        model.add_memory(mem, hierarchical_name=current_name)
+        return
+
+    # For addrmap, regfile, or any container: recurse into children
+    for child in node.get("children", []):
+        child_type = child.get("type", "")
+        if child_type in ("addrmap", "regfile", "reg", "mem"):
+            _parse_node(child, model, current_address, current_name)
+
+
+def load_json(
+    json_path: Union[str, Path],
+    model_name: str = "",
+) -> RegisterModel:
+    """Load a RegisterModel from an RDL-generated JSON file.
+
+    Args:
+        json_path: Path to the JSON register description file.
+        model_name: Optional name for the model. Defaults to the root
+            inst_name from the JSON.
+
+    Returns:
+        A populated RegisterModel.
+    """
+    json_path = Path(json_path)
+    with open(json_path, "r") as f:
+        root = json.load(f)
+
+    name = model_name or root.get("inst_name", json_path.stem)
+    model = RegisterModel(name=name)
+
+    # The root is typically an addrmap — recurse from there
+    _parse_node(root, model, base_address=0, name_prefix="")
+
+    return model