SRAM HAL: TrustZone security attribution + ECC error callbacks. More...

#include <stdint.h>
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_sram.h"
#include "ra8_sram_internal.h"
#include "ra8_sram_regs.h"

Include dependency graph for ra8_sram_security.c:

Functions
ra8_err_t	ra8_sram_set_security (uint32_t sa_mask)
	Write SRAMSAR (per-bank register security + WTSC security).
ra8_err_t	ra8_sram_set_ecc_security (bool non_secure)
	Write SRAMESAR (ECC region security).
ra8_err_t	ra8_sram_set_boundary (uint8_t bank, uint32_t offset)
	Write SRAMSABARn (per-bank Secure/Non-Secure boundary).
ra8_err_t	ra8_sram_attach_handler (ra8_sram_error_fn_t fn, void *ctx)
	Attach the global ECC error callback.
ra8_err_t	ra8_sram_attach_bank_handler (uint8_t bank, ra8_sram_error_fn_t fn, void *ctx)
	Attach a per-bank ECC error callback.
void	ra8_sram_dispatch (uint8_t bank, bool is_2bit, uintptr_t err_addr)
	Dispatch an ECC error event to the registered handler.
uint16_t	ra8_sram_dispatch_from_esr (ra8_sram_status_t *out_status)
	Read SRAMESR + EAR and dispatch every latched flag.

Variables
static const char *	s_tag = "SRAM"
	Module log tag.
ra8_sram_error_fn_t	g_sram_on_error = nullptr
	Registered global ECC error callback (NULL until attach).
void *	g_sram_on_error_ctx = nullptr
	Caller context forwarded to g_sram_on_error.
ra8_sram_error_fn_t	g_sram_on_error_bank [k_ra8_sram_bank_count]
	Per-bank ECC error callback (NULL until attach).
void *	g_sram_on_error_bank_ctx [k_ra8_sram_bank_count]
	Per-bank context forwarded to g_sram_on_error_bank.

Detailed Description

SRAM HAL: TrustZone security attribution + ECC error callbacks.

Tag: [Ring 3 / HAL] {World: S}

Split out of ra8_sram.c (file-size cap). Owns:

CPSCU SRAMSAR / SRAMESAR / SRAMSABARn security attribution setters (HUM Ch 58.2.1..58.2.3)
the registered global + per-bank ECC error callbacks and the ra8_sram_dispatch / ra8_sram_dispatch_from_esr fan-out that walks all eight SRAMESR flags (HUM Ch 58.2.12 p 3535)

The callback state defined here (g_sram_on_error*) is also referenced by ra8_sram_deinit in ra8_sram.c via the extern declarations in ra8_sram_internal.h so teardown can drop every registration.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_sram_security.c.

Function Documentation

◆ ra8_sram_attach_bank_handler()

ra8_err_t ra8_sram_attach_bank_handler	(	uint8_t	bank,
		ra8_sram_error_fn_t	fn,
		void *	ctx )

nodiscard

Attach a per-bank ECC error callback.

Parameters

[in]	bank	Bank index 0..3.
[in]	fn	Non-NULL handler.
[in]	ctx	Opaque context pointer.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler installed for this bank only.
k_ra8_err_null_ptr	fn was NULL.
k_ra8_err_invalid_arg	Bank out of range.

Precondition: ra8_sram_init has run.; Bank handlers are independent of the global handler – both fire if both are attached.

Postcondition: Subsequent ra8_sram_dispatch / ra8_sram_dispatch_from_esr call fn(ctx, bank, ...).

Note: Not thread-safe at install time.

Since: 0.1.0

Definition at line 128 of file ra8_sram_security.c.

References g_sram_on_error_bank, g_sram_on_error_bank_ctx, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sram_bank_count, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_sram_attach_handler()

ra8_err_t ra8_sram_attach_handler	(	ra8_sram_error_fn_t	fn,
		void *	ctx )

nodiscard

Attach the global ECC error callback.

Parameters

[in]	fn	Non-NULL handler invoked from the NMI ISR (or test code).
[in]	ctx	Opaque context pointer forwarded to the handler.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler installed.
k_ra8_err_null_ptr	fn was NULL.

