src/OVERVIEW.TXT

   1 Implementation notes regarding SDB.
   2
   3 I. General Overview:
   4
   5 The Android Debug Bridge (SDB) 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. "sdb shell", "sdb 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 SDB.
  13
  14 As a whole, everything works through the following components:
  15
  16   1. The SDB 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 SDB 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 SDB daemon (sdbd)
  32
  33     The 'sdbd' program runs as a background process within an Android device
  34     or emulated system. Its purpose is to connect to the SDB server
  35     (through USB for devices, through TCP for emulators) and provide a
  36     few services for clients that run on the host.
  37
  38     The SDB server considers that a device is ONLINE when it has successfully
  39     connected to the sdbd program within it. Otherwise, the device is OFFLINE,
  40     meaning that the SDB server detected a new device/emulator, but could not
  41     connect to the sdbd 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 SDB command-line client
  47
  48     The 'sdb' command-line program is used to run sdb commands from a shell
  49     or a script. It first tries to locate the SDB 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 SDB server. It doesn't
  53     need to know.
  54
  55     Currently, a single 'sdb' 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 SDB Server and thus do not need to
  65       communicate with a device at all. A typical example is "sdb 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 sdbd daemon, or are started by
  71       it on the device. The SDB server is used to multiplex streams
  72       between the client and the service running in sdbd. In this case
  73       its role is to initiate the connection, then of being a pass-through
  74       for the data.
  75
  76
  77 II. Protocol details:
  78
  79   1. Client <-> Server protocol:
  80
  81     This details the protocol used between SDB clients and the SDB
  82     server itself. The SDB 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 SDB 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 sdbd daemon.
 118
 119     The file SERVICES.TXT lists all services currently implemented by SDB.
 120
 121
 122   2. Transports:
 123
 124     An SDB transport models a connection between the SDB 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 SDB 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 SDB server must handle
 138     unexpected transport disconnections (e.g. when a device is physically
 139     unplugged) properly.