adb protocol

OVERVIEW.TXT

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.

SERVICES.TXT

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.

HOST SERVICES:

host:version
    Ask the ADB server for its internal version number.

host:kill
    Ask the ADB server to quit immediately. This is used when the
    ADB client detects that an obsolete server is running after an
    upgrade.

host:devices
host:devices-l
    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

host:track-devices
    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.

host:emulator:<port>
    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.

host:transport:<serial-number>
    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)

host:transport-usb
    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)

host:transport-local
    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)

host:transport-any
    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)

host-serial:<serial-number>:<request>
    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.

host-usb:<request>
    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.

host-local:<request>
    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.

host:<request>
    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'.

<host-prefix>:get-product
    XXX

<host-prefix>:get-serialno
    Returns the serial number of the corresponding device/emulator.
    Note that emulator serial numbers are of the form "emulator-5554"

<host-prefix>:get-devpath
    Returns the device path of the corresponding device/emulator.

<host-prefix>:get-state
    Returns the state of a given device as a string.

<host-prefix>:forward:<local>;<remote>
    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.

<host-prefix>:forward:norebind:<local>;<remote>
    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>'

<host-prefix>:killforward:<local>
    Remove any existing forward local connection from <local>.
    This is used to implement 'adb forward --remove <local>'

<host-prefix>:killforward-all
    Remove all forward network connections.
    This is used to implement 'adb forward --remove-all'.

<host-prefix>:list-forward
    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'.

LOCAL SERVICES:

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
above.

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"

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)

remount:
    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
    that.

dev:<path>
    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.

tcp:<port>
    Tries to connect to tcp port <port> on localhost.

tcp:<port>:<server-name>
    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.

local:<path>
    Tries to connect to a Unix domain socket <path> on the device

localreserved:<path>
localabstract:<path>
localfilesystem:<path>
    Variants of local:<path> that are used to access other Android
    socket namespaces.

framebuffer:
    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.

jdwp:<pid>
    Connects to the JDWP thread running in the VM of process <pid>.

track-jdwp
    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.

sync:
    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

reverse:<forward-command>
    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:

      list-forward
      forward:<local>;<remote>
      forward:norebind:<local>;<remote>
      killforward-all
      killforward:<local>

    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'.

SYNC.TXT

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.

SYNC SERVICES:


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.

LIST:
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
   name.

When a sync response "DONE" is received the listing is done.

SEND:
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
format.
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).


RECV:
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.