Administración de energía

Para admitir la administración de energía específica del vehículo, Android proporciona un servicio CarPowerManagementService y una interfaz CarPowerManager.

Las transiciones de estado se activan con la unidad de control principal del vehículo (VMCU). Para comunicarse con la VMCU, los integradores deben implementar varios componentes. Los integradores son responsables de la integración con la capa de abstracción de hardware del vehículo (VHAL) y la implementación del kernel. Los integradores también son responsables de inhabilitar las fuentes de activación y garantizar que los apagados no se pospongan de forma indefinida.

Terminología

En este documento, se utilizan los siguientes términos:

Diseño de sistemas

En esta sección, se describe cómo AAOS representa el estado de energía del procesador de la app y qué módulos implementan el sistema de administración de energía. Este material también describe cómo funcionan estos módulos en conjunto y cómo suelen ocurrir las transiciones de estado.

Máquina de estado de potencia del automóvil

AAOS usa una máquina de estados para representar el estado de energía del AP. La máquina de estados proporciona los estados que se ilustran a continuación:

Figura 1: Máquina de estado de potencia del automóvil.

Las transiciones más comunes se destacan en azul. Estos son los estados y las transiciones comunes:

• Suspender a RAM. El vehículo y el SoC están apagados. No se ejecuta ningún código. Se mantiene la energía en la RAM del SoC.
• Espera a que se cargue el VHAL. Cuando el conductor interactúa con el vehículo, por ejemplo, abriendo una puerta, la VMCU aplica energía al SoC. AAOS se reanuda desde la suspensión a RAM y entra en Wait for VHAL, donde espera la coordinación con el VHAL.
• Activado. El VHAL le indica a AAOS que ingrese al estado On. En este estado, AAOS se ejecuta por completo y puede interactuar con el conductor.
• Preparación previa a la desactivación permanente. Cuando el conductor termina de conducir, el VHAL le indica a AAOS que ingrese a la fase de preparación previa al apagado enviando SHUTDOWN_PREPARE. En este estado, los objetos de escucha de cambios de estado de energía reciben STATE_PRE_SHUTDOWN_PREPARE. Esto sirve como una advertencia anticipada de que se está iniciando el cierre.
• Preparación para el apagado. Cuando todos los objetos de escucha completan su tarea o se alcanza el tiempo de espera de Pre Shutdown Prepare, el sistema Android ingresa en la fase principal de Shutdown Prepare y notifica a los objetos de escucha con STATE_SHUTDOWN_PREPARE. La pantalla y el audio están apagados, y AAOS no interactúa con el conductor. El sistema Android sigue en ejecución y puede realizar operaciones de limpieza y actualización, como ejecutar el modo Garage.
• Wait for VHAL Finish. En este punto, AAOS informa a VHAL que está listo para apagarse. Se espera que la VMCU coloque el SoC en suspensión profunda y quite la alimentación del procesador de aplicaciones. Luego, AAOS se encuentra en el estado de suspensión a RAM, aunque no se ejecuta ningún código.

Módulos de administración de energía

El sistema de administración de energía consta de los siguientes módulos:

La función de suspensión profunda/hibernación (suspensión de Android en la RAM o el disco) se implementa en el kernel. Esta función se expone al espacio del usuario como un archivo especial ubicado en /sys/power/state. Para suspender AAOS, se escribe mem o disk en este archivo.

El CPMS coordina el estado de energía con otros servicios y HAL. El CPMS implementa la máquina de estados descrita anteriormente y envía notificaciones a cada observador cuando se produce una transición de estado de energía. Este servicio también usa la VHAL para enviar mensajes al hardware.

El CPPD es la fuente de información para las políticas de energía. Administra las políticas de energía durante todo el ciclo de vida del dispositivo y notifica los cambios en las políticas de energía al CPMS, al VHAL y a otros objetos de escucha nativos. El CPMS delega las solicitudes de cambio de política de energía al CPPD.

El CPMS se comunica con la VMCU leyendo y escribiendo propiedades de VHAL relacionadas con el estado de energía, como AP_POWER_STATE_REQ y AP_POWER_STATE_REPORT. Las apps pueden usar la interfaz definida en CPM para supervisar los cambios de estado de energía. Esta interfaz también permite que las apps registren objetos de escucha de políticas de energía. Esta API de Java está anotada con @SystemApi y @hide, lo que la hace disponible solo para apps con privilegios. A continuación, se ilustra la relación entre estos módulos, apps y servicios:

Figura 2: Diagrama de referencia de los componentes de alimentación.

Secuencia de mensajes

En la sección anterior, se describieron los módulos que componen el sistema de administración de energía. En esta sección, se usan los ejemplos de ingreso en suspensión y salida de suspensión para explicar cómo se comunican los módulos y las apps:

Entrar en sueño profundo

Solo la VMCU puede iniciar el modo de suspensión profunda. Una vez que se inicia el modo de suspensión profunda, la VMCU envía una notificación al CPMS a través del VHAL. El CPMS cambia el estado a SHUTDOWN PREPARE y transmite esta transición de estado a todos los observadores (las apps y los servicios que supervisan el CPMS) llamando al método onStateChanged() con un nuevo ID de estado proporcionado por el CPM.

El CPM media entre las apps o los servicios y el CPMS. El método onStateChanged() para las apps o los servicios se invoca de forma síncrona en el método onStateChanged() del CPM. La mayoría de las apps y los servicios deben completar su preparación antes de volver de esta llamada. Los servicios privilegiados pueden continuar con sus preparaciones de forma asíncrona después de regresar para PRE_SHUTDOWN_PREPARE, SUSPEND_ENTER y POST_SUSPEND_ENTER. En este caso, se supone que el servicio con privilegios llama a complete() en el objeto CompletablePowerStateChangeFuture proporcionado cuando finaliza su preparación. Ten en cuenta que no se permite la preparación asíncrona para SHUTDOWN_PREPARE. Antes de que se envíe DEEP_SLEEP_ENTRY al VHAL, el CPMS envía periódicamente solicitudes de aplazamiento del cierre al VHAL.

Cuando todos los objetos CPM completaron los preparativos para el cierre, el CPMS envía AP_POWER_STATE_REPORT al VHAL, que luego notifica al VMCU que el AP está listo para suspenderse. El CPMS también llama a su método de suspensión, que suspende el kernel.

La secuencia descrita anteriormente se ilustra a continuación:

Figura 3: Entrar en suspensión profunda

Interfaces de programación proporcionadas por CPM

En esta sección, se describe la API de Java que proporciona el CPM para las apps y los servicios del sistema. Esta API permite que el software del sistema realice las siguientes acciones:

• Supervisa los cambios de estado de energía en el AP.
• Aplica políticas de energía.

Sigue estos pasos para llamar a las APIs que proporciona el CPM:

1. Para adquirir la instancia de CPM, llama a la API de Car.
2. Llama al método adecuado en el objeto creado en el paso 1.

Crea un objeto CarPowerManager

Para crear un objeto CPM, llama al método getCarManager() del objeto Car. Este método es una fachada que se usa para crear objetos de CPM. Especifica android.car.Car.POWER_SERVICE como argumento para crear un objeto CPM.

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

CarPowerStateListener y registro

Las apps y los servicios del sistema pueden recibir notificaciones de cambio de estado de energía implementando CarPowerManager.CarPowerStateListener. Esta interfaz define un método onStateChanged(), que es una función de devolución de llamada que se invoca cuando cambia el estado de energía del CPMS. En el siguiente ejemplo, se define una nueva clase anónima que implementa la interfaz:

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

Para indicarle a este objeto de escucha que supervise una transición de estado de energía, crea un nuevo subproceso de ejecución y registra el objeto de escucha y este subproceso en el objeto CPM:

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

Cuando cambia el estado de energía, se invoca el método onStateChanged() del objeto de escucha con un valor que representa el nuevo estado de energía. La asociación entre el valor real y el estado de energía se define en CarPowerManager y se muestra en la siguiente tabla:

Anulación del registro de CarPowerStateListener

Para anular el registro de todos los objetos de escucha registrados en CPM, llama al método clearListener:

powerManager.clearListener();

Integración del sistema en tu implementación para Android

Los integradores son responsables de los siguientes elementos:

• Implementa la interfaz del kernel para suspender Android.
• Implementa las funciones de VHAL para hacer lo siguiente:
  • Propaga el inicio de la suspensión o el apagado del automóvil a Android.
  • Envía el mensaje de que el auto está listo para apagarse desde Android al auto.
  • Inicia el apagado o la suspensión de Android a través de la interfaz del kernel de Linux.
• Asegúrate de que todas las fuentes de activación estén inhabilitadas cuando el dispositivo esté en suspensión.
• Asegúrate de que las apps se cierren lo suficientemente rápido para no posponer indefinidamente el proceso de cierre.
• Asegúrate de que el BSP encienda (o apague) los componentes del dispositivo según la política de energía para no bloquear la suspensión o la hibernación.

