Interfejs VHAL

AIDL VHAL jest zdefiniowany w android.hardware.automotive.vehicle namespace. Interfejs VHAL jest zdefiniowany w tym miejscu: IVehicle.aidl. O ile nie określono inaczej, wszystkie metody muszą być zaimplementowane w określonej wersji VHAL.

Wersje

Wersja Androida Najnowsza wersja VHAL Najnowsza wersja właściwości VHAL Minimalna zgodna wersja VHAL
Android 16 V4 V4 V1
Android 15 V3 V3 V1
Android 14 V2 V2 V1
Android 13 V1 (Interfejs właściwości VHAL nie jest podzielony) V1

ZALECAMY wdrożenie najnowszej wersji VHAL dla konkretnej wersji Androida.

Funkcje i wywołania zwrotne

Funkcje VHAL są zdefiniowane na stronie IVehicle.aidl.

Metoda
VehiclePropConfigs getAllPropConfigs()
Zwraca listę wszystkich konfiguracji właściwości obsługiwanych przez tę warstwę HAL pojazdu.
VehiclePropConfigs getPropConfigs(in int[] props)
Zwraca listę konfiguracji usługi dla podanych identyfikatorów usługi.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
Pobierz wartości właściwości pojazdu asynchronicznie. Obsługuje asynchronicznie partię obiektów GetValueRequest. Wynik jest przekazywany za pomocą metody wywołania zwrotnego onGetValues.
void setValues(IVehicleCallback callback, in SetValueRequests requests)
Ustaw wartości właściwości pojazdu asynchronicznie. Obsługuje partię obiektów SetValueRequest asynchronicznie. Wynik jest przekazywany za pomocą metody wywołania zwrotnego onSetValues.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Subskrybuje zdarzenia usługi z określonymi opcjami. Opcje subskrypcji obejmują identyfikator usługi, identyfikator obszaru usługi i częstotliwość próbkowania w Hz (w przypadku usługi ciągłej). maxSharedMemoryFileCount nie jest używana.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
Anuluje subskrypcję zdarzeń usługi, która została wcześniej zasubskrybowana, w przypadku określonych usług.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
Nie jest używana i może być zaimplementowana jako operacja bez efektu.
(Nowość w Androidzie 16)
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
Pobiera listy obsługiwanych wartości dla określonych par identyfikatorów właściwości i obszarów.
Wprowadzono w VHAL V4.
(Nowość w Androidzie 16)
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
Pobiera minimalne i maksymalne obsługiwane wartości dla określonych par identyfikatorów właściwości i obszarów.
Wprowadzono w VHAL V4.
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Rejestruje wywołanie zwrotne, które ma być wywoływane, gdy zmienią się obsługiwane wartości.
Wprowadzono w VHAL V4.
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Wyłącza wywołanie zwrotne obsługiwanej zmiany wartości.
Wprowadzono w VHAL V4.

Funkcje zwrotne są zdefiniowane w IVehicleCallback.aidl i zawierają te metody.

Metoda
oneway void onGetValues(in GetValueResults responses)
Wywołanie zwrotne funkcji getValues, które dostarcza wyniki wartości. Wywoływana, gdy niektóre z wartości do pobrania są gotowe.
oneway void onSetValues(in SetValueResults responses)
Wywołanie zwrotne funkcji setValues, które dostarcza wyniki o ustalonej wartości. Wywoływana, gdy VHAL zakończy obsługę niektórych żądań ustawienia właściwości.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
Funkcja zwrotna do raportowania zdarzeń aktualizacji usługi.
CONTINUOUS zdarzenie usługi występuje na podstawie częstotliwości próbkowania subskrypcji w Hz lub częstotliwości wiadomości magistrali pojazdu. Zdarzenie usługi może też wystąpić, jeśli zmieni się stan usługi. Na przykład z niedostępnego na dostępny.
W przypadku usługi ON_CHANGE zdarzenie usługi występuje, gdy zmieni się wartość lub stan usługi.
Należy go też używać do przekazywania zdarzeń związanych ze zmianą stanu usługi, np. gdy usługa staje się niedostępna lub występuje błąd odczytu, należy przekazać VehiclePropValue ze stanem niedostępności lub błędu i pustą wartością.
SharedMemoryFileCount to zawsze 0.
oneway void onPropertySetError(in VehiclePropErrors errors)
Funkcja wywołania zwrotnego do zgłaszania asynchronicznych błędów ustawiania właściwości, które nie mają odpowiedniego żądania ustawienia. Jeśli wiemy, którego żądania zestawu dotyczy błąd, zamiast tego należy użyć właściwości onSetValues z wynikiem błędu.
oneway void onSupportedValueChange(in List propIdAreaIds)
Wywołanie zwrotne do raportowania zmian minimalnej i maksymalnej obsługiwanej wartości lub listy obsługiwanych wartości. Osoba dzwoniąca powinna zadzwonić pod numer getMinMaxSupportedValue lub getSupportedValuesLists, aby uzyskać zaktualizowane wartości.

