usr/src/man/man3cpc/cpc_strtoevent.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_STRTOEVENT 3CPC "Mar 28, 2005"
   8 .SH NAME
   9 cpc_strtoevent, cpc_eventtostr \- translate strings to and from events
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ]
  14 #include <libcpc.h>
  15
  16 \fBint\fR \fBcpc_strtoevent\fR(\fBint\fR \fIcpuver\fR, \fBconst char *\fR\fIspec\fR, \fBcpc_event_t *\fR\fIevent\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBchar *\fR\fBcpc_eventtostr\fR(\fBcpc_event_t *\fR\fIevent\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBcpc_strtoevent()\fR function translates an event specification to the
  28 appropriate collection of control bits in a \fBcpc_event_t\fR structure pointed
  29 to by the \fIevent\fR argument. The event specification is a
  30 \fBgetsubopt\fR(3C)-style string that describes the event and any attributes
  31 that the processor can apply to the event or events. If successful, the
  32 funciton returns 0, the \fBce_cpuver\fR field and the ISA-dependent control
  33 registers of event are initialized appropriately, and the rest of the
  34 \fBcpc_event_t\fR structure is initialized to 0.
  35 .sp
  36 .LP
  37 The \fBcpc_eventtostr()\fR function takes an event and constructs a compact
  38 canonical string representation for that event.
  39 .SH RETURN VALUES
  40 .sp
  41 .LP
  42 Upon successful completion, \fBcpc_strtoevent()\fR returns 0. If the string
  43 cannot be decoded, a non-zero value is returned and a message is printed using
  44 the library's error-reporting mechanism (see  \fBcpc_seterrfn\fR(3CPC)).
  45 .sp
  46 .LP
  47 Upon successful completion, \fBcpc_eventtostr()\fR returns a pointer to a
  48 string. The string returned must be freed by the caller using \fBfree\fR(3C).
  49 If \fBcpc_eventtostr()\fR fails, a null pointer is returned.
  50 .SH USAGE
  51 .sp
  52 .LP
  53 The event selection syntax used is processor architecture-dependent. The
  54 supported processor families allow variations on how events are counted as well
  55 as what events can be counted. This information is available in compact form
  56 from the \fBcpc_getusage()\fR function (see \fBcpc_getcpuver\fR(3CPC)), but is
  57 explained in further detail below.
  58 .SS "UltraSPARC"
  59 .sp
  60 .LP
  61 On UltraSPARC processors, the syntax for setting options is as follows:
  62 .sp
  63 .in +2
  64 .nf
  65 \fBpic0\fR=<eventspec>,\fBpic1\fR=<eventspec> [\fB,sys\fR] [\fB,nouser\fR]
  66 .fi
  67 .in -2
  68 .sp
  69
  70 .sp
  71 .LP
  72 This syntax, which reflects the simplicity of the options available using the
  73 \fB%pcr\fR register, forces both counter events to be selected.  By default
  74 only user events are counted; however, the \fBsys\fR keyword allows system
  75 (kernel) events to be counted as well. User event counting can be disabled by
  76 specifying the \fBnouser\fR keyword.
  77 .sp
  78 .LP
  79 The keywords \fBpic0\fR and \fBpic1\fR may be omitted; they can be used to
  80 resolve ambiguities if they exist.
  81 .SS "Pentium I"
  82 .sp
  83 .LP
  84 On Pentium processors, the syntax for setting counter options is as follows:
  85 .sp
  86 .in +2
  87 .nf
  88 \fBpic0\fR=<eventspec>,\fBpic1\fR=<eventspec> [\fB,sys[[0|1]]]\fR [\fB,nouser[[0|1]]]\fR
  89 [\fB,noedge[[0|1]]]\fR [\fB,pc[[0|1]]]\fR
  90 .fi
  91 .in -2
  92 .sp
  93
  94 .sp
  95 .LP
  96 The syntax and semantics are the same as UltraSPARC, except that is possible to
  97 specify whether a particular counter counts user or system events. If
  98 unspecified, the specification is presumed to apply to both counters.
  99 .sp
 100 .LP
 101 There are some additional keywords. The \fBnoedge\fR keyword specifies that the
 102 counter should count clocks (duration) instead of events. The \fBpc\fR keyword
 103 allows the external pin control pins to be set high (defaults to low).  When
 104 the pin control register is set high, the external pin will be asserted when
 105 the associated register overflows. When the pin control register is set low,
 106 the external pin will be asserted when the counter has been incremented.  The
 107 electrical effect of driving the pin is dependent uptoon how the motherboard
 108 manufacturer has chosen to connect it, if it is connected at all.
 109 .SS "Pentium II"
 110 .sp
 111 .LP
 112 For Pentium II processors, the syntax is substantially more complex, reflecting
 113 the complex configuration options available:
 114 .sp
 115 .in +2
 116 .nf
 117 \fBpic0\fR=<eventspec>,\fBpic1\fR=<eventspec> [\fB,sys[[0|1]]]\fR
 118 [\fB,nouser[[0|1]]]\fR [\fB,noedge[[0|1]]]\fR [\fB,pc[[0|1]]]\fR [\fB,inv[[0|1]]]\fR [\fB,int[[0|1]]]\fR
 119 [\fB,cmask[0|1]\fR=<maskspec>] [\fB,umask[0|1]\fR=<maskspec>]
 120 .fi
 121 .in -2
 122 .sp
 123
 124 .sp
 125 .LP
 126 This syntax is a straightforward extension of the earlier syntax. The
 127 additional \fBinv\fR, \fBint\fR, \fBcmask0\fR, \fBcmask1\fR, \fBumask0\fR, and
 128 \fBumask1\fR keywords allow extended counting semantics. The mask specification
 129 is a number between 0 and 255, expressed in hexadecimal, octal or decimal
 130 notation.
 131 .SH EXAMPLES
 132 .SS "SPARC"
 133 .LP
 134 \fBExample 1 \fRSPARC Example.
 135 .sp
 136 .in +2
 137 .nf
 138 cpc_event_t event;
 139 char *setting = "pic0=EC_ref,pic1=EC_hit"; /* UltraSPARC-specific */
 140
 141 if (cpc_strtoevent(cpuver, setting, &event) != 0)
 142         /* can't measure 'setting' on this processor */
 143 else
 144         setting = cpc_eventtostr(&event);
 145 .fi
 146 .in -2
 147
 148 .SH ATTRIBUTES
 149 .sp
 150 .LP
 151 See \fBattributes\fR(5) for descriptions of the following attributes:
 152 .sp
 153
 154 .sp
 155 .TS
 156 box;
 157 c | c
 158 l | l .
 159 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 160 _
 161 Interface Stability     Obsolete
 162 _
 163 MT-Level        MT-Safe
 164 .TE
 165
 166 .SH SEE ALSO
 167 .sp
 168 .LP
 169 \fBcpc\fR(3CPC), \fBcpc_getcpuver\fR(3CPC), \fBcpc_set_add_request\fR(3CPC),
 170 \fBcpc_seterrfn\fR(3CPC), \fBfree\fR(3C), \fBgetsubopt\fR(3C),
 171 \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
 172 .SH NOTES
 173 .sp
 174 .LP
 175 The \fBcpc_strtoevent()\fR and \fBcpc_eventtostr()\fR functions exist for
 176 binary compatibility only. Source containing these functions will not compile.
 177 These functions are obsolete and might be removed in a future release.
 178 Applications should use \fBcpc_set_add_request\fR(3CPC) instead.
 179 .sp
 180 .LP
 181 These functions are provided as a convenience only. As new processors are
 182 usually released asynchronously with software, the library allows the
 183 \fBpic0\fR and \fBpic1\fR keywords to interpret numeric values specified
 184 directly in hexadecimal, octal, or decimal.