PMC(3)                  NetBSD 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 avail-
     able 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 infor-
     mation 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 mapping
     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 argu-
     ment.

     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 suc-
     cess 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.

NetBSD 5.0_STABLE               August 8, 2002               NetBSD 5.0_STABLE
