## 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 by `bindgen`

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-event] crate.

[perf-event]: https://crates.io/crates/perf-event

### 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 this
    `README.md` file. This runs bindgen and splices its output into the
    `bindings` 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`][semchecks] in order to verify that the
    resulting changes are semver-compatible. We don't always literally follow
    the standards set by cargo-semver-checks (e.g. some changes to
    `perf_event_attr` are actually fine) but it is generally a good starting
    point for determining whether the change is a breaking one.

[bindgen]: https://crates.io/crates/bindgen
[semchecks]: https://github.com/obi1kenobi/cargo-semver-checks
