Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
2fcf7c7
icd_shim: the guest's present mode is the only one, and the override …
joshuatam Nov 11, 2026
6650d49
presenter: measure how long SurfaceFlinger holds a buffer after showi…
joshuatam Nov 11, 2026
57a510c
icd_shim: the guest's mode is the only mode, and every limit comes fr…
joshuatam Nov 11, 2026
642015d
presenter: report SurfaceFlinger's own release of a scan-out buffer
joshuatam Nov 11, 2026
8e2b5a3
icd_shim: the acquire gate holds the cap for every declared mode
joshuatam Nov 11, 2026
d09b5fe
icd_shim: the cap is a rate, and one rule applies it
joshuatam Nov 12, 2026
407ecf3
icd_shim: count which path answers a present wait
joshuatam Nov 12, 2026
ab1a2b5
icd_shim: a present wait is bounded by its own commit
joshuatam Nov 12, 2026
cf76583
icd_shim: the daemon's read rate is not a frame budget
joshuatam Nov 12, 2026
bffacaf
docs/10: the table is the rule; the sessions that run are a subset
joshuatam Nov 12, 2026
db8c8a9
icd_shim: the hold follows the declared present mode
joshuatam Nov 12, 2026
99b0246
icd_shim: immediate is served as mailbox, and generation follows the …
joshuatam Nov 12, 2026
af67cc2
icd_shim: the park bound follows the producer, not the panel
joshuatam Nov 12, 2026
0e6a009
icd_shim: the present wait reports handover, not scan-out
joshuatam Nov 12, 2026
fceaa19
icd_shim: a parked destination is reclaimed, not abandoned
joshuatam Nov 12, 2026
0a801fd
icd_shim: parking has no drought fallback
joshuatam Nov 13, 2026
e4e3fd2
icd_shim: the image count is sized for the served mode
joshuatam Nov 13, 2026
9b56d91
icd_shim: the census rate is frames over time, not 1/latency
joshuatam Nov 13, 2026
be71f84
icd_shim: the release schedule is a grid, not a per-frame offset
joshuatam Nov 13, 2026
5dc1cd9
icd_shim: state the image-count decision at creation
joshuatam Nov 13, 2026
a694ffa
icd_shim: a generated frame reports itself when it is committed
joshuatam Nov 13, 2026
37ffa38
docs/10: the hold follows the served mode, and the gate is a grid
joshuatam Nov 13, 2026
77fba5a
icd_shim: a park's bound cannot be derived from the frame it limits, …
joshuatam Nov 13, 2026
365bd39
icd_shim: a release note that names no parked buffer can still free t…
joshuatam Nov 13, 2026
94a3495
icd_shim: hidden slots are not parked, and the ring is sized from the…
joshuatam Nov 13, 2026
292d0dc
icd_shim: a park is only placed while the release notes are being paid
joshuatam Nov 13, 2026
1a11479
icd_shim: a release note names the commit's ticket, not its buffer
joshuatam Nov 13, 2026
a5b28dc
docs: the release-note channel, the ticket that pairs it, and how to …
joshuatam Nov 13, 2026
31737b1
notes: pair exactly, and name the frame the fence describes
joshuatam Nov 14, 2026
63dd913
Pointers for #67: release notes that free the wrong buffer, and three…
utkarshdalal Nov 14, 2026
e6ccad5
icd_shim: the synced generation ceiling is the panel's leftover, not …
joshuatam Nov 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
311 changes: 176 additions & 135 deletions docs/10-fps-limit.md

Large diffs are not rendered by default.

70 changes: 64 additions & 6 deletions docs/12-present-latency-budget.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,55 @@ emitted with the publish, so a paced frame's present does not wait it out.
Buffer reuse still rides it — the next publish onto a slot waits on the previous
release fence the completion stored.

## SurfaceFlinger's hold on a buffer (which release rule is safe)

The page-flip event says the frame was *published*, not that SurfaceFlinger has
finished with it. A producer handed its buffer at that event may still be
writing into a buffer on the panel — a scan-out tear, and one no screen
recording can show, because the buffer is repainted before anything reads it
again. Deferring the release by one flip removes the tear by removing a buffer
from every producer: a 3-image swapchain keeps one in flight instead of two, so
a producer can no longer run ahead of the flip and a late frame has no cushion.

SurfaceFlinger's own release fence is the exact answer, and the daemon already
receives it. `ASurfaceTransactionStats_getPreviousReleaseFenceFd` reports, in the
completion of a transaction, the fence of the buffer that transaction
**replaced** — not the one it published:

```
publish X, which replaces W ──▶ completion reports W's fence
▼
fence signals: W is free
```

So the fence is filed on W's mailbox (`ReleaseCtx::replaced_ctx`) rather than on
the publisher's — that attribution is what makes it usable at all — and it is
waited on off the completion thread. Two things use it:

- the publish that reuses W waits on it before applying, so the pool never
republishes a buffer the panel is still reading;
- a watcher thread waits on it and pushes `BufferReleased` (`CAP_RELEASE_NOTE`)
carrying W's scan-out inode. A shim that declares the cap keeps that slot busy
until the note arrives: the compositor's `wl_buffer.release` only parks it.

A producer the shim does not render for — the guest's own GL blits through
Xwayland — reads no notes, and for that class the deferral above is the only
lever.

`sf hold:` measures the hold where it ends: the watcher samples the gap from the
released buffer's latch to the instant its fence signals.

```
gndrm-daemon: sf hold: n=<samples> <half=<n> half-one=<n> one-1.5=<n> 1.5-2.5=<n> over-2.5=<n> max=<us>us period=<us>us timeouts=<n>
```

Buckets are halves of one display period, and the period is the latch grid's own
(median of the last nine accepted gaps; a gap outside 3–50 ms is a burst or a
stall, not a period). `one-1.5` and above is the share a one-flip deferral does
**not** cover. `timeouts` counts fences that reached `RELEASE_WATCH_MAX` (500 ms)
without signalling — the release is reported anyway, so a stuck compositor
delays a producer instead of hanging it. One line per 10 s.

## Why the event is emitted with the publish

`commit_worker_loop` emits the page-flip event immediately after the publish
Expand All @@ -44,9 +93,9 @@ into every paced frame.

Buffer-reuse safety is unchanged: the scan-out pool still caches a buffer for
reuse only once the presenter reports SurfaceFlinger's completion (the slot's
`latched` flag), and the next publish still blocks on the previous release
fence. Only the *event* — a pacing/visibility signal to the client — stops
carrying the round trip.
`latched` flag), and the publish that reuses a buffer still waits on that
buffer's own release fence. Only the *event* — a pacing/visibility signal to the
client — stops carrying the round trip.

## Measured effect

Expand All @@ -61,11 +110,18 @@ The paced path meets its target, and the
uncapped rate is bounded upstream — the client's own present lap through the
ICD shim to gamescope — not by the flip-event path.

### The FIFO declaration is not the throughput cost
### The FIFO declaration is not the throughput cost, and not a limiter

The shim's per-commit `swapchain_set_present_mode(FIFO)` declaration does not
bound the uncapped rate — removing both sites left it unchanged. It stays in the
tree: the request/divisor cap needs it.
bound the uncapped rate — removing both sites left it unchanged.

It is not a limiter either, and the gate no longer stands down for it.
gamescope's `steamcompmgr_should_vblank_window` withholds the window's frame
callback, and this shim never requests one; the divisor also only acts when the
cap is below the refresh AND divides it. A FIFO guest at 60 on a 60 Hz panel, or
at 40 on 60 Hz, therefore had no cap at all — measured as a 26 fps Dishonored
session whose Target FPS did nothing. Every declaration is gated now; gamescope's
divisor is left as the pacer for content the shim does not present.

## The X11 arm as a control — pacing is deadline/timer-based, not deferral

Expand Down Expand Up @@ -96,6 +152,8 @@ number into the arm asymmetry from this.

