Power management

To support vehicle-specific power management, Android provides a CarPowerManagementService service and a CarPowerManager interface.

State transitions are triggered by the Vehicle Master Control Unit (VMCU). To communicate with the VMCU, integrators must implement several components. Integrators are responsible for integrating with the Vehicle hardware abstraction layer (VHAL) and the kernel implementation. Integrators are also responsible for disabling wake sources and ensuring that shutdowns aren't postponed indefinitely.

Terminology

These terms are used throughout this document:

System design

This section describes how AAOS represents the app processor's power state and which modules implement the power management system. This material also describes how these modules work together and how state transitions typically occur.

Car power state machine

AAOS uses a state machine to represent the power state of the AP. The state machine provides the states illustrated below:

Figure 1. Car power state machine.

The most common transitions are highlighted in blue. These are the states and common transitions:

• Suspend-to-RAM. The vehicle and the SoC are off. No code is being executed. Power is maintained to the SoC RAM.
• Wait for VHAL. When the driver interacts with the vehicle, for example, by opening a door, the VMCU applies power to the SoC. AAOS resumes from Suspend-to-RAM and enters Wait for VHAL, where it awaits coordination with the VHAL.
• On. The VHAL tells AAOS to enter the On state. In this state, AAOS is fully running and interacting with the driver.
• Shutdown Prepare. When the driver is finished with driving, the VHAL tells AAOS to enter Shutdown Prepare. In this state, the display and audio are off and AAOS isn't interacting with the driver. The Android system is still running and is free to update apps and the Android system. When updates, if any, are completed, the Android system enters Wait for VHAL Finish.
• Wait for VHAL Finish. At this point, AAOS informs the VHAL that it is ready to shut down. The VMCU is expected to place the SoC in Deep Sleep and to remove power from the app processor. AAOS is then in the Suspend-to-RAM state, although no code is being executed.

Power management modules

The power management system is comprised of these modules:

The deep sleep/hibernation feature (suspending Android to RAM/disk) is implemented in the kernel. This feature is exposed to the user space as a special file located at /sys/power/state. AAOS is suspended by writing mem or disk to this file.

The CPMS coordinates the power state with other services and HALs. The CPMS implements the state machine described above and sends notifications to every observer when a power state transition occurs. This service also uses the VHAL to send messages to the hardware.

The CPPD manages the power policy until the CPMS takes control. It also sends power policy change notifications to the native listeners.

Some properties are defined in the VHAL. To communicate with the VMCU, the CPMS reads and writes these properties. apps can use the interface defined in the CPM to monitor power state changes. This interface also enables apps to register power policy listeners. This API can be called from Java and is annotated with @hide / @System API, which means it is available to privileged apps only. The relationship between these modules, apps, and services is illustrated below:

Figure 2. Power components reference diagram.

Message sequence

The previous section described the modules that comprise the power management system. This section uses the enter deep sleep and exit deep sleep examples to explain how the modules and apps communicate:

Enter deep sleep

Only the VMCU can initiate deep sleep. Once deep sleep is initiated, the VMCU sends a notification to the CPMS via the VHAL. The CPMS changes the state to SHUTDOWN PREPARE and broadcasts this state transition to all observers (the apps and services that monitor CPMS) by calling the onStateChanged() method with a new state ID provided by the CPM.

The CPM mediates between the apps/services and the CPMS. The onStateChanged() method for the apps/services is synchronously invoked in the CPM's onStateChanged() method. Most apps and services are required to complete their preparation before returning from this call. Privileged services are allowed to continue their preparations asynchronously after returning for PRE_SHUTDOWN_PREPARE, SUSPEND_ENTER, POST_SUSPEND_ENTER. In this case, the privileged service is supposed to call complete() on the provided CompletablePowerStateChangeFuture object when it finishes its preparation. Note that asynchronous preparation isn't allowed for SHUTDOWN_PREPARE. Before DEEP_SLEEP_ENTRY is sent to the VHAL, the CPMS periodically sends shutdown postpone requests to the VHAL.

When all CPM objects have completed shutdown preparations, the CPMS sends AP_POWER_STATE_REPORT to the VHAL, which then notifies the VMCU that the AP is ready to suspend. The CPMS also calls its suspend method, which suspends the kernel.

The sequence described above is illustrated below:

Figure 3. Enter deep sleep.

Programming interfaces provided by CPM

This section describes the Java API provided by the CPM for system apps and services. This API enables the system software to:

• Monitor power state changes in the AP.
• Apply power policies.

Use these steps to call the APIs provided by the CPM:

1. To acquire the CPM instance, call the Car API.
2. Call the appropriate method on the object created in Step 1.

Create a CarPowerManager object

To create a CPM object, call the Car object's getCarManager() method. This method is a facade used to create CPM objects. Specify android.car.Car.POWER_SERVICE as an argument to create a CPM object.

