Questa pagina descrive lo schema di versionamento delle immagini generiche del kernel (GKI). Un Generic Kernel Image (GKI) ha un identificatore univoco chiamato release del kernel. La release del kernel è composta dalla versione dell'interfaccia del modulo kernel (KMI) e dal sottolivello. La release del kernel è specifica per l'immagine rilasciata, mentre la versione KMI rappresenta l'interfaccia da cui viene creata una release. Una versione KMI può supportare più release del kernel. Una release del kernel è associata a una sola versione KMI. Nel caso improbabile in cui l'interfaccia del modulo del kernel debba essere modificata, la generazione del KMI viene ripetuta per riflettere la modifica della versione del KMI.
Riepilogo dei termini
La tabella seguente riassume i termini importanti utilizzati in questa pagina e per gli aggiornamenti di GKI.
| Nome | Simbolo | Esempio | Descrizione |
|---|---|---|---|
| Release del kernel | w.x.y-zzz-k-suffix | 5.4.42-android12-0-foo | Identificatore univoco di una release GKI. Questo è il valore restituito da uname. |
| Versione KMI | w.x-zzz-k | 5.4-android12-0 | Descrive l'interfaccia del modulo kernel (KMI) tra GKI e i moduli kernel caricabili dinamicamente (DLKM). |
| Livello secondario | y | 42 | Descrive l'ordine di rilascio delle release del kernel all'interno della stessa versione KMI. |
La tabella seguente elenca altri termini correlati come riferimento.
| Nome | Simbolo | Esempio | Descrizione |
|---|---|---|---|
| w.x.y | l.x.a | 5.4.42 |
Per maggiori dettagli, consulta la pagina Makefile del kernel Linux (cerca "KERNELRELEASE"). w.x.y viene utilizzato direttamente in questo documento. È anche comunemente indicato 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 è indicata come kernel_version_tuple in libkver. Questa tupla non deve essere diminuita da alcun aggiornamento, inclusi OTA o principale. |
| Ramo kernel | zzz-w.x | android12-5.4 | Questo termine è utilizzato nei tipi di ramo del kernel comuni. |
| Versione | w | 5 | Questo termine non viene utilizzato in questo documento. Questa variabile è indicata come version in libkver. |
| Livello patch | x | 4 | Questo termine non viene utilizzato in questo documento. Questa variabile è indicata come patch_level in libkver. |
| Release di Android | zzz | android12 |
Questo è il numero di release di Android (dessert) a cui è associato il kernel.
Quando confronti il campo Il numero della release di Android non deve essere diminuito da alcun aggiornamento, inclusi quelli OTA o principali. |
| Generazione di KMI | k | 0 |
Si tratta di un numero aggiuntivo aggiunto per gestire eventi improbabili. Se la correzione di un bug di sicurezza richiede modifiche al KMI all'interno della stessa release di Android, viene aumentata una generazione di KMI. Il numero di generazione del KMI inizia con 0. |
Progettazione del controllo delle versioni
Release del kernel
Definizione
Per i dispositivi forniti con GKI, la release del kernel è definita come segue:
KernelRelease :=
Version.PatchLevel.SubLevel-AndroidRelease-KmiGeneration-suffix
w .x .y -zzz -k -something
Per ulteriori informazioni, consulta la sezione Determinare la release del kernel da un dispositivo.
Di seguito è riportato un esempio di release del kernel.
5.4.42-android12-0-00544-ged21d463f856
Descrizione
La release del kernel è l'ID univoco di una release GKI. Se due file binari GKI hanno la stessa release del kernel, devono essere identici a livello di byte.
Una release del kernel è composta da una versione KMI, un sottolivello e un suffisso. Ai fini di questo documento, il suffisso dopo la generazione del file 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 livello secondario y non fa parte della versione KMI. Per l'esempio riportato in Release 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 release del kernel hanno la stessa versione KMI, implementano la stessa interfaccia del modulo del kernel. I DLKM compatibili con uno sono compatibili anche con l'altro.
La versione KMI non deve essere diminuita da eventuali aggiornamenti OTA.
Livello secondario
Il livello secondario, y, descrive l'ordine di rilascio delle release del kernel all'interno della
stessa versione KMI.
Per due release del kernel con la stessa versione KMI, ma con i sottolivelli Y1 e Y2 rispettivamente:
- Se Y1 è minore o uguale a Y2, un dispositivo con Y1 può ricevere un update a Y2.
- Se Y1 è maggiore di Y2, un dispositivo con Y1 non può essere aggiornato a Y2.
In altre parole, se la versione KMI non cambia, il sottolivello non deve essere ridotto da alcun aggiornamento OTA.
Determinare la release del kernel da un dispositivo
La release completa del kernel è disponibile eseguendo uname -r o
uname(2)
con lo snippet di codice seguente:
std::string get_kernel_release() {
struct utsname buf;
return uname(&buf) == 0 ? buf.release : "";
}
Un output di esempio è:
5.4.42-android12-0-00544-ged21d463f856
Ai fini di questo documento, tutto ciò che segue la generazione del file KMI viene ignorato
durante l'estrazione delle informazioni del kernel. Più formalmente, l'output di uname -r viene analizzato con la seguente regex (supponendo 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 il numero di build di ci.android.com, il numero di patch sul kernel di riferimento e gli hash SHA del commit Git.
libkver
La libreria libkver fornisce un'interfaccia C++ per analizzare la release del kernel o una stringa di versione KMI. Per un elenco delle API esposte da libkver, vedi
packages/modules/Gki/libkver/include/kver.
Controlli VINTF
Per Android 11 o versioni precedenti, la parte della versione KMI relativa alla release di Android viene specificata manualmente nel manifest del dispositivo dai produttori di dispositivi. Per maggiori dettagli, consulta le regole di corrispondenza del kernel VINTF.
Da Android S, la parte della release Android della versione KMI può essere estratta dal kernel e iniettata nel manifest del dispositivo in fase di compilazione.
Poiché i requisiti di configurazione del kernel in genere non cambiano, non è necessario codificare k all'interno della matrice di compatibilità. Tuttavia, nell'improbabile
caso in cui il requisito di configurazione del kernel debba essere modificato, assicurati
di quanto segue:
- Il requisito corrispondente dalla matrice di compatibilità viene rimosso.
- Vengono aggiunti ulteriori test VTS per verificare i nuovi requisiti condizionali alla generazione di KMI.
Versione dell'immagine di avvio nei metadati OTA
Anche se l'immagine di avvio viene aggiornata tramite OTA, deve essere sottoposta a wrapping nel formato di payload OTA, payload.bin. Il payload OTA codifica un
version campo per ogni partizione. Quando update_engine gestisce un payload OTA,
confronta questo campo per assicurarsi che non venga eseguito il downgrade della partizione.
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 release del kernel nella versione dell'immagine di avvio, a meno che in futuro non si voglia unire una vecchia immagine di avvio a un nuovo file binario del kernel.
Prima di un aggiornamento OTA, il client OTA controlla la versione dell'immagine di avvio come qualsiasi altra partizione.