1The Recovery Image
2==================
3
4Quick turn-around testing
5-------------------------
6
7* Devices using recovery-as-boot (e.g. Pixels, which set BOARD\_USES\_RECOVERY\_AS\_BOOT)
8
9      # After setting up environment and lunch.
10      m -j bootimage
11      adb reboot bootloader
12
13      # Pixel devices don't support booting into recovery mode with `fastboot boot`.
14      fastboot flash boot
15
16      # Manually choose `Recovery mode` from bootloader menu.
17
18* Devices with a separate recovery image (e.g. Nexus)
19
20      # After setting up environment and lunch.
21      mm -j && m ramdisk-nodeps && m recoveryimage-nodeps
22      adb reboot bootloader
23
24      # To boot into the new recovery image without flashing the recovery partition:
25      fastboot boot $ANDROID_PRODUCT_OUT/recovery.img
26
27Running the tests
28-----------------
29
30    # After setting up environment and lunch.
31    mmma -j bootable/recovery
32
33    # Running the tests on device (under normal boot).
34    adb root
35    adb sync data
36
37    # 32-bit device
38    adb shell /data/nativetest/recovery_unit_test/recovery_unit_test
39
40    # Or 64-bit device
41    adb shell /data/nativetest64/recovery_unit_test/recovery_unit_test
42
43Running the manual tests
44------------------------
45
46`recovery-refresh` and `recovery-persist` executables exist only on systems without
47/cache partition. And we need to follow special steps to run tests for them.
48
49- Execute the test on an A/B device first. The test should fail but it will log
50  some contents to pmsg.
51
52- Reboot the device immediately and run the test again. The test should save the
53  contents of pmsg buffer into /data/misc/recovery/inject.txt. Test will pass if
54  this file has expected contents.
55
56Using `adb` under recovery
57--------------------------
58
59When running recovery image from debuggable builds (i.e. `-eng` or `-userdebug` build variants, or
60`ro.debuggable=1` in `/prop.default`), `adbd` service is enabled and started by default, which
61allows `adb` communication. A device should be listed under `adb devices`, either in `recovery` or
62`sideload` state.
63
64    $ adb devices
65    List of devices attached
66    1234567890abcdef    recovery
67
68Although `/system/bin/adbd` is built from the same code base as the one in the normal boot, only a
69subset of `adb` commands are meaningful under recovery, such as `adb root`, `adb shell`, `adb push`,
70`adb pull` etc. Since Android Q, `adb shell` no longer requires manually mounting `/system` from
71recovery menu.
72
73## Troubleshooting
74
75### `adb devices` doesn't show the device.
76
77    $ adb devices
78    List of devices attached
79
80 * Ensure `adbd` is built and running.
81
82By default, `adbd` is always included into recovery image, as `/system/bin/adbd`. `init` starts
83`adbd` service automatically only in debuggable builds. This behavior is controlled by the recovery
84specific `/init.rc`, whose source code is at `bootable/recovery/etc/init.rc`.
85
86The best way to confirm a running `adbd` is by checking the serial output, which shows a service
87start log as below.
88
89    [   18.961986] c1      1 init: starting service 'adbd'...
90
91 * Ensure USB gadget has been enabled.
92
93If `adbd` service has been started but device not shown under `adb devices`, use `lsusb(8)` (on
94host) to check if the device is visible to the host.
95
96`bootable/recovery/etc/init.rc` disables Android USB gadget (via sysfs) as part of the `fs` action
97trigger, and will only re-enable it in debuggable builds (the `on property` rule will always run
98_after_ `on fs`).
99
100    on fs
101        write /sys/class/android_usb/android0/enable 0
102
103    # Always start adbd on userdebug and eng builds
104    on property:ro.debuggable=1
105        write /sys/class/android_usb/android0/enable 1
106        start adbd
107
108If device is using [configfs](https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt),
109check if configfs has been properly set up in init rc scripts. See the [example
110configuration](https://android.googlesource.com/device/google/wahoo/+/master/init.recovery.hardware.rc)
111for Pixel 2 devices. Note that the flag set via sysfs (i.e. the one above) is no-op when using
112configfs.
113
114### `adb devices` shows the device, but in `unauthorized` state.
115
116    $ adb devices
117    List of devices attached
118    1234567890abcdef    unauthorized
119
120recovery image doesn't honor the USB debugging toggle and the authorizations added under normal boot
121(because such authorization data stays in /data, which recovery doesn't mount), nor does it support
122authorizing a host device under recovery. We can use one of the following options instead.
123
124 * **Option 1 (Recommended):** Authorize a host device with adb vendor keys.
125
126For debuggable builds, an RSA keypair can be used to authorize a host device that has the private
127key. The public key, defined via `PRODUCT_ADB_KEYS`, will be copied to `/adb_keys`. When starting
128the host-side `adbd`, make sure the filename (or the directory) of the matching private key has been
129added to `$ADB_VENDOR_KEYS`.
130
131    $ export ADB_VENDOR_KEYS=/path/to/adb/private/key
132    $ adb kill-server
133    $ adb devices
134
135`-user` builds filter out `PRODUCT_ADB_KEYS`, so no `/adb_keys` will be included there.
136
137Note that this mechanism applies to both of normal boot and recovery modes.
138
139 * **Option 2:** Allow `adbd` to connect without authentication.
140   * `adbd` is compiled with `ALLOW_ADBD_NO_AUTH` (only on debuggable builds).
141   * `ro.adb.secure` has a value of `0`.
142
143Both of the two conditions need to be satisfied. Although `ro.adb.secure` is a runtime property, its
144value is set at build time (written into `/prop.default`). It defaults to `1` on `-user` builds, and
145`0` for other build variants. The value is overridable via `PRODUCT_DEFAULT_PROPERTY_OVERRIDES`.
146