Chrome OS RMA shim

Author: Jacob Mehnert

RMA stands for Return Merchandise Authorization. This is when a problem occurs with a device that cannot be solved by the end user, and the user chooses to return the device to the device's service center for diagnosis and repair.

Typically, it is difficult for a service center to run any kind of diagnostic tools or repair programs that are not signed by Google, due to Chrome OS's verified boot and write protection. To get around these issues the repair partner will need an RMA shim. This tool is signed by Google and allows a partner to run their own custom diagnostic programs to check and verify components.

The shim's image is designed to be a combination of pre-existing Chrome OS factory bundle components, and include the following:

Factory install shim
Release image (FSI)
Test image
Factory toolkit
HWID bundle
Other optional components (firmware, complete script, etc.)

While extremely useful, the problem with regular signal-board RMA shims is that they are specific to the model of mother board. This can make it hard to manage shim images on physical USB drives.

This issue can be solved by creating a Universal shim. A Universal shim can contain multiple RMA shims for different board, making it easier to manage and distribute the images.

The trade off for this is that the universal shims can be quite large, as each boards shim will need around 3 GB of storage. So a universal shim containing 3 boards will need to have a total size of 9 - 10 GB.

image_tool is the program that is needed to manage RMA shims. This can be downloaded from the factory public repository using the following commands.

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

The tool will be located in setup/image_tool. It is highly recommended that a user syncs the git repository periodically to ensure the they get the latest version. This can be done with the following command...

$ git pull

Once the factory repository has been downloaded, you can run the unit test for the RMA commands to make sure that the commands run correctly on your machine by using...

$ py/tools/image_tool_rma_unittest.py

The RMA test list is different from the test list used in factory manufacture line. For example, there won't be a factory server during the RMA process. Which is why we will need a different test list for the RMA.

The recommended process for creating a test list is to create a list that inherits from generic_rma.test_list.json. This should take care of the general RMA settings like disabling the factory server and enabling rma_mode, along with adding the factory tests to RMAFFT group.

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

It is also recommended that the following settings are changed...

Factory tests in the service centers are ran with reduced test cycles. For example, reduce the duration of the stress test from 4 hours to 10 minutes.
Verify that all spare mainboards used in service centers complete SMT tests.
Verify that all spare mainboards have a registration code that was burned into RW_VPD during the factory process before sending the boards to service centers.
Discuss with the OEM to finalize test items for the RMA process.
Do not modify or remove any GRT (Google Required Test) items.
Make sure the firmware write protection is enabled (which should be true if constants.phase is set to PVT).

After the bundle components are ready, you can combine the components into a single RMA shim image. The RMA shim image can be created from the factory bundle by using the image_tool rma create command:

$ 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

The command can be simplified provided that all the components are put into their proper bundle directories (release_image/, test_image/, etc.):

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

In addition, we can also specify the active test list when we create an RMA shim. This way we won't need to modify the active_test_list.json in the factory tool

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

we can create a Universal RMA shim by using the image_tool rma merge command.

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

To delete a previously generated output image, you will need to specify the -f option:

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

the image_tool rma merge command supports the merging of universal shims. If there are any duplicate boards, then the user will be asked which board they wish to use. This feature can be used to update a board in a universal shim using the updated single-board RMA 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]:

Flash the ram_image.bin to a USB drive, and boot it with developer mode enabled, and your device in recovery mode.

Use the dd command to flash the shim image to your storage device, replacing the /dev/sdx with the name of your storage device.

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

If you have the OS development environment on your device, then you can use the ``cross flash`` command in chroot.

$ cros flash usb:// rma_image.bin

Enter recovery mode.
Press CTRL + D to turn on developer switch.
Press ENTER to confirm.
Enter recovery mode again (no need to wait for wiping).
Insert and boot from USB stick with rma_image.bin.

Enter recovery mode.
Press VOL_UP + VOL_DOWN to show recovery menu.
Press VOL_UP or VOL_DOWN to move the cursor to “Confirm Disabling OS Verification”, and press POWER to select it.
Enter recovery mode again (no need to wait for wiping).
Insert and boot from USB stick with rma_image.bin.

The RMA shim has a menu that allows a user to select different actions, which are documented in the README file. If a user creates an RMA shim through the image_tool rma create command, the tool will add the flag RMA_AUTORUN=1 to the lab-factory file. This will set the default actions in the menu.

There are other image_tool commands that can made verifying and modifying your RMA shims easier. Detailed descriptions can be found using the --help argument for other commands. For example...

$ setup/image_tool rma show --help

The image_tool rma show command can print the component version in your 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
========================================================================

The same command can also be used for Universal RMA shims.

$ 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
========================================================================

The image_tool rma replace command can replace components that are in your RMA shim. For example, you can replace the HWID bundle with a new one:

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

The --board argument will be needed if you want to replace something on a Universal shim.

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

This command can also replace release_image, test_image, toolkit, factory_shim, firmware, hwid, complete_script and toolkit_config.

image_tool rma extract command can be used to extract a single-board RMA shim from your universal 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 command can modify lsb-factory config, such as RMA_AUTORUN flag.

$ 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]:

additionally you can use

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

image_tool edit_toolkit_config command can modify toolkit config, such as active test list and cutoff config.

$ 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]:

additionally you can use

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

image_tool payload toolkit command can unpack and repack the factory toolkit in an 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