Chrome OS RMA-Shim

RMA steht für Return Merchandise Authorization (Warenrücksendegenehmigung). Dies ist der Fall, wenn bei einem Gerät ein Problem auftritt, das nicht vom Endnutzer gelöst werden kann, und der Nutzer das Gerät zur Diagnose und Reparatur an das Servicecenter des Herstellers einsendet.

Normalerweise ist es für ein Servicecenter schwierig, Diagnosewerkzeuge oder Reparaturprogramme auszuführen, die nicht von Google signiert sind, da Chrome OS über einen verifizierten Boot-Vorgang und einen Schreibschutz verfügt. Um diese Probleme zu umgehen, benötigt der Reparaturpartner einen RMA-Shim. Dieses Werkzeug ist von Google signiert und ermöglicht es einem Partner, eigene benutzerdefinierte Diagnoseprogramme auszuführen, um Komponenten zu prüfen und zu verifizieren.

Das Image des Shims ist so konzipiert, dass es eine Kombination aus bereits existierenden Chrome OS Factory-Bundles darstellt und Folgendes umfasst:

• Factory-Installations-Shim
• Release-Image (FSI)
• Test-Image
• Factory-Toolkit
• HWID-Bundle
• Weitere optionale Komponenten (Firmware, vollständiges Skript usw.)

Obwohl sie äußerst nützlich sind, besteht das Problem bei regulären Signalboard-RMA-Shims darin, dass sie spezifisch für das Modell der Hauptplatine sind. Dies kann die Verwaltung von Shim-Images auf physischen USB-Laufwerken erschweren.

Dieses Problem kann durch das Erstellen eines Universal-Shims gelöst werden. Ein Universal-Shim kann mehrere RMA-Shims für verschiedene Platinen enthalten, was die Verwaltung und Verteilung der Images vereinfacht.

Der Kompromiss dabei ist, dass die Universal-Shims recht groß sein können, da der Shim für jede Platine etwa 3 GB Speicher benötigt. Ein Universal-Shim, der 3 Platinen enthält, benötigt also eine Gesamtgröße von 9–10 GB.

image_tool ist das Programm, das für die Verwaltung von RMA-Shims benötigt wird. Dieses kann aus dem öffentlichen Factory-Repository mit den folgenden Befehlen heruntergeladen werden.

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

Das Werkzeug befindet sich in setup/image_tool. Es wird dringend empfohlen, dass der Nutzer das Git-Repository regelmäßig synchronisiert, um sicherzustellen, dass die neueste Version verwendet wird. Dies kann mit dem folgenden Befehl durchgeführt werden...

$ git pull

Sobald das Factory-Repository heruntergeladen wurde, kannst du den Unit-Test für die RMA-Befehle ausführen, um sicherzustellen, dass die Befehle korrekt auf deinem Computer laufen, indem du Folgendes verwendest...

$ py/tools/image_tool_rma_unittest.py

Die RMA-Testliste unterscheidet sich von der Testliste, die in der Factory-Fertigungslinie verwendet wird. Zum Beispiel gibt es während des RMA-Prozesses keinen Factory-Server. Deshalb benötigen wir eine andere Testliste für die RMA.

Der empfohlene Prozess zum Erstellen einer Testliste besteht darin, eine Liste zu erstellen, die von generic_rma.test_list.json erbt. Dies sollte die allgemeinen RMA-Einstellungen abdecken, wie z. B. das Deaktivieren des Factory-Servers und das Aktivieren von rma_mode, zusammen mit dem Hinzufügen der Factory-Tests zur RMAFFT-Gruppe.

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

Es wird außerdem empfohlen, die folgenden Einstellungen zu ändern...

• Factory-Tests in Servicecentern werden mit reduzierten Testzyklen durchgeführt. Reduziere beispielsweise die Dauer des Stresstests von 4 Stunden auf 10 Minuten.
• Überprüfe, ob alle in Servicecentern verwendeten Ersatz-Hauptplatinen SMT-Tests abschließen.
• Überprüfe, ob alle Ersatz-Hauptplatinen einen Registrierungscode haben, der vor dem Versand an die Servicecenter während des Factory-Prozesses in RW_VPD gebrannt wurde.
• Besprich mit dem OEM die endgültigen Testelemente für den RMA-Prozess.
• Ändere oder entferne nicht irgendwelche GRT-Elemente (Google Required Test).
• Stelle sicher, dass der Firmware-Schreibschutz aktiviert ist (was der Fall sein sollte, wenn constants.phase auf PVT gesetzt ist).

Nachdem die Bundle-Komponenten bereit sind, kannst du sie zu einem einzigen RMA-Shim-Image kombinieren. Das RMA-Shim-Image kann aus dem Factory-Bundle mit dem Befehl image_tool rma create erstellt werden:

$ 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

Der Befehl kann vereinfacht werden, sofern alle Komponenten in ihre entsprechenden Bundle-Verzeichnisse (release_image/, test_image/ usw.) verschoben wurden:

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

Zusätzlich können wir beim Erstellen eines RMA-Shims auch die aktive Testliste angeben. Auf diese Weise müssen wir die active_test_list.json im Factory-Toolkit nicht ändern

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

Wir können einen Universal-RMA-Shim mit dem Befehl image_tool rma merge erstellen.

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

Um ein zuvor generiertes Ausgabe-Image zu löschen, musst du die Option -f angeben:

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

Der Befehl image_tool rma merge unterstützt das Zusammenführen von Universal-Shims. Wenn doppelte Platinen vorhanden sind, wird der Nutzer gefragt, welche Platine er verwenden möchte. Diese Funktion kann verwendet werden, um eine Platine in einem Universal-Shim mithilfe des aktualisierten Einzelplatinen-RMA-Shims zu aktualisieren.

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

Flashe das ram_image.bin auf ein USB-Laufwerk und boote es mit aktiviertem Entwicklermodus und dem Gerät im Wiederherstellungsmodus.

Verwende den dd-Befehl, um das Shim-Image auf dein Speichergerät zu flashen. Ersetze dabei /dev/sdx durch den Namen deines Speichergeräts.

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

Wenn du die OS-Entwicklungsumgebung auf deinem Gerät hast, kannst du den ``cross flash``-Befehl in chroot verwenden.

$ cros flash usb:// rma_image.bin

1. Gehe in den Wiederherstellungsmodus.
2. Drücke STRG + D, um den Entwicklerschalter einzuschalten.
3. Drücke ENTER zum Bestätigen.
4. Gehe erneut in den Wiederherstellungsmodus (es ist nicht nötig, auf das Löschen zu warten).
5. Stecke den USB-Stick mit rma_image.bin ein und boote davon.

1. Gehe in den Wiederherstellungsmodus.
2. Drücke VOL_UP + VOL_DOWN, um das Wiederherstellungsmenü anzuzeigen.
3. Drücke VOL_UP oder VOL_DOWN, um den Cursor auf „Confirm Disabling OS Verification“ zu bewegen, und drücke POWER, um es auszuwählen.
4. Gehe erneut in den Wiederherstellungsmodus (es ist nicht nötig, auf das Löschen zu warten).
5. Stecke den USB-Stick mit rma_image.bin ein und boote davon.

Der RMA-Shim verfügt über ein Menü, das es dem Nutzer ermöglicht, verschiedene Aktionen auszuwählen, die in der README-Datei dokumentiert sind. Wenn ein Nutzer einen RMA-Shim über den Befehl image_tool rma create erstellt, fügt das Werkzeug das Flag RMA_AUTORUN=1 zur lab-factory-Datei hinzu. Dies legt die Standardaktionen im Menü fest.

Es gibt weitere image_tool-Befehle, die das Verifizieren und Ändern deiner RMA-Shims erleichtern können. Detaillierte Beschreibungen findest du mithilfe des --help-Arguments für andere Befehle. Zum Beispiel...

$ setup/image_tool rma show --help

Der Befehl image_tool rma show kann die Komponentenversion in deinem RMA-Shim ausgeben

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

Der gleiche Befehl kann auch für Universal-RMA-Shims verwendet werden.

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

Der Befehl image_tool rma replace kann Komponenten in deinem RMA-Shim ersetzen. Du kannst zum Beispiel das HWID-Bundle durch ein neues ersetzen:

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

Das --board-Argument wird benötigt, wenn du etwas auf einem Universal-Shim ersetzen möchtest.

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

Dieser Befehl kann auch release_image, test_image, toolkit, factory_shim, firmware, hwid, complete_script und toolkit_config ersetzen.

Der Befehl image_tool rma extract kann verwendet werden, um einen Einzelplatinen-RMA-Shim aus deinem Universal-Shim zu extrahieren.

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

Der Befehl image_tool edit_lsb kann die lsb-factory-Konfiguration ändern, wie z. B. das 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]:

zusätzlich kannst du verwenden

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

Der Befehl image_tool edit_toolkit_config kann die Toolkit-Konfiguration ändern, wie z. B. die aktive Testliste und die Cutoff-Konfiguration.

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

zusätzlich kannst du verwenden

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

Der Befehl image_tool payload toolkit kann das Factory-Toolkit in einem RMA-Shim entpacken und neu verpacken.

$ 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

oder

$ 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

• Offizielle Dokumentation für Chrome OS RMA-Shims