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

בקטע הזה מתוארות מטריצות התאימות של framework ומכשירים הסכימה של מטריצת התאימות. עבור כללי התאמה, ראו התאמות כללים.

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

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

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

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

כל רכיבי ה-FCM צריכים להתאים לשינויים שה-OEM (יצרן הציוד המקורי) ב-framework במערכת, במוצר, ומחיצות 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 של המוצר הוא קובץ מטריצת תאימות של framework במוצר מחיצה. אובייקט ה-VINTF מצרף את FCM של המוצר ל-FCM במערכת ו-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

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

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

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

קובץ 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": מטריצת תאימות ל-framework.

manifest.level

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

compatibility-matrix.hal

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

compatibility-matrix.hal.format

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

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

compatibility-matrix.hal.optional

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

compatibility-matrix.hal.name

חובה. שם החבילה המלא של HAL הזה. למשל:

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

compatibility-matrix.hal.version

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

ל-HIDL ו-HALs מקוריים, ניתן לבצע חזרה ללא כפילויות. הפורמט הוא אחד מהבאים:

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

ל-AIDL HAL, אסור להשתמש במכשירים עם 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

אופציונלי, אפשר לחזור על הפעולה. לספק רשימה של הגדרות הליבה שה-framework שנדרשת בכל גרסת ליבה (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 פריטים שחייבים להיות תואמת לגרסת הליבה (kernel) הזו. כל פריט 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 חתוכים; אפשר לקרוא פרטים נוספים שטרול דף אדם.)
• 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

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

compatibility-matrix.sepolicy.sepolicy-version

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

compatibility-matrix.sepolicy.kernel-sepolicy-version

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

compatibility-matrix.avb.vbmeta-version

אופציונלי; רק במטריצת התאימות של framework. מצהירה על 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

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