Man Linux: Main Page and Category List

NAME

       pfm_get_pmu_name,       pfm_get_pmu_type,      pfm_get_pmu_name_bytype,
       pfm_pmu_is_supported,  pfm_force_pmu,pfm_list_supported_pmu   -   query
       library about supported PMU models

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_get_pmu_name(char *name, int maxlen);
       int pfm_get_pmu_type(int *type);
       int pfm_get_pmu_name_bytype(int type, char *name, int maxlen);
       int pfm_pmu_is_supported(int type);
       int pfm_force_pmu(int type);
       int pfm_list_supported_pmus(int (*pf)(const char *fmt,...));

DESCRIPTION

       These  functions  retrieve  information about the detected host PMU and
       the PMU models supported by the library. More than  one  model  can  be
       supported by the same library.

       Each  PMU  model  is  assigned  a type and a name. The latter is just a
       string and the former is a unique identifier. The  currently  supported
       types are:

       PFMLIB_GENERIC_PMU
              the default architected PMU model, i.e., the basic model.

       PFMLIB_ITANIUM_PMU
              the Itanium processor PMU model. The model is found in the first
              implementation of the IA-64 architecture, code name Merced.

       PFMLIB_ITANIUM2_PMU
              the Itanium 2 processor PMU model. This is the model provided by
              McKinley, Madison, and Deerfield processors.

       The  pfm_get_pmu_name  function  returns  the name of the detected host
       PMU. The library must have been initialized properly before making this
       call.  The  name  is returned in the name argument. The maxlen argument
       indicates the maximum length of the buffer provided for  name.   Up  to
       maxlen-1  characters  will  be  returned, not including the termination
       character.

       The pfm_get_pmu_type function returns the type  of  the  detected  host
       PMU. The library must have been initialized properly before making this
       call. The type returned in  type can be any one  of  the  three  listed
       above.

       The pfm_get_pmu_name_bytype function returns the name of a PMU model in
       name given a type in the type argument. The maxlen  argument  indicates
       the  maximum  length  of  the buffer provided for name.  Up to maxlen-1
       characters will be returned, not including the termination character.

       The pfm_pmu_is_supported function returns PFMLIB_SUCCESS if  the  given
       PMU type is supported by the library independently of what the host PMU
       model is.

       The pfm_force_pmu function is used to  forced  the  library  to  use  a
       particular  PMU  model  compared  to  what it has detected. The library
       checks that the selected type can be supported by the host PMU. This is
       mostly  useful  to  force  the  library  to  the  use generic PMU model
       PFMLIB_GENERIC_PMU.  This function can be called at any time  and  upon
       return the library is considered initialized.

       The pfm_list_supported_pmu function is used to print the list PMU types
       that the library supports. The results is printed  using  the  function
       provided in the pf argument, which must be a printf-style function.

RETURN

       The  function returns whether or not it was successful.  A return value
       of PFMLIB_SUCCESS indicates success, otherwise the value is  the  error
       code.

ERRORS

       PFMLIB_ERR_NOINIT the library has not been initialized properly.

       PFMLIB_ERR_INVAL
              invalid  argument  was  given,  most  likely  invalid pointer or
              invalid PMU type.

       PFMLIB_ERR_NOTSUPP
              the selected PMU type can be used on the host CPU.

AUTHOR

       Stephane Eranian <eranian@hpl.hp.com>

                                November, 2003                       LIBPFM(3)