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).

Re-exports

use std::mem::size_of; 🔒

use std::path::Path; 🔒

use anyhow::Context; 🔒

use anyhow::Result; 🔒

use libbpf_rs::MapCore; 🔒

use libbpf_rs::MapFlags; 🔒

use log::info; 🔒

use log::warn; 🔒

use scx_utils::Powermode; 🔒

use scx_utils::Topology; 🔒

use scx_utils::get_primary_cpus; 🔒

use crate::bpf_intf::mlfq_bitmap; 🔒

use crate::bpf_intf::mlfq_consts_MLFQ_BITMAP_WORDS; 🔒

use crate::bpf_intf::mlfq_consts_MLFQ_MAX_CPUS; 🔒

use crate::bpf_intf::mlfq_consts_MLFQ_MAX_LLC_CPUS; 🔒

use crate::bpf_intf::mlfq_consts_MLFQ_MAX_LLCS; 🔒

use crate::bpf_intf::mlfq_llc_cpu_list; 🔒

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.