อินเทอร์เฟซ VHAL

VHAL ของ AIDL มีการกำหนดไว้ใน android.hardware.automotive.vehicle namespace อินเทอร์เฟซ VHAL กำหนดไว้ที่ IVehicle.aidl เว้นแต่จะระบุไว้เป็นอย่างอื่น วิธีการทั้งหมดต้องได้รับการติดตั้งใช้งานสำหรับ VHAL เวอร์ชันที่เฉพาะเจาะจง

เวอร์ชัน

เวอร์ชัน Android	เวอร์ชัน VHAL ล่าสุด	เวอร์ชันล่าสุดของพร็อพเพอร์ตี้ VHAL	เวอร์ชัน VHAL ขั้นต่ำที่เข้ากันได้
Android 16	V4	V4	V1
Android 15	V3	V3	V1
Android 14	V2	V2	V1
Android 13	V1	(ไม่ได้แยกอินเทอร์เฟซพร็อพเพอร์ตี้ VHAL)	V1

เราขอแนะนำให้ใช้ VHAL เวอร์ชันล่าสุดสำหรับ Android เวอร์ชันที่เฉพาะเจาะจง

ฟังก์ชันและ Callback

ฟังก์ชัน VHAL มีคำจำกัดความอยู่ที่ IVehicle.aidl

วิธีการ
VehiclePropConfigs getAllPropConfigs() แสดงรายการการกำหนดค่าพร็อพเพอร์ตี้ทั้งหมดที่ HAL ของยานพาหนะนี้รองรับ
VehiclePropConfigs getPropConfigs(in int[] props) แสดงรายการ การกำหนดค่าพร็อพเพอร์ตี้สำหรับ รหัสพร็อพเพอร์ตี้ที่ระบุ
void getValues(IVehicleCallback callback, in GetValueRequests requests) รับค่าพร็อพเพอร์ตี้ยานพาหนะแบบไม่พร้อมกัน จัดการกลุ่ม ของ GetValueRequest แบบไม่พร้อมกัน ระบบจะส่งผลลัพธ์ผ่าน onGetValues ของการเรียกกลับ
void setValues(IVehicleCallback callback, in SetValueRequests requests) ตั้งค่าพร็อพเพอร์ตี้ยานพาหนะแบบไม่พร้อมกัน จัดการกลุ่ม SetValueRequest แบบไม่พร้อมกัน ระบบจะส่งผลลัพธ์ผ่าน onSetValues ของการเรียกกลับ
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount) ติดตามเหตุการณ์พร็อพเพอร์ตี้ด้วยตัวเลือกที่ระบุ ตัวเลือกการติดตามประกอบด้วย รหัสพร็อพเพอร์ตี้ รหัสพื้นที่พร็อพเพอร์ตี้ และอัตราการสุ่มตัวอย่างในหน่วย Hz (สำหรับพร็อพเพอร์ตี้แบบต่อเนื่อง) ไม่ได้ใช้ maxSharedMemoryFileCount
void unsubscribe(in IVehicleCallback callback, in int[] propIds) ยกเลิกการติดตามเหตุการณ์พร็อพเพอร์ตี้ที่ติดตามก่อนหน้านี้สำหรับพร็อพเพอร์ตี้ที่ระบุ
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId) ไม่ได้ใช้และสามารถนำไปใช้เป็น no-op ได้
(ใหม่ใน Android 16) SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds) รับรายการค่าที่รองรับสำหรับคู่รหัสพร็อพเพอร์ตี้และรหัสพื้นที่ที่ระบุ เปิดตัวใน VHAL V4
(ใหม่ใน Android 16) MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds) รับค่าต่ำสุดและสูงสุดที่รองรับสำหรับคู่รหัสพร็อพเพอร์ตี้และรหัสพื้นที่ที่ระบุ เปิดตัวใน VHAL V4
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds) ลงทะเบียน Callback ที่จะเรียกใช้เมื่อค่าที่รองรับมีการเปลี่ยนแปลง เปิดตัวใน VHAL V4
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds) ยกเลิกการลงทะเบียน Callback การเปลี่ยนแปลงค่าที่รองรับ เปิดตัวใน VHAL V4

โดยจะกำหนดการเรียกกลับที่ IVehicleCallback.aidl และมีเมธอดต่อไปนี้

