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