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 lo contrario, se deben implementar todos los métodos.

Método
VehiclePropConfigs getAllPropConfigs()
Devuelve una lista de todas las configuraciones de propiedades que admite este sistema HAL del vehículo.
VehiclePropConfigs getPropConfigs(in int[] props)
Devuelve una lista de configuraciones de propiedades para 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 onGetValues de devolución de llamada.
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 onSetValues de devolución de llamada.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Se suscribe a los eventos de la propiedad con las 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)
Cancela la suscripción a los eventos de propiedades a los que te suscribiste anteriormente para propiedades especificadas.
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 los 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.
En el caso de la propiedad ON_CHANGE, un evento de propiedad ocurre cuando cambia el valor o el estado de una propiedad.
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.

La implementación de VHAL se valida con la VTS de VHAL en VtsHalAutomotiveVehicle_TargetTest.cpp. La prueba verifica que los métodos básicos se implementen correctamente y que las configuraciones de la propiedad 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 sincroniza 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 que uses un subproceso de controlador independiente para controlar las solicitudes de forma asíncrona. Consulta la Implementación de referencia para obtener más detalles.

Figura 1: Proceso asíncrono.

Elementos 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 Es una 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 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 es 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 de LargeParcelable. En el caso de las implementaciones de VHAL y los clientes nativos, se debe serializar y deserializar un 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<LargeParcelableBase::BorrowedOwnedObject, 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.
}