Signed-off-by: Robert Richter <[EMAIL PROTECTED]>
---
docs/man3/libpfm_amd64.3 | 143 ++++++++++++++++++++++++++++++++++++----------
1 files changed, 113 insertions(+), 30 deletions(-)
diff --git a/docs/man3/libpfm_amd64.3 b/docs/man3/libpfm_amd64.3
index 1c29ce3..32ed11d 100644
--- a/docs/man3/libpfm_amd64.3
+++ b/docs/man3/libpfm_amd64.3
@@ -1,43 +1,70 @@
-.TH LIBPFM 3 "October, 2007" "" "Linux Programmer's Manual"
+.TH LIBPFM 3 "March, 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 processors K8
+and Barcelona (families 0Fh and 10H) 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];
+ pfmlib_amd64_counter_t pfp_amd64_counters[PMU_AMD64_MAX_COUNTERS];
+ uint32_t flags;
+ uint32_t reserved1;
+ ibsfetchctl_t ibsfetchctl;
+ ibsopctl_t ibsopctl;
+ 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 +73,78 @@ 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,
+\fBibsfetchctl\fR, \fBibsopctl\fR, \fBibsfetch_base\fR,
+\fBibsop_base\fR. The control registers \fBibsopctl\fR and
+\fBibsfetchctl\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
+There exists a control register for IBS execution profiling and one
+for fetch profiling. The control registers are direct mappings to the
+MSRs IbsFetchCtl (0xC0011030) and IbsOpCtl (0xC0011033). The PMU has
+to be programmed with a PMC and a PMD for each of those control
+registers. The function \fBpfm_dispatch_events()\fR returns the
+entries for these PMCs and PMDs.
+.LP
+Also the index of the register base is returned in \fBibsfetch_base\fR
+and \fBibsop_base\fR of outp_mod (type
+\fBpfmlib_amd64_output_param_t\fR). The index points to the PMD in
+outp.pfp_pmds and may vary depending of 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.ibsopctl.reg.ibsopmaxcnt = 0xFFFF; /* 0xffff0 */
+ inp_mod.ibsopctl.reg.ibsopen = 1;
+ 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
+.SH AUTHORS
+.nf
Stephane Eranian <[EMAIL PROTECTED]>
+Robert Richter <[EMAIL PROTECTED]>
+.if
.PP
--
1.5.3.7
--
Advanced Micro Devices, Inc.
Operating System Research Center
email: [EMAIL PROTECTED]
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
perfmon2-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/perfmon2-devel
