Antarmuka VHAL

VHAL AIDL ditentukan dalam android.hardware.automotive.vehicle namespace. Antarmuka VHAL ditentukan di IVehicle.aidl. Kecuali ditentukan lain, semua metode harus diimplementasikan.

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 tertentu.
void getValues(IVehicleCallback callback, in GetValueRequests requests) Dapatkan nilai properti kendaraan secara asinkron. Menangani batch GetValueRequest secara asinkron. Hasilnya dikirim melalui metode callback onGetValues.
void setValues(IVehicleCallback callback, in SetValueRequests requests) Tetapkan nilai properti kendaraan secara asinkron. Menangani batch SetValueRequest secara asinkron. Hasilnya dikirim melalui metode callback onSetValues.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount) Berlangganan peristiwa properti dengan opsi yang ditentukan. Opsi subscribe mencakup ID properti, ID area properti, dan frekuensi sampel dalam Hz (untuk properti berkelanjutan). maxSharedMemoryFileCount tidak digunakan.
void unsubscribe(in IVehicleCallback callback, in int[] propIds) Membatalkan langganan peristiwa properti yang sebelumnya dilanggani untuk properti yang ditentukan.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId) Tidak digunakan dan dapat diterapkan karena tanpa pengoperasian.

Callback ditentukan di IVehicleCallback.aidl dan berisi metode ini.

Metode
oneway void onGetValues(in GetValueResults responses) Callback untuk fungsi getValues guna memberikan hasil nilai get. Dipanggil saat beberapa nilai yang akan diambil sudah siap.
oneway void onSetValues(in SetValueResults responses) Callback untuk fungsi setValues guna memberikan hasil nilai yang telah ditetapkan. Dipanggil saat VHAL telah selesai menangani beberapa permintaan kumpulan properti.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount) Callback untuk melaporkan peristiwa pembaruan properti. CONTINUOUS, peristiwa properti terjadi berdasarkan frekuensi sampel berlangganan dalam Hz atau frekuensi pesan bus kendaraan. 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. SharedMemoryFileCount selalu 0.
oneway void onPropertySetError(in VehiclePropErrors errors) Callback untuk melaporkan error kumpulan properti asinkron yang tidak memiliki permintaan yang ditetapkan yang sesuai. Jika kita mengetahui permintaan set mana yang mengalami error, onSetValues dengan hasil error harus digunakan, bukan ini.

Untuk informasi selengkapnya, lihat IVehicle.aidl dan IVehicleCallback.aidl.

Penerapan VHAL divalidasi oleh VTS VHAL di VtsHalAutomotiveVehicle_TargetTest.cpp. Pengujian memverifikasi bahwa metode dasar diterapkan dengan benar dan konfigurasi properti yang didukung sudah benar.

Nilai properti kendaraan

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

Kolom	Deskripsi
timestamp	Stempel waktu yang menunjukkan waktu terjadinya peristiwa dan disinkronkan dengan jam SystemClock.elapsedRealtimeNano().
prop	ID properti untuk nilai ini.
areaid	ID area untuk nilai ini. Area harus merupakan 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 di value.int32Values digunakan untuk properti jenis Int32. Untuk mengetahui detailnya, lihat Konfigurasi Properti.

getValues dan setValues asinkron

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

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

Gambar 1. Proses asinkron.

Parcelable besar

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

Panduan	Deskripsi
payloads	Daftar nilai jika ukuran nilai sesuai dengan batasan memori binder, atau daftar kosong.
sharedMemoryFd	Deskripsi file nullable yang mengarah ke file memori bersama yang menyimpan payload serialisasi 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 sharedMemoryFd non-null.

• Jika tidak kosong, payloads akan menyimpan daftar data sebenarnya, yaitu konfigurasi properti.
• Jika sharedMemoryFd bukan null, file tersebut berisi file memori bersama, yang menyimpan struktur serial VehiclePropConfigs. Struktur ini menggunakan fungsi writeToParcel untuk menserialisasi 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 library LargeParcelable atau class wrapper yang berguna untuk library di ParcelableUtils.h.

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

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

Contoh implementasi VHAL yang mengirim 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.
}