Матрицы совместимости

В этом разделе описываются матрицы совместимости платформы и устройств, а также схема матрицы совместимости . Правила соответствия см. в разделе Правила сопоставления .

Матрица совместимости фреймворков (FCM)

Матрица совместимости фреймворка (FCM) описывает требования фреймворка к устройству, на котором он работает. Матрица совместимости фреймворка состоит из матрицы совместимости системы, матрицы совместимости продукта и матрицы совместимости system_ext . Требования FCM должны удовлетворяться манифестом устройства (требования применяются во время сборки, во время выполнения и в 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 продукта с 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 в разделах системы и продукта во время выполнения. См. матрицу совместимости продуктов для примера файла 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. Некоторые «обязательные» теги могут отсутствовать в исходном файле в дереве исходного кода Android и быть записаны 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 )

Для 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) значения. Интерпретируется как 64-битное целое число; переполнения приводят к усечению. (Синтаксический анализатор принимает значения от -2 64 + 1 до 2 64 - 1, 65-й бит усекается; подробности см. на справочной странице 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
Необходимый. Содержит все записи, связанные с 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. Если он отсутствует, то к образу системы не предъявляются требования 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.