1cpc_strtoevent(3CPCC)PU Performance Counters Library Functioncspc_strtoevent(3CPC)
2
6 cpc_strtoevent, cpc_eventtostr - translate strings to and from events
7
9 cc [ flag... ] file... −lcpc [ library... ]
10 #include <libcpc.h>
11 int cpc_strtoevent(int cpuver, const char *spec, cpc_event_t *event);
13 char *cpc_eventtostr(cpc_event_t *event);
16
19 The cpc_strtoevent() function translates an event specification to the
20 appropriate collection of control bits in a cpc_event_t structure
21 pointed to by the event argument. The event specification is a getsub‐
22 opt(3C)-style string that describes the event and any attributes that
23 the processor can apply to the event or events. If successful, the
24 funciton returns 0, the ce_cpuver field and the ISA-dependent control
25 registers of event are initialized appropriately, and the rest of the
26 cpc_event_t structure is initialized to 0.
27 The cpc_eventtostr() function takes an event and constructs a compact
30 canonical string representation for that event.
31
33 Upon successful completion, cpc_strtoevent() returns 0. If the string
34 cannot be decoded, a non-zero value is returned and a message is
35 printed using the library's error-reporting mechanism (see cpc_seter‐
36 rfn(3CPC)).
37 Upon successful completion, cpc_eventtostr() returns a pointer to a
40 string. The string returned must be freed by the caller using free(3C).
41 If cpc_eventtostr() fails, a null pointer is returned.
42
44 The event selection syntax used is processor architecture-dependent.
45 The supported processor families allow variations on how events are
46 counted as well as what events can be counted. This information is
47 available in compact form from the cpc_getusage() function (see
48 cpc_getcpuver(3CPC)), but is explained in further detail below.
49 UltraSPARC
51 On UltraSPARC processors, the syntax for setting options is as follows:
52 pic0=<eventspec>,pic1=<eventspec> [,sys] [,nouser]
54 This syntax, which reflects the simplicity of the options available
59 using the %pcr register, forces both counter events to be selected. By
60 default only user events are counted; however, the sys keyword allows
61 system (kernel) events to be counted as well. User event counting can
62 be disabled by specifying the nouser keyword.
63 The keywords pic0 and pic1 may be omitted; they can be used to resolve
66 ambiguities if they exist.
67 Pentium I
69 On Pentium processors, the syntax for setting counter options is as
70 follows:
71 pic0=<eventspec>,pic1=<eventspec> [,sys[[0|1]]] [,nouser[[0|1]]]
73 [,noedge[[0|1]]] [,pc[[0|1]]]
74 The syntax and semantics are the same as UltraSPARC, except that is
79 possible to specify whether a particular counter counts user or system
80 events. If unspecified, the specification is presumed to apply to both
81 counters.
82 There are some additional keywords. The noedge keyword specifies that
85 the counter should count clocks (duration) instead of events. The pc
86 keyword allows the external pin control pins to be set high (defaults
87 to low). When the pin control register is set high, the external pin
88 will be asserted when the associated register overflows. When the pin
89 control register is set low, the external pin will be asserted when the
90 counter has been incremented. The electrical effect of driving the pin
91 is dependent uptoon how the motherboard manufacturer has chosen to con‐
92 nect it, if it is connected at all.
93 Pentium II
95 For Pentium II processors, the syntax is substantially more complex,
96 reflecting the complex configuration options available:
97 pic0=<eventspec>,pic1=<eventspec> [,sys[[0|1]]]
99 [,nouser[[0|1]]] [,noedge[[0|1]]] [,pc[[0|1]]] [,inv[[0|1]]] [,int[[0|1]]]
100 [,cmask[0|1]=<maskspec>] [,umask[0|1]=<maskspec>]
101 This syntax is a straightforward extension of the earlier syntax. The
106 additional inv, int, cmask0, cmask1, umask0, and umask1 keywords allow
107 extended counting semantics. The mask specification is a number between
108 0 and 255, expressed in hexadecimal, octal or decimal notation.
109
111 SPARC
112 Example 1 SPARC Example.
113 cpc_event_t event;
115 char *setting = "pic0=EC_ref,pic1=EC_hit"; /* UltraSPARC-specific */
116 if (cpc_strtoevent(cpuver, setting, &event) != 0)
118 /* can't measure 'setting' on this processor */
119 else
120 setting = cpc_eventtostr(&event);
121
124 See attributes(5) for descriptions of the following attributes:
125 ┌─────────────────────────────┬─────────────────────────────┐
130 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
131 ├─────────────────────────────┼─────────────────────────────┤
132 │Interface Stability │Obsolete │
133 ├─────────────────────────────┼─────────────────────────────┤
134 │MT-Level │MT-Safe │
135 └─────────────────────────────┴─────────────────────────────┘
136
138 cpc(3CPC), cpc_getcpuver(3CPC), cpc_set_add_request(3CPC), cpc_seter‐
139 rfn(3CPC), free(3C), getsubopt(3C), libcpc(3LIB), attributes(5)
140
142 The cpc_strtoevent() and cpc_eventtostr() functions exist for binary
143 compatibility only. Source containing these functions will not compile.
144 These functions are obsolete and might be removed in a future release.
145 Applications should use cpc_set_add_request(3CPC) instead.
146 These functions are provided as a convenience only. As new processors
149 are usually released asynchronously with software, the library allows
150 the pic0 and pic1 keywords to interpret numeric values specified
151 directly in hexadecimal, octal, or decimal.
152SunOS 5.11 28 Mar 2005 cpc_strtoevent(3CPC)