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, uint32_t cycle)
	Register an event.
void	pm_policy_event_update (struct pm_policy_event *evt, uint32_t cycle)
	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.
int32_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 <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 <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 <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 <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,
		uint32_t	cycle
	)

#include <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 prevent the event handling latency

Note

It is mandatory to unregister events once they have happened by using pm_policy_event_unregister(). Not doing so is an API contract violation, because the system would continue to consider them as valid events in the far future, that is, after the cycle counter rollover.

Parameters

evt	Event.
cycle	When the event will occur, in absolute time (cycles).

See also

pm_policy_event_unregister

pm_policy_event_unregister()

void pm_policy_event_unregister

(

struct pm_policy_event *

evt

)

#include <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,
		uint32_t	cycle
	)

#include <include/zephyr/pm/policy.h>

Update an event.

Parameters

evt	Event.
cycle	When the event will occur, in absolute time (cycles).

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 <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 <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 <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 <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 <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()

int32_t pm_policy_next_event_ticks

(

void

)

#include <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 as a positive or zero value. Otherwise it returns -1

pm_policy_state_lock_get()

void pm_policy_state_lock_get	(	enum pm_state	state,
		uint8_t	substate_id
	)

#include <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 <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 <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()