diff --git a/docs/ip/ps2.md b/docs/ip/ps2.md index a26d3f8c..05c5d126 100644 --- a/docs/ip/ps2.md +++ b/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 -clock frequency for reset timing defaults and instantiates 16-entry RX and TX -FIFOs. +management interrupt vector 12. `apb4_system` instantiates the managed PS/2 +host with the configured external clock frequency for reset timing defaults +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 diff --git a/docs/soc-integration-wiring.md b/docs/soc-integration-wiring.md index bbabd680..6042191f 100644 --- a/docs/soc-integration-wiring.md +++ b/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` -only exposes the pad-side subset of `gpio_if`; neither module contains state. +`apb4_system` is the APB4 platform subsystem (`u_apb4_system`); it is not a +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 diff --git a/physical/smoke/syn/yosys/synth_config.mk b/physical/smoke/syn/yosys/synth_config.mk index 4d142147..6414aaf3 100644 --- a/physical/smoke/syn/yosys/synth_config.mk +++ b/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*$$*" \ diff --git a/rtl/README.md b/rtl/README.md index fcda588c..908b3a94 100644 --- a/rtl/README.md +++ b/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). diff --git a/rtl/mini/README.md b/rtl/mini/README.md index cf45be7e..31a72635 100644 --- a/rtl/mini/README.md +++ b/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. diff --git a/rtl/mini/filelist/top.fl b/rtl/mini/filelist/top.fl index 77e7dfe8..660909eb 100644 --- a/rtl/mini/filelist/top.fl +++ b/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 diff --git a/rtl/mini/integration/README.md b/rtl/mini/integration/README.md index e8176bb9..a8290c43 100644 --- a/rtl/mini/integration/README.md +++ b/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 -`retrosoc.sv`. Generated fabric links are explicit 32-bit AXI4 interfaces. +files for `ip_ribp_wrapper.sv`, `apb4_system.sv`, `axi42apb.sv`, and +`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. diff --git a/rtl/mini/integration/generate_soc_topology.py b/rtl/mini/integration/generate_soc_topology.py index c926efd3..b3d27601 100644 --- a/rtl/mini/integration/generate_soc_topology.py +++ b/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)) diff --git a/rtl/mini/top/ip_apb_wrapper.sv b/rtl/mini/top/apb4_system.sv similarity index 99% rename from rtl/mini/top/ip_apb_wrapper.sv rename to rtl/mini/top/apb4_system.sv index a01d1976..c76a1902 100644 --- a/rtl/mini/top/ip_apb_wrapper.sv +++ b/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, diff --git a/rtl/mini/top/retrosoc.sv b/rtl/mini/top/retrosoc.sv index a9b6fea3..9d9cb0a2 100644 --- a/rtl/mini/top/retrosoc.sv +++ b/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), diff --git a/rtl/rtl_style_audit.json b/rtl/rtl_style_audit.json index 55eeed07..14fc5353 100644 --- a/rtl/rtl_style_audit.json +++ b/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", diff --git a/tests/test_soc_topology.py b/tests/test_soc_topology.py index ec415d97..d6339352 100644 --- a/tests/test_soc_topology.py +++ b/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