mirror of
https://github.com/retroSoC/retroSoC.git
synced 2026-11-05 06:32:37 +00:00
maksyuki
109326021d
- Updated testbench and wrapper test cases to reflect GA2D Phase 5 changes. - Modified Python test scripts to validate Phase 5 functionality and requirements. - Enhanced DMA tests for byte-accurate coverage in Phase 5. - Adjusted register parity tests to include Phase 5 capability and limits. - Updated publication software tests to reference GA2D Phase 5. - Changed formal target tests to utilize Phase 5 production hierarchy.
116 lines
7.2 KiB
Markdown
116 lines
7.2 KiB
Markdown
# APB4 System Control
|
|
|
|
SystemCtrl is the Mini SoC control-plane peripheral at
|
|
`0x1000B000`. It owns legacy user-core/IP compatibility, PLL and clock requests,
|
|
memory-pad mode,
|
|
bus-fault retention, performance-counter snapshots, RTC wake observation, and
|
|
the terminal simulation result. In the HP profile it also owns HP reset release
|
|
and shared-JTAG selection. The integration wrapper is `apb4_sysctrl`;
|
|
the implementation is separated into `sysctrl_reg`, `sysctrl_core`, and
|
|
`sysctrl_if`.
|
|
|
|
## Integration
|
|
|
|
`sysctrl_if` is the SoC-facing contract. It drives the selected user core,
|
|
per-core reset mask, user-bus enable, selected user IP, performance
|
|
enable/clear, and sticky terminal test result. It receives user-bus idle,
|
|
fault metadata, ten wait counters (including independent SDIO0 and SDIO1
|
|
master wait counters), and asynchronous RTC wake. `sysctrl_core`
|
|
synchronizes RTC wake with the Common `cdc_sync` primitive before storing its
|
|
sticky state. HP data-plane faults cross into PCLK through an acknowledged
|
|
mailbox. Their HP sources use valid/ready flow control and retain the complete
|
|
44-bit `{master,target,address,write,reason}` payload until the mailbox
|
|
accepts it, so every accepted no-reset event is delivered once with coherent
|
|
metadata. A reset in either mailbox domain aborts an item already accepted by
|
|
the mailbox; a unilateral PCLK reset backpressures an unaccepted HP source
|
|
event until the link is released. A data-plane fault visible in the same PCLK
|
|
cycle as a local bus fault retains data-plane priority.
|
|
|
|
`pll_ctrl_if` carries a one-request PLL configuration handshake. SystemCtrl
|
|
asserts `req_valid_o` after a valid `PLL_CMD.APPLY`, holds `busy` until the
|
|
PLL response is accepted, and always asserts `rsp_ready_o`. See
|
|
[PLL Clock Control](../pll-clock-control.md) for the required software
|
|
quiesce sequence. `clock_ctrl_if` independently carries LP/PCLK, force-safe,
|
|
timeout, gate, memory-pad, status, and fault requests between PCLK and AON.
|
|
|
|
## APB4 contract
|
|
|
|
SystemCtrl accepts an APB4 access in the ACCESS phase when `psel` and
|
|
`penable` are high and the registered `pready` is still low. It completes in
|
|
the following cycle and captures read data on accepted reads. Reads of an
|
|
unmapped register retain the previously captured read value. Product writes to
|
|
retired user-core/IP controls and rejected concurrent clock commands assert
|
|
`pslverr`. Writes use the existing byte strobe
|
|
qualification for each field; software must use full-word writes for
|
|
`TEST_STATUS`.
|
|
|
|
The offset map remains generated from
|
|
`rtl/mini/address_map/memory_map.json`. RTL aliases are in
|
|
`rtl/ip/peripheral/sysctrl_define.svh`; neither file changes the generated C
|
|
offset macros.
|
|
|
|
## Register ABI
|
|
|
|
| Offset | Register | Access | Semantics |
|
|
| --- | --- | --- | --- |
|
|
| `0x000` | `CORESEL` | RO/unsupported | Product reads zero; writes return `PSLVERR`. MPW retains selection. |
|
|
| `0x004` | `IPSEL` | RO/unsupported | Product reads zero; writes return `PSLVERR`. MPW retains selection. |
|
|
| `0x008` | `PLL_CFG` | RW | Requested PLL profile, bits `[2:0]`. |
|
|
| `0x00C` | `PLL_CMD` | WO | Bit 0 applies `PLL_CFG`; bit 1 clears sticky PLL error. |
|
|
| `0x010` | `FAULT_STATUS` | RW1C | Bit 0 pending, bit 1 write, bits `[4:2]` normalized reason. Write one to bit 0 clears pending. |
|
|
| `0x014` | `FAULT_ADDR` | RO | First fault address while pending. |
|
|
| `0x018` | `FAULT_COUNT` | RO | Saturating count of observed faults. |
|
|
| `0x01C` | `PLL_STATUS` | RO | Active profile, valid, busy, error/error reason, safe clock, lock, and capability. |
|
|
| `0x020` | `USER_CORE_RESET` | RO/unsupported | Product reads all ones and rejects writes. MPW retains its reset mask. |
|
|
| `0x024` | `USER_CORE_STATUS` | RO/unsupported | Product reports present=0, idle=1, and sticky unsupported-write error. |
|
|
| `0x028` | `FAULT_MASTER` | RO | First fault master, a four-bit AXI master ID (0..8); HP is 7 and the active P5 GA2D private-AXI64 master is 8. The offset is unchanged. |
|
|
| `0x02C` | `FAULT_DETAIL` | RO | First raw RIB response code. |
|
|
| `0x040` | `PERF_CTRL` | RW | Bit 0 enable, bit 1 clear pulse, bit 2 snapshot pulse. |
|
|
| `0x044`-`0x098` | `PERF_*_WAIT_{LO,HI}` | RO | Snapshot of management, user, central DMA, SDIO0, SDIO1, APB4, SDRAM, PSRAM, and flash wait counters. |
|
|
| `0x08C`/`0x090` | `PERF_SDIO0_WAIT_LO/HI` | RO | Independent SDIO0 AXI master wait snapshot. |
|
|
| `0x094`/`0x098` | `PERF_SDIO1_WAIT_LO/HI` | RO | Independent SDIO1 AXI master wait snapshot. |
|
|
| `0x084` | `TEST_STATUS` | RW-once/RO | Full-word write with bit 31 set records sticky done, bit 0 pass, and bits `[15:8]` result code. |
|
|
| `0x088` | `RTC_WAKE_STATUS` | RW1C/RO | Bit 0 synchronized live wake; bit 1 sticky wake, cleared by writing one to bit 1. |
|
|
| `0x0A4` | `HP_CTRL` | RW | Bit 0 releases HP reset when the HP profile is present. Reset value 0. |
|
|
| `0x0A8` | `HP_STATUS` | RO | Bits 0/1/2 preserve present and requested release/reset; bits 3/4/5 report draining, forced fault, and actual release. |
|
|
| `0x0AC` | `DEBUG_SELECT` | RW | Bit 0 selects HP on shared JTAG only while HP remains in reset. Reset value 0 selects LP. |
|
|
| `0x0B0` | `CLK_HP_REQ` | RW/WO command | HP P-state; bits 31/30 apply PLL/force safe. |
|
|
| `0x0B4` | `CLK_HP_CURRENT` | RO | Current HP source/P-state and LP/PCLK/gate configuration. |
|
|
| `0x0B8` | `CLK_LP_CFG` | RW | LP SAFE/AUTO/MANUAL mode and `/1,/2,/4` selection. |
|
|
| `0x0BC` | `CLK_PCLK_CFG` | RW | PCLK `/1,/2,/4,/8,/16` selector. |
|
|
| `0x0C0` | `CLK_STATUS` | RO | PLL fault, clock error, and busy state. |
|
|
| `0x0C4` | `CLK_FAULT` | RW1C/RO | AON PLL/clock fault summary and clear command. |
|
|
| `0x0C8` | `CLK_TIMEOUT` | RW | Nonzero AON transaction timeout. |
|
|
| `0x0CC` | `CLK_GATE` | RW | Reserved leaf-gate mask state. |
|
|
| `0x0D0` | `MEM_PAD_CTRL` | RW-once | QPI/OPI mode and lock. |
|
|
| `0x0D4` | `MEM_PAD_STATUS` | RO | Present, mode, lock, and fault. |
|
|
| `0x0D8` | `MEM_PAD_FAULT` | RW1C/RO | Illegal mode/locked-write fault. |
|
|
|
|
The first fault remains visible until software clears pending; later faults
|
|
increase only the saturating count. A hardware fault in the clear cycle
|
|
remains pending. `TEST_STATUS` accepts the first valid full-word write after
|
|
reset and ignores all later writes, allowing the simulator to use a stable
|
|
verdict.
|
|
|
|
## SDK contract
|
|
|
|
`<retrosoc/hal/sysctrl.h>` owns typed SystemCtrl access. It provides semantic
|
|
operations for legacy compatibility, PLL/clock configuration/status, fault
|
|
inspection and clear, performance control/counter reads, terminal status, and
|
|
RTC wake state. Legacy `reg_sysctrl_*` lvalue macros are intentionally absent
|
|
from `<retrosoc/core/soc.h>`.
|
|
|
|
Existing `<retrosoc/hal/clock.h>`, `<retrosoc/hal/user_core.h>`, and
|
|
`<retrosoc/hal/perf.h>` APIs retain their behavior and delegate their
|
|
SystemCtrl accesses to this HAL. `<retrosoc/service/test.h>` writes the
|
|
sticky terminal result through `rs_sysctrl_write_test_status()`.
|
|
|
|
## Verification
|
|
|
|
`tests/test_sysctrl.py` and `tests/rtl/sysctrl_tb.sv` check APB4 response
|
|
retention, reset values, retired-control errors, first-fault retention and
|
|
W1C behavior, performance snapshots, sticky terminal status, and RTC wake
|
|
live/sticky behavior. `sysctrl_formal` proves the user-core, PLL, fault, and
|
|
test-status invariants and covers normal/error paths. The separate PLL/RCU
|
|
test retains dynamic-clock and fallback coverage.
|