enum Power_Constraint |
![](../../../../../Arrow_up.png) |
Constraints that can be registered with Power
typedef enum Power_Constraint {
Power_SB_VIMS_CACHE_RETAIN,
// disallow loss of cache context during Power_STANDBY (i.e., retain the cache)
Power_SD_DISALLOW,
// disallow transition to SHUTDOWN
Power_SB_DISALLOW,
// disallow transition to Power_STANDBY
Power_IDLE_PD_DISALLOW,
// disallow power down of the CPU domain during idle time (IDLE_PD)
Power_NEED_FLASH_IN_IDLE,
// need to keep Flash powered in IDLE_PD
Power_NUMCONSTRAINTS
} Power_Constraint;
enum Power_Event |
![](../../../../../Arrow_up.png) |
Power Event enumerations
typedef enum Power_Event {
Power_ENTERING_STANDBY,
// device is transitioning into Power_STANDBY
Power_ENTERING_SHUTDOWN,
// device is transitioning into SHUTDOWN
Power_AWAKE_STANDBY,
// device has awoken from Power_STANDBY, I/O latches are still frozen
Power_AWAKE_STANDBY_LATE,
// device has awoken from Power_STANDBY, I/O latches are open again
Power_XOSC_HF_SWITCHED,
// the high frequency (HF) crystal oscillator has stabilized, and is now the HF clock source
Power_NUMEVENTS
} Power_Event;
enum Power_LatencyType |
![](../../../../../Arrow_up.png) |
Type of transition latency to query
typedef enum Power_LatencyType {
Power_TOTAL,
// the total latency, to enter the sleep state, and to wake and resume
Power_RESUME
// the latency to wake the device and resume execution
} Power_LatencyType;
enum Power_NotifyResponse |
![](../../../../../Arrow_up.png) |
Return values from a notify function
typedef enum Power_NotifyResponse {
Power_NOTIFYDONE,
// success, done processing the notification
Power_NOTIFYERROR
// an error occurred while processing the notification
} Power_NotifyResponse;
enum Power_SleepState |
![](../../../../../Arrow_up.png) |
Sleep states
typedef enum Power_SleepState {
Power_STANDBY
// STANDBY state
} Power_SleepState;
enum Power_Status |
![](../../../../../Arrow_up.png) |
Function return codes
typedef enum Power_Status {
Power_SOK,
// success
Power_SOK_STATE_RESTORED,
// success, context has been restored
Power_EFAIL,
// error, the operation failed
Power_EINVALIDPOINTER,
// error, an invalid pointer was specified
Power_ECHANGE_NOT_ALLOWED,
// error, the requested change is not allowed
Power_ETIMEOUT,
// error, a timeout occurred
Power_EBUSY
// error, the operation is not allowed; another transition is not completed yet
} Power_Status;
enum Power_TransitionState |
![](../../../../../Arrow_up.png) |
Sleep transition states
typedef enum Power_TransitionState {
Power_ACTIVE,
// device is active; no transition in progress
Power_ENTERING_SLEEP,
// device is entering into a sleep state
Power_EXITING_SLEEP,
// device is exiting a sleep state
Power_SHUTDOWN
// device is transitioning to the SHUTDOWN state
} Power_TransitionState;
config Power_A_tooManyCallsReleaseConstraint // module-wide |
![](../../../../../Arrow_up.png) |
Assert when Power_releaseConstraint is called too many times
extern const Assert_Id Power_A_tooManyCallsReleaseConstraint;
config Power_A_tooManyCallsReleaseDependency // module-wide |
![](../../../../../Arrow_up.png) |
Assert when Power_releaseDependency is called too many times
extern const Assert_Id Power_A_tooManyCallsReleaseDependency;
config Power_idle // module-wide |
![](../../../../../Arrow_up.png) |
Idle the CPU during idle time?
extern const Bool Power_idle;
DETAILS
When this configuration parameter is set to true, the Power module will
insert a power policy function into the list of
Idle loop functions.
When the policy function executes, it will take action to save power
until the next CPU interrupt occurs. The default power policy will
simply invoke a wait for interrupt (WFI) instruction.
SEE
Power_doWFI() // module-wide |
![](../../../../../Arrow_up.png) |
A power policy function that invokes wait-for-interrupt (WFI)
during idle time
DETAILS
This is the most basic power policy function, which will invoke
WFI upon entry to the Idle loop. This is the default policy function
that is invoked when CPU idling is enabled with the
idle
configuration parameter:
Power_getClockHandle() // module-wide |
![](../../../../../Arrow_up.png) |
Get the handle of the Clock object created for scheduling wakeups
Power_getConstraintInfo() // module-wide |
![](../../../../../Arrow_up.png) |
Get a bitmask representing the aggregate of constraints that have been
declared
UInt32 Power_getConstraintInfo();
RETURNS
A bitmask representing all currently declared
constraints
DETAILS
This function returns a bitmask indicating the constraints that are
currently declared to the Power module (via previous calls to
Power_setConstraint()). For each constraint
(of type
Power_Constraint) that is currently
declared, the corresponding bit in the bitmask will be set. For
example, if two clients have declared Power_SB_DISALLOW, and one has
declared Power_SB_VIMS_CACHE_RETAIN, then the returned bitmask
will have the value: Power_SB_DISALLOW | Power_SB_VIMS_CACHE_RETAIN
Power_getDependencyCount() // module-wide |
![](../../../../../Arrow_up.png) |
Get the count of dependencies that are currently declared upon a
resource
UInt32 Power_getDependencyCount(UInt8 resourceID);
ARGUMENTS
resourceID
The resource identifier, as specified in the
device-specific header file
RETURNS
The number of dependencies currently declared upon this
resourceID
DETAILS
This function returns the number of dependencies that are currently
declared upon a resource.
Power_getTicksUntilWakeup() // module-wide |
![](../../../../../Arrow_up.png) |
Get the number of system ticks until the next scheduled wakeup event
UInt32 Power_getTicksUntilWakeup();
RETURNS
The number of system ticks (i.e.,
Clock module) ticks
until the next scheduled wakeup
Power_getTransitionLatency() // module-wide |
![](../../../../../Arrow_up.png) |
Get the minimal transition latency for a sleep state, in units of
system Clock ticks
ARGUMENTS
sleepState
The sleepState whose transition
latency is to be reported (e.g., Power_STANDBY)
type
The type of latency to be
reported
RETURNS
The transition latency, in units of
Clock ticks.
DETAILS
Note that the reported latency is the device transition latency for
the specified sleep state. This latency value does not include any
additional software induced latency, for example, that due to
notifications of the power transition to drivers.
Power_getTransitionState() // module-wide |
![](../../../../../Arrow_up.png) |
Get the current Power module transition state
RETURNS
The current transition state, of type
Power_TransitionState
Power_getXoscStartupTime() // module-wide |
![](../../../../../Arrow_up.png) |
Get the estimated crystal oscillator startup time, in units of
microseconds
UInt32 Power_getXoscStartupTime(UInt32 timeUntilWakeupInMs);
ARGUMENTS
timeUntilWakeupInMs
The estimated time until the next wakeup
event, in units of milliseconds
RETURNS
The estimated crystal oscillator startup latency, in
units of microseconds.
NOTE
The estimated time until wakeup is in units of milliseconds,
but the the estimate crystal startup time is in microseconds.
Power_registerNotify() // module-wide |
![](../../../../../Arrow_up.png) |
Register a function to be called upon a specific power event
ARGUMENTS
pNotifyObj
The notify object to be used for queuing
of the notification callback function
eventTypes
The type or types of Power_Event to
be notified of
notifyFxn
The callback function Power should call to notify
the client of the event
clientArg
A client-defined argument to pass with the notifyFxn
call
arg
For future use, should be specified as:
NULL
RETURNS
Power_SOK if the registration succeeded
Power_EINVALIDPOINTER if either pNotifyObj or notifyFxn
were NULL
DETAILS
This function registers a function to be called when a
Power event occurs. Registrations and the corresponding notifications
are processed in first-in-first-out (FIFO) order. The function
registered must behave as described below.
The pNotifyObj parameter is a pointer to a pre-allocated, opaque
object that will be used by Power to support the notification. This
object could be dynamically allocated, or declared as a global object.
Power_registerNotify() will properly initialized the object's fields as
appropriate; the caller just needs to provide a pointer to this
pre-existing object.
The eventType parameter identifies the type of power event for which
the notify function being registered is to be called. This parameter
is treated as a bitmask, so multiple event types can be registered for
a common function. The event types are enumerated as
Power_Event. For example, to call the specified function when
both the entering standby and the awake from standby events occur,
eventType should be specified as:
(Power_ENTERING_STANDBY | Power_AWAKE_STANDBY)
The clientArg parameter is an arbitrary argument to be passed to the
client upon notification. This argument may allow one notify function
to be used by multiple instances of a driver (that is, the clientArg
can be used to identify the instance of the driver that is being
notified).
The notifyFxn parameter specifies the function to call when the
specified Power event occurs. The notifyFxn must implement
the following signature:
status = notifyFxn(eventType, clientArg);
Where: eventType (type of
Power_Event) is the event
being signalled, and clientArg is the abitrary argument specified
by the client at registration. Note that multipe types of events
can be specified when registering the notification callback function,
but when the callback function is actually called by Power, only a
single eventType will be specified for the callback (i.e., the current
event).
The client notification function being registered must return one of the
following constants as a status value, of type
Power_NotifyResponse: Power_NOTIFYDONE if the client processed the
notification function successfully, or Power_NOTIFYERROR if the
notification cannot be processed (e.g., if an internal client error
occurs).
Power_releaseConstraint() // module-wide |
![](../../../../../Arrow_up.png) |
Release a constraint that was previously declared with Power_setConstraint()
ARGUMENTS
DETAILS
This function releases a constraint that was previously declared with
Power_setConstraint(). For example, if a device
driver is starting a transaction and wants to prohibit activation of
the Power_STANDBY sleep mode, it uses
Power_setConstraint to declare the constraint, before starting
the transaction. When the transaction completes, the driver calls
this function to release the constraint, and allow the power manager
to once again transition into the Power_STANDBY sleep mode, if
appropriate.
CONSTRAINTS
Power_releaseConstraint() must not be called more than
Power_setConstraint() has been called for the same constraint. If
asserts are enabled, one will be generated in this case.
Power_releaseDependency() // module-wide |
![](../../../../../Arrow_up.png) |
Release a dependency that had been previously declared with Power_setDependency()
Void Power_releaseDependency(UInt8 resourceID);
ARGUMENTS
resourceID
The resource identifier, as specified in the
device-specific header file
DETAILS
This function is the companion to
Power_setDependency(). If this release is for the last outstanding
dependency upon the resource, the resource will be de-activated as part
of this function call.
CONSTRAINTS
Power_releaseDependency() must not be called more than
Power_setDependency() has been called for the same resource. If
asserts are enabled, one will be generated in this case.
Power_setConstraint() // module-wide |
![](../../../../../Arrow_up.png) |
Declare an operational constraint
ARGUMENTS
DETAILS
Before taking certain actions, Power checks to see if the requested
action would conflict with a client-declared constraint. If the
action does conflict, Power will not proceed with the request.
This is the function that allows clients to declare their constraints
with Power.
It is critical that clients call
Power_releaseConstraint() when operational constraints no longer
exists. Otherwise, Power may be left unnecessarily restricted from
activating power savings.
Power_setDependency() // module-wide |
![](../../../../../Arrow_up.png) |
Declare a dependency upon a power-manageable resource
Bool Power_setDependency(UInt8 resourceID);
ARGUMENTS
resourceID
The resource identifier, as specified in the
device-specific header file (for example,
PERIPH_UART0, as defined in PowerCC2650.h)
RETURNS
TRUE if resource is active
FALSE if resource was not yet active when the function
return was initiated
DETAILS
This function declares a dependency upon a resource. If the resource
had been inactive, it will be activated during this function call.
This function is the companion to
Power_releaseDependency().
NOTE
When a dependency is declared upon a resource for the first time, the
resource will be activated before the call to Power_setDependency()
returns to the caller. There is only one exception to this rule:
the XOSC_HF resource for CC26xx. The latency to startup the crystal
is much longer than that for other resources. To avoid blocking in
Power_setDependency() for this duration, for the XOSC_HF resource
only, Power_setDependency() will return quickly, after initiating the
activation of XOSC_HF. Once the switchover to the XOSC_HF
happens, notifications will be sent to clients registered for the
Power_XOSC_HF_SWITCHED event.
Power_setDependency() will return a Boolean status to indicate if
the resource is active as the function is initiating a return to the
caller. For all resources other than XOSC_HF, the return status will
always be TRUE, because the resource will be active before the return
to the caller. For XOSC_HF, the return status may be TRUE if the
XOSC_HF is already active. For example, if XOSC_HF was already
activated with an earlier call to Power_setDependency(XOSC_HF).
If the return status is FALSE, this indicates to the caller that
XOSC_HF hadn't been switched by the time the function initiated a
return, and that the caller should wait for the Power_XOSC_HF_SWITCHED
event notification before proceeding to the work that requires XOSC_HF
to be active.
The recommended sequence for a caller to activate XOSC_HF is:
1) Caller registers for a Power_XOSC_HF_SWITCHED notification.
For example, the specified callback function might set a global
flag, which the caller can check to see if the notification
occurred.
2) Caller invokes: status = Power_setDependency(XOSC_HF);
3) Caller checks status to see if XOSC_HF is active yet
- If status is TRUE, XOSC_HF is active, caller should proceed,
and NOT wait for a Power_XOSC_HF_SWITCHED notification
- Else, XOSC_HF wasn't activated yet, caller needs to wait
until the Power_XOSC_HF_SWITCHED event has been signaled.
Note that depending upon timing, the event may have been
signaled between the time the return status was determined
within Power_setDependency() and the time the caller
checks the return status. The key point is that, when
the return status is FALSE, the Power_XOSC_HF_SWITCHED
notification WILL be sent (once the XOSC_HF is switched),
and the caller should wait for this notification before
proceeding with any work that requires XOSC_HF to be active.
CONSTRAINTS
For the XOSC_HF resource (described above), the caller MUST wait for
XOSC_HF activation to complete before calling
Power_releaseDependency(XOSC_HF).
Power_shutdown() // module-wide |
![](../../../../../Arrow_up.png) |
Put the device into the SHUTDOWN state
ARGUMENTS
arg
Reserved for future use; currently unused
RETURNS
Power_EBUSY if Power is currently busy with another
transition
Power_ECHANGE_NOT_ALLOWED if SHUTDOWN is disallowed
due to the Power_SD_DISALLOW constraint having been
declared
Power_EFAIL if a notification error occurred
DETAILS
This function will transition the device into the SHUTDOWN state.
Before the actual device transtion is initiated, notifications will
be sent to any clients who've registered for the
Power_ENTERING_SHUTDOWN event (via
Power_registerNotify()). Once notifications have been completed, the
device shutdown will commence.
If the device is successfully transitioned to SHUTDOWN, this function
call will never return. Upon wakeup, the device and application will
be rebooted. If the transition to SHUTDOWN is not successful, one of
the error codes listed above will be returned.
NOTE
This function will not prepare I/O pins for the device
shutdown state. The application needs to do the appropriate
I/O preparation before calling this API.
Power_sleep() // module-wide |
![](../../../../../Arrow_up.png) |
Put the CPU into a sleep state
ARGUMENTS
arg0
Reserved for future use; currently unused
arg1
Reserved for future use; currently unused
RETURNS
Power_SOK upon success, the device is awake
Power_EBUSY if Power is currently busy with another
transition
Power_EFAIL if a general failure occurred and the
device was not transitioned into sleep
DETAILS
This function transitions the device into and out of a sleep state.
The function returns to the caller when the device is awake again.
NOTE
Power_sleep() is intended to be called from a Power Policy
implementation function. This API is not normally called directly
by an application.
CONSTRAINTS
Power_sleep() does not check the constraints that might prohibit a
sleep transition. The caller of Power_sleep() must validate the
transition versus active constraints, prior to calling Power_sleep().
Power_standbyPolicy() // module-wide |
![](../../../../../Arrow_up.png) |
A power policy function that will transition the device into the
Power_STANDBY sleep state during CPU idle time
Void Power_standbyPolicy();
DETAILS
This is an agressive power policy function that will consider active
constraints, sleep transition latencies, and the next expected wakeup,
and automatically transition the device into the deepest sleep state
possible.
The first goal is to enter Power_STANDBY; if that is not appropriate
given current conditions (e.g., the sleep transition latency is
greater than the time until the next scheduled Clock event), then
the secondary goal is the IDLE_PD state; if that is disallowed (e.g.,
if the Power_IDLE_PD_DISALLOW constraint is declared), then the policy
will fallback and simply invoke wait-for-interrupt, to clock
gate the CPU until the next interrupt.
This policy is enabled and selected via the following application
configuration steps:
Power.idle = true;
Power.policyFunc = Power.standbyPolicy;
Power_unregisterNotify() // module-wide |
![](../../../../../Arrow_up.png) |
Unregister for Power event notifications
ARGUMENTS
pNotifyObj
The notification object that was previously
used with Power_registerNotify() to register for
event notifications
DETAILS
This function unregisters for event notifications that were previously
registered with
Power_registerNotify().
Module-Wide Built-Ins |
![](../../../../../Arrow_up.png) |
// Get this module's unique id
Bool Power_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Power_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Power_Module_getMask();
// Returns the diagnostics mask for this module
Void Power_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module