# Mini Product LP/HP Architecture

The frozen [GA2D specification](ip/ga2d.md) defines the phased GA2D delivery.
Phase 2 expands the implemented platform to nine AXI64 masters with seven-bit
global IDs and Resource Controller entry 8. Phase 5 activates its dedicated
PCLK-to-HP AXI64/ID3 bridge as a direct single-job private-AXI64 2D engine
controlled at `APB4_GA2D`, with resource-owned IRQ. Existing hart,
memory, and source identities remain fixed.

## Product contract

Every committed `MINI_MODE=PRODUCT` profile instantiates two fixed harts:

| Property | LP management | HP application |
| --- | --- | --- |
| Core | Hazard3 | generated VexiiRiscv |
| Hart ID | 0 | 1 |
| ISA | profile RV32I/RV32IM | RV64IMAFDC + Zicbom, S/U mode, Sv39 |
| Reset clock | REF24 at 24 MHz | external 72 MHz safe clock |
| Role | boot, control, diagnostics, recovery | high-throughput application/Linux |
| JTAG | reset owner | selectable while HP is held in reset |

The product generator reports `USER_CORE_COUNT=0`, `USER_IP_COUNT=0`, and
`EXTENSION_COUNT=2`. The former C0-C3 cores and selectable user-IP designs are
available only through `configs/cluster/mini-mpw.mk`; they are not part of the
product address, interrupt, or lifecycle ABI.

There is no hardware cache coherency. Firmware and operating systems must use
explicit ownership, fences, and cache maintenance for shared buffers.

## Clock and reset domains

`soc_clock_reset_subsystem` is the product clock/reset implementation behind
the compatibility `rcu` wrapper.

| Domain | Root | Implemented policy |
| --- | --- | --- |
| AON | dedicated REF24 input | fixed 24 MHz; PLL/clock/pad control and 1 MHz tick |
| LP | REF24 or divided HP | reset default REF24; AUTO/MANUAL division never exceeds 72 MHz |
| HP | EXT72 or PLL | reset default EXT72; generic model supports 72-240 MHz in 24 MHz steps |
| PCLK | LP generated clock | `/1`, `/2`, `/4`, `/8`, `/16`; APB register banks |
| memory | EXT72 `/2` | stable 36 MHz root exported for protocol-engine migration |
| audio | dedicated input | independent audio/RTC/watchdog engine clock |
| DVP, ULPI, JTAG | external functional clocks | dedicated CDC and reset contracts |

Root selection uses Common `safe_clock_mux`; integer division uses Common clock
dividers. The PCLK divider is reset from AON so generated-clock startup cannot
depend on its own downstream reset. `clock_reset_domains.json` records reset
synchronizers and the approved CDC primitives.

`pll_rcu_controller` runs from AON and implements validate, quiesce, LP park,
EXT72 safe selection, PLL apply, lock-low observation, lock qualification,
PLL selection, LP restore, response, and fail-safe states. It blocks new HP
traffic while switching and falls back to EXT72 on timeout or runtime lock
loss. Fault state is sticky until explicitly cleared.

The generic functional PLL maps selectors 0-7 to 72, 96, 120, 144, 168, 192,
216, and 240 MHz from REF24. The ICS55 hard-macro wrapper accepts selector 0
only; other selectors fail safe. This is a digital integration contract, not
PLL jitter, PVT, or clock-tree signoff.

## Control plane

Hazard3 keeps a direct 32-bit control path:

```text
Hazard3 -> AHB-Lite adapter -> LP AXI32 control fabric
        -> LP/PCLK bridge -> APB4 peripheral and system register banks
```

HP uncached MMIO is downsized to AXI32 and crosses HP to LP through
`axi4_async_bridge`. Product access control rejects HP writes to root SYSCTRL,
watchdog, and GPIO administration windows with `SLVERR`; Hazard3 retains full
management access.

`axi4_mgmt_router` keeps APB/control addresses on this path and routes every
memory window through an LP-to-HP data gateway. Hazard3 therefore shares the
same memory admission, inactive-pad, ACL, and fault path as HP and DMA.

## Native AXI64 data plane

`soc_data_plane` contains a 9-master, 6-target AXI64 crossbar. Read and write
channels progress independently, and different source IDs may be active against
the same or different targets. The same source ID is blocked until completion.
SRAM and SDRAM accept four reads and two writes; serial memories and the error
target accept one per direction. Responses route by the global-ID master prefix,
and a Common FIFO preserves write-data order where AXI4 W has no ID.

| Master | Entry path |
| --- | --- |
| HP I-cache | native AXI64, ID prefix 0 |
| HP D-cache | native AXI64, ID prefix 1 |
| central DMA | PCLK-to-HP async bridge, AXI32-to-64 upsizer |
| I/O gateway A | USB2 and SDIO0, then PCLK-to-HP CDC and upsizer |
| I/O gateway B | SDIO1 and SPI-SD, then PCLK-to-HP CDC and upsizer |
| LP data gateway | Hazard3 memory traffic, LP-to-HP CDC and upsizer |
| JPEG | PCLK-to-HP AXI64 async bridge, ID prefix 6; one normal read and one normal write credit, class 8 |
| EXT-H | PCLK-to-HP AXI64 async bridge, ID prefix 7 |
| GA2D | dedicated PCLK-to-HP AXI64/ID3 async bridge; direct single-job FILL/COPY/CONVERT/BLEND engine |

