اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يوضّح هذا المستند تجزئة واجهة 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...995f9ec4vendor.awesome.foo@1.0::IFoo#commentscanalsogohere# types.hal files are also noted in current.txt filesc84da9f5...f8ea2648vendor.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...74d63b8cvendor.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 (تم اختصار العلامات التجزئية):
تحذير: لا تستبدِل تجزئة لواجهة
تم إصدارها سابقًا. عند تغيير واجهة مماثلة، أضِف تجزئة جديدة
إلى نهاية ملف 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. راجِع الأنواع التالية من التغييرات:
التغييرات المسموح بها
تغيير تعليق (ما لم يؤدّ ذلك إلى تغيير معنى إحدى الطرق)
تغيير اسم مَعلمة
تغيير اسم مَعلمة الإرجاع
تغيير التعليقات التوضيحية
التغييرات غير مسموح بها
إعادة ترتيب الوسيطات والأساليب وما إلى ذلك
إعادة تسمية واجهة أو نقلها إلى حزمة جديدة
إعادة تسمية حزمة
إضافة طريقة/حقل بنية/غير ذلك في أي مكان في الواجهة
أيّ شيء قد يؤدي إلى تعطُّل جدول بيانات C++
إلخ
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Interface hashing\n\nThis document describes HIDL interface hashing, a mechanism to prevent\naccidental interface changes and ensure interface changes are thoroughly vetted.\nThis mechanism is required because HIDL interfaces are versioned, which means\nthat after an interface is released it must not be changed except in an\napplication binary interface (ABI) preserving manner (such as a comment\ncorrection).\n\nLayout\n------\n\nEvery package root directory (i.e. `android.hardware` mapping to\n`hardware/interfaces` or `vendor.foo` mapping to\n`vendor/foo/hardware/interfaces`) must contain a\n`current.txt` file that lists all released HIDL interface files. \n\n```objective-c\n# current.txt files support comments starting with a '#' character\n# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt\n\n# Each line has a SHA-256 hash followed by the name of an interface.\n# They have been shortened in this doc for brevity but they are\n# 64 characters in length in an actual current.txt file.\nd4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here\n\n# types.hal files are also noted in current.txt files\nc84da9f5...f8ea2648 vendor.awesome.foo@1.0::types\n\n# Multiple hashes can be in the file for the same interface. This can be used\n# to note how ABI sustaining changes were made to the interface.\n# For instance, here is another hash for IFoo:\n\n# Fixes type where \"FooCallback\" was misspelled in comment on \"FooStruct\"\n822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo\n```\n\n**Note:** To help keep track of which hashes come\nfrom where, Google separates HIDL `current.txt` files into different\nsections: The first section is *Released in Android 8* ; the next section\nwill be *Released in Android 8 MR1* . We strongly recommend using a\nsimilar layout in your `current.txt` file.\n\nHash with hidl-gen\n------------------\n\nYou can add a hash to a `current.txt` file manually or by\nusing `hidl-gen`. The following code snippet provides examples of\ncommands you can use with `hidl-gen` to manage a\n`current.txt` file (hashes have been shortened): \n\n 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\n 9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types\n 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\n 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc\n 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\n 9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types\n 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc\n f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback\n 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 \u003e\u003e vendor/awesome/hardware/interfaces/current.txt\n\n**Warning:** Do not replace a hash for a\npreviously-released interface. When changing such an interface, add a new hash\nto the end of the `current.txt` file. For details, refer to\n[ABI stability](#abi-stability).\n\nEvery interface definition library generated by `hidl-gen`\nincludes hashes, which can be retrieved by calling\n`IBase::getHashChain`. When `hidl-gen` is compiling an\ninterface, it checks the `current.txt` file in the root directory of\nthe HAL package to see if the HAL has been changed:\n\n- If no hash for the HAL is found, the interface is considered unreleased (in development) and compilation proceeds.\n- If hashes are found, they are checked against the current interface:\n - If the interface does match the hash, compilation proceeds.\n - If the interface does not match a hash, compilation is halted as this means a previously-released interface is being changed.\n - For an ABI-preserving change (see [ABI stability](#abi-stability)), the `current.txt` file must be modified before compilation can proceed.\n - All other changes should be made in a minor or major version upgrade of the interface.\n\nABI stability\n-------------\n\n| **Key Point:** Please read and understand this section carefully.\n\nAn ABI includes the binary\nlinkages/calling conventions/etc. If the ABI or API changes, the interface no\nlonger works with a generic `system.img` that was compiled with\nofficial interfaces.\n\nMaking sure that interfaces are versioned and ABI stable is\n**crucial** for several reasons:\n\n- It ensures your implementation can pass the Vendor Test Suite (VTS), which puts you on track to being able to do framework-only OTAs.\n- As an OEM, it enables you to provide a Board Support Package (BSP) that is straightforward to use and compliant.\n- It helps you keep track of what interfaces can be released. Consider `current.txt` a map of an interfaces directory that allows you to see the history and state of all interfaces being provided in a package root.\n\nWhen adding a new hash for an interface that already has an entry in\n`current.txt`, make sure to add only the hashes that represent\ninterfaces which maintain ABI stability. Review the following types of changes:\n\n| Changes allowed | - Changing a comment (unless this changes the meaning of a method). - Changing the name of a parameter. - Changing the name of a return parameter. - Changing annotations. |\n| Changes not allowed | - Reordering arguments, methods, etc. - Renaming an interface or moving it to a new package. - Renaming a package. - Adding a method/struct field/etc. anywhere in the interface. - Anything that would break a C++ vtable. - etc. |\n|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|"]]
