|
Packit |
577717 |
.TH LIBPFM 3 "September, 2009" "" "Linux Programmer's Manual"
|
|
Packit |
577717 |
.SH NAME
|
|
Packit |
577717 |
pfm_get_event_encoding \- get raw event encoding
|
|
Packit |
577717 |
.SH SYNOPSIS
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib.h>
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.BI "int pfm_get_event_encoding(const char *" str ",int " dfl_plm ", char **" fstr ", int *" idx ", uint64_t *"code ", int *" count ");"
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH DESCRIPTION
|
|
Packit |
577717 |
This function is used to retrieve the raw event encoding corresponding to the event string in \fBstr\fR.
|
|
Packit |
577717 |
Only one event per call can be encoded. As such, \fBstr\fR can contain only one symbolic event name.
|
|
Packit |
577717 |
The string may contain unit masks and modifiers. The default privilege level mask is passed in \fBdfl_plm\fR.
|
|
Packit |
577717 |
It may be used depending on the event.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
This function is \fBdeprecated\fR. It is superseded by \fBpfm_get_os_event_encoding()\fR where the OS is set to
|
|
Packit |
577717 |
\fBPFM_OS_NONE\fR. Encoding is retrieve through the \fBpfm_pmu_encode_arg_t\fR structure.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The following examples illustrates the transition:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
int i, count = 0;
|
|
Packit |
577717 |
uint64_t *codes;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, NULL, &codes, &count);
|
|
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 < count; i++)
|
|
Packit |
577717 |
printf("count[%d]=0x%"PRIx64"\\n", i, codes[i]);
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
|
|
Packit |
577717 |
is equivalent to:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
pfm_pmu_encode_arg_t arg;
|
|
Packit |
577717 |
int i;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
memset(&arg, 0, sizeof(arg));
|
|
Packit |
577717 |
arg.size = sizeof(arg);
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_NONE, &arg;;
|
|
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 < arg.count; i++)
|
|
Packit |
577717 |
printf("count[%d]=0x%"PRIx64"\\n", i, arg.codes[i]);
|
|
Packit |
577717 |
|
|
Packit |
577717 |
free(arg.codes);
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The encoding may take several 64-bit integers. The function can use the array passed in \fBcode\fR if the number
|
|
Packit |
577717 |
of entries passed in \fBcount\fR is big enough. However, if both \fB*codes\fR is \fBNULL\fR and \fBcount\fR
|
|
Packit |
577717 |
is 0, the function allocates the memory necessary to store the encoding. It is up to the caller to
|
|
Packit |
577717 |
eventually free the memory. The number of 64-bit entries in \fBcodes\fR is reflected in \fB*count\fR upon
|
|
Packit |
577717 |
return regardless of whether the \fBcodes\fR was allocated or used as is. If the number of 64-bit integers is
|
|
Packit |
577717 |
greater than one, then the order in which each component is returned is PMU-model specific. Refer to the PMU
|
|
Packit |
577717 |
specific man page.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The raw encoding means the encoding as mandated by the underlying PMU model. It may not be directly suitable
|
|
Packit |
577717 |
to pass to a kernel API. You may want to use API-specific library calls to ensure the correct encoding is passed.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If \fBfstr\fR is not NULL, it will point to the fully qualified event string upon successful return. The string
|
|
Packit |
577717 |
contains the event name, any umask set, and the value of all the modifiers. It reflects what the encoding will
|
|
Packit |
577717 |
actually measure. The function allocates the memory to store the string. The caller must eventually free the
|
|
Packit |
577717 |
string.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Here is a example of how this function could be used:
|
|
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 |
uint64_t *codes 0;
|
|
Packit |
577717 |
int count = 0;
|
|
Packit |
577717 |
int ret;
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_initialize();
|
|
Packit |
577717 |
if (ret != PFMLIB_SUCCESS)
|
|
Packit |
577717 |
err(1", cannot initialize library %s", pfm_strerror(ret));
|
|
Packit |
577717 |
|
|
Packit |
577717 |
ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, NULL, &codes, &count);
|
|
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 < count; i++)
|
|
Packit |
577717 |
printf("count[%d]=0x%"PRIx64"\\n", i, codes[i]);
|
|
Packit |
577717 |
|
|
Packit |
577717 |
free(codes);
|
|
Packit |
577717 |
return 0;
|
|
Packit |
577717 |
}
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
.SH RETURN
|
|
Packit |
577717 |
The function returns in \fB*codes\fR the encoding of the event and in \fB*count\fR the number
|
|
Packit |
577717 |
of 64-bit integers to support that encoding. 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 |
.SH SEE ALSO
|
|
Packit |
577717 |
pfm_get_os_event_encoding(3)
|