Chrome OS RMA shim

RMAは「Return Merchandise Authorization（返品承認）」の略です。これは、エンドユーザーが解決できない問題がデバイスに発生し、ユーザーが診断と修理のためにデバイスをサービスセンターへ返送することを選択した場合に行われます。

一般的に、Chrome OSの検証済みブートと書き込み保護の仕組みにより、Googleの署名がない診断ツールや修理プログラムをサービスセンターで実行することは困難です。これらの問題を回避するために、修理パートナーにはRMA shimが必要となります。このツールはGoogleによって署名されており、パートナーが独自のカスタム診断プログラムを実行してコンポーネントをチェックおよび検証できるようになります。

shimのイメージは、既存のChrome OS factory bundleのコンポーネントを組み合わせたものであり、以下が含まれています。

• Factory install shim
• リリースイメージ（FSI）
• テストイメージ
• ファクトリーツールキット
• HWIDバンドル
• その他のオプションコンポーネント（ファームウェア、完了スクリプトなど）

通常の信号基板RMA shimは非常に便利ですが、マザーボードのモデルごとに固有であるという問題があります。これにより、物理的なUSBドライブ上のshimイメージを管理することが困難になる場合があります。

この問題は、ユニバーサル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_mode」の有効化といった一般的なRMA設定が処理され、さらに工場テストが「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に設定されている場合、これは真である必要があります）。

バンドルコンポーネントの準備ができたら、それらを単一のRMA shimイメージに結合できます。RMA shimイメージは、「image_tool rma create」コマンドを使用してファクトリーバンドルから作成できます。

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

「ram_image.bin」をUSBドライブにフラッシュし、デベロッパーモードを有効にし、デバイスをリカバリーモードにして起動します。

「dd」コマンドを使用してshimイメージをストレージデバイスにフラッシュします。「/dev/sdx」はご使用のストレージデバイス名に置き換えてください。

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

デバイス上にOS開発環境がある場合は、chroot内で「cross 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」を押してカーソルを「Confirm Disabling OS Verification（OS検証の無効化を確認）」に合わせ、「POWER」を押して選択します。
4. 再度リカバリーモードに入ります（ワイプされるのを待つ必要はありません）。
5. 「rma_image.bin」が入ったUSBメモリを挿入して起動します。

RMA shimには、ユーザーがさまざまなアクションを選択できるメニューがあり、その詳細はREADMEファイルに記載されています。「image_tool rma create」コマンドを使用してユーザーがRMA shimを作成した場合、ツールは「lab-factory」ファイルにフラグ「RMA_AUTORUN=1」を追加します。これにより、メニュー内のデフォルトアクションが設定されます。

RMA shimの検証や修正を簡単にするその他の「image_tool」コマンドがあります。詳細な説明は、他のコマンドで「--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」コマンドで、「RMA_AUTORUN」フラグなどの「lsb-factory」設定を修正できます。

$ 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」コマンドで、アクティブなテストリストやカットオフ設定などのツールキット設定を修正できます。

$ 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ドキュメント