feat: add QSPI Flash and Flash Read Binder modules

- Introduced for handling QSPI flash memory operations, including command and address handling. - Added to interface with the C++ flash memory implementation, allowing for read operations via DPI-C. - Created for the flash memory implementation, supporting initialization, reading, and memory copying. - Updated to integrate the new QSPI Flash module and connect it with the existing system. - Refactored file paths in various filelists and scripts to accommodate the new directory structure under . - Enhanced the Python scripts for generating memory maps and preparing the environment for the new structure. - Adjusted test scripts to reflect changes in the directory structure and ensure compatibility with the new modules.
2026-11-04 22:32:36 +00:00 · 2026-07-20 16:50:57 +08:00
1 parent 82e5c605a8
commit fb3621e6b8
@@ -33,23 +33,23 @@ jobs:
            app/coremark/coremark-main
            app/fatfs/ff16
            pdk/IHP-Open-PDK
-            rtl/clusterip/archinfo
-            rtl/clusterip/clint
-            rtl/clusterip/common
-            rtl/clusterip/crc
-            rtl/clusterip/i2c
-            rtl/clusterip/i2s
-            rtl/clusterip/plic
-            rtl/clusterip/ps2
-            rtl/clusterip/pwm
-            rtl/clusterip/rng
-            rtl/clusterip/rtc
-            rtl/clusterip/spi
-            rtl/clusterip/timer
-            rtl/clusterip/uart
-            rtl/clusterip/wdg
-            rtl/ip/3rd-party
-            rtl/mini/mpw
+            rtl/managed/clusterip/archinfo
+            rtl/managed/clusterip/clint
+            rtl/managed/clusterip/common
+            rtl/managed/clusterip/crc
+            rtl/managed/clusterip/i2c
+            rtl/managed/clusterip/i2s
+            rtl/managed/clusterip/plic
+            rtl/managed/clusterip/ps2
+            rtl/managed/clusterip/pwm
+            rtl/managed/clusterip/rng
+            rtl/managed/clusterip/rtc
+            rtl/managed/clusterip/spi
+            rtl/managed/clusterip/timer
+            rtl/managed/clusterip/uart
+            rtl/managed/clusterip/wdg
+            rtl/managed/third_party
+            rtl/managed/mpw
            .cache/retrosoc/stamps
          key: sources-${{ runner.os }}-${{ hashFiles('config/dependencies.lock.json') }}

@@ -23,23 +23,23 @@ jobs:
            app/coremark/coremark-main
            app/fatfs/ff16
            pdk/IHP-Open-PDK
-            rtl/clusterip/archinfo
-            rtl/clusterip/clint
-            rtl/clusterip/common
-            rtl/clusterip/crc
-            rtl/clusterip/i2c
-            rtl/clusterip/i2s
-            rtl/clusterip/plic
-            rtl/clusterip/ps2
-            rtl/clusterip/pwm
-            rtl/clusterip/rng
-            rtl/clusterip/rtc
-            rtl/clusterip/spi
-            rtl/clusterip/timer
-            rtl/clusterip/uart
-            rtl/clusterip/wdg
-            rtl/ip/3rd-party
-            rtl/mini/mpw
+            rtl/managed/clusterip/archinfo
+            rtl/managed/clusterip/clint
+            rtl/managed/clusterip/common
+            rtl/managed/clusterip/crc
+            rtl/managed/clusterip/i2c
+            rtl/managed/clusterip/i2s
+            rtl/managed/clusterip/plic
+            rtl/managed/clusterip/ps2
+            rtl/managed/clusterip/pwm
+            rtl/managed/clusterip/rng
+            rtl/managed/clusterip/rtc
+            rtl/managed/clusterip/spi
+            rtl/managed/clusterip/timer
+            rtl/managed/clusterip/uart
+            rtl/managed/clusterip/wdg
+            rtl/managed/third_party
+            rtl/managed/mpw
            .cache/retrosoc/stamps
          key: sources-${{ runner.os }}-${{ hashFiles('config/dependencies.lock.json') }}

@@ -54,7 +54,6 @@ skywater-pdk
 gf180mcu-pdk
 demo*
 dont_use_cell_*
-clusterip
 nanoV
 tinyQV
 kianV
@@ -62,16 +61,17 @@ hazard3
 def.fl
 *yosys*.fl
 *verilator*.fl
-dc.fl
 minirv.sv
 user_design
 *.zip
 *.tar*
 ff16
 lvgl-*
-mpw
 coremark-main
 *wave
-picorv32_ver.v
 socver.*
