Zephyr: Reorganize build around CUSTOM_BUILD facility

Previously, the Zephyr tests requires special rules per test.

This commit instead rewrites the Zephyr test platform to merely
register a CUSTOM_BUILD macro replacing the default compilation+linking
step with a native CMake build of a Zephyr test application wrapping
the test sources.

All standard CFLAGS are forwarded, modulo some renaming.

Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>

Author: hanno-becker

.github/workflows/zephyr.yml

@@ -42,6 +42,9 @@ jobs:
           alloc: false
           rng_fail: false
           check_namespace: false
+          # Zephyr's CMake selects the target arch; disable the host-arch
+          # auto-detection that would otherwise leak into the forwarded CFLAGS.
+          extra_args: --no-auto
       # Smoke only: QEMU doesn't model cycle counts (real numbers come from the
       # FPGA); this just exercises the bench build + run.
       - name: bench (smoke)
@@ -50,5 +53,5 @@ jobs:
           ZEPHYR_TARGET: ${{ matrix.target.board }}
         run: |
           opt=${{ matrix.target.opt == 'all' && 'opt' || 'no_opt' }}
-          nix develop .#zephyr --command ./scripts/tests bench -c PMU --opt=$opt
-          nix develop .#zephyr --command ./scripts/tests bench --components -c PMU --opt=$opt
+          nix develop .#zephyr --command ./scripts/tests bench --no-auto -c PMU --opt=$opt
+          nix develop .#zephyr --command ./scripts/tests bench --no-auto --components -c PMU --opt=$opt

test/zephyr/README.md

