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

AIDL VHAL มีการกำหนดไว้ใน 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)
ลงทะเบียนการเรียกกลับที่จะเรียกใช้เมื่อค่าที่รองรับมีการเปลี่ยนแปลง
เปิดตัวใน VHAL V4
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
ยกเลิกการลงทะเบียน Callback การเปลี่ยนแปลงค่าที่รองรับ
เปิดตัวใน VHAL V4

โดยกำหนด Callback ไว้ที่ 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 และช่องค่าจะมีข้อมูลที่ถูกต้อง ดูสถานะที่เป็นไปได้ได้ที่ VehiclePropertyStatus

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

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

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

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

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

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