גיבוב (hashing) בממשק

במסמך הזה מתואר גיבוב (hashing) של ממשק 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 מפרידה קובצי current.txt HIDL קטעים: הקטע הראשון הוא הושק ב-Android 8. הקטע הבא יושק ב-Android 8 MR1. מומלץ מאוד להשתמש פריסה דומה בקובץ current.txt שלך.

גיבוב (hash) עם 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

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

כל ספריית הגדרה של ממשק שנוצרה על ידי hidl-gen כולל גיבובים, שניתן לאחזר באמצעות קריאה IBase::getHashChain. כש-hidl-gen מחבר הוא בודק את הקובץ current.txt בתיקיית השורש של חבילת ה-HAL כדי לראות אם ה-HAL השתנה:

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

יציבות ABI

נקודה חשובה: חשוב לקרוא ולהבין בזהירות רבה.

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

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

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

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

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