อินเทอร์เฟซ 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 เวอร์ชันที่เฉพาะเจาะจง

ฟังก์ชันและการเรียกกลับ

ฟังก์ชัน 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)
ยกเลิกการลงทะเบียนการเรียกกลับการเปลี่ยนแปลงค่าที่รองรับ
เปิดตัวใน VHAL V4

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

วิธีการ
oneway void onGetValues(in GetValueResults responses)
การเรียกกลับสำหรับฟังก์ชัน getValues เพื่อส่งผลลัพธ์การรับค่า เรียกเมื่อค่าบางค่าที่จะดึงข้อมูลพร้อมแล้ว
oneway void onSetValues(in SetValueResults responses)
การเรียกกลับสำหรับฟังก์ชัน 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 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 กระบวนการแบบอะซิงโครนัส

LargeParcelable

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

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

ในฐานะไคลเอ็นต์ Java สำหรับ VHAL, Car Service จะจัดการการซีเรียลไลซ์และการดีซีเรียลไลซ์สำหรับ 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.
}