Versão GKI

Esta página descreve o esquema de versão para imagens genéricas do kernel (GKIs). Uma imagem genérica do kernel (GKI) tem um identificador exclusivo chamado versão do kernel. A versão do kernel consiste na versão da interface do módulo do kernel (KMI) e no subnível. A versão do kernel é específica para a imagem que está sendo lançada, enquanto a versão KMI representa a interface a partir da qual uma versão é construída. Uma versão KMI pode suportar várias versões do kernel. Uma versão do kernel está vinculada a apenas uma versão KMI. No caso improvável em que a interface do módulo do kernel precise ser alterada, a geração KMI é iterada para refletir a alteração na versão KMI.

Resumo dos termos

A tabela a seguir resume os termos importantes usados ​​nesta página e nas atualizações do GKI.

Nome Símbolo Exemplo Descrição
Versão do kernel wxy-zzz-k-sufixo 5.4.42-android12-0-foo Identificador exclusivo para uma versão do GKI. Este é o valor retornado por uname .
Versão KMI wx-zzz-k 5.4-android12-0 Descreve a interface do módulo do kernel (KMI) entre o GKI e os módulos do kernel carregáveis ​​dinamicamente (DLKM).
Sub-nível y 42 Descreve a ordem de lançamento dos lançamentos do kernel na mesma versão KMI.

A tabela a seguir lista outros termos relacionados como referência.

Nome Símbolo Exemplo Descrição
wxy wxy 5.4.42

Para obter detalhes, consulte Linux Kernel Makefiles (procure por "KERNELRELEASE").

wxy é usado diretamente em todo este documento. Isso também é comumente referido como o número de versão de três partes . O termo usado em VINTF, versão do kernel , pode causar confusão com outros termos, especialmente w .

Esta variável é referida como kernel_version_tuple na libkver .

Esta tupla não deve ser diminuída por nenhuma atualização, incluindo OTA ou mainline.

Ramificação do kernel zzz-wx android12-5.4 Este termo é usado em tipos de ramificações de kernel comuns .
Versão C 5 Este termo não é usado neste documento. Essa variável é chamada de versão em libkver .
Nível de patch x 4 Este termo não é usado neste documento. Esta variável é chamada de patch_level na libkver .
Versão do Android zzz android12

Este é o número de versão do Android (sobremesa) ao qual o kernel está associado.

Ao comparar o campo AndroidRelease , a parte numérica é extraída da string para comparação.

O número de versão do Android não deve ser diminuído por nenhuma atualização, incluindo OTA ou linha principal.

Geração KMI k 0

Este é um número adicional adicionado para lidar com eventos improváveis. Se uma correção de bug de segurança exigir alterações no KMI na mesma versão do Android, uma geração de KMI será aumentada.

O número de geração KMI começa com 0.

Projeto de versão

Versão do kernel

Definição

Para dispositivos fornecidos com GKI, a versão do kernel é definida da seguinte forma:

KernelRelease :=
Version.PatchLevel.SubLevel-AndroidRelease-KmiGeneration-suffix
w      .x         .y       -zzz           -k            -something

Para obter mais informações, consulte Determinando a versão do kernel de um dispositivo .

O seguinte é um exemplo de uma versão do kernel.

5.4.42-android12-0-00544-ged21d463f856

Descrição

A versão do kernel é o ID exclusivo de uma versão do GKI. Se dois binários GKI tiverem a mesma versão do kernel, eles devem ser idênticos em bytes.

Uma versão do kernel consiste em uma versão KMI, um subnível e um sufixo. Para os propósitos deste documento, o sufixo após a geração de KMI é ignorado.

Versão KMI

Definição

A versão KMI é definida da seguinte forma:

KmiVersion :=
Version.PatchLevel-AndroidRelease-KmiGeneration
w      .x         -zzz           -k

Observe que o subnível y não faz parte da versão KMI. Para o exemplo na versão do Kernel , a versão KMI é:

