Low Power Mode + clock-domain wrapper. More...

#include <stdint.h>
#include "ra8_cgc.h"
#include "ra8_err.h"
#include "ra8_mstp_regs.h"

Include dependency graph for ra8_pwr.h:

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

Enumerations
enum	ra8_pwr_wupen_reg_t : uint8_t { k_ra8_pwr_wupen_reg_0 = 0U , k_ra8_pwr_wupen_reg_1 = 1U }
	Which of the two WUPEN registers a wake source lives in. More...
enum	ra8_pwr_wake_t : uint16_t { k_ra8_pwr_wake_irq0 = (uint16_t)(k_ra8_pwr_wupen_reg_0 << 8) , k_ra8_pwr_wake_irq1 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 1U) , k_ra8_pwr_wake_irq2 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 2U) , k_ra8_pwr_wake_irq3 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 3U) , k_ra8_pwr_wake_irq4 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 4U) , k_ra8_pwr_wake_irq5 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 5U) , k_ra8_pwr_wake_irq6 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 6U) , k_ra8_pwr_wake_irq7 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 7U) , k_ra8_pwr_wake_iwdt = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 16U) , k_ra8_pwr_wake_lvd1 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 18U) , k_ra8_pwr_wake_lvd2 = (uint16_t)((k_ra8_pwr_wupen_reg_0 << 8) \| 19U) , k_ra8_pwr_wake_rtc_alarm , k_ra8_pwr_wake_rtc_period , k_ra8_pwr_wake_usbhs_resume , k_ra8_pwr_wake_usbfs_resume , k_ra8_pwr_wake_agt0 = (uint16_t)(k_ra8_pwr_wupen_reg_1 << 8) , k_ra8_pwr_wake_agt1 = (uint16_t)((k_ra8_pwr_wupen_reg_1 << 8) \| 1U) , k_ra8_pwr_wake_ulpt0 = (uint16_t)((k_ra8_pwr_wupen_reg_1 << 8) \| 2U) , k_ra8_pwr_wake_ulpt1 = (uint16_t)((k_ra8_pwr_wupen_reg_1 << 8) \| 3U) }
	Packed (WUPEN register, bit) wake-source identifier. More...

Functions
ra8_err_t	ra8_pwr_init (void)
	Initialise the LPM substrate.
ra8_err_t	ra8_pwr_module_request (ra8_mstp_t id)
	Ask for a peripheral's clock to be enabled.
ra8_err_t	ra8_pwr_module_release (ra8_mstp_t id)
	Release a previously-requested peripheral.
ra8_err_t	ra8_pwr_set_wake_source (ra8_pwr_wake_t source)
	Enable an LPM wake source.
ra8_err_t	ra8_pwr_clear_wake_source (ra8_pwr_wake_t source)
	Disable an LPM wake source.
ra8_err_t	ra8_pwr_wake_source_is_enabled (ra8_pwr_wake_t source, bool *out_enabled)
	Read the current WUPEN bit value for a source.
void	ra8_pwr_enter_sleep (void)
	Enter CPU sleep mode (peripherals continue running).
ra8_err_t	ra8_pwr_enter_software_standby (void)
	Enter Software Standby mode.
ra8_err_t	ra8_pwr_get_clock_hz (ra8_clock_id_t id, uint32_t *out_hz)
	Forward to ra8_cgc_get_clock_hz() for naming consistency.

Detailed Description

Low Power Mode + clock-domain wrapper.

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

Ring 3 / HAL substrate. Sits on top of ra8_mstp and ra8_cgc and exposes the small set of helpers every driver checklist needs:

ra8_pwr_init() – bring-up validation
ra8_pwr_module_request(id) – ref-counted ungate
ra8_pwr_module_release(id) – ref-counted gate
ra8_pwr_set_wake_source / clear – WUPEN0/1 management
ra8_pwr_enter_sleep() – WFI for CPU sleep
ra8_pwr_enter_software_standby() – WFI for SSTBY
ra8_pwr_get_clock_hz() – forwards to ra8_cgc

