retroSoC/rtl/mini/integration/README.md

Mini SoC Topology

soc_topology.json is the source of truth for internal Mini SoC integration that is not part of the software address-map ABI or the package pad map.

GA2D Phase 2 expands the topology to data master/resource 8 and seven-bit global IDs while retaining all existing allocations. Phase 5 drives its dedicated PCLK-to-HP AXI64/ID3 bridge with a direct single-job private-AXI64 2D engine at APB4_GA2D slot 28. It supports FILL, COPY, bit-exact CONVERT, opaque alpha BLEND, A8 fixed-color foreground masks, and exact equal background/destination in-place composition. Its raw IRQ is routed through resource 8: LP group bit 24, core vector bit 32/external ordinal 30, or HP PLIC source 11 according to owner. RGB565, RGB888, XRGB8888, and ARGB8888 are color surfaces with pitch and byte-edge handling; A8 is BLEND foreground-only. Transparent-background and premultiplied-alpha modes, scaling, rendering, and descriptor/ring/queue submission remain unavailable. The Xh3irq SDK path also requires the Phase 1 implementation; a wiring-only expansion is insufficient.

The topology generator validates APB4 island ownership against ../address_map/memory_map.json and emits generated SystemVerilog include files for apb4_periph.sv, apb4_system.sv, axi42apb4_periph.sv, axi42apb4_system.sv, and retrosoc.sv. The two APB4 islands share one decoder template. apb4_system is instantiated as u_apb4_system; its AXI4 configuration port is wired by generated apb4_system_fabric.svh. apb4_periph remains the self-owned APB4 peripheral container. Generated fabric links are explicit 32-bit AXI4 interfaces; mgmt, user, dma, sdio0, sdio1, and usb2 are generated native AXI4 links, while cfg and system are target-side links. Interface arrays are confined to the AXI4 bus implementation and flattened by the existing synthesis/export flow before FPGA or netlist simulation.

The apb4_periph_targets list uses stable response slots for the former RIBP island at 0x1000_0000. Every active apb4_periph memory-map region must appear exactly once. Disabled targets keep their slot and interface declaration but cannot own an address region. This list stays separate from apb4_system_targets, which owns the 0x2000_0000 apb4_system island. Slot 15 is the active SDIO0 management window; SDIO1 is appended at slot 18, the management-only crypto controller at slot 19, USB2 at slot 20, JPEG at slot 26, and the APU shell at slot 27, so the existing slots remain stable.

Each gpio_alt_functions entry defines both alternate modes for one GPIO pin. inputs are driven from the selected GPIO input, and do and oe define the peripheral output path. Values are restricted to scalar signal references and one-bit constants so malformed expressions are rejected before RTL generation.

The apb4_system_targets list defines the stable APB4 response slot, timed/pure APB4 interface names, and corresponding active apb4_system address-map region. Slots are contiguous from zero. The user-IP target is part of the fixed platform integration and its presence is checked against the canonical memory map. Slot 10 is the Resource Controller; slot 11 is the external HP-domain Fabric Monitor reached through its explicit PCLK-to-HP APB bridge.

data_master_policies defines all nine native data-plane master identities, read/write target sets, instruction permission, and non-cacheable attribute requirements. The generator rejects missing, reordered, or unknown entries and emits packed soc_data_policy.svh constants consumed by the crossbar. This keeps access policy reviewable without generating register definitions.

irq_vector_width, irq_groups, and interrupts define the complete core interrupt topology. Phase 1 sets the LP vector capacity to 64 bits while the canonical source list retains the existing assignments in bits 0..31; unallocated bits 32..63 are generated low. Product builds expose 62 external Hazard3 inputs, while MPW compatibility builds select the 30-input wrapper variant. apb4_periph and apb4_system group entries declare the wrapper output width and the associated retrosoc.sv signal. Every group bit must be present exactly once, each allocated core-vector bit must have one source, and sources are limited to scalar signal references or one-bit constants. The generator emits the two wrapper bindings, the core-vector wiring, and simulation-only assertions. Existing allocated core IRQ bits retain their compatibility mapping; additions must use currently unallocated bits and preserve the existing entries. SDIO0 and SDIO1 use APB4 group bits 16 and 17 and core bits 10 and 21. Crypto uses APB4 group bit 18 and core bit 23. USB2 uses APB4 group bit 19 and core bit 24. JPEG uses group bit 22 and core bit 30; APU uses group bit 23 and core bit 31. All resource-owned sources remain management-only in the generated user IRQ mask. Removing a source leaves its core IRQ bit unallocated and driven low. The Phase 1 SDK uses Hazard3 Xh3irq array CSRs and MEINEXT dispatch for the LP management hart; it does not add a PLIC or change the HP interrupt path.

The generator also emits include/retrosoc/generated/irq_metadata.h with the selected vector/external counts and allocated source macros. It contains no GA2D source macro until Phase 3 wiring.

user_extensions.json defines the active SoC-level user-core and user-IP design IDs, slots, module names, and reset types. The locked mini-ver-mpw mpw.toml remains the source of truth for available design metadata and source locations. scripts/generate_mpw.py selects and renumbers the configured designs, then verifies the generated manifest before RTL generation. generate_user_extensions.py then creates isolated default routing and one explicit instance per selected slot for user_core_top.sv and user_ip_top.sv. User cores keep ribp_if.master ribp at the extension ABI and are converted to AXI4 after selection; user IPs use user_gpio_if.user_ip gpio and APB4. This prevents system-fabric and electrical pad-control contracts from entering the extension muxes.

Product extension entries also declare data_master, stream, and local_sram independently. Capability registers are driven from those exact values. The current EXT-H has a data master but no stream or local SRAM; EXT-L has none of the three.

clock_reset_domains.json is the checked inventory of root clock domains, reset synchronizers, and RCU PLL control crossings. It records the primitive, source file, and instance name so an RTL refactor cannot silently remove the declared reset or CDC structure. It complements, but does not replace, a signoff CDC/RDC analysis tool.

Use these commands to validate or generate the selected build artifacts:

make check-soc-topology
make soc-topology
make check-user-extensions
make user-extensions
make check-clock-reset-domains

Generated files are written under build/<variant>/generated/soc_topology/ and build/<variant>/generated/user_extensions/; they must not be committed.