Exercise the WUPEN0 / WUPEN1 wake-source enable matrix. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_err.h"
#include "ra8_isr.h"
#include "ra8_lpm.h"
#include "ra8_lpm_regs.h"
#include "ra8_time.h"

Include dependency graph for main.c:

Enumerations
enum	lpm_wupen_mask_t : uint32_t { k_lpm_wupen_all_mask = 0xFFFFFFFFUL }
	Wake-up enable register masks. More...
enum	lpm_wake_const_t : uint32_t { k_lpm_wake_baud = 115200U }

Functions
static void	internal_lpm_wake_panic_halt (void)
	Park the processor after a fatal setup or wake-matrix failure.
static void	internal_lpm_wake_setup_or_halt (void)
	Bring CGC + SysTick + SCI8 + LED1 + LPM block up.
static ra8_err_t	internal_lpm_wake_arm0 (uint32_t bits)
	Arm a WUPEN0 source mask and update the in-RAM snapshot.
static ra8_err_t	internal_lpm_wake_arm1 (uint32_t bits)
	Arm a WUPEN1 source mask and update the in-RAM snapshot.
static ra8_err_t	internal_lpm_wake_walk_wupen0 (void)
	Walk the WUPEN0 internal-peripheral wake sources.
static ra8_err_t	internal_lpm_wake_walk_wupen1 (void)
	Walk the WUPEN1 internal-peripheral wake sources.
static ra8_err_t	internal_lpm_wake_disarm_all (void)
	Disarm every WUPEN bit the demo set and confirm zero.
void	main (void)
	The application entry point Reset_Handler hands control to.

Variables
static const uint8_t	s_lpm_wake_boot_msg [] = "lpm_wake_matrix: boot\r\n"
	Boot banner – HIL gate string.
static const uint8_t	s_lpm_wake_done_msg [] = "lpm_wake_matrix: done\r\n"
	Per-step completion banner emitted after each arm/disarm.
volatile uint64_t	g_lpm_wake_matrix_armed = 0U
	Snapshot of which WUPEN sources the demo has armed so far.

Detailed Description

Exercise the WUPEN0 / WUPEN1 wake-source enable matrix.

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

Walks every wake-source bit the LPM HAL exposes through ra8_lpm_arm_wupen0_bits / ra8_lpm_arm_wupen1_bits and verifies the matrix is reachable from the application layer. The demo does NOT attempt to enter Software Standby / Deep Standby because most of these sources need additional peripheral wiring (USB device attached, IRQ pin driven, ULPT armed, etc) that the bare EK-RA8D2 cannot synthesise without external hardware.

Instead, the demo:

Brings the standard CGC + SysTick + SCI8 + LPM up.
Emits boot banner "lpm_wake_matrix: boot\r\n" – HIL gate.
Walks the WUPEN0 internal-peripheral bits (those that can be armed without external HW): IWDT / PVD1 / PVD2 / VBATT / RTC alarm / RTC periodic. Each arm + readback updates g_lpm_wake_matrix_armed so the operator can see progress via SWD.
Walks the WUPEN1 internal sources: COMPHS0 / SOSC / ULPT0U / ULPT0A / ULPT0B / I3C0.
Disarms everything via ra8_lpm_clear_wupen0_bits / ra8_lpm_clear_wupen1_bits and confirms the matrix reads back as zero.
Emits "lpm_wake_matrix: done\r\n" and parks LED1 on.

The demo proves that the HAL helpers actually mutate the WUPEN registers as expected – equivalent to the host unit test in tests/mocks/src/test_app_lpm_wake_matrix_demo.c but running on real silicon so the chip's read-as-written semantics are exercised.

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ lpm_wake_const_t

enum lpm_wake_const_t : uint32_t

Enumerator
k_lpm_wake_baud	Lpm wake baud.

Definition at line 60 of file main.c.

◆ lpm_wupen_mask_t

enum lpm_wupen_mask_t : uint32_t

Wake-up enable register masks.

Enumerator
k_lpm_wupen_all_mask	Clear all WUPEN bits.

Definition at line 56 of file main.c.

Function Documentation

◆ internal_lpm_wake_arm0()

ra8_err_t internal_lpm_wake_arm0 ( uint32_t bits )

staticnodiscard

Arm a WUPEN0 source mask and update the in-RAM snapshot.

Applies the requested low-bank mask, then samples the combined exit cause into the externally visible progression snapshot.

Parameters

[in] bits k_ra8_lpm_wupen0_* mask to OR into WUPEN0.

Returns: Error code from ra8_lpm_arm_wupen0_bits.

Return values

k_ra8_ok The mask was armed and the resulting snapshot was captured.

Precondition: LPM block initialised; PRC1 unlocked.; bits is a documented WUPEN0 mask (not arbitrary).

Postcondition: On success g_lpm_wake_matrix_armed low 32 bits reflect the new arm state.; On failure, the prior externally visible snapshot remains unchanged.

Note: The snapshot spans both WUPEN banks even though only bank zero changes.

Since: 0.1.0

Definition at line 169 of file main.c.

References g_lpm_wake_matrix_armed, k_ra8_ok, RA8_INTERNAL, ra8_lpm_arm_wupen0_bits(), and ra8_lpm_get_exit_cause().

Referenced by internal_lpm_wake_walk_wupen0().

◆ internal_lpm_wake_arm1()

ra8_err_t internal_lpm_wake_arm1 ( uint32_t bits )

staticnodiscard

Arm a WUPEN1 source mask and update the in-RAM snapshot.

Applies the requested high-bank mask, then samples the combined exit cause into the externally visible progression snapshot.

Parameters

[in] bits k_ra8_lpm_wupen1_* mask to OR into WUPEN1.

Returns: Error code from ra8_lpm_arm_wupen1_bits.

Return values

k_ra8_ok The mask was armed and the resulting snapshot was captured.

Precondition: LPM block initialised; PRC1 unlocked.; bits is a documented WUPEN1 mask.

Postcondition: On success g_lpm_wake_matrix_armed high 32 bits reflect the new arm state.; On failure, the prior externally visible snapshot remains unchanged.

Note: The snapshot spans both WUPEN banks even though only bank one changes.

Since: 0.1.0

Definition at line 204 of file main.c.

References g_lpm_wake_matrix_armed, k_ra8_ok, RA8_INTERNAL, ra8_lpm_arm_wupen1_bits(), and ra8_lpm_get_exit_cause().

Referenced by internal_lpm_wake_walk_wupen1().

◆ internal_lpm_wake_disarm_all()

ra8_err_t internal_lpm_wake_disarm_all ( void )

staticnodiscard

Disarm every WUPEN bit the demo set and confirm zero.

Clears both complete WUPEN banks in order and refreshes the combined externally visible snapshot only after both clears succeed.

MC/DC:: Compound decision: clear_wupen0 != ok || clear_wupen1 != ok. Two atomic conditions x N+1 = 3 vectors covered in the host test.

Returns: Error code from the first failing primitive.

Return values

k_ra8_ok Both banks were cleared and the zero snapshot was captured.

Precondition: Walk-phase complete.; LPM register protection permits WUPEN updates.

Postcondition: WUPEN0 == 0 and WUPEN1 == 0.; g_lpm_wake_matrix_armed == 0.

Note: A failed clear leaves the hardware and snapshot available for diagnosis.

Since: 0.1.0

Definition at line 340 of file main.c.

References g_lpm_wake_matrix_armed, k_lpm_wupen_all_mask, k_ra8_ok, RA8_INTERNAL, ra8_lpm_clear_wupen0_bits(), ra8_lpm_clear_wupen1_bits(), and ra8_lpm_get_exit_cause().

Referenced by main().

◆ internal_lpm_wake_panic_halt()

void internal_lpm_wake_panic_halt ( void )

static

Park the processor after a fatal setup or wake-matrix failure.

Executes wait-for-interrupt indefinitely so a partial matrix walk cannot be mistaken for a completed diagnostic.

Precondition: The caller has determined that the demo cannot continue safely.; No foreground recovery operation remains capable of restoring state.

Postcondition: This function does not return.; The processor remains in a low-activity wait loop.

Note: The terminal loop preserves the last matrix state for SWD inspection.

Since: 0.1.0

Definition at line 96 of file main.c.

References RA8_INTERNAL.

Referenced by internal_lpm_wake_setup_or_halt(), and main().

◆ internal_lpm_wake_setup_or_halt()

void internal_lpm_wake_setup_or_halt ( void )

static

Bring CGC + SysTick + SCI8 + LED1 + LPM block up.

Initializes clocks, timing, the HIL console, LED1, and LPM configuration in dependency order, halting at the first required failure.

Precondition: IRQs disabled.; Reset_Handler has copied .data and zeroed .bss.

Postcondition: All five sub-systems are armed on success.; LPM block has LPSCR.LPMD = 0 (System Active).

Note: The helper applies a fail-closed startup policy before the matrix walk.

Since: 0.1.0

Definition at line 118 of file main.c.

References internal_lpm_wake_panic_halt(), k_lpm_wake_baud, k_ra8_board_led1, k_ra8_clock_id_cpuclk0, k_ra8_lpm_dcssmode_128us, k_ra8_lpm_ss2lp_default, k_ra8_ok, ra8_board_led_init(), ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, ra8_lpm_init(), and ra8_time_init().

Referenced by main().

◆ internal_lpm_wake_walk_wupen0()

ra8_err_t internal_lpm_wake_walk_wupen0 ( void )

staticnodiscard

Walk the WUPEN0 internal-peripheral wake sources.

Arms each supported low-bank source in a fixed diagnostic order and stops immediately if any individual update or snapshot read fails.

MC/DC:: Compound decision: arm0(iwdt) != ok || arm0(pvd1) != ok || ... Six atomic conditions x N+1 = 7 vectors. Steady-state all-ok runs on bench; each error branch is covered in tests/mocks/src/test_app_lpm_wake_matrix_demo.c.

Returns: Error code from the first failing arm call.

Return values

k_ra8_ok All six WUPEN0 source bits were armed successfully.

Precondition: LPM block initialised and PRC1 unlocked.; The low-bank matrix begins in the state expected by the diagnostic.

Postcondition: On success WUPEN0 has IWDT / PVD1 / PVD2 / VBATT / RTCALM / RTCPRD set; all other WUPEN0 bits left untouched.; On failure, no source after the failing step is attempted.

Note: Each step refreshes g_lpm_wake_matrix_armed for SWD observation.

Since: 0.1.0

Definition at line 243 of file main.c.

References internal_lpm_wake_arm0(), k_ra8_lpm_wupen0_iwdt, k_ra8_lpm_wupen0_pvd1, k_ra8_lpm_wupen0_pvd2, k_ra8_lpm_wupen0_rtcalm, k_ra8_lpm_wupen0_rtcprd, k_ra8_lpm_wupen0_vbatt, k_ra8_ok, and RA8_INTERNAL.

Referenced by main().

◆ internal_lpm_wake_walk_wupen1()

ra8_err_t internal_lpm_wake_walk_wupen1 ( void )

staticnodiscard

Walk the WUPEN1 internal-peripheral wake sources.

Arms each supported high-bank source in a fixed diagnostic order and stops immediately if any individual update or snapshot read fails.

MC/DC:: Compound decision: arm1(comphs0) != ok || arm1(sosc) != ok || arm1(ulpt0u) != ok || arm1(ulpt0a) != ok || arm1(ulpt0b) != ok || arm1(i3c0) != ok. Six atomic conditions x N+1 = 7 vectors covered in tests/mocks/src/test_app_lpm_wake_matrix_demo.c.

Returns: Error code from the first failing arm call.

Return values

k_ra8_ok All six WUPEN1 source bits were armed successfully.

Precondition: LPM block initialised and PRC1 unlocked.; The high-bank matrix begins in the state expected by the diagnostic.