@@ -0,0 +1,58 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Zephyr test platform
+
+This is a test platform that builds the mlkem-native test applications as
+[Zephyr](https://www.zephyrproject.org/) applications, so they can run on
+QEMU-emulated Arm MPS boards. It covers Cortex-M3/M4/M7/M33/M55 through a
+single platform, without the need for per-board hardware abstraction layers.
+
+## Usage
+
+The platform is selected through the `EXTRA_MAKEFILE` environment variable and
+driven by the usual test targets from the top-level `Makefile`. It must run
+inside the `zephyr` Nix development shell, which provides the Arm toolchain,
+QEMU, and the Zephyr tree (`ZEPHYR_BASE`). The board is chosen with the
+`ZEPHYR_TARGET` environment variable (default `mps3-an547`):
+
+```
+export EXTRA_MAKEFILE=test/zephyr/platform.mk
+export ZEPHYR_TARGET=mps3-an547
+nix develop .#zephyr --command ./scripts/tests func --opt=opt
+```
+
+Currently supported targets:
+
+| `ZEPHYR_TARGET` | Zephyr board          | QEMU machine | Core       |
+| --------------- | --------------------- | ------------ | ---------- |
+| `mps2-an385`    | `mps2/an385`          | `mps2-an385` | Cortex-M3  |
+| `mps2-an386`    | `mps2/an386`          | `mps2-an386` | Cortex-M4  |
+| `mps2-an500`    | `mps2/an500`          | `mps2-an500` | Cortex-M7  |
+| `mps2-an521`    | `mps2/an521/cpu0`     | `mps2-an521` | Cortex-M33 |
+| `mps3-an547`    | `mps3/corstone300/an547` | `mps3-an547` | Cortex-M55 |
+
+The Armv8.1-M MVE FIPS202 backend is an `OPT=1` feature and is built for
+`mps3-an547` only (the only listed core with MVE).
+
+## How it works
+
+Test binaries are built as Zephyr applications using Zephyr's standard
+CMake-based build, registered as a `CUSTOM_BUILD` hook in mlkem-native's
+makefiles.
+
+The Zephyr application lives in `app/`:
+
+- `app/CMakeLists.txt` compiles the `mlkem_native.c` amalgamation, the test
+  sources, and `shim.c`. The test's `main()` is renamed to `mlk_test_main` via
+  `-Dmain=mlk_test_main` so the shim can own `main()`.
+- `app/shim.c` fetches argv via semihosting, calls `mlk_test_main`, and exits
+  QEMU with the test's return code (again via semihosting).
+- `app/Kconfig` force-selects the FPU/MVE features for Corstone-300, whose
+  Zephyr SoC does not otherwise advertise MVE.
+
+`platform.mk` forwards the test binary's full `CFLAGS` to the CMake build, so
+the firmware is compiled with the project's own warning/optimization/standard
+policy and feature defines rather than a divergent Zephyr default.
+
+`exec_wrapper.py` runs a built ELF under QEMU (`-nographic`, semihosting on),
+forwarding the guest's exit code; it is wired in as `EXEC_WRAPPER`.

test/zephyr/app/CMakeLists.txt

@@ -7,30 +7,45 @@ project(mlkem_native_zephyr)
 
 # Parameters supplied via -D from platform.mk:
 #   ZEPHYR_NATIVE_ROOT - mlkem-native checkout the test is built from
-#   ZEPHYR_LEVEL       - ML-KEM parameter set: 512 | 768 | 1024
-#   ZEPHYR_TEST_SRC    - test entrypoint, relative to ZEPHYR_NATIVE_ROOT
-#   ZEPHYR_TEST_DEFS   - optional extra -D defines (space separated)
+#   ZEPHYR_TEST_SRCS   - test sources (entrypoint + support, e.g. notrandombytes
+#                        and -- for bench -- the HAL), relative to
+#                        ZEPHYR_NATIVE_ROOT, space separated
+#   ZEPHYR_TEST_CFLAGS - the test binary's CFLAGS (see below); includes the
+#                        parameter set (-DMLK_CONFIG_PARAMETER_SET=...)
 set(R ${ZEPHYR_NATIVE_ROOT})
 
+separate_arguments(_test_srcs UNIX_COMMAND "${ZEPHYR_TEST_SRCS}")
+list(TRANSFORM _test_srcs PREPEND ${R}/)
+
 target_sources(app PRIVATE
   ${R}/mlkem/mlkem_native.c
-  ${R}/${ZEPHYR_TEST_SRC}
-  ${R}/test/notrandombytes/notrandombytes.c
+  ${_test_srcs}
   ${CMAKE_CURRENT_SOURCE_DIR}/shim.c
 )
 
 target_include_directories(app PRIVATE
   ${R}/mlkem
   ${R}/test/notrandombytes
+  ${R}/test/hal
 )
 
-target_compile_definitions(app PRIVATE MLK_CONFIG_PARAMETER_SET=${ZEPHYR_LEVEL})
-
-if(ZEPHYR_TEST_DEFS)
-  separate_arguments(_defs UNIX_COMMAND "${ZEPHYR_TEST_DEFS}")
-  target_compile_definitions(app PRIVATE ${_defs})
+# The test binary's CFLAGS, forwarded from the build (test/zephyr/platform.mk
+# assembles and escapes them) and applied to the mlkem amalgamation and the test
+# sources alike, so both honour the project's own warning/opt/std policy and
+# per-test feature defines rather than a divergent Zephyr default.
+if(ZEPHYR_TEST_CFLAGS)
+  separate_arguments(_cflags UNIX_COMMAND "${ZEPHYR_TEST_CFLAGS}")
+  target_compile_options(app PRIVATE ${_cflags})
 endif()
 
+# The benchmark HAL is the only test source that pulls in Zephyr SDK headers
+# (<zephyr/kernel.h> for the cycle counter). Those headers are not clean under
+# the project's strict, -Werror'd warning set forwarded above (e.g.
+# -Wconversion, -Wsign-conversion, -pedantic), so drop -Werror just for this
+# file -- our own sources stay strict.
+set_source_files_properties(${R}/test/hal/hal.c
+  PROPERTIES COMPILE_OPTIONS "-Wno-error")
+
 # Optional native FIPS202 backend (e.g. Armv8.1-M MVE on Cortex-M55). The
 # monolithic mlkem_native.c already includes the backend C sources; its
 # assembly counterpart comes from mlkem_native_asm.S.
@@ -41,13 +56,9 @@ if(ZEPHYR_FIPS202_BACKEND)
     "MLK_CONFIG_FIPS202_BACKEND_FILE=\"${ZEPHYR_FIPS202_BACKEND}\"")
 endif()
 
-# The bench tests need the cycle-counting HAL.
-if(ZEPHYR_TEST_HAL)
-  target_sources(app PRIVATE ${R}/test/hal/hal.c)
-  target_include_directories(app PRIVATE ${R}/test/hal)
-endif()
-
 # Each test brings its own int main(void); rename it so the Zephyr shim