Targets are SRAM, SDRAM, QPI PSRAM, OPI/HyperBus PSRAM, XPI/flash, and a
finite-latency error slave. SRAM is a native AXI64, seven-bit-ID target in HP and
stripes each beat across two existing 32-bit technology macros. SDRAM, QPI,
OPI, and XPI cross directly from HP to the stable memory domain as AXI64 and
are downsized only beside their current 32-bit controller frontends. Serial
payload therefore does not consume LP fabric bandwidth. Inactive QPI/OPI
windows return `SLVERR`.

Every memory target has a queued guard. SRAM/SDRAM queue depth matches their
credits. Target stalls are bounded by target-specific timeouts; a pre-accept
stall receives synthetic `SLVERR`, while an accepted timeout flushes the CDC
boundary, completes the original burst with `SLVERR`, and permanently isolates
that target until hard reset so a late response cannot contaminate new traffic.

All async AXI channels use Common coordinated warm-flush FIFOs and expose a
source-domain epoch. HP shutdown holds a flush request until every bridge sees
it, then waits for bridge recovery before resetting the core.

`data_plane_fault_cdc` carries HP fault metadata to PCLK through Common's
one-entry `async_reqack` mailbox. The crossbar and target guards hold a
valid, stable 44-bit fault payload until its ready handshake, applying
backpressure before another reportable fault can retire. Reset in either
mailbox domain aborts an item already accepted by the mailbox; a unilateral
PCLK reset keeps an unaccepted HP-source event backpressured until the link
is released.

## Memory and shared pads

Product profiles instantiate on-chip SRAM, SDRAM, QPI, OPI/HyperBus, and XPI
integration paths. The on-chip SRAM product size is 32 KiB. ICS55 uses two
16 KiB `SRAM_4096X32_M8_BW` macros; committed ICS55 regression profiles keep
the SRAM interface/macro disabled until commercial models are supplied locally.

QPI and OPI share GPIO21-31 through `memory_pad_mux`. AON retains
`MEM_PAD_MODE` and its lock across LP/HP changes. Reset selects QPI to preserve
the established boot flow. The inactive controller receives safe input values,
its clock/chip-select/output-enable path is inactive, and mapped data access
returns `SLVERR`. The first product implementation permits boot-time selection
only, not a live protocol switch.

## Extensions

Product Mini has fixed control windows:

| Slot | Window | IRQ | Data path |
| --- | --- | --- | --- |
| EXT-L 0 | `0x20008000-0x20008FFF` | LP IRQ 27 | APB4 only |
| EXT-H 1 | `0x20009000-0x20009FFF` | LP IRQ 28 | APB4 plus AXI64 data master |

Each slot exposes identification, version, capability, owner/lock, lifecycle,
status, timeout, first fault, fault address, and request count. EXT-H adds read
and write ACL ranges that are enforced at data-plane admission. The reference
EXT-H DMA performs aligned 64-bit memory copies with a partial final strobe.
Its IRQ is delivered to LP IRQ 28 or HP PLIC source 3 according to owner,
never both. Software discovers it through `<retrosoc/hal/extension.h>`.

The Resource Controller at `0x2000_A000` is the central owner and IRQ authority
for DMA, USB2, SDIO0/1, SPI-SD, EXT-H, JPEG, APU, and the P5 GA2D engine.
Resource 8 routes its raw IRQ exclusively to LP vector 32/external ordinal 30
or HP PLIC source 11 according to owner, while its associated AXI bridge carries
only that engine's direct FILL/COPY/CONVERT/BLEND traffic. The existing HP
smoke workload remains a FILL/COPY subset; it is not P5 composition or cache
coherency evidence.
Handoff requires idle, owner lock is sticky, and rejected handoffs raise LP IRQ
29. APU index 7 routes exclusively to LP IRQ31 or HP PLIC source10. The
controller also carries the AON cache request/clean acknowledgement used before
HP drain. See
[`ip/resource-controller.md`](ip/resource-controller.md).
Resource 8 qualifies its HP block acknowledgement with a fresh synchronized
source-quiesced state, so an old idle sample cannot hand off a
`WVALID`-before-`AWVALID` write.

The root-only Fabric Monitor at `0x2000_B000` records per-master and
per-target traffic, wait, promotion, credit high-water, timeout, isolation,
flush, and sticky first-fault information. Its APB path crosses PCLK to HP so
the counters observe the native fabric directly. See
[`ip/fabric-monitor.md`](ip/fabric-monitor.md).

The old `APB4_USER_IP` window is a read-only compatibility/capability window.
Product writes to `CORESEL`, `IPSEL`, `USER_CORE_RESET`, or
`USER_CORE_STATUS` return APB `PSLVERR`; legacy HAL mutators return
`RS_ENOTSUP`.

## Configuration and local ICS55 models

Committed `configs/ci/ics55.mk` and `configs/cluster/ics55.mk` deliberately set
both PLL and SRAM to `NO`. `configs/local/ics55.example.mk` documents an
ignored local profile with PLL, SRAM interface, SRAM macro, and 32 KiB enabled.
`LOCAL_RTL_FILES` injects commercial SRAM and PLL simulation models into only
that generated variant filelist. `configs/local/*.mk` and `*.sv` are ignored,
so absolute commercial paths are never tracked.

## Evidence boundary

Behavioral RTL, firmware, directed data-plane/lifecycle/clock tests, manifest
parity, and quality checks are the evidence for this implementation. HP stop
implements a pre-drain cache request/ACK window, drain, coordinated flush,
actual-release status, and bounded forced reset. Vexii implements 64-byte
`Zicbom`; software still owns shared-range selection, and a forced reset cannot
preserve dirty cache data when the ACK times out. It must not be
called cache coherent, power isolated, timing closed, CDC/RDC signed off, or
silicon-qualified. Synthesis, netlist simulation, STA, MMMC, clock-tree, DFT,
and analogue PLL qualification are separate gates.