מטריצות תאימות

בקטע הזה מוסבר על המטריצות של המסגרת ותאימות המכשיר ועל הסכימה של מטריצת התאימות. מידע נוסף על כללי התאמה זמין במאמר כללי התאמה.

מטריצה של תאימות למסגרות (FCM)

במטריצה של תאימות המסגרת (FCM) מתוארות הדרישות של המסגרת במכשיר שבו היא פועלת. מטריצת התאימות של המסגרת מורכבת ממטריצת התאימות למערכת, ממטריצת התאימות למוצר וממטריצת התאימות של system_ext. המניפסט של המכשיר חייב לעמוד בדרישות של FCM (הדרישות נאכפות בזמן ה-build, בסביבת זמן הריצה וב-VTS).

ה-FCM של system_ext וה-FCM של המוצר הם משלימים של FCM ספציפי למכשיר (שמותקן במחיצה של המערכת).

• ה-FCM של המכשיר צריך לשקף את הדרישות של המודולים במחיצה המערכת.
• ה-FCM של system_ext צריך לשקף את הדרישות לפי מודולים במחיצה system_ext.
• ה-FCM של המוצר צריך לשקף את הדרישות לפי מודולים במחיצה של המוצר.

כל קובצי ה-FCM צריכים להיות תואמים לשינויים של יצרן הציוד המקורי (OEM) במסגרת במחיצות system,‏ product ו-system_ext. לדוגמה, אם אפליקציה שמותקנת במחיצה של המוצר משתמשת בהרחבה של ספק לממשק HAL, צריך להצהיר על הדרישה לממשק HAL ב-FCM של המוצר.

קובץ לדוגמה של מטריצה של תאימות למערכות:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework" level="3">
    <hal>
        <name>android.hardware.camera</name>
        <version>1.0</version>
        <version>3.1-4</version>
        <interface>
            <name>ICameraProvider</name>
            <instance>default</instance>
            <regex-instance>[a-z_]+/[0-9]+</regex-instance>
        </interface>
    </hal>
    <hal>
        <name>android.hardware.nfc</name>
        <version>1.0</version>
        <interface>
            <name>INfc</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal optional="true">
        <name>android.hardware.graphics.composer</name>
        <version>2.1</version>
        <interface>
            <name>IComposer</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="aidl" optional="true">
        <name>android.hardware.light</name>
        <version>1-2</version>
        <interface>
            <name>ILights</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="native">
        <name>GL</name>
        <version>1.1</version>
        <version>3.0</version>
    </hal>
    <hal format="native">
        <name>EGL</name>
        <version>1.1</version>
    </hal>
    <kernel version="3.18.51">
        <!-- common configs -->
    </kernel>
    <kernel version="3.18.51">
        <!-- arm specific configs -->
        <condition>
            <config>
                <key>CONFIG_ARM</key>
                <value type="tristate">y</value>
            </config>
        <condition>
        <config>
            <key>CONFIG_A</key>
            <value type="string"></value>
        </config>
        <config>
            <key>CONFIG_B</key>
            <value type="tristate">y</value>
        </config>
    </kernel>
    <kernel version="4.1.22">
        <!-- common configs -->
        <config>
            <key>CONFIG_A</key>
            <value type="string">foo</value>
        </config>
        <config>
            <key>CONFIG_B2</key>
            <value type="int">1024</value>
        </config>
    </kernel>
    <sepolicy>
        <kernel-sepolicy-version>30</kernel-sepolicy-version>
        <sepolicy-version>25.0</sepolicy-version>
        <sepolicy-version>26.0-3</sepolicy-version>
    </sepolicy>
    <avb>
        <vbmeta-version>2.1</vbmeta-version>
    </avb>
    <xmlfile format="dtd">
        <name>media_profile</name>
        <version>1.0</version>
        <path>/system/etc/media_profile_V1_0.dtd</path>
    </xmlfile>
</compatibility-matrix>

פרטים נוספים זמינים במאמר מחזור החיים של FCM.

מטריצת התאימות של מוצרים

קובץ ה-FCM של המוצר הוא קובץ של מטריצה של תאימות למסגרת במחיצה של המוצר. אובייקט ה-VINTF מחבר את ה-FCM של המוצר ל-FCMs במחיצות system ו-system_ext במהלך זמן הריצה.

קובץ FCM לדוגמה של מוצר:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework">
    <hal>
        <name>vendor.foo.camera</name>
        <version>1.0</version>
        <interface>
            <name>IBetterCamera</name>
            <instance>default</instance>
        </interface>
    </hal>
</compatibility-matrix>

מטריצה של תאימות System_ext

ה-FCM של system_ext הוא קובץ של מטריצה של תאימות למסגרת במחיצה system_ext. אובייקט ה-VINTF מחבר את ה-FCM של system_ext ל-FCMs במחיצות המערכת והמוצר בזמן הריצה. במטריצה של תאימות המוצרים תוכלו למצוא דוגמה לקובץ FCM מסוג system_ext.

מטריצת תאימות מכשירים (DCM)

במטריצה של תאימות המכשיר מתוארת קבוצת הדרישות שהמכשיר מצפה מהמסגרת (דרישות שאוכפות בזמן ההשקה ובזמן העדכון האווירי).

קובץ DCM לדוגמה:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="device">
    <hal>
        <name>android.hidl.manager</name>
        <version>1.0</version>
        <interface>
            <name>IServiceManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.memory</name>
        <version>1.0</version>
        <interface>
            <name>IMemory</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.allocator</name>
        <version>1.0</version>
        <interface>
            <name>IAllocator</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.framework.sensor</name>
        <version>1.0</version>
        <interface>
            <name>ISensorManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <vendor-ndk>
        <version>27</version>
    </vendor-ndk>
    <system-sdk>
        <version>27</version>
    </system-sdk>
</compatibility-matrix>

הסכימה של מטריצת התאימות

בקטע הזה מתוארים המשמעות של תגי ה-XML האלה. יכול להיות שחלק מהתגים 'הנדרשים' ייעדרו מקובץ המקור בעץ המקור של Android, ו-assemble_vintf יכתוב אותם בזמן ה-build. תגי החובה חייבים להופיע בקבצים המתאימים במכשיר.

?xml

אופציונלי. היא מספקת מידע רק למנתח ה-XML.

compatibility-matrix.version

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

compatibility-matrix.type

חובה. הסוג של מטריצת התאימות הזו:

• "device": מטריצת תאימות המכשירים.
• "framework": מטריצת תאימות של מסגרות.

manifest.level

נדרש למטריצה של תאימות המסגרת. ב-Android 12 ואילך, מותר להשתמש בקבצים של מטריצות תאימות של מסגרות במחיצות product ו-system_ext. הגרסה של Framework Compatibility Matrix (FCM) של הקובץ הזה. אין להצהיר על כך במטריצת התאימות של המסגרת הספציפית למכשיר (כלומר DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE).

compatibility-matrix.hal

אופציונלי וניתן לחזור עליו. רשימה של HAL יחיד (HIDL או מקומי) שנדרש על ידי הבעלים של מטריצת התאימות (מסגרת או מכשיר) כדי שיהיה נוכח. רשומות HAL נבדלות על ידי רכיב <name>. יכולות להיות כמה רשומות HAL עם אותו שם (המשמעות היא תנאי 'וגם').

compatibility-matrix.hal.format

אופציונלי. הערך יכול להיות אחד מהערכים הבאים:

• "hidl": ממשקי HAL של HIDL. זוהי ברירת המחדל.
• "aidl": HAL של AIDL. תקף רק למטא-גרסה 2.0 של מטריצת התאימות.
• "native": ממשקי HAL מקומיים.

compatibility-matrix.hal.optional (Android מגרסה 15 ומטה)

המאפיין

הוא אופציונלי וערך ברירת המחדל שלו הוא false. מציין אם ה-HAL הזה הוא אופציונלי לבעלים של מטריצת התאימות (מסגרת או מכשיר). אם הרשומה <hal> מסומנת כאופציונלית, המשמעות היא שהבעלים יכולים לעבוד עם ה-HAL הזה, אם הוא קיים, אבל הוא לא חייב להיות קיים.

אזהרה: המאפיין הזה הוצא משימוש אחרי Android מגרסה 15, ולא תהיה לו יותר השפעה. אם יש צורך להתקין ממשקי HAL, צריך לאכוף את הדרישה הזו בבדיקות.

compatibility-matrix.hal.name

חובה. שם החבילה המלא של ה-HAL הזה. דוגמאות:

• android.hardware.camera (HIDL או AIDL HAL)
• GLES (HAL מקורי, נדרש שם בלבד)

compatibility-matrix.hal.version

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

ב-HIDL וב-HAL מקומיים, חובה, אפשר לחזור עליו בלי כפילויות. הפורמט יכול להיות אחד מהפורמטים הבאים:

• MAJOR.MINOR_MIN-MINOR_MAX
• MAJOR.MINOR (שווה ערך ל-MAJOR.MINOR-MINOR)

ב-HAL של AIDL, לא יכול להיות נוכח במכשירים עם Android מגרסה 11 ומטה. אופציונלי במכשירים עם גרסאות מתקדמות יותר. אם מצוין, הפורמט הוא אחד מהפורמטים הבאים:

• VERSION_MIN-VERSION_MAX
• VERSION (שווה ערך ל-VERSION-VERSION)

אם לא מציינים ערך, ערך ברירת המחדל הוא 1.

