Skip to content

Pointers for #67: release notes that free the wrong buffer, and three smaller fixes - #68

Merged
joshuatam merged 4 commits into
refactor/vsyncfrom
notes-pair-by-ticket-only
Nov 14, 2026
Merged

joshuatam merged 4 commits into
refactor/vsyncfrom
notes-pair-by-ticket-only

Conversation

@utkarshdalal

@utkarshdalal utkarshdalal commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

These are pointers for #67, not a finished change. Each commit is one fix and stands alone, so take any of them, rewrite them, or drop them. Nothing here was run on a device. Host tests and clippy pass, and the Android target builds.

What each commit does

1. A release note that arrives during a buffer allocation no longer kills the channel (3d0e35e)

  • What was wrong: exchange_req handled every push except BufferReleased. A note that arrived before the allocation reply was treated as a dead channel.
  • Effect: the channel was closed and reconnected and the note was lost. This can happen on a swapchain recreation or when frame generation adds buffers mid-game.
  • Change: the note is queued the same way poll_notes queues it.

2. The fallback rules no longer spend a note that is older than the park (9ec0f6c)

  • What was wrong: the inode rule and the order rule ignored the ticket on the note. A late note for an earlier use of a buffer, or a note for a hidden or generated frame, could free a guest buffer that was on screen.
  • Effect: a torn frame, which is what the park exists to prevent.
  • Change: both rules refuse a note whose ticket is lower than the park's ticket. A note with a higher ticket still pays, because a newer frame leaving the screen means the older one has left too. This should leave the order traffic on Odin 3 alone, but that is read from the code and not measured.

3. The daemon forgets the old ticket order when a new shim connects (735beb7)

  • What was wrong: MARK_LAST_TICKET is never reset, and the shim starts its tickets again in every game process.
  • Effect: in the second game of one app run, every order match was refused as skew and the refused mark blocked the queue behind it.
  • Change: pending marks and the last ticket are cleared when a shim subscribes for present ids.

4. INBOUND_MAX includes LsfgConfig (68ea3b0)

  • What was wrong: the shim sends a 288-byte settings request and the daemon read it into a 32-byte buffer, so it was cut short and never answered. Settings only arrived with the subscribe answer.
  • Change: the constant and its test include LsfgConfig.

The frame generation limit change that was here is removed: the current rule stays.

Not changed here, but worth a look

The park is not active on the RP6. This is separate from the Portal 2 tear, which was the IMMEDIATE present mode and is fixed by serving it as MAILBOX (99b0246); the RP6 log confirms the game asks for mode 0 and is served mailbox. The point below is only about the buffer-reuse hold. Portal 2, cap 60 at 60 Hz, a5b28dc with GNDRM_LOG_DAEMON=1:

  • The game has four slots. The daemon shows only two of them, ino 1051452 and 1051456, alternating (300 and 300 in the last 600 commits). There is no foreign dma-buf copy line, so the panel reads the game's own buffers.
  • Release notes stop after the first second: 25 notes for 1610 commits, park_timeouts=13, then dead:true.
  • So after 292d0dc the park is off on this device, and each buffer is written again one frame after it was replaced. I have not seen a tear from this on the RP6. The question is whether the hold is needed there, and if it is, why the fence stops coming.
  • The notes stop because on_complete gets no previous-release fence (asc.rs around line 623 to 647). I do not know why Android stops returning one on this device.

Other points from the review, left for you to decide:

  • PresentMark and BufferReleased changed length with no version or capability check. A mismatched app and payload drop the messages without an error.
  • Hidden slots and generation destinations are not parked, so generated frames can still tear.
  • An uncapped mailbox guest is parked, and a frame the daemon coalesces gets no note, so each waits for the full bound.
  • docs/24 describes RELEASE_UNWATCHED and RELEASE_POOL_COPY, but nothing sends them.

Utkarsh Dalal added 3 commits November 14, 2026 10:17
… 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.
…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.
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.
@utkarshdalal
utkarshdalal force-pushed the notes-pair-by-ticket-only branch from 0c4e8b3 to f2a3b41 Compare November 14, 2026 04:47
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.
@utkarshdalal
utkarshdalal force-pushed the notes-pair-by-ticket-only branch from f2a3b41 to 68ea3b0 Compare November 14, 2026 05:59
@utkarshdalal utkarshdalal changed the title Pointers for #67: release notes that free the wrong buffer, and four smaller fixes Pointers for #67: release notes that free the wrong buffer, and three smaller fixes Nov 14, 2026
@joshuatam
joshuatam marked this pull request as ready for review November 14, 2026 06:24
@joshuatam
joshuatam merged commit 63dd913 into refactor/vsync Nov 14, 2026
1 check passed
@joshuatam
joshuatam deleted the notes-pair-by-ticket-only branch November 14, 2026 06:24
joshuatam added a commit that referenced this pull request Nov 14, 2026
…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 added a commit that referenced this pull request Nov 14, 2026
…comes from one rule (#67)

* icd_shim: the guest's present mode is the only one, and the override 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).

* presenter: measure how long SurfaceFlinger holds a buffer after showing 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.

* icd_shim: the guest's mode is the only mode, and every limit comes from 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.

* presenter: report SurfaceFlinger's own release of a scan-out buffer

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.

* icd_shim: the acquire gate holds the cap for every declared mode

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.

* icd_shim: the cap is a rate, and one rule applies it

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.

* icd_shim: count which path answers a present wait

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.

* icd_shim: a present wait is bounded by its own commit

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.

* icd_shim: the daemon's read rate is not a frame budget

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.

* docs/10: the table is the rule; the sessions that run are a subset

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.

* icd_shim: the hold follows the declared present mode

`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.

* icd_shim: immediate is served as mailbox, and generation follows the 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.

* icd_shim: the park bound follows the producer, not the panel

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.

* icd_shim: the present wait reports handover, not scan-out

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.

* icd_shim: a parked destination is reclaimed, not abandoned

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.

* icd_shim: parking has no drought fallback

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`).

* icd_shim: the image count is sized for the served mode

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.

* icd_shim: the census rate is frames over time, not 1/latency

`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.

* icd_shim: the release schedule is a grid, not a per-frame offset

`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.

* icd_shim: state the image-count decision at creation

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.

* icd_shim: a generated frame reports itself when it is committed

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.

* docs/10: the hold follows the served mode, and the gate is a grid

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.

* icd_shim: a park's bound cannot be derived from the frame it limits, 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.

* icd_shim: a release note that names no parked buffer can still free the 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.

* icd_shim: hidden slots are not parked, and the ring is sized from the 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.

* icd_shim: a park is only placed while the release notes are being paid

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.

* icd_shim: a release note names the commit's ticket, not its buffer

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.

* docs: the release-note channel, the ticket that pairs it, and how to 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.

* notes: pair exactly, and name the frame the fence describes

`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`.

* Pointers for #67: release notes that free the wrong buffer, and three 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>

* icd_shim: the synced generation ceiling is the panel's leftover, not 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.

---------

Co-authored-by: …
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