feat: implement apb4_system module and update related documentation and tests

docs/ip/ps2.md

@@ -8,9 +8,9 @@ and release documentation under `rtl/managed/clusterip/ps2`.
 ## SoC Binding
 
 The controller is APB target slot 4 and reports its combined level interrupt at
-management interrupt vector 12. The APB wrapper uses the configured external
+management interrupt vector 12. `apb4_system` instantiates the managed PS/2
-clock frequency for reset timing defaults and instantiates 16-entry RX and TX
+host with the configured external clock frequency for reset timing defaults
-FIFOs.
+and 16-entry RX and TX FIFOs.
 
 GPIO0 and GPIO1 ALT1 select PS/2 clock and data respectively. Each ALT1 path
 binds all three signals as one function: resolved pad input, constant-zero pad

docs/soc-integration-wiring.md

@@ -24,8 +24,10 @@ unsupported features, and unapproved connection syntax.
 
 SoC wrappers use the existing clusterIP interfaces for protocol boundaries,
 except for the self-owned UART0 `uart_if` under `rtl/ip/serial`.
-`apb4_if_bridge` only adapts `apb4_pure_if` to `apb4_if`, and `gpio_pad_bridge`
+`apb4_system` is the APB4 platform subsystem (`u_apb4_system`); it is not a
-only exposes the pad-side subset of `gpio_if`; neither module contains state.
+protocol bridge. `apb4_if_bridge` only adapts `apb4_pure_if` to `apb4_if`, and
+`gpio_pad_bridge` only exposes the pad-side subset of `gpio_if`; neither
+adapter contains state.
 
 ## UART flow-control alternate functions
 

physical/smoke/syn/yosys/synth_config.mk

@@ -22,7 +22,7 @@ export YOSYS_KEEP_HIER_INST :=  "t:tc_clk*$$*" \
 								"t:core_*$$*" \
 								"t:bus*$$*" \
 								"t:ip_rib_wrapper*$$*" \
-								"t:ip_apb_wrapper*$$*" \
+								"t:apb4_system*$$*" \
 								"t:apb_spi_master*$$*" \
 								"t:spi_flash*$$*" \
 								"t:mem2apb*$$*" \

rtl/README.md

@@ -78,3 +78,9 @@ SystemCtrl uses `sysctrl_if.sv`, `sysctrl_define.svh`, `sysctrl_reg.sv`, and
 generated register offsets, RIBP timing, control-plane behavior, and
 verification contract are documented in
 [RIBP System Control](../docs/ip/sysctrl.md).
+
+The Mini SoC APB4 platform block is `apb4_system` in `rtl/mini/top`. It owns
+archinfo, RTC, watchdog, PWM, PS/2, RNG, CRC, and the user-IP APB window.
+`ip_ribp_wrapper` remains the RIBP peripheral container. Topology generation
+and the `soc_apb4_system_fabric.svh` include are documented in
+[Mini SoC Topology](mini/integration/README.md).

rtl/mini/README.md

@@ -9,7 +9,8 @@ This directory is the active Mini SoC integration boundary.
 - filelist contains canonical ordered .fl templates.
 - mk contains simulator and software make fragments.
 - script contains filelist, address-map, conversion, and setup helpers.
-- top contains SoC integration RTL.
+- top contains SoC integration RTL, including `apb4_system` for the APB4
+  platform block and `ip_ribp_wrapper` for the RIBP peripheral container.
 
 Generated filelists, address-map products, and MPW output belong in the
 configured build variant, not under this directory.

rtl/mini/filelist/top.fl

@@ -21,7 +21,7 @@
 /top/retrosoc_asic.sv
 /top/onchip_ram.sv
 /top/ip_ribp_wrapper.sv
-/top/ip_apb_wrapper.sv
+/top/apb4_system.sv
 /top/rib_bus.sv
 /top/axi4_bus.sv
 /top/rcu.sv

rtl/mini/integration/README.md

@@ -5,8 +5,11 @@ that is not part of the software address-map ABI or the package pad map.
 
 The topology generator validates RIBP configuration and APB target ownership against
 `../address_map/memory_map.json` and emits generated SystemVerilog include
-files for `ip_ribp_wrapper.sv`, `ip_apb_wrapper.sv`, `axi42apb.sv`, and
+files for `ip_ribp_wrapper.sv`, `apb4_system.sv`, `axi42apb.sv`, and
-`retrosoc.sv`. Generated fabric links are explicit 32-bit AXI4 interfaces.
+`retrosoc.sv`. The APB4 platform subsystem is `apb4_system`, instantiated as
+`u_apb4_system`; its AXI4 configuration port is wired by generated
+`soc_apb4_system_fabric.svh`. `ip_ribp_wrapper` remains the RIBP peripheral
+container. Generated fabric links are explicit 32-bit AXI4 interfaces.
 Interface arrays are confined to the AXI4 bus implementation and flattened by
 the existing synthesis/export flow before FPGA or netlist simulation.
 

rtl/mini/integration/generate_soc_topology.py

@@ -934,7 +934,7 @@ def generate(topology_path: Path, memory_map_path: Path, output_dir: Path) -> No
         + render_fabric_connection(fabric_links, "dma", "dma_axi4"),
     )
     atomic_write(
-        rtl_dir / "soc_ip_apb_wrapper_fabric.svh",
+        rtl_dir / "soc_apb4_system_fabric.svh",
         render_fabric_connection(fabric_links, "apb", "axi4"),
     )
     atomic_write(rtl_dir / "soc_gpio_alt_bindings.svh", render_gpio_bindings(gpio_functions))

rtl/mini/top/apb4_system.sv

@@ -15,7 +15,7 @@
 `include "soc_irq_config.svh"
 `include "archinfo_integration_metadata.svh"
 
-module ip_apb_wrapper (
+module apb4_system (
     // verilog_format: off -- preserve reviewed column alignment
     input  logic                          clk_i,
     input  logic                          rst_n_i,

rtl/mini/top/retrosoc.sv

@@ -223,13 +223,13 @@ core_wrapper u_core_wrapper (
       .sdram   (sdram)
   );
 
-  ip_apb_wrapper u_ip_apb_wrapper (
+  apb4_system u_apb4_system (
       .clk_i          (clk_i),
       .rst_n_i        (rst_n_i),
       .clk_aud_i      (clk_aud_i),
       .rst_aud_n_i    (rst_aud_n_i),
       .debug_halted_i (s_mgmt_debug_halted),
-      `include "soc_ip_apb_wrapper_fabric.svh"
+      `include "soc_apb4_system_fabric.svh"
       .pwm            (u_pwm_if),
       .ps2            (u_ps2_if),
       .ip_sel_i       (u_sysctrl_if.ip_sel_o),

rtl/rtl_style_audit.json

@@ -184,6 +184,7 @@
       "ahbl2axi4.sv",
       "ahbl2ribp.sv",
       "apb4_if_bridge.sv",
+      "apb4_system.sv",
       "axi4_bus.sv",
       "axi4_connector.sv",
       "axi4_error_slave.sv",
@@ -194,7 +195,6 @@
       "axi42ribp_burst.sv",
       "core_wrapper.sv",
       "gpio_pad_bridge.sv",
-      "ip_apb_wrapper.sv",
       "ip_ribp_wrapper.sv",
       "mgmt_core_wrapper.sv",
       "mgmt_debug_reset.sv",

tests/test_soc_topology.py

@@ -66,6 +66,7 @@ def test_topology_generates_complete_rib_apb_and_gpio_bindings(tmp_path: Path) -
     apb_response = (tmp_path / "rtl/soc_apb_response_mux.svh").read_text(encoding="utf-8")
     fabric = (tmp_path / "rtl/soc_fabric_interfaces.svh").read_text(encoding="utf-8")
     bus_fabric = (tmp_path / "rtl/soc_bus_fabric.svh").read_text(encoding="utf-8")
+    apb_system_fabric = (tmp_path / "rtl/soc_apb4_system_fabric.svh").read_text(encoding="utf-8")
     irq_config = (tmp_path / "rtl/soc_irq_config.svh").read_text(encoding="utf-8")
     rib_irq = (tmp_path / "rtl/ribp_irq_bindings.svh").read_text(encoding="utf-8")
     apb_irq = (tmp_path / "rtl/soc_apb_irq_bindings.svh").read_text(encoding="utf-8")
@@ -112,6 +113,7 @@ def test_topology_generates_complete_rib_apb_and_gpio_bindings(tmp_path: Path) -
     assert ".dma_axi4(u_dma_axi4_if)" in bus_fabric
     assert ".cfg_axi4(u_cfg_axi4_if)" in bus_fabric
     assert ".apb_axi4(u_apb_axi4_if)" in bus_fabric
+    assert ".axi4(u_apb_axi4_if)" in apb_system_fabric
     assert "`define SOC_IRQ_VECTOR_WIDTH 32" in irq_config
     assert "`define SOC_USER_IRQ_MASK 32'h000EFBFC" in irq_config
     assert "`define SOC_IRQ_RIBP_WIDTH 14" in irq_config