Interfaccia VHAL

Il VHAL AIDL è definito in android.hardware.automotive.vehicle namespace. L'interfaccia VHAL è definita in IVehicle.aidl. Se non specificato, tutti i metodi devono essere implementati.

Metodo
VehiclePropConfigs getAllPropConfigs()
Restituisce un elenco di tutte le configurazioni delle proprietà supportate dall'HAL del veicolo.
VehiclePropConfigs getPropConfigs(in int[] props)
Restituisce un elenco di configurazioni proprietà per ID proprietà specificati.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
Recupero dei valori delle proprietà del veicolo in modo asincrono. Gestisce un batch di GetValueRequest in modo asincrono. Il risultato viene fornito tramite il metodo onGetValues del callback.
void setValues(IVehicleCallback callback, in SetValueRequests requests)
Imposta i valori delle proprietà del veicolo in modo asincrono. Gestisce un batch di SetValueRequest in modo asincrono. Il risultato viene fornito tramite il metodo onSetValues del callback.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Si iscrive agli eventi della proprietà con le opzioni specificate. Le opzioni di abbonamento includono ID proprietà, ID area della proprietà e frequenza di campionamento in Hz (per una proprietà continua). maxSharedMemoryFileCount non viene utilizzato.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
Annulla l'iscrizione agli eventi delle proprietà a cui hai effettuato l'iscrizione in precedenza per le proprietà specificate.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
Non utilizzato e può essere implementato come no-op.

I callback sono definiti in IVehicleCallback.aidl e contengono questi metodi.

Metodo
oneway void onGetValues(in GetValueResults responses)
Il callback per la funzione getValues per fornire i risultati del valore get. Viene chiamato quando alcuni dei valori da recuperare sono pronti.
oneway void onSetValues(in SetValueResults responses)
Callback per la funzione setValues per fornire i risultati del valore impostato. Viene chiamato quando VHAL ha terminato la gestione di alcune richieste relative agli insiemi di proprietà.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
Callback per la generazione di report sugli eventi di aggiornamento della struttura.
proprietà
CONTINUOUS, un evento della proprietà si verifica in base alla frequenza di campionamento dell'abbonamento in Hz o alla frequenza del messaggio del bus di bordo. Un evento della proprietà può verificarsi anche se lo stato di una proprietà cambia. Ad esempio, da non disponibile a disponibile.
Per la proprietà ON_CHANGE, un evento si verifica quando il valore o lo stato di una proprietà cambia.
SharedMemoryFileCount è sempre 0.
oneway void onPropertySetError(in VehiclePropErrors errors)
Call-back per segnalare errori relativi a set di proprietà asincroni che non hanno una richiesta di set corrispondente. Se sappiamo per quale richiesta del set si verifica l'errore, al suo posto deve essere utilizzato onSetValues con un risultato di errore.

Per ulteriori informazioni, consulta IVehicle.aidl e IVehicleCallback.aidl.

L'implementazione VHAL viene convalidata dal VTS VHAL in VtsHalAutomotiveVehicle_TargetTest.cpp. Il test verifica che i metodi di base siano implementati correttamente e che le configurazioni delle proprietà supportate siano corrette.

Valore della proprietà del veicolo

Utilizza la struttura VehiclePropValue per descrivere il valore di ogni proprietà, che contiene i seguenti campi:

Campo Descrizione
timestamp Il timestamp che rappresenta l'ora in cui si è verificato l'evento e sincronizzato con l'ora del SystemClock.elapsedRealtimeNano().
prop L'ID proprietà per questo valore.
areaid L'ID area per questo valore. L'area deve essere una delle aree supportate elencate nella configurazione dell'ID area o 0 per le proprietà globali.
value Una struttura di dati contenente il valore effettivo della proprietà. In base al tipo di proprietà, uno o più campi al suo interno vengono utilizzati per memorizzare il valore effettivo. Ad esempio, il primo elemento in value.int32Values viene utilizzato per le proprietà di tipo Int32. Per maggiori dettagli, consulta Configurazioni proprietà.

getValues e setValues asincroni

Le operazioni getValues e setValues vengono eseguite in modo asincrono, il che significa che la funzione potrebbe restituire un valore prima del completamento dell'operazione get o set effettiva. I risultati dell'operazione (ad esempio il valore della proprietà per getValues e lo stato di esito positivo o di errore per setValues) vengono trasmessi tramite i callback passati come argomenti.

L'implementazione non deve bloccarsi sul risultato nel thread del binder che gestisce la richiesta. Ti consigliamo invece di memorizzare la richiesta in una coda di richieste e di utilizzare un thread di gestore distinto per gestire le richieste in modo asincrono. Per maggiori dettagli, consulta la sezione Implementazione di riferimento.

Figura 1. Processo asincrono.

Parcelable di grandi dimensioni

Tutte le strutture denominate XXXs, ad esempio VehiclePropConfigs, SetValueRequests e VehiclePropValues, sono chiamate LargeParcelable (o StableLargeParcelable). Ognuna rappresenta un elenco di valori utilizzati per trasmettere dati di grandi dimensioni che potrebbero superare le limitazioni del binder (4 KB nell'implementazione della libreria LargeParcelable) oltre i confini del binder. Ognuno ha una definizione di struttura simile che contiene i seguenti campi.

Assistenza Descrizione
payloads Elenco di valori quando la dimensione del valore rientra in una limitazione di memoria del binder o un elenco vuoto.
sharedMemoryFd Descrittore di file facoltativo che punta a un file di memoria condivisa che memorizza i payload serializzati se l'elenco di valori è troppo grande.

Ad esempio, VehiclePropConfigs è definito come:

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 contiene payload non vuoti o un valore non nullo sharedMemoryFd.

  • Se payloads non è vuoto, memorizza un elenco dei dati effettivi, ovvero la configurazione della proprietà.
  • Se sharedMemoryFd non è nullo, contiene un file di memoria condivisa che memorizza la struttura serializzata di VehiclePropConfigs. La struttura utilizza la funzione writeToParcel per serializzare un pacchetto.

In qualità di client Java per VHAL, Car Service gestisce la serializzazione e la deserializzazione per LargeParcelable. Per le implementazioni VHAL e i client nativi, un LargeParcelable deve essere serializzato e deserializzato con la libreria LargeParcelable o con una classe wrapper utile per la libreria in ParcelableUtils.h.

Ad esempio, un client nativo che analizza le richieste per getValues ricevute da un binder è il seguente:

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

Di seguito è riportata un'implementazione di VHAL di esempio che invia i risultati per getValues tramite il binder:

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