A partir del 27 de marzo de 2025, te recomendamos que uses android-latest-release en lugar de aosp-main para compilar y contribuir a AOSP. Para obtener más información, consulta Cambios en AOSP.

Se usó la API de Cloud Translation para traducir esta página.

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, todos los métodos deben implementarse para una versión específica de VHAL.

Versiones

Versión de Android	Versión más reciente de VHAL	Versión más reciente de la propiedad de VHAL	Versión mínima compatible de VHAL
Android 16	V4	V4	V1
Android 15	V3	V3	V1
Android 14	V2	V2	V1
Android 13	V1	(Interfaz de propiedad de VHAL no dividida)	V1

Se RECOMIENDA implementar la versión más reciente de VHAL para una versión específica de Android.

Funciones y devoluciones de llamada

Las funciones de VHAL se definen en IVehicle.aidl.

Método
`VehiclePropConfigs getAllPropConfigs()` Devuelve una lista de todas las configuraciones de propiedades compatibles con este HAL del vehículo.
`VehiclePropConfigs getPropConfigs(in int[] props)` Devuelve una lista de configuraciones de propiedades para los IDs de propiedad proporcionados.
`void getValues(IVehicleCallback callback, in GetValueRequests requests)` Obtén valores de propiedades de vehículos 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 valores de 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 frecuencia de muestreo en Hz (para una propiedad continua). No se usa `maxSharedMemoryFileCount`.
`void unsubscribe(in IVehicleCallback callback, in int[] propIds)` Cancela la suscripción a los eventos de propiedad suscritos anteriormente para las propiedades especificadas.
`returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)` No se usa y se puede implementar como una operación sin efecto.
(Nuevo en Android 16) `SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)` Obtiene las listas de valores admitidos para los pares de ID de propiedad y de área especificados. Se introdujo en VHAL V4.
(Novedad en Android 16) `MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)` Obtiene los valores mínimos y máximos admitidos para los pares de ID de propiedad y de área especificados. Se introdujo en VHAL V4.
`void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)` Registra una devolución de llamada para que se llame cuando cambien los valores admitidos. Se introdujo en VHAL V4.
`void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)` Anula el registro de la devolución de llamada de cambio de valor admitida. Se introdujo en VHAL V4.

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 que la función `getValues` entregue los resultados de obtener el valor. 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 los resultados del valor establecido. Se llama cuando el VHAL terminó de controlar algunas de las solicitudes de configuración de propiedades.
`oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)` Devolución de llamada para informar eventos de actualización de la propiedad. Propiedad `CONTINUOUS`: Se produce un evento de propiedad según la frecuencia 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. En el caso de la propiedad `ON_CHANGE`, se produce un evento de propiedad cuando cambia el valor o el estado de una propiedad. Esto también se debe usar para enviar eventos de cambio de estado de la propiedad, por ejemplo, cuando la propiedad deja de estar disponible o se produce un error de lectura, se debe enviar un `VehiclePropValue` con un estado de no disponible o de error y un valor vacío. `SharedMemoryFileCount` siempre es `0`.
`oneway void onPropertySetError(in VehiclePropErrors errors)` Devolución de llamada para informar errores de configuración de propiedades asíncronas que no tienen una solicitud de configuración correspondiente. Si sabemos para qué solicitud de configuración es el error, se debe usar `onSetValues` con un resultado de error en lugar de este.
`oneway void onSupportedValueChange(in List propIdAreaIds)` Devolución de llamada para informar los cambios en la lista de valores admitidos o en el valor mínimo y máximo admitidos. Se supone que la entidad que llama debe llamar a `getMinMaxSupportedValue` o `getSupportedValuesLists` para obtener los valores actualizados.

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 propiedades admitidas sean correctas. La prueba se ejecuta en todas las instancias de VHAL del dispositivo. Sin embargo, AAOS solo usa la instancia predeterminada (android.hardware.automotive.vehicle.IVehicle/default).

Valor de la propiedad del vehículo

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

Campo	Descripción
`timestamp`	Es la marca de tiempo que representa el momento en que ocurrió el evento y se sincronizó con el reloj `SystemClock.elapsedRealtimeNano()`.
`prop`	Es el ID de la propiedad para este valor.
`areaid`	Es 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 las 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 de `value.int32Values` se usa para las propiedades de tipo Int32. Para obtener más detalles, consulta Configuraciones de propiedades.
`status`	Es el estado de la propiedad para la lectura. En el caso de la propiedad de lectura y escritura, esto también podría aplicarse a la escritura, pero no está garantizado. Por ejemplo, la propiedad podría estar disponible para la lectura, pero no para la escritura. En ese caso, el estado es `AVAILABLE` y el campo de valor contiene información válida. Nota: Actualmente, no hay forma de que un cliente supervise el estado de escritura de una propiedad de lectura/escritura o de escritura. El cliente solo sabe si la propiedad está disponible para escritura cuando intenta establecer un valor. Importante: Si el estado no es `AVAILABLE`, se debe ignorar el campo de valor. Para conocer los estados posibles, consulta `VehiclePropertyStatus`.

getValues y setValues asíncronos

Las operaciones getValues y setValues se realizan de forma asíncrona, lo que significa que la función podría 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 éxito o error para setValues) se entregan a través de las devoluciones de llamada que se pasan como argumentos.

La implementación no debe bloquear el resultado en el subproceso del vinculador que controla la solicitud. En cambio, te recomendamos que almacenes la solicitud en una cola de solicitudes y 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.

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 exceder las limitaciones del vinculador (4 KB en la implementación de la biblioteca LargeParcelable) a través de los límites del vinculador. 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 del vinculador o una lista vacía.
`sharedMemoryFd`	Descriptor de archivo anulable 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. Para las implementaciones de VHAL y los clientes nativos, se debe serializar y deserializar un LargeParcelable con la biblioteca LargeParcelable o una clase wrapper útil para la biblioteca en ParcelableUtils.h.

Por ejemplo, un cliente nativo que analiza solicitudes de getValues recibidas de un vinculador se ve de la siguiente manera:

// '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 un ejemplo de implementación de VHAL que envía resultados para getValues a través del vinculador:

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