pmc/
lib.rs

1#![warn(missing_docs)]
2
3//! `pmc-rs` provides a safe abstraction for interacting with Performance
4//! Monitor Counters on [`FreeBSD`].
5//!
6//! PMCs are part of the CPU hardware and are typically used to profile CPU
7//! micro-architecture events such as L1/L2/etc cache hit ratio, instructions
8//! processed per CPU tick, TLB lookups, branch mispredictions, etc for a
9//! particular application or algorithm. Using PMCs an algorithm can be tuned
10//! for performance by minimising CPU stalls, optimising CPU cache usage, etc.
11//!
12//! The events are defined by the CPU manufacturer (here is the [Intel 64 and
13//! IA-32 Architectures Developer's Manual: vol.
14//! 3B](https://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-vol-3b-part-2-manual.html)
15//! where the events can be found in section `18.2.1.2 "Pre-defined
16//! Architectural Performance Events"`, `Table 18-1 "UMask and Event Select
17//! Encodings for Pre-Defined Architectural Performance Events"`).
18//!
19//! `pmc-rs` makes use of [`libpmc`] and the [`hwpmc`] kernel module on
20//! [`FreeBSD`].
21//!
22//! [`FreeBSD`]: https://www.freebsd.org/
23//! [`hwpmc`]: https://www.freebsd.org/cgi/man.cgi?query=hwpmc
24//! [`libpmc`]: https://www.freebsd.org/cgi/man.cgi?query=pmc
25
26#[macro_use]
27extern crate lazy_static;
28extern crate libc;
29
30mod error;
31pub use error::*;
32
33mod counter;
34pub use counter::*;
35
36#[cfg(not(target_os = "freebsd"))]
37mod stubs;
38
39#[cfg(not(target_os = "freebsd"))]
40const _CPU_ANY: i32 = -1;
41#[cfg(target_os = "freebsd")]
42const _CPU_ANY: i32 = pmc_sys::PMC_CPU_ANY;
43
44/// `Counter` instances allocated with `CPU_ANY` will measure events across all
45/// CPUs.
46///
47/// `CPU_ANY` is a convenience value for readability and should be preferred
48/// over using `0` directly.
49pub const CPU_ANY: i32 = _CPU_ANY;
50
51// TODO: add sampler type that records to a log file
pmc/lib.rs

pmc/
lib.rs
