Google Git
Sign in
android / platform / packages / modules / adb / 0e0cfd7951b7ae72f2c19a4f41ff35e02c33febe
commit0e0cfd7951b7ae72f2c19a4f41ff35e02c33febe[log] [tgz]
authorTreeHugger Robot <treehugger-gerrit@google.com>Mon Jun 21 08:20:22 2021 +0000
committerAutomerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>Mon Jun 21 08:20:22 2021 +0000
tree22c51e9539a48bc0d3baee37967d557e09c423cc
parent3c5867f4b9820b3705cd0e58f01eda8976c4624e [diff]
parent49798a9b63a71d7e7fee22fa7ce49de1133c2271 [diff]
Merge changes I6bc4158b,Ieb0da0a7 into sc-dev am: 7caeb9d422 am: 49798a9b63

Original change: https://googleplex-android-review.googlesource.com/c/platform/packages/modules/adb/+/14804252

Change-Id: I6fdd0356b70e8b02ad862c778af93b028c25fffe
tree: 22c51e9539a48bc0d3baee37967d557e09c423cc
  1. apex/
  2. client/
  3. coverage/
  4. crypto/
  5. daemon/
  6. fastdeploy/
  7. fdevent/
  8. libs/
  9. pairing_auth/
  10. pairing_connection/
  11. proto/
  12. sysdeps/
  13. tls/
  14. tools/
  15. .clang-format
  16. adb.bash
  17. adb.cpp
  18. adb.h
  19. adb_auth.h
  20. adb_integration_test_adb.xml
  21. adb_integration_test_device.xml
  22. adb_io.cpp
  23. adb_io.h
  24. adb_io_test.cpp
  25. adb_listeners.cpp
  26. adb_listeners.h
  27. adb_listeners_test.cpp
  28. adb_mdns.cpp
  29. adb_mdns.h
  30. adb_test.xml
  31. adb_trace.cpp
  32. adb_trace.h
  33. adb_unique_fd.cpp
  34. adb_unique_fd.h
  35. adb_utils.cpp
  36. adb_utils.h
  37. adb_utils_test.cpp
  38. adb_wifi.h
  39. Android.bp
  40. benchmark_device.py
  41. bugreport_test.cpp
  42. compression_utils.h
  43. file_sync_protocol.h
  44. mdns_test.cpp
  45. MODULE_LICENSE_APACHE2
  46. NOTICE
  47. OVERVIEW.TXT
  48. OWNERS
  49. PREUPLOAD.cfg
  50. protocol.txt
  51. README.md
  52. security_log_tags.h
  53. services.cpp
  54. services.h
  55. SERVICES.TXT
  56. shell_protocol.h
  57. shell_service_protocol.cpp
  58. shell_service_protocol_test.cpp
  59. SOCKET-ACTIVATION.txt
  60. socket.h
  61. socket_spec.cpp
  62. socket_spec.h
  63. socket_spec_test.cpp
  64. socket_test.cpp
  65. sockets.cpp
  66. sockets.dia
  67. SYNC.TXT
  68. sysdeps.h
  69. sysdeps_test.cpp
  70. sysdeps_unix.cpp
  71. sysdeps_win32.cpp
  72. sysdeps_win32_test.cpp
  73. test_adb.py
  74. test_device.py
  75. TEST_MAPPING
  76. trace.sh
  77. transfer_id.h
  78. transport.cpp
  79. transport.h
  80. transport_benchmark.cpp
  81. transport_fd.cpp
  82. transport_test.cpp
  83. types.cpp
  84. types.h
  85. types_test.cpp
README.md

ADB Internals

If you are new to adb source code, you should start by reading OVERVIEW.TXT which describes the three components of adb pipeline.

This document is here to boost what can be achieved within a “window of naive interest”. You will not find function or class documentation here but rather the “big picture” which should allow you to build a mental map to help navigate the code.

Three components of adb pipeline

As outlined in the overview, this codebase generates three components (Client, Server (a.k.a Host), and Daemon (a.k.a adbd)). The central part is the Server which runs on the Host computer. On one side the Server exposes a “Smart Socket” to Clients such as adb or DDMLIB. On the other side, the Server continuously monitors for connecting Daemons (as USB devices or TCP emulator). Communication with a device is done with a Transport.

