.TH LIBPFM 3  "August, 2006" "" "Linux Programmer's Manual"

.SH NAME

pfm_get_event_name, pfm_get_full_event_name, pfm_get_event_mask_name, pfm_get_event_code,

pfm_get_event_mask_code, pfm_get_event_counters, pfm_get_num_events, pfm_get_max_event_name_len,

pfm_get_event_description, pfm_get_event_mask_description \- get event information

.SH SYNOPSIS

.nf

.B #include <perfmon/pfmlib.h>

.sp

.BI "int pfm_get_event_name(unsigned int " e ", char *"name ", size_t " maxlen ");"

.BI "int pfm_get_full_event_name(pfmlib_event_t *" ev ", char *"name ", size_t " maxlen ");"

.BI "int pfm_get_event_mask_name(unsigned int " e ", unsigned int "mask ", char *"name ", size_t " maxlen ");"

.BI "int pfm_get_event_code(unsigned int " e ", int *"code ");"

.BI "int pfm_get_event_mask_code(unsigned int " e ", unsigned int "mask ", int *"code ");"

.BI "int pfm_get_event_code_counter(unsigned int " e ", unsigned int " cnt ", int *"code ");"

.BI "int pfm_get_event_counters(int " e ", pfmlib_regmask_t "counters ");"

.BI "int pfm_get_num_events(unsigned int *" count ");"

.BI "int pfm_get_max_event_name_len(size_t *" len ");"

.BI "int pfm_get_event_description(unsigned int " ev ", char **" str ");"

.BI "int pfm_get_event_mask_description(unsigned int " ev ", unsigned int "mask ", char **" str ");"

.sp

.SH DESCRIPTION

The \fBpfm_get_event_name()\fR function returns in \fBname\fR the event 

name given its opaque descriptor in \fBe\fR. The \fBmaxlen\fR argument 

indicates the maximum length of the buffer provided for \fBname\fR. Up

to \fBmaxlen\fR-1 characters are stored in the buffer.

The buffer size must be large enough to store the event name, otherwise

an error is returned. This behavior is required to avoid returning partial

names with no way for the caller to verify this is not the full name, except

by failing other calls. The buffer can be appropriately sized using the

\fBpfm_get_max_event_name_len()\fR function. The returned name is a

null terminated string with all upper-case characters and no spaces.

.sp

The \fBpfm_get_full_event_name()\fR function returns in \fBname\fR the event 

name given the full event description in \fBev\fR. The description contains

the event code in \fBev->event\fR and optional unit masks descriptors in

\fBev->unit_masks\fR. The \fBmaxlen\fR argument indicates the maximum length

of the buffer provided for \fBname\fR.  If more than \fBmaxlen\fR-1 characters

are needed to represent the event, an error is returned. Applications may use

the \fBpfm_get_max_event_name_len()\fR function to size the buffer correctly.

In case unit masks are provided, the final event name string is structured as:

event_name:unit_masks1[:unit_masks2]. Event names and unit masks names are

returned in all upper case.

.sp

The \fBpfm_get_event_code()\fR function returns the event code in \fBcode\fR

given its opaque descriptor \fBe\fR.

.sp

On some PMU models, the code associated with an event is different based

on the counter it is programmed into. The \fBpfm_get_event_code_counter()\fR

function is used to retrieve the event code in \fBcode\fR when the event \fBe\fR

is programmed into counter \fBcnt\fR. The counter index \fBcnt\fR must correspond

to of a counting PMD register.

.sp

Given an opaque event descriptor \fBe\fR, the \fBpfm_get_event_counters()\fR 

function returns in \fBcounters\fR a bitmask of type \fBpfmlib_regmask_t\fR where 

each bit set represents a PMU config register which can be used to program this 

event. The bitmask must be accessed using accessor macros defined by the library.

.so

The \fBpfm_get_num_events()\fR function returns in \fBcount\fR the

total number of events available for the PMU model. On some PMU

models, however, not all events in the table may be useable due

to processor stepping changes. However, The library guarantees that

no more that \fBcount\fR events are available.

.sp

It is possible to list all existing events for the detected host PMU

using accessor functions as the full table of events is not accessible

to the applications. The index of the first event is always zero,

then using the \fBpfm_get_num_events()\fR function you get the total number of events.

On some PMU models, e.g., AMD64, not all events are necessarily supported by the host

PMU, therefore the count returned by this calls may not be the actual number of available

events. Event descriptors are contiguous therefore a simple loop will allow

complete scanning. The typical scan loop is constructed as 

follows:

.sp

.nf

unsigned int i, count;

char name[256];

int ret;

pfm_get_num_events(&count);

for(i=0;i < count; i++)

{

   ret = pfm_get_event_name(i, name, 256);

   if (ret != PFMLIB_SUCCESS)

       continue;

   printf("%s\\n", name);

}

.fi

.sp

The \fBpfm_get_max_event_name_len()\fR function returns in \fBlen\fR 

the maximum length in bytes for the name of the events or its unit masks, if any,

available on one PMU implementation. The value excludes the string termination

character ('\\0').

.sp

The \fBpfm_get_event_description()\fR function returns in \fBstr\fR the

description string associated with the event specified in \fBev\fR. 

The description is returned into a buffer that is allocated to hold the entire

description text. It is the responsibility of the caller to free the buffer when

it becomes useless by calling the \fBfree(3)\fR function.

.sp

The \fBpfm_get_event_mask_code()\fR function must be used to retrieve the actual

unit mask value given a event descriptor in \fBe\fR and a unit mask descriptor

in \fBmask\fR. The value is returned in \fBcode\fR.

.sp

The \fBpfm_get_event_mask_name()\fR function must be used to retrieve the name

associated with a unit mask specified in \fBmask\fR for event \fBe\fR. The

name is returned in the buffer specified in \fBname\fR. The maximum size

of the  buffer must be specified in \fBmaxlen\fR.

.sp

The \fBpfm_get_event_mask_description()\fR function  returns in \fBstr\fR the

description string associated with the unit mask specified in \fBmask\fR for

the event specified in \fBev\fR. The description is returned into a buffer that

is allocated to hold the entire description text. It is the responsibility of

the caller to free the buffer when it becomes useless by calling the \fBfree(3)\fR

function.

.SH RETURN

All functions return whether or not the call 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.

.TP

.B PFMLIB_ERR_FULL

the string buffer provided is too small

.TP

.B PFMLIB_ERR_INVAL

the event or unit mask descriptor, or the \fBcnt\fR argument is invalid, or a pointer argument is NULL.

.SH SEE ALSO

pfm_get_impl_counters(3), pfm_get_max_event_name_len(3), free(3)

.SH AUTHOR

Stephane Eranian <eranian@gmail.com>

.PP