Интерфейс AIDL VHAL

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

Версии

Версию Android. Последняя версия VHAL Последняя версия свойства VHAL Минимальная совместимая версия VHAL
Android 16 V4 V4 V1
Android 15 V3 V3 V1
Android 14 V2 V2 V1
Android 13 V1 (интерфейс свойства VHAL не разделен) V1

РЕКОМЕНДУЕТСЯ использовать последнюю версию 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)
Не используется и может быть реализован как пустая операция.
(Новое в 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 проверяется с помощью 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 выполняются асинхронно. Это означает, что функция может вернуть значение до того, как будет завершена операция получения или установки. Результаты операции (например, значение свойства для getValues и статус успешного выполнения или ошибки для setValues) передаются через обратные вызовы, переданные в качестве аргументов.

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

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

Большие объекты Parcelable

Все структуры с названием 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.

Как Java-клиент для VHAL, Car Service обрабатывает сериализацию и десериализацию для 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.
}