'\" te
.\" Copyright (c) 2004, 2000, Oracle and/or its affiliates. All rights reserved.
.TH cpc_buf_create 3CPC "30 Jan 2004" "SunOS 5.11" "CPU Performance Counters Library Functions"
.SH 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, cpc_buf_smpl_rec_count, cpc_buf_smpl_get_item, cpc_buf_smpl_get_record, cpc_get_smpl_max_rec_count \- sample and manipulate CPC and SMPL data
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <libcpc.h>

\fBcpc_buf_t *\fR\fBcpc_buf_create\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_buf_destroy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_set_sample\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_buf_get\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR, \fBint\fR \fIindex\fR, \fBuint64_t *\fR\fIval\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_buf_set\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR, \fBint\fR \fIindex\fR, \fBuint64_t\fR \fIval\fR);
.fi

.LP
.nf
\fBhrtime_t\fR \fBcpc_buf_hrtime\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBuint64_t\fR \fBcpc_buf_tick\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcpc_buf_sub\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIa\fR, \fBcpc_buf_t *\fR\fIb\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcpc_buf_add\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIa\fR, \fBcpc_buf_t *\fR\fIb\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcpc_buf_copy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcpc_buf_zero\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_buf_smpl_rec_count\fR(\fBcpc_t\fR \fB*\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR, 
		\fBint\fR \fIrequest_index\fR, \fBuint_t\fR \fB*\fR\fIrec_count\fR);
.fi

.LP
.nf
\fBint\fR \fBcpc_buf_smpl_get_item\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t\fR \fB*\fR\fIbuf\fR, 
		\fBint\fR \fIrequest_index\fR, \fBint\fR \fIrecord_index\fR, \fBint\fR \fIrecord_item_index\fR, \fBuint64_t *\fR\fIval\fR);
.fi

.LP
.nf
\fBuint64_t\fR \fB*cpc_buf_smpl_get_record\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR, 
		\fBint\fR \fIrequest_index\fR, \fBint\fR \fIrecord_index\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Counter data and sampling results are sampled into CPC buffers, which are represented by the opaque data type \fBcpc_buf_t\fR. A CPC buffer is created with \fBcpc_buf_create()\fR 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.
