Struct DynamicBuilder 

pub struct DynamicBuilder { /* private fields */ }

Builder for a Dynamic event.

The linux kernel exposes dynamic perfomance monitoring units (PMUs) using a special filesystem under /sys/bus/event_source/devices. This builder reads the config files for a specified PMU and allows you to set their values by using the kernel-specified names instead of having to directly set the right bits in the config fields.

If you find yourself having to use Dynamic and DynamicBuilder for an event please consider submitting a PR to add a native Event impl for it to this crate.

Fields and Parameters

Generally, kernel PMUs expose a few pieces of info:

• A format, which defines fields and indicates which bits they correspond to within perf_event_attr.
• A set of events, which contain values to assign to the the fields defined in the format.

Generally, all you need to do is to pick a PMU and an event within that PMU. Here’s how one would configure the Msr PMU using Dynamic:

use perf_event::events::Dynamic;

let event = Dynamic::builder("msr")?.event("tsc")?.build()?;

You can use perf list to get a list of which kernel PMU events are supported on the current machine. These will generally be listed in the format <pmu>/<event>/. Here is a sample of some of the events on my machine:

msr/aperf/                                         [Kernel PMU event]
msr/cpu_thermal_margin/                            [Kernel PMU event]
msr/mperf/                                         [Kernel PMU event]
msr/pperf/                                         [Kernel PMU event]
msr/smi/                                           [Kernel PMU event]
msr/tsc/                                           [Kernel PMU event]
power/energy-cores/                                [Kernel PMU event]
power/energy-gpu/                                  [Kernel PMU event]
power/energy-pkg/                                  [Kernel PMU event]
power/energy-psys/                                 [Kernel PMU event]
power/energy-ram/                                  [Kernel PMU event]

In most cases, the event file has values for all the fields contained in the format. However, for some events, the kernel leaves the field as an event parameter which must be set by the user. In that case, you must set the value for the field using the field method.

use perf_event::events::Dynamic;

let event = Dynamic::builder(&pmu)?
    .event("evt1")?
    .field("param", 32)?
    .build()?;

In cases where the kernel does not provide the desired event you can still set the fields directly. Whether this works properly will ultimately depend on the PMU itself. You will need to set all the fields or else build will return an error.

use perf_event::events::Dynamic;

let event = Dynamic::builder(&pmu)?
    .field("event", 77)?
    .field("param", 32)?
    .field("flag", 1)?
    .build()?;

Implementations

impl DynamicBuilder

pub fn new(pmu: impl AsRef<Path>) -> Result<Self>

Construct a new dynamic builder for the provided perf PMU.

pmu can be either

• an absolute path to the PMU directory, or,
• the name of a pmu under /sys/bus/event_source/devices.

This method will read the dynamic format configuration out of the PMU directory tree and configure the builder to use it.

Errors

This method reads the contents of the format directory. Any IO errors from this will be returned directly. Any errors from parsing will have kind io::ErrorKind::Other with the inner error being a DynamicBuilderError.

pub fn event(&mut self, event: impl AsRef<Path>) -> Result<&mut Self>

Initialize the builder for the specified event.

event can be either

• an absolute path to the event config file, or,
• the name of an event file under /sys/bus/event_source/devices/<pmu>/events.

Errors

This method reads the contents of the event file. Any IO errors from this will be returned directly. Any errors from parsing will have kind io::ErrorKind::Other with the inner error being a DynamicBuilderError.

pub fn field( &mut self, field: &str, value: u64, ) -> Result<&mut Self, DynamicBuilderError>

Set the value of a field.

This overwrites the previous value of the field, if there was one.

Errors

An error will be returned if

• field did not exist in the format description for the PMU, or,
• value was larger than the availabel bits for field.

pub fn build(&self) -> Result<Dynamic, MissingParameterError>

Build the Dynamic event type using the fields in this builder.

This will return an error if any event parameters have not been set to a value.

pub fn params(&self) -> impl Iterator<Item = &str>

Iterate over all unset parameter fields.

By default, no fields are parameter fields. They only become parameter fields when the event file contains <field>=?.

pub fn fields(&self) -> impl Iterator<Item = (&str, Option<u64>)>

Iterate over all fields in this builder.

pub fn scale(&self) -> Result<Option<f64>>

Read the scale factor of the event.

This is a value to be multiplied by the event count emitted by the kernel in order to convert the count to the unit as returned by unit. Not all events have a scale.

If event has not been specified then this method will always return an error.

pub fn unit(&self) -> Result<Option<String>>

Read the unit of the event.

This is a string describing the english unit that the event represents (once multiplied by scale). Not all events have a unit.

If event has not been specified then this method will always return an error.

Trait Implementations

impl Clone for DynamicBuilder

fn clone(&self) -> DynamicBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DynamicBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.