Matrizes de compatibilidade

Esta seção descreve as matrizes de compatibilidade da estrutura e do dispositivo e o esquema da matriz de compatibilidade . Para regras de correspondência, consulte Regras de correspondência .

Matriz de compatibilidade de estrutura (FCM)

A matriz de compatibilidade da estrutura (FCM) descreve os requisitos da estrutura no dispositivo em que ela é executada. A matriz de compatibilidade da estrutura consiste na matriz de compatibilidade do sistema, na matriz de compatibilidade do produto e na matriz de compatibilidade system_ext . Os requisitos do FCM devem ser atendidos pelo manifesto do dispositivo (requisitos aplicados em tempo de construção, tempo de execução e em VTS).

O FCM system_ext e o FCM do produto são complementos do FCM específico do dispositivo (instalado na partição do sistema).

  • O dispositivo FCM deve refletir os requisitos dos módulos na partição do sistema .
  • O FCM system_ext deve refletir os requisitos por módulos na partição system_ext.
  • O FCM do produto deve refletir os requisitos por módulos na partição do produto .

Todos os FCMs devem estar alinhados com as modificações de um OEM na estrutura nas partições system, product e system_ext. Por exemplo, se um aplicativo instalado na partição do produto usar uma extensão do fornecedor de uma interface HAL, o requisito da interface HAL deverá ser declarado no FCM do produto.

Exemplo de arquivo de matriz de compatibilidade do 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 obter mais detalhes, consulte Ciclo de vida do FCM .

Matriz de compatibilidade do produto

O produto FCM é um arquivo de matriz de compatibilidade de estrutura na partição do produto. O objeto VINTF une o produto FCM com FCMs no sistema e partições system_ext em tempo de execução.

Exemplo de arquivo FCM do produto:

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

O system_ext FCM é um arquivo de matriz de compatibilidade de estrutura na partição system_ext. O objeto VINTF une o FCM system_ext com FCMs nas partições do sistema e do produto em tempo de execução. Consulte a matriz de compatibilidade do produto para obter um exemplo de arquivo system_ext FCM.

Matriz de compatibilidade de dispositivos (DCM)

A matriz de compatibilidade de dispositivos descreve um conjunto de requisitos que o dispositivo espera da estrutura (requisitos aplicados no lançamento e no momento da OTA).

Exemplo de arquivo 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 compatibilidade

Esta seção descreve o significado dessas tags XML. Algumas tags "obrigatórias" podem estar faltando no arquivo de origem na árvore de origem do Android e escritas por assemble_vintf no momento da compilação. As tags "obrigatórias" devem estar presentes nos arquivos correspondentes no dispositivo.

?xml
Opcional. Ele fornece apenas informações ao analisador XML.
compatibility-matrix.version
Obrigatório. Metaversão desta matriz de compatibilidade. Descreve os elementos esperados na matriz de compatibilidade. Não relacionado à versão XML.
compatibility-matrix.type
Obrigatório. Tipo desta matriz de compatibilidade:
  • "device" : Matriz de compatibilidade de dispositivos.
  • "framework" : matriz de compatibilidade do framework.
manifest.level
Necessário para matriz de compatibilidade de estrutura. No Android 12 e versões posteriores, arquivos de matriz de compatibilidade de estrutura são permitidos nas partições product e system_ext. Especifica a versão da matriz de compatibilidade do Framework (versão FCM) deste arquivo. Não declare isso na matriz de compatibilidade da estrutura específica do dispositivo (ou seja, DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE ).
compatibility-matrix.hal
Opcional e pode repetir. Lista um único HAL (HIDL ou nativo) que o proprietário da matriz de compatibilidade (estrutura ou dispositivo) exige que esteja presente. As entradas HAL são diferenciadas por um elemento <name> ; pode haver várias entradas HAL com o mesmo nome (implica condição "e").
compatibility-matrix.hal.format
Opcional. O valor pode ser um dos seguintes:
  • "hidl" : HALs HIDL. Este é o padrão.
  • "aidl" : HALs AIDL . Válido apenas na meta-versão 2.0 da matriz de compatibilidade.
  • "native" : HALs nativos.
compatibility-matrix.hal.optional
O atributo é opcional e o padrão é falso. Indica se este HAL é opcional para o proprietário da matriz de compatibilidade (estrutura ou dispositivo). Se uma entrada <hal> estiver marcada como opcional, significa que o proprietário pode trabalhar com este HAL, se presente, mas não exige que ele esteja presente.
compatibility-matrix.hal.name
Obrigatório. Nome completo do pacote deste HAL. Exemplos:
  • android.hardware.camera (HIDL ou AIDL HAL)
  • GLES (HAL nativo, requer apenas nome)
compatibility-matrix.hal.version
Uma lista de intervalos de versões (veja correspondências HAL ) que define quais versões o proprietário da matriz de compatibilidade (estrutura ou dispositivo) espera.

