تجزئة الواجهة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

ثبات ABI

يتضمّن ABI روابط ثنائية/اتّفاقيات الاستدعاء/غير ذلك. في حال تغيّر ABI أو واجهة برمجة التطبيقات، لن تعمل الواجهة بعد ذلك مع system.img عام تم تجميعه باستخدام واجهات رسمية.

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

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

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