usr/src/man/man3cpc/cpc_buf_create.3cpc

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CPC_BUF_CREATE 3CPC "Jan 30, 2004"
   7 .SH NAME
   8 cpc_buf_create, cpc_buf_destroy, cpc_set_sample, cpc_buf_get, cpc_buf_set,
   9 cpc_buf_hrtime, cpc_buf_tick, cpc_buf_sub, cpc_buf_add, cpc_buf_copy,
  10 cpc_buf_zero \- sample and manipulate CPC data
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <libcpc.h>
  16
  17 \fBcpc_buf_t *\fR\fBcpc_buf_create\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBcpc_buf_destroy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBcpc_set_sample\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \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);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \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);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBhrtime_t\fR \fBcpc_buf_hrtime\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBuint64_t\fR \fBcpc_buf_tick\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \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);
  53 .fi
  54
  55 .LP
  56 .nf
  57 \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);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBvoid\fR \fBcpc_buf_copy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIsrc\fR);
  63 .fi
  64
  65 .LP
  66 .nf
  67 \fBvoid\fR \fBcpc_buf_zero\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR);
  68 .fi
  69
  70 .SH DESCRIPTION
  71 .sp
  72 .LP
  73 Counter data is sampled into CPC buffers, which are represented by the opaque
  74 data type \fBcpc_buf_t\fR. A CPC buffer is created with \fBcpc_buf_create()\fR
  75 to hold the data for a specific CPC set. Once a CPC buffer has been created, it
  76 can only be used to store and manipulate the data of the CPC set for which it
  77 was created.
  78 .sp
  79 .LP
  80 Once a set has been successfully bound, the counter values are sampled using
  81 \fBcpc_set_sample()\fR. The \fBcpc_set_sample()\fR function takes a snapshot of
  82 the hardware performance counters counting on behalf of the requests in
  83 \fIset\fR and stores the 64-bit virtualized software representations of the
  84 counters in the supplied CPC buffer. If a set was bound with
  85 \fBcpc_bind_curlwp\fR(3CPC) or \fBcpc_bind_curlwp\fR(3CPC), the set can only be
  86 sampled by the LWP that bound it.
  87 .sp
  88 .LP
  89 The kernel maintains 64-bit virtual software counters to hold the counts
  90 accumulated for each request in the set, thereby allowing applications to count
  91 past the limits of the underlying physical counter, which can be significantly
  92 smaller than 64 bits. The kernel attempts to maintain the full 64-bit counter
  93 values even in the face of physical counter overflow on architectures and
  94 processors that can automatically detect overflow. If the processor is not
  95 capable of overflow detection, the caller must ensure that the counters are
  96 sampled often enough to avoid the physical counters wrapping. The events most
  97 prone to wrap are those that count processor clock cycles. If such an event is
  98 of interest, sampling should occur frequently so that the counter does not wrap
  99 between samples.
 100 .sp
 101 .LP
 102 The \fBcpc_buf_get()\fR function retrieves the last sampled value of a
 103 particular request in \fIbuf\fR. The \fIindex\fR argument specifies which
 104 request value in the set to retrieve. The index for each request is returned
 105 during set configuration by \fBcpc_set_add_request\fR(3CPC). The 64-bit
 106 virtualized software counter value is stored in the location pointed to by the
 107 \fIval\fR argument.
 108 .sp
 109 .LP
 110 The \fBcpc_buf_set()\fR function stores a 64-bit value to a specific request in
 111 the supplied buffer. This operation can be useful for performing calculations
 112 with CPC buffers, but it does not affect the value of the hardware counter (and
 113 thus will not affect the next sample).
 114 .sp
 115 .LP
 116 The \fBcpc_buf_hrtime()\fR function returns a high-resolution timestamp
 117 indicating exactly when the set was last sampled by the kernel.
 118 .sp
 119 .LP
 120 The\fB cpc_buf_tick()\fR function returns a 64-bit virtualized cycle counter
 121 indicating how long the set has been programmed into the counter since it was
 122 bound. The units of the values returned by \fBcpc_buf_tick()\fR are CPU clock
 123 cycles.
 124 .sp
 125 .LP
 126 The \fBcpc_buf_sub()\fR function calculates the difference between each request
 127 in sets \fIa\fR and \fIb\fR, storing the result in the corresponding request
 128 within set \fIds\fR. More specifically, for each request index \fIn\fR, this
 129 function performs \fIds\fR[\fIn\fR] = \fIa\fR[\fIn\fR] - \fIb\fR[n]. Similarly,
 130 \fBcpc_buf_add()\fR adds each request in sets \fIa\fR and \fIb\fR and stores
 131 the result in the corresponding request within set \fIds\fR.
 132 .sp
 133 .LP
 134 The \fBcpc_buf_copy()\fR function copies each value from buffer \fIsrc\fR into
 135 buffer \fIds\fR. Both buffers must have been created from the same
 136 \fBcpc_set_t\fR.
 137 .sp
 138 .LP
 139 The \fBcpc_buf_zero()\fR function sets each request's value in the buffer to
 140 zero.
 141 .sp
 142 .LP
 143 The \fBcpc_buf_destroy()\fR function frees all resources associated with the
 144 CPC buffer.
 145 .SH RETURN VALUES
 146 .sp
 147 .LP
 148 Upon successful completion, \fBcpc_buf_create()\fR returns a pointer to a CPC
 149 buffer which can be used to hold data for the set argument. Otherwise, this
 150 function returns \fINULL\fR and sets \fBerrno\fR to indicate the error.
 151 .sp
 152 .LP
 153 Upon successful completion, \fBcpc_set_sample()\fR, \fBcpc_buf_get()\fR, and
 154 \fBcpc_buf_set()\fR return 0. Otherwise, they return -1 and set \fBerrno\fR to
 155 indicate the error.
 156 .SH ERRORS
 157 .sp
 158 .LP
 159 These functions will fail if:
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBEINVAL\fR\fR
 164 .ad
 165 .RS 10n
 166 For \fBcpc_set_sample()\fR, the set is not bound, the set and/or CPC buffer
 167 were not created with the given \fIcpc\fR handle, or the CPC buffer was not
 168 created with the supplied set.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBEAGAIN\fR\fR
 175 .ad
 176 .RS 10n
 177 When using \fBcpc_set_sample()\fR to sample a CPU-bound set, the LWP has been
 178 unbound from the processor it is measuring.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBENOMEM\fR\fR
 185 .ad
 186 .RS 10n
 187 The library could not allocate enough memory for its internal data structures.
 188 .RE
 189
 190 .SH ATTRIBUTES
 191 .sp
 192 .LP
 193 See \fBattributes\fR(5) for descriptions of the following attributes:
 194 .sp
 195
 196 .sp
 197 .TS
 198 box;
 199 c | c
 200 l | l .
 201 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 202 _
 203 Interface Stability     Evolving
 204 _
 205 MT-Level        Safe
 206 .TE
 207
 208 .SH SEE ALSO
 209 .sp
 210 .LP
 211 \fBcpc_bind_curlwp\fR(3CPC), \fBcpc_set_add_request\fR(3CPC),
 212 \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
 213 .SH NOTES
 214 .sp
 215 .LP
 216 Often the overhead of performing a system call can be too disruptive to the
 217 events being measured. Once a \fBcpc_bind_curlwp\fR(3CPC) call has been issued,
 218 it is possible to access directly the performance hardware registers from
 219 within the application. If the performance counter context is active, the
 220 counters will count on behalf of the current LWP.
 221 .sp
 222 .LP
 223 Not all processors support this type of access. On processors where direct
 224 access is not possible, \fBcpc_set_sample()\fR must be used to read the
 225 counters.
 226 .sp
 227 .ne 2
 228 .na
 229 \fBSPARC\fR
 230 .ad
 231 .RS 9n
 232 .sp
 233 .in +2
 234 .nf
 235 rd %pic, %rN        ! All UltraSPARC
 236 wr %rN, %pic        ! (All UltraSPARC, but see text)
 237 .fi
 238 .in -2
 239
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fBx86\fR
 246 .ad
 247 .RS 9n
 248 .sp
 249 .in +2
 250 .nf
 251 rdpmc               ! Pentium II, III, and 4 only
 252 .fi
 253 .in -2
 254
 255 .RE
 256
 257 .sp
 258 .LP
 259 If the counter context is not active or has been invalidated, the \fB%pic\fR
 260 register (SPARC), and the \fBrdpmc\fR instruction (Pentium) becomes
 261 unavailable.
 262 .sp
 263 .LP
 264 Pentium II and III processors support the non-privileged rdpmc instruction that
 265 requires that the counter of interest be specified in \fB%ecx\fR and return a
 266 40-bit value in the \fB%edx\fR:\fB%eax\fR register pair. There is no
 267 non-privileged access mechanism for Pentium I processors.