Struct Topology 

pub struct Topology {
    pub llcs: u32,
    pub cores_per_llc: u32,
    pub threads_per_core: u32,
    pub numa_nodes: u32,
    pub nodes: Option<&'static [NumaNode]>,
    pub distances: Option<&'static NumaDistance>,
}

Re-exports of topology types for use in KtstrTestEntry statics generated by the #[ktstr_test] macro. CPU topology specification with NUMA memory topology.

Models the hierarchy: NUMA nodes → LLCs → cores → threads.

Each NUMA node owns a contiguous range of LLCs and a memory region. When nodes is None (the default), memory and LLCs are distributed uniformly across numa_nodes synthetic nodes with 10/20 distances.

Use new for the simple uniform case, or with_nodes for explicit per-node configuration.

Fields

llcs: u32

Total number of last-level caches across the whole VM; must be a multiple of numa_nodes when nodes is None.

cores_per_llc: u32

Physical cores grouped into each LLC.

threads_per_core: u32

Hardware threads exposed per core (1 = no SMT, 2 = SMT-2).

numa_nodes: u32

Number of NUMA nodes.

nodes: Option<&'static [NumaNode]>

Per-node configuration. When None, LLCs and memory are distributed uniformly. When Some, the slice length must equal numa_nodes and the sum of all NumaNode::llcs must equal self.llcs.

distances: Option<&'static NumaDistance>

Inter-node distance matrix. When None, distances default to 10 (local) / 20 (remote). When Some, the matrix dimension must equal numa_nodes.

Implementations

impl Topology

pub const DEFAULT_FOR_PAYLOAD: Topology

Fallback topology used by Payload::topology for binary-kind payloads that have no scheduler-side topology opinion. Matches the inline default in KtstrTestEntry::DEFAULT: 1 NUMA node / 1 LLC / 2 cores / 1 thread (2 CPUs total), the smallest VM shape that runs the harness meaningfully.

pub const fn new( numa_nodes: u32, llcs: u32, cores_per_llc: u32, threads_per_core: u32, ) -> Self

Validated const constructor for uniform topologies.

Produces a topology where LLCs and memory are distributed evenly across NUMA nodes, with default 10/20 distances.

See validate for a non-panicking alternative.

Panics

Panics if any invariant is violated:

• any of llcs, cores_per_llc, threads_per_core, numa_nodes is zero
• llcs is not divisible by numa_nodes
• total CPU count (llcs * cores_per_llc * threads_per_core) overflows u32

