ota_commit.h File Reference

Secure-side OTA bank commit + flash-bank-config write. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ota_commit.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	ra8_ota_bank_t : uint8_t {   k_ra8_ota_bank_a = 0U ,   k_ra8_ota_bank_b = 1U }
	Bank selector used by ra8_ota_commit_swap_bank. More...
enum	ra8_ota_bank_config_mask_t : uint32_t { k_ra8_ota_bank_config_allowed = 0x00000003U }
	Allowed-bit masks for the bank-config register. More...

Functions
ra8_err_t	ra8_ota_commit_reset (void)
	Reset the secure OTA shadow (drops any pending commit).
ra8_err_t	ra8_ota_commit_swap_bank (ra8_ota_bank_t target)
	Arm the boot ROM to start from target on next reset.
ra8_err_t	ra8_ota_commit_pending (ra8_ota_bank_t *out_target)
	Read back the pending swap target (for tests + diagnostics).
ra8_err_t	ra8_ota_commit_set_bank_config (uint32_t raw_value)
	Write the bank-config register, masked to the allowed bits.
ra8_err_t	ra8_ota_commit_get_bank_config (uint32_t *out_value)
	Read back the bank-config shadow (for tests).

Detailed Description

Secure-side OTA bank commit + flash-bank-config write.

Tag

[Ring 5 / SECAPP] {World: S}

The RA8D2 supports a swappable A/B bank layout in MRAM where the boot ROM picks the active bank from a flash-config option byte. The two operations exposed here are privileged:

• ra8_ota_commit_swap_bank(slot) arms the boot ROM to start from the other bank on next reset. NS code can request this via the NSC veneer ra8_nsc_ota_commit; the secure side is the only world allowed to touch the option byte.
• ra8_ota_commit_set_bank_config(value) programs the raw OFS3-style configuration register that selects the active bank, debug ports, and integrity check mode. The veneer ra8_nsc_flash_bank_config lets NS supply just the bank-select bits; everything else is masked off in this module.

Both writes touch the option region (an OFS3 / BTFLG option-byte program behind the PRCR unlock), which is brick-risky and not yet wired – it is bench-gated. On silicon both functions are therefore FAIL-CLOSED: they validate their arguments and then return k_ra8_err_not_supported instead of a fake k_ra8_ok (T5-10). Under RA8_OFF_TARGET they run against an in-memory shadow so the unit tests can verify the masking and re-entry guards without touching real flash. The real ra8_flash_* call sites are marked TODO at each fail-closed branch in the implementation.

Copyright

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

Definition in file ota_commit.h.

Enumeration Type Documentation

ra8_ota_bank_config_mask_t

enum ra8_ota_bank_config_mask_t : uint32_t

Allowed-bit masks for the bank-config register.

The bank-config register has a handful of fields the secure side exposes to NS callers; everything else (debug-disable, integrity check mode, lifetime fuses) is filtered out before the write lands.

Enumerator
k_ra8_ota_bank_config_allowed	Only the 2-bit BANK_SEL field.

Definition at line 66 of file ota_commit.h.

ra8_ota_bank_t

enum ra8_ota_bank_t : uint8_t

Bank selector used by ra8_ota_commit_swap_bank.

Enumerator
k_ra8_ota_bank_a	Bank A is the next-boot target.
k_ra8_ota_bank_b	Bank B is the next-boot target.

Definition at line 51 of file ota_commit.h.

Function Documentation

ra8_ota_commit_get_bank_config()

ra8_err_t ra8_ota_commit_get_bank_config ( uint32_t * out_value )

nodiscard

Read back the bank-config shadow (for tests).

Parameters

[out]

out_value

Filtered value.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Value written.
k_ra8_err_null_ptr	out_value was NULL.

Precondition

out_value non-NULL.

Since

0.1.0

Definition at line 151 of file ota_commit.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, s_bank_config, and s_tag.

ra8_ota_commit_pending()

ra8_err_t ra8_ota_commit_pending ( ra8_ota_bank_t * out_target )

nodiscard

Read back the pending swap target (for tests + diagnostics).

Parameters

[out]

out_target

Pending bank, valid only when the function returns k_ra8_ok.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	A swap is pending; target written.
k_ra8_err_no_data	No swap pending.
k_ra8_err_null_ptr	out_target was NULL.

Precondition

out_target non-NULL.

Postcondition

On success, *out_target is one of k_ra8_ota_bank_*.

Since

0.1.0

Definition at line 119 of file ota_commit.c.

References k_ra8_err_no_data, k_ra8_ok, RA8_CHECK_NULL_PTR, s_pending, s_pending_target, and s_tag.

ra8_ota_commit_reset()

ra8_err_t ra8_ota_commit_reset ( void )

nodiscard

Reset the secure OTA shadow (drops any pending commit).

Returns

ra8_err_t error code (currently always k_ra8_ok).

Precondition

Called from the secure boot path before any veneer can fire.

Postcondition

No swap is pending.

Bank-config shadow reads zero.

Note

Thread safety: secure-world only, single-threaded init.

Since

0.1.0

Reset the secure OTA shadow (drops any pending commit).

Clears the pending swap-bank request, returns the pending target to bank A, and zeroes the bank-config shadow. Used by the unit tests between scenarios and during secure-side bring-up.

Returns

ra8_err_t error code.

Return values

k_ra8_ok

Always; the operation cannot fail.

Precondition

Caller is in the secure-side init/test path.

No NS-side OTA orchestration is in flight.

Postcondition

s_pending == false.

s_bank_config == 0.

Note

Not thread-safe.

Since

0.1.0

Definition at line 79 of file ota_commit.c.

References k_ra8_ok, k_ra8_ota_bank_a, s_bank_config, s_pending, and s_pending_target.

ra8_ota_commit_set_bank_config()

ra8_err_t ra8_ota_commit_set_bank_config ( uint32_t raw_value )

nodiscard

Write the bank-config register, masked to the allowed bits.

Any bit outside k_ra8_ota_bank_config_allowed is masked off first so an NS caller can only touch the bank-select field. Persisting that masked value is an option-region write (same PRCR-unlocked, brick-risky path as ra8_ota_commit_swap_bank); it is not yet wired, so on silicon this function is FAIL-CLOSED: it returns k_ra8_err_not_supported and writes nothing, rather than a fake k_ra8_ok (T5-10). Under RA8_OFF_TARGET it records the masked value in the host shadow so the masking policy stays unit-testable. This is the entry point behind the ra8_nsc_flash_bank_config veneer.

Parameters

[in]

raw_value

Raw register value supplied by NS code.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	(RA8_OFF_TARGET only) masked value recorded in the host shadow.
k_ra8_err_not_supported	(silicon build) the real option-region write is bench-gated – fail-closed, nothing written.

Precondition

IRQs masked (or single-threaded boot context).

raw_value may take any uint32_t value (reserved bits are masked off).

Postcondition

On k_ra8_ok (fake), the shadow holds raw_value masked to the allowed bits.

On any error, no shadow state changes and no option region is written.

Note

Thread safety: not thread-safe.

Warning

On silicon this is a fail-closed stub: it never persists a value.

Since

0.1.0

Write the bank-config register, masked to the allowed bits.

Definition at line 132 of file ota_commit.c.

References k_ra8_err_not_supported, k_ra8_ok, k_ra8_ota_bank_config_allowed, and s_bank_config.

Referenced by ra8_nsc_flash_bank_config().

ra8_ota_commit_swap_bank()

ra8_err_t ra8_ota_commit_swap_bank ( ra8_ota_bank_t target )

nodiscard

Arm the boot ROM to start from target on next reset.

Arming a boot-bank swap requires programming the boot option region (an OFS3 / BTFLG option-byte write behind the PRCR unlock). That write is brick-risky and is not yet wired – it is bench-gated – so on silicon this function is FAIL-CLOSED: after the argument + idempotency checks it returns k_ra8_err_not_supported and arms nothing, rather than reporting a fake k_ra8_ok for a commit that never touched flash (T5-10). Under RA8_OFF_TARGET it instead records the request in a host shadow so the unit tests can exercise the argument-validation + single-shot idempotency policy without real flash. A caller therefore never mistakes an unwritten option byte for an armed swap.

Parameters

[in]

target

Bank selector (k_ra8_ota_bank_a / k_ra8_ota_bank_b).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	(RA8_OFF_TARGET only) swap armed in the host shadow.
k_ra8_err_invalid_arg	target not in ra8_ota_bank_t.
k_ra8_err_invalid_state	Another commit is already pending.
k_ra8_err_not_supported	(silicon build) the real option-byte bank-swap write is bench-gated – fail-closed, nothing armed.

Precondition

Caller has already validated firmware integrity on target.

IRQs masked (or single-threaded boot context).

Postcondition

On k_ra8_ok (fake), the shadow records target as pending.

On any error, no shadow state changes and no option byte is written.

Note

Thread safety: not thread-safe; serialise via secure-side mutex.

Warning

On silicon this is a fail-closed stub: it never arms a swap. Do not treat a non-error return as a committed bank swap until the bench-gated option-byte write is wired.

Since

0.1.0

Arm the boot ROM to start from target on next reset.

Definition at line 90 of file ota_commit.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_not_supported, k_ra8_ok, k_ra8_ota_bank_a, k_ra8_ota_bank_b, s_pending, s_pending_target, and s_tag.

Referenced by ra8_nsc_ota_commit().