VBATT backup-register read/write + reset-survival demo (EK-RA8D2). More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_bkup.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_isr.h"
#include "ra8_mstp.h"
#include "ra8_time.h"

Include dependency graph for main.c:

Enumerations
enum	bkup_demo_config_t : uint32_t { k_bkup_demo_baud = 115200U , k_bkup_demo_period_ms = 1000U , k_bkup_demo_sentinel = 0x600DCAFEU , k_bkup_demo_pat_mult = 0x01010101U , k_bkup_demo_pat_xor = 0xA5A5A5A5U }
	Compile-time settings. More...
enum	bkup_demo_layout_t : uint8_t { k_bkup_demo_data_words = 30U , k_bkup_demo_idx_sentinel = 30U , k_bkup_demo_idx_boot = 31U }
	Backup-word layout (32 words total; 0..29 data, 30/31 reserved). More...

Functions
static void	internal_bkup_demo_panic_halt (void)
	Park forever after a fatal initialization failure.
static uint32_t	internal_bkup_demo_pattern (uint8_t i)
	Derive the deterministic pattern for one backup word.
static void	internal_bkup_demo_setup_or_halt (void)
	Initialize clocks, time, console, LEDs, and the backup domain.
static ra8_err_t	internal_bkup_demo_rw_check (uint8_t *out_ok)
	Write words 0..29 with the pattern, read them back, and compare.
static ra8_err_t	internal_bkup_demo_survival_check (void)
	Detect reset survival and maintain the boot counter.
static void	internal_bkup_demo_report_survival (void)
	Emit the fixed-width reset-survival suffix over the console.
void	main (void)
	The application entry point Reset_Handler hands control to.

Variables
static const char *	s_tag = "bkup_demo"
	Diagnostic / log tag.
static const uint8_t	s_bkup_demo_ok_msg [] = "bkup: rw=ok "
	Prefix for a successful backup-word read/write report.
static const uint8_t	s_bkup_demo_bad_msg [] = "bkup: rw=BAD "
	Prefix for a failed backup-word read/write report.
static const uint8_t	s_bkup_demo_surv_y [] = "survived=Y "
	Warm-reset survival suffix.
static const uint8_t	s_bkup_demo_surv_n [] = "survived=N "
	Cold-start survival suffix.
static const uint8_t	s_bkup_demo_crlf [] = "\r\n"
	Console line terminator for each periodic report.
volatile uint32_t	g_bkup_rw_ok = 0U
	1 when words 0..29 read back exactly what was written.
volatile uint32_t	g_bkup_survived = 0U
	1 when the sentinel was found at boot (state retained across reset).
volatile uint32_t	g_bkup_boot_count = 0U
	Boot counter held in backup word 31 (increments per reset on HW).
volatile uint32_t	g_bkup_heartbeat = 0U
	Bumps once per main-loop pass – liveness for headless probes.

Detailed Description

VBATT backup-register read/write + reset-survival demo (EK-RA8D2).

Tag: [Ring 6 / APP] {World: S}

The RA8D2 keeps 128 bytes (32 x 32-bit VBTBKRn words) of backup register storage in the VBATT-backed power domain, which retains its contents across a CPU reset (and, with a battery on VBATT, across a power cycle). This demo exercises both halves of that contract:

Read / write window. Words 0..29 are filled with a deterministic pattern, read back, and compared byte-exact (g_bkup_rw_ok).
Reset survival. Word 30 holds a sentinel and word 31 a boot counter. On the first boot the sentinel is absent, so it is written and the counter set to 1 (g_bkup_survived = 0). After a reset the sentinel is found intact, the counter is incremented, and g_bkup_survived = 1 – proving the domain retained state.

Bring-up: CGC + SysTick + SCI8 + LEDs. Once a second the loop reports "bkup: rw=ok survived=Y boot=3\r\n" on the J-Link OB CDC channel. LED1 toggles while the read/write window is healthy; LED2 toggles if it ever mismatches.

Bare EK-RA8D2 only – no shields or external transceivers.