pub const fn with_nodes( cores_per_llc: u32, threads_per_core: u32, nodes: &'static [NumaNode], ) -> Self

Const constructor with explicit per-node configuration.

Total LLC count is computed from the sum of NumaNode::llcs across all nodes. Memory-only nodes (llcs=0) are permitted.

Panics

Panics if:

• nodes is empty
• cores_per_llc == 0
• threads_per_core == 0
• node LLC sum overflows u32
• a CPU-bearing node (llcs > 0) has memory_mib == 0
• total CPU count overflows u32
• no node has LLCs (at least one must have llcs > 0)

pub const fn distances(self, distances: &'static NumaDistance) -> Self

Attach a distance matrix.

Panics

Panics if distances.n != self.numa_nodes — the matrix dimension must equal the topology’s NUMA node count.

pub fn validate(&self) -> Result<(), String>

Non-panicking validation.

Returns Ok(()) if all invariants hold, or Err with a description of the first violated invariant.

pub fn total_cpus(&self) -> u32

Total vCPU count = llcs * cores_per_llc * threads_per_core.

pub fn num_llcs(&self) -> u32

Number of LLC domains in the topology.

pub fn num_numa_nodes(&self) -> u32

Number of NUMA nodes in the topology.

pub fn llcs_in_node(&self, node_id: u32) -> u32

LLCs owned by NUMA node node_id.

With explicit nodes, returns nodes[node_id].llcs. With uniform distribution, returns llcs / numa_nodes.

pub fn llcs_per_numa_node(&self) -> u32

LLCs per NUMA node (uniform distribution only).

Panics

Panics if the topology uses explicit nodes (use llcs_in_node instead), if numa_nodes == 0, or if llcs is not divisible by numa_nodes.

pub fn numa_node_of(&self, llc_id: u32) -> u32

NUMA node that owns the given LLC index.

With explicit nodes, walks the node list to find the owning node. With uniform distribution, computes llc_id / llcs_per_node.

Out-of-bounds llc_id (>= total LLCs): with explicit nodes, saturates to the last node index; with uniform distribution, no bounds check — returns llc_id / llcs_per_node, which may exceed numa_nodes - 1.

pub fn first_llc_in_node(&self, node_id: u32) -> u32

First LLC index owned by NUMA node node_id.

Uniform topologies do not bounds-check and return node_id * llcs_per_node for any input.

Panics

Panics if node_id > numa_nodes for explicit-node topologies (the walk would index past the end of the node slice).

pub fn node_memory_mib(&self, node_id: u32) -> Option<u32>

Memory in MiB for NUMA node node_id.

With explicit nodes, returns nodes[node_id].memory_mib. With uniform distribution, returns None (caller must divide total memory evenly).

pub fn total_node_memory_mib(&self) -> Option<u32>

Total memory across all explicit nodes, or None for uniform.

pub fn distance(&self, i: u32, j: u32) -> u8

Distance from node i to node j.

Returns the explicit distance if a matrix is attached, otherwise 10 for local and 20 for remote.

pub fn has_memory_only_nodes(&self) -> bool

Whether any node is memory-only (CXL).

pub fn cpu_bearing_nodes(&self) -> u32

Number of nodes that have CPUs (non-memory-only).

pub fn decompose(&self, cpu_id: u32) -> (u32, u32, u32)

Decompose a logical CPU ID into (llc, core, thread).

Trait Implementations

impl Clone for Topology

fn clone(&self) -> Topology

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Topology

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Topology

Formats as {numa}n{llcs}l{cores}c{threads}t — e.g. 1n2l4c2t = 1 NUMA node, 2 LLCs, 4 cores/LLC, 2 threads/core.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Topology> for TopologyJson

Project a Topology into its wire-format mirror. Drops the nodes and distances fields (uniform-distribution shape only); callers that need to preserve explicit per-node config or distance matrices must not use this conversion. Takes Topology by value (it derives Copy) to match the by-value shape of [From<TopologyConstraintsJson> for TopologyConstraints].

fn from(t: Topology) -> Self

Converts to this type from the input type.

impl FromStr for Topology

Parse the Display format back into a uniform Topology with nodes = None and distances = None.

Lossy round-trip

Only topologies built via Topology::new (uniform layout, no per-node configuration, default 10/20 distances) round-trip cleanly through Display → FromStr. A Topology built via Topology::with_nodes or chained with Topology::distances loses its per-node config + custom distance matrix through Display (which serializes only the 4 primitives); FromStr cannot reconstruct that information and produces a uniform Topology instead. Use the Topology value directly when full fidelity is required.

type Err = TopologyParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Topology

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Topology

fn eq(&self, other: &Topology) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<TopologyJson> for Topology

Result-based validation for wire-format topology values. Lets the verifier dispatch surface a per-cell “topology rejected” diagnostic instead of taking the Topology::new panic surface in the builder. Mirrors Topology::validate — any field == 0, overflow in total CPU count, or llcs not divisible by numa_nodes returns Err. The result is a uniform-distribution Topology (nodes = None, distances = None); explicit per-node config and distance matrices require constructing Topology directly.

type Error = String

The type returned in the event of a conversion error.

fn try_from(value: TopologyJson) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Topology

impl Eq for Topology

impl StructuralPartialEq for Topology