com.oracle.deviceaccess.power

Interface PowerManaged

public interface PowerManaged

The PowerManaged interface provides methods that a Peripheral class may implement to control how the underlying peripheral hardware resource is managed by the power management facility of the device.

The power management states defined are peripheral device as well as host device-dependent. For peripherals on a microcontroller unit, there may be no distinction between POWER_OFF, LOW_POWER and LOWEST_POWER and they may for example all be supported by clock-gating the unused peripherals. Conversely, a peripheral device external to the host device could support the four power management modes and could especially be powered off.

A power state change may be dictated by the power management facility of the device or it may be requested by the power management facility on behalf of the application itself or of another application (see requestPowerStateChange(int, long)). A power state change for a specific peripheral device may be requested by another application if the peripheral device or some of the underlying peripheral device hardware resources are shared. This is, for example, the case on a GPIOPin instance: another application may have opened a different GPIO pin controlled by the same GPIO controller; the application will get notified of any power state changes requested by the other application. Peripherals currently open by an application whose power managements are logically or physically dependent belong to the same power management group (see PowerManaged.Group).

An application may register to get notified of power state changes. When notified, the application may take the following actions:

1. the application may save or restore the state/configuration of the peripheral if needed. Saving the peripheral's state/configuration may be needed when the application is being notified of a power state change requested by another application on a peripheral device hardware resources shared with the current application. Saving/Restoration of the peripheral's state/configuration may be needed when changing from/to POWER_OFF or LOWEST_POWER to/from POWER_ON, as the peripheral state/context may not be preserved.
2. the application may veto a power state change. For example, the application may veto a power state change from POWER_ON to LOWEST_POWER if the application is currently using or is about to use the designated peripheral.
3. the application may grant a shorter power state change duration. For example, the application may grant a duration of a power state change from POWER_ON to LOWEST_POWER shorter than the specified duration if the application anticipates it will use the designated peripheral earlier than the specified duration.

If application-dictated power saving for a peripheral device is not explicitly enabled by a call to one of the enablePowerSaving() methods the default power saving strategy of the platform applies. This strategy is platform as well as implementation-dependent. It may define power saving rules (changing the power state of a peripheral device when certain conditions are met) that may or may not differ from peripheral device to peripheral device. It may, for example, consist in forcefully changing all peripherals' power state to LOWEST_POWER upon some condition; in such a situation, attempting to access the peripheral without restoring its state/configuration may result in unexpected behavior. Therefore an application should always either:

1. register for power state changes on the peripherals it uses
2. or, register for system-wide power state changes (if supported by the platform) and close the peripherals when going to power saving modes that may not preserve the peripheral state/context and then open again the peripherals when returning from such power saving modes.

When an application has enabled application-dictated power saving for several peripheral devices that belong to the same power management group (by a call to one of the enablePowerSaving() methods) the effective set of enabled power states is the intersection of the individually sets of enabled power states (bitwise AND). This corresponds to the power states enabled for the group. If one of the peripheral is subsequently closed the power states enabled for the group MUST reflect the change.

Valid Power State Transitions

The valid power state transitions are as follows:

From the higher power states (lesser power saving states) to the lower power states (higher power saving states):

• from POWER_ON to LOW_POWER
• from POWER_ON to LOWEST_POWER
• from POWER_ON to POWER_OFF
• from LOW_POWER to LOWEST_POWER
• from LOW_POWER to POWER_OFF
• from LOWEST_POWER to POWER_OFF

From any of the lower power states (higher power saving state) back to the highest power state (lesser power saving state):

• from LOW_POWER to POWER_ON
• from LOWEST_POWER to POWER_ON
• from POWER_OFF to POWER_ON

Subsequently, after the duration of a power state change requested by a call to requestPowerStateChange(int, long) has expired the peripheral's power state always transitions to POWER_ON.

See Also:

PowerSavingHandler

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	PowerManaged.Group The Group interface provides methods for registering for power state changes of peripherals belonging to the same power management group.

Field Summary

Fields

Modifier and Type	Field and Description
static int	LOW_POWER Low power mode (may save less power while preserving more peripheral device context/state than LOWEST_POWER, hence allowing for a faster return to full performance).
static int	LOWEST_POWER Lowest power mode (may save more power while preserving less peripheral device context/state than LOW_POWER, hence only allowing for a slower return to full performance).
static int	POWER_OFF Power has been fully removed from the device (for example from an external peripheral device).
static int	POWER_ON Fully powered on.
static long	UNLIMITED_DURATION Unlimited or unknown power state change requested duration.

Method Summary

Methods

Modifier and Type	Method and Description
void	disablePowerSaving() Disables application-dictated power saving for the Peripheral instance.
void	enablePowerSaving(int powerStates) Enables application-dictated power saving for the Peripheral instance.
void	enablePowerSaving(int powerStates, PowerSavingHandler handler) Enables application-dictated power saving for the Peripheral instance and registers a PowerSavingHandler instance to get asynchronously notified when the power management facility is about to change the power state of the Peripheral instance, hence allowing the application to veto the power state change on the peripheral.
PowerManaged.Group	getGroup() Returns the power management Group this peripheral belongs to.
int	getPowerState() Returns the current power state of the Peripheral instance.
long	requestPowerStateChange(int powerState, long duration) Requests the change of the peripheral's current power state to the specified power state for the specified duration.

Field Detail

LOW_POWER

static final int LOW_POWER

Low power mode (may save less power while preserving more peripheral device context/state than LOWEST_POWER, hence allowing for a faster return to full performance).

When transitioning from this state to POWER_ON no state/configuration restoration of the peripheral device must be needed.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

LOWEST_POWER

static final int LOWEST_POWER

Lowest power mode (may save more power while preserving less peripheral device context/state than LOW_POWER, hence only allowing for a slower return to full performance).

When transitioning from this state to POWER_ON some state/configuration restoration of the peripheral device may be needed. This state/configuration restoration of the peripheral device may be handled by a PowerSavingHandler.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

POWER_OFF

static final int POWER_OFF

Power has been fully removed from the device (for example from an external peripheral device).

When transitioning from this state to POWER_ON a complete state/configuration restoration of the peripheral device may be needed. This state/configuration restoration of the peripheral device may be handled by a PowerSavingHandler.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

POWER_ON

static final int POWER_ON

Fully powered on.

This bit flag can be bitwise-combined (OR) with other power state bit flags.

See Also:

Constant Field Values

UNLIMITED_DURATION

static final long UNLIMITED_DURATION

Unlimited or unknown power state change requested duration.

See Also:

Constant Field Values

Method Detail

disablePowerSaving

void disablePowerSaving()
                        throws java.io.IOException,
                               ClosedPeripheralException

Disables application-dictated power saving for the Peripheral instance. The power saving strategy of the platform applies.

If a PowerSavingHandler instance was registered using enablePowerSaving(int, com.oracle.deviceaccess.power.PowerSavingHandler) it will be unregistered.

Throws:

ClosedPeripheralException - if the peripheral has been closed.

java.lang.SecurityException - if the caller does not have the required permission.

java.io.IOException - if some other I/O error occurs.

enablePowerSaving

void enablePowerSaving(int powerStates)
                       throws java.io.IOException,
                              ClosedPeripheralException

Enables application-dictated power saving for the Peripheral instance. Only the specified power states are enabled for the Peripheral instance. Any attempt by another application to change the power state of the Peripheral instance to a state different from those specified will be automatically vetoed. The power management facility will not forcefully change the power state of the Peripheral instance to a state different from those specified unless in case of urgency.

By using the requestPowerStateChange(int, long) method an application may override this directive and request a power state change to a state other than those specified.

Note that the POWER_ON state is always implicitly enabled.

Subsequent calls to this method silently override any previous settings of enabled power states as well as registered PowerSavingHandler.

Parameters:

powerStates - bitwise OR of enabled power states: LOW_POWER, LOWEST_POWER or POWER_OFF.

Throws:

java.lang.IllegalArgumentException - if powerStates is not a bitwise OR of the defined power state values.

java.lang.SecurityException - if the caller does not have the required permission.

ClosedPeripheralException - if the peripheral has been closed.

java.io.IOException - if some other I/O error occurs.

enablePowerSaving

