August 8, 2002 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

```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 NetBSD2.0.

### AUTHORS

The pmc library was written by Jason R. Thorpe
<thorpej@wasabisystems.com> and contributed by Wasabi Systems, Inc.