Ciclo de vida de FCM

Una versión del framework de Android tiene varias matrices de compatibilidad del framework (FCM), una para cada versión de FCM de destino actualizable, que definen lo que puede usar el framework y los requisitos de la versión de FCM de destino. Como parte del ciclo de vida de FCM , Android da de baja y quita las HAL de HIDL y, luego, modifica los archivos FCM para reflejar el estado de la versión de HAL.

Para habilitar las OTA solo del framework en sus propios ecosistemas, los socios que extienden las interfaces del proveedor también deben dar de baja y quitar las HAL de HIDL con los mismos métodos.

Terminología

Matriz de compatibilidad del framework (FCM)

Es un archivo en formato XML que especifica los requisitos del framework en las implementaciones de proveedores conformes. La matriz de compatibilidad tiene versiones, y se congela una versión nueva para cada versión del framework. Cada versión del framework contiene varias FCM.

Versiones de FCM de la plataforma (S_F)

Es el conjunto de todas las versiones de FCM en una versión del framework. El framework puede funcionar con cualquier implementación de proveedor que satisfaga una de estas FCM.

Versión de FCM (F)

Es la versión más alta entre todas las FCM en una versión del framework.

Versión de FCM de destino (V)

Es la versión de FCM de destino (de S_F), declarada explícitamente en el manifiesto del dispositivo, que satisface una implementación de proveedor. Se debe generar una implementación de proveedor en función de una FCM publicada, aunque puede declarar versiones de HAL más recientes en su manifiesto del dispositivo.

Versión de HAL

Una versión de HAL tiene el formato foo@x.y, en el que foo es el nombre de la HAL y x.y es la versión específica; p.ej., nfc@1.0, keymaster@3.0 (el prefijo raíz, p.ej., android.hardware, se omite en todo este documento.)

Manifiesto del dispositivo

Son archivos XML que especifican qué versiones de HAL proporciona el lado del dispositivo de la interfaz del proveedor, incluidas las imágenes del proveedor y del ODM. El contenido de un manifiesto del dispositivo está restringido por la versión de FCM de destino del dispositivo, pero puede enumerar las HAL que son estrictamente más nuevas en relación con la FC correspondiente a V.

HAL del dispositivo

Son las HAL que se enumeran (proporcionan) en el manifiesto del dispositivo y en la matriz de compatibilidad del framework (FCM).

Matriz de compatibilidad del dispositivo (DCM)

Es un archivo en formato XML que especifica los requisitos del proveedor en las implementaciones de framework conformes. Cada dispositivo contiene una DCM.

Manifiesto del framework

Es un archivo en formato XML que especifica qué versiones de HAL proporciona el lado del framework de la interfaz del proveedor, incluidas las imágenes del sistema, system_ext y del producto. Las HAL en el manifiesto del framework se inhabilitan de forma dinámica según la versión de FCM de destino del dispositivo.

HAL del framework

Son las HAL que se enumeran como proporcionadas en el manifiesto del framework y en la matriz de compatibilidad del dispositivo (DCM).

Ciclo de vida de FCM en la base de código

En este documento, se describe el ciclo de vida de FCM en abstracto. Para ver los manifiestos compatibles, consulta hardware/interfaces/compatibility_matrices/compatibility_matrix.<FCM>.xml donde se puede encontrar FCM en system/libvintf/include/vintf/Level.h.

Se espera que un dispositivo que envíe la versión correspondiente de Android tenga un valor de FCM mayor o igual que el nivel equivalente. Por ejemplo, un dispositivo que se envía con Android 12 generalmente tendría el nivel 6 de FCM, pero podría implementar el nivel 7 de FCM o uno superior, lo que cambia el comportamiento de Android y obliga a usar las APIs de proveedor más recientes, como se especifica en las matrices de compatibilidad. Los niveles compatibles para Android 16 son los siguientes:

El nivel de FCM es igual o más reciente que el nivel de API del proveedor.

