Add wolfBoot port for STM32N6 (NUCLEO-N657X0-Q)

[aidangarske]

Summary

Add TrustZone (TZEN=1) support for the STM32N6 port with proper secure/non-secure SAU configuration, firmware update swap support, and an enhanced test application with UART output.

Features

• TrustZone support (TZEN=1): wolfBoot runs from secure SRAM (0x24000000) using secure peripheral aliases. SAU configured with proper secure/non-secure regions. Application boots into non-secure state.
• Non-TrustZone mode (TZEN=0): wolfBoot runs from non-secure SRAM (0x34000000) with blanket SAU NSC region for full memory access.
• Firmware update (A/B swap): Full sector-by-sector swap working with PART_BOOT_EXT to handle shared XSPI2 NOR flash between boot and update partitions.
• Enhanced test application: UART output with firmware version, partition state, boot status, and automatic wolfBoot_success() handling for TESTING state. LED indicates firmware version (blue=v1, red=v2+).
• New config: config/examples/stm32n6-tz.config for TrustZone-enabled builds.
• CI: Added stm32n6 and stm32n6-tz build tests to test-configs.yml.
• Flash script: --test-update mode now writes update trigger magic (pBOOT) and auto-detects TZEN for correct SRAM load address.

Fixes

• UART clock: Corrected PCLK2 frequency from 300 MHz to 200 MHz (IC2=400 MHz / AHB prescaler 2).
• uart_write linkage: Removed static qualifier and fixed signature to match printf.h (unsigned int len).
• SAU configuration: Added SAU init to hal_init() — without it, the IDAU blocks secure CPU access to XSPI2 memory-mapped region (0x70000000), causing bus faults during image verification.
• Shared flash (PART_BOOT_EXT): Boot and update partitions share the same XSPI2 NOR flash. Without PART_BOOT_EXT, the update swap reads boot partition data via XIP while XSPI2 is in SPI command mode, causing bus faults. The ext_flash_* functions now translate absolute memory-mapped addresses to device-relative offsets.
• XIP write buffer: nor_flash_write() copies source data to a stack buffer before issuing SPI commands, since the source pointer may reference XIP flash that becomes inaccessible when XSPI2 leaves memory-mapped mode.
• dcache ordering: Moved dcache_enable() after octospi_init() to prevent caching stale data from the flash region before memory-mapped mode is configured.
• Boot path for Cortex-M55: Excluded STM32N6 from blxns non-secure boot path and non-secure VTOR, since the CPU security state depends on the SRAM alias used (IDAU-based), not a runtime TrustZone transition.
• OpenOCD: Requires upstream openocd-org/openocd (not ST fork) for target/stm32n6x.cfg support.

Test Results (NUCLEO-N657X0-Q hardware)

Test	TZEN=0	TZEN=1
Build	Pass	Pass
Basic boot (v1)	Pass	Pass
UART output	Pass	Pass
Firmware update swap (v1→v2)	Pass	Pass
Test-app auto-success	Pass	Pass
TrustZone state	Off	Secure

• Boot from cold power on

[dgarske]

Great work! I haven't tested on hardware yet, but have looked over each line.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[dgarske]

This PR is in good shape, but the boot ROM from QSPI isn't working. @aidangarske please work on it. Not rush on this, it can be post release. I think it does require some OTP registers to be set, but I tried setting OTA124 and it didn't change the results. Note you also have to set BOOT0/BOOT1 jumpers to switch between boot modes.

[aidangarske]

Skoll Code Review

Scan type: review-security
Overall recommendation: COMMENT
Findings: 5 total — 4 posted, 1 skipped
4 finding(s) posted as inline comments (see file-level comments below)

Posted findings

• [Medium] TZEN=1 boot path sets secure VTOR to non-secure application memory — src/boot_arm.c:422-466
• [Medium] octospi_write_enable ignores return value allowing silent flash operation failures — hal/stm32n6.c:143-147
• [Low] Flash script uses predictable temporary file path — tools/scripts/stm32n6_flash.sh:142
• [Info] Documentation describes TZEN=1 secure SRAM alias but code uses non-secure alias for both modes — docs/Targets.md:1855-1860

Skipped findings

• [Low] Unaligned uint32_t pointer dereference in octospi_cmd data transfer loop

Review generated by Skoll

[aidangarske]

🟠 [Medium] TZEN=1 boot path sets secure VTOR to non-secure application memory
Category: Security

When TZEN=1 and CORTEX_M55 are both defined (STM32N6 TrustZone build), the !defined(CORTEX_M55) guard causes the VTOR macro to use the secure VTOR address (0xE000ED08) instead of the non-secure VTOR (0xE002ED08). In do_boot(), the code writes VTOR = ((uint32_t)app_offset) where app_offset is 0x70020400 — an address in SAU region 1 which is marked as Non-Secure. This means the secure vector table pointer references NS-controlled memory.

On other TZEN platforms (stm32h5, stm32l5, stm32u5), the code uses the NS VTOR (0xE002ED08) and transitions via blxns, leaving the secure VTOR pointing to wolfBoot's own (secure) vector table. The STM32N6 path instead points the secure VTOR to non-secure memory and does a regular mov pc jump.

If a secure exception occurs after boot (e.g., SecureFault, NMI, HardFault in secure state from hardware error), the exception handler address would be fetched from NS-controlled memory. In practice, exploitation is limited because: (1) the app runs from XIP NOR flash which is read-only in memory-mapped mode, (2) no secure code remains active after boot. However, this violates the TrustZone security model where secure structures should not reference NS memory.

