Matrices de compatibilidad

En esta sección, se describen las matrices de compatibilidad del framework y del dispositivo, y el esquema de la matriz de compatibilidad. Para ver las reglas de coincidencia, consulta Reglas de coincidencia.

Matriz de compatibilidad del framework (FCM)

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

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

  • El FCM del dispositivo debe reflejar los requisitos de los módulos en la partición del sistema.
  • El FCM de 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 que realiza un OEM en el framework en las particiones del sistema, del producto y de system_ext. Por ejemplo, si una app instalada en la partición del producto usa una extensión del proveedor de una interfaz HAL, el requisito de la interfaz HAL se debe declarar 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, consulta el ciclo de vida de FCM.

Matriz de compatibilidad de productos

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

Ejemplo de archivo FCM de productos:

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

El FCM de system_ext es un archivo de matriz de compatibilidad del framework 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 durante el tiempo de ejecución. Consulta la matriz de compatibilidad de productos para ver un ejemplo de archivo FCM de system_ext.

Matriz de compatibilidad de dispositivos (DCM)

La matriz de compatibilidad del dispositivo describe un conjunto de requisitos que el dispositivo espera del framework (requisitos que se aplican en el lanzamiento y en el tiempo de actualización 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 la matriz de compatibilidad

En esta sección, se describe el significado de estas etiquetas XML. Es posible que falten algunas etiquetas "obligatorias" en el archivo fuente del árbol de fuentes de Android y que assemble_vintf las escriba 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 de XML.
compatibility-matrix.version
Obligatorio. Es la metaversión de esta matriz de compatibilidad. Describe los elementos que se esperan en la matriz de compatibilidad. No se relaciona con la versión de XML.
compatibility-matrix.type
Obligatorio. Tipo de esta matriz de compatibilidad:
  • "device": Matriz de compatibilidad de dispositivos.
  • "framework": Matriz de compatibilidad del framework.
manifest.level
Obligatorio para la matriz de compatibilidad del framework. En Android 12 y versiones posteriores, se permite en los archivos de matriz de compatibilidad del framework en las particiones product y system_ext. Especifica la versión de la matriz de compatibilidad del framework (versión de FCM) de este archivo. No declares esto en la matriz de compatibilidad del framework 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 (framework o dispositivo) requiere que esté presente. Las entradas de HAL se distinguen por un elemento <name>. Puede haber varias entradas de HAL con el mismo nombre (implica la condición "y").
compatibility-matrix.hal.format
Opcional. El valor puede ser uno de los siguientes:
  • "hidl": HAL de HIDL Es el valor predeterminado.
  • "aidl": HAL de AIDL Solo es válido en la metaversión 2.0 de la matriz de compatibilidad.
  • "native": HALs nativos.
compatibility-matrix.hal.optional (Android 15 o versiones anteriores)
El atributo
es opcional y su valor predeterminado es falso. Indica si este HAL es opcional para el propietario de la matriz de compatibilidad (framework o dispositivo). Si una entrada <hal> está marcada como opcional, significa que el propietario puede trabajar con este HAL, si está presente, pero no es obligatorio que lo esté.
Advertencia: Este atributo dejó de estar disponible después de Android 15 y ya no tiene ningún efecto. Si se requiere instalar algún HAL, este requisito se debe aplicar en las pruebas.
compatibility-matrix.hal.name
Obligatorio. Es el nombre completo del paquete de este HAL. Ejemplos:
  • android.hardware.camera (HAL de HIDL o AIDL)
  • GLES (HAL nativo, solo requiere el nombre)
compatibility-matrix.hal.version
Es una lista de rangos de versiones (consulta HAL matches) que define qué versiones espera el propietario de la matriz de compatibilidad (framework o dispositivo).

Para HIDL y HAL nativos, es obligatorio y se puede repetir sin duplicados. El formato es uno de los siguientes:
  • MAJOR.MINOR_MIN-MINOR_MAX
  • MAJOR.MINOR (equivalente a MAJOR.MINOR-MINOR)

En el caso de los HAL de AIDL, 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. Es una lista de las interfaces obligatorias de este HAL.
compatibility-matrix.hal.interface.name
Obligatorio. Es el nombre de la interfaz.
compatibility-matrix.hal.interface.instance
Opcional, se puede repetir. Es una lista de instancias obligatorias de esta interfaz.
compatibility-matrix.hal.interface.regex-instance
Opcional, se puede repetir. Es una lista de los patrones de nombres de instancias obligatorios en esta interfaz. Usa el formato de expresión regular extendida.
compatibility-matrix.kernel
Opcional, se puede repetir. Especifica una lista de parámetros de configuración del kernel que requiere el framework en cada versión del kernel.
Pueden existir varios <kernel> con el mismo <version> para implicar una relación "y". Cada <kernel> es un "fragmento" de los requisitos que se habilitan solo cuando se cumplen <conditions>.
compatibility-matrix.kernel.version
Obligatorio. Versión del kernel. 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 mínima de LTS del kernel que espera el framework.
compatibility-matrix.kernel.condition
Opcional. No debe existir para el primer <kernel> de cada versión. Especifica una lista de condiciones. Cuando se cumplen las condiciones, se habilitan los requisitos que se indican en este fragmento <kernel>.
compatibility-matrix.kernel.config
Opcional, se puede repetir. Enumera los elementos 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
Obligatorio. Es el nombre clave del elemento CONFIG. Comienza con CONFIG_.
compatibility-matrix.kernel.config.value
Obligatorio. Es el 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)). Se interpreta como un número entero de 64 bits. Los desbordamientos producen truncamiento. (El analizador acepta valores de -264 + 1 a 264 - 1, el bit 65 se trunca. Para obtener más información, consulta la página man de strtoull).
  • range. El formato es [int]-[int], p.ej., 10-20. Se aceptan valores hexadecimales y deben comenzar con 0x o 0X. Dos límites deben ser un número entero de 64 bits sin firma.
  • tristate. Los valores válidos son y, m y n.