5.4-android12-0

Descrição

A versão KMI descreve a interface do módulo do kernel (KMI) entre o GKI e os módulos de kernel carregáveis ​​dinamicamente (DLKM).

Se duas versões do kernel tiverem a mesma versão KMI, elas implementarão a mesma interface do módulo do kernel. Os DLKMs compatíveis com um também são compatíveis com o outro.

A versão KMI não deve ser diminuída por nenhuma atualização OTA.

Sub-nível

O subnível, y , descreve a ordem de lançamento dos lançamentos do kernel dentro da mesma versão KMI.

Para duas versões do kernel que têm a mesma versão KMI, mas têm subnível Y1 e Y2, respectivamente:

  • Se Y1 for menor ou igual a Y2, um dispositivo executando Y1 poderá receber uma atualização para Y2.
  • Se Y1 for maior que Y2, um dispositivo executando Y1 não poderá ser atualizado para Y2.

Ou seja, se a versão KMI não mudar, o subnível não deve ser diminuído por nenhuma atualização OTA.

Determinando a versão do kernel de um dispositivo

A versão completa do kernel pode ser encontrada executando uname -r ou uname(2) com o seguinte trecho de código:

std::string get_kernel_release() {
  struct utsname buf;
  return uname(&buf) == 0 ? buf.release : "";
}

Um exemplo de saída é:

5.4.42-android12-0-00544-ged21d463f856

Para os propósitos deste documento, qualquer coisa após a geração KMI é ignorada ao extrair informações do kernel. Mais formalmente, a saída de uname -r é analisada com o seguinte regex (assumindo que zzz sempre começa com "android"):

^(?P<w>\d+)[.](?P<x>\d+)[.](?P<y>\d+)-(?P<z>android\d+)-(?P<k>\d+).*$

As informações ignoradas podem incluir informações como o número de compilação ci.android.com , número de patches no topo do kernel de linha de base e hashes SHA do git commit.

libkver

A biblioteca, libkver, fornece uma interface C++ para analisar a versão do kernel ou uma string de versão KMI. Para uma lista de APIs que o libkver expõe, veja packages/modules/Gki/libkver/include/kver .

Cheques VINTF

Para o Android 11 ou inferior, a parte de lançamento do Android da versão KMI é especificada manualmente no manifesto do dispositivo pelos fabricantes do dispositivo. Para obter detalhes, consulte Regras de correspondência do kernel VINTF .

No Android S, a parte de lançamento do Android da versão KMI pode ser extraída do kernel e injetada no manifesto do dispositivo em tempo de compilação.

Como os requisitos de configuração do kernel geralmente não mudam, não há necessidade de codificar k dentro da matriz de compatibilidade. No entanto, no caso improvável em que o requisito de configuração do kernel precise ser alterado, certifique-se do seguinte:

  • O requisito correspondente da matriz de compatibilidade é removido.
  • Testes VTS adicionais são adicionados para verificar os novos requisitos condicionais à geração de KMI.

Versão da imagem de inicialização nos metadados OTA

Mesmo que a imagem de inicialização seja atualizada por meio de uma atualização OTA, ela deve ser encapsulada no formato de carga útil OTA, payload.bin . A carga útil OTA codifica um campo de version para cada partição. Quando update_engine manipula uma carga útil OTA, ele compara esse campo para garantir que a partição não seja rebaixada.

Para evitar confusão, o campo de version da partição de inicialização nos metadados OTA é chamado boot image version .

Como o ramdisk é sempre construído do zero, usar o timestamp do ramdisk é suficiente para descrever toda a imagem de inicialização. Não há necessidade de codificar a versão do kernel na versão da imagem de inicialização, a menos que você esteja costurando uma imagem de inicialização antiga para um novo binário do kernel no futuro.

Antes de uma atualização OTA, o cliente OTA verifica a versão da imagem de inicialização da mesma forma que qualquer outra partição.