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

或者,您也可以使用 repack_bootimg 工具通过更新后的 GSI sepolicy 来重新构建 boot-debug.imgvendor_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.cilboot-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.imgvendor_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,这样便可以在 bootvendor_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