Tribblix: manual page: cpc_walk

CPC_SET_CREATE(3CPC) CPU Performance Counters Library Functions

NAME

cpc_set_create, cpc_set_destroy, cpc_set_add_request,
cpc_walk_requests - manage sets of counter requests

SYNOPSIS

cc [ flag... ] file... -lcpc [ library... ]
#include <libcpc.h>

cpc_set_t *cpc_set_create(cpc_t *cpc);

int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);

int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set,
const char *event, uint64_t preset, uint_t flags,
uint_t nattrs, const cpc_attr_t *attrs);

void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
void (*action)(void *arg, int index, const char *event,
uint64_t preset, uint_t flags, int nattrs,
const cpc_attr_t *attrs));

DESCRIPTION

The cpc_set_create() function returns an initialized and empty CPC
set. A CPC set contains some number of requests, where a request
represents a specific configuration of a hardware performance
instrumentation counter present on the processor. The cpc_set_t data
structure is opaque and must not be accessed directly by the
application.

Applications wanting to program one or more performance counters must
create an empty set with cpc_set_create() and add requests to the set
with cpc_set_add_request(). Once all requests have been added to a
set, the set must be bound to the hardware performance counters (see
cpc_bind_curlwp(), cpc_bind_pctx(), and cpc_bind_cpu(), all described
on cpc_bind_curlwp(3CPC)) before counting events. At bind time, the
system attempts to match each request with an available physical
counter capable of counting the event specified in the request. If
the bind is successful, a 64-bit virtualized counter is created to
store the counts accumulated by the hardware counter. These counts
are stored and managed in CPC buffers separate from the CPC set whose
requests are being counted. See cpc_buf_create(3CPC) and
cpc_set_sample(3CPC).

The cpc_set_add_request() function specifies a configuration of a
hardware counter. The arguments to cpc_set_add_request() are:

event
A string containing the name of an event supported
by the system's processor. The
cpc_walk_events_all() and cpc_walk_events_pic()
functions (both described on cpc_npic(3CPC)) can be
used to query the processor for the names of
available events. Certain processors allow the use
of raw event codes, in which case a string
representation of an event code in a form acceptable
to strtol(3C) can be used as the event argument.

preset
The value with which the system initializes the
counter.

flags
Three flags are defined that modify the behavior of
the counter acting on behalf of this request:

CPC_COUNT_USER

The counter should count events that occur while
the processor is in user mode.

CPC_COUNT_SYSTEM

The counter should count events that occur while
the processor is in privileged mode.

CPC_OVF_NOTIFY_EMT

Request a signal to be sent to the application
when the physical counter overflows. A SIGEMT
signal is delivered if the processor is capable
of delivering an interrupt when the counter
counts past its maximum value. All requests in
the set containing the counter that overflowed
are stopped until the set is rebound.

At least one of CPC_COUNT_USER or CPC_COUNT_SYSTEM
must be specified to program the hardware for
counting.

nattrs, attrs
The nattrs argument specifies the number of
attributes pointed to by the attrs argument, which
is an array of cpc_attr_t structures containing
processor-specific attributes that modify the
request's configuration. The cpc_walk_attrs()
function (see cpc_npic(3CPC)) can be used to query
the processor for the list of attributes it accepts.
The library makes a private copy of the attrs array,
allowing the application to dispose of it
immediately after calling cpc_set_add_request().

The cpc_walk_requests() function calls the action function on each
request that has been added to the set. The arg argument is passed
unmodified to the action function with each call.

RETURN VALUES

Upon successful completion, cpc_set_create() returns a handle to the
opaque cpc_set_t data structure. Otherwise, NULL is returned and
errno is set to indicate the error.

Upon successful completion, Cpc_set_destroy() returns 0. Otherwise,
-1 is returned and errno is set to indicate the error.

Upon successful completion, cpc_set_add_request() returns an integer
index used to refer to the data generated by that request during data
retrieval. Otherwise, -1 is returned and errno is set to indicate the
error.

ERRORS

These functions will fail if:

EINVAL
An event, attribute, or flag passed to
cpc_set_add_request() was invalid.

For cpc_set_destroy() and cpc_set_add_request(), the set
parameter was not created with the given cpc_t.

ENOMEM
There was not enough memory available to the process to
create the library's data structures.

ATTRIBUTES

NOTES

The system automatically determines which particular physical counter
to use to count the events specified by each request. Applications
can force the system to use a particular counter by specifying the
counter number in an attribute named picnum that is passed to
cpc_set_add_request(). Counters are numbered from 0 to n - 1, where n
is the number of counters in the processor as returned by
cpc_npic(3CPC).

Some processors, such as UltraSPARC, do not allow the hardware
counters to be programmed differently. In this case, all requests in
the set must have the same configuration, or an attempt to bind the
set will return EINVAL. If a cpc_errhndlr_t has been registered with
cpc_seterrhndlr(3CPC), the error handler is called with subcode
CPC_CONFLICTING_REQS. For example, on UltraSPARC pic0 and pic1 must
both program events in the same processor mode (user mode, kernel
mode, or both). For example, pic0 cannot be programmed with
CPC_COUNT_USER while pic1 is programmed with CPC_COUNT_SYSTEM. Refer
to the hardware documentation referenced by cpc_cpuref(3CPC) for
details about a particular processor's performance instrumentation
hardware.

August 20, 2007 CPC_SET_CREATE(3CPC)