DroidDeck/docs/development/gpu-pending-completion.md

# Compositor work whose completion is unknown

A timed-out fence wait does not cancel submitted GPU work. Continuing after
that result can reset a command buffer or fence still in use, or destroy an
image and its memory while the GPU may still read them. Previously the finite
wait paths returned without putting the compositor into a terminal state, and
swapchain teardown ignored the result of `vkDeviceWaitIdle`.

An unsuccessful completion check other than real `VK_ERROR_DEVICE_LOST` now
puts the compositor in a distinct completion-unknown state. It stops subsequent
presentation and retains potentially pending image/memory and swapchain
resources until the DroidDeck app process exits. Device loss continues through
the existing device-loss path. This is deliberate retention rather than an
automatic recovery; restarting a guest session cannot reset the in-process GPU
state, so the diagnostic asks for an app restart.

Initialization checks the black-image submit and fence result. An unsuccessful
empty completion-marker submit no longer causes a wait on an unsignalled fence.
Surface-rebuild and effect-map paths stop when teardown cannot establish idle.
Acquire retries also stop: retaining the old swapchain is not permission to
acquire from it again. A later frame-generation acquire that ends in a terminal
state returns before the completion marker, fence wait or any further recording.
Real device loss on present is handled before attempting that marker, too.
Mapped SHM bytes are retained unchanged, including same-size `wl_shm` and
single-pixel commits; keeping only the allocation would still race a GPU read.
Off-screen pass copy/abort and the internal fence wait reject terminal states
without further Vulkan calls. Release fds are still consumed on rejected copies.
The normal frame fence still has its existing infinite timeout; this change is
not a general GPU hang watchdog.

Externally owned DMA-BUF contents need the same protection. `vkp_completion_unknown()`
exposes the terminal state to compositor-thread lifecycle paths. Replacement,
surface/client destruction, cursor/idle-role releases, previously queued paced
releases and SurfaceFlinger callbacks no longer return a DMA-BUF to its client
after quarantine. The compositor retains DMA-BUF references/backing FDs and AHB
references until app process exit. A display fence alone does not establish that
the compositor's Vulkan reads completed. Queued releases detach destroyed surfaces
and remain held without repeatedly arming an expired timer. New terminal releases
require no allocation, so allocation failure cannot fall back to an unsafe release.
Copied SHM releases and healthy/genuine-device-loss cleanup keep their existing
behaviour. This intentionally prevents further client buffer reuse; restarting
the Android app process, not just the guest session, is required.

## Regression coverage

`python3 -m unittest discover -s tools/tests -p test_vk_pending_completion.py -v`
compiles the production wait/destructor and swapchain teardown functions with a
fake Vulkan dispatch table. The two cases cover success, timeout, host-memory
errors, genuine device loss, resource retention and suppressed repeated teardown.
No real GPU fault is injected. The harness matches main's Vulkan-image resources;
it does not assume the experimental PowerVR branch's additional AHB fields.

`python3 -m unittest discover -s tools/tests -p test_vk_terminal_callers.py -v`
additionally compiles the **entire production `vk_present.c`**, with fake Vulkan
dispatch callbacks and stub external modules. The compositor's `take_shm` and
`take_pixel` callers are inserted verbatim, not rewritten. It needs the Android
NDK's Vulkan-Headers (`ANDROID_HOME`/`ANDROID_SDK_ROOT`/`NDK`), a host Vulkan
development package, or `DROIDDECK_VULKAN_INCLUDE`; absent headers are explicitly
reported as a skip. No Android runtime or GPU is required.

The 12 scenarios include first/later OUT_OF_DATE and SURFACE_LOST followed by an
idle failure, a finite blit timeout followed by same-size SHM/single-pixel
uploads, normal presentation/frame generation, a healthy later acquire timeout
whose earlier work still needs draining, real acquire/present device loss, and
terminal off-screen pass entry. Every work-issuing fake callback asserts the
device is live. After quarantine, the tests verify retained handles and unchanged
mapped bytes, and probe the public render/blit/readback/import/pass entry points
for suppressed acquire/submit/wait/reset and destruction. Consumed fds are checked.
Against PR #560's `68dc1c45` the same harness compiles, but nine scenarios fail
(the three healthy controls pass); the corrected production unit passes all 12.

The baseline production fence/destructor compiles but fails the timeout-state
oracle; the corrected functions pass both cases with `-Wall -Wextra -Werror`.
The change was also exercised in an independently integrated Pixel PowerVR Lab,
but its short game observations do not establish the cause of the earlier GNOC
reboot or sustained device stability. Main's native CI and APK build remain
separate validation.

`python3 -m unittest discover -s tools/tests -p test_vk_dmabuf_quarantine.py -v`
compiles the production compositor/AHB release, reference and listener functions
verbatim, using the real Wayland list layouts/macros with fake IPC/timer/AHB
endpoints. It covers paced replacement, immediate surface cleanup, already queued
releases, a mixed DMA-BUF/SHM queue, client destruction, a display-fence callback,
healthy cleanup and genuine device loss. It checks withheld releases, retained
FDs/references/AHB ownership, removal of surface listeners and disarmed timers.
The same harness can test an old source directory via
`DROIDDECK_DMABUF_TEST_SOURCE`; it does not inject a real driver fault or prove
long-term device stability.