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));
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:
At least one of CPC_COUNT_USER or CPC_COUNT_SYSTEM must be specified to program the hardware for counting.
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.
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.
These functions will fail if:
For cpc_set_destroy() and cpc_set_add_request(), the set parameter was not created with the given cpc_t.
See attributes(5) for descriptions of the following attributes:
cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC), cpc_npic(3CPC), cpc_seterrhndlr(3CPC), libcpc(3LIB), strtol(3C), attributes(5)
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.