Chrome OS RMA shim

RMA 代表退货授权 (Return Merchandise Authorization)。当设备出现最终用户无法解决的问题，且用户选择将设备退回设备维修中心进行诊断和维修时，就会用到此流程。

通常情况下，由于 Chrome OS 的验证启动和写保护机制，维修中心难以运行任何未经 Google 签名的诊断工具或维修程序。为了绕过这些问题，维修合作伙伴需要一个 RMA shim。此工具由 Google 签名，允许合作伙伴运行其自定义的诊断程序来检查和验证组件。

shim 镜像被设计为预先存在的 Chrome OS 工厂捆绑包 组件的组合，并包含以下内容：

• 工厂安装 shim
• 发布版本镜像 (FSI)
• 测试镜像
• 工厂工具套装
• HWID 捆绑包
• 其他可选组件（固件、完整脚本等）

虽然常规单板 RMA shim 非常有用，但它的问题在于它们是针对特定主板型号的。这会使在物理 USB 驱动器上管理 shim 镜像变得困难。

这个问题可以通过创建通用 (Universal) shim 来解决。通用 shim 可以包含针对不同主板的多个 RMA shim，从而更容易管理和分发这些镜像。

这样做的权衡是通用 shim 可能会非常大，因为每个主板的 shim 大约需要 3 GB 的存储空间。因此，一个包含 3 个主板的通用 shim 总大小将达到 9 到 10 GB。

image_tool 是管理 RMA shim 所需的程序。可以使用以下命令从工厂公共存储库下载该程序。

$ git clone https://chromium.googlesource.com/chromiumos/platform/factory
$ cd factory\/

该工具位于 setup\/image_tool 中。强烈建议用户定期同步 git 存储库，以确保获得最新版本。可以使用以下命令完成此操作...

$ git pull

下载工厂存储库后，你可以运行 RMA 命令的单元测试，通过以下命令确保命令在你的机器上正确运行...

$ py\/tools\/image_tool_rma_unittest.py

RMA 测试列表与工厂生产线使用的测试列表不同。例如，RMA 过程中不会有工厂服务器。这就是为什么我们需要一个单独的 RMA 测试列表。

建议的测试列表创建流程是创建一个继承自 generic_rma.test_list.json 的列表。这应该能处理常规的 RMA 设置，如禁用工厂服务器和启用 rma_mode，并将工厂测试添加到 RMAFFT 组中。

{
  "inherit": [
    "generic_rma.test_list"
  ],
  "label": "RMA Test List for <project>",
  "definitions": {
    "RMAFFT": {
      "subtests": [
        ...
        ...
      ]
    }
  }
}

还建议更改以下设置...

• 维修中心的工厂测试应以减少的测试周期运行。例如，将压力测试的持续时间从 4 小时减少到 10 分钟。
• 验证维修中心使用的所有备用主板均已完成 SMT 测试。
• 在将主板发送到维修中心之前，验证所有备用主板是否具有在工厂流程中烧录到 RW_VPD 中的注册码。
• 与 OEM 讨论并确定 RMA 流程的测试项目。
• 不要修改或删除任何 GRT（Google 强制测试）项目。
• 确保固件写保护已启用（如果 constants.phase 设置为 PVT，则应为 true）。

准备好捆绑包组件后，你可以将这些组件合并为一个 RMA shim 镜像。可以通过使用 image_tool rma create 命令从工厂捆绑包创建 RMA shim 镜像：

$ setup\/image_tool rma create 
    --board BOARD
    --factory_shim path\/to\/factory_install_shim.bin 
    --test_image path\/to\/chromiumos_test_image.bin 
    --toolkit path\/to\/install_factory_toolkit.run 
    --release_image path\/to\/chromiumos_image.bin 
    --hwid path\/to\/hwid_bundle.sh 
    --output rma_image.bin

如果所有组件都放入了它们各自的 捆绑包 目录（release_image\/, test_image\/ 等）中，则命令可以简化为：

$ setup\/image_tool rma create
      --board BOARD
      --output rma_image.bin

此外，我们在创建 RMA shim 时还可以指定活动测试列表。这样我们就无需在工厂工具中修改 active_test_list.json。

$ setup\/image_tool rma create
     --board BOARD
     --output rma_image.bin
     --active_test_list rma_main

我们可以通过使用 image_tool rma merge 命令来创建通用 RMA shim。

$ setup\/image_tool rma merge 
    -i soraka.bin scarlet.bin 
    -o universal.bin

要删除先前生成的输出镜像，你需要指定 -f 选项：

$ setup\/image_tool rma merge 
    -i soraka.bin scarlet.bin 
    -o universal.bin -f

image_tool rma merge 命令支持合并通用 shim。如果有任何重复的主板，系统会询问用户希望使用哪个主板。此功能可用于使用更新后的单板 RMA shim 来更新通用 shim 中的主板。

$ setup\/image_tool rma merge 
    -i universal.bin soraka_new.bin 
    -o universal_new.bin
Scanning 2 input image files...

Board soraka has more than one entry.
========================================================================
(1)
From universal.bin
board         : soraka
install_shim  : 10323.39.28
release_image : 10575.37.0 (Official Build) dev-channel soraka
test_image    : 10323.39.24 (Official Build) dev-channel soraka test
toolkit       : soraka Factory Toolkit 10323.39.24
firmware      : Google_Soraka.10431.32.0;Google_Soraka.10431.48.0
hwid          : None
complete      : None
toolkit_config: None
lsb_factory   : lsb_factory
========================================================================
(2)
From soraka_new.bin
board         : soraka
install_shim  : 10323.39.31
release_image : 10575.37.0 (Official Build) dev-channel soraka
test_image    : 10323.39.24 (Official Build) dev-channel soraka test
toolkit       : soraka Factory Toolkit 10323.39.24
firmware      : Google_Soraka.10431.32.0;Google_Soraka.10431.48.0
hwid          : None
complete      : None
toolkit_config: None
lsb_factory   : lsb_factory
========================================================================
Please select an option [1-2]:

将 rma_image.bin 烧录到 USB 驱动器，并按照 启用开发者模式并使设备进入恢复模式 启动它。

使用 dd 命令将 shim 镜像烧录到你的存储设备，将 \/dev\/sdx 替换为你的存储设备名称。

$ sudo dd if=rma_image.bin of=\/dev\/sdX bs=8M iflag=fullblock oflag=dsync

如果你的设备上有 操作系统开发环境，则可以在 chroot 中使用 ``cros flash`` 命令。

$ cros flash usb:\/\/ rma_image.bin

1. 进入恢复模式。
2. 按 CTRL + D 打开开发者开关。
3. 按 ENTER 键确认。
4. 再次进入恢复模式（无需等待擦除）。
5. 插入含有 rma_image.bin 的 USB 盘并从中启动。

1. 进入恢复模式。
2. 按 VOL_UP + VOL_DOWN 显示恢复菜单。
3. 按 VOL_UP 或 VOL_DOWN 将光标移至“确认禁用操作系统验证”，然后按 POWER 键进行选择。
4. 再次进入恢复模式（无需等待擦除）。
5. 插入含有 rma_image.bin 的 USB 盘并从中启动。

RMA shim 有一个菜单，允许用户选择不同的操作，这些操作记录在 README 文件中。如果用户通过 image_tool rma create 命令创建 RMA shim，该工具会将 RMA_AUTORUN=1 标志添加到 lab-factory 文件中。这将设置菜单中的默认操作。

还有其他 image_tool 命令可以使验证和修改 RMA shim 变得更容易。可以使用其他命令的 --help 参数找到详细描述。例如...

$ setup\/image_tool rma show --help

image_tool rma show 命令可以打印 RMA shim 中的组件版本

$ setup\/image_tool rma show -i soraka.bin
This RMA shim contains boards: soraka
========================================================================
board         : soraka
install_shim  : 10323.39.31
release_image : 10575.37.0 (Official Build) dev-channel soraka
test_image    : 10323.39.24 (Official Build) dev-channel soraka test
toolkit       : soraka Factory Toolkit 10323.39.24
firmware      : Google_Soraka.10431.32.0;Google_Soraka.10431.48.0
hwid          : None
complete      : None
toolkit_config: cb5b52296cd4fcb0418b6879c0acc32b
lsb_factory   : d2c9d6a7d32ee3b1279c2b0b27244727
========================================================================

同样的命令也可以用于通用 RMA shim。

$ setup\/image_tool rma show -i universal.bin
This RMA shim contains boards: soraka scarlet
========================================================================
board         : soraka
install_shim  : 10323.39.31
release_image : 10575.37.0 (Official Build) dev-channel soraka
test_image    : 10323.39.24 (Official Build) dev-channel soraka test
toolkit       : soraka Factory Toolkit 10323.39.24
firmware      : Google_Soraka.10431.32.0;Google_Soraka.10431.48.0
hwid          : None
complete      : None
toolkit_config: cb5b52296cd4fcb0418b6879c0acc32b
lsb_factory   : d2c9d6a7d32ee3b1279c2b0b27244727
========================================================================
board         : scarlet
install_shim  : 10211.68.0
release_image : 10575.67.0 (Official Build) stable-channel scarlet
test_image    : 10211.53.0 (Official Build) dev-channel scarlet test
toolkit       : scarlet Factory Toolkit 10211.53.0
firmware      : Google_Scarlet.10388.26.0
hwid          : None
complete      : None
toolkit_config: None
lsb_factory   : c82d4c1f831bf20d7cdc70138fe4ef72
========================================================================