วิธีการ
oneway void onGetValues(in GetValueResults responses) Callback สำหรับฟังก์ชัน getValues เพื่อแสดงผลลัพธ์ของฟังก์ชัน get value เรียกใช้ เมื่อค่าบางค่าที่จะดึงข้อมูลพร้อมใช้งาน
oneway void onSetValues(in SetValueResults responses) Callback for setValues function to deliver set value results. เรียกใช้เมื่อ VHAL จัดการคำขอตั้งค่าพร็อพเพอร์ตี้บางรายการเสร็จแล้ว
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount) การเรียกกลับสําหรับการรายงานเหตุการณ์การอัปเดตพร็อพเพอร์ตี้ พร็อพเพอร์ตี้ CONTINUOUS เหตุการณ์พร็อพเพอร์ตี้จะเกิดขึ้นตามอัตราการสุ่มตัวอย่างการติดตาม ใน Hz หรือความถี่ของข้อความบัสของยานพาหนะ นอกจากนี้ เหตุการณ์พร็อพเพอร์ตี้อาจเกิดขึ้นหากสถานะของพร็อพเพอร์ตี้มีการเปลี่ยนแปลง ด้วย เช่น จากไม่พร้อมใช้งานเป็นพร้อมใช้งาน สำหรับพร็อพเพอร์ตี้ ON_CHANGE เหตุการณ์พร็อพเพอร์ตี้จะเกิดขึ้นเมื่อค่าของพร็อพเพอร์ตี้ หรือสถานะของพร็อพเพอร์ตี้เปลี่ยนแปลง ควรใช้เพื่อส่งเหตุการณ์การเปลี่ยนแปลงสถานะพร็อพเพอร์ตี้ด้วย เช่น เมื่อพร็อพเพอร์ตี้ ไม่พร้อมใช้งานหรือเกิดข้อผิดพลาดในการอ่าน ควรส่ง VehiclePropValue ที่มีสถานะไม่พร้อมใช้งานหรือข้อผิดพลาด และค่าว่าง SharedMemoryFileCount จะเป็น 0 เสมอ
oneway void onPropertySetError(in VehiclePropErrors errors) การเรียกกลับสำหรับการรายงานข้อผิดพลาดในการตั้งค่าพร็อพเพอร์ตี้แบบไม่พร้อมกันที่ไม่มีคำขอตั้งค่าที่เกี่ยวข้อง หากเราทราบว่าคำขอตั้งค่าใดที่เกิดข้อผิดพลาด จะต้องใช้ onSetValues ที่มีผลลัพธ์ข้อผิดพลาดแทน
oneway void onSupportedValueChange(in List propIdAreaIds) การเรียกกลับสำหรับการรายงานการเปลี่ยนแปลงค่าต่ำสุดและสูงสุดที่รองรับ หรือรายการค่าที่รองรับ ผู้โทร ควรโทรหา getMinMaxSupportedValue หรือ getSupportedValuesLists เพื่อรับค่าที่อัปเดต

VHAL VTS จะตรวจสอบความถูกต้องของการใช้งาน VHAL ที่ VtsHalAutomotiveVehicle_TargetTest.cpp

การทดสอบจะยืนยันว่าได้ใช้เมธอดพื้นฐานอย่างถูกต้องและการกำหนดค่าพร็อพเพอร์ตี้ที่รองรับถูกต้อง การทดสอบจะทำงานกับอินสแตนซ์ VHAL ทั้งหมดในอุปกรณ์ แต่ AAOS จะใช้อินสแตนซ์เริ่มต้น (android.hardware.automotive.vehicle.IVehicle/default) เท่านั้น

มูลค่าพร็อพเพอร์ตี้ยานพาหนะ

ใช้โครงสร้าง VehiclePropValue เพื่ออธิบายค่าของแต่ละพร็อพเพอร์ตี้ ซึ่งมีช่องต่อไปนี้

ช่อง	คำอธิบาย
timestamp	การประทับเวลาที่แสดงเวลาที่เกิดเหตุการณ์และซิงค์กับ SystemClock.elapsedRealtimeNano() นาฬิกา
prop	รหัสพร็อพเพอร์ตี้สำหรับค่านี้
areaid	รหัสพื้นที่สำหรับค่านี้ พื้นที่ต้องเป็นหนึ่งในพื้นที่ที่รองรับซึ่งระบุไว้ในการกำหนดค่ารหัสพื้นที่ หรือ 0 สำหรับพร็อพเพอร์ตี้ทั่วโลก
value	โครงสร้างข้อมูลที่มีค่าพร็อพเพอร์ตี้จริง ระบบจะใช้ฟิลด์อย่างน้อย 1 รายการภายในฟิลด์นี้เพื่อจัดเก็บค่าจริงตามประเภทพร็อพเพอร์ตี้ เช่น องค์ประกอบแรกใน value.int32Values ใช้สำหรับพร็อพเพอร์ตี้ประเภท Int32 โปรดดูรายละเอียดที่ การกำหนดค่า พร็อพเพอร์ตี้
status	สถานะของพร็อพเพอร์ตี้สำหรับการอ่าน สำหรับพร็อพเพอร์ตี้แบบอ่าน/เขียน อาจใช้ได้กับการเขียนด้วย แต่ไม่รับประกัน เช่น พร็อพเพอร์ตี้อาจพร้อมใช้งานสำหรับการอ่าน แต่ไม่พร้อมใช้งานสำหรับการเขียน ในกรณีดังกล่าว สถานะจะเป็น AVAILABLE และช่องค่าจะมีข้อมูลที่ถูกต้อง หมายเหตุ: ปัจจุบันยังไม่มีวิธีให้ไคลเอ็นต์ตรวจสอบสถานะการเขียนสำหรับ พร็อพเพอร์ตี้อ่าน/เขียนหรือเขียน ไคลเอ็นต์จะทราบว่าพร็อพเพอร์ตี้พร้อมสำหรับการเขียนหรือไม่ เมื่อพยายามตั้งค่า สำคัญ: หากสถานะไม่ใช่ AVAILABLE คุณต้องไม่สนใจช่องค่า ดูสถานะที่เป็นไปได้ได้ที่ VehiclePropertyStatus

