ماتریس‌های سازگاری

این بخش چارچوب و ماتریس‌های سازگاری دستگاه و طرحواره ماتریس سازگاری را شرح می‌دهد. برای قوانین مطابقت، به قوانین مطابقت مراجعه کنید.

ماتریس سازگاری چارچوب (FCM)

ماتریس سازگاری چارچوب (FCM) الزامات چارچوب را در دستگاهی که در آن اجرا می‌شود شرح می‌دهد. ماتریس سازگاری چارچوب شامل ماتریس سازگاری سیستم، ماتریس سازگاری محصول، و ماتریس سازگاری system_ext است. دستگاه باید الزامات FCM را در مانیفست دستگاه برآورده کند (الزامات در زمان ساخت، زمان اجرا، و در VTS اعمال می‌شود).

‫FCM سیستم_ext و FCM محصول مکمل FCM مختص دستگاه (نصب‌شده در پارتیشن سیستم) هستند.

• «اف‌سی‌ام» دستگاه باید الزامات واحدها در پارتیشن سیستم را منعکس کند.
• ‫FCM مربوط به system_ext باید الزامات را براساس واحدها در پارتیشن system_ext منعکس کند.
• «فایل مقایسه محصول» (FCM) باید الزامات را براساس واحدها در بخش محصول منعکس کند.

همه FCMها باید با اصلاحات OEM در چارچوب سیستم، محصول، و پارتیشن‌های 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 Lifecycle را ببینید.

ماتریس سازگاری محصول

‫FCM محصول فایل ماتریس سازگاری چارچوب در بخش محصول است. شیء VINTF در زمان اجرا FCM محصول را با FCMهای موجود در پارتیشن‌های 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

‫system_ext FCM فایل ماتریس سازگاری چارچوب در پارتیشن system_ext است. شیء VINTF در زمان اجرا، FCM‏ system_ext را با FCMها در پارتیشن‌های سیستم و محصول ادغام می‌کند. برای نمونه فایل FCM سیستم_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 نوشته شوند. برچسب‌های «الزامی» باید در فایل‌های مربوطه در دستگاه وجود داشته باشند.

?xml

اختیاری. این ویژگی فقط اطلاعات را به تجزیه‌کننده XML ارائه می‌دهد.

compatibility-matrix.version

‫

الزامی. نسخه فراداده این ماتریس سازگاری. عناصر موردانتظار در ماتریس سازگاری را شرح می‌دهد. غیرمرتبط با نسخه XML.

compatibility-matrix.type

‫

الزامی. نوع این ماتریس سازگاری:

• "device": ماتریس سازگاری دستگاه.
• "framework": ماتریس سازگاری چارچوب.

manifest.level

برای ماتریس سازگاری چارچوب الزامی است. در Android 12 و بالاتر، در فایل‌های ماتریس سازگاری چارچوب در پارتیشن‌های محصول و system_ext مجاز است. «نسخه ماتریس سازگاری چارچوب» (نسخه FCM) این فایل را مشخص می‌کند. Don't declare this in device-specific framework compatibility matrix (i.e. DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE).

compatibility-matrix.hal

اختیاری است و می‌تواند تکرار شود. فهرست یک HAL (HIDL یا بومی) که مالک ماتریس سازگاری (چارچوب یا دستگاه) برای حضور آن نیاز دارد. ورودی‌های HAL با عنصر <name> متمایز می‌شوند؛ چندین ورودی HAL با نام یکسان می‌تواند وجود داشته باشد (شرط «و» را دربرمی‌گیرد).

compatibility-matrix.hal.format

‫

اختیاری. مقدار می‌تواند یکی از این موارد باشد:

• "hidl": HIDL HALs. این گزینه پیش‌فرض است.
• ‫"aidl": AIDL HALs. فقط در فرا-نسخه ۲.۰ ماتریس سازگاری معتبر است.
• ‫"native": HAL بومی.

compatibility-matrix.hal.optional (Android 15 یا پایین‌تر)

‫

مشخصه اختیاری است و به‌طور پیش‌فرض روی نادرست تنظیم می‌شود. بیان می‌کند که آیا این 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)

برای 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

اختیاری، می‌تواند تکرار شود. فهرستی از پیکربندی‌های هسته را که چارچوب در هر نسخه هسته به آن‌ها نیاز دارد مشخص کنید.
چندین <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) شروع شود) پذیرفته می‌شود. به‌صورت عدد صحیح ۶۴ بیتی تفسیر می‌شود؛ سرریزها منجر به کوتاه شدن نتیجه می‌شوند. (تجزیه‌گر مقادیر را از ‎-2⁶⁴ + 1 تا ‎2⁶⁴ - 1 می‌پذیرد، بیت ۶۵ بریده می‌شود؛ برای جزئیات به صفحه راهنمای strtoull مراجعه کنید.)
• range. قالب [int]-[int] است، برای مثال 10-20. مقادیر مبنای شانزده پذیرفته می‌شود و باید با 0x یا 0X شروع شود. دو مرز باید عدد صحیح ۶۴ بیتی بدون علامت باشد.
• ‫tristate. مقادیر معتبر عبارت‌اند از y، m، و n.

compatibility-matrix.kernel.config.value.type

‫

الزامی. نوع مقدار عنصر CONFIG، یکی از این موارد:

• string
• int
• range
• tristate

compatibility-matrix.sepolicy

‫

الزامی. شامل همه ورودی‌های مربوط به sepolicy است. فقط توسط ماتریس سازگاری چارچوب استفاده می‌شود.

compatibility-matrix.sepolicy.sepolicy-version

‫

الزامی، می‌تواند تکرار شود. الزام مربوط به نسخه sepolicy را توصیف می‌کند. معادل manifest.sepolicy.version است. هر نمونه از یک عنصر محدوده نسخه‌های sepolicy را تعریف می‌کند.

compatibility-matrix.sepolicy.kernel-sepolicy-version

الزامی. اعلام می‌کند چارچوب با نسخه policydb کار می‌کند.

compatibility-matrix.avb.vbmeta-version

اختیاری؛ فقط توسط ماتریس سازگاری چارچوب استفاده می‌شود. نسخه AVB استفاده‌شده برای امضای system.img را اعلام می‌کند. در Android 10 منسوخ شده است.

compatibility-matrix.vendor-ndk

اختیاری؛ فقط توسط ماتریس سازگاری دستگاه استفاده می‌شود. الزام VNDK vendor snapshot را اعلام می‌کند. اگر وجود نداشته باشد، هیچ الزامی برای VNDK در تصویر سیستم وجود ندارد.

compatibility-matrix.vendor-ndk.version

‫

الزامی. عدد صحیح مثبتی که نسخه VNDK موردنیاز تصویر فروشنده را اعلام می‌کند.

compatibility-matrix.vendor-ndk.library

اختیاری، می‌تواند تکرار شود. مجموعه‌ای از کتابخانه‌های VNDK موردنیاز تصویر فروشنده را اعلام می‌کند. معناشناسی مشابه با manifest.vendor-ndk.library.

compatibility-matrix.system-sdk.version

اختیاری، می‌تواند تکرار شود؛ فقط توسط ماتریس سازگاری دستگاه استفاده می‌شود. الزامات برنامه‌های فروشنده را در نسخه‌های کیت توسعه نرم‌افزار سیستم اعلام می‌کند. اگر وجود نداشته باشد، هیچ الزام «کیت توسعه نرم‌افزار سیستم»<0x0A>در تصویر سیستم وجود ندارد.