corescout_substrate/lib.rs
1//! The substrate: hardware discovery and passive observation.
2//!
3//! **This is the only crate in the workspace that touches hardware.** It reads
4//! sysfs, procfs, `CPUID` and `perf_event_open`, and it produces
5//! [`MirrorSnapshot`](corescout_mirror::MirrorSnapshot)s. Every other crate
6//! either produces snapshots for it to publish, or consumes them.
7//!
8//! That is the load-bearing fact about the dependency graph. `corescout-model`,
9//! `corescout-observer` and their neighbours do not depend on this crate, so an
10//! observer cannot read `/sys` even by mistake: the code that would do it is not
11//! linked into its binary.
12//!
13//! # Layers here
14//!
15//! | module | responsibility |
16//! |---|---|
17//! | [`platform`] | the only `cfg(target_os)` in the project |
18//! | [`topology`] | platform-neutral model of what the CPU is made of |
19//! | [`discovery`] | turning topology into stable entities and relations |
20//! | [`observation`] | passive sensors, each declaring what looking costs |
21//! | [`reflector`] | the loop that binds sensors and produces reflections |
22//!
23//! # The rule this crate enforces
24//!
25//! > Observation belongs to the mirror. Intentional perturbation belongs to
26//! > experimentation.
27//!
28//! Every sensor here is passive: it reads state the machine maintains anyway,
29//! for its own reasons, whether or not anyone is looking. Nothing here runs a
30//! workload, moves a thread, changes a frequency or requests an idle state.
31//! Code that wants to do those things lives in `corescout-experiment` or
32//! `corescout-agency`.
33
34pub mod discovery;
35pub mod observation;
36pub mod platform;
37pub mod reflector;
38pub mod topology;
39
40#[doc(hidden)]
41pub mod test_support;
42
43pub use discovery::{Roots, Substrate};
44pub use reflector::Reflector;
45pub use topology::Topology;