+----------+              +------------------------+
|   ADB    +----------+   |      ADB SERVER        |                   +----------+
|  CLIENT  |          |   |                        |              (USB)|   ADBD   |
+----------+          |   |                     Transport+-------------+ (DEVICE) |
                      |   |                        |                   +----------+
+-----------          |   |                        |
|   ADB    |          v   +                        |                   +----------+
|  CLIENT  +--------->SmartSocket                  |              (USB)|   ADBD   |
+----------+          ^   | (TCP/IP)            Transport+-------------+ (DEVICE) |
                      |   |                        |                   +----------+
+----------+          |   |                        |
|  DDMLIB  |          |   |                     Transport+--+          +----------+
|  CLIENT  +----------+   |                        |        |  (TCP/IP)|   ADBD   |
+----------+              +------------------------+        +----------|(EMULATOR)|
                                                                       +----------+

The Client and the Server are contained in the same executable and both run on the Host machine. Code sections specific to the Host is enclosed within ADB_HOST guard. adbd runs on the Android Device. Daemon specific code is enclosed in !ADB_HOST but also sometimes with-in __ANDROID__ guard.

“SMART SOCKET” and TRANSPORT

A smart socket is a simple TCP socket with a smart protocol built on top of it. 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.TXT.

On the other side, the Server communicate 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.

THREADING MODEL and FDEVENT system

At the heart of both the Server and Daemon is a main thread running an fdevent loop, which is an platform-independent abstraction over poll/epoll/WSAPoll monitoring file descriptors events. Requests and services are usually server from the main thread but some service requests result in new threads being spawned.

To allow for operations to run on the Main thread, fdevent features a RunQueue combined with an interrupt fd to force polling to return.

+------------+    +-------------------------^
|  RUNQUEUE  |    |                         |
+------------+    |  POLLING (Main thread)  |
| Function<> |    |                         |
+------------+    |                         |
| Function<> |    ^-^-------^-------^------^^
+------------+      |       |       |       |
|    ...     |      |       |       |       |
+------------+      |       |       |       |
|            |      |       |       |       |
|============|      |       |       |       |
|Interrupt fd+------+  +----+  +----+  +----+
+------------+         fd      Socket  Pipe

ASOCKET, APACKET, and AMESSAGE

The 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 in a amessage header featuring a command (A_SYNC, A_OPEN, A_CLSE, A_WRTE, A_OKAY, ...) followed by a payload (find more documentation in protocol.txt. There is no A_READ command because an asocket is unidirectional. To model a bi-directional stream, asocket have a peer which go in the opposite direction.

An asocket features a buffer where the elemental unit is an apacket. Is traffic is inbound, the buffer stores apacket until they are consumed. If the traffic is oubound, the buffer store apackets until they are sent down the wire (with A_WRTE commands).

+---------------------ASocket------------------------+
 |                                                   |
 | +----------------APacket Queue------------------+ |
 | |                                               | |
 | |            APacket     APacket     APacket    | |
 | |          +--------+  +--------+  +--------+   | |
 | |          |AMessage|  |AMessage|  |AMessage|   | |
 | |          +--------+  +--------+  +--------+   | |
 | |          |        |  |        |  |        |   | |
 | |  .....   |        |  |        |  |        |   | |
 | |          |  Data  |  |  Data  |  |  Data  |   | |
 | |          |        |  |        |  |        |   | |
 | |          |        |  |        |  |        |   | |
 | |          +--------+  +--------+  +--------+   | |
 | |                                               | |
 | +-----------------------------------------------+ |
 +---------------------------------------------------+

This system allows to multiplex data streams on an unique byte stream. Without entering too much into details, the amessage fields arg1 and arg2 are used alike in the TCP protocol where local and remote ports identify an unique stream. Note that unlike TCP which feature an “unacknowledged-send window”, an apacket is sent only after the previous one has been confirmed to be received.

The two types of asocket (Remote and Local) differentiate between outbound and inbound traffic.

adbd <-> APPPLICATION communication

This pipeline is detailed in services.cpp. The JDWP extension implemented by Dalvik/ART are documented in:

  • platform/dalvik/+/master/docs/debugmon.html
  • platform/dalvik/+/master/docs/debugger.html