Precondition: ra8_sram_init has run.; Caller writes shared data the handler reads under a memory barrier (the handler runs at NMI priority).

Postcondition: Subsequent calls to ra8_sram_dispatch will fire fn.

Note: Not thread-safe at install time.

Since: 0.1.0

Definition at line 119 of file ra8_sram_security.c.

References g_sram_on_error, g_sram_on_error_ctx, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_sram_dispatch()

void ra8_sram_dispatch	(	uint8_t	bank,
		bool	is_2bit,
		uintptr_t	err_addr )

Dispatch an ECC error event to the registered handler.

Parameters

[in]	bank	Bank index 0..3 (out-of-range silently ignored).
[in]	is_2bit	true for uncorrectable, false for 1-bit.
[in]	err_addr	Faulting offset (from SRAMEARnm).

Fires both the global handler (if attached) and the per-bank handler (if attached). Out-of-range bank is silently ignored so the caller can blindly walk SRAMESR bits.

Precondition: bank is a valid bank index OR the call is ignored.; Handler is called with the same ctx supplied to ra8_sram_attach_handler.

Postcondition: Both attached handlers run to completion before this function returns.

Note: Safe to call from NMI context (the underlying handler must itself be NMI-safe).

Since: 0.1.0

Postcondition: Caller-visible state matches the documented contract.

Definition at line 139 of file ra8_sram_security.c.

References g_sram_on_error, g_sram_on_error_bank, g_sram_on_error_bank_ctx, g_sram_on_error_ctx, and k_ra8_sram_bank_count.

Referenced by ra8_sram_dispatch_from_esr().

◆ ra8_sram_dispatch_from_esr()

uint16_t ra8_sram_dispatch_from_esr ( ra8_sram_status_t * out_status )

Read SRAMESR + EAR and dispatch every latched flag.

The intended NMI path: snapshots SRAMESR once, walks each of the 8 defined error bits, calls ra8_sram_dispatch for every set bit with the corresponding EAR address, and returns the OR of all dispatched flags so the caller can clear them in a single SRAMESCLR write.

Parameters

[out] out_status Optional snapshot of the SRAMESR / EAR state (may be NULL if the caller does not need it).

Returns: Bitmask of flags that were dispatched (in SRAMESR encoding).

Precondition: ra8_sram_init has run.; Caller is willing to clear the returned mask via ra8_sram_clear_status.

Postcondition: Every set bit in SRAMESR fires a callback exactly once.; No register state is mutated by this call – clearing is the caller's responsibility (so per-bank handlers can decide whether to consume the address before clearing).

Note: Safe to call from NMI context.

Since: 0.1.0

Return values

k_ra8_ok Operation succeeded.

Definition at line 156 of file ra8_sram_security.c.

References ra8_sram_status_t::addr_1bit, ra8_sram_status_t::addr_2bit, k_ra8_ok, k_ra8_sram_bank_count, ra8_sram_dispatch(), ra8_sram_get_status(), and ra8_sram_status_t::raw_esr.

◆ ra8_sram_set_boundary()

ra8_err_t ra8_sram_set_boundary	(	uint8_t	bank,
		uint32_t	offset )

nodiscard

Write SRAMSABARn (per-bank Secure/Non-Secure boundary).

Parameters

[in]	bank	Bank index 0..3.
[in]	offset	Boundary offset inside the bank's 0x80000-byte slot (must be 4 KB aligned per HUM 58.2.1 p 3527).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SABAR updated.
k_ra8_err_invalid_arg	Bank or offset rejected.

Precondition: Caller is in Secure World.; offset & k_ra8_sram_sabar_align_mask == 0.

Postcondition: SRAMSABARn reads back offset & ~k_ra8_sram_sabar_align_mask.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 99 of file ra8_sram_security.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sram_bank_count, k_ra8_sram_sabar_align_mask, ra8_sram_cpscu_regs(), and r_sram_cpscu_regs_t::SRAMSABAR.

◆ ra8_sram_set_ecc_security()

ra8_err_t ra8_sram_set_ecc_security ( bool non_secure )

nodiscard

Write SRAMESAR (ECC region security).

Parameters

