pfm_get_event_encoding(3)

1LIBPFM(3)                  Linux Programmer's Manual                 LIBPFM(3)
2
3
4

NAME

6       pfm_get_event_encoding - get raw event encoding
7

SYNOPSIS

9       #include <perfmon/pfmlib.h>
10
11       int pfm_get_event_encoding(const char *str,int dfl_plm, char **fstr, int *idx, uint64_t *code, int *count);
12
13

DESCRIPTION

15       This  function is used to retrieve the raw event encoding corresponding
16       to the event string in str.  Only one event per call can be encoded. As
17       such,  str  can  contain  only one symbolic event name.  The string may
18       contain unit masks and modifiers. The default privilege level  mask  is
19       passed in dfl_plm.  It may be used depending on the event.
20
21       This     function     is    deprecated.    It    is    superseded    by
22       pfm_get_os_event_encoding() where the OS is set to PFM_OS_NONE.  Encod‐
23       ing is retrieve through the pfm_pmu_encode_arg_t structure.
24
25       The following examples illustrates the transition:
26
27          int i, count = 0;
28          uint64_t *codes;
29
30          ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, NULL, &codes, &count);
31          if (ret != PFM_SUCCESS)
32             err(1", cannot get encoding %s", pfm_strerror(ret));
33
34          for(i=0; i < count; i++)
35             printf("count[%d]=0x%"PRIx64"\n", i, codes[i]);
36
37       is equivalent to:
38
39          pfm_pmu_encode_arg_t arg;
40          int i;
41
42          memset(&arg, 0, sizeof(arg));
43          arg.size = sizeof(arg);
44
45          ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_NONE, &arg);
46          if (ret != PFM_SUCCESS)
47             err(1", cannot get encoding %s", pfm_strerror(ret));
48
49          for(i=0; i < arg.count; i++)
50             printf("count[%d]=0x%"PRIx64"\n", i, arg.codes[i]);
51
52          free(arg.codes);
53
54       The encoding may take several 64-bit integers. The function can use the array passed in code if the number
55       of entries passed in count is big enough. However, if both *codes is NULL and count
56       is 0, the function allocates the memory necessary to store the encoding. It is up to the caller to
57       eventually free the memory. The number of 64-bit entries in codes is reflected in *count upon
58       return regardless of whether the codes was allocated or used as is. If the number of 64-bit integers is
59       greater than one, then the order in which each component is returned is PMU-model specific. Refer to the PMU
60       specific man page.
61
62       The raw encoding means the encoding as mandated by the underlying PMU model. It may not be directly suitable
63       to pass to a kernel API. You may want to use API-specific library calls to ensure the correct encoding is passed.
64
65       If fstr is not NULL, it will point to the fully qualified event string upon successful return. The string
66       contains the event name, any umask set, and the value of all the modifiers. It reflects what the encoding will
67       actually measure. The function allocates the memory to store the string. The caller must eventually free the
68       string.
69
70       Here is a example of how this function could be used:
71       #include <inttypes.h>
72       #include <err.h>
73       #include <perfmon/pfmlib.h>
74       int main(int argc, char **argv)
75       {
76          uint64_t *codes 0;
77          int count = 0;
78          int ret;
79
80          ret = pfm_initialize();
81          if (ret != PFMLIB_SUCCESS)
82             err(1", cannot initialize library %s", pfm_strerror(ret));
83
84          ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, NULL, &codes, &count);
85          if (ret != PFM_SUCCESS)
86             err(1", cannot get encoding %s", pfm_strerror(ret));
87
88          for(i=0; i < count; i++)
89             printf("count[%d]=0x%"PRIx64"\n", i, codes[i]);
90
91          free(codes);
92          return 0;
93       }
94

RETURN

96       The  function returns in *codes the encoding of the event and in *count
97       the number of 64-bit integers to support that encoding.  Upon  success,
98       PFM_SUCCESS is returned otherwise a specific error code is returned.
99

ERRORS

101       PFM_ERR_TOOSMALL
102              The code argument is too small for the encoding.
103
104       PFM_ERR_INVAL
105              The code or count argument is NULL or the str contains more than
106              one symbolic event.
107
108       PFM_ERR_NOMEM
109              Not enough memory.
110
111       PFM_ERR_NOTFOUND
112              Event not found.
113
114       PFM_ERR_ATTR
115              Invalid event attribute (unit mask or modifier)
116
117       PFM_ERR_ATTR_VAL
118              Invalid modifier value.
119
120       PFM_ERR_ATTR_SET
121              attribute already set, cannot be changed.
122
123       PFM_ERR_ATTR_UMASK
124              Missing unit mask.
125
126       PFM_ERR_ATTR_FEATCOMB
127              Unit masks or features cannot be combined into a single event.
128

AUTHOR

130       Stephane Eranian <eranian@gmail.com>
131

NAME

SYNOPSIS

DESCRIPTION

RETURN

ERRORS

AUTHOR

SEE ALSO