Gitiles
Code Review Sign In
review.blissroms.org / platform_packages_modules_adb / 3dac5b70f053ca2988e9ac77eb64f55b9193acbb
commit3dac5b70f053ca2988e9ac77eb64f55b9193acbb[log] [tgz]
authorRyan Prichard <rprichard@google.com>Tue Oct 11 13:09:35 2022 -0700
committerRyan Prichard <rprichard@google.com>Tue Oct 11 13:26:22 2022 -0700
tree9571e840ff177e38abccb33c4d7b1e74e364fb6b
parent59be29d99b8632b1f2e6f1eb7b9e23eb53ba34f5 [diff]
Refactor ReadAcknowledgements to fix two race conditions

Race 1:
 * Suppose there is a single successful copy to acknowledge.
 * The early opportunistic ReadAcknowledgements call (read_all==false)
   won't block.
 * If the 8-byte ID_OKAY is ready to read soon enough, then the first
   adb_poll and adb_read calls will bring the entire 8 bytes into
   acknowledgement_buffer_.
 * ReadAcknowledgements then reaches "// We don't want to read again
   yet, because the socket might be empty." and restarts the loop.
 * The second adb_poll finds no more data and ReadAcknowledgements
   returns.
 * The final blocking ReadAcknowledgements call (read_all==true) calls
   adb_poll and hangs because there are no more bytes to read.

Race 2:
 * Suppose that when ReadAcknowledgements (read_all==true) is called,
   the socket has less than a complete header available (i.e.
   1 <= NUM_BYTES <= 7).
 * The first adb_read will return the partial header, then
   ReadAcknowledgements will reach "// Early exit if we run out of data
   in the socket." We're supposed to block until all the
   acknowledgements are read, though!
 * adb_read uses TEMP_RETRY_FAILURE, but that merely restarts an EINTR
   syscall -- it doesn't ensure that all requested bytes were read.
 * I found this bug by inspection. I haven't reproduced it.

Factor out a "read_until_amount" function that fills
acknowledgement_buffer_ to a given number of bytes (or exits early if
non-blocking). Use this function to read both the copy response header
and the copy response error message.

This patch establishes an invariant: when ReadAcknowledgements returns,
acknowledgement_buffer_ may be non-empty, but it won't have a complete
message in it.

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

THREADING MODEL and FDEVENT system

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

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

+---------------------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 daemon/jdwp_service.cpp with ASCII drawings! The JDWP extension implemented by Dalvik/ART are documented in:

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