ktstr/distro/
acquire.rs

1//! Orchestration for prebuilt distro / local-package kernels.
2//!
3//! Ties the three foundation pieces together into a cache entry the
4//! rest of ktstr boots like any built kernel:
5//!
6//! 1. [`repo::resolve_distro_kernel`](crate::distro::repo) — spec →
7//!    concrete package URLs + sha256 (distro path only).
8//! 2. [`crate::fetch::download_verified_file`] — stream each package
9//!    (and its debuginfo) with the shared watchdog + progress + retry.
10//! 3. [`extract`](crate::distro::extract) — unpack the packages and
11//!    locate image / modules / config / vmlinux.
12//!
13//! then a config gate (boot-critical options must be `=y`/`=m`, other
14//! ktstr-feature options warn), a boot-module selection (each modular
15//! virtio driver is `module_closure`'d and embedded in the entry), and
16//! an atomic install into the kernel cache.
17//!
18//! ## Config gate & boot modules — why these options
19//!
20//! The ktstr guest boots off the initramfs (no root disk — see
21//! `src/vmm/setup/mod.rs` `rdinit=/init`), so the only devices EVERY
22//! boot touches are the virtio-console control ports
23//! (the named `ktstr-bulk` sys_rdy channel and `/dev/hvc0`), presented over
24//! the virtio-MMIO transport on both arches
25//! (`src/vmm/setup/mod.rs` console `virtio_mmio.device=`,
26//! `src/vmm/aarch64/fdt.rs` `virtio,mmio` nodes) and loaded before any
27//! virtio access by guest init
28//! (`src/vmm/rust_init/init.rs` "load modules BEFORE any virtio device
29//! is touched"). So `BOOT_CRITICAL` — virtio core, the MMIO
30//! transport, and the console driver — is what a kernel cannot boot in
31//! ktstr without, in ANY form; absent (neither `=y` nor `=m`) is a
32//! hard error. `FEATURE_MODULES` (blk / net / pci / btrfs) back
33//! optional devices attached only by tests that request a disk or NIC
34//! (`self.disk` / `self.networks` gating in `setup/mod.rs`), so a
35//! missing one only warns. `virtio_pci` is x86-only (aarch64 has no
36//! PCI bus).
37
38use std::collections::{HashMap, HashSet};
39use std::fs;
40use std::path::{Path, PathBuf};
41
42use anyhow::{Context, Result, anyhow, bail};
43use sha2::{Digest, Sha256};
44
45use crate::cache::{CacheArtifacts, CacheDir, KernelMetadata, KernelSource};
46use crate::distro::extract::{
47    ExtractedKernel, ensure_arch_matches_host, extract_kernel_packages, extract_vmlinux,
48    module_closure, package_arch,
49};
50use crate::distro::repo::{DistroKind, PackageRef, ResolvedDistroKernel, resolve_distro_kernel};
51
52/// Kernel config options whose driver the ktstr VMM needs present in
53/// SOME form for EVERY guest boot, mapped to the module ktstr must load
54/// when the option is `=m`. See the module docs for the code-verified
55/// justification (virtio-console control port over the MMIO transport).
56const BOOT_CRITICAL: &[(&str, &str)] = &[
57    ("CONFIG_VIRTIO", "virtio"),
58    ("CONFIG_VIRTIO_MMIO", "virtio_mmio"),
59    ("CONFIG_VIRTIO_CONSOLE", "virtio_console"),
60];
61
62/// Optional-device options bundled as boot modules when `=m` (so the
63/// corresponding ktstr feature works) but not required to boot — the
64/// device is only presented when a test attaches a disk / NIC / btrfs
65/// disk. `virtio_pci` is x86-only (aarch64 routes virtio over MMIO with
66/// no PCI bus — `src/vmm/setup/mod.rs`).
67const FEATURE_MODULES: &[(&str, &str)] = &[
68    #[cfg(target_arch = "x86_64")]
69    ("CONFIG_VIRTIO_PCI", "virtio_pci"),
70    ("CONFIG_VIRTIO_BLK", "virtio_blk"),
71    ("CONFIG_VIRTIO_NET", "virtio_net"),
72    ("CONFIG_BTRFS_FS", "btrfs"),
73];
74
75/// ktstr monitor/debug niceties that are not on the build path's
76/// critical list but degrade functionality when absent from a prebuilt
77/// kernel. Warn-only, with the concrete effect the operator loses.
78const WARN_EXTRA: &[(&str, &str)] = &[
79    (
80        "CONFIG_KALLSYMS_ALL",
81        "monitor kallsyms symbol resolution will be less complete",
82    ),
83    (
84        "CONFIG_IKCONFIG_PROC",
85        "/proc/config.gz unavailable for in-guest config inspection",
86    ),
87    (
88        "CONFIG_IKHEADERS",
89        "/sys/kernel/kheaders.tar.xz absent — bpftrace/BCC in shell mode \
90         cannot fall back to in-kernel headers",
91    ),
92    (
93        "CONFIG_FTRACE_SYSCALLS",
94        "syscall tracepoints (tracepoint:syscalls:*) unavailable",
95    ),
96];
97
98/// State of a kconfig symbol in an extracted `.config`.
99#[derive(Clone, Copy, PartialEq, Eq, Debug)]
100enum OptState {
101    /// `CONFIG_X=y` (or any non-`m` value assignment) — compiled in.
102    Builtin,
103    /// `CONFIG_X=m` — loadable module.
104    Module,
105    /// `# CONFIG_X is not set`, `=n`, or absent entirely.
106    Off,
107}
108
109/// Parsed states of the symbols in a kernel `.config`, for the gate.
110struct ConfigStates(HashMap<String, OptState>);
111
112impl ConfigStates {
113    fn parse(text: &str) -> Self {
114        let mut map = HashMap::new();
115        for line in text.lines() {
116            let line = line.trim();
117            if let Some(rest) = line.strip_prefix("# ")
118                && let Some(sym) = rest.strip_suffix(" is not set")
119                && sym.starts_with("CONFIG_")
120            {
121                map.insert(sym.to_string(), OptState::Off);
122            } else if line.starts_with("CONFIG_")
123                && let Some((sym, val)) = line.split_once('=')
124            {
125                let state = match val {
126                    "m" => OptState::Module,
127                    "n" => OptState::Off,
128                    _ => OptState::Builtin,
129                };
130                map.insert(sym.to_string(), state);
131            }
132        }
133        ConfigStates(map)
134    }
135
136    fn state(&self, opt: &str) -> OptState {
137        self.0.get(opt).copied().unwrap_or(OptState::Off)
138    }
139
140    fn is_enabled(&self, opt: &str) -> bool {
141        matches!(self.state(opt), OptState::Builtin | OptState::Module)
142    }
143}
144
145/// The module NAMES a gate run selected, split by criticality.
146#[derive(Debug)]
147struct GateResult {
148    /// `=m` boot-critical drivers — every one MUST resolve to a `.ko`
149    /// or acquisition fails (the kernel cannot boot in ktstr).
150    critical: Vec<&'static str>,
151    /// `=m` feature drivers — best-effort: a module the kernel declares
152    /// `=m` but does not actually ship in the resolved packages only
153    /// disables that feature, not the boot.
154    feature: Vec<&'static str>,
155}
156
157/// Apply the config gate to an extracted kernel and return the boot-
158/// critical and feature module NAMES to load. Boot-critical options
159/// absent in any form (neither `=y` nor `=m`) are a hard error; every
160/// other classified option warns and proceeds.
161///
162/// A package that shipped no `.config` (SteamOS's linux-neptune
163/// carries neither a config file nor an embedded IKCONFIG — verified
164/// against a live jupiter-3.8 package) but did ship a module tree is
165/// gated on the TREE instead: every boot-critical and feature
166/// driver is listed for [`select_boot_modules`], whose
167/// `module_closure` run skips drivers built in per `modules.builtin`,
168/// resolves shipped `.ko`s, hard-errors on a boot-critical driver
169/// found in neither, and warns per missing feature driver — the same
170/// outcomes the config gate produces, derived from what the package
171/// actually carries. With neither config nor module tree, the gate is
172/// skipped with a warning and the kernel is trusted to have virtio
173/// built in.
174fn gate_config(extracted: &ExtractedKernel) -> Result<GateResult> {
175    let kernel_label = &extracted.kernel_release;
176    let Some(config_path) = extracted.config.as_deref() else {
177        if extracted.modules_dir.is_some() {
178            tracing::warn!(
179                kernel = %kernel_label,
180                "prebuilt kernel shipped no .config — gating boot-critical \
181                 virtio drivers on the module tree (modules.builtin + \
182                 modules.dep) instead; config-derived feature warnings are \
183                 unavailable for this kernel"
184            );
185            return Ok(GateResult {
186                critical: BOOT_CRITICAL.iter().map(|(_, m)| *m).collect(),
187                feature: FEATURE_MODULES.iter().map(|(_, m)| *m).collect(),
188            });
189        }
190        tracing::warn!(
191            kernel = %kernel_label,
192            "prebuilt kernel shipped no .config — skipping config gate. If the \
193             guest hangs at boot, the kernel likely lacks CONFIG_VIRTIO_MMIO / \
194             CONFIG_VIRTIO_CONSOLE (which ktstr needs for its console/control port)."
195        );
196        return Ok(GateResult {
197            critical: Vec::new(),
198            feature: Vec::new(),
199        });
200    };
201    let text = fs::read_to_string(config_path)
202        .with_context(|| format!("read extracted config {}", config_path.display()))?;
203    let states = ConfigStates::parse(&text);
204
205    let mut critical: Vec<&'static str> = Vec::new();
206    let mut missing_critical: Vec<&'static str> = Vec::new();
207    for (opt, module) in BOOT_CRITICAL {
208        match states.state(opt) {
209            OptState::Builtin => {}
210            OptState::Module => critical.push(module),
211            OptState::Off => missing_critical.push(opt),
212        }
213    }
214    if !missing_critical.is_empty() {
215        bail!(
216            "prebuilt kernel {kernel_label} cannot boot under ktstr: \
217             boot-critical option(s) {missing_critical:?} are neither =y nor =m. \
218             ktstr presents its console + host control port over the virtio-MMIO \
219             transport, so without these drivers the guest hangs before reaching \
220             userspace. This kernel is unsupported."
221        );
222    }
223
224    let mut feature: Vec<&'static str> = Vec::new();
225    for (opt, module) in FEATURE_MODULES {
226        match states.state(opt) {
227            OptState::Module => feature.push(module),
228            OptState::Builtin => {}
229            OptState::Off => tracing::warn!(
230                kernel = kernel_label,
231                option = opt,
232                "not enabled — the corresponding ktstr feature (disk / NIC / btrfs \
233                 disk) will not work with this kernel; plain boots are unaffected"
234            ),
235        }
236    }
237
238    // Warn on every other option the build path treats as critical
239    // (SCHED_CLASS_EXT, DEBUG_INFO_BTF, BPF, FTRACE, tracepoints, ACPI,
240    // PCI, ...) that this prebuilt kernel lacks — reusing that list so
241    // the two never drift. Options already classified above are skipped.
242    let handled: HashSet<&str> = BOOT_CRITICAL
243        .iter()
244        .chain(FEATURE_MODULES.iter())
245        .map(|(opt, _)| *opt)
246        .collect();
247    for (opt, hint) in crate::cli::critical_config_options() {
248        if handled.contains(opt) || states.is_enabled(opt) {
249            continue;
250        }
251        tracing::warn!(
252            kernel = kernel_label,
253            option = opt,
254            "not enabled in this prebuilt kernel — {hint}"
255        );
256    }
257    for (opt, effect) in WARN_EXTRA {
258        if !states.is_enabled(opt) {
259            tracing::warn!(
260                kernel = kernel_label,
261                option = opt,
262                "not enabled in this prebuilt kernel — {effect}"
263            );
264        }
265    }
266
267    Ok(GateResult { critical, feature })
268}
269
270/// Resolve the gate's module NAMES into the ordered, dependency-first,
271/// already-decompressed `.ko` paths to embed. Boot-critical modules
272/// must all resolve; a feature module the kernel declares `=m` but does
273/// not actually ship in the extracted packages is warned and skipped
274/// rather than failing the whole acquisition.
275fn select_boot_modules(extracted: &ExtractedKernel, gate: &GateResult) -> Result<Vec<PathBuf>> {
276    if gate.critical.is_empty() && gate.feature.is_empty() {
277        return Ok(Vec::new());
278    }
279    let modules_dir = extracted.modules_dir.as_ref().ok_or_else(|| {
280        anyhow!(
281            "kernel needs loadable modules but the package(s) carried no module \
282             tree — cannot assemble a bootable module set"
283        )
284    })?;
285    let release = &extracted.kernel_release;
286
287    let mut out: Vec<PathBuf> = Vec::new();
288    let mut seen: HashSet<PathBuf> = HashSet::new();
289
290    // Boot-critical: every module must resolve, or this kernel cannot
291    // reach the ktstr console/control port and is unsupported.
292    let crit = module_closure(modules_dir, release, &gate.critical).with_context(|| {
293        format!(
294            "prebuilt kernel {release} neither builds in nor ships a \
295             boot-critical virtio module among {:?} — ktstr cannot reach its \
296             console/host control port without it, so this kernel is unsupported \
297             (some distros split virtio-console into a subpackage the resolver \
298             must include)",
299            gate.critical
300        )
301    })?;
302    for p in crit {
303        if seen.insert(p.clone()) {
304            out.push(p);
305        }
306    }
307
308    // Feature drivers: resolve each independently so a missing one only
309    // disables its feature (disk / NIC / btrfs) instead of blocking boot.
310    for module in &gate.feature {
311        match module_closure(modules_dir, release, std::slice::from_ref(module)) {
312            Ok(mods) => {
313                for p in mods {
314                    if seen.insert(p.clone()) {
315                        out.push(p);
316                    }
317                }
318            }
319            Err(e) => tracing::warn!(
320                module = module,
321                "declared =m but not shipped by this kernel ({e:#}); the \
322                 corresponding disk/NIC/btrfs feature will not work"
323            ),
324        }
325    }
326
327    Ok(out)
328}
329
330/// Atomically install the extracted kernel + already-selected boot
331/// modules into the cache under `cache_key`. Returns the cache entry
332/// directory. Shared tail of the distro and local-package paths; the
333/// config gate and boot-module selection run in the caller (before this)
334/// so the distro path can gate a kernel before downloading its
335/// debuginfo.
336pub(crate) fn install_extracted(
337    cache_key: &str,
338    extracted: &ExtractedKernel,
339    modules: &[PathBuf],
340    source: KernelSource,
341) -> Result<PathBuf> {
342    let (arch, image_name) = crate::fetch::arch_info();
343    let meta = KernelMetadata::new(source, arch, image_name, crate::test_support::now_iso8601())
344        .with_version(&extracted.kernel_release);
345
346    let mut artifacts = CacheArtifacts::new(&extracted.image).with_modules(modules);
347    if let Some(vmlinux) = extracted.vmlinux.as_deref() {
348        artifacts = artifacts.with_vmlinux(vmlinux);
349    }
350    if let Some(config) = extracted.config.as_deref() {
351        artifacts = artifacts.with_config(config);
352    }
353
354    let cache = CacheDir::new()?;
355    let entry = cache.store(cache_key, &artifacts, &meta).with_context(|| {
356        format!(
357            "install prebuilt kernel {} into cache",
358            extracted.kernel_release
359        )
360    })?;
361    Ok(entry.path)
362}
363
364/// A disk-backed scratch directory under the kernel cache root, so
365/// large debuginfo downloads (~1 GiB) don't land in a tmpfs `/tmp` and
366/// so the final reflink-copy into the cache stays on one filesystem.
367/// Dot-prefixed, which `CacheDir::list` skips, so it never surfaces as
368/// a cache entry even mid-run.
369pub(crate) fn scratch_dir() -> Result<tempfile::TempDir> {
370    let root = crate::cache::resolve_cache_root_with_suffix("kernels")?;
371    fs::create_dir_all(&root).with_context(|| format!("create cache root {}", root.display()))?;
372    tempfile::Builder::new()
373        .prefix(".acquire-")
374        .tempdir_in(&root)
375        .with_context(|| "create acquire scratch dir")
376}
377
378/// Cache key for a distro kernel:
379/// `distro-{tag}-{release}-{arch}-pkg{sha12}` — deliberately with NO
380/// `kc{...}` kconfig suffix (ktstr did not build this kernel, so its
381/// kconfig hash is irrelevant). `sha12` is the first 12 hex of the
382/// primary (first) package's declared sha256, so a distro republish of
383/// the same version under a new build lands at a distinct entry.
384fn distro_cache_key(resolved: &ResolvedDistroKernel) -> Result<String> {
385    let primary = resolved
386        .packages
387        .first()
388        .ok_or_else(|| anyhow!("distro resolver returned no kernel packages"))?;
389    let sha12 = primary.sha256.get(..12).unwrap_or(&primary.sha256);
390    Ok(format!(
391        "distro-{}-{}-{}-pkg{}",
392        sanitize_key_part(&resolved.distro),
393        sanitize_key_part(&resolved.kernel_release),
394        resolved.arch,
395        sha12,
396    ))
397}
398
399/// Cache key for local packages: `pkg-{combined12}-{arch}`, where
400/// `combined12` is the first 12 hex of the sha256 over the sorted
401/// per-file sha256 digests (order-independent, content-addressed).
402fn local_cache_key(file_hashes: &[String], arch: &str) -> String {
403    let mut sorted: Vec<&str> = file_hashes.iter().map(String::as_str).collect();
404    sorted.sort_unstable();
405    let mut h = Sha256::new();
406    for fh in sorted {
407        h.update(fh.as_bytes());
408    }
409    let combined = hex::encode(h.finalize());
410    format!("pkg-{}-{arch}", &combined[..12])
411}
412
413/// Reduce a key part to the `validate_cache_key` alphabet
414/// (`[A-Za-z0-9._-]`), folding every other byte to `_`. Distro tags and
415/// kernel releases already fit; this is a guard against a future distro
416/// tag with an out-of-alphabet byte producing an invalid key.
417fn sanitize_key_part(s: &str) -> String {
418    s.chars()
419        .map(|c| {
420            if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
421                c
422            } else {
423                '_'
424            }
425        })
426        .collect()
427}
428
429/// sha256 (lowercase hex) of a file's contents, streamed.
430fn sha256_file(path: &Path) -> Result<String> {
431    use std::io::Read;
432    let mut file = fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
433    let mut hasher = Sha256::new();
434    let mut buf = [0u8; 65536];
435    loop {
436        let n = file
437            .read(&mut buf)
438            .with_context(|| format!("read {}", path.display()))?;
439        if n == 0 {
440            break;
441        }
442        hasher.update(&buf[..n]);
443    }
444    Ok(hex::encode(hasher.finalize()))
445}
446
447/// Try every equivalent official origin for one package while keeping one
448/// repository-declared digest as the authority for all of them.
449///
450/// An origin gets the complete shared transport retry policy before advancing
451/// to the next one. Interruption never looks like origin failure: it aborts the
452/// sequence immediately instead of beginning another potentially large
453/// download after Ctrl-C/SIGTERM.
454fn try_package_urls<T, F>(package: &PackageRef, attempt: F) -> Result<T>
455where
456    F: FnMut(&str) -> Result<T>,
457{
458    try_package_urls_with(package, crate::fetch::git_operation_interrupted, attempt)
459}
460
461fn try_package_urls_with<T, I, F>(
462    package: &PackageRef,
463    mut interrupted: I,
464    mut attempt: F,
465) -> Result<T>
466where
467    I: FnMut() -> bool,
468    F: FnMut(&str) -> Result<T>,
469{
470    let urls: Vec<&str> = std::iter::once(package.url.as_str())
471        .chain(package.alternate_urls.iter().map(String::as_str))
472        .collect();
473    let mut failures = Vec::with_capacity(urls.len());
474
475    for (index, url) in urls.iter().copied().enumerate() {
476        match attempt(url) {
477            Ok(value) => return Ok(value),
478            Err(error) if interrupted() => {
479                return Err(error).with_context(|| format!("download {} from {url}", package.name));
480            }
481            Err(error) => {
482                failures.push(format!("{url}: {error:#}"));
483                if index + 1 < urls.len() {
484                    tracing::warn!(
485                        package = %package.name,
486                        failed_url = url,
487                        next_url = urls[index + 1],
488                        error = %format!("{error:#}"),
489                        "official package origin failed; trying independent origin",
490                    );
491                }
492            }
493        }
494    }
495
496    bail!(
497        "all official download origins failed for {}: {}",
498        package.name,
499        failures.join("; ")
500    )
501}
502
503/// Acquire a prebuilt distro kernel (`--kernel fedora` / `ubuntu` /
504/// `amazonlinux`, with optional pinned release) into the cache and
505/// return its cache-entry directory.
506///
507/// Resolves repo metadata, composes the cache key, and on a hit returns
508/// immediately. On a miss: downloads the kernel image/modules packages
509/// with sha256 verification, checks each against the host arch,
510/// extracts, and runs the config gate + boot-module selection — all
511/// BEFORE fetching the debuginfo, so an unsupported kernel fails without
512/// any (up to ~1 GiB) debuginfo bytes crossing the wire. Only once the
513/// gate passes does it download + extract the debuginfo, merge its
514/// vmlinux, and install atomically. Debuginfo is mandatory for every
515/// distro whose repos publish it (the resolvers fail hard on a missing
516/// package); a distro that publishes none (SteamOS) resolves with an
517/// empty debuginfo set and proceeds with a warning naming what
518/// degrades.
519pub fn acquire_distro_kernel(
520    kind: DistroKind,
521    release: Option<&str>,
522    cli_label: &str,
523    mp: Option<&crate::cli::FetchProgress>,
524) -> Result<PathBuf> {
525    if kind == DistroKind::Gke {
526        return crate::distro::gke::acquire_gke_kernel(release, cli_label, mp);
527    }
528    let resolved =
529        resolve_distro_kernel(kind, release).with_context(|| "resolve distro kernel metadata")?;
530    let cache_key = distro_cache_key(&resolved)?;
531
532    let cache = CacheDir::new()?;
533    if let Some(entry) = cache.lookup(&cache_key) {
534        tracing::info!(cache_key = %cache_key, "distro kernel cache hit");
535        return Ok(entry.path);
536    }
537
538    let msg = format!(
539        "{cli_label}: resolving {} kernel {} ({} package(s) + {} debuginfo)",
540        resolved.distro,
541        resolved.kernel_release,
542        resolved.packages.len(),
543        resolved.debuginfo.len(),
544    );
545    match mp {
546        Some(fp) => fp.println(&msg),
547        None => eprintln!("{msg}"),
548    }
549    if resolved.debuginfo.is_empty() {
550        // A distro with no published debug packages (SteamOS) is exempt
551        // from the otherwise-mandatory debuginfo: the cache entry gets
552        // no vmlinux, so the monitor's vmlinux-dependent features
553        // (symbolized stacks, probe file:line resolution) surface their
554        // normal "no vmlinux" error if actually used.
555        let warn = format!(
556            "{cli_label}: {} publishes no kernel debuginfo — proceeding \
557             without vmlinux; monitor features that need it (symbolized \
558             stacks, probe file:line) will be unavailable for this kernel",
559            resolved.distro,
560        );
561        match mp {
562            Some(fp) => fp.println(&warn),
563            None => eprintln!("{warn}"),
564        }
565        tracing::warn!(distro = %resolved.distro, "no debuginfo published; caching kernel without vmlinux");
566    }
567
568    let scratch = scratch_dir()?;
569    let download_dir = scratch.path().join("pkgs");
570    fs::create_dir_all(&download_dir)?;
571
572    // Download one package with its own progress line + sha256 check,
573    // then guard it against the host arch before it is unpacked.
574    let download = |pkg: &PackageRef| -> Result<PathBuf> {
575        let file_name = pkg
576            .url
577            .rsplit('/')
578            .next()
579            .filter(|s| !s.is_empty())
580            .unwrap_or(&pkg.name);
581        let dest = download_dir.join(file_name);
582        try_package_urls(pkg, |url| {
583            crate::fetch::download_verified_file(url, &dest, &pkg.sha256, &pkg.name, cli_label, mp)
584        })
585        .with_context(|| format!("download {}", pkg.name))?;
586        if let Some(expected) = pkg.size {
587            let actual = fs::metadata(&dest)
588                .with_context(|| format!("stat downloaded package {}", dest.display()))?
589                .len();
590            if actual != expected {
591                bail!(
592                    "downloaded package {} has size {actual}, expected {expected}",
593                    pkg.name
594                );
595            }
596        }
597        ensure_arch_matches_host(&package_arch(&dest)?, &dest)?;
598        Ok(dest)
599    };
600
601    // Download + extract the kernel image/modules packages FIRST, then
602    // gate the config and select boot modules — all before touching the
603    // mandatory (up to ~1 GiB) debuginfo. A kernel that cannot boot
604    // under ktstr (e.g. one built without CONFIG_VIRTIO_MMIO) fails at
605    // the gate here with no debuginfo bytes fetched.
606    let extract_dir = scratch.path().join("tree");
607    let kernel_paths: Vec<PathBuf> = resolved
608        .packages
609        .iter()
610        .map(&download)
611        .collect::<Result<_>>()?;
612    let kernel_refs: Vec<&Path> = kernel_paths.iter().map(PathBuf::as_path).collect();
613    let mut extracted = extract_kernel_packages(&kernel_refs, &extract_dir)
614        .with_context(|| format!("extract {} packages", resolved.distro))?;
615
616    let gate = gate_config(&extracted)?;
617    let modules = select_boot_modules(&extracted, &gate)?;
618
619    // Gate passed — only now fetch the debuginfo and merge its vmlinux
620    // into the extracted set. SteamOS publishes none (debuginfo empty,
621    // warned about above) and is skipped here.
622    if !resolved.debuginfo.is_empty() {
623        let debug_paths: Vec<PathBuf> = resolved
624            .debuginfo
625            .iter()
626            .map(&download)
627            .collect::<Result<_>>()?;
628        let debug_refs: Vec<&Path> = debug_paths.iter().map(PathBuf::as_path).collect();
629        extracted.vmlinux = extract_vmlinux(&debug_refs, &extract_dir, &extracted.kernel_release)
630            .with_context(|| format!("extract {} debuginfo", resolved.distro))?;
631    }
632
633    let packages_meta: Vec<String> = resolved
634        .packages
635        .iter()
636        .chain(resolved.debuginfo.iter())
637        .map(|p| format!("{}-{}", p.name, p.version))
638        .collect();
639    let source = KernelSource::DistroPackage {
640        distro: resolved.distro.clone(),
641        packages: packages_meta,
642    };
643    install_extracted(&cache_key, &extracted, &modules, source)
644}
645
646/// Acquire a kernel from one or more local `.rpm`/`.deb` files into the
647/// cache and return its cache-entry directory. No debuginfo requirement
648/// — `vmlinux` is cached only when a debuginfo package is among the
649/// files; otherwise the entry has no vmlinux and the monitor's
650/// vmlinux-dependent features surface their normal "no vmlinux" error
651/// only if actually used.
652pub fn acquire_package_kernel(paths: &[PathBuf]) -> Result<PathBuf> {
653    if paths.is_empty() {
654        bail!("acquire_package_kernel: no package files supplied");
655    }
656    for p in paths {
657        if !p.is_file() {
658            bail!("kernel package not found: {}", p.display());
659        }
660    }
661
662    let (arch, _) = crate::fetch::arch_info();
663    let hashes: Vec<String> = paths
664        .iter()
665        .map(|p| sha256_file(p))
666        .collect::<Result<_>>()?;
667    let cache_key = local_cache_key(&hashes, arch);
668
669    let cache = CacheDir::new()?;
670    if let Some(entry) = cache.lookup(&cache_key) {
671        tracing::info!(cache_key = %cache_key, "local package kernel cache hit");
672        return Ok(entry.path);
673    }
674
675    // Arch guard up front for a clear message before extraction work.
676    for p in paths {
677        ensure_arch_matches_host(&package_arch(p)?, p)?;
678    }
679
680    let scratch = scratch_dir()?;
681    let extract_dir = scratch.path().join("tree");
682    let refs: Vec<&Path> = paths.iter().map(PathBuf::as_path).collect();
683    let extracted = extract_kernel_packages(&refs, &extract_dir)
684        .with_context(|| "extract local kernel packages")?;
685    let gate = gate_config(&extracted)?;
686    let modules = select_boot_modules(&extracted, &gate)?;
687
688    let packages_meta: Vec<String> = paths
689        .iter()
690        .filter_map(|p| p.file_name().map(|n| n.to_string_lossy().into_owned()))
691        .collect();
692    let source = KernelSource::LocalPackage {
693        packages: packages_meta,
694    };
695    install_extracted(&cache_key, &extracted, &modules, source)
696}
697
698#[cfg(test)]
699#[path = "acquire_tests.rs"]
700mod tests;