-# (shim.c) owns main() and can stop QEMU with the test's exit code.
-set_source_files_properties(${R}/${ZEPHYR_TEST_SRC}
+# (shim.c) owns main() and can stop QEMU with the test's exit code. Only the
+# test entrypoint in ZEPHYR_TEST_SRCS defines main(); the support sources
+# (notrandombytes, hal) don't, so applying the define to all is harmless.
+set_source_files_properties(${_test_srcs}
   PROPERTIES COMPILE_DEFINITIONS "main=mlk_test_main")

test/zephyr/app/Kconfig

@@ -5,10 +5,10 @@
 # QEMU's mps3-an547) has it. Force-select it to build the Armv8.1-M MVE FIPS202
 # backend. Enabled per target by platform.mk.
 config FIPS202_MVE_BACKEND
-	bool "Build with the Armv8.1-M MVE FIPS202 backend"
-	select FPU
-	select ARMV8_M_DSP
-	select ARMV8_1_M_MVEI
-	select ARMV8_1_M_MVEF
+    bool "Build with the Armv8.1-M MVE FIPS202 backend"
+    select FPU
+    select ARMV8_M_DSP
+    select ARMV8_1_M_MVEI
+    select ARMV8_1_M_MVEF
 
 source "Kconfig.zephyr"

test/zephyr/platform.mk

@@ -1,26 +1,34 @@
 # Copyright (c) The mlkem-native project authors
 # SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
 
+# Zephyr test platform for QEMU-emulated Arm MPS boards.
+#
+# Each test binary is built as a Zephyr application by CMake (which owns the arm
+# toolchain, per-board arch flags and libc via the .#zephyr dev shell). The
+# generic rules don't link these; CUSTOM_BUILD (below, see test/mk/rules.mk)
+# drives the CMake build from the binary's TEST_SRCS, set by components.mk --
+# adding a test binary there needs no change here.
+
 PLATFORM_PATH := test/zephyr
 
 # BUILD_DIR is set by the top-level Makefile after this file is included;
-# define it here too so the explicit bin rules below expand to the right path.
+# define it here too so CUSTOM_BUILD below expands to the right path.
 BUILD_DIR ?= test/build
 
 # ZEPHYR_TARGET=<key> selects a target. Each key maps to a Zephyr board and the
 # QEMU machine emulating it; add a board with a row below.
 ZEPHYR_TARGET ?= mps3-an547
 
 ZEPHYR_BOARD_mps2-an385 := mps2/an385
-ZEPHYR_QEMU_mps2-an385  := mps2-an385                                # Cortex-M3
+ZEPHYR_QEMU_mps2-an385  := mps2-an385                    # Cortex-M3
 ZEPHYR_BOARD_mps2-an386 := mps2/an386
-ZEPHYR_QEMU_mps2-an386  := mps2-an386                                # Cortex-M4
+ZEPHYR_QEMU_mps2-an386  := mps2-an386                    # Cortex-M4
 ZEPHYR_BOARD_mps2-an500 := mps2/an500
-ZEPHYR_QEMU_mps2-an500  := mps2-an500                                # Cortex-M7
+ZEPHYR_QEMU_mps2-an500  := mps2-an500                    # Cortex-M7
 ZEPHYR_BOARD_mps2-an521 := mps2/an521/cpu0
-ZEPHYR_QEMU_mps2-an521  := mps2-an521                                # Cortex-M33
+ZEPHYR_QEMU_mps2-an521  := mps2-an521                    # Cortex-M33
 ZEPHYR_BOARD_mps3-an547 := mps3/corstone300/an547
-ZEPHYR_QEMU_mps3-an547  := mps3-an547                                # Cortex-M55
+ZEPHYR_QEMU_mps3-an547  := mps3-an547                    # Cortex-M55
 
 ZEPHYR_FIPS202_BACKEND_mps3-an547 := fips202/native/armv81m/mve.h
 
@@ -33,11 +41,8 @@ ifeq ($(ZEPHYR_BOARD),)
 $(error Unknown ZEPHYR_TARGET '$(ZEPHYR_TARGET)'. Supported: $(ZEPHYR_TARGETS))
 endif
 
-# The test binaries are built by Zephyr's CMake (which uses its own arm
-# toolchain via the .#zephyr dev shell), not the generic Make rules. The
-# top-level targets still attach the usual object/library prerequisites to the
-# bin paths; with OPT=0 those are portable host objects that compile cleanly
-# and are simply discarded (the Zephyr ELF is copied over them).
+# CUSTOM_BUILD must be set before components.mk is included so it switches that
+# file to source prerequisites (it is: the top-level Makefile includes us first).
 OPT ?= 0
 
 # Native backends are an OPT=1 feature (an547 builds the Armv8.1-M MVE backend).
@@ -46,51 +51,41 @@ ZEPHYR_FIPS202_BACKEND := $(if $(filter 1,$(OPT)),$(strip $(ZEPHYR_FIPS202_BACKE
 ZEPHYR_APP := $(PLATFORM_PATH)/app
 ZEPHYR_BUILD_DIR := $(BUILD_DIR)/zephyr/$(ZEPHYR_TARGET)
 
-# Build a test as a Zephyr application and drop the resulting ELF at the path
-# the top-level Makefile expects. An explicit rule for the exact bin path wins
-# over the generic link pattern rule in test/mk/rules.mk.
-#   $(1) level  $(2) bin name  $(3) test source (repo-relative)  $(4) extra -D
-define ZEPHYR_BIN
-$(BUILD_DIR)/mlkem$(1)/bin/$(2):
-	$$(Q)echo "  ZEPHYR  $(ZEPHYR_TARGET) ML-KEM-$(1): $(3)"
-	$$(Q)cmake -GNinja -S $(ZEPHYR_APP) -B $(ZEPHYR_BUILD_DIR)/$(2) \
+# Per-binary CMake build dir, keyed on $(notdir $@) so binaries build in
+# parallel. Recipe-expanded, so $@ is the specific bin being built.
+ZEPHYR_OUT = $(ZEPHYR_BUILD_DIR)/$(notdir $@)
+
+# Shrink the test iteration counts (the sources default them higher, sized for
+# native hardware): QEMU is far slower. On CFLAGS so they forward below.
+CFLAGS += -DNTESTS_FUNC=3 -DNTESTS_KAT=100 \
+	-DMLK_BENCHMARK_NTESTS=10 -DMLK_BENCHMARK_NITERATIONS=10 -DMLK_BENCHMARK_NWARMUP=10 \
+	-DNUM_RANDOM_TESTS=100 -DNUM_RANDOM_TESTS_REJ_UNIFORM=100 -DMAX_INTT_CONSTANT_COEFF=512
+
+# The binary's CFLAGS, forwarded to the CMake build (which applies them to the
+# mlkem amalgamation and test sources alike). '=' not ':=', so the recipe-time
+# $(CFLAGS) includes the binary's target-specific additions (e.g.
+# -DMLK_STATIC_TESTABLE= for test_unit, -DMLK_CONFIG_FILE="..." for test_alloc).
+# Two rewrites:
+#   - -Imlkem -> absolute, as CMake builds from its own dir, not the repo root
+#     (and the alloc config path is relative to -Imlkem);
+#   - \" -> \\", so one level of quoting survives each of the recipe shell and
+#     CMake's separate_arguments and reaches the compiler intact.
+# Requires AUTO=0 (see .github/workflows/zephyr.yml): the host-arch flags AUTO=1
+# adds must not reach the Zephyr toolchain, which selects the target arch itself.
+ZEPHYR_TEST_CFLAGS = $(subst \",\\\",$(patsubst -Imlkem,-I$(abspath mlkem),$(CFLAGS)))
+
+CUSTOM_BUILD = \
+	echo "  ZEPHYR  $(ZEPHYR_TARGET): $(notdir $@)" && \
+	cmake -GNinja -S $(ZEPHYR_APP) -B $(ZEPHYR_OUT) \
 		-DBOARD=$(ZEPHYR_BOARD) \
 		-DZEPHYR_NATIVE_ROOT=$(CURDIR) \
-		-DZEPHYR_LEVEL=$(1) \
-		-DZEPHYR_TEST_SRC=$(3) \
-		-DZEPHYR_TEST_DEFS="NTESTS_FUNC=3 NTESTS_KAT=100 MLK_BENCHMARK_NTESTS=10 MLK_BENCHMARK_NITERATIONS=10 MLK_BENCHMARK_NWARMUP=10" \
+		-DZEPHYR_TEST_SRCS="$(strip $(TEST_SRCS))" \
+		-DZEPHYR_TEST_CFLAGS="$(ZEPHYR_TEST_CFLAGS)" \
 		-DZEPHYR_FIPS202_BACKEND=$(ZEPHYR_FIPS202_BACKEND) \
 		$(if $(ZEPHYR_FIPS202_BACKEND),-DCONFIG_FIPS202_MVE_BACKEND=y) \
-		$(4) \
-		-DUSER_CACHE_DIR=$(abspath $(ZEPHYR_BUILD_DIR)/$(2)/.cache) \
-		>/dev/null
-	$$(Q)cmake --build $(ZEPHYR_BUILD_DIR)/$(2) >/dev/null
-	$$(Q)[ -d $$(@D) ] || mkdir -p $$(@D)
-	$$(Q)cp $(ZEPHYR_BUILD_DIR)/$(2)/zephyr/zephyr.elf $$@
-endef
-
-$(eval $(call ZEPHYR_BIN,512,test_mlkem512,test/src/test_mlkem.c))
-$(eval $(call ZEPHYR_BIN,768,test_mlkem768,test/src/test_mlkem.c))
-$(eval $(call ZEPHYR_BIN,1024,test_mlkem1024,test/src/test_mlkem.c))
-
-$(eval $(call ZEPHYR_BIN,512,gen_KAT512,test/src/gen_KAT.c))
-$(eval $(call ZEPHYR_BIN,768,gen_KAT768,test/src/gen_KAT.c))
-$(eval $(call ZEPHYR_BIN,1024,gen_KAT1024,test/src/gen_KAT.c))
-
-$(eval $(call ZEPHYR_BIN,512,acvp_mlkem512,test/acvp/acvp_mlkem.c))
-$(eval $(call ZEPHYR_BIN,768,acvp_mlkem768,test/acvp/acvp_mlkem.c))
-$(eval $(call ZEPHYR_BIN,1024,acvp_mlkem1024,test/acvp/acvp_mlkem.c))
-
-$(eval $(call ZEPHYR_BIN,512,wycheproof_mlkem512,test/wycheproof/wycheproof_mlkem.c))
-$(eval $(call ZEPHYR_BIN,768,wycheproof_mlkem768,test/wycheproof/wycheproof_mlkem.c))
-$(eval $(call ZEPHYR_BIN,1024,wycheproof_mlkem1024,test/wycheproof/wycheproof_mlkem.c))
-
-$(eval $(call ZEPHYR_BIN,512,bench_mlkem512,test/bench/bench_mlkem.c,-DZEPHYR_TEST_HAL=ON))
-$(eval $(call ZEPHYR_BIN,768,bench_mlkem768,test/bench/bench_mlkem.c,-DZEPHYR_TEST_HAL=ON))
-$(eval $(call ZEPHYR_BIN,1024,bench_mlkem1024,test/bench/bench_mlkem.c,-DZEPHYR_TEST_HAL=ON))
-
-$(eval $(call ZEPHYR_BIN,512,bench_components_mlkem512,test/bench/bench_components_mlkem.c,-DZEPHYR_TEST_HAL=ON))
-$(eval $(call ZEPHYR_BIN,768,bench_components_mlkem768,test/bench/bench_components_mlkem.c,-DZEPHYR_TEST_HAL=ON))
-$(eval $(call ZEPHYR_BIN,1024,bench_components_mlkem1024,test/bench/bench_components_mlkem.c,-DZEPHYR_TEST_HAL=ON))
+		-DUSER_CACHE_DIR=$(abspath $(ZEPHYR_OUT)/.cache) \
+		>/dev/null && \
+	cmake --build $(ZEPHYR_OUT) >/dev/null && \
+	cp $(ZEPHYR_OUT)/zephyr/zephyr.elf $@
 
 EXEC_WRAPPER := $(abspath $(PLATFORM_PATH)/exec_wrapper.py)