از 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 منتشر شده است. بخش بعدی در اندروید 8 MR1 منتشر خواهد شد. ما قویاً توصیه می کنیم از طرح بندی مشابهی در فایل current.txt خود استفاده کنید.
هش با hidl-gen
می توانید به صورت دستی یا با استفاده از hidl-gen یک هش به فایل current.txt اضافه کنید. قطعه کد زیر نمونه‌هایی از دستوراتی را ارائه می‌کند که می‌توانید با 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 یا API تغییر کند، رابط دیگر با یک system.img عمومی که با رابط های رسمی کامپایل شده است کار نمی کند.
اطمینان از اینکه اینترفیس ها نسخه بندی شده و ABI پایدار هستند به چند دلیل بسیار مهم است:
این تضمین می‌کند که پیاده‌سازی شما می‌تواند مجموعه تست فروشنده (VTS) را پشت سر بگذارد، که شما را در مسیری قرار می‌دهد که بتوانید OTAهای فقط چارچوبی را انجام دهید.
به عنوان یک OEM، به شما این امکان را می دهد که یک بسته پشتیبانی هیئت مدیره (BSP) ارائه دهید که استفاده از آن ساده و سازگار است.
این به شما کمک می کند تا ببینید چه رابط هایی می توانند منتشر شوند. current.txt را نقشه ای از دایرکتوری واسط ها در نظر بگیرید که به شما امکان می دهد تاریخچه و وضعیت همه اینترفیس های ارائه شده در ریشه بسته را ببینید.
هنگام افزودن هش جدید برای رابطی که از قبل دارای ورودی در current.txt است، مطمئن شوید که فقط هش هایی را اضافه کنید که نمایانگر رابط هایی هستند که پایداری ABI را حفظ می کنند. انواع تغییرات زیر را مرور کنید:
تغییرات مجاز است
تغییر یک نظر (مگر اینکه این معنی یک روش را تغییر دهد).
تغییر نام یک پارامتر
تغییر نام پارامتر بازگشتی
تغییر حاشیه نویسی
تغییرات مجاز نیست
مرتب سازی مجدد آرگومان ها، روش ها و غیره
تغییر نام یک رابط یا انتقال آن به یک بسته جدید.
تغییر نام یک بسته
افزودن فیلد متد/ ساختار/غیره در هر نقطه از رابط
هر چیزی که یک vtable C++ را خراب کند.
و غیره
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-29 بهوقت ساعت هماهنگ جهانی."],[],[],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|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|"]]
