VHAL-интерфейс

Интерфейс VHAL AIDL определён в android.hardware.automotive.vehicle namespace . Интерфейс VHAL определён в IVehicle.aidl . Если не указано иное, все методы должны быть реализованы для конкретной версии VHAL.

Версии

Android-версия Последняя версия VHAL Последняя версия свойства VHAL Минимальная совместимая версия VHAL
Андроид 16 В4 В4 В1
Андроид 15 В3 В3 В1
Андроид 14 В2 В2 В1
Андроид 13 В1 (Интерфейс свойств VHAL не разделен) В1

РЕКОМЕНДУЕТСЯ реализовать последнюю версию VHAL для конкретной версии Android.

Функции и обратные вызовы

Функции VHAL определены в IVehicle.aidl .

Метод
VehiclePropConfigs getAllPropConfigs()
Возвращает список всех конфигураций свойств, поддерживаемых HAL этого транспортного средства.
VehiclePropConfigs getPropConfigs(in int[] props)
Возвращает список конфигураций свойств для заданных идентификаторов свойств.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
Асинхронное получение значений свойств транспортного средства . Асинхронно обрабатывает пакет запросов GetValueRequest . Результат доставляется через метод обратного вызова onGetValues .
void setValues(IVehicleCallback callback, in SetValueRequests requests)
Асинхронная установка значений свойств транспортного средства . Обрабатывает пакет SetValueRequest асинхронно. Результат передается через метод обратного вызова onSetValues .
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Подписывается на события свойств с указанными параметрами. Параметры подписки включают идентификатор свойства, идентификатор области свойства и частоту дискретизации в Гц (для непрерывного свойства). maxSharedMemoryFileCount не используется.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
Отменяет подписку на ранее подписанные события свойств для указанных свойств.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
Не используется и может быть реализован как no-op.
( Новое в Android 16 )
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
Получает списки поддерживаемых значений для указанных пар идентификаторов свойств и идентификаторов областей.
Представлено в VHAL V4.
( Новое в Android 16 )
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
Получает минимальные и максимальные поддерживаемые значения для указанных пар идентификаторов свойства и области.
Представлено в VHAL V4.
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Регистрирует обратный вызов, который будет вызван при изменении поддерживаемых значений.
Представлено в VHAL V4.
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Отменяет регистрацию поддерживаемого обратного вызова изменения значения.
Представлено в VHAL V4.

Обратные вызовы определены в IVehicleCallback.aidl и содержат эти методы.

Метод
oneway void onGetValues(in GetValueResults responses)
Обратный вызов функции getValues ​​для получения результатов получения значений. Вызывается, когда некоторые из значений для извлечения готовы.
oneway void onSetValues(in SetValueResults responses)
Обратный вызов для функции setValues ​​для получения результатов установки значений. Вызывается, когда VHAL завершает обработку некоторых запросов на установку свойств.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
Обратный вызов для сообщения о событиях обновления свойств.
Свойство CONTINUOUS , событие свойства происходит в зависимости от частоты дискретизации подписки в Гц или частоты сообщений шины транспортного средства. Событие свойства также может произойти при изменении статуса свойства, например, с недоступного на доступное.
Для свойства ON_CHANGE событие свойства происходит, когда изменяется значение свойства или статус свойства.
Это также следует использовать для доставки событий изменения статуса свойства, например, когда свойство становится недоступно или возникает ошибка при чтении, следует доставить VehiclePropValue со статусом недоступно или ошибка и пустым значением.
SharedMemoryFileCount всегда равен 0 .
oneway void onPropertySetError(in VehiclePropErrors errors)
Обратный вызов для сообщения об ошибках асинхронного набора свойств, для которых не существует соответствующего запроса. Если известно, к какому запросу относится ошибка, вместо этого следует использовать onSetValues ​​с результатом ошибки.
oneway void onSupportedValueChange(in List propIdAreaIds)
Обратный вызов для сообщения об изменении минимального и максимального поддерживаемых значений или списка поддерживаемых значений. Вызывающий объект должен вызвать функцию getMinMaxSupportedValue или getSupportedValuesLists для получения обновлённых значений.

