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 應使用 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.
}

以下是透過繫結器傳送 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.
}