projects/linux·blob master · refs

244 lines · 6.5 KiB

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