Manual browser: pmc(3)

Section:
Page:
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 7.0
Back to the section
Back to the homepage