Ciclo de vida do FCM

Uma versão do framework Android tem várias matrizes de compatibilidade do framework (FCMs), uma para cada versão de destino do FCM atualizável, que definem o que o framework pode usar e os requisitos da versão de destino do FCM. Como parte do ciclo de vida do FCM, o Android suspende o uso e remove HIDL HALs e modifica os arquivos do FCM para refletir o status da versão da HAL.

Para ativar OTAs somente de framework nos próprios ecossistemas, os parceiros que estendem interfaces de fornecedor também precisam descontinuar e remover HALs HIDL usando os mesmos métodos.

Observação: para mais detalhes sobre HALs de HIDL, consulte Matrizes de compatibilidade, Regras de correspondência, Controle de versões de HAL de HIDL.

Terminologia

Matriz de compatibilidade de framework (FCM)

Um arquivo XML que especifica requisitos de framework em implementações de fornecedores em conformidade. A matriz de compatibilidade tem controle de versões, e uma nova versão é congelada para cada lançamento do framework. Cada lançamento de framework contém vários FCMs.

Versões da plataforma FCM (S_F)

O conjunto de todas as versões do FCM em um lançamento de framework. O framework pode funcionar com qualquer implementação de fornecedor que satisfaça uma dessas FCMs.

Versão do FCM (F)

A versão mais recente entre todas as FCMs em uma versão de framework.

Versão de destino do FCM (V)

A versão do FCM segmentada (do S_F), declarada explicitamente no manifesto do dispositivo, que uma implementação do fornecedor atende. Uma implementação do fornecedor precisa ser gerada com base em um FCM publicado, embora possa declarar versões mais recentes da HAL no manifesto do dispositivo.

Versão da HAL

Uma versão da HAL tem o formato foo@x.y, em que foo é o nome da HAL e x.y é a versão específica. Por exemplo, nfc@1.0, keymaster@3.0. O prefixo raiz, por exemplo, android.hardware, é omitido em todo este documento.

Manifesto do dispositivo

Arquivos XML que especificam quais versões de HAL o lado do dispositivo da interface do fornecedor, incluindo as imagens do fornecedor e do ODM, oferece. O conteúdo de um manifesto de dispositivo é limitado pela versão de destino do FCM do dispositivo, mas pode listar HALs que são estritamente mais recentes em relação ao FC correspondente a V.

HALs de dispositivos

HALs listadas (fornecidas) no manifesto do dispositivo e na matriz de compatibilidade de framework (FCM).

Matriz de compatibilidade de dispositivos (DCM)

Um arquivo XML que especifica os requisitos do fornecedor em implementações de framework em conformidade. Cada dispositivo contém um DCM.

Manifesto do framework

Um arquivo XML que especifica quais versões da HAL o lado do framework da interface do fornecedor, incluindo imagens do sistema, system_ext e produto, oferece. As HALs no manifesto do framework são desativadas dinamicamente de acordo com a versão do FCM de destino do dispositivo.

HALs do framework

HALs listadas como fornecidas no manifesto do framework e na matriz de compatibilidade de dispositivos (DCM).

Ciclo de vida do FCM na base de código

Este documento descreve o ciclo de vida do FCM de forma abstrata. Para conferir os manifestos compatíveis, consulte hardware/interfaces/compatibility_matrices/compatibility_matrix.<FCM>.xml em que o FCM pode ser encontrado em system/libvintf/include/vintf/Level.h.

Espera-se que um dispositivo com a versão correspondente do Android tenha um valor do FCM maior ou igual ao nível equivalente. Por exemplo, um dispositivo enviado com o Android 12 geralmente tem o nível 6 do FCM, mas pode implementar o nível 7 ou superior do FCM, o que muda o comportamento do Android e força o uso de APIs de fornecedores mais recentes, conforme especificado nas matrizes de compatibilidade. Os níveis compatíveis com o Android 16 são:

FCM	Versão do Android
6	Android 12/S
7	Android 13/T
8	Android 14/U
202404	Android 15/V
202504	Android 16/B

O nível do FCM é igual ou mais recente que o nível da API do fornecedor.

Quando o Project Treble foi anunciado, as imagens do sistema Android foram criadas para serem compatíveis com as três versões anteriores de implementações de fornecedores (quatro no total). Para oferecer suporte a vidas úteis mais longas dos dispositivos, esse período aumentou para suportar a versão atual e as seis anteriores do FCM (sete no total) para 202404 e versões mais recentes.

Quando o Android descontinua um nível do FCM, ele ainda é compatível com dispositivos atuais. Dispositivos que segmentam níveis mais baixos do FCM podem usar implicitamente HALs listados em níveis mais altos do FCM, desde que estejam disponíveis na ramificação.

Desenvolver em uma nova versão do FCM

O Android incrementa a versão do FCM para cada lançamento de framework (como Android 8 e 8.1). Durante o desenvolvimento, o novo compatibility_matrix.F.xml é criado, e o compatibility_matrix.f.xml atual (em que f < F) não é mais alterado.

Para começar a desenvolver em uma nova versão do FCM F:

1. Copie o compatibility_matrix.<F-1>.xml mais recente para compatibility_matrix.F.xml.
2. Atualize o atributo level no arquivo para F.
3. Adicione as regras de build correspondentes para instalar essa matriz de compatibilidade no dispositivo.

Introduzir uma nova HAL

Durante o desenvolvimento, ao introduzir uma nova HAL (Wi-Fi, NFC etc.) no Android na versão atual do FCM F, adicione a HAL a compatibility_matrix.F.xml.

Por exemplo, o Android 8.1 introduziu o cas@1.0. Os dispositivos lançados com o Android 8.1 podem implementar essa HAL. Por isso, a seguinte entrada foi adicionada a compatibility_matrix.F.xml (que era chamada de compatibility_matrix.current.xml temporariamente durante o desenvolvimento dessa versão):

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

Fazer upgrade de uma HAL (secundário)

As versões da HAL AIDL contam como versões secundárias da HAL. As versões de interface HIDL têm versões major.minor, como 1.2.

Durante o desenvolvimento, quando uma HAL do AIDL tem um upgrade de versão de 2 para 3 na versão atual do FCM F, a nova versão é adicionada à entrada da HAL em compatibility_matrix.F.xml. O campo de versão de uma entrada HAL aceita intervalos como 2-3.

Por exemplo, o FCM do Android F introduziu foo@3 como uma atualização de versão secundária da HAL. A versão mais antiga, foo@2, é usada para dispositivos que têm como destino FCMs mais antigos, enquanto a versão mais recente, foo@3, pode ser usada para dispositivos que têm como destino o FCM do Android F. A entrada nos FCMs mais antigos antes da versão 2 é assim:

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

Esta entrada foi copiada para compatibility_matrix.F.xml e modificada para oferecer suporte à versão 3 da seguinte maneira:

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

Fazer upgrade de uma HAL (principal)

Durante o desenvolvimento, quando uma HAL tem um upgrade de versão principal na versão atual do FCM F, a nova versão principal x.0 é adicionada a compatibility_matrix.F.xml com as seguintes configurações:

• Somente a versão x.0, se os dispositivos enviados com V = F precisarem ser iniciados com x.0.
• Com versões principais mais antigas na mesma tag <hal>, se os dispositivos enviados com V = F puderem ser iniciados com uma versão principal mais antiga.

Por exemplo, a versão F do FCM apresenta o foo@2.0 como uma atualização de versão principal da HAL 1.0 e descontinua a HAL 1.0. A versão mais antiga, foo@1.0, é usada para dispositivos destinados a versões anteriores do FCM. Os dispositivos que usam a versão F do FCM precisam fornecer a nova versão 2.0 se disponibilizarem a HAL. Neste exemplo, as versões anteriores do FCM contêm esta entrada:

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

Copie essa entrada para compatibility_matrix.F.xml e modifique da seguinte forma:

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

Restrições:

• Como o HAL 1.0 não está em compatibility_matrix.F.xml, dispositivos que têm como destino a versão F do FCM não podem fornecer o HAL 1.0, já que ele é considerado obsoleto.
• Como o HAL 1.0 está presente em versões mais antigas do FCM, o framework ainda pode funcionar com o HAL 1.0, sendo compatível com versões anteriores de dispositivos que têm como destino versões mais antigas do FCM.

Novas versões do FCM

O processo de lançamento de uma versão do FCM na partição do sistema é feito exclusivamente pelo Google como parte de um lançamento do AOSP e inclui as seguintes etapas:

1. Verifique se o compatibility_matrix.F.xml tem o atributo level="F".
2. Verifique se todos os dispositivos estão sendo criados e inicializados.
3. Atualize os testes do VTS para garantir que os dispositivos lançados com a estrutura mais recente (com base no nível da API de envio) tenham a versão V >= F do FCM de destino.
4. Publicar o arquivo no AOSP.

Por exemplo, os testes VTS garantem que os dispositivos lançados com o Android 9 tenham a versão de destino do FCM >= 3.

Além disso, os FCMs do produto e do system_ext também podem listar requisitos para cada versão do FCM da plataforma. O lançamento das versões do FCM nas partições product e system_ext é feito pelo proprietário dessas imagens, respectivamente. Os números das versões do FCM nas partições product e system_ext precisam estar alinhados com os da partição system. Semelhante às versões do FCM na partição do sistema, a matriz de compatibilidade na versão F do FCM nas partições product e system_ext reflete os requisitos em um dispositivo com a versão F do FCM de destino.

Descontinuação da versão da HAL

A descontinuação de uma versão de HAL é uma decisão do desenvolvedor. Por exemplo, para HALs do AOSP, o Google toma a decisão. Isso pode acontecer quando uma versão mais recente da HAL (secundária ou principal) é lançada.

Descontinuar uma HAL de dispositivo

Quando um determinado HAL de dispositivo foo@x.y é descontinuado na versão F do FCM, isso significa que qualquer dispositivo lançado com a versão V = F ou mais recente do FCM de destino não pode implementar foo na versão x.y ou em qualquer versão anterior a x.y. Uma versão HAL descontinuada ainda é compatível com o framework para fazer upgrade de dispositivos.

Quando a versão F do FCM for lançada, a versão foo@x.y do HAL será considerada descontinuada se não for explicitamente declarada no FCM mais recente para a versão V = F do FCM de destino. Para dispositivos lançados com o V = F, uma das seguintes condições é verdadeira:

• O framework exige uma versão mais recente (principal ou secundária).
• O framework não exige mais a HAL.

Por exemplo, no Android 9, o health@2.0 foi introduzido como uma atualização importante da versão da HAL 1.0. health@1.0 foi removido de compatibility_matrix.3.xml, mas está presente em compatibility_matrix.legacy.xml, compatibility_matrix.1.xml e compatibility_matrix.2.xml. Portanto, health@1.0 é considerado suspenso.

Descontinuar uma HAL de framework

Quando uma determinada HAL de framework foo@x.y é descontinuada na versão F do FCM, isso significa que qualquer dispositivo lançado com a versão V = F ou mais recente do FCM de destino não deve esperar que o framework forneça foo na versão x.y ou em qualquer versão mais antiga que x.y. Uma versão HAL descontinuada ainda é fornecida pela estrutura para atualizar dispositivos.

Quando a versão F do FCM for lançada, uma versão foo@x.y da HAL será considerada descontinuada se o manifesto do framework especificar max-level="F - 1" para foo@x.y. Para dispositivos lançados com o V = F, o framework não fornece a HAL foo@x.y. A matriz de compatibilidade de dispositivos lançados com o V = F não pode listar HALs de framework com max-level < V.

Por exemplo, no Android 12, schedulerservice@1.0 foi descontinuado. O atributo max-level é definido como 5, a versão do FCM introduzida no Android 11. Consulte Manifesto do framework do Android 12.

Remoção do suporte para versões de destino do FCM

Usamos um processo baseado em programação para determinar a remoção da versão de destino do FCM, manter a compatibilidade por durações necessárias e atender aos requisitos de parceiros para dispositivos mais duráveis.

Quando removemos uma versão de destino do FCM do conjunto S_F da próxima versão do framework, realizamos as duas etapas a seguir:

1. Remova compatibility_matrix.V.xml das regras de build (para que não seja instalado na imagem do sistema) e exclua qualquer código que tenha implementado ou dependido dos recursos removidos.

2. Remova as HALs de framework com max-level menor ou igual a V do manifesto do framework e exclua qualquer código que implemente as HALs de framework removidas.

Descontinuação gradual para configurações de versão

A estratégia de ramificação do Trunk Stable, em que os lançamentos trimestrais da plataforma (QPRs) são feitos diretamente de git_main em vez de ramificações separadas de desenvolvimento de lançamento, exige um processo de descontinuação gradual. Uma versão do FCM pode ser removida para sinal antecipado em builds trunk_staging, mas continuar com suporte na ramificação de lançamento para acomodar dispositivos que recebem QPRs ao longo do ano.

Normalmente, um lançamento de framework oferece suporte a seis FCMs: uma versão atual, quatro versões anteriores e uma versão adicional para oferecer suporte a QPRs. Esse número pode aumentar se versões específicas do FCM (como o 202404 do Android 15) tiverem suporte estendido para a longevidade do dispositivo.

Dispositivos com uma versão de destino do FCM fora do S_F para uma determinada versão de framework não podem fazer upgrade para essa versão.

Remoção de HALs totalmente descontinuados

Quando uma versão do FCM é removida, algumas interfaces HAL ou versões de interfaces HAL não estão mais presentes em nenhum FCM. Isso significa que o Android não oferece mais suporte a eles, nem mesmo para atualizar dispositivos.

Depois que uma HAL não é mais compatível, os desenvolvedores removem as referências a essa interface HAL do Android, incluindo no código do cliente no framework, na implementação padrão e nos casos de teste do VTS.

Se não houver HALs compatíveis herdando do HAL que está sendo removido, a definição do HAL poderá ser removida com algumas etapas extras.

Observação: é comum que as interfaces HIDL HAL herdem de versões anteriores da interface. As interfaces AIDL HAL são implicitamente semelhantes.

1. Remova a definição da interface HAL do código-fonte. Isso inclui os arquivos *.aidl e o módulo Android.bp aidl_interface.
2. Se for HIDL, remova o HASH de hardware/interfaces/current.txt.
3. Se for AIDL, remova o diretório aidl_api com os arquivos AIDL congelados.
4. Remova a interface de hardware/interfaces/compatibility_matrices/exclude/fcm_exclude.cpp.

Status da versão da HAL

As seções a seguir descrevem (em ordem cronológica) os possíveis estados de uma versão do HAL.

Inéditos

Para HALs de dispositivos, se uma versão do HAL não estiver em nenhuma das matrizes de compatibilidade públicas e congeladas, ela será considerada não lançada e possivelmente em desenvolvimento. Isso inclui versões de HAL que estão apenas no compatibility_matrix.F.xml. Exemplos:

• Durante o desenvolvimento do Android 9, a HAL health@2.0 foi considerada uma HAL não lançada e estava presente apenas em compatibility_matrix.3.xml.
• O HAL teleportation@1.0 não está em nenhuma matriz de compatibilidade lançada e também é considerado um HAL não lançado.

Para HALs de framework, se uma versão do HAL estiver apenas no manifesto do framework de uma ramificação de desenvolvimento não relacionada, ela será considerada não lançada.

Lançada e atual

Para HALs de dispositivos, se uma versão de HAL estiver em qualquer matriz de compatibilidade pública e congelada, ela será lançada. Por exemplo, depois que a versão 3 do FCM for congelada e publicada no AOSP, a HAL health@2.0 será considerada uma versão HAL lançada e atual.

Se uma versão de HAL estiver em uma matriz de compatibilidade pública e congelada que tenha a versão mais recente do FCM, a versão do HAL será atual (ou seja, não será descontinuada). Por exemplo, as versões de HAL atuais (como nfc@1.0, introduzido no compatibility_matrix.legacy.xml) que continuam existindo em compatibility_matrix.3.xml também são consideradas versões de HAL lançadas e atuais.

Para HALs de framework, se uma versão estiver no manifesto do framework da ramificação lançada mais recente sem o atributo max-level ou (incomum) um max-level igual ou maior que a versão do FCM lançada nessa ramificação, ela será considerada uma versão lançada e atual do HAL. Por exemplo, a HAL displayservice é lançada e está atualizada no Android 12, conforme especificado no manifesto do framework do Android 12.

Lançado, mas com uso suspenso

Para HALs de dispositivos, uma versão do HAL será descontinuada se e somente se todas as condições a seguir forem atendidas:

• Ele é lançado.
• Ela não está na matriz de compatibilidade pública e congelada que tem a versão mais alta do FCM.
• Ela está em uma matriz de compatibilidade pública e congelada que o framework ainda suporta.

Exemplos:

• O HAL health@1.0 está em compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, e compatibility_matrix.2.xml, mas não em compatibility_matrix.3.xml. Por isso, ele é considerado descontinuado no Android 9.
• A HAL de energia tem uma atualização de versão secundária no Android 9, mas power@1.0 ainda está em compatibility_matrix.3.xml.
• power@1.0 compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, e compatibility_matrix.2.xml.
• compatibility_matrix.3.xml tem power@1.0-1.

Portanto, power@1.0 é atual, mas NÃO está descontinuado no Android 9.

Para HALs de framework, se uma versão de HAL estiver no manifesto de framework da ramificação lançada mais recente com um atributo max-level menor que a versão do FCM lançada nessa ramificação, ela será considerada uma versão de HAL lançada, mas descontinuada. Por exemplo, a HAL schedulerservice é lançada, mas descontinuada no Android 12, conforme especificado no manifesto do framework do Android 12.

Removido

Para HALs de dispositivo, uma versão do HAL será removida se e somente se as seguintes condições forem verdadeiras:

• Ele foi lançado anteriormente.
• Ela não está em nenhuma matriz de compatibilidade pública e congelada que a estrutura suporta.

As matrizes de compatibilidade públicas, congeladas, mas não compatíveis com o framework são mantidas na base de código para definir o conjunto de versões de HAL removidas. Assim, os testes do VTS podem ser gravados para garantir que as HALs removidas não estejam em novos dispositivos.

Para HALs de framework, uma versão será removida somente se as seguintes condições forem atendidas:

• Ele foi lançado anteriormente.
• Ele não está em nenhum manifesto de framework do branch lançado mais recentemente.

FCMs legados

A versão legada do Target FCM é um valor especial para todos os dispositivos não Treble. O FCM legado, compatibility_matrix.legacy.xml, lista os requisitos da estrutura em dispositivos legados (ou seja, dispositivos lançados antes do Android 8.0).

Se esse arquivo existir para um FCM com a versão F, qualquer dispositivo não Treble poderá ser atualizado para F, desde que o manifesto do dispositivo seja compatível com esse arquivo. A remoção segue o mesmo procedimento das FCMs para outras versões de destino da FCM (removidas quando o número de dispositivos ativos pré-8.0 cai abaixo de um determinado limiar).

Versões lançadas do FCM

A lista de versões lançadas do FCM pode ser encontrada em hardware/interfaces/compatibility_matrices.

Para encontrar a versão do FCM lançada com uma versão específica do Android, consulte Level.h.