From 8946b3080b8dcbf7b4eb72d3538596b0ae0187fb Mon Sep 17 00:00:00 2001 From: Joshua Tam <297250+joshuatam@users.noreply.github.com> Date: Fri, 20 Nov 2026 01:10:09 +0800 Subject: [PATCH] icd_shim: spend generation's leftover as a rate, not a ratio of whole frames MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The eight rows of `limits()` already match docs/10's table, so the ceiling was right and the divergence was one step later: `generate_per_source` floored `generate / acquire` to whole frames per source, which turned every ceiling below one frame per source into zero. At 60 Hz, cap 40, ×2 the panel leaves 20 generated against 40 source frames -- one every other source frame -- and the flooring produced none. So frame generation did nothing at any cap above half the refresh while the panel still had room, which is not what the table's total column promises. Measured on Nova at 120 Hz, cap 70, ×2: `cap=70 acquire=70 generate=70`, and the leftover `120 - 70 = 50` was reachable in principle and unreachable in fact. `generate_batch(m, &mut credit)` carries the remainder across source frames in units of one source frame, so a rate that is not a whole frame per source is still spent: cap 70 on 120 Hz yields 50 generated over 70 source frames, cap 40 on 60 Hz yields 0,1,0,1,..., and the multiplier's `m - 1` remains the per-frame bound. The credit lives on `GnSwapchain`, one per swapchain, since it is the swapchain's stream being spaced. Tests are rewritten rather than deleted: the one that pinned the flooring as intended behaviour now asserts the leftover is spent (`20` over `40`, `0` only above the panel), and two new ones pin the 0,1,0,1 sequence and the cap-70 case. docs/10's paragraph about the leftover is corrected with it. 130 tests pass; clippy clean with -D warnings. --- docs/10-fps-limit.md | 24 ++++++---- icd_shim/src/limits.rs | 100 ++++++++++++++++++++++++++++------------- icd_shim/src/proxy.rs | 11 ++++- 3 files changed, 93 insertions(+), 42 deletions(-) diff --git a/docs/10-fps-limit.md b/docs/10-fps-limit.md index 25701a6..2e15c57 100644 --- a/docs/10-fps-limit.md +++ b/docs/10-fps-limit.md @@ -128,10 +128,16 @@ divisor cap reads its target exactly. **Synced, the source frames are part of the panel's budget.** The generated ceiling on that row is `refresh − acquire`, not `refresh`: a 60 Hz panel can show 60 frames whichever way they were made, so a cap 40 session leaves 20 for the - generator and no more. The consequence is deliberate and it is not a rounding - detail — at cap 40, ×2, that is 20 generated against 40 source frames, half a - frame each, which floors to none, so frame generation does nothing at any cap - above half the refresh. Lower the cap or the multiplier to make room. + generator and no more. + + That leftover is a *rate*, not a ratio of whole frames, so it is spent rather + than rounded away. At cap 40, ×2, on 60 Hz the generator gets 20 against 40 + source frames — one generated frame every other source frame — and the session + produces 60. The earlier rule floored the ratio to whole frames per source, + which turned those 20 into 0 and made frame generation do nothing at any cap + above half the refresh while the panel still had room. Carrying the remainder + (`Limits::generate_batch`'s `credit`, one per swapchain) is what keeps the + output on the rate in the table; a whole-number-per-source rule cannot. `hold` is when an acquired image may be drawn into again. It follows the **served** mode — the same one `on_buffer_release` keys on — and on this route @@ -221,11 +227,11 @@ divisor cap reads its target exactly. HUD. `generate_per_s` is consumed as a bound on how many frames one source frame may - yield, not as a fourth limiter: `Limits::generate_per_source(m)` caps the batch - the generator plans (`proxy.rs`, `lsfg_generate`), and the batch's frames are - placed on the latch grid (`docs/17`). The rate in the table is therefore the - generator's ceiling; what actually lands is that ceiling, floored to whole frames - per source. + yield, not as a fourth limiter: `Limits::generate_batch(m, &mut credit)` caps the + batch the generator plans (`proxy.rs`, `lsfg_generate`), and the batch's frames + are placed on the latch grid (`docs/17`). The rate in the table is therefore the + generator's ceiling, and the credit is what makes the average land on it when + 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. diff --git a/icd_shim/src/limits.rs b/icd_shim/src/limits.rs index e86e99c..6061822 100644 --- a/icd_shim/src/limits.rs +++ b/icd_shim/src/limits.rs @@ -33,18 +33,34 @@ pub(crate) struct Limits { } impl Limits { - /// How many frames the generator may add per source frame, `None` when it - /// may not add any. + /// How many frames the generator may add after this source frame, `None` + /// when it may not add any. /// - /// The ceiling is a rate, so a panel that cannot show `acquire × multiplier` - /// frames leaves the generator fewer per source frame; it never leaves it - /// more. `multiplier` is the configured one, and the return value never - /// exceeds `multiplier - 1`. - pub(crate) fn generate_per_source(&self, multiplier: u32) -> Option { - let generate = self.generate_per_s?; - let acquire = self.acquire_per_s?; - let asked = multiplier.saturating_sub(1); - Some(asked.min(generate / acquire.max(1))) + /// The ceiling is a rate, not a ratio, so the batch is not required to be a + /// whole number of frames per source frame: a cap 70 session on a 120 Hz + /// panel leaves 50 generated against 70 source frames -- five frames every + /// seven. `credit` carries the remainder between calls, which is what makes + /// the generator's output land on the rate in the table instead of on the + /// floor of it. Flooring the ratio instead switched generation off entirely + /// at any cap above half the refresh, where the table still promises the + /// panel's leftover. + /// + /// The return value never exceeds `multiplier - 1`: asking for more than the + /// configured multiplier is not what a rate bound means. + pub(crate) fn generate_batch(&self, multiplier: u32, credit: &mut u64) -> Option { + let generate = self.generate_per_s? as u64; + let acquire = self.acquire_per_s? as u64; + if acquire == 0 { + return Some(0); + } + *credit += generate; + let mut batch = *credit / acquire; + *credit %= acquire; + let asked = u64::from(multiplier.saturating_sub(1)); + if batch > asked { + batch = asked; + } + Some(batch as u32) } } @@ -81,11 +97,11 @@ pub(crate) fn limits( // 80 commits a second, of which the compositor dropped 20 — the // budget is the panel's, so it belongs in the same subtraction. // - // The consequence is deliberate and worth knowing: at 60 Hz, cap 40, - // ×2, this leaves 20 generated against 40 source frames, i.e. 0.5 - // per source frame, which `generate_per_source` floors to 0. Frame - // generation therefore does nothing at any cap above half the - // refresh, where before it over-subscribed the panel instead. + // That leftover is a rate, not a ratio of whole frames: at 60 Hz, + // cap 40, ×2 it is 20 generated against 40 source frames, one every + // other source frame. `generate_batch` carries the remainder so the + // average lands on it; flooring the ratio instead zeroed generation + // at any cap above half the refresh, where the panel still had room. // // Unsynced, only the cap does, and the compositor drops the // remainder by design. @@ -218,33 +234,55 @@ mod tests { } #[test] - fn generation_per_source_narrows_when_the_panel_is_the_ceiling() { + fn the_generator_spends_a_rate_that_is_not_a_whole_frame_per_source() { // 40 acquires, 60 panel, ×4 asked: the panel leaves 20 generated in - // total, i.e. none per source frame at this rate. + // total -- one every other source frame, not none. let l = limits(true, Some(40), Some(4), 60); assert_eq!(l.generate_per_s, Some(20)); - assert_eq!(l.generate_per_source(4), Some(0)); - // Unsynced the same numbers leave the ask intact. - let l = limits(false, Some(40), Some(4), 60); - assert_eq!(l.generate_per_source(4), Some(3)); + let mut credit = 0u64; + let batches: Vec = (0..8).map(|_| l.generate_batch(4, &mut credit).unwrap()).collect(); + assert_eq!(batches, vec![0, 1, 0, 1, 0, 1, 0, 1]); + // 20 generated over 40 source frames is exactly the panel's leftover. + assert_eq!(batches.iter().sum::(), 4); + + // and a rate that is more than one per source keeps the multiplier's cap + let l = limits(true, Some(30), Some(2), 60); + let mut credit = 0u64; + assert!((0..20).all(|_| l.generate_batch(2, &mut credit).unwrap() <= 1)); + } + + #[test] + fn a_cap_above_half_the_panel_still_gets_its_leftover() { + // 70 on a 120 Hz panel: the table's total is 70 + 50, not 70 + 0. + let l = limits(true, Some(70), Some(2), 120); + assert_eq!(l.acquire_per_s, Some(70)); + assert_eq!(l.generate_per_s, Some(50)); + let mut credit = 0u64; + let batches: Vec = (0..70).map(|_| l.generate_batch(2, &mut credit).unwrap()).collect(); + // 50 frames over 70 source frames, ~5 every 7 + assert_eq!(batches.iter().sum::(), 50); + assert!(batches.iter().all(|&b| b <= 1)); } - /// The consequence of `refresh - acquire`, pinned so it cannot drift into a - /// claim about the feature working: at 60 Hz, cap 40, ×2, the panel leaves 20 - /// generated against 40 source frames, and half a frame per source floors to - /// none. A user with LSFG on at that cap gets no generated frames, which is - /// the price of not over-subscribing the panel. + /// `refresh - acquire` is spent, not rounded away: at 60 Hz, cap 40, ×2 the + /// panel leaves 20 generated against 40 source frames -- one every other + /// source frame. #[test] - fn a_cap_above_half_the_panel_leaves_no_room_to_generate() { + fn a_cap_above_half_the_panel_spends_its_leftover() { let l = limits(true, Some(40), Some(2), 60); assert_eq!(l.generate_per_s, Some(20)); - assert_eq!(l.generate_per_source(2), Some(0)); - // One step lower and generation survives: cap 30 at ×2 on 60 Hz. + let mut credit = 0u64; + let batches: Vec = (0..40).map(|_| l.generate_batch(2, &mut credit).unwrap()).collect(); + assert_eq!(batches.iter().sum::(), 20); + // A cap at or below half the panel is one per source. let l = limits(true, Some(30), Some(2), 60); assert_eq!(l.generate_per_s, Some(30)); - assert_eq!(l.generate_per_source(2), Some(1)); + let mut credit = 0u64; + assert_eq!(l.generate_batch(2, &mut credit), Some(1)); // A cap above the panel cannot underflow: nothing is left to generate. let l = limits(true, Some(120), Some(2), 60); assert_eq!(l.generate_per_s, Some(0)); + let mut credit = 0u64; + assert_eq!(l.generate_batch(2, &mut credit), Some(0)); } } diff --git a/icd_shim/src/proxy.rs b/icd_shim/src/proxy.rs index 039c312..4f4fffa 100644 --- a/icd_shim/src/proxy.rs +++ b/icd_shim/src/proxy.rs @@ -1589,9 +1589,10 @@ unsafe fn lsfg_generate(sc: *mut GnSwapchain, src_idx: i32) -> bool { // frame and only generation and blit are gated on the plan. // The engine plans by the multiplier; the session's generation limit is a // rate, so a panel that cannot show `acquire × multiplier` frames leaves - // fewer per source frame ([`crate::limits::Limits::generate_per_source`]). + // fewer per source frame ([`crate::limits::Limits::generate_batch`]), carried + // across frames so a rate that is not a whole frame per source is still spent. let planned = unsafe { (*session).plan(capacity) }; - let allowed = session_limits(sc).generate_per_source(multiplier); + let allowed = session_limits(sc).generate_batch(multiplier, unsafe { &mut (*sc).gen_credit }); let planned = match allowed { Some(per) => planned.min(per), None => 0, @@ -2681,6 +2682,7 @@ unsafe extern "C" fn gn_vkCreateSwapchainKHR( slots: Vec::new(), guest_slots: 0, spare_slots: 0, + gen_credit: 0, spare: None, gen_no_grow: false, release: crate::vsync_gate::Schedule::default(), @@ -8118,6 +8120,11 @@ pub struct GnSwapchain { /// (`crate::image_count::hidden_slot_count`); 0 when there are none. The /// ring itself may be larger when generation's destinations need more. pub spare_slots: u32, + /// Generation's fractional frame credit, in units of one source frame + /// (`limits::Limits::generate_batch`). Carrying the remainder is what lets + /// the generator spend a rate that is not a whole number of frames per + /// source frame. + pub gen_credit: u64, /// Made at the first present of a swapchain with hidden slots. pub spare: Option, pub worker: Option>,