.TH LIBPFM 3  "July, 2003" "" "Linux Programmer's Manual"

.SH NAME

pfm_get_impl_pmcs, pfm_get_impl_pmds, pfm_get_impl_counters,

pfm_get_num_counters, pfm_get_num_pmcs, pfm_get_num_pmds,

pfm_get_hw_counter_width \- return 

bitmask of implemented PMU registers or number of PMU registers

.SH SYNOPSIS

.nf

.B #include <perfmon/pfmlib.h>

.sp

.BI "int pfm_get_impl_pmcs(pfmlib_regmask_t *" impl_pmcs ");"

.BI "int pfm_get_impl_pmds(pfmlib_regmask_t *" impl_pmds ");"

.BI "int pfm_get_impl_counters(pfmlib_regmask_t *" impl_counters ");"

.BI "int pfm_get_num_counters(unsigned int *"num ");"

.BI "int pfm_get_num_pmcs(unsigned int *"num ");"

.BI "int pfm_get_num_pmds(unsigned int *"num ");"

.BI "int pfm_get_num_counters(unsigned int *"num ");"

.BI "int pfm_get_hw_counter_width(unsigned int *"width ");"

.sp

.SH DESCRIPTION

The \fBpfm_get_impl_*()\fR functions can be used to figure out which

PMU registers are implemented on the host CPU. All implemented registers

may not necessarily be available to applications. Programs need to query

the operating system kernel monitoring interface to figure out the list

of available registers.

.sp

The \fBpfm_get_impl_*()\fR functions all return a bitmask of registers corresponding to

the query. The bitmask pointer passed as argument is reset to zero by each function.

The returned bitmask must be accessed using the set of functions provided by the

library to ensure portability. See related man pages below.

.sp

The \fBpfm_get_num_*()\fR functions return the number of implemented PMC or PMD

registers. Those numbers may be different from the actual number of registers

available to applications.

.sp

The \fBpfm_get_impl_pmcs()\fR function returns in \fBimpl_pmcs\fR the bitmask of implemented PMCS.

The \fBpfm_get_impl_pmds()\fR function returns in \fBimpl_pmds\fR the bitmask of implemented PMDS.

The \fBpfm_get_impl_counters()\fR function returns in \fBimpl_counters\fR a bitmask of the PMD

registers used as counters. Depending on the PMU mode, not all PMD registers are

necessarily used as counters.

.sp

The \fBpfm_get_num_counters()\fR function returns in \fBnum\fR the number of PMD

used as counters. A counter is a PMD which is used to accumulate the

number of occurrences of an event.

The \fBpfm_get_num_pmcs()\fR function returns in \fBnum\fR the number of 

implemented PMCs by the host PMU.

The \fBpfm_get_num_pmds()\fR function returns in \fBnum\fR the number of 

implemented PMDs by the host PMU.

The \fBpfm_get_hw_counter_width()\fR function returns the width in bits of the 

counters in \fBwidth\fR. PMU implementations can have different number of 

bits implemented. For instance, Itanium has 32-bit counters, while Itanium 

2 has 47-bits. 

.SH RETURN

The function returns whether or not it was successful.

A return value of \fBPFMLIB_SUCCESS\fR indicates success, 

otherwise the value is the error code.

.SH ERRORS

.B PFMLIB_ERR_NOINIT

the library has not been initialized properly.

.SH SEE ALSO

pfm_regmask_set(3), pfm_regmask_isset(3)

.SH AUTHOR

Stephane Eranian <eranian@hpl.hp.com>

.PP