Merge #561 into the non-Adreno test branch

docs/development/gpu-pending-completion.md

@@ -0,0 +1,88 @@
+# 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.