גיבוב ממשק

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

במסמך הזה מוסבר על גיבוב ממשק HIDL, מנגנון למניעת שינויים לא מכוונים בממשק ולהבטחת בדיקה יסודית של שינויים בממשק. המנגנון הזה נדרש כי לממשקי HIDL יש גרסאות, כלומר אחרי שממשק מסוים משוחרר, אסור לשנות אותו אלא באופן שמגן על ממשק הבינארי של האפליקציה (ABI) (למשל, תיקון של הערה).

פריסה

כל ספריית root של חבילה (כלומר מיפוי של 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 לקטעים שונים: הקטע הראשון הוא Released in Android 8, והקטע הבא יהיה Released in Android 8 MR1. מומלץ מאוד להשתמש בפריסה דומה בקובץ current.txt.

גיבוב באמצעות hidl-gen

אפשר להוסיף גיבוב לקובץ current.txt באופן ידני או באמצעות hidl-gen. קטע הקוד הבא כולל דוגמאות לפקודות שאפשר להשתמש בהן עם hidl-gen כדי לנהל קובץ current.txt (ה-hashes מקוצרים):

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 כוללת גיבוב (hash), שאפשר לאחזר באמצעות קריאה ל-IBase::getHashChain. כש-hidl-gen יוצר קובץ ‎interface, הוא בודק את הקובץ current.txt בספרייה הראשית של חבילת ה-HAL כדי לראות אם ה-HAL השתנה:

• אם לא נמצא גיבוב של HAL, הממשק נחשב כלא פורסם (בשלבי פיתוח) והאוסף ממשיך.
• אם נמצאים גיבובים, הם נבדקים מול הממשק הנוכחי:
  • אם הממשק תואם לגיבוב, תהליך ה-compilation ממשיך.
  • אם הממשק לא תואם ל-hash, תהליך ה-compilation מושהה כי המשמעות היא שמתבצע שינוי בממשק שפורסם בעבר.
    • כדי לשמור על ABI (ראו יציבות ABI), צריך לשנות את הקובץ current.txt לפני שממשיכים בתהליך ה-compilation.
    • כל שינויים אחרים צריכים להתבצע בשדרוג של גרסה משנית או ראשית של הממשק.

יציבות ABI

ABI כולל את הקישורים הבינאריים, מוסכמות הקריאה וכו'. אם ה-ABI או ה-API משתנים, הממשק לא יפעל יותר עם system.img כללי שעבר הידור באמצעות ממשקים רשמיים.

חשוב מאוד לוודא שהממשקים מחולקים לגרסאות ושה-ABI יציב מכמה סיבות:

• כך תוכלו לוודא שההטמעה שלכם עומדת בדרישות של ערכת בדיקות הספק (VTS), וכך תוכלו לבצע עדכוני OTA רק של המסגרת.
• כ-OEM, ה-BSP מאפשר לכם לספק חבילת תמיכה ללוח (BSP) שתהיה פשוטה לשימוש ותואמת.
• הוא עוזר לכם לעקוב אחרי הממשקים שאפשר להשיק. אפשר להתייחס ל-current.txt כלמפה של ספריית ממשקים שמאפשרת לראות את ההיסטוריה והמצב של כל הממשקים שסופקו ברמה הבסיסית של החבילה.

כשאתם מוסיפים גיבוב חדש לממשק שכבר יש לו רשומה ב-current.txt, חשוב להוסיף רק את הגיבובים שמייצגים ממשקים שמשמרים את היציבות של ABI. כדאי לבדוק את סוגי השינויים הבאים: