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 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.
· 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:
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
· 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 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 ALSOpmc(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