compatibility-matrix.hal.interface

אופציונלי, אפשר לחזור עליו. רשימה של הממשקים הנדרשים של ה-HAL הזה.

compatibility-matrix.hal.interface.name

חובה. שם הממשק.

compatibility-matrix.hal.interface.instance

אופציונלי, אפשר לחזור עליו. רשימה של המופעים הנדרשים של הממשק הזה.

compatibility-matrix.hal.interface.regex-instance

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

compatibility-matrix.kernel

אופציונלי, אפשר לחזור עליו. מציינים רשימה של הגדרות הליבה שנדרשות למסגרת בכל גרסה של הליבה.
יכולים להתקיים כמה <kernel> עם אותו <version> כדי להצביע על קשר מסוג 'וגם'. כל <kernel> הוא 'קטע' של הדרישות שמופעל רק כשהדרישות של <conditions> מתקיימות.

compatibility-matrix.kernel.version

חובה. גרסת הליבה. הפורמט הוא VERSION.MAJOR_REVISION.MINOR_REVISION. הגרסה והגרסה הראשית חייבות להיות זהות. הגרסה המשנית מגדירה את גרסת ה-LTS המינימלית של הליבה שמערכת המסגרת מצפה לה.

compatibility-matrix.kernel.condition

אופציונלי. לא יכול להיות קיים ב-<kernel> הראשונים של כל גרסה. מציין רשימה של תנאים. כשהתנאים מתקיימים, מתבצעת הפעלה של הדרישות שמפורטות בקטע <kernel>.

compatibility-matrix.kernel.config

אופציונלי, אפשר לחזור עליו. רשימה של הפריטים מסוג CONFIG שצריך להתאים לגרסה הזו של הליבה. כל פריט CONFIG הוא צמד מפתח/ערך. פריטי ההגדרה נבדלים לפי מפתח.

compatibility-matrix.kernel.config.key

חובה. שם המפתח של הפריט CONFIG. מתחיל ב-CONFIG_.

compatibility-matrix.kernel.config.value

חובה. הערך של הפריט CONFIG. הפורמט תלוי בסוג:

• string. קווים נטויים לא מופיעים.
• int. ערכים עשרוניים והקסדצימליים (חייבים להתחיל ב-0x או ב-0X)). מתפרש כמספר שלם של 64 ביט. במקרה של זליגה, מתבצע חיתוך. (המנתח מקבל ערכים מ--2⁶⁴ + 1 עד 2⁶⁴ - 1, הביט ה-65 נקטע. לפרטים נוספים, אפשר לעיין במדריך man של strtoull).
• range. הפורמט הוא [int]-[int], למשל 10-20. אפשר להשתמש בערכים הקסדצימליים, והם חייבים להתחיל ב-0x או ב-0X. שני הגבולות חייבים להיות מספרים שלמים של 64 ביט ללא סימן.
• tristate. הערכים החוקיים הם y, ‏ m ו-n.

compatibility-matrix.kernel.config.value.type

חובה. סוג הערך של הפריט CONFIG, אחד מהערכים הבאים:

• string
• int
• range
• tristate

compatibility-matrix.sepolicy

חובה. מכיל את כל הרשומות שקשורות למדיניות האבטחה. משמש רק את מטריצת התאימות של המסגרת.

compatibility-matrix.sepolicy.sepolicy-version

חובה, אפשר לחזור עליו. תיאור הדרישות לגרסה של sepolicy. תואם ל-manifest.sepolicy.version. כל מופע של רכיב מגדיר טווח של גרסאות של מדיניות האבטחה.

compatibility-matrix.sepolicy.kernel-sepolicy-version

חובה. הצהרה על גרסת policydb שבה ה-framework פועל.

compatibility-matrix.avb.vbmeta-version

אופציונלי. משמש רק למטרות של מטריצת התאימות של המסגרת. הצהרה על גרסת ה-AVB ששימשה לחתימה על system.img. הוצא משימוש ב-Android 10.

compatibility-matrix.vendor-ndk

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

compatibility-matrix.vendor-ndk.version

חובה. מספר שלם חיובי שמצהיר על גרסת VNDK שנדרשת לתמונת הספק.

compatibility-matrix.vendor-ndk.library

אופציונלי, אפשר לחזור עליו. הצהרה על קבוצה של ספריות VNDK שנדרשות לתמונת הספק. סמנטיקה זהה לזו של manifest.vendor-ndk.library.

compatibility-matrix.system-sdk.version

אופציונלי, אפשר לחזור עליו. משמש רק למטרות של מטריצת התאימות למכשירים. הצהרה על הדרישה של אפליקציות של ספקים לגרסאות System SDK. אם הוא חסר, לא תהיה דרישה ל-System SDK בתמונת המערכת.