.TH LIBPFM 3  "April, 2008" "" "Linux Programmer's Manual"
.SH NAME
libpfm_amd64 - support for AMD64 processors
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.B #include <perfmon/pfmlib_amd64.h>
.sp
.SH DESCRIPTION
The libpfm library provides full support for the AMD64 processor
families 0Fh and 10H (K8, Barcelona, Phenom) when running in either
32-bit or 64-bit mode. The interface is defined in
\fBpfmlib_amd64.h\fR. It consists of a set of functions and structures
which describe and allow access to the AMD64 specific PMU
features. Note that it only supports AMD processors.
.sp
When AMD64 processor-specific features are needed to support a
measurement, their descriptions must be passed as model-specific input
arguments to the \fBpfm_dispatch_events()\fR function. The AMD64
processor-specific input arguments are described in the
\fBpfmlib_amd64_input_param_t\fR structure and the output parameters
in \fBpfmlib_amd64_output_param_t\fR. They are defined as follows:
.sp
.nf
typedef struct {
        uint32_t        cnt_mask;
        uint32_t        flags;
} pfmlib_amd64_counter_t;

typedef struct {
        unsigned int maxcnt;
        unsigned int options;
} ibs_param_t;

typedef struct {
        pfmlib_amd64_counter_t pfp_amd64_counters[PMU_AMD64_MAX_COUNTERS];
        uint32_t        flags;
        uint32_t        reserved1;
        ibs_param_t     ibsfetch;
        ibs_param_t     ibsop;
        uint64_t        reserved2;
} pfmlib_amd64_input_param_t;

typedef struct {
        uint32_t        ibsfetch_base;
        uint32_t        ibsop_base;
        uint64_t        reserved[7];
} pfmlib_amd64_output_param_t;
.fi
.LP
The \fBflags\fR field of \fBpfmlib_amd64_input_param_t\fR describes
which features of the PMU to use. Following use flags exist:
.TP
.B PFMLIB_AMD64_USE_IBSFETCH
Profile IBS fetch performance (see below under \fBINSTRUCTION BASED
SAMPLING\fR)
.TP
.B PFMLIB_AMD64_USE_IBSOP
Profile IBS execution performance (see below under \fBINSTRUCTION BASED
SAMPLING\fR)
.LP
Multiple features can be selected. Note that there are no use flags
needed for \fBADDITIONAL PER-EVENT FEATURES\fR.
.LP
Various typedefs for MSR encoding and decoding are available. See
\fBpfmlib_amd64.h\fR for details.
.SS ADDITIONAL PER-EVENT FEATURES
AMD64 processors provide a few additional per-event features for
counters: thresholding, inversion, edge detection,
virtualization. They can be set using the \fBpfp_amd64_counters\fR
data structure for each event.  The \fBflags\fR field of
\fBpfmlib_amd64_counter_t\fR can be initialized as follows:
.TP
.B PFMLIB_AMD64_SEL_INV
Inverse the results of the \fBcnt_mask\fR comparison when set
.TP
.B PFMLIB_AMD64_SEL_EDGE
Enables edge detection of events. 
.TP
.B PFMLIB_AMD64_SEL_GUEST
On AMD64 Family 10h processors only. Event is only measured when
processor is in guest mode.
.TP
.B PFMLIB_AMD64_SEL_HOST
On AMD64 Family 10h processors only. Event is only measured when
processor is in host mode.
.LP
The \fBcnt_mask\fR field is used to set the event threshold.  The
value of the counter is incremented each time the number of
occurrences per cycle of the event is greater or equal to the value of
the field. When zero all occurrences are counted.
.SS INSTRUCTION BASED SAMPLING (IBS)
The libpfm_amd64 provides access to the model specific feature
Instruction Based Sampling (IBS). IBS has been introduced with family
10h.
.LP
The IBS setup is using the structures \fBpfmlib_amd64_input_param_t\fR
and \fBpfmlib_amd64_output_param_t\fR with its members \fBflags\fR,
\fBibsfetch\fR, \fBibsop\fR, \fBibsfetch_base\fR,
\fBibsop_base\fR. The input arguments \fBibsop\fR and \fBibsfetch\fR
can be set in inp_mod (type \fBpfmlib_amd64_input_param_t\fR). The
corresponding \fBflags\fR must be set to enable a feature.
.LP
Both, IBS execution profiling and IBS fetch profiling, require a
maximum count value of the periodic counter (\fBmaxcnt\fR) as
parameter. This is a 20 bit value, bits 3:0 are always set to
zero. Additionally, there is an option (\fBoptions\fR) to enable
randomization (\fBIBS_OPTIONS_RANDEN\fR) for IBS fetch profiling.
.LP
The IBS registers IbsFetchCtl (0xC0011030) and IbsOpCtl (0xC0011033)
are available as PMC and PMD in Perfmon. The function
\fBpfm_dispatch_events()\fR initializes these registers according to
the input parameters in \fBpfmlib_amd64_input_param_t\fR.
.LP
Also, \fBpfm_dispatch_events()\fR passes back the index in pfp_pmds[]
of the IbsOpCtl and IbsFetchCtl register. For this there are the
entries \fBibsfetch_base\fR and \fBibsop_base\fR in
\fBpfmlib_amd64_output_param_t\fR. The index may vary depending on
other PMU settings, especially counter settings. If using the PMU with
only one IBS feature and no counters, the index of the base register
is 0.
.LP
Example code:
.LP
.nf
	/* initialize IBS */
	inp_mod.ibsop.maxcnt = 0xFFFF0;
	inp_mod.flags |= PFMLIB_AMD64_USE_IBSOP;
	ret = pfm_dispatch_events(NULL, &inp_mod, &outp, &outp_mod);
	if (ret != PFMLIB_SUCCESS) { ... }

	/* setup PMU */
	/* PMC_IBSOPCTL */
	pc[0].reg_num   = outp.pfp_pmcs[0].reg_num;
	pc[0].reg_value = outp.pfp_pmcs[0].reg_value;
	/* PMD_IBSOPCTL */
	pd[0].reg_num   = outp.pfp_pmds[0].reg_num;
	pd[0].reg_value = 0;

	/* setup sampling */
	pd[0].reg_flags = PFM_REGFL_OVFL_NOTIFY;
	/* add range check here */
	pd[0].reg_smpl_pmds[0] =
		((1UL << PMD_IBSOP_NUM) - 1) << outp.pfp_pmds[0].reg_num;

	/* write pc and pd to PMU */
	...
.fi
.SH ERRORS
Refer to the description of the \fBpfm_dispatch_events()\fR function for errors.
.SH SEE ALSO
pfm_dispatch_events(3) and set of examples shipped with the library
.SH AUTHORS
.nf
Stephane Eranian <eranian@gmail.com>
Robert Richter <robert.richter@amd.com>
.if
.PP