pulp-platform · callme-sam · Feb 4, 2026 · Feb 4, 2026 · Feb 5, 2026 · Feb 5, 2026
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,4 @@ testsuite.py
 test.conf
 testsuite*
 testlogs/
+llvm/
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -17,7 +17,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS TRUE)
 set(CMAKE_VERBOSE_MAKEFILE TRUE)
 
 set(CMAKE_EXE_LINKER_FLAGS_INIT "--specs=nosys.specs")
-set(CMAKE_LINK_LIBRARY_USING_WHOLE_ARCHIVE 
+set(CMAKE_LINK_LIBRARY_USING_WHOLE_ARCHIVE
 "-Wl,--whole-archive <LIBRARY> -Wl,--no-whole-archive"
 )
 set(CMAKE_LINK_LIBRARY_USING_WHOLE_ARCHIVE_SUPPORTED True)
@@ -57,6 +57,11 @@ endif()
 
 include(${CMAKE_CURRENT_LIST_DIR}/cmake/utils.cmake)
 
+# Spatz support
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/spatz_config.cmake)
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/spatz_helpers.cmake)
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/bootrom_helpers.cmake)
+
 ################################################################################
 # Add subdirectories                                                           #
 ################################################################################
@@ -74,4 +79,4 @@ add_subdirectory(drivers)
 # Testing                                                                      #
 ################################################################################
 
-add_subdirectory(tests)
+add_subdirectory(tests)
diff --git a/Makefile b/Makefile
@@ -1,7 +1,7 @@
 # Copyright (C) 2025 ETH Zurich and University of Bologna
 #
-# Licensed under the Solderpad Hardware License, Version 0.51 
-# (the "License"); you may not use this file except in compliance 
+# Licensed under the Solderpad Hardware License, Version 0.51
+# (the "License"); you may not use this file except in compliance
 # with the License. You may obtain a copy of the License at
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
@@ -15,13 +15,15 @@
 #
 # Authors: Victor Isachi <victor.isachi@unibo.it>
 # Alberto Dequino <alberto.dequino@unibo.it>
-# 
+#
 # Magia-sdk Makefile
 
 SHELL 			:= /bin/bash
 
 BUILD_DIR 		?= ../sw/tests/$(test)
 MAGIA_DIR 		?= ../
+MAGIA_DIR_ABS	?= $(abspath $(MAGIA_DIR))
+BUILD_DIR_ABS	?= $(MAGIA_DIR_ABS)/sw/tests/$(test)
 GVSOC_DIR 		?= ./gvsoc
 CURR_DIR		?= $(shell pwd)
 GVSOC_ABS_PATH	?= $(CURR_DIR)/gvsoc
@@ -46,6 +48,15 @@ compiler 		?= GCC_PULP
 ISA				?= rv32imcxgap9
 gui 			?= 0
 tiles 			?= 2
+spatz_tests		?= 1
+
+LLVM_CMAKE			?= cmake
+LLVM_DIR			?= llvm
+LLVM_REPO			?= git@github.com:pulp-platform/llvm-project.git
+LLVM_COMMIT			?= b494f2d8dde88723026db8ec16ac6c7ee1e140ca
+LLVM_INSTALL_DIR	?= $(CURR_DIR)/llvm/install
+LLVM_BUILD_DIR		?= $(LLVM_DIR)/llvm-project/build
+LLVM_JOBS			?= 8
 
 tiles_2 		:= $(shell echo $$(( $(tiles) * $(tiles) )))
 tiles_log    	:= $(shell awk 'BEGIN { printf "%.0f", log($(tiles_2))/log(2) }')
@@ -79,13 +90,13 @@ ifeq ($(compiler), GCC_MULTILIB)
 	sed -i -E 's/^#add_subdirectory\(flatatt\)/add_subdirectory\(flatatt\)/' ./tests/magia/mesh/CMakeLists.txt
 	sed -i -E 's/^\/\/#include "utils\/attention_utils.h"/#include "utils\/attention_utils.h"/' ./targets/$(target_platform)/include/tile.h
 endif