Car car = Car.createCar(this);
CarPowerManager powerManager =
  (CarPowerManager) car.getCarManager(android.car.Car.POWER_SERVICE);

CarPowerStateListener and registration

System apps and services can receive power state change notifications by implementing CarPowerManager.CarPowerStateListener. This interface defines one method onStateChanged(), which is a callback function invoked when the power state of CPMS is changed. The following example defines a new anonymous class that implements the interface:

private final CarPowerManager.CarPowerStateListener powerListener =
  new CarPowerManager.CarPowerStateListener () {
    @Override
     public void onStateChanged(int state) {
       Log.i(TAG, "onStateChanged() state = " + state);
     }
};

To instruct this listener object to monitor a power state transition, create a new execution thread and register the listener and this thread to the CPM object:

executor = new ThreadPerTaskExecutor();
powerManager.setListener(powerListener, executor);

When the power state is changed, the onStateChanged() method of the listener object is invoked with a value to represent the new power state. The association between actual value and power state is defined in CarPowerManager and is shown in the following table:

CarPowerStateListener unregistration

To unregister all listener objects registered to CPM, call the clearListener method:

powerManager.clearListener();

System integration on your Android implementation

Integrators are responsible for the following items:

• Implementing the kernel interface to suspend Android.
• Implementing the VHAL functions to:
  • Propagate the initiation of suspend or shutdown from the car to Android.
  • Send the shutdown ready message from Android to the car.
  • Initiate shutdown or suspend of Android through the Linux kernel interface.
• Ensure that all wakesources are disabled when the device is in suspend.
• Ensure that apps shut down quickly enough so as not to indefinitely postpone the shutdown process.
• Ensure that the BSP turns on (or off) device components according to the power policy so as not to block suspend or hibernation

Kernel interface: /sys/power/state

AAOS places a device into suspend mode when an app or service writes mem for suspend-to-RAM or disk for suspend-to-disk into a file located at /sys/power/state. The integrator must provide a function that monitors this file and puts Linux into the suspend power state. This function may send a GPIO to the VMCU to notify the VMCU that the device has shut down completely. The integrator is also responsible for removing any race conditions between VHAL sending the final message to the VMCU and the system going into suspend or shutdown mode.

VHAL responsibility

The VHAL provides an interface between the vehicle network and Android. The VHAL:

• Propagates the initiation of suspend or shutdown from the car to Android.
• Sends the shutdown ready message from Android to the car.
• Initiates the shutdown or suspend of Android via the Linux kernel interface.

When the CPMS informs the VHAL that it is ready to shut down, the VHAL sends the shutdown ready message to the VMCU. Typically, on-chip peripherals such as UART, SPI, and USB transmit the message. Once the message has been sent, the CPMS calls the kernel command to suspend or shutdown the device. Before doing so, the VHAL or BSP may toggle a GPIO to instruct the VMCU that it is safe to remove power from the device.

The VHAL must support the following properties, which control power management via the VHAL:

AP_POWER_STATE_REPORT

Use this property to report Android's current power management state. This property contains two integers:

• int32Values[0]: VehicleApPowerStateReport enum of the current state.
• int32Values[1]: Time in milliseconds to postpone or sleep or shutdown. The meaning of this value depends on the first value.

The first value can take one of the following values. VehicleApPowerStateReport.aidl contains more specific descriptions, which are stored in the hardware/interfaces/automotive/vehicle/aidl/android/hardware/automotive/vehicle.

The state can be set autonomously or in response to a request via the VMCU.

AP_POWER_STATE_REQ

This property is sent by the VMCU to transition Android into a different power state and contains two integers:

• int32Values[0]: VehicleApPowerStateReq enum value, which represents the new state into which to transition.
• int32Values[1]: VehicleApPowerStateShutdownParam enum value. This value is sent only for a SHUTDOWN_PREPARE message and transmits to Android the options it contains.

The first integer value represents the new state into which Android is to transit. The semantics are defined in VehicleApPowerStateReq.aidl and provided below:

VehicleApPowerStateShutdownParam is defined in VehicleApPowerStateShutdownParam.aidl. This enum has these elements:

Wake sources

The integrator must disable the appropriate wake sources when the device is in suspend mode. Common wake sources include heartbeats, modem, Wi-Fi, and Bluetooth. The only valid wake source must be an interrupt from the VMCU to wake up the SoC. This assumes that the VMCU can listen to the modem for remote wakeup events (such as remote engine start). If this functionality is pushed to the AP, then another wake source to service the modem must be added.

Apps

OEMs must be careful to write apps so that they can be shut down quickly and not postpone the process indefinitely.

Appendix

Directories in the source code tree

Class diagram

This class diagram displays the Java classes and interfaces in the power management system:

Figure 4. Power class diagram.

Object relationship

Figure 5 illustrates which objects have references to other objects. An edge means that the source object holds a reference to the target object. For example, VehicleHAL has a reference to a PropertyHalService object.

Figure 5. Object reference diagram.