Skip to content

refactor: the guest's present mode is the only mode, and every limit comes from one rule - #67

Merged
utkarshdalal merged 31 commits into
masterfrom
refactor/vsync
Nov 14, 2026
Merged

utkarshdalal merged 31 commits into
masterfrom
refactor/vsync

Conversation

@joshuatam

@joshuatam joshuatam commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

What this is

The shim now treats the guest's declared present mode as the only mode, applies every rate limit from a single rule, derives every wait from a measured rate instead of a literal, and keeps a buffer alive only as long as the display actually holds it. Tearing under direct scan-out is gone without costing swapchain depth, and frame generation is no longer starved by the mechanism that fixed it.

One rule decides every rate

limits.rs turns the guest's present mode, the cap, the multiplier and the panel's refresh into the frames per second the guest may acquire and the frames per second the generator may add:

present cap LSFG acquire generated total hold show in HUD
synced on off cap — cap note cap
synced off off refresh — refresh note refresh
synced on on cap cap × (m−1), at most refresh − cap cap + min(cap × (m−1), refresh − cap) note total
synced off on refresh / m acquire × (m−1) acquire × m note total
unsynced on off cap — cap note cap
unsynced off off none — none note measured
unsynced on on cap cap × (m−1) cap × m note total
unsynced off on refresh / m acquire × (m−1) acquire × m note total

hold is when an acquired image may be drawn into again. It follows the served mode — FIFO or MAILBOX, since every declaration on this route is served as one of the two — so it is note on every row: the image returns when the compositor reports its release and the display reports its scan-out release after that.

  • IMMEDIATE is served as MAILBOX — the one substitution left, in drm only, because an immediate guest would otherwise tear by construction.
  • A generation session is served the QuickMenu's mode (LsfgConfig::present_mode), and its image count is sized for the served mode, so a guest that asks FIFO while being served mailbox gets the mailbox depth.

The cap is a rate, and the schedule is a grid

One regulator replaces the previous three, and its release points are booked from the previous release point, not from the instant a frame happened to start. Lateness is therefore absorbed by the following frame instead of accumulating: a 30 cap that read 27.74 now reads 29.0 on the same title, with the residual visible as skipped frames — stalls reported rather than repaid.

The hold follows the present mode

The synced generated ceiling is the panel's leftover, not the panel: source frames
are part of the same budget, so generated <= refresh - acquire. At 60 Hz, cap 40,
×2 that leaves 20 generated against 40 source frames — half a frame each, which
floors to none, so generation does nothing at any cap above half the refresh. That
is the price of not over-subscribing the panel, and it is deliberate.

A synced slot waits for SurfaceFlinger's own release note before the guest may write into it, and an unsynced one does not. That removed the tear (sf hold measures 1.5–2.5 display periods) while an uncapped immediate session returns to free-running instead of being pinned at depth × refresh / hold.

Generation destinations share the same release path — the hole that made five destinations park for a session and produce six frames is closed in both allocators, and the bound is the only fallback, so a silent channel costs one bound per slot and leaks nothing.

The present wait reports handover, not scan-out

A frame handed to the compositor is not a frame that has been scanned out, and VK_KHR_present_wait is a report in native FIFO, not the throttle — the throttle is inside vkQueuePresentKHR. Answering the wait at the latch made the shim wait twice for the same frame: once in its own park and again in the guest's wait. The override route now answers at commit for every mode, which leaves the display's pacing with the compositor, where the spec puts it.

Diagnostics that do not lie

The census reports a rate (frames over elapsed clock time) instead of the reciprocal of the mean acquire duration; it states the image-count decision once per swapchain creation; it exposes the generation ring as dests=[in_flight/total parked=n] and destination releases at the default log level; and a generated frame reports itself at its own commit rather than riding the next acquired frame.

Verified

Device results are listed per device: the same build behaves differently on each, and one of the two found defects only exists on the second.

Retroid Pocket Nova (Adreno 740, 60 Hz panel)

  • Witcher 3, ×2, mailbox: frame generation went from 6 frames per session to 3 103+, short: free 4 790 → ~0, rate 27.7 → 29.0 of a 30 cap, no tearing.
  • Dave, vsync on: steady 60 fps with the acquisition path no longer paying a park and a present wait for the same frame.
  • Hades II, uncapped at 120 Hz: free-running instead of depth × refresh / hold.
  • Portal 2: declares IMMEDIATE and tore under direct scan-out. Serving that declaration as MAILBOX removed the tearing outright.

Odin 3 (Adreno 830, 60 Hz panel)

  • Witcher 3, generation off, FIFO, cap 60: two defects met here. A park bound derived from the frame interval it governs fed on itself (3 fps → 318 ms spacing → 636 ms bound → 3 fps), and the release note does not name the parked buffer — rnotes=2961 against park_timeouts=2954, notelag empty on every bucket, and slot ino=11411 beside released=[11366 11368 11370], same allocator, never the same buffer. Parks are now answered by order as well as by identity. slot_avg_us 26 728 → 1 461, acq_fps 23.5 → HUD 53.8, GPU 14 % → 89 % — the session became device-bound, which is where it should be.
  • Doom 2016, FIFO_RELAXED on the strict list (two images): holds exactly 30.0 whenever a released slot waits for the display's note. Three changes were needed and each is in this PR — FIFO_RELAXED served as MAILBOX (a late frame is superseded rather than deferred a whole vblank), the hidden-slot ring sized from the guest's ask rather than from the served count (a mailbox floor raised 2 to 4, which hid the ring), and hidden slots not parked (four parked copies dry the ring, the frame falls back to a guest slot, and two guest images over a 1.5-4.5-period hold lands on 2 / hold = 30). Result: 29.9 → 57.4 fps, GPU 79 %, dests=[1/4 parked=0], park_timeouts=0.
  • A fallback that took the swapchain lock twice deadlocked the acquire thread on this device: acq=5 frozen, guest parked on a timeline semaphore, park_timeouts=0. Both defects are named because neither was visible in the counters.

clippy -D warnings clean, 344 tests, build-android.sh clean, check-exports.sh PASS.

…goes

`MESA_VK_WSI_PRESENT_MODE` was read as the mode a swapchain keeps, ahead of the
guest's own request, as Mesa reads it. That made the container the authority on
pacing: every container carried `mailbox` as a stamped default, so a title whose
own VSync is a FIFO request was declared mailbox and ran uncapped, and one that
asked for immediate was promoted to mailbox as well. The container setting is
inert now and the shim reads no variable: `guest_present_mode(ci)` is the mode,
and what the guest asks for is what it gets.

Gone with it: `parse_present_mode_override` (and its one-shot
`Invalid … value!` log), `ModeSource`, `effective_present_mode`,
`Declared::GuestVsync` (it existed only for a FIFO guest under a non-FIFO env),
`GnSwapchain::requested_mode` (equal to `present_mode` once nothing overrides
it), and the override argument of `offered_present_modes` — the list the guest is
offered is `SERVED_PRESENT_MODES` in its own order, FIFO appended when a served
set lacks it.

`choose_live_mode` loses two parameters and one branch:

```rust
if generating                    { (MAILBOX, Generating) }
else if mode == FIFO || !capped  { (mode, Mode) }
else { None => (FIFO, CapCompat)                    // no latch grid yet
       Some(g) if at_display_rate(g) => if mode == FIFO_RELAXED
                                         { (mode, CapRateVsync) }
                                        else { (FIFO, CapRate) }
       Some(_) => (mode, Mode) }                    // the gate paces it
```

The cap still moves the *declaration* in the two cells where gamescope's limiter
would otherwise see a commit it cannot hold (it holds FIFO only), and it still
never moves the image count. An uncapped immediate guest is now declared
immediate, where the container's mailbox used to replace it.

The census line loses `requested=` (it would print the declared value twice) and
names the frame-generation case: `source=guest|cap-compat|cap-rate|cap-rate-vsync|
generating`.

Docs, in the same change, because every one of them justified the override:
`docs/10`'s cap section is rebuilt around the guest's mode — the table is now
"guest asked for × cap → declared → what limits the rate", its two
env-justifying paragraphs are replaced by the reason the two declaration moves
exist — and `docs/15`'s three-places table and "behaviour changes" bullet,
`docs/20`, `maint1.rs`, `present.rs` and the four `docs/performance` prose
mentions are corrected. Run transcripts that quote `source=env` are left as
recorded, with a line saying they predate this change.

