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(NULL);
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 <linux-perf-users@vger.kernel.org>.
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)
245