-	cmake -DTARGET_PLATFORM=$(target_platform) -DEVAL=$(eval) -DSTALLING=$(stalling) -DFSYNC_MM=$(fsync_mm) -DIDMA_MM=$(idma_mm) -DREDMULE_MM=$(redmule_mm) -DCOMPILER=$(compiler) -DPROFILE_CMP=$(profile_cmp) -DPROFILE_CMI=$(profile_cmi) -DPROFILE_CMO=$(profile_cmo) -DPROFILE_SNC=$(profile_snc) -B build --trace-expand
+	cmake -DTARGET_PLATFORM=$(target_platform) -DEVAL=$(eval) -DSTALLING=$(stalling) -DFSYNC_MM=$(fsync_mm) -DIDMA_MM=$(idma_mm) -DREDMULE_MM=$(redmule_mm) -DCOMPILER=$(compiler) -DPROFILE_CMP=$(profile_cmp) -DPROFILE_CMI=$(profile_cmi) -DPROFILE_CMO=$(profile_cmo) -DPROFILE_SNC=$(profile_snc) -DSPATZ_TESTS=$(spatz_tests) -DSPATZ_LLVM_PATH=$(LLVM_INSTALL_DIR) -B build --trace-expand
 	cmake --build build --verbose
 
 set_mesh:
 ifeq ($(tiles), 1)
 	$(eval mesh_dv=0)
-endif 
+endif
 
 run: set_mesh
 	@echo 'Magia is available at https://github.com/pulp-platform/MAGIA.git'
@@ -107,10 +118,10 @@ else ifeq ($(platform), rtl)
 	cp ./build/bin/$(test) $(BUILD_DIR)/build/verif
 	objcopy --srec-len 1 --output-target=srec $(BIN) $(BIN).s19
 	scripts/parse_s19.pl $(BIN).s19 > $(BIN).txt
-	python3 scripts/s19tomem.py $(BIN).txt $(BUILD_DIR)/build/stim_instr.txt $(BUILD_DIR)/build/stim_data.txt	
+	python3 scripts/s19tomem.py $(BIN).txt $(BUILD_DIR)/build/stim_instr.txt $(BUILD_DIR)/build/stim_data.txt
 	cd $(BUILD_DIR)													&& \
 	cp -sf ../../../sim/modelsim.ini modelsim.ini    				&& \
-	ln -sfn ../../../sim/work work         			
+	ln -sfn ../../../sim/work work
 	riscv32-unknown-elf-objdump -d -S -Mmarch=$(ISA) $(BIN) > $(BIN).dump
 	riscv32-unknown-elf-objdump -d -l -s -Mmarch=$(ISA) $(BIN) > $(BIN).objdump
 	python3 scripts/objdump2itb.py $(BIN).objdump > $(BIN).itb
@@ -120,6 +131,36 @@ else
 	$(error Only rtl and gvsoc are supported as platforms.)
 endif
 
+run_with_spatz: set_mesh
+ifndef test
+	$(error Proper formatting is: make run_with_spatz test=<test_name> platform=<rtl|gvsoc>)
+endif
+ifeq (,$(wildcard ./build/bin/$(test)))
+	$(error No test found with name: $(test))
+endif
+ifndef platform
+	$(error Proper formatting is: make run_with_spatz test=<test_name> platform=rtl|gvsoc)
+endif
+ifeq ($(platform), gvsoc)
+	$(GVSOC_DIR)/install/bin/gvrun --target magia_v2 --work-dir $(GVSOC_ABS_PATH)/Documents/test --param binary=$(BIN_ABS_PATH)/$(test) run --attr magia/n_tiles_x=$(tiles) --attr magia/n_tiles_y=$(tiles) --attr magia_v2/spatz_romfile=$(BIN_ABS_PATH)/bootrom/spatz_init.bin
+else ifeq ($(platform), rtl)
+	mkdir -p $(BUILD_DIR_ABS) && cd $(BUILD_DIR_ABS) && mkdir -p build
+	cp ./build/bin/$(test) $(BUILD_DIR_ABS)/build/verif
+	objcopy --srec-len 1 --output-target=srec $(BUILD_DIR_ABS)/build/verif $(BUILD_DIR_ABS)/build/verif.s19
+	scripts/parse_s19.pl $(BUILD_DIR_ABS)/build/verif.s19 > $(BUILD_DIR_ABS)/build/verif.txt
+	python3 scripts/s19tomem.py $(BUILD_DIR_ABS)/build/verif.txt $(BUILD_DIR_ABS)/build/stim_instr.txt $(BUILD_DIR_ABS)/build/stim_data.txt
+	cd $(BUILD_DIR_ABS)													&& \
+	cp -sf "$(MAGIA_DIR_ABS)/sim/modelsim.ini" modelsim.ini    				&& \
+	ln -sfn "$(MAGIA_DIR_ABS)/sim/work" work
+	riscv32-unknown-elf-objdump -d -S -Mmarch=$(ISA) $(BUILD_DIR_ABS)/build/verif > $(BUILD_DIR_ABS)/build/verif.dump
+	riscv32-unknown-elf-objdump -d -l -s -Mmarch=$(ISA) $(BUILD_DIR_ABS)/build/verif > $(BUILD_DIR_ABS)/build/verif.objdump
+	python3 scripts/objdump2itb.py $(BUILD_DIR_ABS)/build/verif.objdump > $(BUILD_DIR_ABS)/build/verif.itb
+	cd $(MAGIA_DIR_ABS) 												&& \
+	make run test=$(test) gui=$(gui) mesh_dv=$(mesh_dv)
+else
+	$(error Only rtl and gvsoc are supported as platforms.)
+endif
+
 MAGIA: set_mesh
 ifeq ($(shell expr $(tiles_2) \> 256), 1)
 	$(eval tiles_2=256)
@@ -175,4 +216,27 @@ gvsoc_init:
 	cd ../pulp && \
 	git checkout lz/magia-v2-pulp
 
-
+llvm:
+	mkdir -p $(LLVM_DIR)
+	if [ ! -d "$(LLVM_DIR)/llvm-project/.git" ]; then \
+		cd $(LLVM_DIR) && git clone $(LLVM_REPO); \
+	fi
+	cd $(LLVM_DIR)/llvm-project && \
+	git checkout $(LLVM_COMMIT) && \
+	git submodule update --init --recursive --jobs=$(LLVM_JOBS) .
+	mkdir -p $(LLVM_INSTALL_DIR)
+	cd $(LLVM_DIR)/llvm-project && mkdir -p build && cd build && \
+	$(LLVM_CMAKE) \
+		-DCMAKE_INSTALL_PREFIX=$(LLVM_INSTALL_DIR) \
+		-DCMAKE_CXX_COMPILER=${CXX} \
+		-DCMAKE_C_COMPILER=${CC} \
+		-DLLVM_OPTIMIZED_TABLEGEN=True \
+		-DLLVM_ENABLE_PROJECTS="clang;lld" \
+		-DLLVM_TARGETS_TO_BUILD="RISCV" \
+		-DLLVM_DEFAULT_TARGET_TRIPLE=riscv32-unknown-elf \
+		-DLLVM_ENABLE_LLD=False \
+		-DLLVM_APPEND_VC_REV=ON \
+		-DCMAKE_BUILD_TYPE=Release \
+		../llvm && \
+	make -j$(LLVM_JOBS) all && \
+	make install
diff --git a/README.md b/README.md
@@ -36,6 +36,8 @@ The following *optional* parameters can be specified when running the make comma
 
 `profile_cmp|cmi|cmo|snc`: **0**|**1** (**Default**: 0). Activates the profiling utilities for computing|comunication(input line)|comunication(output line)|synchronization
 
