mirror of
https://github.com/Droid-Deck/DroidDeck.git
synced 2026-11-18 12:28:40 +00:00
docs(phantom): how Android counts guest processes and why detaching cannot escape it (#2584)
* docs(phantom): how Android counts guest processes and why detaching cannot escape it * docs(phantom): clarify probe permissions and batch capture * docs(phantom): qualify probe precondition by SDK and size the limit device-wide * docs(phantom): keep phantom discovery on for the 12L probe and raise the limit instead * docs(phantom): warn about the CPU kill, raise the limit before the flag and restore both after the probe * docs(phantom): restore the monitor flag before the phantom limit after the probe * docs(phantom): restore the flag before the limit whether each is put or deleted
This commit is contained in:
1 parent
56fabbdbf0
commit
4527e93118
2 files changed
+211
No files matched your search
@@ -58,6 +58,24 @@ class PhantomProcessLimitTest {
|
||||
assertFalse(PhantomProcessLimit.verified("null", enabled = false, sdk = 33))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun android12LKeepsTheFlagAndNotTheCountLimit() {
|
||||
assertFalse(PhantomProcessLimit.usesDeviceConfig(32))
|
||||
assertEquals(
|
||||
listOf("settings put global settings_enable_monitor_phantom_procs false"),
|
||||
PhantomProcessLimit.shellCommands(enabled = false, sdk = 32),
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun android12KeepsTheCountLimitBecauseItHasNoFlag() {
|
||||
assertTrue(PhantomProcessLimit.usesDeviceConfig(31))
|
||||
assertTrue(
|
||||
PhantomProcessLimit.shellCommands(enabled = false, sdk = 31)
|
||||
.any { it.startsWith("device_config put activity_manager max_phantom_processes") }
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun developerToggleStartsAtAndroid14() {
|
||||
assertFalse(PhantomProcessLimit.hasDeveloperToggle(33))
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
# Android's child-process limit and the guest session
|
||||
|
||||
Since Android 12 the platform counts the processes an app forks as "phantom processes" and
|
||||
kills them under pressure. A Wine, FEX or Steam session forks dozens of them, so this limit
|
||||
decides whether a session survives. This note records how the platform counts, what it kills,
|
||||
why the guest cannot leave the count, and what DroidDeck changes on the device.
|
||||
|
||||
## What the platform counts
|
||||
|
||||
Discovery is a cgroup scan, not a parent-child relation. For every app process the platform
|
||||
knows, it reads the cgroup member list of that process and takes every pid that is not a known
|
||||
app process as a phantom of it:
|
||||
|
||||
- `frameworks/base/services/core/java/com/android/server/am/PhantomProcessList.java:117-122`
|
||||
holds the two cgroup roots (`/acct/uid_` for cgroup v1, `/sys/fs/cgroup/uid_` for v2) and
|
||||
the `cgroup.procs` file name.
|
||||
- `PhantomProcessList.java:136-208` scans every app process; `:220-222` builds the path
|
||||
`/…/uid_<uid>/pid_<appPid>/cgroup.procs`; `:238-275` turns a pid that is not a known app
|
||||
process into a phantom of that app process.
|
||||
- The mechanism is the same in Android 12.0, 12.1, 13, 14, 15, 16 and in `main`. Only the
|
||||
path lookup moved to a native helper in 16 and `main`
|
||||
(`PhantomProcessList.java:205`).
|
||||
|
||||
DroidDeck's guest is forked by the main app process: `SessionService` starts it with
|
||||
`HostProcess.start` (`app/src/main/java/com/droiddeck/launcher/session/SessionService.kt:779`),
|
||||
and both `SessionService` and `SessionActivity` run in the main process
|
||||
(`app/src/main/AndroidManifest.xml:284-293`, `:326-329`). Every guest process is therefore a
|
||||
phantom of the main app process.
|
||||
|
||||
## What the platform kills
|
||||
|
||||
1. Count trim. When the number of phantom processes in the system passes
|
||||
`MAX_PHANTOM_PROCESSES` (32 by default, `ActivityManagerConstants.java:192`), the surplus
|
||||
is killed, starting with the phantoms whose parent app has the least importance
|
||||
(`PhantomProcessList.java:423-466`).
|
||||
2. Excessive CPU group kill. Every five minutes the platform measures each app's CPU use. For
|
||||
an app whose process state is HOME or less important (backgrounded), a phantom process that
|
||||
used more than its threshold (25, 25, 10 or 2 percent) is killed together with its phantom
|
||||
siblings **and the app process itself**
|
||||
(`ActivityManagerService.java:16114-16152`, `PhantomProcessList.java:496-515`). A
|
||||
foreground DroidDeck is exempt; a backgrounded one is not.
|
||||
|
||||
The second path is the one that ends a session without an error message in the guest log: the
|
||||
app process dies with it.
|
||||
|
||||
## The gate, and how the versions differ
|
||||
|
||||
Both paths are behind the feature flag `settings_enable_monitor_phantom_procs`, whose default
|
||||
is on. The flag is read from `Settings.Global` first
|
||||
(`frameworks/base/core/java/android/util/FeatureFlagUtils.java:68-70`, `:272-283`). When it is
|
||||
off, the trim returns early (`PhantomProcessList.java:423-427`) and the phantom CPU check is
|
||||
skipped (`ActivityManagerService.java:16117-16118`, `:16144-16148`). From 12L on it also stops
|
||||
the periodic cgroup scan that discovers phantom processes (`AppProfiler.java:1788-1829` at
|
||||
`android-12.1.0_r1`).
|
||||
|
||||
| Android | flag `settings_enable_monitor_phantom_procs` | count limit | CPU group kill |
|
||||
| --- | --- | --- | --- |
|
||||
| 12.0 (SDK 31) | does not exist | DeviceConfig `activity_manager/max_phantom_processes`, default 32 | not gated |
|
||||
| 12L (SDK 32) | exists | flag | flag |
|
||||
| 13 and later (SDK 33+) | exists | flag | flag |
|
||||
|
||||
The flag was added in 12.1. On 12.0 the count limit comes from DeviceConfig
|
||||
(`ActivityManagerConstants.java:1202-1206` in 12.0) and the CPU group kill has no gate at all
|
||||
(`ActivityManagerService.java:14237-14271` in 12.0).
|
||||
|
||||
## Why the guest cannot leave the count
|
||||
|
||||
- **Reparenting does not help.** A double fork, `setsid()` or an orphaning parent changes the
|
||||
parent and the session, not the cgroup. Cgroup membership is inherited at fork and only a
|
||||
write into another cgroup's `cgroup.procs` changes it, so the platform still finds the pid
|
||||
in the app process's cgroup and still counts it. On cgroup v2 the uid group cannot take
|
||||
processes while it has the per-process groups as children, so there is no unscanned group to
|
||||
move into.
|
||||
- **A separate `:process` service only moves the count.** The scan covers every app process the
|
||||
platform knows, so the guest tree started from another service of the same app is counted
|
||||
against that service. The manifest already has such services
|
||||
(`app/src/main/AndroidManifest.xml:78`, `:244`, `:255`), and the guest tree is one coupled
|
||||
userspace whose graphics, input and session state would not survive the split.
|
||||
- **The platform's own blind spot is out of reach.** Processes forked from an app zygote are
|
||||
skipped by the scan (`PhantomProcessList.java:153-155`), but `android.os.AppZygote` is
|
||||
`@hide` (`frameworks/base/core/java/android/os/AppZygote.java:36-38`) and hidden API
|
||||
enforcement keeps it away from apps.
|
||||
- **Detaching would break the session.** The guest tree is deliberately kept under a reaper: the
|
||||
processes that load the session library mark themselves as child subreapers, so that a
|
||||
double-forked Xwayland is reparented inside the session instead of to init, where a vendor
|
||||
kernel's orphan reaper would kill it (`tools/linuxfs/preload/subreaper.c:1-16`). A guest
|
||||
tree that leaves the app's process tree leaves that arrangement with nothing to reap it.
|
||||
|
||||
## What DroidDeck changes on the device
|
||||
|
||||
`PhantomProcessLimit` (`app/src/main/java/com/droiddeck/launcher/core/PhantomProcessLimit.kt`)
|
||||
holds the platform lever per version: the DeviceConfig count limit on SDK 31 and the flag from
|
||||
SDK 32 up (`:23-37`). `WirelessAdbFix`
|
||||
(`app/src/main/java/com/droiddeck/launcher/core/WirelessAdbFix.kt:219-228`) runs those shell
|
||||
commands over wireless debugging when the user has no computer at hand, and the gate screen
|
||||
shows the result. The names on that screen come from `strings.xml` (`phantom_title_on`
|
||||
"Child-process limit is on", `phantom_instructions_fix`, `phantom_fix_toggle`).
|
||||
|
||||
## The remaining gap on Android 12.0
|
||||
|
||||
On SDK 31 the count trim is covered by the DeviceConfig write, but the backgrounded CPU group
|
||||
kill is not: the flag does not exist there, and the CPU thresholds live in the global string
|
||||
`activity_manager_constants` (`power_check_max_cpu_1` … `power_check_max_cpu_4`), not in
|
||||
DeviceConfig. In 12.0 the DeviceConfig listener reacts to `max_phantom_processes` only
|
||||
(`ActivityManagerConstants.java:654-757`), while the thresholds are parsed from
|
||||
`Settings.Global activity_manager_constants` (`:852-892`). Raising them means rewriting that
|
||||
global string, which changes the CPU kill thresholds for every app on the device. That is a
|
||||
trade the developers have to accept; DroidDeck does not do it on its own.
|
||||
|
||||
## Probe to run on hardware
|
||||
|
||||
The mechanism above is source-verified. The probe below settles the two points a source read
|
||||
cannot: what a device actually does with detached children, and whether the app uid may write
|
||||
another cgroup's `cgroup.procs`. It needs a device with the guest running.
|
||||
|
||||
Precondition: keep `settings_enable_monitor_phantom_procs` enabled on Android 12L (SDK 32) and
|
||||
later, because disabling it also stops the cgroup scan, so no snapshot would discover either batch
|
||||
(`AppProfiler.java:1788-1829` at `android-12.1.0_r1`). Android 12.0 (SDK 31) has no such flag and
|
||||
scans unconditionally (`AppProfiler.java:1833-1834` at `android-12.0.0_r1`). An enabled flag, and
|
||||
every 12.0 device, also keeps the backgrounded CPU group kill active, which can end the guest
|
||||
together with the app process (see "What the platform kills", item 2). Keep DroidDeck in the
|
||||
foreground and stop CPU-intensive guest programs before the probe.
|
||||
|
||||
The limit counts phantom processes of every app on the device, not only the probe's, so raise it
|
||||
before anything can trim. Record the current flag and limit values first. Then raise
|
||||
`max_phantom_processes` well above any plausible device-wide count, and only after that enable the
|
||||
flag if it was disabled, because a flag enabled under the default limit of 32 can trim existing
|
||||
phantoms of every app at once. Wait for the platform to discover the existing phantoms, read the
|
||||
device-wide phantom count, and check that the limit is above that count, plus both batches (80),
|
||||
plus headroom for processes the guest and other apps start meanwhile; raise it again if not. With
|
||||
the limit at its default, starting 80 long-lived processes can trigger the platform trim and
|
||||
disrupt the guest session and processes of other apps. Restore the recorded values once the probe
|
||||
processes have exited, in reverse order: the flag first, then the limit, because lowering the limit
|
||||
schedules a trim that is skipped only while the flag is disabled.
|
||||
|
||||
Run the `sleep` loops from the app's own shell so the children run under the app uid. Run each
|
||||
`dumpsys activity processes` snapshot from an authorized ADB shell, because the app uid normally
|
||||
cannot read that dump. After each batch, record the child PIDs and wait long enough for the
|
||||
platform to discover them before taking the snapshot.
|
||||
|
||||
```sh
|
||||
# record the current values
|
||||
adb shell settings get global settings_enable_monitor_phantom_procs
|
||||
adb shell device_config get activity_manager max_phantom_processes
|
||||
|
||||
# raise the limit first, then enable the flag on SDK 32 and later
|
||||
adb shell device_config put activity_manager max_phantom_processes 1000
|
||||
adb shell settings put global settings_enable_monitor_phantom_procs true
|
||||
# after platform discovery: device-wide phantom count
|
||||
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'
|
||||
|
||||
# from the app's own shell: attached children
|
||||
for i in $(seq 1 40); do sleep 600 & echo $!; done
|
||||
# from an authorized ADB shell, after platform discovery
|
||||
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'
|
||||
|
||||
# from the app's own shell: detached children
|
||||
# (the middle process exits, so the child is reparented to init)
|
||||
for i in $(seq 1 40); do ( setsid sleep 600 & echo $! ) ; done
|
||||
# from an authorized ADB shell, after platform discovery
|
||||
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'
|
||||
|
||||
# from the app's own shell
|
||||
cat /proc/<appPid>/cgroup
|
||||
|
||||
# whether the uid may move a child out of the scanned cgroup
|
||||
echo <childPid> > /sys/fs/cgroup/uid_<uid>/cgroup.procs
|
||||
|
||||
# from the app's own shell: end the probe processes
|
||||
kill <childPids>
|
||||
# restore the flag first: put the recorded value, or delete the key if it was "null"
|
||||
adb shell settings put global settings_enable_monitor_phantom_procs <recordedFlag>
|
||||
adb shell settings delete global settings_enable_monitor_phantom_procs
|
||||
# then the limit: put the recorded value, or delete the key if it was "null"
|
||||
adb shell device_config put activity_manager max_phantom_processes <recordedLimit>
|
||||
adb shell device_config delete activity_manager max_phantom_processes
|
||||
```
|
||||
|
||||
Compare the PIDs recorded for each batch with the phantom list in the snapshot taken after that
|
||||
batch. Expected from the source: both batches are counted, the detached ones included, and the
|
||||
cgroup write fails (no unscanned group, or no permission).
|
||||
|
||||
## References
|
||||
|
||||
- AOSP `frameworks/base`: `services/core/java/com/android/server/am/PhantomProcessList.java`,
|
||||
`services/core/java/com/android/server/am/ActivityManagerService.java`,
|
||||
`services/core/java/com/android/server/am/ActivityManagerConstants.java`,
|
||||
`core/java/android/util/FeatureFlagUtils.java`, checked at tags android-12.0.0_r1,
|
||||
android-12.1.0_r1, android-13.0.0_r1, android-14.0.0_r2, android-15.0.0_r1,
|
||||
android-16.0.0_r1 and `main`.
|
||||
- Pull request 1394, the OEM check of the same settings, and the issues it links, 713 and 1083.
|
||||
- Termux meets the same limit on Android 12 and solves it the same way, with detection plus
|
||||
the adb path (termux-app issues 4388 and 4857).
|
||||
Reference in new issue
Block a user