8 stable releases
new 5.0.6 | Nov 20, 2024 |
---|---|
5.0.5 | May 30, 2024 |
5.0.3 | May 17, 2023 |
5.0.2 | Apr 23, 2023 |
4.0.0 | Apr 20, 2023 |
#201 in Unix APIs
586 downloads per month
Used in 4 crates
(2 directly)
395KB
10K
SLoC
Direct, unsafe Rust bindings for Linux's perf_event_open
system call
This crate exports unsafe
Rust wrappers for Linux system calls for accessing
performance monitoring counters and tracing facilities. This includes:
- the processor's own performance monitoring registers
- kernel counters for things like context switches and page faults
- kernel tracepoints, kprobe, and uprobes
- processor tracing facilities like Intel's Branch Trace Store (BTS)
- hardware breakpoints
This crate provides:
- a Rust wrapper the Linux
perf_event_open
system call - Rust wrappers for the ioctls you can apply to a file descriptor returned by
perf_event_open
- bindings for
perf_event_open
's associated header files, automatically generated bybindgen
All functions are direct, unsafe
wrappers for the underlying calls. They
operate on raw pointers and raw file descriptors.
For a type-safe API for basic functionality, see the perf-event2 crate.
Using perf types on other platforms
Even though Windows and Mac don't have the perf_event_open
system
call, the perf_event_open_sys
crate still builds on those platforms:
the type definitions in the bindings
module can be useful to code
that needs to parse perf-related data produced on Linux or Android
systems. The syscall and ioctl wrapper functions are not available.
Updating the System Call Bindings
The bindings
module defines Rust equivalents for the types and constants used
by the Linux perf_event_open
system call and its related ioctls. These are
generated automatically from the kernel's C header files, using bindgen. Both
the interface and the underlying functionality are quite complex, and new
features are added at a steady pace. To update the generated bindings:
-
Run the
regenerate.sh
script, found in the same directory as thisREADME.md
file. This runs bindgen and splices its output into thebindings
module's source code, preserving the documentation. -
If this resulted in any changes to the API, update the crate's major or minor version as appropriate. Most updates to the kernel headers will not actually affect the API at all, and even those that do may not require a new major version.
You can use
cargo-semver-checks
in order to verify that the resulting changes are semver-compatible.