Postcondition: On success WUPEN1 has COMPHS0 / SOSC / ULPT0U / ULPT0A / ULPT0B / I3C0 set; all other WUPEN1 bits left untouched.; On failure, no source after the failing step is attempted.

Note: Each step refreshes g_lpm_wake_matrix_armed for SWD observation.

Since: 0.1.0

Definition at line 293 of file main.c.

References internal_lpm_wake_arm1(), k_ra8_lpm_wupen1_comphs0, k_ra8_lpm_wupen1_i3c0, k_ra8_lpm_wupen1_sosc, k_ra8_lpm_wupen1_ulpt0a, k_ra8_lpm_wupen1_ulpt0b, k_ra8_lpm_wupen1_ulpt0u, k_ra8_ok, 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

The application entry point Reset_Handler hands control to.

Precondition: SystemInit set VTOR / FPU / priority grouping.

The application entry point Reset_Handler hands control to.

See file header.

Precondition: Boot init has completed.; The secure-boot library's BLXNS into NS image either failed or was skipped (the call site in ra8_trustzone_init is a no-op on host builds).

Postcondition: Diagnostic counter latched, CPU parked in a halt loop.; Function never returns.

Note: Single-threaded entry.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

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

Postcondition: On success g_eoh_chapters / g_eoh_crc hold the parsed results, the banner is emitted, and g_eoh_heartbeat advances once per frame.; On any failure g_eoh_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

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

Postcondition: The chapters/ch0-CRC banner is emitted; the CPU then loops in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

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

Postcondition: On success the g_etoc_* result globals hold the parsed TOC values, the banner is emitted, and g_etoc_heartbeat advances once per frame.; On any failure g_etoc_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss; SystemInit set VTOR/FPU.

Postcondition: The shelf scans on the panel; taps open books, browse, and read.

Since: 0.1.0

Definition at line 358 of file main.c.

References internal_lpm_wake_disarm_all(), internal_lpm_wake_panic_halt(), internal_lpm_wake_setup_or_halt(), internal_lpm_wake_walk_wupen0(), internal_lpm_wake_walk_wupen1(), k_ra8_board_led1, k_ra8_ok, ra8_board_led_on(), ra8_board_uart_console_write(), ra8_isr_globals_enable(), s_lpm_wake_boot_msg, and s_lpm_wake_done_msg.

Variable Documentation

◆ g_lpm_wake_matrix_armed

volatile uint64_t g_lpm_wake_matrix_armed = 0U

Snapshot of which WUPEN sources the demo has armed so far.

Updated after each successful ra8_lpm_arm_wupen0_bits / ra8_lpm_arm_wupen1_bits call. Exposed for SWD inspection so an operator can confirm matrix progression without a UART.

Since: 0.1.0

Definition at line 81 of file main.c.

Referenced by internal_lpm_wake_arm0(), internal_lpm_wake_arm1(), and internal_lpm_wake_disarm_all().

◆ s_lpm_wake_boot_msg

const uint8_t s_lpm_wake_boot_msg[] = "lpm_wake_matrix: boot\r\n"

static

Boot banner – HIL gate string.

Definition at line 65 of file main.c.

Referenced by main().

◆ s_lpm_wake_done_msg

const uint8_t s_lpm_wake_done_msg[] = "lpm_wake_matrix: done\r\n"

static

Per-step completion banner emitted after each arm/disarm.

Definition at line 68 of file main.c.

Referenced by main().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ lpm_wake_const_t

◆ lpm_wupen_mask_t

Function Documentation

◆ internal_lpm_wake_arm0()

◆ internal_lpm_wake_arm1()

◆ internal_lpm_wake_disarm_all()

◆ internal_lpm_wake_panic_halt()

◆ internal_lpm_wake_setup_or_halt()

◆ internal_lpm_wake_walk_wupen0()

◆ internal_lpm_wake_walk_wupen1()

◆ main()

Variable Documentation

◆ g_lpm_wake_matrix_armed

◆ s_lpm_wake_boot_msg

◆ s_lpm_wake_done_msg