Skip to content
Merged
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
24 changes: 15 additions & 9 deletions docs/10-fps-limit.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
100 changes: 69 additions & 31 deletions icd_shim/src/limits.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<u32> {
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<u32> {
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)
}
}

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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<u32> = (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::<u32>(), 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<u32> = (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::<u32>(), 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<u32> = (0..40).map(|_| l.generate_batch(2, &mut credit).unwrap()).collect();
assert_eq!(batches.iter().sum::<u32>(), 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));
}
}
11 changes: 9 additions & 2 deletions icd_shim/src/proxy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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(),
Expand Down Expand Up @@ -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<SpareCopy>,
pub worker: Option<std::thread::JoinHandle<()>>,
Expand Down
Loading