使用调试 ramdisk 进行 VTS 测试

从 Android 10 开始，用于运行 CTS-on-GSI/VTS 合规性测试的通用系统映像 (GSI) 从 userdebug build 类型改成了 user build 类型，以便进行版本签名。这会给 VTS 测试带来问题，因为 VTS 需要 adb root 才能运行，但 user build 设备并不支持 adb root。

为此，我们引入了调试 ramdisk（即调试启动映像），以便在引导加载程序已解锁的 user build 设备上启用 adb root。这样就可以为 CTS-on-GSI 和 VTS-on-GSI 使用相同的 user build GSI system.img，从而简化测试流程。对于 STS 设置，仍需使用另一个 userdebug OEM system.img。

下表显示了 Android 10 中的合规性测试所需的映像和 build 类型变更。

测试套件 测试所用的 buildbuild 类型调试 ramdisk是否运行 adb root？ Android 9 -> 10 build 变体变化
CTS OEM 的系统 用户 否 否 没有变化
CTS-on-GSI GSI 用户 否 否

userdebug -> 用户 GSI

已进行版本签名
STS OEM 的系统 userdebug 否 是 Q 中新增
VTS GSI 用户 是 是

userdebug -> 用户 GSI

已进行版本签名

概览

这些附加的映像文件是在 build 文件夹 (${ANDROID_PRODUCT_OUT}) 下生成的：

  • boot-debug.img
  • vendor_boot-debug.img

将 boot-debug.img 刷写到设备的 boot 分区上时，系统会加载 userdebug 版本的系统 sepolicy 文件和一个附加的属性文件 adb_debug.prop。这样就可以在 user build system.img（GSI 或 OEM 的系统映像）中运行 adb root。

对于使用具有 vendor_boot 分区的设备的通用内核映像 (GKI)，则不得刷写 boot-debug.img，因为 boot 分区必须使用经过认证的 GKI 映像进行刷写。 您应改为将 vendor_boot-debug.img 刷写到 vendor_boot 分区上，以方便调试 ramdisk。

使用调试 ramdisk 的先决条件

调试 ramdisk 由运行合规性测试的 OEM 提供。它不得进行版本签名，并且只能在设备处于解锁状态时使用。

在以下情况下，系统不会为升级设备而生成或使用调试 ramdisk：

  • BOARD_BUILD_SYSTEM_ROOT_IMAGE true
  • 内核命令行中的 skip_initramfs

Android 12 GSI

无需任何额外说明，即可将调试 ramdisk 与 Android 12 GSI 搭配使用。

从 2021 年 9 月 29 日开始，调试 ramdisk 不再需要使用 repack_bootimg 工具进行更新。SGR1.210929.001 (7777720) 之后的 Android 12 GSI build 会在其 system.img 中纳入最新的 userdebug_plat_sepolicy.cil 文件，并忽略调试 ramdisk 中的 userdebug_plat_sepolicy.cil。如需了解详情，请参阅变更列表。

Android 11 GSI

使用 boot-debug.img 或 vendor_boot-debug.img 时，系统将从 boot-debug.img 或 vendor_boot-debug.img 的调试 ramdisk 中的 userdebug_plat_sepolicy.cil 文件加载系统 sepolicy。为了启动 GSI 映像，请始终采用来自 android11-gsi 分支的最新 sepolicy 变更来重新构建 boot-debug.img 或 vendor_boot-debug.img。

或者，您也可以使用 repack_bootimg 工具通过更新后的 GSI sepolicy 来重新构建 boot-debug.img 或 vendor_boot-debug.img。

重新打包调试 ramdisk

合作伙伴可以使用 repack_bootimg 将 GSI sepolicy 文件更新到 boot-debug.img（在设备使用 GKI 的情况下更新到 vendor_boot-debug.img），而无需采用 sepolicy 变更来重新构建 boot-debug.img。

相关步骤如下：

  1. 从 https://ci.android.com 下载 otatools.zip。我们建议在 aosp-main 上从 aosp_arm64-userdebug 的 build 工件中下载。

  2. 为 repack_bootimg 设置执行环境：

    unzip otatools.zip -d otatools
