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