+`spatz_tests`: **0**|**1** (**Default**: 1). Enable compilation of tests with Spatz task (along with default mesh tests)
+
 0. In case you are using this SDK as non-submodule: Clone the [MAGIA](https://github.com/pulp-platform/MAGIA/tree/main) repository:
 
     `git clone git@github.com:pulp-platform/MAGIA.git`
@@ -51,9 +53,9 @@ The following *optional* parameters can be specified when running the make comma
 1. Initialize the GVSoC submodule:
 
     `make gvsoc_init`
-    
+
 2. Build the Magia architecture (*this command may take time and return an error, please be patient.*):
-        
+
     `make MAGIA <target_platform> <tiles> <build_mode> <fsync_mode>`
 
     And/Or the GVSoC module:
@@ -90,7 +92,7 @@ The following *optional* parameters can be specified when running the make comma
 
     `make run test=<test_name> <platform>`
 
-***WARNING: YOU HAVE TO REBUILD BOTH RTL/GVSOC AND THE TEST BINARY EACH TIME YOU WANT TO TEST A MAGIA MESH WITH A DIFFERENT NUMBER OF TILES.*** 
+***WARNING: YOU HAVE TO REBUILD BOTH RTL/GVSOC AND THE TEST BINARY EACH TIME YOU WANT TO TEST A MAGIA MESH WITH A DIFFERENT NUMBER OF TILES.***
 
 If you want to run gvsoc or a binary from outside the magia-sdk directory you can edit the **GVSOC_ABS_PATH** and **BIN_ABS_PATH** option in Makefile or directly on the *run* command line.
 
@@ -122,7 +124,7 @@ To add your own test, you have to integrate a new test folder inside the **tests
 4. Add to the *\<test_name\>* directory:
 
     1. A new CMakeList.txt file following this template:
-    
+
             set(TEST_NAME <test_name>)
 
             file(GLOB_RECURSE TEST_SRCS
@@ -142,11 +144,83 @@ To add your own test, you have to integrate a new test folder inside the **tests
                     TARGET ${TEST_NAME}
                     POST_BUILD
                     COMMAND ${CMAKE_OBJDUMP} -dhS -Mmarch=${ISA} $<TARGET_FILE:${TEST_NAME}> > $<TARGET_FILE:${TEST_NAME}>.s)
-    
+
     2. An **src** directory containing your test's source (.c) files
 
     3. An **include** directory containing your test's header (.h) files
 
+## Spatz integration in MAGIA
+
+This SDK provides a flow to compile C code for the Spatz vector accelerator, embed the resulting binary into the main CV32 executable, and manage the execution. This allows the main RISC-V core (CV32) to offload tasks to the Spatz accelerator.
+
+Examples using this flow are available in the `tests/spatz_on_magia/` directory. Each test sub-folder contains a `main.c` for the CV32 host and a `spatz_task/` directory with the source code for the Spatz accelerator.
+
+For more informations about hardware integration, configuration parameters, control interface, programming APIs and execution flow please refer to the [MAGIA-Spatz README](https://github.com/pulp-platform/MAGIA/tree/lb/magia-spatz/spatz)
+
+> **Warning:** The external README linked above is tailored for baremetal hardware development. Some information may overlap or contain minor inaccuracies regarding the specific abstractions and automation provided by this SDK.
+
+### Prerequisites
+
+The compilation flow requires a dedicated Spatz LLVM toolchain.
+You can install it automatically by running the following command from the SDK root:
+
+```sh
+make llvm
+```
+This will clone the required repository and build the toolchain in the `llvm/install` directory. Alternatively, if you have a pre-built toolchain, you can specify its location by passing the `LLVM_INSTALL_DIR` variable to the make command:
+```sh
+make build LLVM_INSTALL_DIR=/path/to/your/llvm/install
+```
+
+### Compilation Flow
+
+The compilation process is managed by two CMake functions defined in `cmake/spatz_helpers.cmake`: `add_spatz_task` and `add_cv32_executable_with_spatz`.
+
+#### 1. `add_spatz_task`
+This function compiles the C code for the Spatz accelerator and prepares it for embedding.
+
+*   **What it does**:
+    1.  Compiles the Spatz source code into an ELF binary using a dedicated `clang` compiler from the Spatz LLVM toolchain.
+    2.  Converts the ELF file into a raw binary format (`.bin`).
+    3.  Uses the `scripts/bin2header.py` script to transform the raw binary into a C header file. This header contains a `uint32_t` array holding the machine code of the Spatz task. This array is placed in a special linker section named `.spatz_binary`.
+    4.  Runs the `scripts/extract_task_symbols.sh` script to append additional information to the header. This script inspects the Spatz ELF file and extracts the addresses of key symbols, defining them as macros. These symbols include:
+        *   `SPATZ_BINARY_START`: The starting memory address where the Spatz binary will be loaded. This is resolved by the CV32 linker.
+        *   `SPATZ_DISPATCHER_LOOP`: The entry point for the Spatz control loop.
+        *   Task function addresses (e.g., `MY_TASK`): Entry points for specific functions within the Spatz code that can be called from the CV32 host.
+
+#### 2. `add_cv32_executable_with_spatz`
+This function compiles the main application for the CV32 core and embeds the Spatz binary within it.
+
+*   **What it does**:
+    1.  Compiles the C source code for the CV32 processor.
+    2.  Includes the header file generated by `add_spatz_task`. By including this header, the Spatz binary (as a C array) becomes part of the CV32 application's source.
+    3.  Links the compiled CV32 code with the Spatz binary data. The main linker script (`targets/magia_v2/link.ld`) ensures that the `.spatz_binary` section is placed at the correct memory address.
+
+### Example Usage
+To use this flow, you need to call the two functions in your `CMakeLists.txt`. The convention is to have separate sources for the host (CV32) and the accelerator (Spatz).
+
+Here is an example from `tests/spatz_on_magia/hello_spatz/CMakeLists.txt`:
+```cmake
+set(TEST_NAME hello_spatz)
+
+# Step 1: Compile the Spatz task and generate the C header
+add_spatz_task(
+    TEST_NAME ${TEST_NAME}
+    TASK_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/spatz_task/hello_task.c
+    FIRST_TASK_NAME hello_task
+)
+
+# Step 2: Compile the CV32 executable and embed the Spatz binary
+add_cv32_executable_with_spatz(
+    TARGET_NAME ${TEST_NAME}
+    SPATZ_HEADER ${SPATZ_HEADER}
+    SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/main.c
+)
+```
+
+### Run Tests
+To run test a special Makefile rule can be used: `make run_with_spatz test=<test_name> platform=<rtl|gvsoc>`.
+
 ## Folder Structure
 
 ### README.md
@@ -171,7 +245,7 @@ Contains the weak definitions of this SDK APIs. These are the API instruction th
 Contains the architecture-specific implementation and source code for the HAL APIs. Despite each implementation having different names, thanks to an aliasing system the programmer can use the same name for the same API instruction on different architectures.
 
 ### devices
-Nothing there. 
+Nothing there.
 
 If MAGIA ever evolves to have a host-offload mechanism, this folder will contain the trampoline functions.
 
@@ -180,4 +254,3 @@ Contains utility files for *cmake* automatic compilation.
 
 ### gvsoc
 A submodule containing the Germain Virtual System on Chip, built to simulate MAGIA (and other PULP-related platforms).
-
diff --git a/cmake/bootrom_helpers.cmake b/cmake/bootrom_helpers.cmake
@@ -0,0 +1,43 @@
+# Spatz bootrom compilation helpers
+
+# add_spatz_bootrom()
+# Builds the Spatz bootrom artifacts (ELF/BIN/DUMP).
+function(add_spatz_bootrom)
+    file(MAKE_DIRECTORY "${SPATZ_BOOTROM_OUTPUT_DIR}")
+
+    # Compile bootrom ELF [MAGIA/spatz/bootrom/Makefile: $(ELF)]
+    add_custom_command(
+        OUTPUT ${SPATZ_BOOTROM_ELF}
+        COMMAND ${SPATZ_CLANG}
+            ${SPATZ_COMPILE_FLAGS}
+            ${SPATZ_CFLAGS_DEFINES}
+            ${SPATZ_LINK_FLAGS}
+            -T${SPATZ_BOOTROM_LINK_SCRIPT}
+            -o ${SPATZ_BOOTROM_ELF}
+            ${SPATZ_BOOTROM_SRC}
+        DEPENDS ${SPATZ_BOOTROM_SRC} ${SPATZ_BOOTROM_LINK_SCRIPT}
+        COMMENT "[SPATZ-BOOTROM] Compiling bootrom ELF..."
+        VERBATIM
+    )
+
+    # Extract binary [MAGIA/spatz/bootrom/Makefile: $(BIN)]
+    add_custom_command(
+        OUTPUT ${SPATZ_BOOTROM_BIN}
+        COMMAND ${SPATZ_OBJCOPY} -O binary ${SPATZ_BOOTROM_ELF} ${SPATZ_BOOTROM_BIN}
+        DEPENDS ${SPATZ_BOOTROM_ELF}
+        COMMENT "[SPATZ-BOOTROM] Generating bootrom binary..."
+        VERBATIM
+    )
+
+    # Generate disassembly [MAGIA/spatz/bootrom/Makefile: $(DUMP)]
+    add_custom_command(
+        OUTPUT ${SPATZ_BOOTROM_DUMP}
+        COMMAND ${SPATZ_OBJDUMP} -D ${SPATZ_BOOTROM_ELF} > ${SPATZ_BOOTROM_DUMP}
+        DEPENDS ${SPATZ_BOOTROM_ELF}
+        COMMENT "[SPATZ-BOOTROM] Generating disassembly..."
+        VERBATIM
+    )
+
+    add_custom_target(spatz_bootrom ALL DEPENDS ${SPATZ_BOOTROM_BIN} ${SPATZ_BOOTROM_DUMP})
+    set(SPATZ_BOOTROM_BIN ${SPATZ_BOOTROM_BIN} PARENT_SCOPE)
+endfunction()