export PATH="${PWD}/otatools/bin:${PATH}"
repack_bootimg --help

  3. 从您正在使用的 GSI build 下载 userdebug_plat_sepolicy.cil 或 boot-with-debug-ramdisk-${KERNEL_VERSION}.img。例如，如果您使用的是来自 RJR1.211020.001 (7840830) 的 arm64 GSI，则从 https://ci.android.com/builds/submitted/7840830/aosp_arm64-user/latest 下载。

  4. 使用 userdebug_plat_sepolicy.cil 更新设备 boot-debug.img 或 vendor_boot-debug.img：

    repack_bootimg --local --dst_bootimg boot-debug.img \
    --ramdisk_add userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
    --ramdisk_add userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil
# If using GKI
repack_bootimg --local --dst_bootimg vendor_boot-debug.img \
    --ramdisk_add userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
    --ramdisk_add userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil

    使用 boot-with-debug-ramdisk-${KERNEL_VERSION}.img 进行更新：

    repack_bootimg --src_bootimg boot-with-debug-ramdisk-5.4.img \
    --dst_bootimg boot-debug.img \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil
# If using GKI
repack_bootimg --src_bootimg boot-with-debug-ramdisk-5.4.img \
    --dst_bootimg vendor_boot-debug.img \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil

    您可以根据设备配置来调整 --ramdisk_add 的参数。如需查看详细说明，请参阅下一部分。

userdebug sepolicy 的路径

上述 repack_bootimg 文件会将文件 userdebug_plat_sepolicy.cil 从 --src_bootimg 的 ramdisk 复制到 --dst_bootimg 的 ramdisk。但是，调试 ramdisk 中的路径可能因 Android 版本的不同而异。在 Android 10 和 11 中，若内核命令行中存在 androidboot.force_normal_boot=1，则设备的路径为 first_stage_ramdisk/userdebug_plat_sepolicy.cil。否则，路径为 userdebug_plat_sepolicy.cil。

运行以下命令以检查内核命令行中是否存在 androidboot.force_normal_boot：

adb root
adb shell cat /proc/cmdline | grep force_normal_boot

从 Android 12 开始，无论内核命令行中是否存在 androidboot.force_normal_boot=1，调试 ramdisk 中的路径始终为 userdebug_plat_sepolicy.cil。下表显示了不同 Android 版本中调试 ramdisk 中的路径。

调试映像 Android 10 Android 11 Android 12
GKI boot-with-debug-ramdisk-${KERNEL_VERSION}.img 不适用 first_stage_ramdisk/userdebug_plat_sepolicy.cil userdebug_plat_sepolicy.cil
设备专用的 boot-debug.img 取决于 force_normal_boot 取决于 force_normal_boot userdebug_plat_sepolicy.cil
设备专用的 vendor_boot-debug.img 不适用 取决于 force_normal_boot userdebug_plat_sepolicy.cil

您可以通过指定 --ramdisk_add 来复制文件，借助 src_path:dst_path 对列表，可以为文件复制指定不同的源和目标路径。例如，以下命令会将 Android 11 boot-with-debug-ramdisk-5.4.img 中的文件 first_stage_ramdisk/userdebug_plat_sepolicy.cil 复制到 Android 11 vendor_boot-debug.img 内的 first_stage_ramdisk/userdebug_plat_sepolicy.cil 中。

repack_bootimg \
    --src_bootimg boot-with-debug-ramdisk-5.4.img \
    --dst_bootimg vendor_boot-debug.img \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil

如果内核命令行中没有 androidboot.force_normal_boot=1，应按如下方式调整命令，以将目的地路径更改为 userdebug_plat_sepolicy.cil。

repack_bootimg \
    --src_bootimg boot-with-debug-ramdisk-5.4.img \
    --dst_bootimg vendor_boot-debug.img \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil

如果传递给 --dst_bootimg 的映像被配置为 AVB 链式分区，则需要在运行 repack_bootimg 命令后添加 AVB 页脚。

例如，在运行 repack_bootimg 之前，请运行以下命令来检查 vendor_boot-debug.img 是否具有链式 AVB 页脚。

avbtool info_image --image vendor_boot-debug.img

如果它最初具有链式 AVB 页脚，则需要在运行 repack_bootimg 命令之后添加 AVB 页脚。可以使用任何测试密钥为 vendor_boot-debug.img 签名，因为只有在设备解锁后才可以使用调试 ramdisk，这样便可以在 boot 或 vendor_boot 分区中使用通过非发布密钥签名的映像。

avbtool add_hash_footer --partition_name vendor_boot \
    --partition_size 100663296 \
    --algorithm SHA256_RSA4096 \
    --key otatools/external/avb/test/data/testkey_rsa4096.pem \
    --image vendor_boot-debug.img