The 14-checkbox per-driver feature template (see docs/ROADMAP.md) lists "Power transition" as "ra8_pwr_module_enter_stop + restore, wake event register". The naming in this file is the canonical version: request / release for ungate / gate so that "stop" only ever means "STBY-style stopped" rather than "MSTP bit set".

Wake-up sources

The RA8D2 has 64 distinct wake-up sources spread across two 32-bit WUPEN registers (HUM 11.2.x). Sources include the IRQ pins, AGT/ULPT timers, RTC alarm, USB suspend/resume, LVD detectors, and the temperature monitor. ra8_pwr_set_wake_source() takes a packed identifier (register index + bit) and toggles the corresponding bit.

Threading

Single-threaded init context only.

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

Definition in file ra8_pwr.h.

Enumeration Type Documentation

◆ ra8_pwr_wake_t

enum ra8_pwr_wake_t : uint16_t

Packed (WUPEN register, bit) wake-source identifier.

Encoding mirrors ra8_mstp_t: (reg << 8) | bit. Only a handful of well-known sources are listed here; full coverage of all 64 sources is added as the relevant drivers come online.

Source list comes from HUM Ch 14 "Interrupt Controller Unit (ICU)" (the WUPEN0 and WUPEN1 register description tables).

Enumerator
k_ra8_pwr_wake_irq0	RA8 pwr wake irq0.
k_ra8_pwr_wake_irq1	RA8 pwr wake irq1.
k_ra8_pwr_wake_irq2	RA8 pwr wake irq2.
k_ra8_pwr_wake_irq3	RA8 pwr wake irq3.
k_ra8_pwr_wake_irq4	RA8 pwr wake irq4.
k_ra8_pwr_wake_irq5	RA8 pwr wake irq5.
k_ra8_pwr_wake_irq6	RA8 pwr wake irq6.
k_ra8_pwr_wake_irq7	RA8 pwr wake irq7.
k_ra8_pwr_wake_iwdt	RA8 pwr wake iwdt.
k_ra8_pwr_wake_lvd1	RA8 pwr wake lvd1.
k_ra8_pwr_wake_lvd2	RA8 pwr wake lvd2.
k_ra8_pwr_wake_rtc_alarm	RA8 pwr wake rtc alarm.
k_ra8_pwr_wake_rtc_period	RA8 pwr wake rtc period.
k_ra8_pwr_wake_usbhs_resume	RA8 pwr wake usbhs resume.
k_ra8_pwr_wake_usbfs_resume	RA8 pwr wake usbfs resume.
k_ra8_pwr_wake_agt0	RA8 pwr wake agt0.
k_ra8_pwr_wake_agt1	RA8 pwr wake agt1.
k_ra8_pwr_wake_ulpt0	RA8 pwr wake ulpt0.
k_ra8_pwr_wake_ulpt1	RA8 pwr wake ulpt1.

Definition at line 83 of file ra8_pwr.h.

◆ ra8_pwr_wupen_reg_t

enum ra8_pwr_wupen_reg_t : uint8_t

Which of the two WUPEN registers a wake source lives in.

Enumerator
k_ra8_pwr_wupen_reg_0	WUPEN0 (sources 0..31).
k_ra8_pwr_wupen_reg_1	WUPEN1 (sources 32..63).

Definition at line 66 of file ra8_pwr.h.

Function Documentation

◆ ra8_pwr_clear_wake_source()

ra8_err_t ra8_pwr_clear_wake_source ( ra8_pwr_wake_t source )

nodiscard

Disable an LPM wake source.

Clears the corresponding bit in WUPEN0 or WUPEN1.

Parameters

[in] source Packed ra8_pwr_wake_t identifier.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The bit is clear.
k_ra8_err_invalid_arg	source decodes to an out-of-range register or bit.

