Battery Backup Function (VBATT) HAL driver – public API. More...

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

Include dependency graph for ra8_bkup.h:

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

Data Structures
struct	ra8_bkup_config_t
	Configuration descriptor passed to ra8_bkup_init. More...
struct	ra8_bkup_status_t
	Decoded snapshot of VBTBPSR. More...
struct	ra8_bkup_tamper_chan_cfg_t
	Per-channel tamper-detection configuration. More...
struct	ra8_bkup_tamper_config_t
	Whole-block tamper-detection configuration. More...
struct	ra8_bkup_security_config_t
	BBFSAR + backup-register boundary descriptor. More...

Typedefs
typedef void(*	ra8_bkup_event_fn_t) (void *ctx, uint8_t tamper_flags)
	Low-battery / tamper event callback signature.

Enumerations
enum	ra8_bkup_vdet_level_t : uint8_t { k_ra8_bkup_vdet_2p80v = 0U , k_ra8_bkup_vdet_2p53v = 1U , k_ra8_bkup_vdet_2p10v = 2U , k_ra8_bkup_vdet_1p95v = 3U , k_ra8_bkup_vdet_1p85v = 4U , k_ra8_bkup_vdet_1p75v = 5U }
	VDETBATT trip level (HUM Ch 12.2.12 p 508, VBTBPCR2.VDETLVL). More...
enum	ra8_bkup_source_t : uint8_t { k_ra8_bkup_source_vbatt = 0U , k_ra8_bkup_source_vcc = 1U }
	Live power-source decoded from VBTBPSR.BPWSWM. More...
enum	ra8_bkup_channel_t : uint8_t { k_ra8_bkup_chan_rtcic0 = 0U , k_ra8_bkup_chan_rtcic1 = 1U , k_ra8_bkup_chan_rtcic2 = 2U }
	RTCICn tamper-detection channel index (HUM Ch 12.2.8 p 505). More...
enum	ra8_bkup_edge_t : uint8_t { k_ra8_bkup_edge_falling = 0U , k_ra8_bkup_edge_rising = 1U }
	Tamper-detection edge select (HUM Ch 12.2.9 p 506). More...
enum	ra8_bkup_nc_width_t : uint8_t { k_ra8_bkup_nc_width_32768hz = 0U , k_ra8_bkup_nc_width_64hz = 1U , k_ra8_bkup_nc_width_32hz = 2U , k_ra8_bkup_nc_width_16hz = 3U , k_ra8_bkup_nc_width_8hz = 4U , k_ra8_bkup_nc_width_4hz = 5U , k_ra8_bkup_nc_width_2hz = 6U , k_ra8_bkup_nc_width_1hz = 7U }
	Noise-canceller sampling clock select (HUM Ch 12.2.18 p 511, VBTNCWCR.VINCW). More...
enum	ra8_bkup_capture_src_t : uint8_t { k_ra8_bkup_capture_src_pin = 0U , k_ra8_bkup_capture_src_vbtadf = 1U }
	RTC time-capture event source select (HUM Ch 12.2.16 p 511, VBTADCR2.VBRTCESn). More...

Functions
ra8_err_t	ra8_bkup_init (const ra8_bkup_config_t *cfg)
	Configure the battery-backup block from cfg.
ra8_err_t	ra8_bkup_deinit (void)
	Disable the battery-backup switch and close the VBTBKRn window.
ra8_err_t	ra8_bkup_cold_start_init (ra8_bkup_vdet_level_t level, uint32_t timeout_iters)
	Drive the cold-start flow from HUM Ch 12.3.7.1 p 517.
ra8_err_t	ra8_bkup_warm_start_check (bool *needs_reinit, uint32_t timeout_iters)
	Warm-start sanity check (HUM Ch 12.3.7.2 p 517).
ra8_err_t	ra8_bkup_no_switch_init (uint32_t timeout_iters)
	"Power-supply switch unused" init flow (HUM Ch 12.3.7.3 p 518).
ra8_err_t	ra8_bkup_get_status (ra8_bkup_status_t *out)
	Read VBTBPSR + VBTADSR and decode into out.
ra8_err_t	ra8_bkup_clear_status (uint8_t mask)
	Clear latched VBPORF and tamper flags selected by mask.
ra8_err_t	ra8_bkup_read_word (uint8_t word_index, uint32_t *out)
	Read one 32-bit word from the VBTBKRn array.
ra8_err_t	ra8_bkup_write_word (uint8_t word_index, uint32_t value)
	Write one 32-bit word into the VBTBKRn array.
ra8_err_t	ra8_bkup_read_byte (uint16_t index, uint8_t *out)
	Read one 8-bit byte from the VBTBKRn array.
ra8_err_t	ra8_bkup_write_byte (uint16_t index, uint8_t value)
	Write one 8-bit byte into the VBTBKRn array.
ra8_err_t	ra8_bkup_zero_all (void)
	Bulk-zeroise the entire 128-byte backup-register array.
ra8_err_t	ra8_bkup_tamper_init (const ra8_bkup_tamper_config_t *cfg)
	Apply per-channel tamper configuration in one shot.
