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 8.3