Module cache 

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.

ExclusiveLockGuard

RAII guard for a LOCK_EX hold on a cache-entry lockfile.

KernelMetadata

Metadata stored alongside a cached kernel image.

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.

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.