To implement deep sleep, Android Automotive OS (AAOS) 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 are not postponed indefinitely.
Terminology
These terms are used throughout this document:
Term | Description |
---|---|
Application Processor (AP) | Part of the System on a Chip (SoC). |
Board Support Processor (BSP) | All of the chip and hardware specific code necessary for the product to work. Typically provided by the SoC vendor and hardware manufacturer. This covers items such as device drivers, the PMIC sequencing code, and SoC bringup. |
CarPowerManager (CPM) | Exposes an API for applications to register for power state changes. |
CarPowerManagementService (CPMS) | Implements the car power state machine, interfaces with VHAL, and performs the final calls to
suspend() and shutdown() . |
CarServiceHelperService (CSHS) | Provides a hook into SystemServer for OK, provided that is the Car Service. |
General Purpose Input/Output (GPIO) | A digital signal pin for general purpose use. |
Hibernate | Also referred to as Suspend to Disk (S2D/S4). The SoC is placed into S4 power mode (hibernate) and RAM content is written to non-volatile media (such as flash or disk) and the entire system is powered off. AAOS does not currently implement hibernate. |
Media Processor (MP) | See System on a Chip (SoC). |
Power Management Integrated Circuit (PMIC) | Chip used to manage power requirements for the host system. |
System on a Chip (SoC) | Main processor that runs AAOS, typically supplied by manufacturers such as Intel, MediaTek, Nvidia, Qualcomm, Renesas, and Texas Instruments. |
Suspend | Also referred to as Suspend-to-RAM (S2R or STR). The SoC is placed into S3 power mode and the CPU is powered off while RAM remains powered on. |
Vehicle HAL (VHAL) | The Android API used to interface with the vehicle network. The Tier 1 partner or OEM is responsible for writing this module. The vehicle network can use any physical layer (such as CAN, LIN, MOST, and Ethernet). The VHAL abstracts this vehicle network to enable AAOS to interact with the vehicle. |
Vehicle Interface Processor (VIP) | See Vehicle MCU. |
Vehicle Master Control Unit (VMCU) | The microcontroller that provides the interface between the vehicle network and the SoC. The SoC communicates with the VMCU via USB, UART, SPI, and GPIO signals. |
System design
This section describes how AAOS represents the application 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 beig 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 driving, the VHAL tells AAOS to enter Shutdown Prepare. In this state, the display and audio are off and AAOS is not 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 Application 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:
Module name | Description |
---|---|
CarPowerManager | Java/C++ API. |
CarPowerManagementService | Coordinates the Sleep/Suspend power state. |
Vehicle HAL | Interface to the VMCU. |
libsuspend | Native library to place the device into suspend. |
Kernel | Suspend to RAM implementation. |
The deep sleep feature (suspending Android to RAM) 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
to this file.
libsuspend
is a native library that implements forcesuspend()
. This
function uses /sys/power/state
to suspend AAOS. forcesuspend()
can be
called from system services, including CPMS.
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 libsuspend
and the VHAL to send messages to the
hardware.
Some properties are defined in the VHAL. To communicate with the VMCU, the CPMS reads and writes these properties. Applications can use the interface defined in the CPM to monitor power state changes. This interface also enables applications to acquire the boot reason and to send shutdown requests. This API can be called from Java and C++ and is annotated with @hide / @System API, which means it is available to privileged applications only. The relationship between these five modules, applications, 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 applications 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 applications and services that monitor
CPMS) by calling the onStateChanged()
method with a new state ID provided by the
CPM.
The CPM mediates between the applications/services and the CPMS. The
onStateChanged()
method for the applications/services is synchronously invoked in the
CPM's onStateChanged()
method. Most applications and services are required to complete
their preparation before returning from this call. Privileged services are allowed to continue their
preparations asynchronously after returning. In this case, the privileged service calls finish() on
the provided CompletableFuture object when it finishes its preparation. While waiting for all
preparations to complete, 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 with a feature provided
by libsuspend
.
The sequence described above is illustrated below:
Figure 3. Enter deep sleep
Programming interfaces provided by CPM
This section describes the Java and C++ API provided by the CPM for system applications and services. The process to call the CPM in C++ is identical to that used by the Java API. This API enables the system software to:
- Monitor power state changes in the AP.
- Request the VMCU to shut down the AP rather than suspend, when the VMCU next stops the AP.
PowerTestFragment.java
in com.google.android.car.kitchensink.power
illustrates how to use these APIs in Java. Use these steps to call the APIs provided by the CPM:
- To acquire the CPM instance, call the Car API.
- Call the appropriate method on the object created in Step 1.
Creating a CarPowerManager object
To create a CPM object, call the Car object's getCarManager()
method. This method is
a facade used to create CM objects. Specify android.car.Car.POWER_SERVICE
as an
argument to create a CPM object.
Car car = Car.createCar(this, carCallbacks); CarPowerManager powerManager = (CarPowerManager)car.getCarManager(android.car.Car.POWER_SERVICE);
CarPowerStateListener and registration
System applications 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 listener = 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 PM object:
executer = new ThreadPerTaskExecuter(); powerManager.setListener(powerListener, executer);
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.CarPowerStateListener
and is shown in the
following table:
Name | Description |
---|---|
ON | Enter the on state. The system is fully operational. |
SHUTDOWN_CANCELLED | Shutdown is cancelled and power state is returned to the normal state. |
SHUTDOWN_ENTER | Preparations for shutting down have completed. Enter the shutdown state. |
SHUTDOWN_PREPARE | Applications are expected to clean up and be ready to suspend or shut down. |
SUSPEND_ENTER | Preparations for shutting down have been completed. Enter the suspend state. |
SUSPEND_EXIT | Wake up from suspend or resume from a cancelled suspend. |
WAIT_FOR_VHAL | The system is starting up, but waiting to establish communication with the VHAL before going to the ON state. |
CarPowerStateListener unregistration
To unregister all listener objects registered to CPM, call the clearListener
method:
powerManager.clearListener();
Shutdown request on next suspend
The requestShutdownOnNextSuspend()
method instructs CPMS to shut down instead of deep
sleep at the next opportunity.
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 applications shut down quickly enough so as not to indefinitely postpone the shutdown process.
Kernel interface: /sys/power/state
AAOS places a device into suspend mode when
an application or service writes mem
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 VHAL 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:
Name | Description |
---|---|
AP_POWER_STATE_REPORT | Android reports state transitions to the VMCU with this property, using VehicleApPowerStateReport enum values. |
AP_POWER_STATE_REQ | The VMCU uses this property to instruct Android to transition to different power states, using VehicleApPowerStateReq enum values. |
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. Types.hal
contains more
specific descriptions, which are stored in the
hardware/interfaces/automotive/vehicle/2.0.
Value name | Description | Second value |
---|---|---|
WAIT_FOR_VHAL | AP is starting and needs to establish communication with the VHAL. | |
DEEP_SLEEP_ENTRY | AP is entering the deep sleep state. The VMCU should turn the AP back on after the time specified in the second value. | Must be set |
DEEP_SLEEP_EXIT | AP is exiting the deep sleep state. | |
SHUTDOWN_POSTPONE | Android is not ready to shut down. The VMCU should wait the time specified in the second value before shutting down the AP. Android may request additional postponement by issuing additional SHUTDOWN_POSTPONE reports. | Must be set |
SHUTDOWN_PREPARE | Android is preparing to shut down. | Must be set |
SHUTDOWN_START | AP is ready to shut down. The VMCU should turn the AP back on after the time specified in the second value. (The VMCU is not required to support the timed turn-on feature.) | Must be set |
SHUTDOWN_CANCELLED | Android is ceasing to prepare to shut down and will proceed to WAIT_FOR_VHAL. | |
ON | Android is running normally. |
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 aSHUTDOWN_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 types.hal
and provided below:
Value name | Description |
---|---|
ON | AP should begin full operation. |
SHUTDOWN_PREPARE | The AP should prepare to shut down. The second value indicates if the AP is allowed to postpone shutting down and whether the AP should expect to power off or enter deep sleep. |
CANCEL_SHUTDOWN | The AP should stop preparing to shut down and prepare to go ON. |
FINISHED | The AP will now be shut down or suspended. |
VehicleApPowerStateShutdownParam
is also defined in types.hal
. This
enum has these elements:
Value name | Description |
---|---|
CAN_SLEEP | AP can enter deep sleep instead of shutting down completely. Postponing is allowed. |
SHUTDOWN_ONLY | AP should shut down. Postponing is allowed. Deep sleep is not allowed. |
SLEEP_IMMEDIATELY | AP may enter deep sleep, but must either sleep or shut down immediately. Postponing is not allowed. |
SHUTDOWN_IMMEDIATELY | AP must shut down immediately. Postponing is not allowed. Deep sleep is not allowed. |
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.
Applications
OEMs must be careful to write applications so that they can be shut down quickly and not postpone the process indefinitely.
Appendix
Directories in the source code tree
Content | Directory |
---|---|
CarPowerManager-related code. | packages/services/Car/car-lib/src/android/car/hardware/power |
CarPowerManagementService and so on. | packages/services/Car/service/src/com/android/car |
Services dealing with the VHAL, such as VehicleHal and HAlClient . |
packages/services/Car/service/src/com/android/car/hal |
VHAL interface and property definitions. | hardware/interfaces/automotive/vehicle/2.0 |
Sample app to provide some idea about the CarPowerManager |
packages/services/Car/tests/EmbeddedKitchenSinkApp/src/com/google/android/car/kitchensink |
libsuspend resides in this directory. |
system/core/libsuspend |
Class diagram
This class diagram displays the Java classes and interfaces in the power management system:
Figure 5. Power class diagram
Object relationship
The following graph 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 6. Object reference diagram