Xeratec · Mar 6, 2026 · Mar 4, 2026 · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/.gitignore b/.gitignore
@@ -7,9 +7,12 @@ idma
 hyperbus
 snitch_cluster
 .cache
-deps/
+# Bender checks its dependencies out into the repo-root deps/ only; anchor so it
+# does not also ignore committed paths like sw/deps/chimera-sdk (the SDK submodule).
+/deps/
 *.OLD
 *.egg-info/
+*compile.log
 
 # EMACS
 
@@ -41,6 +44,7 @@ utils/verible-verilog
 *wave*.do
 target/sim/models
 target/sim/vsim/work
+target/sim/vsim/runs
 target/sim/vsim/transcript
 target/sim/vsim/*.do
 target/sim/vsim/trace*
@@ -53,3 +57,22 @@ vsim.wlf
 
 nonfree/
 working_dir/
+
+# GENERATED (SystemRDL / peakrdl)
+
+.generated/
+docs/addressmap.md
+
+# TEST / PROFILING ARTIFACTS
+
+chim-test-report.xml
+gmon.out
+
+# CONTAINERS
+
+# Auto-pulled toolchain images (see scripts/sdk_container.sh); never commit them.
+*.sif
+.cache/containers/
+
+# Claude
+.claude/
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,4 @@
+[submodule "sw/deps/chimera-sdk"]
+	path = sw/deps/chimera-sdk
+	url = https://github.com/Xeratec/chimera-sdk.git
+	branch = dev/multi-binary
diff --git a/.python-version b/.python-version
@@ -0,0 +1 @@
+3.11
diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.json
@@ -0,0 +1,13 @@
+{
+    "configurations": [
+        {
+            "name": "chimera-sdk",
+            "compileCommands": "${workspaceFolder}/sw/deps/chimera-sdk/build/compile_commands.json",
+            "compilerPath": "/usr/pack/llvm-17.0.6-af/bin/clang",
+            "cStandard": "c11",
+            "cppStandard": "c++17",
+            "intelliSenseMode": "linux-clang-x64"
+        }
+    ],
+    "version": 4
+}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "ms-vscode.cpptools"
+    ]
+}
diff --git a/Bender.local b/Bender.local
@@ -0,0 +1,3 @@
+overrides:
+  common_cells:             { git: "https://github.com/pulp-platform/common_cells.git",       rev: ca9d577f2fbc45ec557ab4e0905bbfc154441540 } # snitch branch from 15.12.25 commit "Add iomsb function used in most other PULP repos"
+  axi:                      { git: "https://github.com/colluca/axi",                          rev: bd1abffc0812f8170902e5fb93142c7785c0b8c1 } #  idma:                     { git: "https://github.com/pulp-platform/iDMA.git",               rev: 28a36e5e07705549e59fc33db96ab681bc1ca88e}
diff --git a/Bender.lock b/Bender.lock
@@ -17,7 +17,7 @@ packages:
     - obi_peripherals
     - register_interface
   axi:
-    revision: 8e04779f341eb2c89412aae92223a292beef487e
+    revision: bd1abffc0812f8170902e5fb93142c7785c0b8c1
     version: null
     source:
       Git: https://github.com/colluca/axi
@@ -37,8 +37,8 @@ packages:
     - register_interface
     - tech_cells_generic
   axi_riscv_atomics:
-    revision: 0ac3a78fe342c5a5b9b10bff49d58897f773059e
-    version: 0.8.2
+    revision: 97a1dd2ac643c276880420a0cf8eea697f228aa9
+    version: 0.8.3
     source:
       Git: https://github.com/pulp-platform/axi_riscv_atomics.git
     dependencies:
@@ -71,7 +71,7 @@ packages:
     - common_cells
     - register_interface
   cheshire:
-    revision: 1b6ba6294a5925a5dc199b4f98704adb76648ed1
+    revision: b34d22838ed54b8f4f941f4eabb6a15ca29192a0
     version: null
     source:
       Git: https://github.com/pulp-platform/cheshire.git
@@ -87,6 +87,7 @@ packages:
     - common_cells
     - common_verification
     - cva6
+    - dram_rtl_sim
     - idma
     - irq_router
     - opentitan_peripherals
@@ -95,8 +96,8 @@ packages:
     - serial_link
     - unbent
   clic:
-    revision: 8ed76ffc779a435d0ed034f3068e4c3334fe2ecf
-    version: 2.0.0
+    revision: 6515a71eb4ae3b143ab912d265e79832b3179a76
+    version: 3.0.0
     source:
       Git: https://github.com/pulp-platform/clic.git
     dependencies:
@@ -128,8 +129,8 @@ packages:
     dependencies:
     - common_cells
   common_cells:
-    revision: 9afda9abb565971649c2aa0985639c096f351171
-    version: 1.38.0
+    revision: ca9d577f2fbc45ec557ab4e0905bbfc154441540
+    version: null
     source:
       Git: https://github.com/pulp-platform/common_cells.git
     dependencies:
@@ -142,17 +143,24 @@ packages:
       Git: https://github.com/pulp-platform/common_verification.git
     dependencies: []
   cva6:
-    revision: 630bd959c9cc69a35d461a2abc205310d2edacf8
+    revision: 4c02b24fe7c04690f626776a92274da24f80d1da
     version: null
     source:
-      Git: https://github.com/Scheremo/cva6.git
+      Git: https://github.com/pulp-platform/cva6.git
     dependencies:
     - axi
     - common_cells
     - fpnew
     - tech_cells_generic
+  dram_rtl_sim:
+    revision: 2cac4a9e12a60537567276b539ab6c919c87b5dc
+    version: 0.1.1
+    source:
+      Git: https://github.com/pulp-platform/dram_rtl_sim.git
+    dependencies:
+    - axi
   fpnew:
-    revision: a8e0cba6dd50f357ece73c2c955d96efc3c6c315
+    revision: e5aa6a01b5bbe1675c3aa8872e1203413ded83d1
     version: null
     source:
       Git: https://github.com/pulp-platform/cvfpu.git
@@ -167,8 +175,8 @@ packages:
     dependencies:
     - common_cells
   hyperbus:
-    revision: 841deb9d821b63bf05a1c85d3a4746352a8bcae2
-    version: null
+    revision: 2a14bd8f9a985b488ee23d240764f52f129f7729
+    version: 0.0.9
     source:
       Git: https://github.com/pulp-platform/hyperbus.git
     dependencies:
@@ -198,7 +206,7 @@ packages:
     - common_cells
     - register_interface
   memory_island:
-    revision: 64828cb7a9ccc1f1656ec92d06129072f445c319
+    revision: d072ba0945adad5ccd0af2d4604abe57c1058252
     version: null
     source:
       Git: https://github.com/pulp-platform/memory_island.git
@@ -234,8 +242,8 @@ packages:
     - register_interface
     - tech_cells_generic
   register_interface:
-    revision: 8e8c209ea559d3b54f45cf30fcce95ce70ff5e49
-    version: 0.4.6
+    revision: d6e1d4cdaab7870f4faf3f88a1c788eaf5ac129d
+    version: 0.4.7
     source:
       Git: https://github.com/pulp-platform/register_interface.git
     dependencies:
@@ -252,8 +260,8 @@ packages:
     - common_cells
     - tech_cells_generic
   scm:
-    revision: 472f99affe44ff7b282b519c047a3cfeb35b16c6
-    version: 1.2.0
+    revision: 1976c7efb4979271eee2abe262fde0f9a20e2557
+    version: 1.2.1
     source:
       Git: https://github.com/pulp-platform/scm.git
     dependencies:

diff --git a/Bender.yml b/Bender.yml
@@ -9,25 +9,20 @@ package:
     - "Lorenzo Leone <lleone@iis.ee.ethz.ch>"
 
 dependencies:
-  register_interface:       { git: "https://github.com/pulp-platform/register_interface.git", version: 0.4.3  }
-  axi:                      { git: https://github.com/colluca/axi,                            rev: multicast }
-  cheshire:                 { git: "https://github.com/pulp-platform/cheshire.git",           rev: 1b6ba6294a5925a5dc199b4f98704adb76648ed1}
-  snitch_cluster:           { git: "https://github.com/pulp-platform/snitch_cluster.git",     rev: 5b2fccd96c42812774c20ab2f9b811e164809789}
-  common_cells:             { git: "https://github.com/pulp-platform/common_cells.git",       version: 1.31.1}
+  register_interface:       { git: "https://github.com/pulp-platform/register_interface.git", version: 0.4.7 }
+  axi:                      { git: "https://github.com/colluca/axi",                          rev: bd1abffc0812f8170902e5fb93142c7785c0b8c1 } #
+  cheshire:                 { git: "https://github.com/pulp-platform/cheshire.git",           rev: wiesep/chimera-main }
+  snitch_cluster:           { git: "https://github.com/pulp-platform/snitch_cluster.git",     rev: 5b2fccd96c42812774c20ab2f9b811e164809789 } # main branch from 22.09.25 commit "treewide: Bump AXI after rebase"
+  common_cells:             { git: "https://github.com/pulp-platform/common_cells.git",       version: 1.39.0 }
   idma:                     { git: "https://github.com/pulp-platform/iDMA.git",               version: 0.6.5 }
-  memory_island:            { git: "https://github.com/pulp-platform/memory_island.git",      rev: 64828cb7a9ccc1f1656ec92d06129072f445c319 } # main branch
-  apb:                      { git: "https://github.com/pulp-platform/apb.git",                version: 0.2.4          }
-  hyperbus:                 { git: "https://github.com/pulp-platform/hyperbus.git",           rev: aottaviano/nonfree } # TMP: to fix hyperbus model issue
+  memory_island:            { git: "https://github.com/pulp-platform/memory_island.git",      rev: main }
+  apb:                      { git: "https://github.com/pulp-platform/apb.git",                version: 0.2.4 }
+  hyperbus:                 { git: "https://github.com/pulp-platform/hyperbus.git",           version : 0.0.9 }
   tech_cells_generic:       { git: "https://github.com/pulp-platform/tech_cells_generic.git", version: 0.2.12 }
 
 export_include_dirs:
   - hw/include
 
-workspace:
-  package_links:
-    cheshire: cheshire
-    idma: idma
-
 sources:
   # Level 0
   - hw/chimera_pkg.sv

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+Guidance for Claude Code (claude.ai/code) when working in this repository.
+
+## What Chimera is
+
+Chimera is an open-source, configurable heterogeneous SoC template (PULP Platform, ETH Zurich /
+University of Bologna). It integrates:
+
+- a **Cheshire** host SoC (64-bit CVA6, CLINT/PLIC/CLIC, JTAG debug, UART/I²C/SPI/GPIO, AXI LLC),
+- up to **5 Snitch clusters** (9 cores each) as compute accelerators,
+- a shared multi-banked **memory island** (`0x4800_0000`),
+- a **HyperBus** controller for off-chip HyperRAM (`0x8000_0000`).
+
+This repo is the *integration layer*: almost all leaf IP comes from Bender git dependencies
+(cheshire, snitch_cluster, idma, memory_island, hyperbus, axi, common_cells, …). The RTL here
+wires those together and adds SoC-control registers, a Snitch bootrom, and the cluster/memory
+adapters.
+
+## Documentation map
+
+Detailed docs live in `docs/`:
+
+- `docs/architecture.md` — SoC block diagram, HW module map, full address map.
+- `docs/build-system.md` — Bender + Make flow, every target, dependency versions.
+- `docs/software.md` — SW build, the cluster-offload model, test inventory, linker layout.
+- `docs/verification.md` — current sim/test flow **and** the planned pytest-based framework.
+- `docs/sdk-integration.md` — plan to adopt `chimera-sdk` as the SW layer.
+
+`TODO.md` (repo root) tracks the active cleanup / verification-framework initiative.
+
+## Environment
+
+IIS members: `source iis-env.sh` (pins bender-0.31.0, questa-2022.3, RISC-V GCC 32/64, Snitch
+LLVM, python3.11; auto-creates `.venv`). Non-IIS: `make python-venv`, install Bender, and a
+RISC-V GCC toolchain (`RISCV_GCC_BINROOT`). See `README.md`.
+
+## Build (current Bender + Make flow)
+
+```sh
+bender checkout
+make chim-all        # = HW (chs-hw-init sn-hw-all chim-bootrom-init) + SW (chim-sw) + sim (chim-sim)
+```
+
+Selective:
+```sh
+make chs-hw-init         # patch PLIC, gen iDMA, build libchimera.a, then Cheshire chs-hw-all
+make sn-hw-all           # generate Snitch cluster RTL (uses cfg/default.json)
+make chim-sw             # build libchimera.a + all sw/tests/*.c -> *.memisl.elf
+make chim-bootrom-init   # Cheshire bootrom  (⚠ requires chim-sw first)
+make snitch_bootrom      # regenerate hw/bootrom/snitch/snitch_bootrom.sv (rv32im)
+make chim-sim            # fetch HyperRAM model + compile RTL in Questa
+make chim-run-batch BINARY=sw/tests/<test>.memisl.elf   # run a test (batch)
+make help                # list all targets
+```
+
+Key gotchas:
+- **`chim-sw` must run before `chim-bootrom-init`** (bootrom embeds SW).
+- Host builds at `CHS_XLEN=64` (`rv64gc_zifencei`/`lp64d`); the Snitch bootrom is **rv32im**.
+- Register offsets come from generated `sw/include/regs/soc_ctrl.h`; regenerate with
+  `make regenerate_soc_regs` after editing `hw/regs/chimera_regs.hjson`.
+- Core counts are hardcoded in `chimera.mk` (`CLINTCORES/PLICCORES/PLIC_NUM_INTRS`) and must
+  track `ExtClusters`/`NrCores` in `hw/chimera_pkg.sv`.
+
+## Running / writing tests
+
+Today a "test" is a host (CVA6) ELF linked into the memory island; it drives SoC-control
+registers and offloads functions to clusters via a shared-memory function-pointer + CLINT MSIP
+mechanism. Pass/fail = the program's return code. CI runs a fixed matrix via `chim-run-batch`
+and greps the transcript with `scripts/vsim_ret_error.sh`. See `docs/software.md` (offload model,
+test inventory) and `docs/verification.md` (the planned pytest framework that replaces the
+grep-the-transcript approach).
+
+## Formatting
+
+```sh
+verible-verilog-format --flagfile .verilog_format --inplace hw/*.sv target/sim/src/*.sv
+python scripts/run_clang_format.py -ir sw/    # llvm-12; on IIS pass --clang-format-executable=<pulp-llvm>/bin/clang-format
+```
+
+## Conventions
+
+- Every source file carries an SPDX header (SHL-0.51 for HW/scripts, Apache-2.0 for SW and
+  generated register RTL).
+- Do not commit build artifacts. Most are gitignored; note `build/` is currently a gap.
+- `iis_compile.sh` is an empty placeholder (0 bytes) — safe to ignore/remove.
diff --git a/Makefile b/Makefile
@@ -35,7 +35,7 @@ SN_CFG = $(SN_ROOT)/cfg/default.json
 BENDER_YML = $(CHIM_ROOT)/Bender.yml
 BENDER_LOCK = $(CHIM_ROOT)/Bender.lock
 
-CHS_XLEN ?= 32
+CHS_XLEN ?= 64
 
 CHIM_HW_DIR ?= $(CHIM_ROOT)/hw
 CHIM_SW_DIR ?= $(CHIM_ROOT)/sw
@@ -46,20 +46,19 @@ CHIM_SW_DIR ?= $(CHIM_ROOT)/sw
 ########
 # MISC #
 ########
-BASE_PYTHON ?= python
-PIP_CACHE_DIR ?= $(CHIM_ROOT)/.cache/pip
+UV ?= uv
+# Keep the uv cache on the (writable, large) repo scratch, not $HOME (small IIS quota).
+export UV_CACHE_DIR ?= $(CHIM_ROOT)/.cache/uv
 
-.PHONY: dvt-flist pythomn-venv python-venv-clean
+.PHONY: dvt-flist python-venv python-venv-clean
 
 dvt_flist:
 	mkdir -p .dvt
 	$(BENDER) script flist-plus $(COMMON_TARGS) $(SIM_TARGS) > .dvt/default.build
 
-python-venv: .venv ## Create a Python virtual environment
+python-venv: .venv ## Create the Python virtual environment (uv)
 .venv:
-	$(BASE_PYTHON) -m venv $@
-	. $@/bin/activate && \
-	python -m pip install --cache-dir $(PIP_CACHE_DIR) .
+	$(UV) sync
 
 python-venv-clean: ## Clean Python virtual environment
 	rm -rf .venv

diff --git a/bender.mk b/bender.mk
@@ -6,6 +6,6 @@
 # Lorenzo Leone <lleone@iis.ee.ethz.ch>
 
 COMMON_TARGS ?=
-COMMON_TARGS += -t snitch_cluster -t cv32a6_convolve -t cva6 -t rtl
+COMMON_TARGS += -t snitch_cluster -t snitch_cluster_wrapper -t cv64a6_imafdchsclic_sv39_wb -t cva6 -t rtl
 
 SIM_TARGS = $(COMMON_TARGS) -t test -t sim
diff --git a/chimera.mk b/chimera.mk
@@ -23,7 +23,7 @@ gen_idma_hw:
 CHS_SW_LD_DIR = $(CHIM_ROOT)/sw/link
 
 .PHONY: chs-hw-init
-chs-hw-init: update_plic gen_idma_hw $(CHIM_SW_LIB) ## Generate Cheshire RTL
+chs-hw-init: update_plic gen_idma_hw ## Generate Cheshire RTL
 	make -B chs-hw-all CHS_XLEN=$(CHS_XLEN) CHS_SW_LD_DIR=$(CHS_SW_LD_DIR)
 
 ##################
@@ -51,8 +51,8 @@ $(CHIM_HW_DIR)/regs/pcr.md: $(CHIM_ROOT)/hw/regs/chimera_regs.hjson
 
 
 .PHONY: snitch_bootrom
-CHIM_BROM_SRCS = $(wildcard $(CHIM_ROOT)/hw/bootrom/snitch/*.S $(CHIM_ROOT)/hw/bootrom/snitch/*.c) $(CHIM_SW_LIBS)
-CHIM_BROM_FLAGS = $(CHS_SW_LDFLAGS) -Os -fno-zero-initialized-in-bss -flto -fwhole-program -march=rv32im
+CHIM_BROM_SRCS = $(wildcard $(CHIM_ROOT)/hw/bootrom/snitch/*.S $(CHIM_ROOT)/hw/bootrom/snitch/*.c)
+CHIM_BROM_FLAGS = $(CHS_SW_LDFLAGS) -Os -fno-zero-initialized-in-bss -flto -fwhole-program -march=rv32im_zicsr -mabi=ilp32
 
 CHIM_BOOTROM_ALL += $(CHIM_ROOT)/hw/bootrom/snitch/snitch_bootrom.sv $(CHIM_ROOT)/hw/bootrom/snitch/snitch_bootrom.dump
 
@@ -78,7 +78,7 @@ $(CHIM_ROOT)/hw/regs/chimera_reg_pkg.sv $(CHIM_ROOT)/hw/regs/chimera_reg_top.sv:
 
 -include $(CHIM_ROOT)/bender.mk
 
-# Necessary to build libchimera.a for bootrom.elf
+# Provides the Snitch bootrom include paths + flags (sw/include, march/ABI)
 -include $(CHIM_ROOT)/sw/sw.mk
 
 # Include subdir Makefiles