GKI のバージョニングスキーム

このページでは、汎用カーネルイメージ（GKI）のバージョニングスキームについて説明します。汎用カーネルイメージ（GKI）にはカーネルリリースと呼ばれる一意の識別子があります。カーネルリリースは、カーネルモジュールインターフェース（KMI）のバージョンとサブレベルで構成されます。カーネルリリースはリリースされるイメージに固有のものであるのに対し、KMI バージョンはリリースがビルドされるインターフェースを表します。KMI バージョンは複数のカーネルリリースをサポートできますが、カーネルリリースは 1 つの KMI バージョンにのみ関連付けられます。万が一、カーネルモジュールインターフェースを変更する必要がある場合、KMI バージョンの変更を反映するために KMI 世代が反復処理されます。

用語の概要

次の表は、このページおよび GKI の更新で使用される重要な用語をまとめたものです。

名前	記号	例	説明
カーネルリリース	w.x.y-zzz-k-suffix	5.4.42-android12-0-foo	GKI リリースの一意の識別子。これは `uname` で返される値です。
KMI バージョン	w.x-zzz-k	5.4-android12-0	GKI とダイナミックローダブルカーネルモジュール（DLKM）の間のカーネルモジュールインターフェース（KMI）を表します。
サブレベル	y	42	同じ KMI バージョン内のカーネルリリースのリリース順序を表します。

次の表に、その他の関連する用語をリファレンスとして示します。

名前	記号	例	説明
w.x.y	w.x.y	5.4.42	詳しくは、Linux カーネルの Makefile をご覧ください（「KERNELRELEASE」を検索）。このドキュメント全体を通して、w.x.y をそのまま使用しています。これは一般に、「3 つのパートから構成されるバージョン番号」とも呼ばれます。VINTF で使用される用語の「カーネルバージョン」は、他の用語、特に w と混同される可能性があります。この変数は、libkver では kernel_version_tuple と表記されます。このタプルは、OTA やメインラインなどのアップデートで下げることはできません。
カーネルブランチ	zzz-w.x	android12-5.4	この用語は、共通カーネルブランチタイプで使用されます。
バージョン	w	5	この用語は、このドキュメントでは使用されません。この変数は、libkver では version と表記されます。
パッチレベル	x	4	この用語は、このドキュメントでは使用されません。この変数は、libkver では patch_level と表記されます。
Android リリース	zzz	android12	これは、カーネルが関連付けられている Android（デザート名）リリース番号です。 `AndroidRelease` フィールドを比較する際に、数値部分が文字列から抽出されて比較されます。 Android のリリース番号は、OTA やメインラインなどのアップデートで下げることはできません。
KMI 世代	k	0	これは、めったに発生しないイベントに対応するための追加の数値です。セキュリティバグの修正により同じ Android リリース内で KMI を変更する必要が生じた場合は、KMI 世代が上がります。 KMI 世代番号は 0 から始まります。

バージョニングの設計

カーネルリリース

定義

GKI が搭載されたデバイスの場合、カーネルリリースは次のように定義されます。

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

詳細については、デバイスでカーネルリリースを確認するをご覧ください。

カーネルリリースの例を次に示します。

5.4.42-android12-0-00544-ged21d463f856

説明

カーネルリリースは、GKI リリースの一意の ID です。2 つの GKI バイナリのカーネルリリースが同じ場合は、バイト単位で同一である必要があります。

カーネルリリースは、KMI バージョン、サブレベル、サフィックスで構成されます。このドキュメントでは、KMI 世代の後ろのサフィックスは無視します。

KMI バージョン

定義

KMI バージョンは次のように定義されます。

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

サブレベルの y は KMI バージョンには含まれません。カーネルリリースの例の場合、KMI バージョンは次のようになります。

5.4-android12-0

説明

KMI バージョンは、GKI とダイナミックローダブルカーネルモジュール（DLKM）の間のカーネルモジュールインターフェース（KMI）を表します。

2 つのカーネルリリースが同じ KMI バージョンを持つ場合、これらは同じカーネルモジュールインターフェースを実装しています。1 つのカーネルリリースと互換性のある DLKM は、もう 1 つのカーネルリリースとも互換性があります。

OTA アップデートによって KMI バージョンを下げることはできません。

サブレベル

サブレベルの y は、同じ KMI バージョン内のカーネルリリースのリリース順序を表します。

KMI バージョンが同じで、サブレベルがそれぞれ Y1 と Y2 である 2 つのカーネルリリースの場合、次のようになります。

Y1 が Y2 以下の場合、Y1 を搭載したデバイスは Y2 のアップデートを受信できます。
Y1 が Y2 より大きい場合、Y1 を搭載したデバイスは Y2 にアップデートできません。

つまり、KMI バージョンが変わらない場合、OTA アップデートによってサブレベルを下げることはできません。

デバイスでカーネルリリースを確認する

完全なカーネルリリースを確認するには、uname -r を実行するか、または次のコードスニペットで uname(2) を実行します。

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

出力例:

5.4.42-android12-0-00544-ged21d463f856

このドキュメントでは、KMI 世代の後ろの情報はすべて、カーネル情報の抽出時に無視します。より正式には、uname -r の出力は次の正規表現で解析されます（zzz が常に「android」で始まる場合）。

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

無視される情報には、ci.android.com のビルド番号、ベースラインカーネル上のパッチの数、git commit の SHA ハッシュなどがあります。

libkver

ライブラリ libkver には、カーネルリリースや KMI バージョンの文字列を解析するための C++ インターフェースが用意されています。libkver が公開する API のリストについては、packages/modules/Gki/libkver/include/kver をご覧ください。

VINTF チェック

Android 11 以前の場合、KMI バージョンの Android リリース部分は、デバイスメーカーがデバイスマニフェストで手動で指定します。詳細については、VINTF カーネルのマッチングルールをご覧ください。

Android S 以降では、KMI バージョンの Android リリース部分をカーネルから抽出して、ビルド時にデバイスマニフェストに挿入できます。

通常はカーネル構成要件を変更することはないため、互換性マトリックス内で k をエンコードする必要はありません。ただし、万が一カーネル構成要件を変更する必要がある場合は、次の点を確認してください。

互換性マトリックスから対応する要件が削除されている。
KMI 世代を条件とする新しい要件をチェックするための VTS テストが追加されている。

OTA メタデータ内のブートイメージバージョン

ブートイメージが OTA アップデートにより更新された場合でも、OTA ペイロード形式 payload.bin でラップする必要があります。OTA ペイロードは、各パーティションの version フィールドをエンコードします。update_engine は、OTA ペイロードを処理するときに、このフィールドを比較して、パーティションがダウングレードされないようにします。

混乱を避けるために、OTA メタデータのブートパーティションの version フィールドは boot image version と呼ばれます。

RAM ディスクは常にゼロから作成されるため、RAM ディスクのタイムスタンプを使用するだけでブートイメージ全体を記述できます。将来的に古いブートイメージを新しいカーネルバイナリに合成する場合を除き、ブートイメージバージョンでカーネルリリースをエンコードする必要はありません。

OTA アップデートの前に、OTA クライアントは他のパーティションと同じ方法でブートイメージのバージョンをチェックします。

GKI のバージョニング スキーム