Phase 3: flash-backed NVM via whFlashCb adapter over hal_flash_*

  Replaces the Phase 1 ramsim NVM with a real flash-backed store living
  in the existing wolfBoot keyvault region (FLASH_KEYVAULT, 112 KiB at
  0x0C040000), so wolfHSM-cached keys persist across reset.

  - include/wolfboot/wolfhsm_flash_hal.h: whFlashH5Ctx (base / size /
    partition_size) and whFlashH5_Cb extern.
  - src/wolfhsm_flash_hal.c: 10-callback whFlashCb adapter wrapping
    hal_flash_unlock/lock/write/erase. PartitionSize is configurable via
    the context (default 32 KiB per partition; two partitions = 64 KiB
    used, 48 KiB headroom in the 112 KiB keyvault). Direct memory reads
    for Read/Verify/BlankCheck. WriteLock/Unlock are no-ops on H5 (lock
    is global).
  - src/wolfhsm_callable.c: drop ramsim ctx/cfg + wh_flash_ramsim
    include; wire wh_NvmFlashConfig to the new adapter; vault address /
    size sourced from the linker symbols _flash_keyvault /
    _flash_keyvault_size, matching the PSA / PKCS11 store pattern.
  - options.mk: drop wh_flash_ramsim.o, add src/wolfhsm_flash_hal.o.

  Verified on m33mu with --persist: CommInit handshake + RNG + SHA256 +
  AES cached-key round-trips all pass through wolfHSM's two-partition
  journaling layer talking to actual flash. Persistence-across-reset
  test (P3.3) follows in a separate commit. PKCS11 / PSA / fwTPM
  regression builds remain clean.

Author: aidangarske

include/wolfboot/wolfhsm_flash_hal.h

@@ -0,0 +1,37 @@
+/* wolfhsm_flash_hal.h
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfBoot.
+ */
+
+/*
+ * Adapter that exposes wolfBoot's hal_flash_*() API as a wolfHSM whFlashCb,
+ * letting the secure-side wolfHSM server persist its NVM in real flash
+ * instead of the ramsim used during bring-up.
+ */
+
+#ifndef WOLFBOOT_WOLFHSM_FLASH_HAL_H
+#define WOLFBOOT_WOLFHSM_FLASH_HAL_H
+
+#ifdef WOLFCRYPT_TZ_WOLFHSM
+
+#include <stdint.h>
+
+#include "wolfhsm/wh_flash.h"
+
+typedef struct {
+    uint32_t base;           /* Absolute flash address of the wolfHSM NVM
+                                region (must be 8 KiB-aligned) */
+    uint32_t size;           /* Size of the region in bytes (>= 2 *
+                                partition_size, multiple of 8 KiB) */
+    uint32_t partition_size; /* Per-partition size in bytes; wolfHSM uses
+                                two partitions (active + backup) for
+                                journaling. Must be a multiple of 8 KiB. */
+} whFlashH5Ctx;
+
+extern const whFlashCb whFlashH5_Cb;
+
+#endif /* WOLFCRYPT_TZ_WOLFHSM */
+
+#endif /* WOLFBOOT_WOLFHSM_FLASH_HAL_H */

options.mk

@@ -1147,6 +1147,7 @@ ifeq ($(WOLFCRYPT_TZ_WOLFHSM),1)
   endif
   WOLFCRYPT_OBJS+=src/store_sbrk.o
   WOLFCRYPT_OBJS+=src/wolfhsm_callable.o
+  WOLFCRYPT_OBJS+=src/wolfhsm_flash_hal.o
   WOLFCRYPT_OBJS+=$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/cryptocb.o
   WOLFCRYPT_OBJS+=$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/coding.o
   WOLFCRYPT_OBJS+=$(WOLFBOOT_LIB_WOLFSSL)/wolfcrypt/src/hmac.o
@@ -1165,7 +1166,6 @@ ifeq ($(WOLFCRYPT_TZ_WOLFHSM),1)
   endif
   endif
   WOLFHSM_OBJS+=$(WOLFHSM_SERVER_OBJS)
-  WOLFHSM_OBJS+=$(WOLFBOOT_LIB_WOLFHSM)/src/wh_flash_ramsim.o
   WOLFHSM_OBJS+=$(WOLFBOOT_LIB_WOLFHSM)/port/stmicro/stm32-tz/wh_transport_nsc.o
   STACK_USAGE=20000
 endif

src/wolfhsm_callable.c

@@ -12,14 +12,14 @@
 
 #include "store_sbrk.h"
 #include "wolfboot/wcs_wolfhsm.h"
+#include "wolfboot/wolfhsm_flash_hal.h"
 
 #include "wolfssl/wolfcrypt/settings.h"
 #include "wolfssl/wolfcrypt/random.h"
 
 #include "wolfhsm/wh_comm.h"
 #include "wolfhsm/wh_error.h"
 #include "wolfhsm/wh_flash.h"
-#include "wolfhsm/wh_flash_ramsim.h"
 #include "wolfhsm/wh_nvm.h"
 #include "wolfhsm/wh_nvm_flash.h"
 #include "wolfhsm/wh_server.h"
@@ -36,32 +36,30 @@ void *_sbrk(unsigned int incr)
         (uint32_t)(&_heap_size));
 }
 
-/* pageSize must match WHFU_BYTES_PER_UNIT (8) — wolfHSM programs the flash
- * one unit at a time, so a larger pageSize causes the modulo check in
- * whFlashRamsim_Program to fail. */
-#define WCS_WOLFHSM_RAMSIM_SIZE      (32U * 1024U)
-#define WCS_WOLFHSM_RAMSIM_SECTOR    (8U * 1024U)
-#define WCS_WOLFHSM_RAMSIM_PAGE      8U
-
-#define WCS_WOLFHSM_SERVER_ID        56U
-
-static uint8_t                   g_ramsim_buf[WCS_WOLFHSM_RAMSIM_SIZE];
-static whFlashRamsimCtx          g_ramsim_ctx;
-static whFlashRamsimCfg          g_ramsim_cfg = {
-    .memory     = g_ramsim_buf,
-    .size       = WCS_WOLFHSM_RAMSIM_SIZE,
-    .sectorSize = WCS_WOLFHSM_RAMSIM_SECTOR,
-    .pageSize   = WCS_WOLFHSM_RAMSIM_PAGE,
-    .erasedByte = 0xFFU,
-    .initData   = NULL,
+#define WCS_WOLFHSM_SERVER_ID            56U
+
+/* Two 32 KiB partitions in the wolfBoot keyvault region: 64 KiB used out of
+ * 112 KiB, leaving headroom. Per-partition layout = 24 B state header +
+ * 32 directory entries * 56 B (= ~1.8 KiB) + ~30 KiB usable payload. */
+#define WCS_WOLFHSM_PARTITION_SIZE       (32U * 1024U)
+
+/* Linker-provided symbols for the FLASH_KEYVAULT region defined in
+ * hal/stm32h5.ld; matches the PSA / PKCS11 stores' pattern. */
+extern uint32_t _flash_keyvault;
+extern uint32_t _flash_keyvault_size;
+
+static whFlashH5Ctx              g_flash_ctx;
+static const whFlashH5Ctx        g_flash_cfg = {
+    .base           = (uint32_t)&_flash_keyvault,
+    .size           = (uint32_t)&_flash_keyvault_size,
+    .partition_size = WCS_WOLFHSM_PARTITION_SIZE,
 };
-static whFlashCb                 g_flash_cb = WH_FLASH_RAMSIM_CB;
 
 static whNvmFlashContext         g_nvm_flash_ctx;
 static whNvmFlashConfig          g_nvm_flash_cfg = {
-    .cb      = &g_flash_cb,
-    .context = &g_ramsim_ctx,
-    .config  = &g_ramsim_cfg,
+    .cb      = &whFlashH5_Cb,
+    .context = &g_flash_ctx,
+    .config  = &g_flash_cfg,
 };
 static whNvmCb                   g_nvm_flash_cb = WH_NVM_FLASH_CB;
 static whNvmContext              g_nvm_ctx;

src/wolfhsm_flash_hal.c

@@ -0,0 +1,206 @@
+/* wolfhsm_flash_hal.c
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfBoot.
+ */
+
+#ifdef WOLFCRYPT_TZ_WOLFHSM
+
+#include <stdint.h>
+#include <string.h>
+
+#include "hal.h"
+#include "wolfboot/wolfhsm_flash_hal.h"
+
+#include "wolfhsm/wh_error.h"
+#include "wolfhsm/wh_flash.h"
+
+/*
+ * STM32H5 page (= erase) size and program-quad-word size. The dual-bank
+ * H5 erase granularity is 8 KiB; flash programming happens in 16-byte
+ * quad-word units.
+ */
+#define WHFH5_SECTOR_SIZE       (8U * 1024U)
+#define WHFH5_PROGRAM_UNIT      16U
+
+
+static int _Init(void *context, const void *config)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+
+    if (ctx == NULL || config == NULL) {
+        return WH_ERROR_BADARGS;
+    }
+    *ctx = *((const whFlashH5Ctx *)config);
+
+    if (ctx->base == 0U || ctx->size == 0U || ctx->partition_size == 0U ||
+        (ctx->base % WHFH5_SECTOR_SIZE) != 0U ||
+        (ctx->size % WHFH5_SECTOR_SIZE) != 0U ||
+        (ctx->partition_size % WHFH5_SECTOR_SIZE) != 0U ||
+        ctx->size < (uint32_t)2 * ctx->partition_size) {
+        return WH_ERROR_BADARGS;
+    }
+    return WH_ERROR_OK;
+}
+
+static int _Cleanup(void *context)
+{
+    if (context == NULL) {
+        return WH_ERROR_BADARGS;
+    }
+    return WH_ERROR_OK;
+}
+
+static uint32_t _PartitionSize(void *context)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+    if (ctx == NULL) {
+        return 0U;
+    }
+    return ctx->partition_size;
+}
+
+/*
+ * STM32H5 has a single global flash unlock; per-region lock/unlock isn't
+ * available. Program/Erase wrap the unlock+op+lock cycle themselves, so
+ * the wh_FlashUnit_Program helper's "WriteUnlock around batch of writes"
+ * pattern is satisfied without per-call hardware action here.
+ */
+static int _WriteLock(void *context, uint32_t offset, uint32_t size)
+{
+    (void)context;
+    (void)offset;
+    (void)size;
+    return WH_ERROR_OK;
+}
+
+static int _WriteUnlock(void *context, uint32_t offset, uint32_t size)
+{
+    (void)context;
+    (void)offset;
+    (void)size;
+    return WH_ERROR_OK;
+}
+
+static int _Read(void *context, uint32_t offset, uint32_t size, uint8_t *data)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+
+    if (ctx == NULL || (size != 0U && data == NULL)) {
+        return WH_ERROR_BADARGS;
+    }
+    if (offset > ctx->size || size > ctx->size - offset) {
+        return WH_ERROR_BADARGS;
+    }
+    if (size > 0U) {
+        memcpy(data, (const uint8_t *)(ctx->base + offset), size);
+    }
+    return WH_ERROR_OK;
+}
+
+static int _Program(void *context, uint32_t offset, uint32_t size,
+                    const uint8_t *data)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+    int rc;
+
+    if (ctx == NULL || (size != 0U && data == NULL)) {
+        return WH_ERROR_BADARGS;
+    }
+    if (offset > ctx->size || size > ctx->size - offset) {
+        return WH_ERROR_BADARGS;
+    }
+    if (size == 0U) {
+        return WH_ERROR_OK;
+    }
+    /* hal_flash_write programs in H5 quad-word (16 byte) chunks; partial
+     * quad-words at either end fold the existing flash content so any
+     * `size` is acceptable here. The H5 ECC rule ("each quad-word may be
+     * programmed at most once between erases") is satisfied as long as
+     * wolfHSM's unit writes don't share a quad-word, which holds for the
+     * 32 KiB-aligned partitions / 8-byte units we use. */
+    hal_flash_unlock();
+    rc = hal_flash_write(ctx->base + offset, data, (int)size);
+    hal_flash_lock();
+    return (rc == 0) ? WH_ERROR_OK : WH_ERROR_ABORTED;
+}
+
+static int _Erase(void *context, uint32_t offset, uint32_t size)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+    int rc;
+
+    if (ctx == NULL) {
+        return WH_ERROR_BADARGS;
+    }
+    if (offset > ctx->size || size > ctx->size - offset) {
+        return WH_ERROR_BADARGS;
+    }
+    if ((offset % WHFH5_SECTOR_SIZE) != 0U ||
+        (size % WHFH5_SECTOR_SIZE) != 0U) {
+        return WH_ERROR_BADARGS;
+    }
+    if (size == 0U) {
+        return WH_ERROR_OK;
+    }
+
+    hal_flash_unlock();
+    rc = hal_flash_erase(ctx->base + offset, (int)size);
+    hal_flash_lock();
+    return (rc == 0) ? WH_ERROR_OK : WH_ERROR_ABORTED;
+}
+
+static int _Verify(void *context, uint32_t offset, uint32_t size,
+                   const uint8_t *data)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+
+    if (ctx == NULL || (size != 0U && data == NULL)) {
+        return WH_ERROR_BADARGS;
+    }
+    if (offset > ctx->size || size > ctx->size - offset) {
+        return WH_ERROR_BADARGS;
+    }
+    if (size > 0U &&
+        memcmp((const uint8_t *)(ctx->base + offset), data, size) != 0) {
+        return WH_ERROR_NOTVERIFIED;
+    }
+    return WH_ERROR_OK;
+}
+
+static int _BlankCheck(void *context, uint32_t offset, uint32_t size)
+{
+    whFlashH5Ctx *ctx = (whFlashH5Ctx *)context;
+    const uint8_t *p;
+    uint32_t i;
+
+    if (ctx == NULL) {
+        return WH_ERROR_BADARGS;
+    }
+    if (offset > ctx->size || size > ctx->size - offset) {
+        return WH_ERROR_BADARGS;
+    }
+    p = (const uint8_t *)(ctx->base + offset);
+    for (i = 0U; i < size; i++) {
+        if (p[i] != 0xFFU) {
+            return WH_ERROR_NOTBLANK;
+        }
+    }
+    return WH_ERROR_OK;
+}
+
+const whFlashCb whFlashH5_Cb = {
+    .Init          = _Init,
+    .Cleanup       = _Cleanup,
+    .PartitionSize = _PartitionSize,
+    .WriteLock     = _WriteLock,
+    .WriteUnlock   = _WriteUnlock,
+    .Read          = _Read,
+    .Program       = _Program,
+    .Erase         = _Erase,
+    .Verify        = _Verify,
+    .BlankCheck    = _BlankCheck,
+};
+
+#endif /* WOLFCRYPT_TZ_WOLFHSM */