ra8_tz_secure_boot.c

Go to the documentation of this file.

 
#include "ra8_tz_secure_boot.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#ifdef RA8_ENABLE_ROOT_OF_TRUST
#include "ra8_rot.h"
#endif

static const char* s_tag = "TZBOOT";

static volatile ra8_tz_secure_boot_step_t s_step = k_ra8_tz_secure_boot_step_idle;
 
/* =============================================================================
 * Address constants (verified against HUM Ch 13 + Ch 3)
 * =============================================================================
 */

typedef enum : uintptr_t {
  k_ra8_tz_sau_ctrl_addr    = 0xE000EDD0UL, 
  k_ra8_tz_sau_type_addr    = 0xE000EDD4UL, 
  k_ra8_tz_sau_rnr_addr     = 0xE000EDD8UL, 
  k_ra8_tz_sau_rbar_addr    = 0xE000EDDCUL, 
  k_ra8_tz_sau_rlar_addr    = 0xE000EDE0UL, 
  k_ra8_tz_scb_vtor_ns_addr = 0xE002ED08UL, 
  k_ra8_tz_ipcsar_addr      = 0x40008610UL, 
  k_ra8_tz_ipcpar_addr      = 0x40008614UL, 
  k_ra8_tz_prcr_s_addr      = 0x4001E3FAUL, 
} ra8_tz_secure_boot_addr_t;

typedef enum : uint32_t {
  k_ra8_tz_sau_ctrl_enable = 0x00000001U, 
  k_ra8_tz_sau_ctrl_allns  = 0x00000002U, 
  k_ra8_tz_sau_rlar_enable = 0x00000001U, 
  k_ra8_tz_sau_rlar_nsc    = 0x00000002U, 
  k_ra8_tz_sau_type_mask   = 0x000000FFU, 
} ra8_tz_secure_boot_sau_bit_t;

typedef enum : uint16_t {
  k_ra8_tz_prcr_s_key       = 0xA500U, 
  k_ra8_tz_prcr_s_prc4_open = 0x0010U, 
  k_ra8_tz_prcr_s_open      = 0xA510U, 
  k_ra8_tz_prcr_s_close     = 0xA500U, 
} ra8_tz_secure_boot_prcr_t;

typedef enum : uint32_t {
  k_ra8_tz_part_code_nsc_base  = 0x10000000U, 
  k_ra8_tz_part_code_nsc_limit = 0x100FFFE0U, 
  k_ra8_tz_part_ns_mram_base   = 0x02080000U, 
  k_ra8_tz_part_ns_mram_limit  = 0x020FFFE0U, 
  k_ra8_tz_part_sram_nsc_base  = 0x12000000U, 
  k_ra8_tz_part_sram_nsc_limit = 0x1200FFE0U, 
  k_ra8_tz_part_ns_sram_base   = 0x22100000U, 
  k_ra8_tz_part_ns_sram_limit  = 0x221FFFE0U, 
  /* NS peripheral region needs to cover BOTH the standard Cortex-M
   * peripheral window at 0x40000000 (where IPC lives at 0x40020000)
   * AND the alias window at 0x50000000. With the original 0x5xxxxxxx-
   * only region, CPU1 (NS-only per SECEXT-disabled silicon) cannot
   * reach any IPC channel even after IPCSAR=0x50000 makes channels
   * 0/2 NS-attributed at the peripheral level -- the SAU still has
   * to permit the underlying peripheral address as NS. Bench
   * evidence on 2026-05-27: with 0x5xxxxxxx-only the ping-pong
   * counters stay at zero (CPU0 sends, CPU1 SecureFaults on recv);
   * extending the region down to 0x40000000 unblocks the round-trip. */
  k_ra8_tz_part_ns_per_base  = 0x50000000U, 
  k_ra8_tz_part_ns_per_limit = 0x5FFFFFE0U, 
} ra8_tz_secure_boot_partition_t;
 
#ifdef RA8_OFF_TARGET
 
/* =============================================================================
 * Host-side captures
 * =============================================================================
 *
 * On the host build the SAU / CPSCU / VTOR writes go into the
 * captures below so unit tests can assert on the documented behaviour
 * without touching real memory.
 */

