{ "schema_version": 1, "source_revision": "c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b", "sources": [ "Makefile", "app/README.md", "app/apps/apu_release/main.c", "app/apps/hp_boot/hp_boot_bundle.h", "app/apps/hp_boot/main.c", "app/ports/hp-apu/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-apu.mk", "configs/ci/ihp130-hp.mk", "configs/ci/ihp130.mk", "configs/cluster/mini-mpw.mk", "crt/README.md", "crt/include/retrosoc/hal/apu_regs.h", "crt/include/retrosoc/hal/ga2d.h", "crt/include/retrosoc/hal/npu.h", "crt/include/retrosoc/hal/npu_regs.h", "crt/include/retrosoc/hal/resource.h", "crt/include/retrosoc/hal/sysctrl.h", "crt/src/hal/ga2d.c", "crt/src/hal/npu.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/npu-verification.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", "publications/examples/npu.c", "rtl/ip/multimedia/apb4_apu.sv", "rtl/ip/multimedia/apb4_ga2d.sv", "rtl/ip/multimedia/apb4_npu.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/apu_reg.sv", "rtl/ip/multimedia/ga2d_core.sv", "rtl/ip/multimedia/ga2d_dma.sv", "rtl/ip/multimedia/npu_accumulator.sv", "rtl/ip/multimedia/npu_define.svh", "rtl/ip/multimedia/npu_job_decoder.sv", "rtl/ip/multimedia/npu_local_sram.sv", "rtl/ip/multimedia/npu_pkg.sv", "rtl/ip/multimedia/npu_reg.sv", "rtl/ip/multimedia/npu_scheduler.sv", "rtl/mini/integration/soc_topology.json", "scripts/apu_abi_digest.py", "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/npu_compiler.py", "scripts/npu_compiler_p0.py", "scripts/npu_descriptors.py", "scripts/package_hp_boot.py", "scripts/parse_performance_log.py", "tests/test_lp_irq.py", "rtl/mini/top/retrosoc.sv", "rtl/mini/top/apb4_periph.sv", "docs/development-environment.md", "scripts/development_environment.py", "dependencies/dependencies.lock.json", "docker/Dockerfile", "flake.nix", ".github/workflows/development-environment.yml", ".github/workflows/quality.yml", "CONTRIBUTING.md", "docs/git-workflow.md" ], "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/ip/memory/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": "Ten independently managed shared resources; resource 8 owns GA2D and resource 9 owns NPU execution, including lifecycle and LP/HP IRQ routing.", "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": "Ten master and six target observation banks; master bank 8 observes GA2D traffic and master bank 9 observes NPU descriptor and data DMA 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": "WAV/FLAC image and job/stream execution; APUC-backed KWS is enabled only in the P9 acceptance configuration. MP3 remains unsupported.", "dependencies": "Load compatible APUMC V2, APUC and APUM images in order. 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": "No delivered Linux ASoC integration. The LP/HP APU release image is bare-metal acceptance firmware, not a kernel driver.", "verification": "Tests available", "sources": [ "Makefile", "app/apps/apu_release/main.c", "app/ports/hp-apu/main.c", "configs/ci/ihp130-apu.mk", "crt/include/retrosoc/hal/apu.h", "crt/include/retrosoc/hal/apu_regs.h", "crt/src/hal/apu.c", "docs/ip/apu.md", "publications/examples/apu.c", "rtl/ip/multimedia/apb4_apu.sv", "rtl/ip/multimedia/apu_define.svh", "rtl/ip/multimedia/apu_kws_coeff_loader.sv", "rtl/ip/multimedia/apu_kws_coeff_store.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/apu_reg.sv", "rtl/ip/multimedia/apu_proof_memo.sv", "scripts/apu_abi_digest.py", "scripts/apu_isa.py", "scripts/apu_kws.py", "scripts/apu_kws_coeff.py", "scripts/apu_mcasm.py", "scripts/apu_p5_coefficients.py", "scripts/build_apu_p5_bundle.py" ], "tests": [ "tests/test_apu.py", "tests/test_apu_p7_concurrent.py", "tests/test_apu_p7_qualification.py", "tests/test_apu_p8_contention.py", "tests/test_apu_p8_quiesce_load.py" ], "reports": [] }, { "id": "npu", "title": "Neural Processing Unit", "implementation": "Integrated", "scope": "Eight INT8 operators with native HP descriptor/DMA execution and private local SRAM.", "dependencies": "Static compiler-supported graphs, exclusive resource/buffer ownership and explicit cache maintenance; locked KWS/VWW references for qualification.", "hal": "Eleven public NPU HAL operations and a bounded submission example.", "linux": "No native Linux NPU driver ABI is established. The HP smoke payload is freestanding acceptance firmware.", "verification": "Tests available", "sources": [ "crt/include/retrosoc/hal/npu.h", "crt/include/retrosoc/hal/npu_regs.h", "crt/src/hal/npu.c", "docs/ip/npu-verification.md", "docs/ip/npu.md", "publications/examples/npu.c", "rtl/ip/multimedia/apb4_npu.sv", "rtl/ip/multimedia/npu_accumulator.sv", "rtl/ip/multimedia/npu_define.svh", "rtl/ip/multimedia/npu_job_decoder.sv", "rtl/ip/multimedia/npu_local_sram.sv", "rtl/ip/multimedia/npu_pkg.sv", "rtl/ip/multimedia/npu_reg.sv", "rtl/ip/multimedia/npu_scheduler.sv", "scripts/npu_compiler.py", "scripts/npu_compiler_p0.py", "scripts/npu_descriptors.py" ], "tests": [ "tests/test_npu_register_parity.py", "tests/test_npu_rtl_p4.py", "tests/test_npu_compiler.py", "tests/test_npu_p6.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.5 PRODUCT snapshot; MPW differences are stated separately.", "sources": [ "docs/lp-hp-architecture.md", "docs/ip/resource-controller.md" ] }, { "id": "hp-ready-wait", "title": "Linux ready service does not complete loader acceptance", "impact": "The supplied rootfs publishes the initial ready checkpoint but does not provide the later GA2D result and cache-clean service required by the current hp_boot acceptance sequence.", "trigger": "Using the ready-only Linux service where the loader expects the full acceptance mailbox protocol.", "workaround": "Pair the loader with a matching acceptance payload or service. Current polling is bounded by iteration budgets and missing handshakes fail their stage; an initial ready message is not a terminal pass.", "applies_to": "Reviewed v0.5 PRODUCT snapshot; MPW differences are stated separately.", "sources": [ "app/apps/hp_boot/main.c", "configs/ci/ihp130-hp.mk", "app/ports/linux/hp_ready.c", "crt/src/hal/hp_mailbox.c" ] }, { "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.5 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.5 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.5 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.5 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.5 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.5 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. MP3 remains a reserved trap; default PRODUCT disables KWS, while the dedicated P7 configuration enables its fixed APUM model. These facts do not establish full-corpus, sustained real-time or physical qualification.", "trigger": "Submitting MP3, assuming default KWS availability, or inferring full qualification from capability bits.", "workaround": "Read the configuration-specific capability/digest. Use the supported image/model and explicit loader, cache and ownership protocol. Obtain complete revision-matched accuracy/concurrency/physical reports before wider qualification.", "applies_to": "Reviewed v0.5 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.5 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.5 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.5 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.5 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/mk/software.mk" ] }, { "id": "npu-deployment-scope", "title": "NPU execution does not imply arbitrary model or qualified performance support", "impact": "Unsupported graphs, unsafe buffer reuse or an assumed Linux driver can prevent correct deployment.", "trigger": "Dynamic/arbitrary TFLite graphs, unadvertised operators, timeout without drain, or missing cache/ownership handoff.", "workaround": "Use the static compiler subset and explicit CPU preprocessing/Softmax. Check capability and numeric profile, retain buffers until terminal/drained state, and require exact-revision reports for accuracy/performance claims.", "applies_to": "Reviewed v0.5 PRODUCT snapshot; no MLPerf, timing-closure or silicon qualification claim.", "sources": [ "rtl/ip/multimedia/npu_reg.sv", "rtl/ip/multimedia/apb4_npu.sv", "scripts/npu_compiler.py", "crt/src/hal/npu.c" ] } ], "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. DMA permits one normal read and one normal write at a time.", "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 unsupported; KWS requires the P7-enabled configuration. No generic codec, arbitrary TFLite, Linux ASoC or complete 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" } ] }, { "id": "npu", "ips": [ "npu" ], "title": "NPU", "role": "Static INT8 tensor processing", "modes": "Eight operator classes, checked INT32 accumulation, double-rounding requantization and native HP descriptor DMA.", "software": "Static compiler-generated C, NPU HAL and freestanding LP/HP acceptance; preprocessing and terminal Softmax run on CPU.", "excluded": "No arbitrary/dynamic TFLite graphs, implicit fallback, APUM binary compatibility, dedicated camera/audio stream or native Linux driver ABI.", "evidence": "Source-level subset; no compliance report attached", "sources": [ "rtl/ip/multimedia/npu_define.svh", "rtl/ip/multimedia/apb4_npu.sv", "scripts/npu_compiler.py" ], "bindings": [ { "file": "rtl/ip/multimedia/npu_define.svh", "kind": "snippet", "text": "`define APB4_NPU__CAPABILITY_P4 32'h0000_007f" } ] } ], "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/ip/core/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_npu", "chapter": "npu", "family": "npu", "mode": "PRODUCT", "region": "APB4_NPU", "catalog": "npu", "qualification": "Integrated native-HP NPU execution with eight operator classes, descriptor DMA and private SRAM; CAPABILITY=0x7F and OP_CAPABILITY=0x1FE. Resource 9 routes LP vector 33 / HP PLIC source 12. Use configured lifecycle, cache and descriptor admission rules; no native Linux driver, arbitrary model or current corpus/physical qualification is implied.", "sources": [ "docs/ip/npu.md", "rtl/ip/multimedia/npu_reg.sv", "rtl/ip/multimedia/apb4_npu.sv", "rtl/ip/multimedia/npu_control_cdc.sv", "rtl/ip/multimedia/npu_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`RIB_RESP_\\w+|default):\\s*s_fault_reason_d\\s*=\\s*(?P3\\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+(?PRIB_RESP_\\w+)\\s+(?P3\\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+(?PFault\\w+)\\s*=\\s*(?P4\\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+(?PFaultTimeout)\\s*=\\s*(?P4\\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*(?P2\\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+(?PDMA_ERROR_\\w+)\\s*=\\s*(?P4\\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+(?PRS_SDIO_DMA_ERROR_\\w+)\\s+UINT32_C\\((?P0x[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+(?PError\\w+)\\s*=\\s*(?P8\\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": "(?PUsb2Desc\\w+)\\s*=\\s*(?P5\\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": "(?PUsb2Result\\w+)\\s*=\\s*(?P4\\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+(?PAPB4_APU__ERROR_CODE_\\w+)\\s+(?P\\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*(?PRS_(?:OK|E[A-Z]+))\\s*=\\s*(?P-?\\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, 9, 18, 18, 10, 18, 19, 11, 12, 13, 14, 15, 16, 17, 17, 19 ], "expected_entries": 4, "meanings": { "0": "Selected workload completed: Linux-ready, RT-Thread kernel/mailbox IRQ tests, or smoke GA2D/cache lifecycle.", "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.", "18": "NPU handoff to HP failed, or the RT-Thread ready message reported failure or mismatched identity.", "19": "NPU handoff back to LP failed, or the RT-Thread IRQ command/final verdict 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/hp_ready.c", "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/mk/software.mk", "scripts/build_hp_linux.py", "scripts/regress.py", "crt/src/hal/hp_mailbox.c", "crt/include/retrosoc/core/status.h", "rtl/ip/peripheral/hp_mailbox_define.svh", "rtl/mini/address_map/memory_map.json", "rtl/ip/peripheral/apb4_hp_mailbox.sv", "app/ports/linux/init" ], "bindings": [ { "id": "csr-selection", "file": "rtl/mk/software.mk", "text": "ifeq ($(HAVE_CSR),YES)\nDEF_VAL += -DCSR_ENABLE\nendif" }, { "id": "irq-objects", "file": "rtl/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/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\"][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/hp_ready.c", "text": "puts(\"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": "ga2d-bounded-wait", "title": "GA2D bounded wait and timeout ownership", "kind": "test-fail", "code": 15, "trigger": "rs_ci_smoke_ga2d_bounded_wait(", "coverage": "Force a deliberately small rs_ga2d_wait budget to expire with RS_ETIMEOUT while a real SDRAM job keeps running, prove timeout expiry does not imply safe idle or buffer reclaim, then complete the job under a normal bounded wait with exact destination and counter checks, and confirm rs_ga2d_abort_wait on the idle engine.", "boundary": "Covers LP polling-budget semantics only; it does not exercise HP-side timeout handling, watchdog TIMEOUT error recovery, or abort of an in-flight job." }, { "id": "ga2d-dma-contention", "title": "GA2D and central DMA concurrent progress", "kind": "test-fail", "code": 16, "trigger": "rs_ci_smoke_ga2d_dma_contention(", "coverage": "Run a central-DMA memory-to-memory transfer and a GA2D copy concurrently in disjoint SDRAM regions, verify both payloads byte-exactly, and confirm fabric-monitor request counters advance for both master 2 and master 8 during the shared window.", "boundary": "Covers LP CPU, central DMA, and GA2D competition with SDRAM refresh in the behavioral product; wider peripheral-master contention is evidenced in the GA2D platform testbench, and no starvation bound is proven here." }, { "id": "npu-p2-shell-irq", "title": "NPU P2 shell ownership and IRQ route", "kind": "test-fail", "code": 17, "trigger": "rs_ci_smoke_npu_irq(", "coverage": "Hand resource 9 to LP through the Resource Controller quiesce/acknowledge round trip, read back the shell identity/capability, and verify the IRQ_TEST-injected event reaches external ordinal 31 and clears by W1C.", "boundary": "Covers the P2 register shell and interrupt route only; EXECUTION_READY stays clear, the private master is tied idle, and no job, DMA, or operator behavior is exercised." }, { "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", "app/apps/hp_boot/hp_boot_bundle.c" ], "loader_bindings": [ { "source": "app/apps/hp_boot/hp_boot_bundle.c", "function": "rs_hp_boot_crc32_byte", "body_sha256": "b048241b3b6c9507a3d2b630af3ce8e4f2dbc0cdfbe662f76a8fce8ebe6037bc" }, { "source": "app/apps/hp_boot/hp_boot_bundle.c", "function": "rs_hp_boot_crc32", "body_sha256": "ee0d898baadc9da12772f6246b2f8b4635216fe68cf67e08793865d2ca40dc90" }, { "source": "app/apps/hp_boot/hp_boot_bundle.c", "function": "rs_hp_boot_header_valid", "body_sha256": "cd86a399c2307681a36887647da8f3a585a0d6bbe5cb531b33bfdd84ad2e96a2" } ], "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": "Linux uses four entries; smoke and RT-Thread use one executable entry. The remaining three slots are zero.", "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": "Must equal REQUIRED (1); extra flag bits are rejected.", "workload": "V2 workload discriminator: 1 Linux, 2 smoke, 3 RT-Thread. Unknown values and V1 are rejected." }, "entry_fields": { "type": "Linux uses types 1..4 in fixed order; smoke/RT-Thread use executable type 5 at 0x38000000.", "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": "Must equal REQUIRED (1); extra flag bits are rejected." }, "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": "Workload 1: four Linux artifacts. Workloads 2/3: one executable type 5. Unused descriptor slots are zero.", "loader": "Checks workload, exact count/type/order/address, per-artifact size limits and zero unused slots.", "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": "Requires each absolute flash offset to be 4096-byte aligned and the exact fixed load address.", "consequence": "Loader and packager enforce the same payload-start alignment." }, { "topic": "Flags and workload", "producer": "Writes flags=1 and the explicit V2 workload discriminator.", "loader": "Rejects additional flag bits, unknown workloads, V1 and nonzero unused descriptors.", "consequence": "Rebuild old bundles; do not infer workload from placeholder payload bytes." }, { "topic": "Payload placement and fill", "producer": "Places payloads sequentially without overlap, filling unused image bytes with 0xFF.", "loader": "Enforces monotonic non-overlapping flash payload extents within the bundle. Exact fixed load windows are disjoint. Padding bytes are not checked.", "consequence": "Overlap is rejected; padding is neither payload data nor authenticated metadata." }, { "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/apb4_npu.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/multimedia/npu_accumulator.sv", "rtl/ip/multimedia/npu_control_cdc.sv", "rtl/ip/multimedia/npu_core.sv", "rtl/ip/multimedia/npu_define.svh", "rtl/ip/multimedia/npu_dma.sv", "rtl/ip/multimedia/npu_local_sram.sv", "rtl/ip/multimedia/npu_pkg.sv", "rtl/ip/multimedia/npu_reg.sv", "rtl/ip/multimedia/npu_scheduler.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", "crt/include/retrosoc/hal/crypto_regs.h", "rtl/ip/security/apb4_crypto.sv", "rtl/ip/security/crypto_aes_sram_engine.sv", "rtl/ip/security/crypto_clearable_fifo.sv", "rtl/ip/security/crypto_rsa_sram_core.sv", "rtl/ip/security/crypto_sha2_sram_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/ip/core/mgmt_debug_wrapper.sv", "rtl/ip/memory/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/npu_compiler_p0.py", "scripts/npu_descriptors.py", "scripts/npu_executor.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": "c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b", "checked_date": "2026-09-23", "checked_at": "2026-09-23T08:26:42Z", "boundary": "Observed public GitHub workflow status for this exact commit. Unfinished runs have no conclusion. Installation, environment checking and runtime regression are separate evidence; workflow outcomes do not qualify unexecuted physical or silicon stages.", "runs": [ { "name": "quality", "run_id": 35833990836, "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990836", "scope": "Repository quality checks and script/RTL fixture tests", "note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred." }, { "name": "regression-smoke", "run_id": 35833991124, "status": "completed", "conclusion": "success", "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991124", "scope": "Bounded IHP130 smoke regression", "note": "Selected workflow stages completed successfully. No per-IP corpus or physical qualification is inferred." }, { "name": "regression-ihp130", "run_id": 35833991071, "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991071", "scope": "IHP130 hosted behavioral regression", "note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred." }, { "name": "regression-sky130", "run_id": 35833991199, "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991199", "scope": "SKY130 hosted behavioral regression", "note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred." }, { "name": "regression-gf180", "run_id": 35833991194, "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991194", "scope": "GF180 hosted behavioral regression", "note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred." }, { "name": "regression-ics55", "run_id": 35833991306, "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991306", "scope": "ICS55 hosted behavioral regression", "note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred." }, { "name": "development-environment", "run_id": 35833990893, "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893", "scope": "Docker/Nix installation, environment checks and hosted IHP130 behavioral regression", "note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred.", "observations": [ { "name": "docker: Build Docker development environment", "scope": "installation", "status": "completed", "conclusion": "success", "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965761" }, { "name": "docker: Run IHP130 regression in development environment", "scope": "runtime-regression", "status": "in_progress", "conclusion": null, "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965761" }, { "name": "nix: Install Nix", "scope": "installation", "status": "completed", "conclusion": "success", "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965933" }, { "name": "nix: Check Nix flake", "scope": "environment-check", "status": "completed", "conclusion": "success", "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965933" }, { "name": "nix: Run IHP130 regression in development environment", "scope": "runtime-regression", "status": "completed", "conclusion": "success", "url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965933" } ] } ] } }