Règles de correspondance

Les deux paires de matrices de compatibilité et de fichiers manifestes sont censées être réconciliées pour vérifier que l'implémentation du framework et du fournisseur peuvent fonctionner ensemble. Cette validation est réussie si la matrice de compatibilité du framework correspond au fichier manifeste de l'appareil, et si le fichier manifeste du framework correspond à la matrice de compatibilité de l'appareil.

Cette vérification est effectuée au moment de la compilation, de la génération du package de mise à jour OTA, du démarrage et des tests de compatibilité VTS.

Les sections suivantes décrivent en détail les règles de mise en correspondance utilisées par les différents composants.

La version de la matrice de compatibilité du framework correspond

Pour faire correspondre un fichier manifeste d'appareil à une matrice de compatibilité du framework, la version FCM de livraison spécifiée par manifest.target-level doit être exactement égale à la version FCM spécifiée par compatibility-matrix.level. Sinon, il n'y a pas de correspondance.

Lorsque la matrice de compatibilité du framework est demandée avec libvintf, cette correspondance est toujours réussie, car libvintf ouvre le fichier manifeste de l'appareil, récupère la version FCM de livraison et renvoie la matrice de compatibilité du framework à cette version FCM de livraison (plus certains HAL facultatifs des matrices de compatibilité aux versions FCM supérieures).

Correspondances HAL

La règle de correspondance HAL identifie les versions des éléments hal dans un fichier manifeste qui sont considérées comme compatibles par le propriétaire de la matrice de compatibilité correspondante.

HIDL et HAL natifs

Les règles de correspondance pour les HAL HIDL et natifs sont les suivantes :

• Plusieurs éléments <hal> sont évalués avec une seule relation ET.
• Les éléments <hal> peuvent avoir <hal optional="true"> pour les marquer comme non obligatoires.
• Plusieurs éléments <version> au sein du même élément <hal> ont une relation OR. Si plusieurs versions sont spécifiées, une seule d'entre elles doit être implémentée. (Voir Correspondance HAL réussie pour le module DRM.)
• Plusieurs éléments <instance> et <regex-instance> au sein du même élément <hal> sont évalués avec une seule relation ET lorsque l'élément <hal> est requis. (Consultez Correspondance HAL réussie pour le module DRM.)

Exemple : correspondance HAL réussie pour un module

Pour un HAL en version 2.5, la règle de correspondance est la suivante :

Exemple : correspondance HAL réussie pour le module DRM

La matrice de compatibilité du framework indique les informations de version suivantes pour DRM HAL :

<hal>
    <name>android.hardware.drm
    <version>1.0</version>
    <version>3.1-2</version>
    <interface>
        <name>IDrmFactory</name>
        <instance>default</instance>
        <instance>specific</instance>
    </interface>
</hal>
<hal>
    <name>android.hardware.drm
    <version>2.0</version>
    <interface>
        <name>ICryptoFactory</name>
        <instance>default</instance>
        <regex-instance>[a-z]+/[0-9]+</regex-instance>
    </interface>
</hal>

Un fournisseur doit implémenter l'UNE des instances suivantes :

android.hardware.drm@1.x::IDrmFactory/default          // where x >= 0
android.hardware.drm@1.x::IDrmFactory/specific         // where x >= 0

OU :

android.hardware.drm@3.y::IDrmFactory/default          // where y >= 1
android.hardware.drm@3.y::IDrmFactory/specific         // where y >= 1

ET doit implémenter toutes ces instances :

android.hardware.drm@2.z::ICryptoFactory/default       // where z >= 0
android.hardware.drm@2.z::ICryptoFactory/${INSTANCE}
            // where z >= 0 and ${INSTANCE} matches [a-z]+/[0-9]+
            // e.g. legacy/0

HAL AIDL

Android 11 et versions ultérieures sont compatibles avec les versions des HAL AIDL dans VINTF. Les règles de correspondance pour les HAL AIDL sont semblables à celles des HAL HIDL et natifs, sauf qu'il n'y a pas de versions majeures et qu'il existe exactement une version par instance HAL (1 si la version n'est pas spécifiée) :

