LIBPFM(3) Linux Programmer's Manual LIBPFM(3)NAME
pfm_get_cycle_event, pfm_get_inst_retired_event - get basic event
descriptors
SYNOPSIS
#include <perfmon/pfmlib.h>
int pfm_get_cycle_event(pfmlib_event_t *ev);
int pfm_get_inst_retired_event(pfmlib_event_t *ev);
DESCRIPTION
In order to build very simple generic examples that work across all PMU
models, the library provides a way to retrieve information about two
basic events that are present in most PMU models: cycles and instruc‐
tion retired. The first event, cycles, counts the number of elapsed
cycles. The second event, instruction retired, counts the number of
instructions that have executed and retired from the processor pipe‐
line. Depending on the PMU model, there may be variations in the exact
definition of those events. The library provides this information on a
best effort basis. User must refer to PMU model specific documentation
to validate the event definition.
The pfm_get_cycle_event() function returns in ev the event and optional
unit mask descriptors for the event that counts elapsed cycles. Depend‐
ing on the PMU model, there may be unit mask(s) necessary to count
cycles. Application must check the value returned in ev->num_masks.
The pfm_get_inst_retired_event() function returns in ev the event and
optional unit mask descriptors for the event that counts the number of
returned instruction. Depending on the PMU model, there may be unit
mask(s) necessary to count retired instructions. Application must check
the value returned in ev->num_masks.
RETURN
All functions return whether or not the call was successful. A return
value of PFMLIB_SUCCESS indicates success, otherwise the value is the
error code.
ERRORS
PFMLIB_ERR_NOINIT the library has not been initialized properly.
PFMLIB_ERR_INVAL
the ev parameter is NULL.
PFMLIB_ERR_NOTSUPP
the host PMU does not define an event to count cycles or
instructions retired.
AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
September, 2006 LIBPFM(3)