ra8_err_t	ra8_bkup_tamper_disable (void)
	Disable every tamper input and clear flags.
ra8_err_t	ra8_bkup_read_input (ra8_bkup_channel_t channel, bool *high_out)
	Read the live RTCICn pin level via VBTIMONR.
ra8_err_t	ra8_bkup_set_input_enable (ra8_bkup_channel_t channel, bool enable)
	Convenience wrapper that just sets / clears VCHnINEN.
ra8_err_t	ra8_bkup_set_voltage_monitor (bool enable)
	Enable / disable the VBATT/6 analog tap to ADC16H.
ra8_err_t	ra8_bkup_get_voltage_monitor_enabled (bool *enabled_out)
	Read the live VBATTMNSELR.VBTMNSEL bit.
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.
ra8_err_t	ra8_bkup_attach_handler (ra8_bkup_event_fn_t fn, void *ctx)
	Attach the shared low-battery / tamper event callback.
ra8_err_t	ra8_bkup_isr_handle (void)
	ISR entry point that fires the registered callback.
void	ra8_bkup_dispatch (uint8_t tamper_flags)
	Fire the registered callback (called from the ISR shim).

Detailed Description

Battery Backup Function (VBATT) HAL driver – public API.

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

Driver for the RA8D2 battery-backup block (HUM Ch 12, p 498-519). The block has no MSTPCR bit – it is permanently powered as long as VBATT or VCC is supplied (HUM Ch 12.1 p 498). The driver exposes:

Lifecycle: ra8_bkup_init / ra8_bkup_deinit / cold + warm start helpers (ra8_bkup_cold_start_init, ra8_bkup_warm_start_check, ra8_bkup_no_switch_init).
Status decode: ra8_bkup_get_status / ra8_bkup_clear_status.
Backup-register window: byte and 32-bit accessors over all 32 words / 128 bytes of VBTBKRn.
Tamper-detection front-end: per-channel input enable, edge select, noise-canceller enable, noise-width clock select, IRQ enable, backup-clear enable, HUK zeroize enable, RTC time-capture event source select, live input monitor.
VBATT analog monitor: enable / disable + ADC-channel routing.
TrustZone partitioning: BBFSAR (per-register S/NS), VBRSABAR (backup-register S/NS boundary), VBRPABAR{S,NS} (privilege boundaries inside each S/NS region).
IRQ dispatch: ra8_bkup_attach_handler + ra8_bkup_dispatch wired to the single VBATTADI interrupt source listed in HUM Ch 12.4 Table 12.2 p 518 (sources VBTADF0..2 share one ICU slot; the dispatch passes the live VBTADSR mask so the callback knows which channel(s) fired).

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

Definition in file ra8_bkup.h.

Typedef Documentation

◆ ra8_bkup_event_fn_t

typedef void(* ra8_bkup_event_fn_t) (void *ctx, uint8_t tamper_flags)

Low-battery / tamper event callback signature.

Parameters

[in]	ctx	Caller context attached at registration.
[in]	tamper_flags	Raw VBTADSR.VBTADF[2:0] mask at the moment the ISR dispatched. 0 means a non-tamper event (low-battery / VBATT_POR).

Definition at line 235 of file ra8_bkup.h.

Enumeration Type Documentation

◆ ra8_bkup_capture_src_t

enum ra8_bkup_capture_src_t : uint8_t

RTC time-capture event source select (HUM Ch 12.2.16 p 511, VBTADCR2.VBRTCESn).

Enumerator
k_ra8_bkup_capture_src_pin	0 -> raw RTCICn pin.
k_ra8_bkup_capture_src_vbtadf	1 -> VBTADFn flag.

Definition at line 128 of file ra8_bkup.h.

◆ ra8_bkup_channel_t

enum ra8_bkup_channel_t : uint8_t

RTCICn tamper-detection channel index (HUM Ch 12.2.8 p 505).

Enumerator
k_ra8_bkup_chan_rtcic0	RTCIC0 -> VBTADF0 / VCH0*.
k_ra8_bkup_chan_rtcic1	RTCIC1 -> VBTADF1 / VCH1*.
k_ra8_bkup_chan_rtcic2	RTCIC2 -> VBTADF2 / VCH2*.

Definition at line 87 of file ra8_bkup.h.

◆ ra8_bkup_edge_t

enum ra8_bkup_edge_t : uint8_t

Tamper-detection edge select (HUM Ch 12.2.9 p 506).

Enumerator
k_ra8_bkup_edge_falling	VCHnEG = 0 -> falling edge.
k_ra8_bkup_edge_rising	VCHnEG = 1 -> rising edge.

Definition at line 97 of file ra8_bkup.h.

◆ ra8_bkup_nc_width_t

enum ra8_bkup_nc_width_t : uint8_t

Noise-canceller sampling clock select (HUM Ch 12.2.18 p 511, VBTNCWCR.VINCW).

Encoding matches the HUM table – 000b is the high-frequency sub-clock, 001b..111b are the divided-down 64 Hz counter taps. When VINCW is non-zero the RTC 64 Hz counter must be running.

Enumerator
k_ra8_bkup_nc_width_32768hz	000b: 32.768 kHz (sub-clock).
k_ra8_bkup_nc_width_64hz	001b: 64 Hz.
k_ra8_bkup_nc_width_32hz	010b: 32 Hz.
k_ra8_bkup_nc_width_16hz	011b: 16 Hz.
k_ra8_bkup_nc_width_8hz	100b: 8 Hz.
k_ra8_bkup_nc_width_4hz	101b: 4 Hz.
k_ra8_bkup_nc_width_2hz	110b: 2 Hz.
k_ra8_bkup_nc_width_1hz	111b: 1 Hz.

Definition at line 112 of file ra8_bkup.h.

◆ ra8_bkup_source_t

enum ra8_bkup_source_t : uint8_t

Live power-source decoded from VBTBPSR.BPWSWM.

Enumerator
k_ra8_bkup_source_vbatt	BPWSWM=0: VCC < VDETBATT, on VBATT.
k_ra8_bkup_source_vcc	BPWSWM=1: VCC > VDETBATT, on VCC.

Definition at line 78 of file ra8_bkup.h.

◆ ra8_bkup_vdet_level_t

enum ra8_bkup_vdet_level_t : uint8_t

VDETBATT trip level (HUM Ch 12.2.12 p 508, VBTBPCR2.VDETLVL).

Selects the VCC threshold below which the battery power-supply switch flips from VCC to VBATT. The two highest encodings (110b and 111b) are listed as "setting prohibited" in the HUM and are intentionally not exposed. The numeric values match the HUM encoding so they can be written directly into VBTBPCR2.VDETLVL.

Enumerator
k_ra8_bkup_vdet_2p80v	000b: 2.80 V (default after reset).
k_ra8_bkup_vdet_2p53v	001b: 2.53 V.
k_ra8_bkup_vdet_2p10v	010b: 2.10 V.
k_ra8_bkup_vdet_1p95v	011b: 1.95 V.
k_ra8_bkup_vdet_1p85v	100b: 1.85 V.
k_ra8_bkup_vdet_1p75v	101b: 1.75 V.

Definition at line 65 of file ra8_bkup.h.

Function Documentation

◆ ra8_bkup_attach_handler()