image_tool rma replace 命令可以替换 RMA shim 中的组件。例如，你可以用一个新的 HWID 捆绑包替换现有的：

$ setup\/image_tool rma replace -i rma_image.bin --hwid new_hwid_bundle.sh

如果你想在通用 shim 上进行替换，则需要 --board 参数。

$ setup\/image_tool rma replace -i universal.bin
    --board soraka --hwid new_hwid_bundle.sh

此命令还可以替换 release_image, test_image, toolkit, factory_shim, firmware, hwid, complete_script 和 toolkit_config。

image_tool rma extract 命令可用于从通用 shim 中提取单板 RMA shim。

$ setup\/image_tool rma extract -i universal.bin -o extract.bin
Scanning input image file...

Please select a board to extract.
========================================================================
(1)
board         : soraka
install_shim  : 10323.39.31
release_image : 10575.37.0 (Official Build) dev-channel soraka
test_image    : 10323.39.24 (Official Build) dev-channel soraka test
toolkit       : soraka Factory Toolkit 10323.39.24
firmware      : Google_Soraka.10431.32.0;Google_Soraka.10431.48.0
hwid          : None
complete      : None
toolkit_config: cb5b52296cd4fcb0418b6879c0acc32b
lsb_factory   : d2c9d6a7d32ee3b1279c2b0b27244727
========================================================================
(2)
board         : scarlet
install_shim  : 10211.68.0
release_image : 10575.67.0 (Official Build) stable-channel scarlet
test_image    : 10211.53.0 (Official Build) dev-channel scarlet test
toolkit       : scarlet Factory Toolkit 10211.53.0
firmware      : Google_Scarlet.10388.26.0
hwid          : None
complete      : None
toolkit_config: None
lsb_factory   : c82d4c1f831bf20d7cdc70138fe4ef72
========================================================================
Please select an option [1-2]:

image_tool edit_lsb 命令可以修改 lsb-factory 配置，例如 RMA_AUTORUN 标志。

$ setup\/image_tool edit_lsb -i rma_image.bin

Current LSB config:
========================================================================
CHROMEOS_AUSERVER=http://...
CHROMEOS_DEVSERVER=http://...
FACTORY_INSTALL=1
HTTP_SERVER_OVERRIDE=true
FACTORY_INSTALL_FROM_USB=1
RMA_AUTORUN=true
========================================================================
(1) Modify Chrome OS Factory Server address.
(2) Modify cutoff config in cros payload (only for old devices).
(3) Enable\/disable complete prompt in RMA shim.
(4) Enable\/disable autorun in RMA shim.
(q) Quit without saving changes.
(w) Apply changes and exit.
Please select an option [1-4, q, w]:

此外，你可以使用

$ setup\/image_tool edit_lsb -i universal.bin --board soraka

image_tool edit_toolkit_config 命令可以修改工具套装配置，例如活动测试列表和 cutoff 配置。

$ setup\/image_tool edit_toolkit_config -i rma_image.bin

Toolkit config:
========================================================================
{
  "cutoff": {
    "CUTOFF_BATTERY_MAX_PERCENTAGE": 90,
    "CUTOFF_BATTERY_MIN_PERCENTAGE": 60,
    "CUTOFF_METHOD": "battery_cutoff",
    "CUTOFF_AC_STATE": "remove_ac"
  },
  "active_test_list": {
    "id": "main_rma"
  }
}
========================================================================
(1) Modify active test list.
(2) Modify test list constants.
(3) Modify cutoff config.
(q) Quit without saving changes.
(w) Apply changes and exit.
Please select an option [1-3, q, w]:

此外，你可以使用

$ setup\/image_tool edit_toolkit_config -i universal.bin --board soraka

image_tool payload toolkit 命令可以解包和重新打包 RMA shim 中的工厂工具套装。

$ setup\/image_tool payload toolkit -i rma_image.bin --unpack toolkit_path
(Edit some files in toolkit_path\/ ...)
$ setup\/image_tool payload toolkit -i rma_image.bin --repack toolkit_path

或者

$ setup\/image_tool payload toolkit 
    -i universal.bin --board soraka --unpack toolkit_path
(Edit some files in toolkit_path\/ ...)
$ setup\/image_tool payload toolkit 
    -i universal.bin --board soraka --repack toolkit_path

• 官方 Chrome OS RMA Shim 文档