Precondition: IRQs masked or single-threaded init context.; ra8_pwr_init() has been called.

Postcondition: The relevant WUPEN bit is clear.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 183 of file ra8_pwr.c.

References internal_decode_wake(), internal_wupen_ptr(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_log_error_val, and s_tag.

◆ ra8_pwr_enter_sleep()

void ra8_pwr_enter_sleep ( void )

Enter CPU sleep mode (peripherals continue running).

Issues a single WFI instruction. The Cortex-M85 enters Sleep mode and the CPU clock is gated until any enabled interrupt fires. Peripherals run normally because LPMD bits are not touched.

On the host (RA8_OFF_TARGET) this is a no-op so unit tests do not stall.

Precondition: IRQs are masked at the level the caller wants to wake on.; At least one enabled interrupt source exists, otherwise the CPU never wakes.

Postcondition: On wake, the function returns to the caller. Caller is responsible for draining whatever woke them.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Postcondition: Caller-visible state matches the documented contract.

Definition at line 212 of file ra8_pwr.c.

References internal_wfi().

◆ ra8_pwr_enter_software_standby()

ra8_err_t ra8_pwr_enter_software_standby ( void )

nodiscard

Enter Software Standby mode.

Sets LPSCR.LPMD = 0x5 and the Cortex-M85 SCR.SLEEPDEEP bit, then issues WFI (HUM 11.6.2.1 p 482). Most oscillators stop, the CPU stops, peripherals freeze. Wakes from any source armed via ra8_pwr_set_wake_source().

On the host this is a no-op.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Returned cleanly after wake.
k_ra8_err_invalid_state	Caller failed to arm any wake source first.

Precondition: At least one wake source is armed in WUPEN0/1.; IRQs are configured per HUM 11.6.2.1 (the wake interrupt must have its IELSRn entry programmed).

Postcondition: On wake, the function returns to the caller.; LPMD has been written back to 0 (normal mode).

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 217 of file ra8_pwr.c.

References internal_wfi(), internal_wupen_ptr(), k_ra8_err_invalid_state, k_ra8_ok, ra8_log_error, and s_tag.

◆ ra8_pwr_get_clock_hz()

ra8_err_t ra8_pwr_get_clock_hz	(	ra8_clock_id_t	id,
		uint32_t *	out_hz )

nodiscard

Forward to ra8_cgc_get_clock_hz() for naming consistency.

Plain forwarding helper. Drivers that already include ra8_pwr.h for module gating do not need to also include ra8_cgc.h just to look up a baud-rate divider.

Parameters

[in]	id	Clock identifier.
[out]	out_hz	On success, current frequency in Hz.

Returns: Result of the underlying ra8_cgc_get_clock_hz().

Precondition: out_hz is non-NULL.; id is a value from ra8_clock_id_t.

Postcondition: On success, *out_hz holds the live frequency.; No hardware state is modified.

Note: Thread safety: not thread-safe.

See also: ra8_cgc_get_clock_hz

Since: 0.1.0

Definition at line 240 of file ra8_pwr.c.

References ra8_cgc_get_clock_hz().

◆ ra8_pwr_init()

ra8_err_t ra8_pwr_init ( void )

nodiscard

Initialise the LPM substrate.

Validates the post-reset state and clears every WUPEN bit so that subsequent ra8_pwr_set_wake_source() calls are the only source of wake events. Also calls ra8_mstp_init() so the MSTP ref-count table starts in lockstep with hardware.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Substrate ready.
k_ra8_err_hw_timeout	ra8_mstp_init() did not see its read-back within budget.

Precondition: Caller is in single-threaded init context.; Cold reset has just occurred (warm-reset entry is OK too – the function tolerates either).

Postcondition: WUPEN0 == 0 and WUPEN1 == 0.; ra8_mstp ref-count table is all zero.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 141 of file ra8_pwr.c.

References internal_wupen_ptr(), k_ra8_ok, ra8_log_error_val, ra8_log_info, ra8_mstp_init(), and s_tag.

Referenced by ra8_nsc_periph_init().

◆ ra8_pwr_module_release()

ra8_err_t ra8_pwr_module_release ( ra8_mstp_t id )

nodiscard

Release a previously-requested peripheral.

Forwards to ra8_mstp_disable(id).

Parameters

[in] id Peripheral identifier from ra8_mstp_t.

Returns: Result of the underlying ra8_mstp_disable().

Precondition: IRQs masked or single-threaded init context.; Caller previously called ra8_pwr_module_request(id).

Postcondition: On the last release, the peripheral is gated.; Ref count for id is decremented by 1.

Note: Thread safety: not thread-safe.

See also: ra8_mstp_disable

Since: 0.1.0

Definition at line 163 of file ra8_pwr.c.

References ra8_mstp_disable().

◆ ra8_pwr_module_request()

ra8_err_t ra8_pwr_module_request ( ra8_mstp_t id )

nodiscard

Ask for a peripheral's clock to be enabled.

Forwards to ra8_mstp_enable(id) after logging. Future versions will validate the requested module against the current LPM state and route the request through an NSC veneer.

Parameters

[in] id Peripheral identifier from ra8_mstp_t.

Returns: Result of the underlying ra8_mstp_enable().

Precondition: IRQs masked or single-threaded init context.; ra8_pwr_init() has been called.

Postcondition: On success, the peripheral is clocked.; Ref count for id is at least 1.

Note: Thread safety: not thread-safe.

See also: ra8_mstp_enable

Since: 0.1.0

Definition at line 158 of file ra8_pwr.c.

References ra8_mstp_enable().

◆ ra8_pwr_set_wake_source()

ra8_err_t ra8_pwr_set_wake_source ( ra8_pwr_wake_t source )

nodiscard

Enable an LPM wake source.

Sets the corresponding bit in WUPEN0 or WUPEN1 (HUM 11.2.x register descriptions). Wake sources are addressed by the packed ra8_pwr_wake_t enum.

Parameters

[in] source Packed ra8_pwr_wake_t identifier.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The bit is set.
k_ra8_err_invalid_arg	source decodes to an out-of-range register or bit.

Precondition: IRQs masked or single-threaded init context.; ra8_pwr_init() has been called.

Postcondition: The relevant WUPEN bit is set.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 168 of file ra8_pwr.c.

References internal_decode_wake(), internal_wupen_ptr(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_log_error_val, and s_tag.

◆ ra8_pwr_wake_source_is_enabled()

ra8_err_t ra8_pwr_wake_source_is_enabled	(	ra8_pwr_wake_t	source,
		bool *	out_enabled )

nodiscard

Read the current WUPEN bit value for a source.

Diagnostic accessor used by tests. Returns true if the source is currently armed.

Parameters

[in]	source	Packed ra8_pwr_wake_t identifier.
[out]	out_enabled	true on success if the bit is set.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bit value returned.
k_ra8_err_null_ptr	out_enabled was NULL.
k_ra8_err_invalid_arg	source decoded out of range.

Precondition: out_enabled is non-NULL.; source is a value from ra8_pwr_wake_t.

Postcondition: No hardware state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 198 of file ra8_pwr.c.

References internal_decode_wake(), internal_wupen_ptr(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Enumerations

Functions

Detailed Description

Wake-up sources

Threading

Enumeration Type Documentation

◆ ra8_pwr_wake_t

◆ ra8_pwr_wupen_reg_t

Function Documentation

◆ ra8_pwr_clear_wake_source()

◆ ra8_pwr_enter_sleep()

◆ ra8_pwr_enter_software_standby()

◆ ra8_pwr_get_clock_hz()

◆ ra8_pwr_init()

◆ ra8_pwr_module_release()

◆ ra8_pwr_module_request()

◆ ra8_pwr_set_wake_source()

◆ ra8_pwr_wake_source_is_enabled()