Module cache

Module cache 

Source
Expand description

Kernel image cache for ktstr.

Manages a local cache of built kernel images under an XDG-compliant directory. Each cached kernel is a directory containing the boot image, optionally a stripped vmlinux ELF (symbol table, BTF, and the section headers that monitor/probe code reads), and a metadata.json descriptor. CONFIG_HZ is recovered from the embedded IKCONFIG blob in the stripped vmlinux (ktstr.kconfig forces CONFIG_IKCONFIG=y), so no separate .config sidecar is cached.

§Cache location

Resolved in order:

  1. KTSTR_CACHE_DIR environment variable
  2. $XDG_CACHE_HOME/ktstr/kernels/
  3. $HOME/.cache/ktstr/kernels/

§Submodule layout

  • metadata — public types: KernelSource, KernelMetadata, CacheArtifacts, KconfigStatus, CacheEntry, ListedEntry, plus the internal classify_corrupt_reason dispatcher.
  • cache_dir — CacheDir handle, lock guards (SharedLockGuard, ExclusiveLockGuard), store/lookup/list/ clean lifecycle, and reader/writer-asymmetric lock policy.
  • housekeeping — atomic-rename install primitives, cache-key and image-name validators, read_metadata decoder, and the clean_orphaned_tmp_dirs cross-PID sweep.
  • vmlinux_strip — ELF strip pipeline (strip_vmlinux_debug, neutralize_relocs, strip_keep_list, strip_debug_prefix) plus the keep-list / zero-data section-name unions.
  • resolve — env-cascade root resolution (resolve_cache_root_with_suffix, validate_home_for_cache, path_inside_cache_root) and source-tree path helpers (prefer_source_tree_for_dwarf, recover_local_source_tree).

Each submodule owns its tests in a #[cfg(test)] mod tests block — inline in the same file except cache_dir, whose tests live in cache_dir_tests.rs via #[path]; shared test fixtures used by more than one submodule’s tests live in shared_test_helpers.

Re-exports§

pub use crate::kernel_path::KernelId;

Structs§

CacheArtifacts
Bundle of cache artifacts for crate::cache::CacheDir::store.
CacheDir
Handle to the kernel image cache directory.
CacheEntry
A cached kernel entry returned by crate::cache::CacheDir::lookup and crate::cache::CacheDir::store.
ContentFileSnapshot
One immutable, content-addressed snapshot of an input file.
ExclusiveLockGuard
RAII guard for a LOCK_EX hold on a cache-entry lockfile.
KernelMetadata
Metadata stored alongside a cached kernel image.
PinnedContentFile
One opened regular-file revision retained independently of its pathname.
SharedLockGuard
RAII guard for a LOCK_SH hold on a cache-entry lockfile.

Enums§

KconfigStatus
Comparison between a cache entry’s kconfig hash and a current reference hash. Returned by CacheEntry::kconfig_status.
KernelSource
How a cached kernel’s source was acquired, with per-variant payload (git details for Git, source-tree path and git hash for Local).
ListedEntry
Entry yielded by crate::cache::CacheDir::list. Distinguishes valid entries from corrupt ones.

Functions§

affected_cache_root
Cache root for the cargo ktstr affected per-scheduler input-set cache.
boot_modules_for_image
Ordered boot modules for a cached kernel image, discovered from the modules/ subdirectory that sits beside the image in its cache entry (<entry>/bzImage + <entry>/modules/). Empty for built kernels and build-tree images (no sibling modules/), so callers can pass the result to KtstrVmBuilder::kernel_modules unconditionally — an empty set is a no-op.
cargo_build_output_lock_root
Host-global coordination namespace for wrapper-owned Cargo output locks.
initrd_compression_for_image
Initrd compression the kernel behind image can unpack, discovered from the config file that sits beside the image in its cache entry (<entry>/bzImage + <entry>/config). No config (built kernels pin CONFIG_RD_LZ4=y via ktstr.kconfig; raw images carry no sidecar) defaults to LZ4 — today’s behavior. With a config, the first of RD_LZ4 / RD_ZSTD / RD_GZIP the kernel enables wins, falling back to uncompressed cpio (which needs no CONFIG_RD_*) when it enables none. Callers pass the result to KtstrVmBuilder::initrd_compression (crate-private) unconditionally.
ordered_boot_modules_in
Ordered boot modules under modules_dir (NNN-*.ko), sorted by file name so the zero-padded NNN index reproduces the load order CacheDir::store wrote. Non-directory / missing paths yield an empty vector. Pure over one read_dir.
pin_content_file
Open and pin one regular-file revision without publishing it yet.
prefer_source_tree_for_dwarf
Re-route a cache-entry directory to its original source tree when blazesym DWARF access is required. Validates the source-tree vmlinux’s current size and mtime against the values captured at cache-store time.
recover_local_source_tree
Read dir/metadata.json and return the persisted source-tree path when the entry was built from a local source tree.
snapshot_content_file
Pin one regular-file revision and publish it into the shared content CAS.
snapshot_pinned_content_file
Publish an already-pinned file revision into the shared content CAS.