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
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
strtol(3C),
cpc_bind_curlwp(3CPC),
cpc_buf_create(3CPC),
cpc_npic(3CPC),
cpc_seterrhndlr(3CPC),
libcpc(3LIB),
attributes(7)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)