• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

src/H03-May-2022-3,1592,940

.cargo-checksum.jsonH A D03-May-202289 11

.cargo_vcs_info.jsonH A D21-Aug-202074 65

.gitignoreH A D18-Dec-201930 43

Cargo.tomlH A D21-Aug-2020920 2422

Cargo.toml.orig-cargoH A D21-Aug-2020391 1614

LICENSE-APACHEH A D27-Mar-201710.6 KiB202169

LICENSE-MITH A D24-Nov-20171,023 2421

README.mdH A D18-Aug-20202.2 KiB4834

regenerate.shH A D19-Dec-2019226 137

wrapper.hH A D18-Dec-2019778 2417

README.md

1## Direct, unsafe Rust bindings for Linux's `perf_event_open` system call
2
3This crate exports `unsafe` Rust wrappers for Linux system calls for accessing
4performance monitoring counters and tracing facilities. This includes:
5
6- the processor's own performance monitoring registers
7- kernel counters for things like context switches and page faults
8- kernel tracepoints, kprobe, and uprobes
9- processor tracing facilities like Intel's Branch Trace Store (BTS)
10- hardware breakpoints
11
12This crate provides:
13
14- a Rust wrapper the Linux `perf_event_open` system call
15- Rust wrappers for the ioctls you can apply to a file descriptor returned by `perf_event_open`
16- bindings for `perf_event_open`'s associated header files, automatically generated by `bindgen`
17
18All functions are direct, `unsafe` wrappers for the underlying calls. They
19operate on raw pointers and raw file descriptors.
20
21For a type-safe API for basic functionality, see the [perf-event] crate.
22
23[perf-event]: https://crates.io/crates/perf-event
24
25### Updating the System Call Bindings
26
27The `bindings` module defines Rust equivalents for the types and constants used
28by the Linux `perf_event_open` system call and its related ioctls. These are
29generated automatically from the kernel's C header files, using [bindgen]. Both
30the interface and the underlying functionality are quite complex, and new
31features are added at a steady pace. To update the generated bindings:
32
33-   Run the `regenerate.sh` script, found in the same directory as this
34    `README.md` file. This runs bindgen and splices its output in the `bindings`
35    module's source code, preserving the documentation.
36
37-   Fix the comments in `src/lib.rs` explaining exactly which version of the
38    kernel headers you generated the bindings from.
39
40-   Update the crate's major version. Newer versions of the kernel headers may
41    add fields to structs, which is a breaking change. (As explained in the
42    module documentation, properly written user crates should not be affected,
43    but it seems unnecessary to risk `cargo update` breaking builds. When users
44    need new functionality from the bindings, they can update the major version
45    number of this crate they request.)
46
47[bindgen]: https://crates.io/crates/bindgen
48