NAME

       pfm_get_event_encoding - get raw event encoding

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_get_event_encoding(const char *str,int dfl_plm, char **fstr, int *idx, uint64_t *code, int *count);

DESCRIPTION

       This function is used to retrieve the raw event encoding corresponding to the event string
       in str.  Only one event per call can be  encoded.  As  such,  str  can  contain  only  one
       symbolic  event  name.   The  string  may  contain  unit  masks and modifiers. The default
       privilege level mask is passed in dfl_plm.  It may be used depending on the event.

       This function is deprecated. It is superseded by pfm_get_os_event_encoding() where the  OS
       is set to PFM_OS_NONE. Encoding is retrieve through the pfm_pmu_encode_arg_t structure.

       The following examples illustrates the transition:

          int i, count = 0;
          uint64_t *codes;

          ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, NULL, &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]);

       is equivalent to:

          pfm_pmu_encode_arg_t arg;
          int i;

          memset(&arg, 0, sizeof(arg));
          arg.size = 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);

       The encoding may take several 64-bit integers. The function can use the array passed in code if the number
       of entries passed in count is big enough. However, if both *codes is NULL and count
       is 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 in codes is reflected in *count upon
       return regardless of whether the codes was allocated or used as is. 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.

       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 fstr is not NULL, it will point to the fully qualified event string upon successful return. The string
       contains the event name, any umask set, and the value of all the modifiers. It reflects what the encoding will
       actually measure. The function allocates the memory to store the string. The caller must eventually free the
       string.

       Here is a example of how this function could be used:
       #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", PFM_PLM3, NULL, &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;
       }

RETURN

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

ERRORS

       PFM_ERR_TOOSMALL
              The code argument is too small for the encoding.

       PFM_ERR_INVAL
              The  code  or  count  argument  is  NULL or the str contains 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.

AUTHOR

       Stephane Eranian <eranian@gmail.com>

SEE ALSO

       pfm_get_os_event_encoding(3)

                                         September, 2009                                LIBPFM(3)