Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Glossary

The words this guide leans on, in one place. Kernel terms carry their kernel meaning; ktstr terms are defined by ktstr’s own behavior.

Kernel and sched_ext

TermMeaning
sched_extThe kernel’s BPF-extensible scheduler class: process schedulers written as BPF programs, attached via struct_ops.
EEVDFThe kernel’s default scheduler. Tests without a scheduler attribute run under it — the baseline ktstr compares against.
DSQDispatch queue — sched_ext’s task queues. Schedulers move tasks between DSQs; ktstr reads their depths from guest memory.
LLCLast-level cache. The cache domain schedulers optimize placement around, and one axis of every ktstr topology.
stallThe kernel scx watchdog’s word, and reserved for it here: a runnable task the scheduler failed to run within the watchdog timeout fires SCX_EXIT_ERROR_STALL and evicts the scheduler.
verifierThe kernel’s BPF verifier. The verifier sweep runs it — the real one, in the target kernel — against every declared scheduler.
BTFThe kernel’s type metadata. ktstr resolves struct offsets through it to read guest memory, and BPF skeletons load against it.
kfuncA kernel function exposed to BPF programs. Schedulers call scx_bpf_* kfuncs; kernels and headers must agree on their signatures.

Declaring tests

TermMeaning
topologyThe machine shape a test declares — NUMA nodes, LLCs, cores, threads — rendered 1n2l4c2t and realized in the guest. See Topology.
scenarioWhat the test does inside the VM: cgroups, workers, operations, expressed as data.
Step / Op / holdA scenario is Steps; each Step applies Ops (create, resize, destroy, write), builds its setup, then holds — the measured window. See Ops, Steps, and Backdrop.
phaseThe metrics bucket for one Step (plus a pre-run baseline). Per-phase metrics make before/after comparisons inside one run possible.
BackdropScenario furniture that persists across Steps instead of being torn down with the Step that made it.
work typeWhat a worker burns its time on — spin, futex ping-pong, schbench, taobench — 45 variants in all. See Work Types.
payloadAn external binary (fio, stress-ng, your tool) run as a workload, with metrics extracted from its output. See Payloads.

Checking results

TermMeaning
verdictThe four-state outcome lattice — Fail > Inconclusive > Pass > Skip; the most severe wins. See Checking.
no progressA worker that completed zero work units. Whether the scheduler denied it CPU or it wedged itself is more than the measurement claims.
stuckA worker whose gap between progress checkpoints exceeded the threshold — ktstr’s own liveness word (the kernel’s is stall, above).
unfairOff-CPU share spread across a cgroup’s workers beyond the threshold.
claimOne labeled assertion inside a Verdict — the accumulator custom scenarios use. claim_better compares candidate vs baseline with registry polarity.
projectionTurning a per-sample value — an scx_stats field, a BPF global or map entry, a host per-CPU reading — into a typed SeriesField column for temporal patterns and claims. See Projections.
sidecarThe per-test JSON stats file written under target/ktstr/{kernel}-{commit}/ — the raw material for stats and perf-delta.

Running at scale

TermMeaning
gauntletOne test declaration fanned out across topology presets (and kernels). Variants are named gauntlet/{test}/{preset} and skipped unless asked for.
presetA named topology in the gauntlet catalog — 4cpu-1llc-nosmt, 9cpu-3llc-nosmt, 2numa-128cpu-8llc-smt, 26 in all on x86_64.
cellOne (scheduler × kernel × preset) unit of the verifier sweep: verify, attach, dispatch.
perf-deltaThe regression gate comparing performance metrics between HEAD and a baseline commit, with --noise-adjust running both sides fresh. See Runs.
auto-reproOn a crash, the failing scenario reruns in a second VM with BPF probes on the crash call chain, capturing argument and struct state on the way to the error. See Auto-Repro.
performance modeExclusive host-LLC reservation for measurement-grade runs; budgeted (shared) mode is the default. See Resource Budget.