Topology
Schedulers make placement decisions across LLC and NUMA boundaries — where to wake a task, when a migration is worth the cache cost. Each ktstr test declares the topology those decisions should be tested against, and the VM it runs in actually has it: the declared NUMA nodes, cache domains, and SMT siblings are what the guest kernel sees.
The notation
Topologies render as {n}n{l}l{c}c{t}t — NUMA nodes, LLCs, cores per
LLC, threads per core. One quirk to internalize:
Note
The
lcount is the total LLC count across the VM, not per-node.2n4l4c2tis 2 NUMA nodes and 4 LLCs total (2 per node), 4 cores per LLC, 2 threads per core = 4 × 4 × 2 = 32 vCPUs.
Containment is strict — threads in a core, cores in an LLC, LLCs in
a NUMA node — and guest CPUs are numbered sequentially through it.
1n2l4c2t (16 vCPUs) lays out as:
node 0
├─ LLC 0 ├─ LLC 1
│ ├─ core 0: cpu 0, 1 │ ├─ core 4: cpu 8, 9
│ ├─ core 1: cpu 2, 3 │ ├─ core 5: cpu 10, 11
│ ├─ core 2: cpu 4, 5 │ ├─ core 6: cpu 12, 13
│ └─ core 3: cpu 6, 7 │ └─ core 7: cpu 14, 15
Most tests use one NUMA node; multi-NUMA topologies matter when the scheduler weighs memory locality. The gauntlet sweeps a test across a whole preset matrix of these shapes.
What a test declares — and what it gets
The #[ktstr_test] attributes numa_nodes, llcs, cores,
threads declare the shape (see the
macro reference for defaults
and inheritance). The run output echoes the topology the guest
booted with — the [topo=...] tag in failure headers and the
timeline header:
ktstr_test 'throughput_gate' [sched=scx-ktstr] [topo=1n1l2c1t] failed:
...
topology: 1n1l2c1t (2 cpus) scheduler: my_sched scenario: throughput_gate duration: 15.0s
To see a host’s physical layout in the same vocabulary, ktstr topo:
CPUs: 64
LLCs: 4
NUMA nodes: 1
LLC 0 (node 0): [0, 1, 2, 3, 4, 5, 6, 7, 32, 33, 34, 35, 36, 37, 38, 39]
LLC 1 (node 0): [8, 9, 10, 11, 12, 13, 14, 15, 40, 41, 42, 43, 44, 45, 46, 47]
LLC 2 (node 0): [16, 17, 18, 19, 20, 21, 22, 23, 48, 49, 50, 51, 52, 53, 54, 55]
LLC 3 (node 0): [24, 25, 26, 27, 28, 29, 30, 31, 56, 57, 58, 59, 60, 61, 62, 63]
(Host CPU numbering differs from the guest’s sequential scheme — here SMT siblings sit 32 apart — which is exactly why tests declare a topology instead of inheriting the host’s.)
Cpusets from topology
Scenarios don’t hard-code CPU lists; a
CpusetSpec resolves against the test’s
topology at runtime. On 1n2l4c2t, CpusetSpec::Llc(0) resolves to
CPUs 0-7, so the cgroup’s cpuset.cpus is written as 0-7; Llc
and Numa cover their full domain, while the fractional and
partition variants (Range, Disjoint, Overlap) slice the
usable-CPU pool.
Querying topology from a scenario
Ctx.topo is a TestTopology. The queries scenario authors
actually use:
total_cpus(),num_llcs(),num_numa_nodes()— sizes, e.g. for skip guards (if ctx.topo.num_llcs() < 2 { return Ok(AssertResult::skip(...)) }).usable_cpus()/usable_cpuset()— CPUs available for workload placement. On topologies with more than 2 CPUs the last CPU is reserved for the root cgroup (on 8 CPUs: usable = 0-6). Built-in scenarios and fractionalCpusetSpecs use this pool automatically.llc_aligned_cpuset(idx)/numa_aligned_cpuset(node)— the CPU set of one LLC or one node’s LLCs.numa_nodes_for_cpuset(cpus)— which nodes a CPU set touches; this derives the expected-node set for NUMA checks.numa_distance(from, to)— kernel conventions: 10 local, higher is farther, 255 unreachable/unknown. VM topologies without explicit distances report 10 local / 20 remote.node_meminfo(node)/is_memory_only(node)— per-node memory and CXL-style memory-only node detection.
Ctx::cpuset_cpus(&spec) returns the CPU count a spec resolves to —
useful for sizing worker counts by hand. Its denominator is the
topology-level cpuset, not any cgroup’s currently-effective one; for
cgroup-aware sizing prefer
CgroupDef::workers_pct,
which resolves against the cgroup’s own cpuset at apply time.
The full method catalog (construction, LlcInfo, CPU-list parsing)
is in the
TestTopology rustdoc.
Memory policy
NUMA is the axis topology and memory placement share: a multi-node
topology gives the scheduler somewhere to get locality wrong, and
MemPolicy gives the test a way to measure it. It pins where each
worker’s pages live — pages that verifiably sit on specific nodes, so
placement decisions show up as page counts instead of guesswork.
MemPolicy wraps set_mempolicy(2) per worker (applied after fork,
before the work loop), and the NUMA checks
gate on where the pages actually landed. Pair it with multi-NUMA
gauntlet presets to sweep the same
test across node counts.
Force pages onto one node set when locality must be strict.
Bias allocation toward a node or set while allowing fallback.
Spread pages across nodes for bandwidth or cross-node fairness tests.
pub enum MemPolicy {
Default,
Bind(BTreeSet<usize>),
Preferred(usize),
Interleave(BTreeSet<usize>),
Local,
PreferredMany(BTreeSet<usize>),
WeightedInterleave(BTreeSet<usize>),
}
Default— inherit the parent’s policy; no syscall made.Bind(nodes)(MemPolicy::bind([0, 1])) — allocate only from these nodes (MPOL_BIND); allocation fails withENOMEMwhen they are exhausted.Preferred(node)(::preferred(0)) — prefer one node, fall back silently when it is full (MPOL_PREFERRED).Interleave(nodes)(::interleave([0, 1])) — round-robin allocations across the nodes (MPOL_INTERLEAVE).Local— nearest node to the allocating CPU (MPOL_LOCAL).PreferredMany(nodes)(::preferred_many([0, 1])) — prefer any of the nodes, fall back when all are full (MPOL_PREFERRED_MANY, kernel 5.15+).WeightedInterleave(nodes)(::weighted_interleave([0, 1])) — interleave proportional to the per-node weights in/sys/kernel/mm/mempolicy/weighted_interleave/(MPOL_WEIGHTED_INTERLEAVE, kernel 6.9+).
Node-set constructors accept any IntoIterator<Item = usize>.
MemPolicy::node_set() returns the referenced nodes (empty for
Default / Local).
MpolFlags
Optional mode flags OR’d into the set_mempolicy mode:
| Flag | Meaning |
|---|---|
NONE | No flags |
STATIC_NODES | Nodemask is absolute — not remapped when the task’s cpuset changes |
RELATIVE_NODES | Nodemask is relative to the task’s current cpuset |
NUMA_BALANCING | Enable NUMA-balancing optimization for this policy |
Flags combine with |. STATIC_NODES | RELATIVE_NODES is rejected
at setup time (the kernel would return EINVAL), as is any unknown
bit. The kernel accepts NUMA_BALANCING only alongside MPOL_BIND
or MPOL_PREFERRED_MANY — ktstr does not pre-validate that pairing,
so other combinations surface as EINVAL from the worker’s
set_mempolicy call.
Usage
WorkSpec and CgroupDef both take .mem_policy() and
.mpol_flags():
let def = CgroupDef::named("cg_0")
.cpuset(CpusetSpec::numa(0))
.workers(4)
.mem_policy(MemPolicy::bind([0]));
Cpuset validation
When a cgroup has a cpuset and no remapping flag is set, ktstr
validates at setup time that the policy’s nodes are reachable from
that cpuset — MemPolicy::Bind([1]) on a cgroup confined to node 0
fails before the run starts, not as a mystery ENOMEM mid-run.
The check is flag-aware: STATIC_NODES swaps it for a
node-exists-on-host check (the nodemask is absolute and deliberately
allowed outside the cpuset), and RELATIVE_NODES bypasses it (the
kernel remaps the ordinals internally). Policies without a node set
(Default, Local) skip validation.
What gets checked
Locality results feed the NUMA checking
thresholds — min_page_locality,
max_cross_node_migration_ratio, max_slow_tier_ratio. The
expected node set is derived from the cgroup’s cpuset at
evaluation time, not from the worker’s MemPolicy; in the common
case where memory is bound to the same nodes the cpuset pins, the
two coincide. A locality violation renders with the observed
fraction, the threshold, and the page counts (format from the
assertion source):
page locality <observed> (<pct>%) below threshold <min> (<pct>%) (<local>/<total> pages local)
Example: NUMA-aware locality test
use ktstr::prelude::*;
#[ktstr_test(
numa_nodes = 2, llcs = 4, cores = 4, threads = 1,
min_numa_nodes = 2, max_numa_nodes = 2,
min_page_locality = 0.8,
)]
fn numa_locality(ctx: &Ctx) -> Result<AssertResult> {
execute_defs(ctx, vec![
CgroupDef::named("node0")
.cpuset(CpusetSpec::numa(0))
.workers(4)
.mem_policy(MemPolicy::bind([0])),
CgroupDef::named("node1")
.cpuset(CpusetSpec::numa(1))
.workers(4)
.mem_policy(MemPolicy::bind([1])),
])
}
Each cgroup’s workers are pinned to one NUMA node’s CPUs via
CpusetSpec::numa() and their allocations bound to the same node
via MemPolicy::bind(); the test fails if less than 80% of pages
land where they were bound. The constraint pair
min_numa_nodes = 2, max_numa_nodes = 2 keeps gauntlet expansion on
two-node presets — single-node presets are filtered out rather than
failing. Both bounds are needed: the default constraints cap at one
NUMA node, and an inverted pair (min above max) is rejected at
validation time.
Related
- Gauntlet — preset topology matrices and the constraints that filter them.
- Resource Budget — how the host’s topology is carved up when tests run concurrently.