void enablePowerSaving(int powerStates,
                     PowerSavingHandler handler)
                       throws java.io.IOException,
                              ClosedPeripheralException

Enables application-dictated power saving for the Peripheral instance and registers a PowerSavingHandler instance to get asynchronously notified when the power management facility is about to change the power state of the Peripheral instance, hence allowing the application to veto the power state change on the peripheral. Only the specified power states are enabled for the Peripheral instance. Any attempt by another application to change the power state of the Peripheral instance to a state different from those specified will be automatically vetoed. The power management facility will not forcefully change the power state of the Peripheral instance to a state different from those specified unless in case of urgency.

By using the requestPowerStateChange(int, long) method an application may override this directive and request a power state change to a state other than those specified.

Note that the POWER_ON state is always implicitly enabled.

Since only the specified power states are enabled, the application will only be notified of changes to these states (including the POWER_ON state).

Subsequent calls to this method silently override any previous settings of enabled power states as well as registered PowerSavingHandler.

Parameters:

powerStates - bitwise OR of enabled power states: LOW_POWER, LOWEST_POWER or POWER_OFF.

handler - the PowerSavingHandler instance to be notified when a power state change is requested for the peripheral.

Throws:

java.lang.IllegalArgumentException - if powerStates is not a bitwise OR of the defined power state values.

java.lang.SecurityException - if the caller does not have the required permission.

ClosedPeripheralException - if the peripheral has been closed.

java.io.IOException - if some other I/O error occurs.

getPowerState

int getPowerState()
                  throws java.io.IOException,
                         ClosedPeripheralException

Returns the current power state of the Peripheral instance. If application-dictated power saving is disabled (see disablePowerSaving() the power state depends on the power saving strategy of the platform.

Returns:

the current power state of the Peripheral instance: POWER_ON, LOW_POWER, LOWEST_POWER or POWER_OFF.

Throws:

java.lang.SecurityException - if the caller does not have the required permission.

ClosedPeripheralException - if the peripheral has been closed.

java.io.IOException - if some other I/O error occurs.

requestPowerStateChange

long requestPowerStateChange(int powerState,
                           long duration)
                             throws java.io.IOException,
                                    ClosedPeripheralException

Requests the change of the peripheral's current power state to the specified power state for the specified duration. The power state change may be vetoed by the system or by other applications, or the actual duration of the power state change may be lesser than the requested duration.

If a PowerSavingHandler instance has been registered by the current application, it will not get notified of the requested power state change; it will only get notified when returning back to the POWER_ON state or of any interleaving power state changes requested by the system or by other applications.

If the peripheral is already in the requested power state no notification will be performed and the remaining duration of the current state will be set to the smallest of the requested duration and the currently remaining duration.

Any invalid power state request (see Valid Power State Transitions) is automatically vetoed and 0 is returned.

A transition to the POWER_ON state can never be vetoed such as to not deny peripheral access to other applications and the duration parameter is ignored and always assumed to be UNLIMITED_DURATION.

Parameters:

powerState - the new power state of the Peripheral instance: POWER_ON, LOW_POWER, LOWEST_POWER or POWER_OFF.

duration - the expected duration (in milliseconds) of the requested power state change or UNLIMITED_DURATION if unlimited or unknown.

Returns:

the actual (negotiated) duration (in milliseconds) - which may be lesser than or equal to the requested duration ( UNLIMITED_DURATION if an unlimited/unknown duration was requested) or 0 if the requested power state change has been vetoed.

Throws:

java.lang.IllegalArgumentException - if powerState is not one of the defined power state values or if duration is not greater than 0 or equal to UNLIMITED_DURATION.

java.lang.SecurityException - if the caller does not have the required permission.

ClosedPeripheralException - if the peripheral has been closed.

java.io.IOException - if some other I/O error occurs.

getGroup

PowerManaged.Group getGroup()
                            throws java.io.IOException,
                                   ClosedPeripheralException

Returns the power management Group this peripheral belongs to.

Returns:

the Group this peripheral belongs to.

Throws:

java.lang.SecurityException - if the caller does not have the required permission.

ClosedPeripheralException - if the peripheral has been closed.

java.io.IOException - if some other I/O error occurs.