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

   1 '\" te
   2 .\" Copyright (c) 2007, 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_SET_CREATE 3CPC "Aug 20, 2007"
   7 .SH NAME
   8 cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests \-
   9 manage sets of counter requests
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <libcpc.h>
  15
  16 \fBcpc_set_t *\fR\fBcpc_set_create\fR(\fBcpc_t *\fR\fIcpc\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBcpc_set_destroy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBcpc_set_add_request\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR,
  27      \fBconst char *\fR\fIevent\fR, \fBuint64_t\fR \fIpreset\fR, \fBuint_t\fR \fIflags\fR,
  28      \fBuint_t\fR \fInattrs\fR, \fBconst cpc_attr_t *\fR\fIattrs\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBcpc_walk_requests\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, \fBvoid *\fR\fIarg\fR,
  34      \fBvoid (*\fR\fIaction\fR)(void *\fIarg\fR, int \fIindex\fR, const char *\fIevent\fR,
  35      uint64_t \fIpreset\fR, uint_t \fIflags\fR, int \fInattrs\fR,
  36      const cpc_attr_t *\fIattrs\fR));
  37 .fi
  38
  39 .SH DESCRIPTION
  40 .sp
  41 .LP
  42 The \fBcpc_set_create()\fR function returns an initialized and empty CPC set. A
  43 CPC set contains some number of requests, where a request represents a specific
  44 configuration of a hardware performance instrumentation counter present on the
  45 processor. The \fBcpc_set_t\fR data structure is opaque and must not be
  46 accessed directly by the application.
  47 .sp
  48 .LP
  49 Applications wanting to program one or more performance counters must create an
  50 empty set with \fBcpc_set_create()\fR and add requests to the set with
  51 \fBcpc_set_add_request()\fR. Once all requests have been added to a set, the
  52 set must be bound to the hardware performance counters (see
  53 \fBcpc_bind_curlwp()\fR, \fBcpc_bind_pctx()\fR, and \fBcpc_bind_cpu()\fR, all
  54 described on \fBcpc_bind_curlwp\fR(3CPC)) before counting events. At bind time,
  55 the system attempts to match each request with an available physical counter
  56 capable of counting the event specified in the request. If the bind is
  57 successful, a 64-bit virtualized counter is created to store the counts
  58 accumulated by the hardware counter. These counts are stored and managed in CPC
  59 buffers separate from the CPC set whose requests are being counted. See
  60 \fBcpc_buf_create\fR(3CPC) and \fBcpc_set_sample\fR(3CPC).
  61 .sp
  62 .LP
  63 The \fBcpc_set_add_request()\fR function specifies a configuration of a
  64 hardware counter.  The arguments to \fBcpc_set_add_request()\fR are:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIevent\fR\fR
  69 .ad
  70 .RS 17n
  71 A string containing the name of an event supported by the system's processor.
  72 The \fBcpc_walk_events_all()\fR and \fBcpc_walk_events_pic()\fR functions (both
  73 described on \fBcpc_npic\fR(3CPC)) can be used to query the processor for the
  74 names of available events. Certain processors allow the use of raw event codes,
  75 in which case a string representation of an event code in a form acceptable to
  76 \fBstrtol\fR(3C) can be used as the \fIevent\fR argument.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIpreset\fR\fR
  83 .ad
  84 .RS 17n
  85 The value with which the system initializes the counter.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIflags\fR\fR
  92 .ad
  93 .RS 17n
  94 Three flags are defined that modify the behavior of the counter acting on
  95 behalf of this request:
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBCPC_COUNT_USER\fR\fR
 100 .ad
 101 .sp .6
 102 .RS 4n
 103 The counter should count events that occur while the processor is in user mode.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBCPC_COUNT_SYSTEM\fR\fR
 110 .ad
 111 .sp .6
 112 .RS 4n
 113 The counter should count events that occur while the processor is in privileged
 114 mode.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBCPC_OVF_NOTIFY_EMT\fR\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Request a signal to be sent to the application when the physical counter
 125 overflows. A \fBSIGEMT\fR signal is delivered if the processor is capable of
 126 delivering an interrupt when the counter counts past its maximum value. All
 127 requests in the set containing the counter that overflowed are stopped until
 128 the set is rebound.
 129 .RE
 130
 131 At least one of \fBCPC_COUNT_USER\fR or \fBCPC_COUNT_SYSTEM\fR must be
 132 specified to program the hardware for counting.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fInattrs\fR, \fIattrs\fR\fR
 139 .ad
 140 .RS 17n
 141 The \fInattrs\fR argument specifies the number of attributes pointed to by the
 142 \fIattrs\fR argument, which is an array of \fBcpc_attr_t\fR structures
 143 containing processor-specific attributes that modify the request's
 144 configuration. The \fBcpc_walk_attrs()\fR function (see \fBcpc_npic\fR(3CPC))
 145 can be used to query the processor for the list of attributes it accepts. The
 146 library makes a private copy of the \fIattrs\fR array, allowing the application
 147 to dispose of it immediately after calling \fBcpc_set_add_request()\fR.
 148 .RE
 149
 150 .sp
 151 .LP
 152 The \fBcpc_walk_requests()\fR function calls the action function on each
 153 request that has been added to the set. The \fIarg\fR argument is passed
 154 unmodified to the \fIaction\fR function with each call.
 155 .SH RETURN VALUES
 156 .sp
 157 .LP
 158 Upon successful completion, \fBcpc_set_create()\fR returns a handle to the
 159 opaque \fBcpc_set_t\fR data structure. Otherwise, NULL is returned and
 160 \fBerrno\fR is set to indicate the error.
 161 .sp
 162 .LP
 163 Upon successful completion, \fBCpc_set_destroy()\fR returns 0. Otherwise, -1 is
 164 returned and \fBerrno\fR is set to indicate the error.
 165 .sp
 166 .LP
 167 Upon successful completion, \fBcpc_set_add_request()\fR returns an integer
 168 index used to refer to the data generated by that request during data
 169 retrieval. Otherwise, -1 is returned and \fBerrno\fR is set to indicate the
 170 error.
 171 .SH ERRORS
 172 .sp
 173 .LP
 174 These functions will fail if:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBEINVAL\fR\fR
 179 .ad
 180 .RS 10n
 181 An event, attribute, or flag passed to \fBcpc_set_add_request()\fR was invalid.
 182 .sp
 183 For \fBcpc_set_destroy()\fR and \fBcpc_set_add_request()\fR, the set parameter
 184 was not created with the given cpc_t.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBENOMEM\fR\fR
 191 .ad
 192 .RS 10n
 193 There was not enough memory available to the process to create the library's
 194 data structures.
 195 .RE
 196
 197 .SH ATTRIBUTES
 198 .sp
 199 .LP
 200 See \fBattributes\fR(5) for descriptions of the following attributes:
 201 .sp
 202
 203 .sp
 204 .TS
 205 box;
 206 c | c
 207 l | l .
 208 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 209 _
 210 Interface Stability     Committed
 211 _
 212 MT-Level        Safe
 213 .TE
 214
 215 .SH SEE ALSO
 216 .sp
 217 .LP
 218 \fBcpc_bind_curlwp\fR(3CPC), \fBcpc_buf_create\fR(3CPC), \fBcpc_npic\fR(3CPC),
 219 \fBcpc_seterrhndlr\fR(3CPC), \fBlibcpc\fR(3LIB), \fBstrtol\fR(3C),
 220 \fBattributes\fR(5)
 221 .SH NOTES
 222 .sp
 223 .LP
 224 The system automatically determines which particular physical counter to use to
 225 count the events specified by each request. Applications can force the system
 226 to use a particular counter by specifying the counter number in an attribute
 227 named \fIpicnum\fR that is passed to \fBcpc_set_add_request()\fR. Counters are
 228 numbered from 0 to \fIn\fR - 1, where n is the number of counters in the
 229 processor as returned by \fBcpc_npic\fR(3CPC).
 230 .sp
 231 .LP
 232 Some processors, such as UltraSPARC, do not allow the hardware counters to be
 233 programmed differently. In this case, all requests in the set must have the
 234 same configuration, or an attempt to bind the set will return \fBEINVAL\fR. If
 235 a \fBcpc_errhndlr_t\fR has been registered with \fBcpc_seterrhndlr\fR(3CPC),
 236 the error handler is called with subcode \fBCPC_CONFLICTING_REQS\fR. For
 237 example, on UltraSPARC \fBpic0\fR and \fBpic1\fR must both program events in
 238 the same processor mode (user mode, kernel mode, or both). For example,
 239 \fBpic0\fR cannot be programmed with \fBCPC_COUNT_USER\fR while \fBpic1\fR is
 240 programmed with \fBCPC_COUNT_SYSTEM\fR. Refer to the hardware documentation
 241 referenced by \fBcpc_cpuref\fR(3CPC) for details about a particular processor's
 242 performance instrumentation hardware.