darwin_kperf_sys/lib.rs
1//! Raw FFI bindings for Apple's private `kperf.framework` and `kperfdata.framework`.
2//!
3//! Low-level, `#![no_std]` bindings to the two private macOS frameworks behind
4//! hardware performance monitoring counters (PMCs). The safe [`darwin-kperf`]
5//! crate is built on top of these.
6//!
7//! # ⚠️ Experimental
8//!
9//! These frameworks are not part of any public SDK. Apple may change struct
10//! layouts, function signatures, or remove symbols entirely in any macOS
11//! update. The `repr(C)` structs in this crate have compile-time layout
12//! assertions, but those only validate the macOS version you build against.
13//!
14//! # Frameworks
15//!
16//! **`kperf.framework`** contains the Kernel Performance Counter (KPC) and
17//! Kernel Performance (KPERF) interfaces. KPC functions configure which counter
18//! classes are active, program hardware register values, and read back
19//! per-thread or per-CPU counter accumulations. KPERF functions manage the
20//! sampling subsystem: actions, timers, and trigger-based profiling. All of
21//! these are thin wrappers around `sysctl` calls into the XNU kernel. See the
22//! [`kperf`] module.
23//!
24//! **`kperfdata.framework`** contains the Kernel Performance Event Programming
25//! (KPEP) interface. KPEP manages the PMC event database: the plist files
26//! shipped in `/usr/share/kpep/` that describe every hardware event a given CPU
27//! supports. It provides functions to open a database for the current CPU, look
28//! up events by name or alias, and build the register configuration that KPC
29//! expects. See the [`kperfdata`] module.
30//!
31//! # Runtime loading
32//!
33//! These frameworks are private, have no public headers, and no stable ABI, so
34//! this crate loads them at runtime via `dlopen(3)` / `dlsym(3)` rather than
35//! linking against them directly. Runtime loading also lets callers provide
36//! alternative framework paths if needed. Each function pointer is resolved
37//! into a [`VTable`](kperf::VTable). The [`load`] module provides the
38//! underlying [`LibraryHandle`](load::LibraryHandle) and
39//! [`LibrarySymbol`](load::LibrarySymbol) primitives, with no dependency on
40//! `libc` or `libloading`. Resolution is all-or-nothing: if any symbol is
41//! missing, loading fails with a [`LoadError`](load::LoadError).
42//!
43//! # Platform
44//!
45//! macOS only (`x86_64` and `aarch64`). Root privileges are required to
46//! force-acquire counters and read thread-level PMC values.
47//!
48//! # Safety
49//!
50//! Everything in this crate is `unsafe`. The function pointer type aliases
51//! describe C calling conventions with raw pointers, and the `repr(C)` structs
52//! mirror kernel data structures whose layout Apple does not guarantee. Callers
53//! must uphold the documented preconditions for every FFI call: buffer sizes,
54//! pointer validity, and thread-safety constraints.
55//!
56//! For a safe interface, use [`darwin-kperf`] instead.
57//!
58//! # References
59//!
60//! API surface and struct layouts are derived from [ibireme's
61//! `kpc_demo.c`][kpc-demo], a standalone C program that demonstrates the full
62//! KPC/KPEP workflow on Apple Silicon.
63//!
64//! [`darwin-kperf`]: https://docs.rs/darwin-kperf
65//! [kpc-demo]: https://gist.github.com/ibireme/173517c208c7dc333ba962c1f0d67d12
66#![cfg(target_os = "macos")]
67#![cfg_attr(docsrs, feature(doc_cfg))]
68#![expect(unsafe_code)]
69#![no_std]
70
71extern crate alloc;
72
73pub mod kperf;
74pub mod kperfdata;
75pub mod load;