Unified power management with sleep state machine, peripheral power domains, wake source registration, and runtime statistics. More...

Collaboration diagram for Power Management:

Data Structures
struct	ove_pm_cfg
	PM subsystem configuration. More...

struct	ove_pm_wake_src
	Wake source descriptor. More...

struct	ove_pm_stats
	Runtime power statistics. More...

Typedefs
typedef ove_pm_state_t(*	ove_pm_policy_fn) (ove_pm_state_t current, uint32_t idle_ms, uint32_t next_timeout_ms, void *user_data)
	Power policy callback — returns recommended next state.

typedef void(*	ove_pm_notify_fn) (ove_pm_event_t event, ove_pm_state_t from_state, ove_pm_state_t to_state, void *user_data)
	Transition notification callback.

Enumerations
enum	ove_pm_state_t { OVE_PM_STATE_ACTIVE = 0 , OVE_PM_STATE_IDLE = 1 , OVE_PM_STATE_STANDBY = 2 , OVE_PM_STATE_DEEP_SLEEP = 3 , OVE_PM_STATE_COUNT = 4 }
	System power states, ordered by increasing sleep depth. More...

enum	ove_pm_wake_type_t { OVE_PM_WAKE_GPIO = 0 , OVE_PM_WAKE_TIMER = 1 , OVE_PM_WAKE_UART = 2 , OVE_PM_WAKE_RTC = 3 }
	Wake source types. More...

enum	ove_pm_domain_t { OVE_PM_DOMAIN_RADIO = 0 , OVE_PM_DOMAIN_SENSOR = 1 , OVE_PM_DOMAIN_DISPLAY = 2 , OVE_PM_DOMAIN_AUDIO = 3 , OVE_PM_DOMAIN_STORAGE = 4 , OVE_PM_DOMAIN_COMMS = 5 , OVE_PM_DOMAIN_USER0 = 6 , OVE_PM_DOMAIN_USER1 = 7 , OVE_PM_DOMAIN_COUNT = 8 }
	Peripheral power domain identifiers.

enum	ove_pm_event_t { OVE_PM_EVENT_PRE_SLEEP = 0 , OVE_PM_EVENT_POST_WAKE = 1 }
	Transition event type for notification callbacks. More...

Functions
int	ove_pm_init (const struct ove_pm_cfg *cfg)
	Initialise the PM subsystem.

void	ove_pm_deinit (void)
	Tear down the PM subsystem and release resources.

int	ove_pm_set_state (ove_pm_state_t state)
	Request an explicit transition to `state`.

ove_pm_state_t	ove_pm_get_state (void)
	Query the current power state.

void	ove_pm_activity (void)
	Report system activity (resets idle timer).

int	ove_pm_wake_register (const struct ove_pm_wake_src *src)
	Register a wake source.

int	ove_pm_wake_unregister (const struct ove_pm_wake_src *src)
	Unregister a previously registered wake source.

int	ove_pm_domain_request (ove_pm_domain_t domain)
	Increment the reference count for a peripheral power domain.

int	ove_pm_domain_release (ove_pm_domain_t domain)
	Decrement the reference count for a peripheral power domain.

int	ove_pm_domain_get_refcount (ove_pm_domain_t domain)
	Query the current reference count for a domain.

int	ove_pm_set_policy (ove_pm_policy_fn policy, void *user_data)
	Register a custom power policy callback.

int	ove_pm_notify_register (ove_pm_notify_fn cb, void *user_data)
	Register a transition notification callback.

int	ove_pm_notify_unregister (ove_pm_notify_fn cb, void *user_data)
	Unregister a transition notification callback.

int	ove_pm_get_stats (struct ove_pm_stats *stats)
	Query accumulated power statistics.

void	ove_pm_reset_stats (void)
	Reset all accumulated power statistics to zero.

int	ove_pm_set_budget (uint32_t target_low_power_pct_x100)
	Set a target percentage of time in low-power states.

int	ove_pm_get_budget_status (uint32_t *actual_pct_x100)
	Query actual low-power percentage vs. budget target.

void	ove_pm_idle_process (void)
	Process idle — called from RTOS idle context by the HAL.

Detailed Description

Unified power management with sleep state machine, peripheral power domains, wake source registration, and runtime statistics.

The PM subsystem is a singleton module (like GPIO and console) — there is exactly one system power state. Initialise with ove_pm_init() and tear down with ove_pm_deinit().

Four sleep states are defined, ordered by increasing depth:

OVE_PM_STATE_ACTIVE — full speed, all clocks running.
OVE_PM_STATE_IDLE — light sleep, fast wakeup, peripherals on.
OVE_PM_STATE_STANDBY — deeper sleep, some peripherals off.
OVE_PM_STATE_DEEP_SLEEP — lowest power, RAM retained, slow wakeup.

A pluggable policy engine decides when to transition between states based on idle duration, next scheduled timeout, and registered wake sources. Peripheral power domains are reference-counted: power is gated when the last user releases a domain.

Note: Requires CONFIG_OVE_PM.

Typedef Documentation

◆ ove_pm_policy_fn

typedef ove_pm_state_t(* ove_pm_policy_fn) (ove_pm_state_t current, uint32_t idle_ms, uint32_t next_timeout_ms, void *user_data)

Power policy callback — returns recommended next state.

Parameters

[in]	current	Current power state.
[in]	idle_ms	Milliseconds since last activity.
[in]	next_timeout_ms	Milliseconds until next scheduled event.
[in]	user_data	Opaque pointer from ove_pm_set_policy().

Returns: Recommended next power state.

◆ ove_pm_notify_fn

typedef void(* ove_pm_notify_fn) (ove_pm_event_t event, ove_pm_state_t from_state, ove_pm_state_t to_state, void *user_data)

Transition notification callback.

Parameters

[in]	event	PRE_SLEEP or POST_WAKE.
[in]	from_state	State being left.
[in]	to_state	State being entered.
[in]	user_data	Opaque pointer from ove_pm_notify_register().

Enumeration Type Documentation

◆ ove_pm_state_t

enum ove_pm_state_t

System power states, ordered by increasing sleep depth.

Enumerator
OVE_PM_STATE_ACTIVE	Full speed.
OVE_PM_STATE_IDLE	Light sleep, fast wakeup.
OVE_PM_STATE_STANDBY	Deep idle, some peripherals off.
OVE_PM_STATE_DEEP_SLEEP	Lowest power, RAM retained.

◆ ove_pm_wake_type_t

enum ove_pm_wake_type_t

Wake source types.

Enumerator
OVE_PM_WAKE_GPIO	GPIO pin edge.
OVE_PM_WAKE_TIMER	Timer expiry.
OVE_PM_WAKE_UART	UART RX activity.
OVE_PM_WAKE_RTC	RTC alarm.

◆ ove_pm_event_t

enum ove_pm_event_t

Transition event type for notification callbacks.

Enumerator
OVE_PM_EVENT_PRE_SLEEP	About to enter low-power state.
OVE_PM_EVENT_POST_WAKE	Just woke from low-power state.

Function Documentation

◆ ove_pm_init()

int ove_pm_init ( const struct ove_pm_cfg * cfg )

Initialise the PM subsystem.

Parameters

[in] cfg Configuration parameters. Must not be NULL.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_pm_set_state()

int ove_pm_set_state ( ove_pm_state_t state )

Request an explicit transition to state.

Parameters

[in] state Target power state.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_pm_get_state()

ove_pm_state_t ove_pm_get_state ( void )

Query the current power state.

Lock-free, ISR-safe — performs a single volatile read of an aligned word, which is atomic on every supported target. The returned value may be stale if a state transition is in flight on another context, but it can never tear. Callers that need a snapshot synchronised with a specific transition should serialise around their own primitive.

Returns: Current power state.

◆ ove_pm_activity()

void ove_pm_activity ( void )

Report system activity (resets idle timer).

This function is ISR-safe — it performs only a volatile write.

◆ ove_pm_wake_register()

int ove_pm_wake_register ( const struct ove_pm_wake_src * src )

Register a wake source.

Parameters

[in] src Wake source descriptor.

Returns: OVE_OK on success, OVE_ERR_NO_MEMORY if table full.

◆ ove_pm_wake_unregister()

int ove_pm_wake_unregister ( const struct ove_pm_wake_src * src )

Unregister a previously registered wake source.

Parameters

[in] src Wake source descriptor (must match a registered entry).

Returns: OVE_OK on success, OVE_ERR_NOT_REGISTERED if not found.

◆ ove_pm_domain_request()

int ove_pm_domain_request ( ove_pm_domain_t domain )

Increment the reference count for a peripheral power domain.

On the first request (0→1), the domain hardware is powered on.

Parameters

[in] domain Domain identifier.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_pm_domain_release()

int ove_pm_domain_release ( ove_pm_domain_t domain )

Decrement the reference count for a peripheral power domain.

When the count reaches zero, the domain hardware is powered off.

Parameters

[in] domain Domain identifier.

Returns: OVE_OK on success, OVE_ERR_INVALID_PARAM on underflow.

◆ ove_pm_domain_get_refcount()

int ove_pm_domain_get_refcount ( ove_pm_domain_t domain )

Query the current reference count for a domain.

Parameters

[in] domain Domain identifier.

Returns: Reference count (>= 0), or negative error code.

◆ ove_pm_set_policy()

int ove_pm_set_policy	(	ove_pm_policy_fn	policy,
		void *	user_data
	)

Register a custom power policy callback.

Replaces the default threshold-based policy. Pass NULL to restore the default policy.

Parameters

[in]	policy	Policy function, or NULL for default.
[in]	user_data	Opaque pointer forwarded to `policy`.

Returns: OVE_OK.

◆ ove_pm_notify_register()

int ove_pm_notify_register	(	ove_pm_notify_fn	cb,
		void *	user_data
	)

Register a transition notification callback.

Parameters

[in]	cb	Callback invoked on PRE_SLEEP and POST_WAKE.
[in]	user_data	Opaque pointer forwarded to `cb`.

Returns: OVE_OK on success, OVE_ERR_NO_MEMORY if table full.

◆ ove_pm_notify_unregister()

int ove_pm_notify_unregister	(	ove_pm_notify_fn	cb,
		void *	user_data
	)

Unregister a transition notification callback.

Parameters

[in]	cb	Previously registered callback.
[in]	user_data	Pointer that was passed at registration time.

Returns: OVE_OK on success, OVE_ERR_NOT_REGISTERED if not found.

◆ ove_pm_get_stats()

int ove_pm_get_stats ( struct ove_pm_stats * stats )

Query accumulated power statistics.

Parameters

[out] stats Receives current statistics snapshot.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_pm_set_budget()

int ove_pm_set_budget ( uint32_t target_low_power_pct_x100 )

Set a target percentage of time in low-power states.

Parameters

[in] target_low_power_pct_x100 Target in hundredths of percent.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_pm_get_budget_status()

int ove_pm_get_budget_status ( uint32_t * actual_pct_x100 )

Query actual low-power percentage vs. budget target.

Parameters

[out] actual_pct_x100 Actual low-power % in hundredths.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_pm_idle_process()

void ove_pm_idle_process ( void )

Process idle — called from RTOS idle context by the HAL.

This drives the state machine: checks activity, invokes policy, arms wake sources, transitions state, fires notifications. Not intended to be called by application code.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ove_pm_policy_fn

◆ ove_pm_notify_fn

Enumeration Type Documentation

◆ ove_pm_state_t

◆ ove_pm_wake_type_t

◆ ove_pm_event_t

Function Documentation

◆ ove_pm_init()

◆ ove_pm_set_state()

◆ ove_pm_get_state()

◆ ove_pm_activity()

◆ ove_pm_wake_register()

◆ ove_pm_wake_unregister()

◆ ove_pm_domain_request()

◆ ove_pm_domain_release()

◆ ove_pm_domain_get_refcount()

◆ ove_pm_set_policy()

◆ ove_pm_notify_register()

◆ ove_pm_notify_unregister()

◆ ove_pm_get_stats()

◆ ove_pm_set_budget()

◆ ove_pm_get_budget_status()

◆ ove_pm_idle_process()