-3rd-party
+/rtl/managed/clusterip/*
+!/rtl/managed/clusterip/setup.py
+/rtl/managed/mpw/
+/rtl/managed/third_party/
+/rtl/managed/picorv32/rtl/picorv32_ver.v
@@ -6,8 +6,8 @@ This repository contains RTL source files that retain copyright and attribution

 Several RTL files retain the original copyright notice from ETH Zurich and University of Bologna, including files under the following paths:

- rtl/clusterip/**
- rtl/mini/mpw/core/username7/ibex/**
+- rtl/managed/clusterip/**
+- rtl/managed/mpw/core/username7/ibex/**
 - rtl/tech/tc_clk.sv

 The header in rtl/tech/tc_clk.sv also states the Solderpad Hardware License, Version 0.51.
@@ -16,26 +16,26 @@ The header in rtl/tech/tc_clk.sv also states the Solderpad Hardware License, Ver

 The following RTL files retain the original header from the Ravenna example SoC project, which refers to a design using PicoRV32 in ASIC:

- rtl/ip/native/gpio.sv
- rtl/ip/native/timer.sv
- rtl/ip/native/uart.sv
+- rtl/ip/native/peripheral/gpio.sv
+- rtl/ip/native/peripheral/timer.sv
+- rtl/ip/native/serial/uart.sv

 The preserved notice attributes the work to Clifford Wolf and Tim Edwards.

 ## 3. Hirosh Dabui

-The SDRAM controller implementation in rtl/ip/native/sdram_core.sv retains the original copyright notice attributed to Hirosh Dabui.
+The SDRAM controller implementation in rtl/ip/native/memory/sdram_core.sv retains the original copyright notice attributed to Hirosh Dabui.

 ## 4. EmbedFire

 Several SPI/I2C-related RTL files retain the original attribution to EmbedFire and refer to source files such as sd_init.v, sd_write.v, sd_read.v, data_rw_ctrl.v, and i2c_ctrl.v:

- rtl/ip/native/i2c_core.sv
- rtl/ip/native/spisd_core.sv
- rtl/ip/native/spisd_data.sv
- rtl/ip/native/spisd_init.sv
- rtl/ip/native/spisd_read.sv
- rtl/ip/native/spisd_write.sv
+- rtl/ip/native/serial/i2c_core.sv
+- rtl/ip/native/storage/spisd_core.sv
+- rtl/ip/native/storage/spisd_data.sv
+- rtl/ip/native/storage/spisd_init.sv
+- rtl/ip/native/storage/spisd_read.sv
+- rtl/ip/native/storage/spisd_write.sv

 These headers state that the original code was published on GitHub by EmbedFire, but that the original license was not specified in the retained header.

@@ -220,10 +220,10 @@ setup-mpw:
 	@touch $(MPW_STAMP)

 setup-core: setup-mpw
-	python3 $(ROOT_PATH)/rtl/mini/core/setup.py
+	python3 $(ROOT_PATH)/rtl/mini/script/prepare_picorv32.py

 setup-clusterip:
-	python3 $(ROOT_PATH)/rtl/clusterip/setup.py
+	python3 $(ROOT_PATH)/rtl/managed/clusterip/setup.py

 setup-ip:
 	python3 $(ROOT_PATH)/rtl/ip/setup.py
@@ -4,9 +4,9 @@ This repository includes RTL source files that preserve third-party copyright an

 The following third-party projects or authors are referenced in the RTL source headers currently present in this repository:

- ETH Zurich and University of Bologna: notices are preserved in several RTL files under rtl/clusterip/, rtl/mini/mpw/core/username7/ibex/, and in rtl/tech/tc_clk.sv.
- Ravenna / PicoRV32 in ASIC: notices are preserved in rtl/ip/native/gpio.sv, rtl/ip/native/timer.sv, and rtl/ip/native/uart.sv.
- Hirosh Dabui: the original copyright notice is preserved in rtl/ip/native/sdram_core.sv.
- EmbedFire: attribution is preserved in rtl/ip/native/i2c_core.sv and the SPI SD card related files under rtl/ip/native/.
+- ETH Zurich and University of Bologna: notices are preserved in several RTL files under rtl/managed/clusterip/, rtl/managed/mpw/core/username7/ibex/, and in rtl/tech/tc_clk.sv.
+- Ravenna / PicoRV32 in ASIC: notices are preserved in rtl/ip/native/peripheral/gpio.sv, rtl/ip/native/peripheral/timer.sv, and rtl/ip/native/serial/uart.sv.
+- Hirosh Dabui: the original copyright notice is preserved in rtl/ip/native/memory/sdram_core.sv.
+- EmbedFire: attribution is preserved in rtl/ip/native/serial/i2c_core.sv and the SPI SD card related files under rtl/ip/native/storage/.

 These notices are included solely to preserve attribution for the retained third-party source material. They do not alter the licensing terms of the retroSoC repository itself, which is distributed under the Mulan PSL v2 license.
@@ -4,19 +4,19 @@
    "mpw": {
      "url": "https://github.com/retroSoC/mini-ver-mpw.git",
      "revision": "30503eb8a7cf33a0c955913faba5014ebd00186f",
-      "destination": "rtl/mini/mpw",
+      "destination": "rtl/managed/mpw",
      "license": "NOASSERTION"
    },
    "hazard3": {
      "url": "https://github.com/Wren6991/Hazard3.git",
      "revision": "5b3a34f6955e50e03bdcb964201c91462f7078c3",
-      "destination": "rtl/mini/mpw/Hazard3",
+      "destination": "rtl/managed/mpw/Hazard3",
      "license": "NOASSERTION"
    },
    "ibex": {
      "url": "https://github.com/lowRISC/ibex.git",
      "revision": "0c233f54361d769f370889223acc456f2ac19d46",
-      "destination": "rtl/mini/mpw/ibex",
+      "destination": "rtl/managed/mpw/ibex",
      "license": "Apache-2.0"
    },
    "coremark": {
@@ -28,7 +28,7 @@
    "third_party_ip": {
      "url": "https://github.com/retroSoC/3rd-party.git",
      "revision": "d991ec9f7bf696e7e5d840758487068b11bd4121",
-      "destination": "rtl/ip/3rd-party",
+      "destination": "rtl/managed/third_party",
      "license": "NOASSERTION"
    },
    "pdk_ihp130": {
@@ -45,21 +45,21 @@
      "recursive": true,
      "license": "NOASSERTION"
    },
-    "cluster_archinfo": {"url": "https://github.com/retroSoC/archinfo.git", "revision": "d65dd13c83a1176668bf5178004814a1551bf6ba", "destination": "rtl/clusterip/archinfo", "license": "NOASSERTION"},
-    "cluster_clint": {"url": "https://github.com/retroSoC/clint.git", "revision": "ce49f1a5501c0a9f18c0e3f358417648f3f2fb18", "destination": "rtl/clusterip/clint", "license": "NOASSERTION"},
-    "cluster_common": {"url": "https://github.com/retroSoC/common.git", "revision": "d9921eb05160be873aebc46bb2f820bee2c7eebc", "destination": "rtl/clusterip/common", "license": "NOASSERTION"},
-    "cluster_crc": {"url": "https://github.com/retroSoC/crc.git", "revision": "4654a63d06d487b5b9fe22af228c36c736b90bad", "destination": "rtl/clusterip/crc", "license": "NOASSERTION"},
-    "cluster_i2c": {"url": "https://github.com/retroSoC/i2c.git", "revision": "73b024547c5cd70fb8bf801cc7757db2536c604f", "destination": "rtl/clusterip/i2c", "license": "NOASSERTION"},
-    "cluster_i2s": {"url": "https://github.com/retroSoC/i2s.git", "revision": "bd0978e8b45e4cf4c1335a1fa7311385d2a4e805", "destination": "rtl/clusterip/i2s", "license": "NOASSERTION"},
-    "cluster_plic": {"url": "https://github.com/retroSoC/plic.git", "revision": "c851d93829d2e75b224003a058e718925855c0cc", "destination": "rtl/clusterip/plic", "license": "NOASSERTION"},
-    "cluster_ps2": {"url": "https://github.com/retroSoC/ps2.git", "revision": "60921e0f72d6113f8615d03ce54567388fc2410f", "destination": "rtl/clusterip/ps2", "license": "NOASSERTION"},
-    "cluster_pwm": {"url": "https://github.com/retroSoC/pwm.git", "revision": "0777ef085c661d2b103f2fa0f8519f97eea3c950", "destination": "rtl/clusterip/pwm", "license": "NOASSERTION"},
-    "cluster_rng": {"url": "https://github.com/retroSoC/rng.git", "revision": "7374e1e7f25bfd1ff9954ea99f19b77a583def29", "destination": "rtl/clusterip/rng", "license": "NOASSERTION"},
-    "cluster_rtc": {"url": "https://github.com/retroSoC/rtc.git", "revision": "69963b8424cb00e04c8be70157b8ca738464e342", "destination": "rtl/clusterip/rtc", "license": "NOASSERTION"},
-    "cluster_spi": {"url": "https://github.com/retroSoC/spi.git", "revision": "515cb408806584525605b4747db5e890dbdf1928", "destination": "rtl/clusterip/spi", "license": "NOASSERTION"},
-    "cluster_timer": {"url": "https://github.com/retroSoC/timer.git", "revision": "0c44b0d8b742c6a477fda15a812cf22962b54dd8", "destination": "rtl/clusterip/timer", "license": "NOASSERTION"},
-    "cluster_uart": {"url": "https://github.com/retroSoC/uart.git", "revision": "eca12213ba06f42e0a6dd0f27907fd4c447e2774", "destination": "rtl/clusterip/uart", "license": "NOASSERTION"},
-    "cluster_wdg": {"url": "https://github.com/retroSoC/wdg.git", "revision": "b2603c1faeba96603392f0fe9e692e645d7e061f", "destination": "rtl/clusterip/wdg", "license": "NOASSERTION"}
+    "cluster_archinfo": {"url": "https://github.com/retroSoC/archinfo.git", "revision": "d65dd13c83a1176668bf5178004814a1551bf6ba", "destination": "rtl/managed/clusterip/archinfo", "license": "NOASSERTION"},
+    "cluster_clint": {"url": "https://github.com/retroSoC/clint.git", "revision": "ce49f1a5501c0a9f18c0e3f358417648f3f2fb18", "destination": "rtl/managed/clusterip/clint", "license": "NOASSERTION"},
+    "cluster_common": {"url": "https://github.com/retroSoC/common.git", "revision": "d9921eb05160be873aebc46bb2f820bee2c7eebc", "destination": "rtl/managed/clusterip/common", "license": "NOASSERTION"},
+    "cluster_crc": {"url": "https://github.com/retroSoC/crc.git", "revision": "4654a63d06d487b5b9fe22af228c36c736b90bad", "destination": "rtl/managed/clusterip/crc", "license": "NOASSERTION"},
+    "cluster_i2c": {"url": "https://github.com/retroSoC/i2c.git", "revision": "73b024547c5cd70fb8bf801cc7757db2536c604f", "destination": "rtl/managed/clusterip/i2c", "license": "NOASSERTION"},
+    "cluster_i2s": {"url": "https://github.com/retroSoC/i2s.git", "revision": "bd0978e8b45e4cf4c1335a1fa7311385d2a4e805", "destination": "rtl/managed/clusterip/i2s", "license": "NOASSERTION"},
+    "cluster_plic": {"url": "https://github.com/retroSoC/plic.git", "revision": "c851d93829d2e75b224003a058e718925855c0cc", "destination": "rtl/managed/clusterip/plic", "license": "NOASSERTION"},
+    "cluster_ps2": {"url": "https://github.com/retroSoC/ps2.git", "revision": "60921e0f72d6113f8615d03ce54567388fc2410f", "destination": "rtl/managed/clusterip/ps2", "license": "NOASSERTION"},
+    "cluster_pwm": {"url": "https://github.com/retroSoC/pwm.git", "revision": "0777ef085c661d2b103f2fa0f8519f97eea3c950", "destination": "rtl/managed/clusterip/pwm", "license": "NOASSERTION"},
+    "cluster_rng": {"url": "https://github.com/retroSoC/rng.git", "revision": "7374e1e7f25bfd1ff9954ea99f19b77a583def29", "destination": "rtl/managed/clusterip/rng", "license": "NOASSERTION"},
+    "cluster_rtc": {"url": "https://github.com/retroSoC/rtc.git", "revision": "69963b8424cb00e04c8be70157b8ca738464e342", "destination": "rtl/managed/clusterip/rtc", "license": "NOASSERTION"},
+    "cluster_spi": {"url": "https://github.com/retroSoC/spi.git", "revision": "515cb408806584525605b4747db5e890dbdf1928", "destination": "rtl/managed/clusterip/spi", "license": "NOASSERTION"},
+    "cluster_timer": {"url": "https://github.com/retroSoC/timer.git", "revision": "0c44b0d8b742c6a477fda15a812cf22962b54dd8", "destination": "rtl/managed/clusterip/timer", "license": "NOASSERTION"},
+    "cluster_uart": {"url": "https://github.com/retroSoC/uart.git", "revision": "eca12213ba06f42e0a6dd0f27907fd4c447e2774", "destination": "rtl/managed/clusterip/uart", "license": "NOASSERTION"},
+    "cluster_wdg": {"url": "https://github.com/retroSoC/wdg.git", "revision": "b2603c1faeba96603392f0fe9e692e645d7e061f", "destination": "rtl/managed/clusterip/wdg", "license": "NOASSERTION"}
  },
  "archives": {
    "fatfs": {
@@ -71,7 +71,7 @@
    "serv": {
      "url": "https://github.com/olofk/serv/archive/refs/tags/1.4.0.tar.gz",
      "sha256": "f81c37b9f9d548c658e23bb7eb90fbed8b54e2e9e51fa42b8cd2f34cecc472ab",
-      "destination": "rtl/mini/mpw/serv-1.4.0.tar.gz",
+      "destination": "rtl/managed/mpw/serv-1.4.0.tar.gz",
      "license": "ISC"
    }
  },
@@ -13,9 +13,9 @@ extend-exclude = [
  "app/fatfs/ff16",
  "pdk/IHP-Open-PDK",
  "pdk/icsprout55-pdk",
-  "rtl/clusterip",
-  "rtl/ip/3rd-party",
-  "rtl/mini/mpw",
+  "rtl/managed/clusterip",
+  "rtl/managed/third_party",
+  "rtl/managed/mpw",
 ]

 [tool.ruff.lint]
@@ -1,34 +1,79 @@
 {
  "entries": [
    {
-      "count": 2,
-      "example": "CMPCONST:$ROOT/rtl/ip/native/spisd_write.sv:<line>: Comparison is constant due to limited range",
-      "signature": "11b9d285d4747e4f"
+      "count": 1,
+      "example": "UNSIGNED:$ROOT/rtl/ip/native/storage/xpi.sv:<line>: Comparison is constant due to unsigned arithmetic",
+      "signature": "010491867f065cec"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'h8' generates 8 bits.",
+      "signature": "2f1913ee897eabb8"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator EQ expects 32 bits on the LHS, but LHS's SEL generates 8 bits.",
+      "signature": "3bba21d5150bdc2e"
+    },
+    {
+      "count": 1,
+      "example": "UNOPTFLAT:$ROOT/rtl/ip/native/storage/xpi.sv:<line>: Signal unoptimizable: Circular combinational logic: 'retrosoc_top.u_retrosoc_asic.u_xpi_if.io_di_i'",
+      "signature": "411d9ab46fef9d7d"
+    },
+    {
+      "count": 1,
+      "example": "UNSIGNED:$ROOT/rtl/mini/top/ip_nmi_wrapper.sv:<line>: Comparison is constant due to unsigned arithmetic",
+      "signature": "7350cffccb478d64"
    },
    {
      "count": 1,
      "example": "SPECIFYIGN:$ROOT/pdk/IHP-Open-PDK/ihp-sg13g2/libs.ref/sg13g2_sram/verilog/RM_IHPSG13_1P_1024x64_c2_bm_bist.v:<line>: Ignoring unsupported: specify block construct",
      "signature": "7a759d6e07651fd8"
    },
+    {
+      "count": 2,
+      "example": "CMPCONST:$ROOT/rtl/ip/native/storage/spisd_write.sv:<line>: Comparison is constant due to limited range",
+      "signature": "813090adc9f1e8a8"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'h0' generates 8 bits.",
+      "signature": "8ad9b6921bd232e7"
+    },
+    {
+      "count": 1,
+      "example": "UNSIGNED:$ROOT/rtl/mini/top/bus.sv:<line>: Comparison is constant due to unsigned arithmetic",
+      "signature": "9f53ff454a8648a4"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'h4' generates 8 bits.",
+      "signature": "be2cb5333a881eca"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case expression, but Case expression's SEL generates 8 bits.",
+      "signature": "c43a29f4c975e9c1"
+    },
    {
      "count": 68,
      "example": "SPECIFYIGN:$ROOT/pdk/IHP-Open-PDK/ihp-sg13g2/libs.ref/sg13g2_stdcell/verilog/sg13g2_stdcell.v:<line>: Ignoring unsupported: specify block construct",
      "signature": "c54331448f63ac73"
    },
+    {
+      "count": 1,
+      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/storage/spisd_read.sv:<line>: Operator ASSIGNDLY expects 8 bits on the Assign RHS, but Assign RHS's REPLICATE generates 9 bits.",
+      "signature": "c963ef155f9a032c"
+    },
    {
      "count": 3,
-      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/spisd_write.sv:<line>: Bit extraction of var[7:0] requires 3 bit index, not 4 bits.",
-      "signature": "cdd5c3ca84a609c6"
+      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/storage/spisd_write.sv:<line>: Bit extraction of var[7:0] requires 3 bit index, not 4 bits.",
+      "signature": "ef9f314dab2ac31d"
    },
    {
      "count": 1,
-      "example": "UNOPTFLAT:$ROOT/rtl/ip/native/xpi.sv:<line>: Signal unoptimizable: Circular combinational logic: 'retrosoc_top.u_retrosoc_asic.u_xpi_if.io_di_i'",
-      "signature": "ee29e23bc895ee17"
-    },
-    {
-      "count": 1,
-      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/spisd_read.sv:<line>: Operator ASSIGNDLY expects 8 bits on the Assign RHS, but Assign RHS's REPLICATE generates 9 bits.",
-      "signature": "f8f8278c6ce4431d"
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'hc' generates 8 bits.",
+      "signature": "f6f2aa6bb2b3f6c4"
    },
    {
      "count": 11,
@@ -1,9 +1,9 @@
 {
  "entries": [
    {
-      "count": 2,
-      "example": "CMPCONST:$ROOT/rtl/ip/native/spisd_write.sv:<line>: Comparison is constant due to limited range",
-      "signature": "11b9d285d4747e4f"
+      "count": 1,
+      "example": "UNSIGNED:$ROOT/rtl/ip/native/storage/xpi.sv:<line>: Comparison is constant due to unsigned arithmetic",
+      "signature": "010491867f065cec"
    },
    {
      "count": 1,
@@ -25,11 +25,26 @@
      "example": "WIDTHEXPAND:$BUILD/generated/mpw/verilator/core/username6/./darkriscv/darkriscv_username6.v:<line>: Operator COND expects 32 bits on the Conditional True, but Conditional True's LT generates 1 bits.",
      "signature": "259baf70503bfe0d"
    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'h8' generates 8 bits.",
+      "signature": "2f1913ee897eabb8"
+    },
    {
      "count": 1,
      "example": "WIDTHEXPAND:$BUILD/generated/mpw/verilator/core/username6/./darkriscv/darkriscv_username6.v:<line>: Operator COND expects 32 bits on the Conditional True, but Conditional True's LTS generates 1 bits.",
      "signature": "323be25f98c25432"
    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator EQ expects 32 bits on the LHS, but LHS's SEL generates 8 bits.",
+      "signature": "3bba21d5150bdc2e"
+    },
+    {
+      "count": 1,
+      "example": "UNOPTFLAT:$ROOT/rtl/ip/native/storage/xpi.sv:<line>: Signal unoptimizable: Circular combinational logic: 'retrosoc_top.u_retrosoc_asic.u_xpi_if.io_di_i'",
+      "signature": "411d9ab46fef9d7d"
+    },
    {
      "count": 14,
      "example": "WIDTHTRUNC:$BUILD/generated/mpw/verilator/core/username6/./darkriscv/darkriscv_username6.v:<line>: Logical operator COND expects 1 bit on the Conditional Test, but Conditional Test's VARREF 'FLUSH' generates 2 bits.",
@@ -45,25 +60,55 @@
      "example": "UNOPTFLAT:$BUILD/generated/mpw/verilator/core/username1/./kianV/alu_decoder_username1.v:<line>: Signal unoptimizable: Circular combinational logic: 'retrosoc_top.u_retrosoc_asic.u_retrosoc.u_core_wrapper.u_user_core_wrapper.u_user_core_top.u_user_core_design_username1.u_kianv_harris_mc_edition.control_unit_I.alu_decoder_I.ALUControl'",
      "signature": "5dc2cc2658c8e2c1"
    },
+    {
+      "count": 1,
+      "example": "UNSIGNED:$ROOT/rtl/mini/top/ip_nmi_wrapper.sv:<line>: Comparison is constant due to unsigned arithmetic",
+      "signature": "7350cffccb478d64"
+    },
    {
      "count": 1,
      "example": "SPECIFYIGN:$ROOT/pdk/IHP-Open-PDK/ihp-sg13g2/libs.ref/sg13g2_sram/verilog/RM_IHPSG13_1P_1024x64_c2_bm_bist.v:<line>: Ignoring unsupported: specify block construct",
      "signature": "7a759d6e07651fd8"
    },
+    {
+      "count": 2,
+      "example": "CMPCONST:$ROOT/rtl/ip/native/storage/spisd_write.sv:<line>: Comparison is constant due to limited range",
+      "signature": "813090adc9f1e8a8"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'h0' generates 8 bits.",
+      "signature": "8ad9b6921bd232e7"
+    },
+    {
+      "count": 1,
+      "example": "UNSIGNED:$ROOT/rtl/mini/top/bus.sv:<line>: Comparison is constant due to unsigned arithmetic",
+      "signature": "9f53ff454a8648a4"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'h4' generates 8 bits.",
+      "signature": "be2cb5333a881eca"
+    },
+    {
+      "count": 1,
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case expression, but Case expression's SEL generates 8 bits.",
+      "signature": "c43a29f4c975e9c1"
+    },
    {
      "count": 68,
      "example": "SPECIFYIGN:$ROOT/pdk/IHP-Open-PDK/ihp-sg13g2/libs.ref/sg13g2_stdcell/verilog/sg13g2_stdcell.v:<line>: Ignoring unsupported: specify block construct",
      "signature": "c54331448f63ac73"
    },
    {
-      "count": 3,
-      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/spisd_write.sv:<line>: Bit extraction of var[7:0] requires 3 bit index, not 4 bits.",
-      "signature": "cdd5c3ca84a609c6"
+      "count": 1,
+      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/storage/spisd_read.sv:<line>: Operator ASSIGNDLY expects 8 bits on the Assign RHS, but Assign RHS's REPLICATE generates 9 bits.",
+      "signature": "c963ef155f9a032c"
    },
    {
-      "count": 1,
-      "example": "UNOPTFLAT:$ROOT/rtl/ip/native/xpi.sv:<line>: Signal unoptimizable: Circular combinational logic: 'retrosoc_top.u_retrosoc_asic.u_xpi_if.io_di_i'",
-      "signature": "ee29e23bc895ee17"
+      "count": 3,
+      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/storage/spisd_write.sv:<line>: Bit extraction of var[7:0] requires 3 bit index, not 4 bits.",
+      "signature": "ef9f314dab2ac31d"
    },
    {
      "count": 1,
@@ -72,8 +117,8 @@
    },
    {
      "count": 1,
-      "example": "WIDTHTRUNC:$ROOT/rtl/ip/native/spisd_read.sv:<line>: Operator ASSIGNDLY expects 8 bits on the Assign RHS, but Assign RHS's REPLICATE generates 9 bits.",
-      "signature": "f8f8278c6ce4431d"
+      "example": "WIDTHEXPAND:$ROOT/rtl/ip/native/peripheral/sysctrl.sv:<line>: Operator CASE expects 32 bits on the Case Item, but Case Item's CONST '8'hc' generates 8 bits.",
+      "signature": "f6f2aa6bb2b3f6c4"
    },
    {
      "count": 11,
@@ -4,10 +4,11 @@ This directory contains retroSoC SystemVerilog RTL, CPU/IP integration,
 peripheral and technology wrappers, filelists, testbench support, and the Mini
 SoC build entry points.

-`mini/` is the active SoC integration flow. `clusterip/` and `ip/` contain
-managed or generated integration inputs; `filelist/` selects PDK-specific RTL
-sources; `tech/` contains technology wrappers. Respect managed upstream
-boundaries and use setup helpers rather than editing generated MPW output.
+`mini/` is the active SoC integration flow. `managed/` contains locked or
+vendored integration inputs, while `ip/` contains self-owned IP and
+experiments. `filelist/` selects PDK-specific RTL sources; `tech/` contains
+technology wrappers. Respect managed upstream boundaries and use setup helpers
+rather than editing generated MPW output.

 RTL changes require an affected firmware build and simulation. Use
 `make regress-pr` or `make regress-nightly` for supported regression coverage;
@@ -0,0 +1,12 @@
+# Native and Experimental IP
+
+This directory owns project RTL IP.
+
+native groups maintained blocks by function: interconnect, util, memory,
+storage, serial, multimedia, and peripheral. The Mini SoC selects active
+sources explicitly in rtl/mini/filelist/ip.fl, whose source order is part of
+the build contract.
+
+experimental contains retained inactive RTL. It is not included by any active
+filelist and must not become a build dependency without an explicit integration
+change and matching validation.
@@ -0,0 +1,9 @@
+# Experimental RTL
+
+This directory retains self-owned RTL that is not integrated into the active
+Mini SoC profiles. Sources here are intentionally excluded from canonical
+filelists and regressions.
+
+Promote an experimental block only by adding it to a reviewed active filelist,
+updating its documentation and running the affected firmware and simulator
+validation.
@@ -0,0 +1,15 @@
+# Managed RTL Inputs
+
+This directory contains RTL whose source lifecycle is controlled outside the
+ordinary self-owned IP workflow.
+
+- clusterip contains repositories locked by config/dependencies.lock.json.
+- mpw contains the locked Mini-ver-MPW generator and its prepared core inputs.
+- third_party contains the locked external IP repository.
+- picorv32 contains the repository-vendored PicoRV32 source and its
+  flow-generated picorv32_ver.v derivative.
+
+Use the top-level setup targets to update locked inputs. Do not edit MPW output
+or locked checkouts in place. The PicoRV32 derivative is regenerated by the
+setup-core target from the vendored source and preserves the project macro
+contract used by the active filelist.
@@ -5,7 +5,7 @@ import sys
 from pathlib import Path


-ROOT = Path(__file__).resolve().parents[2]
+ROOT = Path(__file__).resolve().parents[3]
 sys.path.insert(0, str(ROOT))
 from scripts.dependency_lock import load_lock  # noqa: E402
 from scripts.setup_helpers import ensure_git_repo  # noqa: E402
@@ -1,6 +1,6 @@
 GENERATED_FL_DIR := $(FLOW_FILELIST_DIR)
-MEMORY_MAP_SOURCE := $(RTL_PATH)/memory_map.json
-MEMORY_MAP_SCRIPT := $(RTL_PATH)/script/generate_memory_map.py
+MEMORY_MAP_SOURCE := $(RTL_PATH)/address_map/memory_map.json
+MEMORY_MAP_SCRIPT := $(RTL_PATH)/address_map/generate_memory_map.py
 MEMORY_MAP_DIR    := $(VARIANT_ROOT)/generated/memory_map
 MEMORY_MAP_STAMP  := $(MEMORY_MAP_DIR)/.stamp
 MEMORY_MAP_RTL_DIR := $(MEMORY_MAP_DIR)/rtl
@@ -15,8 +15,8 @@ FILELIST_TEMPLATES := $(sort $(wildcard $(ROOT_PATH)/rtl/filelist/pdk_*.fl) \
                      $(wildcard $(RTL_PATH)/filelist/*.fl) $(RTL_PATH)/lint.msg)

 $(MPW_STAMP):
-	@test -d $(RTL_PATH)/mpw/.git || { \
-		echo "missing $(RTL_PATH)/mpw; run 'make setup-mpw' first" >&2; \
+	@test -d $(ROOT_PATH)/rtl/managed/mpw/.git || { \
+		echo "missing $(ROOT_PATH)/rtl/managed/mpw; run 'make setup-mpw' first" >&2; \
 		exit 1; \
 	}
 	python3 $(ROOT_PATH)/scripts/prepare_mpw.py \
@@ -0,0 +1,15 @@
+# Mini SoC Integration
+
+This directory is the active Mini SoC integration boundary.
+
+- address_map contains the canonical address-map input and generator.
+- core contains self-owned Mini core wrappers.
+- dv contains behavioural testbench, device models, and Verilator harness
+  sources.
+- 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.
+
+Generated filelists, address-map products, and MPW output belong in the
+configured build variant, not under this directory.
@@ -0,0 +1,8 @@
+# Canonical Address Map
+
+memory_map.json is the sole source for Mini SoC address ranges. Its generator
+emits RTL include definitions, SDK headers, linker memory regions, and the
+filelist include path into the selected build variant.
+
+Validate edits with make check-memory-map and the address-map tests before
+running an affected simulation.
@@ -101,7 +101,7 @@ def join_or(expressions: list[str]) -> str:

 def render_rtl(cpu_reset: int, regions: list[dict[str, Any]]) -> str:
    lines = [
-        "// Generated by rtl/mini/script/generate_memory_map.py; do not edit.",
+        "// Generated by rtl/mini/address_map/generate_memory_map.py; do not edit.",
        "`ifndef RETROSOC_GENERATED_MMAP_DEFINE_SVH",
        "`define RETROSOC_GENERATED_MMAP_DEFINE_SVH",
        "",
@@ -141,7 +141,7 @@ def render_rtl(cpu_reset: int, regions: list[dict[str, Any]]) -> str:

 def render_c(cpu_reset: int, regions: list[dict[str, Any]], have_sram_if: str) -> str:
    lines = [
-        "/* Generated by rtl/mini/script/generate_memory_map.py; do not edit. */",
+        "/* Generated by rtl/mini/address_map/generate_memory_map.py; do not edit. */",
        "#ifndef RETROSOC_GENERATED_MEMORY_MAP_H",
        "#define RETROSOC_GENERATED_MEMORY_MAP_H",
        "",
