1libperf-counting(7)
2===================
3
4NAME
5----
6libperf-counting - counting interface
7
8DESCRIPTION
9-----------
10The counting interface provides API to meassure and get count for specific perf events.
11
12The following test tries to explain count on `counting.c` example.
13
14It is by no means complete guide to counting, but shows libperf basic API for counting.
15
16The `counting.c` comes with libbperf package and can be compiled and run like:
17
18[source,bash]
19--
20$ gcc -o counting counting.c -lperf
21$ sudo ./counting
22count 176792, enabled 176944, run 176944
23count 176242, enabled 176242, run 176242
24--
25
26It requires root access, because of the `PERF_COUNT_SW_CPU_CLOCK` event,
27which is available only for root.
28
29The `counting.c` example monitors two events on the current process and displays their count, in a nutshel it:
30
31* creates events
32* adds them to the event list
33* opens and enables events through the event list
34* does some workload
35* disables events
36* reads and displays event counts
37* destroys the event list
38
39The first thing you need to do before using libperf is to call init function:
40
41[source,c]
42--
43  8 static int libperf_print(enum libperf_print_level level,
44  9                          const char *fmt, va_list ap)
45 10 {
46 11         return vfprintf(stderr, fmt, ap);
47 12 }
48
49 14 int main(int argc, char **argv)
50 15 {
51 ...
52 35         libperf_init(libperf_print);
53--
54
55It will setup the library and sets function for debug output from library.
56
57The `libperf_print` callback will receive any message with its debug level,
58defined as:
59
60[source,c]
61--
62enum libperf_print_level {
63        LIBPERF_ERR,
64        LIBPERF_WARN,
65        LIBPERF_INFO,
66        LIBPERF_DEBUG,
67        LIBPERF_DEBUG2,
68        LIBPERF_DEBUG3,
69};
70--
71
72Once the setup is complete we start by defining specific events using the `struct perf_event_attr`.
73
74We create software events for cpu and task:
75
76[source,c]
77--
78 20         struct perf_event_attr attr1 = {
79 21                 .type        = PERF_TYPE_SOFTWARE,
80 22                 .config      = PERF_COUNT_SW_CPU_CLOCK,
81 23                 .read_format = PERF_FORMAT_TOTAL_TIME_ENABLED|PERF_FORMAT_TOTAL_TIME_RUNNING,
82 24                 .disabled    = 1,
83 25         };
84 26         struct perf_event_attr attr2 = {
85 27                 .type        = PERF_TYPE_SOFTWARE,
86 28                 .config      = PERF_COUNT_SW_TASK_CLOCK,
87 29                 .read_format = PERF_FORMAT_TOTAL_TIME_ENABLED|PERF_FORMAT_TOTAL_TIME_RUNNING,
88 30                 .disabled    = 1,
89 31         };
90--
91
92The `read_format` setup tells perf to include timing details together with each count.
93
94Next step is to prepare threads map.
95
96In this case we will monitor current process, so we create threads map with single pid (0):
97
98[source,c]
99--
100 37         threads = perf_thread_map__new_dummy();
101 38         if (!threads) {
102 39                 fprintf(stderr, "failed to create threads\n");
103 40                 return -1;
104 41         }
105 42
106 43         perf_thread_map__set_pid(threads, 0, 0);
107--
108
109Now we create libperf's event list, which will serve as holder for the events we want:
110
111[source,c]
112--
113 45         evlist = perf_evlist__new();
114 46         if (!evlist) {
115 47                 fprintf(stderr, "failed to create evlist\n");
116 48                 goto out_threads;
117 49         }
118--
119
120We create libperf's events for the attributes we defined earlier and add them to the list:
121
122[source,c]
123--
124 51         evsel = perf_evsel__new(&attr1);
125 52         if (!evsel) {
126 53                 fprintf(stderr, "failed to create evsel1\n");
127 54                 goto out_evlist;
128 55         }
129 56
130 57         perf_evlist__add(evlist, evsel);
131 58
132 59         evsel = perf_evsel__new(&attr2);
133 60         if (!evsel) {
134 61                 fprintf(stderr, "failed to create evsel2\n");
135 62                 goto out_evlist;
136 63         }
137 64
138 65         perf_evlist__add(evlist, evsel);
139--
140
141Configure event list with the thread map and open events:
142
143[source,c]
144--
145 67         perf_evlist__set_maps(evlist, NULL, threads);
146 68
147 69         err = perf_evlist__open(evlist);
148 70         if (err) {
149 71                 fprintf(stderr, "failed to open evsel\n");
150 72                 goto out_evlist;
151 73         }
152--
153
154Both events are created as disabled (note the `disabled = 1` assignment above),
155so we need to enable the whole list explicitely (both events).
156
157From this moment events are counting and we can do our workload.
158
159When we are done we disable the events list.
160
161[source,c]
162--
163 75         perf_evlist__enable(evlist);
164 76
165 77         while (count--);
166 78
167 79         perf_evlist__disable(evlist);
168--
169
170Now we need to get the counts from events, following code iterates throught the events list and read counts:
171
172[source,c]
173--
174 81         perf_evlist__for_each_evsel(evlist, evsel) {
175 82                 perf_evsel__read(evsel, 0, 0, &counts);
176 83                 fprintf(stdout, "count %llu, enabled %llu, run %llu\n",
177 84                         counts.val, counts.ena, counts.run);
178 85         }
179--
180
181And finaly cleanup.
182
183We close the whole events list (both events) and remove it together with the threads map:
184
185[source,c]
186--
187 87         perf_evlist__close(evlist);
188 88
189 89 out_evlist:
190 90         perf_evlist__delete(evlist);
191 91 out_threads:
192 92         perf_thread_map__put(threads);
193 93         return err;
194 94 }
195--
196
197REPORTING BUGS
198--------------
199Report bugs to <linux-perf-users@vger.kernel.org>.
200
201LICENSE
202-------
203libperf is Free Software licensed under the GNU LGPL 2.1
204
205RESOURCES
206---------
207https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
208
209SEE ALSO
210--------
211libperf(3), libperf-sampling(7)
212