Browse Source

Document instructions for using adb under recovery.

Fixes: 72740736
Test: N/A
Change-Id: Ifc96ed785fd80501bc6c276cb649c8cc1f05be0e
Tao Bao 3 years ago
parent
commit
c84a4ef053
1 changed files with 91 additions and 0 deletions
  1. 91
    0
      README.md

+ 91
- 0
README.md View File

@@ -47,3 +47,94 @@ image under recovery.
47 47
     1. `adb sync data` to make sure the test-dir has the images to test.
48 48
     2. The test will automatically pickup and verify all `_text.png` files in
49 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`.