1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 libpfm_amd64 - support for AMD64 processors
7
9 #include <perfmon/pfmlib.h>
10 #include <perfmon/pfmlib_amd64.h>
11
14 The libpfm library provides full support for the AMD64 processor fami‐
15 lies 0Fh and 10H (K8, Barcelona, Phenom) when running in either 32-bit
16 or 64-bit mode. The interface is defined in pfmlib_amd64.h. It consists
17 of a set of functions and structures which describe and allow access to
18 the AMD64 specific PMU features. Note that it only supports AMD proces‐
19 sors.
20 When AMD64 processor-specific features are needed to support a measure‐
22 ment, their descriptions must be passed as model-specific input argu‐
23 ments to the pfm_dispatch_events() function. The AMD64 processor-spe‐
24 cific input arguments are described in the pfmlib_amd64_input_param_t
25 structure and the output parameters in pfmlib_amd64_output_param_t.
26 They are defined as follows:
27 typedef struct {
29 uint32_t cnt_mask;
30 uint32_t flags;
31 } pfmlib_amd64_counter_t;
32 typedef struct {
34 unsigned int maxcnt;
35 unsigned int options;
36 } ibs_param_t;
37 typedef struct {
39 pfmlib_amd64_counter_t pfp_amd64_counters[PMU_AMD64_MAX_COUNTERS];
40 uint32_t flags;
41 uint32_t reserved1;
42 ibs_param_t ibsfetch;
43 ibs_param_t ibsop;
44 uint64_t reserved2;
45 } pfmlib_amd64_input_param_t;
46 typedef struct {
48 uint32_t ibsfetch_base;
49 uint32_t ibsop_base;
50 uint64_t reserved[7];
51 } pfmlib_amd64_output_param_t;
52 The flags field of pfmlib_amd64_input_param_t describes which features
54 of the PMU to use. Following use flags exist:
55 PFMLIB_AMD64_USE_IBSFETCH
57 Profile IBS fetch performance (see below under INSTRUCTION BASED
58 SAMPLING)
59 PFMLIB_AMD64_USE_IBSOP
61 Profile IBS execution performance (see below under INSTRUCTION
62 BASED SAMPLING)
63 Multiple features can be selected. Note that there are no use flags
65 needed for ADDITIONAL PER-EVENT FEATURES.
66 Various typedefs for MSR encoding and decoding are available. See pfm‐
68 lib_amd64.h for details.
69 ADDITIONAL PER-EVENT FEATURES
71 AMD64 processors provide a few additional per-event features for coun‐
72 ters: thresholding, inversion, edge detection, virtualization. They can
73 be set using the pfp_amd64_counters data structure for each event. The
74 flags field of pfmlib_amd64_counter_t can be initialized as follows:
75 PFMLIB_AMD64_SEL_INV
77 Inverse the results of the cnt_mask comparison when set
78 PFMLIB_AMD64_SEL_EDGE
80 Enables edge detection of events.
81 PFMLIB_AMD64_SEL_GUEST
83 On AMD64 Family 10h processors only. Event is only measured when
84 processor is in guest mode.
85 PFMLIB_AMD64_SEL_HOST
87 On AMD64 Family 10h processors only. Event is only measured when
88 processor is in host mode.
89 The cnt_mask field is used to set the event threshold. The value of
91 the counter is incremented each time the number of occurrences per
92 cycle of the event is greater or equal to the value of the field. When
93 zero all occurrences are counted.
94 INSTRUCTION BASED SAMPLING (IBS)
96 The libpfm_amd64 provides access to the model specific feature Instruc‐
97 tion Based Sampling (IBS). IBS has been introduced with family 10h.
98 The IBS setup is using the structures pfmlib_amd64_input_param_t and
100 pfmlib_amd64_output_param_t with its members flags, ibsfetch, ibsop,
101 ibsfetch_base, ibsop_base. The input arguments ibsop and ibsfetch can
102 be set in inp_mod (type pfmlib_amd64_input_param_t). The corresponding
103 flags must be set to enable a feature.
104 Both, IBS execution profiling and IBS fetch profiling, require a maxi‐
106 mum count value of the periodic counter (maxcnt) as parameter. This is
107 a 20 bit value, bits 3:0 are always set to zero. Additionally, there is
108 an option (options) to enable randomization (IBS_OPTIONS_RANDEN) for
109 IBS fetch profiling.
110 The IBS registers IbsFetchCtl (0xC0011030) and IbsOpCtl (0xC0011033)
112 are available as PMC and PMD in Perfmon. The function pfm_dis‐
113 patch_events() initializes these registers according to the input
114 parameters in pfmlib_amd64_input_param_t.
115 Also, pfm_dispatch_events() passes back the index in pfp_pmds[] of the
117 IbsOpCtl and IbsFetchCtl register. For this there are the entries ibs‐
118 fetch_base and ibsop_base in pfmlib_amd64_output_param_t. The index may
119 vary depending on other PMU settings, especially counter settings. If
120 using the PMU with only one IBS feature and no counters, the index of
121 the base register is 0.
122 Example code:
124 /* initialize IBS */
126 inp_mod.ibsop.maxcnt = 0xFFFF0;
127 inp_mod.flags |= PFMLIB_AMD64_USE_IBSOP;
128 ret = pfm_dispatch_events(NULL, &inp_mod, &outp, &outp_mod);
129 if (ret != PFMLIB_SUCCESS) { ... }
130 /* setup PMU */
132 /* PMC_IBSOPCTL */
133 pc[0].reg_num = outp.pfp_pmcs[0].reg_num;
134 pc[0].reg_value = outp.pfp_pmcs[0].reg_value;
135 /* PMD_IBSOPCTL */
136 pd[0].reg_num = outp.pfp_pmds[0].reg_num;
137 pd[0].reg_value = 0;
138 /* setup sampling */
140 pd[0].reg_flags = PFM_REGFL_OVFL_NOTIFY;
141 /* add range check here */
142 pd[0].reg_smpl_pmds[0] =
143 ((1UL << PMD_IBSOP_NUM) - 1) << outp.pfp_pmds[0].reg_num;
144 /* write pc and pd to PMU */
146 ...
147
149 Refer to the description of the pfm_dispatch_events() function for
150 errors.
151
153 pfm_dispatch_events(3) and set of examples shipped with the library
154
156 Stephane Eranian <eranian@gmail.com>
157 Robert Richter <robert.richter@amd.com>
158 April, 2008 LIBPFM(3)