Tests: the three env-driven cases are deleted (`present_mode_override_matches_mesa`,
`every_parsed_present_mode_is_served`, `the_container_mode_and_the_cap_decide_the_gamescope_route`
— its guest-only rows already live in
`the_declared_mode_follows_the_swapchain_the_cap_and_the_lead`), and the
offered-list test pins the served order and the FIFO append instead of an
override leading.

Verified: clippy `-D warnings` clean on the workspace and all targets, 337 tests
pass in 30 suites, `tools/build-android.sh` and `build-shim.sh android` green
through the export allowlists, and `strings` over the rebuilt
`libadrenotools_gamescope.so` finds no `MESA_VK_WSI_PRESENT_MODE`.

The app side, in GameNative's `gamescope-present-mode-from-the-guest`: on this
route `XServerScreen.setupXEnvironment` removes both `MESA_VK_WSI_PRESENT_MODE`
and `WRAPPER_MAX_IMAGE_COUNT` from the container environment, after
`extractGraphicsDriverFiles` has written them from the driver config. That is what
made the guest's request reach the shim while the shim still read the variable.
With this change the two halves are belt-and-braces rather than dependent: the
shim reads no mode variable at all, and `WRAPPER_MAX_IMAGE_COUNT` is still read
(`max_swapchain_images`), so the ceiling half is the one the app still owns. Both
orders work — app first (this shim sees no variable), shim first (this shim
ignores it).
…ng it

The flip event says the frame was published, not that SurfaceFlinger has
finished with it, so a producer handed its buffer at that event can be writing
into a buffer on the panel: a scan-out tear no screen recording shows, because
the buffer is repainted before anything reads it again. Holding the release one
flip longer (gamescope A56) removes the tear by removing a buffer from every
producer — a 3-image swapchain keeps one in flight instead of two, so nothing
can run ahead of the flip — which fixes one title and changes every other.

The number that decides between that and SurfaceFlinger's own fence is the hold:
latch to release. The daemon already has both ends — the completion callback
reports the latch, and the publish reusing a registration waits on the release
fence the previous completion stored — so the probe is the wait and a bucket.

`sf hold:` prints one line per 10 s: samples, buckets in halves of one display
period (the gap between consecutive latches, over 100 ms treated as a stall),
the maximum hold in microseconds, that period, and the waits that hit
RELEASE_FENCE_TIMEOUT_MS and so produced no sample. `one-1.5` and above is the
share a one-flip deferral does not cover: zero means the deferral is sufficient
on that device, non-zero means only the fence is exact.

Files: modules/gndrm-android/src/asc.rs (ReleaseCtx.latch_ns, the flip period
from consecutive latches, note_hold/note_hold_timeout/report_hold, and the
publish's release-fence wait); docs/12-present-latency-budget.md (the section on
what the hold decides, the line's fields, and the open item that it has no
device capture yet).

Verified: clippy -D warnings clean (workspace, all targets), 337 tests pass,
build-android.sh rc 0, check-exports PASS.
…om one rule

The declaration to gamescope is what the guest asked for. A cap no longer
rewrites it — not to FIFO at the display's rate, not for want of the daemon's
stamp lead — because what a cap decides is a rate. Which rate, and how many
frames generation may add to it, is one function over four inputs: the guest's
present mode, the cap, the multiplier and the panel's refresh.

  synced   (FIFO, FIFO-relaxed): cap or refresh acquires; generation adds
           cap × (m−1), at most the panel's rate
  unsynced (immediate, mailbox): cap or nothing; generation adds cap × (m−1),
           and the compositor drops what the panel cannot show
  no cap:                        refresh / multiplier acquires and the rest of
                                 the refresh is generated, so generation no
                                 longer needs a cap to run

A generated ceiling that is not a whole number of frames per source frame is
floored, because the engine takes an integer count per source frame.

Who holds the acquire rate follows the declaration, unchanged: gamescope's
limiter for FIFO, the shim's vblank-grid gate otherwise, and the gate's own
clock while it holds a source rate for the generator. The gate's present-wait
answer for a paced FIFO-relaxed guest is unchanged.

Gone with the old rule: Declared::{CapCompat, CapRate, CapRateVsync},
vsync_gate::at_display_rate, lsfg::{source_cap, output_rate, grid}, and the FIFO
fallback for a note without a stamp lead. The census gains acquire= and
generate=, because the declaration no longer says what the cap did.

