Module topology 

Topology view for the flow scheduler.

Copyright (c) 2026 Galih Tama galpt@v.recipes Delegates host discovery to scx_utils::Topology with a sysfs fallback, then seeds the BPF view in two best-effort phases. Phase one writes the primary rows with sibling plus node, and phase two refreshes the LLC bitmaps for the start log. Either phase keeps the BPF defaults on fault with no trap and no hot-path use. Sibling assumes two-way SMT as in sibling_cpus, so a third thread stays single with all ones. Span holds online CPUs at init, so the seed matches the sysfs online list with no hotplug use.

Re-exports

use scx_utils::Topology; 🔒

Constants

CPU_BOUND 🔒

CPU ids past this bound never seed, mirroring FLOW_MAX_CPUS.

NODE_BOUND 🔒

Node ids past this bound fold to zero, mirroring FLOW_MAX_NODES.

Functions

cpu_node 🔒

Node of one CPU with None on fault. Reads the NUMA view through the per CPU node links with a fallback to the node cpulists, so package ids never shape placement. A missing link plus a missing cpulist means unknown, so the caller folds to zero with no panic.

describe_topology

Short topology line for the start log. Shows cpus seeded with primary plus llcs counts, so the 4.8.14 start log carries primary plus llcs past the old cpus seeded line with no hot-path use.

fallback_rows 🔒

Fallback rows from the sysfs lists with the same shape. Sibling reads the thread list with all ones on fault, and node reads the NUMA view with zero on fault and a cap at sixteen.

init_topology

Build the seeded rows from the shared Topology view. Uses scx_utils::Topology as the source of truth with a sysfs fallback on fault, so large hosts fold to the machine queue with no panic and no extra scan on the hot paths. Span equals the online list at construction, sorted in rank order with the CPU plus node bounds, so the seed matches sysfs online with no extra view. Sibling follows sibling_cpus with two-way assumed, so extra threads on wider cores stay single with no extra scan.

is_smt_thread

True when the CPU is the second thread of one core. Sibling holds all ones on single thread, so single thread stays false with no panic. A lower sibling marks the second thread, so only one card per core shows SMT with no extra sysfs use. Two-way assumed as in sibling_cpus, so a third thread on wider cores stays single by design with no extra kick and no non-x86 walk.

node_from_cpulists 🔒

Node of one CPU from the node cpulists with None on fault. Scans the online nodes and returns the first node whose cpulist holds the CPU, so hosts without per CPU links still seed.

parse_cpu_list

Parse a kernel CPU list like 0-3 plus 5 into ids. Ranges clamp to the CPU bound before the walk, so a faulty list never loops the full u32 range. Ids past the bound never seed.

read_cpu_list_file

Read one kernel CPU list file into ids with empty on fault.

thread_sibling 🔒

Thread sibling of one CPU with None on fault.

topo_rows

One topology row per CPU with sibling plus node. Sibling comes from the core view with all ones on fault, and node folds to zero on fault with a cap at sixteen. A Topology failure falls back to the sysfs lists with the same shape and no panic.

write_llc_bitmaps

LLC bitmap texts for the start log, one entry per LLC. Best effort with empty on fault, so hosts without an LLC view log no bitmap with no trap and no hot-path use.

write_primary_bitmap

Primary bitmap text for the start log in rank order. Best effort with empty on fault, so a failed read never traps.