1#[cfg(test)]
50use crate::assert::AssertResult;
51#[cfg(test)]
52use crate::scenario::Ctx;
53#[cfg(test)]
54use anyhow::Result;
55
56mod admission_stamp;
57mod args;
58#[doc(hidden)]
59pub use admission_stamp::{
60 AdmissionCellDescriptor, AdmissionCellKind, AdmissionMode, AdmissionTestKeyV3,
61 AdmissionTestStampV3, AdmissionTopologyDescriptor, KTSTR_ADMISSION_TEST_KEYS_V3,
62 KTSTR_ADMISSION_TESTS_V3, read_admission_cell_stamp,
63};
64pub(crate) use args::resolve_cgroup_root;
68mod boot_retry;
69#[cfg(target_arch = "x86_64")]
73pub(crate) use boot_retry::guest_kernel_rejected_wide_apic;
74pub(crate) use boot_retry::{AP_BRINGUP_GAP_MARKER, run_vm_with_ap_gap_retry};
75mod dispatch;
76mod entry;
77mod entry_validate;
78mod eval;
79mod host_class;
80mod metrics;
81mod output;
82#[doc(hidden)]
83pub use output::strip_ansi_csi;
84pub(crate) use output::parse_assert_result_from_drain;
89mod payload;
90mod probe;
91pub(crate) use probe::PROBE_OUTPUT_END;
97mod probe_metrics;
98mod profraw;
99pub(crate) use eval::FrameworkInfrastructureFailure;
100pub use eval::{
101 capture_starvation_witness, periodic_starvation_gate, post_vm_skip, stall_ejection_skip,
102 starved_below_minimum_skip,
103};
104pub use profraw::current_binary_is_coverage_instrumented;
105pub mod runtime;
106mod scheduler_manifest_stamp;
107#[doc(hidden)]
108pub use scheduler_manifest_stamp::{
109 KTSTR_SCHEDULER_MANIFEST_DECLARATIONS_V1, KTSTR_SCHEDULER_MANIFEST_TESTS_V1,
110 SchedulerManifestDeclarationStampV1, SchedulerManifestStampSliceV1,
111 SchedulerManifestStampStrV1, SchedulerManifestStampSysctlV1, SchedulerManifestTestStampV1,
112 SchedulerManifestUseStampV1, read_scheduler_manifest_stamp,
113};
114
115#[doc(hidden)]
124pub fn read_scheduler_manifest_and_validate_admission_stamp(
125 path: &std::path::Path,
126) -> std::result::Result<Option<SchedulerManifestProbe>, String> {
127 let file = std::fs::File::open(path).map_err(|error| {
128 format!(
129 "open warmed test binary {} for ktstr metadata: {error}",
130 path.display(),
131 )
132 })?;
133 let data = unsafe { memmap2::MmapOptions::new().map(&file) }.map_err(|error| {
136 format!(
137 "map warmed test binary {} for ktstr metadata: {error}",
138 path.display(),
139 )
140 })?;
141 scheduler_manifest_stamp::advise_sparse_elf(&data);
142 let reader = scheduler_manifest_stamp::ElfStampReader::new(path, &data)?;
143 let manifest = scheduler_manifest_stamp::read_scheduler_manifest_stamp_reader(&reader)?;
144 admission_stamp::validate_admission_stamp_envelope_reader(&reader)?;
145 Ok(manifest)
146}
147mod shell_descriptor;
148pub use shell_descriptor::{SchedulerKind, ShellTestDescriptor};
149#[cfg(feature = "wprof")]
150pub mod wprof;
151#[cfg(feature = "wprof")]
152pub use wprof::{PERFETTO_TRACE_PACKETS_TAG, WPROF_PB_MIN_BYTES, assert_wprof_pb_shape};
153#[cfg(test)]
154pub(crate) mod btf_blob;
155mod sidecar;
156pub(crate) mod staged;
157#[cfg(test)]
158pub(crate) mod test_helpers;
159mod timefmt;
160mod topo;
161
162pub type PostVmCallback = fn(&crate::vmm::VmResult) -> anyhow::Result<()>;
173
174#[cfg(feature = "export")]
179pub(crate) use args::extract_export_output_arg;
180#[allow(unused_imports)]
181pub(crate) use args::{
182 CellParentCgroupArg, VERIFIER_WORKLOAD_FLAG, cell_parent_path_is_valid,
183 extract_export_check_test_arg, extract_export_test_arg, extract_probe_stack_arg,
184 extract_shell_test_arg, extract_test_fn_arg, extract_topo_arg, extract_work_type_arg,
185 is_verifier_workload, parse_cell_parent_cgroup, parse_line_framed_args,
186};
187#[allow(unused_imports)]
188pub(crate) use runtime::{append_base_sched_args, content_hash, scratch_dir, sys_rdy_budget_ms};
189#[cfg(test)]
190pub(crate) use sidecar::enriched_parse_error_message_for_test;
191pub use sidecar::{
192 PerfDeltaAssertionRecord, SidecarResult, ThroughputDenomination, collect_pool,
193 detect_kernel_commit, detect_project_commit, format_run_artifact_footer,
194 kernel_commit_for_resolved, newest_run_dir, repo_is_dirty, runs_root, sidecar_dir,
195 source_dir_for,
196};
197pub(crate) use sidecar::{
198 SidecarIoError, SidecarParseError, apply_archive_source_override, collect_sidecars,
199 collect_sidecars_with_errors, format_callback_profile, format_kvm_stats, format_verifier_stats,
200 is_run_directory, is_sidecar_filename, warn_skipped_sidecars,
201};
202
203pub use dispatch::{
204 DEFAULT_HOST_CGROUP_PARENT, EXIT_FAIL, EXIT_INCONCLUSIVE, EXIT_PASS, analyze_sidecars,
205 is_cpu_budget_unsatisfiable, is_kernel_unavailable, is_perf_mode_unavailable,
206 is_resource_contention, is_topology_insufficient, is_topology_unrepresentable, ktstr_main,
207 ktstr_test_early_dispatch, resolve_host_cgroup_parent, run_ktstr_test, sanitize_kernel_label,
208};
209pub use entry::{
210 BinaryKindJson, BpfMapAgg, BpfMapWrite, CgroupPath, KTSTR_SCHEDULERS, KTSTR_TESTS,
211 KtstrTestEntry, MemSideCache, NumaDistance, NumaNode, PerfDeltaAssertion,
212 SCHEDULER_MANIFEST_PROBE_ARG, Scheduler, SchedulerArtifactRequirement, SchedulerJson,
213 SchedulerListEntry, SchedulerManifestProbe, SchedulerSpec, SchedulerTestJson, Sysctl,
214 SysctlJson, Topology, TopologyConstraints, TopologyConstraintsJson, TopologyJson, WatchBpfMap,
215 default_post_vm_periodic_fired, find_scheduler, find_test, runtime_manifest_dir,
216};
217pub use eval::{KernelUnavailable, ResolveSource, resolve_scheduler, resolve_test_kernel};
218pub(crate) use eval::{record_skip_sidecar, run_ktstr_test_inner};
219pub(crate) use host_class::host_skip_class;
220pub use host_class::{HostClass, classify_host_error};
221
222#[doc(hidden)]
230pub fn is_framework_infrastructure_failure(error: &anyhow::Error) -> bool {
231 error
232 .downcast_ref::<eval::FrameworkInfrastructureFailure>()
233 .is_some()
234}
235pub use metrics::{
236 MAX_WALK_DEPTH, WALK_TRUNCATION_SENTINEL_NAME, extract_metrics, is_truncation_sentinel_name,
237 walk_json_leaves,
238};
239pub(crate) use output::extract_panic_message;
240pub use payload::{
241 Metric, MetricCheck, MetricHint, MetricStream, OutputFormat, Payload, PayloadKind,
242 PayloadMetrics, Polarity,
243};
244pub(crate) use probe::maybe_dispatch_vm_test;
245pub(crate) use probe::{
246 PROBE_DRAIN_GRACE, ProbePhaseAState, finalize_probe_after_unwind,
247 maybe_dispatch_vm_test_with_args, maybe_dispatch_vm_test_with_phase_a,
248 propagate_rust_env_from_cmdline, start_probe_phase_a,
249};
250pub use probe_metrics::{
251 MAX_SCAN_INDEX, ThreadLookup, count_indexed_metrics, find_metric, find_metric_u64,
252 flat_metrics_dump, has_metric, lookup_thread, snapshot_count, snapshot_worker_allocated,
253 thread_count,
254};
255pub use profraw::target_dir as profraw_target_dir;
256pub(crate) use profraw::{find_symbol_vaddrs, persist_guest_profraw, try_flush_profraw};
257pub(crate) use timefmt::now_iso8601;
258pub(crate) use topo::{TopoOverride, parse_topo_string};
259
260pub fn host_capacity() -> (u32, u32, u32) {
269 let host_cpus = std::thread::available_parallelism()
270 .map(|n| n.get() as u32)
271 .unwrap_or(1);
272 let host_topo = crate::vmm::host_topology::HostTopology::from_sysfs().ok();
273 let host_llcs = host_topo
274 .as_ref()
275 .map(|t| t.llc_groups.len() as u32)
276 .unwrap_or(1);
277 let host_max_cpus_per_llc = host_topo
278 .as_ref()
279 .map(|t| t.max_cores_per_llc() as u32)
280 .unwrap_or(host_cpus);
281 (host_cpus, host_llcs, host_max_cpus_per_llc)
282}
283
284#[cfg(test)]
325#[allow(dead_code)] pub(crate) fn cargo_ktstr_orchestrated() -> bool {
327 std::env::var(crate::KTSTR_ORCHESTRATED_ENV).is_ok()
328}
329
330#[cfg(test)]
340#[allow(dead_code)] pub(crate) const SKIP_NOT_ORCHESTRATED_MSG: &str = "raw nextest fan-out starves KVM resource budgets — see \
342 boot_kernel_with_monitor for the shared rationale. Run via \
343 `cargo ktstr test --kernel ../linux`.";
344
345#[cfg(test)]
346mod cargo_ktstr_orchestrated_tests {
347 use super::cargo_ktstr_orchestrated;
355 use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
356 #[test]
357 fn cargo_ktstr_orchestrated_true_when_env_set() {
358 let _lock = lock_env();
359 let _guard = EnvVarGuard::set(crate::KTSTR_ORCHESTRATED_ENV, "1");
360 assert!(
361 cargo_ktstr_orchestrated(),
362 "KTSTR_ORCHESTRATED set → orchestrated check must return true"
363 );
364 }
365 #[test]
366 fn cargo_ktstr_orchestrated_false_when_env_unset() {
367 let _lock = lock_env();
368 let _guard = EnvVarGuard::remove(crate::KTSTR_ORCHESTRATED_ENV);
369 assert!(
370 !cargo_ktstr_orchestrated(),
371 "KTSTR_ORCHESTRATED absent → orchestrated check must return false \
372 (otherwise raw nextest invocations would run vmm tests and \
373 starve KVM resource budgets)"
374 );
375 }
376}
377
378#[cfg(test)]
386#[allow(dead_code)] pub(crate) fn require_kernel() -> std::path::PathBuf {
388 match crate::find_kernel() {
389 Ok(Some(p)) => p,
390 Ok(None) => panic!(
391 "ktstr_test: test requires a kernel but none was found. {}",
392 crate::KTSTR_KERNEL_HINT
393 ),
394 Err(e) => panic!("ktstr_test: kernel resolution failed: {e:#}"),
395 }
396}
397
398#[cfg(test)]
406#[allow(dead_code)] pub(crate) fn require_vmlinux(kernel_path: &std::path::Path) -> std::path::PathBuf {
408 crate::vmm::find_vmlinux(kernel_path).unwrap_or_else(|| {
409 panic!(
410 "ktstr_test: no vmlinux found alongside {}. The cache entry or \
411 kernel build is incomplete. Rebuild with `cargo ktstr kernel \
412 build --force`; the specified kernel must include `vmlinux` \
413 alongside the boot image. {}",
414 kernel_path.display(),
415 crate::KTSTR_KERNEL_HINT,
416 )
417 })
418}
419
420#[cfg(test)]
426pub(crate) fn require_binary(package: &str) -> std::path::PathBuf {
427 crate::build_and_find_binary(package, env!("CARGO_MANIFEST_DIR")).unwrap_or_else(|e| {
428 panic!(
429 "ktstr_test: build of `{package}` failed: {e:#}. \
430 Run `cargo build -p {package}` to reproduce and diagnose."
431 )
432 })
433}
434
435#[cfg(test)]
439#[allow(dead_code)] pub(crate) fn require_kernel_symbols(
441 vmlinux_path: &std::path::Path,
442) -> crate::monitor::symbols::KernelSymbols {
443 crate::monitor::symbols::KernelSymbols::from_vmlinux(vmlinux_path).unwrap_or_else(|e| {
444 panic!(
445 "ktstr_test: kernel symbol resolution from {} failed: {e:#}",
446 vmlinux_path.display(),
447 )
448 })
449}
450
451#[cfg(test)]
456pub(crate) fn require_kernel_offsets(
457 vmlinux_path: &std::path::Path,
458) -> crate::monitor::btf_offsets::KernelOffsets {
459 crate::monitor::btf_offsets::KernelOffsets::from_vmlinux(vmlinux_path).unwrap_or_else(|e| {
460 panic!(
461 "ktstr_test: kernel BTF resolution from {} failed: {e:#}. \
462 The kernel must be built with CONFIG_DEBUG_INFO_BTF=y; \
463 rebuild with `cargo ktstr kernel build --force` if the \
464 cache entry was produced without BTF.",
465 vmlinux_path.display(),
466 )
467 })
468}
469
470#[cfg(test)]
474pub(crate) fn require_bpf_map_offsets(
475 vmlinux_path: &std::path::Path,
476) -> crate::monitor::btf_offsets::BpfMapOffsets {
477 crate::monitor::btf_offsets::BpfMapOffsets::from_vmlinux(vmlinux_path).unwrap_or_else(|e| {
478 panic!(
479 "ktstr_test: BpfMapOffsets resolution from {} failed: {e:#}. \
480 The kernel must be built with CONFIG_DEBUG_INFO_BTF=y; \
481 rebuild with `cargo ktstr kernel build --force` if the \
482 cache entry was produced without BTF.",
483 vmlinux_path.display(),
484 )
485 })
486}
487
488#[cfg(test)]
492pub(crate) fn require_bpf_prog_offsets(
493 vmlinux_path: &std::path::Path,
494) -> crate::monitor::btf_offsets::BpfProgOffsets {
495 crate::monitor::btf_offsets::BpfProgOffsets::from_vmlinux(vmlinux_path).unwrap_or_else(|e| {
496 panic!(
497 "ktstr_test: BpfProgOffsets resolution from {} failed: {e:#}. \
498 The kernel must be built with CONFIG_DEBUG_INFO_BTF=y; \
499 rebuild with `cargo ktstr kernel build --force` if the \
500 cache entry was produced without BTF.",
501 vmlinux_path.display(),
502 )
503 })
504}
505
506#[cfg(test)]
507mod tests {
508 use super::*;
509 use crate::ktstr_test;
510
511 fn __ktstr_inner_unit_test_dummy(_ctx: &Ctx) -> Result<AssertResult> {
513 Ok(AssertResult::pass())
514 }
515
516 #[crate::ktstr_test_entry]
517 static __KTSTR_ENTRY_UNIT_TEST_DUMMY: KtstrTestEntry = KtstrTestEntry {
518 name: "__unit_test_dummy__",
519 func: __ktstr_inner_unit_test_dummy,
520 ..KtstrTestEntry::DEFAULT
521 };
522
523 #[test]
524 fn find_test_registered_entry() {
525 let entry = find_test("__unit_test_dummy__");
526 assert!(entry.is_some(), "registered entry should be found");
527 let entry = entry.unwrap();
528 assert_eq!(entry.name, "__unit_test_dummy__");
529 assert_eq!(entry.topology.llcs, 1);
530 assert_eq!(entry.topology.cores_per_llc, 2);
531 }
532
533 #[test]
534 fn find_test_nonexistent() {
535 assert!(find_test("__nonexistent_test_xyz__").is_none());
536 }
537
538 #[test]
539 fn find_test_from_distributed_slice() {
540 assert!(!KTSTR_TESTS.is_empty());
542 }
543
544 #[ktstr_test(cpu_budget = 7, host_only, no_perf_mode)]
553 fn cpu_budget_codegen_probe(_ctx: &Ctx) -> Result<AssertResult> {
554 Ok(AssertResult::pass())
555 }
556
557 #[ktstr_test(host_only)]
558 fn cpu_budget_codegen_probe_none(_ctx: &Ctx) -> Result<AssertResult> {
559 Ok(AssertResult::pass())
560 }
561
562 #[test]
563 fn cpu_budget_attr_emits_some() {
564 let e = find_test("cpu_budget_codegen_probe")
565 .expect("the cpu_budget probe entry must be registered");
566 assert_eq!(
567 e.cpu_budget,
568 Some(7),
569 "#[ktstr_test(cpu_budget = 7)] must emit cpu_budget: Some(7)"
570 );
571 }
572
573 #[test]
574 fn omitted_cpu_budget_defaults_none() {
575 let e = find_test("cpu_budget_codegen_probe_none")
576 .expect("the no-cpu_budget probe entry must be registered");
577 assert_eq!(
578 e.cpu_budget, None,
579 "omitting cpu_budget must leave the DEFAULT None (no field emitted)"
580 );
581 }
582}