Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

test: shared, checked real-time scheduling for verification input threads

Richie McIlroyee24a4e71090
diff --git a/crates/verify-stimulus/src/main.rs b/crates/verify-stimulus/src/main.rs
index 7888a0753..5e783bca6 100644
--- a/crates/verify-stimulus/src/main.rs
+++ b/crates/verify-stimulus/src/main.rs
@@ -31,6 +31,7 @@ mod app {
use cap_verify::{
audio_code::{self, AudioSource, MarkerPlacement},
+ sched,
stimulus::{StimulusEvent, StimulusSpec, host_add_secs, host_now, host_secs},
video_code::{self, FrameMarker, PixelOrder, StreamKind},
};
@@ -115,7 +116,7 @@ mod app {
created: None,
idle_tick: 0,
last_idle: None,
- thread: unsafe { mach_thread_self() },
+ thread: sched::current_thread(),
wake: (String::new(), None),
presented_at: None,
};
@@ -254,92 +255,17 @@ mod app {
presented_at: Option<(u32, Instant)>,
}
- #[repr(C)]
- struct ThreadExtendedInfo {
- user_time: u64,
- system_time: u64,
- cpu_usage: i32,
- policy: i32,
- run_state: i32,
- flags: i32,
- sleep_time: i32,
- cur_pri: i32,
- priority: i32,
- max_priority: i32,
- name: [u8; 64],
- }
-
- unsafe extern "C" {
- fn mach_thread_self() -> u32;
- fn thread_info(thread: u32, flavor: i32, info: *mut i32, count: *mut u32) -> i32;
- fn thread_policy_set(thread: u32, flavor: u32, policy: *const i32, count: u32) -> i32;
- fn pthread_set_qos_class_self_np(qos: u32, relative_priority: i32) -> i32;
- }
-
/// Hosted runners start jobs at utility QoS (scheduler base priority 20)
/// and children inherit it, so under recording load the stimulus loses
/// the CPU to the capture and encoder services for 50-190 ms at a time.
/// The pictures a user records come from foreground apps; the stimulus
/// asks for the same treatment (user-interactive QoS) and a time
- /// constraint matching its frame period, so it keeps its schedule.
- /// Returns the kernel status of each request (0 = applied).
+ /// constraint matching its frame period, so it keeps its schedule
+ /// (`cap_verify::sched`, shared with the synthetic camera and
+ /// microphone). Returns the kernel status of each request (0 = applied).
fn raise_priority(fps: f64) -> (i32, i32) {
- const QOS_CLASS_USER_INTERACTIVE: u32 = 0x21;
- const THREAD_TIME_CONSTRAINT_POLICY: u32 = 2;
- #[repr(C)]
- struct TimeConstraint {
- period: u32,
- computation: u32,
- constraint: u32,
- preemptible: i32,
- }
- let qos = unsafe { pthread_set_qos_class_self_np(QOS_CLASS_USER_INTERACTIVE, 0) };
- let info = cidre::mach::TimeBaseInfo::new();
- let ticks =
- |secs: f64| (secs * 1e9 * f64::from(info.denom) / f64::from(info.numer)).round() as u32;
- let period = 1.0 / fps;
- let policy = TimeConstraint {
- period: ticks(period),
- computation: ticks(0.010),
- constraint: ticks(period),
- preemptible: 1,
- };
- let realtime = unsafe {
- thread_policy_set(
- mach_thread_self(),
- THREAD_TIME_CONSTRAINT_POLICY,
- (&raw const policy).cast(),
- (std::mem::size_of::<TimeConstraint>() / 4) as u32,
- )
- };
- (qos, realtime)
- }
-
- fn sched_info(thread: u32) -> Option<ThreadExtendedInfo> {
- const THREAD_EXTENDED_INFO: i32 = 5;
- let mut info = ThreadExtendedInfo {
- user_time: 0,
- system_time: 0,
- cpu_usage: 0,
- policy: 0,
- run_state: 0,
- flags: 0,
- sleep_time: 0,
- cur_pri: 0,
- priority: 0,
- max_priority: 0,
- name: [0; 64],
- };
- let mut count = (std::mem::size_of::<ThreadExtendedInfo>() / 4) as u32;
- let status = unsafe {
- thread_info(
- thread,
- THREAD_EXTENDED_INFO,
- (&raw mut info).cast(),
- &mut count,
- )
- };
- (status == 0).then_some(info)
+ let realtime = sched::request_realtime(1.0 / fps, 0.010);
+ (realtime.qos_status, realtime.policy_status)
}
impl App {
@@ -598,7 +524,7 @@ mod app {
fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
let now = Instant::now();
if let Some((index, at)) = self.presented_at.take()
- && let Some(info) = sched_info(self.thread)
+ && let Some(info) = sched::thread_state(self.thread)
{
self.log.write(&StimulusEvent::Sched {
index,
@@ -606,8 +532,8 @@ mod app {
wake_late_us: self.wake.1,
post_present_us: now.saturating_duration_since(at).as_micros() as i64,
cur_pri: info.cur_pri,
- base_pri: info.priority,
- cpu_us: (info.user_time + info.system_time) / 1000,
+ base_pri: info.base_pri,
+ cpu_us: info.cpu_us,
});
}
if let Some(due) = self.idle_due(now) {
diff --git a/crates/verify/src/lib.rs b/crates/verify/src/lib.rs
index cdaf89ddf..5eb582258 100644
--- a/crates/verify/src/lib.rs
+++ b/crates/verify/src/lib.rs
@@ -13,5 +13,7 @@ pub mod model;
pub mod oracle;
pub mod pipeline;
pub mod report;
+#[cfg(target_os = "macos")]
+pub mod sched;
pub mod stimulus;
pub mod video_code;
diff --git a/crates/verify/src/sched.rs b/crates/verify/src/sched.rs
new file mode 100644
index 000000000..df8960fd9
--- /dev/null
+++ b/crates/verify/src/sched.rs
@@ -0,0 +1,250 @@
+//! Real-time scheduling for the verification suite's input sources.
+//!
+//! Hosted runners start jobs at utility QoS (scheduler base priority 20) and
+//! every thread inherits it. A blocking sleep at that tier may be coalesced
+//! by up to `min(8 * requested, 150 ms)` (XNU timer coalescing with idle
+//! amplification), and a successful user-interactive QoS request does not
+//! lift the task's clamp: synthetic sources at QoS 33 still ran at priority
+//! 20 and woke about 151 ms late (run 38766191045). The inputs a user
+//! records come from a foreground app and device callbacks the system runs
+//! in real time, so every input thread asks for a time constraint matching
+//! its period, and the result is read back from the kernel instead of
+//! trusting the request's status.
+
+use serde::{Deserialize, Serialize};
+
+/// A time-constraint policy in milliseconds.
+#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Constraint {
+ pub period_ms: f64,
+ pub computation_ms: f64,
+ pub constraint_ms: f64,
+ pub preemptible: bool,
+}
+
+/// A thread's effective scheduling state (`THREAD_EXTENDED_INFO`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ThreadState {
+ pub policy: i32,
+ pub base_pri: i32,
+ pub cur_pri: i32,
+ pub max_pri: i32,
+ pub cpu_us: u64,
+}
+
+/// Lowest scheduler priority of the real-time band (`BASEPRI_RTQUEUES`).
+pub const REALTIME_PRIORITY: i32 = 97;
+
+/// The outcome of [`request_realtime`]: every kernel status, the policy the
+/// kernel reports back and the thread's effective state right after.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct Realtime {
+ pub requested: Constraint,
+ pub qos_status: i32,
+ pub policy_status: i32,
+ pub readback_status: i32,
+ /// The kernel answered the readback with the default policy: the thread
+ /// is not time-constrained.
+ pub readback_default: bool,
+ pub granted: Option<Constraint>,
+ pub state: Option<ThreadState>,
+}
+
+impl Realtime {
+ /// `Ok` when the kernel applied the time constraint (the computation
+ /// budget may be raised by the kernel, never lowered) and the thread
+ /// runs in the real-time band.
+ pub fn obtained(&self) -> Result<(), String> {
+ if self.policy_status != 0 {
+ return Err(format!(
+ "thread_policy_set(TIME_CONSTRAINT) returned {}",
+ self.policy_status
+ ));
+ }
+ if self.readback_status != 0 || self.readback_default {
+ return Err(format!(
+ "thread_policy_get(TIME_CONSTRAINT) returned {} (default policy: {})",
+ self.readback_status, self.readback_default
+ ));
+ }
+ let Some(granted) = self.granted else {
+ return Err("no time constraint read back".into());
+ };
+ let tick = 0.001;
+ if (granted.period_ms - self.requested.period_ms).abs() > tick
+ || (granted.constraint_ms - self.requested.constraint_ms).abs() > tick
+ || granted.computation_ms + tick < self.requested.computation_ms
+ || granted.computation_ms > granted.constraint_ms + tick
+ || granted.preemptible != self.requested.preemptible
+ {
+ return Err(format!(
+ "kernel granted {granted:?} for requested {:?}",
+ self.requested
+ ));
+ }
+ state_is_realtime(self.state)
+ }
+}
+
+/// `Ok` when the thread state is in the real-time band.
+pub fn state_is_realtime(state: Option<ThreadState>) -> Result<(), String> {
+ match state {
+ Some(state) if state.base_pri >= REALTIME_PRIORITY => Ok(()),
+ Some(state) => Err(format!(
+ "thread base priority {} is below the real-time band ({REALTIME_PRIORITY})",
+ state.base_pri
+ )),
+ None => Err("thread_info(THREAD_EXTENDED_INFO) failed".into()),
+ }
+}
+
+#[repr(C)]
+struct ThreadExtendedInfo {
+ user_time: u64,
+ system_time: u64,
+ cpu_usage: i32,
+ policy: i32,
+ run_state: i32,
+ flags: i32,
+ sleep_time: i32,
+ cur_pri: i32,
+ priority: i32,
+ max_priority: i32,
+ name: [u8; 64],
+}
+
+#[repr(C)]
+#[derive(Default)]
+struct TimeConstraintPolicy {
+ period: u32,
+ computation: u32,
+ constraint: u32,
+ preemptible: i32,
+}
+
+const QOS_CLASS_USER_INTERACTIVE: u32 = 0x21;
+const THREAD_TIME_CONSTRAINT_POLICY: u32 = 2;
+const THREAD_EXTENDED_INFO: i32 = 5;
+
+unsafe extern "C" {
+ fn pthread_self() -> usize;
+ fn pthread_mach_thread_np(thread: usize) -> u32;
+ fn thread_info(thread: u32, flavor: i32, info: *mut i32, count: *mut u32) -> i32;
+ fn thread_policy_set(thread: u32, flavor: u32, policy: *const i32, count: u32) -> i32;
+ fn thread_policy_get(
+ thread: u32,
+ flavor: u32,
+ policy: *mut i32,
+ count: *mut u32,
+ get_default: *mut i32,
+ ) -> i32;
+ fn pthread_set_qos_class_self_np(qos: u32, relative_priority: i32) -> i32;
+ fn mach_wait_until(deadline: u64) -> i32;
+}
+
+/// The calling thread's Mach port, owned by pthread for the thread's
+/// lifetime (unlike `mach_thread_self`, it adds no port reference).
+pub fn current_thread() -> u32 {
+ unsafe { pthread_mach_thread_np(pthread_self()) }
+}
+
+fn ticks_per_ms() -> f64 {
+ let info = cidre::mach::TimeBaseInfo::new();
+ 1e6 * f64::from(info.denom) / f64::from(info.numer)
+}
+
+/// Asks for user-interactive QoS and a time constraint of `period`
+/// (constraint = period, preemptible) with a bounded `computation` budget,
+/// then reads both back.
+pub fn request_realtime(period_secs: f64, computation_secs: f64) -> Realtime {
+ let per_ms = ticks_per_ms();
+ let ticks = |secs: f64| (secs * 1e3 * per_ms).round() as u32;
+ let requested = Constraint {
+ period_ms: period_secs * 1e3,
+ computation_ms: computation_secs * 1e3,
+ constraint_ms: period_secs * 1e3,
+ preemptible: true,
+ };
+ let qos_status = unsafe { pthread_set_qos_class_self_np(QOS_CLASS_USER_INTERACTIVE, 0) };
+ let thread = current_thread();
+ let policy = TimeConstraintPolicy {
+ period: ticks(period_secs),
+ computation: ticks(computation_secs),
+ constraint: ticks(period_secs),
+ preemptible: 1,
+ };
+ let count = (std::mem::size_of::<TimeConstraintPolicy>() / 4) as u32;
+ let policy_status = unsafe {
+ thread_policy_set(
+ thread,
+ THREAD_TIME_CONSTRAINT_POLICY,
+ (&raw const policy).cast(),
+ count,
+ )
+ };
+ let mut readback = TimeConstraintPolicy::default();
+ let mut readback_count = count;
+ let mut get_default = 0i32;
+ let readback_status = unsafe {
+ thread_policy_get(
+ thread,
+ THREAD_TIME_CONSTRAINT_POLICY,
+ (&raw mut readback).cast(),
+ &mut readback_count,
+ &mut get_default,
+ )
+ };
+ let ms = |ticks: u32| f64::from(ticks) / per_ms;
+ Realtime {
+ requested,
+ qos_status,
+ policy_status,
+ readback_status,
+ readback_default: get_default != 0,
+ granted: (readback_status == 0).then(|| Constraint {
+ period_ms: ms(readback.period),
+ computation_ms: ms(readback.computation),
+ constraint_ms: ms(readback.constraint),
+ preemptible: readback.preemptible != 0,
+ }),
+ state: thread_state(thread),
+ }
+}
+
+/// The effective scheduling state of `thread`.
+pub fn thread_state(thread: u32) -> Option<ThreadState> {
+ let mut info = ThreadExtendedInfo {
+ user_time: 0,
+ system_time: 0,
+ cpu_usage: 0,
+ policy: 0,
+ run_state: 0,
+ flags: 0,
+ sleep_time: 0,
+ cur_pri: 0,
+ priority: 0,
+ max_priority: 0,
+ name: [0; 64],
+ };
+ let mut count = (std::mem::size_of::<ThreadExtendedInfo>() / 4) as u32;
+ let status = unsafe {
+ thread_info(
+ thread,
+ THREAD_EXTENDED_INFO,
+ (&raw mut info).cast(),
+ &mut count,
+ )
+ };
+ (status == 0).then_some(ThreadState {
+ policy: info.policy,
+ base_pri: info.priority,
+ cur_pri: info.cur_pri,
+ max_pri: info.max_priority,
+ cpu_us: (info.user_time + info.system_time) / 1000,
+ })
+}
+
+/// Blocks until the host clock reaches `deadline` (Mach absolute ticks).
+pub fn wait_until(deadline: u64) {
+ unsafe { mach_wait_until(deadline) };
+}