PMC(3)							   BSD Library Functions Manual 						    PMC(3)

NAME

     pmc_configure_counter, pmc_start_counter, pmc_stop_counter, pmc_get_num_counters, pmc_get_counter_class, pmc_get_counter_type,
     pmc_get_counter_value, pmc_get_accumulated_counter_value, pmc_get_counter_class_name, pmc_get_counter_type_name, pmc_get_counter_event_name,
     pmc_get_counter_event_list -- performance counter interface library

LIBRARY

     Performance Counters Library (libpmc, -lpmc)

SYNOPSIS

     #include <pmc.h>

     int
     pmc_configure_counter(int ctr, const char *evname, pmc_ctr_t reset_val, uint32_t flags);

     int
     pmc_start_counter(int ctr);

     int
     pmc_stop_counter(int ctr);

     int
     pmc_get_num_counters(void);

     int
     pmc_get_counter_class(void);

     int
     pmc_get_counter_type(int ctr, int *typep);

     int
     pmc_get_counter_value(int ctr, uint64_t *valp);

     int
     pmc_get_accumulated_counter_value(int ctr, uint64_t *valp);

     const char *
     pmc_get_counter_class_name(int class);

     const char *
     pmc_get_counter_type_name(int type);

     const char *
     pmc_get_counter_event_name(pmc_evid_t event);

     const struct pmc_event *
     pmc_get_counter_event_list(void);

DESCRIPTION

     The pmc library is an interface to performance monitoring counters available on some CPUs.

     The pmc library can count events on the following CPU families.  Each second-level entry describes a performance counter class.  A given
     class may apply to multiple individual CPU models.  Each class has one or more counter types.  A CPU may have more than one counter of a
     given type.  Refer to the corresponding processor programmer's manual for more information about individual events.

     o	 ARM

	 o   Intel i80200 (PMC_CLASS_I80200)

	     There are two types of counters available in this class:

	     PMC_TYPE_I80200_CCNT    cycle counter

	     PMC_TYPE_I80200_PMCx    performance counter

	     The following events may be counted by a counter of type PMC_TYPE_I80200_CCNT:

		   clock
		   clock-div-64

	     The following events may be counted by a counter of type PMC_TYPE_I80200_PMCx:

		   insfetch-miss
		   insfetch-stall
		   datadep-stall
		   itlb-miss
		   dtlb-miss
		   branch-taken
		   branch-mispredicted
		   instruction-executed
		   dcachebufffull-stall-time
		   dcachebufffull-stall-count
		   dcache-access
		   dcache-miss
		   dcache-writeback
		   swchange-pc
		   bcu-mem-request
		   bcu-queue-full
		   bcu-queue-drain
		   bcu-ecc-no-elog
		   bcu-1bit-error
		   narrow-ecc-caused-rmw

     o	 i386

	 o   Intel i586 (PMC_CLASS_I586)

	     There are two types of counters available in this class:

	     PMC_TYPE_I586_TSC	   cycle counter

	     PMC_TYPE_I586_PMCx    performance counter

	     The following events may be counted by a counter of type PMC_TYPE_I586_PMCx:

		   tlb-data-miss
		   tlb-ins-miss
		   l1cache-ins-miss
		   l1cache-data-miss
		   l1cache-data-miss-read
		   l1cache-data-miss-write
		   l1cache-writeback
		   l1cache-writeback-hit
		   l2cache-data-snoop
		   l2cache-data-snoop-hit
		   mem-read
		   mem-write
		   mem-access
		   mem-access-both-pipes
		   mem-bank-conflicts
		   mem-misalign-ref
		   mem-uncached-read
		   seg-load-any
		   branch
		   branch-btb-hit
		   branch-taken
		   ins-read
		   ins-pipeline-flush
		   ins-executed
		   ins-executed-vpipe
		   ins-stall-agi
		   ins-stall-write
		   ins-stall-data
		   ins-stall-writeline
		   bus-utilization
		   bus-locked
		   bus-io-cycle
		   fpu-flops
		   int-hw
		   break-match0
		   break-match1
		   break-match2
		   break-match3

	 o   Intel i686 (PMC_CLASS_I686)

	     There are two types of counters available in this class:

	     PMC_TYPE_I686_TSC	   cycle counter

	     PMC_TYPE_I686_PMCx    performance counter

	     The following events may be counted by a counter of type PMC_TYPE_I686_PMCx:

		   mem-refs
		   l1cache-lines
		   l1cache-mlines
		   l1cache-mlines-evict
		   l1cache-miss-wait
		   ins-fetch
		   ins-fetch-misses
		   itlb-misses
		   insfetch-mem-stall
		   insfetch-decode-stall
		   l2cache-insfetch
		   l2cache-data-loads
		   l2cache-data-stores
		   l2cache-lines
		   l2cache-lines-evict
		   l2cache-mlines
		   l2cache-mlines-evict
		   l2cache-reqs
		   l2cache-addr-strobes
		   l2cache-data-busy
		   l2cache-data-busy-read
		   bus-drdy-clocks-self
		   bus-drdy-clocks-any
		   bus-lock-clocks-self
		   bus-lock-clocks-any
		   bus-req-outstanding-self
		   bus-req-outstanding-any
		   bus-burst-reads-self
		   bus-burst-reads-any
		   bus-read-for-ownership-self
		   bus-read-for-ownership-any
		   bus-write-back-self
		   bus-write-back-any
		   bus-ins-fetches-self
		   bus-ins-fetches-any
		   bus-invalidates-self
		   bus-invalidates-any
		   bus-partial-writes-self
		   bus-partial-writes-any
		   bus-partial-trans-self
		   bus-partial-trans-any
		   bus-io-trans-self
		   bus-io-trans-any
		   bus-deferred-trans-self
		   bus-deferred-trans-any
		   bus-burst-trans-self
		   bus-burst-trans-any
		   bus-total-trans-self
		   bus-total-trans-any
		   bus-mem-trans-self
		   bus-mem-trans-any
		   bus-recv-cycles
		   bus-bnr-cycles
		   bus-hit-cycles
		   bus-hitm-cycles
		   bus-snoop-stall
		   fpu-flops
		   fpu-comp-ops
		   fpu-except-assist
		   fpu-mul
		   fpu-div
		   fpu-div-busy
		   mem-sb-blocks
		   mem-sb-drains
		   mem-misalign-ref
		   ins-pref-dispatch-nta
		   ins-pref-dispatch-t1
		   ins-pref-dispatch-t2
		   ins-pref-dispatch-weak
		   ins-pref-miss-nta
		   ins-pref-miss-t1
		   ins-pref-miss-t2
		   ins-pref-miss-weak
		   ins-retired
		   uops-retired
		   ins-decoded
		   ins-stream-retired-packed-scalar
		   ins-stream-retired-scalar
		   ins-stream-comp-retired-packed-scalar
		   ins-stream-comp-retired-scalar
		   int-hw
		   int-cycles-masked
		   int-cycles-masked-pending
		   branch-retired
		   branch-miss-retired
		   branch-taken-retired
		   branch-taken-mispred-retired
		   branch-decoded
		   branch-btb-miss
		   branch-bogus
		   branch-baclear
		   stall-resource
		   stall-partial
		   seg-loads
		   unhalted-cycles
		   mmx-exec
		   mmx-sat-exec
		   mmx-uops-exec
		   mmx-exec-packed-mul
		   mmx-exec-packed-shift
		   mmx-exec-pack-ops
		   mmx-exec-unpack-ops
		   mmx-exec-packed-logical
		   mmx-exec-packed-arith
		   mmx-trans-mmx-float
		   mmx-trans-float-mmx
		   mmx-assist
		   mmx-retire
		   seg-rename-stalls-es
		   seg-rename-stalls-ds
		   seg-rename-stalls-fs
		   seg-rename-stalls-gs
		   seg-rename-stalls-all
		   seg-rename-es
		   seg-rename-ds
		   seg-rename-fs
		   seg-rename-gs
		   seg-rename-all
		   seg-rename-retire

	 o   AMD Athlon / K7 (PMC_CLASS_K7)

	     There are two types of counters available in this class:

	     PMC_TYPE_K7_TSC	 cycle counter

	     PMC_TYPE_K7_PMCx	 performance counter

	     The following events may be counted by a counter of type PMC_TYPE_K7_PMCx:

		   seg-load-all
		   seg-load-es
		   seg-load-cs
		   seg-load-ss
		   seg-load-ds
		   seg-load-fs
		   seg-load-gs
		   seg-load-hs
		   seg-load-stall
		   l1cache-access
		   l1cache-miss
		   l1cache-refill
		   l1cache-refill-invalid
		   l1cache-refill-shared
		   l1cache-refill-exclusive
		   l1cache-refill-owner
		   l1cache-refill-modified
		   l1cache-load
		   l1cache-load-invalid
		   l1cache-load-shared
		   l1cache-load-exclusive
		   l1cache-load-owner
		   l1cache-load-modified
		   l1cache-writeback
		   l1cache-writeback-invalid
		   l1cache-writeback-shared
		   l1cache-writeback-exclusive
		   l1cache-writeback-owner
		   l1cache-writeback-modified
		   l2cache-access
		   l2cache-tag-read
		   l2cache-tag-write
		   l2cache-inst-read
		   l2cache-inst-load
		   l2cache-data-store
		   l2cache-data-loadmem
		   l2cache-data-write
		   l2cache-data-move
		   l2cache-access-busy
		   l2cache-hit
		   l2cache-miss
		   mem-misalign-ref
		   mem-access
		   mem-access-uc
		   mem-access-wc
		   mem-access-wt
		   mem-access-wp
		   mem-access-wb
		   ins-fetch
		   ins-fetch-miss
		   ins-refill-l2
		   ins-refill-mem
		   ins-fetch-stall
		   ins-retired
		   ins-empty
		   itlb-miss-l1
		   itlb-miss-l2
		   ops-retired
		   branch-retired
		   branch-miss-retired
		   branch-taken-retired
		   branch-taken-miss-retired
		   branch-far-retired
		   branch-resync-retired
		   branch-near-retired
		   branch-near-miss-retired
		   branch-indirect-miss-retired
		   int-hw
		   int-cycles-masked
		   int-cycles-masked-pending
		   break-match0
		   break-match1
		   break-match2
		   break-match3

     The pmc library maintains a mapping between event names and the event selector used by the CPU's performance monitoring hardware.	The map-
     ping is described by the following structure:

	   struct pmc_event {
		   const char *name;
		   pmc_evid_t val;
	   };

     The pmc_configure_counter() function configures the counter ctr to count the event evname.  The initial value of the counter will be set to
     reset_val, and this value will be loaded back into the counter each time it overflows.  There are currently no flags defined for the flags
     argument.

     The pmc_start_counter() function enables counting on counter ctr.

     The pmc_stop_counter() function disables counting on counter ctr.

     The pmc_get_num_counters() function returns the number of counters present in the CPU.

     The pmc_get_counter_class() function returns the counter class of the CPU.

     The pmc_get_counter_type() function places the counter type of counter ctr into *typep.

     The pmc_get_counter_value() function places the total number of events counted by counter ctr into *valp.

     The pmc_get_accumulated_counter_value() function places the total number of events counted for the current process and all of its children by
     counter ctr into *valp.

     The pmc_get_counter_class_name() function returns the name of the counter class classval.

     The pmc_get_counter_type_name() function returns the name of the counter type type.

     The pmc_get_counter_event_name() function returns the name of the event event for the current CPU's performance counter class.

     The pmc_get_counter_event_list() function returns an array of pmc_event structures, listing the supported event types for the CPU.  The array
     is terminated by and entry who's name member is NULL.

RETURN VALUES

     The pmc_configure_counter(), pmc_start_counter(), pmc_stop_counter(), pmc_get_counter_type(), pmc_get_counter_value(), and
     pmc_get_accumulated_counter_value() functions return 0 to indicate success and -1 to indicate failure, in which case errno(2) will be set to
     indicate the mode of failure.

     The pmc_get_counter_class_name(), pmc_get_counter_type_name(), pmc_get_counter_event_name(), and pmc_get_counter_event_list() functions
     return NULL and set errno(2) to indicate failure.

SEE ALSO

     pmc(1), pmc_control(2), pmc_get_info(2), pmc(9)

HISTORY

     The pmc library first appeared in NetBSD 2.0.

AUTHORS

     The pmc library was written by Jason R. Thorpe <thorpej@wasabisystems.com> and contributed by Wasabi Systems, Inc.

BSD
								  August 8, 2002							       BSD