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.

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.