1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
//! Read hardware performance counters on Apple Silicon.
//!
//! Every Apple Silicon chip (M1 through M5) has a Performance Monitoring Unit
//! (PMU): a set of dedicated hardware registers that count low-level CPU events
//! like retired instructions, elapsed cycles, branch mispredictions, and cache
//! misses. These are the same counters that power Instruments and `xctrace`.
//!
//! This crate wraps Apple's private `kperf.framework` and `kperfdata.framework`
//! to give you direct access to those counters from Rust. Both frameworks are
//! loaded at runtime via `dlopen`, so there is no link-time dependency on
//! private headers.
//!
//! # ⚠️ Experimental
//!
//! These frameworks are not part of any public SDK. Apple may change struct
//! layouts, rename symbols, or drop them entirely in any macOS update. Testing
//! requires root on physical hardware; the suite cannot run in CI, sandboxed
//! environments, or under Miri.
//!
//! # Quick start
//!
//! ```rust,ignore
//! use darwin_kperf::{Sampler, event::Event};
//!
//! let sampler = Sampler::new()?;
//! let mut thread = sampler.thread([Event::FixedInstructions, Event::FixedCycles])?;
//!
//! thread.start()?;
//! let before = thread.sample()?;
//! // ... do work ...
//! let after = thread.sample()?;
//! thread.stop()?;
//!
//! let instructions = after[0] - before[0];
//! let cycles = after[1] - before[1];
//! ```
//!
//! # Raw values and deltas
//!
//! [`ThreadSampler::sample`] returns the raw hardware counter values at the
//! moment you call it. These are running totals that the CPU maintains
//! internally; they do not reset between calls. To measure a specific region
//! of code, take two samples and subtract:
//!
//! ```rust,ignore
//! let before = thread.sample()?;
//! my_function();
//! let after = thread.sample()?;
//!
//! let instructions_in_my_function = after[0] - before[0];
//! ```
//!
//! The counters only track events on the calling thread, so other threads
//! running concurrently will not pollute your measurements.
//!
//! # Choosing events
//!
//! Apple Silicon CPUs have two kinds of performance counters: fixed and
//! configurable. Fixed counters are always available and always count the same
//! thing (instructions and cycles). Configurable counters can be programmed to
//! count any event the CPU supports, but there are only a handful of them
//! (typically 6 or 8), and you can only use as many configurable events as
//! there are configurable counter registers.
//!
//! For most use cases, [`Event::FixedInstructions`](event::Event::FixedInstructions)
//! and [`Event::FixedCycles`](event::Event::FixedCycles) are what you want.
//! Instruction counts are nearly deterministic for straight-line code, making
//! them ideal for benchmarking. Cycle counts reflect actual execution time on
//! the microarchitecture, but vary with frequency scaling and thermal state.
//!
//! If you need events like branch mispredictions or cache misses, use the
//! configurable counter variants from the [`Event`](event::Event) enum. The
//! [`Event::on`](event::Event::on) method resolves a chip-agnostic event name
//! to the correct hardware-specific name for the detected CPU.
//!
//! # Platform
//!
//! macOS only. Requires root or the `com.apple.private.kernel.kpc` entitlement.
//!
//! ```sh
//! sudo -E cargo test --package darwin-kperf -- --ignored --nocapture
//! ```
//!
//! # Related crates
//!
//! [`darwin-kperf-sys`] provides the raw FFI bindings if you need direct
//! access to the C function pointers and `repr(C)` structs.
//!
//! [`darwin-kperf-criterion`] plugs into Criterion.rs to benchmark with
//! hardware counters instead of wall-clock time.
//!
//! # References
//!
//! The API surface and struct layouts are derived from [ibireme's
//! `kpc_demo.c`][kpc-demo], a standalone C program that demonstrates the full
//! KPC/KPEP workflow on Apple Silicon.
//!
//! [kpc-demo]: https://gist.github.com/ibireme/173517c208c7dc333ba962c1f0d67d12
//! [`darwin-kperf-sys`]: https://docs.rs/darwin-kperf-sys
//! [`darwin-kperf-criterion`]: https://docs.rs/darwin-kperf-criterion
extern crate alloc;
pub use darwin_kperf_events as event;
pub
pub use LoadError;
pub use ;