From 472ed4096d4962eedfbf2710e92a860eda2f61ae Mon Sep 17 00:00:00 2001 From: K11MCH1 <81425424+K11MCH1@users.noreply.github.com> Date: Sat, 24 Oct 2026 02:02:23 +0900 Subject: [PATCH] Document Qualcomm driver integration and device validation (cherry picked from commit c32dfb6aee136074b63b1c5083996287b3182299) (cherry picked from commit 0d4cafb23ece56d8a5ac67e19c35452a6e7b3949) --- .../qualcomm-system-driver-research.md | 193 ++++++++++++++++++ tools/qualcomm/README.md | 69 +++++++ 2 files changed, 262 insertions(+) create mode 100644 docs/development/qualcomm-system-driver-research.md create mode 100644 tools/qualcomm/README.md diff --git a/docs/development/qualcomm-system-driver-research.md b/docs/development/qualcomm-system-driver-research.md new file mode 100644 index 000000000..a5eebbd6b --- /dev/null +++ b/docs/development/qualcomm-system-driver-research.md @@ -0,0 +1,193 @@ +# Qualcomm system Vulkan driver in DroidDeck + +Research date: 2026-10-23. Target: Adreno 840, Vulkan 1.4.295, as shown in the user's device screenshot. The existing `LOGS/my/2026-10-21-03-steam/device.txt` additionally describes a nubia NX809J, SM8850, Android 16/API 36, 4 KiB pages, KGSL, and `/vendor/lib64/hw/vulkan.adreno.so`. Those log details are a candidate baseline; the screenshot alone does not establish the phone model or Qualcomm driver build. + +Implementation update, 2026-10-24: imported AdrenoTools Qualcomm packages are now available as Linux runtime choices. The existing v891.7 import passed a GPU transfer/readback probe and rendered Steam/Windows Isaac on the RedMagic 11 Pro; Gamescope and game process maps identify the imported HAL. Its metadata says Vulkan 1.4.359, while the device probe exposes 1.3.351 and driver 0.891.7. See `tools/qualcomm/README.md` for selection, namespace mounts, evidence and limitations. + +## Decision + +Implement an experimental **System Qualcomm driver** Linux backend using a glibc libhybris ICD that loads the installed Android Vulkan driver. Present through gralloc/native handles and an Android hardware buffer Wayland receiver. Keep the existing Turnip backend selectable. Add imported Qualcomm packages through an explicit driver-selection extension to this bridge after the system-driver path passes validation. + +This has credible prior implementation evidence. It does not require recompiling Qualcomm's closed driver, changing the device kernel, or replacing the phone's system graphics stack. Subsequent testing on the connected RedMagic 11 Pro confirmed GPU execution and presentation; see the hardware implementation results below. + +My earlier assessment understated both the existing libhybris integration work and the availability of Qualcomm Linux drivers using KGSL. A Linux Qualcomm package must be inspected for its actual kernel interface; assuming all such packages require mainline DRM is incorrect. + +## Evidence and route comparison + +| Route | Evidence | Remaining DroidDeck work | Priority | +| --- | --- | --- | --- | +| Installed Android Qualcomm driver through libhybris | An Adreno 840 report shows Qualcomm driver 0.842.19, Vulkan 1.4.295, vkcube/vkmark and Zink queries in unrooted Debian PRoot; resizing and GL swapchain failures were also reported | Runtime packaging, Android system-library visibility, Wayland buffer receiver, Gamescope and Proton validation | First | +| Imported Android Qualcomm driver through libhybris selection hooks | AdrenoTools already packages and loads proprietary Qualcomm drivers; bridge support for selecting the same driver throughout is additional work | Adapt namespace/loader selection, dependencies and driver identity checks | Second | +| Native glibc Qualcomm driver plus Mesa WSI wrapper | An existing wrapper reports vkcube/vkmark on Adreno 740 with driver r00026; also reports exit hangs, artifacts and GPU faults | Find an 840-compatible binary, verify KGSL ABI and allocation path, implement suitable WSI | Parallel fallback experiment | +| Android renderer process using Venus/vtest or another command transport | A DroidDeck fork reports Vulkan enumeration and Gamescope initialization on PowerVR | Transport buffer import, synchronization and compatibility, plus Android renderer service | Fallback if in-process bridge cannot load this firmware | + +The Adreno report is third-party evidence, not a test on this user's firmware. Its 60 FPS vkmark result was FIFO limited and cannot establish performance relative to Turnip. See [the original device report](https://github.com/Droid-Deck/DroidDeck/issues/165#issuecomment-6086402696). The [native Qualcomm wrapper README](https://github.com/fish4terrisa-MSDSM/mesa-vulkan-wrapper/blob/9658357c332d25cd251d71a0bea440d9d7daf49b/README.md) documents its own limitations. The [Venus investigation](https://github.com/gogetwoo/DroidDeck/blob/pixel-venus/docs/pixel-venus.md) is a fallback reference, not an established Qualcomm solution. + +## Recommended architecture + +```text +Steam / Linux application / ARM64 Proton WineVulkan / FEX host Vulkan thunk + -> runtime's glibc Khronos Vulkan loader + -> libhybris Vulkan ICD + selected compatibility layers + -> Android system loader for instance initialization + -> selected Qualcomm Android Vulkan HAL for rendering + -> /dev/kgsl-3d0 + +Linux Wayland presentation + -> bridge-owned swapchain and gralloc/native buffers + -> android_wlegl native handles and file descriptors + -> DroidDeck Android hardware buffer receiver + -> compositor Vulkan import/copy initially + -> Android window / SurfaceFlinger +``` + +Vulkan rendering stays in the calling ARM64 Linux process. The buffer presentation exchange crosses processes; ordinary draw calls do not need an IPC round trip. TLS/ABI mediation still has overhead, and the existing PRoot overhead remains. There is no measured performance conclusion for this target. + +The current [libhybris ICD implementation](https://github.com/taowen/libhybris/blob/2375acd0b5d278a0a2f745c645680545e8f80539/hybris/vulkan/icd/icd.c) loads the HAL in the SP-HAL namespace when appropriate and loads Android's Vulkan loader for instance initialization. Its [instance code](https://github.com/taowen/libhybris/blob/2375acd0b5d278a0a2f745c645680545e8f80539/hybris/vulkan/icd/instance.c) verifies that platform and HAL physical-device query functions agree. This prevents mixing objects from independently selected drivers. Preserve that invariant when adding imported drivers. + +Use the normal glibc loader plus an ICD manifest. Avoid globally replacing `libvulkan.so.1` with libhybris's legacy replacement frontend: existing Linux layers, Steam runtime loaders, and FEX need the desktop loader contract. The [Khronos ICD interface](https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderDriverInterface.md) defines negotiation and dispatch responsibilities. + +## Existing DroidDeck fork to reuse + +The inspected `wallentx/DroidDeck` branch `wallentx/powervr`, revision `c931c4de26339c50f92354b9b06f6fdf7043ca8f`, already contains: + +- `tools/hybris/build_runtime.sh`: pinned cross-build, packaged bridge libraries, source/license bundle, manifests and hashes. +- `SystemVulkanDriver.java`: component preparation, ICD and per-process environment setup. +- `wl_android_buffer.c`: `android_wlegl` native-handle receiver using Android hardware buffer import. +- Gamescope/session integration and separate session/game compatibility policies. + +Its shipped vendor profiles are PowerVR, Xclipse and Mali. Adding Adreno requires its own capability policy; copying a Mali or PowerVR profile wholesale would enable irrelevant workarounds. The fork's pinned libhybris is `bc8cb3586b79d208fd21b925fa0209b3e432e008`, whereas the independently inspected `arlinux` branch is `2375acd0b5d278a0a2f745c645680545e8f80539`. Audit the differences and choose one reproducible baseline before importing patches; the fork applies patches to its older pin. + +Source references: [runtime builder](https://github.com/wallentx/DroidDeck/blob/c931c4de26339c50f92354b9b06f6fdf7043ca8f/tools/hybris/build_runtime.sh), [backend class](https://github.com/wallentx/DroidDeck/blob/c931c4de26339c50f92354b9b06f6fdf7043ca8f/app/src/main/java/com/droiddeck/launcher/gpu/SystemVulkanDriver.java), [buffer receiver](https://github.com/wallentx/DroidDeck/blob/c931c4de26339c50f92354b9b06f6fdf7043ca8f/app/src/main/cpp/waylandcomp/src/wl_android_buffer.c). + +## Device detection and user selection + +The UI should offer the following explicit choices, with probe status alongside the installed driver identity: + +| Choice | Meaning | +| --- | --- | +| Auto | Existing device-tested recommendation | +| Turnip | Existing Linux and Android driver selections | +| System Qualcomm driver — experimental | Device's currently installed Qualcomm driver through the Linux bridge | +| Imported Qualcomm driver — experimental | A selected AdrenoTools Qualcomm package through the extended bridge | + +Detect through the system Android Vulkan loader before loading a custom driver. Existing `deviceinfo/vkinfo.c` and `gpu/VulkanInfo.kt` already query device/vendor IDs, driver name/info, versions and selected features. Extend the structured result with `VkPhysicalDeviceDriverProperties.driverID`, device/driver UUIDs and raw driverVersion. Prefer `VK_DRIVER_ID_QUALCOMM_PROPRIETARY` where available; vendor ID `0x5143` and an Adreno name alone cannot distinguish Qualcomm's driver from Turnip. + +Display the GPU, driver name, driver build, Vulkan version and test result. Do not label Vulkan 1.4.295 as the Qualcomm package version. Record the loaded HAL/library identity separately from the GPU name. Android's loader chooses the actual system driver through HAL/APEX rules; a hard-coded `/vendor` filename is only a candidate for the bridge. See [Android's driver discovery contract](https://source.android.com/docs/core/graphics/implement-vulkan). + +Use a short-lived helper process for bridge probes so a native loader/compiler failure cannot kill the launcher. Distinguish **detected**, **bridge loads**, **renders**, **presents**, and **game tested**. Cache success against Android build fingerprint, driver identity, bridge build and selected package hash. An OTA or imported-driver change invalidates it. Probe under the DroidDeck app UID; `adb shell` success does not prove app access. + +Persist the backend and package identity for each session. Stop/restart the Linux session to change its driver; the compositor may require its own process restart. Per-game overrides must preserve the backend's complete environment and bridge assets. Snapshot selected component paths for running sessions so updating or deleting a package cannot invalidate their loaded dependencies. + +## What AdrenoTools contributes + +The upstream [AdrenoTools project](https://github.com/bylaws/libadrenotools) is already vendored in DroidDeck. It loads alternate ARM64 Android drivers without root; its [package format](https://github.com/bylaws/libadrenotools/blob/8fae8ce254dfc1344527e05301e43f37dea2df80/tools/ADPKG.md) explicitly includes proprietary Qualcomm libraries and renamed dependencies. Existing `TurnipDriver.java` accepts an ARM64 Android library named by `meta.json`, rather than enforcing Mesa as its vendor. + +Its [loader](https://github.com/bylaws/libadrenotools/blob/8fae8ce254dfc1344527e05301e43f37dea2df80/src/driver.cpp) creates Android namespaces and hooks the system Vulkan loader. That provides driver selection inside an Android process. It does not convert a Bionic binary into a glibc ICD or supply Linux Wayland swapchains. + +For imported Qualcomm support, port or adapt its selection mechanism inside the libhybris-controlled Android loading environment. Both Android instance creation and HAL resolution must select the same imported library and dependency set. Merely setting `HYBRIS_VULKAN_HAL` to the imported package while leaving platform instance creation on the system driver violates the bridge's identity check. Removing that check is not a solution. + +Keep this integration behind a separate milestone. Loading the existing Android AdrenoTools binary unchanged through libhybris is an experiment, not established compatibility: its linker hooks and namespace objects must belong to the same loader implementation used by the bridge. Alternatively, place AdrenoTools in a native Android renderer service, accepting a command-transport architecture. + +DroidDeck's bundled BC enabler is not called by the compositor loader, and its driver-version gating is specific. Do not assume importing a Qualcomm package automatically supplies desktop BC texture support. Query native format support, then enable only a validated native or decoding path. + +## Port map in this checkout + +| Area | Required change | +| --- | --- | +| `gpu/VulkanInfo.kt`, `deviceinfo/vkinfo.c` | Driver ID, UUID/build identity, complete capability probe and persistent result | +| `gpu/LinuxVulkanDriver.java`, `LinuxVulkanDriverManager.java` | Introduce a backend descriptor distinct from a Turnip ZIP; current import expects `libvulkan_freedreno*.so` and a glibc string | +| `DriverMenus.kt`, `ui/DriverPage.kt`, `session/SessionPrefs.kt` | System/imported Qualcomm choices, status and session restart behavior | +| `runtime/LinuxRuntime.java`, `session/SessionService.kt` | Bridge component paths; Android library/config mounts; select ICD and loader environment | +| `runtime/BwrapSpawner.kt` | Propagate selected bridge and Android dependencies into Flatpak/nested runtime plans; avoid the default Turnip injection | +| `tools/linuxfs/overlay/usr/local/bin/droiddeck-session` | Backend-specific Gamescope/presentation environment and diagnostics | +| `waylandcomp` | Add native-handle receiver, AHB Vulkan import and correct ownership/release behavior | +| Component build/verification pipeline | Build, pin, hash and package bridge sources/libraries/protocols | + +The Linux guest currently binds `/dev`, `/proc` and `/sys`; Android paths need an explicit audit. Expose readable host `/system`, `/vendor`, `/odm`, `/system_ext`, `/product`, `/apex`, `/linkerconfig` and property-service data as required by the selected firmware and bridge, including their resolved symlink destinations. PRoot path mappings do not grant extra Android permissions. Do not mix driver dependencies extracted from a different firmware with the installed system driver. + +Keep the glibc library search path separate from Android's library search path. The bridge builder uses private RPATHs for its own dependencies; set `HYBRIS_LD_LIBRARY_PATH` for Bionic loading rather than putting Android `libc.so` into glibc `LD_LIBRARY_PATH`. + +Audit preload behavior as part of the backend switch. `tools/linuxfs/preload/kgslid.c` currently rewrites reported chip ID `0x44050A21` to `0x44050A31`; a proprietary driver may need the original hardware ID. Disable that translation for the Qualcomm backend unless device evidence establishes a need. Check whether libhybris's ioctl hooks reach the glibc interposer before assuming the rewrite occurs. `LinuxRuntime.java` and `tools/linuxfs/preload/drm.c` also provide a DRM facade over KGSL. That facade is not a real DRM/MSM kernel driver and cannot satisfy arbitrary ioctls expected by a different UMD. + +Use the maintained bridge's TLS and namespace fixes. Stock upstream libhybris documentation assumes Android adaptation changes; this fork contains support for unpatched firmware, Bionic static TLS and linker configuration. Validate thread creation, compiler initialization and process exit with the selected API 36 firmware. Late-loading the bridge into a process with a large existing TLS footprint is a separate acceptance case from loading it at startup. + +## Buffer presentation and synchronization + +The current Android compositor requests dma-buf external-memory and DRM modifier extensions. An Android Qualcomm driver may support AHB import without supporting that raw dma-buf path. A successful `dlopen` therefore does not make the current compositor path compatible. + +Initially use the existing fork's `android_wlegl` receiver and AHB import. Preserve full native handles, all FDs, integer metadata, buffer dimensions/stride/format and lifetime. A raw dma-buf FD cannot reconstruct the missing gralloc metadata. DroidDeck's existing `banner_ahb_v1` protocol is another possible transport, but libhybris currently speaks `android_wlegl`; adapting one side is required. + +The bridge [swapchain implementation](https://github.com/taowen/libhybris/blob/2375acd0b5d278a0a2f745c645680545e8f80539/hybris/vulkan/icd/swapchain.c) uses Android acquire/release operations. Audit producer completion and compositor release separately. The current Wayland native-handle protocol lacks a per-commit fence channel, so its implementation can wait on release FDs on the host. Begin with correct FIFO behavior. Optimize to explicit fence transport and SurfaceControl only after reuse, resize, surface destruction and GPU effects paths pass. + +The screenshot's `VK_KHR_swapchain_mutable_format` is encouraging but does not prove bridge swapchains support the necessary flags and storage usage. In the inspected bridge, `hybris/vulkan/icd/swapchain.c` explicitly rejects any nonzero swapchain creation flags, including mutable format. Supporting that mode requires an actual bridge implementation, not adding an extension name. Query the bridge surface and gralloc-backed image capabilities. If Gamescope cannot write its composition output directly into those images, use an optimal composition image followed by a GPU copy into the presentation image. Validate color channels and sRGB conversion with pixel readbacks; a visible cube alone misses these failures. + +## Native Linux Qualcomm route + +Qualcomm publishes [Debian packaging for prebuilt Adreno libraries](https://github.com/qualcomm-linux/pkg-adreno). Its [8 Elite Gen 5 announcement](https://www.qualcomm.com/developer/blog/2025/10/same-day-snapdragon-8-elite-gen-5-upstream-linux-support) describes a Vulkan 1.4 UMD with a DRM/MSM stack. A separate [Qualcomm image recipe](https://github.com/qualcomm-linux/meta-qcom-distro/blob/main/recipes-products/images/qcom-multimedia-proprietary-image.bb) includes both qcom-adreno and KGSL. These are distinct integration contexts. + +For each candidate package, inspect ELF architecture, DT_NEEDED, GLIBC symbol requirements, exported Vulkan entry points, kernel device/ioctl use, GPU IDs, gralloc/GBM dependencies and redistribution terms. Extract into a private experiment prefix. Test compute/readback before adding WSI. A matching ARM64/glibc ABI does not establish matching KGSL or 840 support. + +The inspected Mesa native wrapper uses `WRAPPER_VULKAN_PATH`, defaults to `/opt/qti/usr/lib/libvulkan_adreno.so`, and adds desktop WSI. Its published 740 evidence makes this worth a controlled experiment. It is less suitable as the initial user-facing system-driver option because it substitutes a separate vendor binary rather than using the known installed Android driver. + +## Execution gates + +| Gate | Experiment and acceptance | +| --- | --- | +| 0. Native identity | Query installed driver in a fresh Android helper; save raw capabilities, build/UUID, feature chains and format support | +| 1. Bridge load | Same driver identity through glibc loader and libhybris; instance/device create/destroy and repeated process exits | +| 2. Rendering | Transfer and compute readbacks; sampled textures; BC formats; multithreaded shader compilation; compare actual pixel values | +| 3. Presentation | Wayland/AHB triangle with RGB and sRGB checks; resize, minimize, surface loss, buffer retirement and release-before-reuse | +| 4. Gamescope | Nested startup without a genuine DRM node; confirm buffer import, storage usage, modifiers and synchronization; copy fallback if required | +| 5. Steam | Zink context creation and Steam UI redraw/scroll/resize; check CEF/ANGLE separately; tolerate a UI-only software fallback if needed | +| 6. Games | Native ARM64 Vulkan, x86-64 through FEX, DXVK, VKD3D-Proton, then 32-bit WoW64 mapping and low-address behavior | +| 7. Product | Selection persistence, driver restart, failed probe recovery, OTA invalidation, nested runtime/Flatpak visibility and logs | +| 8. Performance | Matched resolution/settings, warm caches, repeated runs, frametime percentiles, thermal state, memory and presentation latency against Turnip | + +Check DXVK/VKD3D's actual required features for the shipped versions: BC formats, robustness, transform feedback, descriptor indexing, dynamic rendering, timeline synchronization and any shader requirements. A Vulkan version string is insufficient. Apply compatibility layers only where a tested driver needs them; do not expose unimplemented features by name. + +FEX's existing Vulkan thunk should reach the ARM64 host loader and bridge, but function coverage and process environment need tests. WoW64 additionally requires suitable low-address mapped memory. VR/effects and ray tracing are later acceptance cases; the screenshot's ray-tracing-maintenance extension alone does not establish complete ray tracing support. + +The libhybris repository includes baseline rendering probes and a [WSI runner](https://github.com/taowen/libhybris/blob/2375acd0b5d278a0a2f745c645680545e8f80539/tests/wsi/README.md). Reuse their pixel checks and validation support after adapting the external compositor contract to DroidDeck. Their default endpoint belongs to Arlinux and their X11 path expects TAWC-DRI, so they are not turnkey DroidDeck tests. + +## Reproducible research inputs + +Inspected local DroidDeck revision: `2e0db5a2cd21c92fd93380478a305a20cce0c203`. + +| Source | Inspected revision | +| --- | --- | +| taowen/libhybris, arlinux | `2375acd0b5d278a0a2f745c645680545e8f80539` | +| wallentx/DroidDeck, wallentx/powervr | `c931c4de26339c50f92354b9b06f6fdf7043ca8f` | +| bylaws/libadrenotools | `8fae8ce254dfc1344527e05301e43f37dea2df80` | +| fish4terrisa-MSDSM/mesa-vulkan-wrapper | `9658357c332d25cd251d71a0bea440d9d7daf49b` | +| taowen/arlinux-rootfs | `c092b069c407afa02b14706f650571cea4301f9e` | + +Source checkouts and issue snapshots are retained under ignored `build/research/qualcomm/`. The donor APK was inspected as an archive to extract its checksum-pinned Gamescope executable; the donor APK itself was not installed. The modified local DroidDeck development APK was installed into `com.droiddeck.launcher.xr` for hardware tests. + +## Hardware implementation results + +Connected device: RedMagic 11 Pro, NX809J, Android 16, Adreno 840, installed Qualcomm 0.842.44, Vulkan 1.4.295. The regular DroidDeck application package was not replaced. + +Verified on this phone: + +- Android driver detection and persistent **System Qualcomm driver** selection in the runtime driver list; selecting it also selects the system display driver. +- Linux `vulkaninfo` identifies the same Qualcomm driver through the glibc libhybris ICD. +- A GPU fill/copy/readback probe verifies 4096 bytes. +- The Android compositor imports an AHardwareBuffer and verifies all 4096 pixels by GPU readback. +- Wayland `vkcube` completes 120 frames. +- An X11 `vkcube` renders visibly through Gamescope, the shared-memory X11 WSI fallback, the libhybris Wayland swapchain and the Android compositor. +- `glxinfo -B` reports accelerated Zink OpenGL 4.6 on the Qualcomm GPU, including with Steam's bundled Vulkan loader. +- Steam Big Picture reaches the app's `READY` state and displays its library. Its browser uses software compositing; Gamescope continues to render on Qualcomm Vulkan. +- The installed Windows version of The Binding of Isaac: Rebirth/Repentance launches through ARM64 Proton, receives focus as app 250900 and renders its intro and a game room. Its process maps contain `/vendor/lib64/hw/vulkan.adreno.so` and the selected libhybris ICD. This is a rendering smoke test, not a full playthrough or performance comparison. + +Required integration fixes found by these tests: + +1. Bind traversable Android APEX paths even when directory listing is denied. Filtering mounts with `canRead()` excluded Bionic's libc. +2. Advertise dma-buf only when the display driver supports it; use `android_wlegl`/AHB for Qualcomm instead. +3. Use Gamescope's SDL Wayland backend and an offscreen composition/copy fallback for the Android swapchain's supported usage flags. +4. Replace dynamic indexing of YUV sampler arrays with constant-index switches. Qualcomm's compiler otherwise raises SIGTRAP with `constant expression is expected for indexing YUV samplers`. A small Vulkan layer substitutes only the six known Gamescope shader fingerprints, rebuilt from pinned source and the tracked patch; it leaves other shaders alone. +5. Use the vendor-neutral WSI layer's X11 shared-memory path inside Gamescope; the bridge's native X11 backend expects TAWC-DRI, which this Xwayland does not provide. +6. Reserve additional glibc static TLS for late loading in Steam. The diagnostic log identified `libhybris-common.so.1: cannot allocate memory in static TLS block`. +7. Scope `SDL_FRAMEBUFFER_ACCELERATION=0` and the Kopper override to Steam's webhelper through the helper's `taskset` invocation. SDL's accelerated window-surface setup otherwise stalls on the X11 SHM path. This adaptation follows the inspected fork's `droiddeck-steam-taskset` integration. + +Broader game coverage, FEX-specific cases, suspend/resume, HDR and performance require separate acceptance. A Gamescope shutdown SIGSEGV has also been observed after its primary child exits. The backend remains explicitly experimental. Source pins, build instructions and probe limitations are in `tools/qualcomm/README.md`; device logs and screenshots are retained under `build/research/qualcomm/`. Successful Steam/game evidence belongs to session `2026-10-23-10-steam`. diff --git a/tools/qualcomm/README.md b/tools/qualcomm/README.md new file mode 100644 index 000000000..fb0838567 --- /dev/null +++ b/tools/qualcomm/README.md @@ -0,0 +1,69 @@ +# Experimental Qualcomm backends + +The Linux backend uses the installed Qualcomm Vulkan HAL through a pinned libhybris ICD. The Android compositor imports gralloc buffers through `android_wlegl`. Choosing **System Qualcomm driver** in the runtime driver list also selects the system display driver. Restart the app after changing an already loaded display driver. + +## Imported AdrenoTools Qualcomm packages + +Import a Qualcomm Android driver with **Change display driver → Import an AdrenoTools zip…**. In **Mix and match → Change runtime driver**, select its **Qualcomm (AdrenoTools, experimental)** entry. Previously imported packages appear without reimporting. This selects the package for Linux applications and the system driver for Android presentation. The runtime change applies to the next session; restart DroidDeck if its display driver was already loaded. Changing only the display selection does not change the Linux runtime driver. + +Candidates must have `vendor: Qualcomm` metadata, an installed ARM64 library, and a `minApi` no newer than the phone. Mesa/Turnip packages are excluded. The runtime setting uses `qualcomm-adrenotools:`. Deleting the source package clears a matching runtime selection. A selected package that disappears or becomes incompatible outside that removal flow causes an explicit startup error rather than switching drivers silently. + +PRoot privately overlays the package HAL at `/vendor/lib64/hw/vulkan.adreno.so` and its ARM64 companion libraries under `/vendor/lib64`. Packaged `libc++.so` is also overlaid at `/system/lib64/libc++.so`: Android's SP-HAL namespace resolves that dependency from system first. These mounts are repeated in nested application sandboxes and use the running session's selection. Android's instance loader and the bridge must resolve the same HAL; passing only an imported path to `HYBRIS_VULKAN_HAL` is insufficient. Android core libraries and its Vulkan loader are not replaced. No device system file is modified. + +RedMagic 11 Pro hardware verification on 2026-10-24 used the existing `v891.7` import. Its HAL SHA-256 is `b2c6e92a05d4e6388250f5ec6f94408f2e693cb7fd26274382913ddcb6586108`. Vulkan reports **Qualcomm 0.891.7**, and the GPU fill/copy/readback probe passes. Steam Big Picture reached its library and the installed Windows Isaac rendered through ARM64 Proton. Both Gamescope and the game mapped `graphics_driver/v891.7/vulkan.ad891.so`, its compiler/dependencies and the bridge ICD. The system HAL SHA-256 remained `16acf005480a071af9452f13d8e9bb9930971488d889ea276f87d73616cfd6f5`. + +The import's metadata advertises Vulkan **1.4.359**, but this device's Linux Vulkan probe actually reports physical-device API **1.3.351**, including with implicit layers disabled. The package label is not proof of its exposed API on a particular GPU. Driver identity and API support are separate results. Broader compatibility is untested. Evidence is in `build/research/qualcomm/packaged-*`, session `2026-10-24-02-steam`. + +## Steam browser hardware-rendering investigation + +Games, Gamescope and Android presentation already use Vulkan hardware acceleration. The software overrides apply to Steam's CEF browser and its SDL window surface. RedMagic 11 Pro/v891.7 trials on 2026-10-24 removed the CEF software override, tried ANGLE Vulkan and OpenGL/Zink, explicitly passed Chromium backend switches, removed the requested in-process GPU switch, and retried without the SDL software-surface override. None produced a stable usable Steam UI. The browser restarted or exited and the session subsequently shut down; logs include command-buffer creation and X11 connection errors. These observations do not isolate the root cause, and `READY` alone does not confirm the Steam window is usable. + +The working software UI fallback was restored. No hardware CEF mode is shipped or claimed as working. Reproduction logs and trial scripts are retained in ignored `build/research/qualcomm/cef-gpu-*` and `cef-trial-*`; device sessions are `2026-10-24-04-steam` through `2026-10-24-08-steam`. Chromium/ANGLE backend switches are documented in [ANGLE debugging tips](https://github.com/google/angle/blob/main/doc/DebuggingTips.md). + +`runtime.json` pins the downloaded bridge and WSI archives, the locally built private Gamescope binary and corresponding source archive, and every private Mesa runtime file. `fetch_runtime.py` checks these pins before Gradle stages them. Missing local build outputs fail the build. Qualcomm's proprietary device libraries are loaded from the phone and are not included in these archives. The bridge archive includes its licenses, source snapshot and patches. + +The same lock pins a vendor-neutral X11 WSI layer and upstream Gamescope shader source. `build_shaders.py` applies `constant-yuv-samplers.patch` and builds six replacement SPIR-V modules with the configured NDK's `glslc`. It builds a small ARM64 glibc Vulkan layer using the NDK compiler without Android runtime linkage. The layer matches the six original Gamescope module fingerprints before substituting a shader; ordinary applications use the WSI/compatibility layers instead. Source archives, patches and licenses are packaged with the runtime. The patch can also be applied during a full Gamescope source build. + +Qualcomm 0.842.44 traps in its LLVM shader compiler when Gamescope dynamically indexes YUV sampler arrays. The constant-index switch preserves the eight-layer selection. The inner X11 WSI layer uses shared-memory copies; this is a compatibility path with additional CPU and memory-bandwidth cost. Steam additionally needs a larger `glibc.rtld.optional_static_tls` reserve because it loads the Bionic TLS bridge late. + +The private Gamescope is built from Valve revision `8f212644c46460549035971ab914421180f61a7c` with the regular DroidDeck patches, the additional SHM/cursor patches in `gamescope-patches`, the constant YUV sampler patch, and `gamescope-no-dmabuf.patch`. The additional integration patches were taken from `wallentx/DroidDeck` revision `c931c4de26339c50f92354b9b06f6fdf7043ca8f`. The corresponding source is packaged in the APK. Upstream integration references: + +- [DroidDeck fork at the producer revision](https://github.com/wallentx/DroidDeck/tree/af320dd86c7de5738ff16cfeeefbcf42581c199e/tools/gamescope) +- [libhybris runtime builder and patches](https://github.com/wallentx/DroidDeck/tree/4ed93fb9ee6e2a0b24ff087196f2e93d247fd985/tools/hybris) + +The Wayland receiver and external-image ownership handling were adapted from `wallentx/DroidDeck` revision `c931c4de26339c50f92354b9b06f6fdf7043ca8f`. The protocol retains its Collabora/libhybris license in `app/src/main/cpp/waylandcomp/protocols/wayland-android.xml`. + +## Older Qualcomm capabilities + +The connected vivo V2243A/SM8550 reports Adreno 740, proprietary Qualcomm 0.676.1, and physical Vulkan API 1.3.128. It lacks `VK_EXT_external_memory_dma_buf` and `VK_KHR_maintenance5`. The original private Gamescope refused to create a device. The new Gamescope permits missing DMA-BUF only for Vulkan swapchain backends, disables DMA-BUF format advertisement and imports/exports, and uses synchronous SHM uploads. Non-swapchain backends retain their requirement. GPU composition and Android hardware-buffer presentation remain Vulkan operations. + +Mesa 26.2.3 made maintenance5 mandatory for Zink. `zink-optional-maintenance5.patch` restores the earlier optional extension check, preserves point-size shader stores without that feature, and omits the maintenance5 buffer-view usage structure when unsupported. The private build uses the same Mesa release as the installed runtime, exposes a distinct GLVND vendor, and includes only Zink as its Gallium driver. `qualcomm-gl.sh` selects its libraries for applications and Mangoapp in Qualcomm sessions. It does not change the Vulkan device's reported features or enable software rendering. This does not establish full OpenGL conformance or game compatibility. + +Hardware verification on 2026-10-24 installed the full-runtime development APK and reached the visible Steam Big Picture library on this Adreno 740. Steam and Gamescope mapped `/vendor/lib64/hw/vulkan.adreno.so` through the bridge; Steam also mapped the private GLX vendor and `libgallium-26.2.3.so`. `egl_probe.c` reported **OpenGL 3.2 Compatibility Profile**, rendered a triangle through `zink Vulkan 1.3(Adreno (TM) 740 (QUALCOMM_PROPRIETARY))`, and verified all 256 readback pixels. Evidence is under ignored `build/research/qualcomm/adreno740`, device session `2026-10-24-05-steam`. Steam's CEF software fallback remains enabled. Games have not been verified on this phone, and the newly rebuilt components have not yet been retested on Adreno 840. + +Build the private components on ARM64 Linux with their normal development dependencies (GCC/C++, Meson, Ninja, pkg-config, Wayland/X11/SDL2 headers, Vulkan headers, glslang, and Mesa's Python Mako/packaging/PyYAML, Flex and Bison requirements): + +```sh +python3 tools/qualcomm/build_gamescope.py +python3 tools/qualcomm/build_zink.py +``` + +The recipes pin upstream source revisions and retain local outputs under `build/qualcomm-gamescope` and `build/qualcomm-zink/runtime`. Update `runtime.json` from the produced `build.json` hashes after deliberately rebuilding a component. The APK check verifies the pinned Gamescope, its source archive, WSI files, and private Mesa files alongside the full Linux runtime and all add-on packs. Native build outputs are prerequisites, just like the other prepared runtime components. + +## APK packaging + +Prepare the normal Linux runtime inputs and all five published add-on packs before compiling. Every APK must support a fresh installation; installed-device runtime reuse is prohibited by `AGENTS.md` and rejected by Gradle. + +```powershell +./gradlew.bat -PskipRust=true :app:assembleDebug +``` + +The build verifies prepared inputs before packaging, then verifies the APK and the add-on pack contents after assembly. Published packs are downloaded on first use using their pinned checksums, as in the normal DroidDeck build. The base Linux root filesystem is downloaded during setup. The package follows `droiddeck.debugApplicationIdSuffix` in `local.properties`. + +## Device probes + +`probe.py` runs inside the Linux runtime with the bridge ICD selected. It submits a GPU fill and copy, then checks 4 KiB of host-visible readback. It requires Python 3 and the runtime's normal glibc Vulkan loader. + +`ahb_probe.c` is an Android NDK program. Pass the newly built `libdroiddeckwayland.so` as its argument, with that library's dependencies on `LD_LIBRARY_PATH`. It allocates and writes an Android hardware buffer, imports it through the compositor's system Qualcomm Vulkan path, and verifies all 4096 converted BGRA pixels by GPU readback. + +The two standalone probes do not establish presentation or game compatibility. Additional RedMagic 11 Pro tests confirmed Wayland vkcube presentation, a visible X11 cube through Gamescope, accelerated Zink OpenGL 4.6, Steam Big Picture startup and rendering in the installed Windows version of The Binding of Isaac through ARM64 Proton. Qualcomm 0.842.44, Adreno 840 and Vulkan 1.4.295 were identified under the development app's UID; the game's process maps also contain the Qualcomm HAL and the selected bridge ICD. Steam's browser uses software compositing and its SDL window-surface workaround is scoped to the webhelper. Broader game compatibility and performance remain untested. A Gamescope shutdown SIGSEGV after child exit is still under investigation. Device evidence is retained in `build/research/qualcomm/`, including `isaac-driver-maps.txt`, `isaac-qualcomm.png` and `isaac-menu-qualcomm.png`.