Module topology 

Hybrid-capacity and cache-domain topology discovery.

Feeds the BPF CPU-selection path (select_cpu.bpf.c) two placement hints derived from the host topology:

1. The primary (big-core) set on asymmetric-capacity systems.
2. The per-LLC cache domains for LLC-aware wakeup placement.

Two phases:

1. init_topology() runs before scx_ops_load!(). It discovers the topology, computes the plans, and writes the rodata globals (rodata is frozen at load).
2. write_primary_bitmap() and write_llc_bitmaps() run after scx_ops_load!(). They write the CPU-membership bitmaps directly into the ARRAY maps (mlfq_primary_bitmap, mlfq_llc_bitmaps) that the CPU-selection path reads.

All discovery is best-effort: a placement hint must never abort the scheduler, so any failure leaves the bitmaps empty and the scheduler keeps working on the base behavior (uniform capacity, no LLC awareness).

Structs

CapacityPlan

Capacity-planning decision, separated from sysfs discovery so the pure logic is unit-testable without touching the host topology.

LlcPlan

Cache-domain planning decision, separated from sysfs discovery so the pure logic is unit-testable.

SiblingPlan

SMT sibling-planning decision, separated from sysfs discovery so the pure logic is unit-testable.

TopologyPlan

The two placement plans produced by init_topology().

Constants

MAX_CPUS 🔒

Compile-time CPU bound; must match MLFQ_MAX_CPUS in src/bpf/intf.h.

MAX_LLCS 🔒

Compile-time LLC bound; must match MLFQ_MAX_LLCS in src/bpf/intf.h.

MAX_LLC_CPUS 🔒

Compile-time per-LLC CPU-list bound; must match MLFQ_MAX_LLC_CPUS in src/bpf/intf.h.

Functions

bitmap_mask 🔒

Bit mask of @cpu within its bitmap word.

bitmap_word 🔒

Word index of @cpu within a CPU bitmap, matching the word layout of struct mlfq_bitmap in src/bpf/intf.h.

build_bitmap 🔒

Build a CPU-membership bitmap from a CPU list.

build_llc_cpu_list 🔒

Pack a CPU list into the mlfq_llc_cpu_list map value type.

current_freq_khz

Read a CPU’s current operating frequency from sysfs, in kHz. The scaling_cur_freq file reflects the live frequency of the CPU, whatever the governor is doing; a missing or unreadable file (no cpufreq driver) yields 0.

init_topology

Phase 1 (pre-load): discover the topology and write the rodata globals.

llc_cpu_list_for 🔒

Build the Tier-A CPU list one LLC domain publishes.

llc_size_bytes 🔒

Read the LLC cache size of one CPU from sysfs.

parse_cache_size 🔒

Parse a kernel cache size string (“32M”, “16384K”, plain bytes) into bytes. The kernel exposes cache sizes in the human-readable form with a K/M/G suffix; a parse failure yields None.

pick_largest_llc

Pick the LLC domain with the strictly-largest cache size.

plan_llcs

Build the LLC plan from a synthetic (cpu, llc) map.

plan_primary_mask

Decide the primary set from the discovered big cores.

plan_sibling_table

Plan the SMT sibling table from a synthetic (cpu, core) map.

smt_enabled

Whether SMT is active on the host, read from the kernel’s /sys/devices/system/cpu/smt/active interface. The knob is absent on systems without SMT support; a missing or unreadable knob yields None, so the caller can omit the SMT annotation from the startup banner rather than guessing.

web_cpu_static

Per-CPU static data for the web UI, seeded once at attach.

write_bitmap_value 🔒

Write @value into the ARRAY map @map at @key (a u32 key).

write_llc_bitmaps

Phase 2 (post-load): write the per-LLC membership bitmaps.

write_llc_cpu_list_value 🔒

Write @value into the ARRAY map @map at @key (a u32 key).

write_llc_cpu_lists

Phase 2 (post-load): write the per-LLC CPU lists into the mlfq_llc_cpus array map.

write_primary_bitmap

Phase 2 (post-load): write the primary (big-core) membership bitmap.