ra8_err_t ra8_bkup_attach_handler	(	ra8_bkup_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the shared low-battery / tamper event callback.

The battery-backup block exposes its tamper / low-battery events through ICU IELSR slots that map onto VBTADSR.VBTADF[2:0]. The driver provides a single callback slot; the ISR is expected to call ra8_bkup_dispatch with the live VBTADSR mask.

Parameters

[in]	fn	Callback function (may be nullptr to detach).
[in]	ctx	Opaque pointer forwarded to the callback.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Handler stored.

Precondition: Driver initialized.; Caller-managed lifetime for ctx.

Postcondition: Subsequent ra8_bkup_dispatch invokes fn.; Passing nullptr for fn makes dispatch a no-op.

Note: Thread safety: callback storage is plain pointer assignment, not atomic.

Since: 0.1.0

Definition at line 580 of file ra8_bkup.c.

References k_ra8_ok, s_bkup_ctx, and s_bkup_fn.

◆ ra8_bkup_clear_status()

ra8_err_t ra8_bkup_clear_status ( uint8_t mask )

nodiscard

Clear latched VBPORF and tamper flags selected by mask.

VBPORF is W0C (write-0-to-clear) per HUM Ch 12.2.13 p 509; the driver does the inverted-mask write so callers can pass the same bit mask they observed via ra8_bkup_get_status.

Parameters

[in] mask OR of k_ra8_bkup_vbtbpsr_mask_vbporf and k_ra8_bkup_vbtadsr_mask_* values.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always succeeds (bits not set in mask left alone).

Precondition: Driver initialized.; IRQs masked or single-threaded context.

Postcondition: VBPORF cleared if requested.; Bits of VBTADSR present in mask cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 448 of file ra8_bkup.c.

References k_ra8_bkup_vbtadsr_mask_all, k_ra8_bkup_vbtbpsr_mask_vbporf, k_ra8_ok, k_ra8_prcr_unlock_lpm, priv_ra8_bkup_internal_rmw8(), ra8_bkup_vbtadsr(), and ra8_bkup_vbtbpsr().

◆ ra8_bkup_cold_start_init()

ra8_err_t ra8_bkup_cold_start_init	(	ra8_bkup_vdet_level_t	level,
		uint32_t	timeout_iters )

nodiscard

Drive the cold-start flow from HUM Ch 12.3.7.1 p 517.

Implements the seven HUM-documented steps for first-time power-up of both VCC and VBATT:

Wait for VBPORM to read 1 (VBATT_R above VPORBATT).
Clear VBPORF.
Program VDETLVL.
Caller must wait tDETWT externally (see timeout_iters).
Set VDETE.
Sub-clock + RTC bring-up is the caller's job (out of scope here).
Returns success once the switch is armed.

The wait in step 1 is bounded by timeout_iters polling cycles to avoid livelock on broken hardware – callers should pass a value that comfortably exceeds the spec'd VBATT_R rise time.

Parameters

[in]	level	VDETBATT level to programme.
[in]	timeout_iters	Maximum poll iterations waiting for VBPORM.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Switch armed.
k_ra8_err_invalid_arg	level out of range.
k_ra8_err_hw_timeout	VBPORM stayed 0 for the whole poll loop.

Precondition: PRCR unlocked, IRQs masked.; timeout_iters > 0.

Postcondition: VBTBPCR2.VDETE == 1.; VBPORF cleared, VDETLVL == level.

Note: Caller still needs to wait tDETWT between this call and any use of the switch; the wait is intentionally external so the HAL stays clock-agnostic.

See also: ra8_bkup_warm_start_check; ra8_bkup_no_switch_init

Since: 0.1.0

Definition at line 291 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_max_vdet_level, k_ra8_bkup_status_clear_keep_mask, k_ra8_bkup_vbtbpcr2_mask_lvl, k_ra8_bkup_vbtbpcr2_mask_vdete, k_ra8_bkup_vbtbpsr_mask_vbporm, k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtbpcr1(), ra8_bkup_vbtbpcr2(), ra8_bkup_vbtbpsr(), ra8_log_info, RA8_PROTECTED_WRITE, and s_bkup_initialized.

◆ ra8_bkup_deinit()

ra8_err_t ra8_bkup_deinit ( void )

nodiscard

Disable the battery-backup switch and close the VBTBKRn window.

Clears VBAE so VBTBKRn data is preserved across VCC loss (per HUM Ch 12.2.6 p 504 the bit must be 0 before VBATT cutover) and stops the battery power-supply switch by setting BPWSWSTP. Leaves the latched VBPORF / tamper flags alone – use ra8_bkup_clear_status to also wipe them.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always succeeds.

Precondition: Driver previously initialized via ra8_bkup_init.; IRQs masked or single-threaded shutdown context.

Postcondition: VBTBER.VBAE == 0.; VBTBPCR1.BPWSWSTP == 1.

Note: Not thread-safe.

See also: ra8_bkup_init

Since: 0.1.0

Definition at line 273 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_vbtbpcr1_mask_bpwswstp, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtber(), ra8_bkup_vbtbpcr1(), ra8_log_info, RA8_PROTECTED_WRITE, and s_bkup_initialized.

◆ ra8_bkup_dispatch()

void ra8_bkup_dispatch ( uint8_t tamper_flags )

Fire the registered callback (called from the ISR shim).

Parameters

[in] tamper_flags Snapshot of VBTADSR observed in the ISR.

Precondition: Driver initialized.; Caller has read VBTADSR before clearing flags.

Postcondition: Callback executed if attached.; No state change in this driver.

Note: Thread safety: not re-entrant; call from one ISR context only.

Since: 0.1.0

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

Definition at line 613 of file ra8_bkup.c.

References s_bkup_ctx, and s_bkup_fn.

Referenced by ra8_bkup_isr_handle().

◆ ra8_bkup_get_status()

ra8_err_t ra8_bkup_get_status ( ra8_bkup_status_t * out )

nodiscard

Read VBTBPSR + VBTADSR and decode into out.

Parameters

[out] out Non-NULL status descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	out populated.
k_ra8_err_null_ptr	out == nullptr.

Precondition: Driver initialized.; out points to writable storage.

Postcondition: out->source reflects current BPWSWM bit.; out->raw_vbtbpsr matches the live register read.

Note: Thread safety: read-only, safe to call concurrently with writes provided the register is naturally aligned (it is).

See also: ra8_bkup_clear_status

Since: 0.1.0

Definition at line 427 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_source_vbatt, k_ra8_bkup_source_vcc, k_ra8_bkup_vbtadsr_mask_all, k_ra8_bkup_vbtbpsr_mask_swm, k_ra8_bkup_vbtbpsr_mask_vbporf, k_ra8_bkup_vbtbpsr_mask_vbporm, k_ra8_ok, ra8_bkup_status_t::por_detected, ra8_bkup_vbtadsr(), ra8_bkup_vbtbpsr(), RA8_CHECK_NULL_PTR, ra8_bkup_status_t::raw_vbtbpsr, ra8_bkup_status_t::source, ra8_bkup_status_t::tamper_flags, and ra8_bkup_status_t::vbatt_r_ok.

◆ ra8_bkup_get_voltage_monitor_enabled()

ra8_err_t ra8_bkup_get_voltage_monitor_enabled ( bool * enabled_out )

nodiscard

Read the live VBATTMNSELR.VBTMNSEL bit.

Parameters

[out] enabled_out Set to true when the analog tap is on.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status decoded.
k_ra8_err_null_ptr	enabled_out == nullptr.

Precondition: enabled_out writable.

Postcondition: *enabled_out matches the register bit.

Since: 0.1.0

Definition at line 567 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_vbattmnselr_mask_vbtmnsel, k_ra8_ok, ra8_bkup_vbattmnselr(), and RA8_CHECK_NULL_PTR.

◆ ra8_bkup_init()

ra8_err_t ra8_bkup_init ( const ra8_bkup_config_t * cfg )

nodiscard

Configure the battery-backup block from cfg.

Sequence (HUM Ch 12.2.11 p 507 + Ch 12.2.6 p 504):

If cfg->enable_switch, clear BPWSWSTP and program VBTBPCR2.VDETLVL, then set VDETE so the VCC drop detector arms.
If cfg->enable_backup, write 1 to VBTBER.VBAE to open the VBTBKRn access window, then busy-wait the HUM-mandated >= 500 ns settle (HUM Ch 12.2.6 p 504: "You must write 1 to VBAE before accessing VBTBKR" ... "wait for at least 500 ns after writing 1 to VBAE, and then access VBTBKR"). VBAE resets to 1, but the HUM procedure requires the explicit write + settle. To retain VBTBKRn across a real VBATT cutover the app must later write VBAE back to 0 via ra8_bkup_deinit. Note: VBAE is only one precondition – the battery-backup block is also inoperative unless voltage monitor 0 (LVD0) reset is enabled via the OFS1.PVDAS option byte (HUM Ch 12.1.3 p 499, Ch 12.3.2 p 514), which is a boot-time option setting outside this driver's scope.
Clear any latched VBPORF and tamper flags so the first call to ra8_bkup_get_status starts from a known state.

The driver does not unlock PRCR – the caller (typically board init) is expected to handle the SYSC protection key for the few BAT* registers that require it.

State Machine: Driver-state transitions enforced by this entry point:
<p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p>

Parameters

[in] cfg Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Hardware armed; backup window open.
k_ra8_err_null_ptr	cfg == nullptr.
k_ra8_err_invalid_arg	cfg->vdet_level is one of the two "setting prohibited" encodings.

Precondition: PRCR group 0 is unlocked (caller's responsibility).; IRQs masked or single-threaded init context.

Postcondition: BPWSWSTP and VBAE reflect cfg.; When cfg->enable_backup, the VBTBKRn window is armed and the >= 500 ns settle has elapsed, so the next VBTBKRn access is valid.; VBTADSR == 0 and VBPORF == 0.

Note: Not thread-safe.

See also: ra8_bkup_deinit; ra8_bkup_cold_start_init

Since: 0.1.0

Definition at line 222 of file ra8_bkup.c.

References ra8_bkup_config_t::enable_backup, ra8_bkup_config_t::enable_switch, g_bkup_tag, internal_validate_cfg(), internal_vbae_access_settle(), k_ra8_bkup_status_clear_keep_mask, k_ra8_bkup_vbtber_mask_vbae, k_ra8_bkup_vbtbpcr1_mask_bpwswstp, k_ra8_bkup_vbtbpcr2_mask_lvl, k_ra8_bkup_vbtbpcr2_mask_vdete, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtadsr(), ra8_bkup_vbtber(), ra8_bkup_vbtbpcr1(), ra8_bkup_vbtbpcr2(), ra8_bkup_vbtbpsr(), RA8_CHECK_NULL_PTR, ra8_log_info, RA8_PROTECTED_WRITE, RA8_RETURN_ON_ERROR, s_bkup_initialized, and ra8_bkup_config_t::vdet_level.

Referenced by internal_bkup_demo_setup_or_halt().

◆ ra8_bkup_isr_handle()

ra8_err_t ra8_bkup_isr_handle ( void )

nodiscard

ISR entry point that fires the registered callback.

Reads VBTADSR, masks against VBTADCR1.VBTADIE[2:0] (only IRQ-armed channels generate the VBATTADI interrupt per HUM Ch 12.4 Table 12.2 p 518), W0Cs the flags it dispatched on, then invokes the registered callback with the mask of fired channels.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Dispatched (or no-op if no flag set).
k_ra8_err_not_initialized	Driver not initialized.

Precondition: ISR caller, IRQs masked at this point.

Postcondition: Flagged-and-armed VBTADFn bits are W0Ced.; Callback invoked exactly once with the dispatched mask.

Since: 0.1.0

Definition at line 587 of file ra8_bkup.c.

References k_ra8_bkup_vbtadcr1_mask_ie_all, k_ra8_bkup_vbtadsr_mask_all, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_prcr_unlock_lpm, priv_ra8_bkup_internal_rmw8(), ra8_bkup_dispatch(), ra8_bkup_vbtadcr1(), ra8_bkup_vbtadsr(), and s_bkup_initialized.

◆ ra8_bkup_no_switch_init()

ra8_err_t ra8_bkup_no_switch_init ( uint32_t timeout_iters )

nodiscard

"Power-supply switch unused" init flow (HUM Ch 12.3.7.3 p 518).

Used when VCC and VBATT are externally tied together. Sets BPWSWSTP, waits for VBPORM to drop, clears VDETE, restores VDETLVL to the prohibited 110b sentinel (HUM-documented "initial" value), W0Cs VBPORF, and zeroes VBTICTLR / VBTICTLR2 / VBTADSR / VBTADCR1 / VBTADCR2 / VBTBKRn. Sub-clock and RTC bring-up are out of scope for the HAL.

Parameters

[in] timeout_iters Max polls waiting for VBPORM == 0.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	All registers reset, switch stopped.
k_ra8_err_hw_timeout	VBPORM never dropped.

Precondition: PRCR unlocked, IRQs masked.; timeout_iters > 0.

Postcondition: VBTBPCR1.BPWSWSTP == 1.; VBTBPCR2.VDETE == 0 and VDETLVL == 110b.; VBTICTLR / VBTICTLR2 / VBTADSR / VBTADCR1 / VBTADCR2 == 0.

See also: ra8_bkup_cold_start_init

Since: 0.1.0

Definition at line 367 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_no_switch_lvl_raw, k_ra8_bkup_status_clear_keep_mask, k_ra8_bkup_vbtbpcr1_mask_bpwswstp, k_ra8_bkup_vbtbpsr_mask_vbporm, k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtadcr1(), ra8_bkup_vbtadcr2(), ra8_bkup_vbtadsr(), ra8_bkup_vbtbpcr1(), ra8_bkup_vbtbpcr2(), ra8_bkup_vbtbpsr(), ra8_bkup_vbtictlr(), ra8_bkup_vbtictlr2(), ra8_log_info, RA8_PROTECTED_WRITE, and s_bkup_initialized.

◆ ra8_bkup_read_byte()

ra8_err_t ra8_bkup_read_byte	(	uint16_t	index,
		uint8_t *	out )

nodiscard

Read one 8-bit byte from the VBTBKRn array.

Parameters

[in]	index	Backup-register index in 0..127.
[out]	out	Non-NULL receiver.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Byte read.
k_ra8_err_null_ptr	out == nullptr.
k_ra8_err_invalid_arg	index >= 128.

Precondition: Driver initialized with cfg->enable_backup == true.; out writable.

Postcondition: *out matches the live byte.

See also: ra8_bkup_write_byte

Since: 0.1.0

Definition at line 504 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_reg_count, k_ra8_err_invalid_arg, k_ra8_ok, ra8_bkup_vbtbkr(), and RA8_CHECK_NULL_PTR.

◆ ra8_bkup_read_input()

ra8_err_t ra8_bkup_read_input	(	ra8_bkup_channel_t	channel,
		bool *	high_out )

nodiscard

Read the live RTCICn pin level via VBTIMONR.

Parameters

[in]	channel	RTCICn channel index.
[out]	high_out	Set to true if the pin reads high.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Level decoded.
k_ra8_err_null_ptr	high_out == nullptr.
k_ra8_err_invalid_arg	channel >= 3.

Precondition: Driver initialized; VCHnINEN must be 1 for the read to be meaningful (HUM Ch 12.2.10 p 506 – otherwise reads as 0).

Postcondition: *high_out matches the live VCHnMON bit.

Since: 0.1.0

Definition at line 398 of file ra8_bkup_tamper.c.

References g_bkup_tag, internal_chan_mask(), k_ra8_bkup_chan_count, k_ra8_bkup_vbtimonr_mask_vch0mon, k_ra8_err_invalid_arg, k_ra8_ok, ra8_bkup_vbtimonr(), and RA8_CHECK_NULL_PTR.

◆ ra8_bkup_read_word()

ra8_err_t ra8_bkup_read_word	(	uint8_t	word_index,
		uint32_t *	out )

nodiscard

Read one 32-bit word from the VBTBKRn array.

Parameters

[in]	word_index	Word index in 0..31 (32 words = 128 bytes).
[out]	out	Non-NULL receiver for the word value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Word read into *out.
k_ra8_err_null_ptr	out == nullptr.
k_ra8_err_invalid_arg	word_index >= 32.

Precondition: Driver initialized with cfg->enable_backup == true.; out points to writable storage.

Postcondition: *out matches the live 32-bit register value.

Note: Thread safety: read-only.

See also: ra8_bkup_write_word

Since: 0.1.0

Definition at line 474 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_word_count, k_ra8_err_invalid_arg, k_ra8_ok, ra8_bkup_vbtbkr_word(), and RA8_CHECK_NULL_PTR.

Referenced by internal_bkup_demo_rw_check(), and internal_bkup_demo_survival_check().

◆ 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.

◆ ra8_bkup_set_input_enable()

ra8_err_t ra8_bkup_set_input_enable	(	ra8_bkup_channel_t	channel,
		bool	enable )

nodiscard

Convenience wrapper that just sets / clears VCHnINEN.

Parameters

[in]	channel	RTCICn channel index.
[in]	enable	true -> drive pad as input.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	VBTICTLR updated.
k_ra8_err_invalid_arg	channel >= 3.

Precondition: PRCR unlocked.

Postcondition: Bit channel of VBTICTLR matches enable.

Since: 0.1.0

Definition at line 410 of file ra8_bkup_tamper.c.

References internal_chan_mask(), k_ra8_bkup_chan_count, k_ra8_bkup_vbtictlr_mask_vch0inen, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_prcr_unlock_lpm, priv_ra8_bkup_internal_rmw8(), and ra8_bkup_vbtictlr().

◆ ra8_bkup_set_voltage_monitor()

ra8_err_t ra8_bkup_set_voltage_monitor ( bool enable )

nodiscard

Enable / disable the VBATT/6 analog tap to ADC16H.

HUM Ch 12.2.5 p 503 + Ch 12.3.6 p 517: set VBTMNSEL = 1 to route VBATT/6 to ANVBAT (ADC channel input). The HUM mandates a tMONWT settling delay before the ADC reading is valid; the wait is the caller's responsibility because the HAL has no delay primitive. Recommend clearing again as soon as the conversion completes because VBTMNSEL = 1 increases VBATT current draw.

Parameters

[in] enable true -> enable monitor; false -> disable.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always succeeds.

Precondition: PRCR unlocked.

Postcondition: VBATTMNSELR.VBTMNSEL == enable.

See also: ra8_bkup_get_voltage_monitor_enabled

Since: 0.1.0

Definition at line 555 of file ra8_bkup.c.

References k_ra8_bkup_vbattmnselr_mask_vbtmnsel, k_ra8_ok, k_ra8_prcr_unlock_pvd, priv_ra8_bkup_internal_rmw8(), and ra8_bkup_vbattmnselr().

◆ ra8_bkup_tamper_disable()

ra8_err_t ra8_bkup_tamper_disable ( void )

nodiscard

Disable every tamper input and clear flags.

Counterpart to ra8_bkup_tamper_init: zeroes VBTICTLR / VBTICTLR2 / VBTADCR1 / VBTADCR2 / VBTADCR3 and W0Cs VBTADSR. Used during deinit and during the noise-canceller reconfiguration dance the HUM mandates ("VCHnNCE, VBTADCR1/2/3 should be disabled before changing VINCW", HUM Ch 12.3.5 p 516).

Returns: ra8_err_t error code.

Return values

k_ra8_ok Hardware disarmed.

Precondition: PRCR unlocked, IRQs masked.

Postcondition: VBTICTLR / VBTICTLR2 / VBTADCR1 / VBTADCR2 / VBTADCR3 == 0.; VBTADSR.VBTADF[2:0] cleared.

Since: 0.1.0

Definition at line 377 of file ra8_bkup_tamper.c.

References k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtadcr1(), ra8_bkup_vbtadcr2(), ra8_bkup_vbtadcr3(), ra8_bkup_vbtadsr(), ra8_bkup_vbtictlr(), ra8_bkup_vbtictlr2(), and RA8_PROTECTED_WRITE.

◆ ra8_bkup_tamper_init()

ra8_err_t ra8_bkup_tamper_init ( const ra8_bkup_tamper_config_t * cfg )

nodiscard

Apply per-channel tamper configuration in one shot.

Implements HUM Ch 12.3.7.4 p 518 steps 1-8: programs VCHnINEN / VCHnNCE / VCHnEG, sets VINCW for the noise canceller, dummy-reads and clears VBTADFn flags after edge programming, then enables VBTADCR1 (IRQ + clear) / VBTADCR2 (capture source) / VBTADCR3 (HUK zeroize) per channel.

The HUM-documented 50us pin-stable wait and 5-RTC-clock noise canceller wait are the caller's responsibility – the HAL has no generic delay primitive.

Parameters

[in] cfg Non-NULL whole-block configuration.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Hardware programmed.
k_ra8_err_null_ptr	cfg == nullptr.
k_ra8_err_invalid_arg	cfg->nc_width out of range.

Precondition: PRCR unlocked, IRQs masked.; All cfg->channels[].edge are valid enum values.

Postcondition: VBTICTLR / VBTICTLR2 / VBTNCWCR / VBTADCR1..3 reflect cfg.; VBTADSR cleared after the dummy-read step.

See also: ra8_bkup_tamper_disable

Since: 0.1.0

Definition at line 322 of file ra8_bkup_tamper.c.

References g_bkup_tag, internal_compose_vbtadcr1(), internal_compose_vbtadcr2(), internal_compose_vbtadcr3(), internal_compose_vbtictlr(), internal_compose_vbtictlr2(), internal_validate_tamper_channels(), k_ra8_bkup_max_nc_width, k_ra8_bkup_vbtncwcr_mask_vincw, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_tamper_config_t::nc_width, ra8_bkup_vbtadcr1(), ra8_bkup_vbtadcr2(), ra8_bkup_vbtadcr3(), ra8_bkup_vbtadsr(), ra8_bkup_vbtictlr(), ra8_bkup_vbtictlr2(), ra8_bkup_vbtncwcr(), RA8_CHECK_NULL_PTR, ra8_log_info, RA8_PROTECTED_WRITE, RA8_RETURN_ON_ERROR, and s_bkup_initialized.

◆ ra8_bkup_warm_start_check()

ra8_err_t ra8_bkup_warm_start_check	(	bool *	needs_reinit,
		uint32_t	timeout_iters )

nodiscard

Warm-start sanity check (HUM Ch 12.3.7.2 p 517).

After a VBATT->VCC transition the firmware must:

Wait for VBPORM == 1.
Inspect VBPORF: if set, the VBATT_R rail dropped below VPORBATT and the entire backup area must be reinitialized by calling ra8_bkup_cold_start_init. If clear, the backup area state survived and no further action is required.

Parameters

[out]	needs_reinit	Set to true when VBPORF was latched and the caller must run cold-start init.
[in]	timeout_iters	Max polls waiting for VBPORM.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status decoded into *needs_reinit.
k_ra8_err_null_ptr	needs_reinit == nullptr.
k_ra8_err_hw_timeout	VBPORM stayed 0.

Precondition: PRCR unlocked.; timeout_iters > 0.

Postcondition: *needs_reinit reflects VBPORF.; VBPORF is left untouched (caller decides when to W0C it).

Note: Pure status read; safe to call from cold reset path.

See also: ra8_bkup_cold_start_init

Since: 0.1.0

Definition at line 341 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_vbtbpsr_mask_vbporf, k_ra8_bkup_vbtbpsr_mask_vbporm, k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_ok, ra8_bkup_vbtbpsr(), and RA8_CHECK_NULL_PTR.

◆ ra8_bkup_write_byte()

ra8_err_t ra8_bkup_write_byte	(	uint16_t	index,
		uint8_t	value )

nodiscard

Write one 8-bit byte into the VBTBKRn array.

Parameters

[in]	index	Backup-register index in 0..127.
[in]	value	Byte to store.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Byte written.
k_ra8_err_invalid_arg	index >= 128.

Precondition: Driver initialized with cfg->enable_backup == true.

Postcondition: VBTBKRn[index] == value.

See also: ra8_bkup_read_byte

Since: 0.1.0

Definition at line 517 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_reg_count, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtbkr(), RA8_CHECK_NULL_PTR, and RA8_PROTECTED_WRITE.

◆ ra8_bkup_write_word()

ra8_err_t ra8_bkup_write_word	(	uint8_t	word_index,
		uint32_t	value )

nodiscard

Write one 32-bit word into the VBTBKRn array.

Parameters

[in]	word_index	Word index in 0..31.
[in]	value	32-bit value to store.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Value written.
k_ra8_err_invalid_arg	word_index >= 32.

Precondition: Driver initialized with cfg->enable_backup == true.; IRQs masked or single-threaded context.

Postcondition: VBTBKRn[word_index*4 .. word_index*4+3] == value (LE).

Note: Not thread-safe.

See also: ra8_bkup_read_word

Since: 0.1.0

Definition at line 487 of file ra8_bkup.c.

References g_bkup_tag, k_ra8_bkup_word_count, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtbkr_word(), RA8_CHECK_NULL_PTR, and RA8_PROTECTED_WRITE.

Referenced by internal_bkup_demo_rw_check(), and internal_bkup_demo_survival_check().

◆ ra8_bkup_zero_all()

ra8_err_t ra8_bkup_zero_all ( void )

nodiscard

Bulk-zeroise the entire 128-byte backup-register array.

Software equivalent of the tamper-detection backup-clear path. Useful when an application detects a logical tamper that does not trip an RTCICn pin.

Returns: ra8_err_t error code.

Return values

k_ra8_ok All 128 VBTBKRn slots zeroed.

Precondition: Driver initialized with cfg->enable_backup == true.; IRQs masked.

Postcondition: Every VBTBKRn[0..127] == 0.

Since: 0.1.0

Definition at line 533 of file ra8_bkup.c.

References k_ra8_bkup_reg_count, k_ra8_ok, k_ra8_prcr_unlock_lpm, ra8_bkup_vbtbkr(), and RA8_PROTECTED_WRITE.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_bkup_event_fn_t

Enumeration Type Documentation

◆ ra8_bkup_capture_src_t

◆ ra8_bkup_channel_t

◆ ra8_bkup_edge_t

◆ ra8_bkup_nc_width_t

◆ ra8_bkup_source_t

◆ ra8_bkup_vdet_level_t

Function Documentation

◆ ra8_bkup_attach_handler()

◆ ra8_bkup_clear_status()

◆ ra8_bkup_cold_start_init()

◆ ra8_bkup_deinit()

◆ ra8_bkup_dispatch()

◆ ra8_bkup_get_status()

◆ ra8_bkup_get_voltage_monitor_enabled()

◆ ra8_bkup_init()

◆ ra8_bkup_isr_handle()

◆ ra8_bkup_no_switch_init()

◆ ra8_bkup_read_byte()

◆ ra8_bkup_read_input()

◆ ra8_bkup_read_word()

◆ ra8_bkup_security_apply()

◆ ra8_bkup_security_get()

◆ ra8_bkup_set_input_enable()

◆ ra8_bkup_set_voltage_monitor()

◆ ra8_bkup_tamper_disable()

◆ ra8_bkup_tamper_init()

◆ ra8_bkup_warm_start_check()

◆ ra8_bkup_write_byte()

◆ ra8_bkup_write_word()

◆ ra8_bkup_zero_all()