• Plusieurs éléments <hal> sont évalués avec une seule relation ET.
• Les éléments <hal> peuvent comporter <hal optional="true"> pour indiquer qu'ils ne sont pas obligatoires.
• Plusieurs éléments <instance> et <regex-instance> au sein du même <hal> sont évalués avec une seule relation ET lorsque le <hal> est requis. (Consultez Correspondance HAL réussie pour plusieurs modules.)

Exemple : correspondance HAL réussie pour un module

Pour une HAL de version 5, la règle de correspondance est la suivante :

Exemple : correspondance HAL réussie pour plusieurs modules

La matrice de compatibilité du framework indique les informations de version suivantes pour les HAL du vibreur et de l'appareil photo :

<hal>
    <name>android.hardware.vibrator
    <version>1-2</version>
    <interface>
        <name>IVibrator</name>
        <instance>default</instance>
        <instance>specific</instance>
    </interface>
</hal>
<hal>
    <name>android.hardware.camera
    <version>5</version>
    <interface>
        <name>ICamera</name>
        <instance>default</instance>
        <regex-instance>[a-z]+/[0-9]+</regex-instance>
    </interface>
</hal>

Un fournisseur doit implémenter toutes ces instances :

android.hardware.vibrator.IVibrator/default     // version >= 1
android.hardware.vibrator.IVibrator/specific    // version >= 1
android.hardware.camera.ICamera/default         // version >= 5
android.hardware.camera.ICamera/${INSTANCE}
            // with version >= 5, where ${INSTANCE} matches [a-z]+/[0-9]+
            // e.g. legacy/0

Correspondances du noyau

La section <kernel> de la matrice de compatibilité du framework décrit les exigences du framework concernant le noyau Linux sur l'appareil. Ces informations doivent correspondre aux informations sur le noyau qui sont signalées par l'objet VINTF de l'appareil.

Faire correspondre les branches du noyau

Chaque suffixe de branche de noyau (par exemple, 5.4-r) est mappé à une version FCM de noyau unique (par exemple, 5). Le mappage est le même que celui entre les lettres de version (par exemple, R) et les versions FCM (par exemple, 5).

Les tests VTS imposent que l'appareil spécifie explicitement la version FCM du noyau dans le fichier manifeste de l'appareil, /vendor/etc/vintf/manifest.xml, si l'une des conditions suivantes est remplie :

• La version FCM du noyau est différente de la version FCM cible. Par exemple, l'appareil mentionné ci-dessus a une version FCM cible de 4 et une version FCM du noyau de 5 (suffixe de branche du noyau r).
• La version FCM du noyau est supérieure ou égale à 5 (suffixe de branche du noyau r).

Les tests VTS garantissent que, si la version FCM du noyau est spécifiée, elle est supérieure ou égale à la version FCM cible dans le fichier manifeste de l'appareil.

Exemple : Déterminer la branche du noyau

Si l'appareil cible la version 4 de FCM (publiée dans Android 10), mais exécute le noyau de la branche 4.19-r, le fichier manifeste de l'appareil doit spécifier les éléments suivants :

<manifest version="2.0" type="device" target-level="4">
   <kernel target-level="5" />
</manifest>

L'objet VINTF vérifie la compatibilité du noyau par rapport aux exigences de la branche du noyau 4.19-r, qui est spécifiée dans la version 5 de FCM. Ces exigences sont basées sur kernel/configs/r/android-4.19 dans l'arborescence source Android.

Exemple : Déterminer la branche du noyau pour GKI

Si l'appareil utilise l'image générique du noyau (GKI) et que la chaîne de version du noyau de /proc/version est la suivante :

5.4.42-android12-0-00544-ged21d463f856

L'objet VINTF obtient ensuite la version d'Android à partir de la version du noyau et l'utilise pour déterminer la version FCM du noyau. Dans cet exemple, android12 signifie la version 6 du noyau FCM (publiée dans Android 12).

Pour en savoir plus sur l'analyse de la chaîne de version du noyau, consultez Gestion des versions GKI.

Faire correspondre les versions du noyau

Une matrice peut inclure plusieurs sections <kernel>, chacune avec un attribut version différent au format suivant :

${ver}.${major_rev}.${kernel_minor_rev}

L'objet VINTF ne prend en compte que la section <kernel> du FCM avec la version FCM correspondante, avec les mêmes ${ver} et ${major_rev} que le noyau de l'appareil (c'est-à-dire version="${ver}.${major_rev}.${matrix_minor_rev}")). Les autres sections sont ignorées. De plus, la révision mineure du noyau doit être une valeur de la matrice de compatibilité (${kernel_minor_rev} >= ${matrix_minor_rev}). Si aucune section <kernel> ne répond à ces exigences, il n'y a pas de correspondance.

Exemple : sélectionner les exigences pour la mise en correspondance

Prenons l'exemple hypothétique suivant, dans lequel les FCM de /system/etc/vintf déclarent les exigences suivantes (les balises d'en-tête et de pied de page sont omises) :

<!-- compatibility_matrix.3.xml -->
<kernel version="4.4.107" level="3"/>
<!-- See kernel/configs/p/android-4.4/ for 4.4-p requirements -->
<kernel version="4.9.84" level="3"/>
<!-- See kernel/configs/p/android-4.9/ for 4.9-p requirements -->
<kernel version="4.14.42" level="3"/>
<!-- See kernel/configs/p/android-4.14/ for 4.14-p requirements -->

<!-- compatibility_matrix.4.xml -->
<kernel version="4.9.165" level="4"/>
<!-- See kernel/configs/q/android-4.9/ for 4.9-q requirements -->
<kernel version="4.14.105" level="4"/>
<!-- See kernel/configs/q/android-4.14/ for 4.14-q requirements -->
<kernel version="4.19.42" level="4"/>
<!-- See kernel/configs/q/android-4.19/ for 4.19-q requirements -->

<!-- compatibility_matrix.5.xml -->
<kernel version="4.14.180" level="5"/>
<!-- See kernel/configs/r/android-4.14/ for 4.14-r requirements -->
<kernel version="4.19.123" level="5"/>
<!-- See kernel/configs/r/android-4.19/ for 4.19-r requirements -->
<kernel version="5.4.41" level="5"/>
<!-- See kernel/configs/r/android-5.4/ for 5.4-r requirements -->

La version FCM cible, la version FCM du noyau et la version du noyau sélectionnent ensemble les exigences du noyau à partir des FCM :

Faire correspondre les configurations du noyau

Si la section <kernel> correspond, le processus se poursuit en tentant de faire correspondre les éléments config à /proc/config.gz. Pour chaque élément de configuration de la matrice de compatibilité, il recherche /proc/config.gz pour voir si la configuration est présente. Lorsqu'un élément de configuration est défini sur n dans la matrice de compatibilité pour la section <kernel> correspondante, il doit être absent de /proc/config.gz. Enfin, un élément de configuration qui ne figure pas dans la matrice de compatibilité peut ou non être présent dans /proc/config.gz.

Exemple : Faire correspondre les configurations du kernel

• <value type="string">bar</value> correspond à "bar". Les guillemets sont omis dans la matrice de compatibilité, mais sont présents dans /proc/config.gz.
• <value type="int">4096</value> correspond à 4096, 0x1000 ou 0X1000.
• <value type="int">0x1000</value> correspond à 4096, 0x1000 ou 0X1000.
• <value type="int">0X1000</value> correspond à 4096, 0x1000 ou 0X1000.
• <value type="tristate">y</value> correspond à y.
• <value type="tristate">m</value> correspond à m.
• <value type="tristate">n</value> signifie que l'élément de configuration ne doit PAS exister dans /proc/config.gz.
• <value type="range">1-0x3</value> correspond à 1, 2 ou 3, ou à l'équivalent hexadécimal.

Exemple : correspondance réussie du noyau

Une matrice de compatibilité du framework avec FCM version 1 contient les informations de noyau suivantes :

<kernel version="4.14.42">
   <config>
      <key>CONFIG_TRI</key>
      <value type="tristate">y</value>
   </config>
   <config>
      <key>CONFIG_NOEXIST</key>
      <value type="tristate">n</value>
   </config>
   <config>
      <key>CONFIG_DEC</key>
      <value type="int">4096</value>
   </config>
   <config>
      <key>CONFIG_HEX</key>
      <value type="int">0XDEAD</value>
   </config>
   <config>
      <key>CONFIG_STR</key>
      <value type="string">str</value>
   </config>
   <config>
      <key>CONFIG_EMPTY</key>
      <value type="string"></value>
   </config>
</kernel>

La branche du noyau est mise en correspondance en premier. La branche du noyau est spécifiée dans le fichier manifeste de l'appareil dans manifest.kernel.target-level, qui est défini par défaut sur manifest.level si la première n'est pas spécifiée :

• Si la branche du noyau dans le fichier manifeste de l'appareil est définie sur 1, le processus passe à l'étape suivante et vérifie la version du noyau.
• Si la branche du noyau dans le fichier manifeste de l'appareil est définie sur 2, il n'y a aucune correspondance avec la matrice. Les objets VINTF lisent les exigences du noyau à partir de la matrice à la version 2 de FCM.

La version du noyau est ensuite mise en correspondance. Si un appareil dans uname() signale :

• 4.9.84 (aucune correspondance avec la matrice, sauf s'il existe une section distincte du noyau avec <kernel version="4.9.x">, où x <= 84)
• 4.14.41 (aucune correspondance avec la matrice, plus petit que version)
• 4.14.42 (correspondance avec la matrice)
• 4.14.43 (correspondance avec la matrice)
• 4.1.22 (aucune correspondance avec la matrice, sauf s'il existe une section de noyau distincte avec <kernel version="4.1.x">, où x <= 22)

Une fois la section <kernel> appropriée sélectionnée, pour chaque élément <config> dont la valeur est différente de n, l'entrée correspondante doit être présente dans /proc/config.gz ; pour chaque élément <config> dont la valeur est n, l'entrée correspondante ne doit pas être présente dans /proc/config.gz. Le contenu de <value> doit correspondre exactement au texte après le signe égal (y compris les guillemets), jusqu'au caractère de nouvelle ligne ou #, avec les espaces blancs de début et de fin tronqués.

La configuration du noyau suivante est un exemple de correspondance réussie :

# comments don't matter
CONFIG_TRI=y
# CONFIG_NOEXIST shouldn't exist
CONFIG_DEC = 4096 # trailing comments and whitespaces are fine
CONFIG_HEX=57005  # 0XDEAD == 57005
CONFIG_STR="str"
CONFIG_EMPTY=""   # empty string must have quotes
CONFIG_EXTRA="extra config items are fine too"

La configuration du noyau suivante est un exemple de correspondance infructueuse :

CONFIG_TRI="y"   # mismatch: quotes
CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists
CONFIG_HEX=0x0   # mismatch; value doesn't match
CONFIG_DEC=""    # mismatch; type mismatch (expect int)
CONFIG_EMPTY=1   # mismatch; expects ""
# mismatch: CONFIG_STR is missing

Correspondances SEPolicy

SEPolicy nécessite les correspondances suivantes :

• <sepolicy-version> définit une plage fermée de versions mineures pour chaque version majeure. La version SEPolicy signalée par l'appareil doit se situer dans l'une de ces plages pour être compatible avec le framework. Les règles de correspondance sont semblables aux versions HAL. La correspondance est établie si la version SEPolicy est supérieure ou égale à la version minimale de la plage. La version maximale est fournie à titre informatif uniquement.
• <kernel-sepolicy-version>, c'est-à-dire la version de la base de données des règles, doit être inférieure à security_policyvers() indiqué par l'appareil.

Exemple : correspondance SEPolicy réussie

La matrice de compatibilité du framework indique les informations SEPolicy suivantes :

<sepolicy>
    <kernel-sepolicy-version>30</kernel-sepolicy-version>
    <sepolicy-version>25.0</sepolicy-version>
    <sepolicy-version>26.0-3</sepolicy-version>
</sepolicy>

Sur l'appareil :

• La valeur renvoyée par security_policyvers() doit être supérieure ou égale à 30. Sinon, il ne s'agit pas d'une correspondance. Par exemple :
  • Si un appareil renvoie 29, cela signifie qu'il n'y a pas de correspondance.
  • Si un appareil renvoie 31, il s'agit d'une correspondance.
• La version de SEPolicy doit être comprise entre 25.0 et ∞ ou entre 26.0 et ∞. Sinon, il n'y a pas de correspondance. (Le -3 après 26.0 est purement informatif.)

Correspondances de version AVB

La version AVB contient une version MAJEURE et une version MINEURE, au format MAJEURE.MINEURE (par exemple, 1.0, 2.1). Pour en savoir plus, consultez Gestion des versions et compatibilité. La version AVB possède les propriétés système suivantes :

• ro.boot.vbmeta.avb_version est la version libavb dans le bootloader.
• ro.boot.avb_version correspond à la version libavb dans l'OS Android (init/fs_mgr).

La propriété système ne s'affiche que lorsque le libavb correspondant a été utilisé pour valider les métadonnées AVB (et renvoie OK). Il est absent en cas d'échec de la validation (ou si aucune validation n'a eu lieu).

Une correspondance de compatibilité compare les éléments suivants :

• sysprop ro.boot.vbmeta.avb_version avec avb.vbmeta-version de la matrice de compatibilité du framework :
  • ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR
  • ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR
• sysprop ro.boot.avb_version avec avb.vbmeta-version de la matrice de compatibilité du framework :
  • ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
  • ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR

Le bootloader ou l'OS Android peuvent contenir deux copies des bibliothèques libavb, chacune avec une version MAJOR différente pour les appareils de mise à niveau et les appareils de lancement. Dans ce cas, la même image système non signée peut être partagée, mais les images système signées finales sont différentes (avec des avb.vbmeta-version différents) :

Figure 1 : La version AVB correspond (/system est P, toutes les autres partitions sont O).

Figure 2. Les versions AVB correspondent (toutes les partitions sont P).

Exemple : version AVB correspondante

La matrice de compatibilité du framework indique les informations AVB suivantes :

<avb>
    <vbmeta-version>2.1</vbmeta-version>
</avb>

Sur l'appareil :

ro.boot.avb_version              == 1.0 &&
ro.boot.vbmeta.avb_version       == 2.1  mismatch 

ro.boot.avb_version              == 2.1 &&
ro.boot.vbmeta.avb_version       == 3.0  mismatch 

ro.boot.avb_version              == 2.1 &&
ro.boot.vbmeta.avb_version       == 2.3  match 

ro.boot.avb_version              == 2.3 &&
ro.boot.vbmeta.avb_version       == 2.1  match 

Faire correspondre la version AVB pendant la mise à jour OTA

Pour les appareils lancés avec Android 9 ou une version antérieure, lors de la mise à jour vers Android 10, les exigences de version AVB dans la matrice de compatibilité du framework sont comparées à la version AVB actuelle sur l'appareil. Si la version AVB fait l'objet d'une mise à niveau de version majeure lors d'une mise à jour OTA (par exemple, de 0.0 à 1.0), la vérification de la compatibilité VINTF dans la mise à jour OTA ne reflète pas la compatibilité après la mise à jour OTA.

Pour résoudre ce problème, un OEM peut placer une fausse version AVB dans le package OTA (compatibility.zip) pour passer la vérification. Voici la marche à suivre :

1. Sélectionnez les CL suivants dans l'arborescence source d'Android 9 :
   • CL 732261
   • CL 732262
2. Définissez BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE pour l'appareil. Sa valeur doit être égale à la version AVB avant la mise à jour OTA, c'est-à-dire la version AVB de l'appareil lors de son lancement.
3. Recompilez le package OTA.

Ces modifications placent automatiquement BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE en tant que compatibility-matrix.avb.vbmeta-version dans les fichiers suivants :

• /system/compatibility_matrix.xml (qui n'est pas utilisé dans Android 9) sur l'appareil
• system_matrix.xml dans compatibility.zip dans le package OTA

Ces modifications n'ont aucune incidence sur les autres matrices de compatibilité du framework, y compris /system/etc/vintf/compatibility_matrix.xml. Après la mise à jour OTA, la nouvelle valeur de /system/etc/vintf/compatibility_matrix.xml est utilisée pour les vérifications de compatibilité.

La version VNDK correspond

La matrice de compatibilité des appareils déclare la version VNDK requise dans compatibility-matrix.vendor-ndk.version. Si la matrice de compatibilité des appareils ne comporte pas de tag <vendor-ndk>, aucune exigence n'est imposée et la compatibilité est toujours considérée comme acquise.

Si la matrice de compatibilité des appareils comporte une balise <vendor-ndk>, une entrée <vendor-ndk> avec un <version> correspondant est recherchée dans l'ensemble des instantanés du fournisseur VNDK fournis par le framework dans le fichier manifeste du framework. Si une telle entrée n'existe pas, il n'y a aucune correspondance.

Si une telle entrée existe, l'ensemble des bibliothèques énumérées dans la matrice de compatibilité des appareils doit être un sous-ensemble de l'ensemble des bibliothèques indiquées dans le fichier manifeste du framework. Sinon, l'entrée n'est pas considérée comme une correspondance.

• Dans un cas particulier, si aucune bibliothèque n'est énumérée dans la matrice de compatibilité des appareils, l'entrée est toujours considérée comme une correspondance, car un ensemble vide est un sous-ensemble de n'importe quel ensemble.

Exemple : version VNDK correspondante

Si la matrice de compatibilité des appareils indique l'exigence suivante concernant VNDK :

<!-- Example Device Compatibility Matrix -->
<vendor-ndk>
    <version>27</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
</vendor-ndk>

Dans le fichier manifeste du framework, seule l'entrée avec la version 27 est prise en compte.

<!-- Framework Manifest Example A -->
<vendor-ndk>
    <version>27</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
    <library>libfoo.so</library>
</vendor-ndk>

L'exemple A correspond, car la version 27 du VNDK figure dans le fichier manifeste du framework et {libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so}.

<!-- Framework Manifest Example B -->
<vendor-ndk>
    <version>26</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
</vendor-ndk>
<vendor-ndk>
    <version>27</version>
    <library>libbase.so</library>
</vendor-ndk>

L'exemple B ne correspond pas. Même si la version 27 du VNDK figure dans le fichier manifeste du framework, libjpeg.so n'est pas compatible avec le framework dans cet instantané. La version 26 du VNDK est ignorée.

La version du SDK système correspond

La matrice de compatibilité des appareils déclare un ensemble de versions SDK système requises dans compatibility-matrix.system-sdk.version. Il n'y a de correspondance que si l'ensemble est un sous-ensemble des versions du SDK système fournies, telles qu'elles sont déclarées dans manifest.system-sdk.version dans le fichier manifeste du framework.

• Dans un cas particulier, si aucune version du SDK système n'est énumérée dans la matrice de compatibilité des appareils, elle est toujours considérée comme une correspondance, car un ensemble vide est un sous-ensemble de n'importe quel ensemble.

Exemple : version du SDK système correspondante

Si la matrice de compatibilité des appareils indique l'exigence suivante concernant le SDK System :

<!-- Example Device Compatibility Matrix -->
<system-sdk>
    <version>26</version>
    <version>27</version>
</system-sdk>

Le framework doit ensuite fournir les versions 26 et 27 du SDK système pour correspondre :

<!-- Framework Manifest Example A -->
<system-sdk>
    <version>26</version>
    <version>27</version>
</system-sdk>

L'exemple A correspond :

<!-- Framework Manifest Example B -->
<system-sdk>
    <version>26</version>
    <version>27</version>
    <version>28</version>
</system-sdk>

L'exemple B correspond :

<!-- Framework Manifest Example C -->
<system-sdk>
    <version>26</version>
</system-sdk>

L'exemple C ne correspond pas, car la version 27 du SDK système n'est pas fournie.