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