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.
- ARM
- 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:
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
- i386
- 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
- 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
- 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
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.