public interface PowerManaged
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.
An application may register to get notified of power state changes. When notified, the application may take the
following actions:
POWER_OFF
or
LOWEST_POWER
to/from POWER_ON
, as the peripheral state/context may not be
preserved.POWER_ON
to LOWEST_POWER
if the application is currently using or is about
to use the designated peripheral.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.enablePowerSaving()
method 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:
PowerSavingHandler
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.
|
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. |
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.
|
static final int LOW_POWER
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.static final int LOWEST_POWER
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.static final int POWER_OFF
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.static final int POWER_ON
static final long UNLIMITED_DURATION
void disablePowerSaving() throws java.io.IOException, PeripheralNotAvailableException
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.java.io.IOException
- if an I/O error occurs.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.lang.SecurityException
- if the caller does not have the required permission.void enablePowerSaving(int powerStates) throws java.io.IOException, PeripheralNotAvailableException
Peripheral
instance.
Note that the POWER_ON
state is always implicitly enabled.powerStates
- bitwise OR of enabled power states: LOW_POWER
, LOWEST_POWER
or POWER_OFF
.java.io.IOException
- if an I/O error occurs.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.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).void enablePowerSaving(int powerStates, PowerSavingHandler handler) throws java.io.IOException, PeripheralNotAvailableException
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.
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).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.java.io.IOException
- if an I/O error occurs.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.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int getPowerState() throws java.io.IOException, PeripheralNotAvailableException
Peripheral
instance. If application-dictated power saving is
disabled (see disablePowerSaving()
the power state depends on the power saving strategy of the platform.Peripheral
instance: POWER_ON
, LOW_POWER
,
LOWEST_POWER
or POWER_OFF
.java.io.IOException
- if an I/O error occurs.java.lang.SecurityException
- if the caller does not have the required permission.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).long requestPowerStateChange(int powerState, long duration) throws java.io.IOException, PeripheralNotAvailableException
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.
Valid power state transitions are as follows:
POWER_ON
to LOW_POWER
POWER_ON
to LOWEST_POWER
POWER_ON
to POWER_OFF
LOW_POWER
to LOWEST_POWER
LOW_POWER
to POWER_OFF
LOWEST_POWER
to POWER_OFF
0
is returned.
A transition to the POWER_ON
state can never be vetoed such as to no deny peripheral access to other
applications and the duration
parameter is ignored and always assumed to be UNLIMITED_DURATION
.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.UNLIMITED_DURATION
if an unlimited/unknown duration was requested) or 0
if
the requested power state change has been vetoed.java.io.IOException
- if an I/O error occurs.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.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).Copyright (c) 1990, 2013, Oracle and/or its affiliates. All rights reserved.