GKI-Versionsschema

Auf dieser Seite wird das Versionsverwaltungsschema für generische Kernel-Images (Generic Kernel Images, GKIs) beschrieben. Ein generisches Kernel-Image (GKI) hat eine eindeutige Kennung, die als Kernel-Release bezeichnet wird. Das Kernel-Release besteht aus der Version der Kernelmodulschnittstelle (Kernel Module Interface, KMI) und der Unterebene. Das Kernel-Release ist spezifisch für das freigegebene Image, während die KMI-Version die Schnittstelle darstellt, aus der ein Release erstellt wird. Eine KMI-Version kann mehrere Kernel-Releases unterstützen. Ein Kernel-Release ist nur mit einer KMI-Version verknüpft. In dem unwahrscheinlichen Fall, dass die Kernelmodulschnittstelle geändert werden muss, wird die KMI-Generation wiederholt, um die Änderung der KMI-Version widerzuspiegeln.

Zusammenfassung der Begriffe

In der folgenden Tabelle sind wichtige Begriffe zusammengefasst, die auf dieser Seite und für GKI-Updates verwendet werden.

Name Symbol Beispiel Beschreibung
Kernel-Release w.x.y-zzz-k-Suffix 5.4.42-android12-0-foo Eindeutige Kennung für ein GKI-Release. Dies ist der von uname zurückgegebene Wert.
KMI-Version w.x-zzz-k 5.4-android12-0 Beschreibt die Kernelmodulschnittstelle (KMI) zwischen GKI und dynamisch ladbaren Kernelmodulen (Dynamically Loadable Kernel Modules, DLKMs).
Untebene y 42 Beschreibt die Release-Reihenfolge von Kernel-Releases innerhalb derselben KMI-Version.

In der folgenden Tabelle sind weitere verwandte Begriffe als Referenz aufgeführt.

Name Symbol Beispiel Beschreibung
w.x.y w.x.y 5.4.42

Weitere Informationen finden Sie in den Linux Kernel-Makefiles (suchen Sie nach "KERNELRELEASE").

w.x.y wird in diesem Dokument direkt verwendet. Dies wird auch als dreiteilige Versionsnummer bezeichnet. Der in VINTF verwendete Begriff Kernel-Version kann zu Verwechslungen mit anderen Begriffen führen, insbesondere mit w.

Diese Variable wird in libkver als kernel_version_tuple bezeichnet.

Dieses Tupel darf durch keine Updates verringert werden, einschließlich OTA- oder Mainline-Updates.
Kernel-Branch zzz-w.x android12-5.4 Dieser Begriff wird in Häufige Kernel-Branch-Typen verwendet.
Version w 5 Dieser Begriff wird in diesem Dokument nicht verwendet. Diese Variable wird in libkver als version bezeichnet.
Patchebene x 4 Dieser Begriff wird in diesem Dokument nicht verwendet. Diese Variable wird in libkver als patch_level bezeichnet.
Android-Release zzz android12

Dies ist die Android-Release-Nummer (Dessert), mit der der Kernel verknüpft ist.

Beim Vergleich des AndroidRelease Felds wird der numerische Teil wird aus dem String extrahiert.

Die Android-Release-Nummer darf durch keine Updates verringert werden, einschließlich OTA- oder Mainline-Updates.

KMI-Generation k 0

Dies ist eine zusätzliche Zahl, die für unwahrscheinliche Ereignisse hinzugefügt wird. Wenn für eine Fehlerkorrektur in Bezug auf die Sicherheit Änderungen an der KMI innerhalb desselben Android-Release erforderlich sind, wird die KMI-Generation erhöht.

Die KMI-Generationsnummer beginnt mit 0.

Versionsverwaltungsdesign

Kernel-Release

Definition

Für Geräte, die mit GKI ausgeliefert werden, ist das Kernel-Release so definiert:

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

Weitere Informationen finden Sie unter Kernel-Release von einem Gerät bestimmen.

Das folgende Beispiel zeigt ein Kernel-Release.

5.4.42-android12-0-00544-ged21d463f856

Beschreibung

Das Kernel-Release ist die eindeutige ID eines GKI-Release. Wenn zwei GKI-Binärdateien dasselbe Kernel-Release haben, müssen sie bytegenau identisch sein.

Ein Kernel-Release besteht aus einer KMI-Version, einer Unterebene und einem Suffix. Für die Zwecke dieses Dokuments wird das Suffix nach der KMI-Generation ignoriert.

KMI-Version

Definition

Die KMI-Version ist so definiert:

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

Beachten Sie, dass die Unterebene y nicht Teil der KMI-Version ist. Für das Beispiel unter Kernel-Release ist die KMI-Version:

5.4-android12-0

Beschreibung

Die KMI-Version beschreibt die Kernelmodulschnittstelle (KMI) zwischen GKI und dynamisch ladbaren Kernelmodulen (DLKMs).

Wenn zwei Kernel-Releases dieselbe KMI-Version haben, implementieren sie dieselbe Kernelmodulschnittstelle. Die DLKMs, die mit einem kompatibel sind, sind auch mit dem anderen kompatibel.

Die KMI-Version darf durch keine OTA-Updates verringert werden.

Untebene

Die Unterebene y beschreibt die Release-Reihenfolge von Kernel-Releases innerhalb derselben KMI-Version.

Für zwei Kernel-Releases mit derselben KMI-Version, aber mit den Unterebenen Y1 bzw. Y2 gilt Folgendes:

  • Wenn Y1 kleiner oder gleich Y2 ist, kann ein Gerät mit Y1 auf Y2 aktualisiert werden.
  • Wenn Y1 größer als Y2 ist, kann ein Gerät mit Y1 nicht auf Y2 aktualisiert werden.

Wenn sich die KMI-Version nicht ändert, darf die Unterebene durch kein OTA-Update verringert werden.

Kernel-Release von einem Gerät bestimmen

Das vollständige Kernel-Release finden Sie durch Ausführen von uname -r oder uname(2) mit dem folgenden Code-Snippet:

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

Die Ausgabe sieht beispielsweise so aus:

5.4.42-android12-0-00544-ged21d463f856

Für die Zwecke dieses Dokuments wird alles nach der KMI-Generation beim Extrahieren von Kernel-Informationen ignoriert. Formaler ausgedrückt: Die Ausgabe von uname -r wird mit dem folgenden regulären Ausdruck geparst (vorausgesetzt, zzz beginnt immer mit "android"):

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

Die ignorierten Informationen können beispielsweise die Build-Nummer von ci.android.com, die Anzahl der Patches über dem Baseline-Kernel und die SHA-Hashes des Git-Commits enthalten.

libkver

Die Bibliothek libkver bietet eine C++-Schnittstelle zum Parsen des Kernel-Release- oder KMI-Versionsstrings. Eine Liste der von libkver bereitgestellten APIs finden Sie unter packages/modules/Gki/libkver/include/kver.

VINTF-Prüfungen

Bei Android 11 oder niedriger wird der Android-Release-Teil der KMI-Version von Geräteherstellern manuell im Gerätemanifest angegeben. Weitere Informationen finden Sie unter VINTF-Kernel-Abgleichsregeln.

Ab Android S kann der Android-Release-Teil der KMI-Version aus dem Kernel extrahiert und zur Build-Zeit in das Gerätemanifest eingefügt werden.

Da sich die Anforderungen an die Kernelkonfiguration in der Regel nicht ändern, muss k nicht in der Kompatibilitätsmatrix codiert werden. Sollte sich die Anforderung an die Kernelkonfiguration jedoch ändern, beachten Sie Folgendes:

  • Die entsprechende Anforderung aus der Kompatibilitätsmatrix wird entfernt.
  • Zusätzliche VTS-Tests werden hinzugefügt, um die neuen Anforderungen bedingt durch die KMI-Generation zu prüfen.

Boot-Image-Version in OTA-Metadaten

Auch wenn das Boot-Image über OTA aktualisiert wird, muss es im OTA-Nutzlastformat payload.bin verpackt sein. Die OTA-Nutzlast codiert ein version-Feld für jede Partition. Wenn update_engine eine OTA-Nutzlast verarbeitet, wird dieses Feld verglichen, um sicherzustellen, dass die Partition nicht herabgestuft wird.

Um Verwechslungen zu vermeiden, wird das version Feld für die Bootpartition in den OTA Metadaten als boot image version bezeichnet.

Da die Ramdisk immer von Grund auf neu erstellt wird, reicht der Ramdisk-Zeitstempel aus, um das gesamte Boot-Image zu beschreiben. Das Kernel-Release muss nicht in der Boot-Image-Version codiert werden, es sei denn, Sie möchten in Zukunft ein altes Boot-Image mit einer neuen Kernel-Binärdatei zusammenfügen.

Vor einem OTA-Update prüft der OTA-Client die Boot-Image-Version auf dieselbe Weise wie jede andere Partition.