ra8_bkup_security.c File Reference

Battery Backup Function (VBATT) driver – TrustZone partitioning. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_bkup.h"
#include "ra8_bkup_internal.h"
#include "ra8_bkup_regs.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_register_protection.h"

Include dependency graph for ra8_bkup_security.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_validate_boundary (uint16_t addr)
	Validate one boundary-address register value.
static ra8_err_t	internal_validate_security_cfg (const ra8_bkup_security_config_t *cfg)
	Validate every field of an ra8_bkup_security_config_t.
ra8_err_t	ra8_bkup_security_apply (const ra8_bkup_security_config_t *cfg)
	Apply BBFSAR + VBRSABAR + VBRPABAR{S,NS} from one descriptor.
ra8_err_t	ra8_bkup_security_get (ra8_bkup_security_config_t *cfg)
	Read back the four security partition registers.

Detailed Description

Battery Backup Function (VBATT) driver – TrustZone partitioning.

Tag

[Ring 3 / HAL] {World: NS}

TrustZone attribution half of the RA8D2 battery-backup driver: the security / privilege boundary registers that partition the VBTBKRn backup store between the Secure and Non-secure worlds. Split out of ra8_bkup.c to stay under the per-file line cap; the core lifecycle, backup store and interrupt path stay there, and tamper detection lives in ra8_bkup_tamper.c.

This TU touches exactly four registers – BBFSAR, VBRSABAR, VBRPABARS and VBRPABARNS – and its validators exist only to keep those four in range, so it shares nothing with the tamper path.

PRCR write protection (issue #131)

These four are attribution registers and sit behind PRC4, not the PRC1 that guards the rest of the block (HUM Ch 13.1 Table 13.1 "Association between PRCR bits and use of registers to be protected" p 520-521). ra8_bkup_security_apply was broken for its whole life by issuing its writes with PRC4 locked, where they were silently discarded – no bus fault, no status flag. The single RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_sar) window below is what makes those writes land; do not separate it from the stores it guards. See the ra8_bkup.c file comment for the bench evidence.

Copyright

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

Definition in file ra8_bkup_security.c.

Function Documentation

internal_validate_boundary()

ra8_err_t internal_validate_boundary ( uint16_t addr )

static

Validate one boundary-address register value.

Parameters

[in]

addr

Candidate value (lower-16 of the boundary).

Returns

k_ra8_ok if 32-byte aligned and below saba_max.

Precondition

None.

Postcondition

No side effects.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Note

Thread safety: see the header declaration.

Since

0.1.0

Precondition

Module has been initialized.

Postcondition

Side effects bounded to documented state.

Definition at line 70 of file ra8_bkup_security.c.

References k_ra8_bkup_saba_align_mask, k_ra8_bkup_saba_max, k_ra8_err_invalid_arg, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_validate_security_cfg().

internal_validate_security_cfg()

ra8_err_t internal_validate_security_cfg ( const ra8_bkup_security_config_t * cfg )

static

Validate every field of an ra8_bkup_security_config_t.

Parameters

[in]

cfg

Caller-supplied, null-checked security config.

Returns

k_ra8_ok if every field is in range.

Precondition

cfg != nullptr.

cfg->bbfsar / cfg->saba / cfg->pabas / cfg->pabans are populated.

Postcondition

No side effects.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Note

Thread safety: see the header declaration.

Since

0.1.0

Postcondition

Side effects bounded to documented state.

Definition at line 101 of file ra8_bkup_security.c.

References ra8_bkup_security_config_t::bbfsar, g_bkup_tag, internal_validate_boundary(), k_ra8_bkup_bbfsar_mask_all, k_ra8_err_invalid_arg, k_ra8_ok, ra8_bkup_security_config_t::pabans, ra8_bkup_security_config_t::pabas, RA8_INTERNAL, RA8_RETURN_ON_ERROR, and ra8_bkup_security_config_t::saba.

Referenced by ra8_bkup_security_apply().

ra8_bkup_security_apply()

ra8_err_t ra8_bkup_security_apply ( const ra8_bkup_security_config_t * cfg )

nodiscard

Apply BBFSAR + VBRSABAR + VBRPABAR{S,NS} from one descriptor.

Validates that saba / pabas / pabans are 32-byte aligned (HUM Ch 12.2.2/3/4 require the bottom 5 bits to be 0) and within k_ra8_bkup_saba_max, then writes the registers in the order required by Renesas SDK convention – BBFSAR first (so the NS view sees the right registers), then VBRSABAR (S/NS split), then VBRPABARS / VBRPABARNS (privilege split inside each region).

Parameters

[in]

cfg

Non-NULL security descriptor.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	All four registers updated.
k_ra8_err_null_ptr	cfg == nullptr.
k_ra8_err_invalid_arg	An address is unaligned or > saba_max, or bbfsar has reserved bits set.

Precondition

PRCR unlocked (BBFSAR is PRCR-protected per HUM Ch 12.2.1).

IRQs masked or boot context.

Postcondition

BBFSAR == cfg->bbfsar.

VBRSABAR / VBRPABARS / VBRPABARNS reflect cfg.

See also

ra8_bkup_security_get

Since

0.1.0

Definition at line 120 of file ra8_bkup_security.c.

References ra8_bkup_security_config_t::bbfsar, g_bkup_tag, internal_validate_security_cfg(), k_ra8_bkup_bbfsar_mask_all, k_ra8_ok, k_ra8_prcr_unlock_sar, ra8_bkup_security_config_t::pabans, ra8_bkup_security_config_t::pabas, ra8_bkup_bbfsar(), ra8_bkup_vbrpabarns(), ra8_bkup_vbrpabars(), ra8_bkup_vbrsabar(), RA8_CHECK_NULL_PTR, RA8_PROTECTED_WRITE, RA8_RETURN_ON_ERROR, and ra8_bkup_security_config_t::saba.

ra8_bkup_security_get()

ra8_err_t ra8_bkup_security_get ( ra8_bkup_security_config_t * cfg )

nodiscard

Read back the four security partition registers.

Parameters

[out]

cfg

Non-NULL receiver.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	cfg == nullptr.

Precondition

cfg writable.

Postcondition

cfg mirrors the live registers.

Since

0.1.0

Definition at line 143 of file ra8_bkup_security.c.

References ra8_bkup_security_config_t::bbfsar, g_bkup_tag, k_ra8_bkup_bbfsar_mask_all, k_ra8_ok, ra8_bkup_security_config_t::pabans, ra8_bkup_security_config_t::pabas, ra8_bkup_bbfsar(), ra8_bkup_vbrpabarns(), ra8_bkup_vbrpabars(), ra8_bkup_vbrsabar(), RA8_CHECK_NULL_PTR, and ra8_bkup_security_config_t::saba.