Matrices de compatibilité

Cette section décrit les matrices de compatibilité du cadre et des appareils ainsi que le schéma de la matrice de compatibilité . Pour les règles de correspondance, voir Règles de correspondance .

Matrice de compatibilité du framework (FCM)

La matrice de compatibilité du framework (FCM) décrit les exigences du framework sur l'appareil sur lequel il s'exécute. La matrice de compatibilité du framework comprend la matrice de compatibilité du système, la matrice de compatibilité des produits et la matrice de compatibilité system_ext . Les exigences du FCM doivent être satisfaites par le manifeste du périphérique (exigences appliquées au moment de la construction, de l'exécution et dans VTS).

Le FCM system_ext et le FCM du produit sont des compléments du FCM spécifique au périphérique (installé dans la partition système).

  • Le FCM du périphérique doit refléter les exigences des modules de la partition système .
  • Le FCM system_ext doit refléter les exigences des modules dans la partition system_ext.
  • Le FCM du produit doit refléter les exigences par modules dans la partition du produit .

Tous les FCM doivent s'aligner sur les modifications apportées par un OEM au cadre dans les partitions système, produit et system_ext. Par exemple, si une application installée dans la partition du produit utilise une extension fournisseur d'une interface HAL, les exigences en matière d'interface HAL doivent être déclarées dans le FCM du produit.

Exemple de fichier de matrice de compatibilité système :

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

Pour plus de détails, consultez Cycle de vie FCM .

Matrice de compatibilité des produits

Le produit FCM est un fichier de matrice de compatibilité de framework dans la partition du produit. L'objet VINTF rejoint le FCM du produit avec les FCM dans les partitions system et system_ext au moment de l'exécution.

Exemple de fichier FCM de produit :

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

Matrice de compatibilité System_ext

Le FCM system_ext est un fichier de matrice de compatibilité de framework dans la partition system_ext. L'objet VINTF rejoint le FCM system_ext avec les FCM dans les partitions système et produit au moment de l'exécution. Voir la matrice de compatibilité des produits pour un exemple de fichier FCM system_ext.

Matrice de compatibilité des appareils (DCM)

La matrice de compatibilité des appareils décrit un ensemble d'exigences que l'appareil attend du framework (exigences appliquées au lancement et au moment de l'OTA).

Exemple de fichier 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>

Schéma de la matrice de compatibilité

Cette section décrit la signification de ces balises XML. Certaines balises "obligatoires" peuvent manquer dans le fichier source dans l'arborescence des sources Android et être écrites par assemble_vintf au moment de la construction. Les balises "Obligatoires" doivent être présentes dans les fichiers correspondants sur l'appareil.

?xml
Facultatif. Il fournit uniquement des informations à l'analyseur XML.
compatibility-matrix.version
Requis. Méta-version de cette matrice de compatibilité. Décrit les éléments attendus dans la matrice de compatibilité. Sans rapport avec la version XML.
compatibility-matrix.type
Requis. Type de cette matrice de compatibilité :
  • "device" : Matrice de compatibilité des appareils.
  • "framework" : Matrice de compatibilité du framework.
manifest.level
Requis pour la matrice de compatibilité du framework. Sous Android 12 et versions ultérieures, autorisé dans les fichiers de matrice de compatibilité du framework dans les partitions product et system_ext. Spécifie la version de la matrice de compatibilité du framework (version FCM) de ce fichier. Ne déclarez pas cela dans la matrice de compatibilité du framework spécifique à l'appareil (c'est-à-dire DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE ).
compatibility-matrix.hal
Facultatif et peut répéter. Répertorie un seul HAL (HIDL ou natif) dont le propriétaire de la matrice de compatibilité (framework ou périphérique) doit être présent. Les entrées HAL se distinguent par un élément <name> ; il peut y avoir plusieurs entrées HAL avec le même nom (implique la condition "et").
compatibility-matrix.hal.format
Facultatif. La valeur peut être l'une des suivantes :
  • "hidl" : HIDL HAL. C'est la valeur par défaut.
  • "aidl" : AIDL HAL . Uniquement valable sur la méta-version 2.0 de la matrice de compatibilité.
  • "native" : HAL natifs.
compatibility-matrix.hal.optional
L'attribut est facultatif et la valeur par défaut est false. Indique si ce HAL est facultatif pour le propriétaire de la matrice de compatibilité (framework ou périphérique). Si une entrée <hal> est marquée comme facultative, cela signifie que le propriétaire peut travailler avec cette HAL, si elle est présente, mais n'exige pas qu'elle soit présente.
compatibility-matrix.hal.name
Requis. Nom complet du package de ce HAL. Exemples:
  • android.hardware.camera (HIDL ou AIDL HAL)
  • GLES (HAL natif, nécessite uniquement le nom)
compatibility-matrix.hal.version
Une liste de plages de versions (voir Correspondances HAL ) qui définit les versions attendues par le propriétaire de la matrice de compatibilité (framework ou périphérique).

Pour HIDL et HAL natifs, requis, peuvent se répéter sans doublons. Le format est l'un des suivants :
  • MAJOR . MINOR_MIN - MINOR_MAX
  • MAJOR . MINOR (équivalent à MAJOR . MINOR - MINOR )

Pour les HAL AIDL, ne doivent pas être présents sur les appareils exécutant Android 11 et versions antérieures. Facultatif sur les appareils exécutant des versions ultérieures. S'il est spécifié, le format est l'un des suivants :
  • VERSION_MIN - VERSION_MAX
  • VERSION (équivalent à VERSION - VERSION )
Si elle n'est pas spécifiée, la valeur par défaut est 1 .
compatibility-matrix.hal.interface
Facultatif, peut répéter. Une liste des interfaces requises de ce HAL.
compatibility-matrix.hal.interface.name
Requis. Nom de l'interface.
compatibility-matrix.hal.interface.instance
Facultatif, peut répéter. Une liste des instances requises de cette interface.
compatibility-matrix.hal.interface.regex-instance
Facultatif, peut répéter. Une liste des modèles de nom d'instance requis sur cette interface. Utilisez le format d'expression régulière étendue .
compatibility-matrix.kernel
Facultatif, peut répéter. Spécifiez une liste de configurations de noyau requises par le framework sur chaque version du noyau.
Plusieurs <kernel> avec la même <version> peuvent exister pour impliquer une relation « et ». Chaque <kernel> est un « fragment » des exigences qui ne sont activées que lorsque <conditions> sont remplies.
compatibility-matrix.kernel.version
Requis. Version noyau. Le format est VERSION . MAJOR_REVISION . MINOR_REVISION . La version et la révision majeure doivent correspondre exactement. La révision mineure définit la version LTS minimale du noyau attendue par le framework.
compatibility-matrix.kernel.condition
Facultatif. Ne doit pas exister pour le premier <kernel> de chaque version. Spécifie une liste de conditions. Lorsque les conditions sont remplies, les exigences indiquées dans ce fragment <kernel> sont activées.
compatibility-matrix.kernel.config
Facultatif, peut répéter. Répertorie les éléments CONFIG qui doivent correspondre pour cette version du noyau. Chaque élément CONFIG est une paire clé-valeur ; les éléments de configuration sont distingués par clé.
compatibility-matrix.kernel.config.key
Requis. Nom de clé de l'élément CONFIG . Commence par CONFIG_ .
compatibility-matrix.kernel.config.value
Requis. Valeur de la rubrique CONFIG . Le format dépend du type :
  • string . Les citations sont omises.
  • int . Les valeurs décimales et hexadécimales (doivent commencer par 0x ou 0X) sont acceptées. Interprété comme un entier de 64 bits ; les débordements entraînent une troncature. (L'analyseur accepte les valeurs de -2 64 + 1 à 2 64 - 1, le 65ème bit est tronqué ; pour plus de détails, reportez-vous à la page de manuel strtoull .)
  • range . Le format est [int]-[int] , par exemple 10-20 . Les valeurs hexadécimales sont acceptées et doivent commencer par 0x ou 0X . Deux limites doivent être un entier non signé de 64 bits.
  • tristate . Les valeurs valides sont y , m et n .
compatibility-matrix.kernel.config.value.type
Requis. Type de la valeur de l'élément CONFIG , l'un des suivants :
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
Requis. Contient toutes les entrées liées à la politique de sécurité. Utilisé uniquement par la matrice de compatibilité du framework.
compatibility-matrix.sepolicy.sepolicy-version
Obligatoire, peut répéter. Décrit les exigences relatives à la version de la stratégie de sécurité. Correspond à manifest.sepolicy.version . Chaque instance d'un élément définit une plage de versions de stratégie.
compatibility-matrix.sepolicy.kernel-sepolicy-version
Requis. Déclare la version policydb avec laquelle le framework fonctionne.
compatibility-matrix.avb.vbmeta-version
Facultatif; utilisé uniquement par la matrice de compatibilité du framework. Déclare la version AVB utilisée pour signer system.img . Obsolète dans Android 10.
compatibility-matrix.vendor-ndk
Facultatif; utilisé uniquement par la matrice de compatibilité des appareils. Déclare l’exigence de l’instantané du fournisseur VNDK. En cas d'absence, aucune exigence VNDK n'est effectuée sur l'image système.
compatibility-matrix.vendor-ndk.version
Requis. Entier positif qui déclare une version VNDK requise par l’image du fournisseur.
compatibility-matrix.vendor-ndk.library
Facultatif, peut répéter. Déclare un ensemble de bibliothèques VNDK requises par l'image du fournisseur. Même sémantique que manifest.vendor-ndk.library .
compatibility-matrix.system-sdk.version
Facultatif, peut répéter ; utilisé uniquement par la matrice de compatibilité des appareils. Déclare l’exigence des applications du fournisseur sur les versions du SDK système. S’il est manquant, aucune exigence du SDK système n’est faite sur l’image système.