share/man/man3cpc/cpc_shared_open.3cpc

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.
   3 .\" All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH CPC_SHARED_OPEN 3CPC "Mar 28, 2005"
   8 .SH NAME
   9 cpc_shared_open, cpc_shared_bind_event, cpc_shared_take_sample,
  10 cpc_shared_rele, cpc_shared_close \- use CPU performance counters on processors
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ]
  15 #include <libcpc.h>
  16
  17 \fBint\fR \fBcpc_shared_open\fR(\fBvoid\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBcpc_shared_bind_event\fR(\fBint\fR \fIfd\fR, \fBcpc_event_t *\fR\fIevent\fR, \fBint\fR \fIflags\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBcpc_shared_take_sample\fR(\fBint\fR \fIfd\fR, \fBcpc_event_t *\fR\fIevent\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBint\fR \fBcpc_shared_rele\fR(\fBint\fR \fIfd\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBvoid\fR \fBcpc_shared_close\fR(\fBint\fR \fIfd\fR);
  38 .fi
  39
  40 .SH DESCRIPTION
  41 .sp
  42 .LP
  43 The \fBcpc_shared_open()\fR function allows the caller to access the hardware
  44 counters in such a way that the performance of the currently bound CPU can be
  45 measured. The function returns a file descriptor if successful. Only one such
  46 open can be active at a time on any CPU.
  47 .sp
  48 .LP
  49 The \fBcpc_shared_bind_event()\fR, \fBcpc_shared_take_sample()\fR, and
  50 \fBcpc_shared_rele()\fR functions are directly analogous to the corresponding
  51 \fBcpc_bind_event()\fR, \fBcpc_take_sample()\fR, and \fBcpc_rele()\fR functions
  52 described on the \fBcpc_bind_event\fR(3CPC)manual page, except that they
  53 operate on the counters of a particular processor.
  54 .SH USAGE
  55 .sp
  56 .LP
  57 If a thread wishes to access the counters using this interface, it \fBmust\fR
  58 do so using a thread bound to an lwp, (see the \fBTHR_BOUND\fR flag to
  59 \fBthr_create\fR(3C)), that has in turn bound itself to a processor using
  60 \fBprocessor_bind\fR(2).
  61 .sp
  62 .LP
  63 Unlike the \fBcpc_bind_event\fR(3CPC) family of functions, no counter context
  64 is attached to those lwps, so the performance counter samples from the
  65 processors reflects the system-wide usage, instead of per-lwp usage.
  66 .sp
  67 .LP
  68 The first successful invocation of \fBcpc_shared_open()\fR will immediately
  69 \fBinvalidate\fR \fIall\fR existing performance counter context on the system,
  70 and \fBprevent\fR \fIall\fR subsequent attempts to bind counter context to lwps
  71 from succeeding anywhere on the system until the last caller invokes
  72 \fBcpc_shared_close()\fR.
  73 .sp
  74 .LP
  75 This is because it is impossible to simultaneously use the counters to
  76 accurately measure per-lwp and system-wide events, so there is an exclusive
  77 interlock between these uses.
  78 .sp
  79 .LP
  80 Access to the shared counters is mediated by file permissions on a \fBcpc\fR
  81 pseudo device.  Only a user with the {\fBPRIV_SYS_CONFIG\fR} privilege is
  82 allowed to access the shared device. This control prevents use of the counters
  83 on a per-lwp basis to other users.
  84 .sp
  85 .LP
  86 The \fBCPC_BIND_LWP_INHERIT\fR and \fBCPC_BIND_EMT_OVF\fR flags are invalid for
  87 the shared interface.
  88 .SH RETURN VALUES
  89 .sp
  90 .LP
  91 On success, the functions (except for \fBcpc_shared_close()\fR) return 0.  On
  92 failure, the functions return -1 and set \fBerrno\fR to indicate the reason.
  93 .SH ERRORS
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBEACCES\fR\fR
  98 .ad
  99 .RS 11n
 100 The caller does not have appropriate privilege to access the CPU performance
 101 counters system-wide.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEAGAIN\fR\fR
 108 .ad
 109 .RS 11n
 110 For cpc_shared_open(\|), this value implies that the counters on the bound cpu
 111 are busy because they are already being used to measure system-wide events by
 112 some other caller.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBEAGAIN\fR\fR
 119 .ad
 120 .RS 11n
 121 Otherwise, this return value implies that the counters are not available
 122 because the thread has been unbound from the processor it was bound to at open
 123 time. Robust programs should be coded to expect this behavior, and should
 124 invoke \fBcpc_shared_close\fR(\|), before retrying the operation.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBEINVAL\fR\fR
 131 .ad
 132 .RS 11n
 133 The counters cannot be accessed on the current CPU because the calling thread
 134 is not bound to that CPU using \fBprocessor_bind\fR(2).
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBENOTSUP\fR\fR
 141 .ad
 142 .RS 11n
 143 The caller has attempted an operation that is illegal or not supported on the
 144 current platform.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBENXIO\fR\fR
 151 .ad
 152 .RS 11n
 153 The current machine either has no performance counters, or has been configured
 154 to disallow access to them system-wide.
 155 .RE
 156
 157 .SH ATTRIBUTES
 158 .sp
 159 .LP
 160 See \fBattributes\fR(5) for descriptions of the following attributes:
 161 .sp
 162
 163 .sp
 164 .TS
 165 box;
 166 c | c
 167 l | l .
 168 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 169 _
 170 MT-Level        MT-Safe
 171 _
 172 Interface Stability     Obsolete
 173 .TE
 174
 175 .SH SEE ALSO
 176 .sp
 177 .LP
 178 \fBprocessor_bind\fR(2), \fBcpc\fR(3CPC), \fBcpc_bind_cpu\fR(3CPC),
 179 \fBcpc_bind_event\fR(3CPC), \fBcpc_set_sample\fR(3CPC), \fBcpc_unbind\fR(3CPC),
 180 \fBlibcpc\fR(3LIB), \fBthr_create\fR(3C), \fBattributes\fR(5)
 181 .SH NOTES
 182 .sp
 183 .LP
 184 The \fBcpc_shared_open()\fR, \fBcpc_shared_bind_event()\fR,
 185 \fBcpc_shared_take_sample()\fR, \fBcpc_shared_rele()\fR, and
 186 \fBcpc_shared_close()\fR functions exist for binary compatibility only. Source
 187 containing these functions will not compile. These functions are obsolete and
 188 might be removed in a future release. Applications should use
 189 \fBcpc_bind_cpu\fR(3CPC), \fBcpc_set_sample\fR(3CPC), and
 190 \fBcpc_unbind\fR(3CPC) instead.