Ciclo de vida do FCM

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

Para habilitar OTAs somente de estrutura em seus próprios ecossistemas, os parceiros que estendem as interfaces do fornecedor também devem descontinuar e remover HIDL HALs usando os mesmos métodos.

Terminologia

Matriz de Compatibilidade da Estrutura (FCM) Um arquivo XML que especifica os requisitos de estrutura 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ários FCMs.
Versões do FCM da Plataforma (S F ) O conjunto de todas as versões do FCM em uma versão do framework. A estrutura pode funcionar com qualquer implementação de fornecedor que satisfaça um desses FCMs.
Versão FCM (F) A versão mais alta entre todos os FCMs em uma versão de estrutura.
Versão do FCM de destino (V) A versão de destino do FCM (de S F ), declarada explicitamente no manifesto do dispositivo, que uma implementação de fornecedor satisfaz. Uma implementação de fornecedor deve ser gerada em um FCM publicado, embora possa declarar versões HAL mais recentes em seu Manifesto de dispositivo.
Versão HAL Uma versão HAL tem o formato foo@xy , onde foo é o nome HAL e xy é 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 o fornecedor e as imagens ODM, fornece. O conteúdo de um manifesto de dispositivo é restrito pela versão Target FCM do dispositivo, mas pode listar HALs estritamente mais recentes em relação ao FCM correspondente a V.
HALs do dispositivo HALs listadas (fornecidas) no manifesto do dispositivo e listadas (necessárias ou opcionais) na matriz de compatibilidade da estrutura (FCM).
Matriz de compatibilidade de dispositivos (DCM) Um arquivo XML que especifica os requisitos do fornecedor em implementações de estrutura em conformidade. Cada dispositivo contém um DCM.
Manifesto da Estrutura Um arquivo XML que especifica quais versões HAL são fornecidas pelo lado da estrutura da interface do fornecedor, incluindo sistema, system_ext e imagens do produto. As HALs no manifesto da estrutura são desabilitadas dinamicamente de acordo com a versão do Target FCM do dispositivo.
Estrutura HALs HALs listados conforme fornecidos no manifesto da estrutura e listados como obrigatórios ou opcionais na matriz de compatibilidade de dispositivos (DCM).

Desenvolvendo em uma nova versão do FCM

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

Para começar a desenvolver em um novo FCM Versão F :

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

Apresentando um novo HAL

Durante o desenvolvimento, ao introduzir um novo HAL (Wi-Fi, NFC, etc.) para Android no FCM Versão F atual, adicione o HAL a compatibility_matrix.current.xml com as seguintes configurações optional :

  • optional="false" se os dispositivos enviados com V = F devem ser iniciados com este HAL,

    OU
  • optional="true" se os dispositivos fornecidos com V = F puderem ser iniciados sem este HAL.

Por exemplo, o Android 8.1 introduziu o cas@1.0 como um HAL opcional. Dispositivos iniciados com o Android 8.1 não precisam implementar esse HAL, portanto, a seguinte entrada foi adicionada a compatibility_matrix.current.xml (renomeada para compatibility_matrix.2.xml após o lançamento do Android 8.1):

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

Atualizando um HAL (menor)

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

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

Por exemplo, o Android 8.1 introduziu o broadcastradio@1.1 como uma atualização de versão secundária do 1.0 HAL. A versão mais antiga, broadcastradio@1.0 , é opcional para dispositivos iniciados com Android 8.0, enquanto a versão mais recente, broadcastradio@1.1 , é opcional para dispositivos iniciados com 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>

Essa entrada foi copiada para compatibility_matrix.current.xml (renomeada para compatibility_matrix.2.xml após o lançamento do Android 8.1) e modificada da seguinte forma:

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

Atualizando um HAL (principal)

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

  • optional="false" apenas com a versão x.0 , se os dispositivos fornecidos com V = F devem ser iniciados com x.0 .
  • optional="false" , mas junto com versões principais mais antigas na mesma tag <hal> , se os dispositivos fornecidos com V = F devem ser iniciados com este HAL, mas podem ser iniciados com uma versão principal mais antiga.
  • optional="true" se os dispositivos fornecidos com V = F não precisarem iniciar o HAL.

Por exemplo, o Android 9 apresenta health@2.0 como uma atualização de versão principal do 1.0 HAL e descontinua o 1.0 HAL. A versão mais antiga, health@1.0 , é opcional para dispositivos iniciados com Android 8.0 e Android 8.1. Os dispositivos lançados com o Android 9 não devem fornecer a HAL 1.0 obsoleta e, em vez disso, devem fornecer a nova versão 2.0. Em compatibility_matrix.legacy.xml , compatibility_matrix.1.xml e compatibility_matrix.2.xml :

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

Essa entrada é copiada para compatibility_matrix.current.xml (renomeada para compatibility_matrix.3.xml com a versão Android 9) e modificada da seguinte forma:

<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 iniciados com o Android 9 devem ser fornecidos com a HAL 2.0.
  • Como a HAL 1.0 não está em compatibility_matrix.3.xml , os dispositivos iniciados com o Android 9 não devem fornecer a HAL 1.0 (já que essa HAL é considerada obsoleta).
  • Como o HAL 1.0 está presente em legacy/1/2.xml (versões FCM mais antigas com as quais o Android 9 pode trabalhar) como um HAL opcional, a estrutura do Android 9 ainda pode funcionar com o HAL 1.0 (que não é considerado uma versão HAL removida ).

Novas versões do FCM

O processo de liberação 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. Renomeie compatibility_matrix.current.xml para compatibility_matrix.F.xml .
  2. Certifique-se de que o arquivo tenha o atributo level="F" .
  3. Edite as regras de compilação correspondentes para refletir a alteração do nome do arquivo.
  4. Certifique-se de que todos os dispositivos sejam compilados e inicializados.
  5. Atualize os testes de VTS para garantir que os dispositivos lançados com a estrutura mais recente (com base no nível da API de envio) tenham Target FCM Version V >= F .
  6. Publique o arquivo no AOSP.

Este arquivo não pode ser alterado depois de renomeado e publicado. Por exemplo, durante o desenvolvimento do Android 9, os seguintes arquivos são criados para hardware/interfaces/compatibility_matrices/ :

  • compatibility_matrix.legacy.xml
  • compatibility_matrix.1.xml
  • compatibility_matrix.2.xml
  • compatibility_matrix.current.xml

Quando o Android 9 é lançado, compatibility_matrix.current.xml é renomeado para compatibility_matrix.3.xml e os seguintes arquivos são criados para hardware/interfaces/compatibility_matrices/ :

  • compatibility_matrix.legacy.xml
  • compatibility_matrix.1.xml
  • compatibility_matrix.2.xml
  • compatibility_matrix.3.xml

Os testes VTS garantem que os dispositivos iniciados 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 para cada versão do FCM da plataforma. A liberação das versões do FCM nas partições product e system_ext é feita pelo proprietário dessas imagens, respectivamente. Os números de versão do FCM nas partições product e system_ext devem estar alinhados com os da partição do sistema. Semelhante às versões do FCM na partição do sistema, a matriz de compatibilidade no FCM versão F nas partições product e system_ext reflete os requisitos em um dispositivo com o FCM de destino versão F.

Descontinuação da versão HAL

Descontinuar uma versão HAL é uma decisão do desenvolvedor (ou seja, para HALs AOSP, o Google toma a decisão). Isso pode acontecer quando uma versão HAL superior (seja menor ou maior) for lançada.

Descontinuar um dispositivo HAL

Quando um determinado dispositivo HAL foo@xy é preterido no FCM Versão F , isso significa que qualquer dispositivo iniciado com o Target FCM Versão V = F ou posterior não deve implementar foo na versão xy ou qualquer versão anterior a xy . Uma versão de HAL obsoleta ainda é suportada pela estrutura para atualização de dispositivos.

Quando o FCM Versão F é lançado, uma versão HAL foo@xy é considerada obsoleta se a versão HAL específica não for explicitamente declarada no FCM mais recente para Target FCM Version V = F . Para dispositivos iniciados com V = F , uma das seguintes condições é verdadeira:

  • O framework requer uma versão superior (major ou minor);
  • A estrutura não requer mais o HAL.

Por exemplo, no Android 9, health@2.0 é introduzido como uma atualização de versão principal do 1.0 HAL. health@1.0 é 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 obsoleto.

Descontinuar um framework HAL

Quando uma determinada estrutura HAL foo@xy é preterida no FCM Versão F , isso significa que qualquer dispositivo iniciado com o Target FCM Versão V = F ou posterior não deve esperar que a estrutura forneça foo na versão xy ou em qualquer versão anterior a xy . Uma versão HAL obsoleta ainda é fornecida pela estrutura para atualização de dispositivos.

