mirror of
https://github.com/Droid-Deck/DroidDeck.git
synced 2026-11-21 05:46:03 +00:00
Merge main into PR #54
This commit is contained in:
commit
05284b0dd6
196 files changed
+15270
-1428
No files matched your search
@@ -0,0 +1,118 @@
|
||||
# Flatpak and the Store
|
||||
|
||||
Both features are beta and off by default. Setup → Launcher → "Linux apps (beta)" has one toggle for the
|
||||
Flathub Store, which shows the Store rail item and the Store's apps on the Desktop page, and one for
|
||||
AppImages, which shows the AppImages section. Turning either off hides it; installed apps stay installed
|
||||
and remain in the Linux desktop's menu.
|
||||
|
||||
The Store rail section installs apps from Flathub into the Linux runtime with Flatpak. Only
|
||||
ARM64 builds are listed. Everything lives in one per-user installation at
|
||||
`/root/.local/share/flatpak`, so nothing needs Flatpak's system helper or polkit.
|
||||
|
||||
## Putting Flatpak in the runtime
|
||||
|
||||
`bannerlator-flatpak-setup` runs under proot's fake root (`-0`), because pacman and pacman-key
|
||||
refuse any other uid. The runtime's pacman database lists only the base image. The desktop
|
||||
and emulator packages were unpacked over it without registering. A plain `pacman -S flatpak`
|
||||
would therefore reinstall about a hundred packages, Mesa among them, over the runtime's KGSL
|
||||
Turnip build, and run every hook in the image, mkinitcpio included. So pacman, with a
|
||||
database of its own under `/var/cache/droiddeck-flatpak`, only downloads the nine packages
|
||||
Flatpak adds to this image and checks their signatures against the Arch Linux ARM keyring.
|
||||
The script then unpacks them without hooks and checks what the binaries link. Libraries that
|
||||
the Desktop package normally brings (PyGObject, json-glib, fuse3 and others) are fetched too,
|
||||
but only when their files are missing. Flathub is added as a per-user remote from a copy of
|
||||
its `.flatpakrepo` carried in the script, so that step needs no network. Every store command
|
||||
writes its output to `Download/DroidDeck/flatpak-<verb>.log`, next to the session logs. The
|
||||
setup script also puts Flatpak's own error text in the failure message the app shows.
|
||||
|
||||
## bubblewrap without namespaces
|
||||
|
||||
Android gives apps no user namespaces, so `bwrap` cannot work. Flatpak is pointed at
|
||||
`bannerlator-bwrap` instead (`FLATPAK_BWRAP`, exported by `bannerlator-session` and by the
|
||||
store's commands). It reads bwrap's command line, including `--args` fds and the `--file` and
|
||||
`--bind-data` payloads, and then does one of two things:
|
||||
|
||||
- A sandbox that remaps nothing runs directly. Flatpak's install triggers (`--ro-bind / /`) and
|
||||
the D-Bus proxy (every top-level directory bound onto itself) are the cases, and they keep the
|
||||
file descriptors Flatpak handed them.
|
||||
- Anything else is described to the app over the abstract socket
|
||||
`com.droiddeck.launcher.bwrap`, which serves only the app's own uid. `BwrapSpawner` builds the
|
||||
tree under `cache/bwrap/<n>`: a root directory for top-level links, directories and files,
|
||||
scratch directories for `--tmpfs` inside a bind, and every `--bind` translated from guest
|
||||
to host paths through the session's own binds. It then starts it as a proot of its own
|
||||
beside the session's. Output, the pid (for `--info-fd`) and the exit status flow back, and
|
||||
the stand-in exiting kills the sandbox.
|
||||
|
||||
A proot nested in the session's proot would also work, but every system call then goes
|
||||
through two tracers, about thirty times slower at a program's start.
|
||||
|
||||
The spawner also adds what the rootfs gives its own programs:
|
||||
|
||||
- **GPU.** Flathub's Mesa has Turnip only for DRM, and Adreno on Android is KGSL. The runtime's
|
||||
own `libvulkan_freedreno.so` is bound in with the three libraries the Freedesktop runtime
|
||||
lacks (`libdisplay-info`, SPIRV-Tools). Vulkan uses it, and Mesa's GL runs on it through Zink
|
||||
(`MESA_LOADER_DRIVER_OVERRIDE=zink`). This is skipped for an app drawing into a desktop
|
||||
composited by pixman, where Zink cannot present.
|
||||
- **Controllers.** The libraries in the rootfs's `/etc/ld.so.preload` (the session shim and the
|
||||
fake evdev reader) go in through `LD_PRELOAD`, with the session's `dev` directory.
|
||||
- **Browsers.** Firefox's child sandboxes are switched off (`MOZ_DISABLE_*_SANDBOX`), and
|
||||
Chromium and Electron apps use zypak's mimic strategy (`ZYPAK_ZYGOTE_STRATEGY_SPAWN=0`). The
|
||||
Flatpak portal's Spawn refuses a caller whose `/proc/<pid>/root` holds no `.flatpak-info`,
|
||||
and a proot sandbox's root is the host's.
|
||||
- **CPU.** `/proc/cpuinfo` without the cores' part numbers. Snapdragon's ARMv9 cores imply SVE2
|
||||
to LLVM, Qualcomm leaves SVE off, and llvmpipe's first shader died with SIGILL.
|
||||
|
||||
## Running apps
|
||||
|
||||
The front end starts an app as a run-mode session of `bannerlator-flatpak-run <app-id>`, full
|
||||
screen under gamescope. Under gamescope it passes `--nosocket=wayland --socket=x11` and sets
|
||||
`XDG_SESSION_TYPE=x11`. Otherwise Flatpak finds the app compositor's `wayland-0` and the window
|
||||
opens behind gamescope. gamescope's own Wayland socket is no alternative: Chromium on Wayland
|
||||
asks the render node it names for a DRM version, which KGSL cannot give, and aborts. The
|
||||
launcher also starts a session bus when there is none. On the Linux desktop, the apps' exported
|
||||
menu entries appear in the LXQt menu. While the desktop is composited by pixman, games are
|
||||
wrapped through `droiddeck-gpu` like the rootfs's own.
|
||||
|
||||
## The store
|
||||
|
||||
`FlathubApi` reads flathub.org's public API: collections, search filtered to `aarch64`, and
|
||||
AppStream details. `bannerlator-flatpak` drives libflatpak through PyGObject and prints one
|
||||
JSON object per line (`op`, `progress`, `error`, `done`). `FlatpakManager` turns those lines
|
||||
into the store's progress bar. Store commands run in a proot of their own, and
|
||||
`OrphanReaper` spares them when a session starts.
|
||||
|
||||
## AppImages
|
||||
|
||||
"Add AppImage" on the Desktop page imports an ARM64, type 2 AppImage from storage. `AppImageManager`
|
||||
checks its ELF header first, so an x86_64 image is refused with a message saying so. It then copies the
|
||||
image in, because shared storage is noexec, and extracts it once to `/opt/appimages/user/<id>/app`.
|
||||
proot has no FUSE, and extracting at every start would cost the whole image each time. The name,
|
||||
comment and icon come from the image's own desktop entry. A menu entry goes to
|
||||
`/usr/local/share/applications`, where the desktop's GPU wrapper picks it up.
|
||||
|
||||
`bannerlator-appimage-run` starts it:
|
||||
|
||||
- `APPIMAGE` stays unset, so apps don't offer to add themselves to the menu or update in place.
|
||||
- Firefox forks get the same sandbox switches as Flatpaks.
|
||||
- Electron apps (a `chrome-sandbox` beside them) get `--no-sandbox` and X11.
|
||||
- A session bus is started when the session has none.
|
||||
- The launcher waits while anything from the image still runs, because Electron apps relaunch themselves.
|
||||
|
||||
Known to fail:
|
||||
|
||||
- Obsidian's own AppImage traps (SIGTRAP) after startup. Its Flatpak works.
|
||||
- Zen's AppImage hangs in Firefox's startup GPU probe. The Firefox Flatpak works.
|
||||
|
||||
## x86_64 apps
|
||||
|
||||
Flathub lists x86_64-only apps (Heroic, Discord, Spotify, Steam), and the store hides them. Running them
|
||||
would need an x86 emulator in the sandbox. There's no FEX or box64 package in Arch Linux ARM; Valve's
|
||||
ARM64 Steam can install its FEX compatibility tool, but only through the Steam client. With a FEX binary
|
||||
available, the path would be:
|
||||
|
||||
1. `flatpak install --arch=x86_64`. Flatpak accepts it, and the x86 runtime is also the x86 root FEX needs.
|
||||
2. `BwrapSpawner` starts those sandboxes with `proot -q`, through a small wrapper that runs FEXInterpreter.
|
||||
`-q` passes QEMU-style arguments.
|
||||
3. GPU drivers would need FEX's thunks, or Mesa runs emulated on the CPU.
|
||||
|
||||
x86 AppImages would also need an x86 rootfs for the libraries they don't bundle.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Steam game environment
|
||||
|
||||
Open **Games → Game environment**, directly below **FEX preset**, in Steam
|
||||
settings or the in-session drawer. Choose all Proton games, an installed game, or enter a Steam app ID. For a
|
||||
non-Steam shortcut, use its numeric `compatdata` directory ID (unsigned 32-bit).
|
||||
Changes apply on the next game launch, including when Steam is already running.
|
||||
A running game must be restarted. Native Linux games and Steam itself are outside
|
||||
this editor's scope.
|
||||
|
||||
The order is inherited process environment, selected FEX preset and built-in
|
||||
settings, shared edits, then game-specific edits. Editor entries therefore win
|
||||
over matching Steam launch-option variables. **Remove** explicitly unsets a
|
||||
variable. **Restore inherited settings** removes the override. **Reset this
|
||||
profile** clears only that profile's overrides. Values are literal strings, with
|
||||
no shell expansion; quotes are only needed when the consuming program expects them.
|
||||
|
||||
## Defaults and available suggestions
|
||||
|
||||
The initial configuration enables Mesa shader caching with
|
||||
`MESA_SHADER_CACHE_DISABLE=false`, sets `VKD3D_FEATURE_LEVEL=12_2` and
|
||||
`VKD3D_SHADER_MODEL=6_9`, and preserves the selected FEX preset. Existing edits
|
||||
and explicit removals take precedence over these defaults. FEX's own default
|
||||
remains the default preset. Shader caching in VKD3D/DXVK, synchronization, ray
|
||||
tracing and diagnostic logging otherwise retain the runtime's defaults.
|
||||
|
||||
The variable-name picker offers 24 predefined variables and a Custom entry. Like
|
||||
WinNative, known variables use toggles, value dropdowns, multi-select lists, or
|
||||
numeric/text fields. Feature-level and shader-model dropdowns also accept custom
|
||||
values. Custom variables have editable names and literal values.
|
||||
|
||||
| Variable | Use |
|
||||
| --- | --- |
|
||||
| `VKD3D_FEATURE_LEVEL` | D3D12 capability override; defaults to `12_2`. |
|
||||
| `VKD3D_SHADER_MODEL` | Shader-model override; defaults to `6_9`. |
|
||||
| `VKD3D_CONFIG` | Per-game workarounds such as `nodxr`; not a universal performance preset. |
|
||||
| `MESA_SHADER_CACHE_MAX_SIZE` | Storage budget for Mesa's shader cache, for example `1G`. |
|
||||
| `mesa_glthread` | OpenGL threading; test with the affected game. |
|
||||
| `DXVK_CONFIG` | DXVK configuration options; recent builds accept `dxvk.maxFrameRate = 60`. |
|
||||
| `VKD3D_FRAME_RATE` | D3D12 frame-rate limit. |
|
||||
| `DXVK_HUD`, `PROTON_LOG` | Optional diagnostics; leave unset for ordinary play. |
|
||||
| `PROTON_USE_WINED3D` | D3D9–11 OpenGL fallback for compatibility testing. |
|
||||
| `PROTON_USE_XALIA` | Proton's gamepad-navigation helper toggle. |
|
||||
|
||||
Forcing `12_2` or `6_9` changes reported capabilities; it cannot implement a missing
|
||||
Vulkan feature. Remove either entry to use automatic detection for that capability.
|
||||
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,
|
||||
ALSA-server, Box64 and patched async-DXVK options are identified in the editor as
|
||||
requiring a different/custom component; custom entries remain allowed. The old
|
||||
`DXVK_FRAME_RATE` environment variable was removed from current DXVK, so it is
|
||||
not offered as a suggestion. Prefer the session frame limiter for ordinary play.
|
||||
|
||||
## Launch path and references
|
||||
|
||||
WinNative's Linux session filters Android-only options, merges user variables
|
||||
over the FEX preset, and passes the result to `env -i` before starting Steam. Its
|
||||
Windows/Wine graphics helper also maps the selected feature level to
|
||||
`VKD3D_FEATURE_LEVEL`. Reviewed source: [WinNative Linux session](https://github.com/maxjivi05/WinNative/blob/c9fbbb342f2689c852046804f4f5c9afa45b5dcb/app/src/main/runtime/display/XServerDisplayActivity.java),
|
||||
[variable editor](https://github.com/maxjivi05/WinNative/blob/c9fbbb342f2689c852046804f4f5c9afa45b5dcb/app/src/main/shared/ui/widget/EnvVarsView.java),
|
||||
[graphics configuration](https://github.com/maxjivi05/WinNative/blob/c9fbbb342f2689c852046804f4f5c9afa45b5dcb/app/src/main/feature/settings/drivers/DXVKConfigUtils.java).
|
||||
|
||||
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 `bannerlator-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
|
||||
configuration falls back to the inherited environment without evaluating its
|
||||
contents. Signed non-Steam prefix IDs are normalized to unsigned IDs.
|
||||
|
||||
Upstream references: [VKD3D capability parsing](https://github.com/HansKristian-Work/vkd3d-proton/blob/master/libs/vkd3d/device.c),
|
||||
[VKD3D options](https://github.com/HansKristian-Work/vkd3d-proton#environment-variables),
|
||||
[Proton runtime options](https://github.com/ValveSoftware/Proton/tree/proton_11.0#runtime-config-options),
|
||||
[Mesa variables](https://docs.mesa3d.org/envvars.html),
|
||||
[DXVK variables](https://github.com/doitsujin/dxvk#environment-variables),
|
||||
[DXVK frame-limiter changes](https://github.com/doitsujin/dxvk/releases).
|
||||
|
||||
Validation: `./gradlew testDebugUnitTest` and
|
||||
`python3 -m unittest discover -s tools/tests -p test_game_environment.py`.
|
||||
Actual game compatibility depends on the installed Proton, VKD3D and Vulkan driver;
|
||||
these checks do not establish that every device supports feature level 12_2 or SM 6_9.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Steam game imports
|
||||
|
||||
Second Library still registers the selected Steam library. It now also scans Windows
|
||||
executables in its immediate game subfolders and `steamapps/common`, using the same
|
||||
importer as Added Games. Existing Steam manifests are preserved.
|
||||
|
||||
`bannerlator-steam-games watch` runs beside the client. It identifies a game by an
|
||||
existing manifest's install directory, a `steam_appid.txt` beside the game or selected
|
||||
executable, or a unique normalized title from Steam's store search with an explicit
|
||||
country. Matching also accepts the terminal Windows Edition and INTERGRADE suffixes;
|
||||
multiple matches still remain unresolved. Artwork's fuzzy matching is deliberately not
|
||||
used for identity. Ambiguous or unresolved titles remain non-Steam games.
|
||||
|
||||
Ownership comes from the running native ARM64 client's `BIsSubscribedApp`, through
|
||||
versioned SteamClient020 / SteamUser021 / STEAMAPPS_INTERFACE_VERSION008 interfaces. The
|
||||
helper gets the account from that connection, not from a public profile. No API key,
|
||||
password, profile visibility change, or CEF debugging port is needed. Each probe runs in
|
||||
a bounded subprocess so library failures cannot crash the importer or client.
|
||||
|
||||
The resulting snapshot is stored under that account's `userdata/<id>/config` and
|
||||
refreshed every 30 seconds while logged in. Title lookups retry every five minutes and
|
||||
when the source changes, so an early network failure does not end the watcher. Changed
|
||||
status and probe failures are written to the session log. Startup and post-exit import
|
||||
use the last successful snapshot for the selected account. The client reads manifests
|
||||
and shortcuts only at start, so when a snapshot confirms owned titles that are not yet
|
||||
imported, the watcher restarts the client once (not while a game runs or a download is in
|
||||
progress) and the importer runs between the exit and the next start. An unavailable client or offline first launch falls back to shortcuts; existing
|
||||
snapshots remain usable offline. Steam still enforces the current license at launch.
|
||||
|
||||
For a confirmed game without a manifest, the importer links the source folder into the
|
||||
internal Steam library and writes an installed manifest with `Universe=1` and
|
||||
`StateFlags=4`. Steam ignores manifests without the universe field. A manifest without
|
||||
installed depots makes Steam verify every file, so the importer carries the build another
|
||||
client recorded: WinNative's `.winnative-steam/steamapps` manifest beside the game folder,
|
||||
or a completed download's `.DepotDownloader/depot.config` depot manifest IDs. Steam then
|
||||
only downloads what changed since that build. Bare manifests from earlier imports are
|
||||
upgraded while Steam has not touched them. Without either record Steam still verifies.
|
||||
WinNative's manifest also identifies the folder without a store lookup. Steam updates and uninstall
|
||||
operate on the linked game files, so imported folders must be writable. Existing Steam
|
||||
manifests and directories are preserved. Only the exact minimal manifests generated by
|
||||
the earlier importer are migrated, with the matching source symlink still present. If
|
||||
registration fails, the game remains a shortcut. Once Steam takes over an install,
|
||||
manage it in Steam; forgetting an Added Games folder only removes its shortcuts.
|
||||
|
||||
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
|
||||
unreadable shortcut files are preserved. Both routes use the existing ARM64 Proton
|
||||
registration.
|
||||
|
||||
## Validation
|
||||
|
||||
Run `python3 -m unittest discover -s tools/tests -p 'test_*.py'` and Android unit tests.
|
||||
Tests cover identity and edition matching, network recovery, account isolation,
|
||||
owned/unowned/unknown routing, legacy manifest migration, manifest preservation,
|
||||
filesystem collisions, shortcut preservation, and the versioned IPC call/cleanup
|
||||
contract. On 2026-09-28, the ARM64 Steam client (1790545198) confirmed ownership and
|
||||
installed status through ISteamApps for Final Fantasy VII Rebirth (2909400), Final
|
||||
Fantasy VII Remake Intergrade (1462040), and Final Fantasy XV (637650), with all three
|
||||
install paths resolving to the original second-library folders. The old managed
|
||||
shortcuts were removed. This verifies library registration, not complete game launches.
|
||||
Unowned fallback and account isolation are covered by automated tests.
|
||||
|
||||
References: [Steam Apps
|
||||
API](https://partner.steamgames.com/doc/api/ISteamApps#BIsSubscribedApp), [Valve's
|
||||
versioned interfaces](https://github.com/ValveSoftware/Proton/tree/proton_11.0/lsteamcli
|
||||
ent/steamworks_sdk_154).
|
||||
@@ -7,6 +7,47 @@ the timeline, then lessons and backlog. Companion to the README (what the app *d
|
||||
|
||||
---
|
||||
|
||||
## 2026-09-29 - `feat/controller-input`: the pad the way SteamOS has it
|
||||
|
||||
Device-tested on the AYN Thor (Katamari under Proton Experimental ARM64).
|
||||
|
||||
- **Why**: the client read the pad as an Xbox 360 controller, and games read the *same* node
|
||||
wearing Steam Input's virtual identity (28de:11ff), because the client's own virtual pad needs
|
||||
`/dev/uinput` and never appeared. Steam Input's layouts therefore never reached a game, and the
|
||||
QAM was a timed Guide+A chord. InputPlumber itself cannot run in the sandbox (root, uinput, uhid,
|
||||
udev, D-Bus), so what it provides is emulated in the interposer instead.
|
||||
- **`/dev/uinput` stand-in** (`FAKE_EVDEV_UINPUT=1`, libfakeinput): a gamepad the client makes
|
||||
becomes `/dev/input/event16+`, backed by a ring of the app's own format, with the client's name,
|
||||
ids and bits; its writes are that ring's events. Other devices (virtual keyboard and mouse) are
|
||||
accepted and dropped. `inputudev.c` describes these nodes to Wine's HID bus from a `.uevent` file
|
||||
beside each one, and while one exists describes the app's pads as the Xbox 360 pad they are, so
|
||||
Wine reads only Steam Input's output. Verified: the client makes "Microsoft X-Box 360 pad 0",
|
||||
re-makes it at game launch, and the game binds it (`Controller 0 uses xinput : true`).
|
||||
- **Steam Deck controller** (`FAKE_EVDEV_DECK=1`, Steam sessions): `/dev/hidraw16`, found through a
|
||||
sysfs tree `SteamDeckPad.kt` binds in (usb_device → interface 2 → hid 28de:1205 → hidraw), streams
|
||||
the Deck's 64-byte state report every 4 ms from ring 0 and answers feature reports as InputPlumber
|
||||
does. systemd 261's libudev refuses a syspath not on sysfs, so `fstatfs`/`statfs` report sysfs
|
||||
for that tree. The app's evdev nodes are withdrawn while it is on, and only the `steam` process
|
||||
sees the Deck. QAM is a real button (snapshot bit 11). Verified: the client lists a Steam Deck
|
||||
Controller (V1 HID protocol) and runs its handshake (0x83, 0xAE, 0x81/0x87 lizard off, 0x8F).
|
||||
- **Setting**: Steam page → Touch & controls → **Controller**: *Steam Deck controller* (default) or
|
||||
*Xbox 360 controller* (the pad of earlier versions, QAM by Guide+A; games still get Steam Input's
|
||||
virtual pad). Debug switches: `droiddeck-no-uinput` (back to the 28de:11ff disguise),
|
||||
`droiddeck-no-deck-pad` (forces the Xbox 360 pad).
|
||||
- **Gyro**: `PadMotion.kt` feeds the handheld's own gyro and accelerometer (4 ms sampling, while
|
||||
the session is on screen) into an IMU block after ring 0's events, turned to the screen and then
|
||||
to the Deck's axes and units; the Deck report carries them. Verified: Steam's Gyro Calibration
|
||||
page moves with the Thor (sh5001 IMU); at rest the accelerometer reads 1 g.
|
||||
- **Deck grips + trackpads on the second screen** (`DeckControlsPanel.kt`, offered while the pad
|
||||
is a Deck controller): tabs for the four grips (2x2), either trackpad with a click bar, and both
|
||||
trackpads over the grips in a row; a second finger on a trackpad clicks it. True black for OLED.
|
||||
Grips, pad positions, touch, click and pressure go through the same block after ring 0's events
|
||||
as the gyro (`DeckControls.kt`) into the Deck report.
|
||||
- **Not yet**: a Bluetooth pad's own IMU (DualSense); the
|
||||
game's rumble on the virtual pad goes straight to the vibrator rather than back through the client.
|
||||
- **Prior art checked**: WinNative and Bannerlator never emulated uinput or hidraw; Bannerlator's
|
||||
`-steamdeck` mode stopped at "the virtual pad never arrives", which is this missing uinput.
|
||||
|
||||
## 2026-09-28 - Cemu's Turnip fix released for every driver; A8xx driver back; proven on the Galaxy Z Fold 8
|
||||
|
||||
State: **DroidDeck main unchanged** (`d98c211`); this is driver-side work in `The412Banner/Banners-Turnip`,
|
||||
|
||||
Reference in new issue
Block a user