Signed-off-by: Robert Richter <[EMAIL PROTECTED]>
---
docs/man3/libpfm_amd64.3 | 153 ++++++++++++++++++++++++++++++++++++---------
1 files changed, 122 insertions(+), 31 deletions(-)
diff --git a/docs/man3/libpfm_amd64.3 b/docs/man3/libpfm_amd64.3
index 1c29ce3..c30c7f9 100644
--- a/docs/man3/libpfm_amd64.3
+++ b/docs/man3/libpfm_amd64.3
@@ -1,43 +1,75 @@
-.TH LIBPFM 3 "October, 2007" "" "Linux Programmer's Manual"
+.TH LIBPFM 3 "April, 2008" "" "Linux Programmer's Manual"
.SH NAME
-libpfm_x86_64 - support for AMD64 processors
+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 family 15 and
16 when
-running in either 32 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 does not support Intel EM64T
processors.
+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:
+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 {
- unsigned int cnt_mask;
- unsigned int flags;
+ uint32_t cnt_mask;
+ uint32_t flags;
} pfmlib_amd64_counter_t;
typedef struct {
- pfmlib_amd64_counter_t pfp_amd64_counters[PMU_AMD64_NUM_COUNTERS];
- uint64_t reserved[4];
+ 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 {
- uint64_t reserved[8];
+ uint32_t ibsfetch_base;
+ uint32_t ibsop_base;
+ uint64_t reserved[7];
} pfmlib_amd64_output_param_t;
.fi
-.sp
-.sp
-The X86-64 processor provides a few additional per-event features for
-counters: thresholding, inversion, edge detection. They can be set using the
-\fBpfp_amd64_counters\fR data structure for each event. The \fBflags\fR
-field can be initialized as follows:
+.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
@@ -46,22 +78,81 @@ Inverse the results of the \fBcnt_mask\fR comparison when
set
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.
+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.
+On AMD64 Family 10h processors only. Event is only measured when
+processor is in host mode.
.LP
-
-The \fBcnt_mask\fR field contains 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.
-.sp
+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
+entires \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 AUTHOR
-Stephane Eranian <[EMAIL PROTECTED]>
+.SH AUTHORS
+.nf
+Stephane Eranian <[EMAIL PROTECTED]>
+Robert Richter <[EMAIL PROTECTED]>
+.if
.PP
--
1.5.3.7
-------------------------------------------------------------------------
This SF.net email is sponsored by the 2008 JavaOne(SM) Conference
Don't miss this year's exciting event. There's still time to save $100.
Use priority code J8TL2D2.
http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone
_______________________________________________
perfmon2-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/perfmon2-devel
