mirror of
https://github.com/Droid-Deck/DroidDeck.git
synced 2026-11-21 13:55:58 +00:00
chore: merge main into feat/lse-emu
This commit is contained in:
commit
73104aff03
667 files changed
+75245
-4143
No files matched your search
+19
-1
@@ -28,7 +28,7 @@ Player controls and observations work over authorized ADB on any build: `state`,
|
||||
`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `pacing`,
|
||||
`thermal`, `displays`, `wake`, `glasses` (except `glasses raw`), and `access`.
|
||||
|
||||
**Setup > Diagnostics > Debugging tools** is off by default in every build, including debug builds.
|
||||
**Setup > Developer > Debugging tools** is off by default in every build, including debug builds.
|
||||
It enables `run`, `guest`, `cdp`, all `env` operations, `override`, `prefs`, and `glasses raw`. The
|
||||
toggle switches directly without a confirmation dialog. The bridge refuses to change it through `ui`
|
||||
or preference writes. The existing preference key, `setting-agent-commands` test tag, JSON command
|
||||
@@ -122,6 +122,10 @@ tools/droiddeckctl input swipe 100 600 100 100 --duration 400
|
||||
tools/droiddeckctl input pad a
|
||||
tools/droiddeckctl input stick left 0 -1 --hold 500
|
||||
tools/droiddeckctl input trigger right 1.0
|
||||
tools/droiddeckctl input pen tap 0.5 0.5 --pressure 0.7
|
||||
tools/droiddeckctl input pen stroke 0.2 0.5 0.8 0.5 --pressure 0.1:0.9 --tilt-x=-30:30
|
||||
tools/droiddeckctl input pen hover 0.3 0.5 --to 0.7 0.5 --duration 600
|
||||
tools/droiddeckctl input pen button primary 0.5 0.5
|
||||
|
||||
tools/droiddeckctl ui dump
|
||||
tools/droiddeckctl ui click rail-steam
|
||||
@@ -196,6 +200,20 @@ virtual pad, the same one the on-screen controls drive, so games that ignore tou
|
||||
`launch`, `quit` and `cdp` need a Steam session; `focus` and `wait focused` need gamescope (every
|
||||
mode except the desktop).
|
||||
|
||||
`input pen` does not go through the app. It registers a virtual pen with `adb shell uinput -`, so
|
||||
Android's own input reader makes the stylus events, as for a built-in pen, and it works on whatever
|
||||
is on screen, without a session or Setup > Developer > Debugging tools. Positions are fractions of
|
||||
the screen as shown; `dumpsys input` gives the frame, rotation and size of the display Android maps
|
||||
internal touchscreens to. `hover` comes near and glides to `--to`; `tap`, `stroke` and `button`
|
||||
hover for `--hover-ms` (80) before and after the touch or the button press. Each takes
|
||||
`--tool pen|eraser`, `--tilt-x` and `--tilt-y` in degrees, `--distance` in device units (0 to 255)
|
||||
and `--rate` (120 samples a second); `--pressure` and tilt take `FROM:TO` ranges, written
|
||||
`--tilt-x=-30:30` when they start negative. A gesture lasts at most 30 s. `UINPUT_UNAVAILABLE`
|
||||
means the shell has no `uinput` or cannot write `/dev/uinput`, `NO_VIEWPORT` that there is no
|
||||
internal display or it is off, and `UINPUT_FAILED` that `uinput` stopped early; all three exit 3.
|
||||
It needs Android 14 QPR2 or later: the `uinput` of Android 12 to 14 QPR1 takes only numeric codes
|
||||
and the USB or Bluetooth bus, so there the pen ends with `UINPUT_FAILED`.
|
||||
|
||||
## State (schema 2)
|
||||
|
||||
`state` returns `schema`, `build`, `appVersion`, `runtime {installed, version}`,
|
||||
|
||||
@@ -4,7 +4,9 @@ Settings → Boot movie has four tabs.
|
||||
|
||||
- **Installed**: "Browse" lists every movie Steam can play: DroidDeck's two, plus every `.webm` in Steam's
|
||||
`config/uioverrides/movies` folder (imported, installed from SteamDeckRepo, or put there by Steam). The list is re-read
|
||||
every two seconds, so a movie picked or removed inside Steam shows up, and a movie picked inside Steam becomes the choice.
|
||||
every two seconds, so a movie picked or removed inside Steam shows up, and a movie picked inside Steam becomes the choice. The Shuffle switch is Steam's own `Shuffle` setting (`startup_movie_shuffle` in
|
||||
Steam's client settings, `Shuffle` next to `MovieID` and `LocalPath`): it is written at the next session start, a change made in Steam is
|
||||
taken over, and with it off the selected movie plays as before.
|
||||
- **Import**: the same importer as before (copy, remux or on-device transcode to VP8/Opus). The result is written into
|
||||
Steam's movies folder, so Steam lists it as well.
|
||||
- **SteamDeckRepo**: browses `https://steamdeckrepo.com/api/posts` (`sort`, `device`, `search`, `page`; 12 posts a page).
|
||||
|
||||
@@ -104,7 +104,7 @@ Run the batch/reference and work-budget regressions with
|
||||
|
||||
## Game debug logs
|
||||
|
||||
Under **Setup > Diagnostics**, enable **Session logs** and **Game debug logs**
|
||||
Under **Setup > Developer**, enable **Session logs** and **Game debug logs**
|
||||
before reproducing a Windows game problem. Game debug logs is off by default and
|
||||
is available when Session logs is enabled. It applies to the next game launch through DroidDeck's
|
||||
Valve or third-party Proton wrapper, including added games and store shortcuts.
|
||||
@@ -142,7 +142,7 @@ that diagnostics were skipped instead of writing uncollected files elsewhere.
|
||||
|
||||
## Enhanced diagnostics
|
||||
|
||||
Use **Setup > Diagnostics > Enhanced diagnostics for next session** when normal
|
||||
Use **Setup > Developer > Enhanced diagnostics for next session** when normal
|
||||
session logs are not enough. The setting is one-shot: DroidDeck creates and
|
||||
retains the next session's log directory, records the diagnostic profile, then
|
||||
turns the setting off. It also enables the existing game diagnostic environment
|
||||
@@ -254,6 +254,14 @@ The former feature-level rules for Caravan SandWitch, RoboCop: Rogue City,
|
||||
ReSkate and Cyberpunk 2077 compensated for the global `12_2` override and are
|
||||
removed. Stellar Blade also uses automatic detection. The separate Deep Rock
|
||||
Galactic GDK ray-tracing opt-out and Mali bridge capability cap remain.
|
||||
|
||||
"Skip GL error checks" (under "Client interface") sets `MESA_NO_ERROR=1` for the client
|
||||
interface and Chromium apps only. Games keep Mesa's GL error checks: with
|
||||
`MESA_NO_ERROR`, an invalid call such as `glBufferData` with no buffer bound reads
|
||||
a NULL buffer object instead of returning `GL_INVALID_OPERATION`, and the game's
|
||||
render thread stops. A game profile entry, or `MESA_NO_ERROR` in the session's own
|
||||
environment, still applies to games.
|
||||
|
||||
Other picker suggestions are editable starting values and are enabled only when
|
||||
added and saved. Older or
|
||||
custom components can support a different set of options. Android Wine wrapper,
|
||||
@@ -275,7 +283,12 @@ DroidDeck instead publishes an atomic JSON snapshot at
|
||||
`/root/.config/droiddeck/game-environment.json`. Both its Valve ARM64 Proton
|
||||
wrapper and adopted third-party Proton wrappers execute `droiddeck-game-env`,
|
||||
which reads that snapshot for each real game launch and uses `execvpe` to start
|
||||
Proton. Probe prefix `compatdata/0` and non-launch verbs are unchanged. Malformed
|
||||
Proton. Probe prefix `compatdata/0` and non-launch verbs are unchanged. A game launch
|
||||
adds `tabtip.exe=d` to `WINEDLLOVERRIDES` unless the launch has `SteamDeck=1`
|
||||
or the overrides already set `tabtip.exe` (also as `*tabtip.exe` or
|
||||
`tabtip.exe.dll`): Proton's tabtip only opens Steam's
|
||||
keyboard with `SteamDeck=1`, but it always runs UI Automation queries inside the
|
||||
focused game, which crash games that answer them (Godot 4.5 AccessKit). Malformed
|
||||
configuration falls back to the inherited environment without evaluating its
|
||||
contents. Both component and environment selection normalize signed non-Steam
|
||||
prefix IDs to unsigned IDs.
|
||||
|
||||
@@ -9,8 +9,10 @@ Every five seconds the monitor reads `MemAvailable`, swap headroom and memory PS
|
||||
headroom means less than one fifth of total RAM (bounded to 512–1536 MiB), or at least 1%
|
||||
`some avg10` memory stall with less than one third of RAM available. Pressure requests target
|
||||
only the launcher processes already recognized by the monitor, never the game. They require
|
||||
at least 128 MiB launcher RSS and enough free swap to cover its entire RSS while leaving
|
||||
one fifth of swap (at least 256 MiB) free. The regular automatic client request uses the
|
||||
at least 128 MiB launcher RSS and enough free swap to cover its anonymous RSS while leaving
|
||||
one fifth of swap (at least 256 MiB) free. File-backed resident pages do not consume this
|
||||
budget: the page-out helper targets private anonymous mappings. If `RssAnon` is absent from a
|
||||
process's status, its full RSS is used instead. The regular automatic client request uses the
|
||||
same swap guard. An explicit session RAM cap retains its existing behavior.
|
||||
|
||||
Pressure requests are at least 30 seconds apart. Reclaiming less than 16 MiB doubles the
|
||||
@@ -41,27 +43,35 @@ reduced aggregate launcher RSS only from 263 to 255 MiB and backed off. Thus lau
|
||||
does not resolve this load failure, and this run did not exhaust swap. The unevictable/shmem
|
||||
growth needs allocation attribution before treating it as a driver or GPU-memory diagnosis.
|
||||
|
||||
## Low-RAM devices: compressing idle game memory
|
||||
## Pressure reclaim: compressing idle game memory
|
||||
|
||||
On devices with at most 13 GiB `MemTotal` (every 12 GB phone and handheld and below), the
|
||||
monitor also compresses the game session itself when memory runs out. The trigger is absolute
|
||||
headroom, not a percentage: Android's `lmkd` killed a session on a 7.5 GiB device with
|
||||
The monitor also compresses the game session itself when observed pressure approaches the
|
||||
system kill boundary. There is no RAM-size gate. The trigger is absolute real headroom, not a
|
||||
percentage: Android's `lmkd` killed a session on a 7.5 GiB device with
|
||||
490 MiB still available, so a 95% used threshold (about 400 MiB left on 8 GB) is already past the
|
||||
kill. A world load added 1 GiB of GPU memory in about ten seconds, and compressing 1.4 GiB took
|
||||
2.6 seconds, so the request has to leave room for both.
|
||||
|
||||
The session request runs when available memory falls below a quarter of RAM (bounded to
|
||||
768–2560 MiB, 1.85 GiB on an 8 GB device), or below one and a half times that with at least 1%
|
||||
`some avg10` memory stall. One request pages out every session process that loaded
|
||||
`libblsession.so`: the game, Wine and its services, plus the launcher processes unless their
|
||||
compression is turned off, under a single wait. It runs before the launcher-only check, which
|
||||
can wait up to 12 seconds for acknowledgements. While a game runs and available memory is under
|
||||
twice that level, memory is read every second instead of every five. Requests are at least 30 seconds apart and need the same swap reserve as launcher
|
||||
requests. When the session has read back more than half of what the previous request compressed,
|
||||
that memory is in use: the request is skipped and the wait doubles, up to five minutes. A
|
||||
request whose memory stayed compressed resets it to 30 seconds. Below half the headroom the
|
||||
wait is ignored and only the 30-second spacing applies. The state resets when the game exits. Devices above 13 GiB keep the
|
||||
launcher-only behaviour.
|
||||
Performance > Compress idle game memory turns this off (`BL_ZRAM_IDLE=0`); launcher compression
|
||||
and the RAM cap are unaffected.
|
||||
|
||||
The session request runs when real headroom falls below a quarter of RAM (bounded to
|
||||
768–2560 MiB), or below one and a half times that with at least 1% `some` or `full avg10`
|
||||
memory stall. Real headroom subtracts positive growth in KGSL allocation, `Unevictable`, and
|
||||
`Shmem` from `MemAvailable`; a rapid fall also qualifies near twice the headroom. The monitor
|
||||
may first request page-out of idle Steam and hidden launchers, subject to the Performance
|
||||
setting and client reclaim limits. When both qualify, both requests are sent before waiting
|
||||
for either to complete, so a slow launcher acknowledgement does not delay the game request. Until the client
|
||||
request finishes, its anonymous RSS remains reserved from the session's swap budget. Completion
|
||||
and backoff are measured against the processes that received each request, even if a later scan
|
||||
finds different processes. The session request targets processes that loaded
|
||||
`libblsession.so`: the game, Wine and its services, and excludes Steam and hidden launchers.
|
||||
Requests are at least 30 seconds apart and need the same
|
||||
swap reserve as launcher requests. When the session has read back more than half of what the
|
||||
previous request compressed, that memory is in use: the request is skipped and the wait doubles,
|
||||
up to five minutes. A request whose memory stayed compressed resets it to 30 seconds. Below half
|
||||
the headroom the wait is ignored and only the 30-second spacing applies. The state resets when
|
||||
the game exits.
|
||||
|
||||
Measured on a Retroid Pocket Duo (7.5 GiB, kernel 6.6, 6 GiB lzo-rle zram plus a 4 GiB swap file)
|
||||
entering the world in World of Warcraft: Forever, one run each:
|
||||
@@ -91,7 +101,8 @@ A second run on that build showed the trigger arriving too late: character selec
|
||||
there. During the load, available memory crossed the headroom 9 seconds after Enter World, but the
|
||||
launcher check ran first and waited 12 seconds for acknowledgements; the game request started at
|
||||
21 seconds, moved about 200 MiB, and `lmkd` ended the session at 30 seconds. The quarter-of-RAM
|
||||
level and the game-first single request address both.
|
||||
level starts reclaim earlier. Sending both requests before waiting removes the launcher
|
||||
acknowledgement delay; it does not guarantee that reclaim can keep up with every loading peak.
|
||||
|
||||
Without root an app cannot write its memory cgroup's `memory.reclaim` (owned by `system`),
|
||||
`process_madvise` on another process returns `EPERM`, `PAGEMAP_SCAN` is absent before Linux 6.7,
|
||||
|
||||
@@ -122,11 +122,16 @@ What it does, per feature:
|
||||
- The source must be memory the application has mapped; DXVK's staging memory is.
|
||||
- Decoded texels go through the layer's own staging buffers, recycled when the command buffer is reset.
|
||||
- Copies from a BC image into a buffer, and between BC and uncompressed images, are skipped with a warning.
|
||||
- `dualSrcBlend`: reports maxFragmentDualSrcAttachments 1. DXVK 2.x and 3.x require it for D3D11.
|
||||
- Fragment outputs with `Index 1` become Private, in shader modules and in inline stage code.
|
||||
- SRC1 blend factors become source alpha: `SRC1_COLOR` and `SRC1_ALPHA` → `SRC_ALPHA`, their `ONE_MINUS_` forms → `ONE_MINUS_SRC_ALPHA`.
|
||||
- Pipelines and `vkCmdSetColorBlendEquationEXT` both.
|
||||
- Why alpha: output 0's color is the paint, its alpha is the usual coverage. Per-channel coverage collapses to one value; blending stays plain alpha blending, not tinted by the paint.
|
||||
|
||||
Files:
|
||||
- `layer.c`: loader plumbing, feature and limit reporting, device creation, the hook table.
|
||||
- `pipeline.c`: pipelines, shader modules, viewports.
|
||||
- `spirv.c`: the SPIR-V rewriter for clip and cull distances.
|
||||
- `spirv.c`: the SPIR-V rewriter for clip and cull distances and the second blend source.
|
||||
- `bc.c`: BC formats, images and uploads.
|
||||
- `VkLayer_droiddeck_mali_compat.json`: implicit layer manifest.
|
||||
|
||||
@@ -142,7 +147,8 @@ How it ships:
|
||||
- Guest paths: `usr/local/lib/droiddeck-mali/` and `usr/local/share/vulkan/implicit_layer.d/`.
|
||||
|
||||
Not done yet:
|
||||
- Unit tests for the SPIR-V rewriter. It is untested beyond DXVK's shaders, and unknown whether Silksong's shaders used clip distances at all.
|
||||
- Unit tests for the clip and cull distance rewriter. It is untested beyond DXVK's shaders, and unknown whether Silksong's shaders used clip distances at all.
|
||||
- The dual-source rewrite has them: `tools/tests/test_mali_compat_layer.py`.
|
||||
- Performance: BC decoding on the CPU makes loads slow. A compute-shader decoder would be the next step.
|
||||
|
||||
## Changes on the branch
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# Pen input
|
||||
|
||||
A pen on the phone's screen, or an external drawing tablet, drives the session's pointer like a mouse: hover moves
|
||||
the pointer, the tip holds the left button and the side button right-clicks. Fingers keep their touch mode.
|
||||
|
||||
The settings are a "Pen" group after the touch settings, in the Steam and Desktop sheets' **Controls** tab and on
|
||||
the session drawer's **Controller** page. The group is shown once the phone has a stylus device or a pen event was
|
||||
seen; the first of either sets `penSeen`, which a settings reset keeps. Before Android 14 every touchscreen whose
|
||||
driver reports a tool type has the stylus source, pen or not, so there a touchscreen counts only with its first pen
|
||||
event.
|
||||
|
||||
## Modes
|
||||
|
||||
`pen`: Mouse (default) or Touch.
|
||||
|
||||
| | Mouse | Touch |
|
||||
|---|---|---|
|
||||
| Hover | moves the pointer and the cursor | ignored |
|
||||
| Tip | holds the left button | a finger in the current touch mode |
|
||||
| Side button | as the Side button setting says | ignored; a Bluetooth pen key is an ordinary key |
|
||||
|
||||
- With the picture on the glasses, or while a program in gamescope holds a pointer lock, Mouse drives the touchpad
|
||||
as a finger does: a tap clicks and a drag moves the pointer relatively.
|
||||
- App UI on top (the drawer, achievements, input settings, picture in picture) takes the pen as Android input, as
|
||||
it takes a mouse.
|
||||
- The Touch column is for a pen on the phone's screen. In Touch an external tablet stays on the mouse path, so its
|
||||
hover moves the pointer. The stylus rules under Android capture apply in both modes.
|
||||
- A touch mode change ends the pen whatever its route, so it cannot leave a pen click held
|
||||
([#318](https://github.com/Droid-Deck/DroidDeck/issues/318)).
|
||||
|
||||
## Side button
|
||||
|
||||
`penButton`: Right click (default), Middle click or Off. It applies to the pen's first barrel button. A second
|
||||
barrel button, where a pen has one, sends the other click: middle when the setting is Right click, right otherwise.
|
||||
Off sends nothing. The row is hidden in Touch.
|
||||
|
||||
Some pens send their button as a key from a separate Bluetooth keyboard; the OPPO AI Pen sends `KEYCODE_F21`. Such a
|
||||
key is the side button when its device is external, keyboard-only and not alphabetic, and has a word starting with
|
||||
"pen" or "stylus" in its name. In Mouse the pen always takes it, so neither the program nor the key bindings see
|
||||
it, and it acts only while the pen is near: a key held when the pen comes back presses the button. Pause, focus
|
||||
loss, pointer-capture loss and removing its device forget it. In Touch it is an ordinary key.
|
||||
|
||||
## Android capture
|
||||
|
||||
- Pens are found by tool type (stylus or eraser), or by `SOURCE_STYLUS` when the tool type is unknown. External
|
||||
tablets report `SOURCE_MOUSE | SOURCE_STYLUS`, so the source alone is not enough. Events that mix a finger and a
|
||||
pen are split, and the finger keeps its route.
|
||||
- Contact is taken at the top of `SessionActivity.onTouchEvent`, after the Compose UI and the on-screen controls
|
||||
declined it, so the pen presses on-screen buttons like a finger. Hover is taken in `dispatchGenericMotionEvent`
|
||||
before the mouse branch. The lower-screen game takes both.
|
||||
- With Low latency mode on (the default) the window asks for unbuffered pointer dispatch, so pen samples are not
|
||||
batched per frame. Every historical sample is forwarded in order, and `pointerSubset` keeps the history when it
|
||||
splits an event.
|
||||
- `PenStream` keeps proximity, tip and buttons. A `HOVER_EXIT` followed within 50 ms by a hover or a `DOWN` does not
|
||||
leave proximity: Android splits a landing into an exit and a down with the same time, and a digitizer can flicker
|
||||
out and in at the top of its hover range. A hover that sends no sample for 2 s leaves proximity.
|
||||
- Stylus devices are not hardware mice, so a drawing tablet does not turn on pointer capture.
|
||||
- On the desktop a hardware mouse makes KWin grab the pointer. A pen that comes near releases the grab, so it
|
||||
moves KWin's pointer, and the mouse takes the grab back when it moves after the pen has left.
|
||||
- Where the session hides the mouse pointer it also hides Android's stylus hover icon.
|
||||
|
||||
## What ends the pen
|
||||
|
||||
Everything that cancels touches: touch mode, touch route and pen setting changes, app UI opening, configuration
|
||||
changes, surface resize, the game moving between screens, picture in picture, pause, focus loss, pointer-capture
|
||||
loss and the activity's end. So do a change of the pen's own route and the removal of its device. `UP` with
|
||||
`FLAG_CANCELED` and `ACTION_CANCEL` end it at once instead of lifting into hover. Ending the pen releases every
|
||||
button and leaves proximity; `wl_pointer` has no cancel, so on the pointer a cancelled tap still clicks.
|
||||
|
||||
## Compositor
|
||||
|
||||
Each sample is one input record, type 13: the flags (in proximity, tip, right, middle) and the position in input
|
||||
space as 24.8 fixed point. A record is the pen's whole state, so the next record makes good any lost one.
|
||||
|
||||
`deliver_pen` emulates the pointer, as the touch `pointer_fallback` does: hover is motion, the tip is `BTN_LEFT`,
|
||||
the side button `BTN_RIGHT` or `BTN_MIDDLE`, and a record without the in-proximity bit releases every button. A
|
||||
button pressed or released mid-stroke keeps the implicit grab on the window the stroke started in. The
|
||||
relative-motion origin is reset when the pen comes and goes, so its jump never reaches a program as relative
|
||||
motion. Under a program's pointer lock only the buttons pass, which also covers the time before the app sees the
|
||||
lock.
|
||||
|
||||
The app logs `pen route <old> -> <new> (mode=<mode>)` and the compositor `[pen] <client> gets the pen as the
|
||||
pointer`.
|
||||
|
||||
## Limits
|
||||
|
||||
- A hardware eraser end clicks like the tip.
|
||||
- The pen and a mouse share the pointer's buttons, so a release from one ends a press of the other, as with the
|
||||
touch fallback.
|
||||
- Some systems keep the pen's button for themselves, such as Samsung's Air actions. ColorOS opens its stylus
|
||||
palette for the OPPO AI Pen's key unless that action is turned off in the system's stylus settings.
|
||||
@@ -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).
|
||||
@@ -204,7 +204,7 @@ call can be answered in-process with the 0014 design.
|
||||
| syscalls | why proot traps them | can it bypass proot? |
|
||||
|---|---|---|
|
||||
| `openat`/`open`/`creat`, `newfstatat`/`stat`/`lstat`, `statx`, `faccessat`/`access`, `readlinkat` (exit), `mkdirat`, `unlinkat`, `renameat(2)`, `symlinkat`, `linkat`, `fchmodat`, `fchownat`, `utimensat`, `truncate`, `*xattr`, `inotify_add_watch`, `name_to_handle_at` | path translation (guest → host), plus exit fixups for `readlink` and `rename` | **Yes, through libc wrappers.** The prototype covers open, stat, statx, access, readlink, opendir and fopen; the write family is next. Raw `svc` and glibc's internal callers (ld.so, fts, realpath, nss) still go to proot. |
|
||||
| `chdir`/`fchdir`, `getcwd` (exit) | proot emulates the cwd; until 0014 the kernel's cwd never moved | With 0014 the kernel's cwd follows the guest's. `getcwd` stays in proot (cheap, rare). |
|
||||
| `chdir`/`fchdir`, `getcwd` (exit) | proot emulates the cwd; until 0014 the kernel's cwd never moved | With 0014 the kernel's cwd follows the guest's. With 0028 `fchdir` takes the path of the open directory from `/proc/<pid>/fd` instead of walking it again. `getcwd` stays in proot (cheap, rare). |
|
||||
| `execve`/`execveat` | runs the loader, maps `PT_INTERP` inside the rootfs, shebangs, tracks `/proc/self/exe` | **No.** This is the core of what proot is for. Costs 0.4–0.8 ms per exec; the session scripts already avoid exec-heavy loops (`nap`). |
|
||||
| `brk` (entry and exit) | heap emulation: programs are mapped by proot's loader, so the kernel's brk area is the loader's | No (`PR_SET_MM` needs `CAP_SYS_RESOURCE`). **Fewer calls:** `GLIBC_TUNABLES=glibc.malloc.top_pad=…` grows the heap in larger steps. |
|
||||
| `bind`, `connect`, `accept(4)`, `getsockname`, `getpeername` | `sun_path` of Unix sockets | Same-path binds (runtime dir, files dir) need no translation, but the filter can't see the address. Possible fast-path candidate. |
|
||||
@@ -325,7 +325,7 @@ or repeatedly hit a path the wrappers cannot resolve.
|
||||
|
||||
### Opt-in tracer profiling
|
||||
|
||||
With **Setup > Diagnostics > Debugging tools** enabled, queue profiling for one session:
|
||||
With **Setup > Developer > Debugging tools** enabled, queue profiling for one session:
|
||||
|
||||
```sh
|
||||
tools/droiddeckctl proot-profile enable --slow-us 1000
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# Soundtracks
|
||||
|
||||
Steam soundtracks get their own tab under Library, a built-in music player, and an Android media session.
|
||||
|
||||
## Where soundtracks live
|
||||
|
||||
Steam installs a soundtrack to `<library>/steamapps/music/<installdir>`, next to a normal `appmanifest_<appid>.acf`. This holds for the internal Steam library and for a second library folder.
|
||||
|
||||
`Library.steamGames()` skips any manifest whose install directory exists only under `steamapps/music`. `Library.soundtracks()` returns exactly those entries, marked with `SteamGame.soundtrack`. While the Music tab is enabled, games and soundtracks therefore never mix in the Library tab, the launch drawer, game file sync or component preparation.
|
||||
|
||||
Folders added by hand (Soundtracks tab, plus button) are stored in `added-soundtracks.json` and carry a negative app id, so they cannot collide with a Steam app id.
|
||||
|
||||
## Turning it off
|
||||
|
||||
Setup > Launcher > Soundtracks. When off, the tab disappears and installed Steam soundtracks show in Library again, as they did before.
|
||||
|
||||
## Tracks, discs and duplicates
|
||||
|
||||
`Soundtrack.load()` walks the folder (four levels deep) for mp3, flac, ogg, opus, wav, m4a and aac. Tags come from `MediaMetadataRetriever` and are cached per folder in `files/soundtrack-index`, keyed by path, size and modification time.
|
||||
|
||||
`Soundtrack.group()` is pure and unit tested:
|
||||
|
||||
1. The same track in several formats collapses to one. Identity is disc and track number when both tags exist, otherwise the cleaned title. Lossless wins over lossy.
|
||||
2. Disc comes from the disc tag, otherwise from the subfolder (natural order), labelled with the folder name when it is numeric (for example `3+4`). A folder with no subfolders is one disc and shows no disc headers. Tags missing on the kept copy are filled from its duplicates, since FLAC files often use tag names Android does not read.
|
||||
3. Tracks sort by the number at the start of the file name, then by track tag, then by name. This matches Valve's soundtrack documentation, which says the Steam music player takes play order from file names and not from metadata. Numbers shown on screen are positions inside the disc.
|
||||
4. Titles come from the tag, otherwise from the file name with the artist, album and track number removed.
|
||||
|
||||
## Cover art
|
||||
|
||||
Steam's own library cache image first, then `AlbumArtwork`, `cover`, `folder` and similar files in the soundtrack folder. When none exists, the picture embedded in the first track that has one is used, so the grid shows it without opening the album. The player page shows the embedded picture of the track that is playing and falls back to the album cover for tracks without one. The media notification and the system media panel follow the same rule: while a track plays, its embedded picture replaces the item artwork in place, which does not restart playback, unless a cover was chosen in the art changer. The SteamGridDB artwork changer applies to Steam soundtracks like any other Steam entry.
|
||||
|
||||
## Player page
|
||||
|
||||
The layout follows Steam's soundtrack page and uses the DroidDeck theme colors and shapes, so every theme works. Cover, title, artist and total length sit on the left with seek, shuffle, previous, play or pause, next, repeat and volume. The track list with disc headers sits on the right. Portrait stacks the two. The action buttons (game files, shortcut, edit art, uninstall) use the same wide pill style as Steam's See More button.
|
||||
|
||||
Controller: d-pad moves between buttons and rows, A confirms, B goes back, the sliders respond to left and right.
|
||||
|
||||
Shortcuts use `droiddeck://soundtrack/<appid>` and open the soundtrack page.
|
||||
|
||||
## Playback and Android media controls
|
||||
|
||||
`SoundtrackService` is a media3 `MediaSessionService` with an `ExoPlayer`. It runs as a foreground service of type `mediaPlayback`, so playback keeps going when DroidDeck is closed and the notification and lock screen controls show the cover, title and artist. `SoundtrackController` connects a `MediaController` to it and exposes Compose state.
|
||||
|
||||
Launching a game pauses the music unless Enable ingame is on (see Playing during games). Audio focus and headphone unplug are handled by ExoPlayer.
|
||||
|
||||
Added dependencies: `androidx.media3:media3-exoplayer` and `androidx.media3:media3-session` 1.3.1.
|
||||
|
||||
## Playback options
|
||||
|
||||
The player page has a Playback options button that opens a panel with:
|
||||
|
||||
- Speed and pitch, from 0.5x to 2x in 0.05 steps, applied through ExoPlayer's playback parameters.
|
||||
- Skip silence.
|
||||
- A sleep timer for 15, 30 or 60 minutes or the end of the current track. The timer runs in `SoundtrackService`, so it still fires when DroidDeck is closed.
|
||||
- An equalizer with the device presets, one slider per band, and bass boost where the device supports it. The effects are attached to the player's audio session in the service.
|
||||
|
||||
Settings are saved in `soundtrack_settings` and sent to the service whenever the controller connects. The last album, track and position are saved too, so the play button on an album resumes where it stopped. The position is saved on track changes, pauses and seeks.
|
||||
|
||||
## Playing during games
|
||||
|
||||
Setup › Launcher has an Enable ingame toggle, shown while soundtracks are on. When it is off, launching a game pauses the soundtrack. When it is on, the soundtrack keeps playing and the service stops requesting audio focus, so the game's own audio mixes with it. The setting is sent to the service with the `INGAME` session command and is read again when the service starts.
|
||||
|
||||
## Searching and sorting
|
||||
|
||||
Inside a soundtrack, a search field above the track list filters by title, artist and album, and a sort button orders the list by album order, title or length. Track numbers always count from 1 by position in the list shown.
|
||||
|
||||
Custom (added) soundtracks, collections and Favorites can be reordered: select tracks first (long-press one, or use the select button), then with Album order selected and no search text, long-press a selected track and drag it. The order of an added soundtrack is stored in `soundtrack-order.json` and applied by `Soundtrack.load` within each disc; a collection stores its order in `soundtrack-collections.json`. Steam soundtracks cannot be reordered. The Music tab search also looks up tracks: soundtracks and collections whose names match come first, followed by a Tracks section.
|
||||
|
||||
## Favorites and collections
|
||||
|
||||
- The heart under the transport controls adds or removes the current track from Favorites. The bookmark button next to it opens the Saved panel to add the track to a collection or create one.
|
||||
- The Music tab has a Collections chip. Favorites is the first entry under it. The bookmark in the Music header opens the same Saved panel to open or create a collection.
|
||||
- Long-press a track to select. The selection bar has Select all, Deselect all, Add to collection, Add to favorites and, on a collection page, Remove from collection.
|
||||
- A collection page has a Manage button to rename, add tracks, remove tracks or delete. Favorites cannot be renamed or deleted.
|
||||
- Collection pages have Manage, Playback options, Shortcut and Edit art. Edit art changes the cover only, from a track cover or an image of your own, and is stored in `soundtrack-art/<id>`. Added soundtracks have the same Edit art, with the images in their folder and the first track cover as the choices; Steam soundtracks keep the Steam art editor.
|
||||
- Collections are stored in `soundtrack-collections.json` in the app files directory as snapshots of path, title, artist, album, length and cover. Tracks whose files are gone are skipped when a collection is played.
|
||||
- Collection and Favorites playback does not overwrite the saved resume position of an album.
|
||||
|
||||
@@ -52,6 +52,12 @@ again. A failed title lookup undoes nothing. The launcher likewise drops artwork
|
||||
fetched for the app the files named before and fetches it again; pictures the user chose
|
||||
are kept.
|
||||
|
||||
A game that stays a shortcut but sits in a Steam install directory with a single matching
|
||||
manifest links its shortcut prefix to that app's existing `compatdata/<appid>`, so cloud
|
||||
saves the client downloaded are the ones the shortcut sees. A Steam library install only
|
||||
uses its own library's prefix. An existing shortcut prefix is never replaced, a link to a
|
||||
missing prefix is removed first, and nothing is copied.
|
||||
|
||||
The account's `.droiddeck-routes.json` maps shortcut IDs to real Steam app IDs so the
|
||||
Android launcher uses the same title and Proton prefix as Steam. Other accounts do not
|
||||
inherit those routes. Managed shortcuts are replaced; user-created shortcuts and
|
||||
|
||||
@@ -296,7 +296,10 @@ it, the cloud copies before an upload replaces them, under
|
||||
A game launched before Proton has made its prefix (a first launch) gets its download deferred: the
|
||||
request is answered at once (`result=deferred reason=no-prefix`) and the download runs as soon as
|
||||
the prefix's user folder appears, within a minute. Every path logs
|
||||
`cloud <store> <id> down|up result=ok|skipped|deferred|failed files= bytes= reason=`.
|
||||
`cloud <store> <id> down|up result=ok|skipped|deferred|failed files= bytes= reason=`. A failure adds
|
||||
`detail="..."`: the exception chain with the step (`list`, `get`, `put`), HTTP status, file and the
|
||||
start of the server's error body, with URLs cut to their host and tokens, secrets and codes redacted.
|
||||
GOG uploads stage their gzip body in the app's cache folder, which is created if it is missing.
|
||||
|
||||
- **The folder:** GOG's public remote-config gives a location template per game (by its Galaxy client
|
||||
id), e.g. `<?APPLICATION_DATA_LOCAL_LOW?>/Hyperstrange/ELDERBORN`; Epic's catalog gives
|
||||
@@ -328,7 +331,10 @@ the prefix's user folder appears, within a minute. Every path logs
|
||||
migration runs once per game (`cloud_layout_<id>`), so a game that legitimately keeps a folder
|
||||
named like the location is not relocated again; a non-prefixed listing is left unchanged.
|
||||
- **The services:** GOG `cloudstorage.gog.com/v1/<user>/<client>` with a token issued to the game's
|
||||
own client (the client secret is kept at install; the Galaxy token is the fallback); Epic's
|
||||
own client (the client secret is kept at install; the Galaxy token is the fallback). Every
|
||||
cloudstorage request sends Galaxy's communication-service `User-Agent` (`GOG_CLOUD_UA`, the
|
||||
same string Heroic's gogdl and Lutris send), and PUT repeats it as `X-Object-Meta-User-Agent`;
|
||||
the bare `GOG Galaxy` value is now refused with HTTP 400 `invalid_version`. Epic's
|
||||
savesync data storage with signed read and write links (`EpicCloud` → `EpicSaveSync` → the Rust
|
||||
`epic/savesync.rs`; the template's root token and `{EpicId}` / `{AppName}` are read by
|
||||
`EpicSaveTemplate`).
|
||||
|
||||
@@ -33,11 +33,12 @@ followed by a proto2 message, except on `uplay_service_ipc_pipe_`.
|
||||
| Pipe | Client | Exchange |
|
||||
|---|---|---|
|
||||
| `game_start_ipc_pipe_` | `UbisoftGameLauncher.exe` | `game_starter.Upstream{1:{1:{1: build, 2: product, 10: exe, 11: arguments, ...}}}` → `Downstream{2:{1:{1:0 (overlay off), 2:0, 3: <root>/ + "/" + <exe under root>, 4: <root>/, 8:3, 9:{1:{1,113,0,1,0} 1:{3,123,0,0,0}}}}}` |
|
||||
| `uplay_api_process_ipc_pipe_` | game | `Req.initProcessReq{1: product, 2: game pid, 5: env set}` → `Rsp.initProcessRsp(13){1:1, 3:0 (overlay off), 4:3, 6:0}`. Kept open. Answering it is what releases the starter (below) |
|
||||
| `uplay_ipc_pipe_` | game (`uplay_r1.dll`) | `Req.initReq(1)` → `Rsp.initRsp(1)`, answered every time it is asked. `Req.installerReq(13)` with `initInstallerReq` → `Rsp.installerRsp(10){1:{1:1, 2:"", 3: language}}` |
|
||||
| `uplay_api_process_ipc_pipe_` | game | `Req.initProcessReq{1: product, 2: game pid, 5: env set}` → `Rsp.initProcessRsp(13){1:1, 3:0 (overlay off), 4:3, 6:0}`. Kept open. Answering it is what releases the starter (below). Far Cry 3 Blood Dragon sends only `{2: pid, 5:1}`; a missing pid is taken from the pipe's client process |
|
||||
| `uplay_ipc_pipe_` | game (`uplay_r1.dll`, `uplay_r2.dll`) | `Req.initReq(1)` → `Rsp.initRsp(1)`, answered every time it is asked. `Req.installerReq(13)` with `initInstallerReq` → `Rsp.installerRsp(10){1:{1:1, 2:"", 3: language}}`. `Req.userReq(11).getCredentialsReq(1){1: id}` → `Rsp.userRsp(8).getCredentialsRsp(1){1: id, 2: username, 3: "" (password), 4: userId, 5: email}`. `Req.streamingReq(27)` → `Rsp.streamingRsp(20){1: id, 2:1, 4:{1:0}}` for the streaming type (not streamed), `{1: id, 2:4}` for any other streaming query |
|
||||
| `uplay_aux_ipc_pipe_` | `uplay_aux_r1(64).dll` (Denuvo) | `{1: rid, 2: init}` → `{1: rid, 2:{1:1, 2: pid, 3:3367, 3:3368, 3:3962}}`; `{1: rid, 3:{2:{2: challenge}}}` → `{1: rid, 3:{2:{2:1, 3:0, 4: game token, 5:""}}}` |
|
||||
| `uplay_service_ipc_pipe_` | Ubisoft helpers | Server sends `{3:{1:1, 3:{1: <hwscore path>}}}` once, then only reads, unframed |
|
||||
| `upc_api_process_ipc_pipe_standard`, `uplay_protocol_ipc_pipe_`, `uplay_overlay_ipc_pipe_`, `orbit_ipc_pipe_`, `uplay_crash_reporter_ipc_pipe_` | — | Held open, never answered |
|
||||
| `orbit_ipc_pipe_` | game (`ubiorbitapi_r2.dll`) | `mg.protocol.orbitdll` from the DLL's own `proto_orbitdll/OrbitDll.proto`. `Req{1: id, 12: init{1: product}}` → `Rsp{1: id, 12:{1: save folder, 2:1}}`; `getLoginDetails(2)` → `{1: username, 2:"", 3:""}`; `getOsi(3){1: sub}` → `{2:1}` (failed, no online-services pipe) |
|
||||
| `upc_api_process_ipc_pipe_standard`, `uplay_protocol_ipc_pipe_`, `uplay_overlay_ipc_pipe_`, `uplay_crash_reporter_ipc_pipe_` | — | Held open, never answered |
|
||||
|
||||
### The session (`InitRsp`)
|
||||
|
||||
@@ -52,14 +53,36 @@ followed by a proto2 message, except on `uplay_service_ipc_pipe_`.
|
||||
| 7 isInOfflineMode | 0 |
|
||||
| 8 upcTicket | the PC ticket from `GetUplayPCTicket`, never the Denuvo token |
|
||||
| 11, 12, 15, 16, 18, 19, 21, 23 | the values a real launch carries (`{1:0}`, 0, overlay `{1:0, 2:3}`, hardware score `{6211, 22395, 1.0f}`, empty, `{1:1, 2:1}`, `{2:1}`, empty) |
|
||||
| 14 gameInstall | `{1:1, 2: installed chunks, 3: language}` |
|
||||
| 17 storage | `{1: "C:/users/steamuser/Saved Games/Ubisoft/<userId>/<product>/"}`; the game appends file names directly, so the trailing slash matters |
|
||||
| 22 ubiServices | `{1: applicationId}` from the account's entitlements, left out when unknown |
|
||||
|
||||
### R2 titles
|
||||
|
||||
`uplay_r2.dll` speaks the same `mg.protocol.uplaydll` messages (its embedded `UplayDll.proto` is identical to
|
||||
`uplay_r1.dll`'s), but its `InitReq` names the subsystems the game uses: fields 4 to 11 (friend, overlay,
|
||||
product, storage, install, multiplayer, store, streaming). Its `ApiContext` creates one object per requested
|
||||
subsystem and copies the session into them. Friends, overlay, game session, store and crossboot are checked
|
||||
for a missing object first; install and storage are not. A `gameInstall` sent to a game that did not ask for
|
||||
install is copied into a null object: Prince of Persia: The Lost Crown (6145) asks for overlay, product and store
|
||||
only, and crashed reading `0x68` in `uplay_r264.dll+0xaca2` two seconds after the session arrived.
|
||||
|
||||
So when the request names subsystems, 14 is sent only with `subSystemInstall` (8), 17 only with
|
||||
`subSystemStorage` (7), and an empty `multiplayerInit` (20) is added, which `uplay_r2.dll` asks for even when
|
||||
empty. A request that names none gets the session above unchanged. The Lost Crown also opens a second context
|
||||
that asks for every subsystem, and it gets the full session.
|
||||
|
||||
The overlay is reported off in all three places. `uplay_r1.dll` still loads `overlay.dll` from the
|
||||
runtime folder right after the session arrives, whatever the session says; without that file it gives up
|
||||
with `UplayAPI [ERROR]: Startup failed: cannot load uplay library` (Assassin's Creed Chronicles: China
|
||||
then sits on a black screen and aborts with code 3 after about 160 s), so the runtime includes it.
|
||||
|
||||
### Orbit titles
|
||||
|
||||
Older titles such as Far Cry 3 Blood Dragon (205) load `ubiorbitapi_r2.dll` next to `uplay_r1.dll` and ask
|
||||
`orbit_ipc_pipe_` for `init` before anything else; unanswered, the game waits forever on a black screen. The DLL
|
||||
keeps savegames itself as `*.save` files in the folder `init` returns, the same save folder as field 17 above.
|
||||
|
||||
## Start sequence
|
||||
|
||||
1. `droiddeck-upc.exe` creates the pipes and an auto-reset event marked inheritable, then starts the
|
||||
@@ -84,7 +107,6 @@ titles without Denuvo never open the aux pipe.
|
||||
|
||||
## Not covered yet
|
||||
|
||||
- R2 (`UPC_*`) titles use `uplay_r2.dll`; their pipe traffic has not been captured, so whether the
|
||||
same server answers them is unverified.
|
||||
- Orbit (`ubiorbitapi_r2`) titles.
|
||||
- R2 titles other than The Lost Crown, and R2 requests beyond the session, credentials, product list and streaming type.
|
||||
- Orbit's online-services pipe (`getOsi` is declined) and Orbit titles other than Far Cry 3 Blood Dragon.
|
||||
- Achievements, friends, overlay, cloud saves.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Reported video memory budget
|
||||
|
||||
The Performance VRAM setting enables `VK_LAYER_DROIDDECK_vram_cap` for games and reports smaller device-local `VK_EXT_memory_budget` budgets. DXVK exposes these through DXGI's `QueryVideoMemoryInfo`, including to D3D12 games using DXVK's DXGI alongside vkd3d-proton. Games that consult this budget can choose smaller working sets. The driver still supplies real heap sizes, usage figures, memory types, and actual allocation results. DXVK also receives its existing `dxgi.maxDeviceMemory` setting, which separately reduces the adapter's advertised dedicated video memory. A lower driver budget remains lower; the layer never increases it.
|
||||
The Performance VRAM setting enables `VK_LAYER_DROIDDECK_vram_cap` for games and reports smaller device-local `VK_EXT_memory_budget` budgets. DXVK exposes these through DXGI's `QueryVideoMemoryInfo`, including to D3D12 games using DXVK's DXGI alongside vkd3d-proton. Games that consult this budget can choose smaller working sets. The driver still supplies real heap sizes, usage figures, memory types, and actual allocation results. DXVK also receives `dxgi.maxDeviceMemory` and `dxgi.maxSharedMemory`, which separately reduce the adapter's advertised dedicated and shared video memory (on a single-heap GPU DXVK reports the heap as both, so a game adding the two would otherwise still see the whole heap as shared), and, for caps below DXVK's 4096 MiB D3D9 default, `d3d9.maxAvailableMemory`, which caps the texture memory DXVK's D3D9 frontend reports, since D3D9 games do not read the DXGI setting. Higher caps leave the D3D9 setting alone so DXVK's lower per-game limits still apply. OpenGL games are not covered. A lower driver budget remains lower; the layer never increases it.
|
||||
|
||||
This does not make vkd3d-proton automatically enforce the selected budget. In the [upstream allocator inspected during this investigation](https://github.com/HansKristian-Work/vkd3d-proton/blob/865b12ba0cc20796b3709397ce5d6d3b8a205b04/libs/vkd3d/memory.c), `heapBudget` is used for diagnostic reporting, while the [DXVK adapter](https://github.com/doitsujin/dxvk/blob/cf0a0d90f8965147741ad17dcd0b263817572ab3/src/dxgi/dxgi_adapter.cpp) returns the Vulkan budget to applications. Seeing a smaller budget in a VKD3D log verifies reporting, not reduced allocation or eviction.
|
||||
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# Lab builds
|
||||
|
||||
A Lab build is DroidDeck app code and resources built on the device itself, by the on-device agent
|
||||
or by hand, and loaded over the installed APK at the next start. Nothing is reinstalled or
|
||||
re-signed, so a tester on a release build keeps their games, sign-ins and settings while trying a
|
||||
change.
|
||||
|
||||
While a Lab build is active, add-on packs reuse the newest complete copy already installed on the
|
||||
device, even when the checkout pins another version. This keeps helpers such as proot available
|
||||
after restarting. If no complete copy exists, the pack uses the checkout's pin.
|
||||
|
||||
## How it works
|
||||
|
||||
- `tools/agent/dd-lab-build` builds the checkout with Gradle on the device (`processReleaseResources`
|
||||
and `mergeDexRelease`), packs the linked resources and dex files into `overlay.apk`, writes
|
||||
`overlay.json`, and stages both in the app's `files/lab/next`. It then recompiles the app without
|
||||
an app image and restarts DroidDeck.
|
||||
- Run by the app's own agent (`DD_AGENT` set), it writes `files/agent/lab-request` instead, and the
|
||||
app runs the build in a process of its own, logging to `~/.cache/dd-lab-build.log`; the agent's
|
||||
copy follows that log and exits with the build. A turn's processes end with the turn, so a build
|
||||
started there would otherwise die when the agent stops or finishes early.
|
||||
- At start, `LabOverlay` (called from `App.attachBaseContext`) promotes `next` to `active`, checks
|
||||
that the build was made for this install, puts its dex files ahead of the APK's, and adds its
|
||||
resources through `ResourcesLoader` to the app and every activity. Contexts made from them
|
||||
(presentations on the second screen) inherit the loader.
|
||||
- The watermark shows `LAB | <branch> @ <commit>`. When the app comes back on a new build it posts
|
||||
a "Lab build installed" notification, so the restart does not look like a crash.
|
||||
- A build that is replaced, turned off or refused is kept in `files/lab/builds` (the newest 12).
|
||||
Updates lists them under Lab builds: the one in use can be turned off, one built for this
|
||||
install can be used again, and any can be deleted.
|
||||
|
||||
The build targets the package owning `DD_AGENT_INBOX` when run from the Agent tab.
|
||||
For a manual build of another package, set `DROIDDECK_PACKAGE`, for example
|
||||
`DROIDDECK_PACKAGE=com.tencent.ig dd-lab-build`. This also selects the control provider,
|
||||
Lab storage, and package to restart.
|
||||
|
||||
## What a Lab build cannot change
|
||||
|
||||
The manifest, native code (`cpp`, `jniLibs`, Rust), Gradle files, `App`, `AppLanguage`, and `LabOverlay` itself:
|
||||
they are loaded before a Lab build can be, or are not part of it. `dd-lab-build` refuses those
|
||||
changes; they need a new APK.
|
||||
|
||||
## Safety
|
||||
|
||||
- A build is only used on the install it was built for: `overlay.json` carries the APK's commit
|
||||
(`apkCommit` in `droiddeckctl state`) and the APK's path, which changes with every install and
|
||||
update. A build for another install is turned off.
|
||||
- Two starts in a row that do not reach a resumed activity for 10 seconds turn the build off.
|
||||
- It needs Android 11 or later (`ResourcesLoader`) and no app image (classes in one load before the
|
||||
Lab build). `dd-lab-build` runs `cmd package compile -m verify` before restarting. Android's
|
||||
background optimization can bring an app image back; the build is then paused, a notification
|
||||
says so, and Restart in Updates recompiles through the app's wireless debugging pairing.
|
||||
|
||||
## Setting up a device
|
||||
|
||||
From the DroidDeck terminal, in a checkout of this repository:
|
||||
|
||||
```sh
|
||||
tools/agent/setup
|
||||
```
|
||||
|
||||
It installs Claude Code, git, gh and loopback adb, plus the build toolchain: JDK 17, the Android
|
||||
SDK platform, and Google's x86-64 `aapt2` run under `qemu-user`. The first Lab build compiles the
|
||||
whole app and takes about 8 minutes on a Snapdragon 865; later ones compile only what changed.
|
||||
That needs the Kotlin daemon: Kotlin's in-process compiles always redo the whole app. BuildConfig
|
||||
is given the installed commit, so committing a change does not change it. Setup
|
||||
does that first build ahead of time with `dd-lab-build --prepare`, which compiles the installed
|
||||
commit without making a Lab build.
|
||||
`~/.cache/dd-lab-build.json` reports the stage, the current task, progress in thousandths and the
|
||||
seconds left, estimated from how long each task took the last time (`~/.cache/dd-lab-build-times`).
|
||||
`~/.cache/dd-lab-build-base` holds the installed commit the last successful build compiled, so the
|
||||
Agent tab can offer to prepare again after DroidDeck updates.
|
||||
@@ -22,11 +22,11 @@ This describes the integrations implemented in DroidDeck as of 2026-10-24. A rec
|
||||
| **VITURE Luma Ultra** | SDK-dependent Carina transport | Yes | **Experimental, opt-in** | **Experimental, opt-in** |
|
||||
| Recognized RayNeo / TCL Air-series devices | Integrated RayNeo USB transport | Yes, with orientation calibration controls | No | No |
|
||||
| RayNeo GT-series devices matching the supported USB identity, including GT Max identification | Integrated GT USB/IMU path | Yes, with orientation calibration controls | No | No |
|
||||
| **XREAL 1S** | **Experimental**; exact USB identity plus the device's USB-Ethernet control/IMU connection | Yes, when that connection is ready | No | No |
|
||||
| **XREAL 1S, One, One Pro, One Pro+, Aura** | **Experimental**; exact USB identity plus the device's USB-Ethernet control/IMU connection. Head tracking and 2D/3D switching are tested on the Aura | Yes, when that connection is ready | No | No |
|
||||
| Rokid Max / Max 2; Rokid Air under the Max USB identity | Integrated Rokid USB transport (vendor control requests and HID IMU reports) | Yes | No | No |
|
||||
| Other XREAL models; unrecognized glasses; display adapters and docks | Display-only where Android exposes a usable display; automatic glasses routing also requires display recognition | No supported app tracking connection | No | No |
|
||||
| Other XREAL models (Air family and others); unrecognized glasses; display adapters and docks | Display-only where Android exposes a usable display; automatic glasses routing also requires display recognition | No supported app tracking connection | No | No |
|
||||
|
||||
RayNeo's Air-series recognition uses its known USB identity or a RayNeo/TCL Air name under the accepted vendor IDs; it is not a per-model certification list. The GT vendor path requires the specific supported product ID. Rokid recognition requires USB 04d2:162f (Max/Air) or 04d2:2002 (Max 2), plus a Rokid product name, since that vendor ID is shared with unrelated devices. Max 2 reports the USB product name "Rokid Max2". Hardware checks cover the Max and Max 2; the Air follows the same published protocol untested. XREAL support currently targets **1S only**: One, One Pro, Air-family devices, and recovery-mode products are not enabled by the 1S transport. VITURE Pro 2 is identified through SDK validation rather than a guessed product ID. A dock does not supply the connected glasses' sensors by itself.
|
||||
RayNeo's Air-series recognition uses its known USB identity or a RayNeo/TCL Air name under the accepted vendor IDs; it is not a per-model certification list. The GT vendor path requires the specific supported product ID. Rokid recognition requires USB 04d2:162f (Max/Air) or 04d2:2002 (Max 2), plus a Rokid product name, since that vendor ID is shared with unrelated devices. Max 2 reports the USB product name "Rokid Max2". Hardware checks cover the Max and Max 2; the Air follows the same published protocol untested. XREAL support targets the 1S, One, One Pro, One Pro+ and Aura by exact USB product ID; Air-family devices and recovery-mode products are not enabled by this transport. VITURE Pro 2 is identified through SDK validation rather than a guessed product ID. A dock does not supply the connected glasses' sensors by itself.
|
||||
|
||||
The final column refers specifically to Luma Ultra's stereo tracking cameras. DroidDeck's separate phone-camera and physical-controller features are independent of this matrix.
|
||||
|
||||
@@ -43,6 +43,7 @@ All display modes depend on the phone's video output, the cable/adapter, and And
|
||||
| VITURE Pro 2 | 1080p per eye; 2D and SBS | Brightness and volume; no electrochromic-film control |
|
||||
| RayNeo Air/GT | 2D/SBS switching; resolution and refresh follow available Android modes | Orientation calibration; no app brightness, volume, or dimming commands |
|
||||
| XREAL 1S | Supported 1S display-mode commands, including native 1200p/60 Hz and SBS | Brightness and dimming toggle; no app volume command |
|
||||
| XREAL One, One Pro, One Pro+, Aura | 2D and SBS only, switched with the glasses' 3D input command; the display-mode set command is never sent (an unexpected index reboots the Aura) | No app brightness, dimming or volume commands |
|
||||
| Rokid Max / Max 2 | 1080p at 60 or 120 Hz in 2D; SBS at 1080p/60, 1200p/60, or 1200p/90 | Brightness; volume follows Android's USB audio volume; no dimming film |
|
||||
| Rokid Air | 1080p/60 in 2D and SBS | Brightness; volume follows Android's USB audio volume |
|
||||
|
||||
@@ -56,7 +57,7 @@ The pointer is left out of the picture when it cannot be drawn where the game is
|
||||
|
||||
## Setup and app-wide behavior
|
||||
|
||||
1. Connect the glasses through a compatible video/data connection. Accept USB access when requested. For XREAL 1S, Android must also expose the glasses' USB-Ethernet network; the app leaves Steam's Internet connection on its normal network.
|
||||
1. Connect the glasses through a compatible video/data connection. Accept USB access when requested. For XREAL 1S, One, One Pro, One Pro+ and Aura, Android must also expose the glasses' USB-Ethernet network; the app leaves Steam's Internet connection on its normal network.
|
||||
2. Open **Setup → Smart glasses**. Enable glasses output and **3DoF virtual screen**. This selects the tracked screen and saves the setting without forcing SBS or changing brightness.
|
||||
3. Adjust screen width and distance, then recenter while looking where the screen should sit. The same settings apply when navigating DroidDeck, opening a non-Steam launcher, or entering a game/desktop session.
|
||||
4. On an SDK-enabled Luma Ultra, optionally enable positional tracking and set the floor from the current eye height. Use the tracking setup and recovery controls for calibration or recentering. SteamVR startup defers Luma positional initialization until two seconds after SteamVR reports running.
|
||||
@@ -85,4 +86,4 @@ If only a flat picture is available, check video output first, then the control
|
||||
- [Agent diagnostics and capture commands](agent-control.md)
|
||||
- [RayNeo attribution and protocol references](third-party/rayneo/README.md)
|
||||
|
||||
The capability definitions are maintained in [VITURE models](../app/src/main/java/com/droiddeck/launcher/glasses/VitureProtocol.kt), [RayNeo models](../app/src/main/java/com/droiddeck/launcher/glasses/RayNeoModel.kt), [XREAL 1S](../app/src/main/java/com/droiddeck/launcher/glasses/XrealModel.kt), [Rokid](../app/src/main/java/com/droiddeck/launcher/glasses/RokidModel.kt), and [connection capability routing](../app/src/main/java/com/droiddeck/launcher/glasses/Glasses.kt). Update this matrix when those integrations change.
|
||||
The capability definitions are maintained in [VITURE models](../app/src/main/java/com/droiddeck/launcher/glasses/VitureProtocol.kt), [RayNeo models](../app/src/main/java/com/droiddeck/launcher/glasses/RayNeoModel.kt), [XREAL](../app/src/main/java/com/droiddeck/launcher/glasses/XrealModel.kt), [Rokid](../app/src/main/java/com/droiddeck/launcher/glasses/RokidModel.kt), and [connection capability routing](../app/src/main/java/com/droiddeck/launcher/glasses/Glasses.kt). Update this matrix when those integrations change.
|
||||
Reference in new issue
Block a user