Hash של ממשק

מסמך זה מתאר גיבוב של ממשק 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

הערה: כדי לעזור לעקוב אחר ה-hashs מהיכן, Google מפרידה קובצי HIDL current.txt למקטעים שונים: הקטע הראשון פורסם ב-Android O ; הסעיף הבא ישוחרר ב-Android O MR1 . אנו ממליצים בחום להשתמש בפריסה דומה בקובץ current.txt שלך.

hashing עם hidl-gen

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

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 עבור ממשק שפורסם בעבר. בעת שינוי ממשק כזה, הוסף hash חדש לסוף קובץ ה- current.txt . לפרטים, עיין ב- ABI יציבות .

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

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

יציבות ABI

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

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

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

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