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}