מחזור החיים של FCM

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

כדי לאפשר עדכוני OTA של מסגרות בלבד בסביבות העסקיות שלהם, שותפים שמרחיבים את ממשקי הספקים צריכים גם להוציא משימוש ולהסיר את HIDL HALs באמצעות אותן שיטות.

הערה: לפרטים נוספים על HIDL HALs, ראו מטריצות תאימות, כללי התאמה וניהול גרסאות של HIDL HAL.

טרמינולוגיה

מטריצת תאימות של framework (FCM)

קובץ XML שמציין את דרישות המסגרת להטמעות של ספקים שתואמות לה. למטרות ניהול גרסאות, מטריית התאימות מחולקת לגרסאות, וגרסה חדשה קופאת בכל גרסה של המסגרת. כל מהדורה של המסגרת מכילה כמה FCM.

גרסאות של פלטפורמת FCM (S_F)

הקבוצה של כל הגרסאות של FCM במהדורת מסגרת. המסגרת יכולה לפעול עם כל הטמעה של ספק שעומדת באחד מ-FCM האלה.

גרסת FCM (F)

הגרסה הגבוהה ביותר מבין כל ספקי ה-FCM בגרסת framework.

גרסת יעד של FCM (V)

גרסת FCM המטורגטת (מ-S_F), שמוצהרת במפורש במניפסט המכשיר, שהטמעה של ספק עומדת בדרישות. יש ליצור הטמעה של ספק לפי מניפסט FCM שפורסם, אבל אפשר להצהיר על גרסאות HAL חדשות יותר במניפסט המכשיר.

גרסת HAL

גרסת HAL בפורמט foo@x.y, שבו foo הוא שם ה-HAL ו-x.y הוא הגרסה הספציפית. לדוגמה: nfc@1.0, ‏ keymaster@3.0 (הקידומת של הבסיס, למשל android.hardware, לא מופיעה במסמך הזה).

מניפסט של מכשיר

קבצי XML שמציינים אילו גרסאות HAL זמינות בצד המכשיר של ממשק הספק, כולל קובצי האימג' של הספק ושל ה-ODM. התוכן של מניפסט המכשיר מוגבל על ידי גרסת היעד של FCM של המכשיר, אבל הוא יכול לכלול רשימה של רכיבי HAL חדשים באופן מובהק ביחס ל-FC שתואם ל-V.

Device HALs

HAL שרשומים (מסופקים) במניפסט של המכשיר ורשומים (חובה או אופציונלי) במטריצה של תאימות המסגרת (FCM).

Device Compatibility Matrix‏ (DCM)

קובץ XML שמציין את דרישות הספק לגבי הטמעות תואמות של המסגרת. כל מכשיר מכיל DCM אחד.

מניפסט של Framework

קובץ XML שמציין אילו גרסאות HAL יסופקו בצד המסגרת של ממשק הספק, כולל system,‏ system_ext ותמונות של מוצרים. ממשקי HAL במניפסט של המסגרת מושבתים באופן דינמי בהתאם לגרסה של FCM שמוגדרת כיעד במכשיר.

Framework HALs

HALs שמפורטים כחלק מהמניפסט של המסגרת, ומפורטים כחובה או כאופציונליים במטריצה של תאימות המכשירים (DCM).

מחזור החיים של FCM בקוד הבסיס

במסמך הזה מתוארים באופן כללי שלבי מחזור החיים של FCM. כדי לראות את המניפסטים הנתמכים, אפשר לעיין במאמר hardware/interfaces/compatibility_matrix.<FCM>.xml, שבו FCM מופיע בקטע system/libvintf/include/vintf/Level.h.

במכשיר עם גרסת Android המתאימה, הערך של FCM אמור להיות גדול מאותה רמה או שווה לה. לדוגמה, למשלוח של מכשיר עם Android 11 בדרך כלל רמת FCM היא 5, אבל מטמיעים את FCM ברמה 6 ומעלה, שכוללת דרישות נוספות שונות שמפורטות במטריצות התאימות. הרמות הנתמכות הן:

FCM	גרסת Android
4	Android 10/Q
5	Android 11/R
6	Android 12/S
7	Android 13/T
8	Android 14/U
202404	Android 15/V

רמת ה-FCM זהה לרמת ה-API של הספק או חדשה יותר.

