CPU Performance Counters Library Functions cpc_set_create(3CPC)
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
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 theprocessor. The cpc_set_t data structure is opaque and must
not be accessed directly by the application. Applications wanting to program one or more performancecounters 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 tothe 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 inthe 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 beingcounted. 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 toSunOS 5.11 Last change: 20 Aug 2007 1
CPU Performance Counters Library Functions cpc_set_create(3CPC)
cpc_set_add_request() are:
event A string containing the name of an event supported by the system's processor. Thecpc_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 avail-
able 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 deliveredif the processor is capable of deliver-
ing 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 pro-
gram the hardware for counting.SunOS 5.11 Last change: 20 Aug 2007 2
CPU Performance Counters Library Functions cpc_set_create(3CPC)
nattrs, attrs The nattrs argument specifies the number ofattributes pointed to by the attrs argu-
ment, which is an array of cpc_attr_t
structures containing processor-specific
attributes that modify the request's confi-
guration. 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 copyof the attrs array, allowing the applica-
tion to dispose of it immediately aftercalling 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 han-
dle 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 thatrequest 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 tocpc_set_add_request() was invalid.
For cpc_set_destroy() and cpc_set_add_request(),
the set parameter was not created with the givencpc_t.
ENOMEM There was not enough memory available to the pro-
cess to create the library's data structures.SunOS 5.11 Last change: 20 Aug 2007 3
CPU Performance Counters Library Functions cpc_set_create(3CPC)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC), cpc_npic(3CPC),
cpc_seterrhndlr(3CPC), libcpc(3LIB), strtol(3C), attri-
butes(5) NOTESThe system automatically determines which particular physi-
cal counter to use to count the events specified by eachrequest. Applications can force the system to use a particu-
lar counter by specifying the counter number in an attributenamed 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 thiscase, all requests in the set must have the same configura-
tion, or an attempt to bind the set will return EINVAL. If acpc_errhndlr_t has been registered with
cpc_seterrhndlr(3CPC), the error handler is called with sub-
code 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 cannotbe 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 particu-
lar processor's performance instrumentation hardware.SunOS 5.11 Last change: 20 Aug 2007 4