Files: icd_shim/src/limits.rs (new: the rule and its tests),
icd_shim/src/proxy.rs (choose_live_mode without the rewrite, session limits
feeding the gate, the generator and the census), icd_shim/src/lsfg/mod.rs (the
three functions deleted, the ready line reports configuration only),
icd_shim/src/scanout.rs (target_fps is the daemon's cap again),
icd_shim/src/vsync_gate.rs (at_display_rate deleted), icd_shim/src/lib.rs (mod
limits), docs/10-fps-limit.md (the rule replaces the cap-rate cells),
docs/15-fps-limiter-pacing-and-vsync.md (six sites that named those cells),
docs/17-lsfg-frame-generation.md (the multiplier bullet, which asserted the
panel never capped generation).

Verified: clippy -D warnings clean (workspace, all targets), 341 tests pass,
build-android.sh rc 0, check-exports PASS.
A compositor hands a buffer back when it has finished *compositing* with it; the
display may still be scanning it out. Measured on the Retroid Pocket Nova at
60 Hz: a buffer the panel latched is released 1.5-2.5 periods later (25-41 ms,
83 % of 33313 releases), so a producer that reused it on the compositor's
release wrote into memory the panel was still reading. gamescope's
`wl_buffer.release` is that compositor release, and the shim freed the slot on
it — the scan-out tear that no screen recording can show.

SurfaceFlinger reports the true release a transaction later, as the
previous-release fence of the buffer that transaction *replaced*. The daemon
already received that fence, but filed it on the buffer doing the publishing,
where it was almost always already signalled: the wait gated nothing, and
`sf hold:` measured the pool's rotation rather than a hold. Filing it on the
replaced buffer's mailbox makes it both a real guard and the answer a producer
needs.

- `wire`: `BufferReleased` ("GNBR"), naming the scan-out inode, and
  `CAP_RELEASE_NOTE` as the opt-in — one push shape per fact, and a magic no
  other note on the channel decodes as.
- `asc`: `ReleaseCtx` carries its inode and the mailbox it replaced; the
  completion files the fence on that mailbox and hands the watcher a separate
  descriptor, which is waited out off the callback thread and pushed as a note.
  The hold is sampled where the fence ends, so `sf hold:` reports the hold and
  not how often the buffer came round. The single accept gap becomes the median
  of the last nine, so one burst cannot shrink the period the buckets are
  percentages of.
- `scanout`: notes are recorded as they arrive in a bounded list and taken by
  the slot they name, never by an older note for the same buffer;
  `release_notes_live()` leaves a daemon that sends none on the old behaviour.
- `proxy`: a slot the compositor released is parked rather than freed until the
  note for its inode arrives, and the acquire polls at 250 us while any slot is
  parked — only the note can free one, and the idle 4 ms slice is half a frame
  at 120 Hz. A parked slot is taken after 100 ms regardless, so a lost note
  costs a frame instead of the session.
- `docs/12`: the release rule, who is told about it, and what `sf hold:` now
  measures.

Measured with the release gate live: `timeouts=0` across 33313 releases, no
stalls, `p95 16.9 ms`, `slow=0/134`, `repeated=0` at cap 60 on a 60 Hz panel,
and no tear by eye at cap 120 on the same panel.

Not in this commit: the cap gate. A slot wait now outlasts the release
interval, and `book()` re-anchors the schedule to the late instant instead of
holding the debt (`skipped=7448` over 8598 acquires), so the slot pipeline
paces the guest at 67.4/s against a 60 cap.
A FIFO declaration is not a pacer. gamescope's limiter withholds a window's
frame callback, and this shim paces on its own schedule and the buffer release,
never on that callback; its divisor also only acts when the cap is below the
refresh AND divides it, so `60` on a 60 Hz panel and `40` on 60 Hz passed every
vblank. Standing down for FIFO therefore left the guest with no cap at all —
measured on Dishonored as a 26 fps session whose Target FPS did nothing, with
`gated=236 ungated=2006` over one session: the gate existed only until the first
commit declared FIFO.

Every `Declared::Mode` is gated now, on the display's grid, and gamescope's
divisor is left as the pacer for frames the shim does not present. `live` is no
longer a parameter of `gamescope_route_pacing`.

The same session also exposed the shape of the park bound. A slot is parked on
the compositor's release and freed by the daemon's note for its inode, and the
daemon names only a buffer it replaced on the layer — so a buffer its publish
path coalesced away is never named. At 100 ms that bound was not a safety net
but a pacing rule: four slots cap the session at 40/s. It is two display periods
now (33 ms), the scale of the hold the note reports.

The census gains what decides those two questions for the next run: `notes=`
(notes applied to a parked slot) against `park_timeouts=` (slots freed by the
bound, i.e. a note that never came), `age_s=` for the denominator a cumulative
counter needs, and `calls=`/`ok=`/`retry=` so an acquire call can never again be
mistaken for a frame.

- `proxy`: `gamescope_route_pacing` gated for every declaration; park bound 33 ms;
  the counters above; the 40/60 and 60/60 cells pinned by test.
- `vsync_gate`: the module note said gamescope's limiter holds a FIFO guest; it
  does not, and the gate runs on its own clock until the grid exists.
- `docs/10`, `docs/12`, `docs/15`: who holds the rate, corrected.

Verified: 345 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
On device: Dishonored back from 26 fps to its own rate with the 33 ms bound.

Not fixed here: Portal 2 over-runs the cap, 74.7 frames/s at 60. `book()`'s late
arm sets the next release one grid period after the *grid instant* the acquire
fell on, not one interval after the release, so two releases can land a fraction
of an interval apart; with 70 % of acquires slot-waiting, that arm takes almost
every frame and the gate holds 8 % of them.
The gate booked its next release from the grid instant the acquire fell on, not
from the release that actually happened. A late release therefore had a successor
a fraction of an interval behind it, and the cap over-ran: Portal 2 at cap 60
measured 74.7 commits/s, with `book late 1962 / on 3080`.

Three arms tried to bound that debt (`now + interval`, `previous release +
interval`, and a floor only when late). Each failed a pinned case — a 16 ms-work
guest fell to 30 fps, or a guest below the cap was quantized to a divisor — and
the third was a no-op: exactly where the late arm fired, "carry the debt but
never more than one interval" reduces to the release's own instant.

So the grid goes. `gate: while now < next_ns { wait }`, and `book: next_ns = now
+ period` from the release that was just granted. Two releases are then never
closer than one period by construction, a stall carries no debt, and a slower
guest is never held — the cap is a rate, not a phase.

The cost is that releases no longer land on vblanks: 1e9/60 = 16.667 ms against
the panel's 16.673 ms slips a vblank every ~2500 frames (~42 s at 60/60). If
that judder is visible the period tracks the panel instead
(`round(1e9/cap / panel_period) * panel_period`, computed once), which is a
one-line change to `period()`, not a return to the grid.

- `vsync_gate`: 715 -> 245 lines. `Grid`, `current_grid`, `ideal_ns`, the three
  booking arms, `book_clock`, `book_counts`, `next_acquire_after`, `Pacing::Grid`
  and `GateClock::Vsync` are gone; `pacing()` is a period or nothing.
- `proxy`: `gamescope_route_pacing(declared, acquire)` needs no grid,
  `scanout::apply_vsync` no longer pushes a note into the gate, and the census
  drops `book=`.
- `docs/10`, `docs/15`: who applies the cap, and the 74.7/s measurement that
  ended the grid.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.

Not fixed here: the guest's own frame on the gamescope route is one frame in
flight, so its rate is also the speed of the answer to its present wait. That
path is untouched by this change and is where the next measurement points.
On the gamescope route a FIFO guest runs one frame in flight: it presents, then
waits for that frame's presentation, so its frame rate is the speed of the answer
and nothing else. The census could not say who answered. Dishonored at 3.4 fps
showed `presented=670 fallback=0` — every wait answered by the compositor's
feedback, not once by the release, the two-period grace or the feedback safety —
which looks the same whether the compositor is slow or our own bound never armed.

The counts now separate those, and the first run separated them: of 3407 waits,
`nocommit=2975` began with no commit registered for their id, so `grace` had no
commit time to bound and could never fire; `noid=0` says the commit did see the
wait id, so the id was lost between the present arming it and the commit
registering it — the release handler clears it on the dispatch thread, and the
commit registers 100 lines later, after a blocking `send_present_mark`.

`notelag` separates the other half. Of 624 notes that resolved a park, 570
arrived more than 100 ms after it against a 33 ms bound, so the bound is the
normal path and a slot is recycled while the display still holds the buffer.

- `present`: `record_for` returns whether it answered, and every path that
  answers counts itself — at queue, at commit, feedback, daemon latch, grace,
  release, discarded, unarmed, timeout; plus `nocommit`.
- `scanout`: `release_notes_received()`, the denominator `notes=` never had, and
  the lag of the note that resolved a park, bucketed at 5 ms, 33 ms and 100 ms.
- `proxy`: `noid=` at the commit, and the census fields that carry all of it.

No behaviour changes; this is instrumentation only.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
On device: the numbers above, from a 14-minute Dishonored session at 3.6 fps.
Two ways a frame's wait reached `present::wait` with no commit registered, and
both left the guest with nothing but the compositor's feedback to answer it:

The release handler consumed `wait_id` unconditionally. A buffer's release can
arrive between the present that armed the id and the worker's commit — it may
belong to an earlier use of the same buffer — and `complete_on_release`
declines that answer while presentation feedback is pending, so the id was
dropped and told nobody. The commit then found an empty slot, registered
nothing, and sent the daemon no mark.

The registration also ran after `send_present_mark`, which is a blocking
`sendmsg` on the channel, so the bound was measured from whenever the mark left
rather than from the commit.

Measured on Dishonored at 3.4 fps: 2975 of 3407 waits began with no commit to
bound them, `grace` never fired once, and every wait ran to the compositor's
feedback at 255-264 ms.

A slot now records whether its wait has been registered. The release answers and
consumes only a registered id; a re-present, a mailbox replacement and an
at-commit answer clear the flag with the id. `commit_real` reads both ids once,
under the lock, and registers before the mark, so the commit instant the bound
is measured from is the commit instant.

On device, same title: `nocommit` 0 and `noid` 0 from the first frame, and wait
#600 answered `latched after 100051 us` — the bound, exactly. Of 625 waits at
that point 515 were answered by feedback and 110 by the bound.

The frame rate did not move: 277 ms is now 100 ms of bounded wait and ~177 ms
inside the guest, with the daemon publishing one frame per guest frame on the
grid, `late=0`. This removes an unbounded wait; it is not the cause of that
session. Also visible now: the compositor's presentation feedback stops after
~30 s into a session (515 answers, then none), which the bound absorbs.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
Dishonored on the gamescope route sat at 3.6 fps with the GPU idle, while the
same title on the X11 route ran at 60. Both routes reach the same daemon and the
same scan-out; the gamescope route is the one that sends a `PresentMark` for
every frame.

That mark went out through `send_frame`, which is a blocking `sendmsg` on the
channel shared with the allocator, taken under `CHAN` and on the present worker's
path. A daemon that had not yet read its backlog therefore held the commit, and
the frame time became the daemon's read rate: a flat 277 ms, invariant to
everything else on our side. Cutting the present wait from 256 ms to 100 ms moved
no part of it, and the compositor's feedback looked like it had stopped after
~30 s — it had not, we were not reading the socket.

The wait was also made to depend on that feedback. A frame whose feedback was
pending was bounded at 100 ms rather than two periods, so a compositor that went
quiet lengthened every frame to 10 fps. One bound now covers every frame, and the
gate is what paces the guest; a wait that outlives two periods is not measuring a
presentation.

- `scanout`: `send_present_mark` sends with `send_frame_nb` and drops a mark that
  does not fit. A lost mark costs a latch report in the census: its frame is
  answered by the compositor's feedback, or by the grace, both bounded.
- `present`: `FEEDBACK_SAFETY_NS` is gone; every committed frame is bounded by
  `commit_grace_ns()`, the same two periods, feedback or not.

On device, same title, same scene: 59.3 fps, `commit_lat` 16.2 ms (one period),
`gate_holds` 1634 with `gate_us` 2.1 s and a 1.16 ms average — the gate finally
holding the cap instead of idling. Every wait answered by real feedback
(`fb=3647`, `grace=0`), and `notelag` from 570 samples over 100 ms down to 14,
with `notes` resolving 2308 of 3643 parks against 68 before: the note path was
starved by the same congestion and needed no change of its own.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
The synced rows say what `limits.rs` encodes, and the runs do not reach them.
Three facts sit between the two, none of them visible from the table:

- The app disarms the cap when frame generation is armed, so a cap 60 session at
  x2 arrives as `cap=0` and takes the no-cap row (`refresh / m` acquires). The
  cap-with-generation rows are unreachable from the UI.
- The generator is the guest-side layer, not `flush_due`: its frames are presented
  on the same swapchain and are neither an acquire nor a `GEN_COMMITS` entry, so
  the gate holds one stream at `acquire_per_s` and the doubling does not happen —
  measured at cap 30: guest 29.0, needs 59.9 Hz, drawn 1.
- `note_produced` counts acquires plus the shim's own generator, so the app's ring
  sees source frames only and the HUD cannot read a doubled total.

Until a present can be identified as generated, `generate_per_s` is a limit
nothing on that path consumes.
`VkPresentModeKHR` is a contract about when an image comes back, and only the
synced modes promise a display-bound return: FIFO when a latched frame replaces
it, FIFO-relaxed the same but allowed to tear when late. IMMEDIATE returns the
image once it is handed over and MAILBOX as soon as a newer one replaces it.

`on_buffer_release` parked every buffer on the gamescope route whatever the mode
was declared, so an unsynced session got FIFO's lifetime: the slot came back a
scan-out release late, and the pool, not the panel or the cap, set the rate.

Measured on Hades II, uncapped, 120 Hz: `depth x refresh / hold` with depth 3 and
a 3.4-period hold is 106, and the session indeed sat between 100 and 120 with
`slot_waits` at 97 % of acquires and `in_flight` pinned at 3 — oscillating only
because the hold straddled the depth/refresh crossover at 25 ms.

The park is now taken only for a synced declaration; everything else frees the
slot at the compositor's release, which is the return the client was promised.
Same title, cap 120: `slot_waits` 1 595 and flat (was 130 408), `in_flight` 1
with two slots free, `acq_spacing` 98.5 % under 14 ms, and the gate holding the
cap again at ~2 800 holds per 10 s.

- `proxy`: `synced` gates the park; FIFO-relaxed included deliberately, since the
  spec lets it return early and holding it is the conservative side.
- `docs/10`: the table gains `hold`, `note` for the synced rows and `none` for
  the unsynced ones, with the rate as `min(cap, depth x refresh / hold)` and the
  crossover that makes the pool the limiter.

Not changed: the mode is still whatever the guest asked for. An immediate guest
keeps immediate semantics, so its frames are committed in order rather than
dropped for it.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
…QuickMenu

Two mode rules, both about `VkPresentModeKHR` being a contract rather than a
label.

`IMMEDIATE` is served as `MAILBOX`. Immediate presents mid-scan, so it tears, and
the only way a frame it cannot show gets dropped is for the layer to present it as
mailbox instead. The declaration follows the served mode, so gamescope is told
mailbox rather than being asked to pace a window that is not FIFO. This is the
layer's one mode substitution and it is deliberate: the container used to do the
same through `MESA_VK_WSI_PRESENT_MODE`, which the app side no longer sets.

The hold keys on the served mode too, mailbox included. A mode override that
touched only the present path would leave the reuse tear open: the buffer would
still be freed at the compositor's release while the display reads it, which is
the tear that was captured on camera on a FIFO session.

Generation has exactly two outcomes and the QuickMenu picks between them:
`MAILBOX` or `FIFO`, nothing else. `LsfgConfig` gains `present_mode` (0 mailbox,
1 fifo, anything else mailbox), the shim reads it through
`lsfg::generating_present_mode()` and serves it from `choose_live_mode`, and the
JNI setter takes it after `fpsLimit` so the app's QuickMenu value is the one that
reaches the wire. `IMMEDIATE` is never served under generation: a generated frame
cannot be told apart from a tear if it is flipped mid-scan.

- `wire`: `LsfgConfig::present_mode`, `LEN` 24 + 256 + 4 -> 24 + 256 + 8, the
  clamp `u32::from(present_mode == 1)`.
- `lsfg`: `Live::present_mode`, stored by `apply`, seeded from the daemon's
  settings, exposed as `generating_present_mode`.
- `proxy`: `choose_live_mode` serves mailbox for an immediate request and the
  QuickMenu's mode under generation; `on_buffer_release` keys the park on the
  served mode so mailbox holds like a synced mode.
- `gndrm-android`: the JNI export and `LSFG_SETTINGS` carry the field.
- `docs/10`, `docs/15`, `docs/17`: the substitution, its hold, and generation's
  two permitted modes.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
A parked slot is freed by the daemon's release note, and the note was arriving
after a bound measured in *panel* periods. A hold is not a panel period: a buffer
stays on the layer until the next frame replaces it, so at 40 fps on 60 Hz the
hold is two latch gaps (66 ms) against a bound of 33, and `park_timeouts` ran
12 203 against 3 623 slot waits. The reuse guarantee had quietly become "a timeout
expired", which is the tear this park exists to prevent.

The bound is now two producer intervals, floored by two panel periods:

    let spacing = COMMIT_SPACING_NS.load(…);          // EMA of commit intervals
    (spacing * 2).max(2 * (1e9 / panel_hz()))

`COMMIT_SPACING_NS` is measured where the census already samples the commit gap,
and smoothed with the same 1/8 rule as the commit-latency figure. No literal round
numbers: the interval comes from the commits, the floor from the panel's rate.

Measured on Dave, vsync on, 60 Hz panel: `park_timeouts` 12 203 -> 759 against
`notes` 5 860, and `notelag` shows why — the notes were always arriving 33-100 ms
after the park, so a 33 ms bound expired before almost all of them.

- `proxy`: `COMMIT_SPACING_NS`, the measurement in `commit_real`, and
  `release_note_limit_ns` derived from it. `RELEASE_NOTE_LIMIT_NS` is gone.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
In native Vulkan, FIFO's throttle is inside `vkQueuePresentKHR`: it returns when a
vblank slot and an image are available. `VK_KHR_present_wait` is an additional
report of when the frame was displayed, and a client uses it to pace its own
frame-latency loop. This shim had made that report the throttle: a FIFO frame's
wait blocked until gamescope's presentation feedback arrived, so every frame
carried a full latch inside it.

Measured on Dave at 40 fps, 60 Hz, cap 60: `present wait #9000 … done after
10624 us`, `waitans=[fb:9213 grace:0]`, `commit_lat 22.1 ms` against a 24.6 ms
frame. ~11 ms of every frame was blocked waiting to be told the previous frame had
been shown, and the guest ran one frame in flight where its ring allows three.

Every mode on the override route now answers at the commit, and the wait reports
the handover to the compositor. The two things that pace a guest are the acquire
gate and the image ring, which is the design: one regulator, and depth as the
pipelining bound. The X11 route keeps its answer at queue, where the X server
already sends PresentCompleteNotify while handling the request.

- `proxy`: `present_wait_answer` answers at the commit for every override-route
  mode; `answers_present_wait_at_commit` is gone with the branch that read it.
- The X11 and override answers are pinned across all four modes and both gated and
  ungated, replacing the test that asserted AtQueue only under the gate.

Not removed here: `present.rs`'s feedback and grace machinery
(`expect_feedback`, `feedback_pending`, `commit_grace_ns`, `note_commit`, the
`committed` list) is now unreachable from the override route but still referenced
by `wait()`'s grace branch and the X11 path, so it comes out in its own change.

Also in this commit, from the same session: the daemon's release watcher polls on
the panel's own period instead of a fixed 50 ms (`vsync::period_now_ns`), which is
delivery latency that was being added to every parked slot — `slot_waits` fell
from 62 % to 34 % of acquires and `notelag` moved inside 33 ms.

Verified: 338 tests, clippy `-D warnings`, `build-android.sh` clean, exports PASS.
Frame generation was frozen at 6 frames in a session while the rule asked
for 30 a second. The census said why:

    dests=[5/5 parked=5]  gendrel=6  generated 6  short: free 4790

Every generation destination was parked waiting for the daemon's release
note. Two defects kept them there for the life of the swapchain:

1. The only release check in the shim scanned `0..guest_slots`. The
   generation ring starts at `guest_slots`, so a parked destination was
   never unparked, never timed out and never counted.

2. `park_awaits_note()` counted parks since the last note and gave up
   after eight. It is called from `on_buffer_release`, so once the ring was
   fully parked no further release arrived and the counter could not reach
   its limit: `park=on` with all destinations held, in a session that had
   seen one note.

The release check is now `slot_just_freed`, used by both the guest's acquire
and the destination search, so a slot whose note is overdue returns to the
ring on the same bound either way. Taking a destination clears its park and
sets `in_flight` under the same lock, so a reclaimed slot cannot be
double-booked.

`SC_FRAMEGEN_IMAGES` goes back to 3. It sizes the swapchain, not the
generation ring, and the run that raised it to 4 generated exactly as many
frames as the one that left it at 3 — the ring was starved by the leak
above, not by a missing source slot.

The census gains `dests=[in_flight/total parked=n park=on|off]` and moves
`gendrel` out from behind `GNDRM_LOG_VKSHIM`: a destination that never comes
back has to be visible at the default log level, which is the level this
defect was measured at.

Measured on the Retroid Pocket Nova (Adreno 740, panel 60 Hz), Witcher 3,
mailbox, x2:

                    before          after
    generated       6               3103
    short: free     4790            2
    gendrel         6               3107
    acq_fps         34.4            49.7
    rnotes          1               5466

The remaining ceiling is a different defect and is not addressed here: the
daemon measures SurfaceFlinger holding a scanned buffer 1.5-2.5 periods
(`sf hold: 1.5-2.5=5379 period=16703us`), so three guest slots cap the rate
at `depth x refresh / hold`.

Verified: clippy -D warnings clean, 338 tests, build-android.sh clean,
check-exports.sh PASS.
A heuristic decided whether to park a released slot: count parks since the
last release note and stop parking after eight without one. It fired on a
healthy channel and, being sticky, turned the tear fix off for the rest of
the session:

    proxy release: no note in 9 parks (notes=5754) -- freeing on the compositor's release
    rnotes=9811
    park=off   descents visible as tearing

It was wrong in principle as well as in outcome: parks are counted per
release event and notes are drained per poll, so several releases can
legitimately arrive before one note is read. It measured the polling
cadence, not the channel's health.

Parking is unconditional again for a synced mode. It is safe now where it
was not when the fallback was written: a parked *destination* had no reclaim
path at all then (fceaa19), so a missing note leaked it permanently. With
`slot_just_freed` in both the acquire and the destination search, a silent
channel costs one bound per slot and nothing leaks.

The census drops `park=on|off`, which described the removed switch.

Verified: clippy -D warnings clean, 338 tests, build-android.sh clean,
check-exports.sh PASS. Measured on device with no tearing and generation
intact (`gendrel=9855`, `short: free 0`).
Witcher 3 asks for FIFO (`min=3 mode=2`) and is served mailbox, because it
is generating. The hold follows the served mode (`on_buffer_release`) but
the count did not: `swapchain_slots` saw the declaration, so the mailbox
floor of four — `SC_MAILBOX_IMAGES`, written for exactly this case — never
applied and the guest ran on three slots.

    proxy swapchain create: ... min=3 mode=2
    present mode: declared=mailbox source=generating
    slots=[3 guest + destinations]

Three guest slots under a 1.5-2.5-period SurfaceFlinger hold cap the rate at
`depth x refresh / hold` = 54, which is the 49.7 the session measured.

`count_present_mode` asks `choose_live_mode` what will be served and sizes
the count for that instead. Two cases change: a generation session (served
mailbox or fifo from the QuickMenu whatever the guest asked) and a declared
IMMEDIATE (served as mailbox). Strict-list games are untouched — they still
take the ask branch and get exactly their count.

Measured on the Retroid Pocket Nova, Witcher 3, x2, panel 60 Hz:

    before   slots=[3 guest]  generated 6592  hold 1.5-2.5 of 11573
    after    slots=[4 guest]  generated 5996  hold 1.5-2.5 of 11447

Verified: clippy -D warnings clean, 339 tests, build-android.sh clean,
check-exports.sh PASS.
`acq_fps` divided the frame count by the summed `vkAcquireNextImageKHR`
durations:

    1_000_000.0 * n / sum(acq_us)

That is the reciprocal of the mean service time, not a rate. It read 88.98
on a session whose limit was 30 acquires a second, and the readings it
produced in the sessions before it — 34.4, 41.7, 49.7, 64.3 — were all the
same mistake, including one I reported as the guest running above a 60 Hz
panel.

A rate needs frames over elapsed time, and the elapsed time has to come from
a clock rather than from the thing being measured: `ACQ_FIRST_NS` records the
first grant, `ACQ_LAST_NS` the latest, and the census divides `n - 1` by the
difference between them.

`books=` joins it. Every gated grant books the schedule one period ahead, so
a grant can never find its own deadline already past; a `books` count short
of the grants says some grants skip the book, and one equal to it says the
schedule is being re-anchored. The 60 % of acquires that passed the schedule
without sleeping in the measured session is the reading this is for.

Verified: clippy -D warnings clean, 340 tests (three consecutive runs),
build-android.sh clean, check-exports.sh PASS.
`Schedule::book` set the next release to `now + period`, where `now` is the
instant this frame actually started. Every frame whose sleep woke late
therefore pushed the next release back by that lateness, and the lateness
accumulated: a 30 cap settles at `30 / (1 + e)` for whatever jitter the
guest carries.

Measured on Witcher 3 (Adreno 740, panel 60 Hz, mailbox, x2):

    acquire=30  generate=30  acq_fps=27.74  gate_late=12  books=acq

7 % of the cap lost with the CPU and the GPU idle, and generation followed
the source down. It is the same defect A52 fixed in gamescope's limiter, in
the same shape: a release grid in time, where a late frame delays one
release and the grid absorbs it on the next.

`book` now steps from the previous *release point*, so an overshoot shorter
than a period gives the following frame a proportionally shorter hold and
the average rate stays the target. A frame late by a whole period or more is
a lost frame, not a debt: the schedule re-anchors at `now + period` and
counts the skip, so a stall never repays itself with back-to-back releases.

The old comment argued for the per-frame offset on the grounds that a grid
"let the cap leak on a late frame". That is true of a grid that never
re-anchors; with the re-anchor branch it cannot, and the test that pins it
(`an_overshoot_does_not_move_the_grid`) reproduced the 6 % loss before the
change.

Verified: clippy -D warnings clean, 341 tests (three consecutive runs),
build-android.sh clean, check-exports.sh PASS.
The count is decided once, when the swapchain is created, and cannot follow
the app's settings afterwards — a `LsfgConfig` frame can arrive after the
swapchain exists. A session whose settings came late therefore ran on three
images, could not reach its cap, and the only way to see it was to subtract
the generation ring from a slot total in the census:

    slots total 8 = 3 guest + 5 destinations   acq_fps=27.71
    (enabled=false at 09:16:38, generation armed at 09:26:55)

One line at the default level, per creation:

    proxy swapchain create: 4 images for asked=3 ceiling=8 declared=2 counted=1 live=true generating=true strict=false

`declared` against `counted` is what makes a wrong count legible, and `live`
against `generating` separates "the engine is armed" from "the app's saved
settings ask for it" — the pair that differs when settings arrive late.

Measured on the next session: the count line reads 4 images with
`declared=2 counted=1`, and the rate moves from `acq_fps=27.69` with 723
`slot_waits` to `acq_fps=28.96` with 169 — the fourth guest slot, with the
residual 3.5 % visible as `skipped=83` of 3379 frames, i.e. real lost
periods the schedule reports rather than repays.

Verified: clippy -D warnings clean, 341 tests, build-android.sh clean,
check-exports.sh PASS.
The daemon counts produced frames from the deltas of the two totals an
acquire message carries, and that message is sent once per *acquired* frame.
A generated frame therefore reached the app's frame ring only when the guest
next acquired — up to a multiplier's worth late, coalesced into a burst, and
then spread across the interval by `note_produced`. The ring read that as a
HUD that jumped several fps while the session's rate was flat: the shim
measured `acq_fps=29.00, 29.01, 29.00` across 7 000 frames.

`commit_generated` now reports each frame at its own commit, one message per
frame, with the acquire total loaded rather than incremented — so the daemon
sees `dAcquires=0, dGenerated=1` and `notify_frame_published` fires once per
generated frame instead of once per batch.

Reported at the two points where a frame actually lands (after
`x11_present_slot`, and after `wl_display_flush`), never on the early returns
where the buffer could not be made and the slot was released without
producing anything.

`flush_due` drops its batch total: a batch-level `GEN_COMMITS` addition
alongside the per-frame one would report every frame twice.

Verified: clippy -D warnings clean, 341 tests, build-android.sh clean,
check-exports.sh PASS.
Four statements in this doc no longer matched the code, and one of them
contradicted the table directly above it:

- The `hold` column reads `note` on all eight rows. That is correct and the
  prose said otherwise: the hold keys on the *served* mode
  (`on_buffer_release`), and every declaration on this route is served as FIFO
  or MAILBOX — FIFO for a guest that asked for it, MAILBOX for generation and
  for a declared `IMMEDIATE` (`choose_live_mode`). Both are synced, so every
  row's hold is `note`. The paragraph explaining why immediate would otherwise
  tear is kept, as the reason the substitution exists.

- The gate's pseudocode was `next_ns = now + period`, which is the line
  `be71f84` replaced. It now books from the release point and re-anchors only
  on a stall of a whole period, with both branches stated.

- `generate_per_s` was described as "a limit nothing consumes". It is consumed:
  `Limits::generate_per_source` caps the batch `lsfg_generate` plans, and the
  measured session generated 3103 frames against `acquire=30 generate=30`.

- `acq_fps` was defined as "the rate at the instant the cap acts", which is how
  the counter was read before it was corrected — it was the reciprocal of the
  mean acquire duration. It is grants over elapsed clock time now, and the
  census gained `books=`, `slots=`, `dests=` and `gendrel=`.

The `show in HUD` column is left as the intent (`total`) with the bullet below
saying what the widget actually reads: the ring holds both streams, and the
app's `frameSampleStride = m` divides it back down to the source rate.
…and the two waits are counted apart

Two defects from a Witcher 3 session on Odin 3 (Adreno, 60 Hz, FIFO, 3
images):

    acq_fps=3.00  acqus mean 318 ms  park_timeouts=208  rnotes=210
    notelag=[<5:0 <33:0 <100:0 >100:0]

**The bound fed itself.** `release_note_limit_ns` was `2 x COMMIT_SPACING_NS`,
and the spacing is the measured interval between commits. A session that had
already slowed therefore lengthened the hold that kept it slow: 3 fps -> 318 ms
spacing -> 636 ms bound -> three images per 0.64 s -> 3 fps. The bound is now
clamped between two and four panel periods, which still covers the 1.5-2.5
period hold SurfaceFlinger was measured to take, so a working note path never
reaches it. `panel_hz()` returning 0 falls back to 60 rather than the old
`.max(1)`, which would have made a two-second bound.

**The census filed slot time under the rate.** `blocked_at` was fixed when the
rate condition was first hit, and the image wait that followed was accumulated
into the same total: `gate_avg_us=333460` at a 16.7 ms period. The rate wait now
stops at the instant the condition is satisfied, and the remainder is counted
separately as `slot_holds= slot_us= slot_avg_us= slot_max_us=`. The same session
reads 15.2 ms of rate and 26.7 ms of slot, which is the 41.9 ms frame its HUD
showed.

**A park's note is anchored on its commit, not on the park.** The daemon's note
comes from SurfaceFlinger's previous-release fence, which signals when a later
buffer latches, so it can arrive before the compositor's release that parks the
slot. `GnSlot::commit_ns` records the instant the note is about and
`slot_just_freed` matches with `min(commit_ns, parked_ns)`. Written for both the
guest's slots and generation's destinations; a zero there would make the anchor
`min(0, parked) = 0` and accept any note ever sent for that inode.

A first note that matches nothing is now reported once per process with the
slot's own inode beside the notes in hand, which is how the identity question
gets answered on a device where no note applies:

    proxy park timeout: slot ino=11411 parked 66914 us ago; released=[11366 11368 11370]

Verified: clippy -D warnings clean, 342 tests (three consecutive runs),
build-android.sh clean, check-exports.sh PASS. Measured on Odin 3: the bound
clamp took the session from 3.00 to 23.50 fps; the remaining wait is the note
pairing, which is the next change.
…he oldest park

The park waits for the daemon's release note, matched by the buffer's inode.
On Odin 3 the note never names the parked buffer: SurfaceFlinger's
previous-release fence is signalled when a *later* buffer latches, so under a
three-image rotation it carries the identity of the buffer that replaced ours.
Measured on Witcher 3:

    rnotes=2961  park_timeouts=2954  notelag=[<5:0 <33:0 <100:0 >100:0]
    proxy park timeout: slot ino=11411 parked 66914 us ago; released=[11366 11368 11370]

Same allocator, never the same buffer, so every park ran to its bound and the
title sat at 23.5 fps with the GPU at 14 %.

`take_any_released` spends the oldest note whatever buffer it names, and
`answer_park_from_notes` applies it to the parked slot with the smallest
`commit_ns` — by age, not by index, since the acquire scan visits slots in
index order and would free the wrong frame.

The order path runs only after the identity match found nothing, so a device
whose inodes do line up (the Nova applied 3 737 notes) keeps the sharper
pairing and never reaches it. `by_order=` in the census says which path a
session is on.

A note may be up to one display period older than the asking commit: that is
how much later the note for a frame arrives, since it rides the latch of the
frame that replaced it. Bounded there rather than unbounded, so a stale note
still cannot free a slot.

Measured on Odin 3, Witcher 3, FIFO, cap 60, 3 images:

    before   acq_fps=23.50  slot_avg_us=26728  park_timeouts=700/702
    after    acq_fps=53.8 (HUD, in game)  slot_avg_us=1461  by_order=2921/2948

GPU utilisation rose from 14 % to 89 %: the session is now limited by the
device rather than by the shim.

The first version of the fallback deadlocked the acquire thread by taking
`shared` twice — std mutexes are not reentrant — which read as a frozen
`acq=5` with the guest parked on a timeline semaphore. `answer_park_from_notes`
takes a `locked` flag and `acquire_take_free` documents the requirement.

Verified: clippy -D warnings clean, 344 tests (three consecutive runs),
build-android.sh clean, check-exports.sh PASS.
… guest's ask

Two defects behind "the spares are working and Doom is still at 30".

**Hidden slots were parked.** The park arrived after the commit this title was
measured at 50-60 on: `8695197` has no `parked_ns` assignment at all, and
`db8c8a9` added it for every synced slot. A hidden slot is a copy this layer
owns, made so the guest's own images never have to wait, and parking defeats the
mechanism it exists for:

    spare_begin takes a hidden slot only if !in_flight
    4 hidden, each parked for 1.5-4.5 periods  -> the ring is dry within a frame
    the frame falls back to a guest slot, which parks too
    2 guest images / hold  ->  one frame per 2 periods  =  30 fps

Measured on Doom 2016, Odin 3: `dests=[4/4 parked=4]`, 29.9 fps, with the acquire
path looking healthy the whole time (`slot_avg_us=3535`, `by_order` answering
every park) because the wait is not in the acquire, it is in the ring having
nothing to give. Hidden slots now free on the compositor's release as they did
before the park existed; the guest's own images keep the park, so the tear fix
stays where it was measured.

**The ring was sized from the served count.** `hidden_slot_count(n_slots)` reads
the count after the mailbox floor, so a guest that asks for two and is served
mailbox reports four, "already has an image to spare", and gets no ring at all.
Sized from `ci.minImageCount` instead: Doom asks two, is served four, and gets
four hidden behind them.

The count rule of #56 is untouched in both: the guest is answered `n_slots` and
binds `n_slots`, and `spare_begin` only hands out slots at or above
`guest_slots`.

Verified: clippy -D warnings clean, 344 tests, build-android.sh clean,
check-exports.sh PASS.
RP6 ran Dave at 35.6 fps with every number in the acquire pointing at the wrong
thing: `slot_avg_us=5773`, `park_timeouts=14544` against 14679 acquires, and
`rnotes=132`. The release note is news from a producer that may not be there, and
on that device it is not: the daemon threads are alive (`gndrm`, `gn-release`)
and push the panel grid 5000 times a session, but `sf hold:` never prints once,
so `replaced_ctx` never holds a context and `watch_release` is never armed. Every
park was a hold with nobody to end it, and the acquire polled a 250 us slice until
the bound.

A park is now a bet, and the bet is only placed while the notes are paying out:
`PARK_DEAD_AFTER` parks expired without a note in a row frees the slot on its
fence instead, which is what the commit before the park did. A `BufferReleased`
re-arms it, so a producer that comes back needs no probation timer.

Liveness is keyed on `BufferReleased` and not on the socket. The first cut reset it
from `poll_notes` on any message and never armed: RP6 sent ~5000 `VsyncNote`s and
released seventeen buffers, so the census read `channel=[unanswered:2
dead:false]` with `park_timeouts=5181` of 5210 acquires. Measuring the socket is
not measuring the channel — the same mistake as the drought heuristic `0a801fd`
removed.

`park_timeouts` is also a count of parks now, not of loop turns. The bound was
re-evaluated on every pass of the acquire loop over a slot it had already freed,
so 14544 "timeouts" sat beside a total slot wait of 14.5 s: under a millisecond
each. `GnSlot.park_expired` answers each park once.

Measured, Dave on RP6, same payload, 102 s:

    fps             35.59  ->  59.4   (HUD 60.3, GPU 85 %, LIMIT: CPU)
    park_timeouts   14544  ->  28
    slot_avg_us      5773  ->  161
    slot_us         14.5 s ->  0.26 s
    acquire          9.64  ->  3.01 ms/frame
      gate           1.15  ->  2.89 ms   (the cap, now the only wait)
      slot           0.93  ->  0.04 ms
      unaccounted    7.5   ->  0.08 ms

The 7.5 ms that no counter named was this polling, which is why `lock` was added
and reads `n:0 us:0` on both builds: the swapchain lock is not in the path.

Nova and Odin 3 are unchanged by construction: their notes answer every park
within the window, so `unanswered` never reaches four.
The release note was the only one of the three scan-out messages without a token:
PresentMark carried the guest's id, PresentDone echoed it, and BufferReleased
carried an inode. Everything the park did to pair a note with a frame existed to
compensate — inode matching, an order fallback with a 5 ms reorder window, a
one-period floor, `since = commit_ns.min(parked)` and a bound derived from the
interval it governed. One missing field, six mechanisms.

The inode is not a key. It is a property of the dma-buf the allocator handed out,
and it pairs only while the same object reaches SurfaceFlinger: Nova needed the
fallback for 6 % of Portal 2's parks and 84 % of Dave's, on the same device, same
OS, same driver. So the shim now mints a ticket per commit — process-wide,
monotonic, never reused — and the note names it. `take_released_ticket` is the
first arm of `slot_just_freed`; the inode and order arms stay behind it, so a
ticket-less daemon still works.

Both ends had to be taught the ticket, and each was broken in its own way before
it worked:

**The mark was looked up by inode.** `take_present_mark(published_ino)` matched
the shim's slot inode against the daemon's registration inode, which is exactly
the identity the ticket exists to escape — so on RP6 and Odin 3, where those
differ, the lookup missed and every note left with `ticket: 0`. It is identity
first, then the oldest unclaimed mark, which is safe here because both ends see
the same commit sequence: no window, no floor, no reordering. A mark lost to the
queue cap cannot pair later frames with the previous frame's ticket, because order
may only move `MARK_LAST_TICKET` forward.

**A 24-byte read buffer truncated the 32-byte mark.** The daemon read the channel
into `[0u8; ScanoutAllocReq::LEN]`; on SOCK_SEQPACKET a short receive buffer
truncates the frame and discards the rest, so `decode` returned None and the mark
never reached `note_present_mark`. Measured as `sf mark: hit=0 order=0 miss=3
skew=0 pending=0` and `tick=[n:0]` on every census line, with both ends looking
correct. Readers now use `wire::INBOUND_MAX`, derived from the inbound types, and
`every_inbound_frame_fits_the_readers_buffer` fails the build if a new frame does
not fit.

Measured on RP6 (Dave, 1280x720, fifo, cap 60, 60 Hz):

    before  rnotes=16  tick=[n:0]   by_order=2   channel=[dead:true]  59.8 fps
    after   rnotes=16  tick=[n:15]  by_order=2   channel=[dead:true]  60.0 fps
    sf mark: hit=0 order=1 miss=2 skew=0 pending=0 last=1

Tickets now reach the notes; RP6 cannot prove the pairing end to end because its
channel is dead and almost nothing parks there, which leaves Nova and Odin 3 to
exercise it. One instrument is new and unresolved: `sf mark` printed once in 115 s
while 15 ticketed notes arrived, and those two facts cannot both be true with
`ctx.ticket` written only from `take_present_mark`. The behaviour is right, the
evidence is not yet trustworthy, and a publish counter will settle it.
…read the census

New `docs/24-release-notes.md`, with `10-fps-limit.md` and the index pointing at
it. It documents the scan-out release channel as it now stands rather than as it
was built:

- the three messages and their layouts, including the ticket on `BufferReleased` —
  the one message that went without a token while six mechanisms compensated for
  it (identity, order, a reorder window, a one-period floor, an anchor heuristic
  and a bound derived from the interval it governed);
- the ownership inversion that puts the buffers in the daemon, because API 33 has
  no AHB-from-fd and `setBuffer` must come from the allocator;
- the five-step rule that answers a park: ticket, inode, order, bound, fail-open;
- what each of the three devices does, measured on Dave in game.

Three claims in it are corrections rather than descriptions, and they are recorded
as such because each cost a session:

**The census needs `GNDRM_LOG_VKSHIM=1`.** `present mode:` is emitted twice —
`logi!` unconditionally for the header, `logf!` for the census. A session without
the variable is indistinguishable from a shim built before the census existed, and
Odin 3 was twice diagnosed as a stale payload on that basis, once on timestamps
that did not support it.

**A rate comes from two adjacent lines, not from a counter.** Odin 3's first
in-game reading was `fps=36.6 p95=101 ms repeated=20`; it was the loading
transition in the same window, and the steady state is 59.7 with `slow=0/118`.
`acq_fps`, the `acqus` means and the `presiv` means are lifetime figures.

**The order arm is not dead on Odin 3.** It answers 54 % of acquires there, each in
about 110 us, so the identity and order paths can only be retired with Nova's
evidence — and `by_order` climbing is not a defect signal on its own.

Still open, in the document: RP6 has no latch time and therefore no measured hold,
so whether its output is clean or merely fast is unknown; the daemon's counters do
not reconcile on RP6 while they do on Nova; a pooled copy produces no note at all;
and `by_order` conflates a note naming another buffer with a note older than the
anchor.
@joshuatam

Copy link
Copy Markdown
Collaborator Author

Since 292d0dc: the release note now names the frame, not the buffer

Two commits — 1a11479 (code) and a5b28dc (docs).

The change

BufferReleased was the only one of the three scan-out messages without a token.
PresentMark carried the guest's id, PresentDone echoed it, and the release note — the one a park actually waits on — carried an inode. Six mechanisms existed to compensate: identity matching, an order fallback with a 5 ms reorder window, a one-display-period floor, since = commit_ns.min(parked), a liveness heuristic, and a bound derived from the interval it governed.

The shim now mints a ticket per commit (process-wide, monotonic, never reused), sends it in the mark, and the note returns it:

PresentMark    { ino, id, ticket }               // 32 B
BufferReleased { ticket, ino, latch_ns, source } // 40 B

take_released_ticket() is the first arm of slot_just_freed; identity and order stay behind it. source distinguishes a signalled fence from a watcher timeout, which is the distinction RP6 could not express.

Two defects the first version had, both found by measuring

Neither was visible in review, and the second was only findable after the first:

The mark was looked up by inode. take_present_mark(published_ino) matched the shim's slot inode against the daemon's registration inode — precisely the identity the ticket exists to escape — so on RP6 and Odin 3 the lookup missed and every note left with ticket: 0. Now identity first, then the oldest unclaimed mark, guarded so order may only move the ticket forward.

A 24-byte read buffer truncated the 32-byte mark. The daemon read the channel into [0u8; ScanoutAllocReq::LEN], and on SOCK_SEQPACKET a short buffer truncates the frame and discards the rest, so decode returned None and the mark never reached note_present_mark. Measured as sf mark: hit=0 order=0 miss=3 skew=0 pending=0 last=0 with tick=[n:0] on every census line, both ends looking correct. Readers now use wire::INBOUND_MAX, derived from the inbound types, and every_inbound_frame_fits_the_readers_buffer fails the build if a new frame does not fit.

Measured — Dave the Diver, 1280x720, fifo, cap 60, 60 Hz panel

Nova (740) Odin 3 (830) RP6 (740)
fps, menu / in game 60 / 60.0 60 / 59.7 (p95=17.2 ms, slow=0/118, repeated=0) 60 / 59.8
tick= of rnotes 5 168 / 4 627 1 760 / 1 793 15 / 16
sf mark: hit=4 736, order=1, miss=2 hit=7 449, order=2, miss=3, skew=1 not re-read after the fix
channel= unanswered:0 dead:false unanswered:0 dead:false unanswered:6 dead:true
by_order frozen — 1 211 across 240 frames rising, 54 % of acquires, ~110 us each 2
sf hold: 1.5-2.5 periods 76 % at 1-1.5, 22 % at 1.5-2.5, timeouts=0 silent

On Nova, before the ticket: by_order=3 640 of rnotes=4 328 (84 % of parks). After: the counter stops moving entirely. On Odin it does not stop, but each order-answered park costs about a tenth of a millisecond, so that is a cost rather than a defect.

Two things this does not fix

  • RP6 has no latch time. It runs 60 fps on channel=dead:true, i.e. on the fail-open from 292d0dc, and no session has produced a single sf hold: sample — so how long SurfaceFlinger holds a buffer there is unknown, and whether its output is clean or merely fast has not been measured.
  • The order arm is still load-bearing on Odin 3 at 54 % of acquires. Deleting it needs a fix for why the ticket lookup misses that parked slot there, which is a park/release timing relationship Nova does not have.

Documented in docs/24-release-notes.md, including three corrections that each cost a session: that the census needs GNDRM_LOG_VKSHIM=1 and a session without it looks like a pre-census build; that a rate comes from two adjacent census lines and not from acq_fps, which is a lifetime average; and that by_order climbing is not a defect signal by itself.

joshuatam and others added 3 commits November 14, 2026 12:32
`on_complete` read `(*prev).ticket` on SurfaceFlinger's binder thread, some time
after the apply that replaced it. That field is overwritten by the buffer's next
publish, and while the callback normally lands long before the buffer is reused,
a delay (a stalled SF, a suspend) could see the buffer published again first —
the note would then name the newer frame, and the shim would free the slot
holding it while the display was still reading it. Precisely the early free the
ticket exists to prevent.

`release_ticket` is snapshotted at the apply, where the invariant holds:
between the apply and the callback this buffer is on the layer and cannot be
published again. Same value in every non-delayed case, so this is inert on the
common path. It has no observable signature without a delayed callback, so no
session can tell the two binaries apart: the snapshot is verified by review
and by that invariant, not by a counter.

**The ticket was written without the guard its reader holds.** The commit worker
stores `(*s).ticket` without `shared`; `slot_just_freed` loads it with `shared`
held. As a plain `u64` the only ordering between them was temporal, and a stale
read that happened to match an unconsumed older note would free the slot a frame
early. It is `AtomicU64` now, stored `Release` and loaded `Acquire`.

**The mark fallback accepted any ticket that moved forward.** One mark is sent
per commit in order, so the next publish must take the *next* ticket. "Greater
than the last" accepts a mark belonging to a different frame, binds it to this
registration, and when that buffer's release fires the shim frees the slot
holding somebody else's frame — a tear, since the present path never consults a
ticket. The rule is now exactness with three outcomes, because a bare refusal
would wedge on the first lost mark:

    == last + 1                      pair it
    <= last                          already published: discard the head
    last+2 .. last+MARK_RESYNC_GAP   a burst of lost marks: re-seed and pair
    > last + MARK_RESYNC_GAP         refused; the ticket path stands down

`stale` is not cosmetic: an identity hit removes a mark from the middle of the
queue, and without discarding the older heads the queue would sit on a ticket no
publish will ever match. `resync` is the only measurement that `sendmsg` drops
marks under load, which nothing had.

RP6 exercised the exact-next rule: `sf mark: hit=9617 order=1 miss=7 stale=1
resync=0 skew=0 pending=0`, `tick=12 of ~17 notes`, rate 59.7 unchanged. The
stale path ran once without wedging the queue. Unverified on Nova and Odin,
where `tick=` runs in the thousands — RP6 runs on the fail-open and pairs a
dozen notes a session.

`sf mark:` now prints `hit order miss stale resync skew pending last`.
… smaller fixes (#68)

* icd_shim: a release note read while an allocation reply is awaited is queued, not fatal

exchange_req knew every push on the scan-out channel except BufferReleased.
A note that arrived ahead of the allocation reply fell through to
Failure::Dead: the channel was closed and reconnected, and the note was lost.
lsfg_config skipped the same note silently.

The release watcher pushes whenever a fence signals, so this can happen on any
allocation made while frames are being shown (a swapchain recreation, a
generation destination grown mid-session).

Both readers now hand the note to apply_release, the helper poll_notes uses,
so it is queued and re-arms parking the same way wherever it is read. The
exchange test sends one ahead of the reply and checks it is held.

* icd_shim: a fallback arm does not spend a note older than the park's own ticket

The inode arm matched a note on its inode alone, and the order arm took the
oldest note whatever ticket it carried. Two notes could therefore free a slot
that was still on screen:

- a park on a buffer expires, the buffer is committed again and parked, and
  the late note for the earlier frame frees it through either arm;
- a hidden slot or generation destination is committed with a ticket but never
  parked, and its note pays the next guest park by order, while that guest
  frame is the one that replaced it on the layer.

Both notes name a ticket older than the park's. Such a note says nothing about
the parked frame, so both fallback arms now pass the park's ticket and refuse
it: the inode arm drops it as stale for that buffer, the order arm skips it and
leaves it for its own ticket or the age floor.

A newer ticket still pays. A note can arrive before its own slot is parked,
and the ticket arm only looks at parked slots, so the order arm hands it to the
oldest park, which left the layer before the note's frame did. Read from the
code, that is the likeliest source of Odin 3's order traffic with nearly every
note ticketed (not measured), and this rule leaves it alone. Notes or parks
without a ticket are not judged.

* presenter: a new mark sender starts the ticket order again

MARK_LAST_TICKET is a process-wide static that was never reset, and the order
match refuses any mark whose ticket is not above it, before removing the mark
from the queue. The shim's TICKET_SEQ starts again at 1 in every game process.

So a second game in the same app process had every order match refused as
skew, and the refused mark stayed at the head of PRESENT_PENDING, blocking the
marks behind it. Its notes left without a ticket wherever the inode did not
match. The previous game's unclaimed marks could also pair by inode with a
recycled buffer and carry the old game's ticket.

A subscribe that asks for present ids now clears the pending marks and the last
ticket together, under the queue's lock. Only the shim subscribes with that
cap, and it subscribes once per connection before any mark. A reconnect of the
same process loses at most the marks in flight; their notes carry no ticket.

* presenter: the LsfgConfig request fits the daemon's read buffer

INBOUND_MAX says every inbound frame must fit, but it left out LsfgConfig. The
shim sends one from lsfg_config() on the scan-out channel, and serve_scanout
decodes it from the same INBOUND_MAX buffer.

At 288 bytes against a 32-byte buffer, SEQPACKET truncated the request to 32,
LsfgConfig::decode wanted the full length, and the request was logged as an
unknown frame and never answered. The shim only got settings when they rode
along with the subscribe answer, and otherwise fell back to its env defaults.

LsfgConfig is now part of INBOUND_MAX and of the test that guards it. The two
readers that use the constant (serve_scanout, drain_retired) now hold 288
bytes on the stack instead of 32.

---------

Co-authored-by: Utkarsh Dalal <utkarsh.dalal@toptal.com>
…the panel

`min(cap x (m-1), refresh)` counted the source frames outside the panel's budget,
so a synced session could plan more commits than the panel can show: cap 40 x2 on
60 Hz produced 40 acquired + 40 generated = 80 a second, of which the compositor
dropped 20. The panel can show `refresh` frames however they were made, so the
generator's share is what is left after the source frames take theirs:

    generated = min(cap x (m-1), refresh - acquire)

`refresh - acquire` is `saturating_sub`, so a cap above the panel leaves zero
rather than wrapping.

The consequence is deliberate and is now pinned by a test rather than left in
prose: at 60 Hz, cap 40, x2, the panel leaves 20 generated against 40 source
frames — half a frame per source, which `generate_per_source` floors to none, so
frame generation does nothing at any cap above half the refresh. At cap 30 x2 the
same panel leaves 30 and generation survives. Lower the cap or the multiplier to
make room; the unsynced rows are untouched and still let the compositor drop the
remainder by design.

Tests moved with the rule rather than being deleted: cap 40 x2 is 20 generated
(was 40), cap 40 x4 is 20 (was 60), `generate_per_source(4)` is 0 (was 1), and
`a_cap_above_half_the_panel_leaves_no_room_to_generate` holds all three
interesting points including the cap-above-refresh case.

`docs/10` carries the new row and states the floor-to-zero consequence in the
prose, since the table alone cannot show a feature switching itself off.

From Utkarsh's #68, commit 4 of 5, taken deliberately and with the consequence
accepted.
@utkarshdalal
utkarshdalal merged commit f41381e into master Nov 14, 2026
1 check passed
@utkarshdalal
utkarshdalal deleted the refactor/vsync branch November 14, 2026 07:15
@joshuatam
joshuatam restored the refactor/vsync branch November 21, 2026 06:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants