CPU Performance Counters Library Functions cpc_buf_create(3CPC)
NAME
cpc_buf_create, cpc_buf_destroy, cpc_set_sample,
cpc_buf_get, cpc_buf_set, cpc_buf_hrtime, cpc_buf_tick,
cpc_buf_sub, cpc_buf_add, cpc_buf_copy, cpc_buf_zero - sam-
ple and manipulate CPC dataSYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include
cpc_buf_t *cpc_buf_create(cpc_t *cpc, cpc_set_t *set);
int cpc_buf_destroy(cpc_t *cpc, cpc_buf_t *buf);
int cpc_set_sample(cpc_t *cpc, cpc_set_t *set, cpc_buf_t *buf);
int cpc_buf_get(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t *val);
int cpc_buf_set(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t val);
hrtime_t cpc_buf_hrtime(cpc_t *cpc, cpc_buf_t *buf);
uint64_t cpc_buf_tick(cpc_t *cpc, cpc_buf_t *buf);
void cpc_buf_sub(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
void cpc_buf_add(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
void cpc_buf_copy(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *src);
void cpc_buf_zero(cpc_t *cpc, cpc_buf_t *buf);
DESCRIPTION
Counter data is sampled into CPC buffers, which arerepresented by the opaque data type cpc_buf_t. A CPC buffer
is created with cpc_buf_create() to hold the data for a
specific CPC set. Once a CPC buffer has been created, it can only be used to store and manipulate the data of the CPC set for which it was created.SunOS 5.11 Last change: 30 Jan 2004 1
CPU Performance Counters Library Functions cpc_buf_create(3CPC)
Once a set has been successfully bound, the counter valuesare sampled using cpc_set_sample(). The cpc_set_sample()
function takes a snapshot of the hardware performance counters counting on behalf of the requests in set andstores the 64-bit virtualized software representations of
the counters in the supplied CPC buffer. If a set was boundwith cpc_bind_curlwp(3CPC) or cpc_bind_curlwp(3CPC), the set
can only be sampled by the LWP that bound it.The kernel maintains 64-bit virtual software counters to
hold the counts accumulated for each request in the set, thereby allowing applications to count past the limits of the underlying physical counter, which can be significantly smaller than 64 bits. The kernel attempts to maintain thefull 64-bit counter values even in the face of physical
counter overflow on architectures and processors that canautomatically detect overflow. If the processor is not capa-
ble of overflow detection, the caller must ensure that the counters are sampled often enough to avoid the physical counters wrapping. The events most prone to wrap are those that count processor clock cycles. If such an event is of interest, sampling should occur frequently so that the counter does not wrap between samples.The cpc_buf_get() function retrieves the last sampled value
of a particular request in buf. The index argument specifies which request value in the set to retrieve. The index for each request is returned during set configuration bycpc_set_add_request(3CPC). The 64-bit virtualized software
counter value is stored in the location pointed to by the val argument.The cpc_buf_set() function stores a 64-bit value to a
specific request in the supplied buffer. This operation can be useful for performing calculations with CPC buffers, but it does not affect the value of the hardware counter (and thus will not affect the next sample).The cpc_buf_hrtime() function returns a high-resolution
timestamp indicating exactly when the set was last sampled by the kernel.The cpc_buf_tick() function returns a 64-bit virtualized
cycle counter indicating how long the set has been pro-
grammed into the counter since it was bound. The units ofthe values returned by cpc_buf_tick() are CPU clock cycles.
SunOS 5.11 Last change: 30 Jan 2004 2
CPU Performance Counters Library Functions cpc_buf_create(3CPC)
The cpc_buf_sub() function calculates the difference between
each request in sets a and b, storing the result in the corresponding request within set ds. More specifically, foreach request index n, this function performs ds[n] = a[n] -
b[n]. Similarly, cpc_buf_add() adds each request in sets a
and b and stores the result in the corresponding request within set ds.The cpc_buf_copy() function copies each value from buffer
src into buffer ds. Both buffers must have been created fromthe same cpc_set_t.
The cpc_buf_zero() function sets each request's value in the
buffer to zero.The cpc_buf_destroy() function frees all resources associ-
ated with the CPC buffer.RETURN VALUES
Upon successful completion, cpc_buf_create() returns a
pointer to a CPC buffer which can be used to hold data for the set argument. Otherwise, this function returns NULL and sets errno to indicate the error.Upon successful completion, cpc_set_sample(), cpc_buf_get(),
and cpc_buf_set() return 0. Otherwise, they return -1 and
set errno to indicate the error.ERRORS
These functions will fail if:EINVAL For cpc_set_sample(), the set is not bound, the
set and/or CPC buffer were not created with the given cpc handle, or the CPC buffer was not created with the supplied set.EAGAIN When using cpc_set_sample() to sample a CPU-bound
set, the LWP has been unbound from the processor it is measuring. ENOMEM The library could not allocate enough memory for its internal data structures.ATTRIBUTES
SunOS 5.11 Last change: 30 Jan 2004 3
CPU Performance Counters Library Functions cpc_buf_create(3CPC)
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_set_add_request(3CPC),
libcpc(3LIB), attributes(5) NOTES Often the overhead of performing a system call can be too disruptive to the events being measured. Once acpc_bind_curlwp(3CPC) call has been issued, it is possible
to access directly the performance hardware registers from within the application. If the performance counter context is active, the counters will count on behalf of the current LWP.Not all processors support this type of access. On proces-
sors where direct access is not possible, cpc_set_sample()
must be used to read the counters. SPARCrd %pic, %rN ! All UltraSPARC
wr %rN, %pic ! (All UltraSPARC, but see text)
x86 rdpmc ! Pentium II, III, and 4 onlyIf the counter context is not active or has been invali-
dated, the %pic register (SPARC), and the rdpmc instruction
(Pentium) becomes unavailable.Pentium II and III processors support the non-privileged
rdpmc instruction that requires that the counter of interestbe specified in %ecx and return a 40-bit value in the
SunOS 5.11 Last change: 30 Jan 2004 4
CPU Performance Counters Library Functions cpc_buf_create(3CPC)
%edx:%eax register pair. There is no non-privileged access
mechanism for Pentium I processors.SunOS 5.11 Last change: 30 Jan 2004 5