Interfaccia VHAL

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

Metodo
VehiclePropConfigs getAllPropConfigs() Restituisce un elenco di tutte le configurazioni delle proprietà supportate da questo 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) Ottieni i valori delle proprietà del veicolo in modo asincrono. Gestisce un batch di GetValueRequest in modo asincrono. Il risultato viene pubblicato tramite il metodo di callback onGetValues.
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. Richiamato quando VHAL ha terminato di gestire alcune richieste di set di proprietà.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount) Richiamato per i report sugli eventi di aggiornamento della proprietà. Nella 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 di VHAL è convalidata dal VHAL VTS su VtsHalAutomotive Vehicle_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'orologio 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à, vengono utilizzati uno o più campi all'interno di questo campo 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 archiviare la richiesta in una coda di richieste e di utilizzare un thread di gestore separato per gestire le richieste in modo asincrono. Per i dettagli, consulta Implementazione dei riferimenti.

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 i limiti di binder (4 kB nell'implementazione della libreria LargeParcelable) oltre i confini di 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 è null, contiene un file di memoria condivisa in cui è archiviata 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, 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.
}