6 libperf-counting - counting interface
10 The counting interface provides API to measure and get count for specific perf events.
12 The following test tries to explain count on `counting.c` example.
14 It is by no means complete guide to counting, but shows libperf basic API for counting.
16 The `counting.c` comes with libperf package and can be compiled and run like:
20 $ gcc -o counting counting.c -lperf
22 count 176792, enabled 176944, run 176944
23 count 176242, enabled 176242, run 176242
26 It requires root access, because of the `PERF_COUNT_SW_CPU_CLOCK` event,
27 which is available only for root.
29 The `counting.c` example monitors two events on the current process and displays
30 their count, in a nutshell it:
33 * adds them to the event list
34 * opens and enables events through the event list
37 * reads and displays event counts
38 * destroys the event list
40 The first thing you need to do before using libperf is to call init function:
44 8 static int libperf_print(enum libperf_print_level level,
45 9 const char *fmt, va_list ap)
47 11 return vfprintf(stderr, fmt, ap);
50 14 int main(int argc, char **argv)
53 35 libperf_init(libperf_print);
56 It will setup the library and sets function for debug output from library.
58 The `libperf_print` callback will receive any message with its debug level,
63 enum libperf_print_level {
73 Once the setup is complete we start by defining specific events using the `struct perf_event_attr`.
75 We create software events for cpu and task:
79 20 struct perf_event_attr attr1 = {
80 21 .type = PERF_TYPE_SOFTWARE,
81 22 .config = PERF_COUNT_SW_CPU_CLOCK,
82 23 .read_format = PERF_FORMAT_TOTAL_TIME_ENABLED|PERF_FORMAT_TOTAL_TIME_RUNNING,
85 26 struct perf_event_attr attr2 = {
86 27 .type = PERF_TYPE_SOFTWARE,
87 28 .config = PERF_COUNT_SW_TASK_CLOCK,
88 29 .read_format = PERF_FORMAT_TOTAL_TIME_ENABLED|PERF_FORMAT_TOTAL_TIME_RUNNING,
93 The `read_format` setup tells perf to include timing details together with each count.
95 Next step is to prepare threads map.
97 In this case we will monitor current process, so we create threads map with single pid (0):
101 37 threads = perf_thread_map__new_dummy();
103 39 fprintf(stderr, "failed to create threads\n");
107 43 perf_thread_map__set_pid(threads, 0, 0);
110 Now we create libperf's event list, which will serve as holder for the events we want:
114 45 evlist = perf_evlist__new();
116 47 fprintf(stderr, "failed to create evlist\n");
121 We create libperf's events for the attributes we defined earlier and add them to the list:
125 51 evsel = perf_evsel__new(&attr1);
127 53 fprintf(stderr, "failed to create evsel1\n");
131 57 perf_evlist__add(evlist, evsel);
133 59 evsel = perf_evsel__new(&attr2);
135 61 fprintf(stderr, "failed to create evsel2\n");
139 65 perf_evlist__add(evlist, evsel);
142 Configure event list with the thread map and open events:
146 67 perf_evlist__set_maps(evlist, NULL, threads);
148 69 err = perf_evlist__open(evlist);
150 71 fprintf(stderr, "failed to open evsel\n");
155 Both events are created as disabled (note the `disabled = 1` assignment above),
156 so we need to enable the whole list explicitly (both events).
158 From this moment events are counting and we can do our workload.
160 When we are done we disable the events list.
164 75 perf_evlist__enable(evlist);
168 79 perf_evlist__disable(evlist);
171 Now we need to get the counts from events, following code iterates through the
172 events list and read counts:
176 81 perf_evlist__for_each_evsel(evlist, evsel) {
177 82 perf_evsel__read(evsel, 0, 0, &counts);
178 83 fprintf(stdout, "count %llu, enabled %llu, run %llu\n",
179 84 counts.val, counts.ena, counts.run);
185 We close the whole events list (both events) and remove it together with the threads map:
189 87 perf_evlist__close(evlist);
192 90 perf_evlist__delete(evlist);
194 92 perf_thread_map__put(threads);
205 libperf is Free Software licensed under the GNU LGPL 2.1
209 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
213 libperf(3), libperf-sampling(7)