The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 1 | |
| 2 | --- a replacement for aproto ------------------------------------------- |
| 3 | |
| 4 | When it comes down to it, aproto's primary purpose is to forward |
| 5 | various streams between the host computer and client device (in either |
| 6 | direction). |
| 7 | |
| 8 | This replacement further simplifies the concept, reducing the protocol |
| 9 | to an extremely straightforward model optimized to accomplish the |
| 10 | forwarding of these streams and removing additional state or |
| 11 | complexity. |
| 12 | |
| 13 | The host side becomes a simple comms bridge with no "UI", which will |
| 14 | be used by either commandline or interactive tools to communicate with |
| 15 | a device or emulator that is connected to the bridge. |
| 16 | |
| 17 | The protocol is designed to be straightforward and well-defined enough |
| 18 | that if it needs to be reimplemented in another environment (Java |
| 19 | perhaps), there should not problems ensuring perfect interoperability. |
| 20 | |
| 21 | The protocol discards the layering aproto has and should allow the |
| 22 | implementation to be much more robust. |
| 23 | |
| 24 | |
| 25 | --- protocol overview and basics --------------------------------------- |
David 'Digit' Turner | f6330a2 | 2009-05-18 17:36:28 +0200 | [diff] [blame] | 26 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 27 | The transport layer deals in "messages", which consist of a 24 byte |
| 28 | header followed (optionally) by a payload. The header consists of 6 |
| 29 | 32 bit words which are sent across the wire in little endian format. |
| 30 | |
| 31 | struct message { |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 32 | unsigned command; /* command identifier constant (A_CNXN, ...) */ |
| 33 | unsigned arg0; /* first argument */ |
| 34 | unsigned arg1; /* second argument */ |
| 35 | unsigned data_length; /* length of payload (0 is allowed) */ |
| 36 | unsigned data_crc32; /* crc32 of data payload */ |
| 37 | unsigned magic; /* command ^ 0xffffffff */ |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 38 | }; |
| 39 | |
| 40 | Receipt of an invalid message header, corrupt message payload, or an |
| 41 | unrecognized command MUST result in the closing of the remote |
| 42 | connection. The protocol depends on shared state and any break in the |
| 43 | message stream will result in state getting out of sync. |
| 44 | |
| 45 | The following sections describe the six defined message types in |
| 46 | detail. Their format is COMMAND(arg0, arg1, payload) where the payload |
| 47 | is represented by a quoted string or an empty string if none should be |
| 48 | sent. |
| 49 | |
| 50 | The identifiers "local-id" and "remote-id" are always relative to the |
| 51 | *sender* of the message, so for a receiver, the meanings are effectively |
| 52 | reversed. |
| 53 | |
| 54 | |
David 'Digit' Turner | f6330a2 | 2009-05-18 17:36:28 +0200 | [diff] [blame] | 55 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 56 | --- CONNECT(version, maxdata, "system-identity-string") ---------------- |
| 57 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 58 | Command constant: A_CNXN |
| 59 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 60 | The CONNECT message establishes the presence of a remote system. |
| 61 | The version is used to ensure protocol compatibility and maxdata |
| 62 | declares the maximum message body size that the remote system |
| 63 | is willing to accept. |
| 64 | |
Tamas Berghammer | 3d2904c | 2015-07-13 19:12:28 +0100 | [diff] [blame] | 65 | Currently, version=0x01000000 and maxdata=256*1024. Older versions of adb |
| 66 | hard-coded maxdata=4096, so CONNECT and AUTH packets sent to a device must not |
| 67 | be larger than that because they're sent before the CONNECT from the device |
| 68 | that tells the adb server what maxdata the device can support. |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 69 | |
| 70 | Both sides send a CONNECT message when the connection between them is |
| 71 | established. Until a CONNECT message is received no other messages may |
Tamas Berghammer | 3d2904c | 2015-07-13 19:12:28 +0100 | [diff] [blame] | 72 | be sent. Any messages received before a CONNECT message MUST be ignored. |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 73 | |
| 74 | If a CONNECT message is received with an unknown version or insufficiently |
| 75 | large maxdata value, the connection with the other side must be closed. |
| 76 | |
| 77 | The system identity string should be "<systemtype>:<serialno>:<banner>" |
| 78 | where systemtype is "bootloader", "device", or "host", serialno is some |
| 79 | kind of unique ID (or empty), and banner is a human-readable version |
Scott Anderson | e82c2db | 2012-05-25 14:10:02 -0700 | [diff] [blame] | 80 | or identifier string. The banner is used to transmit useful properties. |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 81 | |
| 82 | |
Benoit Goby | d5fcafa | 2012-04-12 12:23:49 -0700 | [diff] [blame] | 83 | --- AUTH(type, 0, "data") ---------------------------------------------- |
| 84 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 85 | Command constant: A_AUTH |
| 86 | |
Benoit Goby | d5fcafa | 2012-04-12 12:23:49 -0700 | [diff] [blame] | 87 | The AUTH message informs the recipient that authentication is required to |
| 88 | connect to the sender. If type is TOKEN(1), data is a random token that |
| 89 | the recipient can sign with a private key. The recipient replies with an |
| 90 | AUTH packet where type is SIGNATURE(2) and data is the signature. If the |
| 91 | signature verification succeeds, the sender replies with a CONNECT packet. |
| 92 | |
| 93 | If the signature verification fails, the sender replies with a new AUTH |
| 94 | packet and a new random token, so that the recipient can retry signing |
| 95 | with a different private key. |
| 96 | |
| 97 | Once the recipient has tried all its private keys, it can reply with an |
| 98 | AUTH packet where type is RSAPUBLICKEY(3) and data is the public key. If |
| 99 | possible, an on-screen confirmation may be displayed for the user to |
| 100 | confirm they want to install the public key on the device. |
| 101 | |
| 102 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 103 | --- OPEN(local-id, 0, "destination") ----------------------------------- |
| 104 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 105 | Command constant: A_OPEN |
| 106 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 107 | The OPEN message informs the recipient that the sender has a stream |
| 108 | identified by local-id that it wishes to connect to the named |
| 109 | destination in the message payload. The local-id may not be zero. |
| 110 | |
| 111 | The OPEN message MUST result in either a READY message indicating that |
| 112 | the connection has been established (and identifying the other end) or |
| 113 | a CLOSE message, indicating failure. An OPEN message also implies |
| 114 | a READY message sent at the same time. |
| 115 | |
| 116 | Common destination naming conventions include: |
| 117 | |
| 118 | * "tcp:<host>:<port>" - host may be omitted to indicate localhost |
| 119 | * "udp:<host>:<port>" - host may be omitted to indicate localhost |
| 120 | * "local-dgram:<identifier>" |
| 121 | * "local-stream:<identifier>" |
| 122 | * "shell" - local shell service |
| 123 | * "upload" - service for pushing files across (like aproto's /sync) |
| 124 | * "fs-bridge" - FUSE protocol filesystem bridge |
| 125 | |
| 126 | |
| 127 | --- READY(local-id, remote-id, "") ------------------------------------- |
| 128 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 129 | Command constant: A_OKAY |
| 130 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 131 | The READY message informs the recipient that the sender's stream |
| 132 | identified by local-id is ready for write messages and that it is |
| 133 | connected to the recipient's stream identified by remote-id. |
| 134 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 135 | Neither the local-id nor the remote-id may be zero. |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 136 | |
| 137 | A READY message containing a remote-id which does not map to an open |
| 138 | stream on the recipient's side is ignored. The stream may have been |
| 139 | closed while this message was in-flight. |
| 140 | |
| 141 | The local-id is ignored on all but the first READY message (where it |
| 142 | is used to establish the connection). Nonetheless, the local-id MUST |
| 143 | not change on later READY messages sent to the same stream. |
| 144 | |
| 145 | |
Derrick Bonafilia | 36da715 | 2015-07-06 10:19:28 -0700 | [diff] [blame] | 146 | --- WRITE(local-id, remote-id, "data") --------------------------------- |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 147 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 148 | Command constant: A_WRTE |
| 149 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 150 | The WRITE message sends data to the recipient's stream identified by |
| 151 | remote-id. The payload MUST be <= maxdata in length. |
| 152 | |
| 153 | A WRITE message containing a remote-id which does not map to an open |
| 154 | stream on the recipient's side is ignored. The stream may have been |
| 155 | closed while this message was in-flight. |
| 156 | |
| 157 | A WRITE message may not be sent until a READY message is received. |
| 158 | Once a WRITE message is sent, an additional WRITE message may not be |
| 159 | sent until another READY message has been received. Recipients of |
| 160 | a WRITE message that is in violation of this requirement will CLOSE |
| 161 | the connection. |
| 162 | |
| 163 | |
| 164 | --- CLOSE(local-id, remote-id, "") ------------------------------------- |
| 165 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 166 | Command constant: A_CLSE |
| 167 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 168 | The CLOSE message informs recipient that the connection between the |
| 169 | sender's stream (local-id) and the recipient's stream (remote-id) is |
| 170 | broken. The remote-id MUST not be zero, but the local-id MAY be zero |
| 171 | if this CLOSE indicates a failed OPEN. |
| 172 | |
| 173 | A CLOSE message containing a remote-id which does not map to an open |
| 174 | stream on the recipient's side is ignored. The stream may have |
| 175 | already been closed by the recipient while this message was in-flight. |
| 176 | |
| 177 | The recipient should not respond to a CLOSE message in any way. The |
| 178 | recipient should cancel pending WRITEs or CLOSEs, but this is not a |
| 179 | requirement, since they will be ignored. |
| 180 | |
| 181 | |
| 182 | --- SYNC(online, sequence, "") ----------------------------------------- |
| 183 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 184 | Command constant: A_SYNC |
| 185 | |
Josh Gao | 0bbf69c | 2018-02-16 13:24:58 -0800 | [diff] [blame] | 186 | *** obsolete, no longer used *** |
| 187 | |
| 188 | The SYNC message was used by the io pump to make sure that stale |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 189 | outbound messages are discarded when the connection to the remote side |
Josh Gao | 0bbf69c | 2018-02-16 13:24:58 -0800 | [diff] [blame] | 190 | is broken. It was only used internally to the bridge and never valid |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 191 | to send across the wire. |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 192 | |
Eyal Lezmy | 39e999e | 2016-08-30 00:53:08 +0200 | [diff] [blame] | 193 | * when the connection to the remote side goes offline, the io pump |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 194 | sends a SYNC(0, 0) and starts discarding all messages |
| 195 | * when the connection to the remote side is established, the io pump |
| 196 | sends a SYNC(1, token) and continues to discard messages |
| 197 | * when the io pump receives a matching SYNC(1, token), it once again |
| 198 | starts accepting messages to forward to the remote side |
| 199 | |
| 200 | |
| 201 | --- message command constants ------------------------------------------ |
| 202 | |
| 203 | #define A_SYNC 0x434e5953 |
| 204 | #define A_CNXN 0x4e584e43 |
Benoit Goby | d5fcafa | 2012-04-12 12:23:49 -0700 | [diff] [blame] | 205 | #define A_AUTH 0x48545541 |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 206 | #define A_OPEN 0x4e45504f |
| 207 | #define A_OKAY 0x59414b4f |
| 208 | #define A_CLSE 0x45534c43 |
| 209 | #define A_WRTE 0x45545257 |
| 210 | |
| 211 | |
David 'Digit' Turner | f6330a2 | 2009-05-18 17:36:28 +0200 | [diff] [blame] | 212 | |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 213 | --- implementation details --------------------------------------------- |
| 214 | |
| 215 | The core of the bridge program will use three threads. One thread |
| 216 | will be a select/epoll loop to handle io between various inbound and |
| 217 | outbound connections and the connection to the remote side. |
| 218 | |
| 219 | The remote side connection will be implemented as two threads (one for |
| 220 | reading, one for writing) and a datagram socketpair to provide the |
| 221 | channel between the main select/epoll thread and the remote connection |
| 222 | threadpair. The reason for this is that for usb connections, the |
| 223 | kernel interface on linux and osx does not allow you to do meaningful |
| 224 | nonblocking IO. |
| 225 | |
| 226 | The endian swapping for the message headers will happen (as needed) in |
| 227 | the remote connection threadpair and that the rest of the program will |
| 228 | always treat message header values as native-endian. |
| 229 | |
| 230 | The bridge program will be able to have a number of mini-servers |
| 231 | compiled in. They will be published under known names (examples |
| 232 | "shell", "fs-bridge", etc) and upon receiving an OPEN() to such a |
| 233 | service, the bridge program will create a stream socketpair and spawn |
| 234 | a thread or subprocess to handle the io. |
| 235 | |
| 236 | |
| 237 | --- simplified / embedded implementation ------------------------------- |
| 238 | |
| 239 | For limited environments, like the bootloader, it is allowable to |
| 240 | support a smaller, fixed number of channels using pre-assigned channel |
| 241 | ID numbers such that only one stream may be connected to a bootloader |
| 242 | endpoint at any given time. The protocol remains unchanged, but the |
| 243 | "embedded" version of it is less dynamic. |
| 244 | |
| 245 | The bootloader will support two streams. A "bootloader:debug" stream, |
| 246 | which may be opened to get debug messages from the bootloader and a |
| 247 | "bootloader:control", stream which will support the set of basic |
| 248 | bootloader commands. |
| 249 | |
| 250 | Example command stream dialogues: |
| 251 | "flash_kernel,2515049,........\n" "okay\n" |
| 252 | "flash_ramdisk,5038,........\n" "fail,flash write error\n" |
| 253 | "bogus_command......" <CLOSE> |
| 254 | |
| 255 | |
| 256 | --- future expansion --------------------------------------------------- |
| 257 | |
| 258 | I plan on providing either a message or a special control stream so that |
| 259 | the client device could ask the host computer to setup inbound socket |
| 260 | translations on the fly on behalf of the client device. |
| 261 | |
| 262 | |
| 263 | The initial design does handshaking to provide flow control, with a |
| 264 | message flow that looks like: |
| 265 | |
| 266 | >OPEN <READY >WRITE <READY >WRITE <READY >WRITE <CLOSE |
| 267 | |
| 268 | The far side may choose to issue the READY message as soon as it receives |
| 269 | a WRITE or it may defer the READY until the write to the local stream |
| 270 | succeeds. A future version may want to do some level of windowing where |
| 271 | multiple WRITEs may be sent without requiring individual READY acks. |
| 272 | |
| 273 | ------------------------------------------------------------------------ |
| 274 | |
| 275 | --- smartsockets ------------------------------------------------------- |
| 276 | |
| 277 | Port 5037 is used for smart sockets which allow a client on the host |
| 278 | side to request access to a service in the host adb daemon or in the |
| 279 | remote (device) daemon. The service is requested by ascii name, |
| 280 | preceeded by a 4 digit hex length. Upon successful connection an |
| 281 | "OKAY" response is sent, otherwise a "FAIL" message is returned. Once |
| 282 | connected the client is talking to that (remote or local) service. |
| 283 | |
| 284 | client: <hex4> <service-name> |
| 285 | server: "OKAY" |
| 286 | |
| 287 | client: <hex4> <service-name> |
| 288 | server: "FAIL" <hex4> <reason> |
| 289 | |