NAME

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_GEN_IA64_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
• PFMLIB_MONTECITO_PMU: the dual-core Itanium 2 processor PMU model
• PFMLIB_AMD64_PMU: the AMD64 processors (family 15 and 16)
• PFMLIB_GEN_IA32_PMU: Intel architectural PMU v1 or v2
• PFMLIB_I386_P6_PMU: Intel P6 processors. That includes Pentium Pro, Pentium II, Pentium III, but excludes Pentium M
• PFMLIB_PENTIUM4_PMU: Intel processors based on Netburst micro-architecture. That includes Pentium 4.
• PFMLIB_COREDUO_PMU: Intel processors based on Yonah micro-architecture. That includes Intel Core Duo/Core Solo processors
• PFMLIB_I386_PM_PMU: Intel Pentium M processors
• PFMLIB_INTEL_CORE_PMU: Intel processors based on the Core micro-architecture. That includes Intel Core 2 Duo/Quad processors
• PFMLIB_MIPS_20KC_PMU: MIPS 20KC processors
• PFMLIB_MIPS_24K_PMU: MIPS 24K processors
• PFMLIB_MIPS_25KF_PMU: MIPS 25KF processors
• PFMLIB_MIPS_34K_PMU: MIPS 34K processors
• PFMLIB_MIPS_5KC_PMU: MIPS 5KC processors
• PFMLIB_MIPS_74K_PMU: MIPS 74K processors
• PFMLIB_MIPS_R10000_PMU: MIPS R10000 processors
• PFMLIB_MIPS_R12000_PMU: MIPS R12000 processors
• PFMLIB_MIPS_RM7000_PMU: MIPS RM7000 processors
• PFMLIB_MIPS_RM9000_PMU: MIPS RM9000 processors
• PFMLIB_MIPS_SB1_PMU: MIPS SB1/SB1A processors
• PFMLIB_MIPS_VR5432_PMU: MIPS VR5432 processors
• PFMLIB_MIPS_VR5500_PMU: MIPS VR5500 processors
• PFMLIB_MIPS_ICE9A_PMU: SiCortex ICE9A
• PFMLIB_MIPS_ICE9B_PMU: SiCortex ICE9B
• PFMLIB_POWERPC_PMU: IBM POWERPC processors
• PFMLIB_CRAYX2_PMU: Cray X2 processors
• PFMLIB_CELL_PMU: IBM Cell processors
• PFMLIB_PPC970_PMU: IBM PowerPC 970(FX,GX) processors
• PFMLIB_PPC970MP_PMU: IBM PowerPC 970MP processors
• PFMLIB_POWER3_PMU: IBM POWER3 processors
• PFMLIB_POWER4_PMU: IBM POWER4 processors
• PFMLIB_POWER5_PMU: IBM POWER5 processors
• PFMLIB_POWER5p_PMU: IBM POWER5+ processors
• PFMLIB_POWER6_PMU: IBM POWER6 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

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