summaryrefslogtreecommitdiffstats
path: root/tools/lib/perf/Documentation/libperf-sampling.txt
blob: 2378980fab8a6b263e44ed3c5bb0f7ae9ed35ce1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
libperf-sampling(7)
===================

NAME
----
libperf-sampling - sampling interface


DESCRIPTION
-----------
The sampling interface provides API to measure and get count for specific perf events.

The following test tries to explain count on `sampling.c` example.

It is by no means complete guide to sampling, but shows libperf basic API for sampling.

The `sampling.c` comes with libperf package and can be compiled and run like:

[source,bash]
--
$ gcc -o sampling sampling.c -lperf
$ sudo ./sampling
cpu   0, pid      0, tid      0, ip     ffffffffad06c4e6, period                    1
cpu   0, pid   4465, tid   4469, ip     ffffffffad118748, period             18322959
cpu   0, pid      0, tid      0, ip     ffffffffad115722, period             33544846
cpu   0, pid   4465, tid   4470, ip         7f84fe0cdad6, period             23687474
cpu   0, pid      0, tid      0, ip     ffffffffad9e0349, period             34255790
cpu   0, pid   4465, tid   4469, ip     ffffffffad136581, period             38664069
cpu   0, pid      0, tid      0, ip     ffffffffad9e55e2, period             21922384
cpu   0, pid   4465, tid   4470, ip         7f84fe0ebebf, period             17655175
...
--

It requires root access, because it uses hardware cycles event.

The `sampling.c` example profiles/samples all CPUs with hardware cycles, in a
nutshell it:

- creates events
- adds them to the event list
- opens and enables events through the event list
- sleeps for 3 seconds
- disables events
- reads and displays recorded samples
- destroys the event list

The first thing you need to do before using libperf is to call init function:

[source,c]
--
 12 static int libperf_print(enum libperf_print_level level,
 13                          const char *fmt, va_list ap)
 14 {
 15         return vfprintf(stderr, fmt, ap);
 16 }

 23 int main(int argc, char **argv)
 24 {
 ...
 40         libperf_init(libperf_print);
--

It will setup the library and sets function for debug output from library.

The `libperf_print` callback will receive any message with its debug level,
defined as:

[source,c]
--
enum libperf_print_level {
        LIBPERF_ERR,
        LIBPERF_WARN,
        LIBPERF_INFO,
        LIBPERF_DEBUG,
        LIBPERF_DEBUG2,
        LIBPERF_DEBUG3,
};
--

Once the setup is complete we start by defining cycles event using the `struct perf_event_attr`:

[source,c]
--
 29         struct perf_event_attr attr = {
 30                 .type        = PERF_TYPE_HARDWARE,
 31                 .config      = PERF_COUNT_HW_CPU_CYCLES,
 32                 .disabled    = 1,
 33                 .freq        = 1,
 34                 .sample_freq = 10,
 35                 .sample_type = PERF_SAMPLE_IP|PERF_SAMPLE_TID|PERF_SAMPLE_CPU|PERF_SAMPLE_PERIOD,
 36         };
--

Next step is to prepare CPUs map.

In this case we will monitor all the available CPUs:

[source,c]
--
 42         cpus = perf_cpu_map__new_online_cpus();
 43         if (!cpus) {
 44                 fprintf(stderr, "failed to create cpus\n");
 45                 return -1;
 46         }
--

Now we create libperf's event list, which will serve as holder for the cycles event:

[source,c]
--
 48         evlist = perf_evlist__new();
 49         if (!evlist) {
 50                 fprintf(stderr, "failed to create evlist\n");
 51                 goto out_cpus;
 52         }
--

We create libperf's event for the cycles attribute we defined earlier and add it to the list:

[source,c]
--
 54         evsel = perf_evsel__new(&attr);
 55         if (!evsel) {
 56                 fprintf(stderr, "failed to create cycles\n");
 57                 goto out_cpus;
 58         }
 59
 60         perf_evlist__add(evlist, evsel);
--

Configure event list with the cpus map and open event:

[source,c]
--
 62         perf_evlist__set_maps(evlist, cpus, NULL);
 63
 64         err = perf_evlist__open(evlist);
 65         if (err) {
 66                 fprintf(stderr, "failed to open evlist\n");
 67                 goto out_evlist;
 68         }
--

Once the events list is open, we can create memory maps AKA perf ring buffers:

[source,c]
--
 70         err = perf_evlist__mmap(evlist, 4);
 71         if (err) {
 72                 fprintf(stderr, "failed to mmap evlist\n");
 73                 goto out_evlist;
 74         }
--

The event is created as disabled (note the `disabled = 1` assignment above),
so we need to enable the events list explicitly.

From this moment the cycles event is sampling.

We will sleep for 3 seconds while the ring buffers get data from all CPUs, then we disable the events list.

[source,c]
--
 76         perf_evlist__enable(evlist);
 77         sleep(3);
 78         perf_evlist__disable(evlist);
--

Following code walks through the ring buffers and reads stored events/samples:

[source,c]
--
 80         perf_evlist__for_each_mmap(evlist, map, false) {
 81                 if (perf_mmap__read_init(map) < 0)
 82                         continue;
 83
 84                 while ((event = perf_mmap__read_event(map)) != NULL) {

                            /* process event */

108                         perf_mmap__consume(map);
109                 }
110                 perf_mmap__read_done(map);
111         }

--

Each sample needs to get parsed:

[source,c]
--
 85                         int cpu, pid, tid;
 86                         __u64 ip, period, *array;
 87                         union u64_swap u;
 88
 89                         array = event->sample.array;
 90
 91                         ip = *array;
 92                         array++;
 93
 94                         u.val64 = *array;
 95                         pid = u.val32[0];
 96                         tid = u.val32[1];
 97                         array++;
 98
 99                         u.val64 = *array;
100                         cpu = u.val32[0];
101                         array++;
102
103                         period = *array;
104
105                         fprintf(stdout, "cpu %3d, pid %6d, tid %6d, ip %20llx, period %20llu\n",
106                                 cpu, pid, tid, ip, period);
--

And finally cleanup.

We close the whole events list (both events) and remove it together with the threads map:

[source,c]
--
113 out_evlist:
114         perf_evlist__delete(evlist);
115 out_cpus:
116         perf_cpu_map__put(cpus);
117         return err;
118 }
--

REPORTING BUGS
--------------
Report bugs to <linux-perf-users@vger.kernel.org>.

LICENSE
-------
libperf is Free Software licensed under the GNU LGPL 2.1

RESOURCES
---------
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

SEE ALSO
--------
libperf(3), libperf-counting(7)