Реализация VHAL проверена VHAL VTS в VtsHalAutomotiveVehicle_TargetTest.cpp .

Тест проверяет корректность реализации базовых методов и корректность поддерживаемых конфигураций свойств. Тест выполняется для всех экземпляров VHAL на устройстве, однако AAOS использует только экземпляр по умолчанию ( android.hardware.automotive.vehicle.IVehicle/default ).

Стоимость имущества транспортного средства

Используйте структуру VehiclePropValue для описания значения каждого свойства, которое имеет следующие поля:

Поле Описание
timestamp Метка времени, представляющая время, когда произошло событие, синхронизированная с часами SystemClock.elapsedRealtimeNano() .
prop Идентификатор свойства для этого значения.
areaid Идентификатор области для этого значения. Область должна быть одной из поддерживаемых областей, перечисленных в конфигурации идентификатора области, или 0 для глобальных свойств.
value Структура данных, содержащая фактическое значение свойства. В зависимости от типа свойства, одно или несколько полей в этом поле используются для хранения фактического значения. Например, первый элемент в value.int32Values ​​используется для свойств типа Int32. Подробнее см. в разделе «Конфигурации свойств» .
status Статус свойства для чтения. Для свойства, доступного для чтения и записи, это может также применяться для записи, но не гарантируется. Например, свойство может быть доступно для чтения, но недоступно для записи. В этом случае статус — AVAILABLE , а поле значения содержит допустимую информацию. Возможные статусы см. в разделе VehiclePropertyStatus .

Асинхронные getValues ​​и setValues

Операции getValues ​​и setValues ​​выполняются асинхронно, то есть функция может завершиться до завершения самой операции get или set. Результаты операции (например, значение свойства для getValues ​​и статус успеха или ошибки для setValues ) передаются через обратные вызовы, передаваемые в качестве аргументов.

Реализация не должна блокировать результат в потоке связывателя, обрабатывающем запрос. Вместо этого мы рекомендуем сохранять запрос в очереди запросов и использовать отдельный поток-обработчик для асинхронной обработки запросов. Подробности см. в справочной реализации .

Рисунок 1. Асинхронный процесс.

Большие посылки

Все структуры с именем XXXs , такие как VehiclePropConfigs , SetValueRequests и VehiclePropValues ​​, называются LargeParcelable (или StableLargeParcelable ). Каждая из них представляет собой список значений, используемых для передачи больших объёмов данных, которые могут превышать ограничения связывателя (4 КБ в реализации библиотеки LargeParcelable ) через границы связывателя. Каждая из них имеет схожее определение структуры, содержащее следующие поля.

Руководство Описание
payloads Список значений, размер которых соответствует ограничению памяти связующего устройства, или пустой список.
sharedMemoryFd Файловый дескриптор, допускающий значение NULL, указывающий на файл общей памяти, в котором хранятся сериализованные полезные данные, если список значений слишком велик.

Например, VehiclePropConfigs определяется как:

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 содержит либо непустые полезные данные, либо ненулевой sharedMemoryFd .

  • Если payloads не пусты, в них хранится список фактических данных, представляющий собой конфигурацию свойств.
  • Если sharedMemoryFd не равно NULL, он содержит файл общей памяти, в котором хранится сериализованная структура VehiclePropConfigs . Эта структура использует функцию writeToParcel для сериализации Parcel.

Car Service, как Java-клиент для VHAL, выполняет сериализацию и десериализацию LargeParcelable . Для реализаций VHAL и нативных клиентов LargeParcelable следует сериализовать и десериализовать с помощью библиотеки LargeParcelable или удобного класса-обёртки для этой библиотеки в ParcelableUtils.h .

Например, собственный клиент, анализирующий запросы на getValues полученные от связующего компонента, выглядит следующим образом:

// '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.
}

Ниже показан пример реализации VHAL, которая отправляет результаты для getValues ​​через связующее звено:

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