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

เอกสารนี้อธิบายการแฮชอินเทอร์เฟซ HIDL ซึ่งเป็นกลไกในการป้องกัน การเปลี่ยนแปลงอินเทอร์เฟซโดยไม่ตั้งใจ และตรวจสอบว่าการเปลี่ยนแปลงอินเทอร์เฟซได้รับการตรวจสอบอย่างละเอียดแล้ว คุณจำเป็นต้องใช้กลไกนี้เนื่องจากอินเทอร์เฟซ HIDL เป็นเวอร์ชันต่างๆ ซึ่งหมายความว่า หลังจากเปิดตัวอินเทอร์เฟซแล้ว จะต้องไม่มีการเปลี่ยนแปลง ยกเว้นใน ลักษณะการคงลักษณะการใช้งานอินเทอร์เฟซไบนารีของแอปพลิเคชัน (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 8 ส่วนถัดไป จะเปิดตัวใน Android 8 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 ต้องแก้ไขก่อนจึงจะสามารถทำการคอมไพล์ได้
    • การเปลี่ยนแปลงอื่นๆ ทั้งหมดควรทำในการอัปเกรดเวอร์ชันย่อยหรือหลัก ของ Google

ความเสถียรของ ABI

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

ABI รวมเลขฐานสอง การเชื่อมโยง/การเรียกประชุม/ฯลฯ ถ้า ABI หรือ API เปลี่ยนแปลง อินเทอร์เฟซหมายเลข ทำงานนานขึ้นกับ system.img ทั่วไปที่คอมไพล์ด้วย อินเทอร์เฟซอย่างเป็นทางการ

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

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

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

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