getValues และ setValues แบบอะซิงโครนัส

การดำเนินการ getValues และ setValues จะดำเนินการแบบไม่พร้อมกัน ซึ่งหมายความว่าฟังก์ชันอาจแสดงผลก่อนที่การดำเนินการรับหรือตั้งค่าจริงจะเสร็จสมบูรณ์ ผลลัพธ์ของการดำเนินการ (เช่น มูลค่าพร็อพเพอร์ตี้สำหรับ getValues และสถานะสำเร็จหรือข้อผิดพลาดสำหรับ setValues) จะแสดงผ่านการเรียกกลับที่ส่งเป็นอาร์กิวเมนต์

การติดตั้งใช้งานต้องไม่บล็อกผลลัพธ์ในเธรด Binder ที่จัดการคำขอ แต่เราขอแนะนำให้คุณจัดเก็บคำขอในคิวคำขอและใช้เธรดตัวแฮนเดิลแยกต่างหาก เพื่อจัดการคำขอแบบอะซิงโครนัส ดูรายละเอียดได้ที่ การติดตั้งใช้งานอ้างอิง

รูปที่ 1 กระบวนการแบบอะซิงโครนัส

ไฟล์พาร์เซลขนาดใหญ่

โครงสร้างทั้งหมดที่ชื่อ XXXs เช่น VehiclePropConfigs, SetValueRequests และ VehiclePropValues เรียกว่า LargeParcelable (หรือ StableLargeParcelable) แต่ละโครงสร้างแสดงรายการค่าที่ใช้ในการส่งข้อมูลขนาดใหญ่ซึ่งอาจเกินขีดจำกัดของ Binder (4 KB ในการติดตั้งใช้งานไลบรารี LargeParcelable) ข้ามขอบเขตของ Binder แต่ละรายการมีคำจำกัดความโครงสร้างที่คล้ายกัน ซึ่งมีฟิลด์ต่อไปนี้

คำแนะนำ	คำอธิบาย
payloads	รายการค่าเมื่อขนาดค่าอยู่ในขีดจำกัดหน่วยความจำของ Binder หรือรายการว่าง
sharedMemoryFd	ตัวอธิบายไฟล์ที่อนุญาตให้เป็น Null ซึ่งชี้ไปยังไฟล์หน่วยความจำที่แชร์ซึ่งจัดเก็บเพย์โหลดที่ซีเรียลไลซ์แล้ว หากรายการค่ามีขนาดใหญ่เกินไป

เช่น VehiclePropConfigs จะกำหนดเป็น

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 มีทั้งเพย์โหลดที่ไม่ว่างเปล่าหรือ sharedMemoryFd ที่ไม่ใช่ค่าว่าง

• หาก payloads ไม่ว่างเปล่า ระบบจะจัดเก็บรายการข้อมูลจริง ซึ่งก็คือ การกำหนดค่าพร็อพเพอร์ตี้
• หาก sharedMemoryFd ไม่ใช่ค่าว่าง แสดงว่ามีไฟล์หน่วยความจำที่ใช้ร่วมกันซึ่งจัดเก็บโครงสร้างที่ซีเรียลไลซ์ของ VehiclePropConfigs โครงสร้างใช้ฟังก์ชัน writeToParcel เพื่อจัดลำดับออบเจ็กต์ Parcel

ในฐานะไคลเอ็นต์ Java สำหรับ VHAL บริการรถยนต์จะจัดการการซีเรียลไลซ์และการดีซีเรียลไลซ์สำหรับ LargeParcelable สำหรับการติดตั้งใช้งาน VHAL และไคลเอ็นต์ดั้งเดิม คุณควรซีเรียลไลซ์และดีซีเรียลไลซ์ LargeParcelable ด้วยไลบรารี LargeParcelable หรือคลาส Wrapper ที่มีประโยชน์สำหรับไลบรารีใน ParcelableUtils.h

ตัวอย่างเช่น ไคลเอ็นต์เนทีฟที่แยกวิเคราะห์คำขอสำหรับ getValues ที่ได้รับจาก Binder มีดังนี้

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

ตัวอย่างการติดตั้งใช้งาน VHAL ที่ส่งผลลัพธ์สำหรับ getValues ผ่าน Binder จะแสดงอยู่ด้านล่าง

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