VHAL 接口

AIDL VHAL 在 android.hardware.automotive.vehicle 命名空间中定义。VHAL 接口在 IVehicle.aidl 中定义。除非另有说明，否则必须实现所有方法。

方法
VehiclePropConfigs getAllPropConfigs()
返回此车辆 HAL 支持的所有属性配置的列表。
VehiclePropConfigs getPropConfigs(in int[] props)
返回给定属性 ID 的属性配置列表。
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)
使用指定的选项订阅属性事件。订阅选项包括属性 ID、属性区域 ID 以及采样率（以 Hz 为单位）（对于连续属性）。不使用 maxSharedMemoryFileCount。
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
取消订阅之前订阅的指定属性的属性事件。
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
未使用，可以实现为无操作。

回调在 IVehicleCallback.aidl 中定义，并且包含以下方法。

方法
oneway void onGetValues(in GetValueResults responses)
getValues 函数的回调，用于传送 get value 结果。当要提取的某些值就绪时调用。
oneway void onSetValues(in SetValueResults responses)
setValues 函数的回调，用于传送 set value 结果。当 VHAL 完成处理某些属性设置请求时调用。
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
用于报告属性更新事件的回调。
对于 CONTINUOUS 属性，属性事件根据订阅的采样率（以 Hz 为单位）或车辆总线消息频率发生。如果属性的状态发生变化（例如，从不可用变为可用），也可能会发生属性事件。
对于 ON_CHANGE 属性，当属性的值或属性的状态发生变化时，会发生属性事件。
SharedMemoryFileCount 始终为 0。
oneway void onPropertySetError(in VehiclePropErrors errors)
用于报告没有相应设置请求的异步属性设置错误的回调。如果我们知道错误是针对哪个设置请求的，则必须使用带有错误结果的 onSetValues 来代替此回调。

如需了解详情，请参阅 IVehicle.aidl 和 IVehicleCallback.aidl。

VHAL 实现通过 VHAL VTS 在 VtsHalAutomotiveVehicle_TargetTest.cpp 中进行验证。该测试验证基本方法是否已正确实现，以及支持的属性配置是否正确。

车辆属性值

使用 VehiclePropValue 结构来描述每个属性的值，该结构具有以下字段

字段 说明
timestamp 表示事件发生时间的时间戳，并与 SystemClock.elapsedRealtimeNano() 时钟同步。
prop 此值的属性 ID。
areaid 此值的区域 ID。该区域必须是区域 ID 配置中列出的受支持区域之一，或者对于全局属性，则为 0。
value 包含实际属性值的数据结构。根据属性类型，此字段中的一个或多个字段用于存储实际值。例如，value.int32Values 中的第一个元素用于 Int32 类型属性。有关详情，请参阅属性配置。

异步 getValues 和 setValues

getValues 和 setValues 操作是异步执行的，这意味着函数可能会在实际的 get 或 set 操作完成之前返回。操作结果（例如，getValues 的属性值和 setValues 的成功或错误状态）通过作为参数传递的回调传送。

实现不得阻止处理请求的 binder 线程中的结果。相反，我们建议您将请求存储在请求队列中，并使用单独的处理程序线程来异步处理请求。有关详情，请参阅参考实现。

图 1. 异步流程。

大型 Parcelable

所有名为 XXXs 的结构（例如 VehiclePropConfigs、SetValueRequests 和 VehiclePropValues）都称为 LargeParcelable（或 StableLargeParcelable）。每个结构都表示一个值列表，用于传递可能超出 binder 限制（LargeParcelable 库实现中为 4KB）的大型数据（跨 binder 边界）。每个结构都有类似的结构定义，其中包含以下字段。

指导 说明
payloads 当值大小在 binder 内存限制范围内时，为值列表；否则为空列表。
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 包含非空载荷或非 null 的 sharedMemoryFd。

  • 如果 payloads 不为空，则它存储实际数据列表，即属性配置。
  • 如果 sharedMemoryFd 不为 null，则它包含一个共享内存文件，该文件存储 VehiclePropConfigs 的序列化结构。该结构使用 writeToParcel 函数来序列化 Parcel。

作为 VHAL 的 Java 客户端，Car Service 处理 LargeParcelable 的序列化和反序列化。对于 VHAL 实现和原生客户端，应使用 LargeParcelable 库或 ParcelableUtils.h 中库的有用封装容器类来序列化和反序列化 LargeParcelable。

例如，原生客户端解析从 binder 收到的 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 实现，该实现通过 binder 发送 getValues 的结果

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