Note: Silicon status (issue #131). The dominant precondition for a live VBTBKRn window is that 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); this app sets OFS1 = 0xFFFFFFF0 in CMakeLists.txt. Bench debugger reads with the default OFS1 = 0xFFFFFFFF (LVD0 off) show the whole VBATT area held in VBATT_POR reset (VBPORF = 1) with every write dropped – rw=BAD. The current HIL flash path (scripts/hil/flash.sh) strips the .option_ setting_* sections, so the OFS1 change does not reach silicon through it; on-silicon rw=ok needs a full-image / option-byte flash (see README).; Headless-emulator status. tools/ra8_emulator models the VBTBKRn window as a reset-retained domain (board_periph_bkup.c) whose writes are gated on VBTBER.VBAE (HUM Ch 12.2.6 p 504), so the read/write half passes (rw=ok) only because this demo first arms VBAE via ra8_bkup_init – a firmware that forgot the VBAE step now reports rw=BAD on the fake too. The emulator cannot model the OFS1/LVD0 option-byte prerequisite (there is no option memory in the fake), which is precisely why the emulator reports rw=ok while the bench reports rw=BAD. --reboot 1 re-runs from the reset vector with the retained domain, so the second boot finds the sentinel and reports survived=Y (the ra8_emulator_smoke.sh gate exercises this).

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ bkup_demo_config_t

enum bkup_demo_config_t : uint32_t

Compile-time settings.

Enumerator
k_bkup_demo_baud	SCI8 console baud rate.
k_bkup_demo_period_ms	Delay between reports.
k_bkup_demo_sentinel	"good cafe" reset-survival marker.
k_bkup_demo_pat_mult	Per-word pattern multiplier.
k_bkup_demo_pat_xor	Per-word pattern XOR mask.

Definition at line 73 of file main.c.

◆ bkup_demo_layout_t

enum bkup_demo_layout_t : uint8_t

Backup-word layout (32 words total; 0..29 data, 30/31 reserved).

Enumerator
k_bkup_demo_data_words	Count of rw-pattern words (0..29).
k_bkup_demo_idx_sentinel	Reset-survival sentinel word index.
k_bkup_demo_idx_boot	Boot-counter word index.

Definition at line 82 of file main.c.

Function Documentation

◆ internal_bkup_demo_panic_halt()

void internal_bkup_demo_panic_halt ( void )

static

Park forever after a fatal initialization failure.

Repeatedly executes the target wait-for-interrupt instruction so the failed application cannot advance its heartbeat or diagnostics.

Precondition: A required platform or backup-domain initialization step failed.; The caller accepts that control never returns.

Postcondition: The core remains in the permanent wait loop.; No success indicator is modified.

Note: A debugger can inspect the call site to identify the failed dependency.

Since: 0.1.0

Definition at line 172 of file main.c.

References RA8_INTERNAL.

Referenced by internal_bkup_demo_setup_or_halt(), and main().

◆ internal_bkup_demo_pattern()

uint32_t internal_bkup_demo_pattern ( uint8_t i )

static

Derive the deterministic pattern for one backup word.

Multiplies the word index into repeated bytes and XORs the fixed mask, producing visibly distinct values for adjacent slots.

Parameters

[in] i Backup data-word index.

Returns: Expected 32-bit pattern for i.

Return values

0x00000000..0xFFFFFFFF Deterministic index-derived word.

Precondition: i is less than k_bkup_demo_data_words.; The compile-time multiplier and mask retain their documented values.

Postcondition: No backup register or global state is accessed.; Repeated calls with the same index return the same value.

Note: The pattern is diagnostic, not cryptographic.

Since: 0.1.0

Definition at line 193 of file main.c.

References k_bkup_demo_pat_mult, k_bkup_demo_pat_xor, and RA8_INTERNAL.

Referenced by internal_bkup_demo_rw_check().

◆ internal_bkup_demo_report_survival()

void internal_bkup_demo_report_survival ( void )

static

Emit the fixed-width reset-survival suffix over the console.

Selects the affirmative or negative string from the retained-state diagnostic and writes its common payload length without allocation.

Precondition: The board UART console has been initialized.; The two suffix arrays retain equal compile-time lengths.

Postcondition: Exactly one survival suffix has been offered to the console backend.; Retained-state globals remain unchanged.

Note: The boot count is exposed through g_bkup_boot_count for SWD probes.

Since: 0.1.0

Definition at line 375 of file main.c.

References g_bkup_survived, ra8_board_uart_console_write(), RA8_INTERNAL, s_bkup_demo_surv_n, and s_bkup_demo_surv_y.

Referenced by main().

◆ internal_bkup_demo_rw_check()

ra8_err_t internal_bkup_demo_rw_check ( uint8_t * out_ok )

staticnodiscard

Write words 0..29 with the pattern, read them back, and compare.

Parameters

[out] out_ok 1 if every word read back exactly, else 0.

MC/DC:: Decision read != internal_bkup_demo_pattern(i) (1 condition). Two vectors: match (steady state) and mismatch (covered by the host test, which seeds a differing read-back).

Returns: ra8_err_t – first accessor error, or k_ra8_ok.

Return values

k_ra8_err_null_ptr out_ok was NULL.

Precondition: Backup domain is powered (VBATT tied to VCC on the EVM).; Words 0..29 are available for this destructive pattern check.

Postcondition: *out_ok is 0 or 1; words 0..29 hold the pattern.; Reserved sentinel and boot-counter words remain unchanged.

Note: Accessor errors stop the sweep immediately and leave *out_ok unspecified.

Since: 0.1.0

Definition at line 283 of file main.c.

References internal_bkup_demo_pattern(), k_bkup_demo_data_words, k_ra8_ok, ra8_bkup_read_word(), ra8_bkup_write_word(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and s_tag.

Referenced by main().

◆ internal_bkup_demo_setup_or_halt()

void internal_bkup_demo_setup_or_halt ( void )

static

Initialize clocks, time, console, LEDs, and the backup domain.

Brings dependencies up in order, then explicitly enables VBATT backup access under the board's VCC-tied supply configuration.

Precondition: Core reset initialization has completed and peripheral MMIO is accessible.; Configurable interrupts remain globally masked.

Postcondition: On success all periodic-report and retained-word dependencies are ready.; Any failed step transfers control to the permanent halt loop.

Note: The backup access window intentionally remains enabled for this demo.

Since: 0.1.0

Definition at line 209 of file main.c.

References internal_bkup_demo_panic_halt(), k_bkup_demo_baud, k_ra8_bkup_vdet_2p80v, k_ra8_board_led1, k_ra8_board_led2, k_ra8_clock_id_cpuclk0, k_ra8_ok, ra8_bkup_init(), ra8_board_led_init(), ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, ra8_mstp_init(), and ra8_time_init().

Referenced by main().

◆ internal_bkup_demo_survival_check()

ra8_err_t internal_bkup_demo_survival_check ( void )

staticnodiscard

Detect reset survival and maintain the boot counter.

Reads the sentinel word. If it already holds the marker the domain retained state across a reset, so the boot counter is incremented; otherwise this is a cold boot, so the marker is planted and the counter set to 1.

MC/DC:: Decision sentinel == k_bkup_demo_sentinel (1 condition). Two vectors: marker present (warm boot) and absent (cold boot), both covered by the host test.

Returns: ra8_err_t from the backup accessors.

Return values

k_ra8_ok Retained-state diagnostics and counter were updated.

Precondition: Backup domain is powered.; Sentinel and boot-counter slots are reserved for this application.

Postcondition: g_bkup_survived / g_bkup_boot_count reflect this boot; the sentinel + counter words are written.; Pattern-test words 0..29 remain unchanged.

Note: A cold boot plants the sentinel and starts the counter at one.

Since: 0.1.0

Definition at line 332 of file main.c.

References g_bkup_boot_count, g_bkup_survived, k_bkup_demo_idx_boot, k_bkup_demo_idx_sentinel, k_bkup_demo_sentinel, k_ra8_ok, ra8_bkup_read_word(), ra8_bkup_write_word(), and RA8_INTERNAL.

Referenced by main().

◆ main()

void main ( void )

The application entry point Reset_Handler hands control to.

Returns void, not int. This is a freestanding image: there is no hosted C environment, no process and nothing to report an exit status to. ISO C fixes main at int only for a hosted implementation; for a freestanding one (C23 5.1.2.1) the startup function's name and type are implementation-defined, and this is that definition. Reset_Handler discards no value because there is none to discard, and if main ever does return, startup halts the CPU rather than resuming anything.

The firmware lane is compiled -ffreestanding (see cmake/ra8_add_app.cmake) and the flag and this signature travel together: without it both GCC and clang reject a non-int main (-Wmain / -Wmain-return-type). Do not remove one without the other.

That coupling is why the declaration sits behind __STDC_HOSTED__ == 0, which -ffreestanding sets and a hosted build does not. The guard is not defensive dressing: this header is reachable from host builds (the unit tests compile ra8_core natively), and an unguarded void main(void); makes every hosted translation unit that includes it fail with conflicting types for 'main' against its own ISO int main. The declaration therefore exists exactly where its contract does.

Hosted first-party code – everything under tests/ and tools/ – uses the ISO int main(...) contract instead, because it genuinely does run under an OS that reads the exit status. scripts/checks/check_entry_points.py holds each domain to its own contract (#707).

Declared here, once, for the same reason SystemInit is: every vector_table.c used to restate it as a local extern int32_t main(void);, sixteen copies that no compiler ever compared against the definition – and roughly thirty of them had silently drifted out of agreement with the main they called.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has configured the clock tree and VTOR.

Postcondition: Control does not return; the image runs until reset or halt.; Any value the application wanted to report has been logged, not returned.

Note: Not thread-safe; single-threaded startup context only.

Warning: Only valid while the translation unit is compiled -ffreestanding. A hosted build rejects this signature.

See also: SystemInit()

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + BSP audio then plays blocks.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the playback loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + GPT triple, runs sweep.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the sweep loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up clocks + UART + RMII pins, then ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.

Postcondition: On clean entry the kernel runs the worker thread once.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up clocks + UART, then enters ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the kernel runs the worker thread forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up LED, console, SDHI pins, then ThreadX.

Precondition: Reset_Handler has copied .data + zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: CPUCLK0 is raised to the PLL1 target before the kernel starts.; On clean entry the SD card thread runs forever.; On any HAL init failure the function halts in __WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + USB-FS + UAC1, then enters the iso-IN feed loop forever.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the iso-IN feed loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

Definition at line 385 of file main.c.

References g_bkup_heartbeat, g_bkup_rw_ok, internal_bkup_demo_panic_halt(), internal_bkup_demo_report_survival(), internal_bkup_demo_rw_check(), internal_bkup_demo_setup_or_halt(), internal_bkup_demo_survival_check(), k_bkup_demo_period_ms, k_ra8_board_led1, k_ra8_board_led2, k_ra8_ok, ra8_board_led_toggle(), ra8_board_uart_console_write(), ra8_delay_ms(), ra8_isr_globals_enable(), s_bkup_demo_bad_msg, s_bkup_demo_crlf, and s_bkup_demo_ok_msg.

Variable Documentation

◆ g_bkup_boot_count

volatile uint32_t g_bkup_boot_count = 0U

Boot counter held in backup word 31 (increments per reset on HW).

Note: Read externally only.

Since: 0.1.0

Definition at line 151 of file main.c.

Referenced by internal_bkup_demo_survival_check().

◆ g_bkup_heartbeat

volatile uint32_t g_bkup_heartbeat = 0U

Bumps once per main-loop pass – liveness for headless probes.

Note: Read externally only.

Since: 0.1.0

Definition at line 159 of file main.c.

Referenced by main().

◆ g_bkup_rw_ok

volatile uint32_t g_bkup_rw_ok = 0U

1 when words 0..29 read back exactly what was written.

Note: Read externally only (HIL / board emulator).

Since: 0.1.0

Definition at line 135 of file main.c.

Referenced by main().

◆ g_bkup_survived

volatile uint32_t g_bkup_survived = 0U

1 when the sentinel was found at boot (state retained across reset).

Note: Read externally only.

Since: 0.1.0

Definition at line 143 of file main.c.

Referenced by internal_bkup_demo_report_survival(), and internal_bkup_demo_survival_check().

◆ s_bkup_demo_bad_msg

const uint8_t s_bkup_demo_bad_msg[] = "bkup: rw=BAD "

static

Prefix for a failed backup-word read/write report.

Identifies either an accessor error or a pattern mismatch.

Note: Followed by the reset-survival suffix.

Since: 0.1.0

Definition at line 103 of file main.c.

Referenced by main().

◆ s_bkup_demo_crlf

const uint8_t s_bkup_demo_crlf[] = "\r\n"

static

Console line terminator for each periodic report.

Uses CRLF to match the board UART diagnostic convention.

Note: The terminating null byte is excluded from writes.

Since: 0.1.0

Definition at line 127 of file main.c.

Referenced by main().

◆ s_bkup_demo_ok_msg

const uint8_t s_bkup_demo_ok_msg[] = "bkup: rw=ok "

static

Prefix for a successful backup-word read/write report.

Begins the periodic console line when all 30 pattern words match.

Note: Followed by the reset-survival suffix.

Since: 0.1.0

Definition at line 95 of file main.c.

Referenced by main().

◆ s_bkup_demo_surv_n

const uint8_t s_bkup_demo_surv_n[] = "survived=N "

static

Cold-start survival suffix.

Reports that startup had to plant a new retained sentinel.

Note: Kept the same byte length as the affirmative suffix.

Since: 0.1.0

Definition at line 119 of file main.c.

Referenced by internal_bkup_demo_report_survival().

◆ s_bkup_demo_surv_y

const uint8_t s_bkup_demo_surv_y[] = "survived=Y "

static

Warm-reset survival suffix.

Reports that the retained sentinel was present at startup.

Note: Kept the same byte length as the negative suffix.

Since: 0.1.0

Definition at line 111 of file main.c.

Referenced by internal_bkup_demo_report_survival().

◆ s_tag

const char* s_tag = "bkup_demo"

static

Diagnostic / log tag.

Definition at line 70 of file main.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ bkup_demo_config_t

◆ bkup_demo_layout_t

Function Documentation

◆ internal_bkup_demo_panic_halt()

◆ internal_bkup_demo_pattern()

◆ internal_bkup_demo_report_survival()

◆ internal_bkup_demo_rw_check()

◆ internal_bkup_demo_setup_or_halt()

◆ internal_bkup_demo_survival_check()

◆ main()

Variable Documentation

◆ g_bkup_boot_count

◆ g_bkup_heartbeat

◆ g_bkup_rw_ok

◆ g_bkup_survived

◆ s_bkup_demo_bad_msg

◆ s_bkup_demo_crlf

◆ s_bkup_demo_ok_msg

◆ s_bkup_demo_surv_n

◆ s_bkup_demo_surv_y

◆ s_tag