Ciclo de vida do FCM

Uma versão do framework do Android tem várias Matrizes de compatibilidade de framework (FCM, na sigla em inglês), uma para cada versão atualizável do FCM, que definem o que o framework pode usar e os requisitos da versão do FCM de destino. Como parte do ciclo de vida do FCM, o Android descontinua o uso e remove HALs HIDL, depois 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 do fornecedor também precisam descontinuar e remover as HALs de HIDL usando os mesmos métodos.

Terminologia

Matriz de compatibilidade de framework (FCM)

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

Versões do FCM da plataforma (S_F)

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

Versão do FCM (F)

A versão mais alta entre todos os FCMs em uma versão de framework.

Versão do FCM de destino (V)

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

Versão 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, foi omitido neste documento).

Manifesto do dispositivo

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

HALs do dispositivo

HALs listados (fornecidos) no manifesto do dispositivo e listados (obrigatórios ou opcionais) na matriz de compatibilidade do framework (FCM, na sigla em inglês).

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 do HAL o lado do framework da interface do fornecedor, incluindo system, system_ext e imagens do produto, fornece. As HALs no manifesto do framework são desativadas dinamicamente de acordo com a versão do FCM de destino do dispositivo.

HALs de framework

HALs listados como fornecidos no manifesto do framework e listados como obrigatórios ou opcionais na matriz de compatibilidade do dispositivo (DCM, na sigla em inglês).

Ciclo de vida do FCM na base de código

Neste documento, descrevemos o ciclo de vida do FCM no resumo. Para conferir os manifestos com suporte, consulte hardware/interfaces/compatibility_matrix.<FCM>.xml, onde o FCM pode ser encontrado em system/libvintf/include/vintf/Level.h.

Espera-se que um dispositivo que envie a versão de lançamento do Android correspondente 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 mais recente, que vem com vários requisitos adicionais especificados nas matrizes de compatibilidade. Os níveis aceitos são:

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 os dispositivos atuais. Os dispositivos com níveis mais baixos do FCM podem usar implicitamente HALs listados em níveis mais recentes do FCM, desde que estejam disponíveis no branch.

Desenvolver em uma nova versão do FCM

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

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

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 regras de build correspondentes para instalar essa matriz de compatibilidade no dispositivo.

Apresentação de um novo 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 com as seguintes configurações optional:

• optional="false" se os dispositivos que vêm com V = F precisam ser iniciados com essa HAL,
• optional="true" se os dispositivos enviados com V = F puderem ser iniciados sem essa HAL.

Por exemplo, o Android 8.1 introduziu cas@1.0 como uma HAL opcional. Os dispositivos lançados com o Android 8.1 não precisam implementar essa HAL. Portanto, a entrada abaixo foi adicionada a compatibility_matrix.F.xml (que costumava ser chamada compatibility_matrix.current.xml temporariamente durante o desenvolvimento dessa versão):

<hal format="hidl" optional="true">
    <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)

Durante o desenvolvimento, quando um HAL tem um upgrade de versão secundária de x.z para x.(z+1) na versão atual do FCM F, se essa versão for:

• Obrigatório em dispositivos iniciados com V = F, compatibility_matrix.F.xml precisa declarar x.(z+1) e optional="false".
• Não é necessário em dispositivos iniciados com V = F. compatibility_matrix.F.xml precisa copiar x.y-z e a opcionalidade de compatibility_matrix.<F-1>.xml e mudar a versão para x.w-(z+1) (onde w >= y).

Por exemplo, o Android 8.1 introduziu broadcastradio@1.1 como um upgrade de versão secundária da HAL 1.0. A versão mais antiga, broadcastradio@1.0, é opcional para dispositivos lançados com o Android 8.0, enquanto a versão mais recente, broadcastradio@1.1, é opcional para dispositivos lançados com o Android 8.1. Em compatibility_matrix.1.xml:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

Esta entrada foi copiada para compatibility_matrix.F.xml e modificada da seguinte maneira:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0-1</version>
    <interface>
        <name>IBroadcastRadioFactory</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 de optional:

• optional="false" apenas com a versão x.0, se os dispositivos que vêm com V = F precisarem ser iniciados com x.0.
• optional="false", mas junto com versões principais mais antigas na mesma tag <hal>, se os dispositivos que vêm com V = F precisarem ser lançados com essa HAL, mas puderem ser iniciados com uma versão principal mais antiga.
• optional="true" se os dispositivos que vêm com o V = F não precisarem iniciar a HAL.

Por exemplo, o Android 9 introduz health@2.0 como uma atualização de versão principal da HAL 1.0 e descontinua a HAL 1.0. A versão anterior, health@1.0, é opcional para dispositivos lançados com o Android 8.0 e o Android 8.1. Os dispositivos lançados com o Android 9 precisam fornecer a nova versão 2.0. Por exemplo, suponha que compatibility_matrix.legacy.xml, compatibility_matrix.1.xml e compatibility_matrix.2.xml tenham esta entrada:

<hal format="hidl" optional="true">
    <name>android.hardware.health</name>
    <version>1.0</version>;
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

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

<hal format="hidl" optional="false">
    <name>android.hardware.health</name>
    <version>2.0</version>
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

Restrições:

• Como a HAL 2.0 está em compatibility_matrix.3.xml com optional="false", os dispositivos lançados com o Android 9 precisam ser enviados com a HAL 2.0.`
• Como a HAL 1.0 não está na compatibility_matrix.3.xml, os dispositivos lançados com o Android 9 não podem fornecer a HAL 1.0, já que ela é considerada obsoleta.
• Como a HAL 1.0 está presente em legacy/1/2.xml (versões mais antigas do FCM com as quais o Android 9 pode funcionar) como uma HAL opcional, o framework do Android 9 ainda pode funcionar com a HAL 1.0 (que não é considerada uma versão de HAL removida).

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 uma versão do AOSP e inclui as seguintes etapas:

1. Verifique se compatibility_matrix.F.xml tem o atributo level="F".
2. Verifique se todos os dispositivos são criados e inicializados.
3. Atualização dos testes do VTS para garantir que os dispositivos iniciados com a estrutura mais recente (com base no nível da API de envio) tenham a versão do FCM de destino V >= F.
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 do FCM de destino >= 3.

Além disso, os FCMs do produto e do system_ext também podem listar os requisitos de cada versão do FCM da plataforma. O lançamento de versões do FCM nas partições do produto e do system_ext é feito pelo proprietário dessas imagens, respectivamente. Os números de versão do FCM nas partições do produto e system_ext precisam estar alinhados com os da partição do sistema. Assim como as versões do FCM na partição do sistema, a matriz de compatibilidade na versão F do FCM nas partições do produto e do 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 do HAL é uma decisão do desenvolvedor. Ou seja, para HALs do AOSP, o Google toma a decisão. Isso pode acontecer quando uma versão mais recente do HAL (menor ou principal) é lançada.

Desativar um HAL de dispositivo

Quando um determinado HAL foo@x.y do dispositivo é descontinuado na versão F do FCM, isso significa que qualquer dispositivo iniciado com a versão de destino do FCM V = F ou mais recente não pode implementar foo na versão x.y ou qualquer versão anterior à x.y. Uma versão descontinuada do HAL ainda tem suporte do framework para upgrade de dispositivos.

Quando a versão F do FCM for lançada, uma versão foo@x.y do HAL será considerada descontinuada se a versão específica do HAL não for explicitada na versão mais recente do FCM para a versão de destino V = F. Para dispositivos iniciados com 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, health@2.0 é apresentado como um upgrade principal da versão 1.0 da HAL. 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. Por isso, o uso de health@1.0 é considerado descontinuado.

Suspensão do uso de uma HAL de framework

Quando o uso de uma determinada HAL de framework foo@x.y é suspenso na versão F do FCM, isso significa que os dispositivos iniciados com a versão V = F ou mais recente do FCM não podem esperar que o framework forneça foo na versão x.y ou em qualquer versão anterior a x.y. Uma versão descontinuada do HAL ainda é fornecida pelo framework para atualização de dispositivos.

Quando a versão F do FCM for lançada, a versão foo@x.y da HAL será considerada obsoleta se o manifesto do framework especificar max-level="F - 1" para foo@x.y. Para dispositivos iniciados com V = F, o framework não fornece o HAL foo@x.y. A matriz de compatibilidade do dispositivo 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 do FCM de destino V ficam abaixo de um determinado limite, a versão do FCM de destino é removida do conjunto S_F da próxima versão do framework. Para isso, siga estas etapas:

1. A remoção de compatibility_matrix.V.xml das regras de build para que ele não seja instalado na imagem do sistema e a exclusão de qualquer código que tenha implementado ou dependido dos recursos removidos.

2. Remoção das HALs de framework com max-level menor ou igual a V do manifesto do framework e exclusão de qualquer código que implemente as HALs de framework removidas.

Os dispositivos com uma versão do FCM de destino fora do S_F para uma determinada versão do framework não podem ser atualizados para essa versão.

Status da versão do HAL

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

Inéditos

Para HALs de dispositivo, se uma versão de 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 do HAL que estão apenas na 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.
• A HAL teleportation@1.0 não está em nenhuma matriz de compatibilidade lançada e também é considerada uma HAL não lançada.

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çado e atual

Para HALs de dispositivo, se uma versão da 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 é congelada e publicada no AOSP, a HAL health@2.0 é considerada uma versão HAL lançada e atual.

Se uma versão do 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 descontinuada). Por exemplo, as versões do HAL atuais (como nfc@1.0 introduzidas em compatibility_matrix.legacy.xml) que continuam existindo em compatibility_matrix.3.xml também são consideradas versões do HAL lançadas e atuais.

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

Lançada, mas descontinuada

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

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

Exemplos:

• A 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 um upgrade 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 foi descontinuado no Android 9.

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

Vídeo removido

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

• Ele foi lançado anteriormente.
• Ele não está em nenhuma matriz de compatibilidade pública e congelada com suporte do framework.

Matrizes de compatibilidade que são públicas, congeladas, mas não têm suporte do framework são mantidas na base de código para definir o conjunto de versões de HAL removidas. Assim, os testes VTS podem ser criados para garantir que as HALs removidas não estejam em novos dispositivos.

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

• Ele já foi lançado.
• Ele não está em nenhum manifesto de framework da ramificação lançada mais recentemente.

FCMs legados

A versão legada do FCM é um valor especial para todos os dispositivos que não são do tipo 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 que não seja do 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 dos FCMs para outras versões do FCM de destino (removidas depois que o número de dispositivos ativos anteriores à versão 8.0 cai abaixo de um determinado limite).

Versões do FCM lançadas

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.