@@ -174,7 +174,7 @@ def render_c(cpu_reset: int, regions: list[dict[str, Any]], have_sram_if: str) -

 def render_linker(regions: list[dict[str, Any]]) -> str:
    lines = [
-        "/* Generated by rtl/mini/script/generate_memory_map.py; do not edit. */",
+        "/* Generated by rtl/mini/address_map/generate_memory_map.py; do not edit. */",
        "MEMORY",
        "{",
    ]
@@ -1 +1 @@
-/core/picorv32_ver.v
+/picorv32/picorv32_ver.v
@@ -16,5 +16,11 @@
 +incdir+/clusterip/wdg/rtl
 +incdir+/clusterip/crc/rtl
 +incdir+/clusterip/timer/rtl
-+incdir+/ip/native
-+incdir+/ip/3rd-party/model/sdram/
+incdir+/ip/native/interconnect
+incdir+/ip/native/util
+incdir+/ip/native/memory
+incdir+/ip/native/storage
+incdir+/ip/native/serial
+incdir+/ip/native/multimedia
+incdir+/ip/native/peripheral
+incdir+/third_party/model/sdram/
@@ -1,48 +1,48 @@
-/ip/native/psram_core.sv
-/ip/native/psram.sv
-/ip/native/opipsram.sv
-/ip/native/opipsram_core.sv
-/ip/native/spisd_init.sv
-/ip/native/spisd_read.sv
-/ip/native/spisd_write.sv
-/ip/native/spisd_reg.sv
-/ip/native/spisd_cache.sv
-/ip/native/spisd_core.sv
-/ip/native/spisd_data.sv
-/ip/native/spisd.sv
-/ip/native/sdio.sv
-/ip/native/i2c_core.sv
-/ip/native/i2c.sv
-/ip/native/i2s_reg.sv
-/ip/native/i2s_clkgen.sv
-/ip/native/i2s_recv.sv
-/ip/native/i2s_send.sv
-/ip/native/i2s_core.sv
-/ip/native/i2s.sv
-/ip/native/onewire_core.sv
-/ip/native/onewire.sv
-/ip/native/xpi_reg.sv
-/ip/native/xpi_mm.sv
-/ip/native/xpi_clkgen.sv
-/ip/native/xpi_core.sv
-/ip/native/xpi.sv
-/ip/native/dma_core.sv
-/ip/native/dma.sv
-/ip/native/sysctrl.sv
-/ip/native/clint.sv
-/ip/native/sdram_clkgen.sv
-/ip/native/sdram_reg.sv
-/ip/native/sdram_core.sv
-/ip/native/sdram.sv
-/ip/native/dvp_core.sv
-/ip/native/dvp.sv
-/ip/native/timer.sv
-/ip/native/uart.sv
-/ip/native/gpio.sv
-/ip/native/nmi2apb.sv
-/ip/native/ahbl2nmi.sv
-/ip/native/axi4l2nmi.sv
-/ip/native/async_fifo.sv
-/ip/native/fifo.sv
-/ip/native/nmi_regslice.sv
-/ip/native/nmi2nmi.sv
+/ip/native/memory/psram_core.sv
+/ip/native/memory/psram.sv
+/ip/native/memory/opipsram.sv
+/ip/native/memory/opipsram_core.sv
+/ip/native/storage/spisd_init.sv
+/ip/native/storage/spisd_read.sv
+/ip/native/storage/spisd_write.sv
+/ip/native/storage/spisd_reg.sv
+/ip/native/storage/spisd_cache.sv
+/ip/native/storage/spisd_core.sv
+/ip/native/storage/spisd_data.sv
+/ip/native/storage/spisd.sv
+/ip/native/storage/sdio.sv
+/ip/native/serial/i2c_core.sv
+/ip/native/serial/i2c.sv
+/ip/native/serial/i2s_reg.sv
+/ip/native/serial/i2s_clkgen.sv
+/ip/native/serial/i2s_recv.sv
+/ip/native/serial/i2s_send.sv
+/ip/native/serial/i2s_core.sv
+/ip/native/serial/i2s.sv
+/ip/native/serial/onewire_core.sv
+/ip/native/serial/onewire.sv
+/ip/native/storage/xpi_reg.sv
+/ip/native/storage/xpi_mm.sv
+/ip/native/storage/xpi_clkgen.sv
+/ip/native/storage/xpi_core.sv
+/ip/native/storage/xpi.sv
+/ip/native/peripheral/dma_core.sv
+/ip/native/peripheral/dma.sv
+/ip/native/peripheral/sysctrl.sv
+/ip/native/peripheral/clint.sv
+/ip/native/memory/sdram_clkgen.sv
+/ip/native/memory/sdram_reg.sv
+/ip/native/memory/sdram_core.sv
+/ip/native/memory/sdram.sv
+/ip/native/multimedia/dvp_core.sv
+/ip/native/multimedia/dvp.sv
+/ip/native/peripheral/timer.sv
+/ip/native/serial/uart.sv
+/ip/native/peripheral/gpio.sv
+/ip/native/interconnect/nmi2apb.sv
+/ip/native/interconnect/ahbl2nmi.sv
+/ip/native/interconnect/axi4l2nmi.sv
+/ip/native/util/async_fifo.sv
+/ip/native/util/fifo.sv
+/ip/native/interconnect/nmi_regslice.sv
+/ip/native/interconnect/nmi2nmi.sv
@@ -3,7 +3,7 @@
 /clusterip/uart/model/rs232.sv
 /clusterip/i2s/model/mic.sv
 /clusterip/spi/model/w25q128jvxim.sv
-/ip/tb/ESP_PSRAM64H.sv
-/ip/tb/DVP_CAMERA.sv
-/ip/3rd-party/model/sdram/sdr.v
+/model/ESP_PSRAM64H.sv
+/model/DVP_CAMERA.sv
+/third_party/model/sdram/sdr.v
 /tb/retrosoc_tb.sv