[in] non_secure true -> SRAMESA=1 (NS); false -> Secure.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller is in Secure World (HUM 58.2.3 p 3529).; PRCR_S.PRC4 has been unlocked by upstream code.

Postcondition: SRAMESAR reads back the requested attribute.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 86 of file ra8_sram_security.c.

References k_ra8_ok, k_ra8_sram_esar_bit_esa, ra8_sram_cpscu_regs(), and r_sram_cpscu_regs_t::SRAMESAR.

◆ ra8_sram_set_security()

ra8_err_t ra8_sram_set_security ( uint32_t sa_mask )

nodiscard

Write SRAMSAR (per-bank register security + WTSC security).

Parameters

[in] sa_mask Bitmask of ra8_sram_sar_bit_t values.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SAR register updated.
k_ra8_err_invalid_arg	sa_mask includes undefined bits.

Precondition: Caller is in Secure World (HUM 58.2.2 p 3528 – "Only Secure access can write to this register").; PRCR_S.PRC4 has been unlocked by upstream code (SRAM CPSCU writes are gated on PRC4, not SRAMPRCR_S).

Postcondition: SRAMSAR reads back sa_mask.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 74 of file ra8_sram_security.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sram_sar_writable, ra8_sram_cpscu_regs(), and r_sram_cpscu_regs_t::SRAMSAR.

Variable Documentation

◆ g_sram_on_error

ra8_sram_error_fn_t g_sram_on_error = nullptr

Registered global ECC error callback (NULL until attach).

Defined in ra8_sram_security.c. Referenced by ra8_sram_deinit in ra8_sram.c to drop the registration on teardown.

Note: Not thread-safe; mutate under the same single-threaded context as the rest of the driver.

Warning: Do not assign directly outside the SRAM driver TUs.

Since: 0.1.0

Definition at line 48 of file ra8_sram_security.c.

Referenced by ra8_sram_attach_handler(), ra8_sram_deinit(), and ra8_sram_dispatch().

◆ g_sram_on_error_bank

ra8_sram_error_fn_t g_sram_on_error_bank[k_ra8_sram_bank_count]

Initial value:

                                         = {
  nullptr,
  nullptr,
  nullptr,
  nullptr,
}

Per-bank ECC error callback (NULL until attach).

Per-bank ECC error callback table (NULL until attach).

Definition at line 54 of file ra8_sram_security.c.

Referenced by ra8_sram_attach_bank_handler(), ra8_sram_deinit(), and ra8_sram_dispatch().

◆ g_sram_on_error_bank_ctx

void* g_sram_on_error_bank_ctx[k_ra8_sram_bank_count]

Initial value:

                              = {
  nullptr,
  nullptr,
  nullptr,
  nullptr,
}

Per-bank context forwarded to g_sram_on_error_bank.

Defined in ra8_sram_security.c.

Note: Not thread-safe.

Warning: Do not assign directly outside the SRAM driver TUs.

Since: 0.1.0

Definition at line 62 of file ra8_sram_security.c.

Referenced by ra8_sram_attach_bank_handler(), ra8_sram_deinit(), and ra8_sram_dispatch().

◆ g_sram_on_error_ctx

void* g_sram_on_error_ctx = nullptr

Caller context forwarded to g_sram_on_error.

Defined in ra8_sram_security.c.

Note: Not thread-safe.

Warning: Do not assign directly outside the SRAM driver TUs.

Since: 0.1.0

Definition at line 51 of file ra8_sram_security.c.

Referenced by ra8_sram_attach_handler(), ra8_sram_deinit(), and ra8_sram_dispatch().

◆ s_tag

const char* s_tag = "SRAM"

static

Module log tag.

Definition at line 40 of file ra8_sram_security.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ra8_sram_attach_bank_handler()

◆ ra8_sram_attach_handler()

◆ ra8_sram_dispatch()

◆ ra8_sram_dispatch_from_esr()

◆ ra8_sram_set_boundary()

◆ ra8_sram_set_ecc_security()

◆ ra8_sram_set_security()

Variable Documentation

◆ g_sram_on_error

◆ g_sram_on_error_bank

◆ g_sram_on_error_bank_ctx

◆ g_sram_on_error_ctx

◆ s_tag