|
Packit |
577717 |
.TH LIBPFM 3 "December, 2009" "" "Linux Programmer's Manual"
|
|
Packit |
577717 |
.SH NAME
|
|
Packit |
577717 |
pfm_get_pmu_info \- get PMU information
|
|
Packit |
577717 |
.SH SYNOPSIS
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib.h>
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.BI "int pfm_get_pmu_info(pfm_pmu_t " pmu ", pfm_pmu_info_t *" info ");"
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH DESCRIPTION
|
|
Packit |
577717 |
This function returns in \fBinfo\fR information about a PMU model
|
|
Packit |
577717 |
designated by its identifier in \fBpmu\fR.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The \fBpfm_pmu_info\fR structure is defined as follows:
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
typedef struct {
|
|
Packit |
577717 |
const char *name;
|
|
Packit |
577717 |
const char *desc;
|
|
Packit |
577717 |
pfm_pmu_t pmu;
|
|
Packit |
577717 |
pfm_pmu_type_t type;
|
|
Packit |
577717 |
int size;
|
|
Packit |
577717 |
int nevents;
|
|
Packit |
577717 |
int first_event;
|
|
Packit |
577717 |
int max_encoding;
|
|
Packit |
577717 |
int num_cntrs;
|
|
Packit |
577717 |
int num_fixed_cntrs;
|
|
Packit |
577717 |
struct {
|
|
Packit |
577717 |
int is_present:1;
|
|
Packit |
577717 |
int is_arch_default:1;
|
|
Packit |
577717 |
int is_core:1;
|
|
Packit |
577717 |
int is_uncore:1;
|
|
Packit |
577717 |
int reserved:28;
|
|
Packit |
577717 |
};
|
|
Packit |
577717 |
} pfm_pmu_info_t;
|
|
Packit |
577717 |
.fi
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The fields of this structure are defined as follows:
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B name
|
|
Packit |
577717 |
This is the symbolic name of the PMU. This name
|
|
Packit |
577717 |
can be used as a prefix in an event string. This is a read-only
|
|
Packit |
577717 |
string.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B desc
|
|
Packit |
577717 |
This is the description of PMU. This is a read-only string.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B pmu
|
|
Packit |
577717 |
This is the unique PMU identification code. It is identical to the value
|
|
Packit |
577717 |
passed in \fBpmu\fR and it provided only for completeness.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B type
|
|
Packit |
577717 |
This field contains the type of the PMU. The following types are defined:
|
|
Packit |
577717 |
.RS
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PMU_TYPE_UNKNOWN
|
|
Packit |
577717 |
The type of the PMU could not be determined.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PMU_TYPE_CORE
|
|
Packit |
577717 |
This field is set to one when the PMU is implemented by the processor core.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFM_PMU_TYPE_UNCORE
|
|
Packit |
577717 |
This field is set to one when the PMU is implemented on the processor
|
|
Packit |
577717 |
die but at the socket level, i.e., capturing events for all cores.
|
|
Packit |
577717 |
.PP
|
|
Packit |
577717 |
.RE
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B nevents
|
|
Packit |
577717 |
This is the number of available events for this PMU model based on the
|
|
Packit |
577717 |
host processor. It is \fBonly\fR valid if the \fBis_present\fR field
|
|
Packit |
577717 |
is set to 1. Event identifiers are not guaranteed contiguous. In other words,
|
|
Packit |
577717 |
it is not because \fBnevents\fR is equal to 100, that event identifiers go
|
|
Packit |
577717 |
from 0 to 99. The iterator function \fBpfm_get_event_next()\fR must be
|
|
Packit |
577717 |
used to go from one identifier to the next.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B first_event
|
|
Packit |
577717 |
This field returns the opaque index of the first event for this PMU model. The index
|
|
Packit |
577717 |
can be used with \fBpfm_get_event_info()\fR or \fBpfm_get_event_next()\fR functions.
|
|
Packit |
577717 |
In case no event is available, this field contains \fB-1\fR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B num_cntrs
|
|
Packit |
577717 |
This field contains the number of generic counters supported by the PMU.
|
|
Packit |
577717 |
A counter is generic if it can count more than one event. When it is not
|
|
Packit |
577717 |
possible to determine the number of generic counters, this field contains \fb-1\fR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B num_fixed_cntrs
|
|
Packit |
577717 |
This field contains the number of fixed counters supported by the PMU.
|
|
Packit |
577717 |
A counter is fixed if it hardwired to count only one event. When it is not
|
|
Packit |
577717 |
possible to determine the number of generic counters, this field contains \fb-1\fR.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B size
|
|
Packit |
577717 |
This field contains the size of the struct passed. This field is used to provide
|
|
Packit |
577717 |
for extensibility of the struct without compromising backward compatibility.
|
|
Packit |
577717 |
The value should be set to \fBsizeof(pfm_pmu_info_t)\fR. If instead, a value of
|
|
Packit |
577717 |
\fB0\fR is specified, the library assumes the struct passed is identical to the
|
|
Packit |
577717 |
first ABI version which size is \fBPFM_PMU_INFO_ABI0\fR. Thus, if fields were
|
|
Packit |
577717 |
added after the first ABI, they will not be set by the library. The library
|
|
Packit |
577717 |
does check that bytes beyond what is implemented are zeroes.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B max_encoding
|
|
Packit |
577717 |
This field returns the number of event codes returned by \fBpfm_get_event_encoding()\fR.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B is_present
|
|
Packit |
577717 |
This field is set to one is the PMU model has been detected on the
|
|
Packit |
577717 |
host system.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B is_dfl
|
|
Packit |
577717 |
This field is set to one if the PMU is the default PMU for this architecture.
|
|
Packit |
577717 |
Otherwise this field is zero.
|
|
Packit |
577717 |
.PP
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.SH RETURN
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If successful, the function returns \fBPFM_SUCCESS\fR and PMU information
|
|
Packit |
577717 |
in \fBinfo\fR, otherwise it returns an error code.
|
|
Packit |
577717 |
.SH ERRORS
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ERR_NOINIT
|
|
Packit |
577717 |
Library has not been initialized properly.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ERR_NOTSUPP
|
|
Packit |
577717 |
PMU model is not supported by the library.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ERR_INVAL
|
|
Packit |
577717 |
The \fBpmu\fR argument is invalid or \fBinfo\fR is \fBNULL\fR or \fBsize\fR
|
|
Packit |
577717 |
is not zero.
|
|
Packit |
577717 |
.SH SEE ALSO
|
|
Packit |
577717 |
pfm_get_event_next(3)
|
|
Packit |
577717 |
.SH AUTHOR
|
|
Packit |
577717 |
Stephane Eranian <eranian@gmail.com>
|
|
Packit |
577717 |
.PP
|