.sp
.LP
Once a set has been successfully bound, the counter values and the sampling results are retrieved using \fBcpc_set_sample()\fR. For the CPC request, the \fBcpc_set_sample()\fR function takes a snapshot of the hardware performance counters counting on behalf of the CPC requests in \fIset\fR and stores the 64-bit virtualized software representations of the counters in the supplied CPC buffer. For the SMPL request, the \fBcpc_set_sample()\fR function retrieves the sampling results collected by the hardware on behalf of the SMPL requests in \fIset\fR and stores the results in the supplied CPC buffer as a form of SMPL records. If a set was bound with \fBcpc_bind_curlwp\fR(3CPC) or \fBcpc_bind_curlwp\fR(3CPC), the set can only be sampled by the LWP that bound it.
.sp
.LP
The kernel maintains 64-bit virtual software counters to hold the counts accumulated for each CPC 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 capable 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.
.sp
.LP
The \fBcpc_buf_get()\fR function retrieves the last sampled value of a particular CPC request in \fIbuf\fR. The \fIindex\fR argument specifies which CPC request value in the set to retrieve. The index for each request is returned during set configuration by \fBcpc_set_add_request\fR(3CPC). The 64-bit virtualized software counter value is stored in the location pointed to by the \fIval\fR argument. If \fIindex \fR does not specify the CPC request but the SMPL request in \fIbuf\fR, \fBcpc_buf_get()\fR function sets \fBerrno\fR to indicate error and returns -1. To retrieve the results for SMPL requests in \fIbuf\fR, \fBcpc_buf_smpl_get_item()\fR and \fBcpc_buf_smpl_get_record()\fR should be used.
.sp
.LP
The \fBcpc_buf_set()\fR function stores a 64-bit value to a specific CPC 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). If \fIindex\fR does not specify the CPC request but the SMPL request in \fIbuf\fR, the \fBcpc_buf_set()\fR function sets \fBerrno\fR to indicate error and returns -1. The operation to store values to a specific SMPL request in the specified buffer is not supported.
.sp
.LP
The \fBcpc_buf_hrtime()\fR function returns a high-resolution timestamp indicating exactly when the set was last sampled by the kernel.
.sp
.LP
The\fB cpc_buf_tick()\fR function returns a 64-bit virtualized cycle counter indicating how long the set has been programmed into the counter since it was bound. The units of the values returned by \fBcpc_buf_tick()\fR are CPU clock cycles.
.sp
.LP
The \fBcpc_buf_sub()\fR function calculates the difference between each CPC request in sets \fIa\fR and \fIb\fR, storing the result in the corresponding request within set \fIds\fR. More specifically, for each CPC request index \fIn\fR, this function performs \fIds\fR[\fIn\fR] = \fIa\fR[\fIn\fR] - \fIb\fR[n]. Similarly, \fBcpc_buf_add()\fR adds each CPC request in sets \fIa\fR and \fIb\fR and stores the result in the corresponding request within set \fIds\fR. If the specified buffer \fIa\fR and \fIb\fR also contain the results of the SMPL requests, \fBcpc_buf_sub()\fR and \fBcpc_buf_add()\fR skip the results of the SMPL requests and handle only the results of the CPC requests.
.sp
.LP
The \fBcpc_buf_copy()\fR function copies each value from buffer \fIsrc\fR into buffer \fIds\fR. Both buffers must have been created from the same \fBcpc_set_t\fR.
.sp
.LP
The \fBcpc_buf_zero()\fR function sets each request's value in the buffer to zero.
.sp
.LP
The \fBcpc_buf_destroy()\fR function frees all resources associated with the CPC buffer.
.sp
.LP
The \fBcpc_buf_smpl_rec_count()\fR function returns the number of available SMPL records that are found in \fIbuf\fR, for the SMPL request specified by \fIrequest_index\fR, into the \fIuint_t\fR object pointed to by \fIrec_count\fR.
.sp
.LP
The \fBcpc_buf_smpl_get_item()\fR function retrieves one record item specified by \fIrecord_item_index\fR in the SMPL record specified by \fIrecord_index\fR for the SMPL request specified by \fIrequest_index\fR, into the \fBuint64_t\fR object pointed to by \fIval\fR. \fIrecord_item_index\fR is the index to an item found in the SMPL record, which should be obtained by using \fBcpc_walk_smpl_recitems()\fR and \fBcpc_walk_smpl_recitems_req()\fR. Also, the following special macros can be used to specify generic record items for \fIrecord_item_index\fR:
.sp
.ne 2
.mk
.na
\fB\fBSMPL_REC_ITEM_PC\fR\fR
.ad
.RS 23n
.rt  
Index to the program counter associated with he monitoring event; for example, this will be internally mapped to the index to the RIP item on Intel PEBS.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSMPL_REC_ITEM_DLINA\fR\fR
.ad
.RS 23n
.rt  
Index to the data linear address associated with the monitoring event; for example, this will be internally mapped to the index to the data linear address item on Intel PEBS.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSMPL_REC_ITEM_LAT\fR\fR
.ad
.RS 23n
.rt  
Index to the latency value associated with the monitoring event; for example, this will be internally mapped to the index to the latency value item on Intel PEBS.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSMPL_REC_ITEM_DSRC\fR\fR
.ad
.RS 23n
.rt  
Index to the data source description associated with the monitoring event; for example, this will be internally mapped to the index to the data source encoding item on Intel PEBS.
.RE

