Interfaz de VHAL

El VHAL de AIDL se define en android.hardware.automotive.vehicle namespace. La interfaz de VHAL se define en IVehicle.aidl. A menos que se especifique, se deben implementar todos los métodos.

Método
VehiclePropConfigs getAllPropConfigs() Muestra una lista de todas las configuraciones de la propiedad que admite esta HAL del vehículo.
VehiclePropConfigs getPropConfigs(in int[] props) Devuelve una lista de configuraciones de propiedades para los IDs de propiedades determinados.
void getValues(IVehicleCallback callback, in GetValueRequests requests) Obtén los valores de las propiedades del vehículo de forma asíncrona. Controla un lote de GetValueRequest de forma asíncrona. El resultado se entrega a través del método de devolución de llamada onGetValues.
void setValues(IVehicleCallback callback, in SetValueRequests requests) Establece los valores de las propiedades del vehículo de forma asíncrona. Controla un lote de SetValueRequest de forma asíncrona. El resultado se entrega a través del método de devolución de llamada onSetValues.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount) Se suscribe a eventos de propiedades con opciones especificadas. Las opciones de suscripción incluyen el ID de la propiedad, el ID del área de la propiedad y la tasa de muestreo en Hz (para una propiedad continua). maxSharedMemoryFileCount no se usa.
void unsubscribe(in IVehicleCallback callback, in int[] propIds) Anula la suscripción de los eventos de propiedades a las que te suscribiste anteriormente en relación con propiedades específicas.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId) No se usa y se puede implementar como no-op.

Las devoluciones de llamada se definen en IVehicleCallback.aidl y contienen estos métodos.

Método
oneway void onGetValues(in GetValueResults responses) Devolución de llamada para la función getValues para entregar resultados de valor de obtención. Se llama cuando algunos de los valores que se recuperarán están listos.
oneway void onSetValues(in SetValueResults responses) Devolución de llamada para la función setValues para entregar resultados de valores establecidos. Se llama cuando VHAL termina de controlar algunas de las solicitudes de conjunto de propiedades.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount) Es una devolución de llamada para informar eventos de actualización de propiedades. En la propiedad CONTINUOUS, un evento de propiedad se produce en función de la tasa de muestreo de suscripción en Hz o la frecuencia de mensajes del bus del vehículo. También puede ocurrir un evento de propiedad si cambia el estado de una propiedad. Por ejemplo, de no disponible a disponible. Para la propiedad ON_CHANGE, se produce un evento de propiedad cuando cambia su valor o estado. SharedMemoryFileCount siempre es 0.
oneway void onPropertySetError(in VehiclePropErrors errors) Es una devolución de llamada para informar errores asíncronos de conjuntos de propiedades que no tienen una solicitud de conjunto correspondiente. Si sabemos para qué solicitud de conjunto es el error, se debe usar onSetValues con un resultado de error en su lugar.

Para obtener más información, consulta IVehicle.aidl y IVehicleCallback.aidl.

El VTS de VHAL valida la implementación de VHAL en VtsHalAutomotiveVehicle_TargetTest.cpp. La prueba verifica que los métodos básicos se implementen correctamente y que las configuraciones de las propiedades compatibles sean correctas.

Valor de la propiedad del vehículo

Usa la estructura VehiclePropValue para describir el valor de cada propiedad, que tiene estos campos:

Campo	Descripción
timestamp	Es la marca de tiempo que representa la hora en que ocurrió el evento y se sincronizó con el reloj SystemClock.elapsedRealtimeNano().
prop	Es el ID de la propiedad para este valor.
areaid	El ID del área para este valor. El área debe ser una de las áreas admitidas que se indican en la configuración del ID de área o 0 para propiedades globales.
value	Es una estructura de datos que contiene el valor real de la propiedad. Según el tipo de propiedad, se usan uno o más campos dentro de este campo para almacenar el valor real. Por ejemplo, el primer elemento en value.int32Values se usa para propiedades de tipo Int32. Para obtener más información, consulta Configuraciones de la propiedad.

getValues y setValues asíncronos

Las operaciones getValues y setValues se realizan de forma asíncrona, lo que significa que la función puede mostrarse antes de que se complete la operación de obtención o configuración real. Los resultados de la operación (por ejemplo, el valor de la propiedad para getValues y el estado de error o de éxito para setValues) se entregan a través de las devoluciones de llamadas que se pasan como argumentos.

La implementación no debe bloquearse en el resultado del subproceso de Binder que controla la solicitud. En su lugar, te recomendamos que almacenes la solicitud en una cola de solicitudes y uses un subproceso de controlador separado para manejar las solicitudes de forma asíncrona. Consulta la Implementación de referencia para obtener más detalles.

Figura 1: Proceso asíncrono.

Objetos parcelables grandes

Todas las estructuras denominadas XXXs, como VehiclePropConfigs, SetValueRequests y VehiclePropValues, se denominan LargeParcelable (o StableLargeParcelable). Cada una representa una lista de valores que se usan para pasar datos grandes que podrían superar las limitaciones de Binder (4 KB en la implementación de la biblioteca LargeParcelable) en los límites de Binder. Cada uno tiene una definición de estructura similar que contiene los siguientes campos.

Orientación	Descripción
payloads	Lista de valores cuando el tamaño del valor se ajusta a una limitación de memoria de Binder o una lista vacía.
sharedMemoryFd	Es un descriptor de archivo nulo que apunta a un archivo de memoria compartida que almacena las cargas útiles serializadas si la lista de valores es demasiado grande.

Por ejemplo, VehiclePropConfigs se define de la siguiente manera:

parcelable VehiclePropConfigs {
    // The list of vehicle property configs if they fit the binder memory
    // limitation.
    VehiclePropConfig[] payloads;
    // Shared memory file to store configs if they exceed binder memory
    // limitation. Created by VHAL, readable only at client. Client could keep
    // the fd opened or keep the FD mapped to access configs.
    @nullable ParcelFileDescriptor sharedMemoryFd;
}

VehiclePropConfigs contiene cargas útiles no vacías o un sharedMemoryFd no nulo.

• Si payloads no está vacío, almacena una lista de los datos reales, que son la configuración de la propiedad.
• Si sharedMemoryFd no es nulo, contiene un archivo de memoria compartida, que almacena la estructura serializada de VehiclePropConfigs. La estructura usa la función writeToParcel para serializar un Parcel.

Como cliente de Java para VHAL, Car Service controla la serialización y deserialización para LargeParcelable. En el caso de las implementaciones de VHAL y los clientes nativos, se debe serializar y deserializar una LargeParcelable con la biblioteca LargeParcelable o una clase de wrapper útil para la biblioteca en ParcelableUtils.h.

Por ejemplo, un cliente nativo que analiza solicitudes de getValues recibidas de un vinculador es el siguiente:

// 'requests' are from the binder.
GetValueRequests requests;
expected, ScopedAStatus> deserializedResults = fromStableLargeParcelable(requests);
if (deserializedResults.ok()) {
    const std::vector& getValueRequests = deserializedResults.value().getObject()->payloads;
    // Use the getValueRequests.
  } else {
    // handle error.
}

A continuación, se muestra una implementación de VHAL de ejemplo que envía resultados para getValues a través del Binder:

std::vector results = getResults();
GetValueResults parcelableResults;
ScopedAStatus status = vectorToStableLargeParcelable(std::move(results), &parcelableResults);
if (status.isOk()) {
    // Send parcelableResults through callback.
} else {
    // Handle error.
}