يصف هذا المستند تجزئة واجهة 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::typeshidl-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::INfchidl-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::INfcClientCallbackhidl-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 )، يجب تعديل الملف
استقرار أبي
تشتمل الواجهة الثنائية للتطبيق (ABI) على الروابط الثنائية/اتفاقيات الاتصال/إلخ. إذا تغير ABI/API، فلن تعمل الواجهة بعد ذلك مع system.img
العام الذي تم تجميعه باستخدام الواجهات الرسمية.
يعد التأكد من إصدار الواجهات وثبات ABI أمرًا بالغ الأهمية لعدة أسباب:
- إنه يضمن أن التنفيذ الخاص بك يمكنه اجتياز مجموعة اختبار البائع (VTS)، مما يضعك على المسار الصحيح لتكون قادرًا على تنفيذ وكالات السفر عبر الإنترنت لإطار العمل فقط.
- باعتبارك أحد مصنعي المعدات الأصلية (OEM)، فإنه يمكّنك من توفير حزمة دعم اللوحة (BSP) التي تتميز بسهولة الاستخدام ومتوافقة.
- يساعدك على تتبع الواجهات التي يمكن إصدارها. خذ بعين الاعتبار
current.txt
عبارة عن خريطة لدليل الواجهات الذي يسمح لك برؤية تاريخ وحالة جميع الواجهات المتوفرة في جذر الحزمة.
عند إضافة تجزئة جديدة لواجهة تحتوي بالفعل على إدخال في current.txt
، تأكد من إضافة التجزئة التي تمثل الواجهات التي تحافظ على استقرار ABI فقط. قم بمراجعة أنواع التغييرات التالية:
التغييرات مسموح بها |
|
---|---|
التغييرات غير مسموح بها |
|