commit | 4bd71c20f7a96bf574a13c02b6a53e1352ab97dd | [log] [tgz] |
---|---|---|
author | Peter Collingbourne <pcc@google.com> | Tue Feb 27 19:37:41 2024 -0800 |
committer | Peter Collingbourne <pcc@google.com> | Mon Apr 01 15:18:49 2024 -0700 |
tree | 569cc714b402aa956d1fa89ba40afbb466edf72e | |
parent | 19cd8dc9e1a8529804ecedd29714416db84cbe25 [diff] |
adb: Do not use fs_config unless we are root (try 3). This enables fs_config for /data when pushing files as root. Also, without this, adb push to /tmp fails as the shell user. When pushing to a directory that does not have an explicit fs_config, such as /data/local/tmp or /tmp, use the original file mode. Because adb copies u permissions into g and o (and in general because the umask on the host may have made these files world writable), this requires adding more fs_config entries to cover directories that may contain dex files i.e. /{odm,product,system,system_ext,vendor}/{framework,app,priv-app} to avoid hitting a SecurityException caused by writable dex files, e.g. 04-01 21:22:16.980 10110 4815 4815 E AndroidRuntime: FATAL EXCEPTION: main 04-01 21:22:16.980 10110 4815 4815 E AndroidRuntime: Process: android.test.app.system_priv, PID: 4815 04-01 21:22:16.980 10110 4815 4815 E AndroidRuntime: java.lang.SecurityException: Writable dex file '/system/priv-app/loadlibrarytest_system_priv_app/loadlibrarytest_system_priv_app.apk' is not allowed. 04-01 21:22:16.980 10110 4815 4815 E AndroidRuntime: at dalvik.system.DexFile.openDexFileNative(Native Method) 04-01 21:22:16.980 10110 4815 4815 E AndroidRuntime: at dalvik.system.DexFile.openDexFile(DexFile.java:406) Bug: 171233429 Bug: 311263616 Change-Id: I18f70095c793d08a25ff59e1851f6dc7648ce4dc
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.
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.
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.
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
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.
This pipeline is detailed in daemon/jdwp_service.cpp with ASCII drawings! The JDWP extension implemented by Dalvik/ART are documented in:
$ ./benchmark_device.py sink 100MiB: 10 runs: median 27.00 MiB/s, mean 26.39 MiB/s, stddev: 1.11 MiB/s source 100MiB: 10 runs: median 36.97 MiB/s, mean 37.05 MiB/s, stddev: 0.46 MiB/s push 100MiB: 10 runs: median 331.96 MiB/s, mean 329.81 MiB/s, stddev: 14.67 MiB/s pull 100MiB: 10 runs: median 34.55 MiB/s, mean 33.57 MiB/s, stddev: 2.54 MiB/s