PEPC-TOPOLOGY(1)

💖 PEPC-TOPOLOGY(1) 💖

okay bestie, gather round 🫶 this is the manual for the topology command — it lives in the General Commands Manual, section 1, and it's literally the little tool that tells you everything about your CPU's topology. sit down, hydrate, let's go ✨

---

🌸 Command topology 🌸

no cap, this is the main character. below are the general options it takes, and then the info subcommand that does the actual gossiping about your CPU layout 👑

---

💅 GENERAL OPTIONS 💅

• -h — show a short help message and dip. bye 👋
• -q — be quiet, bestie. only prints the important stuff (like warnings) 🤫
• -d — print debugging information. it's giving verbose 💀
• --debug-modules MODNAME[,MODNAME1,...] — so the -d option turns on ALL the debug messages, but this one narrows it down to just the modules you name. for example, -d --debug-modules MSR will only show debug messages from the MSR module. obsessed with the precision 🎀
• --version — print the version number and exit. periodt.
• -H HOSTNAME, --host HOSTNAME — host name or IP address of the target system. the pepc command gets executed on that system using SSH instead of running locally. if you don't specify it, the command just runs locally 🏠
• -U USERNAME, --username USERNAME — the name of the user to use for logging into the remote host over SSH. by default it looks up the user name in SSH configuration files, and if it's not found there, it uses the current user name 💁
• -K PRIVKEY, --priv-key PRIVKEY — path to the private SSH key for logging into the remote host. if you don't specify it, keys configured for the host in SSH configuration files (e.g. ~/.ssh/config) are used. if no keys are configured there, standard key files (e.g. ~/.ssh/id_rsa) and the SSH agent are tried 🔑
• -D DATASET, --dataset DATASET — ok so this one is for debugging and testing, iykyk. it specifies the dataset to use for emulating the host for running the command on. the datasets live in the pepc source code repository 📦

the argument can be a dataset path or name. if it's specified by name, these locations get searched for the dataset, in order:

1. ./tests/emul-data in the program's directory
2. $PEPC_DATA_PATH/tests/emul-data
3. $VIRTUAL_ENV/share/pepc/tests/emul-data
4. $HOME/.local/share/pepc/tests/emul-data
5. /usr/local/share/pepc/tests/emul-data
6. /usr/share/pepc/tests/emul-data

• --force-color — force colorized output even if the output stream is not a terminal (adds ANSI escape codes). slay, we love a rainbow that refuses to be silenced 🌈
• --print-man-path — print the pepc manual pages directory path and exit. add this path to the MANPATH environment variable to make the manual pages available to the man tool 📖

---

🦋 SUBCOMMAND info 🦋

display CPU topology details. this is the one that spills all the tea about your cores ☕

Note 1: the Linux kernel provides topology data only for online CPUs. for offline CPUs, unknown topology values (e.g., package number) are replaced with "?". mystery CPU energy 🙈

Note 2: for non-compute dies (dies without any CPUs, for example I/O dies on Granite Rapids Xeon), CPU, core, and module numbers are shown as "-". not me showing up to the table with nothing to contribute 💀

Note 3: topology data is read from multiple sources:

• Core and package numbers: /proc/cpuinfo
• Die numbers: /sys/devices/system/cpu/cpu<N>/topology/die_id
• Module numbers: /sys/devices/system/cpu/cpu<N>/cache/index2/id and shared_cpu_list
• NUMA node numbers: /sys/devices/system/node/node<N>/cpulist
• Hybrid core types: /sys/devices/cpu_core/cpus (P-cores), /sys/devices/cpu_atom/cpus (E-cores), /sys/devices/cpu_lowpower/cpus (LPE-cores, if available; otherwise LPE-cores are identified as CPUs lacking L3 cache, i.e., without /sys/devices/system/cpu/cpu<N>/cache/index3/shared_cpu_list)

---

✨ Options for info ✨

• --cpus CPUS — the list can include individual CPU numbers and CPU number ranges. for example, 1-4,7,8,10-12 would mean CPUs 1 to 4, CPUs 7, 8, and 10 to 12. use the special keyword all to specify all CPUs 💖
• --cores CORES — the list can include individual core numbers and core number ranges. for example, 1-4,7,8,10-12 would mean cores 1 to 4, cores 7, 8, and 10 to 12. use the special keyword all to specify all cores. core numbers are relative to the package 🎀
• --modules MODULES — the list can include individual module numbers and module number ranges. for example, 0,2-5 would mean module 0 and modules 2, 3, 4, and 5. use the special keyword all to specify all modules. heads up: unlike core and die numbers, module numbers are absolute 📍
• --dies DIES — the list can include individual die numbers and die number ranges. for example, 0-3,5 would mean dies 0 to 3, and die 5. use the special keyword all to specify all dies. on some systems, die numbers are globally unique, while on other systems they are relative to the package 🤔
• --packages PACKAGES — the list can include individual package numbers and package number ranges. for example, 0,2-4 would mean package 0 and packages 2 to 4. use the special keyword all to specify all packages 📦
• --core-siblings *CORE_SIBLINGS* — core siblings are CPUs sharing the same core. the list can include individual core sibling indices or index ranges. for example, if a core includes CPUs 2 and 3, index 0 would mean CPU 2 and index 1 would mean CPU 3. this option can only be used to reference online CPUs, because Linux does not provide topology information for offline CPUs. in the example with CPUs 2 and 3, if CPU 2 were offline, then index 0 would mean CPU 3. on Intel processors with hyper-threading, this is typically used to offline hyperthreads 🧵
• --module-siblings *MODULE_SIBLINGS* — module siblings are CPUs sharing the same module. the list can include individual module sibling indices or index ranges. for example, if a module includes CPUs 4, 5, 6, and 7, index 0 would mean CPU 4, index 1 would mean CPU 5, index 2 would mean CPU 6, and index 3 would mean CPU 7. this option can only be used to reference online CPUs, because Linux does not provide topology information for offline CPUs. in the example with CPUs 4, 5, 6, and 7, if CPU 5 were offline, then index 1 would mean CPU 6, index 2 would mean CPU 7, and index 3 would be invalid 🚫
• --order ORDER — by default, the topology table is sorted by CPU number. use this option to sort by core, module, die, node, or package number instead. supported values: cpu, core, module, die, node, package 🔢
• --online-only — include only online CPUs. by default, both online and offline CPUs are included 🌐
• --columns COLUMNS — comma-separated list of topology columns to display. available columns: CPU, core, module, die, node, package, hybrid, dtype. example: --columns Package,Core,CPU. by default, all relevant columns for the platform are shown. the "hybrid" column shows the core type (e.g., E-core or P-core) on hybrid platforms. the "dtype" column shows the die type for non-compute dies (e.g., I/O dies on Granite Rapids Xeon) 🗂️

---

and that's the whole page, bestie 🫶 no notes, ate and left no crumbs 👑 this was PEPC-TOPOLOGY(1) from the General Commands Manual — go forth and inspect your silicon, you iconic little sysadmin 💜✨