compatibility-matrix.kernel.config.value.type
Obligatorio. Es el tipo del valor del elemento CONFIG, uno de los siguientes:
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
Obligatorio. Contiene todas las entradas relacionadas con sepolicy. Solo lo usa la matriz de compatibilidad del framework.
compatibility-matrix.sepolicy.sepolicy-version
Obligatorio, se puede repetir. Describe el requisito de la versión de sepolicy. Corresponde a manifest.sepolicy.version. Cada instancia de un elemento define un rango de versiones de sepolicy.
compatibility-matrix.sepolicy.kernel-sepolicy-version
Obligatorio. Declara la versión de policydb con la que funciona el framework.
compatibility-matrix.avb.vbmeta-version
Opcional. Solo lo usa la matriz de compatibilidad del framework. Declara la versión de AVB que se usa para firmar system.img. Dejó de estar disponible en Android 10.
compatibility-matrix.vendor-ndk
Opcional. Solo lo usa la matriz de compatibilidad del dispositivo. Declara el requisito de la instantánea del proveedor del VNDK. Si falta, no se realiza ningún requisito de VNDK en la imagen del sistema.
compatibility-matrix.vendor-ndk.version
Obligatorio. Es un número entero positivo que declara una versión de VNDK que requiere la imagen del proveedor.
compatibility-matrix.vendor-ndk.library
Opcional, se puede repetir. Declara un conjunto de bibliotecas de VNDK que requiere la imagen del proveedor. Tiene la misma semántica que manifest.vendor-ndk.library.
compatibility-matrix.system-sdk.version
Opcional, se puede repetir; solo lo usa la matriz de compatibilidad del dispositivo. Declara el requisito de las apps del proveedor en las versiones del SDK del sistema. Si falta, no se realiza ningún requisito de SDK del sistema en la imagen del sistema.