PMGR Interface

Detailed Description

Interface for accessing Middleware power modes.

Summary

This section defines the API for the PMGR (Power Manager) Module. The PMGR Module provides smart power engine which controlled by application state and requirement.

Note

The PMGR is automated by default, but can also be configured for manual.

Data Structures
struct	pmgr_cfg_t
struct	pmgr_api_t
struct	pmgr_instance_t

Typedefs
typedef void	pmgr_ctrl_t

Enumerations
enum	pmgr_event_t
enum	pmgr_constraints_t

---

Data Structure Documentation

pmgr_cfg_t

struct pmgr_cfg_t

User configuration structure, used in open function

Data Fields
void const *	p_extend	Placeholder for extension.

pmgr_api_t

struct pmgr_api_t

PMGR driver structure. General PMGR functions implemented at the HAL layer will follow this API.

Data Fields
fsp_err_t(*	open )(pmgr_ctrl_t *const p_ctrl, pmgr_cfg_t const *const p_cfg)
fsp_err_t(*	close )(pmgr_ctrl_t *const p_ctrl)
fsp_err_t(*	notifier_register )(pmgr_ctrl_t *const p_ctrl, void(*p_callback)(pmgr_callback_args_t *), pmgr_callback_args_t *const p_callback_memory, void const *p_extend)
fsp_err_t(*	enter_idle )(pmgr_ctrl_t *const p_ctrl, uint64_t idle_time_us)
fsp_err_t(*	add_sleep_constraint )(pmgr_ctrl_t *const p_ctrl, pmgr_constraints_t constraint)
fsp_err_t(*	remove_sleep_constraint )(pmgr_ctrl_t *const p_ctrl, pmgr_constraints_t constraint)

Field Documentation

open

fsp_err_t(* pmgr_api_t::open) (pmgr_ctrl_t *const p_ctrl, pmgr_cfg_t const *const p_cfg)

Open the PMGR driver module. Add constraint for RAM

Parameters

[in]	p_ctrl	Pointer to PMGR device handle.
[in]	p_cfg	Pointer to a configuration structure.

close

fsp_err_t(* pmgr_api_t::close) (pmgr_ctrl_t *const p_ctrl)

Close the PMGR driver module.

Parameters

[in]

p_ctrl

Pointer to PMGR device handle

Return values

FSP_SUCCESS

Configuration was successful.

notifier_register

fsp_err_t(* pmgr_api_t::notifier_register) (pmgr_ctrl_t *const p_ctrl, void(*p_callback)(pmgr_callback_args_t *), pmgr_callback_args_t *const p_callback_memory, void const *p_extend)

Add a callback notifier function and optional context pointer and working memory pointer. The common implementation defines synchronous approach, where on return from notifier call back the system is ready from power save mode. The callback function will be executed with the RTOS scheduler suspended and inside critical section (PRIMASK=1) Keep the callback short, do not call RTOS blocking functions, no calls to stdio, and do not clear PRIMASK.

Parameters

[in]	p_ctrl	Pointer to the PMGR control block.
[in]	p_callback	Callback function
[in]	p_callback_memory	Pointer to memory of type pmgr_callback_args_t which will be passed to callback function.
[in,out]	p_extend	Implementation specific parameter

enter_idle

fsp_err_t(* pmgr_api_t::enter_idle) (pmgr_ctrl_t *const p_ctrl, uint64_t idle_time_us)

Update expected system idle time. The expected idle time will be the expected sleep duration (unless unexpected interrupt occurs) note for the following 2 usecase for this API:

• called by the OS, when it reaches the idle task,
• called by customized application to force sleep immediately (including tasks delayed wake , timer events etc ...)

Parameters

[in]	p_ctrl	Pointer to the PMGR control block.
[in]	idle_time_us	Expected system Idle time in usec.

add_sleep_constraint

fsp_err_t(* pmgr_api_t::add_sleep_constraint) (pmgr_ctrl_t *const p_ctrl, pmgr_constraints_t constraint)

Add sleep constraint, sleep constraints are used by system middleware or customised application to prohibit specific sleep implication the sleep constraints is a bit map representing functionality, each functionality (in the bitmap) is represented by counter in the implementation each time the add_sleep_constraint() with a bit set, the corresponding counter is increased, the functionality is allowed only if counter is zero.

Parameters

[in]	p_ctrl	Pointer to the PMGR control block.
[in]	constraint	Defines a bit map of single constraint.

remove_sleep_constraint

fsp_err_t(* pmgr_api_t::remove_sleep_constraint) (pmgr_ctrl_t *const p_ctrl, pmgr_constraints_t constraint)

Remove sleep constraint , see add_sleep_constraint details

Parameters

[in]	p_ctrl	Pointer to the PMGR control block.
[in]	constraint	Defines a bit map of single constraint.

pmgr_instance_t

struct pmgr_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
pmgr_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
pmgr_cfg_t const *const	p_cfg	Pointer to the configuration structure for this instance.
pmgr_api_t const *const	p_api	Pointer to the API structure for this instance.

Typedef Documentation

pmgr_ctrl_t

typedef void pmgr_ctrl_t

PMGR control block. Allocate an instance specific control block to pass into the PMGR API calls.

Enumeration Type Documentation

pmgr_event_t

enum pmgr_event_t

Enumerator
PMGR_EVENT_ENTERING_SLEEP	event of sleep mode is not set yet
PMGR_EVENT_EXITING_SLEEP	entering sleep mode

pmgr_constraints_t

enum pmgr_constraints_t

sleep constraints

Enumerator
PMGR_CONSTRAINT_NONE	All available sleep modes are allowed.
PMGR_CONSTRAINT_SLEEP_PROHIBITED	Any sleep mode is not allowed.
PMGR_CONSTRAINT_POWER_MAC_HW	MAC HW must be powered on.
PMGR_CONSTRAINT_POWER_RAM	RAM must be powered on.
PMGR_CONSTRAINT_POWER_RETENTION	Retention must powered on.
PMGR_CONSTRAINT_MAX_BIT	Constraint last bit.