HAL Power Management Interface

Hardware Abstraction Layer interface for power management. More...

Macros
#define	OVE_PM_NO_TIMEOUT   UINT32_MAX
	Sentinel value for "no scheduled wake-up" in PM ms timeouts.

Functions
int	ove_hal_pm_enter_state (ove_pm_state_t state, uint32_t expected_idle_ms)
	Enter a hardware sleep state.
int	ove_hal_pm_wake_arm (const struct ove_pm_wake_src *src)
	Arm a wake source in hardware before entering sleep.
int	ove_hal_pm_wake_disarm (const struct ove_pm_wake_src *src)
	Disarm a wake source after waking.
int	ove_hal_pm_domain_enable (ove_pm_domain_t domain)
	Enable power to a peripheral domain.
int	ove_hal_pm_domain_disable (ove_pm_domain_t domain)
	Disable power to a peripheral domain (power-gate).
uint32_t	ove_hal_pm_get_next_timeout_ms (void)
	Query the time until the next scheduled RTOS event.
void	ove_hal_pm_idle_hook (void)
	Idle hook entry point — registered with the RTOS idle mechanism.
int	ove_hal_pm_setup (void)
	Initialise backend-side PM machinery.
void	ove_hal_pm_teardown (void)
	Tear down backend-side PM machinery.

Detailed Description

Hardware Abstraction Layer interface for power management.

Declares the low-level PM functions that every platform HAL must implement. The portable Power Management layer delegates to these functions after performing state machine logic, refcounting, and statistics tracking.

Note

Platform implementations supply their own definitions of these functions in a backend-specific source file.

Macro Definition Documentation

OVE_PM_NO_TIMEOUT

#define OVE_PM_NO_TIMEOUT   UINT32_MAX

Sentinel value for "no scheduled wake-up" in PM ms timeouts.

PM uses uint32_t milliseconds by design (see ove_pm_register_*). Distinct from the substrate's ns-based OVE_WAIT_FOREVER sentinel.

Function Documentation

ove_hal_pm_enter_state()

int ove_hal_pm_enter_state	(	ove_pm_state_t	state,
		uint32_t	expected_idle_ms
	)

Enter a hardware sleep state.

Called by the portable PM layer after arming wake sources and firing PRE_SLEEP notifications. The function blocks until the system wakes.

Parameters

[in]	state	Target sleep state.
[in]	expected_idle_ms	Hint: expected sleep duration in ms.

Returns

OVE_OK on success, negative error code on failure.

ove_hal_pm_wake_arm()

int ove_hal_pm_wake_arm

(

const struct ove_pm_wake_src *

src

)

Arm a wake source in hardware before entering sleep.

Called for each registered wake source before ove_hal_pm_enter_state().

Parameters

[in]

src

Wake source descriptor.

Returns

OVE_OK on success, negative error code on failure.

ove_hal_pm_wake_disarm()

int ove_hal_pm_wake_disarm

(

const struct ove_pm_wake_src *

src

)

Disarm a wake source after waking.

Parameters

[in]

src

Wake source descriptor.

Returns

OVE_OK on success, negative error code on failure.

ove_hal_pm_domain_enable()

int ove_hal_pm_domain_enable

(

ove_pm_domain_t

domain

)

Enable power to a peripheral domain.

Called when a domain's reference count transitions from 0 to 1.

Parameters

[in]

domain

Domain identifier.

Returns

OVE_OK on success, negative error code on failure.

ove_hal_pm_domain_disable()

int ove_hal_pm_domain_disable

(

ove_pm_domain_t

domain

)

Disable power to a peripheral domain (power-gate).

Called when a domain's reference count transitions from 1 to 0.

Parameters

[in]

domain

Domain identifier.

Returns

OVE_OK on success, negative error code on failure.

ove_hal_pm_get_next_timeout_ms()

uint32_t ove_hal_pm_get_next_timeout_ms

(

void

)

Query the time until the next scheduled RTOS event.

Returns

Milliseconds until next timeout, or OVE_PM_NO_TIMEOUT if none.

ove_hal_pm_idle_hook()

void ove_hal_pm_idle_hook

(

void

)

Idle hook entry point — registered with the RTOS idle mechanism.

The backend registers this function with the RTOS idle task (e.g. vApplicationIdleHook on FreeRTOS, pm_notifier on Zephyr). It calls ove_pm_idle_process() in the portable layer to drive the PM state machine.

ove_hal_pm_setup()

int ove_hal_pm_setup

(

void

)

Initialise backend-side PM machinery.

Called by ove_pm_init() once the portable state has been set up. Backends that drive ove_pm_idle_process() from a kernel idle hook (e.g. FreeRTOS vApplicationIdleHook) can leave this as a no-op; backends without an auto-fired idle hook (NuttX, Zephyr, POSIX) use it to spawn a low-priority polling thread.

Returns

OVE_OK on success, negative error code on failure.

ove_hal_pm_teardown()

void ove_hal_pm_teardown

(

void

)

Tear down backend-side PM machinery.

Called by ove_pm_deinit(). Backends that spawned a polling thread should signal it to exit and join here.