Cuando se anunció Project Treble, las imágenes del sistema Android se compilaron para que fueran retrocompatibles con las tres versiones anteriores de las implementaciones de proveedores (cuatro en total). Para admitir vidas útiles más largas de los dispositivos, este período aumentó para admitir las versiones de FCM actuales y las seis anteriores (siete en total) para 202404 y versiones posteriores.

Cuando Android da de baja un nivel de FCM, este sigue siendo compatible con los dispositivos existentes. Los dispositivos que segmentan niveles de FCM más bajos pueden usar implícitamente las HAL que se enumeran en niveles de FCM más altos, siempre que estén disponibles en la rama.

Desarrolla en una nueva versión de FCM

Android incrementa la versión de FCM para cada versión del framework (como Android 8 y 8.1). Durante el desarrollo, se crea el nuevo compatibility_matrix.F.xml y ya no se cambia el compatibility_matrix.f.xml existente (donde f < F).

Para comenzar a desarrollar en una nueva versión de FCM F, haz lo siguiente:

1. Copia el compatibility_matrix.<F-1>.xml más reciente en compatibility_matrix.F.xml.
2. Actualiza el atributo level en el archivo a F.
3. Agrega las reglas de compilación correspondientes para instalar esta matriz de compatibilidad en el dispositivo.

Presenta una nueva HAL

Durante el desarrollo, cuando presentes una nueva HAL (Wi-Fi, NFC, etc.) en Android en la versión actual de FCM F, agrega la HAL a compatibility_matrix.F.xml.

Por ejemplo, Android 8.1 presentó cas@1.0. Los dispositivos que se lanzan con Android 8.1 pueden implementar esta HAL, por lo que se agregó la siguiente entrada a compatibility_matrix.F.xml (que se denominaba compatibility_matrix.current.xml temporalmente durante el desarrollo de esa versión):

<hal format="hidl">
    <name>android.hardware.cas</name>
    <version>1.0</version>
    <interface>
        <name>IMediaCasService</name>
        <instance>default</instance>
    </interface>
</hal>

Actualiza una HAL (secundaria)

Las versiones de HAL de AIDL cuentan como versiones de HAL secundarias. Las versiones de la interfaz HIDL tienen major.minor versiones como 1.2.

Durante el desarrollo, cuando una HAL de AIDL tiene una actualización de versión de 2 a 3 en la versión actual de FCM F, la versión nueva se agrega a la entrada de HAL en compatibility_matrix.F.xml. El campo de versión de una entrada de HAL acepta rangos como 2-3.

Por ejemplo, la FCM F de Android presentó foo@3 como una actualización de versión secundaria de la HAL. La versión anterior, foo@2, se usa para dispositivos que segmentan FCM anteriores, mientras que la versión más reciente, foo@3, se puede usar para dispositivos que segmentan la FCM F de Android. La entrada en las FCM anteriores a la versión 2 tiene el siguiente aspecto:

<hal format="aidl">
    <name>foo</name>
    <version>2</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Esta entrada se copió a compatibility_matrix.F.xml y se modificó para admitir la versión 3 de la siguiente manera:

<hal format="aidl">
    <name>foo</name>
    <version>2-3</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Actualiza una HAL (principal)

Durante el desarrollo, cuando una HAL tiene una actualización de versión principal en la versión actual de FCM Versión F, la nueva versión principal x.0 se agrega a compatibility_matrix.F.xml con la siguiente configuración:

• Solo la versión x.0, si los dispositivos que se envían con V = F deben lanzarse con x.0.
• Con versiones principales anteriores en la misma <hal> etiqueta, si los dispositivos que se envían con V = F pueden lanzarse con una versión principal anterior.

Por ejemplo, la versión F de FCM presenta foo@2.0 como una actualización de versión principal de la HAL 1.0 y da de baja la HAL 1.0. La versión anterior, foo@1.0, se usa para dispositivos que segmentan versiones anteriores de FCM. Los dispositivos que segmentan la versión F de FCM deben proporcionar la nueva versión 2.0 si proporcionan la HAL. En este ejemplo, las versiones anteriores de FCM contienen esta entrada:

<hal format="hidl">
    <name>foo</name>
    <version>1.0</version>;
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Copia esta entrada en compatibility_matrix.F.xml y modifícala de la siguiente manera:

<hal format="hidl">
    <name>foo</name>
    <version>2.0</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Restricciones:

• Debido a que la HAL 1.0 no está en compatibility_matrix.F.xml, los dispositivos que segmentan la versión F de FCM no deben proporcionar la HAL 1.0 (ya que esta HAL se considera obsoleta).
• Debido a que la HAL 1.0 está presente en versiones anteriores de FCM, el framework aún puede funcionar con la HAL 1.0, por lo que es retrocompatible con dispositivos antiguos que segmentan las versiones anteriores de FCM.

Nuevas versiones de FCM

El proceso de lanzamiento de una versión de FCM en la partición del sistema lo realiza únicamente Google como parte de un lanzamiento de AOSP y consta de los siguientes pasos:

1. Asegúrate de que compatibility_matrix.F.xml tenga el atributo level="F".
2. Asegúrate de que todos los dispositivos se compilen y se inicien.
3. Actualiza las pruebas de VTS para asegurarte de que los dispositivos que se lanzan con el framework más reciente (según el nivel de API de envío) tengan la versión de FCM de destino V >= F.
4. Publica el archivo en AOSP.

Por ejemplo, las pruebas de VTS garantizan que los dispositivos que se lanzan con Android 9 tengan la versión de FCM de destino >= 3.

Además, las FCM de product y system_ext también pueden enumerar los requisitos para cada versión de FCM de la plataforma. El propietario de estas imágenes realiza el lanzamiento de las versiones de FCM en las particiones de product y system_ext, respectivamente. Los números de versión de FCM en las particiones de product y system_ext deben alinearse con los de la partición del sistema. Al igual que las versiones de FCM en la partición del sistema, la matriz de compatibilidad en la versión F de FCM en las particiones de product y system_ext refleja los requisitos en un dispositivo con la versión F de FCM de destino.

Baja de la versión de HAL

Dar de baja una versión de HAL es una decisión del desarrollador (es decir, para las HAL de AOSP, Google toma la decisión). Esto podría suceder cuando se lanza una versión de HAL superior (ya sea secundaria o principal).

Da de baja una HAL del dispositivo

Cuando se da de baja una HAL foo@x.y determinada del dispositivo en la versión F de FCM, significa que ningún dispositivo que se lance con la versión V = F de FCM de destino o una posterior debe implementar foo en la versión x.y ni en ninguna versión anterior a x.y. El framework aún admite una versión de HAL dada de baja para actualizar dispositivos.

Cuando se lanza la versión F de FCM, se considera que una versión foo@x.y de HAL está dada de baja si la versión específica de HAL no se indica explícitamente en la FCM más reciente para la versión V = F de FCM de destino. Para los dispositivos que se lanzan con V = F, se cumple una de las siguientes condiciones:

• El framework requiere una versión superior (principal o secundaria).
• El framework ya no requiere la HAL.

Por ejemplo, en Android 9, se presenta health@2.0 como una actualización de versión principal de la HAL 1.0. health@1.0 se quita de compatibility_matrix.3.xml pero está presente en compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, y compatibility_matrix.2.xml. Por lo tanto, health@1.0 se considera obsoleta.

Da de baja una HAL del framework

Cuando se da de baja una HAL foo@x.y determinada del framework en la versión F de FCM, significa que ningún dispositivo que se lance con la versión V = F de FCM de destino o una posterior debe esperar que el framework proporcione foo en la versión x.y ni en ninguna versión anterior a x.y. El framework aún proporciona una versión de HAL dada de baja para actualizar dispositivos.

Cuando se lanza la versión F de FCM, se considera que una versión foo@x.y de HAL está dada de baja si el manifiesto del framework especifica max-level="F - 1" para foo@x.y. Para los dispositivos que se lanzan con V = F, el framework no proporciona la HAL foo@x.y. La matriz de compatibilidad del dispositivo en los dispositivos que se lanzan con V = F no debe enumerar las HAL del framework con max-level < V.

Por ejemplo, en Android 12, schedulerservice@1.0 está dada de baja. Su atributo max-level se establece en 5, la versión de FCM que se presentó en Android 11. Consulta el manifiesto del framework de Android 12.

Eliminación de la compatibilidad con versiones de FCM de destino

Usamos un proceso basado en la programación para determinar la eliminación de la versión de FCM de destino, mantener la compatibilidad durante los períodos requeridos y admitir los requisitos de los socios para dispositivos más duraderos.

Cuando quitamos una versión de FCM de destino del conjunto S_F de la próxima versión del framework, realizamos los siguientes pasos:

1. Quitamos compatibility_matrix.V.xml de las reglas de compilación (para que no se instale en la imagen del sistema) y borramos cualquier código que implementara o dependiera de las capacidades quitadas.

2. Quitamos las HAL del framework con max-level inferior o igual a V del manifiesto del framework y borramos cualquier código que implemente las HAL del framework quitadas.

Baja escalonada para las configuraciones de lanzamiento

La estrategia de ramificación de Trunk Stable, en la que las versiones trimestrales de la plataforma (QPR) se toman directamente de git_main en lugar de ramas de release-dev separadas, requiere un proceso de baja escalonado. Se puede quitar una versión de FCM para obtener una señal temprana en las compilaciones de trunk_staging, mientras que sigue siendo compatible con la rama de lanzamiento para admitir dispositivos que toman QPR durante todo el año.

Por lo general, una versión del framework admite seis FCM: una versión actual, cuatro versiones anteriores y una versión adicional para admitir QPR. Este número puede aumentar si versiones específicas de FCM (como 202404 de Android 15) tienen compatibilidad extendida para la longevidad del dispositivo.

Los dispositivos con una versión de FCM de destino fuera de S_F para una versión determinada del framework no se pueden actualizar a esa versión.

Eliminación de HAL completamente dadas de baja

Cuando se quita una versión de FCM, algunas interfaces de HAL o versiones de interfaces de HAL ya no están presentes en ninguna FCM. Esto significa que Android ya no las admite, ni siquiera para actualizar dispositivos.

Una vez que ya no se admite una HAL, los desarrolladores quitan las referencias a esa interfaz de HAL de Android, incluso en el código del cliente en el framework, la implementación predeterminada y los casos de prueba de VTS.

Si no hay HAL compatibles que hereden de la HAL que se quita, la definición de HAL se puede quitar con algunos pasos adicionales.

1. Quita la definición de la interfaz HAL del código fuente. Esto incluye los archivos *.aidl y el módulo aidl_interface de Android.bp.
2. Si es HIDL, quita el HASH de hardware/interfaces/current.txt.
3. Si es AIDL, quita el directorio aidl_api con los archivos AIDL congelados.
4. Quita la interfaz de hardware/interfaces/compatibility_matrices/exclude/fcm_exclude.cpp.

Estado de la versión de HAL

En las siguientes secciones, se describen (en orden cronológico) los estados posibles de una versión de HAL.

Beta

Para las HAL del dispositivo, si una versión de HAL no está en ninguna de las matrices de compatibilidad públicas y congeladas, se considera que no se lanzó y que posiblemente esté en desarrollo. Esto incluye las versiones de HAL que solo están en compatibility_matrix.F.xml. Ejemplos:

• Durante el desarrollo de Android 9, la HAL health@2.0 se consideró una HAL no lanzada y solo estaba presente en compatibility_matrix.3.xml.
• La HAL teleportation@1.0 no está en ninguna matriz de compatibilidad lanzada y también se considera una HAL no lanzada.

Para las HAL del framework, si una versión de HAL solo está en el manifiesto del framework de una rama de desarrollo no relacionada, se considera que no se lanzó.

Lanzada y actual

Para las HAL del dispositivo, si una versión de HAL está en alguna matriz de compatibilidad pública y congelada, se lanza. Por ejemplo, después de que se congela la versión 3 de FCM y se publica en AOSP, la HAL health@2.0 se considera una versión de HAL lanzada y actual.

Si una versión de HAL está en una matriz de compatibilidad pública y congelada que tiene la versión de FCM más alta, la versión de HAL es actual (es decir, no está dada de baja). Por ejemplo, las versiones de HAL existentes (como nfc@1.0 que se presentó en compatibility_matrix.legacy.xml) que siguen existiendo en compatibility_matrix.3.xml también se consideran versiones de HAL lanzadas y actuales.

Para las HAL del framework, si una versión de HAL está en el manifiesto del framework de la rama lanzada más reciente sin el atributo max-level o (de manera inusual) un max-level igual o superior a la versión de FCM lanzada en esta rama, se considera una versión de HAL lanzada y actual. Por ejemplo, la displayservice HAL se lanza y es actual en Android 12, como se especifica en el manifiesto del framework de Android 12.

Lanzada, pero dada de baja

Para las HAL del dispositivo, una versión de HAL se da de baja si y solo si se cumplen todas las siguientes condiciones:

• Se lanza.
• No está en la matriz de compatibilidad pública y congelada que tiene la versión de FCM más alta.
• Está en una matriz de compatibilidad pública y congelada que el framework aún admite.

Ejemplos:

• La HAL health@1.0 está en compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, y compatibility_matrix.2.xml, pero no en compatibility_matrix.3.xml. Por lo tanto, se considera obsoleta en Android 9.
• La HAL de energía tiene una actualización de versión secundaria en Android 9, pero power@1.0 aún está en compatibility_matrix.3.xml.
• power@1.0 compatibility_matrix.legacy.xml, compatibility_matrix.1.xml y and compatibility_matrix.2.xml.
• compatibility_matrix.3.xml tiene power@1.0-1.

Por lo tanto, power@1.0 es actual, pero NO está dada de baja, en Android 9.

Para las HAL del framework, si una versión de HAL está en el manifiesto del framework de la rama lanzada más reciente con un atributo max-level inferior a la versión de FCM lanzada en esta rama, se considera una versión de HAL lanzada, pero dada de baja. Por ejemplo, la schedulerservice HAL se lanza, pero está dada de baja en Android 12, como se especifica en el manifiesto del framework de Android 12.

Quitada

Para las HAL del dispositivo, una versión de HAL se quita si y solo si se cumplen las siguientes condiciones:

• Se lanzó anteriormente.
• No está en ninguna matriz de compatibilidad pública y congelada que admita el framework.

Las matrices de compatibilidad que son públicas, congeladas, pero no admitidas por el framework se conservan en la base de código para definir el conjunto de versiones de HAL quitadas, de modo que se puedan escribir pruebas de VTS para garantizar que las HAL quitadas no estén en dispositivos nuevos.

Para las HAL del framework, una versión de HAL se quita si y solo si se cumplen las siguientes condiciones:

• Se lanzó anteriormente.
• No está en ningún manifiesto del framework de la rama lanzada más reciente.

FCM heredadas

La versión de FCM de destino heredada es un valor especial para todos los dispositivos que no son Treble. La FCM heredada, compatibility_matrix.legacy.xml, enumera los requisitos del framework en dispositivos heredados (es decir, dispositivos lanzados antes de Android 8.0).

Si este archivo existe para una FCM con la versión F, cualquier dispositivo que no sea Treble se puede actualizar a F, siempre que su manifiesto del dispositivo sea compatible con este archivo. Su eliminación sigue el mismo procedimiento que las FCM para otras versiones de FCM de destino (se quitan después de que la cantidad de dispositivos activos anteriores a la versión 8.0 cae por debajo de un umbral determinado).

Versiones de FCM lanzadas

La lista de versiones de FCM lanzadas se puede encontrar en hardware/interfaces/compatibility_matrices.

Para encontrar la versión de FCM lanzada con una versión específica de Android, consulta Level.h.