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

.SH NAME

pfm_get_cycle_event, pfm_get_inst_retired_event - get basic event

descriptors

.SH SYNOPSIS

.nf

.B #include <perfmon/pfmlib.h>

.sp

.BI "int pfm_get_cycle_event(pfmlib_event_t *"ev ");"

.BI "int pfm_get_inst_retired_event(pfmlib_event_t *"ev ");"

.sp

.SH DESCRIPTION

In order to build very simple generic examples that work across

all PMU models, the library provides a way to retrieve information

about two basic events that are present in most PMU models: cycles 

and instruction retired. The first event, cycles, counts the number

of elapsed cycles. The second event, instruction retired, counts the

number of instructions that have executed and retired from the processor

pipeline. Depending on the PMU model, there may be variations in the

exact definition of those events. The library provides this information

on a best effort basis. User must refer to PMU model specific documentation

to validate the event definition.

.sp

The \fBpfm_get_cycle_event()\fR function returns in \fBev\fR the event

and optional unit mask descriptors for the event that counts elapsed 

cycles. Depending on the PMU model, there may be unit mask(s) necessary

to count cycles. Application must check the value returned in

\fBev->num_masks\fR.

.sp

The \fBpfm_get_inst_retired_event()\fR function returns in \fBev\fR the event

and optional unit mask descriptors for the event that counts the number

of returned instruction. Depending on the PMU model, there may be unit

mask(s) necessary to count retired instructions. Application must check

the value returned in \fBev->num_masks\fR.

.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_INVAL

the \fBev\fR parameter is NULL.

.TP

.B PFMLIB_ERR_NOTSUPP

the host PMU does not define an event to count cycles or instructions retired.

.TP

.SH AUTHOR

Stephane Eranian <eranian@hpl.hp.com>

.PP