A partir de 27 de março de 2025, recomendamos usar android-latest-release em vez de aosp-main para criar e contribuir com o AOSP. Para mais informações, consulte Mudanças no AOSP.

Esta página foi traduzida pela API Cloud Translation.

Ciclo de vida do FCM

Uma versão do framework Android tem várias matrizes de compatibilidade de framework (FCMs), uma para cada versão de destino da FCM atualizável, que definem o que o framework pode usar e os requisitos da versão de destino da 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.

Terminologia

Matriz de compatibilidade de framework (FCM): Um arquivo XML que especifica os requisitos de framework em implementações de fornecedores em conformidade. A matriz de compatibilidade é versionada, 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 todos os FCMs em uma versão de framework.
Versão do FCM desejada (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 do 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 do dispositivo: 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 do 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 onde 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 11 geralmente tem o nível 5 do FCM, mas implementa o nível 6 ou superior do FCM, que vem com vários requisitos adicionais especificados nas matrizes de compatibilidade. Os níveis compatíveis com o Android 15 são:

FCM	Versão do Android
5	Android 11/R
6	Android 12/S
7	Android 13/T
8	Android 14/U
202404	Android 15/V

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

Quando o Android descontinua um nível do FCM, ele ainda é compatível com dispositivos atuais. Os dispositivos que segmentam níveis mais baixos do FCM têm permissão implícita para usar HALs listados em níveis mais recentes 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:

Copie o compatibility_matrix.<F-1>.xml mais recente para compatibility_matrix.F.xml.
Atualize o atributo level no arquivo para F.
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 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ária)

As versões AIDL HAL 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 segmentam FCMs mais antigos, enquanto a versão mais recente, foo@3, pode ser usada para dispositivos que segmentam 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 F atual do FCM, 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:

Verifique se o compatibility_matrix.F.xml tem o atributo level="F".
Verifique se todos os dispositivos estão sendo criados e inicializados.
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.
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 de 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 uma determinada HAL foo@x.y do dispositivo é 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 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 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 um determinado HAL de framework 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 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 pelo framework 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 em dispositivos lançados com 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

Quando os dispositivos ativos de uma determinada versão de destino do FCM V caem abaixo de um determinado limiar, a versão de destino do FCM é removida do conjunto S_F da próxima versão do framework. Isso é feito com as duas etapas a seguir:

Remover compatibility_matrix.V.xml das regras de build (para que não seja instalado na imagem do sistema) e excluir qualquer código que tenha implementado ou dependido dos recursos removidos.
Remover HALs de framework com max-level menor ou igual a V do manifesto do framework e excluir qualquer código que implemente os HALs de framework removidos.

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.

Remova a definição da interface HAL do código-fonte. Isso inclui os arquivos *.aidl e o módulo Android.bp aidl_interface.
Se for HIDL, remova o HASH de hardware/interfaces/current.txt.
Se for AIDL, remova o diretório aidl_api com os arquivos AIDL congelados.
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 da 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 recente do FCM.
Ele 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.

Vídeo 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 escritos 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 da ramificação lançada 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 do framework 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 do FCM (removidas quando o número de dispositivos ativos anteriores à versão 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.