| blob | e165c18f8422962509ba49fef0563af84a74f9a8 |
1 .\" $NetBSD: pmc.3,v 1.5 2003/04/16 13:35:13 wiz Exp $
2 .\"
3 .\" Copyright (c) 2002 Wasabi Systems, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed for the NetBSD Project by
19 .\" Wasabi Systems, Inc.
20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
21 .\" or promote products derived from this software without specific prior
22 .\" written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC
28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 .\" POSSIBILITY OF SUCH DAMAGE.
35 .\"
36 .Dd August 8, 2002
37 .Dt PMC 3
38 .Os
39 .Sh NAME
40 .Nm pmc_configure_counter ,
41 .Nm pmc_start_counter ,
42 .Nm pmc_stop_counter ,
43 .Nm pmc_get_num_counters ,
44 .Nm pmc_get_counter_class ,
45 .Nm pmc_get_counter_type ,
46 .Nm pmc_get_counter_value ,
47 .Nm pmc_get_accumulated_counter_value ,
48 .Nm pmc_get_counter_class_name ,
49 .Nm pmc_get_counter_type_name ,
50 .Nm pmc_get_counter_event_name ,
51 .Nm pmc_get_counter_event_list
52 .Nd performance counter interface library
53 .Sh LIBRARY
54 .Lb libpmc
55 .Sh SYNOPSIS
56 .In pmc.h
57 .Ft int
58 .Fn pmc_configure_counter "int ctr" "const char *evname" \
59 "pmc_ctr_t reset_val" "uint32_t flags"
60 .Ft int
61 .Fn pmc_start_counter "int ctr"
62 .Ft int
63 .Fn pmc_stop_counter "int ctr"
64 .Ft int
65 .Fn pmc_get_num_counters "void"
66 .Ft int
67 .Fn pmc_get_counter_class "void"
68 .Ft int
69 .Fn pmc_get_counter_type "int ctr" "int *typep"
70 .Ft int
71 .Fn pmc_get_counter_value "int ctr" "uint64_t *valp"
72 .Ft int
73 .Fn pmc_get_accumulated_counter_value "int ctr" "uint64_t *valp"
74 .Ft const char *
75 .Fn pmc_get_counter_class_name "int class"
76 .Ft const char *
77 .Fn pmc_get_counter_type_name "int type"
78 .Ft const char *
79 .Fn pmc_get_counter_event_name "pmc_evid_t event"
80 .Ft const struct pmc_event *
81 .Fn pmc_get_counter_event_list "void"
82 .Sh DESCRIPTION
83 The
84 .Nm pmc
85 library is an interface to performance monitoring counters available
86 on some CPUs.
87 .Pp
88 The
89 .Nm pmc
90 library can count events on the following CPU families.
91 Each second-level entry describes a performance counter class.
92 A given class may apply to multiple individual CPU models.
93 Each class has one or more counter types.
94 A CPU may have more than one counter of a given type.
95 Refer to the corresponding processor programmer's manual for
96 more information about individual events.
97 .Bl -bullet
98 .It
99 ARM
100 .Bl -bullet
101 .It
102 Intel i80200
103 .Pq PMC_CLASS_I80200
104 .Pp
105 There are two types of counters available in this class:
106 .Bl -tag -width PMC_TYPE_I80200_CCNTxx
107 .It PMC_TYPE_I80200_CCNT
108 cycle counter
109 .It PMC_TYPE_I80200_PMCx
110 performance counter
111 .El
112 .Pp
113 The following events may be counted by a counter of type
114 PMC_TYPE_I80200_CCNT:
115 .Pp
116 .Bl -item -offset indent -compact
117 .It
118 clock
119 .It
120 clock-div-64
121 .El
122 .Pp
123 The following events may be counted by a counter of type
124 PMC_TYPE_I80200_PMCx:
125 .Pp
126 .Bl -item -offset indent -compact
127 .It
128 insfetch-miss
129 .It
130 insfetch-stall
131 .It
132 datadep-stall
133 .It
134 itlb-miss
135 .It
136 dtlb-miss
137 .It
138 branch-taken
139 .It
140 branch-mispredicted
141 .It
142 instruction-executed
143 .It
144 dcachebufffull-stall-time
145 .It
146 dcachebufffull-stall-count
147 .It
148 dcache-access
149 .It
150 dcache-miss
151 .It
152 dcache-writeback
153 .It
154 swchange-pc
155 .It
156 bcu-mem-request
157 .It
158 bcu-queue-full
159 .It
160 bcu-queue-drain
161 .It
162 bcu-ecc-no-elog
163 .It
164 bcu-1bit-error
165 .It
166 narrow-ecc-caused-rmw
167 .El
168 .El
169 .It
170 i386
171 .Bl -bullet
172 .It
173 Intel i586
174 .Pq PMC_CLASS_I586
175 .Pp
176 There are two types of counters available in this class:
177 .Bl -tag -width PMC_TYPE_I586_PMCxxx
178 .It PMC_TYPE_I586_TSC
179 cycle counter
180 .It PMC_TYPE_I586_PMCx
181 performance counter
182 .El
183 .Pp
184 The following events may be counted by a counter of type
185 PMC_TYPE_I586_PMCx:
186 .Pp
187 .Bl -item -offset indent -compact
188 .It
189 tlb-data-miss
190 .It
191 tlb-ins-miss
192 .It
193 l1cache-ins-miss
194 .It
195 l1cache-data-miss
196 .It
197 l1cache-data-miss-read
198 .It
199 l1cache-data-miss-write
200 .It
201 l1cache-writeback
202 .It
203 l1cache-writeback-hit
204 .It
205 l2cache-data-snoop
206 .It
207 l2cache-data-snoop-hit
208 .It
209 mem-read
210 .It
211 mem-write
212 .It
213 mem-access
214 .It
215 mem-access-both-pipes
216 .It
217 mem-bank-conflicts
218 .It
219 mem-misalign-ref
220 .It
221 mem-uncached-read
222 .It
223 seg-load-any
224 .It
225 branch
226 .It
227 branch-btb-hit
228 .It
229 branch-taken
230 .It
231 ins-read
232 .It
233 ins-pipeline-flush
234 .It
235 ins-executed
236 .It
237 ins-executed-vpipe
238 .It
239 ins-stall-agi
240 .It
241 ins-stall-write
242 .It
243 ins-stall-data
244 .It
245 ins-stall-writeline
246 .It
247 bus-utilization
248 .It
249 bus-locked
250 .It
251 bus-io-cycle
252 .It
253 fpu-flops
254 .It
255 int-hw
256 .It
257 break-match0
258 .It
259 break-match1
260 .It
261 break-match2
262 .It
263 break-match3
264 .El
265 .It
266 Intel i686
267 .Pq PMC_CLASS_I686
268 .Pp
269 There are two types of counters available in this class:
270 .Bl -tag -width PMC_TYPE_I686_PMCxxx
271 .It PMC_TYPE_I686_TSC
272 cycle counter
273 .It PMC_TYPE_I686_PMCx
274 performance counter
275 .El
276 .Pp
277 The following events may be counted by a counter of type
278 PMC_TYPE_I686_PMCx:
279 .Pp
280 .Bl -item -offset indent -compact
281 .It
282 mem-refs
283 .It
284 l1cache-lines
285 .It
286 l1cache-mlines
287 .It
288 l1cache-mlines-evict
289 .It
290 l1cache-miss-wait
291 .It
292 ins-fetch
293 .It
294 ins-fetch-misses
295 .It
296 itlb-misses
297 .It
298 insfetch-mem-stall
299 .It
300 insfetch-decode-stall
301 .It
302 l2cache-insfetch
303 .It
304 l2cache-data-loads
305 .It
306 l2cache-data-stores
307 .It
308 l2cache-lines
309 .It
310 l2cache-lines-evict
311 .It
312 l2cache-mlines
313 .It
314 l2cache-mlines-evict
315 .It
316 l2cache-reqs
317 .It
318 l2cache-addr-strobes
319 .It
320 l2cache-data-busy
321 .It
322 l2cache-data-busy-read
323 .It
324 bus-drdy-clocks-self
325 .It
326 bus-drdy-clocks-any
327 .It
328 bus-lock-clocks-self
329 .It
330 bus-lock-clocks-any
331 .It
332 bus-req-outstanding-self
333 .It
334 bus-req-outstanding-any
335 .It
336 bus-burst-reads-self
337 .It
338 bus-burst-reads-any
339 .It
340 bus-read-for-ownership-self
341 .It
342 bus-read-for-ownership-any
343 .It
344 bus-write-back-self
345 .It
346 bus-write-back-any
347 .It
348 bus-ins-fetches-self
349 .It
350 bus-ins-fetches-any
351 .It
352 bus-invalidates-self
353 .It
354 bus-invalidates-any
355 .It
356 bus-partial-writes-self
357 .It
358 bus-partial-writes-any
359 .It
360 bus-partial-trans-self
361 .It
362 bus-partial-trans-any
363 .It
364 bus-io-trans-self
365 .It
366 bus-io-trans-any
367 .It
368 bus-deferred-trans-self
369 .It
370 bus-deferred-trans-any
371 .It
372 bus-burst-trans-self
373 .It
374 bus-burst-trans-any
375 .It
376 bus-total-trans-self
377 .It
378 bus-total-trans-any
379 .It
380 bus-mem-trans-self
381 .It
382 bus-mem-trans-any
383 .It
384 bus-recv-cycles
385 .It
386 bus-bnr-cycles
387 .It
388 bus-hit-cycles
389 .It
390 bus-hitm-cycles
391 .It
392 bus-snoop-stall
393 .It
394 fpu-flops
395 .It
396 fpu-comp-ops
397 .It
398 fpu-except-assist
399 .It
400 fpu-mul
401 .It
402 fpu-div
403 .It
404 fpu-div-busy
405 .It
406 mem-sb-blocks
407 .It
408 mem-sb-drains
409 .It
410 mem-misalign-ref
411 .It
412 ins-pref-dispatch-nta
413 .It
414 ins-pref-dispatch-t1
415 .It
416 ins-pref-dispatch-t2
417 .It
418 ins-pref-dispatch-weak
419 .It
420 ins-pref-miss-nta
421 .It
422 ins-pref-miss-t1
423 .It
424 ins-pref-miss-t2
425 .It
426 ins-pref-miss-weak
427 .It
428 ins-retired
429 .It
430 uops-retired
431 .It
432 ins-decoded
433 .It
434 ins-stream-retired-packed-scalar
435 .It
436 ins-stream-retired-scalar
437 .It
438 ins-stream-comp-retired-packed-scalar
439 .It
440 ins-stream-comp-retired-scalar
441 .It
442 int-hw
443 .It
444 int-cycles-masked
445 .It
446 int-cycles-masked-pending
447 .It
448 branch-retired
449 .It
450 branch-miss-retired
451 .It
452 branch-taken-retired
453 .It
454 branch-taken-mispred-retired
455 .It
456 branch-decoded
457 .It
458 branch-btb-miss
459 .It
460 branch-bogus
461 .It
462 branch-baclear
463 .It
464 stall-resource
465 .It
466 stall-partial
467 .It
468 seg-loads
469 .It
470 unhalted-cycles
471 .It
472 mmx-exec
473 .It
474 mmx-sat-exec
475 .It
476 mmx-uops-exec
477 .It
478 mmx-exec-packed-mul
479 .It
480 mmx-exec-packed-shift
481 .It
482 mmx-exec-pack-ops
483 .It
484 mmx-exec-unpack-ops
485 .It
486 mmx-exec-packed-logical
487 .It
488 mmx-exec-packed-arith
489 .It
490 mmx-trans-mmx-float
491 .It
492 mmx-trans-float-mmx
493 .It
494 mmx-assist
495 .It
496 mmx-retire
497 .It
498 seg-rename-stalls-es
499 .It
500 seg-rename-stalls-ds
501 .It
502 seg-rename-stalls-fs
503 .It
504 seg-rename-stalls-gs
505 .It
506 seg-rename-stalls-all
507 .It
508 seg-rename-es
509 .It
510 seg-rename-ds
511 .It
512 seg-rename-fs
513 .It
514 seg-rename-gs
515 .It
516 seg-rename-all
517 .It
518 seg-rename-retire
519 .El
520 .It
521 AMD Athlon / K7
522 .Pq PMC_CLASS_K7
523 .Pp
524 There are two types of counters available in this class:
525 .Bl -tag -width PMC_TYPE_K7_PMCxxx
526 .It PMC_TYPE_K7_TSC
527 cycle counter
528 .It PMC_TYPE_K7_PMCx
529 performance counter
530 .El
531 .Pp
532 The following events may be counted by a counter of type
533 PMC_TYPE_K7_PMCx:
534 .Pp
535 .Bl -item -offset indent -compact
536 .It
537 seg-load-all
538 .It
539 seg-load-es
540 .It
541 seg-load-cs
542 .It
543 seg-load-ss
544 .It
545 seg-load-ds
546 .It
547 seg-load-fs
548 .It
549 seg-load-gs
550 .It
551 seg-load-hs
552 .It
553 seg-load-stall
554 .It
555 l1cache-access
556 .It
557 l1cache-miss
558 .It
559 l1cache-refill
560 .It
561 l1cache-refill-invalid
562 .It
563 l1cache-refill-shared
564 .It
565 l1cache-refill-exclusive
566 .It
567 l1cache-refill-owner
568 .It
569 l1cache-refill-modified
570 .It
571 l1cache-load
572 .It
573 l1cache-load-invalid
574 .It
575 l1cache-load-shared
576 .It
577 l1cache-load-exclusive
578 .It
579 l1cache-load-owner
580 .It
581 l1cache-load-modified
582 .It
583 l1cache-writeback
584 .It
585 l1cache-writeback-invalid
586 .It
587 l1cache-writeback-shared
588 .It
589 l1cache-writeback-exclusive
590 .It
591 l1cache-writeback-owner
592 .It
593 l1cache-writeback-modified
594 .It
595 l2cache-access
596 .It
597 l2cache-tag-read
598 .It
599 l2cache-tag-write
600 .It
601 l2cache-inst-read
602 .It
603 l2cache-inst-load
604 .It
605 l2cache-data-store
606 .It
607 l2cache-data-loadmem
608 .It
609 l2cache-data-write
610 .It
611 l2cache-data-move
612 .It
613 l2cache-access-busy
614 .It
615 l2cache-hit
616 .It
617 l2cache-miss
618 .It
619 mem-misalign-ref
620 .It
621 mem-access
622 .It
623 mem-access-uc
624 .It
625 mem-access-wc
626 .It
627 mem-access-wt
628 .It
629 mem-access-wp
630 .It
631 mem-access-wb
632 .It
633 ins-fetch
634 .It
635 ins-fetch-miss
636 .It
637 ins-refill-l2
638 .It
639 ins-refill-mem
640 .It
641 ins-fetch-stall
642 .It
643 ins-retired
644 .It
645 ins-empty
646 .It
647 itlb-miss-l1
648 .It
649 itlb-miss-l2
650 .It
651 ops-retired
652 .It
653 branch-retired
654 .It
655 branch-miss-retired
656 .It
657 branch-taken-retired
658 .It
659 branch-taken-miss-retired
660 .It
661 branch-far-retired
662 .It
663 branch-resync-retired
664 .It
665 branch-near-retired
666 .It
667 branch-near-miss-retired
668 .It
669 branch-indirect-miss-retired
670 .It
671 int-hw
672 .It
673 int-cycles-masked
674 .It
675 int-cycles-masked-pending
676 .It
677 break-match0
678 .It
679 break-match1
680 .It
681 break-match2
682 .It
683 break-match3
684 .El
685 .El
686 .El
687 .Pp
688 The
689 .Nm pmc
690 library maintains a mapping between event names and the event selector
691 used by the CPU's performance monitoring hardware.
692 The mapping is described by the following structure:
693 .Bd -literal -offset indent
694 struct pmc_event {
695 const char *name;
696 pmc_evid_t val;
697 };
698 .Ed
699 .Pp
700 The
701 .Fn pmc_configure_counter
702 function configures the counter
703 .Fa ctr
704 to count the event
705 .Fa evname .
706 The initial value of the counter will be set to
707 .Fa reset_val ,
708 and this value will be loaded back into the counter each time it overflows.
709 There are currently no flags defined for the
710 .Fa flags
711 argument.
712 .Pp
713 The
714 .Fn pmc_start_counter
715 function enables counting on counter
716 .Fa ctr .
717 .Pp
718 The
719 .Fn pmc_stop_counter
720 function disables counting on counter
721 .Fa ctr .
722 .Pp
723 The
724 .Fn pmc_get_num_counters
725 function returns the number of counters present in the CPU.
726 .Pp
727 The
728 .Fn pmc_get_counter_class
729 function returns the counter class of the CPU.
730 .Pp
731 The
732 .Fn pmc_get_counter_type
733 function places the counter type of counter
734 .Fa ctr
735 into
736 .Fa *typep .
737 .Pp
738 The
739 .Fn pmc_get_counter_value
740 function places the total number of events counted by counter
741 .Fa ctr
742 into
743 .Fa *valp .
744 .Pp
745 The
746 .Fn pmc_get_accumulated_counter_value
747 function places the total number of events counted for the current
748 process and all of its children by counter
749 .Fa ctr
750 into
751 .Fa *valp .
752 .Pp
753 The
754 .Fn pmc_get_counter_class_name
755 function returns the name of the counter class
756 .Fa classval .
757 .Pp
758 The
759 .Fn pmc_get_counter_type_name
760 function returns the name of the counter type
761 .Fa type .
762 .Pp
763 The
764 .Fn pmc_get_counter_event_name
765 function returns the name of the event
766 .Fa event
767 for the current CPU's performance counter class.
768 .Pp
769 The
770 .Fn pmc_get_counter_event_list
771 function returns an array of
772 .Em pmc_event
773 structures, listing the supported event types for the CPU.
774 The array is terminated by and entry who's
775 .Em name
776 member is NULL.
777 .Sh RETURN VALUES
778 The
779 .Fn pmc_configure_counter ,
780 .Fn pmc_start_counter ,
781 .Fn pmc_stop_counter ,
782 .Fn pmc_get_counter_type ,
783 .Fn pmc_get_counter_value ,
784 and
785 .Fn pmc_get_accumulated_counter_value
786 functions return 0 to indicate success and \-1 to indicate failure,
787 in which case
788 .Xr errno 2
789 will be set to indicate the mode of failure.
790 .Pp
791 The
792 .Fn pmc_get_counter_class_name ,
793 .Fn pmc_get_counter_type_name ,
794 .Fn pmc_get_counter_event_name ,
795 and
796 .Fn pmc_get_counter_event_list
797 functions return NULL and set
798 .Xr errno 2
799 to indicate failure.
800 .Sh SEE ALSO
801 .Xr pmc 1 ,
802 .Xr pmc_control 2 ,
803 .Xr pmc_get_info 2 ,
804 .Xr pmc 9
805 .Sh HISTORY
806 The
807 .Nm pmc
808 library first appeared in
809 .Nx 2.0 .
810 .Sh AUTHORS
811 The
812 .Nm pmc
813 library was written by
814 .An Jason R. Thorpe
815 .Aq thorpej@wasabisystems.com
816 and contributed by Wasabi Systems, Inc.