## What is NOT proven / open

- `sf hold:` has no device capture yet: the buckets say which release rule is
sufficient, and nothing has read them on hardware.
- The uncapped ceiling (~259 /s on this scene) is **not** the flip-event path;
it is the client↔gamescope lap (`vkAcquireNextImageKHR` in the ICD shim
blocking on the compositor's `wl_buffer.release`). Not measured end to end;
Expand Down
85 changes: 42 additions & 43 deletions docs/15-fps-limiter-pacing-and-vsync.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,25 +11,22 @@ cursor, scan-out and mode patches.

| place | what it holds | set by |
|---|---|---|
| the shim's declared present mode | the container's `MESA_VK_WSI_PRESENT_MODE` (else the guest's mode); with no cap, a guest's FIFO request over a non-FIFO env; FIFO under a cap at the display's rate; mailbox under frame generation | the container, the guest and the cap (`docs/10`) |
| gamescope's own limiter | `nRefreshHz / nTargetFPS`, a divisor of the mode's rate; holds FIFO commits only | `debug_set_fps_limit`, sent only when generation is off |
| the shim's acquire gate | the cap, on the display's vblank grid, unless the container's mode is FIFO | `FrameCapNote{fps}` and `VsyncNote` from the daemon |
| the shim's declared present mode | the mode the guest asked for, except `IMMEDIATE` which is served as `MAILBOX`; FIFO under a cap at the display's rate when the guest asked for mailbox; mailbox under frame generation | the guest, the served mode and the cap (`docs/10`) |
| gamescope's own limiter | `nRefreshHz / nTargetFPS`, a divisor of the mode's rate; acts only when the cap is below the refresh and divides it, and only for clients that wait on a frame callback | `debug_set_fps_limit`, sent only when generation is off |
| the shim's acquire gate | the cap, one release per `1e9 / cap`, for every declared mode | `FrameCapNote{fps}` |
| the presenter's latch grid | the display's latch points, as measured | `VsyncNote` from the daemon (`docs/17`) |

Which one holds the cap follows the declared mode. Declared FIFO (the container set
fifo, or no env and a FIFO guest), gamescope's limiter passes every
`nRefreshHz / target`-th vblank (`nVblankDivisor = nRefreshHz / min(target, nRefreshHz)`)
and holds the guest's commits to it. Declared mailbox, immediate or FIFO-relaxed (mailbox
is the container default), the limiter does not hold them and the shim's acquire gate
releases the guest's frames on the display's vblank grid. A container in one of those
modes under a cap at the display's rate is declared FIFO with no gate when the guest
asked for mailbox or immediate (`source=cap-rate`), as on master, and keeps its mode with
the gate every vblank when the guest asked for FIFO (`source=cap-rate-vsync`, `docs/10`).
For the former: gamescope latches one commit per vblank at its own
wakeup, which the shim cannot see under mailbox, and its limiter (divisor 1) paces the
guest (`docs/10`). Under frame generation the app
disarms gamescope's limiter and the shim's time gate holds the source rate instead
(`docs/17`).
The shim's gate holds the acquire limit whatever the declared mode, and it is the
only regulator: one release per `1e9 / cap`, booked from the release that just
happened. gamescope's limiter is not a fallback for it — it passes every
`nRefreshHz / limit`-th vblank (`nVblankDivisor = nRefreshHz / min(limit,
nRefreshHz)`) to a client that waits on its frame callback, which the shim never
does, and the truncating divisor means `40` on 60 Hz passes every one of them. It
stays as the pacer for content the shim does not present. What the limit *is* comes from one place — the guest's present mode, the cap,
the multiplier and the panel's refresh (`docs/10`, `icd_shim/src/limits.rs`) — and
the declaration is the guest's own in every case, so the cap never moves it. Under
frame generation the app disarms gamescope's limiter and the shim's gate holds the
source rate instead (`docs/17`).

## 2. The mode is the display's rate

Expand All @@ -50,8 +47,8 @@ that rate is the display's.

- **FIFO.** A present is requeued until the display releases a buffer, so the guest is
paced to the panel whether or not it asked to be. On gamescope's override route the
mode declared per commit is the container's `MESA_VK_WSI_PRESENT_MODE` (the guest's
own without it), cap or no cap, and mailbox under frame generation (`docs/10`). On
mode declared per commit is the one the guest asked for, cap or no cap, and mailbox
under frame generation (`docs/10`). On
that route the shim answers `vkWaitForPresentKHR` from
gamescope's presentation feedback, as Mesa's Wayland WSI does: every commit that
carries a wait requests a `wp_presentation_feedback`, and the wait is answered on
Expand All @@ -71,13 +68,13 @@ that rate is the display's.
session takes (the `fallback=` counter of the periodic `present mode:` line counts it; that line repeats with `GNDRM_LOG_VKSHIM=1`, while the ungated one prints at session start and on a change of the declared mode, its source, the cap or the gate, `docs/10`). Without the global
(or off the override route) the wait is answered on the release, or two refresh
periods after the commit when no release report arrives first.
- **Mailbox and immediate.** A guest that asked for either does not wait, and neither
- **Mailbox, and immediate (served as mailbox).** A guest that asked for either does not wait, and neither
would one whose frames go out as mailbox or immediate (frame generation, or the
container's env while the guest believes it has FIFO), so those waits are not held for
the compositor: they are answered at the commit, after the frame's render fence
(`present_wait_answer`). One case is answered earlier, when the guest queues the
present: `source=cap-rate-vsync` (a cap at the display's rate, a container mode other
than FIFO, a guest that asked for FIFO, declared mailbox with the vblank-grid gate).
present: a FIFO-relaxed guest on gamescope's route whose rate the acquire gate holds
(one that waits on every frame).
That guest waits on every frame, and answered after the fence a latency-1 guest
alternated CPU and GPU: Retroid Pocket 6, DTD at 1080p, cap 60, VSync on, 60 Hz, 42 fps
with 23 ms from acquire to commit, the GPU at 65-69 % busy and 550 MHz because its
Expand Down Expand Up @@ -137,11 +134,9 @@ that rate is the display's.
commit per limited vblank, on the display's vblank stream above, and hands the
previous buffer back with `wl_buffer.release`, which is what frees the guest's next
acquire; a cap that is not the display's rate over a whole number runs at gamescope's
next divisor rate above it. Declared FIFO because the cap is the display's rate
(`source=cap-rate`), no gate runs either: gamescope's FIFO latch alone paces it.
Declared anything else,
gamescope takes the newest commit at each composite and the shim's acquire gate is
the cap (`icd_shim/src/vsync_gate.rs`).
next divisor rate above it. Declared anything else,
gamescope takes the newest commit at each composite and the shim's acquire gate holds
the acquire limit (`icd_shim/src/vsync_gate.rs`).
Its release points are the instants the flip events are stamped at: the daemon's
latch grid (`VsyncNote` anchor and measured period) minus the stamp lead
(`stamp_lead_ns`). gamescope wakes to composite just before each (wakeup = stamp +
Expand All @@ -161,9 +156,9 @@ that rate is the display's.
own clock (exactly 1e9 / N ns) and beat against the display's 59.97-59.99 Hz
(57-59 fps at a 60 cap). A cap above the rate runs on the cap's own clock
(`gate=clock`, also frame generation's source rate). Without the stamp lead (no
note yet, or a daemon that predates it) the gate does not run: a capped swapchain is
declared FIFO and gamescope's limiter holds it (`source=cap-compat`), so a
payload-only rollout keeps today's pacing until the app ships the daemon.
note yet, or a daemon that predates it) the gate cannot run on the grid and paces
on its own clock (`gate=clock`), which beats against the panel: a payload-only
rollout keeps that pacing until the app ships the daemon.
- **Fallbacks.** On API 29-32 Choreographer reports the vsync time only
(`AChoreographer_postFrameCallback64`): its measured period is used with the latch
grid's phase (`vsync.rs`, from `ASurfaceTransactionStats_getLatchTime`), or the vsync
Expand All @@ -177,15 +172,10 @@ that rate is the display's.

## Behaviour changes in gamescope sessions

- **The container's present mode is declared, except under a cap at the display's
rate.** `MESA_VK_WSI_PRESENT_MODE` decides the mode on the gamescope route as on the
X11 Present route; without it the guest's own mode is declared. A container left at
the mailbox default runs, with no cap, FIFO for a guest that asked for FIFO (its
own VSync, `source=guest`) and mailbox for any other guest, and mailbox capped by the shim's
vblank-grid gate under a cap below the display's rate. Under a cap at the display's
rate it is declared FIFO with no gate (`source=cap-rate`), because the shim
cannot keep two mailbox commits out of one gamescope composite (`docs/10`). One set
to fifo runs FIFO under gamescope's limiter.
- **The guest's present mode is what gets declared.** There is no environment
override above it, so a game's own VSync request is never turned into a mailbox
session — and no cap or multiplier changes it either: they set the acquire and generation limits (`docs/10`,
`icd_shim/src/limits.rs`).
- **A game below the cap keeps its own rate under mailbox** (caps below the display's
rate). Under FIFO and gamescope's
limiter each frame is held to whole limited vblanks, so a game below the cap judders
Expand All @@ -207,6 +197,13 @@ that rate is the display's.
separately; between the two, for a moment, the swapchain's mode is declared with no
cap, so a mailbox/immediate swapchain can run uncapped for a few frames.

- **`IMMEDIATE` is served as `MAILBOX`.** The one substitution the layer makes
(`choose_live_mode`): a frame that cannot be shown is dropped for the client
instead of being scanned out mid-flip, and the declaration follows the served
mode. Its hold is the served mode's too (`note`), so the buffer still waits out
its own scan-out — a mode override that changed only the present path would
leave the reuse tear open.

## 4. What the daemon owns

- The latch grid: `ASurfaceTransactionStats_getLatchTime` on every publish, the phase
Expand All @@ -216,7 +213,8 @@ that rate is the display's.
flip events' lead (below), so `anchor_ns - stamp_lead_ns` is gamescope's vblank grid,
the one the shim's acquire gate releases on. The daemon sends at least 1 ns while
the flip events follow a grid, so 0 means "not known" (no grid, or a daemon that
predates the field), and the shim then declares FIFO under a cap instead of gating. Its period is the one measured from Choreographer while that is locked
predates the field), and the shim then cannot gate on the grid and paces on its own
clock (`gate=clock`). Its period is the one measured from Choreographer while that is locked
(the mode's advertised rate otherwise), so frame generation extrapolates
the display's real rate. Its anchor is also the
flip timeline's phase where Choreographer gives no deadline, and its fallback.
Expand Down Expand Up @@ -244,9 +242,10 @@ measures — the latch grid to the presenter, the vsync timeline in the flip eve
Retroid Pocket 6 (59.97-59.98 Hz), DTD title scene, cap 60, against master's FIFO
declaration on the same scene (59.22 fps, 1.3 % doubles):

- **A cap at the display's rate, declared FIFO** (measured with the vblank-grid gate
kept, `source=cap-rate gate=vsync`, before the gate was dropped from this cell;
without it the cell is master's FIFO path): in-game VSync off, 59.199 fps on `SurfaceFlinger`
- **A limit at the display's rate** (measured while the shim still rewrote that one
cell's declaration to FIFO with the vblank-grid gate kept, `source=cap-rate
gate=vsync`; the rewrite is gone — the declaration is the guest's and the gate
holds the limit): in-game VSync off, 59.199 fps on `SurfaceFlinger`
and 1.3 % doubles over 60 s, shim commits equal to the daemon's publishes within
0-2 per 10 s (the guest paces itself at ~59.3); VSync on, 59.983 fps and no
doubles.
Expand Down
Loading
Loading