Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
70 changes: 52 additions & 18 deletions docs/10-fps-limit.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,10 @@ enter it, so the mode is the rate the compositor paints at and the rate clients
are told. With no `-r` on the launch line, the paint tick, the app-refresh cycle
and the divisor base all derive from that one rate.

A divisor cap on the grid lands on its target exactly, and the uncapped ceiling
is the client↔gamescope lap — the grid itself never binds.
A divisor cap on the grid lands on its target's panel multiple — its nominal plus
the gap between the panel's nominal rate and its measured period, 0.9 % on both
devices measured — and the uncapped ceiling is the client↔gamescope lap; the grid
itself never binds.

| `-r` | presents/s |
|---|---|
Expand All @@ -84,7 +86,8 @@ is the client↔gamescope lap — the grid itself never binds.

The flip event is emitted with the publish (see 12), so a paced frame's present
does not carry the SurfaceFlinger round trip: `interval ≈ 1 / target`, and a
divisor cap reads its target exactly.
divisor cap reads its target's panel multiple — 0.9 % above the nominal, on the
devices measured — because the period it books is the panel's measured one.

## How the cap is applied

Expand Down Expand Up @@ -143,10 +146,12 @@ divisor cap reads its target exactly.
**served** mode — the same one `on_buffer_release` keys on — and on this route
every declaration is served as FIFO or MAILBOX: FIFO for a guest that asked for
it, MAILBOX for a generation session and for a declared `IMMEDIATE` or
`FIFO_RELAXED` (`choose_live_mode`). Both are synced, so the hold is `note` on every row: the
image comes back only when the compositor reports its release *and* the display
reports its scan-out release after that — measured at 1.5-2.5 display periods
(`sf hold`). [24-release-notes.md](24-release-notes.md) describes that channel:
`FIFO_RELAXED` (`choose_live_mode`). Only FIFO is synced, so only a FIFO row
holds to `note`: the image comes back when the compositor reports its release
*and* the display reports its scan-out release after that — measured at 1.5-2.5
display periods (`sf hold`). A mailbox row returns at the compositor's release,
which is before the display has finished reading it.
[24-release-notes.md](24-release-notes.md) describes that channel:
the note names the commit's ticket, so the pairing is exact where it once needed
an inode, an order window and a bound, and a park whose note never arrives is
released on its fence after four tries (`channel=[unanswered:… dead:…]`).
Expand Down Expand Up @@ -234,32 +239,60 @@ divisor cap reads its target exactly.
the rate is not a whole number of frames per source.

The gate (`icd_shim/src/vsync_gate.rs`) is one regulator and one rule: a frame
may start `1e9 / limit` after the previous frame started, and not before.
may start one period after the previous frame started, and not before. The
period is `1e9 / limit`, measured in the panel's own periods when the session
has reported its latch grid (`pacing`): a limit the panel can express is
`n` panel periods, and one it cannot keeps its own `1e9 / limit`.

```
gate: while now < next_ns { wait until next_ns }
book: next_ns += period (from the release point, not from now)
late by >= one period: next_ns = now + period, and the skip is counted
```

A limit the panel can express *is* its vblank divisor: 60 on 120 Hz is two
periods, 40 is three, 30 is four. Snapping the period to a whole multiple of the
panel's is what stops the gate beating against the display. `1e9 / 120` is
8 333 333 ns against a measured 8 257 000 ns, which slips 76 us a frame and
sweeps the whole vblank interval every ~108 frames; the frames that land late of
their vblank then wait a second one, and a 120 cap reads 80 fps. Mapped to the
panel the phase never moves, and the cap reads the panel's own rate.

Two things follow. A mapped divisor cap reads above its nominal by the gap
between the panel's nominal rate and its measured period — 60.55 for a 60 cap on
a 121.1 Hz panel, 0.9 % — because the multiple is the measured period and not the
nominal one: the multiple is the only rate the panel can show, and rounding the
other way would cost a whole divisor. And a cap *within* 2 % of a multiple is
served at that multiple even when it is not one, so 119 on that panel reads 121
(+1.7 %) and 122 reads 121. That is the mapping's cost, and the alternative is
leaving the cap to beat against the panel, which costs a vblank per frame. A
limit further from a multiple — 90 on 120 Hz is 33 % off one — is left on its own
clock, because no multiple expresses it and its achieved rate is already
quantized by the display.

So the limit is a maximum by construction — two releases are never closer than
one period. A frame that overshoots its release point by less than a period does
one booked period, and the booked period is the cap's own unless the panel can
express the cap, in which case it is the panel's multiple of it (the 0.9 % above).
A frame that overshoots its release point by less than a period does
not move the grid: the following frame gets a proportionally shorter hold, which
is what keeps the average *at* the limit instead of below it (`next_ns = now +
period` lost 7 % to accumulated lateness). A stall of a whole period or more is a
lost frame, not a debt: the schedule re-anchors at `now + period` and counts the
skip, so nothing repays itself with back-to-back releases. A game slower than the
limit is never held, because its next acquire is already past `next_ns`.

Releases are *not* snapped to the display's vblank grid. A grid-snapped release
holds the phase but bounds only the average rate: a release a slot wait delayed
lands between vblanks, and the next booking on the following vblank could be a
fraction of a period later. Measured on this path at a 60 limit: 74.7 frames/s
with the gate holding 8 % of acquires. The daemon's latch grid is still used
where a phase is what is wanted — frame generation places its batches on it
(`docs/17`) — not to limit a rate.
What the grid decides is the *period*, never the booking. Releases are not
snapped individually: the schedule still advances `next_ns` by the whole period
from the release point, so a release a slot wait delayed keeps its slot's
timeline and cannot shrink its successor. The earlier grid snapped each
release to the next vblank and booked from there, which put the successor a
fraction of a period later — measured at a 60 limit: 74.7 frames/s with the gate
holding 8 % of acquires. Mapping the period instead makes every interval the
same length, so that leak has nowhere to come from, and `docs/15`'s "the cap's
timeline, placed on the grid" is the same statement in the other direction.

`gate=clock` is every gated session now; `gate=off` means no limit.
`gate=clock` is every gated session (`Pacing` has one gated form; the mapping
changes the period, not the kind of release); `gate=off` means no limit.

The census says which path ran. Ungated, once when frames first flow and again
whenever the declaration, its source, the cap, the limits or the gate changes:
Expand All @@ -268,7 +301,8 @@ divisor cap reads its target exactly.
mailbox; `acquire` and `generate` are the limits in frames per second,
`acquire=0` for none and `generate=0` for generation off; `gate=clock` is
every session with a cap, whatever the display's rate — the gate books its own
grid at `1e9 / acquire_per_s` and does not defer to the compositor below a
grid at `1e9 / acquire_per_s`, mapped to whole panel periods when the session's
latch grid can express that rate, and does not defer to the compositor below a
refresh divisor). With
`GNDRM_LOG_VKSHIM=1` the same line repeats every 10 s with the counters a device
run checks the pacing against: `acquires= commits= declared_fifo=
Expand Down
13 changes: 10 additions & 3 deletions docs/15-fps-limiter-pacing-and-vsync.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,9 +200,16 @@ that rate is the display's.
- **`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.
mode. Its hold is *not* the served mode's: only a FIFO declaration waits out its
own scan-out (`note`); a mailbox slot is freed at the compositor's
`wl_buffer.release`, which is before the display has finished reading it. A
mailbox buffer that is superseded in the pending slot was never scanned and has
nothing to wait for, and holding it costs a whole period per frame — measured at
200 fps uncapped, 330 with this rule on the same session (Odin 3, Hades II). The
trade is that a mailbox buffer which *does* reach the panel can be written again
while it is being scanned: the reuse tear is open on that path by construction,
and it is the price of the rate. `wp_presentation_feedback.discarded` is the
authority that separates the two buffers, and it is not subscribed yet.

## 4. What the daemon owns

Expand Down
54 changes: 36 additions & 18 deletions icd_shim/src/proxy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8487,28 +8487,46 @@ extern "C" fn on_buffer_release(data: *mut c_void, _buf: *mut wl_proxy) {
// buffer the daemon does not track (a local allocation, or a daemon too
// old to send notes) is freed here, as before.
//
// Only for a synced declaration. `VkPresentModeKHR` is a contract about
// when an image comes back, and FIFO is the only one that promises the
// client a display-bound return: IMMEDIATE returns the image once it is
// handed over, MAILBOX as soon as a newer one replaces it. Parking those
// applies FIFO's lifetime to a mode that promised none, and the cost is
// measurable — an uncapped immediate session on a 120 Hz panel ran at
// Only for a mode that promises a display-bound return.
// `VkPresentModeKHR` is a contract about when an image comes back, and
// FIFO is the only one that promises it: IMMEDIATE returns the image once
// it is handed over, MAILBOX as soon as a newer one replaces it. Parking
// those applies FIFO's lifetime to a mode that promised none, and the cost
// is measurable — an uncapped immediate session on a 120 Hz panel ran at
// `depth x refresh / hold` = 106 instead of free, with `slot_waits` at
// 99 % and `in_flight` pinned at the depth. FIFO_RELAXED stays synced:
// the spec lets it return a late frame early, and holding it to the note
// is the conservative side of a row the table already calls synced.
// The *served* mode, not the declared one: an immediate guest is served as
// mailbox above, and a mailbox frame is replaced at a vblank rather than
// shown mid-scan — so its buffer still has to survive its scan-out, exactly
// as a FIFO frame's does. Keying this on the declaration would free the slot
// at the compositor's release again and let the guest write into a buffer
// the display is reading.
// 99 % and `in_flight` pinned at the depth.
//
// The other side of the trade, which is why MAILBOX is not in this set. A
// mailbox buffer that reaches the panel is scanned for a full period and
// must be held that long; a buffer replaced in the pending slot never was,
// and nothing else holds it. Parking both holds the latched frames *and*
// waits out the bound for the superseded ones, because only a latched
// frame is ever released and so only it gets a note. Measured on Odin 3
// (Hades II, uncapped, 4 slots, 120 Hz): `commits` 200.4/s against `notes`
// 119.8/s — the panel rate — so 40 % of commits had no note to wait for
// and fell to `release_note_limit_ns()`; every slot averaged 2.42 periods
// against a display hold the daemon measures at 1.0-1.5, and the session
// read 200 fps. With this set it reads 330 (5 samples, 328.7-331.0) at
// `slot_waits` 2 of 59 356 acquires, `park_timeouts` 0 and a 1.46-period
// hold, which is the display's own.
//
// What it gives up: a mailbox buffer that does reach the panel can be
// written again while it is being scanned, so the reuse tear is open on
// this path by construction. The principled fix is the compositor's
// `wp_presentation_feedback.discarded` — park what was latched, free what
// was discarded — which is not subscribed yet (`present::expect_feedback`
// requests none when the present carries no id, so the census reads
// `presented=0 discarded=0`).
//
// The *served* mode, not the declared one, so an immediate and a
// FIFO-relaxed guest are both served as mailbox (`choose_live_mode`) and
// both now take the mailbox rule: FIFO proper is the only declaration this
// still parks, and it is the only one the spec gives a display-bound
// return to.
let served = live_choice(sc).0;
let synced = matches!(
served,
VK_PRESENT_MODE_FIFO_KHR
| VK_PRESENT_MODE_FIFO_RELAXED_KHR
| VK_PRESENT_MODE_MAILBOX_KHR
VK_PRESENT_MODE_FIFO_KHR | VK_PRESENT_MODE_FIFO_RELAXED_KHR
);
// A synced slot waits for the display's own release, which is the note.
// No capability check stands in front of it: the note may never come (a
Expand Down
Loading
Loading