Skip to content

Instantly share code, notes, and snippets.

Forked from hfutxqd/OVERVIEW.TXT
Created January 10, 2022 08:15
Show Gist options
  • Save AshenOneYe/78c3771850fadfbf6f14c487a7aaad14 to your computer and use it in GitHub Desktop.
Save AshenOneYe/78c3771850fadfbf6f14c487a7aaad14 to your computer and use it in GitHub Desktop.
adb protocol
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 called 'services' 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
is 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.
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
states. They are a few 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.
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.
This file tries to document all requests a client can make
to the ADB server of an adbd daemon. See the OVERVIEW.TXT document
to understand what's going on here.
Ask the ADB server for its internal version number.
Ask the ADB server to quit immediately. This is used when the
ADB client detects that an obsolete server is running after an
Ask to return the list of available Android devices and their
state. devices-l includes the device paths in the state.
After the OKAY, this is followed by a 4-byte hex len,
and a string that will be dumped as-is by the client, then
the connection is closed
This is a variant of host:devices which doesn't close the
connection. Instead, a new device list description is sent
each time a device is added/removed or the state of a given
device changes (hex4 + content). This allows tools like DDMS
to track the state of connected devices in real-time without
polling the server repeatedly.
This is a special query that is sent to the ADB server when a
new emulator starts up. <port> is a decimal number corresponding
to the emulator's ADB control port, i.e. the TCP port that the
emulator will forward automatically to the adbd daemon running
in the emulator system.
This mechanism allows the ADB server to know when new emulator
instances start.
Ask to switch the connection to the device/emulator identified by
<serial-number>. After the OKAY response, every client request will
be sent directly to the adbd daemon running on the device.
(Used to implement the -s option)
Ask to switch the connection to one device connected through USB
to the host machine. This will fail if there are more than one such
devices. (Used to implement the -d convenience option)
Ask to switch the connection to one emulator connected through TCP.
This will fail if there is more than one such emulator instance
running. (Used to implement the -e convenience option)
Another host:transport variant. Ask to switch the connection to
either the device or emulator connect to/running on the host.
Will fail if there is more than one such device/emulator available.
(Used when neither -s, -d or -e are provided)
This is a special form of query, where the 'host-serial:<serial-number>:'
prefix can be used to indicate that the client is asking the ADB server
for information related to a specific device. <request> can be in one
of the format described below.
A variant of host-serial used to target the single USB device connected
to the host. This will fail if there is none or more than one.
A variant of host-serial used to target the single emulator instance
running on the host. This will fail if there is none or more than one.
When asking for information related to a device, 'host:' can also be
interpreted as 'any single device or emulator connected to/running on
the host'.
Returns the serial number of the corresponding device/emulator.
Note that emulator serial numbers are of the form "emulator-5554"
Returns the device path of the corresponding device/emulator.
Returns the state of a given device as a string.
Asks the ADB server to forward local connections from <local>
to the <remote> address on a given device.
There, <host-prefix> can be one of the
host-serial/host-usb/host-local/host prefixes as described previously
and indicates which device/emulator to target.
the format of <local> is one of:
tcp:<port> -> TCP connection on localhost:<port>
local:<path> -> Unix local domain socket on <path>
the format of <remote> is one of:
tcp:<port> -> TCP localhost:<port> on device
local:<path> -> Unix local domain socket on device
jdwp:<pid> -> JDWP thread on VM process <pid>
or even any one of the local services described below.
Same as <host-prefix>:forward:<local>;<remote> except that it will
fail it there is already a forward connection from <local>.
Used to implement 'adb forward --no-rebind <local> <remote>'
Remove any existing forward local connection from <local>.
This is used to implement 'adb forward --remove <local>'
Remove all forward network connections.
This is used to implement 'adb forward --remove-all'.
List all existing forward connections from this server.
This returns something that looks like the following:
<hex4>: The length of the payload, as 4 hexadecimal chars.
<payload>: A series of lines of the following format:
<serial> " " <local> " " <remote> "\n"
Where <serial> is a device serial number.
<local> is the host-specific endpoint (e.g. tcp:9000).
<remote> is the device-specific endpoint.
Used to implement 'adb forward --list'.
All the queries below assumed that you already switched the transport
to a real device, or that you have used a query prefix as described
shell:command arg1 arg2 ...
Run 'command arg1 arg2 ...' in a shell on the device, and return
its output and error streams. Note that arguments must be separated
by spaces. If an argument contains a space, it must be quoted with
double-quotes. Arguments cannot contain double quotes or things
will go very wrong.
Note that this is the non-interactive version of "adb shell"
Start an interactive shell session on the device. Redirect
stdin/stdout/stderr as appropriate. Note that the ADB server uses
this to implement "adb shell", but will also cook the input before
sending it to the device (see interactive_shell() in commandline.c)
Ask adbd to remount the device's filesystem in read-write mode,
instead of read-only. This is usually necessary before performing
an "adb sync" or "adb push" request.
This request may not succeed on certain builds which do not allow
Opens a device file and connects the client directly to it for
read/write purposes. Useful for debugging, but may require special
privileges and thus may not run on all devices. <path> is a full
path from the root of the filesystem.
Tries to connect to tcp port <port> on localhost.
Tries to connect to tcp port <port> on machine <server-name> from
the device. This can be useful to debug some networking/proxy
issues that can only be revealed on the device itself.
Tries to connect to a Unix domain socket <path> on the device
Variants of local:<path> that are used to access other Android
socket namespaces.
This service is used to send snapshots of the framebuffer to a client.
It requires sufficient privileges but works as follow:
After the OKAY, the service sends 16-byte binary structure
containing the following fields (little-endian format):
depth: uint32_t: framebuffer depth
size: uint32_t: framebuffer size in bytes
width: uint32_t: framebuffer width in pixels
height: uint32_t: framebuffer height in pixels
With the current implementation, depth is always 16, and
size is always width*height*2
Then, each time the client wants a snapshot, it should send
one byte through the channel, which will trigger the service
to send it 'size' bytes of framebuffer data.
If the adbd daemon doesn't have sufficient privileges to open
the framebuffer device, the connection is simply closed immediately.
Connects to the JDWP thread running in the VM of process <pid>.
This is used to send the list of JDWP pids periodically to the client.
The format of the returned data is the following:
<hex4>: the length of all content as a 4-char hexadecimal string
<content>: a series of ASCII lines of the following format:
<pid> "\n"
This service is used by DDMS to know which debuggable processes are running
on the device/emulator.
Note that there is no single-shot service to retrieve the list only once.
This starts the file synchronization service, used to implement "adb push"
and "adb pull". Since this service is pretty complex, it will be detailed
in a companion document named SYNC.TXT
This implements the 'adb reverse' feature, i.e. the ability to reverse
socket connections from a device to the host. <forward-command> is one
of the forwarding commands that are described above, as in:
Note that in this case, <local> corresponds to the socket on the device
and <remote> corresponds to the socket on the host.
The output of reverse:list-forward is the same as host:list-forward
except that <serial> will be just 'host'.
This file tries to document file-related requests a client can make
to the ADB server of an adbd daemon. See the OVERVIEW.TXT document
to understand what's going on here. See the SERVICES.TXT to learn more
about the other requests that are possible.
Requesting the sync service ("sync:") using the protocol as described in
SERVICES.TXT sets the connection in sync mode. This mode is a binary mode that
differs from the regular adb protocol. The connection stays in sync mode until
explicitly terminated (see below).
After the initial "sync:" command is sent the server must respond with either
"OKAY" or "FAIL" as per usual.
In sync mode both the server and the client will frequently use eight-byte
packets to communicate. In this document these are called sync requests and sync
responses. The first four bytes are an id that specifies the sync request. It is
represented by four utf-8 characters. The last four bytes are a Little-Endian
integer, with various uses. This number will be called "length" below. In fact
all binary integers are Little-Endian in the sync mode. Sync mode is
implicitly exited after each sync request, and normal adb communication
follows as described in SERVICES.TXT.
The following sync requests are accepted:
LIST - List the files in a folder
RECV - Retrieve a file from device
SEND - Send a file to device
STAT - Stat a file
All of the sync requests above must be followed by "length": the number of
bytes containing a utf-8 string with a remote filename.
Lists files in the directory specified by the remote filename. The server will
respond with zero or more directory entries or "dents".
The directory entries will be returned in the following form
1. A four-byte sync response id "DENT"
2. A four-byte integer representing file mode.
3. A four-byte integer representing file size.
4. A four-byte integer representing last modified time.
5. A four-byte integer representing file name length.
6. length number of bytes containing an utf-8 string representing the file
When a sync response "DONE" is received the listing is done.
The remote file name is split into two parts separated by the last
comma (","). The first part is the actual path, while the second is a decimal
encoded file mode containing the permissions of the file on device.
Note that some file types will be deleted before the copying starts, and if
the transfer fails. Some file types will not be deleted, which allows
adb push disk_image /some_block_device
to work.
After this the actual file is sent in chunks. Each chunk has the following
A sync request with id "DATA" and length equal to the chunk size. After
follows chunk size number of bytes. This is repeated until the file is
transferred. Each chunk must not be larger than 64k.
When the file is transferred a sync request "DONE" is sent, where length is set
to the last modified time for the file. The server responds to this last
request (but not to chunk requests) with an "OKAY" sync response (length can
be ignored).
Retrieves a file from device to a local file. The remote path is the path to
the file that will be returned. Just as for the SEND sync request the file
received is split up into chunks. The sync response id is "DATA" and length is
the chunk size. After follows chunk size number of bytes. This is repeated
until the file is transferred. Each chunk will not be larger than 64k.
When the file is transferred a sync response "DONE" is retrieved where the
length can be ignored.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment