# pfm_get_perf_event_encoding

## NAME



           pfm_get_perf_event_encoding - encode event for perf_event API
    


## SYNOPSIS



           **#include <perfmon/pfmlib_perf_event.h>**
    
           **int pfm_get_perf_event_encoding(const char ***_str_**, int** _dfl_plm_**, struct perf_event_attr ***_attr_**, char ****_fstr_**, int ***_idx_**);**
    


## DESCRIPTION



           This function can be used in conjunction with the perf_events
           Linux kernel API which provides access to hardware performance
           counters, kernel software counters and tracepoints.  The function
           takes an event string in **str** and a default privilege level mask in
           **dfl_plm** and fills out the relevant parts of the perf_events
           specific data structure in **attr**.
    
           This function is **deprecated**. It is superseded by
           **pfm_get_os_event_encoding()** with the OS argument set to either
           **PFM_OS_PERF_EVENT** or **PFM_OS_PERF_EVENT_EXT**.  Using this function
           provides extended support for perf_events. Certain perf_event
           configuration option are only available through this new
           interface.
    
           The following examples illustrates the transition:
    
              struct perf_event_attr attr;
              int i, count = 0;
              uint64_t *codes;
    
              memset(&attr, 0, sizeof(attr));
    
              ret = pfm_get_perf_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, &attrs, NULL, NULL);
              if (ret != PFM_SUCCESS)
                 err(1, "cannot get encoding %s", pfm_strerror(ret));
    
           is equivalent to:
    
              #include <perfmon/pfmlib_perf_event.h>
              struct perf_event_attr attr;
              pfm_perf_encode_arg_t arg;
    
              memset(&arg, 0, sizeof(arg));
              arg.size = sizeof(arg);
              arg.attr = &attr;
    
              ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_PERF, &arg);
              if (ret != PFM_SUCCESS)
                 err(1, "cannot get encoding %s", pfm_strerror(ret));
    
           The **dfl_plm** cannot be zero, though it may not necessarily be used by the event.
           Depending on the event, combination of the following privilege levels may be used:
    
           **PFM_PLM3**
                  Measure at privilege level 3. This usually corresponds to user level. On X86, it corresponds
                  to privilege levels 3, 2, 1. Check the PMU specific man page to verify if this level
                  is supported by your PMU model.
    
           **PFM_PLM2**
                  Measure at privilege level 2. Check the PMU specific man page to verify if this level
                  is supported by your PMU model.
    
           **PFM_PLM1**
                  Measure at privilege level 1. Check the PMU specific man page to verify if this level
                  is supported by your PMU model.
    
           **PFM_PLM0**
                  Measure at privilege level 0. This usually corresponds to kernel level. Check the PMU
                  specific man page to verify if this level is supported by your PMU model.
    
           **PFM_PLMH**
                  Measure at hypervisor privilege level. This is used in conjunction with hardware virtualization.
                  Check the PMU specific man page to verify if this level is supported by your PMU model.
    
           If **fstr** is not NULL, the function will make it point to the fully qualified event string,
           i.e., a string with the event name, all unit masks set, and the value of all modifiers.
           The library will allocate memory to store the event string but it is the responsibility of the
           caller to eventually free that string using free().
    
           If **idx** is not NULL, it returns the corresponding unique event identifier.
    
           Only select fields are modified by the function, the others are untouched.
           The following fields in **attr** are modified:
    
           **type** The type of the event
    
           **config** The encoding of the event
    
           **exclude_user**
                  Whether or not user level execution should be excluded from monitoring. The definition
                  of user is PMU model specific.
    
           **exclude_kernel**
                  Whether or not kernel level execution should be excluded from monitoring. The definition
                  of kernel is PMU model specific.
    
           **exclude_hv**
                  Whether or not hypervisor level execution should be excluded from monitoring. The definition
                  of hypervisor is PMU model specific.
    
           By default, if no privilege level modifier is specified in the event string, the library clears
           **exclude_user** , **exclude_kernel** and **exclude_hv** , resulting in the event being
           measured at all levels subject to hardware support.
    
           The function is able to work on only one event at a time. For convenience, it accepts
           event strings with commas. In that case, it will translate the first event up to the
           first comma. This is handy in case tools gets passed events as a comma-separated list.
    


## RETURN



           The function returns in **attr** the perf_event encoding which
           corresponds to the event string. If **idx** is not NULL, then it will
           contain the unique event identifier upon successful return. The
           value **PFM_SUCCESS** is returned if successful, otherwise a negative
           error code is returned.
    


## ERRORS



           **PFM_ERR_TOOSMALL**
                  The **code** argument is too small for the encoding.
    
           **PFM_ERR_INVAL**
                  The **attr** argument is **NULL**.
    
           **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.
    


* * *