Matrices de compatibilidad

En esta sección se describen las matrices de compatibilidad de marcos y dispositivos y el esquema de matriz de compatibilidad . Para conocer las reglas de coincidencia, consulte Reglas de coincidencia .

Matriz de compatibilidad del marco (FCM)

La matriz de compatibilidad del marco (FCM) describe los requisitos del marco en el dispositivo en el que se ejecuta. La matriz de compatibilidad del marco consta de la matriz de compatibilidad del sistema, la matriz de compatibilidad del producto y la matriz de compatibilidad system_ext . El manifiesto del dispositivo debe cumplir los requisitos del FCM (requisitos aplicados en el momento de la compilación, el tiempo de ejecución y en VTS).

El FCM system_ext y el FCM del producto son complementos del FCM específico del dispositivo (instalado en la partición del sistema).

  • El dispositivo FCM debe reflejar los requisitos de los módulos en la partición del sistema .
  • El FCM system_ext debe reflejar los requisitos por módulos en la partición system_ext.
  • El FCM del producto debe reflejar los requisitos por módulos en la partición del producto .

Todos los FCM deben alinearse con las modificaciones de un OEM al marco en las particiones system, product y system_ext. Por ejemplo, si una aplicación instalada en la partición del producto utiliza una extensión de proveedor de una interfaz HAL, el requisito de la interfaz HAL debe declararse en el FCM del producto.

Ejemplo de archivo de matriz de compatibilidad del sistema:

<?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>

Para obtener más detalles, consulte Ciclo de vida de FCM .

Matriz de compatibilidad de productos

El producto FCM es un archivo de matriz de compatibilidad de marco en la partición del producto. El objeto VINTF une el FCM del producto con los FCM en las particiones system y system_ext en tiempo de ejecución.

Ejemplo de archivo FCM de producto:

<?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>

Matriz de compatibilidad system_ext

El FCM system_ext es un archivo de matriz de compatibilidad de marco en la partición system_ext. El objeto VINTF une el FCM system_ext con los FCM en las particiones del sistema y del producto en tiempo de ejecución. Consulte la matriz de compatibilidad de productos para ver un archivo system_ext FCM de ejemplo.

Matriz de compatibilidad de dispositivos (DCM)

La matriz de compatibilidad de dispositivos describe un conjunto de requisitos que el dispositivo espera del marco (requisitos aplicados en el momento del lanzamiento y OTA).

Ejemplo de archivo 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>

esquema de matriz de compatibilidad

Esta sección describe el significado de estas etiquetas XML. Algunas etiquetas "obligatorias" pueden faltar en el archivo de origen en el árbol de fuentes de Android y pueden estar escritas por assemble_vintf en el momento de la compilación. Las etiquetas "Obligatorias" deben estar presentes en los archivos correspondientes del dispositivo.

?xml
Opcional. Solo proporciona información al analizador XML.
compatibility-matrix.version
Requerido. Meta-versión de esta matriz de compatibilidad. Describe los elementos esperados en la matriz de compatibilidad. No relacionado con la versión XML.
compatibility-matrix.type
Requerido. Tipo de esta matriz de compatibilidad:
  • "device" : Matriz de compatibilidad de dispositivos.
  • "framework" : Matriz de compatibilidad del marco.
manifest.level
Requerido para la matriz de compatibilidad del marco. En Android 12 y versiones posteriores, se permiten archivos de matriz de compatibilidad de framework en las particiones product y system_ext. Especifica la versión de la matriz de compatibilidad del marco (versión FCM) de este archivo. No declare esto en la matriz de compatibilidad del marco específico del dispositivo (es decir DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE ).
compatibility-matrix.hal
Opcional y se puede repetir. Muestra una sola HAL (HIDL o nativa) que el propietario de la matriz de compatibilidad (marco o dispositivo) requiere que esté presente. Las entradas HAL se distinguen por un elemento <name> ; puede haber varias entradas HAL con el mismo nombre (implica la condición "y").
compatibility-matrix.hal.format
Opcional. El valor puede ser uno de:
  • "hidl" : HAL HIDL. Este es el valor predeterminado.
  • "aidl" : AIDL HAL . Solo válido en la meta-versión 2.0 de la matriz de compatibilidad.
  • "native" : HAL nativos.
compatibility-matrix.hal.optional
El atributo es opcional y su valor predeterminado es falso. Indica si esta HAL es opcional para el propietario de la matriz de compatibilidad (marco o dispositivo). Si una entrada <hal> está marcada como opcional, significa que el propietario puede trabajar con esta HAL, si está presente, pero no requiere que esté presente.
compatibility-matrix.hal.name
Requerido. Nombre completo del paquete de esta HAL. Ejemplos:
  • android.hardware.camera (HIDL o AIDL HAL)
  • GLES (HAL nativo, solo requiere nombre)
compatibility-matrix.hal.version
Una lista de rangos de versiones (ver coincidencias HAL ) que define qué versiones espera el propietario de la matriz de compatibilidad (marco o dispositivo).

