Policy

System Power Management Policy API . More...

Data Structures
struct	pm_policy_latency_subscription
	Latency change subscription. More...
struct	pm_policy_latency_request
	Latency request. More...
struct	pm_policy_event
	Event. More...

Macros
#define	PM_ALL_SUBSTATES   (UINT8_MAX)
	Special value for 'all substates'.

Typedefs
typedef void(*	pm_policy_latency_changed_cb_t) (int32_t latency)
	Callback to notify when maximum latency changes.

Functions
void	pm_policy_state_lock_get (enum pm_state state, uint8_t substate_id)
	Increase a power state lock counter.
void	pm_policy_state_lock_put (enum pm_state state, uint8_t substate_id)
	Decrease a power state lock counter.
bool	pm_policy_state_lock_is_active (enum pm_state state, uint8_t substate_id)
	Check if a power state lock is active (not allowed).
void	pm_policy_event_register (struct pm_policy_event *evt, int64_t uptime_ticks)
	Register an event.
void	pm_policy_event_update (struct pm_policy_event *evt, int64_t uptime_ticks)
	Update an event.
void	pm_policy_event_unregister (struct pm_policy_event *evt)
	Unregister an event.
void	pm_policy_device_power_lock_get (const struct device *dev)
	Increase power state locks.
void	pm_policy_device_power_lock_put (const struct device *dev)
	Decrease power state locks.
int64_t	pm_policy_next_event_ticks (void)
	Returns the ticks until the next event.
void	pm_policy_latency_request_add (struct pm_policy_latency_request *req, uint32_t value_us)
	Add a new latency requirement.
void	pm_policy_latency_request_update (struct pm_policy_latency_request *req, uint32_t value_us)
	Update a latency requirement.
void	pm_policy_latency_request_remove (struct pm_policy_latency_request *req)
	Remove a latency requirement.
void	pm_policy_latency_changed_subscribe (struct pm_policy_latency_subscription *req, pm_policy_latency_changed_cb_t cb)
	Subscribe to maximum latency changes.
void	pm_policy_latency_changed_unsubscribe (struct pm_policy_latency_subscription *req)
	Unsubscribe to maximum latency changes.

Detailed Description

System Power Management Policy API .

Macro Definition Documentation

PM_ALL_SUBSTATES

#define PM_ALL_SUBSTATES   (UINT8_MAX)

#include <zephyr/pm/policy.h>

Special value for 'all substates'.

Typedef Documentation

pm_policy_latency_changed_cb_t

typedef void(* pm_policy_latency_changed_cb_t) (int32_t latency)

#include <zephyr/pm/policy.h>

Callback to notify when maximum latency changes.

Parameters

latency

New maximum latency. Positive value represents latency in microseconds. SYS_FOREVER_US value lifts the latency constraint. Other values are forbidden.

Function Documentation

pm_policy_device_power_lock_get()

void pm_policy_device_power_lock_get

(

const struct device *

dev

)

#include <zephyr/pm/policy.h>

Increase power state locks.

Set power state locks in all power states that disable power in the given device.

Parameters

dev	Device reference.

See also

pm_policy_device_power_lock_put()

pm_policy_state_lock_get()

pm_policy_device_power_lock_put()

void pm_policy_device_power_lock_put

(

const struct device *

dev

)

#include <zephyr/pm/policy.h>

Decrease power state locks.

Remove power state locks in all power states that disable power in the given device.

Parameters

dev	Device reference.

See also

pm_policy_device_power_lock_get()

pm_policy_state_lock_put()

pm_policy_event_register()

void pm_policy_event_register	(	struct pm_policy_event *	evt,
		int64_t	uptime_ticks )

#include <zephyr/pm/policy.h>

Register an event.

Events in the power-management policy context are defined as any source that will wake up the system at a known time in the future. By registering such event, the policy manager will be able to decide whether certain power states are worth entering or not.

CPU is woken up before the time passed in cycle to minimize event handling latency. Once woken up, the CPU will be kept awake until the event has been handled, which is signaled by pm_policy_event_unregister() or moving event into the future using pm_policy_event_update().

Parameters

evt	Event.
uptime_ticks	When the event will occur, in uptime ticks.

See also

