1# ADB Internals
2
3If you are new to adb source code, you should start by reading [overview.md](overview.md) which describes the three components of adb pipeline.
4
5This document gives the "big picture" which should allow you to build a mental map to help navigate the code.
6
7## Three components of adb pipeline
8
9As described in the [overview](overview.md), this codebase generates three components (Client, Server (a.k.a Host), and Daemon (a.k.a adbd)).
10
11The central part is the Server which runs on the Host computer. On one side the Server exposes a connection to Clients such as adb or DDMLIB.
12
13On the other side, the Server continuously monitors for connecting Daemons (such as USB devices or TCP emulator). Communication with a device is done with a Transport.
14
15```
16+----------+              +------------------------+
17|   ADB    +----------+   |      ADB SERVER        |                   +----------+
18|  CLIENT  |          |   |                        |              (USB)|   ADBD   |
19+----------+          |   |                     Transport+-------------+ (DEVICE) |
20                      |   |                        |                   +----------+
21+-----------          |   |                        |
22|   ADB    |          v   +                        |                   +----------+
23|  CLIENT  +--------->SmartSocket                  |              (USB)|   ADBD   |
24+----------+          ^   | (TCP/IP)            Transport+-------------+ (DEVICE) |
25                      |   |                        |                   +----------+
26+----------+          |   |                        |
27|  DDMLIB  |          |   |                     Transport+--+          +----------+
28|  CLIENT  +----------+   |                        |        |  (TCP/IP)|   ADBD   |
29+----------+              +------------------------+        +----------|(EMULATOR)|
30                                                                       +----------+
31```
32
33The Client and the Server are contained in the same executable and both run on the Host machine. Code sections specific to the Host are enclosed within `ADB_HOST` guard. adbd runs on the Android Device. Daemon specific code is enclosed in `!ADB_HOST` but also sometimes within `__ANDROID__` guards.
34
35
36## "SMART SOCKET" and TRANSPORT
37
38A smart socket is a simple TCP socket with a smart protocol built on top of it which allows to target a device **after** the connection is initalized (see [services.md](services.md) families of `host:transport-` services for more information). This is what Clients connect onto from the Host side. The Client must always initiate communication via a human readable request but the response format varies. The smart protocol is documented in [services.md](services.md).
39
40On the other side, the Server communicates with a device via a Transport. adb initially targeted devices connecting over USB, which is restricted to a fixed number of data streams. Therefore, adb multiplexes multiple byte streams over a single pipe via Transport. When devices connecting over other mechanisms (e.g. emulators over TCP) were introduced, the existing transport protocol was maintained.
41
42## THREADING MODEL and FDEVENT system
43
44At the heart of both the Server and Daemon is a main thread running an fdevent loop, which is a platform-independent abstraction over poll/epoll/WSAPoll monitoring file descriptors events. Requests and services are usually served from the main thread but some service requests result in new threads being spawned.
45
46To allow for operations to run on the Main thread, fdevent features a RunQueue combined with an interrupt fd to force polling to return.
47
48```
49+------------+    +-------------------------^
50|  RUNQUEUE  |    |                         |
51+------------+    |  POLLING (Main thread)  |
52| Function<> |    |                         |
53+------------+    |                         |
54| Function<> |    ^-^-------^-------^------^^
55+------------+      |       |       |       |
56|    ...     |      |       |       |       |
57+------------+      |       |       |       |
58|            |      |       |       |       |
59|============|      |       |       |       |
60|Interrupt fd+------+  +----+  +----+  +----+
61+------------+         fd      Socket  Pipe
62```
63
64## ASOCKET, APACKET, and AMESSAGE
65
66The asocket, apacket, and amessage constructs exist only to wrap data while it transits on a Transport. An asocket handles a stream of apackets. An apacket consists of an amessage header featuring a command (`A_SYNC`, `A_OPEN`, `A_CLSE`, `A_WRTE`, `A_OKAY`, ...) followed by a payload (find more documentation in [protocol.md](protocol.md). There is no `A_READ` command because an asocket is unidirectional. To model a bi-directional stream, asocket have peers which go in the opposite direction.
67
68An asocket features a buffer containing apackets. If traffic is inbound, the buffer stores the apacket until it is consumed. If the traffic is oubound, the buffer stores apackets until they are sent down the wire (with `A_WRTE` commands).
69
70```
71+---------------------ASocket------------------------+
72 |                                                   |
73 | +----------------APacket Queue------------------+ |
74 | |                                               | |
75 | |            APacket     APacket     APacket    | |
76 | |          +--------+  +--------+  +--------+   | |
77 | |          |AMessage|  |AMessage|  |AMessage|   | |
78 | |          +--------+  +--------+  +--------+   | |
79 | |          |        |  |        |  |        |   | |
80 | |  .....   |        |  |        |  |        |   | |
81 | |          |  Data  |  |  Data  |  |  Data  |   | |
82 | |          |        |  |        |  |        |   | |
83 | |          |        |  |        |  |        |   | |
84 | |          +--------+  +--------+  +--------+   | |
85 | |                                               | |
86 | +-----------------------------------------------+ |
87 +---------------------------------------------------+
88```
89
90This system allows adb to multiplex data streams on an unique byte stream. Without going into too much detail, the amessage arg1 and arg2 fields are similar to the TCP local and remote ports, where the combination uniquely identifies a particular stream. Note that unlike TCP which features an [unacknowledged-send window](https://en.wikipedia.org/wiki/TCP_congestion_control), an apacket is sent only after the previous one has been confirmed to be received.
91This is more of an historical accident than a design decision.
92
93The two types of asocket (Remote and Local) differentiate between outbound and inbound traffic.
94
95## adbd <-> APPPLICATION communication
96
97This pipeline is detailed in [daemon/jdwp_service.cpp](../../daemon/jdwp_service.cpp) with ASCII drawings! The JDWP extension implemented by Dalvik/ART are documented in:
98- platform/dalvik/+/main/docs/debugmon.html
99- platform/dalvik/+/main/docs/debugger.html
100
101### Sync protocol
102
103To transfer files and directories, ADB places a smart-socket in SYNC mode and then issues SYNC commands. The SYNC protocol is documented in [sync.md](sync.md).
104Despite its name the `sync` protocol is also what powers operations such as `pull` and `push`.
105
106### ADB Wifi architecture
107
108[here](adb_wifi.md)
109
110### ADB Trade-In Mode
111
112[here](adb_tradeinmode.md)
113
114### Benchmark sample run for Pixel 8,USB
115
116```
117$ ./benchmark_device.py
118sink   100MiB (write RAM)  : 10 runs: median 128.07 MiB/s, mean 126.90 MiB/s, stddev: 19.37 MiB/s
119source 100MiB (read RAM)   : 10 runs: median 233.73 MiB/s, mean 250.81 MiB/s, stddev: 47.45 MiB/s
120push   100MiB (write flash): 10 runs: median 142.82 MiB/s, mean 145.49 MiB/s, stddev: 16.57 MiB/s
121pull   100MiB (read flash) : 10 runs: median 190.37 MiB/s, mean 189.08 MiB/s, stddev: 51.24 MiB/s
122dd     100MiB (write flash): 10 runs: median 121.57 MiB/s, mean 125.60 MiB/s, stddev: 15.81 MiB/s
123```
124
125### Tests
126
127#### Integration Tests
128Run integration tests as follows.
129
130```
131$ atest adb_integration_test_device
132$ atest adb_integration_test_adb
133```
134
135You can use a filter to run only a class of test.
136
137```
138atest adb_integration_test_device --test-filter=FileOperationsTest
139```
140
141You can also use the filter to run a single test in a class.
142
143```
144atest adb_integration_test_device --test-filter=FileOperationsTest#test_push_sync
145```
146
147#### Unit tests
148
149The list of all the units tests can be found in [TEST_MAPPING](../../TEST_MAPPING)
150
151
152### More Legacy documentation
153[socket-activation.md](socket-activation.md): ADB socket control protocol.
154