|
Packit |
577717 |
.TH LIBPFM 3 "January, 2011" "" "Linux Programmer's Manual"
|
|
Packit |
577717 |
.SH NAME
|
|
Packit |
577717 |
pfm_get_os_event_encoding \- get event encoding for a specific operating system
|
|
Packit |
577717 |
.SH SYNOPSIS
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib.h>
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.BI "int pfm_get_os_event_encoding(const char *" str ", int " dfl_plm ", pfm_os_t " os ", void *" arg ");"
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH DESCRIPTION
|
|
Packit |
577717 |
This is the key function to retrieve the encoding of an event for a specific operating system
|
|
Packit |
577717 |
interface. The event string passed in \fBstr\fR is parsed and encoded for the operating system
|
|
Packit |
577717 |
specified by \fBos\fR. Only one event per call can be encoded. As such, \fBstr\fR can contain only
|
|
Packit |
577717 |
one symbolic event name. The event is encoded to monitor at the privilege levels specified
|
|
Packit |
577717 |
by the \fBdfl_plm\fR mask, if supported, otherwise this parameter is ignored. The operating
|
|
Packit |
577717 |
system specific input and output arguments are passed in \fBarg\fR.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The event string, \fBstr\fR, may contains sub-event masks (umask) and any other supported modifiers. Only one
|
|
Packit |
577717 |
event is parsed from the string. For convenience, it is possible to pass a comma-separated list
|
|
Packit |
577717 |
of events in \fBstr\fR but only the first event is encoded.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The following values are supported for \fBos\fR:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_OS_NONE
|
|
Packit |
577717 |
This value causes the event to be encoded purely as specified by the PMU hardware. The \fBarg\fR
|
|
Packit |
577717 |
argument must be a pointer to a \fBpfm_raw_pmu_encode_arg_t\fR structure which is defined as follows:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
uint64_t *codes;
|
|
Packit |
577717 |
char **fstr;
|
|
Packit |
577717 |
size_t size;
|
|
Packit |
577717 |
int count;
|
|
Packit |
577717 |
int idx;
|
|
Packit |
577717 |
} pfm_pmu_encode_arg_t;
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The fields are defined as follows:
|
|
Packit |
577717 |
.RS
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B codes
|
|
Packit |
577717 |
A pointer to an array of 64-bit values. On input, if \fBcodes\fR is NULL, then the library allocates
|
|
Packit |
577717 |
whatever is necessary to store the encoding of the event. If \fBcodes\fR is not NULL on input, then
|
|
Packit |
577717 |
\fBcount\fR must reflect its actual number of elements. If \fBcount\fR is big enough, the library
|
|
Packit |
577717 |
stores the encoding at the address provided. Otherwise, an error is returned.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B count
|
|
Packit |
577717 |
On input, the field contains the maximum number of elements in the array \fBcodes\fR. Upon return,
|
|
Packit |
577717 |
it contains the number of actual entries in \fBcodes\fR. If \fBcodes\fR is NULL, then count must
|
|
Packit |
577717 |
be zero.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B fstr
|
|
Packit |
577717 |
If the caller is interested in retrieving the fully qualified event string where all used unit masks
|
|
Packit |
577717 |
and all modifiers are spelled out, this field must be set to a non-null address of a pointer to a string (char **).
|
|
Packit |
577717 |
Upon return, if \fBfstr\fR was not NULL, then the string pointer passed on entry points to the event string. The string is
|
|
Packit |
577717 |
dynamically allocated and \fBmust\fR eventually be freed by the caller. If \fBfstr\fR was NULL on entry, then nothing is returned
|
|
Packit |
577717 |
in this field. The typical calling sequence looks as follows:
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
char *fstr = NULL
|
|
Packit |
577717 |
pfm_pmu_encode_arg_t arg;
|
|
Packit |
577717 |
arg.fstr = &fst;;
|
|
Packit |
577717 |
ret = pfm_get_os_event_encoding("event",
|
|
Packit |
577717 |
PFM_PLM0|PFM_PLM3,
|
|
Packit |
577717 |
PFM_OS_NONE,
|
|
Packit |
577717 |
&e);
|
|
Packit |
577717 |
if (ret == PFM_SUCCESS) {
|
|
Packit |
577717 |
printf("fstr=%s\n", fstr);
|
|
Packit |
577717 |
free(fstr);
|
|
Packit |
577717 |
}
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B size
|
|
Packit |
577717 |
This field contains the size of the struct passed. This field is used to provide
|
|
Packit |
577717 |
for extensibility of the struct without compromising backward compatibility.
|
|
Packit |
577717 |
The value should be set to \fBsizeof(pfm_pmu_encode_arg_t)\fR. If instead, a value of
|
|
Packit |
577717 |
\fB0\fR is specified, the library assumes the struct passed is identical to the
|
|
Packit |
577717 |
first ABI version which size is \fBPFM_RAW_ENCODE_ABI0\fR. Thus, if fields were
|
|
Packit |
577717 |
added after the first ABI, they will not be set by the library. The library
|
|
Packit |
577717 |
does check that bytes beyond what is implemented are zeroes.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B idx
|
|
Packit |
577717 |
Upon return, this field contains the opaque unique identifier for the event described in \fBstr\fR.
|
|
Packit |
577717 |
This index can be used to retrieve information about the event using \fBpfm_get_event_info()\fR, for instance.
|
|
Packit |
577717 |
.RE
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_OS_PERF_EVENT, PFM_OS_PERF_EVENT_EXT
|
|
Packit |
577717 |
This value causes the event to be encoded for the perf_event Linux kernel interface (available since 2.6.31).
|
|
Packit |
577717 |
The \fBarg\fR must be a pointer to a \fBpfm_perf_encode_arg_t\fR structure. The PFM_OS_PERF_EVENT layer
|
|
Packit |
577717 |
provides the modifiers exported by the underlying PMU hardware, some of which may actually be overridden
|
|
Packit |
577717 |
by the perf_event interface, such as the monitoring privilege levels. The \fBPFM_OS_PERF_EVENT_EXT\fR extends
|
|
Packit |
577717 |
\fBPFM_OS_EVENT\fR to add modifiers controlled only by the perf_event interface, such as sampling period (\fBperiod\fR),
|
|
Packit |
577717 |
frequency (\fBfreq\fR) and exclusive resource access (\fBexcl\fR).
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
struct perf_event_attr *attr;
|
|
Packit |
577717 |
char **fstr;
|
|
Packit |
577717 |
size_t size;
|
|
Packit |
577717 |
int idx;
|
|
Packit |
577717 |
int cpu;
|
|
Packit |
577717 |
int flags;
|
|
Packit |
577717 |
} pfm_perf_encode_arg_t;
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
The fields are defined as follows:
|
|
Packit |
577717 |
.RS
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B attr
|
|
Packit |
577717 |
A pointer to a struct perf_event_attr as defined in perf_event.h. This field cannot be NULL
|
|
Packit |
577717 |
on entry. The struct is not completely overwritten by the call. The library only modifies the
|
|
Packit |
577717 |
fields it knows about, thereby allowing perf_event ABI mismatch between caller and library.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B fstr
|
|
Packit |
577717 |
Same behavior as is described for PFM_OS_NONE above.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B size
|
|
Packit |
577717 |
This field contains the size of the struct passed. This field is used to provide
|
|
Packit |
577717 |
for extensibility of the struct without compromising backward compatibility.
|
|
Packit |
577717 |
The value should be set to \fBsizeof(pfm_perf_encode_arg_t)\fR. If instead, a value of
|
|
Packit |
577717 |
\fB0\fR is specified, the library assumes the struct passed is identical to the
|
|
Packit |
577717 |
first ABI version which size is \fBPFM_PERF_ENCODE_ABI0\fR. Thus, if fields were
|
|
Packit |
577717 |
added after the first ABI, they will not be set by the library. The library
|
|
Packit |
577717 |
does check that bytes beyond what is implemented are zeroes.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B idx
|
|
Packit |
577717 |
Upon return, this field contains the opaque unique identifier for the event described in \fBstr\fR.
|
|
Packit |
577717 |
This index can be used to retrieve information about the event using \fBpfm_get_event_info()\fR, for instance.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B cpu
|
|
Packit |
577717 |
Not used yet.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B flags
|
|
Packit |
577717 |
Not used yet.
|
|
Packit |
577717 |
.RE
|
|
Packit |
577717 |
.PP
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Here is a example of how this function could be used with PFM_OS_NONE:
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
#include <inttypes.h>
|
|
Packit |
577717 |
#include <err.h>
|
|
Packit |
577717 |
#include <perfmon/pfmlib.h>
|
|
Packit |
577717 |
int main(int argc, char **argv)
|
|
Packit |
577717 |
{
|
|
Packit |
577717 |
pfm_raw_pmu_encode_t raw;
|
|
Packit |
577717 |
int ret;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_initialize();
|
|
Packit |
577717 |
if (ret != PFMLIB_SUCCESS)
|
|
Packit |
577717 |
errx(1, "cannot initialize library %s", pfm_strerror(ret));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
memset(&raw, 0, sizeof(raw));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_NONE, &raw;;
|
|
Packit |
577717 |
if (ret != PFM_SUCCESS)
|
|
Packit |
577717 |
err(1", cannot get encoding %s", pfm_strerror(ret));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
for(i=0; i < raw.count; i++)
|
|
Packit |
577717 |
printf("count[%d]=0x%"PRIx64"\\n", i, raw.codes[i]);
|
|
Packit |
577717 |
|
|
Packit |
577717 |
free(raw.codes);
|
|
Packit |
577717 |
return 0;
|
|
Packit |
577717 |
}
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
.SH RETURN
|
|
Packit |
577717 |
The function returns in \fBarg\fR the encoding of the event for the os passed in \fBos\fR. The content
|
|
Packit |
577717 |
of \fBarg\fR depends on the \fBos\fR argument. Upon success, \fBPFM_SUCCESS\fR is returned otherwise
|
|
Packit |
577717 |
a specific error code is returned.
|
|
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 \fBcode\fR or \fBcount\fR argument is \fBNULL\fR or the \fBstr\fR contains more than one symbolic event.
|
|
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 |
.PP
|