.sp
.LP
Calling \fBcpc_buf_smpl_get_item()\fR will not invalidate the sampling results in \fIbuf\fR.
.sp
.LP
The \fBcpc_buf_smpl_get_record()\fR function returns on SMPL record specified by \fIrecord_index\fR for the SMPL request specified by  \fIrequest_index\fR, as the pointer to an array of \fBuint64_t\fR objects. Each record item in the SMPL record should be accessed using the index to the desired SMPL record item, obtained by using \fBcpc_walk_smpl_recitems()\fR and \fBcpc_walk_smpl_recitems_req()\fR. The application must not alter the array of \fBuint64_t\fR objects returned by \fBcpc_buf_smpl_get_record()\fR. Calling \fBcpc_buf_smpl_get_record()\fR will not invalidate the sampling results in \fIbuf\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBcpc_buf_create()\fR returns a pointer to a CPC buffer which can be used to hold data for the set argument. Otherwise, this function returns \fINULL\fR and sets \fBerrno\fR to indicate the error.
.sp
.LP
Upon successful completion, \fBcpc_set_sample()\fR, \fBcpc_buf_get()\fR, and \fBcpc_buf_set()\fR return 0. Otherwise, they return -1 and set \fBerrno\fR to indicate the error.
.sp
.LP
\fBcpc_buf_smpl_get_item()\fR function sets \fBerrno\fR to EINVAL and returns -1 if the system does not support the SMPL record item corresponding to the special macro. If \fIcpc\fR was not successfully opened for SMPL, or if the request specified by \fIrequest_index\fR is not for  SMPL, or if \fIrecord_index\fR does not point to a record entry available in \fIbuf\fR, or if \fIrecord_item_index\fR does not point to an available record item, the \fBcpc_buf_smpl_get_item()\fR function sets \fBerrno\fR to \fBEINVAL\fR and returns -1.
.sp
.LP
\fBcpc_buf_smpl_get_record()\fR function sets \fBerrno\fR to \fBEINVAL\fR and returns -1 if \fIcpc\fR was not successfully opened for SMPL, or if the request specified by \fIrequest_index\fR is not for SMPL, or if  \fIrecord_index\fR does not point to a record entry available in \fIbuf\fR.
.SH ERRORS
.sp
.LP
These functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
For \fBcpc_set_sample()\fR, the set is not bound, the set and/or CPC buffer were not created with the given \fIcpc\fR handle, or the CPC buffer was not created with the supplied set.
.sp
For \fBcpc_buf_get()\fR and \fBcpc_buf_set()\fR functions, the request specified by \fIindex\fR is not for CPC but for SMPL.
.sp
For \fBcpc_buf_smpl_rec_count()\fR functions, the request specified by \fIrequest_index\fR is not for SMPL.
.sp
For \fBcpc_buf_smpl_get_item()\fR, the system does not support the SMPL record item corresponding to the specified special macro, \fIcpc\fR was not  successfully opened  for SMPL, the request specified by \fIrequest_index\fR is not for SMPL, \fIrecord_index\fR does not point to a record entry available in \fIbuf\fR, or \fIrecord_item_index\fR does not point to an available record item.
.sp
For \fBcpc_buf_smpl_get_record()\fR, \fIcpc\fR was not successfully opened for SMPL, the request specified by \fIrequest_index\fR is not for SMPL, or \fIrecord_index\fR does not point to a record entry available in \fIbuf\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
.rt  
When using \fBcpc_set_sample()\fR to sample a CPU-bound set, the LWP has been unbound from the processor it is measuring.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
.rt  
The library could not allocate enough memory for its internal data structures.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBcpc_bind_curlwp\fR(3CPC), \fBcpc_set_add_request\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
Often the overhead of performing a system call can be too disruptive to the events being measured. Once a \fBcpc_bind_curlwp\fR(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.
.sp
.LP
Not all processors support this type of access. On processors where direct access is not possible, \fBcpc_set_sample()\fR must be used to read the counters.
.sp
.ne 2
.mk
.na
\fBSPARC\fR
.ad
.RS 9n
.rt  
.sp
.in +2
.nf
rd %pic, %rN        ! All UltraSPARC
wr %rN, %pic        ! (All UltraSPARC, but see text)
.fi
.in -2

.RE

.sp
.ne 2
.mk
.na
\fBx86\fR
.ad
.RS 9n
.rt  
.sp
.in +2
.nf
rdpmc               ! Pentium II, III, and 4 only
.fi
.in -2

.RE

.sp
.LP
If the counter context is not active or has been invalidated, the \fB%pic\fR register (SPARC), and the \fBrdpmc\fR instruction (Pentium) becomes unavailable.
.sp
.LP
Pentium II and III processors support the non-privileged rdpmc instruction that requires that the counter of interest be specified in \fB%ecx\fR and return a 40-bit value in the \fB%edx\fR:\fB%eax\fR register pair. There is no non-privileged access mechanism for Pentium I processors.