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
libpmc

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.