Quando a versão F do FCM é lançada, uma versão HAL foo@xy é considerada obsoleta se o manifesto do framework especificar max-level=" F - 1 " for foo@xy . Para dispositivos iniciados com V = F , a estrutura não fornece o HAL foo@xy . A matriz de compatibilidade de dispositivos em dispositivos iniciados com V = F não deve listar HALs de estrutura com max-level < V .

Por exemplo, no Android 12, schedulerservice@1.0 está obsoleto. Seu atributo max-level é definido como 5 , a versão do FCM introduzida no Android 11. Consulte o manifesto da estrutura do Android 12 .

Remoção do suporte para versões do Target FCM

Quando os dispositivos ativos de um determinado Target FCM Version V caem abaixo de um determinado limite, o Target FCM Version é removido do conjunto S F da próxima versão do framework. Isso é feito por ambas as etapas a seguir:

  • Removendo compatibility_matrix.V.xml das regras de compilação (para que não seja instalado na imagem do sistema) e excluindo qualquer código que implementasse ou dependesse da funcionalidade removida.
  • Removendo HALs de estrutura com max-level menor ou igual a V do manifesto de estrutura e excluindo qualquer código que implemente as HALs de estrutura removidas.

Dispositivos com uma versão do FCM de destino fora do SF para uma determinada versão da estrutura não podem atualizar para essa versão.

Status da versão HAL

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

Inédito

Para HALs de dispositivo, se uma versão HAL não estiver em nenhuma das matrizes de compatibilidade pública e congelada, ela será considerada inédita e possivelmente em desenvolvimento. Isso inclui Versões HAL que estão apenas em compatibility_matrix.current.xml . Exemplos:

  • Durante o desenvolvimento do Android 9 (antes de compatibiility_matrix.current.xml ser renomeado para compatibility_matrix.3.xml ), a HAL health@2.0 foi considerada uma HAL não lançada.
  • O teleportation@1.0 HAL não está em nenhuma matriz de compatibilidade lançada e também é considerado um HAL não lançado.

Para HALs de estrutura, se uma versão de HAL estiver apenas no manifesto de estrutura 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 HAL estiver em qualquer matriz de compatibilidade pública e congelada, ela será liberada. Por exemplo, depois que o FCM Versão 3 é congelado (quando compatibiility_matrix.current.xml é renomeado para compatibility_matrix.3.xml ) e publicado no AOSP, o health@2.0 HAL é considerado uma versão HAL liberada e atual.

Se uma versão HAL estiver em uma matriz de compatibilidade pública e congelada que tenha a versão FCM mais alta (excluindo compatibility_matrix.current.xml ), a versão HAL será atual (ou seja, não obsoleta). Por exemplo, as versões HAL existentes (como nfc@1.0 introduzidas em compatibility_matrix.legacy.xml ) que continuam a existir em compatibility_matrix.3.xml também são consideradas como versões HAL liberadas e atuais.

Para HALs de estrutura, se uma versão HAL estiver no manifesto de estrutura da ramificação lançada mais recente sem o atributo max-level ou (excepcionalmente) um max-level igual ou superior à versão FCM lançada nesta ramificação, ela é considerada uma versão liberada e versão HAL atual. Por exemplo, o displayservice HAL é lançado e atual no Android 12, conforme especificado pelo Android 12framework manifest .

Lançado, mas obsoleto

Para HALs de dispositivo, uma versão HAL é preterida se e somente se todos os itens a seguir forem atendidos:

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

Exemplos:

Portanto, power@1.0 é atual, mas NÃO obsoleto, no Android 9.

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

Removido

Para HALs de dispositivo, uma versão HAL é removida se e somente se o seguinte for verdadeiro:

  • Foi lançado anteriormente.
  • Não está em nenhuma matriz de compatibilidade pública e congelada que o framework suporta.

As matrizes de compatibilidade que são públicas, congeladas, mas não suportadas pela estrutura são mantidas na base de código para definir o conjunto de Versões HAL removidas para que os testes VTS possam ser gravados para garantir que as HALs removidas não estejam em novos dispositivos.

Para HALs de estrutura, uma versão HAL é removida se e somente se o seguinte for atendido:

  • Foi lançado anteriormente.
  • Não está em nenhum manifesto de estrutura da última ramificação lançada.

FCMs legados

O legado da versão do FCM de destino é 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 este arquivo existir para um FCM com versão F , qualquer dispositivo não-Treble pode ser atualizado para F desde que seu manifesto de dispositivo seja compatível com este arquivo. Sua remoção segue o mesmo procedimento dos FCMs para outras versões do FCM de destino (removido após o número de dispositivos pré-8.0 ativos cair abaixo de um determinado limite).

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 .