Esquema de controle de versões do GKI

Esta página descreve o esquema de controle de versão para imagens genéricas do kernel (GKIs, na sigla em inglês). Um Imagem genérica do kernel (GKI) tem um identificador único chamado versão do kernel. A versão do kernel consiste da versão da interface do módulo do kernel (KMI) e do subnível. O kernel é específico para a imagem lançada, enquanto a versão KMI representa a interface de origem de uma versão. Uma versão do KMI pode oferecer suporte a várias versões do kernel. Uma versão do kernel é vinculada a apenas uma versão do KMI. No improvável caso em que a interface do módulo do kernel precise ser alterada, a geração do KMI é iterada para refletir a mudança na versão do KMI.

Resumo dos termos

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

Nome Símbolo Exemplo Descrição
Versão do kernel w.x.y-zzz-k-suffix 5.4.42-android12-0-foo Identificador exclusivo de uma versão do GKI. Esse é o valor retornado por uname.
Versão KMI w.x-zzz-k 5.4-android12-0 Descreve a interface do módulo do kernel (KMI, na sigla em inglês) entre a GKI e os módulos do kernel carregáveis dinamicamente (DLKM, na sigla em inglês).
Subnível y 42 Descreve a ordem de lançamento dos lançamentos de kernel dentro do mesma versão KMI.

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

Nome Símbolo Exemplo Descrição
w.x.y w.x.y 5.4.42

Para mais detalhes, consulte Makefiles do kernel do Linux (procure por "KERNELRELEASE").

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

Essa variável é chamada de kernel_version_tupla em libkver.

Essa tupla não pode ser reduzida por nenhuma atualização, incluindo OTA ou linha principal.
Ramificação do kernel zzz-w.x android12-5.4 Esse termo é usado em Tipos comuns de ramificação do kernel.
Versão w 5 Este termo não é usado neste documento. Essa variável é chamada de version no libkver.
Nível do patch x 4 Este termo não é usado neste documento. Essa variável é chamada de patch_level em libkver.
Versão do Android zzz android12

É o número da versão do Android (dessert) com que o kernel está associado.

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

O número da versão do Android não pode ser reduzido por nenhuma atualização, incluindo uma agência de viagens on-line (OTA, na sigla em inglês) ou linha principal.

Geração de KMI k 0

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

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

Design do controle de versões

Versão do kernel

Definição

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

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

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

Confira a seguir um exemplo de lançamento do kernel.

5.4.42-android12-0-00544-ged21d463f856

Descrição

A versão do kernel é o ID exclusivo de uma versão de 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 do KMI, um subnível e um sufixo. Para os fins deste documento, o sufixo após a geração de KMI é ignorado.

Versão do KMI

Definição

A versão do KMI é definida da seguinte maneira:

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

O subnível y não faz parte da versão KMI. Para o exemplo Na versão do kernel, a versão do KMI é:

5.4-android12-0

Descrição

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

Se duas versões do kernel tiverem a mesma versão do KMI, elas vão implementar 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 do KMI não pode ser diminuída por nenhuma atualização OTA.

Subnível

O subnível, y, descreve a ordem de lançamento das versões do kernel na mesma versão do 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 com Y1 poderá receber uma atualização para Y2.
  • Se Y1 for maior que Y2, um dispositivo que executa Y1 não poderá ser atualizado para Y2.

Ou seja, se a versão KMI não for alterada, o subnível não poderá ser reduzido por qualquer atualização OTA.

Determinar a versão do kernel de um dispositivo

A versão completa do kernel pode ser encontrada executando uname -r ou uname(2) pelo seguinte snippet 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 fins deste documento, tudo depois da geração de KMI é ignorado ao extrair informações do kernel. Mais formalmente, a saída de uname -r é analisada com o seguinte expressão regular (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 número da versão de ci.android.com, número do patches sobre o kernel de referência e hashes SHA do commit do git.

Libkver

A biblioteca libkver fornece uma interface C++ para analisar a versão do kernel ou uma string de versão do KMI. Para obter uma lista das APIs expostas pelo libkver, consulte packages/modules/Gki/libkver/include/kver

Verificações do VINTF

Para o Android 11 ou versões anteriores, a parte de lançamento do Android da versão KMI é especificados manualmente no manifesto do dispositivo pelos fabricantes. Para mais detalhes, consulte as 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 injetadas no manifesto do dispositivo no momento da compilação.

Como os requisitos de configuração do kernel geralmente não mudam, não é preciso codificar k na matriz de compatibilidade. No entanto, na improvável em que o requisito de configuração do kernel precisa ser alterado, verifique se o seguinte:

  • O requisito correspondente da matriz de compatibilidade é removido.
  • Outros testes VTS foram adicionados para verificar os novos requisitos condicionais na geração de KMI.

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

Mesmo que a imagem de inicialização seja atualizada por OTA, ela precisa ser encapsulado no formato de payload OTA, payload.bin. A carga OTA codifica version para cada partição. Quando update_engine processa um payload OTA, ele compara esse campo para garantir que a partição não seja rebaixada.

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

Como o ramdisk é sempre criado do zero, o uso do carimbo de data/hora do ramdisk é suficiente para descrever toda a imagem de inicialização. Não é necessário codificar a versão do kernel na versão da imagem de inicialização, a menos que você esteja unindo uma imagem de inicialização antiga a um novo binário do kernel no futuro.

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