1 files changed, 47 insertions, 0 deletions
diff --git a/vendor/perf-event-open-sys/README.md b/vendor/perf-event-open-sys/README.md
new file mode 100644
index 000000000..faf43d4ff
--- /dev/null
+++ b/vendor/perf-event-open-sys/README.md
@@ -0,0 +1,47 @@
+## 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
+
+### 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 in the `bindings`
+    module's source code, preserving the documentation.
+
+-   Fix the comments in `src/lib.rs` explaining exactly which version of the
+    kernel headers you generated the bindings from.
+
+-   Update the crate's major version. Newer versions of the kernel headers may
+    add fields to structs, which is a breaking change. (As explained in the
+    module documentation, properly written user crates should not be affected,
+    but it seems unnecessary to risk `cargo update` breaking builds. When users
+    need new functionality from the bindings, they can update the major version
+    number of this crate they request.)
+
+[bindgen]: https://crates.io/crates/bindgen