ktstr/test_support/eval/kernel.rs
1//! Kernel-image resolution and KVM preflight: /dev/kvm accessibility
2//! check, KernelUnavailable error, resolve_test_kernel discovery, and
3//! the cache reader-lock acquisition. Split out of eval/mod.rs to keep
4//! the module under the size ceiling.
5
6use super::*;
7
8/// Check that `/dev/kvm` is accessible for read+write.
9///
10/// Pre-flight check for VM-booting test runs: every ktstr test needs
11/// a KVM fd, and failing fast here yields an actionable error
12/// ("add your user to the kvm group") before the VM builder starts
13/// allocating memory / fetching kernels.
14///
15/// Errno classification on open failure (two branches):
16/// - Transient host pressure (`ENOMEM` / `EBUSY` / `EMFILE` / `ENFILE`
17/// / `EAGAIN`, mirroring the `TRANSIENT_HOST_ERRNOS` set used by
18/// [`crate::vmm::map_transient_to_contention`]): kernel memory
19/// allocator under load, the kvm misc-device's per-CPU init
20/// contended, the calling process exhausting its `RLIMIT_NOFILE`
21/// (`EMFILE`), the system fd table full (`ENFILE`), or a kernel
22/// subsystem signalling "try again" (`EAGAIN`). Routed through
23/// [`crate::vmm::host_topology::ResourceContention`] so the
24/// `#[ktstr_test]` macro routes the run to the retryable-contention
25/// verdict (nextest re-runs it) instead of an unclassified fault. The
26/// `EMFILE` / `ENFILE` arms specifically prevent fd-table pressure
27/// on `/dev/kvm` open from surfacing as a hard error with a
28/// misleading "kvm group" hint.
29/// - Everything else (`EACCES` / `ENOENT` / `EINVAL` / etc.):
30/// infrastructure misconfiguration or a real fault — the device is
31/// missing, the user lacks permission, or the kernel returned an
32/// unexpected errno. Surfaced as a hard error with the actionable
33/// "kvm group" hint; contention-classifying these would hide a
34/// misconfigured runner behind the retry budget.
35pub(crate) fn ensure_kvm() -> Result<()> {
36 match std::fs::OpenOptions::new()
37 .read(true)
38 .write(true)
39 .open("/dev/kvm")
40 {
41 Ok(_) => Ok(()),
42 Err(e) => {
43 let errno = e.raw_os_error();
44 if matches!(
45 errno,
46 Some(libc::ENOMEM)
47 | Some(libc::EBUSY)
48 | Some(libc::EMFILE)
49 | Some(libc::ENFILE)
50 | Some(libc::EAGAIN)
51 ) {
52 let snapshot = vmm::host_resource_snapshot();
53 let errno_label = match errno {
54 Some(libc::ENOMEM) => "ENOMEM",
55 Some(libc::EBUSY) => "EBUSY",
56 Some(libc::EMFILE) => "EMFILE",
57 Some(libc::ENFILE) => "ENFILE",
58 Some(libc::EAGAIN) => "EAGAIN",
59 _ => unreachable!(),
60 };
61 Err(anyhow::Error::new(
62 crate::vmm::host_topology::ResourceContention {
63 reason: format!(
64 "/dev/kvm open: transient host errno {errno_label}: \
65 host resources: {snapshot}\n \
66 hint: KVM device open failed with a host-resource \
67 errno; another peer may be holding the budget. \
68 nextest retries the cell; if the pressure has \
69 cleared, the retry passes.",
70 ),
71 },
72 ))
73 } else {
74 Err(anyhow::Error::new(e).context(
75 "/dev/kvm not accessible — KVM is required for ktstr_test. \
76 Check that KVM is enabled and your user is in the kvm group.",
77 ))
78 }
79 }
80 }
81}
82
83// ---------------------------------------------------------------------------
84// Scheduler resolution
85// ---------------------------------------------------------------------------
86
87// ---------------------------------------------------------------------------
88// Kernel resolution
89// ---------------------------------------------------------------------------
90
91/// Marker error for "the test harness can't find a kernel image to
92/// boot the VM against". Wraps the actionable diagnostic that
93/// [`resolve_test_kernel`] emits when neither
94/// `KTSTR_TEST_KERNEL` nor any standard cache / sysroot location
95/// produced a bootable image.
96///
97/// Distinct from a generic `anyhow::bail!` so the
98/// `#[ktstr_test]` macro's wrapper can downcast and emit a SKIP
99/// banner instead of panicking — the canonical "running under
100/// `cargo nextest run` instead of `cargo ktstr test`" symptom.
101/// Routes through [`crate::test_support::is_kernel_unavailable`]
102/// for the macro's predicate; downcast directly when adding new
103/// SKIP arms.
104#[derive(Debug)]
105pub struct KernelUnavailable {
106 pub diagnostic: String,
107}
108
109impl std::fmt::Display for KernelUnavailable {
110 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
111 write!(f, "{}", self.diagnostic)
112 }
113}
114
115impl std::error::Error for KernelUnavailable {}
116
117/// Find a kernel image for running tests.
118///
119/// Checks `KTSTR_TEST_KERNEL` env var first (direct image path),
120/// then delegates to [`crate::find_kernel()`] for cache and
121/// filesystem discovery. Returns a typed [`KernelUnavailable`] on
122/// failure so the `#[ktstr_test]` macro wrapper can map it onto a
123/// clean SKIP banner — generic `anyhow` errors propagate to the
124/// panic arm and surface as confusing test failures when the
125/// binary runs outside `cargo ktstr test`.
126pub fn resolve_test_kernel() -> Result<PathBuf> {
127 // Check environment variable first. A set-but-missing
128 // `KTSTR_TEST_KERNEL` is an OPERATOR mistake (they pointed at
129 // a path that doesn't exist), not a "harness not configured"
130 // situation — surface it as a regular anyhow error so the
131 // panic arm catches it. Skipping on a typo would silently mask
132 // the bad path.
133 if let Ok(path) = std::env::var(crate::KTSTR_TEST_KERNEL_ENV) {
134 let p = PathBuf::from(&path);
135 anyhow::ensure!(p.exists(), "KTSTR_TEST_KERNEL not found: {path}");
136 return Ok(p);
137 }
138
139 // Standard locations.
140 if let Some(p) = crate::find_kernel()? {
141 return Ok(p);
142 }
143
144 let image_name = if cfg!(target_arch = "aarch64") {
145 "Image"
146 } else {
147 "bzImage"
148 };
149 Err(anyhow::Error::new(KernelUnavailable {
150 diagnostic: format!(
151 "no kernel found — the test harness was likely invoked \
152 outside `cargo ktstr test` (which builds and injects a \
153 kernel automatically).\n \
154 hint: run `cargo ktstr test --kernel <path-or-version>` \
155 to drive this test, or set KTSTR_TEST_KERNEL=/path/to/{image_name} \
156 to point at a pre-built bootable image directly.\n \
157 hint: {kernel_hint}",
158 kernel_hint = crate::KTSTR_KERNEL_HINT,
159 ),
160 }))
161}
162
163/// Detection seam for the [`crate::flock`] helper's timeout-bail
164/// message shape.
165///
166/// Returns `true` iff `rendered` contains BOTH `"timed out after"` and
167/// `"flock LOCK_"`. The two substrings together are the helper's
168/// internal contract for a flock-acquisition timeout — see
169/// `flock/acquire.rs`'s bail format
170/// `"flock {LOCK_EX|LOCK_SH} on {context} timed out after ..."`.
171///
172/// Pinned via the unit test
173/// `flock_timeout_substring_classification_pins_seam` so a
174/// rewording of the bail message that drops either substring is
175/// caught at test time before
176/// [`acquire_test_kernel_lock_if_cached`] starts misclassifying
177/// timeouts as plain anyhow errors.
178pub(crate) fn is_flock_timeout_message(rendered: &str) -> bool {
179 rendered.contains("timed out after") && rendered.contains("flock LOCK_")
180}
181
182/// If `kernel_path` resolves to an image inside a cache entry, hold a
183/// `LOCK_SH` on that entry's coordination lockfile for the duration of
184/// the returned guard. Prevents a concurrent
185/// `cargo ktstr kernel build` from swapping the entry's directory
186/// (see [`crate::cache::CacheDir::store`]) under the VM while the test
187/// reads from it.
188///
189/// Returns `Ok(None)` when `kernel_path` is not shaped like a cache
190/// entry — explicit `KTSTR_TEST_KERNEL=/path/to/bzImage`,
191/// `/lib/modules/.../vmlinuz`, `/boot/vmlinuz-*`, or any path whose
192/// two-level parent does not match the resolved cache root. Such
193/// paths do not need coordination because the build pipeline never
194/// touches them.
195///
196/// Detection: the image is expected at `{root}/{key}/{image_name}`.
197/// Walk `kernel_path` up by two components (image_name, key) to
198/// produce a candidate root and canonicalize both sides before
199/// comparing — symlinks, redundant `./` segments, and `..` traversals
200/// must all reduce to the same inode path or the entry is treated as
201/// non-cache.
202pub(crate) fn acquire_test_kernel_lock_if_cached(
203 kernel_path: &Path,
204) -> Result<Option<crate::cache::SharedLockGuard>> {
205 // Peel the image filename. Fail → not a cache entry.
206 let Some(entry_dir) = kernel_path.parent() else {
207 return Ok(None);
208 };
209 // Peel the entry directory name (this is the candidate cache
210 // key). Fail → not a cache entry.
211 let Some(key_os) = entry_dir.file_name() else {
212 return Ok(None);
213 };
214 let Some(cache_key) = key_os.to_str() else {
215 return Ok(None);
216 };
217 // The directory above the entry is the candidate cache root.
218 let Some(candidate_root) = entry_dir.parent() else {
219 return Ok(None);
220 };
221
222 // Canonicalize both the candidate root and the resolved cache
223 // root so symlinks / `.` / `..` reduce to the same inode path
224 // before comparing. A non-cache path (e.g. /lib/modules/...)
225 // simply canonicalizes to itself and will not match.
226 let candidate_root_canon = match candidate_root.canonicalize() {
227 Ok(p) => p,
228 Err(_) => return Ok(None),
229 };
230 let resolved_root = match crate::cache::CacheDir::default_root() {
231 Ok(p) => p,
232 // Cache root unresolvable (no HOME and no XDG_CACHE_HOME, or
233 // non-UTF-8 KTSTR_CACHE_DIR): no cache exists, so `kernel_path`
234 // cannot be an entry. (A cache root that resolves but is absent
235 // on disk is handled by the canonicalize() arm below.)
236 Err(_) => return Ok(None),
237 };
238 let resolved_root_canon = match resolved_root.canonicalize() {
239 Ok(p) => p,
240 // Cache root resolves but does not exist on disk yet (fresh
241 // developer checkout). `kernel_path` is not inside a cache
242 // entry, so no lock needed.
243 Err(_) => return Ok(None),
244 };
245
246 if candidate_root_canon != resolved_root_canon {
247 return Ok(None);
248 }
249
250 // The path is shaped as a cache entry under the resolved root.
251 // Acquire the reader lock. The flock helper polls on
252 // `EAGAIN`/`EWOULDBLOCK` until either the lock is granted or its
253 // wall-clock timeout elapses. A timeout means a peer (concurrent
254 // `cargo ktstr kernel build` or another reader-blocking writer)
255 // is holding the lock — that is host-resource contention, not a
256 // kernel fault, so route it through
257 // [`crate::vmm::host_topology::ResourceContention`] so the
258 // `#[ktstr_test]` macro fires the retryable-contention verdict
259 // (nextest re-runs after the holder finishes). Non-timeout failures
260 // (parent-directory creation failure, an unexpected `try_flock`
261 // errno other than `EAGAIN`/`EWOULDBLOCK`) propagate as hard
262 // errors — they indicate filesystem corruption or a programming
263 // fault a contention verdict would obscure.
264 //
265 // Detection seam: the flock helper's bail format starts with
266 // `flock LOCK_SH on` (or `LOCK_EX`) and contains `timed out
267 // after`. Both substrings are pinned by the helper's internal
268 // contract and embedded in the rendered message together; the
269 // message also contains the lockfile path and the holder PID
270 // list parsed from `/proc/locks`, which we forward verbatim into
271 // the `ResourceContention` reason so the operator sees the
272 // identical triage information either way.
273 let cache = crate::cache::CacheDir::with_root(resolved_root_canon);
274 match cache.acquire_shared_lock(cache_key) {
275 Ok(guard) => Ok(Some(guard)),
276 Err(e) => {
277 let rendered = format!("{e:#}");
278 if is_flock_timeout_message(&rendered) {
279 let snapshot = crate::vmm::host_resource_snapshot();
280 Err(anyhow::Error::new(
281 crate::vmm::host_topology::ResourceContention {
282 reason: format!(
283 "test kernel cache lock: {rendered}. host resources: \
284 {snapshot}\n \
285 hint: a concurrent `cargo ktstr kernel build` or \
286 another lockholder is preventing the test VM from \
287 reading the cached kernel image. nextest retries \
288 the cell after the holder finishes. If the failure \
289 persists, wait for the holder PIDs above to \
290 finish, or kill them, then retry.",
291 ),
292 },
293 ))
294 } else {
295 Err(e)
296 }
297 }
298 }
299}