อินเทอร์เฟซ 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 ของ Callback
void setValues(IVehicleCallback callback, in SetValueRequests requests) ตั้งค่าค่าพร็อพเพอร์ตี้ยานพาหนะแบบไม่พร้อมกัน จัดการSetValueRequestแบบเป็นกลุ่มแบบไม่พร้อมกัน ระบบจะแสดงผลลัพธ์ผ่านเมธอด onSetValues ของ Callback
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) ไม่ได้ใช้และสามารถติดตั้งใช้งานแบบไม่ทําการได้
(ใหม่ใน 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) ลงทะเบียนการเรียกกลับที่จะเรียกใช้เมื่อค่าที่รองรับมีการเปลี่ยนแปลง เปิดตัวใน VHAL V4
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds) ยกเลิกการลงทะเบียน Callback การเปลี่ยนแปลงค่าที่รองรับ เปิดตัวใน VHAL V4

มีการกําหนดการเรียกกลับที่ IVehicleCallback.aidl และมีวิธีการเหล่านี้

วิธีการ
oneway void onGetValues(in GetValueResults responses) การเรียกกลับสําหรับฟังก์ชัน getValues เพื่อแสดงผลลัพธ์ของ get value เรียกใช้เมื่อค่าที่จะดึงข้อมูลบางส่วนพร้อมแล้ว
oneway void onSetValues(in SetValueResults responses) ฟังก์ชัน Callback สําหรับฟังก์ชัน setValues เพื่อแสดงผลลัพธ์ของค่าที่ตั้งไว้ เรียกใช้เมื่อ 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 ได้รับการตรวจสอบโดย VHAL VTS ที่ 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 จะดำเนินการแบบไม่พร้อมกัน ซึ่งหมายความว่าฟังก์ชันอาจแสดงผลก่อนการดำเนินการ get หรือ set จริงเสร็จสมบูรณ์ ระบบจะส่งผลลัพธ์การดำเนินการ (เช่น ค่าพร็อพเพอร์ตี้สำหรับ getValues และสถานะสำเร็จหรือข้อผิดพลาดสำหรับ setValues) ผ่านคอลแบ็กที่ส่งเป็นอาร์กิวเมนต์

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

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

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

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

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

เช่น 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 ที่ไม่ใช่ค่า Null

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

ในฐานะไคลเอ็นต์ 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.
}