Antarmuka VHAL

AIDL VHAL ditentukan dalam android.hardware.automotive.vehicle namespace. Antarmuka VHAL ditentukan di IVehicle.aidl. Kecuali jika ditentukan, semua metode harus diterapkan untuk versi VHAL tertentu.

Versi

Versi Android Versi VHAL terbaru Versi properti VHAL terbaru Versi VHAL minimum yang kompatibel
Android 16 V4 V4 V1
Android 15 V3 V3 V1
Android 14 V2 V2 V1
Android 13 V1 (Antarmuka properti VHAL tidak dipisah) V1

Sebaiknya terapkan versi VHAL terbaru untuk versi Android tertentu.

Fungsi dan callback

Fungsi VHAL ditentukan di IVehicle.aidl.

Metode
VehiclePropConfigs getAllPropConfigs()
Menampilkan daftar semua Konfigurasi Properti yang didukung oleh HAL kendaraan ini.
VehiclePropConfigs getPropConfigs(in int[] props)
Menampilkan daftar Konfigurasi Properti untuk ID properti yang diberikan.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
Mendapatkan nilai properti kendaraan secara asinkron. Menangani batch dari GetValueRequest secara asinkron. Hasilnya dikirimkan melalui metode onGetValues callback.
void setValues(IVehicleCallback callback, in SetValueRequests requests)
Menetapkan nilai properti kendaraan secara asinkron. Menangani batch SetValueRequest secara asinkron. Hasilnya dikirimkan melalui onSetValues metode callback.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Berlangganan ke peristiwa properti dengan opsi yang ditentukan. Opsi langganan mencakup ID properti, ID area properti, dan frekuensi pengambilan sampel dalam Hz (untuk properti berkelanjutan). maxSharedMemoryFileCount tidak digunakan.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
Berhenti berlangganan peristiwa properti yang sebelumnya dilanggan untuk properti yang ditentukan.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
Tidak digunakan dan dapat diimplementasikan sebagai no-op.
(Baru di Android 16)
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
Mendapatkan daftar nilai yang didukung untuk pasangan ID properti dan ID area yang ditentukan.
Diperkenalkan di VHAL V4.
(Baru di Android 16)
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
Mendapatkan nilai minimum dan maksimum yang didukung untuk pasangan ID properti dan ID area yang ditentukan.
Diperkenalkan di VHAL V4.
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Mendaftarkan callback untuk dipanggil saat nilai yang didukung berubah.
Diperkenalkan di VHAL V4.
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Membatalkan pendaftaran callback perubahan nilai yang didukung.
Diperkenalkan di VHAL V4.

Callback ditentukan di IVehicleCallback.aidl dan berisi metode ini.

Metode
oneway void onGetValues(in GetValueResults responses)
Callback untuk fungsi getValues guna mengirimkan hasil nilai. Dipanggil saat beberapa nilai yang akan diambil sudah siap.
oneway void onSetValues(in SetValueResults responses)
Callback untuk fungsi setValues guna mengirimkan hasil nilai yang ditetapkan. Dipanggil saat VHAL selesai menangani beberapa permintaan set properti.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
Callback untuk melaporkan peristiwa pembaruan properti.
CONTINUOUS properti, peristiwa properti terjadi berdasarkan frekuensi pesan bus kendaraan atau frekuensi pengambilan sampel langganan dalam Hz. Peristiwa properti juga dapat terjadi jika status properti berubah. Misalnya, dari tidak tersedia menjadi tersedia.
Untuk properti ON_CHANGE, peristiwa properti terjadi saat nilai properti atau status properti berubah.
Hal ini juga harus digunakan untuk mengirimkan peristiwa perubahan status properti, misalnya, saat properti menjadi tidak tersedia atau error untuk dibaca, VehiclePropValue dengan status tidak tersedia atau error dan nilai kosong harus dikirimkan.
SharedMemoryFileCount selalu 0.
oneway void onPropertySetError(in VehiclePropErrors errors)
Callback untuk melaporkan error set properti asinkron yang tidak memiliki permintaan set yang sesuai request. Jika kita mengetahui permintaan set mana yang error, onSetValues dengan an hasil error harus digunakan, bukan ini.
oneway void onSupportedValueChange(in List propIdAreaIds)
Callback untuk melaporkan perubahan daftar nilai yang didukung atau nilai minimum dan maksimum yang didukung. Pemanggil seharusnya memanggil getMinMaxSupportedValue atau getSupportedValuesLists untuk mendapatkan nilai yang diperbarui.

Implementasi VHAL divalidasi oleh VHAL VTS di VtsHalAutomotiveVehicle_TargetTest.cpp.

Pengujian ini memverifikasi bahwa metode dasar diimplementasikan dengan benar dan konfigurasi properti yang didukung sudah benar. Pengujian ini dijalankan terhadap semua instance VHAL di perangkat, tetapi AAOS hanya menggunakan instance default (android.hardware.automotive.vehicle.IVehicle/default)

Nilai properti kendaraan

Gunakan struktur untuk mendeskripsikan nilai setiap properti, yang memiliki kolom ini:VehiclePropValue

Kolom Deskripsi
timestamp Stempel waktu yang menunjukkan waktu terjadinya peristiwa dan disinkronkan dengan SystemClock.elapsedRealtimeNano() jam.
prop ID properti untuk nilai ini.
areaid ID area untuk nilai ini. Area harus salah satu area yang didukung yang tercantum dalam konfigurasi ID area, atau 0 untuk properti global.
value Struktur data yang berisi nilai properti sebenarnya. Berdasarkan jenis properti, satu atau beberapa kolom dalam kolom ini digunakan untuk menyimpan nilai sebenarnya. Misalnya, elemen pertama elemen di value.int32Values digunakan untuk properti jenis Int32. Untuk mengetahui detailnya, lihat Konfigurasi Properti.
status Status properti untuk dibaca. Untuk properti baca/tulis, hal ini mungkin juga berlaku untuk penulisan, tetapi tidak dijamin, misalnya, properti mungkin tersedia untuk dibaca, tetapi tidak tersedia untuk penulisan. Dalam hal ini, statusnya adalah AVAILABLE dan kolom nilai berisi informasi yang valid. Untuk mengetahui kemungkinan status, lihat VehiclePropertyStatus.

getValues dan setValues asinkron

Operasi getValues dan setValues dilakukan secara asinkron, yang berarti fungsi mungkin ditampilkan sebelum operasi get atau set sebenarnya selesai. Hasil operasi (misalnya, nilai properti untuk getValues dan status berhasil atau error untuk setValues) dikirimkan melalui callback yang diteruskan sebagai argumen.

Implementasi tidak boleh memblokir hasil dalam thread binder yang menangani permintaan. Sebagai gantinya, sebaiknya simpan permintaan dalam antrean permintaan dan gunakan thread handler terpisah untuk menangani permintaan secara asinkron. Lihat Implementasi Referensi untuk mengetahui detailnya.

Gambar 1. Proses asinkron.

Parcelable besar

Semua struktur yang diberi nama XXXs, seperti VehiclePropConfigs, SetValueRequests, dan VehiclePropValues disebut LargeParcelable (atau, StableLargeParcelable). Setiap struktur mewakili daftar nilai yang digunakan untuk meneruskan data besar yang mungkin melebihi batasan binder (4 KB dalam implementasi library LargeParcelable) di seluruh batas binder. Setiap struktur memiliki definisi struktur yang serupa yang berisi kolom berikut.

Panduan Deskripsi
payloads Daftar nilai saat ukuran nilai sesuai dengan batasan memori binder, atau daftar kosong.
sharedMemoryFd Deskriptor file yang dapat di-nullable yang mengarah ke file memori bersama yang menyimpan payload yang diserialisasi jika daftar nilai terlalu besar.

Misalnya, VehiclePropConfigs ditentukan sebagai:

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 berisi payload yang tidak kosong atau yang tidak nullsharedMemoryFd.

  • Jika payloads tidak kosong, payload akan menyimpan daftar data sebenarnya, yang merupakan konfigurasi properti.
  • Jika sharedMemoryFd tidak null, payload akan berisi file memori bersama, yang menyimpan struktur VehiclePropConfigs yang diserialisasi. Struktur ini menggunakan fungsi writeToParcel untuk melakukan serialisasi Parcel.

Sebagai klien Java untuk VHAL, Layanan Mobil menangani serialisasi dan deserialisasi untuk LargeParcelable. Untuk implementasi VHAL dan klien native, LargeParcelable harus diserialisasi dan dideserialisasi dengan LargeParcelable library atau class wrapper yang berguna untuk library di ParcelableUtils.h.

Misalnya, klien native yang mengurai permintaan untuk getValues yang diterima dari binder adalah sebagai berikut:

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

Contoh implementasi VHAL yang mengirimkan hasil untuk getValues melalui binder ditampilkan di bawah ini:

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