PMC(3)

PMC(3) | 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.

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

August 8, 2002 | NetBSD 8.3