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

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

Include dependency graph for ota_commit.c:

Functions
ra8_err_t	ra8_ota_commit_reset (void)
	Reset the OTA commit shadow registers to power-on defaults.
ra8_err_t	ra8_ota_commit_swap_bank (ra8_ota_bank_t target)
	Implementation of ra8_ota_commit_swap_bank() – host shadow under RA8_OFF_TARGET; fail-closed on silicon (the real option-byte write is bench-gated and brick-risky, so it must not fake success – T5-10).
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)
	Implementation of ra8_ota_commit_set_bank_config() – masks reserved bits, then host shadow under RA8_OFF_TARGET / fail-closed on silicon (the real option-region write is bench-gated and brick-risky – T5-10).
ra8_err_t	ra8_ota_commit_get_bank_config (uint32_t *out_value)
	Read back the bank-config shadow (for tests).

Variables
static const char *	s_tag = "OTACMT"
static bool	s_pending = false
	Whether a swap-bank request is currently armed.
static ra8_ota_bank_t	s_pending_target = k_ra8_ota_bank_a
	Bank that will be active after the next reset, when s_pending.
static uint32_t	s_bank_config = 0U
	Shadow of the masked bank-config register.

Detailed Description

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

Tag: [Ring 5 / SECAPP] {World: S}

The commit + bank-config writes are option-region (OFS3 / BTFLG) programs behind the PRCR unlock – brick-risky and not yet wired, so they are bench-gated. On silicon both are FAIL-CLOSED: they run their argument / idempotency checks and then return k_ra8_err_not_supported rather than a fake k_ra8_ok for a commit that never touched flash (T5-10). Under RA8_OFF_TARGET they instead maintain an in-memory shadow of the boot-bank option byte and the bank-config register so the unit tests can drive the masking + single-shot state-machine logic host-safely. The real ra8_flash_* + PRCR-unlock call sites are marked TODO at each fail-closed branch.

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

Definition in file ota_commit.c.

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 OTA commit shadow registers to power-on defaults.

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

Implementation of ra8_ota_commit_set_bank_config() – masks reserved bits, then host shadow under RA8_OFF_TARGET / fail-closed on silicon (the real option-region write is bench-gated and brick-risky – T5-10).

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

Implementation of ra8_ota_commit_swap_bank() – host shadow under RA8_OFF_TARGET; fail-closed on silicon (the real option-byte write is bench-gated and brick-risky, so it must not fake success – T5-10).

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().

Variable Documentation

◆ s_bank_config

uint32_t s_bank_config = 0U

static

Shadow of the masked bank-config register.

Note: Direct modification outside this TU is forbidden.

Since: 0.1.0

Definition at line 58 of file ota_commit.c.

Referenced by ra8_ota_commit_get_bank_config(), ra8_ota_commit_reset(), and ra8_ota_commit_set_bank_config().

◆ s_pending

bool s_pending = false

static

Whether a swap-bank request is currently armed.

Note: Direct modification outside this TU is forbidden.

Since: 0.1.0

Definition at line 40 of file ota_commit.c.

Referenced by ra8_ota_commit_pending(), ra8_ota_commit_reset(), and ra8_ota_commit_swap_bank().

◆ s_pending_target

ra8_ota_bank_t s_pending_target = k_ra8_ota_bank_a

static

Bank that will be active after the next reset, when s_pending.

Note: Only meaningful while s_pending is true.

Since: 0.1.0

Definition at line 49 of file ota_commit.c.

Referenced by ra8_ota_commit_pending(), ra8_ota_commit_reset(), and ra8_ota_commit_swap_bank().

◆ s_tag

const char* s_tag = "OTACMT"

static

Definition at line 31 of file ota_commit.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ra8_ota_commit_get_bank_config()

◆ ra8_ota_commit_pending()

◆ ra8_ota_commit_reset()

◆ ra8_ota_commit_set_bank_config()

◆ ra8_ota_commit_swap_bank()

Variable Documentation

◆ s_bank_config

◆ s_pending

◆ s_pending_target

◆ s_tag