درحال درهم‌سازی میانا

این سند درهم‌سازی میانای 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

می‌توانید درهم‌سازی را به‌صورت دستی یا بااستفاده از hidl-gen به فایل current.txt اضافه کنید. تکه‌کد زیر نمونه‌هایی از فرمان‌هایی را ارائه می‌دهد که می‌توانید با 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

«میانای برنامه‌های کاربردی» شامل پیوندهای باینری/قراردادهای فراخوانی/و غیره می‌شود. اگر «میانای برنامه‌های کاربردی» یا «میانای برنامه‌سازی کاربردی» تغییر کند، دیگر میانای برنامه‌های کاربردی با system.img عمومی که با میاناهای رسمی تدوین شده است کار نمی‌کند.

اطمینان از اینکه واسط‌ها دارای نسخه و ABI پایدار هستند به چند دلیل حیاتی است:

• این کار تضمین می‌کند که پیاده‌سازی شما بتواند «مجموعه آزمون فروشنده» (VTS) را بگذراند، که شما را در مسیر انجام «به‌روزرسانی‌های نرم‌افزار از راه دور» (OTA) فقط چارچوب قرار می‌دهد.
• به‌عنوان سازنده تجهیزات اصلی، این ویژگی به شما امکان می‌دهد «بسته پشتیبانی برد» (BSP) ارائه دهید که استفاده از آن آسان و سازگار باشد.
• این کار به شما کمک می‌کند پیگیری کنید کدام میان‌ها می‌تواند منتشر شود. به‌عنوان مثال، current.txt نقشه فهرستگان رابط‌ها را درنظر بگیرید که به شما امکان می‌دهد سابقه و وضعیت همه رابط‌های ارائه‌شده در ریشه بسته را ببینید.

هنگام افزودن درهم‌سازی جدید برای میانایی که ازقبل ورودی‌ای در current.txt دارد، مطمئن شوید فقط درهم‌سازی‌هایی را اضافه کنید که نشان‌دهنده میاناهایی هستند که پایداری ABI را حفظ می‌کنند. انواع تغییرات زیر را بررسی کنید: