Normas de coincidencia

Las dos parejas de matrices y manifiestos de compatibilidad deben conciliarse para verificar que el framework y la implementación del proveedor puedan trabajar en conjunto. Esta verificación se realiza correctamente cuando hay una coincidencia entre la matriz de compatibilidad del framework y el manifiesto del dispositivo, así como entre el manifiesto del framework y la matriz de compatibilidad del dispositivo.

Esta verificación se realiza en el momento de la compilación, en el momento de la generación del paquete de actualización OTA, en el momento del inicio y en las pruebas de compatibilidad de VTS.

En las siguientes secciones, se detallan las reglas de coincidencia que utilizan varios componentes.

La versión de la matriz de compatibilidad del framework coincide

Para que un manifiesto del dispositivo coincida con una matriz de compatibilidad del framework, la versión de FCM de envío especificada por manifest.target-level debe ser exactamente igual a la versión de FCM especificada por compatibility-matrix.level. De lo contrario, no habrá coincidencia.

Cuando se solicita la matriz de compatibilidad del framework con libvintf, esta coincidencia siempre se realiza correctamente porque libvintf abre el manifiesto del dispositivo, recupera la versión de FCM de envío y devuelve la matriz de compatibilidad del framework en esa versión de FCM de envío (además de algunos HAL opcionales de las matrices de compatibilidad en versiones de FCM superiores).

Coincidencias de HAL

La regla de coincidencia de HAL identifica las versiones de los elementos hal en un archivo de manifiesto que se consideran compatibles con el propietario de la matriz de compatibilidad correspondiente.

HALs nativas y de HIDL

Las reglas de coincidencia para las HAL nativas y de HIDL son las siguientes:

• Varios elementos <hal> se evalúan con una sola relación Y.
• Los elementos <hal> pueden tener <hal optional="true"> para marcarlos como no obligatorios.
• Varios elementos <version> dentro del mismo elemento <hal> tienen la relación OR. Si se especifican dos o más, solo se debe implementar una de las versiones. (Consulta Coincidencia correcta de HAL para el módulo DRM).
• Cuando se requiere el elemento <hal>, los múltiples elementos <instance> y <regex-instance> dentro del mismo elemento <hal> se evalúan con una sola relación Y. (Consulta Coincidencia correcta de la HAL para el módulo DRM).

Ejemplo: Coincidencia exitosa de HAL para un módulo

Para un HAL en la versión 2.5, la regla de coincidencia es la siguiente:

Ejemplo: Coincidencia exitosa de HAL para el módulo DRM

La matriz de compatibilidad del framework indica la siguiente información de versión para el HAL de DRM:

<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 proveedor debe implementar UNA de las siguientes instancias:

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

O BIEN:

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

Y debe implementar todas estas instancias:

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

HALs de AIDL

Android y versiones posteriores admiten versiones para los HAL de AIDL en VINTF. Las reglas de coincidencia para las HAL de AIDL son similares a las de las HAL nativas y de HIDL, excepto que no hay versiones principales y hay exactamente una versión por instancia de HAL (1 si no se especifica la versión):

• Varios elementos <hal> se evalúan con una sola relación Y.
• Los elementos <hal> pueden tener <hal optional="true"> para marcarlos como no obligatorios.
• Cuando se requiere el elemento <hal>, los múltiples elementos <instance> y <regex-instance> dentro del mismo <hal> se evalúan con una sola relación Y. (Consulta Coincidencia correcta del HAL para varios módulos).

Ejemplo: Coincidencia exitosa de HAL para un módulo

Para un HAL en la versión 5, la regla de coincidencia es la siguiente:

Ejemplo: Coincidencia correcta de la HAL para varios módulos

La matriz de compatibilidad del framework indica la siguiente información de versión para las HAL de la cámara y el vibrador:

<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 proveedor debe implementar todas estas instancias:

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

Coincidencias del kernel

La sección <kernel> de la matriz de compatibilidad del framework describe los requisitos del framework para el kernel de Linux en el dispositivo. Esta información debe coincidir con la información sobre el kernel que informa el objeto VINTF del dispositivo.

Ramas del kernel coincidentes

Cada sufijo de rama del kernel (por ejemplo, 5.4-r) se asigna a una versión única de FCM del kernel (por ejemplo, 5). La asignación es la misma que la asignación entre las letras de versión (por ejemplo, R) y las versiones de FCM (por ejemplo, 5).

Las pruebas de VTS exigen que el dispositivo especifique de forma explícita la versión de FCM del kernel en el manifiesto del dispositivo, /vendor/etc/vintf/manifest.xml, si se cumple una de las siguientes condiciones:

• La versión del kernel de FCM es diferente de la versión de FCM de destino. Por ejemplo, el dispositivo mencionado anteriormente tiene una versión de FCM de destino 4 y su versión de FCM del kernel es 5 (sufijo de la rama del kernel r).
• La versión de FCM del kernel es mayor o igual que 5 (sufijo de la rama del kernel r).

Las pruebas de VTS exigen que, si se especifica la versión de FCM del kernel, esta sea mayor o igual que la versión de FCM objetivo en el manifiesto del dispositivo.

Ejemplo: Determina la rama del kernel

Si el dispositivo tiene la versión 4 de FCM como objetivo (lanzada en Android 10), pero ejecuta el kernel de la rama 4.19-r, el manifiesto del dispositivo debe especificar lo siguiente:

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

El objeto VINTF verifica la compatibilidad del kernel con los requisitos de la rama del kernel 4.19-r, que se especifica en la versión 5 de FCM. Estos requisitos se compilan a partir de kernel/configs/r/android-4.19 en el árbol de fuentes de Android.

Ejemplo: Determina la rama del kernel para GKI

Si el dispositivo usa la imagen genérica de kernel (GKI) y la cadena de versión del kernel de /proc/version es la siguiente:

5.4.42-android12-0-00544-ged21d463f856

Luego, el objeto VINTF obtiene la versión de Android de la versión del kernel y la usa para determinar la versión de FCM del kernel. En este ejemplo, android12 significa la versión 6 del kernel de FCM (lanzada en Android 12).

Para obtener detalles sobre cómo se analiza la cadena de versión del kernel, consulta Control de versiones de GKI.

Versiones de kernel coincidentes

Una matriz puede incluir varias secciones <kernel>, cada una con un atributo version diferente con el siguiente formato:

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

El objeto VINTF solo considera la sección <kernel> del FCM con la versión de FCM coincidente con el mismo ${ver} y ${major_rev} que el kernel del dispositivo (es decir, version="${ver}.${major_rev}.${matrix_minor_rev}"); se ignoran otras secciones). Además, la revisión secundaria del kernel debe ser un valor de la matriz de compatibilidad (${kernel_minor_rev} >= ${matrix_minor_rev};). Si ninguna sección <kernel> cumple con estos requisitos, no hay coincidencia.

Ejemplo: Selecciona los requisitos para la correlación

Considera el siguiente caso hipotético en el que los FCM en /system/etc/vintf declaran los siguientes requisitos (se omiten las etiquetas de encabezado y pie de página):

<!-- 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 versión de FCM objetivo, la versión de FCM del kernel y la versión del kernel seleccionan en conjunto los requisitos del kernel de los FCM:

Configuraciones del kernel coincidentes

Si la sección <kernel> coincide, el proceso continúa intentando hacer coincidir los elementos config con /proc/config.gz. Para cada elemento de configuración de la matriz de compatibilidad, busca /proc/config.gz para ver si la configuración está presente. Cuando un elemento de configuración se establece en n en la matriz de compatibilidad para la sección <kernel> correspondiente, debe estar ausente de /proc/config.gz. Por último, es posible que un elemento de configuración que no se encuentre en la matriz de compatibilidad esté o no presente en /proc/config.gz.

Ejemplo: Coincidencia de configuraciones del kernel

• <value type="string">bar</value> coincide con "bar". Las comillas se omiten en la matriz de compatibilidad, pero están presentes en /proc/config.gz.
• <value type="int">4096</value> coincide con 4096, 0x1000 o 0X1000.
• <value type="int">0x1000</value> coincide con 4096, 0x1000 o 0X1000.
• <value type="int">0X1000</value> coincide con 4096, 0x1000 o 0X1000.
• <value type="tristate">y</value> coincide con y.
• <value type="tristate">m</value> coincide con m.
• <value type="tristate">n</value> significa que el elemento de configuración NO debe existir en /proc/config.gz.
• <value type="range">1-0x3</value> coincide con 1, 2 o 3, o con el equivalente hexadecimal.

Ejemplo: Coincidencia exitosa del kernel

Una matriz de compatibilidad del framework con la versión 1 de FCM tiene la siguiente información del kernel:

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

Primero se busca la rama del kernel. La rama del kernel se especifica en el manifiesto del dispositivo en manifest.kernel.target-level, que se establece de forma predeterminada en manifest.level si no se especifica la primera:

• Si la rama del kernel en el manifiesto del dispositivo es 1, el proceso continúa con el siguiente paso y verifica la versión del kernel.
• Si la rama del kernel en el manifiesto del dispositivo es 2, no hay coincidencia con la matriz. Los objetos VINTF leen los requisitos del kernel de la matriz en la versión 2 de FCM.

Luego, se verifica la versión del kernel. Si un dispositivo en uname() informa lo siguiente:

• 4.9.84 (no coincide con la matriz, a menos que haya una sección de kernel independiente con <kernel version="4.9.x">, donde x <= 84)
• 4.14.41 (no coincide con la matriz, es más pequeño que version)
• 4.14.42 (coincide con la matriz)
• 4.14.43 (coincide con la matriz)
• 4.1.22 (no coincide con la matriz, a menos que haya una sección de kernel separada con <kernel version="4.1.x">, donde x <= 22)

Después de seleccionar la sección <kernel> adecuada, para cada elemento <config> con un valor distinto de n, la entrada correspondiente debe estar presente en /proc/config.gz; para cada elemento <config> con el valor n, la entrada correspondiente no debe estar presente en /proc/config.gz. El contenido de <value> debe coincidir exactamente con el texto que aparece después del signo igual (incluidas las comillas), hasta el carácter de salto de línea o #, con los espacios en blanco iniciales y finales truncados.

La siguiente configuración del kernel es un ejemplo de una coincidencia exitosa:

# 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 siguiente configuración del kernel es un ejemplo de una coincidencia fallida:

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

Coincidencias de SEPolicy

SEPolicy requiere las siguientes coincidencias:

• <sepolicy-version> define un rango cerrado de versiones secundarias para cada versión principal. La versión de SEPolicy que informa el dispositivo debe estar dentro de uno de estos rangos para ser compatible con el framework. Las reglas de coincidencia son similares a las versiones de HAL: hay coincidencia si la versión de SEPolicy es mayor o igual que la versión mínima del rango. La versión máxima es meramente informativa.
• <kernel-sepolicy-version>, es decir, la versión de la base de datos de políticas, debe ser menor que security_policyvers(), que informa el dispositivo.

Ejemplo: Coincidencia exitosa de SEPolicy

La matriz de compatibilidad del framework indica la siguiente información de SEPolicy:

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

En el dispositivo, haz lo siguiente:

• El valor que devuelve security_policyvers() debe ser mayor o igual que 30. De lo contrario, no habrá coincidencia. Por ejemplo:
  • Si un dispositivo devuelve 29, no hay coincidencia.
  • Si un dispositivo devuelve 31, significa que hay una coincidencia.
• La versión de SEPolicy debe ser de 25.0 a ∞ o de 26.0 a ∞. De lo contrario, no coincide. (El -3 después de 26.0 es meramente informativo).

Coincidencias de versión de AVB

La versión de AVB contiene una versión PRINCIPAL y una versión SECUNDARIA, con el formato MAJOR.MINOR (por ejemplo, 1.0, 2.1). Para obtener más información, consulta Control de versiones y compatibilidad. La versión de AVB tiene las siguientes propiedades del sistema:

• ro.boot.vbmeta.avb_version es la versión de libavb en el bootloader.
• ro.boot.avb_version es la versión libavb en el SO Android (init/fs_mgr).

La propiedad del sistema solo aparece cuando se usó el libavb correspondiente para verificar los metadatos de AVB (y devuelve OK). Está ausente si ocurrió un error de verificación (o no se realizó ninguna verificación).

En una coincidencia de compatibilidad, se comparan los siguientes aspectos:

• sysprop ro.boot.vbmeta.avb_version con avb.vbmeta-version de la matriz de compatibilidad del 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 con avb.vbmeta-version de la matriz de compatibilidad del framework:
  • ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
  • ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR

El bootloader o el SO Android pueden contener dos copias de las bibliotecas de libavb, cada una con una versión PRINCIPAL diferente para los dispositivos de actualización y los dispositivos de lanzamiento. En este caso, se puede compartir la misma imagen del sistema sin firmar, pero las imágenes del sistema firmadas finales son diferentes (con diferentes avb.vbmeta-version):

Figura 1: La versión de AVB coincide (la partición /system es P y todas las demás particiones son O).

Figura 2: La versión de AVB coincide (todas las particiones son P).

Ejemplo: Coincidencia exitosa de la versión de AVB

La matriz de compatibilidad del framework indica la siguiente información sobre AVB:

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

En el dispositivo, haz lo siguiente:

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 

Coincide con la versión de AVB durante la OTA

En el caso de los dispositivos lanzados con Android 9 o versiones anteriores, cuando se actualizan a Android 10, los requisitos de versión de AVB en la matriz de compatibilidad del framework se comparan con la versión actual de AVB en el dispositivo. Si la versión de AVB tiene una actualización de versión principal durante una OTA (por ejemplo, de 0.0 a 1.0), la verificación de VINTF para la compatibilidad en la OTA no refleja la compatibilidad después de la OTA.

Para mitigar el problema, un OEM puede colocar una versión falsa de AVB en el paquete OTA (compatibility.zip) para pasar la verificación. Para ello, sigue estos pasos:

1. Realiza un cherry-pick de los siguientes CL en el árbol de fuentes de Android 9:
   • CL 732261
   • CL 732262
2. Define BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE para el dispositivo. Su valor debe ser igual a la versión de AVB anterior a la OTA, es decir, la versión de AVB del dispositivo cuando se lanzó.
3. Vuelve a compilar el paquete OTA.

Estos cambios colocan automáticamente BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE como compatibility-matrix.avb.vbmeta-version en los siguientes archivos:

• /system/compatibility_matrix.xml (que no se usa en Android 9) en el dispositivo
• system_matrix.xml en compatibility.zip en el paquete de OTA

Estos cambios no afectan otras matrices de compatibilidad del framework, incluida /system/etc/vintf/compatibility_matrix.xml. Después de la OTA, se usa el nuevo valor en /system/etc/vintf/compatibility_matrix.xml para las verificaciones de compatibilidad.

Coincidencias de versiones del VNDK

La matriz de compatibilidad del dispositivo declara la versión de VNDK requerida en compatibility-matrix.vendor-ndk.version. Si la matriz de compatibilidad de dispositivos no tiene una etiqueta <vendor-ndk>, no se imponen requisitos y siempre se considera que hay una coincidencia.

Si la matriz de compatibilidad del dispositivo tiene una etiqueta <vendor-ndk>, se busca una entrada <vendor-ndk> con un <version> coincidente en el conjunto de instantáneas del VNDK del proveedor que proporciona el framework en el manifiesto del framework. Si no existe tal entrada, no hay coincidencia.

Si existe una entrada de este tipo, el conjunto de bibliotecas enumeradas en la matriz de compatibilidad del dispositivo debe ser un subconjunto del conjunto de bibliotecas que se indican en el manifiesto del framework. De lo contrario, la entrada no se considera una coincidencia.

• Como caso especial, si no se enumeran bibliotecas en la matriz de compatibilidad del dispositivo, la entrada siempre se considera una coincidencia, ya que un conjunto vacío es un subconjunto de cualquier conjunto.

Ejemplo: Coincidencia exitosa de la versión del VNDK

Si la matriz de compatibilidad del dispositivo indica el siguiente requisito en el VNDK:

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

En el manifiesto del framework, solo se considera la entrada con la versión 27.

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

El ejemplo A es una coincidencia, ya que la versión 27 del VNDK se encuentra en el manifiesto del framework y {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>

El ejemplo B no es una coincidencia. Aunque la versión 27 del VNDK se encuentra en el manifiesto del framework, libjpeg.so no es compatible con el framework en esa instantánea. Se ignora la versión 26 del VNDK.

Coincidencias de la versión del SDK del sistema

La matriz de compatibilidad de dispositivos declara un conjunto de versiones de SDK del sistema requeridas en compatibility-matrix.system-sdk.version. Solo hay una coincidencia si el conjunto es un subconjunto de las versiones del SDK del sistema proporcionadas, como se declara en manifest.system-sdk.version en el manifiesto del framework.

• Como caso especial, si no se enumeran versiones del SDK del sistema en la matriz de compatibilidad del dispositivo, siempre se considera que hay una coincidencia, ya que un conjunto vacío es un subconjunto de cualquier conjunto.

Ejemplo: Coincidencia exitosa de la versión del SDK del sistema

Si la matriz de compatibilidad del dispositivo indica el siguiente requisito en el SDK del sistema:

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

Luego, el framework debe proporcionar las versiones 26 y 27 del SDK del sistema para que coincidan:

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

El ejemplo A es una coincidencia:

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

El ejemplo B es una coincidencia:

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

El ejemplo C no coincide porque no se proporciona la versión 27 del SDK del sistema.