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

建議您為特定 Android 版本實作最新 VHAL 版本。

函式和回呼

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)
未使用，可實作為無運算。
(Android 16 的新功能)
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
取得指定屬性 ID 和區域 ID 配對的支援值清單。
VHAL V4 中導入。
(Android 16 的新功能)
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
取得指定屬性 ID 和區域 ID 配對的支援最小值和最大值。
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 屬性，屬性事件會根據訂閱取樣率 (以 Hz 為單位) 或車輛匯流排訊息頻率發生。如果資源的狀態變更，也可能會發生資源事件。例如從無法使用變為可以使用。
如果是 ON_CHANGE 屬性，當屬性值或屬性狀態變更時，就會發生屬性事件。
這也應做為傳送屬性狀態變更事件的用途，例如當屬性無法使用或讀取時發生錯誤，應傳送狀態為無法使用或錯誤的 VehiclePropValue，且值為空。
SharedMemoryFileCount 一律為 0。
oneway void onPropertySetError(in VehiclePropErrors errors)
回呼，用於回報沒有對應設定要求的非同步屬性設定錯誤。如果我們知道錯誤是針對哪個設定要求，則必須使用含有錯誤結果的 onSetValues，而非這個方法。
oneway void onSupportedValueChange(in List propIdAreaIds)
回呼，用於回報支援的最小值和最大值，或支援的值清單變更。呼叫端應呼叫 getMinMaxSupportedValue 或 getSupportedValuesLists，以取得更新的值。

VHAL 實作項目會在 VtsHalAutomotiveVehicle_TargetTest.cpp 經過 VHAL VTS 驗證。

這項測試會驗證基本方法是否正確實作，以及支援的屬性設定是否正確。這項測試會針對裝置上的所有 VHAL 執行個體執行，但 AAOS 只會使用預設執行個體 (android.hardware.automotive.vehicle.IVehicle/default)

車輛屬性值

使用 VehiclePropValue 結構體說明每個屬性的值，其中包含下列欄位：

欄位 說明
timestamp 代表事件發生時間的時間戳記，並與 SystemClock.elapsedRealtimeNano() 時鐘同步。
prop 這個值的屬性 ID。
areaid 這個值的區域 ID。該區域必須是區域 ID 設定中列出的支援區域，或是全球資源的 0。
value 包含實際屬性值的資料結構。系統會根據屬性類型，使用這個欄位中的一或多個欄位儲存實際值。舉例來說，value.int32Values 中的第一個元素用於 Int32 型別屬性。詳情請參閱「資源設定」。
status 房源的讀取狀態。如果是讀取/寫入屬性，這也可能適用於寫入，但無法保證。舉例來說，屬性可能可供讀取，但無法寫入。在這種情況下，狀態為 AVAILABLE，且值欄位包含有效資訊。 如要查看可能的狀態，請參閱 VehiclePropertyStatus。

非同步 getValues 和 setValues

getValues 和 setValues 作業會以非同步方式執行，也就是說，函式可能會在實際的 get 或 set 作業完成前傳回。作業結果 (例如 getValues 的屬性值，以及 setValues 的成功或錯誤狀態) 會透過做為引數傳遞的回呼函式傳送。

實作作業不得在處理要求的繫結器執行緒中封鎖結果。 建議您將要求儲存在要求佇列中，並使用個別處理常式執行緒非同步處理要求。詳情請參閱參考實作。

圖 1. 非同步程序。

大型 Parcelable

所有名為 XXXs 的結構 (例如 VehiclePropConfigs、SetValueRequests 和 VehiclePropValues) 都稱為 LargeParcelable (或 StableLargeParcelable)。每個結構都代表值清單，用於傳遞可能超出繫結器限制 (LargeParcelable 程式庫實作中的 4 KB) 的大型資料，跨越繫結器界線。兩者都有類似的結構定義，包含下列欄位。

指南 說明
payloads 如果值大小符合繫結器記憶體限制，則為值清單，否則為空白清單。
sharedMemoryFd 可為空值的檔案描述元，指向儲存序列化酬載的共用記憶體檔案 (如果值清單過大)。

舉例來說，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 不是空值，則包含共用記憶體檔案，其中儲存 VehiclePropConfigs 的序列化結構。這個結構會使用 writeToParcel 函式序列化 Parcel。

做為 VHAL 的 Java 用戶端，Car Service 會處理 LargeParcelable 的序列化和還原序列化。對於 VHAL 實作項目和原生用戶端，應使用 LargeParcelable 程式庫或 ParcelableUtils.h 中程式庫的實用包裝函式類別，序列化及還原序列化 LargeParcelable。

舉例來說，剖析從繫結器收到的 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.
}

以下範例說明如何透過繫結器傳送 getValues 的結果，實作 VHAL：

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