.TH LIBPFM 3  "December, 2009" "" "Linux Programmer's Manual"

.SH NAME

pfm_get_event_info \- get event information

.SH SYNOPSIS

.nf

.B #include <perfmon/pfmlib.h>

.sp

.BI "int pfm_get_event_info(int " idx ", pfm_os_t " os ", pfm_event_info_t *" info ");"

.sp

.SH DESCRIPTION

This function returns in \fBinfo\fR information about a specific event

designated by its opaque unique identifier in \fBidx\fR for the operating system

specified in \fBos\fR.

The \fBpfm_event_info_t\fR structure is defined as follows:

.nf

typedef struct {

        const char              *name;

        const char              *desc;

        const char              *equiv;

        size_t			size;

        uint64_t                code;

        pfm_pmu_t               pmu;

        pfm_dtype_t             dtype

        int                     idx;

        int                     nattrs;

        struct {

          unsigned int is_precise:1;

          unsigned int reserved_bits:31;

        };

} pfm_event_info_t;

.fi

The fields of this structure are defined as follows:

.TP

.B name

This is the name of the event. This is a read-only string.

.TP

.B desc

This is the description of the event. This is a read-only string. It may contain

multiple sentences.

.TP

.B equiv

Certain events may be just variations of actual events. They may be provided as

handy shortcuts to avoid supplying a long list of attributes. For those events,

this field is not NULL and contains the complete equivalent event string.

.TP

.B code

This is the raw event code. It should not be confused with the encoding

of the event. This field represents only the event selection code, it does

not include any unit mask or attribute settings.

.TP

.B pmu

This is the identification of the PMU model this event belongs to. It is

of type \fBpfm_pmu_t\fR. Using this value and the \fBpfm_get_pmu_info\fR

function, it is possible to get PMU information.

.TP

.B dtype

This field returns the representation of the event data. By default, it

is \fBPFM_DATA_UINT64\fR.

.B idx

This is the event unique opaque identifier. It is identical to the idx

passed to the call and is provided for completeness.

.TP

.B nattrs

This is the number of attributes supported by this event. Attributes

may be unit masks or modifiers. If the event has not attribute, then

the value of this field is simply 0.

.TP

.B size

This field contains the size of the struct passed. This field is used to provide

for extensibility of the struct without compromising backward compatibility.

The value should be set to \fBsizeof(pfm_event_info_t)\fR. If instead, a value of

\fB0\fR is specified, the library assumes the struct passed is identical to the

first ABI version which size is \fBPFM_EVENT_INFO_ABI0\fR. Thus, if fields were

added after the first ABI, they will not be set by the library. The library

does check that bytes beyond what is implemented are zeroes.

.TP

.B is_precise

This bitfield indicates whether or not the event support precise sampling.

Precise sampling is a hardware mechanism that avoids instruction address

skid when using interrupt-based sampling. When the event has umasks, this

field means that at least one umask supports precise sampling. On Intel X86

processors, this indicates whether the event supports Precise Event-Based

Sampling (PEBS).

.PP

The \fBpfm_os_t\fR enumeration provides the following choices:

.TP

.B PFM_OS_NONE

The returned information pertains only to what the PMU hardware exports.

No operating system attributes is taken into account.

.TP

.B PFM_OS_PERF_EVENT

The returned information includes the actual PMU hardware and the

additional attributes exported by the perf_events kernel interface.

The perf_event attributes pertain only the PMU hardware.

In case perf_events is not detected, an error is returned.

.TP

.B PFM_OS_PERF_EVENT_EXT

The returned information includes all of what is already provided

by \fBPFM_OS_PERF_EVENT\fR plus all the software attributes controlled

by perf_events, such as sampling period, precise sampling.

.PP

.SH RETURN

If successful, the function returns \fBPFM_SUCCESS\fR and event information

in \fBinfo\fR, otherwise it returns an error code.

.SH ERRORS

.TP

.B PFMLIB_ERR_NOINIT

Library has not been initialized properly.

.TP

.B PFMLIB_ERR_INVAL

The \fBidx\fR argument is invalid or \fBinfo\fR is \fBNULL\fR or \fBsize\fR

is not zero.

.TP

.B PFMLIB_ERR_NOTSUPP

The requested \fBos\fR is not detected or supported.

.SH AUTHOR

Stephane Eranian <eranian@gmail.com>

.PP