pm_policy_event_unregister()

pm_policy_event_unregister()

void pm_policy_event_unregister

(

struct pm_policy_event *

evt

)

#include <zephyr/pm/policy.h>

Unregister an event.

Parameters

evt

Event.

See also

pm_policy_event_register

pm_policy_event_update()

void pm_policy_event_update	(	struct pm_policy_event *	evt,
		int64_t	uptime_ticks )

#include <zephyr/pm/policy.h>

Update an event.

This shortcut allows for moving the time an event will occur without the need for an unregister + register cycle.

Parameters

evt	Event.
uptime_ticks	When the event will occur, in uptime ticks.

See also

pm_policy_event_register

pm_policy_latency_changed_subscribe()

void pm_policy_latency_changed_subscribe	(	struct pm_policy_latency_subscription *	req,
		pm_policy_latency_changed_cb_t	cb )

#include <zephyr/pm/policy.h>

Subscribe to maximum latency changes.

Parameters

req	Subscription request.
cb	Callback function (NULL to disable).

pm_policy_latency_changed_unsubscribe()

void pm_policy_latency_changed_unsubscribe

(

struct pm_policy_latency_subscription *

req

)

#include <zephyr/pm/policy.h>

Unsubscribe to maximum latency changes.

Parameters

req	Subscription request.

pm_policy_latency_request_add()

void pm_policy_latency_request_add	(	struct pm_policy_latency_request *	req,
		uint32_t	value_us )

#include <zephyr/pm/policy.h>

Add a new latency requirement.

The system will not enter any power state that would make the system to exceed the given latency value.

Parameters

req	Latency request.
value_us	Maximum allowed latency in microseconds.

pm_policy_latency_request_remove()

void pm_policy_latency_request_remove

(

struct pm_policy_latency_request *

req

)

#include <zephyr/pm/policy.h>

Remove a latency requirement.

Parameters

req	Latency request.

pm_policy_latency_request_update()

void pm_policy_latency_request_update	(	struct pm_policy_latency_request *	req,
		uint32_t	value_us )

#include <zephyr/pm/policy.h>

Update a latency requirement.

Parameters

req	Latency request.
value_us	New maximum allowed latency in microseconds.

pm_policy_next_event_ticks()

int64_t pm_policy_next_event_ticks

(

void

)

#include <zephyr/pm/policy.h>

Returns the ticks until the next event.

If an event is registred, it will return the number of ticks until the next event, if the "next"/"oldest" registered event is in the past, it will return 0. Otherwise it returns -1.

Return values

>0	If next registered event is in the future
0	If next registered event is now or in the past
-1	Otherwise

pm_policy_state_lock_get()

void pm_policy_state_lock_get	(	enum pm_state	state,
		uint8_t	substate_id )

#include <zephyr/pm/policy.h>

Increase a power state lock counter.

A power state will not be allowed on the first call of pm_policy_state_lock_get(). Subsequent calls will just increase a reference count, thus meaning this API can be safely used concurrently. A state will be allowed again after pm_policy_state_lock_put() is called as many times as pm_policy_state_lock_get().

Note that the PM_STATE_ACTIVE state is always allowed, so calling this API with PM_STATE_ACTIVE will have no effect.

Parameters

state	Power state.
substate_id	Power substate ID. Use PM_ALL_SUBSTATES to affect all the substates in the given power state.

See also

pm_policy_state_lock_put()

pm_policy_state_lock_is_active()

bool pm_policy_state_lock_is_active	(	enum pm_state	state,
		uint8_t	substate_id )

#include <zephyr/pm/policy.h>

Check if a power state lock is active (not allowed).

Parameters

state	Power state.
substate_id	Power substate ID. Use PM_ALL_SUBSTATES to affect all the substates in the given power state.

Return values

true	if power state lock is active.
false	if power state lock is not active.

pm_policy_state_lock_put()

void pm_policy_state_lock_put	(	enum pm_state	state,
		uint8_t	substate_id )

#include <zephyr/pm/policy.h>

Decrease a power state lock counter.

Parameters

state	Power state.
substate_id	Power substate ID. Use PM_ALL_SUBSTATES to affect all the substates in the given power state.

See also

pm_policy_state_lock_get()