HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN |ERRORS |AUTHOR |COLOPHON | |
LIBPFM(3) Linux Programmer's ManualLIBPFM(3)pfm_get_os_event_encoding - get event encoding for a specific operating system
#include <perfmon/pfmlib.h>int pfm_get_os_event_encoding(const char *str, intdfl_plm, pfm_os_tos, void *arg);
This is the key function to retrieve the encoding of an event for a specific operating system interface. The event string passed instris parsed and encoded for the operating system specified byos. Only one event per call can be encoded. As such,strcan contain only one symbolic event name. The event is encoded to monitor at the privilege levels specified by thedfl_plmmask, if supported, otherwise this parameter is ignored. The operating system specific input and output arguments are passed inarg. The event string,str, may contains sub-event masks (umask) and any other supported modifiers. Only one event is parsed from the string. For convenience, it is possible to pass a comma-separated list of events instrbut only the first event is encoded. The following values are supported foros:PFM_OS_NONE This value causes the event to be encoded purely as specified by the PMU hardware. Theargargument must be a pointer to apfm_pmu_encode_arg_tstructure which is defined as follows: typedef struct { uint64_t *codes; char **fstr; size_t size; int count; int idx; } pfm_pmu_encode_arg_t; The fields are defined as follows:codesA pointer to an array of 64-bit values. On input, ifcodesis NULL, then the library allocates whatever is necessary to store the encoding of the event. Ifcodesis not NULL on input, thencountmust reflect its actual number of elements. Ifcountis big enough, the library stores the encoding at the address provided. Otherwise, an error is returned.countOn input, the field contains the maximum number of elements in the arraycodes. Upon return, it contains the number of actual entries incodes. Ifcodesis NULL, then count must be zero.fstrIf the caller is interested in retrieving the fully qualified event string where all used unit masks and all modifiers are spelled out, this field must be set to a non-null address of a pointer to a string (char **). Upon return, iffstrwas not NULL, then the string pointer passed on entry points to the event string. The string is dynamically allocated andmusteventually be freed by the caller. Iffstr was NULL on entry, then nothing is returned in this field. The typical calling sequence looks as follows: char *fstr = NULL pfm_pmu_encode_arg_t arg; arg.fstr = &fstr; ret = pfm_get_os_event_encoding("event", PFM_PLM0|PFM_PLM3, PFM_OS_NONE, &e); if (ret == PFM_SUCCESS) { printf("fstr=%s\n", fstr); free(fstr); }sizeThis field contains the size of the struct passed. This field is used to provide for extensibility of the struct without compromising backward compatibility. The value should be set tosizeof(pfm_pmu_encode_arg_t). If instead, a value of0is specified, the library assumes the struct passed is identical to the first ABI version which size isPFM_RAW_ENCODE_ABI0. Thus, if fields were added after the first ABI, they will not be set by the library. The library does check that bytes beyond what is implemented are zeroes.idxUpon return, this field contains the opaque unique identifier for the event described instr. This index can be used to retrieve information about the event usingpfm_get_event_info(), for instance.PFM_OS_PERF_EVENT, PFM_OS_PERF_EVENT_EXT This value causes the event to be encoded for the perf_event Linux kernel interface (available since 2.6.31). Theargmust be a pointer to apfm_perf_encode_arg_t structure. The PFM_OS_PERF_EVENT layer provides the modifiers exported by the underlying PMU hardware, some of which may actually be overridden by the perf_event interface, such as the monitoring privilege levels. ThePFM_OS_PERF_EVENT_EXTextendsPFM_OS_PERF_EVENTto add modifiers controlled only by the perf_event interface, such as sampling period (period), frequency (freq) and exclusive resource access (excl). typedef struct { struct perf_event_attr *attr; char **fstr; size_t size; int idx; int cpu; int flags; } pfm_perf_encode_arg_t; The fields are defined as follows:attrA pointer to a struct perf_event_attr as defined in perf_event.h. This field cannot be NULL on entry. The struct is not completely overwritten by the call. The library only modifies the fields it knows about, thereby allowing perf_event ABI mismatch between caller and library.fstrSame behavior as is described for PFM_OS_NONE above.sizeThis field contains the size of the struct passed. This field is used to provide for extensibility of the struct without compromising backward compatibility. The value should be set tosizeof(pfm_perf_encode_arg_t). If instead, a value of0is specified, the library assumes the struct passed is identical to the first ABI version which size isPFM_PERF_ENCODE_ABI0. Thus, if fields were added after the first ABI, they will not be set by the library. The library does check that bytes beyond what is implemented are zeroes.idxUpon return, this field contains the opaque unique identifier for the event described instr. This index can be used to retrieve information about the event usingpfm_get_event_info(), for instance.cpuNot used yet.flagsNot used yet. Here is a example of how this function could be used with PFM_OS_NONE: #include <inttypes.h> #include <err.h> #include <perfmon/pfmlib.h> int main(int argc, char **argv) { pfm_pmu_encode_arg_t arg; int i, ret; ret = pfm_initialize(); if (ret != PFM_SUCCESS) errx(1, "cannot initialize library %s", pfm_strerror(ret)); memset(&arg, 0, sizeof(arg)); ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_NONE, &arg); if (ret != PFM_SUCCESS) err(1, "cannot get encoding %s", pfm_strerror(ret)); for(i = 0; i < arg.count; i++) printf("count[%d]=0x%"PRIx64"\n", i, arg.codes[i]); free(arg.codes); return 0; }The function returns inargthe encoding of the event for the os passed inos. The content ofargdepends on theosargument. Upon success,PFM_SUCCESSis returned otherwise a specific error code is returned.
PFM_ERR_TOOSMALL Thecodeargument is too small for the encoding.PFM_ERR_INVAL Thecodeorcountargument isNULLor thestrcontains more than one symbolic event.PFM_ERR_NOMEM Not enough memory.PFM_ERR_NOTFOUND Event not found.PFM_ERR_ATTR Invalid event attribute (unit mask or modifier)PFM_ERR_ATTR_VAL Invalid modifier value.PFM_ERR_ATTR_SET attribute already set, cannot be changed.PFM_ERR_ATTR_UMASK Missing unit mask.PFM_ERR_ATTR_FEATCOMB Unit masks or features cannot be combined into a single event.
Stephane Eranian <eranian@gmail.com>
This page is part of theperfmon2 (a performance monitoring library) project. Information about the project can be found at ⟨http://perfmon2.sourceforge.net/⟩. If you have a bug report for this manual page, send it to perfmon2-devel@lists.sourceforge.net. This page was obtained from the project's upstream Git repository ⟨git://git.code.sf.net/p/perfmon2/libpfm4 perfmon2-libpfm4⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-06-29.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.org January, 2011LIBPFM(3)Pages that refer to this page:pfm_get_event_encoding(3), pfm_get_perf_event_encoding(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |