CPU Performance Counters Library Functions cpcbufcreate(3CPC)
NAME
cpcbufcreate, cpcbufdestroy, cpcsetsample,
cpcbufget, cpcbufset, cpcbufhrtime, cpcbuftick,
cpcbufsub, cpcbufadd, cpcbufcopy, cpcbufzero - sam-
ple and manipulate CPC data
SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include
cpcbuft *cpcbufcreate(cpct *cpc, cpcsett *set);
int cpcbufdestroy(cpct *cpc, cpcbuft *buf);
int cpcsetsample(cpct *cpc, cpcsett *set, cpcbuft *buf);
int cpcbufget(cpct *cpc, cpcbuft *buf, int index, uint64t *val);
int cpcbufset(cpct *cpc, cpcbuft *buf, int index, uint64t val);
hrtimet cpcbufhrtime(cpct *cpc, cpcbuft *buf);
uint64t cpcbuftick(cpct *cpc, cpcbuft *buf);
void cpcbufsub(cpct *cpc, cpcbuft *ds, cpcbuft *a, cpcbuft *b);
void cpcbufadd(cpct *cpc, cpcbuft *ds, cpcbuft *a, cpcbuft *b);
void cpcbufcopy(cpct *cpc, cpcbuft *ds, cpcbuft *src);
void cpcbufzero(cpct *cpc, cpcbuft *buf);
DESCRIPTION
Counter data is sampled into CPC buffers, which are
represented by the opaque data type cpcbuft. A CPC buffer
is created with cpcbufcreate() 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 cpcbufcreate(3CPC)
Once a set has been successfully bound, the counter values
are sampled using cpcsetsample(). The cpcsetsample()
function takes a snapshot of the hardware performance
counters counting on behalf of the requests in set and
stores the 64-bit virtualized software representations of
the counters in the supplied CPC buffer. If a set was bound
with cpcbindcurlwp(3CPC) or cpcbindcurlwp(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 the
full 64-bit counter values even in the face of physical
counter overflow on architectures and processors that can
automatically 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 cpcbufget() 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 by
cpcsetaddrequest(3CPC). The 64-bit virtualized software
counter value is stored in the location pointed to by the
val argument.
The cpcbufset() 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 cpcbufhrtime() function returns a high-resolution
timestamp indicating exactly when the set was last sampled
by the kernel.
The cpcbuftick() 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 of
the values returned by cpcbuftick() are CPU clock cycles.
SunOS 5.11 Last change: 30 Jan 2004 2
CPU Performance Counters Library Functions cpcbufcreate(3CPC)
The cpcbufsub() function calculates the difference between
each request in sets a and b, storing the result in the
corresponding request within set ds. More specifically, for
each request index n, this function performs ds[n] = a[n] -
b[n]. Similarly, cpcbufadd() adds each request in sets a
and b and stores the result in the corresponding request
within set ds.
The cpcbufcopy() function copies each value from buffer
src into buffer ds. Both buffers must have been created from
the same cpcsett.
The cpcbufzero() function sets each request's value in the
buffer to zero.
The cpcbufdestroy() function frees all resources associ-
ated with the CPC buffer.
RETURN VALUES
Upon successful completion, cpcbufcreate() returns a
pointer to a CPC buffer which can be used to hold data for
the set argument. Otherwise, this function returns NUL and
sets errno to indicate the error.
Upon successful completion, cpcsetsample(), cpcbufget(),
and cpcbufset() return 0. Otherwise, they return -1 and
set errno to indicate the error.
ERORS
These functions will fail if:
EINVAL For cpcsetsample(), 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 cpcsetsample() 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.
ATRIBUTES
SunOS 5.11 Last change: 30 Jan 2004 3
CPU Performance Counters Library Functions cpcbufcreate(3CPC)
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level Safe
SEE ALSO
cpcbindcurlwp(3CPC), cpcsetaddrequest(3CPC),
libcpc(3LIB), attributes(5)
NOTES
Often the overhead of performing a system call can be too
disruptive to the events being measured. Once a
cpcbindcurlwp(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, cpcsetsample()
must be used to read the counters.
SPARC
rd %pic, %rN ! All UltraSPARC
wr %rN, %pic ! (All UltraSPARC, but see text)
x86
rdpmc ! Pentium I, I, and 4 only
If the counter context is not active or has been invali-
dated, the %pic register (SPARC), and the rdpmc instruction
(Pentium) becomes unavailable.
Pentium I and I processors support the non-privileged
rdpmc instruction that requires that the counter of interest
be 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 cpcbufcreate(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
|
