1 libperf-sampling(7) 1 libperf-sampling(7)
2 =================== 2 ===================
3 3
4 NAME 4 NAME
5 ---- 5 ----
6 libperf-sampling - sampling interface 6 libperf-sampling - sampling interface
7 7
8 8
9 DESCRIPTION 9 DESCRIPTION
10 ----------- 10 -----------
11 The sampling interface provides API to measure 11 The sampling interface provides API to measure and get count for specific perf events.
12 12
13 The following test tries to explain count on ` 13 The following test tries to explain count on `sampling.c` example.
14 14
15 It is by no means complete guide to sampling, 15 It is by no means complete guide to sampling, but shows libperf basic API for sampling.
16 16
17 The `sampling.c` comes with libperf package an 17 The `sampling.c` comes with libperf package and can be compiled and run like:
18 18
19 [source,bash] 19 [source,bash]
20 -- 20 --
21 $ gcc -o sampling sampling.c -lperf 21 $ gcc -o sampling sampling.c -lperf
22 $ sudo ./sampling 22 $ sudo ./sampling
23 cpu 0, pid 0, tid 0, ip ffffff 23 cpu 0, pid 0, tid 0, ip ffffffffad06c4e6, period 1
24 cpu 0, pid 4465, tid 4469, ip ffffff 24 cpu 0, pid 4465, tid 4469, ip ffffffffad118748, period 18322959
25 cpu 0, pid 0, tid 0, ip ffffff 25 cpu 0, pid 0, tid 0, ip ffffffffad115722, period 33544846
26 cpu 0, pid 4465, tid 4470, ip 7f 26 cpu 0, pid 4465, tid 4470, ip 7f84fe0cdad6, period 23687474
27 cpu 0, pid 0, tid 0, ip ffffff 27 cpu 0, pid 0, tid 0, ip ffffffffad9e0349, period 34255790
28 cpu 0, pid 4465, tid 4469, ip ffffff 28 cpu 0, pid 4465, tid 4469, ip ffffffffad136581, period 38664069
29 cpu 0, pid 0, tid 0, ip ffffff 29 cpu 0, pid 0, tid 0, ip ffffffffad9e55e2, period 21922384
30 cpu 0, pid 4465, tid 4470, ip 7f 30 cpu 0, pid 4465, tid 4470, ip 7f84fe0ebebf, period 17655175
31 ... 31 ...
32 -- 32 --
33 33
34 It requires root access, because it uses hardw 34 It requires root access, because it uses hardware cycles event.
35 35
36 The `sampling.c` example profiles/samples all 36 The `sampling.c` example profiles/samples all CPUs with hardware cycles, in a
37 nutshell it: 37 nutshell it:
38 38
39 - creates events 39 - creates events
40 - adds them to the event list 40 - adds them to the event list
41 - opens and enables events through the event l 41 - opens and enables events through the event list
42 - sleeps for 3 seconds 42 - sleeps for 3 seconds
43 - disables events 43 - disables events
44 - reads and displays recorded samples 44 - reads and displays recorded samples
45 - destroys the event list 45 - destroys the event list
46 46
47 The first thing you need to do before using li 47 The first thing you need to do before using libperf is to call init function:
48 48
49 [source,c] 49 [source,c]
50 -- 50 --
51 12 static int libperf_print(enum libperf_prin 51 12 static int libperf_print(enum libperf_print_level level,
52 13 const char *fmt, 52 13 const char *fmt, va_list ap)
53 14 { 53 14 {
54 15 return vfprintf(stderr, fmt, ap); 54 15 return vfprintf(stderr, fmt, ap);
55 16 } 55 16 }
56 56
57 23 int main(int argc, char **argv) 57 23 int main(int argc, char **argv)
58 24 { 58 24 {
59 ... 59 ...
60 40 libperf_init(libperf_print); 60 40 libperf_init(libperf_print);
61 -- 61 --
62 62
63 It will setup the library and sets function fo 63 It will setup the library and sets function for debug output from library.
64 64
65 The `libperf_print` callback will receive any 65 The `libperf_print` callback will receive any message with its debug level,
66 defined as: 66 defined as:
67 67
68 [source,c] 68 [source,c]
69 -- 69 --
70 enum libperf_print_level { 70 enum libperf_print_level {
71 LIBPERF_ERR, 71 LIBPERF_ERR,
72 LIBPERF_WARN, 72 LIBPERF_WARN,
73 LIBPERF_INFO, 73 LIBPERF_INFO,
74 LIBPERF_DEBUG, 74 LIBPERF_DEBUG,
75 LIBPERF_DEBUG2, 75 LIBPERF_DEBUG2,
76 LIBPERF_DEBUG3, 76 LIBPERF_DEBUG3,
77 }; 77 };
78 -- 78 --
79 79
80 Once the setup is complete we start by definin 80 Once the setup is complete we start by defining cycles event using the `struct perf_event_attr`:
81 81
82 [source,c] 82 [source,c]
83 -- 83 --
84 29 struct perf_event_attr attr = { 84 29 struct perf_event_attr attr = {
85 30 .type = PERF_TYPE_H 85 30 .type = PERF_TYPE_HARDWARE,
86 31 .config = PERF_COUNT_ 86 31 .config = PERF_COUNT_HW_CPU_CYCLES,
87 32 .disabled = 1, 87 32 .disabled = 1,
88 33 .freq = 1, 88 33 .freq = 1,
89 34 .sample_freq = 10, 89 34 .sample_freq = 10,
90 35 .sample_type = PERF_SAMPLE 90 35 .sample_type = PERF_SAMPLE_IP|PERF_SAMPLE_TID|PERF_SAMPLE_CPU|PERF_SAMPLE_PERIOD,
91 36 }; 91 36 };
92 -- 92 --
93 93
94 Next step is to prepare CPUs map. 94 Next step is to prepare CPUs map.
95 95
96 In this case we will monitor all the available 96 In this case we will monitor all the available CPUs:
97 97
98 [source,c] 98 [source,c]
99 -- 99 --
100 42 cpus = perf_cpu_map__new_online_cp 100 42 cpus = perf_cpu_map__new_online_cpus();
101 43 if (!cpus) { 101 43 if (!cpus) {
102 44 fprintf(stderr, "failed to 102 44 fprintf(stderr, "failed to create cpus\n");
103 45 return -1; 103 45 return -1;
104 46 } 104 46 }
105 -- 105 --
106 106
107 Now we create libperf's event list, which will 107 Now we create libperf's event list, which will serve as holder for the cycles event:
108 108
109 [source,c] 109 [source,c]
110 -- 110 --
111 48 evlist = perf_evlist__new(); 111 48 evlist = perf_evlist__new();
112 49 if (!evlist) { 112 49 if (!evlist) {
113 50 fprintf(stderr, "failed to 113 50 fprintf(stderr, "failed to create evlist\n");
114 51 goto out_cpus; 114 51 goto out_cpus;
115 52 } 115 52 }
116 -- 116 --
117 117
118 We create libperf's event for the cycles attri 118 We create libperf's event for the cycles attribute we defined earlier and add it to the list:
119 119
120 [source,c] 120 [source,c]
121 -- 121 --
122 54 evsel = perf_evsel__new(&attr); 122 54 evsel = perf_evsel__new(&attr);
123 55 if (!evsel) { 123 55 if (!evsel) {
124 56 fprintf(stderr, "failed to 124 56 fprintf(stderr, "failed to create cycles\n");
125 57 goto out_cpus; 125 57 goto out_cpus;
126 58 } 126 58 }
127 59 127 59
128 60 perf_evlist__add(evlist, evsel); 128 60 perf_evlist__add(evlist, evsel);
129 -- 129 --
130 130
131 Configure event list with the cpus map and ope 131 Configure event list with the cpus map and open event:
132 132
133 [source,c] 133 [source,c]
134 -- 134 --
135 62 perf_evlist__set_maps(evlist, cpus 135 62 perf_evlist__set_maps(evlist, cpus, NULL);
136 63 136 63
137 64 err = perf_evlist__open(evlist); 137 64 err = perf_evlist__open(evlist);
138 65 if (err) { 138 65 if (err) {
139 66 fprintf(stderr, "failed to 139 66 fprintf(stderr, "failed to open evlist\n");
140 67 goto out_evlist; 140 67 goto out_evlist;
141 68 } 141 68 }
142 -- 142 --
143 143
144 Once the events list is open, we can create me 144 Once the events list is open, we can create memory maps AKA perf ring buffers:
145 145
146 [source,c] 146 [source,c]
147 -- 147 --
148 70 err = perf_evlist__mmap(evlist, 4) 148 70 err = perf_evlist__mmap(evlist, 4);
149 71 if (err) { 149 71 if (err) {
150 72 fprintf(stderr, "failed to 150 72 fprintf(stderr, "failed to mmap evlist\n");
151 73 goto out_evlist; 151 73 goto out_evlist;
152 74 } 152 74 }
153 -- 153 --
154 154
155 The event is created as disabled (note the `di 155 The event is created as disabled (note the `disabled = 1` assignment above),
156 so we need to enable the events list explicitl 156 so we need to enable the events list explicitly.
157 157
158 From this moment the cycles event is sampling. 158 From this moment the cycles event is sampling.
159 159
160 We will sleep for 3 seconds while the ring buf 160 We will sleep for 3 seconds while the ring buffers get data from all CPUs, then we disable the events list.
161 161
162 [source,c] 162 [source,c]
163 -- 163 --
164 76 perf_evlist__enable(evlist); 164 76 perf_evlist__enable(evlist);
165 77 sleep(3); 165 77 sleep(3);
166 78 perf_evlist__disable(evlist); 166 78 perf_evlist__disable(evlist);
167 -- 167 --
168 168
169 Following code walks through the ring buffers 169 Following code walks through the ring buffers and reads stored events/samples:
170 170
171 [source,c] 171 [source,c]
172 -- 172 --
173 80 perf_evlist__for_each_mmap(evlist, 173 80 perf_evlist__for_each_mmap(evlist, map, false) {
174 81 if (perf_mmap__read_init(m 174 81 if (perf_mmap__read_init(map) < 0)
175 82 continue; 175 82 continue;
176 83 176 83
177 84 while ((event = perf_mmap_ 177 84 while ((event = perf_mmap__read_event(map)) != NULL) {
178 178
179 /* process event * 179 /* process event */
180 180
181 108 perf_mmap__consume 181 108 perf_mmap__consume(map);
182 109 } 182 109 }
183 110 perf_mmap__read_done(map); 183 110 perf_mmap__read_done(map);
184 111 } 184 111 }
185 185
186 -- 186 --
187 187
188 Each sample needs to get parsed: 188 Each sample needs to get parsed:
189 189
190 [source,c] 190 [source,c]
191 -- 191 --
192 85 int cpu, pid, tid; 192 85 int cpu, pid, tid;
193 86 __u64 ip, period, 193 86 __u64 ip, period, *array;
194 87 union u64_swap u; 194 87 union u64_swap u;
195 88 195 88
196 89 array = event->sam 196 89 array = event->sample.array;
197 90 197 90
198 91 ip = *array; 198 91 ip = *array;
199 92 array++; 199 92 array++;
200 93 200 93
201 94 u.val64 = *array; 201 94 u.val64 = *array;
202 95 pid = u.val32[0]; 202 95 pid = u.val32[0];
203 96 tid = u.val32[1]; 203 96 tid = u.val32[1];
204 97 array++; 204 97 array++;
205 98 205 98
206 99 u.val64 = *array; 206 99 u.val64 = *array;
207 100 cpu = u.val32[0]; 207 100 cpu = u.val32[0];
208 101 array++; 208 101 array++;
209 102 209 102
210 103 period = *array; 210 103 period = *array;
211 104 211 104
212 105 fprintf(stdout, "c 212 105 fprintf(stdout, "cpu %3d, pid %6d, tid %6d, ip %20llx, period %20llu\n",
213 106 cpu, pid, 213 106 cpu, pid, tid, ip, period);
214 -- 214 --
215 215
216 And finally cleanup. 216 And finally cleanup.
217 217
218 We close the whole events list (both events) a 218 We close the whole events list (both events) and remove it together with the threads map:
219 219
220 [source,c] 220 [source,c]
221 -- 221 --
222 113 out_evlist: 222 113 out_evlist:
223 114 perf_evlist__delete(evlist); 223 114 perf_evlist__delete(evlist);
224 115 out_cpus: 224 115 out_cpus:
225 116 perf_cpu_map__put(cpus); 225 116 perf_cpu_map__put(cpus);
226 117 return err; 226 117 return err;
227 118 } 227 118 }
228 -- 228 --
229 229
230 REPORTING BUGS 230 REPORTING BUGS
231 -------------- 231 --------------
232 Report bugs to <linux-perf-users@vger.kernel.or 232 Report bugs to <linux-perf-users@vger.kernel.org>.
233 233
234 LICENSE 234 LICENSE
235 ------- 235 -------
236 libperf is Free Software licensed under the GN 236 libperf is Free Software licensed under the GNU LGPL 2.1
237 237
238 RESOURCES 238 RESOURCES
239 --------- 239 ---------
240 https://git.kernel.org/pub/scm/linux/kernel/gi 240 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
241 241
242 SEE ALSO 242 SEE ALSO
243 -------- 243 --------
244 libperf(3), libperf-counting(7) 244 libperf(3), libperf-counting(7)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.