Controllo delle versioni GKI

Questa pagina descrive lo schema di controllo delle versioni per le immagini kernel generiche (GKI). Una Generic Kernel Image (GKI) ha un identificatore univoco chiamato versione del kernel. La versione del kernel è costituita dalla versione KMI (Kernel Module Interface) e dal sottolivello. La versione del kernel è specifica per l'immagine rilasciata, mentre la versione KMI rappresenta l'interfaccia da cui viene creata una versione. Una versione KMI può supportare più versioni del kernel. Una versione del kernel è legata a una sola versione KMI. Nell'improbabile caso in cui sia necessario modificare l'interfaccia del modulo del kernel, la generazione del KMI viene ripetuta per riflettere il cambiamento nella versione del KMI.

Riepilogo dei termini

La tabella seguente riepiloga i termini importanti utilizzati in questa pagina e per gli aggiornamenti GKI.

Nome Simbolo Esempio Descrizione
Rilascio del kernel suffisso wxy-zzz-k 5.4.42-android12-0-foo Identificatore univoco per una versione GKI. Questo è il valore restituito da uname .
Versione KMI wx-zzz-k 5.4-android12-0 Descrive l'interfaccia del modulo kernel (KMI) tra GKI e i moduli kernel caricabili dinamicamente (DLKM).
Sottolivello 42 Descrive l'ordine di rilascio dei rilasci del kernel all'interno della stessa versione KMI.

La tabella seguente elenca altri termini correlati come riferimento.

Nome Simbolo Esempio Descrizione
wxy wxy 5.4.42

Per i dettagli, vedere Makefile del kernel Linux (cercare "KERNELRELEASE").

wxy viene utilizzato direttamente in tutto questo documento. Questo è comunemente indicato anche come numero di versione in tre parti . Il termine utilizzato in VINTF, versione del kernel , potrebbe causare confusione con altri termini, in particolare w .

Questa variabile è chiamata kernel_version_tuple in libkver .

Questa tupla non deve essere ridotta da eventuali aggiornamenti, inclusi OTA o mainline.

Ramo del nocciolo zzz-wx Android12-5.4 Questo termine viene utilizzato nei tipi di rami comuni del kernel .
Versione w 5 Questo termine non è utilizzato in questo documento. Questa variabile viene definita versione in libkver .
Livello di patch X 4 Questo termine non è utilizzato in questo documento. Questa variabile viene chiamata patch_level in libkver .
Versione Android zzz android12

Questo è il numero di versione Android (dessert) a cui è associato il kernel.

Quando si confronta il campo AndroidRelease , la parte numerica viene estratta dalla stringa per il confronto.

Il numero di versione di Android non deve essere ridotto da eventuali aggiornamenti, inclusi OTA o mainline.

Generazione KMI K 0

Questo è un numero aggiuntivo aggiunto per far fronte a eventi improbabili. Se la correzione di un bug di sicurezza richiede modifiche al KMI all'interno della stessa versione di Android, la generazione di KMI viene aumentata.

Il numero di generazione KMI inizia con 0.

Progettazione del controllo delle versioni

Rilascio del kernel

Definizione

Per i dispositivi forniti con GKI, la versione del kernel è definita come segue:

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

Per ulteriori informazioni, vedere Determinazione della versione del kernel da un dispositivo .

Quello che segue è un esempio di una versione del kernel.

5.4.42-android12-0-00544-ged21d463f856

Descrizione

La versione del kernel è l'ID univoco di una versione GKI. Se due file binari GKI hanno la stessa versione del kernel, devono essere identici in termini di byte.

Una versione del kernel è composta da una versione KMI, un sottolivello e un suffisso. Ai fini di questo documento, il suffisso dopo la generazione del KMI viene ignorato.

Versione KMI

Definizione

La versione KMI è definita come segue:

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

Tieni presente che il sottolivello y non fa parte della versione KMI. Per l'esempio nella versione del kernel , la versione KMI è:

5.4-android12-0

Descrizione

La versione KMI descrive l'interfaccia del modulo kernel (KMI) tra GKI e i moduli kernel caricabili dinamicamente (DLKM).

Se due versioni del kernel hanno la stessa versione KMI, implementano la stessa interfaccia del modulo del kernel. I DLKM compatibili con l'uno sono compatibili anche con l'altro.

La versione KMI non deve essere diminuita da eventuali aggiornamenti OTA.

Sottolivello

Il sottolivello, y , descrive l'ordine di rilascio dei rilasci del kernel all'interno della stessa versione KMI.

Per due versioni del kernel che hanno la stessa versione KMI ma hanno rispettivamente il sottolivello Y1 e Y2:

  • Se Y1 è inferiore o uguale a Y2, un dispositivo che esegue Y1 può ricevere un aggiornamento a Y2.
  • Se Y1 è maggiore di Y2, un dispositivo che esegue Y1 non può essere aggiornato a Y2.

Cioè, se la versione KMI non cambia, il sottolivello non deve essere diminuito da nessun aggiornamento OTA.

Determinazione del rilascio del kernel da un dispositivo

La versione completa del kernel può essere trovata eseguendo uname -r o uname(2) con il seguente frammento di codice:

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

Un esempio di output è:

5.4.42-android12-0-00544-ged21d463f856

Ai fini di questo documento, qualsiasi cosa successiva alla generazione del KMI viene ignorata durante l'estrazione delle informazioni sul kernel. Più formalmente, l'output di uname -r viene analizzato con la seguente regex (assumendo che zzz inizi sempre con "android"):

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

Le informazioni ignorate possono includere informazioni come il numero di build ci.android.com , il numero di patch sul kernel di base e gli hash SHA del commit git.

libkver

La libreria, libkver, fornisce un'interfaccia C++ per analizzare la versione del kernel o una stringa di versione KMI. Per un elenco delle API esposte da libkver, vedere packages/modules/Gki/libkver/include/kver .

Assegni VINTF

Per Android 11 o versioni precedenti, la parte di rilascio Android della versione KMI viene specificata manualmente nel manifesto del dispositivo dai produttori del dispositivo. Per i dettagli, consulta Regole di corrispondenza del kernel VINTF .

Da Android S, la parte di rilascio Android della versione KMI può essere estratta dal kernel e inserita nel manifest del dispositivo in fase di compilazione.

Poiché i requisiti di configurazione del kernel generalmente non cambiano, non è necessario codificare k all'interno della matrice di compatibilità. Tuttavia, nel caso improbabile in cui sia necessario modificare i requisiti di configurazione del kernel, verificare quanto segue:

  • Il requisito corrispondente dalla matrice di compatibilità viene rimosso.
  • Vengono aggiunti ulteriori test VTS per verificare i nuovi requisiti condizionati alla generazione di KMI.

Versione dell'immagine di avvio nei metadati OTA

Anche se l'immagine di avvio viene aggiornata tramite un aggiornamento OTA, deve essere racchiusa nel formato del payload OTA, payload.bin . Il payload OTA codifica un campo version per ciascuna partizione. Quando update_engine gestisce un payload OTA, confronta questo campo per garantire che la partizione non venga sottoposta a downgrade.

Per evitare confusione, il campo version per la partizione di avvio nei metadati OTA è chiamato boot image version .

Poiché il ramdisk viene sempre creato da zero, l'utilizzo del timestamp del ramdisk è sufficiente per descrivere l'intera immagine di avvio. Non è necessario codificare la versione del kernel nella versione dell'immagine di avvio, a meno che non si stia inserendo una vecchia immagine di avvio in un nuovo binario del kernel in futuro.

Prima di un aggiornamento OTA, il client OTA controlla la versione dell'immagine di avvio allo stesso modo di qualsiasi altra partizione.