blob: c40695af6f692e15b4dcaa30a04d4a94a33df1db [file] [log] [blame]
The Android Open Source Projectdd7bc332009-03-03 19:32:55 -08001Implementation notes regarding ADB.
2
3I. General Overview:
4
5The Android Debug Bridge (ADB) is used to:
6
7- keep track of all Android devices and emulators instances
8 connected to or running on a given host developer machine
9
10- implement various control commands (e.g. "adb shell", "adb pull", etc..)
11 for the benefit of clients (command-line users, or helper programs like
12 DDMS). These commands are what is called a 'service' in ADB.
13
14As a whole, everything works through the following components:
15
16 1. The ADB server
17
18 This is a background process that runs on the host machine. Its purpose
19 if to sense the USB ports to know when devices are attached/removed,
20 as well as when emulator instances start/stop.
21
22 It thus maintains a list of "connected devices" and assigns a 'state'
23 to each one of them: OFFLINE, BOOTLOADER, RECOVERY or ONLINE (more on
24 this below).
25
26 The ADB server is really one giant multiplexing loop whose purpose is
27 to orchestrate the exchange of data (packets, really) between clients,
28 services and devices.
29
30
31 2. The ADB daemon (adbd)
32
33 The 'adbd' program runs as a background process within an Android device
34 or emulated system. Its purpose is to connect to the ADB server
35 (through USB for devices, through TCP for emulators) and provide a
36 few services for clients that run on the host.
37
Brian Carlstrom26bb6e92010-04-26 09:33:47 -070038 The ADB server considers that a device is ONLINE when it has successfully
The Android Open Source Projectdd7bc332009-03-03 19:32:55 -080039 connected to the adbd program within it. Otherwise, the device is OFFLINE,
40 meaning that the ADB server detected a new device/emulator, but could not
41 connect to the adbd daemon.
42
43 the BOOTLOADER and RECOVERY states correspond to alternate states of
44 devices when they are in the bootloader or recovery mode.
45
46 3. The ADB command-line client
47
48 The 'adb' command-line program is used to run adb commands from a shell
49 or a script. It first tries to locate the ADB server on the host machine,
50 and will start one automatically if none is found.
51
52 then, the client sends its service requests to the ADB server. It doesn't
53 need to know.
54
55 Currently, a single 'adb' binary is used for both the server and client.
56 this makes distribution and starting the server easier.
57
58
59 4. Services
60
61 There are essentially two kinds of services that a client can talk to.
62
63 Host Services:
64 these services run within the ADB Server and thus do not need to
65 communicate with a device at all. A typical example is "adb devices"
66 which is used to return the list of currently known devices and their
67 state. They are a few couple other services though.
68
69 Local Services:
70 these services either run within the adbd daemon, or are started by
71 it on the device. The ADB server is used to multiplex streams
72 between the client and the service running in adbd. In this case
73 its role is to initiate the connection, then of being a pass-through
74 for the data.
75
76
77II. Protocol details:
78
79 1. Client <-> Server protocol:
80
81 This details the protocol used between ADB clients and the ADB
82 server itself. The ADB server listens on TCP:localhost:5037.
83
84 A client sends a request using the following format:
85
86 1. A 4-byte hexadecimal string giving the length of the payload
87 2. Followed by the payload itself.
88
89 For example, to query the ADB server for its internal version number,
90 the client will do the following:
91
92 1. Connect to tcp:localhost:5037
93 2. Send the string "000Chost:version" to the corresponding socket
94
95 The 'host:' prefix is used to indicate that the request is addressed
96 to the server itself (we will talk about other kinds of requests later).
97 The content length is encoded in ASCII for easier debugging.
98
99 The server should answer a request with one of the following:
100
101 1. For success, the 4-byte "OKAY" string
102
103 2. For failure, the 4-byte "FAIL" string, followed by a
104 4-byte hex length, followed by a string giving the reason
105 for failure.
106
107 3. As a special exception, for 'host:version', a 4-byte
108 hex string corresponding to the server's internal version number
109
110 Note that the connection is still alive after an OKAY, which allows the
111 client to make other requests. But in certain cases, an OKAY will even
112 change the state of the connection.
113
114 For example, the case of the 'host:transport:<serialnumber>' request,
115 where '<serialnumber>' is used to identify a given device/emulator; after
116 the "OKAY" answer, all further requests made by the client will go
117 directly to the corresponding adbd daemon.
118
119 The file SERVICES.TXT lists all services currently implemented by ADB.
120
121
122 2. Transports:
123
124 An ADB transport models a connection between the ADB server and one device
125 or emulator. There are currently two kinds of transports:
126
127 - USB transports, for physical devices through USB
128
129 - Local transports, for emulators running on the host, connected to
130 the server through TCP
131
132 In theory, it should be possible to write a local transport that proxies
133 a connection between an ADB server and a device/emulator connected to/
134 running on another machine. This hasn't been done yet though.
135
136 Each transport can carry one or more multiplexed streams between clients
137 and the device/emulator they point to. The ADB server must handle
138 unexpected transport disconnections (e.g. when a device is physically
139 unplugged) properly.