GKI 版本控制方案

本文介绍了通用内核映像 (GKI) 的版本控制方案。通用内核映像 (GKI) 具有一个称为内核版本的唯一标识符。内核版本由内核模块接口 (KMI) 版本和子级组成。内核版本特定于所发布的映像,而 KMI 版本表示构建版本所基于的接口。KMI 版本可以支持多个内核版本。 一个内核版本仅与一个 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”。此名称通常也称为“三段式版本号”。VINTF 中所用的术语“内核版本”可能会与其他术语(尤其是“w”)相混淆。

此变量在 libkver 中称为“kernel_version_tuple”。kernel_version_tuple

不得通过任何更新(包括 OTA 或 Mainline)减小此元组。

内核分支 zzz-w.x android12-5.4 这一术语在通用内核分支类型中使用。
版本 w 5 本文档中未使用此术语。此变量在 libkver 中称为“version”。
补丁程序级别 x 4 本文档中未使用此术语。此变量在 libkver 中称为“patch_level”。
Android 版本 zzz android12

这是与内核关联的 Android(dessert)版本号。

比较 AndroidRelease 字段时,系统会从字符串中提取数字部分进行比较。

不得通过任何更新(包括 OTA 或 Mainline)减小 Android 版本号。

KMI 代系 k 0

这是为处理不太可能发生的事件而增加的额外编号。如果某个安全 bug 修复程序需要对同一 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。如果两个 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)。

如果两个内核版本具有相同的 KMI 版本,则它们会实现相同的内核模块接口。与其中一个兼容的 DLKM 也会与另一个兼容。

不得通过任何 OTA 更新降低 KMI 版本。

子级

子级 y 用于描述同一 KMI 版本中内核版本的发布顺序。

对于具有相同 KMI 版本但子级分别为 Y1 和 Y2 的两个内核版本:

  • 如果 Y1 小于或等于 Y2,那么搭载 Y1 的设备可以接收 Y2 更新。
  • 如果 Y1 大于 Y2,那么搭载 Y1 的设备无法更新到 Y2。

也就是说,如果 KMI 版本未更改,就无法通过任何 OTA 更新降低子级。

确定设备的内核版本

通过以下代码段执行 uname -runame(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 build 号、基准内核之上的补丁数量,以及 Git 提交的 SHA 哈希值。

libkver

libkver 库提供了一个用于解析内核版本或 KMI 版本字符串的 C++ 接口。 如需查看 libkver 公开的 API 列表,请参阅 packages/modules/Gki/libkver/include/kver

VINTF 检查

对于 Android 11 或更低版本,KMI 版本的 Android 版本部分由设备制造商在设备清单中手动指定。如需了解详情,请参阅 VINTF 内核匹配规则

从 Android S 开始,可以在构建时从内核提取 KMI 版本的 Android 版本部分并将其注入设备清单中。

由于内核配置要求通常不会更改,因此无需在兼容性矩阵中对 k 进行编码。不过,万一需要更改内核配置要求,请确保以下几点:

  • 从兼容性矩阵中移除相应要求。
  • 添加额外的 VTS 测试,用于检查 KMI 代系方面的新要求。

OTA 元数据中的启动映像版本

即使启动映像通过 OTA 执行更新,也必须以 OTA 载荷格式 payload.bin 进行封装。OTA 载荷会对每个分区的 version 字段进行编码。当 update_engine 处理 OTA 载荷时,它会比较此字段,确保相应分区不会被降级。

为避免混淆,OTA 元数据中 boot 分区的 version 字段称为 boot image version

由于 ramdisk 始终从头开始构建,因此,使用 ramdisk 时间戳就可以充分描述整个启动映像。无需将内核版本编码到启动映像版本,除非您将来要将旧启动映像拼接到新的内核二进制文件中。

在 OTA 更新之前,OTA 客户端会以与任何其他分区相同的方式检查启动映像版本。