darwin-kperf 0.1.0

Safe Rust bindings for Apple's kperf/kpc hardware performance counters
Documentation 
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

[license]: https://github.com/hashintel/hash/blob/main/libs/darwin-kperf/LICENSE.md
[Apache License, Version 2.0]: https://github.com/hashintel/hash/blob/main/libs/darwin-kperf/LICENSE-APACHE.md
[MIT license]: https://github.com/hashintel/hash/blob/main/libs/darwin-kperf/LICENSE-MIT.md

# darwin-kperf

**Rust bindings to Apple's `kperf` kernel performance monitoring framework.**

> **⚠️ Experimental.** These crates depend on Apple's *private* `kperf.framework`
> and `kperfdata.framework`, which are not part of any public SDK and carry no ABI
> stability guarantee. Apple may change struct layouts, function signatures, or
> remove symbols entirely in any macOS update. Additionally, meaningful testing
> requires root privileges on physical Apple Silicon hardware. The test suite
> cannot run in CI, sandboxed environments, or under Miri (FFI boundary).

`kperf` is a private macOS framework that exposes hardware performance counters (CPU cycles, instructions retired, cache misses, branch mispredictions, etc.) with extremely low overhead. It is the same infrastructure backing Instruments and `xctrace`.

## Crates

| Crate | Description |
| --- | --- |
| [`darwin-kperf`](.) | Safe Rust API for configuring and sampling performance counters |
| [`darwin-kperf-sys`](sys) | Raw FFI bindings to `kperf.framework` and `kperfdata.framework` |
| [`darwin-kperf-events`](events) | Apple Silicon PMU event definitions (M1-M5), auto-generated from plist databases |
| [`darwin-kperf-criterion`](criterion) | Criterion.rs measurement plugin for hardware-counter benchmarking |

## Platform support

macOS only. Requires root privileges or the `com.apple.private.kernel.kpc` entitlement to access performance counters.

## Example

```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];
```

## Testing

All integration tests require root and are marked `#[ignore]`:

```sh
sudo -E cargo test --package darwin-kperf -- --ignored --nocapture
```

## References

- [ibireme's `kpc_demo.c`](https://gist.github.com/ibireme/173517c208c7dc333ba962c1f0d67d12): the reference C implementation this crate is modeled after.

## Contributors

`darwin-kperf` was created by [Bilal Mahmoud](https://github.com/indietyp). It is being developed in conjunction with [HASH](https://hash.dev/) as an open-source project. We gratefully accept external contributions and have published a [contributing guide](https://github.com/hashintel/hash/blob/main/.github/CONTRIBUTING.md) that outlines the process. If you have questions, please create a [discussion](https://github.com/orgs/hashintel/discussions). You can also report bugs [directly on the GitHub repo](https://github.com/hashintel/hash/issues/new/choose).

## License

`darwin-kperf` is available under either of the [Apache License, Version 2.0] or [MIT license] at your option. Please see the [LICENSE] file to review your options.