כש-Android מפסיקה את השימוש ברמה מסוימת של FCM, היא עדיין נתמכת במכשירים קיימים. מכשירים שמטרגטים רמות נמוכות יותר של FCM מורשים באופן משתמע להשתמש ב-HALs שמפורטים ברמות חדשות יותר של FCM, כל עוד הם זמינים בהסתעפות.

פיתוח בגרסה חדשה של FCM

מערכת Android מגדילה את גרסת FCM לכל גרסת framework (למשל Android 8 ו-8.1). במהלך הפיתוח, ה-compatibility_matrix.F.xml החדש נוצר וה-compatibility_matrix.f.xml הקיים (כאשר f < F) לא משתנה יותר.

כדי להתחיל לפתח גרסה חדשה של FCM : F

1. מעתיקים את compatibility_matrix.<F-1>.xml העדכני ביותר אל compatibility_matrix.F.xml.
2. עליך לעדכן את המאפיין level בקובץ ל-F.
3. מוסיפים כללי build תואמים כדי להתקין את מטריצת התאימות הזו במכשיר.

הצגת HAL חדש

במהלך הפיתוח, כשאתם מוסיפים HAL חדש (Wi-Fi,‏ NFC וכו') ל-Android בגרסה הנוכחית של FCM‏ F, מוסיפים את ה-HAL ל-compatibility_matrix.F.xml עם ההגדרות הבאות של optional:

• optional="false" אם מכשירים ששולחים עם V = F חייבים להתחיל לפעול עם HAL הזה,
• optional="true" אם מכשירים ששולחים עם V = F יכולים לפעול בלי HAL הזה.

לדוגמה, ב-Android 8.1 הוצג cas@1.0 כ-HAL אופציונלי. במכשירים שיושקו עם Android 8.1 אין צורך להטמיע את ה-HAL הזה, ולכן הרשומה הבאה נוספה ל-compatibility_matrix.F.xml (שנקרא compatibility_matrix.current.xml באופן זמני במהלך הפיתוח של הגרסה הזו):

<hal format="hidl" optional="true">
    <name>android.hardware.cas</name>
    <version>1.0</version>
    <interface>
        <name>IMediaCasService</name>
        <instance>default</instance>
    </interface>
</hal>

שדרוג של HAL (גרסה משנית)

במהלך הפיתוח, כשיש ל-HAL שדרוג של גרסה משנית מ-x.z ל-x.(z+1) בגרסה הנוכחית של FCM, F, אם הגרסה הזו:

• נדרש במכשירים שפועלים עם V = F, compatibility_matrix.F.xml חייב לציין x.(z+1) ו-optional="false".
• לא נדרש במכשירים שפועלים עם V = F. ב-compatibility_matrix.F.xml צריך להעתיק את x.y-z ואת האפשרות לבחירה מ-compatibility_matrix.<F-1>.xml ולשנות את הגרסה ל-x.w-(z+1) (כאשר w >= y).

לדוגמה, ב-Android 8.1 הושקה גרסה משנית של broadcastradio@1.1 לשדרוג של 1.0 HAL. הגרסה הישנה יותר, broadcastradio@1.0, היא אופציונלית למכשירים שהושקעו עם Android 8.0, והגרסה החדשה יותר, broadcastradio@1.1, היא אופציונלית למכשירים שהושקעו עם Android 8.1. ב-compatibility_matrix.1.xml:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

הרשומה הזו הועתקה אל compatibility_matrix.F.xml ושונתה באופן הבא:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0-1</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

שדרוג של HAL (שדרוג משמעותי)

במהלך הפיתוח, כשיש ל-HAL שדרוג לגרסה הראשית בגרסה הנוכחית של FCM‏ F, הגרסה הראשית החדשה x.0 מתווספת ל-compatibility_matrix.F.xml עם ההגדרות הבאות של optional:

• optional="false" עם גרסה x.0 בלבד, אם מכשירים ששולחים עם V = F חייבים להתחיל לפעול עם x.0.
• optional="false", אבל יחד עם גרסאות ראשיות ישנות יותר באותו תג <hal>, אם מכשירי V = F חייבים להתחיל לפעול עם HAL הזה, אבל יכולים להתחיל לפעול עם גרסה ראשית ישנה יותר.
• optional="true" אם במכשירים שכוללים את V = F אין צורך להפעיל את ה-HAL.

לדוגמה, ב-Android 9 health@2.0 הוא שדרוג של גרסה ראשית של HAL 1.0, וה-HAL 1.0 הוצא משימוש. הגרסה הישנה יותר, health@1.0, היא אופציונלית למכשירים שהושקעו עם Android 8.0 ו-Android 8.1. במכשירים שיושקו עם Android 9 חייבת להיות גרסה 2.0 החדשה. לדוגמה, נניח שהרשומות compatibility_matrix.legacy.xml,‏ compatibility_matrix.1.xml ו-compatibility_matrix.2.xml מכילות את הערך הזה:

<hal format="hidl" optional="true">
    <name>android.hardware.health</name>
    <version>1.0</version>;
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

מעתיקים את הרשומה הזו ל-compatibility_matrix.F.xml ומשנים אותה באופן הבא:

<hal format="hidl" optional="false">
    <name>android.hardware.health</name>
    <version>2.0</version>
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

הגבלות:

• מכיוון ש-HAL 2.0 נמצא ב-compatibility_matrix.3.xml עם optional="false", מכשירים שיושקו עם Android 9 חייבים להגיע עם HAL 2.0.
• מכיוון ש-HAL 1.0 לא נמצא ב-compatibility_matrix.3.xml, מכשירי Android 9 לא יכולים לספק את HAL 1.0 (כי HAL הזה נחשב ללא תמיכה).
• מאחר ש-HAL 1.0 נמצא ב-legacy/1/2.xml (גרסאות FCM ישנות יותר ש-Android 9 יכולה לפעול איתן) כ-HAL אופציונלי, המסגרת של Android 9 עדיין יכולה לפעול עם HAL 1.0 (שלא נחשב לגרסה של HAL שהוסרה).

גרסאות חדשות של FCM

תהליך השקת גרסה של FCM במחיצה של המערכת מתבצע על ידי Google בלבד כחלק מהשקה של AOSP, והוא כולל את השלבים הבאים:

1. חשוב לוודא שה-compatibility_matrix.F.xml כולל את המאפיין level="F".
2. מוודאים שכל המכשירים נוצרים ומתחילים לפעול.
3. מעדכנים את בדיקות VTS כדי לוודא שבמכשירים שהושקעו עם המסגרת העדכנית ביותר (על סמך רמת ה-API ששולחת את ההודעות) מותקנת גרסת FCM היעד V >= F.
4. מפרסמים את הקובץ ב-AOSP.

לדוגמה, בדיקות VTS מוודאות שגרסת היעד של FCM במכשירים עם Android 9 היא 3>.

בנוסף, ב-FCM של המוצר וב-FCM של system_ext עשויות להופיע גם דרישות לכל גרסאות ה-FCM של הפלטפורמה. הבעלים של התמונות האלה אחראים על פרסום הגרסאות של FCM במחיצות product ו-system_ext, בהתאמה. מספרי הגרסה של FCM במחיצות product ו-system_ext חייבים להיות זהים לאלה במחיצה system. בדומה לגרסאות FCM במחיצה של המערכת, מטריצת התאימות ב-FCM בגרסה F במחיצות product ו-system_ext משקפת את הדרישות במכשיר עם יעד FCM בגרסה F.

הוצאה משימוש של גרסת HAL

ההוצאה משימוש של גרסת HAL היא החלטה של המפתח (כלומר, במקרה של AOSP HALs, Google מקבלת את ההחלטה). זה יכול לקרות כשמשוחררת גרסת HAL גבוהה יותר (קטינה או גדולה).

הוצאה משימוש של HAL של מכשיר

כשמכשיר HAL foo@x.y הוצא משימוש בגרסה F של FCM, המשמעות היא בכל מכשיר שמופעל עם יעד FCM מגרסה V = F ואילך, אסור להטמיע את foo בגרסה x.y או בכל גרסה ישנה יותר מ-x.y. עדיין יש תמיכה בגרסת HAL שהוצאה משימוש במסגרת לשדרוג מכשירים.

כשגרסה F של FCM תפורסם, גרסה foo@x.y של HAL תוגדר כגרסה לא נתמכת אם גרסה ה-HAL הספציפית לא תצוין במפורש ב-FCM העדכני ביותר עבור גרסה V = F של FCM היעד. במכשירים שהושקעו עם V = F, אחד מהתנאים הבאים מתקיים:

• המסגרת דורשת גרסה גבוהה יותר (ראשית או משנית).
• ל-framework אין יותר צורך ב-HAL.

לדוגמה, ב-Android 9, health@2.0 נכלל כשדרוג בגרסה הראשית של 1.0 HAL. השדה health@1.0 הוסר מ-compatibility_matrix.3.xml אבל הוא מופיע ב-compatibility_matrix.legacy.xml, ב-compatibility_matrix.1.xml וב-compatibility_matrix.2.xml. לכן, health@1.0 נחשב לתכונה שהוצאה משימוש.

הוצאה משימוש של framework HAL

כשגרסת HAL foo@x.y של מסגרת מסוימת הוצאה משימוש בגרסה F של FCM, המשמעות היא שמכשיר שמופעל עם גרסת היעד V = F ואילך לא יכול לצפות שהמסגרת תספק את foo בגרסה x.y או בגרסה ישנה יותר מ-x.y. עדיין יש גרסה של HAL שיצאה משימוש, שסופקו על ידי המסגרת לצורך שדרוג המכשירים.

כשגרסת FCM F תושק, גרסה foo@x.y של HAL תוצא משימוש אם המניפסט של המסגרת מציין max-level="F - 1" עבור foo@x.y. במכשירים שפועלים עם V = F, המסגרת לא מספקת את ה-HAL foo@x.y. אסור שרשימת ה-HAL של המסגרת עם max-level < V תופיע במטריצה של תאימות המכשירים במכשירים שהושקעו עם V = F.

לדוגמה, ב-Android 12, הפונקציה schedulerservice@1.0 הוצאה משימוש. המאפיין max-level מוגדר כ-5, גרסת FCM שהוצגה ב-Android 11. למידע נוסף, ראו מניפסט מסגרת ל-Android 12.

הסרת התמיכה בגרסאות היעד של FCM

כשמספר המכשירים הפעילים של גרסה מסוימת של Target FCM ‏V יורד מתחת לסף מסוים, גרסה זו של Target FCM תוסר מהקבוצה S_F במהדורת המסגרת הבאה. כדי לעשות זאת, צריך לבצע את שני השלבים הבאים:

1. הסרת compatibility_matrix.V.xml מכללי ה-build (כדי שלא יותקן בתמונת המערכת) ומחיקת כל קוד שהטמיע או תלוי ביכולות שהוסרו.

2. הסרת HALs של מסגרת עם max-level שקטן מ-V או שווה לו מקובץ המניפסט של המסגרת, ומחיקה של כל קוד שמטמיע את ה-HALs של המסגרת שהוסרו.

מכשירים עם גרסת יעד של FCM מחוץ ל-S_F למהדורת framework מסוימת לא יכולים לשדרג לגרסה הזו.

סטטוס גרסת HAL

בקטעים הבאים מתוארים (בכרונולוגיה) המצבים האפשריים של גרסה של HAL.

לפני השקה

לגבי HAL של מכשירים, אם גרסה של HAL לא מופיעה באף אחת ממטריצות התאימות הציבוריות והקפואות, היא נחשבת כגרסה שלא פורסמה וייתכן שהיא נמצאת בפיתוח. הרשימה הזו כוללת גרסאות HAL שזמינות רק ב-compatibility_matrix.F.xml. לדוגמה:

• במהלך הפיתוח של Android 9, גרסת ה-HAL של health@2.0 נחשבה כ-HAL שלא הושקה והושגה רק ב-compatibility_matrix.3.xml.
• HAL של teleportation@1.0 לא נכלל במטריצות תאימות שפורסמו, והוא נחשב גם ל-HAL שלא פורסם.

ב-framework HALs, אם גרסת HAL נמצאת רק במניפסט ה-framework של הסתעפות פיתוח לא קשורה, היא נחשבת כגרסת HAL שלא פורסמה.

גרסאות שפורסמו ועדכניות

לגבי HAL של מכשירים, אם גרסת HAL נמצאת במטריצה ציבורית וקפואה של תאימות, היא תפורסם. לדוגמה, אחרי שגרסה 3 של FCM קופאת ומתפרסמת ב-AOSP, ה-HAL של health@2.0 נחשב לגרסה הנוכחית והפורסמת של HAL.

אם גרסת HAL נמצאת במטריצה ציבורית וקפואה של תאימות עם גרסת FCM הגבוהה ביותר, גרסת ה-HAL היא גרסה עדכנית (כלומר, היא לא הוצאה משימוש). לדוגמה, גרסאות HAL קיימות (כמו nfc@1.0 שהושקו ב-compatibility_matrix.legacy.xml) שממשיכות להתקיים ב-compatibility_matrix.3.xml נחשבות גם כגרסאות שפורסמו וכגרסאות HAL עדכניות.

לגבי HALs של מסגרות, אם גרסה של HAL נמצאת במניפסט של המסגרת של ההסתעפות האחרונה שפורסמה ללא המאפיין max-level, או (באופן חריג) אם max-level שווה לגרסה של FCM שפורסמה בהסתעפות הזו או גבוהה ממנה, היא נחשבת לגרסה של HAL שפורסמה ועדכנית. לדוגמה, HAL של displayservice זמין ב-Android 12, כפי שמפורט במניפסט של מסגרת Android 12.

פורסמו אבל הוצאו משימוש

לגבי HAL של מכשיר, גרסה של HAL תופסק אם יתקיימו כל התנאים הבאים:

• הוא משוחרר.
• היא לא מופיעה במטריצה הציבורית והקפואה של התאימות, שבה מופיעה גרסת FCM הגבוהה ביותר.
• הוא מופיע במטריצה ציבורית וקפואה של תאימות, שעדיין נתמכת במסגרת.

לדוגמה:

• מדד ה-HAL health@1.0 נמצא ב-compatibility_matrix.legacy.xml, ב-compatibility_matrix.1.xml וב-compatibility_matrix.2.xml, אבל לא ב-compatibility_matrix.3.xml. לכן, הוא נחשב ללא תמיכה ב-Android 9.
• ל-HAL של החשמל יש שדרוג גרסה קטן ב-Android 9, אבל power@1.0 עדיין נמצא ב-compatibility_matrix.3.xml.
• power@1.0 compatibility_matrix.legacy.xml,‏compatibility_matrix.1.xml ו-compatibility_matrix.2.xml.
• לcompatibility_matrix.3.xml יש את power@1.0-1.

לכן, power@1.0 הוא נכס תקף, אבל לא מבוטל ב-Android 9.

לגבי HAL של מסגרות, אם גרסה של HAL נמצאת במניפסט של המסגרת בהסתעפות האחרונה שפורסמה, עם מאפיין max-level נמוך יותר מהגרסה של FCM שפורסמה בהסתעפות הזו, היא נחשבת לגרסה של HAL שפורסמה אבל הוצאה משימוש. לדוגמה, HAL של schedulerservice פורסם אבל הוצא משימוש ב-Android 12, כפי שמפורט במניפסט של מסגרת Android 12.

הוסר

לגבי HAL של מכשיר, גרסה של HAL תוסר רק אם התנאים הבאים מתקיימים:

• הוא כבר שוחרר בעבר.
• הוא לא מופיע באף מטריצה ציבורית ומוקפאת של תאימות שתומכת במסגרת.

מטריצות תאימות שגלומות, קפואות ואינן נתמכות במסגרת נשמרות בקוד הבסיסי כדי להגדיר את קבוצת הגרסאות של HAL שהוסרו, וכך אפשר לכתוב בדיקות VTS כדי לוודא ש-HALs שהוסרו לא נמצאים במכשירים חדשים.

לגבי HAL של מסגרות, גרסה של HAL תוסר רק אם מתקיימים התנאים הבאים:

• היא הושקה בעבר.
• הוא לא נמצא במניפסט של אף מסגרת מהגרסה האחרונה שפורסמה.

מנהלי FCM מדור קודם

Target FCM Version legacy הוא ערך מיוחד לכל המכשירים שאינם Treble. ב-FCM הקודם, compatibility_matrix.legacy.xml, מפורטות הדרישות של המסגרת במכשירים מדור קודם (כלומר, מכשירים שהושקו לפני Android 8.0).

אם הקובץ הזה קיים ב-FCM בגרסה F, אפשר לשדרג כל מכשיר שאינו Treble לגרסה F, בתנאי שמניפסט המכשיר תואם לקובץ הזה. ההסרה שלו מתבצעת לפי אותו תהליך כמו של מודעות FCM לגרסאות אחרות של FCM לטירגוט (המודעות האלה יוסרו אחרי שמספר המכשירים הפעילים בגרסה 8.0 ומטה יירד מתחת לסף מסוים).

גרסאות FCM שפורסמו

רשימת הגרסאות של FCM שפורסמו מופיעה בכתובת hardware/interfaces/compatibility_matrices.

כדי למצוא את גרסת FCM ששוחררה עם גרסה ספציפית של Android, אפשר לעיין במאמר Level.h.