Wdrożenie VHAL jest weryfikowane przez VHAL VTS na stronie VtsHalAutomotiveVehicle_TargetTest.cpp.

Test sprawdza, czy podstawowe metody są prawidłowo zaimplementowane, a obsługiwane konfiguracje usługi są prawidłowe. Test jest przeprowadzany na wszystkich instancjach VHAL na urządzeniu, ale AAOS używa tylko instancji domyślnej (android.hardware.automotive.vehicle.IVehicle/default).

Wartość właściwości pojazdu

Użyj struktury VehiclePropValue, aby opisać wartość każdej właściwości. Struktura ta zawiera te pola:

Pole Opis
timestamp Sygnatura czasowa reprezentująca czas wystąpienia zdarzenia zsynchronizowany z zegarem SystemClock.elapsedRealtimeNano().
prop Identyfikator usługi dla tej wartości.
areaid Identyfikator obszaru dla tej wartości. Obszar musi być jednym z obsługiwanych obszarów wymienionych w konfiguracji identyfikatora obszaru lub 0 w przypadku usług globalnych.
value Struktura danych zawierająca rzeczywistą wartość usługi. W zależności od typu właściwości do przechowywania rzeczywistej wartości używane jest co najmniej 1 pole w tym polu. Na przykład pierwszy element w value.int32Values jest używany w przypadku właściwości typu Int32. Więcej informacji znajdziesz w sekcji Konfiguracje usługi.
status Stan usługi do odczytu. W przypadku właściwości z uprawnieniami do odczytu i zapisu może to również dotyczyć zapisu, ale nie jest to gwarantowane. Na przykład właściwość może być dostępna do odczytu, ale nie do zapisu. W takim przypadku stan to AVAILABLE, a pole wartości zawiera prawidłowe informacje. Możliwe stany znajdziesz w sekcji VehiclePropertyStatus.

Asynchroniczne metody getValues i setValues

Operacje getValues i setValues są wykonywane asynchronicznie, co oznacza, że funkcja może zwrócić wartość przed zakończeniem rzeczywistej operacji pobierania lub ustawiania. Wyniki operacji (np. wartość właściwości dla getValues oraz stan powodzenia lub błędu dla setValues) są dostarczane za pomocą wywołań zwrotnych przekazywanych jako argumenty.

Implementacja nie może blokować wyniku w wątku bindera, który obsługuje żądanie. Zamiast tego zalecamy przechowywanie żądania w kolejce żądań i używanie osobnego wątku obsługi do asynchronicznego obsługiwania żądań. Szczegółowe informacje znajdziesz w implementacji referencyjnej.

Rysunek 1. Proces asynchroniczny.

Duże obiekty Parcelable

Wszystkie struktury o nazwie XXXs, takie jak VehiclePropConfigs, SetValueRequests i VehiclePropValues, są nazywane LargeParcelable (lub StableLargeParcelable). Każda z nich reprezentuje listę wartości używanych do przekazywania dużych ilości danych, które mogą przekraczać ograniczenia mechanizmu Binder (4 KB w implementacji biblioteki LargeParcelable), przez granice mechanizmu Binder. Każda z nich ma podobną definicję struktury, która zawiera te pola:

Wskazówki Opis
payloads Lista wartości, jeśli rozmiar wartości mieści się w limicie pamięci modułu, lub pusta lista.
sharedMemoryFd Deskryptor pliku z wartością null wskazujący plik pamięci współdzielonej, który przechowuje serializowane ładunki, jeśli lista wartości jest zbyt długa.

Na przykład VehiclePropConfigs jest zdefiniowane jako:

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 zawiera niepuste ładunki lub niepustą wartość sharedMemoryFd.

  • Jeśli payloads nie jest pusta, przechowuje listę rzeczywistych danych, czyli konfigurację usługi.
  • Jeśli sharedMemoryFd nie jest wartością null, zawiera plik pamięci współdzielonej, w którym jest przechowywana serializowana struktura VehiclePropConfigs. Struktura używa funkcji writeToParcel do serializacji obiektu Parcel.

Usługa Car Service jako klient VHAL w języku Java obsługuje serializację i deserializację LargeParcelable. W przypadku implementacji VHAL i klientów natywnych element LargeParcelable powinien być serializowany i deserializowany za pomocą biblioteki LargeParcelable lub przydatnej klasy opakowującej dla biblioteki w ParcelableUtils.h.

Na przykład klient natywny analizujący żądania dotyczące getValues otrzymane z bindera wygląda tak:

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

Poniżej znajdziesz przykładową implementację VHAL, która wysyła wyniki dla getValues za pomocą mechanizmu Binder:

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