|
Packit |
577717 |
.TH LIBPFM 3 "September, 2009" "" "Linux Programmer's Manual"
|
|
Packit |
577717 |
.SH NAME
|
|
Packit |
577717 |
pfm_get_perf_event_encoding \- encode event for perf_event API
|
|
Packit |
577717 |
.SH SYNOPSIS
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib_perf_event.h>
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.BI "int pfm_get_perf_event_encoding(const char *" str ", int " dfl_plm ", struct perf_event_attr *" attr ", char **" fstr ", int *" idx ");"
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH DESCRIPTION
|
|
Packit |
577717 |
This function can be used in conjunction with the perf_events Linux kernel API which
|
|
Packit |
577717 |
provides access to hardware performance counters, kernel software counters and tracepoints.
|
|
Packit |
577717 |
The function takes an event string in \fBstr\fR and a default privilege level mask in \fBdfl_plm\fR
|
|
Packit |
577717 |
and fills out the relevant parts of the perf_events specific data structure in \fBattr\fR.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
This function is \fBdeprecated\fR. It is superseded by \fBpfm_get_os_event_encoding()\fR
|
|
Packit |
577717 |
with the OS argument set to either \fBPFM_OS_PERF_EVENT\fR or \fBPFM_OS_PERF_EVENT_EXT\fR.
|
|
Packit |
577717 |
Using this function provides extended support for perf_events. Certain perf_event configuration
|
|
Packit |
577717 |
option are only available through this new interface.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The following examples illustrates the transition:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
struct perf_event_attr attr;
|
|
Packit |
577717 |
int i, count = 0;
|
|
Packit |
577717 |
uint64_t *codes;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
memset(&attr, 0, sizeof(attr));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_get_perf_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, &attrs, NULL, NULL);
|
|
Packit |
577717 |
if (ret != PFM_SUCCESS)
|
|
Packit |
577717 |
err(1", cannot get encoding %s", pfm_strerror(ret));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
|
|
Packit |
577717 |
is equivalent to:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
#include <perfmon/pfmlib_perf_event.h>
|
|
Packit |
577717 |
struct perf_event_attr attr;
|
|
Packit |
577717 |
pfm_perf_encode_arg_t arg;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
memset(&arg, 0, sizeof(arg));
|
|
Packit |
577717 |
arg.size = sizeof(arg);
|
|
Packit |
577717 |
arg.attr = &att;;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_PERF, &arg;;
|
|
Packit |
577717 |
if (ret != PFM_SUCCESS)
|
|
Packit |
577717 |
err(1", cannot get encoding %s", pfm_strerror(ret));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The \fBdfl_plm\fR cannot be zero, though it may not necessarily be used by the event.
|
|
Packit |
577717 |
Depending on the event, combination of the following privilege levels may be used:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PLM3
|
|
Packit |
577717 |
Measure at privilege level 3. This usually corresponds to user level. On X86, it corresponds
|
|
Packit |
577717 |
to privilege levels 3, 2, 1. Check the PMU specific man page to verify if this level
|
|
Packit |
577717 |
is supported by your PMU model.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PLM2
|
|
Packit |
577717 |
Measure at privilege level 2. Check the PMU specific man page to verify if this level
|
|
Packit |
577717 |
is supported by your PMU model.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PLM1
|
|
Packit |
577717 |
Measure at privilege level 1. Check the PMU specific man page to verify if this level
|
|
Packit |
577717 |
is supported by your PMU model.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PLM0
|
|
Packit |
577717 |
Measure at privilege level 0. This usually corresponds to kernel level. Check the PMU
|
|
Packit |
577717 |
specific man page to verify if this level is supported by your PMU model.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PLMH
|
|
Packit |
577717 |
Measure at hypervisor privilege level. This is used in conjunction with hardware virtualization.
|
|
Packit |
577717 |
Check the PMU specific man page to verify if this level is supported by your PMU model.
|
|
Packit |
577717 |
.PP
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If \fBfstr\fR is not NULL, the function will make it point to the fully qualified event string,
|
|
Packit |
577717 |
i.e., a string with the event name, all unit masks set, and the value of all modifiers.
|
|
Packit |
577717 |
The library will allocate memory to store the event string but it is the responsibility of the
|
|
Packit |
577717 |
caller to eventually free that string using free().
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If \fBidx\fR is not NULL, it returns the corresponding unique event identifier.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Only select fields are modified by the function, the others are untouched.
|
|
Packit |
577717 |
The following fields in \fBattr\fR are modified:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B type
|
|
Packit |
577717 |
The type of the event
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B config
|
|
Packit |
577717 |
The encoding of the event
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B exclude_user
|
|
Packit |
577717 |
Whether or not user level execution should be excluded from monitoring. The definition
|
|
Packit |
577717 |
of user is PMU model specific.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B exclude_kernel
|
|
Packit |
577717 |
Whether or not kernel level execution should be excluded from monitoring. The definition
|
|
Packit |
577717 |
of kernel is PMU model specific.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B exclude_hv
|
|
Packit |
577717 |
Whether or not hypervisor level execution should be excluded from monitoring. The definition
|
|
Packit |
577717 |
of hypervisor is PMU model specific.
|
|
Packit |
577717 |
.PP
|
|
Packit |
577717 |
By default, if no privilege level modifier is specified in the event string, the library clears
|
|
Packit |
577717 |
\fBexclude_user\fR, \fBexclude_kernel\fR and \fBexclude_hv\fR, resulting in the event being
|
|
Packit |
577717 |
measured at all levels subject to hardware support.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The function is able to work on only one event at a time. For convenience, it accepts
|
|
Packit |
577717 |
event strings with commas. In that case, it will translate the first event up to the
|
|
Packit |
577717 |
first comma. This is handy in case tools gets passed events as a comma-separated list.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.SH RETURN
|
|
Packit |
577717 |
The function returns in \fBattr\fR the perf_event encoding which corresponds to the event
|
|
Packit |
577717 |
string. If \fBidx\fR is not NULL, then it will contain the unique event identifier upon
|
|
Packit |
577717 |
successful return. The value \fBPFM_SUCCESS\fR is returned if successful, otherwise a negative
|
|
Packit |
577717 |
error code is returned.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.SH ERRORS
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_TOOSMALL
|
|
Packit |
577717 |
The \fBcode\fR argument is too small for the encoding.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_INVAL
|
|
Packit |
577717 |
The \fBattr\fR argument is \fBNULL\fR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_NOMEM
|
|
Packit |
577717 |
Not enough memory.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_NOTFOUND
|
|
Packit |
577717 |
Event not found.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_ATTR
|
|
Packit |
577717 |
Invalid event attribute (unit mask or modifier)
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_ATTR_VAL
|
|
Packit |
577717 |
Invalid modifier value.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_ATTR_SET
|
|
Packit |
577717 |
attribute already set, cannot be changed.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_ATTR_UMASK
|
|
Packit |
577717 |
Missing unit mask.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_ERR_ATTR_FEATCOMB
|
|
Packit |
577717 |
Unit masks or features cannot be combined into a single event.
|
|
Packit |
577717 |
.SH AUTHOR
|
|
Packit |
577717 |
Stephane Eranian <eranian@gmail.com>
|
|
Packit |
577717 |
.SH SEE ALSO
|
|
Packit |
577717 |
pfm_get_os_event_encoding(3)
|