diff --git a/docs/10-fps-limit.md b/docs/10-fps-limit.md index 2e15c57..af3897b 100644 --- a/docs/10-fps-limit.md +++ b/docs/10-fps-limit.md @@ -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 | |---|---| @@ -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 @@ -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:…]`). @@ -234,7 +239,10 @@ 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 } @@ -242,8 +250,30 @@ divisor cap reads its target exactly. 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 @@ -251,15 +281,18 @@ divisor cap reads its target exactly. 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: @@ -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= diff --git a/docs/15-fps-limiter-pacing-and-vsync.md b/docs/15-fps-limiter-pacing-and-vsync.md index f9004ee..7ad29e9 100644 --- a/docs/15-fps-limiter-pacing-and-vsync.md +++ b/docs/15-fps-limiter-pacing-and-vsync.md @@ -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 diff --git a/icd_shim/src/proxy.rs b/icd_shim/src/proxy.rs index 4f4fffa..c9a2959 100644 --- a/icd_shim/src/proxy.rs +++ b/icd_shim/src/proxy.rs @@ -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 diff --git a/icd_shim/src/vsync_gate.rs b/icd_shim/src/vsync_gate.rs index 0c1f97c..3ce8fe5 100644 --- a/icd_shim/src/vsync_gate.rs +++ b/icd_shim/src/vsync_gate.rs @@ -82,10 +82,70 @@ impl Pacing { /// release per `1e9 / cap`. #[must_use] pub(crate) fn pacing(cap_fps: u32) -> Pacing { + paced_on(cap_fps, crate::lsfg::latch_grid()) +} + +/// [`pacing`] with the panel supplied, so the rule is testable without a session. +#[must_use] +pub(crate) fn paced_on( + cap_fps: u32, + grid: Option, +) -> Pacing { match crate::scanout::period_ns(cap_fps) { 0 => Pacing::Off, - period_ns => Pacing::Clock { period_ns }, + period_ns => Pacing::Clock { + period_ns: on_panel(period_ns, grid), + }, + } +} + +/// How far a cap's period may sit from a whole multiple of the panel's before it +/// stops counting as that multiple. Two percent: a cap a user picks *is* meant to +/// be a divisor of the refresh, and the panel's measured rate is not its nominal +/// one, so the cap and the panel disagree in their own nominals by up to this — +/// `1e9 / 120` against a measured 8 260 500 ns is 0.88 %, which is the gap on both +/// devices measured. The headroom past that is for a panel further from its +/// nominal. A cap that genuinely is not a divisor is further away by construction +/// — 90 on 120 Hz is 33 % off — and is left alone. +/// +/// The cost, which is the mapping's and not the tolerance's: a cap up to this +/// close below a divisor is served at the divisor, so it reads up to 2 % above its +/// own nominal (119 on a 121 Hz panel is served 121.06, +1.73 %). That is the +/// trade the mapping makes — the alternative is leaving the cap to beat against +/// the panel, which is what loses a vblank per frame below. +const PANEL_SNAP: f64 = 0.02; + +/// A cap period measured in the panel's own periods. +/// +/// The gate's clock does not need to be a lattice of vblanks to hold a rate, but +/// it does need to not *beat* against one. A period that is a whole multiple of +/// the panel's stays on the same phase forever, so every release falls in the +/// same place in the vblank interval and none of them is spent waiting a second +/// vblank it did not need. That is the whole difference: `1e9 / 120` against a +/// measured 8 257 000 ns slips 76 us a frame, sweeps the whole interval every +/// ~108 frames, and the frames that land late of their vblank cost a period each +/// — 80 fps under a 120 cap on a 120 Hz panel. +/// +/// It rounds to the *nearest* multiple, which can land marginally faster than the +/// cap (60 on a 121 Hz panel becomes two periods, 60.55 fps): the multiple is the +/// only rate the panel can actually show, and rounding up instead would cost a +/// whole divisor (40 fps). +/// +/// A cap that is not near a multiple keeps its own period. It cannot be expressed +/// on this panel anyway, and its achieved rate is already quantized by the +/// display — 90 on 120 Hz releases every 11.1 ms but a frame can only be shown on +/// a vblank, so it lands on alternate ones at 60. +fn on_panel(period_ns: u64, grid: Option) -> u64 { + let Some(grid) = grid.filter(|g| g.period_ns != 0) else { + return period_ns; + }; + let panel = grid.period_ns; + let ratio = period_ns as f64 / panel as f64; + let multiple = ratio.round(); + if multiple < 1.0 || (ratio - multiple).abs() > multiple * PANEL_SNAP { + return period_ns; } + (multiple as u64).saturating_mul(panel) } /// Acquires that started more than a period after their release point, and the @@ -185,12 +245,96 @@ mod tests { const P60: u64 = 16_666_666; fn period(cap: u32) -> u64 { - match pacing(cap) { + match paced_on(cap, None) { Pacing::Clock { period_ns } => period_ns, Pacing::Off => panic!("no cap {cap}"), } } + /// A grid whose latch spacing is `panel_ns`. + fn grid(panel_ns: u64) -> gndrm_lsfg::pacing::Grid { + gndrm_lsfg::pacing::Grid { + anchor_ns: 0, + period_ns: panel_ns, + lead_ns: 0, + } + } + + fn period_on(cap: u32, panel_ns: u64) -> u64 { + match paced_on(cap, Some(grid(panel_ns))) { + Pacing::Clock { period_ns } => period_ns, + other => panic!("{cap} on a {panel_ns} ns panel gave {other:?}"), + } + } + + /// A cap at the panel's own rate is released once per panel period, so its + /// clock cannot walk across the vblank interval. + #[test] + fn a_cap_at_the_panels_rate_takes_the_panels_period() { + // The reported fault: 1e9/120 is 8 333 333 ns against a measured + // 8 257 000 ns panel, so the phase sweeps and a fraction of frames wait a + // second vblank. Measuring the period in panel periods removes the walk. + assert_eq!(period_on(120, 8_257_000), 8_257_000); + assert_eq!(period_on(120, 8_333_333), 8_333_333); + assert_eq!(period_on(60, 8_257_000), 16_514_000); + assert_eq!(period_on(144, 6_944_444), 6_944_444); + // And no grid note leaves the cap on its own clock. + assert_eq!(period(120), 8_333_333); + } + + /// A cap that divides the refresh keeps its divisor exactly, because the + /// panel's own period is what the divisor is a multiple of. + #[test] + fn a_divisor_cap_is_exact_on_the_panels_period() { + let panel = 8_257_000u64; + assert_eq!(period_on(30, panel), 4 * panel); + assert_eq!(period_on(40, panel), 3 * panel); + assert_eq!(period_on(60, panel), 2 * panel); + assert_eq!(period_on(24, panel), 5 * panel); + } + + /// A cap the panel cannot divide keeps its own period: rounding it to a + /// multiple would move the rate to a divisor, and the display quantizes it + /// anyway. + #[test] + fn a_cap_the_panel_cannot_divide_keeps_its_own_period() { + let panel = 8_257_000u64; + for cap in [90u32, 100, 115] { + let own = 1_000_000_000 / u64::from(cap); + assert_eq!(period_on(cap, panel), own, "cap {cap}"); + } + // 120 on a 144 Hz panel is 1.2 periods: not a multiple. + assert_eq!(period_on(120, 6_944_444), 8_333_333); + } + + /// A cap inside the tolerance but not a divisor is served at the neighbour it + /// is close to, so it reads above or below its own nominal. Pinned because it + /// is the mapping's cost, and because a cap this close is not distinguishable + /// from the divisor the user meant to set. + #[test] + fn a_cap_just_off_a_divisor_takes_the_divisor() { + let panel = 8_260_500u64; + // 119 is 1.0173 periods: served 121.06 fps, +1.73 % over its nominal. + assert_eq!(period_on(119, panel), panel); + // 122 is 0.9923 periods: served 121.06 fps, 0.77 % under — a cap may + // round down onto the rate it can actually hold. + assert_eq!(period_on(122, panel), panel); + // Outside the tolerance the cap keeps its own clock, both sides. + assert_eq!(period_on(118, panel), 1_000_000_000 / 118); + assert_eq!(period_on(124, panel), 1_000_000_000 / 124); + } + + /// A cap above the panel keeps its own period. docs/10 is explicit that a cap + /// above the panel reads as more frames than the panel shows — the guest + /// renders at the cap and the display drops the rest — so shortening it to + /// one period would change a documented rate. + #[test] + fn a_cap_above_the_panel_keeps_its_own_period() { + let panel = 8_257_000u64; + assert_eq!(period_on(240, panel), 1_000_000_000 / 240); + assert_eq!(period_on(165, panel), 1_000_000_000 / 165); + } + #[test] fn no_cap_is_no_gate_and_a_cap_is_its_own_period() { assert_eq!(pacing(gndrm_uapi::wire::FPS_UNCAPPED), Pacing::Off);