typedef struct {
  uint32_t sau_ctrl;                                    
  uint32_t sau_region_base[k_ra8_tz_sau_region_count];  
  uint32_t sau_region_limit[k_ra8_tz_sau_region_count]; 
  uint8_t  sau_region_nsc[k_ra8_tz_sau_region_count];   
  uint16_t prcr_s_last;                                 
  uint8_t  prcr_unlock_count;                           
  uint8_t  prcr_relock_count;                           
  uint32_t ipcsar_value;                                
  uint32_t ipcpar_value;                                
  uint32_t blxns_target;                                
  uint32_t blxns_msp_ns;                                
  uint32_t vtor_ns;                                     
} ra8_tz_secure_boot_host_state_t;

static ra8_tz_secure_boot_host_state_t s_host = {};
 
void ra8_tz_secure_boot_host_reset(void)
{
  /* Pre 1: the host state struct lives in BSS so its address is always
   *        non-NULL on any hosted environment we run on. */
  /* Pre 2: ``s_tag`` is a static const string used to silence the
   *        unused-symbol warning on the target build. */
  (void)s_tag;
  s_host = (ra8_tz_secure_boot_host_state_t){};
  s_step = k_ra8_tz_secure_boot_step_idle;
  /* Post 1: tests get a deterministic baseline. */
  /* Post 2: progress counter is back at idle. */
}
 
uint32_t ra8_tz_secure_boot_host_blxns_target(void)
{
  /* Pre + post: pure accessor; no state change. */
  return s_host.blxns_target;
}
 
#else /* !RA8_OFF_TARGET */
 
void ra8_tz_secure_boot_host_reset(void)
{
  /* Pre + post: target build exposes the symbol but the body is a
   * no-op so unit-test fixtures that link against the target stub do
   * not crash. */
  (void)s_tag;
}
 
uint32_t ra8_tz_secure_boot_host_blxns_target(void)
{
  /* Pre + post: target build returns 0 because BLXNS never returns. */
  return 0U;
}
 
#endif /* RA8_OFF_TARGET */
 
/* =============================================================================
 * Small register helpers (host-aware)
 * =============================================================================
 */

RA8_INTERNAL static void internal_write32(uintptr_t addr, uint32_t value)
{
#ifdef RA8_OFF_TARGET
  if (addr == (uintptr_t)k_ra8_tz_ipcsar_addr) {
    s_host.ipcsar_value = value;
  } else if (addr == (uintptr_t)k_ra8_tz_ipcpar_addr) {
    s_host.ipcpar_value = value;
  } else if (addr == (uintptr_t)k_ra8_tz_scb_vtor_ns_addr) {
    s_host.vtor_ns = value;
  } else if (addr == (uintptr_t)k_ra8_tz_sau_ctrl_addr) {
    s_host.sau_ctrl = value;
  }
  /* SAU RBAR / RLAR writes are routed through internal_sau_set_region. */
#else
  /* HUM Ch 3.2.1 "IPCSAR" p 205 and HUM Ch 13.2.1 "PRCR_S" p 521 for
   * the secure-only writes routed through this helper. Generic 32-bit
   * MMIO store; the called sites cite their own register page. */
  *(volatile uint32_t*)addr = value;
#endif
}

RA8_INTERNAL static uint32_t internal_read32(uintptr_t addr)
{
#ifdef RA8_OFF_TARGET
  if (addr == (uintptr_t)k_ra8_tz_sau_type_addr) {
    /* Cortex-M85 implements 8 SAU regions; tests rely on that. */
    return 8U;
  }
  if (addr == (uintptr_t)k_ra8_tz_ipcsar_addr) {
    return s_host.ipcsar_value;
  }
  return 0U;
#else
  /* HUM Ch 3.2.1 "IPCSAR" p 205 -- only IPCSAR is ever read back here
   * after the write; everything else (SAU_TYPE) is architectural. */
  return *(volatile uint32_t*)addr;
#endif
}

RA8_INTERNAL static void internal_write16(uintptr_t addr, uint16_t value)
{
#ifdef RA8_OFF_TARGET
  s_host.prcr_s_last = value;
  if ((value & (uint16_t)k_ra8_tz_prcr_s_prc4_open) != 0U) {
    s_host.prcr_unlock_count = (uint8_t)(s_host.prcr_unlock_count + 1U);
  } else {
    s_host.prcr_relock_count = (uint8_t)(s_host.prcr_relock_count + 1U);
  }
  (void)addr;
#else
  /* HUM Ch 13.2.1 "PRCR_S" p 521 */
  *(volatile uint16_t*)addr = value;
#endif
}

RA8_INTERNAL static inline void internal_dsb(void)
{
#ifndef RA8_OFF_TARGET
  __asm__ volatile("dsb 0xF" ::: "memory");
#endif
}

RA8_INTERNAL static inline void internal_isb(void)
{
#ifndef RA8_OFF_TARGET
  __asm__ volatile("isb 0xF" ::: "memory");
#endif
}
 
/* =============================================================================
 * SAU region programming
 * =============================================================================
 */

RA8_INTERNAL static void
internal_sau_set_region(uint8_t region, uint32_t base, uint32_t limit, bool is_nsc)
{
  internal_write32(k_ra8_tz_sau_rnr_addr, (uint32_t)region);
  internal_write32(k_ra8_tz_sau_rbar_addr, base);
  uint32_t rlar = limit | (uint32_t)k_ra8_tz_sau_rlar_enable;
  if (is_nsc) {
    rlar |= (uint32_t)k_ra8_tz_sau_rlar_nsc;
  }
  internal_write32(k_ra8_tz_sau_rlar_addr, rlar);
 
#ifdef RA8_OFF_TARGET
  if ((uint32_t)region < (uint32_t)k_ra8_tz_sau_region_count) {
    s_host.sau_region_base[region]  = base;
    s_host.sau_region_limit[region] = limit;
    s_host.sau_region_nsc[region]   = (uint8_t)(is_nsc ? 1U : 0U);
  }
#endif
}
 
ra8_err_t ra8_tz_secure_boot_sau_init(void)
{
  /* Pre: SAU_TYPE.SREGION must report >= 5 implemented regions. */
  const uint32_t sau_type = internal_read32(k_ra8_tz_sau_type_addr);
  if ((sau_type & (uint32_t)k_ra8_tz_sau_type_mask) < (uint32_t)k_ra8_tz_sau_region_count) {
    ra8_log_error(s_tag, "SAU_TYPE.SREGION below required count");
    return k_ra8_err_not_supported;
  }
 
  internal_sau_set_region((uint8_t)k_ra8_tz_sau_region_code_nsc,
                          (uint32_t)k_ra8_tz_part_code_nsc_base,
                          (uint32_t)k_ra8_tz_part_code_nsc_limit,
                          /*is_nsc=*/true);
  internal_sau_set_region((uint8_t)k_ra8_tz_sau_region_ns_mram,
                          (uint32_t)k_ra8_tz_part_ns_mram_base,
                          (uint32_t)k_ra8_tz_part_ns_mram_limit,
                          /*is_nsc=*/false);
  internal_sau_set_region((uint8_t)k_ra8_tz_sau_region_sram_nsc,
                          (uint32_t)k_ra8_tz_part_sram_nsc_base,
                          (uint32_t)k_ra8_tz_part_sram_nsc_limit,
                          /*is_nsc=*/true);
  internal_sau_set_region((uint8_t)k_ra8_tz_sau_region_ns_sram,
                          (uint32_t)k_ra8_tz_part_ns_sram_base,
                          (uint32_t)k_ra8_tz_part_ns_sram_limit,
                          /*is_nsc=*/false);
  internal_sau_set_region((uint8_t)k_ra8_tz_sau_region_ns_periph,
                          (uint32_t)k_ra8_tz_part_ns_per_base,
                          (uint32_t)k_ra8_tz_part_ns_per_limit,
                          /*is_nsc=*/false);
 
  internal_dsb();
  internal_write32(k_ra8_tz_sau_ctrl_addr, (uint32_t)k_ra8_tz_sau_ctrl_enable);
  internal_dsb();
  internal_isb();
 
  /* Post: SAU enabled with the canonical layout, default-deny. */
  s_step = k_ra8_tz_secure_boot_step_sau_done;
  return k_ra8_ok;
}
 
ra8_err_t ra8_tz_secure_boot_security_init(uint32_t ipcsar_value, uint32_t ipcpar_value)
{
  /* Pre 1: caller must be in Secure state (architectural; cannot be
   * checked from C, documented in the header). */
  /* Pre 2: PRCR_S unlock must observe the documented key + bit
   * pattern, otherwise the chip silently drops the write. */
 
  /* Open the PRC4 gate so the next IPCSAR / IPCPAR writes land. */
  /* HUM Ch 13.2.1 "PRCR_S" p 521 */
  internal_write16(k_ra8_tz_prcr_s_addr, (uint16_t)k_ra8_tz_prcr_s_open);
  s_step = k_ra8_tz_secure_boot_step_prcr_unlocked;
 
  /* HUM Ch 3.2.1 "IPCSAR" p 205-207 */
  internal_write32(k_ra8_tz_ipcsar_addr, ipcsar_value);
  /* HUM Ch 3.2.2 "IPCPAR" p 208-209 */
  internal_write32(k_ra8_tz_ipcpar_addr, ipcpar_value);
  s_step = k_ra8_tz_secure_boot_step_ipcsar_written;
 
  /* Close the PRC4 gate to restore write-protect on CPSCU. */
  /* HUM Ch 13.2.1 "PRCR_S" p 521 */
  internal_write16(k_ra8_tz_prcr_s_addr, (uint16_t)k_ra8_tz_prcr_s_close);
  s_step = k_ra8_tz_secure_boot_step_prcr_relocked;
 
  internal_dsb();
  /* Post 1: IPCSAR landed (verifiable via JTAG read-back). */
  /* Post 2: PRCR_S.PRC4 clear (write-protect restored). */
  return k_ra8_ok;
}
 
uint32_t ra8_tz_ns_signed_body_len(const uint32_t* ns_vector_table)
{
  /* Validation 1: reject a NULL image base (returns the deny sentinel 0). */
  if (ns_vector_table == nullptr) {
    ra8_log_error(s_tag, "ns_vector_table is NULL");
    return 0U;
  }
  /* The NS linker emits an ::ra8_ns_rot_header_t at a fixed small offset from the
   * NS base (just past the 16-slot ARMv8-M vector table -- see
   * ::k_ra8_tz_ns_rot_header_offset), self-describing the signed body length.
   * This is a plain memory read of the (already-flashed/copied) NS image; there
   * is no MMIO register access here, so no HUM citation applies. The reinterpret
   * casts route through a named `const void*` seam (as `ra8_epub` does): a direct
   * `const uint8_t* -> ra8_ns_rot_header_t*` cast trips -Wcast-align, and a
   * one-expression `(T*)(const void*)p` cast trips bugprone-casting-through-void. */
  const void* const          ns_image  = ns_vector_table;
  const uint8_t*             base      = (const uint8_t*)ns_image;
  const void* const          header_at = base + (uintptr_t)k_ra8_tz_ns_rot_header_offset;
  const ra8_ns_rot_header_t* header    = (const ra8_ns_rot_header_t*)header_at;
  /* Validation 2: reject a missing / wrong-magic header (returns 0 -> deny). */
  if (header->magic != (uint32_t)k_ra8_tz_ns_rot_header_magic) {
    ra8_log_error(s_tag, "NS RoT header magic mismatch");
    return 0U;
  }
  return header->body_len;
}

RA8_INTERNAL static ra8_err_t internal_ns_verify_or_deny(const uint32_t* ns_vector_table)
{
  RA8_CHECK_NULL_PTR(ns_vector_table, s_tag, "ns_vector_table");
#if !defined(RA8_OFF_TARGET) && defined(RA8_ENABLE_ROOT_OF_TRUST)
  const uint32_t ns_body_len = ra8_tz_ns_signed_body_len(ns_vector_table);
  if (ns_body_len == 0U) {
    ra8_log_error(s_tag, "NS RoT header missing/invalid -- denying BLXNS");
    return k_ra8_err_validation_failed;
  }
  const ra8_rot_trailer_t* ns_trailer = ra8_rot_trailer_after(ns_vector_table, ns_body_len);
  if (ns_trailer == nullptr) {
    ra8_log_error(s_tag, "NS RoT body_len out of range -- denying BLXNS");
    return k_ra8_err_invalid_size;
  }
  return ra8_rot_verify_image((const uint8_t*)(const void*)ns_vector_table,
                              ns_body_len,
                              ns_trailer);
#else
  (void)ns_vector_table;
  return k_ra8_ok; /* root of trust disabled (or host build): no verification */
#endif /* !RA8_OFF_TARGET && RA8_ENABLE_ROOT_OF_TRUST */
}
 
ra8_err_t ra8_tz_secure_boot_jump_ns(const uint32_t* ns_vector_table)
{
  RA8_CHECK_NULL_PTR(ns_vector_table, s_tag, "ns_vector_table");
  /* Pre 2: 4-byte alignment. */
  if (((uintptr_t)ns_vector_table & 0x3U) != 0U) {
    ra8_log_error(s_tag, "ns_vector_table misaligned");
    return k_ra8_err_invalid_arg;
  }
 
  const uint32_t initial_sp  = ns_vector_table[0];
  const uint32_t reset_entry = ns_vector_table[1];
 
  /* Reject obviously bogus reset vectors -- 0 (all zeros) or
   * 0xFFFFFFFF (erased MRAM). FSP guards the same way. */
  if (reset_entry == 0U || reset_entry == UINT32_MAX) {
    ra8_log_error_val(s_tag, "NS reset vector invalid", reset_entry);
    return k_ra8_err_invalid_arg;
  }
 
  /* Root-of-trust gate before BLXNS: deny the jump on a failed authentication
   * (no-op when RA8_ENABLE_ROOT_OF_TRUST is off -- see internal_ns_verify_or_deny). */
  const ra8_err_t auth_err = internal_ns_verify_or_deny(ns_vector_table);
  if (auth_err != k_ra8_ok) {
    ra8_log_error(s_tag, "NS image authentication failed -- denying BLXNS");
    return auth_err;
  }
 
  /* HUM Ch 4 "Option Setting Memory" + ARMv8-M ARM B3.2.4: VTOR_NS
   * accessed via the 0xE002... NS alias of SCB.VTOR (=0xE002ED08). */
  internal_write32(k_ra8_tz_scb_vtor_ns_addr, (uint32_t)(uintptr_t)ns_vector_table);
  s_step = k_ra8_tz_secure_boot_step_blxns_armed;
 
#ifdef RA8_OFF_TARGET
  s_host.blxns_target = reset_entry;
  s_host.blxns_msp_ns = initial_sp;
  s_step              = k_ra8_tz_secure_boot_step_branched;
  return k_ra8_ok;
#else
  /* ARMv8-M MSR_NS / BLXNS sequence -- set MSP_NS, then branch into
   * the NS world via BLXNS. The compiler does NOT emit BLXNS through
   * a regular function-pointer call; we need inline asm.
   *
   * BLXNS switches to Non-Secure state only when bit[0] of the target
   * register is 0; bit[0] == 1 keeps the call Secure (it is the
   * function-descriptor "Secure" marker, not the Thumb bit). The NS reset
   * vector carries the Thumb bit set, so it MUST be cleared here -- otherwise
   * the "NS" image executes in Secure state on the Secure stack and every
   * NS-pointer cmse check in the NSC veneers misfires. */
  const uint32_t ns_entry = reset_entry & ~(uint32_t)1U;
  __asm__ volatile("msr msp_ns, %0\n"
                   "blxns %1\n"
                   :
                   : "r"(initial_sp), "r"(ns_entry)
                   : "memory");
  /* Unreachable on target. */
  return k_ra8_ok;
#endif
}
 
ra8_err_t ra8_tz_secure_boot_run(uint32_t        ipcsar_value,
                                 uint32_t        ipcpar_value,
                                 const uint32_t* ns_vector_table)
{
  RA8_CHECK_NULL_PTR(ns_vector_table, s_tag, "ns_vector_table");
 
  ra8_err_t err = ra8_tz_secure_boot_sau_init();
  if (err != k_ra8_ok) {
    return err;
  }
 
  err = ra8_tz_secure_boot_security_init(ipcsar_value, ipcpar_value);
  if (err != k_ra8_ok) {
    return err;
  }
 
  /* Post: the next call BLXNS-es out and never returns on target. */
  return ra8_tz_secure_boot_jump_ns(ns_vector_table);
}
 
ra8_tz_secure_boot_step_t ra8_tz_secure_boot_get_step(void)
{
  /* Pre: progress counter lives in BSS so it is always readable. */
  /* Pre: single 32-bit volatile load -- atomic on all targets. */
  /* Post: returned value matches the most recent step write. */
  /* Post: no state change. */
  return s_step;
}