Para HIDL e HALs nativos, obrigatório, pode ser repetido sem duplicatas. O formato é um dos seguintes:
  • MAJOR . MINOR_MIN - MINOR_MAX
  • MAJOR . MINOR (equivalente a MAJOR . MINOR - MINOR )

Para AIDL HALs, não deve estar presente em dispositivos com Android 11 e versões anteriores. Opcional em dispositivos que executam versões posteriores. Se especificado, o formato é um dos seguintes:
  • VERSION_MIN - VERSION_MAX
  • VERSION (equivalente a VERSION - VERSION )
Se não for especificado, o valor padrão será 1 .
compatibility-matrix.hal.interface
Opcional, pode repetir. Uma lista de interfaces necessárias deste HAL.
compatibility-matrix.hal.interface.name
Obrigatório. Nome da interface.
compatibility-matrix.hal.interface.instance
Opcional, pode repetir. Uma lista de instâncias necessárias desta interface.
compatibility-matrix.hal.interface.regex-instance
Opcional, pode repetir. Uma lista de padrões de nomes de instância necessários nesta interface. Use o formato de Expressão Regular Estendida .
compatibility-matrix.kernel
Opcional, pode repetir. Especifique uma lista de configurações de kernel que a estrutura exige em cada versão do kernel.
Vários <kernel> com a mesma <version> podem existir para implicar relacionamento "e". Cada <kernel> é um "fragmento" dos requisitos que são habilitados somente quando <conditions> são atendidas.
compatibility-matrix.kernel.version
Obrigatório. Versão do kernel. O formato é VERSION . MAJOR_REVISION . MINOR_REVISION . A versão e a revisão principal devem corresponder exatamente. A revisão secundária define a versão LTS mínima do kernel que a estrutura espera.
compatibility-matrix.kernel.condition
Opcional. Não deve existir para o primeiro <kernel> de cada versão. Especifica uma lista de condições. Quando as condições forem atendidas, os requisitos indicados neste fragmento <kernel> serão habilitados.
compatibility-matrix.kernel.config
Opcional, pode repetir. Lista os itens CONFIG que devem corresponder a esta versão do kernel. Cada item CONFIG é um par de valores-chave; os itens de configuração são diferenciados por chave.
compatibility-matrix.kernel.config.key
Obrigatório. Nome chave do item CONFIG . Começa com CONFIG_ .
compatibility-matrix.kernel.config.value
Obrigatório. Valor do item CONFIG . O formato depende do tipo:
  • string . As citações são omitidas.
  • int . Valores decimais e hexadecimais (devem começar com 0x ou 0X) são aceitos. Interpretado como um número inteiro de 64 bits; estouros resultam em truncamento. (O analisador aceita valores de -2 64 + 1 a 2 64 - 1, o 65º bit é truncado; para obter detalhes, consulte a página de manual do strtoull .)
  • range . O formato é [int]-[int] , por exemplo 10-20 . Valores hexadecimais são aceitos e devem começar com 0x ou 0X . Dois limites devem ser um número inteiro sem sinal de 64 bits.
  • tristate . Os valores válidos são y , m e n .
compatibility-matrix.kernel.config.value.type
Obrigatório. Tipo do valor do item CONFIG , um dos seguintes:
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
Obrigatório. Contém todas as entradas relacionadas à sepolicy. Usado apenas pela matriz de compatibilidade da estrutura.
compatibility-matrix.sepolicy.sepolicy-version
Obrigatório, pode repetir. Descreve o requisito na versão da sepolicy. Corresponde a manifest.sepolicy.version . Cada instância de um elemento define um intervalo de versões de sepolicy.
compatibility-matrix.sepolicy.kernel-sepolicy-version
Obrigatório. Declara a versão policydb com a qual a estrutura funciona.
compatibility-matrix.avb.vbmeta-version
Opcional; usado apenas pela matriz de compatibilidade da estrutura. Declara a versão do AVB usada para assinar system.img . Obsoleto no Android 10.
compatibility-matrix.vendor-ndk
Opcional; usado apenas pela matriz de compatibilidade de dispositivos. Declara o requisito do snapshot do fornecedor VNDK. Se estiver ausente, nenhum requisito de VNDK será feito na imagem do sistema.
compatibility-matrix.vendor-ndk.version
Obrigatório. Um número inteiro positivo que declara uma versão do VNDK exigida pela imagem do fornecedor.
compatibility-matrix.vendor-ndk.library
Opcional, pode repetir. Declara um conjunto de bibliotecas VNDK exigidas pela imagem do fornecedor. Mesma semântica de manifest.vendor-ndk.library .
compatibility-matrix.system-sdk.version
Opcional, pode repetir; usado apenas pela matriz de compatibilidade de dispositivos. Declara o requisito por parte dos aplicativos do fornecedor nas versões do System SDK. Se estiver ausente, nenhum requisito do System SDK será feito na imagem do sistema.