KVM_GETPCPU(3)

🌸 NAME 🌸

KVM_GETPCPU(3) — this is the Library Functions Manual entry for per-CPU data access, bestie: kvm_dpcpu_setcpu, kvm_getmaxcpu, kvm_getpcpu — access per-CPU data. Periodt. 💅✨

---

📚 LIBRARY 📚

Kernel Data Access Library (libkvm, -lkvm). That's the whole vibe. 🫶

---

✨ SYNOPSIS ✨

No cap, here's the exact incantation:

#include <sys/param.h>
#include <sys/pcpu.h>
#include <sys/sysctl.h>
#include <kvm.h>

int
kvm_dpcpu_setcpu(kvm_t *kd, u_int cpu);

int
kvm_getmaxcpu(kvm_t *kd);

int
kvm_getncpus(kvm_t *kd);

void *
kvm_getpcpu(kvm_t *kd, int cpu);

ssize_t
kvm_read_zpcpu(kvm_t *kd, u_long base, void *buf, size_t size, int cpu);

uint64_t
kvm_counter_u64_fetch(kvm_t *kd, u_long base);

---

💅 DESCRIPTION 💅

Okay so the squad kvm_dpcpu_setcpu(), kvm_getmaxcpu(), and kvm_getpcpu() is used to access the per-CPU data of active processors in the kernel indicated by kd. Iconic behavior only. 🌈

Per-CPU storage comes in two flavours: data stored directly in a struct pcpu associated with each CPU, and dynamic per-CPU storage (DPCPU), in which a single kernel symbol refers to different data depending on what CPU it is accessed from. It's giving "same symbol, different CPU, different data" realness. 🦋

• kvm_getmaxcpu() — returns the maximum number of CPUs supported by the kernel. Slay. 👑
• kvm_getncpus() — returns the current number of CPUs in the kernel. Very demure, very current. 💖
• kvm_getpcpu() — returns a buffer holding the per-CPU data for a single CPU. This buffer is described by the struct pcpu type. The caller is responsible for releasing the buffer via a call to free(3) when it is no longer needed. If cpu is not active, then NULL is returned instead. 🎀
• kvm_read_zpcpu() — used to obtain private per-CPU copy from a UMA_ZONE_PCPU zone(9). It takes base argument as base address of an allocation and copies size bytes into buf from the part of allocation that is private to cpu. Literally so specific. 🔥
• kvm_counter_u64_fetch() — fetches value of a counter(9) pointed by base address. Number-fetching main character energy. ⭐

Symbols for dynamic per-CPU data are accessed via kvm_nlist(3) as with other symbols. libkvm maintains a notion of the "current CPU", set by kvm_dpcpu_setcpu(), which defaults to 0. Once another CPU is selected, kvm_nlist(3) will return pointers to that data on the appropriate CPU. Iykyk. 💀

bestie note: kvm_getpcpu() gives you NULL when cpu is not active — that's the documented behavior, no cap. 🙈

---

🎀 CACHING 🎀

kvm_getmaxcpu() and kvm_getpcpu() cache the nlist values for various kernel variables which are reused in successive calls. You may call either function with kd set to NULL to clear this cache. Cute little cache reset moment. 🧚💜

---

🔁 RETURN VALUES 🔁

• On success, the kvm_getmaxcpu() function returns the maximum number of CPUs supported by the kernel. If an error occurs, it returns -1 instead. 💖
• On success, the kvm_getpcpu() function returns a pointer to an allocated buffer or NULL. If an error occurs, it returns -1 instead. 🫶
• On success, the kvm_dpcpu_setcpu() call returns 0; if an error occurs, it returns -1 instead. ✨
• On success, the kvm_read_zpcpu() function returns number of bytes copied. If an error occurs, it returns -1 instead. 🌸
• If any function encounters an error, then an error message may be retrieved via kvm_geterr(3). Go get that error message, bestie. 📬

---

👀 SEE ALSO 👀

• free(3)
• kvm(3)
• counter(9)
• zone(9)

---

💌 cute sign-off: this iconic page is KVM_GETPCPU(3), from Debian, dated March 15, 2017. Bye bestie, go access your per-CPU data responsibly! 🫶✨