aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTreehugger Robot2018-02-08 13:20:57 -0600
committerGerrit Code Review2018-02-08 13:20:57 -0600
commit7ee7e27400012c31a78563a8f78a44bdf83d5629 (patch)
tree759323ba478e811935742419e7294da196363c70
parentbded087f7de69fc352c5860659e2db4478b30bdd (diff)
parentc84a4ef0538ca2a8777efea2b09a413d18ed460b (diff)
downloadplatform-bootable-recovery-7ee7e27400012c31a78563a8f78a44bdf83d5629.tar.gz
platform-bootable-recovery-7ee7e27400012c31a78563a8f78a44bdf83d5629.tar.xz
platform-bootable-recovery-7ee7e27400012c31a78563a8f78a44bdf83d5629.zip
Merge "Document instructions for using adb under recovery."
-rw-r--r--README.md91
1 files changed, 91 insertions, 0 deletions
diff --git a/README.md b/README.md
index 8e20b5a6..0aeadaeb 100644
--- a/README.md
+++ b/README.md
@@ -47,3 +47,94 @@ image under recovery.
47 1. `adb sync data` to make sure the test-dir has the images to test. 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 48 2. The test will automatically pickup and verify all `_text.png` files in
49 the test dir. 49 the test dir.
50
51Using `adb` under recovery
52--------------------------
53
54When 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
56allows `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
63Although `/sbin/adbd` shares the same binary between normal boot and recovery images, only a subset
64of `adb` commands are meaningful under recovery, such as `adb root`, `adb shell`, `adb push`, `adb
65pull` etc. `adb shell` works only after manually mounting `/system` from recovery menu (assuming a
66valid 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
77By default, `adbd` is always included into recovery image, as `/sbin/adbd`. `init` starts `adbd`
78service automatically only in debuggable builds. This behavior is controlled by the recovery
79specific `/init.rc`, whose source code is at `bootable/recovery/etc/init.rc`.
80
81The best way to confirm a running `adbd` is by checking the serial output, which shows a service
82start log as below.
83
84 [ 18.961986] c1 1 init: starting service 'adbd'...
85
86 * Ensure USB gadget has been enabled.
87
88If `adbd` service has been started but device not shown under `adb devices`, use `lsusb(8)` (on
89host) 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
92trigger, 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
103If device is using [configfs](https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt),
104check if configfs has been properly set up in init rc scripts. See the [example
105configuration](https://android.googlesource.com/device/google/wahoo/+/master/init.recovery.hardware.rc)
106for Pixel 2 devices. Note that the flag set via sysfs (i.e. the one above) is no-op when using
107configfs.
108
109### `adb devices` shows the device, but in `unauthorized` state.
110
111 $ adb devices
112 List of devices attached
113 1234567890abcdef unauthorized
114
115recovery 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
117authorizing 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
121For debuggable builds, an RSA keypair can be used to authorize a host device that has the private
122key. The public key, defined via `PRODUCT_ADB_KEYS`, will be copied to `/adb_keys`. When starting
123the host-side `adbd`, make sure the filename (or the directory) of the matching private key has been
124added 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
132Note 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
138Both of the two conditions need to be satisfied. Although `ro.adb.secure` is a runtime property, its
139value 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`.