admin/retroSoC
1
0 Fork 0
mirror of https://github.com/retroSoC/retroSoC.git synced 2026-11-04 22:32:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
75ed04e7ef71f928f12ee5f3382572d30afed7b8
retroSoC/publications/datasheets/system-reference.json
T

7212 lines
254 KiB
JSON
Raw Blame History

{
"schema_version": 1,
"source_revision": "2a497ecef0b084c02f77ddfb1e94fb0197e14b02",
"sources": [
"app/README.md",
"app/apps/hp_boot/hp_boot_bundle.h",
"app/apps/hp_boot/main.c",
"app/ports/linux/README.md",
"app/ports/linux/linux/retrosoc_hp.dts",
"app/ports/linux/opensbi/retrosoc_hp/platform.c",
"configs/benchmark/ihp130-hazard3-coremark.mk",
"configs/ci/ihp130-hp.mk",
"configs/ci/ihp130.mk",
"configs/cluster/mini-mpw.mk",
"crt/README.md",
"crt/include/retrosoc/hal/ga2d.h",
"crt/include/retrosoc/hal/resource.h",
"crt/include/retrosoc/hal/sysctrl.h",
"crt/src/hal/ga2d.c",
"crt/src/hal/resource.c",
"crt/src/hal/sysctrl.c",
"docs/axi4-interconnect.md",
"docs/axi4-stream.md",
"docs/coremark.md",
"docs/engineering.md",
"docs/hazard3-debug.md",
"docs/ip/fabric-monitor.md",
"docs/ip/ga2d.md",
"docs/ip/resource-controller.md",
"docs/lp-hp-architecture.md",
"docs/mini-high-performance-traceability.md",
"docs/pll-clock-control.md",
"fpga/README.md",
"physical/README.md",
"publications/datasheets/mini.json",
"publications/datasheets/register-profiles.json",
"rtl/ip/multimedia/apb4_apu.sv",
"rtl/ip/multimedia/apb4_ga2d.sv",
"rtl/ip/multimedia/apu_define.svh",
"rtl/ip/multimedia/apu_kws_engine.sv",
"rtl/ip/multimedia/apu_kws_model_loader.sv",
"rtl/ip/multimedia/apu_kws_sram_client.sv",
"rtl/ip/multimedia/apu_local_sram.sv",
"rtl/ip/multimedia/apu_p5_codecs.apus",
"rtl/ip/multimedia/ga2d_core.sv",
"rtl/ip/multimedia/ga2d_dma.sv",
"rtl/mini/integration/soc_topology.json",
"scripts/apu_isa.py",
"scripts/apu_kws.py",
"scripts/apu_mcasm.py",
"scripts/apu_p5_coefficients.py",
"scripts/build_apu_p5_bundle.py",
"scripts/build_hp_linux.py",
"scripts/check_lp_hp_performance.py",
"scripts/package_hp_boot.py",
"tests/test_lp_irq.py"
],
"support": [
{
"id": "xpi",
"title": "XPI Universal Controller",
"implementation": "Integrated",
"scope": "Four chip-select slots and 16 programmable LUT sequences.",
"dependencies": "External SDR SPI/QSPI flash; board-specific LUT and timing.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Memory/controller setup is a platform responsibility; only SDRAM is advertised as Linux RAM in the supplied DT.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/xpi.h",
"docs/ip/xpi.md",
"publications/examples/xpi.c",
"rtl/ip/storage/xpi_pkg.sv",
"rtl/ip/storage/xpi_reg.sv"
],
"tests": [
"tests/test_xpi_io.py"
],
"reports": []
},
{
"id": "spisd",
"title": "SPI SD Card Controller",
"implementation": "Integrated",
"scope": "SD card SPI-mode command/data host.",
"dependencies": "SPI-mode SD card; GPIO route and card supply.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/spisd.h",
"docs/ip/spisd.md",
"publications/examples/spisd.c",
"rtl/ip/storage/spisd_pkg.sv",
"rtl/ip/storage/spisd_reg.sv"
],
"tests": [
"tests/test_spisd.py"
],
"reports": []
},
{
"id": "sdio0",
"title": "SD/SDIO Host Controller",
"implementation": "Integrated",
"scope": "Native one-bit/four-bit SDR operation.",
"dependencies": "SD card and shared GPIO route.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/sdio.h",
"docs/ip/sdio.md",
"publications/examples/sdio.c",
"rtl/ip/storage/sdio_pkg.sv",
"rtl/ip/storage/sdio_reg.sv"
],
"tests": [
"tests/test_sdio.py"
],
"reports": []
},
{
"id": "sram",
"title": "On-Chip SRAM",
"implementation": "Integrated",
"scope": "32 KiB in the reference profile, using eight 4 KiB banks.",
"dependencies": "Selected technology SRAM macro; 32 KiB in the reference profile.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Memory/controller setup is a platform responsibility; only SDRAM is advertised as Linux RAM in the supplied DT.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/onchip_sram.h",
"docs/ip/onchip-sram.md",
"publications/examples/sram.c",
"rtl/mini/top/onchip_ram_reg.sv"
],
"tests": [
"tests/test_onchip_sram_register_parity.py"
],
"reports": []
},
{
"id": "psram",
"title": "QPI PSRAM Controller",
"implementation": "Integrated",
"scope": "Four ESP-PSRAM64H devices addressable through a 32 MiB window.",
"dependencies": "External QPI PSRAM; mutually exclusive with OPI on shared memory pads.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Memory/controller setup is a platform responsibility; only SDRAM is advertised as Linux RAM in the supplied DT.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/psram.h",
"docs/ip/psram.md",
"publications/examples/psram.c",
"rtl/ip/memory/psram_pkg.sv",
"rtl/ip/memory/psram_reg.sv"
],
"tests": [
"tests/test_psram.py"
],
"reports": []
},
{
"id": "opipsram",
"title": "OPI PSRAM Controller",
"implementation": "Partial",
"scope": "One octal DDR memory interface and one selected protocol profile.",
"dependencies": "Compatible octal/HyperBus-style device; shared pads and board timing qualification.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Memory/controller setup is a platform responsibility; only SDRAM is advertised as Linux RAM in the supplied DT.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/opipsram.h",
"docs/ip/opipsram.md",
"publications/examples/opipsram.c",
"rtl/ip/memory/opipsram_pkg.sv",
"rtl/ip/memory/opipsram_reg.sv"
],
"tests": [
"tests/test_opipsram.py"
],
"reports": []
},
{
"id": "sdram",
"title": "SDRAM Controller",
"implementation": "Integrated",
"scope": "Fixed 64 MiB, x16 SDR geometry with bank/row tracking.",
"dependencies": "External x16 SDR SDRAM; initialization and refresh timings.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Memory/controller setup is a platform responsibility; only SDRAM is advertised as Linux RAM in the supplied DT.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/sdram.h",
"docs/ip/sdram.md",
"publications/examples/sdram.c",
"rtl/ip/memory/sdram_pkg.sv",
"rtl/ip/memory/sdram_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "gpio",
"title": "GPIO Controller",
"implementation": "Integrated",
"scope": "32 bidirectional GPIOs with administration and restricted user windows.",
"dependencies": "Selected pad library and approved pin routing.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/gpio.h",
"docs/ip/gpio.md",
"publications/examples/gpio.c",
"rtl/ip/peripheral/gpio_reg.sv"
],
"tests": [
"tests/test_gpio.py"
],
"reports": []
},
{
"id": "dma",
"title": "DMA Controller",
"implementation": "Integrated",
"scope": "Eight channel contexts share a 32-bit AXI master.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"docs/ip/dma.md",
"publications/examples/dma.c",
"rtl/ip/peripheral/dma_pkg.sv",
"rtl/ip/peripheral/dma_reg.sv"
],
"tests": [
"tests/test_dma.py"
],
"reports": []
},
{
"id": "timer",
"title": "General-Purpose Timers",
"implementation": "Integrated",
"scope": "Two 32-bit general-purpose timers.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/timer.h",
"docs/ip/timer.md",
"publications/examples/timer.c",
"rtl/ip/peripheral/timer_reg.sv"
],
"tests": [
"tests/test_timer.py"
],
"reports": []
},
{
"id": "rtc",
"title": "Real-Time Clock",
"implementation": "Integrated",
"scope": "64-bit seconds and 1/256-second subsecond time.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/rtc.h",
"publications/examples/rtc.c",
"rtl/managed/clusterip/rtc/doc/datasheet.md",
"rtl/managed/clusterip/rtc/rtl/rtc_pkg.sv",
"rtl/managed/clusterip/rtc/rtl/rtc_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "wdg",
"title": "Watchdog",
"implementation": "Integrated",
"scope": "Independent-clock window watchdog.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Register/platform interface; no standalone HAL example indexed.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"rtl/managed/clusterip/wdg/doc/datasheet.md",
"rtl/managed/clusterip/wdg/rtl/wdg_pkg.sv",
"rtl/managed/clusterip/wdg/rtl/wdg_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "pwm",
"title": "PWM Controller",
"implementation": "Integrated",
"scope": "Two timers, four output channels and two operators.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/pwm.h",
"publications/examples/pwm.c",
"rtl/managed/clusterip/pwm/doc/datasheet.md",
"rtl/managed/clusterip/pwm/rtl/pwm_pkg.sv",
"rtl/managed/clusterip/pwm/rtl/pwm_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "uart0",
"title": "UART",
"implementation": "Integrated",
"scope": "64-byte TX and RX FIFOs; fractional baud-rate generator.",
"dependencies": "Management serial connection; optional DMA/flow-control routing.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/uart.h",
"docs/ip/uart.md",
"publications/examples/uart.c",
"rtl/ip/serial/uart_reg.sv"
],
"tests": [
"tests/test_uart.py"
],
"reports": []
},
{
"id": "uart1",
"title": "UART",
"implementation": "Integrated",
"scope": "64-byte TX and RX FIFOs; fractional baud-rate generator.",
"dependencies": "Dedicated console TX/RX; no connected DMA or RTS/CTS.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "DT node exists; native driver not established. UART console uses SBI.",
"verification": "Tests available",
"sources": [
"app/ports/linux/README.md",
"app/ports/linux/linux/retrosoc_hp.dts",
"crt/include/retrosoc/hal/uart.h",
"docs/ip/uart.md",
"publications/examples/uart.c",
"rtl/ip/serial/uart_reg.sv"
],
"tests": [
"tests/test_uart.py"
],
"reports": []
},
{
"id": "i2c",
"title": "I2C Controllers",
"implementation": "Integrated",
"scope": "Two controller instances with 7-bit and 10-bit addressing.",
"dependencies": "External bus pull-ups and compatible target voltages.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/i2c.h",
"docs/ip/i2c.md",
"publications/examples/i2c.c",
"rtl/ip/serial/i2c_reg.sv"
],
"tests": [
"tests/test_i2c.py"
],
"reports": []
},
{
"id": "ws2812",
"title": "WS2812 Transmitter",
"implementation": "Integrated",
"scope": "24-bit GRB transmission on one GPIO alternate function.",
"dependencies": "Compatible LED chain and approved level/supply interface.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/ws2812.h",
"docs/ip/ws2812.md",
"publications/examples/ws2812.c",
"rtl/ip/serial/ws2812_reg.sv"
],
"tests": [
"tests/test_ws2812.py"
],
"reports": []
},
{
"id": "ps2",
"title": "PS/2 Host",
"implementation": "Integrated",
"scope": "Bidirectional open-drain host interface.",
"dependencies": "Open-drain interface and board pull-ups.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/ps2.h",
"publications/examples/ps2.c",
"rtl/managed/clusterip/ps2/doc/datasheet.md",
"rtl/managed/clusterip/ps2/rtl/ps2_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "sdio1",
"title": "SD/SDIO Host Controller",
"implementation": "Integrated",
"scope": "Native one-bit/four-bit SDR operation.",
"dependencies": "SD card and dedicated pads; generic FPGA mapping pending.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/sdio.h",
"docs/ip/sdio.md",
"publications/examples/sdio.c",
"rtl/ip/storage/sdio_pkg.sv",
"rtl/ip/storage/sdio_reg.sv"
],
"tests": [
"tests/test_sdio.py"
],
"reports": []
},
{
"id": "usb2",
"title": "USB 2.0 Controller",
"implementation": "Integrated",
"scope": "Dual-role digital controller with external 8-bit ULPI PHY.",
"dependencies": "External ULPI PHY, 60 MHz interface clock, VBUS/role circuitry.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/usb2.h",
"docs/ip/usb2.md",
"publications/examples/usb2.c",
"rtl/ip/usb/usb2_pkg.sv",
"rtl/ip/usb/usb2_reg.sv"
],
"tests": [
"tests/test_usb2.py"
],
"reports": []
},
{
"id": "archinfo",
"title": "Architecture Information",
"implementation": "Integrated",
"scope": "Read-only identity, configuration and topology discovery.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Register/platform interface; no standalone HAL example indexed.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"publications/examples/archinfo.c",
"rtl/managed/clusterip/archinfo/doc/datasheet.md",
"rtl/managed/clusterip/archinfo/rtl/archinfo_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "sysctrl",
"title": "System Controller",
"implementation": "Integrated",
"scope": "Root-managed configuration, HP lifecycle and clock requests.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/sysctrl.h",
"docs/ip/sysctrl.md",
"publications/examples/sysctrl.c",
"rtl/ip/peripheral/clock_ctrl_if.sv",
"rtl/ip/peripheral/pll_ctrl_if.sv",
"rtl/ip/peripheral/sysctrl_core.sv",
"rtl/ip/peripheral/sysctrl_if.sv",
"rtl/ip/peripheral/sysctrl_reg.sv"
],
"tests": [
"tests/test_clock_reset_domains.py"
],
"reports": []
},
{
"id": "rcu",
"title": "Reset and Clock Unit",
"implementation": "Integrated",
"scope": "AON-controlled requests and clock/reset policy.",
"dependencies": "Reference PLL disabled; any physical PLL/backend needs separate qualification.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/clock.h",
"docs/pll-clock-control.md",
"publications/examples/rcu.c",
"rtl/ip/peripheral/clock_ctrl_if.sv",
"rtl/ip/peripheral/pll_ctrl_if.sv",
"rtl/ip/peripheral/sysctrl_core.sv",
"rtl/ip/peripheral/sysctrl_if.sv",
"rtl/ip/peripheral/sysctrl_reg.sv"
],
"tests": [
"tests/test_clock_reset_domains.py"
],
"reports": []
},
{
"id": "clint",
"title": "Management CLINT",
"implementation": "Integrated",
"scope": "Per-hart software interrupts and 64-bit timer compare.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/clint.h",
"docs/ip/clint.md",
"publications/examples/clint.c",
"rtl/ip/peripheral/clint_reg.sv"
],
"tests": [
"tests/test_clint.py"
],
"reports": []
},
{
"id": "hp-aclint",
"title": "HP ACLINT",
"implementation": "Integrated",
"scope": "Two addressable hart slots; HP consumes slot 1.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Register/platform interface; no standalone HAL example indexed.",
"linux": "OpenSBI timer/IPI and standard DT bindings present; target boot report not supplied.",
"verification": "Tests available",
"sources": [
"app/ports/linux/linux/retrosoc_hp.dts",
"app/ports/linux/opensbi/retrosoc_hp/platform.c",
"docs/ip/clint.md",
"rtl/ip/peripheral/clint_reg.sv"
],
"tests": [
"tests/test_hp_platform.py"
],
"reports": []
},
{
"id": "hp-plic",
"title": "HP PLIC",
"implementation": "Integrated",
"scope": "32 source IDs, with source 0 reserved.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Register/platform interface; no standalone HAL example indexed.",
"linux": "Standard PLIC DT binding present; target IRQ validation report not supplied.",
"verification": "Tests available",
"sources": [
"app/ports/linux/linux/retrosoc_hp.dts",
"app/ports/linux/opensbi/retrosoc_hp/platform.c",
"docs/ip/hp-platform.md",
"rtl/ip/peripheral/apb4_plic.sv"
],
"tests": [
"tests/test_hp_platform.py"
],
"reports": []
},
{
"id": "hp-mailbox",
"title": "LP/HP Mailbox",
"implementation": "Integrated",
"scope": "Separate LP-to-HP and HP-to-LP payload banks.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "DT node and platform ABI exist; native mailbox driver not established.",
"verification": "Tests available",
"sources": [
"app/ports/linux/README.md",
"app/ports/linux/linux/retrosoc_hp.dts",
"crt/include/retrosoc/hal/hp_mailbox.h",
"docs/ip/hp-platform.md",
"publications/examples/mailbox.c",
"rtl/ip/peripheral/apb4_hp_mailbox.sv"
],
"tests": [
"tests/test_hp_mailbox.py"
],
"reports": []
},
{
"id": "resource",
"title": "Resource Controller",
"implementation": "Partial",
"scope": "Nine independently managed shared resources; resource 8 owns the active P5 GA2D direct 2D engine and IRQ route.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/resource.h",
"docs/ip/resource-controller.md",
"publications/examples/resource.c",
"rtl/mini/top/resource_controller.sv"
],
"tests": [
"tests/test_resource_controller.py"
],
"reports": []
},
{
"id": "monitor",
"title": "Fabric Monitor",
"implementation": "Integrated",
"scope": "Nine master and six target observation banks; bank 8 observes active P5 GA2D direct 2D traffic.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/fabric_monitor.h",
"docs/ip/fabric-monitor.md",
"publications/examples/monitor.c",
"rtl/mini/top/fabric_monitor.sv"
],
"tests": [
"tests/test_fabric_monitor.py"
],
"reports": []
},
{
"id": "i2s",
"title": "I2S Transceiver",
"implementation": "Integrated",
"scope": "Stereo master TX/RX with independent audio clock.",
"dependencies": "External audio clock and codec; stereo master operation.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/i2s.h",
"docs/ip/i2s.md",
"publications/examples/i2s.c",
"rtl/ip/serial/i2s_pkg.sv",
"rtl/ip/serial/i2s_reg.sv"
],
"tests": [
"tests/test_i2s.py"
],
"reports": []
},
{
"id": "dvp",
"title": "DVP Capture",
"implementation": "Integrated",
"scope": "8-bit parallel RGB565/YUV422 capture.",
"dependencies": "Parallel camera, sensor configuration and pixel clock.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/dvp.h",
"docs/ip/dvp.md",
"publications/examples/dvp.c",
"rtl/ip/multimedia/dvp_reg.sv"
],
"tests": [
"tests/test_dvp.py"
],
"reports": []
},
{
"id": "jpeg",
"title": "JPEG Codec",
"implementation": "Partial",
"scope": "8-bit Baseline Sequential JPEG encode or decode.",
"dependencies": "Native slot-6 payload admission has one normal read and one normal write credit at class 8; standalone codec behavior and end-to-end system qualification remain separate scopes.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/jpeg.h",
"docs/ip/jpeg.md",
"publications/examples/jpeg.c",
"rtl/ip/multimedia/jpeg_pkg.sv",
"rtl/ip/multimedia/jpeg_reg.sv",
"rtl/mini/top/axi4_data_crossbar.sv",
"rtl/mini/top/soc_data_plane.sv"
],
"tests": [
"tests/test_jpeg.py",
"tests/test_ga2d_platform.py"
],
"reports": []
},
{
"id": "ga2d",
"implementation": "Integrated",
"verification": "Tests available",
"scope": "P5 direct single-job FILL, COPY, CONVERT, opaque alpha BLEND, A8 masks and exact background/destination in-place composition.",
"dependencies": "LP-owned resource admission, DATA_READY, bounded surfaces, cache ownership and external-memory readiness. Phase 6 contention/performance/physical qualification is not implied.",
"sources": [
"docs/ip/ga2d.md",
"rtl/ip/multimedia/apb4_ga2d.sv",
"rtl/ip/multimedia/ga2d_core.sv",
"rtl/ip/multimedia/ga2d_dma.sv",
"crt/include/retrosoc/hal/ga2d.h",
"crt/src/hal/ga2d.c"
],
"tests": [
"tests/test_ga2d.py",
"tests/test_ga2d_dma.py",
"tests/test_ga2d_platform.py",
"tests/test_ga2d_register_parity.py"
],
"reports": [],
"title": "2D Graphics Accelerator",
"hal": "P5 discovery, job validation/configure/start/wait, abort/reset, status/error/counter and IRQ APIs.",
"linux": "No native Linux graphics driver supplied."
},
{
"id": "apu",
"title": "Audio Processing Unit",
"implementation": "Partial",
"scope": "Microcode-controlled WAV/FLAC decoding with private DMA, direct/ring submission, I2S TX and local storage.",
"dependencies": "Load the compatible checked-in P5 APUMC V2 image. MP3 is unsupported and KWS is gated off by default; corpus, real-time and physical qualification remain separate.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/apu.h",
"crt/src/hal/apu.c",
"docs/ip/apu.md",
"publications/examples/apu.c",
"rtl/ip/multimedia/apb4_apu.sv",
"rtl/ip/multimedia/apu_p5_codecs.apus",
"rtl/ip/multimedia/apu_reg.sv",
"scripts/build_apu_p5_bundle.py"
],
"tests": [
"tests/test_apu.py"
],
"reports": []
},
{
"id": "crypto",
"title": "Crypto Controller",
"implementation": "Integrated",
"scope": "AES-128/192/256, SHA-224/256 and raw RSA-2048.",
"dependencies": "LP-controlled buffers and key lifecycle; no secure key-store claim.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Tests available",
"sources": [
"crt/include/retrosoc/hal/crypto.h",
"docs/ip/crypto.md",
"publications/examples/crypto.c",
"rtl/ip/security/apb4_crypto.sv",
"rtl/ip/security/crypto_pkg.sv"
],
"tests": [
"tests/test_crypto.py"
],
"reports": []
},
{
"id": "crc",
"title": "CRC Engine",
"implementation": "Integrated",
"scope": "Programmable 7-, 8-, 16- or 32-bit CRC.",
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/crc.h",
"publications/examples/crc.c",
"rtl/managed/clusterip/crc/doc/datasheet.md",
"rtl/managed/clusterip/crc/rtl/crc_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "rng",
"title": "RNG Controller",
"implementation": "Partial",
"scope": "Entropy-source qualification, FIFO and continuous health checks.",
"dependencies": "Entropy-source qualification absent; deterministic integration source.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/rng.h",
"publications/examples/rng.c",
"rtl/managed/clusterip/rng/doc/datasheet.md",
"rtl/managed/clusterip/rng/rtl/rng_reg.sv"
],
"tests": [],
"reports": []
},
{
"id": "ext-l",
"title": "Low-Bandwidth Extension",
"implementation": "Integrated",
"scope": "Fixed APB4 control and one interrupt.",
"dependencies": "Fixed external APB target and lifecycle contract.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/extension.h",
"docs/ip/extensions.md",
"publications/examples/ext-l.c",
"rtl/mini/top/extension_slot.sv"
],
"tests": [],
"reports": []
},
{
"id": "ext-h",
"title": "Product Extension Slots",
"implementation": "Integrated",
"scope": "Fixed EXT-H control, ownership, bounds and lifecycle.",
"dependencies": "Bounded external AXI master and ACL configuration.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Native driver support not established in this publication.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/extension.h",
"docs/ip/extensions.md",
"publications/examples/extensions.c",
"rtl/mini/top/extension_slot.sv"
],
"tests": [],
"reports": []
},
{
"id": "mpw-timer",
"title": "MPW User Timer",
"implementation": "MPW only",
"scope": "MPW-selectable timer and divider.",
"dependencies": "MPW profile, selected user-IP manifest and pad ownership.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Outside the fixed PRODUCT HP Linux platform.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/user_ip.h",
"docs/ip/user-ip.md",
"publications/examples/mpw_timer.c",
"rtl/managed/mpw/ip/username1/user_ip_design.sv"
],
"tests": [],
"reports": []
},
{
"id": "mpw-gpio",
"title": "MPW User GPIO",
"implementation": "MPW only",
"scope": "MPW-selectable user GPIO data and enables.",
"dependencies": "MPW profile, selected user-IP manifest and pad ownership.",
"hal": "Published API and syntax example; see the IP chapter.",
"linux": "Outside the fixed PRODUCT HP Linux platform.",
"verification": "Source reviewed",
"sources": [
"crt/include/retrosoc/hal/user_ip.h",
"docs/ip/user-ip.md",
"publications/examples/mpw_gpio.c",
"rtl/managed/mpw/ip/username2/user_ip_design.sv"
],
"tests": [],
"reports": []
}
],
"limitations": [
{
"id": "no-hardware-coherency",
"title": "Shared buffers are not hardware coherent",
"impact": "Stale reads or loss of dirty data across CPU/DMA ownership changes.",
"trigger": "Concurrent cached CPU access and non-snooping DMA/LP access.",
"workaround": "Use exclusive ownership, whole cache-block ranges, directional cache maintenance and fences.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/resource-controller.md"
]
},
{
"id": "hp-ready-wait",
"title": "HP loader has no firmware-local ready timeout",
"impact": "LP can wait indefinitely for the expected Linux mailbox event.",
"trigger": "No mailbox message after HP release.",
"workaround": "Use the simulator deadline during acceptance. A board supervisor/watchdog policy is integration work; no automatic retry is implemented here.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"app/apps/hp_boot/main.c",
"configs/ci/ihp130-hp.mk"
]
},
{
"id": "crc-not-authentication",
"title": "Boot CRC is not authentication",
"impact": "A CRC-valid image is not proven to come from a trusted signer.",
"trigger": "Untrusted image or writable external boot storage.",
"workaround": "Treat signing, key storage, rollback prevention and secure recovery as separate unimplemented system requirements.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"app/apps/hp_boot/main.c",
"app/apps/hp_boot/hp_boot_bundle.h"
]
},
{
"id": "native-linux-drivers",
"title": "Native Linux peripheral coverage is incomplete",
"impact": "A HAL or DT node does not provide a native Linux driver.",
"trigger": "Applications attempt direct Linux use of a custom peripheral.",
"workaround": "Use the published support matrix, retain LP ownership where needed, and validate a platform driver before handoff.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"app/ports/linux/README.md",
"app/ports/linux/linux/retrosoc_hp.dts"
]
},
{
"id": "resource-reset",
"title": "Resource reset request is not universal engine reset",
"impact": "Some downstream peripheral engines are not reset by the central lifecycle request.",
"trigger": "Using Resource CONTROL.RESET as independent engine reset containment.",
"workaround": "Drain and use each IP reset/recovery contract. APU P1 has a local reset connection; do not generalize it to all engines.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"docs/ip/resource-controller.md"
]
},
{
"id": "forced-hp-reset",
"title": "Forced HP reset can discard dirty cache state",
"impact": "Missing cache-clean acknowledgement prevents preservation of modified shared data.",
"trigger": "HP shutdown times out before acknowledgement.",
"workaround": "Keep a recoverable authoritative copy outside dirty HP cache; treat timed-out work as failed and reinitialize dependent queues.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/resource-controller.md"
]
},
{
"id": "memory-pad-exclusion",
"title": "QPI and OPI cannot operate together",
"impact": "The inactive memory window returns an error and its pads are disconnected.",
"trigger": "Accessing the inactive memory mode or attempting a live protocol change.",
"workaround": "Select the mode at boot before use; respect the sticky lock. A live handover is not supported.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"docs/lp-hp-architecture.md"
]
},
{
"id": "board-routes",
"title": "Generic FPGA routes do not qualify every interface",
"impact": "Dedicated USB2 ULPI and SDIO1 pads need board assignment and electrical/timing review.",
"trigger": "Assuming logical pads are FPGA ball or package-pin assignments.",
"workaround": "Supply board constraints, bank voltages, external devices and validated timing before enabling a physical route.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"fpga/README.md",
"publications/datasheets/sections/pins.typ"
]
},
{
"id": "apu-production",
"title": "APU MP3/KWS availability and qualification limits",
"impact": "WAV/FLAC code and image are implemented; this does not establish complete corpus, sustained real-time or physical qualification. MP3 remains a reserved trap entry; KWS RTL exists but PRODUCT defaults to EnableP7=0 and does not advertise KWS.",
"trigger": "Submitting MP3, assuming default KWS availability, or inferring full qualification from capability bits.",
"workaround": "Use advertised WAV/FLAC paths with a validated APUMC image and supported formats/rates. Treat KWS as gated development functionality until its complete qualification evidence is supplied.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"publications/datasheets/ips/apu.typ",
"rtl/ip/multimedia/apu_reg.sv"
]
},
{
"id": "rng-entropy",
"title": "Integrated RNG entropy is unqualified",
"impact": "Deterministic test data cannot supply production cryptographic entropy.",
"trigger": "Using the current entropy stream to generate secret keys or nonces.",
"workaround": "Keep diagnostic use separate; production entropy requires a reviewed physical source and qualification.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"publications/datasheets/ips/rng.typ",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "physical-ratings",
"title": "Physical operating limits are not characterized",
"impact": "Configuration clocks and behavioral models are not electrical or silicon ratings.",
"trigger": "Selecting board voltage, frequency, thermal or timing limits from RTL defaults.",
"workaround": "Use approved technology, macro, package and board reports; leave absent specifications TBD.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"physical/README.md",
"docs/pll-clock-control.md"
]
},
{
"id": "mpw-compatibility",
"title": "Legacy PRODUCT window is not an MPW selector",
"impact": "Legacy selection writes are rejected in PRODUCT.",
"trigger": "Calling selectable user-core/IP mutators on a fixed PRODUCT configuration.",
"workaround": "Detect mode/capabilities first and use fixed EXT-L/EXT-H APIs in PRODUCT.",
"applies_to": "Reviewed v0.4 PRODUCT snapshot; MPW differences are stated separately.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/user-ip.md"
]
},
{
"id": "jpeg-system-qualification",
"title": "JPEG native path lacks complete system qualification",
"impact": "The dedicated JPEG AXI path now has one normal read and one normal write credit at data-master slot 6, but its end-to-end producer/consumer workloads, contention behavior, cache ownership, and board performance have not been qualified.",
"trigger": "Claiming a complete JPEG system workload from source-level admission or standalone codec evidence.",
"workaround": "Treat the checked slot-6 admission path as bounded transport evidence only. Run an end-to-end workload with explicit source ordering, buffer ownership, error recovery, and platform evidence before making a system claim.",
"applies_to": "Reviewed PRODUCT source snapshot; static integration qualification boundary, not silicon measurement.",
"sources": [
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/top/axi4_data_crossbar.sv"
]
},
{
"id": "ext-l-rejected-base-write",
"title": "Rejected EXT-L base writes can change readable state",
"impact": "READ_BASE and WRITE_BASE next-state assignments are not gated by the KindExtH write-legal result; an EXT-L write can change those readbacks while returning PSLVERR.",
"trigger": "Writing READ_BASE or WRITE_BASE through the EXT-L register window.",
"workaround": "Treat these writes as invalid and avoid them. Preserve the slot fault/address when diagnosing an error; do not assume a rejected write rolls back state. EXT-L has no connected data master, so these local outputs do not grant an EXT-L DMA path.",
"applies_to": "Reviewed v0.4 PRODUCT source snapshot; static RTL observation, no new simulation or hardware test.",
"sources": [
"rtl/mini/top/extension_slot.sv",
"rtl/mini/top/extension_subsystem.sv"
]
},
{
"id": "lp-startup-psram-wait",
"title": "Generic LP startup has no PSRAM-ready deadline",
"impact": "Execution can remain before main and before the application writes TEST_STATUS.",
"trigger": "The generic CRT requests PSRAM initialization and PSRAM_STATUS.READY never becomes set.",
"workaround": "Confirm the selected startup/linker path, memory-pad selection and external memory readiness; use an external observer deadline. A returned application code cannot describe a stage that was never reached.",
"applies_to": "Reviewed generic LP CRT; dedicated debug and XPI-loader startups have separate initialization contracts.",
"sources": [
"crt/arch/riscv/startup.S",
"rtl/mini/mk/software.mk"
]
}
],
"programming": {
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/include/retrosoc/hal/i2c.h",
"crt/include/retrosoc/hal/i2s.h",
"crt/include/retrosoc/hal/timer.h",
"crt/include/retrosoc/hal/uart.h",
"crt/linker/ld2_all_sram.lds",
"crt/linker/ld2_psram.lds",
"crt/linker/ld2_sdram.lds",
"crt/linker/ld2_sram.lds",
"crt/src/hal/clint.c",
"crt/src/hal/dvp.c",
"crt/src/hal/i2c.c",
"crt/src/hal/i2c_math.c",
"crt/src/hal/i2s.c",
"crt/src/hal/i2s_math.c",
"crt/src/hal/timer.c",
"crt/src/hal/timer_math.c",
"crt/src/hal/uart.c",
"crt/src/hal/uart_math.c",
"docs/README.md",
"docs/axi4-interconnect.md",
"docs/ip/clint.md",
"docs/ip/dma.md",
"docs/ip/dvp.md",
"docs/ip/gpio.md",
"docs/ip/i2s.md",
"docs/ip/opipsram.md",
"docs/ip/psram.md",
"docs/ip/resource-controller.md",
"docs/ip/sdram.md",
"docs/ip/uart.md",
"docs/ip/xpi.md",
"publications/datasheets/system-reference.json",
"rtl/ip/multimedia/dvp_core.sv",
"rtl/ip/peripheral/dma_core.sv",
"rtl/ip/peripheral/dma_pkg.sv",
"rtl/ip/peripheral/dma_reg.sv",
"rtl/ip/serial/i2s_clkgen.sv",
"rtl/ip/serial/i2s_pkg.sv",
"rtl/ip/serial/uart_baudgen.sv",
"rtl/mini/integration/clock_reset_domains.json",
"rtl/mini/integration/soc_topology.json",
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/axi4_data_crossbar.sv",
"rtl/mini/top/axi4_downsizer_64to32.sv",
"rtl/mini/top/axi4_interconnect.sv",
"rtl/mini/top/axi4_upsizer_32to64.sv",
"rtl/mini/top/soc_data_plane.sv"
],
"dma_routes": [
{
"id": "software",
"sdk": "RS_DMA_REQUEST_SOFTWARE",
"rtl": "DMA_REQUEST_SOFTWARE",
"ips": [
"dma"
],
"label": "Software / MMIO clients",
"transport": "MM-to-MM; no peripheral pacing wire",
"channel": "Caller; WS2812 uses 3; HP boot uses 6",
"irq": null,
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": []
},
{
"id": "i2s_tx",
"sdk": "RS_DMA_REQUEST_I2S_TX",
"rtl": "DMA_REQUEST_I2S_TX",
"ips": [
"i2s"
],
"label": "I2S TX",
"transport": "MM-to-stream",
"channel": "3, serialized",
"irq": "i2s",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": ".i2s_tx_axis(u_dma_i2s_tx_axis_if)"
}
]
},
{
"id": "i2s_rx",
"sdk": "RS_DMA_REQUEST_I2S_RX",
"rtl": "DMA_REQUEST_I2S_RX",
"ips": [
"i2s"
],
"label": "I2S RX",
"transport": "Stream-to-MM",
"channel": "3, serialized",
"irq": "i2s",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": ".i2s_rx_axis(u_dma_i2s_rx_axis_if)"
}
]
},
{
"id": "xpi_tx",
"sdk": "RS_DMA_REQUEST_XPI_TX",
"rtl": "DMA_REQUEST_QSPI_TX",
"ips": [
"xpi"
],
"label": "XPI TX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "Caller-selected; bulk convention 3",
"irq": "xpi",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.qspi_tx_proc=~s_dma_xpi_tx_stall;"
}
]
},
{
"id": "xpi_rx",
"sdk": "RS_DMA_REQUEST_XPI_RX",
"rtl": "DMA_REQUEST_QSPI_RX",
"ips": [
"xpi"
],
"label": "XPI RX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "Caller-selected; bulk convention 3",
"irq": "xpi",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.qspi_rx_proc=~s_dma_xpi_rx_stall;"
}
]
},
{
"id": "uart_tx",
"sdk": "RS_DMA_REQUEST_UART_TX",
"rtl": "DMA_REQUEST_UART_TX",
"ips": [
"uart0"
],
"label": "UART0 TX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "0",
"irq": "uart0",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.uart_tx_proc=~s_dma_uart_tx_stall;"
}
]
},
{
"id": "uart_rx",
"sdk": "RS_DMA_REQUEST_UART_RX",
"rtl": "DMA_REQUEST_UART_RX",
"ips": [
"uart0"
],
"label": "UART0 RX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "0",
"irq": "uart0",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.uart_rx_proc=~s_dma_uart_rx_stall;"
}
]
},
{
"id": "i2c0_tx",
"sdk": "RS_DMA_REQUEST_I2C0_TX",
"rtl": "DMA_REQUEST_I2C0_TX",
"ips": [
"i2c"
],
"label": "I2C0 TX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "1",
"irq": "i2c0",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.i2c0_tx_proc=~s_dma_i2c0_tx_stall;"
}
]
},
{
"id": "i2c0_rx",
"sdk": "RS_DMA_REQUEST_I2C0_RX",
"rtl": "DMA_REQUEST_I2C0_RX",
"ips": [
"i2c"
],
"label": "I2C0 RX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "1",
"irq": "i2c0",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.i2c0_rx_proc=~s_dma_i2c0_rx_stall;"
}
]
},
{
"id": "i2c1_tx",
"sdk": "RS_DMA_REQUEST_I2C1_TX",
"rtl": "DMA_REQUEST_I2C1_TX",
"ips": [
"i2c"
],
"label": "I2C1 TX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "2",
"irq": "i2c1",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.i2c1_tx_proc=~s_dma_i2c1_tx_stall;"
}
]
},
{
"id": "i2c1_rx",
"sdk": "RS_DMA_REQUEST_I2C1_RX",
"rtl": "DMA_REQUEST_I2C1_RX",
"ips": [
"i2c"
],
"label": "I2C1 RX",
"transport": "Paced MM-to-MM via the peripheral data window",
"channel": "2",
"irq": "i2c1",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": "assign u_dma_req_if.i2c1_rx_proc=~s_dma_i2c1_rx_stall;"
}
]
},
{
"id": "dvp_rx",
"sdk": "RS_DMA_REQUEST_DVP_RX",
"rtl": "DMA_REQUEST_DVP_RX",
"ips": [
"dvp"
],
"label": "DVP capture",
"transport": "Stream-to-MM; full words only",
"channel": "3",
"irq": "dvp",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": ".dvp_rx_axis(u_dvp_rx_axis_if)"
}
]
},
{
"id": "crypto_in",
"sdk": "RS_DMA_REQUEST_CRYPTO_IN",
"rtl": "DMA_REQUEST_CRYPTO_IN",
"ips": [
"crypto"
],
"label": "Crypto input",
"transport": "MM-to-stream",
"channel": "4",
"irq": null,
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": ".crypto_in_axis(u_crypto_in_axis_if)"
}
]
},
{
"id": "crypto_out",
"sdk": "RS_DMA_REQUEST_CRYPTO_OUT",
"rtl": "DMA_REQUEST_CRYPTO_OUT",
"ips": [
"crypto"
],
"label": "Crypto output",
"transport": "Stream-to-MM",
"channel": "5",
"irq": null,
"sources": [
"rtl/ip/peripheral/dma_pkg.sv",
"crt/include/retrosoc/hal/dma.h",
"rtl/ip/peripheral/dma_core.sv",
"rtl/mini/top/apb4_periph.sv"
],
"bindings": [
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": ".crypto_out_axis(u_crypto_out_axis_if)"
}
]
}
],
"channels": [
{
"id": "uart0",
"symbol": "RS_DMA_CHANNEL_UART0",
"ips": [
"uart0"
],
"label": "UART0 helpers",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/src/hal/uart.c"
],
"bindings": [
{
"file": "crt/src/hal/uart.c",
"text": "rs_dma_configure(RS_DMA_CHANNEL_UART0"
}
]
},
{
"id": "i2c0",
"symbol": "RS_DMA_CHANNEL_I2C0",
"ips": [
"i2c"
],
"label": "I2C0 helpers",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/src/hal/i2c.c"
],
"bindings": [
{
"file": "crt/src/hal/i2c.c",
"text": "RS_DMA_CHANNEL_I2C0 : RS_DMA_CHANNEL_I2C1"
}
]
},
{
"id": "i2c1",
"symbol": "RS_DMA_CHANNEL_I2C1",
"ips": [
"i2c"
],
"label": "I2C1 helpers",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/src/hal/i2c.c"
],
"bindings": [
{
"file": "crt/src/hal/i2c.c",
"text": "RS_DMA_CHANNEL_I2C0 : RS_DMA_CHANNEL_I2C1"
}
]
},
{
"id": "bulk",
"symbol": "RS_DMA_CHANNEL_BULK",
"ips": [
"dvp",
"ws2812",
"i2s",
"xpi"
],
"label": "Shared bulk clients: DVP, WS2812; I2S/XPI convention",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/src/hal/dvp.c",
"crt/src/hal/ws2812.c",
"docs/ip/dma.md"
],
"bindings": [
{
"file": "crt/src/hal/dvp.c",
"text": "rs_dma_configure(RS_DMA_CHANNEL_BULK"
}
]
},
{
"id": "crypto_in",
"symbol": "RS_DMA_CHANNEL_CRYPTO_IN",
"ips": [
"crypto"
],
"label": "Crypto input",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/src/hal/crypto.c"
],
"bindings": [
{
"file": "crt/src/hal/crypto.c",
"text": "rs_dma_configure(RS_DMA_CHANNEL_CRYPTO_IN"
}
]
},
{
"id": "crypto_out",
"symbol": "RS_DMA_CHANNEL_CRYPTO_OUT",
"ips": [
"crypto"
],
"label": "Crypto output",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/src/hal/crypto.c"
],
"bindings": [
{
"file": "crt/src/hal/crypto.c",
"text": "rs_dma_configure(RS_DMA_CHANNEL_CRYPTO_OUT"
}
]
},
{
"id": "hp",
"symbol": "RS_DMA_CHANNEL_HP",
"ips": [
"dma"
],
"label": "HP boot loader",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"app/apps/hp_boot/main.c"
],
"bindings": [
{
"file": "app/apps/hp_boot/main.c",
"text": "rs_dma_submit_tcd(RS_DMA_CHANNEL_HP"
}
]
},
{
"id": "reserved",
"symbol": "RS_DMA_CHANNEL_RESERVED",
"ips": [
"dma"
],
"label": "Reserved; no application allocation",
"sources": [
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/dma_regs.h",
"crt/include/retrosoc/hal/dma_regs.h"
],
"bindings": [
{
"file": "crt/include/retrosoc/hal/dma_regs.h",
"text": "#define RS_DMA_CHANNEL_RESERVED 7U"
}
]
}
],
"engines": [
{
"id": "dma",
"ips": [
"dma"
],
"name": "Central DMA",
"master": "2",
"irq": "dma",
"hp_signal": "resource_irq_hp_i[0]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "usb2",
"ips": [
"usb2"
],
"name": "USB2 private DMA",
"master": "Gateway A (3)",
"irq": "usb2",
"hp_signal": "resource_irq_hp_i[1]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "sdio0",
"ips": [
"sdio0"
],
"name": "SDIO0 private DMA",
"master": "Gateway A (3)",
"irq": "sdio0",
"hp_signal": "resource_irq_hp_i[2]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "sdio1",
"ips": [
"sdio1"
],
"name": "SDIO1 private DMA",
"master": "Gateway B (4)",
"irq": "sdio1",
"hp_signal": "resource_irq_hp_i[3]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "spisd",
"ips": [
"spisd"
],
"name": "SPI-SD private DMA",
"master": "Gateway B (4)",
"irq": "spisd",
"hp_signal": "resource_irq_hp_i[4]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "jpeg",
"ips": [
"jpeg"
],
"name": "JPEG private DMA",
"master": "6; 1 read / 1 write credit; class 8",
"irq": "jpeg",
"hp_signal": "resource_irq_hp_i[5]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "apu",
"ips": [
"apu"
],
"name": "APU private DMA",
"master": "Gateway A (3)",
"irq": "apu",
"hp_signal": "resource_irq_hp_i[6]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "ext-h",
"ips": [
"ext-h"
],
"name": "EXT-H reference DMA",
"master": "7",
"irq": "extension_h",
"hp_signal": "ext_h_hp_irq_i",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/resource-controller.md"
]
},
{
"id": "ga2d",
"ips": [
"ga2d"
],
"name": "GA2D private 2D DMA",
"master": "8",
"irq": "ga2d",
"hp_signal": "resource_irq_hp_i[7]",
"sources": [
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/integration/soc_topology.json",
"docs/ip/ga2d.md"
]
}
],
"conflicts": [
{
"id": "qpi-opi",
"ips": [
"psram",
"opipsram"
],
"resource": "Shared memory pads",
"state": "Hardware exclusion",
"condition": "Select one memory-pad mode at boot; the inactive aperture returns an error.",
"sources": [
"docs/lp-hp-architecture.md",
"rtl/mini/top/memory_pad_mux.sv"
]
},
{
"id": "bulk-context",
"ips": [
"i2s",
"dvp",
"ws2812",
"xpi"
],
"resource": "Central DMA channel 3 convention",
"state": "Serialize / explicitly allocate",
"condition": "Convenience clients cannot overwrite an in-flight shared context. XPI accepts a caller-selected channel; changing it still requires ownership and endpoint checks.",
"sources": [
"docs/ip/dma.md",
"crt/src/hal/dvp.c",
"crt/src/hal/ws2812.c",
"crt/src/hal/xpi.c"
]
},
{
"id": "stream-endpoint",
"ips": [
"i2s",
"dvp",
"crypto"
],
"resource": "One active DMA endpoint selector",
"state": "Hardware exclusion",
"condition": "DMA rejects another active channel targeting the same protected stream endpoint. A different channel number alone does not permit concurrent ownership.",
"sources": [
"rtl/ip/peripheral/dma_core.sv"
]
},
{
"id": "i2s-apu",
"ips": [
"i2s",
"apu",
"dma"
],
"resource": "I2S stream-switch producer/consumer",
"state": "Mode-dependent",
"condition": "Check the APU/I2S stream-switch selection and exclusive endpoint ownership. Supported WAV/FLAC TX uses the selected path; KWS RX exists but is gated off in the default PRODUCT build.",
"sources": [
"rtl/ip/multimedia/apb4_apu.sv",
"rtl/mini/top/apb4_periph.sv",
"docs/ip/apu.md"
]
},
{
"id": "gateway-a",
"ips": [
"usb2",
"sdio0",
"apu"
],
"resource": "I/O gateway A and resource blocking",
"state": "Shared bandwidth / drain",
"condition": "These private masters share a gateway; ownership and lifecycle gates can conservatively block related traffic.",
"sources": [
"rtl/mini/top/soc_data_plane.sv",
"docs/ip/resource-controller.md"
]
},
{
"id": "gateway-b",
"ips": [
"sdio1",
"spisd"
],
"resource": "I/O gateway B",
"state": "Shared bandwidth / drain",
"condition": "Separate controllers still share the admission path and memory targets.",
"sources": [
"rtl/mini/top/soc_data_plane.sv"
]
},
{
"id": "gpio-alt",
"ips": [
"gpio"
],
"resource": "GPIO alternate functions",
"state": "Pin-dependent exclusion",
"condition": "Use the generated GPIO ALT0/ALT1 matrix. A pin has one selected output/enable owner; different functions in one row cannot be enabled independently.",
"sources": [
"rtl/mini/integration/soc_topology.json",
"docs/ip/gpio.md"
]
},
{
"id": "clock-change",
"ips": [
"uart0",
"i2c",
"timer",
"dma"
],
"resource": "Changing functional clock",
"state": "Quiesce / reconfigure",
"condition": "Stop affected transfers before changing their source/divider. Recompute rates after the transition; stable audio/memory domains have separate rules.",
"sources": [
"docs/pll-clock-control.md",
"rtl/mini/integration/clock_reset_domains.json"
]
},
{
"id": "memory-contention",
"ips": [
"dma",
"usb2",
"sdio0",
"sdio1",
"spisd",
"jpeg",
"apu",
"ext-h"
],
"resource": "Shared memory targets",
"state": "Bandwidth contention",
"condition": "Allowed routes are not a simultaneous throughput guarantee. Native JPEG slot 6 has one read and one write credit at class 8; target readiness and arbitration still bound progress.",
"sources": [
"rtl/mini/top/axi4_data_crossbar.sv",
"rtl/mini/top/soc_data_plane.sv"
]
}
],
"devices": [
{
"id": "xpi-winbond",
"ips": [
"xpi"
],
"name": "Winbond W25Q128JV model",
"protocol": "SDR SPI/QSPI; programmed slot/LUT",
"geometry": "Reset profile uses a 16 MiB NSS0 device and boot alias.",
"setup": "Match command/address/mode/dummy phases, status polling, page/erase bounds and slot device size.",
"model": "Pin-level model source and directed tests are present; fast-flash model covers a narrower read path.",
"board": "Not established",
"silicon": "Not established",
"reports": [],
"sources": [
"rtl/model/w25q128jvxim.sv",
"rtl/mini/dv/verilator/rtl/xpi_fast_flash_model.sv",
"tests/test_xpi_io.py",
"docs/ip/xpi.md"
]
},
{
"id": "qpi-esp",
"ips": [
"psram"
],
"name": "ESP-PSRAM64H",
"protocol": "Device-specific SDR SPI/QPI",
"geometry": "Four 8 MiB devices; 32 MiB decoded window.",
"setup": "Perform reset/ID/enter-QPI sequence; obey device page and chip boundaries.",
"model": "ESP_PSRAM64H model and directed tests present.",
"board": "Not established",
"silicon": "Not established",
"reports": [],
"sources": [
"rtl/mini/dv/model/ESP_PSRAM64H.sv",
"tests/test_psram.py",
"docs/ip/psram.md"
]
},
{
"id": "sdram-geometry",
"ips": [
"sdram"
],
"name": "Fixed-geometry SDR SDRAM",
"protocol": "x16 SDR interface",
"geometry": "2 bank bits, 13 row bits, 10 column bits; 64 MiB addressability.",
"setup": "Program initialization, refresh and timing cycles for the actual part and memory clock. Geometry alone does not qualify a supplier part.",
"model": "Directed SDRAM behavioral tests present; no specific board part qualification attached.",
"board": "Not established",
"silicon": "Not established",
"reports": [],
"sources": [
"docs/ip/sdram.md",
"rtl/ip/memory/sdram_pkg.sv",
"tests/test_sdram.py"
]
},
{
"id": "opi-profile",
"ips": [
"opipsram"
],
"name": "OPI profile; specific part not qualified",
"protocol": "Octal DDR command/address profile",
"geometry": "Configured device size must fit the aperture and profile.",
"setup": "Select and initialize the OPI profile; do not reuse HyperBus command encoding.",
"model": "Controller/protocol test source present.",
"board": "Not established",
"silicon": "Not established",
"reports": [],
"sources": [
"docs/ip/opipsram.md",
"rtl/ip/memory/opipsram_protocol.sv",
"tests/test_opipsram.py"
]
},
{
"id": "hyper-profile",
"ips": [
"opipsram"
],
"name": "Single-clock HyperBus-style profile",
"protocol": "Modified single-clock transaction profile",
"geometry": "Device, voltage and timing compatibility remain unqualified.",
"setup": "Select the profile before INIT and obey the profile lock/reset contract; generic HyperBus compatibility is not claimed.",
"model": "Prototype protocol test source present.",
"board": "Not established",
"silicon": "Not established",
"reports": [],
"sources": [
"docs/ip/opipsram.md",
"rtl/ip/memory/opipsram_protocol.sv",
"tests/test_opipsram.py"
]
}
],
"glossary": [
{
"id": "aon",
"term": "AON",
"meaning": "Always-on control clock/reset domain; not proof of a separate supply or retention island.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "lp",
"term": "LP",
"meaning": "Hazard3 root-management hart.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "hp",
"term": "HP",
"meaning": "VexiiRiscv application hart; asymmetric Linux platform.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "pclk",
"term": "PCLK",
"meaning": "Peripheral register/engine clock domain where specified.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "mmio",
"term": "MMIO",
"meaning": "Memory-mapped I/O with register-specific side effects and attributes.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "axi4",
"term": "AXI4",
"meaning": "Five-channel memory transaction protocol; the implemented subset is path-dependent.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "apb4",
"term": "APB4",
"meaning": "Peripheral register protocol, including byte strobes and error response.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "cbo",
"term": "CBO / Zicbom",
"meaning": "Cache-block maintenance operation / RISC-V extension; not hardware coherency.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "tcd",
"term": "TCD",
"meaning": "Central DMA transfer-control descriptor; the published structure is 64 bytes.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "irq",
"term": "IRQ / PLIC",
"meaning": "Interrupt request / HP priority and claim-complete controller; LP bit and HP source are different numbers.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "pio",
"term": "PIO",
"meaning": "Programmed I/O through data registers; may have FIFO pop/push side effects.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "tkeep",
"term": "TKEEP / TSTRB",
"meaning": "AXI4-Stream byte qualification; current central DMA requires full-word stream beats.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "tlast",
"term": "TLAST / TUSER",
"meaning": "Stream boundary and sideband metadata; their meaning depends on the producer.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "cdc",
"term": "CDC / warm flush",
"meaning": "Clock-domain crossing / coordinated clearing and epoch change for in-flight paths.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "dre",
"term": "DRE",
"meaning": "Data realignment engine; not supplied by the central DMA MVP.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "vma",
"term": "VMA / LMA",
"meaning": "Execution/data address / load-image address in the linker layout.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "kib",
"term": "KiB / MiB",
"meaning": "Binary units: 1024 and 1048576 bytes. kHz/MHz are decimal frequency units.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
},
{
"id": "tbd",
"term": "TBD",
"meaning": "No reviewed specification or result is supplied; not zero and not unlimited.",
"sources": [
"docs/lp-hp-architecture.md",
"docs/ip/dma.md",
"crt/linker/ld2_all_sram.lds"
]
}
]
},
"product_details": {
"cpu": {
"lp_fields": [
"BREAKPOINT_TRIGGERS",
"CSR_COUNTER",
"CSR_M_MANDATORY",
"DEBUG_SUPPORT",
"EXTENSION_A",
"EXTENSION_C",
"EXTENSION_M",
"MTVEC_INIT",
"PMP_REGIONS",
"RESET_VECTOR",
"U_MODE"
],
"hp_fields": [
"additionalPerformanceCounters",
"asidWidth",
"decoders",
"fetchL1Enable",
"fetchL1Sets",
"fetchL1Ways",
"fetchMemDataWidthMin",
"lanes",
"lsuL1Enable",
"lsuL1Sets",
"lsuL1Ways",
"lsuMemDataWidthMin",
"physicalWidth",
"pmpParam.granularity",
"pmpParam.pmpSize",
"privParam.debugTriggers",
"privParam.withDebug",
"privParam.withRdTime",
"resetVector",
"xlen"
]
},
"reset": [
{
"id": "clock-root",
"ips": [
"rcu"
],
"label": "LP / peripheral clock selection",
"value_class": "Configured",
"initial": "LP mode resets to 0 (REF24). PCLK divider state is zero, selecting /1 after its reset/configuration path settles.",
"prerequisites": "External reset and reference clocks must satisfy board conditions; local reset must be released.",
"action": "Read clock status/capability before deriving peripheral timing.",
"observation": "Configured rate and observed ready/fault status; not a maximum operating limit.",
"sources": [
"rtl/mini/top/clock_config_controller.sv",
"rtl/mini/top/soc_clock_reset_subsystem.sv",
"rtl/managed/clusterip/common/rtl/utils/register.sv"
],
"bindings": [
{
"file": "rtl/mini/top/clock_config_controller.sv",
"kind": "snippet",
"text": ".RESET_VAL (2'd0)\n ) u_lp_mode_dffrc"
},
{
"file": "rtl/mini/top/clock_config_controller.sv",
"kind": "snippet",
"text": ") u_pclk_div_dffr ("
},
{
"file": "rtl/managed/clusterip/common/rtl/utils/register.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "dat_o",
"value": "'0",
"module": "dffr"
}
]
},
{
"id": "memory-pad",
"ips": [
"rcu",
"psram",
"opipsram"
],
"label": "Memory pad mode",
"value_class": "Configured",
"initial": "MEM_PAD_MODE reset encoding is 1 (QPI); the mode lock resets clear.",
"prerequisites": "The selected external device and its interface clock/reset must be ready.",
"action": "Select the required boot-time mode before memory use; check the lock.",
"observation": "Inactive aperture errors are expected; mode is not a fitted-device probe.",
"sources": [
"rtl/mini/top/clock_config_controller.sv",
"docs/lp-hp-architecture.md",
"rtl/managed/clusterip/common/rtl/utils/register.sv"
],
"bindings": [
{
"file": "rtl/mini/top/clock_config_controller.sv",
"kind": "snippet",
"text": ".RESET_VAL (2'd1)\n ) u_mem_pad_mode_dffrc"
},
{
"file": "rtl/mini/top/clock_config_controller.sv",
"kind": "snippet",
"text": ") u_mem_pad_lock_dffr ("
}
]
},
{
"id": "hp-held",
"ips": [
"sysctrl"
],
"label": "HP lifecycle",
"value_class": "Fixed",
"initial": "Controller state Held; HP release, flush and forced-fault state clear.",
"prerequisites": "Root clocks and management MMIO are available.",
"action": "Prepare memory/image and use the controlled release sequence.",
"observation": "Check requested and actual release/reset status; values can change once a request is accepted.",
"sources": [
"rtl/mini/top/hp_lifecycle_controller.sv",
"crt/src/hal/sysctrl.c"
],
"bindings": [
{
"file": "rtl/mini/top/hp_lifecycle_controller.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_state_q",
"value": "Held"
},
{
"file": "rtl/mini/top/hp_lifecycle_controller.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_hp_release_q",
"value": "1'b0"
},
{
"file": "rtl/mini/top/hp_lifecycle_controller.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_forced_fault_q",
"value": "1'b0"
}
]
},
{
"id": "resource-owner",
"ips": [
"resource"
],
"label": "Resource owners and locks",
"value_class": "Fixed",
"initial": "OWNER flops reset to 0 (LP); owner lock, quiesce and resource-reset request clear.",
"prerequisites": "PCLK/local reset and the producer/engine status path must be available.",
"action": "Inspect owner, busy/idle and pending status before handoff.",
"observation": "Root ownership is not an independent power/reset guarantee for every engine.",
"sources": [
"rtl/mini/top/resource_controller.sv",
"docs/ip/resource-controller.md"
],
"bindings": [
{
"file": "rtl/mini/top/resource_controller.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_owner_q",
"value": "'0"
},
{
"file": "rtl/mini/top/resource_controller.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_owner_lock_q",
"value": "'0"
},
{
"file": "rtl/mini/top/resource_controller.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_reset_q",
"value": "'0"
}
]
},
{
"id": "irq-observation",
"ips": [
"resource"
],
"label": "Interrupt observation",
"value_class": "Dynamic",
"initial": "IRQ outputs depend on peripheral causes, current owner and resource-reset request. A clear initial enable/status can change after an event.",
"prerequisites": "Know each peripheral reset/enable contract and the selected owner route.",
"action": "Install handlers, clear documented stale events, then enable the intended route.",
"observation": "CONTROL.RESET masks owner routes; do not confuse it with an independent controller-wide IRQ enable.",
"sources": [
"rtl/mini/top/resource_controller.sv"
],
"bindings": [
{
"file": "rtl/mini/top/resource_controller.sv",
"kind": "snippet",
"text": "irq_lp_o[resource] = irq_i[resource] && (s_owner_q[resource] == OwnerLp) && !s_reset_q[resource];"
}
]
},
{
"id": "dma-initial",
"ips": [
"dma"
],
"label": "Central DMA register context",
"value_class": "Fixed",
"initial": "Channel configuration, byte count, descriptor head/count and IRQ/event enables reset to zero.",
"prerequisites": "PCLK/register path and selected memory/endpoint are available.",
"action": "Probe capability; configure a legal idle context before START.",
"observation": "Zero reset configuration is not a ready-to-start transfer; the core validates width, count, alignment and endpoint.",
"sources": [
"rtl/ip/peripheral/dma_reg.sv",
"rtl/ip/peripheral/dma_core.sv"
],
"bindings": [
{
"file": "rtl/ip/peripheral/dma_reg.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_ch_cfg_q",
"value": "'0"
},
{
"file": "rtl/ip/peripheral/dma_reg.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_irq_en_q",
"value": "'0"
},
{
"file": "rtl/ip/peripheral/dma_reg.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "s_byte_count_q",
"value": "'0"
}
]
},
{
"id": "gpio-initial",
"ips": [
"gpio"
],
"label": "GPIO digital control state",
"value_class": "Fixed",
"initial": "Output data/enable, alternate-function selection and interrupt-enable state use zero-reset Common flops.",
"prerequisites": "Read the selected PDK pad capability and actual board connection.",
"action": "Establish inactive output state, configure ownership/function, then enable the output or interrupt.",
"observation": "An input pad is not guaranteed low; digital reset values do not specify voltage, pull strength or package pins.",
"sources": [
"rtl/ip/peripheral/gpio_reg.sv",
"rtl/managed/clusterip/common/rtl/utils/register.sv"
],
"bindings": [
{
"file": "rtl/ip/peripheral/gpio_reg.sv",
"kind": "snippet",
"text": ") u_output_enable_dffer ("
},
{
"file": "rtl/ip/peripheral/gpio_reg.sv",
"kind": "snippet",
"text": ") u_alt_enable_dffer ("
},
{
"file": "rtl/ip/peripheral/gpio_reg.sv",
"kind": "snippet",
"text": ") u_intr_enable_dffer ("
},
{
"file": "rtl/managed/clusterip/common/rtl/utils/register.sv",
"kind": "reset",
"signal": "rst_n_i",
"state": "dat_o",
"value": "'0",
"module": "dffer"
}
]
},
{
"id": "external-memory",
"ips": [
"sdram",
"psram",
"opipsram",
"xpi"
],
"label": "External-memory initialization",
"value_class": "Dynamic",
"initial": "Resetting a controller does not establish a populated, initialized and electrically valid external device.",
"prerequisites": "Correct device/protocol, clocks, pins and timing settings.",
"action": "Follow the controller initialization/probe sequence and wait with its defined timeout.",
"observation": "Use READY/INIT/error and ID where applicable; an address aperture alone proves no device presence.",
"sources": [
"docs/ip/sdram.md",
"docs/ip/psram.md",
"docs/ip/opipsram.md",
"docs/ip/xpi.md"
],
"bindings": []
},
{
"id": "memory-content",
"ips": [
"sram"
],
"label": "Memory contents and software startup",
"value_class": "Input-dependent",
"initial": "No universal SRAM/DRAM retention or reset-to-zero content guarantee is published.",
"prerequisites": "The selected memory implementation and loader/linker contract.",
"action": "Initialize software data/BSS and owned buffers before use.",
"observation": "Do not interpret a successful register reset as a memory scrub.",
"sources": [
"physical/README.md",
"crt/linker/ld2_all_sram.lds"
],
"bindings": []
},
{
"id": "time-observation",
"ips": [
"clint",
"rtc"
],
"label": "Counters and time sources",
"value_class": "Dynamic",
"initial": "Counters and status can advance as soon as the relevant clock/reset/enable conditions permit.",
"prerequisites": "Known timebase and the IP-specific coherent read/snapshot sequence.",
"action": "Read a bounded snapshot and establish the software epoch.",
"observation": "A later software read need not equal the reset assignment.",
"sources": [
"crt/src/hal/clint.c",
"docs/ip/clint.md"
],
"bindings": []
}
],
"interfaces": [
{
"id": "uart",
"ips": [
"uart0",
"uart1"
],
"title": "UART0 / UART1",
"role": "Asynchronous TX/RX",
"modes": "5-8 data bits, parity/break and fractional baud; UART0 has the documented flow-control/DMA route.",
"excluded": "UART1 has no connected DMA or RTS/CTS path; unlisted higher-level serial protocols are not implied.",
"software": "LP HAL plus the indexed HP SBI console path; native driver status is separate.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/uart.md",
"publications/datasheets/features.json",
"rtl/ip/serial/uart_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"64-byte TX and RX FIFOs; fractional baud-rate generator.\""
}
]
},
{
"id": "i2c",
"ips": [
"i2c"
],
"title": "I2C0 / I2C1",
"role": "Bus controller",
"modes": "7/10-bit addressing, repeated START, clock stretching, arbitration/error handling and paced DMA.",
"excluded": "Target role and complete SMBus/PMBus protocol support are not advertised by the current controller contract.",
"software": "HAL timing helpers and transactions; electrical mode qualification remains board/device dependent.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/i2c.md",
"publications/datasheets/features.json",
"rtl/ip/serial/i2c_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Two controller instances with 7-bit and 10-bit addressing.\""
}
]
},
{
"id": "i2s",
"ips": [
"i2s"
],
"title": "I2S",
"role": "Stereo master TX/RX",
"modes": "16/24-bit samples; 48/96 kHz presets and exact programmable clocks; PIO and 32-bit streams.",
"excluded": "No slave, TDM or PDM mode; no automatic sample-rate conversion.",
"software": "HAL configuration and sample helpers; observe PIO/stream exclusion and packing.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/i2s.md",
"publications/datasheets/features.json",
"rtl/ip/serial/i2s_pkg.sv",
"rtl/ip/serial/i2s_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Stereo master TX/RX with independent audio clock.\""
}
]
},
{
"id": "ps2",
"ips": [
"ps2"
],
"title": "PS/2",
"role": "Bidirectional host",
"modes": "Host command/receive path, open-drain routing and bounded error/recovery status.",
"excluded": "A PS/2 device-emulation role or arbitrary serial protocol is not implied.",
"software": "Use the host HAL with approved pull-ups and pin routing.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"publications/datasheets/features.json",
"rtl/managed/clusterip/ps2/doc/datasheet.md",
"rtl/managed/clusterip/ps2/rtl/ps2_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Bidirectional open-drain host interface.\""
}
]
},
{
"id": "ws2812",
"ips": [
"ws2812"
],
"title": "WS2812",
"role": "Transmit engine",
"modes": "24-bit GRB words, programmable timing and completion/underflow behavior.",
"excluded": "RGBW or other LED protocol formats are not advertised as equivalent modes.",
"software": "PIO/software-paced DMA helper; select timing from the actual clock and LED requirement.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/ws2812.md",
"publications/datasheets/features.json",
"rtl/ip/serial/ws2812_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"24-bit GRB transmission on one GPIO alternate function.\""
}
]
},
{
"id": "spisd",
"ips": [
"spisd"
],
"title": "SPI-SD",
"role": "SD card SPI host",
"modes": "SPI-mode command/data transfer and private DMA.",
"excluded": "Native SD bus and SDIO I/O-function operation are not supplied by the SPI-SD interface.",
"software": "Use its dedicated card/command HAL rather than SDIO register sequences.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/spisd.md",
"publications/datasheets/features.json",
"rtl/ip/storage/spisd_pkg.sv",
"rtl/ip/storage/spisd_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"SD card SPI-mode command/data host.\""
}
]
},
{
"id": "sdio",
"ips": [
"sdio0",
"sdio1"
],
"title": "SD/SDIO",
"role": "Native 1/4-bit SDR host",
"modes": "SD Memory v2 SDSC/SDHC and SDIO v2 CMD5/CMD52/CMD53 foundation; CRC, PIO and DMA.",
"excluded": "No UHS, DDR, 1.8 V switching, 8-bit bus, MMC/eMMC, tuning/DLL or CQE; hot-remove and combo-card policy are unsupported.",
"software": "Initialization, capabilities and speed selection remain software sequenced.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/sdio.md",
"publications/datasheets/features.json",
"rtl/ip/storage/sdio_pkg.sv",
"rtl/ip/storage/sdio_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Native one-bit/four-bit SDR operation.\""
}
]
},
{
"id": "usb2",
"ips": [
"usb2"
],
"title": "USB2",
"role": "Digital dual-role controller",
"modes": "External ULPI interface; control/bulk/interrupt and single-transaction isochronous paths under the documented role policy.",
"excluded": "No integrated analog PHY; high-bandwidth isochronous and HNP/SRP are outside the current scope.",
"software": "DCD/HCD primitives and descriptor handling do not imply a complete class stack or USB compliance certificate.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/usb2.md",
"publications/datasheets/features.json",
"rtl/ip/usb/usb2_pkg.sv",
"rtl/ip/usb/usb2_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Dual-role digital controller with external 8-bit ULPI PHY.\""
}
]
},
{
"id": "xpi",
"ips": [
"xpi"
],
"title": "XPI",
"role": "Programmable SDR serial controller",
"modes": "Single/dual/quad data phases, LUT, indirect command/polling and mapped read path.",
"excluded": "No DDR/DQS extension or arbitrary memory-mapped NOR writes.",
"software": "Use reviewed slot/LUT/device settings; erase/program use the indirect path.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/xpi.md",
"publications/datasheets/features.json",
"rtl/ip/storage/xpi_pkg.sv",
"rtl/ip/storage/xpi_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Four chip-select slots and 16 programmable LUT sequences.\""
}
]
},
{
"id": "qpi",
"ips": [
"psram"
],
"title": "QPI PSRAM",
"role": "Device-specific SDR controller",
"modes": "ESP-PSRAM64H SPI/QPI initialization and mapped data operation.",
"excluded": "Not a generic controller for every QSPI RAM; shared-pad exclusion applies.",
"software": "Probe and initialize each enabled device with the documented recovery sequence.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/psram.md",
"publications/datasheets/features.json",
"rtl/ip/memory/psram_pkg.sv",
"rtl/ip/memory/psram_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Four ESP-PSRAM64H devices addressable through a 32 MiB window.\""
}
]
},
{
"id": "opi",
"ips": [
"opipsram"
],
"title": "OPI / HyperBus-style",
"role": "Boot/profile-selected prototype",
"modes": "Octal DDR profile or the modified single-clock HyperBus-style profile.",
"excluded": "No live protocol switch or generic commercial HyperBus compatibility claim.",
"software": "Protocol encoding, latency and a specific physical device require separate review.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/opipsram.md",
"publications/datasheets/features.json",
"rtl/ip/memory/opipsram_pkg.sv",
"rtl/ip/memory/opipsram_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"One octal DDR memory interface and one selected protocol profile.\""
}
]
},
{
"id": "sdram",
"ips": [
"sdram"
],
"title": "SDRAM",
"role": "x16 SDR controller",
"modes": "Fixed geometry, bank tracking, native bursts, initialization/refresh and programmable cycle timings.",
"excluded": "DDR/LPDDR and arbitrary geometries are not supported by this interface.",
"software": "Match the controller geometry and timing to the selected external component.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/sdram.md",
"publications/datasheets/features.json",
"rtl/ip/memory/sdram_pkg.sv",
"rtl/ip/memory/sdram_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Fixed 64 MiB, x16 SDR geometry with bank/row tracking.\""
}
]
},
{
"id": "dvp",
"ips": [
"dvp"
],
"title": "DVP",
"role": "8-bit parallel camera input",
"modes": "RGB565/YUV422 byte input, explicit sync, crop/snapshot and word-packed stream output.",
"excluded": "No MIPI CSI receiver or automatic colorspace conversion; odd-pixel line DMA is unsupported.",
"software": "Sensor byte order and sync configuration must match the capture and consumer layout.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/dvp.md",
"publications/datasheets/features.json",
"rtl/ip/multimedia/dvp_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"8-bit parallel RGB565/YUV422 capture.\""
}
]
},
{
"id": "jpeg",
"ips": [
"jpeg"
],
"title": "JPEG",
"role": "Baseline sequential codec",
"modes": "8-bit SOF0 encode/decode and the indexed raster formats; modes are mutually exclusive.",
"excluded": "No progressive/lossless/arithmetic/10-12-bit modes. Native SoC DMA admission is currently blocked at slot 6.",
"software": "Standalone codec/register behavior is distinct from end-to-end SoC payload availability.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/jpeg.md",
"publications/datasheets/features.json",
"rtl/ip/multimedia/jpeg_pkg.sv",
"rtl/ip/multimedia/jpeg_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"8-bit Baseline Sequential JPEG encode or decode.\""
}
]
},
{
"id": "apu",
"ips": [
"apu"
],
"title": "APU",
"role": "Coreless control/transport subsystem",
"modes": "Register/transport and bounded development codec paths described in the IP chapter.",
"excluded": "MP3 is not supported. KWS is implemented as a gated development path and remains disabled/unadvertised by default. No generic codec or full corpus qualification is implied.",
"software": "A HAL, microcode format or test source does not establish an enabled production audio service.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"docs/ip/apu.md",
"publications/datasheets/features.json",
"rtl/ip/multimedia/apu_reg.sv"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Coreless microcode sequencer with private DMA and local storage.\""
}
]
},
{
"id": "ga2d",
"ips": [
"ga2d"
],
"title": "GA2D",
"role": "Direct 2D color-surface processing",
"modes": "P5 FILL, COPY, CONVERT, opaque BLEND, A8 foreground masks and exact background/destination in-place blending.",
"software": "LP HAL and directed firmware scenarios; no native Linux graphics driver.",
"excluded": "No descriptors, job queue, scaling/rotation, transparent-background or premultiplied-alpha blend, YUV/CLUT or rendering API.",
"evidence": "Source-level subset; no compliance report attached",
"sources": [
"rtl/ip/multimedia/ga2d_define.svh",
"rtl/ip/multimedia/ga2d_core.sv",
"crt/include/retrosoc/hal/ga2d.h"
],
"bindings": [
{
"file": "rtl/ip/multimedia/ga2d_define.svh",
"kind": "snippet",
"text": "`define APB4_GA2D__CAPABILITY_P5 32'h0000_07ff"
}
]
}
],
"formats": [
{
"id": "dvp-word",
"ips": [
"dvp"
],
"title": "DVP RGB565/YUV422 stream",
"layout": "Two 16-bit pixels occupy a 32-bit word; sensor byte order and FORMAT swap controls determine the pixel value.",
"boundary": "TUSER marks frame start; TLAST marks line end. Odd width yields a partial last word, not a full-word DMA beat.",
"sources": [
"rtl/ip/multimedia/dvp_core.sv",
"docs/ip/dvp.md"
],
"bindings": [
{
"file": "rtl/ip/multimedia/dvp_core.sv",
"kind": "snippet",
"text": "s_first_word_q, s_last_pixel, 4'b1111, 4'b1111, s_pixel_word, s_word_q"
}
]
},
{
"id": "i2s16",
"ips": [
"i2s"
],
"title": "I2S 16-bit stereo words",
"layout": "Older sample in bits 15:0; newer sample in bits 31:16.",
"boundary": "One word carries two samples; channel/sample ordering must match the selected playback/capture convention.",
"sources": [
"crt/src/hal/i2s_math.c"
],
"bindings": [
{
"file": "crt/src/hal/i2s_math.c",
"kind": "snippet",
"text": "return ((uint32_t)second << 16) | first;"
}
]
},
{
"id": "i2s24",
"ips": [
"i2s"
],
"title": "I2S 24-bit sample words",
"layout": "One sample in bits 23:0 of a 32-bit container.",
"boundary": "Packed three-byte files require conversion into word containers; no implicit rate conversion.",
"sources": [
"crt/src/hal/i2s_math.c",
"docs/ip/i2s.md"
],
"bindings": [
{
"file": "docs/ip/i2s.md",
"kind": "snippet",
"text": "24-bit mode places one sample\nin `[23:0]`."
}
]
},
{
"id": "jpeg-gray",
"ips": [
"jpeg"
],
"title": "JPEG raster GRAY8",
"layout": "One 8-bit grayscale sample per pixel.",
"boundary": "Stride and job geometry are explicit; no automatic expansion to a different raster format.",
"sources": [
"docs/ip/jpeg.md",
"rtl/ip/multimedia/jpeg_reg.sv"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "`GRAY8`, `RGB565`, `RGB888`, `YUYV422`, and two-plane `NV12`"
}
]
},
{
"id": "jpeg-rgb565",
"ips": [
"jpeg"
],
"title": "JPEG raster RGB565",
"layout": "Little-endian 16-bit rrrrrggg gggbbbbb.",
"boundary": "Check camera byte order before consuming the same named format.",
"sources": [
"docs/ip/jpeg.md",
"rtl/ip/multimedia/jpeg_reg.sv"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "RGB565 words are little-endian `rrrrrggg gggbbbbb`."
}
]
},
{
"id": "jpeg-rgb888",
"ips": [
"jpeg"
],
"title": "JPEG raster RGB888",
"layout": "Bytes R, G, B in order.",
"boundary": "A 32-bit padded RGB layout is not identical to packed RGB888.",
"sources": [
"docs/ip/jpeg.md",
"rtl/ip/multimedia/jpeg_reg.sv"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "RGB888 byte order is R,\n G, B."
}
]
},
{
"id": "jpeg-yuyv",
"ips": [
"jpeg"
],
"title": "JPEG raster YUYV422",
"layout": "Bytes Y0, Cb, Y1, Cr.",
"boundary": "A generic YUV422 label does not select UYVY/YVYU or another byte order.",
"sources": [
"docs/ip/jpeg.md",
"rtl/ip/multimedia/jpeg_reg.sv"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "YUYV is Y0, Cb, Y1, Cr."
}
]
},
{
"id": "jpeg-nv12",
"ips": [
"jpeg"
],
"title": "JPEG raster NV12",
"layout": "Two planes; plane 1 contains interleaved Cb/Cr pairs.",
"boundary": "Use the prescribed byte strides and plane addresses; I420/YV12 are not equivalent.",
"sources": [
"docs/ip/jpeg.md",
"rtl/ip/multimedia/jpeg_reg.sv"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "NV12 plane 1 contains interleaved Cb/Cr pairs."
}
]
}
],
"interoperability": [
{
"id": "dvp-jpeg-rgb",
"ips": [
"dvp",
"jpeg"
],
"title": "DVP RGB565 -> memory -> JPEG",
"classification": "Conditional",
"condition": "Even-width word packing can describe compatible RGB565 storage only after byte-order/stride checks. Slot-6 admission is bounded to one read and one write; the end-to-end DVP-to-JPEG workload remains unqualified.",
"blockers": [],
"sources": [
"rtl/ip/multimedia/dvp_core.sv",
"docs/ip/jpeg.md",
"rtl/mini/top/axi4_data_crossbar.sv"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "RGB565 words are little-endian `rrrrrggg gggbbbbb`."
}
]
},
{
"id": "dvp-jpeg-yuv",
"ips": [
"dvp",
"jpeg"
],
"title": "DVP YUV422 -> memory -> JPEG YUYV",
"classification": "Conditional",
"condition": "Confirm Y0/Cb/Y1/Cr order; otherwise software rearrangement is required. Format agreement and bounded slot-6 admission do not qualify an end-to-end DVP-to-JPEG workload.",
"blockers": [],
"sources": [
"rtl/ip/multimedia/dvp_core.sv",
"docs/ip/jpeg.md"
],
"bindings": [
{
"file": "docs/ip/jpeg.md",
"kind": "snippet",
"text": "YUYV is Y0, Cb, Y1, Cr."
}
]
},
{
"id": "pcm16-i2s",
"ips": [
"dma",
"i2s"
],
"title": "Software stereo16 -> DMA -> I2S",
"classification": "Format-compatible",
"condition": "Use the defined two-samples-per-word representation, full-word length, correct sample rate and exclusive endpoint/buffer ownership. Board/driver qualification is separate.",
"blockers": [],
"sources": [
"crt/src/hal/i2s_math.c",
"docs/ip/i2s.md",
"rtl/ip/peripheral/dma_core.sv"
],
"bindings": [
{
"file": "crt/src/hal/i2s_math.c",
"kind": "snippet",
"text": "return ((uint32_t)second << 16) | first;"
}
]
},
{
"id": "pcm24-i2s",
"ips": [
"dma",
"i2s"
],
"title": "Packed 24-bit file bytes -> I2S",
"classification": "Conversion required",
"condition": "Expand each three-byte sample into the low 24 bits of a 32-bit word; preserve sample/channel order and the configured rate.",
"blockers": [],
"sources": [
"docs/ip/i2s.md",
"crt/src/hal/i2s_math.c"
],
"bindings": [
{
"file": "docs/ip/i2s.md",
"kind": "snippet",
"text": "24-bit mode places one sample\nin `[23:0]`."
}
]
},
{
"id": "apu-i2s",
"ips": [
"apu",
"i2s"
],
"title": "Supported APU WAV/FLAC output -> I2S",
"classification": "Conditional",
"condition": "Load the accepted APUMC image, choose supported rate/channel/sample format and the APU TX route, and retain exclusive stream ownership. MP3 and default KWS are unavailable; corpus and sustained playback qualification are separate.",
"blockers": [],
"sources": [
"docs/ip/apu.md",
"rtl/ip/multimedia/apb4_apu.sv",
"publications/datasheets/features.json"
],
"bindings": [
{
"file": "publications/datasheets/features.json",
"kind": "snippet",
"text": "\"Coreless microcode sequencer with private DMA and local storage.\""
}
]
}
],
"physical": [
{
"id": "board",
"title": "Board reference",
"available": "StarrySky V2 FPGA constraint file exists as a board-specific input.",
"missing": "Approved minimal-system schematic, device/BOM review and matching bringup report not supplied.",
"sources": [
"fpga/mini/starrysky_v2.xdc",
"fpga/README.md"
]
},
{
"id": "package",
"title": "Physical package",
"available": "Logical pad inventory and technology wrapper sources are indexed.",
"missing": "Approved package-pin/die-pad assignment, supply-pin map and mechanical supplier drawing not supplied.",
"sources": [
"publications/datasheets/sections/pins.typ",
"physical/README.md"
]
},
{
"id": "measurements",
"title": "Measurements",
"available": "Digital configuration, calculation examples and test entry points are available.",
"missing": "Matching physical DC/AC, power, thermal and application-performance characterization reports not supplied.",
"sources": [
"publications/datasheets/sections/electrical-reference.typ",
"publications/datasheets/sections/performance-reference.typ"
]
}
],
"sources": [
"app/apps/xpi_flash_loader/main.c",
"app/ports/linux/linux/retrosoc_hp.dts",
"configs/ci/ihp130-xpi-flash-loader.mk",
"configs/ci/ihp130.mk",
"crt/linker/jtag_sram.lds",
"crt/src/hal/i2s_math.c",
"dependencies/dependencies.lock.json",
"docs/hazard3-debug.md",
"docs/ip/apu.md",
"docs/ip/jpeg.md",
"docs/ip/xpi.md",
"docs/lp-hp-architecture.md",
"publications/datasheets/features.json",
"publications/datasheets/mini.json",
"publications/datasheets/system-reference.json",
"rtl/ip/multimedia/dvp_core.sv",
"rtl/ip/peripheral/dma_reg.sv",
"rtl/ip/peripheral/gpio_reg.sv",
"rtl/managed/clusterip/common/rtl/utils/register.sv",
"rtl/mini/top/clock_config_controller.sv",
"rtl/mini/top/hp_lifecycle_controller.sv",
"rtl/mini/top/mgmt_core_wrapper.sv",
"rtl/mini/top/resource_controller.sv",
"rtl/mini/top/soc_clock_reset_subsystem.sv",
"scripts/generate_vexiiriscv.py",
"scripts/program_xpi_flash.py",
"scripts/vexiiriscv/GenerateRetroSocHp.scala",
"tests/test_xpi_flash_tool.py"
]
},
"retrieval": {
"instances": [
{
"id": "apb4_xpi",
"chapter": "xpi",
"family": "xpi",
"mode": "PRODUCT",
"region": "APB4_XPI",
"catalog": "xpi",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/xpi.md"
]
},
{
"id": "apb4_spisd",
"chapter": "spisd",
"family": "spisd",
"mode": "PRODUCT",
"region": "APB4_SPISD",
"catalog": "spisd",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/spisd.md"
]
},
{
"id": "apb4_sdio0",
"chapter": "sdio0",
"family": "sdio",
"mode": "PRODUCT",
"region": "APB4_SDIO0",
"catalog": "sdio0",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/sdio.md"
]
},
{
"id": "apb4_sram",
"chapter": "sram",
"family": "sram",
"mode": "PRODUCT",
"region": "APB4_SRAM",
"catalog": "sram",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/onchip-sram.md"
]
},
{
"id": "apb4_psram",
"chapter": "psram",
"family": "psram",
"mode": "PRODUCT",
"region": "APB4_PSRAM",
"catalog": "psram",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/psram.md"
]
},
{
"id": "apb4_opipsram",
"chapter": "opipsram",
"family": "opipsram",
"mode": "PRODUCT",
"region": "APB4_OPIPSRAM",
"catalog": "opipsram",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/opipsram.md"
]
},
{
"id": "apb4_sdram",
"chapter": "sdram",
"family": "sdram",
"mode": "PRODUCT",
"region": "APB4_SDRAM",
"catalog": "sdram",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/sdram.md"
]
},
{
"id": "apb4_gpio",
"chapter": "gpio",
"family": "gpio",
"mode": "PRODUCT",
"region": "APB4_GPIO",
"catalog": "gpio",
"qualification": "User window: PAD_CAPABILITY is not decoded here; common IP_VERSION and CAPABILITY are visible.",
"sources": [
"docs/ip/gpio.md",
"rtl/ip/peripheral/gpio_reg.sv",
"rtl/ip/peripheral/gpio_reg.sv"
],
"groups": [
"user",
"common"
],
"exclude": [
"common.PAD_CAPABILITY"
]
},
{
"id": "apb4_gpio_admin",
"chapter": "gpio",
"family": "gpio",
"mode": "PRODUCT",
"region": "APB4_GPIO_ADMIN",
"catalog": "gpio",
"qualification": "Management window: includes PAD_CAPABILITY and the common discovery words.",
"sources": [
"docs/ip/gpio.md",
"rtl/ip/peripheral/gpio_reg.sv",
"rtl/ip/peripheral/gpio_reg.sv"
],
"groups": [
"admin",
"common"
]
},
{
"id": "apb4_dma",
"chapter": "dma",
"family": "dma",
"mode": "PRODUCT",
"region": "APB4_DMA",
"catalog": "dma",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/dma.md"
]
},
{
"id": "apb4_tim0",
"chapter": "timer",
"family": "timer",
"mode": "PRODUCT",
"region": "APB4_TIM0",
"catalog": "timer",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/timer.md"
]
},
{
"id": "apb4_tim1",
"chapter": "timer",
"family": "timer",
"mode": "PRODUCT",
"region": "APB4_TIM1",
"catalog": "timer",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/timer.md"
]
},
{
"id": "apb4_rtc",
"chapter": "rtc",
"family": "rtc",
"mode": "PRODUCT",
"region": "APB4_RTC",
"catalog": "rtc",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"rtl/managed/clusterip/rtc/doc/datasheet.md",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "apb4_wdg",
"chapter": "wdg",
"family": "wdg",
"mode": "PRODUCT",
"region": "APB4_WDG",
"catalog": "wdg",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"rtl/managed/clusterip/wdg/doc/datasheet.md",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "apb4_pwm",
"chapter": "pwm",
"family": "pwm",
"mode": "PRODUCT",
"region": "APB4_PWM",
"catalog": "pwm",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"rtl/managed/clusterip/pwm/doc/datasheet.md",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "apb4_uart0",
"chapter": "uart0",
"family": "uart",
"mode": "PRODUCT",
"region": "APB4_UART0",
"catalog": "uart0",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/uart.md"
]
},
{
"id": "apb4_uart1",
"chapter": "uart1",
"family": "uart",
"mode": "PRODUCT",
"region": "APB4_UART1",
"catalog": "uart1",
"qualification": "Shared UART register layout; UART1 has no UART0 DMA/RTS/CTS routing. Consult its instance-specific capabilities and software notes.",
"sources": [
"docs/ip/uart.md"
]
},
{
"id": "apb4_i2c0",
"chapter": "i2c",
"family": "i2c",
"mode": "PRODUCT",
"region": "APB4_I2C0",
"catalog": "i2c",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/i2c.md"
]
},
{
"id": "apb4_i2c1",
"chapter": "i2c",
"family": "i2c",
"mode": "PRODUCT",
"region": "APB4_I2C1",
"catalog": "i2c",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/i2c.md"
]
},
{
"id": "apb4_ws2812",
"chapter": "ws2812",
"family": "ws2812",
"mode": "PRODUCT",
"region": "APB4_WS2812",
"catalog": "ws2812",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/ws2812.md"
]
},
{
"id": "apb4_ps2",
"chapter": "ps2",
"family": "ps2",
"mode": "PRODUCT",
"region": "APB4_PS2",
"catalog": "ps2",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/ps2.md"
]
},
{
"id": "apb4_sdio1",
"chapter": "sdio1",
"family": "sdio",
"mode": "PRODUCT",
"region": "APB4_SDIO1",
"catalog": "sdio1",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/sdio.md"
]
},
{
"id": "apb4_usb2",
"chapter": "usb2",
"family": "usb2",
"mode": "PRODUCT",
"region": "APB4_USB2",
"catalog": "usb2",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/usb2.md"
]
},
{
"id": "apb4_archinfo",
"chapter": "archinfo",
"family": "archinfo",
"mode": "PRODUCT",
"region": "APB4_ARCHINFO",
"catalog": "archinfo",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"rtl/managed/clusterip/archinfo/doc/datasheet.md",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "apb4_sysctrl",
"chapter": "sysctrl",
"family": "sysctrl",
"mode": "PRODUCT",
"region": "APB4_SYSCTRL",
"catalog": "sysctrl",
"qualification": "SYSCTRL includes the RCU clock/memory-pad registers. There is no additional RCU base. PRODUCT-disabled selectors retain their published access restrictions.",
"sources": [
"docs/ip/sysctrl.md"
]
},
{
"id": "apb4_clint",
"chapter": "clint",
"family": "clint",
"mode": "PRODUCT",
"region": "APB4_CLINT",
"catalog": "clint",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/clint.md"
]
},
{
"id": "hp_aclint",
"chapter": "hp-aclint",
"family": "aclint",
"mode": "PRODUCT",
"region": "HP_ACLINT",
"catalog": "hp-platform",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/hp-platform.md",
"docs/lp-hp-architecture.md"
]
},
{
"id": "hp_plic",
"chapter": "hp-plic",
"family": "plic",
"mode": "PRODUCT",
"region": "HP_PLIC",
"catalog": "hp-platform",
"qualification": "PRIORITY index 0 is reserved and hardwired zero; its generic array access does not make source 0 programmable. Context indices retain the HP-platform contract.",
"sources": [
"docs/ip/hp-platform.md",
"docs/lp-hp-architecture.md"
]
},
{
"id": "apb4_hp_mailbox",
"chapter": "hp-mailbox",
"family": "mailbox",
"mode": "PRODUCT",
"region": "APB4_HP_MAILBOX",
"catalog": "hp-platform",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/hp-platform.md",
"docs/lp-hp-architecture.md"
]
},
{
"id": "apb4_resource_ctrl",
"chapter": "resource",
"family": "resource",
"mode": "PRODUCT",
"region": "APB4_RESOURCE_CTRL",
"catalog": "resource",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/resource-controller.md"
]
},
{
"id": "apb4_fabric_monitor",
"chapter": "monitor",
"family": "monitor",
"mode": "PRODUCT",
"region": "APB4_FABRIC_MONITOR",
"catalog": "monitor",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/fabric-monitor.md"
]
},
{
"id": "apb4_i2s",
"chapter": "i2s",
"family": "i2s",
"mode": "PRODUCT",
"region": "APB4_I2S",
"catalog": "i2s",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/i2s.md"
]
},
{
"id": "apb4_dvp",
"chapter": "dvp",
"family": "dvp",
"mode": "PRODUCT",
"region": "APB4_DVP",
"catalog": "dvp",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/dvp.md"
]
},
{
"id": "apb4_jpeg",
"chapter": "jpeg",
"family": "jpeg",
"mode": "PRODUCT",
"region": "APB4_JPEG",
"catalog": "jpeg",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/jpeg.md"
]
},
{
"id": "apb4_apu",
"chapter": "apu",
"family": "apu",
"mode": "PRODUCT",
"region": "APB4_APU",
"catalog": "apu",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/apu.md",
"rtl/ip/multimedia/apu_reg.sv",
"rtl/ip/multimedia/apb4_apu.sv"
]
},
{
"id": "apb4_ga2d",
"chapter": "resource",
"family": "ga2d",
"mode": "PRODUCT",
"region": "APB4_GA2D",
"catalog": "ga2d",
"qualification": "Phase 5 implements GA2D as a PCLK-controlled, direct single-job private-AXI64 2D engine with resource-owned IRQ, snapshots, pitch, and byte-edge support. FILL, COPY, bit-exact CONVERT, opaque alpha BLEND, A8 fixed-color foreground masks, and exact equal background/destination in-place composition are supported. RGB565, RGB888, XRGB8888, and ARGB8888 are color surfaces; A8 is BLEND foreground-only. Transparent-background/premultiplied-alpha modes, scaling, rendering, descriptor/ring/queue submission, hardware cache coherency, and a Linux graphics driver are unavailable.",
"sources": [
"docs/ip/ga2d.md",
"rtl/ip/multimedia/ga2d_reg.sv",
"rtl/ip/multimedia/apb4_ga2d.sv",
"rtl/ip/multimedia/ga2d_pkg.sv",
"rtl/ip/multimedia/ga2d_addr_gen.sv",
"rtl/ip/multimedia/ga2d_axi4_master.sv",
"rtl/ip/multimedia/ga2d_dma.sv",
"rtl/ip/multimedia/ga2d_pixel.sv",
"rtl/ip/multimedia/ga2d_core.sv"
]
},
{
"id": "apb4_crypto",
"chapter": "crypto",
"family": "crypto",
"mode": "PRODUCT",
"region": "APB4_CRYPTO",
"catalog": "crypto",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"docs/ip/crypto.md"
]
},
{
"id": "apb4_crc",
"chapter": "crc",
"family": "crc",
"mode": "PRODUCT",
"region": "APB4_CRC",
"catalog": "crc",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"rtl/managed/clusterip/crc/doc/datasheet.md",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "apb4_rng",
"chapter": "rng",
"family": "rng",
"mode": "PRODUCT",
"region": "APB4_RNG",
"catalog": "rng",
"qualification": "Use the named instance, ownership and reset conditions in the linked IP reference.",
"sources": [
"rtl/managed/clusterip/rng/doc/datasheet.md",
"rtl/mini/top/apb4_system.sv"
]
},
{
"id": "apb4_ext_l",
"chapter": "ext-l",
"family": "extensions",
"mode": "PRODUCT",
"region": "APB4_EXT_L",
"catalog": "ext-l",
"qualification": "No data master. ACL/timeout and DMA writes are rejected. In this snapshot, rejected READ_BASE/WRITE_BASE writes can still change readable storage; do not rely on an error response to roll back state.",
"sources": [
"docs/ip/extensions.md",
"rtl/mini/top/extension_slot.sv",
"rtl/mini/top/extension_subsystem.sv",
"rtl/mini/integration/user_extensions.json"
],
"bindings": [
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "localparam logic [31:0] Identifier = KindExtH ? 32'h4558_5448 : 32'h4558_544C;"
},
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "16'd0, 8'(IrqCount), 4'd0, HasLocalSram, HasStream, HasDataMaster, 1'b1"
},
{
"file": "rtl/mini/top/extension_subsystem.sv",
"text": ".KindExtH (1'b0), .HasDataMaster(1'b0), .HasStream (1'b0), .HasLocalSram (1'b0), .IrqCount (1)"
},
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "ReadBase: begin s_cfg_write_legal = KindExtH; s_read_base_d = cfg_apb4.pwdata; end"
},
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "WriteBase: begin s_cfg_write_legal = KindExtH; s_write_base_d = cfg_apb4.pwdata; end"
}
],
"overrides": {
"main.Identification": {
"reset": "0x4558544C"
},
"main.Capability": {
"reset": "0x00000101"
},
"main.ReadBase": {
"access": "Write rejected"
},
"main.ReadLimit": {
"access": "Write rejected"
},
"main.WriteBase": {
"access": "Write rejected"
},
"main.WriteLimit": {
"access": "Write rejected"
},
"main.Timeout": {
"access": "Write rejected"
},
"main.DmaSource": {
"access": "Write rejected"
},
"main.DmaDestination": {
"access": "Write rejected"
},
"main.DmaLength": {
"access": "Write rejected"
},
"main.DmaCommand": {
"access": "Write rejected"
},
"main.DmaStatus": {
"access": "RO (zero)",
"reset": "0x00000000"
}
}
},
{
"id": "apb4_ext_h",
"chapter": "ext-h",
"family": "extensions",
"mode": "PRODUCT",
"region": "APB4_EXT_H",
"catalog": "ext-h",
"qualification": "Shared extension-slot definitions are qualified by the slot capabilities. EXT-L has no data master; ACL/timeout and DMA writes are rejected there.",
"sources": [
"docs/ip/extensions.md",
"rtl/mini/top/extension_slot.sv",
"rtl/mini/top/extension_subsystem.sv",
"rtl/mini/integration/user_extensions.json"
],
"bindings": [
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "localparam logic [31:0] Identifier = KindExtH ? 32'h4558_5448 : 32'h4558_544C;"
},
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "16'd0, 8'(IrqCount), 4'd0, HasLocalSram, HasStream, HasDataMaster, 1'b1"
}
],
"overrides": {
"main.Identification": {
"reset": "0x45585448"
},
"main.Capability": {
"reset": "0x00000103"
}
}
},
{
"id": "mpw-timer",
"chapter": "mpw-timer",
"family": "mpw-timer",
"mode": "MPW",
"region": "APB4_USER_IP",
"slot": 1,
"design_id": "tiny_timer",
"qualification": "MPW selection 1: tiny_timer. Not an active PRODUCT user-IP register bank.",
"sources": [
"rtl/mini/integration/user_extensions_legacy.json"
]
},
{
"id": "mpw-gpio",
"chapter": "mpw-gpio",
"family": "mpw-gpio",
"mode": "MPW",
"region": "APB4_USER_IP",
"slot": 2,
"design_id": "tiny_gpio",
"qualification": "MPW selection 2: tiny_gpio. Not an active PRODUCT user-IP register bank.",
"sources": [
"rtl/mini/integration/user_extensions_legacy.json"
]
}
],
"codes": [
{
"id": "sysctrl-reason",
"title": "SYSCTRL first-fault reason",
"source": "rtl/ip/peripheral/sysctrl_core.sv",
"pattern": "(?P<name>`RIB_RESP_\\w+|default):\\s*s_fault_reason_d\\s*=\\s*(?P<value>3\\x27d\\d+)",
"kind": "enum",
"expected": {
"default": 1,
"`RIB_RESP_RESERVED": 2,
"`RIB_RESP_PROTERR": 3,
"`RIB_RESP_SLVERR": 4,
"`RIB_RESP_TIMEOUT": 5
},
"meanings": {
"default": "Decode/unclassified reason used by the default detail mapping.",
"`RIB_RESP_RESERVED": "Reserved target.",
"`RIB_RESP_PROTERR": "Access protection failure.",
"`RIB_RESP_SLVERR": "Target/slave error.",
"`RIB_RESP_TIMEOUT": "Transaction timeout."
},
"observation": "FAULT_STATUS.REASON [4:2], only meaningful with PENDING. Capture address, master, write direction and FAULT_DETAIL together.",
"handling": "Preserve the first event before W1C of PENDING. Clearing permits a later event to replace the captured fields; the counter is separate.",
"link": "sysctrl",
"sources": [
"rtl/ip/peripheral/sysctrl_core.sv"
]
},
{
"id": "rib-detail",
"title": "RIB response / SYSCTRL detail",
"source": "rtl/mini/top/rib_defs.svh",
"pattern": "^`define\\s+(?P<name>RIB_RESP_\\w+)\\s+(?P<value>3\\x27d\\d+)",
"kind": "enum",
"expected": {
"RIB_RESP_OK": 0,
"RIB_RESP_DECERR": 1,
"RIB_RESP_PROTERR": 2,
"RIB_RESP_SLVERR": 3,
"RIB_RESP_TIMEOUT": 4,
"RIB_RESP_RESERVED": 5,
"RIB_RESP_BURSTERR": 6
},
"meanings": {
"RIB_RESP_OK": "Successful response; not a fault cause.",
"RIB_RESP_DECERR": "Unmapped address / decode error.",
"RIB_RESP_PROTERR": "Access protection rejected.",
"RIB_RESP_SLVERR": "Slave error response.",
"RIB_RESP_TIMEOUT": "Finite transaction timeout.",
"RIB_RESP_RESERVED": "Reserved target decode.",
"RIB_RESP_BURSTERR": "Burst shape/length rejected; SYSCTRL reason uses its default mapping when this detail is captured."
},
"observation": "RIB response code; SYSCTRL FAULT_DETAIL preserves the selected fault detail. Its numeric namespace differs from FAULT_STATUS.REASON.",
"handling": "Follow the SYSCTRL capture sequence. A response code is not independently cleared by software.",
"link": "sysctrl",
"sources": [
"rtl/mini/top/rib_defs.svh"
]
},
{
"id": "fabric-reason",
"title": "Native data-plane rejection reasons",
"source": "rtl/mini/top/axi4_data_crossbar.sv",
"pattern": "localparam\\s+logic\\s*\\[3:0\\]\\s+(?P<name>Fault\\w+)\\s*=\\s*(?P<value>4\\x27d\\d+)",
"kind": "enum",
"expected": {
"FaultUnmapped": 1,
"FaultInactivePad": 2,
"FaultAccess": 3,
"FaultProtocol": 4
},
"meanings": {
"FaultUnmapped": "Address does not select a decoded data target.",
"FaultInactivePad": "QPI/OPI access targets the inactive memory-pad mode.",
"FaultAccess": "Initiator access policy rejects the request.",
"FaultProtocol": "Request violates the admitted AXI transaction subset."
},
"observation": "Fabric Monitor FAULT reason, with master/target/direction/address. These native AXI reasons are not the RIB/SYSCTRL reason enumeration.",
"handling": "Capture the monitor record and clear under its CONTROL contract. A clear neither widens access nor reactivates an isolated target.",
"link": "monitor",
"sources": [
"rtl/mini/top/axi4_data_crossbar.sv"
]
},
{
"id": "fabric-timeout",
"title": "Native data-plane target timeout",
"source": "rtl/mini/top/soc_data_plane.sv",
"pattern": "localparam\\s+logic\\s*\\[3:0\\]\\s+(?P<name>FaultTimeout)\\s*=\\s*(?P<value>4\\x27d\\d+)",
"kind": "enum",
"expected": {
"FaultTimeout": 5
},
"meanings": {
"FaultTimeout": "Target guard reports a timed-out transaction and isolation state."
},
"observation": "Same Fabric Monitor native reason namespace as the rejection table. Inspect target guard/isolation status.",
"handling": "Stop new work and follow the target recovery/reset contract before reuse. Clearing the monitor record alone does not reconnect the target.",
"link": "monitor",
"sources": [
"rtl/mini/top/soc_data_plane.sv"
]
},
{
"id": "pll-response",
"title": "PLL transaction result",
"source": "rtl/mini/top/pll_rcu_controller.sv",
"pattern": "s_err_d\\s*=\\s*(?P<value>2\\x27d[0-3])",
"kind": "enum",
"expected": {
"0": 0,
"1": 1,
"2": 2,
"3": 3
},
"meanings": {
"0": "No transaction error; force-safe may also report zero.",
"1": "PLL capability absent.",
"2": "Quiesce, lock-low observation or lock qualification timed out.",
"3": "Previously active PLL lost lock."
},
"observation": "SYSCTRL PLL_STATUS error reason; also inspect valid, safe-clock and current lock bits.",
"handling": "Retain the error with clock state. Clear the appropriate sticky indication only after diagnosis; zero does not alone prove PLL operation.",
"link": "rcu",
"sources": [
"rtl/mini/top/pll_rcu_controller.sv"
],
"assignment_values": true
},
{
"id": "dma-error",
"title": "Central DMA channel error code",
"source": "rtl/ip/peripheral/dma_pkg.sv",
"pattern": "localparam\\s+logic\\s*\\[3:0\\]\\s+(?P<name>DMA_ERROR_\\w+)\\s*=\\s*(?P<value>4\\x27d\\d+)",
"kind": "enum",
"expected": {
"DMA_ERROR_NONE": 0,
"DMA_ERROR_CONFIG": 1,
"DMA_ERROR_ALIGNMENT": 2,
"DMA_ERROR_AXI_READ": 3,
"DMA_ERROR_AXI_WRITE": 4,
"DMA_ERROR_AXI_PROTOCOL": 5,
"DMA_ERROR_STREAM": 6,
"DMA_ERROR_ABORT": 7
},
"meanings": {
"DMA_ERROR_NONE": "No channel error.",
"DMA_ERROR_CONFIG": "Invalid channel/descriptor configuration.",
"DMA_ERROR_ALIGNMENT": "Address/length alignment check failed.",
"DMA_ERROR_AXI_READ": "AXI read returned a non-OKAY response.",
"DMA_ERROR_AXI_WRITE": "AXI write returned a non-OKAY response.",
"DMA_ERROR_AXI_PROTOCOL": "AXI completion/protocol check failed.",
"DMA_ERROR_STREAM": "Stream transfer framing or acceptance error.",
"DMA_ERROR_ABORT": "Transfer aborted."
},
"observation": "CH_ERROR_STATUS low nibble; response, direction and stream-last flags occupy separate fields. Capture CH_ERROR_ADDR and completed byte count.",
"handling": "Use channel event/IRQ acknowledgement and the documented submit/recovery sequence; do not write a read-only error code as an acknowledgement.",
"link": "dma",
"sources": [
"rtl/ip/peripheral/dma_pkg.sv"
]
},
{
"id": "sdio-dma-mask",
"title": "SDIO private DMA ABI masks",
"source": "crt/include/retrosoc/hal/sdio_regs.h",
"pattern": "^#define\\s+(?P<name>RS_SDIO_DMA_ERROR_\\w+)\\s+UINT32_C\\((?P<value>0x[0-9A-Fa-f]+)\\)",
"kind": "mask",
"expected": {
"RS_SDIO_DMA_ERROR_INVALID_START": 1,
"RS_SDIO_DMA_ERROR_DESCRIPTOR": 2,
"RS_SDIO_DMA_ERROR_AXI": 4,
"RS_SDIO_DMA_ERROR_ABORT": 8,
"RS_SDIO_DMA_ERROR_PAYLOAD": 16,
"RS_SDIO_DMA_ERROR_INTERNAL": 128
},
"meanings": {
"RS_SDIO_DMA_ERROR_INVALID_START": "Invalid start/configuration.",
"RS_SDIO_DMA_ERROR_DESCRIPTOR": "Descriptor check failed.",
"RS_SDIO_DMA_ERROR_AXI": "AXI transfer failed.",
"RS_SDIO_DMA_ERROR_ABORT": "Abort observed.",
"RS_SDIO_DMA_ERROR_PAYLOAD": "Payload transfer failed.",
"RS_SDIO_DMA_ERROR_INTERNAL": "Internal DMA failure."
},
"observation": "Published SDK mask values, not ordinal numbers. The shared SDIO/SPI-SD engine currently emits one cause mask at a time; it uses 0x02 for its invalid-start check. The SDK 0x01 declaration is not emitted by the reviewed engine.",
"handling": "Preserve DMA and controller errors before local IRQ/error W1C; reinitialize the transfer only after the engine has stopped.",
"link": "sdio0",
"sources": [
"crt/include/retrosoc/hal/sdio_regs.h",
"rtl/ip/storage/sdio_dma.sv",
"rtl/ip/storage/sdio_core.sv",
"rtl/ip/storage/spisd_core.sv"
],
"bindings": [
{
"file": "rtl/ip/storage/sdio_dma.sv",
"text": "s_err_code_d = 8'h02;"
},
{
"file": "rtl/ip/storage/spisd_core.sv",
"text": "assign dma_error_o = {24'd0, s_dma_err_code};"
},
{
"file": "rtl/ip/storage/sdio_core.sv",
"text": "assign dma_error_o = {24'd0, s_dma_err_code};"
}
]
},
{
"id": "usb-dma",
"title": "USB2 DMA engine error codes",
"source": "rtl/ip/usb/usb2_dma.sv",
"pattern": "localparam\\s+logic\\s*\\[7:0\\]\\s+(?P<name>Error\\w+)\\s*=\\s*(?P<value>8\\x27d\\d+)",
"kind": "enum",
"expected": {
"ErrorDescriptor": 1,
"ErrorLength": 2,
"ErrorAxiRead": 3,
"ErrorAxiWrite": 4,
"ErrorPacket": 5,
"ErrorAbort": 6,
"ErrorWriteback": 7
},
"meanings": {
"ErrorDescriptor": "Descriptor ownership/geometry validation failed.",
"ErrorLength": "Transfer length invalid.",
"ErrorAxiRead": "DMA AXI read failed.",
"ErrorAxiWrite": "DMA AXI write failed.",
"ErrorPacket": "Packet/buffer result failed.",
"ErrorAbort": "DMA transfer aborted.",
"ErrorWriteback": "Descriptor writeback failed."
},
"observation": "ERROR_CODE low byte captures a DMA engine code for DMA faults. Scheduler packet faults instead encode 0x80 OR the transfer-result nibble; capture the associated ERROR_STATUS and ERROR_INFO.",
"handling": "Record ERROR_DESC_ADDR and ERROR_BUFFER_ADDR before local W1C. A zero-initialized code is not a successful completion without the corresponding valid/done state.",
"link": "usb2",
"sources": [
"rtl/ip/usb/usb2_dma.sv"
],
"bindings": [
{
"file": "rtl/ip/usb/usb2_scheduler.sv",
"text": "s_fault_code_d = {4'h8, s_result_code};"
},
{
"file": "rtl/ip/usb/usb2_scheduler.sv",
"text": "s_err_code_d = {24'd0, s_fault_code_q};"
}
]
},
{
"id": "usb-descriptor",
"title": "USB2 descriptor validation codes",
"source": "rtl/ip/usb/usb2_pkg.sv",
"pattern": "(?P<name>Usb2Desc\\w+)\\s*=\\s*(?P<value>5\\x27d\\d+)",
"kind": "enum",
"expected": {
"Usb2DescOk": 0,
"Usb2DescNotOwned": 1,
"Usb2DescReserved": 2,
"Usb2DescBufferAlign": 3,
"Usb2DescLength": 4,
"Usb2DescNextAlign": 5,
"Usb2DescChain": 6,
"Usb2DescFrameReserved": 7,
"Usb2DescAddressWrap": 8
},
"meanings": {
"Usb2DescOk": "Descriptor validation succeeded.",
"Usb2DescNotOwned": "Descriptor not owned by hardware.",
"Usb2DescReserved": "Reserved descriptor fields are set.",
"Usb2DescBufferAlign": "Buffer alignment invalid.",
"Usb2DescLength": "Length invalid.",
"Usb2DescNextAlign": "Next descriptor alignment invalid.",
"Usb2DescChain": "Chain/end relationship invalid.",
"Usb2DescFrameReserved": "Frame reserved fields set.",
"Usb2DescAddressWrap": "Buffer address plus length wraps."
},
"observation": "Descriptor validation result; distinguish it from the USB2 packet result and descriptor completion bits.",
"handling": "Fix ownership, geometry or reserved fields after software owns the descriptor; preserve ERROR_CODE/INFO and descriptor/buffer addresses.",
"link": "usb2",
"sources": [
"rtl/ip/usb/usb2_pkg.sv"
]
},
{
"id": "usb-result",
"title": "USB2 transfer result codes",
"source": "rtl/ip/usb/usb2_pkg.sv",
"pattern": "(?P<name>Usb2Result\\w+)\\s*=\\s*(?P<value>4\\x27d\\d+)",
"kind": "enum",
"expected": {
"Usb2ResultSuccess": 0,
"Usb2ResultNak": 1,
"Usb2ResultStall": 2,
"Usb2ResultTimeout": 3,
"Usb2ResultCrc": 4,
"Usb2ResultProtocol": 5,
"Usb2ResultOverflow": 6,
"Usb2ResultCanceled": 7
},
"meanings": {
"Usb2ResultSuccess": "Transfer completed successfully.",
"Usb2ResultNak": "NAK response; handle according to transfer/scheduling policy.",
"Usb2ResultStall": "Endpoint stalled.",
"Usb2ResultTimeout": "Response timed out.",
"Usb2ResultCrc": "CRC check failed.",
"Usb2ResultProtocol": "Protocol check failed.",
"Usb2ResultOverflow": "Received data exceeds capacity.",
"Usb2ResultCanceled": "Transfer canceled."
},
"observation": "Internal transfer result consumed by scheduling/writeback. Decode the corresponding public descriptor status, endpoint/channel status and error record.",
"handling": "These values are not a universal encoding of ERROR_CODE. Complete descriptor ownership and local acknowledgement before resubmission.",
"link": "usb2",
"sources": [
"rtl/ip/usb/usb2_pkg.sv"
]
},
{
"id": "jpeg-error",
"title": "JPEG job error codes",
"source": "rtl/ip/multimedia/jpeg_pkg.sv",
"pattern": "",
"kind": "enum",
"expected": {
"JpegErrorNone": 0,
"JpegErrorConfig": 1,
"JpegErrorDescriptor": 2,
"JpegErrorTable": 3,
"JpegErrorUnsupportedMarker": 4,
"JpegErrorUnsupportedProcess": 5,
"JpegErrorUnsupportedPrecision": 6,
"JpegErrorUnsupportedSampling": 7,
"JpegErrorMalformedMarker": 8,
"JpegErrorMalformedHuffman": 9,
"JpegErrorTruncated": 10,
"JpegErrorRestart": 11,
"JpegErrorOutputOverflow": 12,
"JpegErrorAxiRead": 13,
"JpegErrorAxiWrite": 14,
"JpegErrorAxiDescriptor": 15,
"JpegErrorTimeout": 16,
"JpegErrorAborted": 17,
"JpegErrorInternal": 18
},
"meanings": {
"JpegErrorNone": "No error.",
"JpegErrorConfig": "Configuration rejected.",
"JpegErrorDescriptor": "Descriptor rejected.",
"JpegErrorTable": "Coding table invalid.",
"JpegErrorUnsupportedMarker": "Marker unsupported.",
"JpegErrorUnsupportedProcess": "JPEG process unsupported.",
"JpegErrorUnsupportedPrecision": "Sample precision unsupported.",
"JpegErrorUnsupportedSampling": "Sampling unsupported.",
"JpegErrorMalformedMarker": "Malformed marker.",
"JpegErrorMalformedHuffman": "Malformed Huffman data/table.",
"JpegErrorTruncated": "Input truncated.",
"JpegErrorRestart": "Restart sequence invalid.",
"JpegErrorOutputOverflow": "Output capacity exceeded.",
"JpegErrorAxiRead": "Input/payload AXI read failed.",
"JpegErrorAxiWrite": "Output AXI write failed.",
"JpegErrorAxiDescriptor": "Descriptor AXI access failed.",
"JpegErrorTimeout": "Engine timeout.",
"JpegErrorAborted": "Job aborted.",
"JpegErrorInternal": "Internal failure."
},
"observation": "ERROR_STATUS code and stage, ERROR_ADDRESS/DETAIL and descriptor result. A declared code does not prove the system payload path is usable.",
"handling": "Copy the first error before ERROR_STATUS/IRQ_STATE W1C and follow ring/direct-job recovery. JPEG master 6 has bounded transport of one normal read and one normal write credit at class 8; complete system qualification remains separate.",
"link": "jpeg",
"sources": [
"rtl/ip/multimedia/jpeg_pkg.sv"
],
"enum_type": "jpeg_error_e"
},
{
"id": "apu-error",
"title": "APU declared error codes",
"source": "rtl/ip/multimedia/apu_define.svh",
"pattern": "^`define\\s+(?P<name>APB4_APU__ERROR_CODE_\\w+)\\s+(?P<value>\\d+)\\s*$",
"kind": "enum",
"expected": {
"APB4_APU__ERROR_CODE_NONE": 0,
"APB4_APU__ERROR_CODE_INVALID_CONFIG": 1,
"APB4_APU__ERROR_CODE_INVALID_RING": 2,
"APB4_APU__ERROR_CODE_UNSUPPORTED": 3,
"APB4_APU__ERROR_CODE_MALFORMED": 4,
"APB4_APU__ERROR_CODE_TRUNCATED": 5,
"APB4_APU__ERROR_CODE_CODEC_CRC": 6,
"APB4_APU__ERROR_CODE_DECODE": 7,
"APB4_APU__ERROR_CODE_RECONSTRUCTION": 8,
"APB4_APU__ERROR_CODE_MICROCODE": 9,
"APB4_APU__ERROR_CODE_MICROCODE_CRC": 10,
"APB4_APU__ERROR_CODE_SEQUENCER": 11,
"APB4_APU__ERROR_CODE_KWS_MODEL": 12,
"APB4_APU__ERROR_CODE_KWS_CRC": 13,
"APB4_APU__ERROR_CODE_KWS_ARITHMETIC": 14,
"APB4_APU__ERROR_CODE_AXI_READ": 15,
"APB4_APU__ERROR_CODE_AXI_WRITE": 16,
"APB4_APU__ERROR_CODE_DMA_TIMEOUT": 17,
"APB4_APU__ERROR_CODE_STREAM_UNDERRUN": 18,
"APB4_APU__ERROR_CODE_STREAM_OVERRUN": 19,
"APB4_APU__ERROR_CODE_ABORT": 20,
"APB4_APU__ERROR_CODE_RESOURCE_RESET": 21,
"APB4_APU__ERROR_CODE_OVERFLOW": 22
},
"meanings": {
"APB4_APU__ERROR_CODE_NONE": "No error.",
"APB4_APU__ERROR_CODE_INVALID_CONFIG": "Configuration invalid.",
"APB4_APU__ERROR_CODE_INVALID_RING": "Ring configuration invalid.",
"APB4_APU__ERROR_CODE_UNSUPPORTED": "Requested operation unsupported.",
"APB4_APU__ERROR_CODE_MALFORMED": "Input malformed.",
"APB4_APU__ERROR_CODE_TRUNCATED": "Input truncated.",
"APB4_APU__ERROR_CODE_CODEC_CRC": "Codec CRC failure.",
"APB4_APU__ERROR_CODE_DECODE": "Decode failure.",
"APB4_APU__ERROR_CODE_RECONSTRUCTION": "Reconstruction failure.",
"APB4_APU__ERROR_CODE_MICROCODE": "Microcode rejected.",
"APB4_APU__ERROR_CODE_MICROCODE_CRC": "Microcode CRC failure.",
"APB4_APU__ERROR_CODE_SEQUENCER": "Sequencer failure.",
"APB4_APU__ERROR_CODE_KWS_MODEL": "KWS model rejected.",
"APB4_APU__ERROR_CODE_KWS_CRC": "KWS CRC failure.",
"APB4_APU__ERROR_CODE_KWS_ARITHMETIC": "KWS arithmetic failure.",
"APB4_APU__ERROR_CODE_AXI_READ": "AXI read failure.",
"APB4_APU__ERROR_CODE_AXI_WRITE": "AXI write failure.",
"APB4_APU__ERROR_CODE_DMA_TIMEOUT": "DMA timeout.",
"APB4_APU__ERROR_CODE_STREAM_UNDERRUN": "Stream underrun.",
"APB4_APU__ERROR_CODE_STREAM_OVERRUN": "Stream overrun.",
"APB4_APU__ERROR_CODE_ABORT": "Job aborted.",
"APB4_APU__ERROR_CODE_RESOURCE_RESET": "Resource reset interrupted work.",
"APB4_APU__ERROR_CODE_OVERFLOW": "Capacity or arithmetic overflow."
},
"observation": "ERROR_STATUS code, stage, AXI response and descriptor index; ERROR_ADDRESS/DETAIL provide context.",
"handling": "Preserve the first error, then apply the documented ERROR_STATUS/IRQ_STATE acknowledgement. Declared codec/KWS codes do not establish implemented production features.",
"link": "apu",
"sources": [
"rtl/ip/multimedia/apu_define.svh"
]
},
{
"id": "sdk-result",
"title": "SDK rs_status_t return values",
"source": "crt/include/retrosoc/core/status.h",
"pattern": "^\\s*(?P<name>RS_(?:OK|E[A-Z]+))\\s*=\\s*(?P<value>-?\\d+),",
"kind": "enum",
"expected": {
"RS_OK": 0,
"RS_EINVAL": -1,
"RS_ENOMEM": -2,
"RS_ENOSPC": -3,
"RS_ETIMEOUT": -4,
"RS_EIO": -5,
"RS_ENOTSUP": -6,
"RS_EFORMAT": -7
},
"meanings": {
"RS_OK": "Operation completed under that API contract.",
"RS_EINVAL": "Input parameter invalid.",
"RS_ENOMEM": "Required memory unavailable.",
"RS_ENOSPC": "Output/buffer capacity insufficient.",
"RS_ETIMEOUT": "Bounded operation timed out.",
"RS_EIO": "I/O operation failed.",
"RS_ENOTSUP": "Operation unsupported.",
"RS_EFORMAT": "Input format rejected."
},
"observation": "Signed API return value. Exact triggering conditions depend on the called function; the enum definition does not make every code reachable from every API.",
"handling": "Check the return before using output values. No hardware W1C applies to a C return value; preserve the relevant peripheral status if diagnosis requires it.",
"link": "software-support",
"sources": [
"crt/include/retrosoc/core/status.h"
]
}
],
"status_registers": [
{
"id": "clock-lifecycle",
"title": "Clock, memory-pad and HP lifecycle observations",
"family": "sysctrl",
"registers": [
"main.PLL_STATUS",
"clock.CLK_STATUS",
"clock.CLK_FAULT",
"clock.MEM_PAD_FAULT",
"main.HP_STATUS"
],
"observation": "Clock command response 0 means accepted and 1 means rejected; the controller validates selectors, idle state, nonzero timeout and memory-pad lock. Read requested and actual HP state together.",
"handling": "PLL/clock fault clear and memory-pad fault clear are distinct commands. HP forced-fault records cache-clean, drain or flush timeout and clears on reset/new release under its lifecycle contract.",
"link": "rcu",
"sources": [
"rtl/mini/top/clock_config_controller.sv",
"rtl/mini/top/pll_rcu_controller.sv",
"rtl/mini/top/hp_lifecycle_controller.sv",
"crt/src/hal/sysctrl.c"
],
"bindings": [
{
"file": "rtl/mini/top/clock_config_controller.sv",
"text": "s_rsp_code_d = s_req_legal ? 4'd0 : 4'd1;"
},
{
"file": "rtl/ip/peripheral/sysctrl_core.sv",
"text": "21'd0, pll_ctrl.capable_i, s_pll_lock_q, s_pll_safe_clk_q, s_pll_err_reason_q, s_pll_err_q, s_pll_busy_q, s_pll_active_valid_q, s_pll_active_sel_q"
},
{
"file": "rtl/ip/peripheral/sysctrl_core.sv",
"text": "28'd0, s_clock_err_q, s_clock_busy_q, clock_ctrl.fault_i[1], clock_ctrl.fault_i[0]"
},
{
"file": "rtl/ip/peripheral/sysctrl_core.sv",
"text": "26'd0, sysctrl.hp_actual_released_i, sysctrl.hp_forced_fault_i, sysctrl.hp_draining_i, sysctrl.hp_present_i && !s_hp_release_q, s_hp_release_q, sysctrl.hp_present_i"
},
{
"file": "rtl/mini/top/clock_config_controller.sv",
"text": "assign clock_ctrl.fault_i = {30'd0, s_rsp_code_q != 4'd0, pll_fault_i};"
},
{
"file": "rtl/ip/peripheral/sysctrl_core.sv",
"text": "MemPadFault: read_data_o = {31'd0, clock_ctrl.memory_i[4]};"
}
],
"field_overrides": {
"main.PLL_STATUS": [
{
"lsb": 0,
"msb": 2,
"name": "ACTIVE_SELECTION",
"description": "Returned active PLL selection."
},
{
"lsb": 3,
"msb": 3,
"name": "ACTIVE_VALID",
"description": "The returned PLL selection is valid."
},
{
"lsb": 4,
"msb": 4,
"name": "BUSY",
"description": "PLL request/response pending."
},
{
"lsb": 5,
"msb": 5,
"name": "ERROR",
"description": "Latched transaction error indication."
},
{
"lsb": 6,
"msb": 7,
"name": "ERROR_REASON",
"description": "PLL result enumeration in the code table."
},
{
"lsb": 8,
"msb": 8,
"name": "SAFE_CLOCK",
"description": "Returned safe-clock selection state."
},
{
"lsb": 9,
"msb": 9,
"name": "LOCKED",
"description": "Returned PLL lock observation."
},
{
"lsb": 10,
"msb": 10,
"name": "CAPABLE",
"description": "Selected implementation supplies the PLL capability."
}
],
"clock.CLK_STATUS": [
{
"lsb": 0,
"msb": 0,
"name": "SOURCE_FAULT",
"description": "PLL or monitored-source fault input."
},
{
"lsb": 1,
"msb": 1,
"name": "RESPONSE_REJECTED",
"description": "Last AON clock command response was nonzero."
},
{
"lsb": 2,
"msb": 2,
"name": "BUSY",
"description": "Clock configuration request/response pending."
},
{
"lsb": 3,
"msb": 3,
"name": "ERROR",
"description": "Control-side command error indication."
}
],
"clock.CLK_FAULT": [
{
"lsb": 0,
"msb": 0,
"name": "SOURCE_FAULT",
"description": "Aggregate PLL/clock monitor fault."
},
{
"lsb": 1,
"msb": 1,
"name": "RESPONSE_REJECTED",
"description": "Nonzero clock command response."
}
],
"clock.MEM_PAD_FAULT": [
{
"lsb": 0,
"msb": 0,
"name": "PAD_CONFIG_FAULT",
"description": "Rejected memory-pad configuration observed; use its dedicated clear command."
}
],
"main.HP_STATUS": [
{
"lsb": 0,
"msb": 0,
"name": "PRESENT",
"description": "HP is present in this implementation."
},
{
"lsb": 1,
"msb": 1,
"name": "REQUESTED_RELEASE",
"description": "LP requested HP release."
},
{
"lsb": 2,
"msb": 2,
"name": "REQUESTED_HOLD",
"description": "HP present and release request is clear; this is not an independent observation of actual reset."
},
{
"lsb": 3,
"msb": 3,
"name": "DRAINING",
"description": "Lifecycle is draining/stopping HP traffic."
},
{
"lsb": 4,
"msb": 4,
"name": "FORCED_FAULT",
"description": "A cache, drain or flush timeout forced lifecycle progress."
},
{
"lsb": 5,
"msb": 5,
"name": "ACTUAL_RELEASED",
"description": "Actual HP lifecycle release observation."
}
]
}
},
{
"id": "resource-fault",
"title": "Resource ownership fault",
"family": "resource",
"registers": [
"resource.Status",
"resource.Fault"
],
"observation": "FAULT is one sticky bit, not an encoded reason. A rejected OWNER write sets it; inspect owner lock, quiesce, block acknowledgement and idle state to determine the cause.",
"handling": "Capture STATUS before full-word W1C of FAULT bit 0. Clearing does not change owner or unlock the resource.",
"link": "resource",
"sources": [
"rtl/mini/top/resource_controller.sv",
"crt/src/hal/resource.c"
]
},
{
"id": "central-dma-status",
"title": "Central DMA completion and error observations",
"family": "dma",
"registers": [
"ch.STATUS",
"ch.EVENT_STATUS",
"ch.ERROR_STATUS"
],
"observation": "Use CH_ERROR_ADDR, bytes completed and descriptor status with these fields. ERROR_STATUS and channel events have distinct purposes.",
"handling": "Acknowledge local W1C event/IRQ fields according to the DMA contract; preserve read-only error detail before a new channel command changes it.",
"link": "dma",
"sources": [
"rtl/ip/peripheral/dma_core.sv",
"crt/include/retrosoc/hal/dma_regs.h"
],
"field_overrides": {
"ch.ERROR_STATUS": [
{
"lsb": 0,
"msb": 3,
"name": "CODE",
"description": "Central DMA error enumeration in the code table."
},
{
"lsb": 4,
"msb": 5,
"name": "AXI_RESPONSE",
"description": "Captured two-bit AXI response."
},
{
"lsb": 6,
"msb": 6,
"name": "READ",
"description": "One identifies the read side of the reported error."
},
{
"lsb": 8,
"msb": 8,
"name": "STREAM_LAST",
"description": "Captured stream-last observation."
}
]
},
"bindings": [
{
"file": "rtl/ip/peripheral/dma_core.sv",
"text": "channel_error_status = {stream_last_i, 1'b0, error_read_i, response_i, error_code_i};"
}
]
},
{
"id": "spisd-dma-status",
"title": "SPI-SD private DMA status",
"family": "spisd",
"registers": [
"main.DMA_STATUS",
"main.DMA_ERROR",
"main.ERROR_STATUS"
],
"observation": "SPI-SD has its own DMA register semantics. Capture DMA_ERROR_ADDR, command/data completion and actual transfer count.",
"handling": "Copy the error snapshot before ERROR_STATUS and IRQ_STATUS W1C. Do not substitute the central DMA nibble enumeration.",
"link": "spisd",
"sources": [
"rtl/ip/storage/spisd_reg.sv",
"crt/include/retrosoc/hal/spisd_regs.h"
]
},
{
"id": "sdio-dma-status",
"title": "SDIO0/1 private DMA status",
"family": "sdio",
"registers": [
"main.DMA_STATUS",
"main.DMA_ERROR"
],
"observation": "Decode against the selected SDIO instance. The mask table above applies to DMA_ERROR; controller ERROR_STATUS remains a separate cause set.",
"handling": "Capture DMA_ERROR_ADDR and controller errors, stop/abort as required, then acknowledge local interrupt/error state.",
"link": "sdio0",
"sources": [
"rtl/ip/storage/sdio_reg.sv",
"crt/include/retrosoc/hal/sdio_regs.h"
]
},
{
"id": "usb-dma-status",
"title": "USB2 first error record",
"family": "usb2",
"registers": [
"main.ERROR_STATUS",
"main.ERROR_CODE",
"main.ERROR_INFO"
],
"observation": "Capture ERROR_DESC_ADDR and ERROR_BUFFER_ADDR plus endpoint/channel state and descriptor completion. Internal result and descriptor-validation enums are separate namespaces.",
"handling": "Follow USB2 ERROR_STATUS/IRQ_STATUS W1C and descriptor ownership rules. A packet retry is a scheduler/transfer-policy decision.",
"link": "usb2",
"sources": [
"rtl/ip/usb/usb2_reg.sv",
"rtl/ip/usb/usb2_pkg.sv"
],
"field_overrides": {
"main.ERROR_STATUS": [
{
"lsb": 0,
"msb": 0,
"name": "SCHEDULER_FAULT",
"description": "Scheduler/DMA first-fault event, latched and W1C in the register block."
}
],
"main.ERROR_CODE": [
{
"lsb": 0,
"msb": 7,
"name": "CODE",
"description": "DMA engine error code, or 0x80 OR packet-result nibble for scheduler packet faults."
}
],
"main.ERROR_INFO": [
{
"lsb": 0,
"msb": 3,
"name": "INDEX",
"description": "Affected device endpoint or host channel."
},
{
"lsb": 4,
"msb": 4,
"name": "DIRECTION_IN",
"description": "Captured transfer direction."
},
{
"lsb": 14,
"msb": 15,
"name": "ROLE",
"description": "Captured role: 1 device, 2 host."
}
]
},
"bindings": [
{
"file": "rtl/ip/usb/usb2_scheduler.sv",
"text": "s_err_stat_d = 32'h0000_0001;"
},
{
"file": "rtl/ip/usb/usb2_scheduler.sv",
"text": "s_err_code_d = {24'd0, s_fault_code_q};"
},
{
"file": "rtl/ip/usb/usb2_scheduler.sv",
"text": "s_err_info_d = {16'd0, s_current_role, 9'd0, s_current_direction_in, s_current_index};"
}
]
},
{
"id": "jpeg-dma-status",
"title": "JPEG first error record",
"family": "jpeg",
"registers": [
"main.ERROR_STATUS",
"main.ERROR_DETAIL"
],
"observation": "Capture ERROR_ADDRESS, ring position and descriptor status with the error code/stage.",
"handling": "Record the first failure before acknowledgement. Slot 6 has bounded normal admission; drain/recovery and complete system qualification remain separate requirements.",
"link": "jpeg",
"sources": [
"rtl/ip/multimedia/jpeg_reg.sv",
"rtl/ip/multimedia/jpeg_pkg.sv"
]
},
{
"id": "apu-dma-status",
"title": "APU first error record",
"family": "apu",
"registers": [
"main.ERROR_STATUS",
"main.ERROR_DETAIL"
],
"observation": "Capture ERROR_ADDRESS, ring position and stream state. The enum covers the declared ABI; production availability is qualified in the APU/system chapters.",
"handling": "Preserve error details before W1C; recover descriptor/stream ownership under the APU contract.",
"link": "apu",
"sources": [
"rtl/ip/multimedia/apu_reg.sv",
"rtl/ip/multimedia/apu_define.svh"
]
},
{
"id": "extension-dma-status",
"title": "EXT-H DMA and slot fault",
"family": "extensions",
"registers": [
"main.Fault",
"main.DmaStatus"
],
"observation": "FAULT is sticky; DMA_STATUS contains busy, a completion pulse and fault. Capture FAULT_ADDRESS. EXT-L reads zero in its DMA status view.",
"handling": "The slot COMMAND clear operation controls the sticky fault; DMA done is a pulse, not a W1C completion register. Preserve software completion state before it disappears.",
"link": "ext-h",
"sources": [
"rtl/mini/top/extension_slot.sv",
"rtl/mini/top/extension_dma_master.sv"
],
"field_overrides": {
"main.DmaStatus": [
{
"lsb": 0,
"msb": 0,
"name": "BUSY",
"description": "EXT-H DMA busy."
},
{
"lsb": 1,
"msb": 1,
"name": "DONE_PULSE",
"description": "EXT-H one-cycle DMA completion observation; software must account for the interrupt/handler timing."
},
{
"lsb": 2,
"msb": 2,
"name": "FAULT",
"description": "EXT-H sticky slot/DMA fault. EXT-L returns zero for this whole register."
}
]
},
"bindings": [
{
"file": "rtl/mini/top/extension_slot.sv",
"text": "s_apb4_rdata_d = KindExtH ? {29'd0, s_fault_sticky_q, dma_done_i, dma_busy_i} : 32'd0;"
}
]
}
],
"verification": [
{
"id": "integration-source",
"title": "Topology, register and reset contracts",
"stage": "source",
"status": "Source reviewed",
"tests": [],
"profiles": [
"configs/ci/ihp130.mk",
"configs/ci/ihp130-hp.mk"
],
"sources": [
"rtl/mini/integration/soc_topology.json",
"rtl/mini/integration/clock_reset_domains.json",
"publications/datasheets/register-profiles.json"
],
"boundary": "Static source-derived mappings; no runtime result is implied.",
"limitations": "Generated HP artifact/cache capacity remains unconfirmed.",
"reports": []
},
{
"id": "host-tools",
"title": "Host software and tooling tests",
"stage": "host",
"status": "Tests available",
"tests": [
"tests/c/test_runtime.c",
"tests/test_hp_boot_bundle.py",
"tests/test_publication_programming.py"
],
"profiles": [
"configs/ci/ihp130.mk",
"configs/ci/ihp130-hp.mk"
],
"sources": [
"tests/README.md",
"docs/engineering.md"
],
"boundary": "Host logic and compiled-helper checks do not exercise MMIO timing or actual board devices.",
"limitations": "Publication-turn test results are delivered separately from product qualification.",
"reports": []
},
{
"id": "fabric",
"title": "Bus, clocks and resource behavior",
"stage": "simulation",
"status": "Tests available",
"tests": [
"tests/test_axi4.py",
"tests/test_clock_reset_domains.py",
"tests/test_resource_controller.py"
],
"profiles": [
"configs/ci/ihp130.mk",
"configs/ci/ihp130-hp.mk"
],
"sources": [
"docs/axi4-interconnect.md",
"docs/ip/resource-controller.md"
],
"boundary": "Directed unit/component tests exist; selected test invocation and source/profile must accompany a run.",
"limitations": "JPEG master 6 has bounded transport of one normal read and one normal write credit at class 8; end-to-end producer/consumer workloads, contention, cache ownership, and board performance remain unqualified.",
"reports": []
},
{
"id": "boot",
"title": "HP platform and boot image path",
"stage": "simulation",
"status": "Tests available",
"tests": [
"tests/test_hp_boot_bundle.py",
"tests/test_hp_platform.py",
"tests/test_hp_mailbox.py",
"tests/test_plic.py"
],
"profiles": [
"configs/ci/ihp130-hp.mk"
],
"sources": [
"docs/ip/hp-platform.md"
],
"boundary": "Image/layout and platform tests are not a recorded complete Linux boot on this publication profile.",
"limitations": "Boot-ready waiting and driver-support qualifications still apply.",
"reports": []
},
{
"id": "peripheral",
"title": "Storage, multimedia and private DMA",
"stage": "simulation",
"status": "Tests available",
"tests": [
"tests/test_dma.py",
"tests/test_sdram.py",
"tests/test_usb2.py",
"tests/test_jpeg.py",
"tests/test_apu.py"
],
"profiles": [
"configs/ci/ihp130.mk",
"configs/ci/ihp130-hp.mk"
],
"sources": [
"docs/ip/jpeg.md",
"docs/ip/apu.md"
],
"boundary": "Standalone engine coverage must be distinguished from an integrated producer-to-consumer path.",
"limitations": "JPEG integration and APU production-feature limits remain active.",
"reports": []
},
{
"id": "physical-analysis",
"title": "Synthesis, netlist and static timing",
"stage": "physical-analysis",
"status": "Tests available",
"tests": [
"scripts/regress.py",
"physical/smoke/syn/yosys/script/synth.tcl",
"physical/smoke/sta/opensta/opensta.tcl"
],
"profiles": [
"configs/ci/ihp130.mk"
],
"sources": [
"physical/README.md",
"docs/engineering.md"
],
"boundary": "Flows must report PDK, tools, constraints, corner and exact implementation.",
"limitations": "No matching physical signoff report is attached.",
"reports": []
},
{
"id": "fpga-board",
"title": "Board routes and FPGA bringup",
"stage": "fpga",
"status": "Not supplied",
"tests": [],
"profiles": [
"configs/ci/ihp130.mk",
"configs/ci/ihp130-hp.mk"
],
"sources": [
"fpga/README.md",
"fpga/mini/starrysky_v2.xdc"
],
"boundary": "The XDC is an input for its named FPGA board, not a pass report or an ASIC package map.",
"limitations": "Approved SDIO1/ULPI routes and matching board acceptance evidence remain missing.",
"reports": []
},
{
"id": "silicon",
"title": "Silicon, package and characterization",
"stage": "silicon",
"status": "Not supplied",
"tests": [],
"profiles": [
"configs/ci/ihp130.mk"
],
"sources": [
"physical/README.md"
],
"boundary": "Requires identified die/revision/lot, package, board, methods and test conditions.",
"limitations": "No measured DC/AC, power, thermal, reliability or orderable-part qualification is attached.",
"reports": []
}
],
"sources": [
"publications/retrieval_reference.py",
"rtl/rtl_readiness.json",
"scripts/check_rtl_readiness.py",
"app/apps/hp_boot/main.c",
"app/apps/hp_boot/hp_boot_bundle.h",
"crt/src/service/test.c",
"crt/src/hal/sysctrl.c",
"rtl/ip/peripheral/sysctrl_define.svh",
"rtl/mini/dv/tb/retrosoc_tb.sv",
"rtl/mini/dv/verilator/csrc/Emulator.cpp",
"scripts/regress.py",
"scripts/run_flow.py",
"docs/engineering.md",
"tests/test_publication_retrieval.py"
],
"boot": {
"expected_direct": [
2,
3,
4,
9,
9,
10,
11,
12,
13,
14,
15,
16,
17,
17
],
"expected_entries": 4,
"meanings": {
"0": "Linux-ready and P5 GA2D mailbox/cache-clean handoff completed; successful terminal status.",
"1": "UART initialization failed; terminal failure is written directly without requiring a printable console.",
"2": "HP hold/reset/debug-selection/presence prerequisite failed.",
"3": "SDRAM did not reach the required ready/error-free state within the firmware wait.",
"4": "Bundle header or bounds/format validation failed.",
"5": "DMA and software copy/CRC fallback failed for bundle entry index 0.",
"6": "DMA and software copy/CRC fallback failed for bundle entry index 1.",
"7": "DMA and software copy/CRC fallback failed for bundle entry index 2.",
"8": "DMA and software copy/CRC fallback failed for bundle entry index 3.",
"9": "Mailbox probe, LP-owned idle check, GA2D handoff to HP, or HP-owned idle confirmation failed.",
"10": "LP interrupt clear, HP release request, or released-state check failed.",
"11": "The expected Linux-ready mailbox event/argument/sequence was not received.",
"12": "The P5 GA2D start mailbox command could not be sent to HP.",
"13": "The expected P5 GA2D FILL/COPY-subset completion mailbox event/argument/sequence was not received.",
"14": "GA2D did not return to the expected HP-owned safe idle state after the P5 FILL/COPY-subset job.",
"15": "The request to hold HP after P5 GA2D completion returned an unexpected error.",
"16": "Cache-clean request, P5 GA2D cache mailbox event, clean acknowledgement, or HP-held confirmation failed.",
"17": "GA2D handoff back to LP or LP-owned safe-idle confirmation failed."
}
}
},
"software": {
"sources": [
"app/apps/bringup/app.mk",
"app/apps/bringup/main.c",
"app/apps/ci_smoke/app.mk",
"app/apps/ci_smoke/main.c",
"app/apps/debug/app.mk",
"app/apps/debug/startup.S",
"app/apps/hp_boot/app.mk",
"app/apps/hp_boot/hp_boot_bundle.h",
"app/apps/hp_boot/main.c",
"app/apps/xpi_flash_loader/app.mk",
"app/apps/xpi_flash_loader/startup.S",
"app/ports/linux/linux/retrosoc_hp.config",
"app/ports/linux/linux/retrosoc_hp.dts",
"app/ports/linux/opensbi/retrosoc_hp/platform.c",
"app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp",
"crt/arch/riscv/startup.S",
"crt/arch/riscv/system_irq.S",
"crt/include/retrosoc/arch/riscv/system_csr.h",
"crt/include/retrosoc/core/irq.h",
"crt/linker/jtag_sram.lds",
"crt/linker/ld2_all_sram.lds",
"crt/linker/ld2_psram.lds",
"crt/linker/ld2_sram.lds",
"crt/src/core/archinfo.c",
"crt/src/core/irq.c",
"crt/src/core/irq_nocsr.c",
"crt/src/core/system_irq_handler.c",
"crt/src/hal/crypto.c",
"crt/src/hal/sdio.c",
"crt/src/hal/usb2.c",
"crt/src/service/test.c",
"publications/datasheets/mini.json",
"rtl/mini/integration/soc_topology.json",
"rtl/mini/mk/software.mk",
"scripts/build_hp_linux.py",
"scripts/regress.py"
],
"bindings": [
{
"id": "csr-selection",
"file": "rtl/mini/mk/software.mk",
"text": "ifeq ($(HAVE_CSR),YES)\nDEF_VAL += -DCSR_ENABLE\nendif"
},
{
"id": "irq-objects",
"file": "rtl/mini/mk/software.mk",
"text": "ifeq ($(HAVE_CSR),YES)\nCRT_SRCS += $(ROOT_PATH)/crt/arch/riscv/system_irq.S\nCRT_SRCS += $(ROOT_PATH)/crt/src/core/system_irq_handler.c\nCRT_SRCS += $(ROOT_PATH)/crt/src/core/irq.c"
},
{
"id": "app-override",
"file": "rtl/mini/mk/software.mk",
"text": "ifneq ($(strip $(APP_CRT_SRCS)),)\nCRT_SRCS := $(APP_CRT_SRCS)\nendif"
},
{
"id": "trap-before-memory",
"file": "crt/arch/riscv/startup.S",
"text": "_start:\n#ifdef CSR_ENABLE"
},
{
"id": "direct-trap-mode",
"file": "crt/arch/riscv/startup.S",
"text": "la t0, system_trap_entry\ncsrw CSR_MTVEC, t0"
},
{
"id": "psram-wait",
"file": "crt/arch/riscv/startup.S",
"text": "PSRAM_READY_WAIT:\nli t0, PSRAM_STATUS\nlw t1, 0(t0)\nandi t1, t1, PSRAM_READY\nbeqz t1, PSRAM_READY_WAIT"
},
{
"id": "psram-pin-mask",
"file": "crt/arch/riscv/startup.S",
"text": ".equ BIT_MASK, 0x3FE00000"
},
{
"id": "initial-stack",
"file": "crt/arch/riscv/startup.S",
"text": "la x2, _stack_point"
},
{
"id": "code-copy",
"file": "crt/arch/riscv/startup.S",
"text": "la a0, _ram_lma\nla a1, _ram_vma\nbeq a0, a1, data_loader_start"
},
{
"id": "data-copy",
"file": "crt/arch/riscv/startup.S",
"text": "la a0, _psram_lma\nla a1, _psram_vma\nbeq a0, a1, bss_cleaner_start"
},
{
"id": "bss",
"file": "crt/arch/riscv/startup.S",
"text": "bss_cleaner:\nsw zero, 0(a0)\naddi a0, a0, 4\nblt a0, a1, bss_cleaner"
},
{
"id": "premain",
"file": "crt/arch/riscv/startup.S",
"text": "main_start:\n# call main\n#ifdef CSR_ENABLE\ncall _premain_init # init irq\n#endif\ncall main\nloop:\nj loop"
},
{
"id": "debug-start",
"file": "app/apps/debug/startup.S",
"text": "_start:\nla sp, _stack_point\ncall main\n1:\nj 1b"
},
{
"id": "loader-start",
"file": "app/apps/xpi_flash_loader/startup.S",
"text": "la a0, _sbss\nla a1, _ebss"
},
{
"id": "loader-return",
"file": "app/apps/xpi_flash_loader/startup.S",
"text": "2:\ncall main\n3:\nebreak\nj 3b"
},
{
"id": "trap-save",
"file": "crt/arch/riscv/system_irq.S",
"text": "system_trap_entry:\nSAVE_CONTEXT\nSAVE_CSR_CONTEXT"
},
{
"id": "trap-call",
"file": "crt/arch/riscv/system_irq.S",
"text": "csrr a0, mcause\nmv a1, sp"
},
{
"id": "trap-return",
"file": "crt/arch/riscv/system_irq.S",
"text": "call system_trap_handler\nRESTORE_CSR_CONTEXT\nRESTORE_CONTEXT\nmret"
},
{
"id": "handler-init",
"file": "crt/src/core/system_irq_handler.c",
"text": "rs_irq_init_tables();\n__enable_all_counter();",
"function": "_premain_init"
},
{
"id": "exception-loop",
"file": "crt/src/core/system_irq_handler.c",
"text": "for (;;) { }",
"function": "rs_default_exception"
},
{
"id": "external-dispatch",
"file": "crt/src/core/system_irq_handler.c",
"text": "if (id == IRQ_M_EXT) { rs_irq_dispatch_external(mcause, stack_pointer); }",
"function": "system_trap_handler"
},
{
"id": "enable-order",
"file": "crt/src/core/system_irq_handler.c",
"text": "const rs_status_t status = rs_irq_register_core(id, handler);",
"function": "rs_irq_enable_core"
},
{
"id": "global-enable-separate",
"file": "crt/src/core/irq.c",
"text": "__enable_irq();",
"function": "irq_test"
},
{
"id": "linux-single-hart",
"file": "app/ports/linux/opensbi/retrosoc_hp/platform.c",
"text": ".hart_count = 1U,"
},
{
"id": "aclint-index-range",
"file": "app/ports/linux/opensbi/retrosoc_hp/platform.c",
"text": ".first_hartid = 0U,\n.hart_count = 2U,"
},
{
"id": "sbi-console",
"file": "app/ports/linux/opensbi/retrosoc_hp/platform.c",
"text": "sbi_console_set_device(&s_console);",
"function": "retrosoc_hp_early_init"
},
{
"id": "sbi-serial-poll",
"file": "app/ports/linux/opensbi/retrosoc_hp/platform.c",
"text": "while ((retrosoc_hp_uart_read(RETROSOC_HP_UART_STATUS_REG) & RETROSOC_HP_UART_TX_FULL) != 0U) { }",
"function": "retrosoc_hp_console_putc"
},
{
"id": "sbi-timer",
"file": "app/ports/linux/opensbi/retrosoc_hp/platform.c",
"text": "return aclint_mtimer_cold_init(&s_mtimer, NULL);",
"function": "retrosoc_hp_timer_init"
},
{
"id": "sbi-mswi",
"file": "app/ports/linux/opensbi/retrosoc_hp/platform.c",
"text": "return aclint_mswi_cold_init(&s_mswi);",
"function": "retrosoc_hp_early_init"
},
{
"id": "kernel-sbi",
"file": "app/ports/linux/linux/retrosoc_hp.config",
"text": "CONFIG_SMP=n\nCONFIG_PRINTK=y\nCONFIG_TTY=y\nCONFIG_BINFMT_ELF=y\nCONFIG_BINFMT_SCRIPT=y\nCONFIG_HVC_RISCV_SBI=y\nCONFIG_SERIAL_EARLYCON_RISCV_SBI=y"
},
{
"id": "kernel-ready-support",
"file": "app/ports/linux/linux/retrosoc_hp.config",
"text": "CONFIG_DEVMEM=y"
},
{
"id": "initrd-patch",
"file": "scripts/build_hp_linux.py",
"text": "initrd_end = LAYOUT[\"rootfs.cpio.gz\"][0] + rootfs_source.stat().st_size"
},
{
"id": "sbi-entry",
"file": "scripts/build_hp_linux.py",
"text": "\"FW_TEXT_START=0x38000000\",\n\"FW_JUMP=y\",\n\"FW_JUMP_ADDR=0x38400000\",\n\"FW_JUMP_FDT_ADDR=0x38080000\","
},
{
"id": "ready-log",
"file": "app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp",
"text": "echo \"retroSoC HP Linux ready\""
},
{
"id": "smoke-selection",
"file": "scripts/regress.py",
"text": "CI_SMOKE_APP_VALUE = \"APP=ci_smoke\""
},
{
"id": "usb-test-irq",
"file": "crt/src/hal/usb2.c",
"text": "const uint32_t test_irq = RS_USB2_IRQ_FATAL;",
"function": "rs_usb2_controller_selftest"
},
{
"id": "usb-idle",
"file": "crt/src/hal/usb2.c",
"text": "if ((rs_usb2_read(RS_USB2_REG_GLOBAL_STATUS) & RS_USB2_GLOBAL_STATUS_BUSY) != 0U) { return RS_EIO; }",
"function": "rs_usb2_controller_selftest"
},
{
"id": "usb-preserve-old-irq",
"file": "crt/src/hal/usb2.c",
"text": "if ((irq_before & test_irq) == 0U) { rs_usb2_write(RS_USB2_REG_IRQ_STATUS, test_irq); }",
"function": "rs_usb2_controller_selftest"
},
{
"id": "sdio-caps",
"file": "crt/src/hal/sdio.c",
"text": "(capability & (RS_SDIO_CAP_PIO | RS_SDIO_CAP_CRC)) != (RS_SDIO_CAP_PIO | RS_SDIO_CAP_CRC)",
"function": "rs_sdio_controller_selftest"
},
{
"id": "sdio-test-irq",
"file": "crt/src/hal/sdio.c",
"text": "result = rs_sdio_irq_test(instance, RS_SDIO_IRQ_CMD_DONE);",
"function": "rs_sdio_controller_selftest"
},
{
"id": "crypto-aes",
"file": "crt/src/hal/crypto.c",
"text": "rs_crypto_aes_crypt(RS_CRYPTO_AES_ECB, false, NULL, Plaintext, output, sizeof(Plaintext), timeout)",
"function": "rs_crypto_selftest"
},
{
"id": "crypto-sha",
"file": "crt/src/hal/crypto.c",
"text": "rs_crypto_sha2(true, Message, sizeof(Message), output, timeout)",
"function": "rs_crypto_selftest"
},
{
"id": "crypto-zero",
"file": "crt/src/hal/crypto.c",
"text": "if (rs_crypto_zeroize() != RS_OK) { result = RS_EIO; }",
"function": "rs_crypto_selftest"
},
{
"id": "smoke-apu-discovery",
"file": "app/apps/ci_smoke/main.c",
"text": "(info.abi_digest == RS_APU_DIGEST_IMPLEMENTED)",
"function": "rs_ci_smoke_apu"
},
{
"id": "smoke-rng-boundary",
"file": "app/apps/ci_smoke/main.c",
"text": "return rs_rng_read_entropy(&entropy, RS_TIMEOUT_DEFAULT) == RS_ENOTSUP;",
"function": "rs_ci_smoke_rng_v2"
},
{
"id": "smoke-gpio-pin",
"file": "app/apps/ci_smoke/main.c",
"text": "rs_gpio_configure(31U, &config)",
"function": "rs_ci_smoke_gpio_v2"
},
{
"id": "smoke-sdram-span",
"file": "app/apps/ci_smoke/main.c",
"text": "#define RS_CI_SMOKE_SDRAM_SPAN UINT32_C(16)"
}
],
"runtime_profiles": [
"configs/ci/ihp130.mk",
"configs/ci/ihp130-hp.mk",
"configs/ci/ihp130-debug.mk",
"configs/ci/ihp130-xpi-flash-loader.mk"
],
"applications": [
{
"id": "bringup",
"title": "Bringup application",
"source": "app/apps/bringup/main.c",
"profiles": [
"configs/ci/ihp130.mk"
],
"selection": "Default APP=bringup in the publication reference profile.",
"prerequisites": "Complete generic LP startup and memory initialization; provide the reviewed peripheral configuration and LP ownership. The routine changes interrupt-test and Crypto state.",
"stages": [
{
"id": "uart",
"title": "Initialize UART0",
"kind": "return",
"code": 1,
"trigger": "rs_uart_init(",
"coverage": "Initialize the LP diagnostic console.",
"boundary": "Failure returns from main without writing TEST_STATUS; generic CRT then loops."
},
{
"id": "sdio",
"title": "SDIO0 controller discovery / IRQ",
"kind": "test-fail",
"code": 1,
"trigger": "rs_sdio_controller_selftest(",
"coverage": "Probe controller, check PIO/CRC capability and presence; inject/read/clear CMD_DONE.",
"boundary": "Does not initialize an SD card or transfer card data."
},
{
"id": "usb",
"title": "USB2 controller discovery / IRQ",
"kind": "test-fail",
"code": 2,
"trigger": "rs_usb2_controller_selftest(",
"coverage": "Probe the controller, require idle and observe an injected fatal-status IRQ.",
"boundary": "Does not enumerate a device or exercise a ULPI packet transfer."
},
{
"id": "crypto",
"title": "Crypto known-answer self-test",
"kind": "test-fail",
"code": 3,
"trigger": "rs_crypto_selftest(",
"coverage": "AES-128 ECB encryption and SHA-256 known answers, followed by zeroization.",
"boundary": "Does not cover every AES mode, SHA variant, RSA or streaming/DMA combination."
},
{
"id": "complete",
"title": "Completed selected checks",
"kind": "test-pass",
"code": 0,
"trigger": "rs_test_finish(RS_TEST_FAILED,3U)",
"coverage": "All preceding terminal checks returned success.",
"boundary": "ARCHINFO diagnostic text has no separately propagated terminal result in this application."
}
]
},
{
"id": "ci_smoke",
"title": "CI smoke application",
"source": "app/apps/ci_smoke/main.c",
"profiles": [
"configs/ci/ihp130.mk"
],
"selection": "Selected by the regression runner with APP=ci_smoke on the selected supported profile; not the default reference application.",
"prerequisites": "Reserve the scratch SRAM/SDRAM regions and GPIO31, stop competing users and use the matching PRODUCT map. Source-present checks are not an instruction to run this destructive scratch test on a live workload.",
"stages": [
{
"id": "uart-init",
"title": "Initialize UART0",
"kind": "test-fail",
"code": 6,
"trigger": "rs_uart_init(",
"coverage": "Initialize the console.",
"boundary": "Failure can precede usable UART output."
},
{
"id": "uart-loopback",
"title": "UART v3 loopback",
"kind": "test-fail",
"code": 7,
"trigger": "rs_ci_smoke_uart_v3(",
"coverage": "Check version/capability; transmit and receive one internal-loopback byte; restore console configuration.",
"boundary": "No board TX/RX or hardware-flow-control qualification."
},
{
"id": "identity",
"title": "ARCHINFO and RTC probe",
"kind": "test-fail",
"code": 1,
"trigger": "rs_ci_smoke_archinfo_v2(",
"coverage": "Validate build identity, expected unsupported device-ID read and RTC probe.",
"boundary": "No unique silicon identity or RTC accuracy qualification."
},
{
"id": "external-irq",
"title": "Hazard3 external IRQ dispatch",
"kind": "test-fail",
"code": 15,
"trigger": "rs_ci_smoke_external_irq(",
"coverage": "Exercise Xh3irq ordinals 0/15/16/29/30/31/32/61, invalid 62, priority/masking, no-handler masking, timer/software coexistence, and handler entry/return.",
"boundary": "Only the CSR-enabled build exercises dispatch; the physical P5 GA2D route is covered by the following stage."
},
{
"id": "monitor-start",
"title": "Start Fabric Monitor",
"kind": "test-fail",
"code": 13,
"trigger": "rs_ci_smoke_fabric_monitor_start(",
"coverage": "Clear and enable monitoring before the GA2D direct-DMA and later memory traffic.",
"boundary": "Code 13 also identifies the later monitor-observation stage."
},
{
"id": "ga2d-p5-composition-dma",
"title": "GA2D P5 direct 2D composition and IRQ route",
"kind": "test-fail",
"code": 15,
"trigger": "rs_ci_smoke_ga2d_irq(",
"coverage": "Discover P5 capability, submit direct single-job FILL/COPY/CONVERT/BLEND work through master 8, including A8 fixed-color foreground masks and exact equal background/destination in-place composition, verify the resource-owned LP external completion route, and inspect destinations.",
"boundary": "Exercises the direct private-AXI64 P5 functional subset only; it does not cover transparent-background/premultiplied-alpha modes, scaling, rendering, descriptor/ring/queue submission, cache coherency, a Linux graphics driver, HP P5 composition acceptance, or physical performance."
},
{
"id": "apu",
"title": "APU discovery",
"kind": "test-fail",
"code": 14,
"trigger": "rs_ci_smoke_apu(",
"coverage": "Compare APU discovery capabilities and ABI digest.",
"boundary": "No production codec job is submitted."
},
{
"id": "sram",
"title": "SRAM discovery and memory accesses",
"kind": "test-fail",
"code": 12,
"trigger": "rs_ci_smoke_onchip_sram(",
"coverage": "Check presence/size/banks; exercise byte/halfword/word lanes and boundary storage when present.",
"boundary": "Writes scratch memory; not an exhaustive memory or ECC test. Code 12 is also used by USB2."
},
{
"id": "monitor-check",
"title": "Inspect Fabric Monitor",
"kind": "test-fail",
"code": 13,
"trigger": "rs_ci_smoke_fabric_monitor_check(",
"coverage": "Snapshot LP/target traffic and require nonzero reads/writes without recorded fault or flush.",
"boundary": "No throughput, latency or long-run fault-coverage claim."
},
{
"id": "extensions",
"title": "PRODUCT extension control",
"kind": "test-fail",
"code": 11,
"trigger": "rs_ci_smoke_extensions(",
"coverage": "Probe EXT-L/H, reject MPW selection and EXT-L ACL configuration; exercise EXT-H ACL/lifecycle.",
"boundary": "Does not execute an EXT-H DMA workload."
},
{
"id": "rng",
"title": "RNG diagnostic source",
"kind": "test-fail",
"code": 8,
"trigger": "rs_ci_smoke_rng_v2(",
"coverage": "Read changing diagnostic words, check source state and expected entropy rejection.",
"boundary": "Does not qualify entropy or cryptographic randomness."
},
{
"id": "clint",
"title": "Management CLINT access",
"kind": "test-fail",
"code": 2,
"trigger": "rs_ci_smoke_clint_standard_map(",
"coverage": "Observe time progress; write/read compare and software-pending state; restore compare.",
"boundary": "Polling register behavior does not demonstrate trap-handler delivery."
},
{
"id": "timer0",
"title": "Timer0 one-shot",
"kind": "test-fail",
"code": 3,
"trigger": "rs_ci_smoke_timer_one_shot(",
"coverage": "Configure/start down-counting one-shot; poll stopped state and timeout/compare flags.",
"boundary": "No CPU ISR, waveform or pad timing measurement."
},
{
"id": "timer1",
"title": "Timer1 periodic",
"kind": "test-fail",
"code": 4,
"trigger": "rs_ci_smoke_timer_periodic(",
"coverage": "Configure up-counting periodic timer; poll timeout/compare flags and stop.",
"boundary": "No guaranteed interrupt latency or accuracy result."
},
{
"id": "gpio",
"title": "GPIO31 output controls",
"kind": "test-fail",
"code": 5,
"trigger": "rs_ci_smoke_gpio_v2(",
"coverage": "Check capabilities; configure, write, toggle and clear output 31.",
"boundary": "Changes a GPIO output; no independent external voltage/readback measurement."
},
{
"id": "sdram",
"title": "SDRAM scratch access",
"kind": "test-fail",
"code": 9,
"trigger": "rs_ci_smoke_sdram_access(",
"coverage": "Wait for ready; byte/halfword/word write and readback in the last 16 mapped bytes.",
"boundary": "Destructive scratch test; not an exhaustive device/timing test."
},
{
"id": "crypto",
"title": "Crypto known-answer self-test",
"kind": "test-fail",
"code": 10,
"trigger": "rs_crypto_selftest(",
"coverage": "Run the same AES/SHA/zeroization routine as bringup.",
"boundary": "Does not extend that routine to other algorithms or DMA paths."
},
{
"id": "usb",
"title": "USB2 controller self-test",
"kind": "test-fail",
"code": 12,
"trigger": "rs_usb2_controller_selftest(",
"coverage": "Run the same discovery/idle/IRQ test as bringup.",
"boundary": "Code 12 also identifies SRAM failures; retain stage logs."
},
{
"id": "complete",
"title": "Completed selected checks",
"kind": "test-pass",
"code": 0,
"trigger": "printf(\"ci_smoke:allperipheraltestspassed\\n\")",
"coverage": "All preceding selected checks passed.",
"boundary": "The printed summary covers this sequence, not every SoC peripheral or operating mode."
}
]
}
],
"api_semantics": [
{
"name": "rs_wait_mask",
"source": "crt/include/retrosoc/core/wait.h",
"body_sha256": "14f8fbc8e8654becac7c40e776098a2e62445468400d5578f070535e718c7b3a",
"budget": "At most timeout loop iterations/read attempts after input checks.",
"zero": "With valid input, return RS_ETIMEOUT without reading the register.",
"success": "A register sample satisfied the predicate: the masked register equals expected.",
"failure": "The helper performs no command, abort or reset. Its register reads can still have the target register's side effects.",
"next": "Check input validity and the owning IP state before retrying. A polling budget is not a wall-clock deadline."
},
{
"name": "rs_wait_value",
"source": "crt/include/retrosoc/core/wait.h",
"body_sha256": "2a38a2ad4befcb67b1b9fa9585b5ba67fa836bf77080b55e56a7ebb9d9679eea",
"budget": "At most timeout loop iterations/read attempts after input checks.",
"zero": "With valid input, return RS_ETIMEOUT without reading the register.",
"success": "A register sample satisfied the predicate: the register equals expected.",
"failure": "The helper performs no command, abort or reset. Its register reads can still have the target register's side effects.",
"next": "Check input validity and the owning IP state before retrying. A polling budget is not a wall-clock deadline."
},
{
"name": "rs_wait_not_value",
"source": "crt/include/retrosoc/core/wait.h",
"body_sha256": "34afe971625e3faef7eaef790260c84f63e5769e3beb8e7d940249f0f4108e7e",
"budget": "At most timeout loop iterations/read attempts after input checks.",
"zero": "With valid input, return RS_ETIMEOUT without reading the register.",
"success": "A register sample satisfied the predicate: the register differs from value.",
"failure": "The helper performs no command, abort or reset. Its register reads can still have the target register's side effects.",
"next": "Check input validity and the owning IP state before retrying. A polling budget is not a wall-clock deadline."
},
{
"name": "rs_uart_write",
"source": "crt/src/hal/uart.c",
"body_sha256": "ea54ac52b5e5835995715bc4456d51bf53718a21ed99a327f4231f549e3e8e04",
"budget": "One budget is shared across the call and consumed only while TX_FULL is observed.",
"zero": "Can write when FIFO space is immediately available; otherwise return RS_ETIMEOUT at the first required wait. Zero length succeeds.",
"success": "All requested bytes were written to TXDATA. The final serial bit need not have left the pin.",
"failure": "A prefix may already be queued or transmitted. No transferred-length result, automatic abort or rollback is returned.",
"next": "Use protocol-level framing and status before deciding what can be retried; blind replay can duplicate bytes."
},
{
"name": "rs_uart_read",
"source": "crt/src/hal/uart.c",
"body_sha256": "ff146e6746e27b576252c6e61b9dcbc056642b029edb3f048451bd0c813e0319",
"budget": "One budget is shared across the call and consumed only while RX_EMPTY is observed.",
"zero": "Can consume immediately available bytes; otherwise return RS_ETIMEOUT at the first required wait. Zero length succeeds.",
"success": "The requested number of RX entries was consumed and written into the caller buffer, including per-entry error bits.",
"failure": "Earlier entries may already have been popped and copied. The API does not return the completed prefix length.",
"next": "Validate entry error fields on success; use a protocol-aware receive/recovery policy after partial failure."
},
{
"name": "rs_dma_start",
"source": "crt/src/hal/dma.c",
"body_sha256": "159bc71910716dbdc95a6218282d98bd1fbdede26571d46ae870cf9bdd4ff5d0",
"budget": "No timeout argument; no completion polling.",
"zero": "Not applicable: no timeout parameter.",
"success": "For a valid channel, software cleared event flags and wrote START. It did not independently confirm command admission or completion.",
"failure": "An invalid channel is rejected locally; hardware may later report a command or transfer error.",
"next": "Observe channel status and completion/error records before consuming output or reusing buffers."
},
{
"name": "rs_dma_abort",
"source": "crt/src/hal/dma.c",
"body_sha256": "218dcfacb4d4af383b8f4dab44d3d4158f9cc580aeef690abbcdfcbea4a62749",
"budget": "No timeout argument; no drain polling.",
"zero": "Not applicable: no timeout parameter.",
"success": "For a valid channel, the ABORT command was written. Accepted transactions may still be draining.",
"failure": "The return does not confirm that BUSY is clear or that the buffer is reusable.",
"next": "Use rs_dma_abort_wait or an equivalent status/drain observation, then preserve completion and error details."
},
{
"name": "rs_dma_abort_wait",
"source": "crt/src/hal/dma.c",
"body_sha256": "ab0fcf5e54f87ab2d02064ce2f80c969474e6ea87769e3b327d69f76d626a80d",
"budget": "Send ABORT, then perform up to timeout status polls.",
"zero": "Still sends ABORT for a valid channel, then returns RS_ETIMEOUT without a status poll.",
"success": "A status read succeeded and BUSY was clear; it does not require a particular abort/error flag combination.",
"failure": "RS_ETIMEOUT does not establish that draining finished. The command has already been issued.",
"next": "Keep buffers owned until a later idle/drain confirmation; inspect the final reason flags separately."
},
{
"name": "rs_dma_wait",
"source": "crt/src/hal/dma.c",
"body_sha256": "4e256ff8cc97db4f4861e8c4f856135bfa4db4fbe97e8ebd9c18e8900a5e4125",
"budget": "Up to timeout status polls; error/aborted is tested before DONE.",
"zero": "For a valid channel, return RS_ETIMEOUT without reading status.",
"success": "A status sample showed DONE without the error or aborted flags.",
"failure": "Returns RS_EIO for an observed error/abort; exhaustion returns RS_ETIMEOUT without issuing ABORT.",
"next": "Retain ownership and inspect progress; if stopping is required, request abort and confirm drain before reusing storage."
},
{
"name": "rs_timer_delay_ms",
"source": "crt/src/hal/timer.c",
"body_sha256": "62c07d2e1581dceca825102377455044cffc7628b60fd09d3c462ce21b767868",
"budget": "milliseconds selects the hardware period; timeout independently bounds status-loop iterations.",
"zero": "Zero milliseconds succeeds for a valid timer. With a positive delay, zero timeout still configures/starts the timer, then attempts stop and returns RS_ETIMEOUT.",
"success": "Zero duration was requested, or a status sample showed the configured one-shot no longer active.",
"failure": "On loop exhaustion it calls rs_timer_stop, ignores that return and reports RS_ETIMEOUT. Earlier configuration/start errors do not provide a general rollback guarantee.",
"next": "This helper reconfigures the selected timer. Reserve it, and confirm state explicitly if recovery depends on successful stopping."
}
],
"boot_bundle": {
"sources": [
"scripts/package_hp_boot.py",
"app/apps/hp_boot/hp_boot_bundle.h",
"app/apps/hp_boot/main.c"
],
"loader_bindings": [
{
"source": "app/apps/hp_boot/main.c",
"function": "rs_hp_boot_crc32_byte",
"body_sha256": "b048241b3b6c9507a3d2b630af3ce8e4f2dbc0cdfbe662f76a8fce8ebe6037bc"
},
{
"source": "app/apps/hp_boot/main.c",
"function": "rs_hp_boot_crc32",
"body_sha256": "ee0d898baadc9da12772f6246b2f8b4635216fe68cf67e08793865d2ca40dc90"
},
{
"source": "app/apps/hp_boot/main.c",
"function": "rs_hp_boot_range_valid",
"body_sha256": "d9bdafe55cf55481f4a4b33e5ed41e73be9cf9f18a212c8acfcf20c46e0db4ed"
},
{
"source": "app/apps/hp_boot/main.c",
"function": "rs_hp_boot_entry_expected",
"body_sha256": "742ab68f51e33c801d28e5df8f18302f8a0651621868fb5e6ed64762b0734938"
},
{
"source": "app/apps/hp_boot/main.c",
"function": "rs_hp_boot_header_valid",
"body_sha256": "2409563cb2fb7bace28215f54f83189ecbd11c2257d1959be5aed5013d7c2905"
}
],
"header_fields": {
"magic": "Format marker written as a little-endian 32-bit word.",
"version": "Bundle format version; distinct from the datasheet revision.",
"header_size": "Bytes in the fixed header plus all entry descriptors.",
"entry_count": "Number of fixed-order artifact entries.",
"total_size": "Bundle-relative byte extent from BUNDLE_OFFSET through the aligned image end; includes gaps and padding.",
"header_crc32": "CRC of the complete header/entry area with this field zeroed.",
"flags": "Generator writes REQUIRED; loader requires its bit to be set.",
"reserved": "Generator writes zero; loader has no independent zero-value check for this field."
},
"entry_fields": {
"type": "Fixed artifact type in the expected OpenSBI, DTB, Linux, initramfs order.",
"flash_offset": "Absolute offset from the start of the flash image, not from the bundle header.",
"load_address": "Fixed destination address in the selected SDRAM map.",
"size": "Nonzero payload byte count; excludes alignment padding.",
"crc32": "CRC of exactly size payload bytes.",
"flags": "Generator writes REQUIRED; loader requires its bit to be set."
},
"rules": [
{
"topic": "Serialization",
"producer": "Little-endian 32-bit words, eight fixed-header words and six words per entry.",
"loader": "Copies the header into the RV32 C structure and interprets its words; no alternative byte-order negotiation.",
"consequence": "Use the declared byte format; do not serialize an arbitrary host structure with native packing."
},
{
"topic": "Entry identity",
"producer": "Four artifacts in fixed order, with the prescribed load address and maximum size for each.",
"loader": "Checks exact type/order/load address and the per-artifact maximum, plus nonzero size and mapped ranges.",
"consequence": "This is not a generic relocatable image table."
},
{
"topic": "Header and payload CRC",
"producer": "Computes the complete header CRC with its CRC word zero; computes each payload CRC before padding.",
"loader": "Zeroes the header CRC word in its local copy before comparison; payload checks follow the existing DMA/copy path.",
"consequence": "Padding bytes are not payload CRC input; CRC detects corruption, not origin or rollback."
},
{
"topic": "Address alignment",
"producer": "Aligns each payload start and the final cursor to PAYLOAD_ALIGNMENT.",
"loader": "Checks flash_offset and load_address modulo four, not the generator's larger boundary.",
"consequence": "Generated layout and accepted alignment are different conditions."
},
{
"topic": "Flags and reserved word",
"producer": "Writes flags=REQUIRED and fixed-header reserved=0.",
"loader": "Requires the REQUIRED bit in header and entries. Does not independently reject extra flag bits or nonzero reserved.",
"consequence": "Preserve canonical generator values; do not claim strict reserved-bit rejection."
},
{
"topic": "Payload placement and fill",
"producer": "Places payloads sequentially without overlap, filling unused image bytes with 0xFF.",
"loader": "Bounds each entry within the bundle/SDRAM ranges; does not independently enforce sequential disjoint extents or padding values.",
"consequence": "Do not confuse deterministic output layout with stronger validation that is absent from the loader."
},
{
"topic": "Capacity and length",
"producer": "Rejects LP firmware beyond the bundle start, empty/oversized payloads and an aligned image beyond FLASH_SIZE.",
"loader": "Checks header size/count, bundle total limits and each entry's source/destination bounds.",
"consequence": "Per-artifact maximum allocations do not mean all maximum-sized artifacts fit simultaneously in flash."
}
]
}
},
"illustrations": {
"schema_version": 1,
"sources": [
"app/apps/debug/startup.S",
"app/apps/hp_boot/hp_boot_bundle.h",
"app/apps/hp_boot/main.c",
"app/apps/xpi_flash_loader/startup.S",
"app/ports/linux/linux/retrosoc_hp.dts",
"configs/ci/ihp130-debug.mk",
"configs/ci/ihp130-hp.mk",
"configs/ci/ihp130-xpi-flash-loader.mk",
"configs/ci/ihp130.mk",
"crt/arch/riscv/startup.S",
"crt/include/retrosoc/hal/apu.h",
"crt/include/retrosoc/hal/dma.h",
"crt/include/retrosoc/hal/jpeg.h",
"crt/include/retrosoc/hal/sdio.h",
"crt/include/retrosoc/hal/sdio_regs.h",
"crt/include/retrosoc/hal/spisd_regs.h",
"crt/include/retrosoc/hal/usb2_regs.h",
"crt/linker/jtag_sram.lds",
"crt/linker/ld2_all_sram.lds",
"crt/linker/ld2_psram.lds",
"crt/linker/ld2_sram.lds",
"crt/src/hal/dma.c",
"crt/src/hal/ga2d_math.c",
"crt/src/hal/i2s_math.c",
"crt/src/hal/ws2812_math.c",
"crt/src/hal/xpi.c",
"docs/ip/apu.md",
"docs/ip/crypto.md",
"docs/ip/dma.md",
"docs/ip/dvp.md",
"docs/ip/i2c.md",
"docs/ip/i2s.md",
"docs/ip/jpeg.md",
"docs/ip/ps2.md",
"docs/ip/sdio.md",
"docs/ip/spisd.md",
"docs/ip/usb2.md",
"publications/api_bundle_reference.py",
"publications/datasheets/chapter-index.json",
"publications/datasheets/diagram-circuits.json",
"publications/datasheets/diagram-layouts.json",
"publications/datasheets/diagram-storage.json",
"publications/programming_reference.py",
"rtl/ip/memory/apb4_opipsram.sv",
"rtl/ip/memory/apb4_psram.sv",
"rtl/ip/memory/axi4_sdram.sv",
"rtl/ip/memory/opipsram_axi4.sv",
"rtl/ip/memory/opipsram_core.sv",
"rtl/ip/memory/opipsram_phy.sv",
"rtl/ip/memory/opipsram_protocol.sv",
"rtl/ip/memory/opipsram_reg.sv",
"rtl/ip/memory/psram_axi4.sv",
"rtl/ip/memory/psram_core.sv",
"rtl/ip/memory/psram_phy.sv",
"rtl/ip/memory/psram_pkg.sv",
"rtl/ip/memory/psram_reg.sv",
"rtl/ip/memory/sdram_axi4.sv",
"rtl/ip/memory/sdram_core.sv",
"rtl/ip/memory/sdram_reg.sv",
"rtl/ip/multimedia/apb4_apu.sv",
"rtl/ip/multimedia/apb4_ga2d.sv",
"rtl/ip/multimedia/apb4_jpeg.sv",
"rtl/ip/multimedia/apu_control_store.sv",
"rtl/ip/multimedia/apu_define.svh",
"rtl/ip/multimedia/apu_local_sram.sv",
"rtl/ip/multimedia/apu_microcode_loader.sv",
"rtl/ip/multimedia/apu_microcode_pkg.sv",
"rtl/ip/multimedia/apu_primitive_dispatcher.sv",
"rtl/ip/multimedia/axi4s_dvp.sv",
"rtl/ip/multimedia/dvp_core.sv",
"rtl/ip/multimedia/dvp_reg.sv",
"rtl/ip/multimedia/ga2d_axi4_master.sv",
"rtl/ip/multimedia/ga2d_core.sv",
"rtl/ip/multimedia/ga2d_dma.sv",
"rtl/ip/multimedia/ga2d_pixel.sv",
"rtl/ip/multimedia/ga2d_reg.sv",
"rtl/ip/multimedia/jpeg_coefficient_engine.sv",
"rtl/ip/multimedia/jpeg_decode_core.sv",
"rtl/ip/multimedia/jpeg_dma.sv",
"rtl/ip/multimedia/jpeg_encode_core.sv",
"rtl/ip/multimedia/jpeg_reg.sv",
"rtl/ip/multimedia/jpeg_table_store.sv",
"rtl/ip/peripheral/apb4_clint.sv",
"rtl/ip/peripheral/apb4_dma.sv",
"rtl/ip/peripheral/apb4_gpio.sv",
"rtl/ip/peripheral/apb4_hp_mailbox.sv",
"rtl/ip/peripheral/apb4_plic.sv",
"rtl/ip/peripheral/apb4_sysctrl.sv",
"rtl/ip/peripheral/apb4_timer.sv",
"rtl/ip/peripheral/clint_core.sv",
"rtl/ip/peripheral/clint_reg.sv",
"rtl/ip/peripheral/dma_core.sv",
"rtl/ip/peripheral/gpio_core.sv",
"rtl/ip/peripheral/gpio_reg.sv",
"rtl/ip/peripheral/sysctrl_core.sv",
"rtl/ip/peripheral/sysctrl_reg.sv",
"rtl/ip/peripheral/timer_core.sv",
"rtl/ip/peripheral/timer_reg.sv",
"rtl/ip/security/apb4_crypto.sv",
"rtl/ip/security/crypto_aes_engine.sv",
"rtl/ip/security/crypto_rsa_core.sv",
"rtl/ip/security/crypto_sha2_engine.sv",
"rtl/ip/serial/apb4_i2c.sv",
"rtl/ip/serial/apb4_i2c_define.svh",
"rtl/ip/serial/apb4_i2s.sv",
"rtl/ip/serial/apb4_uart.sv",
"rtl/ip/serial/apb4_uart_rx.sv",
"rtl/ip/serial/apb4_uart_tx.sv",
"rtl/ip/serial/apb4_ws2812.sv",
"rtl/ip/serial/i2c_core.sv",
"rtl/ip/serial/i2c_filter.sv",
"rtl/ip/serial/i2c_reg.sv",
"rtl/ip/serial/i2s_core.sv",
"rtl/ip/serial/i2s_reg.sv",
"rtl/ip/serial/uart_core.sv",
"rtl/ip/serial/uart_reg.sv",
"rtl/ip/serial/ws2812_core.sv",
"rtl/ip/serial/ws2812_reg.sv",
"rtl/ip/storage/apb4_sdio.sv",
"rtl/ip/storage/apb4_spisd.sv",
"rtl/ip/storage/apb4_xpi.sv",
"rtl/ip/storage/sdio_command.sv",
"rtl/ip/storage/sdio_core.sv",
"rtl/ip/storage/sdio_data.sv",
"rtl/ip/storage/sdio_pkg.sv",
"rtl/ip/storage/sdio_reg.sv",
"rtl/ip/storage/spisd_command.sv",
"rtl/ip/storage/spisd_core.sv",
"rtl/ip/storage/spisd_data.sv",
"rtl/ip/storage/spisd_pkg.sv",
"rtl/ip/storage/spisd_reg.sv",
"rtl/ip/storage/xpi_indirect.sv",
"rtl/ip/storage/xpi_mm.sv",
"rtl/ip/storage/xpi_pkg.sv",
"rtl/ip/storage/xpi_reg.sv",
"rtl/ip/usb/apb4_usb2.sv",
"rtl/ip/usb/usb2_dma.sv",
"rtl/ip/usb/usb2_link_domain.sv",
"rtl/ip/usb/usb2_packet_ram.sv",
"rtl/ip/usb/usb2_pkg.sv",
"rtl/ip/usb/usb2_reg.sv",
"rtl/ip/usb/usb2_scheduler.sv",
"rtl/ip/usb/usb2_sie_tx.sv",
"rtl/ip/usb/usb2_ulpi_link.sv",
"rtl/managed/clusterip/archinfo/rtl/apb4_archinfo.sv",
"rtl/managed/clusterip/archinfo/rtl/archinfo_reg.sv",
"rtl/managed/clusterip/common/rtl/cdc/async_reqack.sv",
"rtl/managed/clusterip/common/rtl/cdc/cdc_2phase.sv",
"rtl/managed/clusterip/common/rtl/cdc/cdc_fifo.sv",
"rtl/managed/clusterip/crc/rtl/apb4_crc.sv",
"rtl/managed/clusterip/crc/rtl/crc_reg.sv",
"rtl/managed/clusterip/ps2/rtl/apb4_ps2.sv",
"rtl/managed/clusterip/ps2/rtl/ps2_core.sv",
"rtl/managed/clusterip/ps2/rtl/ps2_reg.sv",
"rtl/managed/clusterip/pwm/rtl/apb4_pwm.sv",
"rtl/managed/clusterip/pwm/rtl/pwm_capture.sv",
"rtl/managed/clusterip/pwm/rtl/pwm_define.svh",
"rtl/managed/clusterip/pwm/rtl/pwm_reg.sv",
"rtl/managed/clusterip/rng/rtl/apb4_rng.sv",
"rtl/managed/clusterip/rng/rtl/rng_core.sv",
"rtl/managed/clusterip/rng/rtl/rng_reg.sv",
"rtl/managed/clusterip/rtc/rtl/apb4_rtc.sv",
"rtl/managed/clusterip/rtc/rtl/rtc_core.sv",
"rtl/managed/clusterip/rtc/rtl/rtc_reg.sv",
"rtl/managed/clusterip/wdg/rtl/apb4_wdg.sv",
"rtl/managed/clusterip/wdg/rtl/wdg_core.sv",
"rtl/managed/clusterip/wdg/rtl/wdg_reg.sv",
"rtl/managed/mpw/ip/username1/user_ip_design.sv",
"rtl/managed/mpw/ip/username2/user_ip_design.sv",
"rtl/mini/address_map/memory_map.json",
"rtl/mini/integration/clock_reset_domains.json",
"rtl/mini/integration/soc_topology.json",
"rtl/mini/pin_map/pin_map.json",
"rtl/mini/top/apb4_periph.sv",
"rtl/mini/top/apb4_system.sv",
"rtl/mini/top/axi4_bus.sv",
"rtl/mini/top/axi4_data_crossbar.sv",
"rtl/mini/top/axi4_mgmt_router.sv",
"rtl/mini/top/core_wrapper.sv",
"rtl/mini/top/extension_dma_master.sv",
"rtl/mini/top/extension_slot.sv",
"rtl/mini/top/extension_subsystem.sv",
"rtl/mini/top/fabric_monitor.sv",
"rtl/mini/top/hp_subsystem.sv",
"rtl/mini/top/memory_pad_mux.sv",
"rtl/mini/top/mgmt_debug_wrapper.sv",
"rtl/mini/top/onchip_ram.sv",
"rtl/mini/top/rcu.sv",
"rtl/mini/top/resource_controller.sv",
"rtl/mini/top/retrosoc.sv",
"rtl/mini/top/rib2axi4.sv",
"rtl/mini/top/soc_clock_reset_subsystem.sv",
"rtl/mini/top/soc_data_plane.sv",
"rtl/mini/top/user_core_top.sv",
"rtl/mini/top/user_ip_top.sv",
"rtl/mini/top/user_ip_wrapper.sv",
"scripts/apu_isa.py",
"scripts/package_hp_boot.py"
],
"bindings": [
{
"file": "rtl/ip/storage/sdio_command.sv",
"text": "s_tx_shift_d = { 1'b0, 1'b1, cmd_index_i, cmd_arg_i, sdio_pkg::sdio_crc7_calc({1'b0, 1'b1, cmd_index_i, cmd_arg_i}), 1'b1 };"
},
{
"file": "rtl/ip/storage/sdio_command.sv",
"text": "input logic [5:0] cmd_index_i"
},
{
"file": "rtl/ip/storage/sdio_command.sv",
"text": "input logic [31:0] cmd_arg_i"
},
{
"file": "rtl/ip/storage/sdio_command.sv",
"text": "? s_tx_shift_q[47] : 1'b1"
},
{
"file": "rtl/mini/top/apb4_periph.sv",
"text": ".NumChannels(8), .FifoDepth(32)"
},
{
"file": "rtl/ip/multimedia/apu_define.svh",
"text": "`define APB4_APU__APUMC_MAX_INSTRUCTIONS 2048"
},
{
"file": "crt/src/hal/dma.c",
"text": "current->crc_result = RS_DMA_CH_REG(channel, RS_DMA_CH_REG_CRC_RESULT);"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": "assign u_apu_rx_axis.tready = s_kws_rx_ready;"
}
],
"sdio_command": [
{
"name": "start",
"label": "S",
"lsb": 47,
"bits": 1
},
{
"name": "direction",
"label": "T",
"lsb": 46,
"bits": 1
},
{
"name": "command",
"label": "CMD",
"lsb": 40,
"bits": 6
},
{
"name": "argument",
"label": "ARG",
"lsb": 8,
"bits": 32
},
{
"name": "crc7",
"label": "CRC7",
"lsb": 1,
"bits": 7
},
{
"name": "end",
"label": "E",
"lsb": 0,
"bits": 1
}
],
"circuits": {
"uart0": {
"nodes": [
{
"id": "apb",
"title": "APB4 control\nregister interface",
"x": 0,
"y": 5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/serial/apb4_uart.sv"
],
"ports": [
{
"id": "out",
"side": "east",
"direction": "out",
"width": 32
}
]
},
{
"id": "reg",
"title": "Register bank\nTX / RX FIFOs",
"x": 6.3,
"y": 5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/serial/uart_reg.sv"
],
"ports": [
{
"id": "apb",
"side": "west",
"direction": "in",
"width": 32
},
{
"id": "tx",
"side": "east",
"direction": "out",
"width": 8
},
{
"id": "rx",
"side": "east",
"direction": "in",
"width": 12
},
{
"id": "level",
"side": "south",
"direction": "out",
"width": 7
}
],
"port_margins": {
"east": [
0,
25
]
}
},
{
"id": "core",
"title": "Baud generator\nTX / RX engines",
"x": 12.6,
"y": 5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/serial/uart_core.sv"
],
"ports": [
{
"id": "tx",
"side": "west",
"direction": "in",
"width": 8
},
{
"id": "rx",
"side": "west",
"direction": "out",
"width": 12
},
{
"id": "allow",
"side": "west",
"direction": "in",
"width": 1
},
{
"id": "txpad",
"side": "south",
"direction": "out",
"width": 1
},
{
"id": "rxpad",
"side": "south",
"direction": "in",
"width": 1
}
]
},
{
"id": "flow",
"title": "CTS synchronizer\nRTS / start control",
"x": 6.3,
"y": 1.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/serial/uart_flow_ctrl.sv"
],
"ports": [
{
"id": "cts",
"side": "west",
"direction": "in",
"width": 1
},
{
"id": "rts",
"side": "west",
"direction": "out",
"width": 1
},
{
"id": "level",
"side": "north",
"direction": "in",
"width": 7
},
{
"id": "allow",
"side": "east",
"direction": "out",
"width": 1
}
]
},
{
"id": "modem",
"title": "CTS_n / RTS_n\nGPIO alternate path",
"x": 0,
"y": 1.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/serial/apb4_uart.sv"
],
"ports": [
{
"id": "cts",
"side": "east",
"direction": "out",
"width": 1
},
{
"id": "rts",
"side": "east",
"direction": "in",
"width": 1
}
]
},
{
"id": "pads",
"title": "Dedicated\nTX / RX pads",
"x": 12.6,
"y": 1.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/serial/apb4_uart.sv"
],
"ports": [
{
"id": "tx",
"side": "north",
"direction": "in",
"width": 1
},
{
"id": "rx",
"side": "north",
"direction": "out",
"width": 1
}
]
}
],
"edges": [
{
"from": "apb.out",
"to": "reg.apb",
"label": "APB4 / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".apb4(apb4)"
}
]
},
{
"from": "reg.tx",
"to": "core.tx",
"label": "TX / 8",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".tx_data_o(s_tx_data)"
},
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".tx_data_i(s_tx_data)"
}
]
},
{
"from": "core.rx",
"to": "reg.rx",
"label": "RX / 12",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".rx_data_o(s_rx_data)"
},
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".rx_data_i(s_rx_data)"
}
]
},
{
"from": "reg.level",
"to": "flow.level",
"label": "LEVEL / 7",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".rx_level_o(s_rx_level)"
},
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".rx_level_i(s_rx_level)"
}
]
},
{
"from": "modem.cts",
"to": "flow.cts",
"label": "CTS_n",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".cts_n_async_i(uart.cts_n_i)"
}
]
},
{
"from": "flow.rts",
"to": "modem.rts",
"label": "RTS_n",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".rts_n_o(uart.rts_n_o)"
}
]
},
{
"from": "flow.allow",
"to": "core.allow",
"label": "START",
"kind": "control",
"style": "zigzag",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".tx_start_allowed_o(s_tx_start_allowed)"
},
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".tx_start_allowed_i(s_tx_start_allowed)"
}
]
},
{
"from": "core.txpad",
"to": "pads.tx",
"label": "TX",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".tx_o(s_tx)"
},
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": "assign uart.tx_o = s_tx;"
}
]
},
{
"from": "pads.rx",
"to": "core.rxpad",
"label": "RX",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/serial/apb4_uart.sv",
"text": ".rx_i(uart.rx_i)"
}
]
}
],
"note": "Selected functional paths. Data labels show payload width; dashed links are control. Clock/reset, full handshake and IRQ wiring are omitted for clarity."
},
"dma": {
"nodes": [
{
"id": "apb",
"title": "APB4 control\nregister interface",
"x": 0,
"y": 7,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/peripheral/apb4_dma.sv"
],
"ports": [
{
"id": "out",
"side": "south",
"direction": "out",
"width": 32
}
]
},
{
"id": "reg",
"title": "8 channel\nregister contexts",
"x": 0,
"y": 3.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/peripheral/dma_reg.sv"
],
"ports": [
{
"id": "apb",
"side": "north",
"direction": "in",
"width": 32
},
{
"id": "cfg",
"side": "east",
"direction": "out",
"width": 256
},
{
"id": "start",
"side": "east",
"direction": "out",
"width": 8
},
{
"id": "status",
"side": "east",
"direction": "in",
"width": 8
}
]
},
{
"id": "core",
"title": "Channel scheduling\nFIFO / CRC control",
"x": 6.3,
"y": 3.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/peripheral/dma_core.sv"
],
"ports": [
{
"id": "cfg",
"side": "west",
"direction": "in",
"width": 256
},
{
"id": "start",
"side": "west",
"direction": "in",
"width": 8
},
{
"id": "status",
"side": "west",
"direction": "out",
"width": 8
},
{
"id": "req",
"side": "east",
"direction": "out",
"width": 1
},
{
"id": "read",
"side": "east",
"direction": "in",
"width": 32
},
{
"id": "write",
"side": "east",
"direction": "out",
"width": 32
},
{
"id": "out",
"side": "south",
"direction": "out",
"width": 32
},
{
"id": "in",
"side": "south",
"direction": "in",
"width": 32
}
]
},
{
"id": "master",
"title": "AXI4 read/write\ntransaction engine",
"x": 12.6,
"y": 3.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/peripheral/dma_axi4_master.sv"
],
"ports": [
{
"id": "req",
"side": "west",
"direction": "in",
"width": 1
},
{
"id": "read",
"side": "west",
"direction": "out",
"width": 32
},
{
"id": "write",
"side": "west",
"direction": "in",
"width": 32
},
{
"id": "axi",
"side": "south",
"direction": "out",
"width": 32
}
]
},
{
"id": "streams",
"title": "I2S / DVP / Crypto\nstream endpoints",
"x": 6.3,
"y": 0,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/peripheral/apb4_dma.sv"
],
"ports": [
{
"id": "out",
"side": "north",
"direction": "in",
"width": 32
},
{
"id": "in",
"side": "north",
"direction": "out",
"width": 32
}
]
},
{
"id": "memory",
"title": "AXI32 gateway\nshared memory path",
"x": 12.6,
"y": 0,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/peripheral/apb4_dma.sv"
],
"ports": [
{
"id": "axi",
"side": "north",
"direction": "in",
"width": 32
}
]
}
],
"edges": [
{
"from": "apb.out",
"to": "reg.apb",
"label": "APB4 / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".apb4(apb4)"
}
]
},
{
"from": "reg.cfg",
"to": "core.cfg",
"label": "CFG / 8ch",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".ch_cfg_o(s_ch_cfg)"
},
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".ch_cfg_i(s_ch_cfg)"
}
]
},
{
"from": "reg.start",
"to": "core.start",
"label": "START",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".start_o(s_start)"
},
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".start_i(s_start)"
}
]
},
{
"from": "core.status",
"to": "reg.status",
"label": "BUSY",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".busy_o(s_busy)"
},
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".busy_i(s_busy)"
}
]
},
{
"from": "core.req",
"to": "master.req",
"label": "RD request",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/dma_core.sv",
"text": ".read_start_valid_i(s_axi_read_start_valid)"
}
]
},
{
"from": "master.read",
"to": "core.read",
"label": "READ / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/dma_core.sv",
"text": ".read_data_o(s_axi_read_data)"
}
]
},
{
"from": "core.write",
"to": "master.write",
"label": "WRITE / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/dma_core.sv",
"text": ".write_data_i(s_axi_write_data)"
}
]
},
{
"from": "master.axi",
"to": "memory.axi",
"label": "AXI4 / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/dma_core.sv",
"text": ".axi4(axi4)"
}
]
},
{
"from": "core.out",
"to": "streams.out",
"label": "TX / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".i2s_tx_axis(i2s_tx_axis)"
},
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".crypto_in_axis(crypto_in_axis)"
}
]
},
{
"from": "streams.in",
"to": "core.in",
"label": "RX / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".i2s_rx_axis(i2s_rx_axis)"
},
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".dvp_rx_axis(dvp_rx_axis)"
},
{
"file": "rtl/ip/peripheral/apb4_dma.sv",
"text": ".crypto_out_axis(crypto_out_axis)"
}
]
}
],
"note": "Functional grouping of the integrated eight-channel DMA. Stream ports aggregate the listed input/output endpoints; handshakes and the request map remain defined by the protocol chapter."
},
"apu": {
"nodes": [
{
"id": "reg",
"title": "APB4 registers\njob / lifecycle control",
"x": 0,
"y": 7,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apb4_apu.sv"
],
"ports": [
{
"id": "load",
"side": "east",
"direction": "out",
"width": 1
},
{
"id": "acl",
"side": "south",
"direction": "out",
"width": 32
}
]
},
{
"id": "loader",
"title": "Microcode loader\nheader / CRC checks",
"x": 6.3,
"y": 7,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apu_microcode_loader.sv"
],
"ports": [
{
"id": "load",
"side": "west",
"direction": "in",
"width": 1
},
{
"id": "data",
"side": "south",
"direction": "in",
"width": 32
},
{
"id": "store",
"side": "east",
"direction": "out",
"width": 64
}
]
},
{
"id": "store",
"title": "Control store\n4096 x 64 bits",
"x": 12.6,
"y": 7,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apu_control_store.sv"
],
"ports": [
{
"id": "write",
"side": "west",
"direction": "in",
"width": 64
},
{
"id": "fetch",
"side": "south",
"direction": "out",
"width": 64
}
]
},
{
"id": "dma",
"title": "Private DMA\nrequest arbitration\nring scheduler",
"x": 0,
"y": 3.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apb4_apu.sv"
],
"ports": [
{
"id": "acl",
"side": "north",
"direction": "in",
"width": 32
},
{
"id": "loader",
"side": "north",
"direction": "out",
"width": 32
},
{
"id": "read",
"side": "east",
"direction": "out",
"width": 32
},
{
"id": "write",
"side": "east",
"direction": "in",
"width": 32
}
],
"port_margins": {
"east": [
0,
25
]
}
},
{
"id": "transport",
"title": "Codec transport\nDMA / FIFO staging",
"x": 6.3,
"y": 3.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apu_codec_transport.sv"
],
"ports": [
{
"id": "read",
"side": "west",
"direction": "in",
"width": 32
},
{
"id": "write",
"side": "west",
"direction": "out",
"width": 32
},
{
"id": "fifo",
"side": "east",
"direction": "in",
"width": 41
},
{
"id": "stream",
"side": "west",
"direction": "out",
"width": 32
}
]
},
{
"id": "seq",
"title": "Bounded sequencer\npredicates / operands",
"x": 12.6,
"y": 3.5,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apu_codec_sequencer.sv"
],
"ports": [
{
"id": "fetch",
"side": "north",
"direction": "in",
"width": 64
},
{
"id": "instr",
"side": "south",
"direction": "out",
"width": 64
}
]
},
{
"id": "stream",
"title": "I2S stream router\nselected TX path",
"x": 0,
"y": 0,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apu_stream_router.sv"
],
"ports": [
{
"id": "tx",
"side": "east",
"direction": "in",
"width": 32
}
]
},
{
"id": "primitive",
"title": "Processing primitives\nlocal storage / FIFOs",
"x": 12.6,
"y": 0,
"w": 4.0,
"h": 1.8,
"sources": [
"rtl/ip/multimedia/apu_primitive_dispatcher.sv"
],
"ports": [
{
"id": "instr",
"side": "north",
"direction": "in",
"width": 64
},
{
"id": "fifo",
"side": "west",
"direction": "out",
"width": 41
}
]
}
],
"edges": [
{
"from": "reg.load",
"to": "loader.load",
"label": "LOAD",
"kind": "control",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".microcode_load_o(s_microcode_load)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".start_i(s_microcode_load)"
}
]
},
{
"from": "loader.store",
"to": "store.write",
"label": "WRITE / 64",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".store_data_o(s_store_write_data)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".loader_data_i(s_store_write_data)"
}
]
},
{
"from": "store.fetch",
"to": "seq.fetch",
"label": "FETCH / 64",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".fetch_data_o(s_seq_fetch_data)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".fetch_data_i(s_seq_fetch_data)"
}
]
},
{
"from": "reg.acl",
"to": "dma.acl",
"label": "ACL / 32",
"kind": "control",
"style": "zigzag",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".read_base_o(s_read_base)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".read_base_i(s_read_base)"
}
],
"zigzag-dir": "horizontal"
},
{
"from": "dma.loader",
"to": "loader.data",
"label": "MC read / 32",
"kind": "data",
"style": "zigzag",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".read_axis(u_dma_read_axis)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".dma_data_i(u_dma_read_axis.tdata)"
}
],
"zigzag-dir": "horizontal"
},
{
"from": "dma.read",
"to": "transport.read",
"label": "READ / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": "assign u_transport_read_axis.tdata = u_dma_read_axis.tdata;"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".dma_read_axis(u_transport_read_axis)"
}
]
},
{
"from": "transport.write",
"to": "dma.write",
"label": "WRITE / 32",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".dma_write_axis(u_transport_write_axis)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": "u_transport_write_axis.tdata : u_scheduler_write_axis.tdata;"
}
]
},
{
"from": "seq.instr",
"to": "primitive.instr",
"label": "INSTR / 64",
"kind": "data",
"style": "direct",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".primitive_instruction_o(s_primitive_instruction)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".instruction_i(s_primitive_instruction)"
}
]
},
{
"from": "primitive.fifo",
"to": "transport.fifo",
"label": "FIFO / 41",
"kind": "data",
"style": "zigzag",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".output_data_o(s_primitive_output_data)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".output_fifo_data_i(s_primitive_output_data)"
}
]
},
{
"from": "transport.stream",
"to": "stream.tx",
"label": "PCM / 32",
"kind": "data",
"style": "zigzag",
"bindings": [
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".tx_axis(u_apu_tx_axis)"
},
{
"file": "rtl/ip/multimedia/apb4_apu.sv",
"text": ".apu_tx_axis(u_apu_tx_axis)"
}
]
}
],
"note": "Selected loader, execution and TX paths. Request arbitration/ring control is grouped; detailed launch/status/return handshakes are not all shown. WAV/FLAC use the checked-in P5 image. KWS RX is connected internally but gated by EnableP7, which is false in default PRODUCT. MP3 and KWS are not publicly advertised; corpus and physical qualification remain separate."
}
},
"circuit_catalog": "publications/datasheets/diagram-circuits.json",
"layout_catalog": "publications/datasheets/diagram-layouts.json",
"storage_catalog": "publications/datasheets/diagram-storage.json",
"soc_architecture_catalog": "publications/datasheets/soc-architecture.json"
},
"ci_snapshot": {
"revision": "2a497ecef0b084c02f77ddfb1e94fb0197e14b02",
"checked_date": "2026-09-17",
"boundary": "Public GitHub workflow/job outcomes for this exact commit. Behavioral regression success is not synthesis, netlist, STA, formal, FPGA or silicon qualification. A failed prerequisite can leave later tests unexecuted.",
"runs": [
{
"name": "regression-ihp130",
"run_id": 35035899124,
"result": "success",
"scope": "IHP130 PR behavioral-only regression",
"note": "Run pr regression passed; formal environment step skipped. Synthesis/timing environment checks are setup checks, not physical results.",
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35035899124"
},
{
"name": "regression-gf180",
"run_id": 35035899130,
"result": "success",
"scope": "GF180 workflow",
"note": "Workflow outcome only; detailed stages require their own artifacts.",
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35035899130"
},
{
"name": "regression-ics55",
"run_id": 35035899146,
"result": "success",
"scope": "ICS55 workflow",
"note": "Workflow outcome only; detailed stages require their own artifacts.",
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35035899146"
},
{
"name": "regression-smoke",
"run_id": 35035899140,
"result": "success",
"scope": "Smoke workflow",
"note": "Does not qualify all peripheral use cases.",
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35035899140"
},
{
"name": "quality",
"run_id": 35035898949,
"result": "failure",
"scope": "Quality workflow",
"note": "Check source formatting failed. Later host tests, script tests and APU P5 acceptance were skipped.",
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35035898949"
},
{
"name": "regression-sky130",
"run_id": 35035899137,
"result": "failure",
"scope": "SKY130 PR workflow",
"note": "Run pr regression failed. Do not present this platform as passing.",
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35035899137"
}
]
}
}
Reference in new issue View Git Blame Copy Permalink