The SYS/BIOS Power Manager, (Power module) provides APIs that allow you to
reduce power consumption of C6748 and OMAP-L138 applications. It provides
the following core functionality:
Resource tracking. You can set and release program dependencies upon power
manageable resources. For example, when a dependency is set on a UART, if
it is the first dependency upon the UART, then Power will automatically
enable the clock to the UART module. And when the last dependency on the
UART is released, Power will automatically disable the clock to the UART.
Voltage and frequency scaling. You can dynamically change the voltage and
frequency for the CPU domain, or the peripheral domain. Since power
consumption is linearly proportional to frequency and quadratically
proportional to voltage, this can significantly reduce power consumption
of the device.
CPU idling. You can configure Power to automatically idle (i.e., clock
gate) the CPU while waiting for the next interrupt, at which time new
processing is required. This is a "lightweight" sleep mechanism and has
negligible CPU wakeup latency.
Activate sleep modes. You can dynamically activate processor sleep modes
that will perform clock gating and in some cases voltage reduction. These
sleep modes are "heavier weight" compared to idling, with longer wakeup
latency, but provide significant savings during application standby times.
Coordinate scaling and sleep modes. You can register application functions
to be called upon specific power events, for example, before activating a
particular sleep mode. The Power module will call these functions at the
appropriate times, allowing coordination between affected software
components, and power saving actions of the Power module.
const Power_CRESOURCETRACKING |
|
Bitmask for resource tracking capability
#define Power_CRESOURCETRACKING (UInt)0x200
const Power_CVFSCALING |
|
Bitmask for V/F scaling capability
#define Power_CVFSCALING (UInt)0x8
const Power_EXTERNAL |
|
Used to specify external controller wakeup source for Power_DEEPSLEEP
#define Power_EXTERNAL (UInt)0x8
const Power_PLL0 |
|
Used to specify bypass PLL0 during Power_SLEEP
#define Power_PLL0 (UInt)0x1
const Power_PLL1 |
|
Used to specify bypass PLL1 during Power_SLEEP
#define Power_PLL1 (UInt)0x2
const Power_RTC_ALARM |
|
Used to specify an RTC alarm wakeup source for Power_DEEPSLEEP
#define Power_RTC_ALARM (UInt)0x10
enum Power_Constraint |
|
Constraints that can be registered with Power
typedef enum Power_Constraint {
Power_DISALLOWED_CPU_SETPOINT_MASK,
// Disallowed CPU domain setpoints
Power_DISALLOWED_PER_SETPOINT_MASK,
// Disallowed peripheral domain setpoints
Power_DISALLOWEDSLEEPSTATE_MASK
// Disallowed sleep states
} Power_Constraint;
enum Power_Domain |
|
Scaling domains
typedef enum Power_Domain {
Power_CPU,
// CPU domain
Power_PER
// Peripheral domain
} Power_Domain;
enum Power_Event |
|
Power Event enumerations
typedef enum Power_Event {
Power_GOINGTOSTANDBY,
// Going to Power_STANDBY
Power_AWAKEFROMSTANDBY,
// Awake from Power_STANDBY
Power_GOINGTOSLEEP,
// Going to Power_SLEEP
Power_AWAKEFROMSLEEP,
// Awake from Power_SLEEP
Power_GOINGTODEEPSLEEP,
// Going to Power_DEEPSLEEP
Power_AWAKEFROMDEEPSLEEP,
// Awake from Power_DEEPSLEEP
Power_PENDING_CPU_SETPOINTCHANGE,
// A CPU setpoint change is about to occur
Power_PENDING_PER_SETPOINTCHANGE,
// A peripheral setpoint change is about to occur
Power_DONE_CPU_SETPOINTCHANGE,
// A CPU setpoint change has just completed
Power_DONE_PER_SETPOINTCHANGE,
// A peripheral setpoint change has just completed
Power_INVALIDEVENT
} Power_Event;
enum Power_NotifyResponse |
|
Return values from a notify function
typedef enum Power_NotifyResponse {
Power_NOTIFYDONE,
// Client has finished processing the notification
Power_NOTIFYNOTDONE,
// Client needs to wait (delayed completion) to finish processing the notification
Power_NOTIFYERROR
// An error occurred while processing the notification
} Power_NotifyResponse;
enum Power_Resource |
|
Resource enumerations. Some of these are not applicable for C6746 and
C6742 derivative devices
typedef enum Power_Resource {
Power_RSRC_EDMA3_CC_0,
// EDMA3_0 Channel Controller 0
Power_RSRC_EDMA3_TC_0,
// EDMA3_0 Transfer Controller 0
Power_RSRC_EDMA3_TC_1,
// EDMA3_0 Transfer Controller 1
Power_RSRC_EMIFA,
// EMIFA
Power_RSRC_SPI_0,
// SPI0
Power_RSRC_MMCSD_0,
// MMC/SD0
Power_RSRC_AINTC,
// ARM Interrupt Controller
Power_RSRC_RSVD1,
// RESERVED
Power_RSRC_UART_0,
// UART0
Power_RSRC_RSVD2,
// RESERVED
Power_RSRC_EDMA3_CC_1,
// EDMA3_1 Channel Controller 0
Power_RSRC_USB0,
// USB0
Power_RSRC_USB1,
// USB1
Power_RSRC_GPIO,
// GPIO
Power_RSRC_UHPI,
// HPI
Power_RSRC_EMAC,
// EMAC
Power_RSRC_DDR2,
// DDR2/mDDR
Power_RSRC_MCASP_0,
// McASP0
Power_RSRC_SATA,
// SATA
Power_RSRC_VPIF,
// VPIF
Power_RSRC_SPI_1,
// SPI1
Power_RSRC_I2C_1,
// I2C1
Power_RSRC_UART_1,
// UART1
Power_RSRC_UART_2,
// UART2
Power_RSRC_MCBSP_0,
// McBSP0
Power_RSRC_MCBSP_1,
// McBSP1
Power_RSRC_LCDC,
// LCDC
Power_RSRC_EHRPWM,
// eHRPWM0/1
Power_RSRC_MMCSD_1,
// MMC/SD1
Power_RSRC_UPP,
// uPP
Power_RSRC_ECAP,
// eCAP0/1/2
Power_RSRC_EDMA3_TC_2,
// EDMA3_1 Transfer Controller 0
Power_RSRC_END
} Power_Resource;
enum Power_SleepCode |
|
Sleep modes
typedef enum Power_SleepCode {
Power_STANDBY,
Power_SLEEP,
Power_DEEPSLEEP
} Power_SleepCode;
enum Power_Status |
|
Function return codes
typedef enum Power_Status {
Power_SOK,
Power_EFAIL,
Power_EINVALIDEVENT,
Power_EINVALIDHANDLE,
Power_EINVALIDPOINTER,
Power_EINVALIDVALUE,
Power_ENOTIMPLEMENTED,
Power_ENOTSUPPORTED,
Power_EOUTOFRANGE,
Power_ETIMEOUT,
Power_EBUSY,
Power_EINITFAILURE,
Power_ETOOMANYCALLS
} Power_Status;
enum Power_pmiLib |
|
Power Management Interface (PMI) control library options
typedef enum Power_pmiLib {
Power_pmiLib_evm6748,
// evm6748 with dedicated I2C control of PMIC
Power_pmiLib_shared_evm6748,
// evm6748 with shared I2C control of PMIC
Power_pmiLib_lcdk,
// LCDK with no voltage scaling
Power_pmiLib_null,
// evm6748 with no voltage scaling
Power_pmiLib_user
// user will provide custom PMI library
} Power_pmiLib;
enum Power_psclLib |
|
Power Scaling Library (PSCL) configuration library options
typedef enum Power_psclLib {
Power_psclLib_evm6748,
// evm6748 with 300MHz device
Power_psclLib_evm6748_372,
// evm6748 with 372MHz device
Power_psclLib_evm6748_408,
// evm6748 with 408MHz device
Power_psclLib_evm6748_456,
// evm6748 with 456MHz device
Power_psclLib_lcdk,
// LCDK with 456MHz device
Power_psclLib_null,
// evm6748 with 300MHz device, no scaling
Power_psclLib_user
// user will provide custom PSCL library
} Power_psclLib;
typedef Power_ConstraintHandle |
|
Handle for a registered constraint
typedef UArg *Power_ConstraintHandle;
typedef Power_FuncPtr |
|
Idle function prototype
typedef Void (*Power_FuncPtr)();
typedef Power_NotifyHandle |
|
Handle for a registered notification
typedef Void *Power_NotifyHandle;
struct Power_Attrs |
|
Power attributes structure
typedef struct Power_Attrs {
Bool scaleVoltage;
// Scale voltage along with frequency
Bool waitForVoltageScale;
// Wait during down voltage ramp
} Power_Attrs;
struct Power_Config |
|
Scaling configuration structure
typedef struct Power_Config {
Bool scaleVoltage;
// Scale voltage with frequency?
Bool waitForVoltageScale;
// Wait for down ramp?
} Power_Config;
struct Power_SetpointInfo |
|
Setpoint info structure
typedef struct Power_SetpointInfo {
UInt frequency;
// Clock frequency
UInt voltage;
// Voltage
} Power_SetpointInfo;
struct Power_SleepOverride |
|
Sleep attributes override structure
typedef struct Power_SleepOverride {
UInt sleepVoltage;
// override sleep voltage (millivolts) for Power_SLEEP
UInt bypassedPLLs;
// override PLLs to bypass for Power_SLEEP
} Power_SleepOverride;
config Power_enableScaling // module-wide |
|
Enable voltage and frequency (V/F) scaling? Default is false
extern const Bool Power_enableScaling;
config Power_idle // module-wide |
|
Idle the CPU during idle time?
extern const Bool Power_idle;
config Power_initialSetpointCPU // module-wide |
|
Initial CPU domain setpoint. Default is 2
extern const UInt Power_initialSetpointCPU;
config Power_initialSetpointPER // module-wide |
|
Initial peripheral (PER) domain setpoint. Default is 0
extern const UInt Power_initialSetpointPER;
config Power_trackResources // module-wide |
|
Enable resource tracking? Default is false
extern const Bool Power_trackResources;
Power_changeSetpoint() // module-wide |
|
Initiate a change to the V/F setpoint of the CPU, or the peripheral
domain
ARGUMENTS
domain
The relevant scaling domain (Power_CPU or Power_PER)
newSetpoint
The new V/F setpoint to be scaled to
notifyTimeout
The maximum time (in Clock ticks) to wait for
client notifications to complete
RETURNS
Power_SOK if the operation succeeded and the new
setpoint is in effect
Power_EFAIL if a general failure occurred; the
requested transition did not occur
Power_ENOTIMPLEMENTED if V/F scaling is not implemented
on this platform
Power_ENOTSUPPORTED if the operation failed because
a client registered a constraint with Power indicating
that it cannot support the requested setpoint
Power_EOUTOFRANGE if the operation failed because
the domain or newSetpoint parameter is not a valid value
for the platform
Power_ETIMEOUT if the operation failed because
a registered notification function did not complete its
processing within the specified notifyTimeout
Power_EBUSY if the operation failed because the
operation cannot be performed at this time; Power is
busy processing a previous request
Power_EINITFAILURE if there was a previous failure when
V/F scaling support was being initialized; V/F scaling
is unavailable
DETAILS
Power_changeSetpoint() changes the voltage and frequency of a
scalable domain.
The domain parameter indicates the relevant scaling domain. The
domains that can be scaled vary by platform, and are enumerated as
Power_Domain. For example, for the TMS320C6748, there are two
scalable domains: the CPU domain (Power_CPU) and the peripheral
domain (Power_PER).
The newSetpoint parameter is a numeric value that indexes into a table
of frequency/voltage pairs, as defined by the underlying scaling
configuration library.
The notifyTimeout parameter is the maximum amount of time (in system
Clock ticks) to wait for registered notification functions (set by
Power_registerNotify()) to respond to a delayed completion, before
declaring failure and returning Power_ETIMEOUT.
For example, if notifyTimeout is set to 200, Power_changeSetpoint()
waits up to 200 ticks (typically 200 milliseconds) before declaring
that function has failed to respond. Power uses notifyTimeout for each
type of notification. For example, if notification functions are
registered for both before and after setpoint changes,
Power_changeSetpoint() waits up to notifyTimeout on each type of
notification.
All registered notification functions are called from the context of
Power_changeSetpoint().
The application should treat return values of Power_ETIMEOUT or
Power_EFAIL as critical system failures. These values indicate the
notification client is taking too long or is unresponsive, and the
system is in an unknown state.
Power_changeSetpoint() disables Swi and Task scheduling when it
begins making a change. However, Hwis may run during the notification
process. After the setpoint has been changed, Swi and Task scheduling
are re-enabled, and a context switch occurs only if some other thread
has since been made ready to run.
CONSTRAINTS
Power_changeSetpoint() cannot be called from a Hwi or main()
Power_changeSetpoint() can be called from a Swi only if notifyTimeout
is zero
Power_configure() // module-wide |
|
Set new configuration parameters for Power
ARGUMENTS
attrs
An Attrs structure defining new
configuration parameters
RETURNS
Power_SOK if the configuration was changed
Power_EINVALIDVALUE if the change failed because one of
the attributes is invalid
DETAILS
Power_configure() specifies new configuration properties for the Power
module. It overrides those specified in the static configuration.
Configuration parameters are specified via a Power_Attrs structure.
In this structure, 'scaleVoltage' indicates whether Power should scale
voltages during setpoint changes, and when switching to sleep modes that
support voltage reduction. It corresponds to the
scaleVoltage
configuration property. If 'scaleVoltage' is TRUE, the voltage is
scaled down if possible when going to a lower frequency or activating
sleep modes. If 'scaleVoltage' is FALSE, the voltage is not scaled
lower. The voltage is always scaled up if the new (destination)
setpoint frequency is higher than that supported at the current voltage.
In the Power_attrs structure, the 'waitForVoltageScale' flag indicates
whether Power should wait for a down-voltage transition to complete
before returning from Power_changeSetpoint(). It corresponds to the
waitVoltage configuration property. (Such transition times can
be long, and they typically depend upon power supply load.) Currently,
it is recommended that this property always be TRUE. Note that the
Power module always waits during up-voltage transitions; this is
required to avoid overclocking the device.
Power_getCapabilities() // module-wide |
|
Get info on Power's capabilities on the current platform
ARGUMENTS
capsMask
Location of a bitmask to be written with capabilities
flags
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDPOINTER if the operation failed because
capsMask was NULL
DETAILS
The capsMask parameter should point to the location where
Power_getCapabilities() should write a bitmask that defines the
capabilities.
You can use the following constants to check for capabilities
in the bitmask:
Power_CRESOURCETRACKING - Power supports dynamic resource tracking
Power_CVFSCALING - Power supports voltage and frequency scaling
Power_getConstraintInfo() // module-wide |
|
Get info on the aggregate of constraints that have been registered with
Power
ARGUMENTS
type
Type of constraint
value
Location to be written with aggregate of constraints
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDVALUE if the operation failed because
type does not correspond to a supported constraint type
Power_EINVALIDPOINTER if the operation failed because
the value parameter was NULL
DETAILS
Power_getConstraintInfo() returns information about constraints that are
currently registered with the Power module, via previous calls to
Power_registerConstraint().
The type parameter identifies the type of constraint being queried. The
constraint types vary by platform, and are enumerated as
Power_Constraint. Currently the following are supported:
Power_DISALLOWEDSLEEPSTATE_MASK - Sleep states that should
not be activated.
Power_DISALLOWED_CPU_SETPOINT_MASK - CPU setpoints that should not
be activated.
Power_DISALLOWED_PER_SETPOINT_MASK - Peripheral setpoints that
should not be activated.
Power_getContraintInfo() returns a value that is the aggregate of all
constraints that are currently registered. For example, if one Power
client disallowed the sleep state Power_SLEEP, and a different client
disallowed the sleep state Power_DEEPSLEEP, the returned value will
be (Power_SLEEP | Power_DEEPSLEEP).
Power_getCurrentSetpoint() // module-wide |
|
Get the current setpoint in effect
ARGUMENTS
domain
The scaling domain being queried (Power_CPU or
Power_PER)
setpoint
Location to write the current setpoint
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDPOINTER if the operation failed because
the setpoint parameter was NULL
Power_EINVALIDVALUE if the operation failed because the
domain parameter was invalid
Power_EINITFAILURE if there was a previous failure when
V/F scaling support was being initialized; V/F scaling
is unavailable
Power_ENOTSUPPORTED if the operation failed because
V/F scaling support is not enabled
DETAILS
Power_getCurrentSetpoint() returns the V/F scaling setpoint currently in
use for the specified scaling domain.
The domain parameter indicates the relevant scaling domain. The
domains that can be scaled vary by platform, and are enumerated as
Power_Domain.
The setpoint parameter should point to the location where
Power_getCurrentSetpoint() should write the current setpoint.
CONSTRAINTS
If a call to Power_getCurrentSetpoint() is made during a change to the
current setpoint, the value Power_getCurrentSetpoint() returns may
be the old setpoint and not the new setpoint
Power_getDependencyCount() // module-wide |
|
Get the count of dependencies that are currently declared on a resource
ARGUMENTS
resourceID
The resource identifier
count
Location to write the resource's dependency count
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDPOINTER if the operation failed because
the count parameter was NULL
Power_EINVALIDVALUE if the operation failed because
Power cannot control this resource
Power_ENOTSUPPORTED if the operation failed because
resource tracking is not enabled
Power_EOUTOFRANGE if the specified resourceID is
outside the range of valid resource IDs
DETAILS
Power_getDependencyCount() returns the number of dependencies that
are currently declared on a resource. Normally this corresponds to the
number of times Power_setDependency() has been called for the
resource, minus the number of times Power_releaseDependency() has
been called for the same resource.
On some platforms, early boot code may enable individual resources
before Power initializes. To ensure proper state synchronization in
this case, Power queries individual resource states as the Power module
initializes. So, it is possible for the returned "count" value to be 1,
even if Power_setDependency() has not been called by the application.
Resources are enumerated as Power_Resource.
Power_getNumSetpoints() // module-wide |
|
Get the number of setpoints supported on the platform
ARGUMENTS
domain
The scaling domain being queried (Power_CPU or
Power_PER)
numberSetpoints
Location to write the number of supported
setpoints
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDPOINTER if the operation failed because
the numberSetpoints parameter was NULL
Power_EINVALIDVALUE if the operation failed because the
domain parameter was invalid
Power_EINITFAILURE if there was a previous failure when
V/F scaling support was being initialized; V/F scaling
is unavailable
Power_ENOTSUPPORTED if the operation failed because
V/F scaling support is not enabled
DETAILS
Power_getNumSetpoints() returns the number of setpoints supported for
a specified domain.
The domain parameter indicates the relevant scaling domain. The
domains that can be scaled vary by platform, and are enumerated as
Power_Domain.
Power_getSetpointInfo() // module-wide |
|
Get the frequency and core voltage for a setpoint
ARGUMENTS
domain
The scaling domain being queried (Power_CPU or
Power_PER)
setpoint
The setpoint to be queried
frequency
Location to write the frequency (in kHz) of the
specified setpoint
voltage
Location to write the voltage (in millivolts) of the
specified setpoint
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDPOINTER if the operation failed because
the frequency or votage parameter was NULL
Power_EINVALIDVALUE if the operation failed because the
domain parameter was invalid
Power_EINITFAILURE if there was a previous failure when
V/F scaling support was being initialized; V/F scaling
is unavailable
Power_ENOTSUPPORTED if the operation failed because
V/F scaling support is not enabled
Power_EOUTOFRANGE if the operation failed because
the setpoint parameter is out of range of valid
setpoints for the specified domain
DETAILS
Power_getSetpointInfo() returns the frequency and voltage for a given
setpoint.
The domain parameter indicates the relevant scaling domain for which
the setpoint information is to be retrieved. The domains that can be
scaled vary by platform, and are enumerated as Power_Domain.
Power_getTransitionLatency() // module-wide |
|
Get the latency to scale from one setpoint to another setpoint
Power_Status Power_getTransitionLatency(
Power_Domain domain,
UInt initialSetpoint,
UInt finalSetpoint,
UInt *
frequencyLatency,
UInt *
voltageLatency);
ARGUMENTS
domain
The relevant scaling domain (Power_CPU or Power_PER)
initialSetpoint
The setpoint to be scaled from
finalSetpoint
The setpoint to be scaled to
frequencyLatency
Location to write the frequency transition
latency (in microseconds) from that of the
initialSetpoint to that of the finalSetpoint
voltageLatency
Location to write the voltage transition
latency (in microseconds) from that of the
initialSetpoint to that of the finalSetpoint
RETURNS
Power_SOK if the operation succeeded
Power_EFAIL if a general failure occurred
Power_EINVALIDPOINTER if the operation failed because
the frequencyLatency or votageLatency parameter was NULL
Power_EINVALIDVALUE if the operation failed because the
domain, initialSetpoint, or finalSetpoint value was
invalid
Power_EINITFAILURE if there was a previous failure when
V/F scaling support was being initialized; V/F scaling
is unavailable
Power_ENOTIMPLEMENTED if the operation failed because
V/F scaling is not supported
DETAILS
Power_getTransitionLatency() retrieves the latencies (times required)
in microseconds to scale from a specific setpoint to another specific
setpoint.
The domain parameter should indicate the relevant scaling domain.
The initialSetpoint parameter should specify the setpoint from which the
transition would start. The finalSetpoint parameter should specify the
setpoint at which the transition would end.
The frequencyLatency parameter should point to the location where
Power_getTransitionLatency() should write the time required to change
the frequency from that of the initialSetpoint to that of the
finalSetpoint, in microseconds.
Similarly, the voltageLatency should point to the location where
Power_getTransitionLatency() should write the time required to change
the voltage from that of the initialSetpoint to that of the
finalSetpoint, in microseconds.
When frequency and voltage are scaled together, the total latency is the
sum of the frequency scaling latency and the voltage scaling latency.
Note that the time required to change a setpoint may not be
deterministic (depending upon the hardware characteristics, the
underlying software implementation, and the specific V/F swing), but it
is bounded by the value returned by Power_getTransitionLatency().
Power_registerConstraint() // module-wide |
|
Register an operational constraint with Power
ARGUMENTS
type
Type of constraint
value
A constraint type-specific mask
handle
Location to write the resulting constraint handle
(which is used for unregistering the constraint)
RETURNS
Power_SOK if the operation succeeded
Power_EFAIL if the registration failed due to a memory
allocation failure
Power_EINVALIDVALUE if the operation failed because
type does not correspond to a supported constraint type
Power_EINVALIDPOINTER if the operation failed because
the handle parameter was NULL
DETAILS
Before taking certain actions, Power checks to see if the requested
action would conflict with a client-registered constraint. If the
action does conflict, Power will not proceed with the request.
Power_registerConstraint() is the API that allows clients to register
their constraints with Power.
The type parameter identifies the type of constraint being registered.
The constraint types vary by platform, and are enumerated as
Power_Constraint. Currently the following are supported:
Power_DISALLOWEDSLEEPSTATE_MASK - Sleep states that should
not be activated.
Power_DISALLOWED_CPU_SETPOINT_MASK - CPU setpoints that should not
be activated.
Power_DISALLOWED_PER_SETPOINT_MASK - Peripheral setpoints that
should not be activated.
The Power_DISALLOWEDSLEEPSTATE_MASK is a bitmask of the
sleep states that can be activated via Power_sleepDSP(). For the
TMS320C6748, the states are identified via a combination of the
following bitmask values: Power_STANDBY, Power_SLEEP, and
Power_DEEPSLEEP.
The Power_DISALLOWED_CPU_SETPOINT_MASK is a bitmask of
setpoints that the CPU should not be transitioned to. For example, if a
driver won't operate properly below a specific CPU performance level, it
can register the lower performance levels via the setpoint mask.
Setpoint IDs are zero-based, with a lower index representing a lower
performance level. They are represented right-justified in the bitmask.
For example, to disallow setpoint "0", the mask is "0x1". To disallow
the lowest five setpoints the mask value is "0x1F".
The Power_DISALLOWED_PER_SETPOINT_MASK performs the
same function as the Power_DISALLOWED_CPU_SETPOINT_MASK,
but corresponds to scaling of the peripheral domain. The bitmask follows
the same format; setpoints are zero-based and have right-justified bit
positions, starting with "0x1".
It is important that clients call Power_unregisterConstraint() when the
operational constraint no longer exists. Otherwise, Power may be left
unnecessarily restricted from activating power savings.
CONSTRAINTS
Power_registerConstraint() cannot be called from a Swi or Hwi, because
it allocates memory, and this may incur a context switch.
Power_registerNotify() // module-wide |
|
Register a function to be called on a specific power event
ARGUMENTS
eventType
The type of Power event to be notified of
eventMask
A Power event type-specific mask
notifyFxn
The function Power should call to notify the client
of the event
clientArg
A client-defined argument to pass with the notifyFxn
call
notifyHandle
Location to write the resulting notification
handle (which is used for unregistering for the event)
delayedCompletionFxn
Location for the pointer to the delayed
completion function the client should call if it
requires more time to process an event (the client
calls this function once its processing is complete)
RETURNS
Power_SOK if the registration succeeded
Power_EFAIL if the registration failed due to a memory
allocation failure
Power_EINVALIDPOINTER if the operation failed because
the notifyFxn, notifyHandle, or delayedCompletionFxn
parameter was NULL
Power_EINVALIDEVENT if the operation failed because
eventType is invalid
DETAILS
Power_registerNotify() registers a function to be called when a specific
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 eventType parameter identifies the type of power event for which the
notify function being registered is to be called. The eventType
parameter can vary by platform, and is enumerated as Power_Event. For
example, on the TMS320C6748 this parameter may have one of the
following values:
Power_PENDING_CPU_SETPOINTCHANGE - The CPU domain V/F setpoint is
about to change
Power_DONE_CPU_SETPOINTCHANGE - The pending CPU setpoint change has
now completed
Power_PENDING_PER_SETPOINTCHANGE - The peripheral domain V/F
setpoint is about to change
Power_DONE_PER_SETPOINTCHANGE - The pending peripheral setpoint
change has now completed
Power_GOINGTOSTANDBY - The DSP is going to STANDBY state
Power_AWAKEFROMSTANDBY - The DSP has awoken from STANDBY
Power_GOINGTOSLEEP - The DSP is going to SLEEP state
Power_AWAKEFROMSLEEP - The DSP has awoken from SLEEP
Power_GOINGTODEEPSLEEP - The DSP is going to DEEPSLEEP state
Power_AWAKEFROMDEEPSLEEP - The DSP has awoken from DEEPSLEEP
The eventMask parameter is an event-specific mask. Currently the
eventMask is not used by Power.
The notifyFxn parameter specifies the function to call when the
specified Power event occurs. The notifyFxn must implement the
following signature:
status = notifyFxn(eventType, eventArg1, eventArg2, clientArg);
Where: eventType (of type Power_Event) is the type of Power event of
the notification; eventArg1 (of type UArg) is an event-specific
argument; eventArg2 (of type UArg) is a second event-specific argument;
and clientArg (of type UArg) is an abitrary argument.
Currently, eventArg1 and eventArg2 are used only for V/F scaling events:
for a 'pending' setpoint change, eventArg1 holds the current setpoint,
and eventArg2 holds the pending setpoint; for a 'done' sepoint change
event, eventArg1 holds the previous setpoint, and eventArg2 holds the
new setpoint.
The notification function must return one of the following constants
as a status value of type Power_NotifyResponse: Power_NOTIFYDONE if the
the client processed the notification function successfully;
Power_NOTIFYNOTDONE if the client must wait for interrupt processing
to occur before it can proceed (the client must later call the
delayedCompletionFxn specified when this function was registered); or
Power_NOTIFYERROR if the notification cannot be processed (either an
internal client error occurred or the client was notified of an event
it could not process).
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).
For Power_regsiterNotify(), notifyHandle should point to the location
where Power_registerNotify() should write a notification handle. If the
application later needs to unregister the notification function, the
application should pass this handle to Power_unregisterNotify().
The delayedCompletionFxn is a pointer to a function provided by the
Power module to the client at registration time. If a client cannot act
immediately upon notification, its notify function should return
Power_NOTIFYNOTDONE. Later, when the action is complete, the
client should call the delayedCompletionFxn to signal Power that it has
finished. The delayedCompletionFxn is a void function, taking no
arguments, and having no return value. If a client can and does act
immediately on the notification, it should return Power_NOTIFYDONE in
response to notification, and should not call the delayedCompletionFxn.
For example, if a DMA driver is to prepare for a setpoint change, it may
need to wait for the current DMA transfer to complete. When the driver's
DMA completes (for example, on the next hardware interrupt), it calls
the delayedCompletionFxn function provided when it registered for
notification. This completion function tells the Power module that the
driver is finished. Meanwhile, the Power module was able to continue
notifying other clients, and was waiting for all clients to signal
completion.
CONSTRAINTS
Power_registerNotify() cannot be called from a Swi or Hwi, because
it allocates memory, and this may incur a context switch.
Power_releaseDependency() // module-wide |
|
Release a dependency that has been previously declared by
Power_setDependency
ARGUMENTS
resourceID
The resource identifier
RETURNS
Power_SOK if the operation succeeded and the dependency
has been released
Power_EFAIL if the operation failed while attempting
to release the resource
Power_EINVALIDVALUE if the operation failed because
Power cannot control this resource
Power_ENOTSUPPORTED if the operation failed because
resource tracking is not enabled
Power_EOUTOFRANGE if the specified resourceID is
outside the range of valid resource IDs
Power_ETOOMANYCALLS if a dependency was not previously
set for the resource, and was therefore not released
DETAILS
This function is the companion to Power_setDependency(). It releases
a resource dependency that was previously set. Resources are enumerated
by Power_Resource.
Power_ETOOMANYCALLS is returned if you call Power_releaseDependency()
when there are no dependencies currently declared for the specified
resource (either because all have been released or because none were
set).
Power_setDependency() // module-wide |
|
Declare a dependency upon a power-manageable resource
ARGUMENTS
resourceID
The resource identifier
RETURNS
Power_SOK if the operation succeeded and the dependency
has been set
Power_EFAIL if the operation failed while attempting
to activate the resource
Power_EINVALIDVALUE if the operation failed because
Power cannot control this resource
Power_ENOTSUPPORTED if the operation failed because
resource tracking is not enabled
Power_EOUTOFRANGE if the specified resourceID is
outside the range of valid resource IDs
DETAILS
Power_setDependency() declares a dependency upon a resource. Resources
are enumerated by Power_Resource.
If the resource had been inactive, it will be activated during this
function call.
This function is the companion to Power_releaseDependency().
Power_signalEvent() // module-wide |
|
Signal a Power event to registered clients
ARGUMENTS
eventType
The Power event to be signaled
eventArg1
The event-specific first argument
eventArg2
The event-specific second argument
notifyTimeout
The maximum time (in Clock ticks) to wait for
client notifications to complete
RETURNS
Power_SOK if the operation succeeded
Power_EFAIL if a notification failure occurred
Power_EINVALIDEVENT if the operation failed because
eventType is invalid
Power_ETIMEOUT if the operation failed because
a registered notification client did not complete its
processing within the specified notifyTimeout
DETAILS
Power_signalEvent() provides a mechanism for an application to signal
Power events. Power_signalEvent() only signals the event occurrence; it
does not implement the actual processing associated with the Power
event.
For example, on a platform where V/F scaling is accomplished on a
separate processor, Power_signalEvent() can be called by the DSP
application before the scaling to notify registered clients on this
processor of the pending setpoint change event. Similarly, after the
scaling, Power_signalEvent() can be called to signal the done setpoint
change event. Here Power is not orchestrating the change to the
V/F setpoint, but its registration, notification, and signaling
capabilities allow synchronization between scaling by the other
processor and the affected software on this processor.
The parameters eventArg1 and eventArg2 should correspond to the type
of event being signaled. For example, for a pending setpoint
change event, the current and pending setpoints should be specified as
eventArg1 and eventArg2.
The notifyTimeout parameter is the maximum amount of time (in system
Clock ticks) to wait for all registered notification functions (set by
Power_registerNotify()) to respond to a delayed completion, before
declaring failure and returning Power_ETIMEOUT.
Power_signalEvent() is intended only for signaling power events that are
outside the full control of the Power implementation on the current
processor. It can be used for V/F scaling notification as described
avove when Power does not implement the actual scaling. For events where
Power does orchestrate the processing, for example, on platforms
where Power performs the actual V/F scaling, or activates a processor
sleep mode, Power handles the notifications automatically, and
Power_signalEvent() must not be used for these events. In other words,
Power_signalEvent() only validates that the indicated eventType is
within the range of valid events for the platform; it does not validate
whether it makes sense for the application to trigger the signaling of
the indicated event, and it does not implement the actual power
transition indicated by the event.
CONSTRAINTS
Power_signalEvent can be called from a Hwi or Swi only if notifyTimeout
is zero
Power_sleepDSP() // module-wide |
|
Put the DSP into a sleep state
Power_Status Power_sleepDSP(
UInt sleepCode,
UInt sleepArg,
UInt notifyTimeout);
ARGUMENTS
sleepCode
The sleep state for the DSP
sleepArg
A sleepCode-specific argument structure (see below)
notifyTimeout
The maximum time (in Clock ticks) to wait for
client notifications to complete
RETURNS
Power_SOK if the operation succeeded and a successful
sleep and wake occurred
Power_EFAIL if a general failure occurred and the DSP
could not be put to sleep
Power_ENOTIMPLEMENTED if the requested sleep state
is not implemented on this platform
Power_ETIMEOUT if the operation failed because
a registered notification function did not complete its
(delayed completion) processing within the specified
notifyTimeout
Power_EBUSY if the operation failed because Power
is still busy processing a previous request
DETAILS
Power_sleepDSP() transitions the DSP to a new sleep state. A successful
call to Power_sleepDSP() returns when the DSP has awoken from the
specified sleep state.
The sleepCode parameter indicates the new sleep state for the DSP. The
sleep states supported by Power usually vary by device. For example,
the following constants may be used to activate sleep states on the
TMS320C6748:
Power_STANDBY - The GEM is put into a power-saving standby mode,
with its clock turned off at the GEM boundary. This mode has a low
latency for wakeup.
Power_SLEEP - In addition to putting the GEM into standby, the core
voltage is reduced, and the PLLs are slowed down or bypassed.
Power_DEEPSLEEP - In addition to the actions for Power_SLEEP, the
GEM clock is gated up-stream at the power sleep controller, memories
are put into retention, and PLLs are powered down.
The sleepArg parameter is a sleepCode-specific argument. For example,
for the TMS320C6748, this parameter is not used for Power_STANDBY,
but is used for Power_SLEEP and Power_DEEPSLEEP (see below).
For Power_SLEEP: the sleepArg can be used to override Power's
default behavior. If sleepArg is NULL, then Power reduces the core
voltage to 1.0 volts during sleep, and bypasses both PLLs. If sleepArg
is non-NULL, it is interpreted as a pointer to a
SleepOverride
structure. In this structure, the sleepVoltage is in millivolts, and
must correspond to a voltage level defined by the scaling configuration
library. The bypassedPLLs value is treated as a bitmask to indicate
which PLLs get bypassed during sleep: Power_PLL0 and/or Power_PLL1.
This override mechanism can be used to ensure operation within the
TMS320C6748 device constraints. For example, if the minimum supported
voltage when DDR2 is used is 1.1 volts, and no DDR2 accesses can be
made when PLL1 is bypassed. These constraints could be violated in some
use cases, for example, when DDR2 memory is used, and there is a
possibility that the wakeup interrupt service routine triggers some
off-chip code or data accesses. The override mechanism allows the sleep
voltage to be increased to 1.1 volts and PLL1 to not be bypassed during
sleep.
For Power_DEEPSLEEP: sleepArg defines the DEEPSLEEP signal source that
Power should configure for wakeup. This must be either Power_RTC_ALARM
or Power_EXTERNAL.
The notifyTimeout parameter is the maximum amount of time (in system
Clock ticks) to wait for registered notification functions (set by
Power_registerNotify()) to respond to a delayed completion, before
declaring failure and returning Power_ETIMEOUT. If the notifyTimeout
parameter is zero, then all notification functions must return
Power_NOTIFYDONE-they cannot request a delayed completion. If a
notification function does not return, the system will hang. The
notifyTimeout is not used to abandon a notification function; rather it
indicates the amount of time Power_sleepDSP waits for all delayed
completion requests to complete. The wait-loop is entered after all
notification functions have been invoked.
The application should treat return values of Power_ETIMEOUT or
Power_EFAIL as critical system failures. These values indicate the
notification client is unresponsive, and the system is in an unknown
state.
Due to the critical system nature of sleep commands, clients that
register for sleep notification should make every effort to respond
immediately to the sleep event.
CONSTRAINTS
Power_sleepDSP() cannot be called from an Hwi
Power_sleepDSP() cannot be called from a program's main() function
Power_sleepDSP() can be called from a Swi only if notifyTimeout is 0
For Power_SLEEP: no DDR memory accesses (code, data, or stack) can
occur while the PLL1 is bypassed, otherwise DDR corruption may occur
For Power_SLEEP: if DDR2 memories are used, then no DDR2 accesses can
occur with a sleep voltage of 1.0 volts, otherwise DDR2 corruption
may occur
For Power_DEEPSLEEP: this state must be invoked from an on-chip
context; no code, data, or stack access can occur during
Power_sleepDSP, otherwise DDR corruption may occur
Power_unregisterConstraint() // module-wide |
|
Unregister a constraint that was previously registered with Power
ARGUMENTS
handle
The handle to the previously-registered constraint
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDHANDLE if the operation failed because
handle is invalid
DETAILS
Power_unregisterConstraint() unregisters a constraint that was
registered with Power_registerConstraint(). For example, when a device
driver is closed, any constraints it registered with Power must be
unregistered with this function, otherwise Power may be left
unnecessarily restricted from activating power savings.
The handle parameter is the handle that was provided by
Power_registerConstraint() when the constraint was registered.
CONSTRAINTS
This function cannot be called from a program's main() function.
Power_unregisterNotify() // module-wide |
|
Unregister for a Power event notification
ARGUMENTS
notifyHandle
The event notification handle
RETURNS
Power_SOK if the operation succeeded
Power_EINVALIDHANDLE if the operation failed because
notifyHandle is invalid
DETAILS
Power_unregisterNotify() unregisters an event notification that was
registered with Power_registerNotify(). For example, when an audio codec
device is closed, and it no longer needs event notifications, it must
unregister by calling this function.
The notifyHandle parameter is the handle that was provided by
Power_registerNotify() when registering for an event notification.
CONSTRAINTS
This function cannot be called from a program's main() function.
Module-Wide Built-Ins |
|
// 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