واجهة تجزئة

يصف هذا المستند تجزئة واجهة 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 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 قبل أن تتمكن من متابعة التجميع.
    • يجب إجراء جميع التغييرات الأخرى في ترقية الإصدار الثانوي أو الرئيسي للواجهة.

استقرار أبي

تشتمل الواجهة الثنائية للتطبيق (ABI) على الروابط الثنائية/اتفاقيات الاتصال/إلخ. إذا تغير ABI/API، فلن تعمل الواجهة بعد ذلك مع system.img العام الذي تم تجميعه باستخدام الواجهات الرسمية.

يعد التأكد من إصدار الواجهات وثبات ABI أمرًا بالغ الأهمية لعدة أسباب:

• إنه يضمن أن التنفيذ الخاص بك يمكنه اجتياز مجموعة اختبار البائع (VTS)، مما يضعك على المسار الصحيح لتكون قادرًا على تنفيذ وكالات السفر عبر الإنترنت لإطار العمل فقط.
• باعتبارك أحد مصنعي المعدات الأصلية (OEM)، فإنه يمكّنك من توفير حزمة دعم اللوحة (BSP) التي تتميز بسهولة الاستخدام ومتوافقة.
• يساعدك على تتبع الواجهات التي يمكن إصدارها. خذ بعين الاعتبار current.txt عبارة عن خريطة لدليل الواجهات الذي يسمح لك برؤية تاريخ وحالة جميع الواجهات المتوفرة في جذر الحزمة.

عند إضافة تجزئة جديدة لواجهة تحتوي بالفعل على إدخال في current.txt ، تأكد من إضافة التجزئة التي تمثل الواجهات التي تحافظ على استقرار ABI فقط. قم بمراجعة أنواع التغييرات التالية: