139 lines
5.4 KiB
Text
139 lines
5.4 KiB
Text
Implementation notes regarding ADB.
|
|
|
|
I. General Overview:
|
|
|
|
The Android Debug Bridge (ADB) is used to:
|
|
|
|
- keep track of all Android devices and emulators instances
|
|
connected to or running on a given host developer machine
|
|
|
|
- implement various control commands (e.g. "adb shell", "adb pull", etc..)
|
|
for the benefit of clients (command-line users, or helper programs like
|
|
DDMS). These commands are what is called a 'service' in ADB.
|
|
|
|
As a whole, everything works through the following components:
|
|
|
|
1. The ADB server
|
|
|
|
This is a background process that runs on the host machine. Its purpose
|
|
if to sense the USB ports to know when devices are attached/removed,
|
|
as well as when emulator instances start/stop.
|
|
|
|
It thus maintains a list of "connected devices" and assigns a 'state'
|
|
to each one of them: OFFLINE, BOOTLOADER, RECOVERY or ONLINE (more on
|
|
this below).
|
|
|
|
The ADB server is really one giant multiplexing loop whose purpose is
|
|
to orchestrate the exchange of data (packets, really) between clients,
|
|
services and devices.
|
|
|
|
|
|
2. The ADB daemon (adbd)
|
|
|
|
The 'adbd' program runs as a background process within an Android device
|
|
or emulated system. Its purpose is to connect to the ADB server
|
|
(through USB for devices, through TCP for emulators) and provide a
|
|
few services for clients that run on the host.
|
|
|
|
The ADB server considers that a device is ONLINE when it has successfully
|
|
connected to the adbd program within it. Otherwise, the device is OFFLINE,
|
|
meaning that the ADB server detected a new device/emulator, but could not
|
|
connect to the adbd daemon.
|
|
|
|
the BOOTLOADER and RECOVERY states correspond to alternate states of
|
|
devices when they are in the bootloader or recovery mode.
|
|
|
|
3. The ADB command-line client
|
|
|
|
The 'adb' command-line program is used to run adb commands from a shell
|
|
or a script. It first tries to locate the ADB server on the host machine,
|
|
and will start one automatically if none is found.
|
|
|
|
then, the client sends its service requests to the ADB server. It doesn't
|
|
need to know.
|
|
|
|
Currently, a single 'adb' binary is used for both the server and client.
|
|
this makes distribution and starting the server easier.
|
|
|
|
|
|
4. Services
|
|
|
|
There are essentially two kinds of services that a client can talk to.
|
|
|
|
Host Services:
|
|
these services run within the ADB Server and thus do not need to
|
|
communicate with a device at all. A typical example is "adb devices"
|
|
which is used to return the list of currently known devices and their
|
|
state. They are a few couple other services though.
|
|
|
|
Local Services:
|
|
these services either run within the adbd daemon, or are started by
|
|
it on the device. The ADB server is used to multiplex streams
|
|
between the client and the service running in adbd. In this case
|
|
its role is to initiate the connection, then of being a pass-through
|
|
for the data.
|
|
|
|
|
|
II. Protocol details:
|
|
|
|
1. Client <-> Server protocol:
|
|
|
|
This details the protocol used between ADB clients and the ADB
|
|
server itself. The ADB server listens on TCP:localhost:5037.
|
|
|
|
A client sends a request using the following format:
|
|
|
|
1. A 4-byte hexadecimal string giving the length of the payload
|
|
2. Followed by the payload itself.
|
|
|
|
For example, to query the ADB server for its internal version number,
|
|
the client will do the following:
|
|
|
|
1. Connect to tcp:localhost:5037
|
|
2. Send the string "000Chost:version" to the corresponding socket
|
|
|
|
The 'host:' prefix is used to indicate that the request is addressed
|
|
to the server itself (we will talk about other kinds of requests later).
|
|
The content length is encoded in ASCII for easier debugging.
|
|
|
|
The server should answer a request with one of the following:
|
|
|
|
1. For success, the 4-byte "OKAY" string
|
|
|
|
2. For failure, the 4-byte "FAIL" string, followed by a
|
|
4-byte hex length, followed by a string giving the reason
|
|
for failure.
|
|
|
|
3. As a special exception, for 'host:version', a 4-byte
|
|
hex string corresponding to the server's internal version number
|
|
|
|
Note that the connection is still alive after an OKAY, which allows the
|
|
client to make other requests. But in certain cases, an OKAY will even
|
|
change the state of the connection.
|
|
|
|
For example, the case of the 'host:transport:<serialnumber>' request,
|
|
where '<serialnumber>' is used to identify a given device/emulator; after
|
|
the "OKAY" answer, all further requests made by the client will go
|
|
directly to the corresponding adbd daemon.
|
|
|
|
The file SERVICES.TXT lists all services currently implemented by ADB.
|
|
|
|
|
|
2. Transports:
|
|
|
|
An ADB transport models a connection between the ADB server and one device
|
|
or emulator. There are currently two kinds of transports:
|
|
|
|
- USB transports, for physical devices through USB
|
|
|
|
- Local transports, for emulators running on the host, connected to
|
|
the server through TCP
|
|
|
|
In theory, it should be possible to write a local transport that proxies
|
|
a connection between an ADB server and a device/emulator connected to/
|
|
running on another machine. This hasn't been done yet though.
|
|
|
|
Each transport can carry one or more multiplexed streams between clients
|
|
and the device/emulator they point to. The ADB server must handle
|
|
unexpected transport disconnections (e.g. when a device is physically
|
|
unplugged) properly.
|