Vendor perf event

1 files changed, 50 insertions, 0 deletions

diff --git a/perf-event/README.md b/perf-event/README.md
new file mode 100644
index 0000000..b6754cd
--- /dev/null
+++ b/perf-event/README.md
@@ -0,0 +1,50 @@
+## perf-event: a Rust interface to Linux performance monitoring
+
+This uses the Linux [`perf_event_open`][man] API to access performance monitoring
+hardware and software. Use `Builder` to create a perf event counter, then use
+`enable` and `disable` to start and stop counting. Call `read` to get your
+count.
+
+For example, this counts the number of cycles used by the call to `println!`.
+Try adjusting the length of the vector to see the cycle count change.
+
+    use perf_event::Builder;
+
+    fn main() -> std::io::Result<()> {
+        let mut counter = Builder::new().build()?;
+
+        let vec = (0..=51).collect::<Vec<_>>();
+
+        counter.enable()?;
+        println!("{:?}", vec);
+        counter.disable()?;
+
+        println!("{} instructions retired", counter.read()?);
+
+        Ok(())
+    }
+
+Since we don't specify what sort of event we want to count, `Builder` defaults
+to `PERF_COUNT_HW_INSTRUCTIONS` events, whose documentation says:
+
+> Retired instructions. Be careful, these can be affected by various issues,
+> most notably hardware interrupt counts.
+
+The `examples` directory includes programs that count other sorts of events.
+
+[man]: http://man7.org/linux/man-pages/man2/perf_event_open.2.html
+
+## See also
+
+The [`perfcnt`] crate provides more extensive coverage of the Linux
+`perf_event_open` API than this crate.
+
+Markus Stange's [`linux-perf-event-reader`][lper] supports events.
+This crate only handles counters for now.
+
+The [`not-perf`] project is a rewrite of `perf` in Rust, and has a
+bunch of code for dealing with the Linux perf API.
+
+[`perfcnt`]: https://crates.io/crates/perfcnt
+[lper]: https://crates.io/crates/linux-perf-event-reader
+[`not-perf`]: https://github.com/koute/not-perf