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