การแฮชอินเทอร์เฟซ

เอกสารนี้อธิบายการแฮชอินเทอร์เฟซ HIDL ซึ่งเป็นกลไกในการป้องกันการเปลี่ยนแปลงอินเทอร์เฟซโดยไม่ตั้งใจ และช่วยให้แน่ใจว่าการเปลี่ยนแปลงอินเทอร์เฟซได้รับการตรวจสอบอย่างละเอียด กลไกนี้จำเป็นเนื่องจากอินเทอร์เฟซ HIDL ได้รับการกำหนดเวอร์ชันแล้ว ซึ่งหมายความว่าหลังจากอินเทอร์เฟซถูกเผยแพร่แล้ว จะต้องไม่สามารถเปลี่ยนแปลงได้ ยกเว้นในรูปแบบการรักษา Application Binary Interface (ABI) (เช่น การแก้ไขความคิดเห็น)

เค้าโครง

ทุกไดเรกทอรีรากของแพ็คเกจ (เช่น การแมป android.hardware กับ hardware/interfaces หรือการแมป vendor.foo กับ vendor/foo/hardware/interfaces ) จะต้องมีไฟล์ current.txt ที่แสดงรายการไฟล์อินเทอร์เฟซ HIDL ที่เผยแพร่ทั้งหมด

# current.txt files support comments starting with a ‘#' character
# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt

# Each line has a SHA-256 hash followed by the name of an interface.
# They have been shortened in this doc for brevity but they are
# 64 characters in length in an actual current.txt file.
d4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here

# types.hal files are also noted in current.txt files
c84da9f5...f8ea2648 vendor.awesome.foo@1.0::types

# Multiple hashes can be in the file for the same interface. This can be used
# to note how ABI sustaining changes were made to the interface.
# For instance, here is another hash for IFoo:

# Fixes type where "FooCallback" was misspelled in comment on "FooStruct"
822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo

หมายเหตุ: เพื่อช่วยติดตามว่าแฮชใดมาจากไหน Google จึงแยกไฟล์ HIDL current.txt ออกเป็นส่วนต่างๆ: ส่วนแรก เปิดตัวใน Android O ; ส่วนถัดไปจะ เปิดตัวใน Android O MR1 เราขอแนะนำอย่างยิ่งให้ใช้รูปแบบที่คล้ายกันในไฟล์ current.txt ของคุณ

การแฮชด้วย hidl-gen

คุณสามารถเพิ่มแฮชลงในไฟล์ current.txt ด้วยตนเองหรือโดยใช้ hidl-gen ข้อมูลโค้ดต่อไปนี้มีตัวอย่างคำสั่งที่คุณสามารถใช้กับ hidl-gen เพื่อจัดการไฟล์ current.txt (แฮชถูกทำให้สั้นลง):

hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 >> vendor/awesome/hardware/interfaces/current.txt

คำเตือน: อย่าแทนที่แฮชสำหรับอินเทอร์เฟซที่เผยแพร่ก่อนหน้านี้ เมื่อเปลี่ยนอินเทอร์เฟซดังกล่าว ให้เพิ่มแฮชใหม่ต่อท้ายไฟล์ current.txt สำหรับรายละเอียด โปรดดูที่ ความเสถียรของ ABI

ทุกไลบรารีคำจำกัดความของอินเทอร์เฟซที่สร้างโดย hidl-gen จะมีแฮช ซึ่งสามารถดึงข้อมูลได้โดยการเรียก IBase::getHashChain เมื่อ hidl-gen กำลังรวบรวมอินเทอร์เฟซ มันจะตรวจสอบไฟล์ current.txt ในไดเร็กทอรีรากของแพ็คเกจ HAL เพื่อดูว่า HAL มีการเปลี่ยนแปลงหรือไม่:

• หากไม่พบแฮชสำหรับ HAL อินเทอร์เฟซจะถือว่ายังไม่ได้เผยแพร่ (อยู่ระหว่างการพัฒนา) และดำเนินการรวบรวมต่อไป
• หากพบแฮช ระบบจะตรวจสอบแฮชกับอินเทอร์เฟซปัจจุบัน:
  • หากอินเทอร์เฟซตรงกับแฮช การคอมไพล์จะดำเนินการต่อไป
  • หากอินเทอร์เฟซไม่ตรงกับแฮช การคอมไพล์จะหยุดลงเนื่องจากหมายความว่าอินเทอร์เฟซที่เผยแพร่ก่อนหน้านี้มีการเปลี่ยนแปลง
    • สำหรับการเปลี่ยนแปลงที่รักษา ABI (ดู ความเสถียรของ ABI ) ต้องแก้ไขไฟล์ current.txt ก่อนจึงจะสามารถคอมไพล์ได้
    • การเปลี่ยนแปลงอื่นๆ ทั้งหมดควรทำในการอัพเกรดอินเทอร์เฟซเวอร์ชันรองหรือเวอร์ชันหลัก

ความมั่นคงของเอบีไอ

ประเด็นสำคัญ: โปรดอ่านและทำความเข้าใจส่วนนี้อย่างละเอียด

Application Binary Interface (ABI) รวมถึงการเชื่อมโยงไบนารี/แบบแผนการเรียก/อื่นๆ หาก ABI/API เปลี่ยนแปลง อินเทอร์เฟซจะไม่ทำงานกับ system.img ทั่วไปที่คอมไพล์ด้วยอินเทอร์เฟซอย่างเป็นทางการอีกต่อไป

ตรวจสอบให้แน่ใจว่าอินเทอร์เฟซได้รับการกำหนดเวอร์ชันและ ABI เสถียรเป็น สิ่งสำคัญ ด้วยเหตุผลหลายประการ:

• ช่วยให้มั่นใจว่าการใช้งานของคุณสามารถผ่าน Vendor Test Suite (VTS) ซึ่งทำให้คุณสามารถดำเนินการ OTA เฉพาะเฟรมเวิร์กได้
• ในฐานะ OEM คุณสามารถจัดเตรียมแพ็คเกจสนับสนุนบอร์ด (BSP) ที่ใช้งานได้ง่ายและเป็นไปตามข้อกำหนด
• ช่วยให้คุณติดตามว่าอินเทอร์เฟซใดบ้างที่สามารถเผยแพร่ได้ พิจารณา current.txt แผนผังของไดเร็กทอรีอินเทอร์เฟซที่ช่วยให้คุณเห็นประวัติและสถานะของอินเทอร์เฟซทั้งหมดที่มีให้ในรูทแพ็กเกจ

เมื่อเพิ่มแฮชใหม่สำหรับอินเทอร์เฟซที่มีรายการใน current.txt อยู่แล้ว ตรวจสอบให้แน่ใจว่าได้เพิ่มเฉพาะแฮชที่แสดงถึงอินเทอร์เฟซที่รักษาความเสถียรของ ABI ตรวจสอบการเปลี่ยนแปลงประเภทต่อไปนี้:

อนุญาตให้เปลี่ยนแปลงได้	การเปลี่ยนความคิดเห็น (เว้นแต่ว่าสิ่งนี้จะเปลี่ยนความหมายของวิธีการ) การเปลี่ยนชื่อพารามิเตอร์ การเปลี่ยนชื่อพารามิเตอร์ส่งคืน การเปลี่ยนคำอธิบายประกอบ
ไม่อนุญาตให้เปลี่ยนแปลง	การเรียงลำดับอาร์กิวเมนต์ วิธีการ ฯลฯ... การเปลี่ยนชื่ออินเทอร์เฟซหรือย้ายไปยังแพ็คเกจใหม่ การเปลี่ยนชื่อแพ็คเกจ การเพิ่มเมธอด/ฟิลด์ struct/ฯลฯ... ที่ใดก็ได้ในอินเทอร์เฟซ สิ่งใดก็ตามที่จะทำให้ C++ vtable พัง ฯลฯ