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

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