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

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

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

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

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

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

ماتریس سازگاری دستگاه (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 را شرح می دهد. برخی از تگ‌های "الزامی" ممکن است در فایل منبع در درخت منبع اندروید وجود نداشته باشند و در زمان ساخت توسط assemble_vintf نوشته شده باشند. برچسب های "لازم" باید در فایل های مربوطه در دستگاه وجود داشته باشد.

?xml
اختیاری. فقط اطلاعات را در اختیار تجزیه کننده XML قرار می دهد.
compatibility-matrix.version
مورد نیاز. نسخه متا این ماتریس سازگاری. عناصر مورد انتظار در ماتریس سازگاری را توصیف می کند. غیر مرتبط با نسخه XML.
compatibility-matrix.type
مورد نیاز. نوع این ماتریس سازگاری:
  • "device" : ماتریس سازگاری دستگاه.
  • "framework" : ماتریس سازگاری چارچوب.
manifest.level
برای ماتریس سازگاری چارچوب مورد نیاز است. در Android 12 و بالاتر، در فایل‌های ماتریس سازگاری فریمورک در پارتیشن‌های product و system_ext مجاز است. نسخه ماتریس سازگاری چارچوب (نسخه FCM) این فایل را مشخص می کند. این را در ماتریس سازگاری چارچوب خاص دستگاه (یعنی DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE ) اعلام نکنید.
compatibility-matrix.hal
اختیاری است و می تواند تکرار شود. یک HAL منفرد (HIDL یا بومی) را فهرست می کند که توسط مالک ماتریس سازگاری (فریم ورک یا دستگاه) لازم است وجود داشته باشد. ورودی های HAL با عنصر <name> متمایز می شوند. ممکن است چندین ورودی HAL با یک نام وجود داشته باشد (به معنای شرط "و" است).
compatibility-matrix.hal.format
اختیاری. ارزش می تواند یکی از موارد زیر باشد:
  • "hidl" : HIDL HAL. این پیش فرض است.
  • "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 مراجعه کنید) که مشخص می‌کند صاحب ماتریس سازگاری (فریم‌ورک یا دستگاه) چه نسخه‌هایی را انتظار دارد.

برای 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
اختیاری، می تواند تکرار شود. فهرستی از الگوهای نام نمونه مورد نیاز در این رابط. از فرمت Extended Regular Expression استفاده کنید.
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 64 + 1 تا 2 64 - 1 را می پذیرد، بیت 65 کوتاه شده است؛ برای جزئیات به صفحه strtoull man مراجعه کنید.)
  • 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 است. هر نمونه از یک عنصر، طیفی از نسخه های sepolicy را تعریف می کند.
compatibility-matrix.sepolicy.kernel-sepolicy-version
مورد نیاز. نسخه policydb را که چارچوب با آن کار می کند، اعلام می کند.
compatibility-matrix.avb.vbmeta-version
اختیاری؛ فقط توسط ماتریس سازگاری چارچوب استفاده می شود. نسخه AVB مورد استفاده برای امضای system.img را اعلام می کند. در اندروید 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 را اعلام می کند. در صورت عدم وجود، هیچ نیازی به سیستم SDK در تصویر سیستم وجود ندارد.