Para HIDL y HAL nativos, requerido, puede repetirse sin duplicados. El formato es uno de los siguientes:
  • MAJOR . MINOR_MIN - MINOR_MAX
  • MAJOR . MINOR (equivale a MAJOR . MINOR - MINOR )

Para AIDL HAL, no debe estar presente en dispositivos que ejecutan Android 11 y versiones anteriores. Opcional en dispositivos que ejecutan versiones posteriores. Si se especifica, el formato es uno de los siguientes:
  • VERSION_MIN - VERSION_MAX
  • VERSION (equivalente a VERSION - VERSION )
Si no se especifica, el valor predeterminado es 1 .
compatibility-matrix.hal.interface
Opcional, se puede repetir. Una lista de las interfaces necesarias de esta HAL.
compatibility-matrix.hal.interface.name
Requerido. Nombre de la interfaz.
compatibility-matrix.hal.interface.instance
Opcional, se puede repetir. Una lista de las instancias requeridas de esta interfaz.
compatibility-matrix.hal.interface.regex-instance
Opcional, se puede repetir. Una lista de patrones de nombre de instancia requeridos en esta interfaz. Utilice el formato de expresión regular extendida .
compatibility-matrix.kernel
Opcional, se puede repetir. Especifique una lista de configuraciones del kernel que requiere el marco en cada versión del kernel.
Pueden existir múltiples <kernel> con la misma <version> para implicar una relación "y". Cada <kernel> es un "fragmento" de los requisitos que se habilitan solo cuando se cumplen las <conditions> .
compatibility-matrix.kernel.version
Requerido. Versión del núcleo. El formato es VERSION . MAJOR_REVISION . MINOR_REVISION . La versión y la revisión principal deben coincidir exactamente. La revisión menor define la versión LTS mínima del kernel que espera el marco.
compatibility-matrix.kernel.condition
Opcional. No debe existir para el primer <kernel> de cada versión. Especifica una lista de condiciones. Solo cuando se cumplen las condiciones, se habilitan los requisitos establecidos en este fragmento <kernel> .
compatibility-matrix.kernel.config
Opcional, se puede repetir. Enumera los elementos de CONFIG que deben coincidir para esta versión del kernel. Cada elemento CONFIG es un par clave-valor; Los elementos de configuración se distinguen por clave.
compatibility-matrix.kernel.config.key
Requerido. Nombre de clave del elemento CONFIG . Comienza con CONFIG_ .
compatibility-matrix.kernel.config.value
Requerido. Valor del elemento CONFIG . El formato depende del tipo:
  • string Se omiten las comillas.
  • int . Se aceptan valores decimales y hexadecimales (deben comenzar con 0x o 0X) . Interpretado como un entero de 64 bits; los desbordamientos dan como resultado el truncamiento. (El analizador acepta valores de -2 64 + 1 a 2 64 - 1, el bit 65 se trunca; para obtener más información, consulte la página man de strtoull ).
  • range El formato es [int]-[int] , por ejemplo, 10-20 . Se aceptan valores hexadecimales y deben comenzar con 0x o 0X . Dos límites deben ser un entero de 64 bits sin signo.
  • tristate Los valores válidos son y , m y n .
compatibility-matrix.kernel.config.value.type
Requerido. Tipo del valor del elemento CONFIG , uno de:
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
Requerido. Contiene todas las entradas relacionadas con sepolicy. Usado solo por la matriz de compatibilidad del marco.
compatibility-matrix.sepolicy.sepolicy-version
Se requiere, se puede repetir. Describe el requisito de la versión de la política. Corresponde a manifest.sepolicy.version . Cada instancia de un elemento define un rango de versiones de sepolicy.
compatibility-matrix.sepolicy.kernel-sepolicy-version
Requerido. Declara la versión de policydb con la que trabaja el marco.
compatibility-matrix.avb.vbmeta-version
Opcional; utilizado solo por la matriz de compatibilidad del marco. Declara la versión de AVB utilizada para firmar system.img . Obsoleto en Android 10.
compatibility-matrix.vendor-ndk
Opcional; utilizado solo por la matriz de compatibilidad de dispositivos. Declara el requisito de la instantánea del proveedor de VNDK. Si falta, no se realiza ningún requisito de VNDK en la imagen del sistema.
compatibility-matrix.vendor-ndk.version
Requerido. Un entero positivo que declara una versión de VNDK requerida por la imagen del proveedor.
compatibility-matrix.vendor-ndk.library
Opcional, se puede repetir. Declara un conjunto de bibliotecas VNDK requeridas por la imagen del proveedor. Misma semántica que manifest.vendor-ndk.library .
compatibility-matrix.system-sdk.version
Opcional, se puede repetir; utilizado solo por la matriz de compatibilidad de dispositivos. Declara el requisito de las aplicaciones del proveedor en las versiones del SDK del sistema. Si falta, no se hace ningún requisito del SDK del sistema en la imagen del sistema.