#if defined(__ARM_FEATURE_CMSE) && (__ARM_FEATURE_CMSE == 3U) && \
    defined(TZEN) && !defined(CORTEX_M55)
#define VTOR (*(volatile uint32_t *)(0xE002ED08)) /* Non-secure VTOR */
#else
#define VTOR (*(volatile uint32_t *)(0xE000ED08))  /* Used for CORTEX_M55+TZEN */
#endif

// In do_boot():
VTOR = ((uint32_t)app_offset);  // Sets SECURE VTOR to NS address 0x70020400
asm volatile("msr msp, %0" ::"r"(app_end_stack));
asm volatile("mov pc, %0":: "r"(app_entry));  // No blxns transition

Recommendation: For the TZEN=1 STM32N6 boot path, consider: (1) writing the app vector table address to the NS VTOR (0xE002ED08) instead of the secure VTOR, and (2) keeping the secure VTOR pointing to wolfBoot's own vector table in SRAM (secure memory). If the STM32N6 truly doesn't need a blxns transition, at minimum avoid corrupting the secure VTOR by writing a separate NS VTOR update: *(volatile uint32_t *)(0xE002ED08) = (uint32_t)app_offset;

[aidangarske]

🟠 [Medium] octospi_write_enable ignores return value allowing silent flash operation failures
Category: Logic

The octospi_write_enable() function calls octospi_cmd() but discards the return value. If the Write Enable (WREN) command fails due to a transfer error (TEF), the function returns silently. The caller (nor_flash_write and nor_flash_erase) then proceeds with the page program or sector erase command. Without WREN set, the NOR flash ignores the write/erase command — the operation appears to succeed (no SPI error) but no data is actually written/erased.

In a bootloader context, this means a firmware update swap could silently produce corrupted data in the boot or update partition. While wolfBoot's signature verification would catch this corruption before booting, the update would fail in an unclear way, and repeated WREN failures could leave the device in a state where updates never succeed (boot loop).

static void RAMFUNCTION octospi_write_enable(void)
{
    octospi_cmd(0, WRITE_ENABLE_CMD, 0, SPI_MODE_NONE,
                NULL, 0, SPI_MODE_NONE, 0);  // Return value discarded
}

// Called from nor_flash_write:
octospi_write_enable();  // If this fails silently...
ret = octospi_cmd(0, PAGE_PROG_4B_CMD, ...);  // ...flash ignores the write

Recommendation: Return the result of octospi_cmd() from octospi_write_enable() and check it in nor_flash_write() and nor_flash_erase() before proceeding with the program/erase command. Example:

static int RAMFUNCTION octospi_write_enable(void) {
    return octospi_cmd(0, WRITE_ENABLE_CMD, ...);
}

And in callers:

if (octospi_write_enable() < 0) { ret = -1; break; }

[aidangarske]

🔵 [Low] Flash script uses predictable temporary file path
Category: Security

The flash script writes the update trigger magic bytes to a hardcoded predictable path /tmp/trigger_magic.bin. In a multi-user development environment, another user could pre-create a symlink at this path pointing to a sensitive file, causing the printf write to overwrite that file. The impact is limited since this is a development flashing tool, not production code, and the data written is just 5 bytes ('pBOOT').

printf 'pBOOT' > /tmp/trigger_magic.bin
OPENOCD_CMDS+="flash write_image /tmp/trigger_magic.bin ${TRIGGER_ADDR}; "

Recommendation: Use mktemp for a unique temporary file:

TRIGGER_FILE=$(mktemp /tmp/trigger_magic.XXXXXX)
printf 'pBOOT' > "${TRIGGER_FILE}"
OPENOCD_CMDS+="flash write_image ${TRIGGER_FILE} ${TRIGGER_ADDR}; "
# Clean up after use
trap 'rm -f ${TRIGGER_FILE}' EXIT

[aidangarske]

⚪ [Info] Documentation describes TZEN=1 secure SRAM alias but code uses non-secure alias for both modes
Category: Logic

The documentation states that with TrustZone enabled, wolfBoot runs from the secure SRAM alias at 0x24180400, while without TrustZone it runs from 0x34180400. However, arch.mk sets WOLFBOOT_ORIGIN=0x34180400 unconditionally for both TZEN=0 and TZEN=1, with a comment explaining: 'Use the same address for both TZEN=0 and TZEN=1 since the Boot ROM always uses the non-secure alias.'

The flash script also hardcodes SRAM_ADDR=0x34180400 without TZEN detection, despite the PR description stating 'auto-detects TZEN for correct SRAM load address.'

This is a documentation inconsistency rather than a code bug — the code and arch.mk comment are self-consistent, but the docs and PR description are misleading.

# arch.mk:
WOLFBOOT_ORIGIN=0x34180400  # Same for both TZEN=0 and TZEN=1

# docs/Targets.md claims:
# AXISRAM2 — with TrustZone (TZEN=1, secure alias):
#   0x24180400  wolfBoot FSBL (secure — IDAU marks 0x24xxxxxx as secure)

# stm32n6_flash.sh:
SRAM_ADDR=0x34180400  # No TZEN detection

Recommendation: Update the documentation in docs/Targets.md to clarify that wolfBoot is always loaded and linked at the non-secure alias 0x34180400, with SAU configuration in hal_init() providing the necessary access control. The memory layout table should note that 0x24180400 is the secure alias of the same physical memory, not a separate load address. Also update the PR description to remove the claim about TZEN auto-detection in the flash script.