Interfaz del kernel: /sys/power/state

AAOS coloca un dispositivo en modo de suspensión cuando una app o un servicio escriben mem para la suspensión en RAM o disk para la suspensión en disco en un archivo ubicado en /sys/power/state. El integrador debe proporcionar una función que supervise este archivo y coloque Linux en el estado de energía de suspensión. Esta función puede enviar un GPIO a la VMCU para notificarle que el dispositivo se apagó por completo. El integrador también es responsable de quitar cualquier condición de carrera entre el envío del mensaje final del VHAL al VMCU y el momento en que el sistema entra en modo de suspensión o apagado.

Responsabilidad del VHAL

La VHAL proporciona una interfaz entre la red del vehículo y Android. El VHAL:

• Propaga el inicio de la suspensión o el apagado del automóvil a Android.
• Envía el mensaje de preparación para el apagado de Android al automóvil.
• Inicia el apagado o la suspensión de Android a través de la interfaz del kernel de Linux.

Cuando el CPMS informa al VHAL que está listo para apagarse, el VHAL envía el mensaje de apagado listo al VMCU. Por lo general, los periféricos integrados en el chip, como UART, SPI y USB, transmiten el mensaje. Una vez que se envía el mensaje, el CPMS llama al comando del kernel para suspender o apagar el dispositivo. Antes de hacerlo, el VHAL o el BSP pueden activar o desactivar un GPIO para indicarle a la VMCU que es seguro quitar la alimentación del dispositivo.

El VHAL debe admitir las siguientes propiedades, que controlan la administración de energía a través del VHAL:

AP_POWER_STATE_REPORT

Usa esta propiedad para informar el estado actual de administración de energía de Android. Esta propiedad contiene dos números enteros:

• int32Values[0]: Es la enumeración VehicleApPowerStateReport del estado actual.
• int32Values[1]: Tiempo en milisegundos para posponer, suspender o apagar. El significado de este valor depende del primer valor.

El primer valor puede tomar uno de los siguientes valores. VehicleApPowerStateReport.aidl contiene descripciones más específicas, que se almacenan en hardware/interfaces/automotive/vehicle/aidl/android/hardware/automotive/vehicle.

El estado se puede establecer de forma autónoma o en respuesta a una solicitud a través de la VMCU.

AP_POWER_STATE_REQ

El VMCU envía esta propiedad para que Android realice la transición a un estado de energía diferente, y contiene dos números enteros:

• int32Values[0]: Valor de enumeración VehicleApPowerStateReq que representa el nuevo estado al que se realizará la transición.
• int32Values[1]: Es el valor de enumeración VehicleApPowerStateShutdownParam. Este valor se envía solo para un mensaje SHUTDOWN_PREPARE y transmite a Android las opciones que contiene.

El primer valor entero representa el nuevo estado al que debe transicionar Android. La semántica se define en VehicleApPowerStateReq.aidl y se proporciona a continuación:

VehicleApPowerStateShutdownParam se define en VehicleApPowerStateShutdownParam.aidl. Este enum tiene los siguientes elementos:

Fuentes de activación

El integrador debe inhabilitar las fuentes de activación adecuadas cuando el dispositivo está en modo de suspensión. Las fuentes de activación comunes incluyen los latidos del corazón, el módem, el Wi-Fi y el Bluetooth. La única fuente de activación válida debe ser una interrupción de la VMCU para activar el SoC. Esto supone que la VMCU puede escuchar el módem para detectar eventos de activación remota (como el arranque remoto del motor). Si esta funcionalidad se envía al AP, se debe agregar otra fuente de activación para dar servicio al módem.

Aplicaciones

Los OEM deben tener cuidado al escribir apps para que se puedan cerrar rápidamente y no posponer el proceso de forma indefinida.

Apéndice

Directorios en el árbol del código fuente

Diagrama de clases

En este diagrama de clases, se muestran las clases e interfaces de Java en el sistema de administración de energía:

Figura 4: Diagrama de clases de potencia.

Relación de objeto

En la figura 5, se ilustra qué objetos tienen referencias a otros objetos. Una arista significa que el objeto de origen contiene una referencia al objeto de destino. Por ejemplo, VehicleHAL tiene una referencia a un objeto PropertyHalService.

Figura 5: Diagrama de referencia de objetos.