Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

[4ba6cc]: docs / man3 / pfm_get_event_encoding.3 Maximize Restore History

Download this file

pfm_get_event_encoding.3    86 lines (78 with data), 2.8 kB

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
.TH LIBPFM 4 "September, 2009" "" "Linux Programmer's Manual"
.SH NAME
pfm_get_event_encoding \- get raw event encoding
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_get_event_encoding(const char *" str ",int *" idx ", uint64_t *"code ", int *" count ");"
.sp
.SH DESCRIPTION
This function is used to retrieve the raw event encoding corresponding to the event string in \fBstr\fR.
The string may contain unit masks and modifiers and they will be taken into account. The encoding may
take several 64-bit integers. The function can use the array passed in \fBcode\fR if the number
of entries passed in \fBcount\fR is big enough. However, if both \fBcodes\fR is \fBNULL\fR and \fBcount\fR
are 0, the function allocates the memory necessary to store the encoding. It is up to the caller to
eventually free the memory. The number of 64-bit entries used is reflected in \fB*count\fR upon
return regardless of whether the \fBcodes\fR was allocated or used as is.
The raw encoding means the encoding as mandated by the underlying PMU model. It may not be directly suitable
to pass to a kernel API. You may want to use API-specific library calls to ensure the correct encoding is passed.
If the number of 64-bit integers is greater than one, then the order in which each component is returned is
PMU-model specific. Refer to the PMU specific man page.
Here is a example of how this function could be used:
.nf
#include <inttypes.h>
#include <err.h>
#include <perfmon/pfmlib.h>
int main(int argc, char **argv)
{
uint64_t *codes 0;
int count = 0;
int ret;
ret = pfm_initialize();
if (ret != PFMLIB_SUCCESS)
err(1", cannot initialize library %s", pfm_strerror(ret));
ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS:u", &codes, &count);
if (ret != PFM_SUCCESS)
err(1", cannot get encoding %s", pfm_strerror(ret));
for(i=0; i < count; i++)
printf("count[%d]=0x%"PRIx64"\\n", i, codes[i]);
free(codes);
return 0;
}
.fi
.SH RETURN
The function returns in \fBcodes\fR the encoding of the event and in \fBcount\fR the number
of 64-bit integers to support that encoding. Upon success, \fBPFM_SUCCESS\fR is returned otherwise
a specific error code is returned.
.SH ERRORS
.TP
.B PFM_ERR_TOOSMALL
The \fBcode\fR argument is too small for the encoding.
.TP
.B PFM_ERR_INVAL
The \fBcode\fR or \fBcount\fR argument is \fBNULL\fR.
.TP
.B PFM_ERR_NOMEM
Not enough memory.
.TP
.B PFM_ERR_NOTFOUND
Event not found.
.TP
.B PFM_ERR_ATTR
Invalid event attribute (unit mask or modifier)
.TP
.B PFM_ERR_ATTR_VAL
Invalid modifier value.
.TP
.B PFM_ERR_ATTR_SET
attribute already set, cannot be changed.
.TP
.B PFM_ERR_ATTR_UMASK
Missing unit mask.
.TP
.B PFM_ERR_ATTR_FEATCOMB
Unit masks or features cannot be combined into a single event.
.SH AUTHOR
Stephane Eranian <eranian@gmail.com>
.PP