Power policy

To ensure that hardware and software components (such as display, audio, and voice interaction) are selectively turned on and off as needed, AAOS provides a power policy, which consists of a set of expected power on and off states for hardware and software components. VHAL, or system-privileged vendor services, can apply a new power policy when the Android power state transitions or when conditions they're waiting for are met.

Applying a power policy is allowed in the states of Wait for VHAL and On (sometimes with some restrictions). In Shutdown Prepare, Garage Mode is running and should not be disturbed by a power state change. Though a regular power policy can't be applied, a special power policy, which is the system power policy named no user interaction, is applied in Shutdown Prepare.

AAOS power state

AAOS devices follow this power state diagram:

Figure 1. AAOS power state diagram.

Each power state is described below:

How is power policy defined?

Implementers define power policies in /vendor/etc/automotive/power_policy.xml, which:

• Defines the power policy.
• Defines power policy groups, which include the default power policy and are automatically applied when power state transitions occur.
• Overrides the system power policy.

Power policy

The power policy consists of a set of expected power states of hardware and software components. AAOS supports these components in the power policy:

Vendors can also define their own custom power components for use with power policies. Define custom power components in the same XML file as power policies, as in this example:

<customComponents>
  CUSTOM_COMPONENT_1000
  CUSTOM_COMPONENT_SPECIAL_SENSOR
  CUSTOM_COMPONENT_AUX_INPUT
</customComponents>

Power policy group

The default power policy is automatically applied at power state transition is specified in the power policy group. Vendors can define the default power policy for Wait For VHAL, On, and Wait for VHAL Finish (Deep Sleep Entry or Shutdown Start).

System power policies

AAOS supports two system power policies, which are no user interaction and suspend prep. The system power policy is applied when the device goes into Silent Mode, Garage Mode, Suspend-to-RAM, or Suspend-to-disk.

The following tables list the behavior of each component in the system power policy. Implementers can override Bluetooth, NFC, and Trusted device detection in the no user interaction system power policy. Overrides are applied in /vendor/etc/power_policy.xml.

no user interaction

The behavior of the no user interaction system power policy is defined in this table:

suspend prep

The behavior of the suspend prep system power policy is defined in this table:

Interaction with the VHAL

The car power policy daemon running in the system layer subscribes two properties to listen to requests from the VHAL:

• POWER_POLICY_REQ the VHAL writes power policy ID to this property.
• POWER_POLICY_GROUP_REQ the VHAL writes the power policy group ID to this property.

The current power policy in the system can be changed by modules other than VHAL. In that case, the car power policy daemon updates the CURRENT_POWER_POLICY property to notify the change to the VHAL.

Interaction with native processes

As mentioned above, the car power policy daemon runs in the system layer and, in terms of power policy management, provides almost the same functionality as CPMS running in the framework layer. Also, assume that the car power policy daemon and CPMS are fully synced.

The car power policy daemon exports AIDL interfaces for use by HALs and other native processes. They can be notified when a new power policy is changed. In other words, when each must change its power state.

ICarPowerPolicyServer.aidl

  package android.frameworks.automotive.powerpolicy;

  import android.frameworks.automotive.powerpolicy.CarPowerPolicy;
  import android.frameworks.automotive.powerpolicy.CarPowerPolicyFilter;
  import android.frameworks.automotive.powerpolicy.ICarPowerPolicyChangeCallback;
  import android.frameworks.automotive.powerpolicy.PowerComponent;

  /**
   * ICarPowerPolicyServer is an interface implemented by the power policy daemon.
   * VHAL changes the power policy and the power policy daemon notifies the change to
   * registered subscribers. When subscribing to policy changes, a filter can be specified so
   * that the registered callbacks can listen only to a specific power component's change.
   */

  @VintfStability
  interface ICarPowerPolicyServer {
    /**
     * Gets the current power policy.
     * @throws IllegalStateException if the current policy is not set.
     */
    CarPowerPolicy getCurrentPowerPolicy();

    /**
     * Gets whether the power component is turned on or off.
     *
     * @param componentId Power component ID defined in PowerComponent.aidl to check power
     * state.
     * @return True if the component's power state is on.
     * @throws IllegalArgumentException if the componentId is invalid.
     */
    boolean getPowerComponentState(in PowerComponent componentId);

    /**
     * Subscribes to power policy change.
     * Notification is sent to the registered callback when the power policy changes and the
     * power state of the components which the callback is interested in changes.
     *
     * @param callback Callback that is invoked when the power policy changes.
     * @param filter The list of components which the callback is interested in.
     * @throws IllegalArgumentException if the callback is already registered.
     * @throws IllegalStateException if the callback is dead.
     */
    void registerPowerPolicyChangeCallback(in ICarPowerPolicyChangeCallback callback,
        in CarPowerPolicyFilter filter);

    /**
     * Unsubscribes from power policy change.
     *
     * @param callback Callback that doesn't want to receive power policy change.
     * @throws IllegalArgumentException if the callback is not registered.
     */
    void unregisterPowerPolicyChangeCallback(in ICarPowerPolicyChangeCallback callback);

    /**
     * Applies the power policy.
     *
     * 
{@code policyId} should be one of power policy IDs defined in
     * {@code /vendor/etc/automotive/power_policy.xml} or predefined system power policies.
     *
     * @param policyId ID of power policy.
     * @throws IllegalArgumentException if {@code policyId} is invalid.
     */
    void applyPowerPolicy(in @utf8InCpp String policyId);

    /**
     * Sets the current power policy group.
     *
     * 
{@code policyGroupId} should be one of power policy group IDs defined in
     * {@code /vendor/etc/automotive/power_policy.xml}.
     *
     * @param policyGroupId ID of power policy group.
     * @throws IllegalArgumentException if {@code policyGroupId} is invalid.
     */
    void setPowerPolicyGroup(in @utf8InCpp String policyGroupId);
  }

ICarPowerPolicyChangeCallback.aidl

  package android.frameworks.automotive.powerpolicy;

  import android.frameworks.automotive.powerpolicy.CarPowerPolicy;

  /**
   * ICarPowerPolicyChangeCallback is notified when a power policy changes.
   */

  @VintfStability
  oneway interface ICarPowerPolicyChangeCallback {
    /**
     * Called when a power policy is fully changed.
     *
     * @param policy The current policy.
     */
    void onPolicyChanged(in CarPowerPolicy policy);
  }

Interaction with Java modules

CarPowerManager provides methods to enable power policy management:

• Get the current power policy
• Apply a new power policy
• Set a new power policy group

Only system-privileged modules can use the methods. Modules that want to be informed when a power policy is applied can register a power policy change listener to CarPowerManager