Print this page
XXX Remove nawk(1)
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1m/cpustat.1m
+++ new/usr/src/man/man1m/cpustat.1m
1 1 '\" te
2 2 .\" Copyright (c) 2005, Sun Microsystems, Inc.
3 3 .TH CPUSTAT 1M "Jun 16, 2009"
4 4 .SH NAME
5 5 cpustat \- monitor system behavior using CPU performance counters
6 6 .SH SYNOPSIS
7 7 .LP
8 8 .nf
9 9 \fBcpustat\fR \fB-c\fR \fIeventspec\fR [\fB-c\fR \fIeventspec\fR]... [\fB-p\fR \fIperiod\fR] [\fB-T\fR u | d ]
10 10 [\fB-sntD\fR] [\fIinterval\fR [\fIcount\fR]]
11 11 .fi
12 12
13 13 .LP
14 14 .nf
15 15 \fBcpustat\fR \fB-h\fR
16 16 .fi
17 17
18 18 .SH DESCRIPTION
19 19 .sp
20 20 .LP
21 21 The \fBcpustat\fR utility allows \fBCPU\fR performance counters to be used to
22 22 monitor the overall behavior of the \fBCPU\fRs in the system.
23 23 .sp
24 24 .LP
25 25 If \fIinterval\fR is specified, \fBcpustat\fR samples activity every
26 26 \fIinterval\fR seconds, repeating forever. If a \fIcount\fR is specified, the
27 27 statistics are repeated \fIcount\fR times. If neither are specified, an
28 28 interval of five seconds is used, and there is no limit to the number of
29 29 samples that are taken.
30 30 .SH OPTIONS
31 31 .sp
32 32 .LP
33 33 The following options are supported:
34 34 .sp
35 35 .ne 2
36 36 .na
37 37 \fB\fB-c\fR \fIeventspec\fR\fR
38 38 .ad
39 39 .sp .6
40 40 .RS 4n
41 41 Specifies a set of events for the \fBCPU\fR performance counters to monitor.
42 42 The syntax of these event specifications is:
43 43 .sp
44 44 .in +2
45 45 .nf
46 46 [picn=]\fIeventn\fR[,attr[\fIn\fR][=\fIval\fR]][,[picn=]\fIeventn\fR
47 47 [,attr[n][=\fIval\fR]],...,]
48 48 .fi
49 49 .in -2
50 50 .sp
51 51
52 52 You can use the \fB-h\fR option to obtain a list of available events and
53 53 attributes. This causes generation of the usage message. You can omit an
54 54 explicit counter assignment, in which case \fBcpustat\fR attempts to choose a
55 55 capable counter automatically.
56 56 .sp
57 57 Attribute values can be expressed in hexadecimal, octal, or decimal notation,
58 58 in a format suitable for \fBstrtoll\fR(3C). An attribute present in the event
59 59 specification without an explicit value receives a default value of \fB1\fR. An
60 60 attribute without a corresponding counter number is applied to all counters in
61 61 the specification.
62 62 .sp
63 63 The semantics of these event specifications can be determined by reading the
64 64 \fBCPU\fR manufacturer's documentation for the events.
65 65 .sp
66 66 Multiple \fB-c\fR options can be specified, in which case the command cycles
67 67 between the different event settings on each sample.
68 68 .RE
69 69
70 70 .sp
71 71 .ne 2
72 72 .na
73 73 \fB\fB-D\fR\fR
74 74 .ad
75 75 .sp .6
76 76 .RS 4n
77 77 Enables debug mode.
78 78 .RE
79 79
80 80 .sp
81 81 .ne 2
82 82 .na
83 83 \fB\fB-h\fR\fR
84 84 .ad
85 85 .sp .6
86 86 .RS 4n
87 87 Prints an extensive help message on how to use the utility and how to program
88 88 the processor-dependent counters.
89 89 .RE
90 90
91 91 .sp
92 92 .ne 2
93 93 .na
94 94 \fB\fB-n\fR\fR
95 95 .ad
96 96 .sp .6
97 97 .RS 4n
98 98 Omits all header output (useful if \fBcpustat\fR is the beginning of a
99 99 pipeline).
100 100 .RE
101 101
102 102 .sp
103 103 .ne 2
104 104 .na
105 105 \fB\fB-p\fR \fIperiod\fR\fR
106 106 .ad
107 107 .sp .6
108 108 .RS 4n
109 109 Causes \fBcpustat\fR to cycle through the list of \fIeventspec\fRs every
110 110 \fIperiod\fR seconds. The tool sleeps after each cycle until \fIperiod\fR
111 111 seconds have elapsed since the first \fIeventspec\fR was measured.
112 112 .sp
113 113 When this option is present, the optional \fIcount\fR parameter specifies the
114 114 number of total cycles to make (instead of the number of total samples to
115 115 take). If \fIperiod\fR is less than the number of \fIeventspec\fRs times
116 116 \fIinterval\fR, the tool acts as it period is \fB0\fR.
117 117 .RE
118 118
119 119 .sp
120 120 .ne 2
121 121 .na
122 122 \fB\fB-s\fR\fR
123 123 .ad
124 124 .sp .6
125 125 .RS 4n
126 126 Creates an idle soaker thread to spin while system-only \fIeventspec\fRs are
127 127 bound. One idle soaker thread is bound to each CPU in the current processor
128 128 set. System-only \fIeventspec\fRs contain both the \fBnouser\fR and the
129 129 \fBsys\fR tokens and measure events that occur while the CPU is operating in
130 130 privileged mode. This option prevents the kernel's idle loop from running and
131 131 triggering system-mode events.
132 132 .RE
133 133
134 134 .sp
135 135 .ne 2
136 136 .na
137 137 \fB\fB-T\fR \fBu\fR | \fBd\fR\fR
138 138 .ad
139 139 .sp .6
140 140 .RS 4n
141 141 Display a time stamp.
142 142 .sp
143 143 Specify \fBu\fR for a printed representation of the internal representation of
144 144 time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
145 145 \fBdate\fR(1).
146 146 .RE
147 147
148 148 .sp
149 149 .ne 2
150 150 .na
151 151 \fB\fB-t\fR\fR
152 152 .ad
153 153 .sp .6
154 154 .RS 4n
155 155 Prints an additional column of processor cycle counts, if available on the
156 156 current architecture.
157 157 .RE
158 158
159 159 .SH USAGE
160 160 .sp
161 161 .LP
162 162 A closely related utility, \fBcputrack\fR(1), can be used to monitor the
163 163 behavior of individual applications with little or no interference from other
164 164 activities on the system.
165 165 .sp
166 166 .LP
167 167 The \fBcpustat\fR utility must be run by the super-user, as there is an
168 168 intrinsic conflict between the use of the \fBCPU\fR performance counters
169 169 system-wide by \fBcpustat\fR and the use of the \fBCPU\fR performance counters
170 170 to monitor an individual process (for example, by \fBcputrack\fR.)
171 171 .sp
172 172 .LP
173 173 Once any instance of this utility has started, no further per-process or
174 174 per-\fBLWP\fR use of the counters is allowed until the last instance of the
175 175 utility terminates.
176 176 .sp
177 177 .LP
178 178 The times printed by the command correspond to the wallclock time when the
179 179 hardware counters were actually sampled, instead of when the program told the
180 180 kernel to sample them. The time is derived from the same timebase as
181 181 \fBgethrtime\fR(3C).
182 182 .sp
183 183 .LP
184 184 The processor cycle counts enabled by the \fB-t\fR option always apply to both
185 185 user and system modes, regardless of the settings applied to the performance
186 186 counter registers.
187 187 .sp
|
↓ open down ↓ |
187 lines elided |
↑ open up ↑ |
188 188 .LP
189 189 On some hardware platforms running in system mode using the "sys" token, the
190 190 counters are implemented using 32-bit registers. While the kernel attempts to
191 191 catch all overflows to synthesize 64-bit counters, because of hardware
192 192 implementation restrictions, overflows can be lost unless the sampling interval
193 193 is kept short enough. The events most prone to wrap are those that count
194 194 processor clock cycles. If such an event is of interest, sampling should occur
195 195 frequently so that less than 4 billion clock cycles can occur between samples.
196 196 .sp
197 197 .LP
198 -The output of cpustat is designed to be readily parseable by \fBnawk\fR(1) and
198 +The output of cpustat is designed to be readily parseable by \fBawk\fR(1) and
199 199 \fBperl\fR(1), thereby allowing performance tools to be composed by embedding
200 200 \fBcpustat\fR in scripts. Alternatively, tools can be constructed directly
201 201 using the same \fBAPI\fRs that \fBcpustat\fR is built upon using the facilities
202 202 of \fBlibcpc\fR(3LIB). See \fBcpc\fR(3CPC).
203 203 .sp
204 204 .LP
205 205 The \fBcpustat\fR utility only monitors the \fBCPU\fRs that are accessible to
206 206 it in the current processor set. Thus, several instances of the utility can be
207 207 running on the \fBCPU\fRs in different processor sets. See \fBpsrset\fR(1M) for
208 208 more information about processor sets.
209 209 .sp
210 210 .LP
211 211 Because \fBcpustat\fR uses \fBLWP\fRs bound to \fBCPU\fRs, the utility might
212 212 have to be terminated before the configuration of the relevant processor can be
213 213 changed.
214 214 .SH EXAMPLES
215 215 .SS "SPARC"
216 216 .LP
217 217 \fBExample 1 \fRMeasuring External Cache References and Misses
218 218 .sp
219 219 .LP
220 220 The following example measures misses and references in the external cache.
221 221 These occur while the processor is operating in user mode on an UltraSPARC
222 222 machine.
223 223
224 224 .sp
225 225 .in +2
226 226 .nf
227 227 example% cpustat -c EC_ref,EC_misses 1 3
228 228
229 229 time cpu event pic0 pic1
230 230 1.008 0 tick 69284 1647
231 231 1.008 1 tick 43284 1175
232 232 2.008 0 tick 179576 1834
233 233 2.008 1 tick 202022 12046
234 234 3.008 0 tick 93262 384
235 235 3.008 1 tick 63649 1118
236 236 3.008 2 total 651077 18204
237 237 .fi
238 238 .in -2
239 239 .sp
240 240
241 241 .SS "x86"
242 242 .LP
243 243 \fBExample 2 \fRMeasuring Branch Prediction Success on Pentium 4
244 244 .sp
245 245 .LP
246 246 The following example measures branch mispredictions and total branch
247 247 instructions in user and system mode on a Pentium 4 machine.
248 248
249 249 .sp
250 250 .in +2
251 251 .nf
252 252 example% cpustat -c \e
253 253 pic12=branch_retired,emask12=0x4,pic14=branch_retired,\e
254 254 emask14=0xf,sys 1 3
255 255
256 256 time cpu event pic12 pic14
257 257 1.010 1 tick 458 684
258 258 1.010 0 tick 305 511
259 259 2.010 0 tick 181 269
260 260 2.010 1 tick 469 684
261 261 3.010 0 tick 182 269
262 262 3.010 1 tick 468 684
263 263 3.010 2 total 2063 3101
264 264 .fi
265 265 .in -2
266 266 .sp
267 267
268 268 .LP
269 269 \fBExample 3 \fRCounting Memory Accesses on Opteron
270 270 .sp
271 271 .LP
272 272 The following example determines the number of memory accesses made through
273 273 each memory controller on an Opteron, broken down by internal memory latency:
274 274
275 275 .sp
276 276 .in +2
277 277 .nf
278 278 cpustat -c \e
279 279 pic0=NB_mem_ctrlr_page_access,umask0=0x01, \e
280 280 pic1=NB_mem_ctrlr_page_access,umask1=0x02, \e
281 281 pic2=NB_mem_ctrlr_page_access,umask2=0x04,sys \e
282 282 1
283 283
284 284 time cpu event pic0 pic1 pic2
285 285 1.003 0 tick 41976 53519 7720
286 286 1.003 1 tick 5589 19402 731
287 287 2.003 1 tick 6011 17005 658
288 288 2.003 0 tick 43944 45473 7338
289 289 3.003 1 tick 7105 20177 762
290 290 3.003 0 tick 47045 48025 7119
291 291 4.003 0 tick 43224 46296 6694
292 292 4.003 1 tick 5366 19114 652
293 293 .fi
294 294 .in -2
295 295 .sp
296 296
297 297 .SH WARNINGS
298 298 .sp
299 299 .LP
300 300 By running the \fBcpustat\fR command, the super-user forcibly invalidates all
301 301 existing performance counter context. This can in turn cause all invocations of
302 302 the \fBcputrack\fR command, and other users of performance counter context, to
303 303 exit prematurely with unspecified errors.
304 304 .sp
305 305 .LP
306 306 If \fBcpustat\fR is invoked on a system that has \fBCPU\fR performance counters
307 307 which are not supported by Solaris, the following message appears:
308 308 .sp
309 309 .in +2
310 310 .nf
311 311 cpustat: cannot access performance counters - Operation not applicable
312 312 .fi
313 313 .in -2
314 314 .sp
315 315
316 316 .sp
317 317 .LP
318 318 This error message implies that \fBcpc_open()\fR has failed and is documented
319 319 in \fBcpc_open\fR(3CPC). Review this documentation for more information about
320 320 the problem and possible solutions.
321 321 .sp
322 322 .LP
323 323 If a short interval is requested, \fBcpustat\fR might not be able to keep up
324 324 with the desired sample rate. In this case, some samples might be dropped.
325 325 .SH ATTRIBUTES
326 326 .sp
327 327 .LP
328 328 See \fBattributes\fR(5) for descriptions of the following attributes:
329 329 .sp
330 330
331 331 .sp
332 332 .TS
333 333 box;
|
↓ open down ↓ |
125 lines elided |
↑ open up ↑ |
334 334 c | c
335 335 l | l .
336 336 ATTRIBUTE TYPE ATTRIBUTE VALUE
337 337 _
338 338 Interface Stability Evolving
339 339 .TE
340 340
341 341 .SH SEE ALSO
342 342 .sp
343 343 .LP
344 -\fBcputrack\fR(1), \fBnawk\fR(1), \fBperl\fR(1), \fBiostat\fR(1M),
344 +\fBcputrack\fR(1), \fBawk\fR(1), \fBperl\fR(1), \fBiostat\fR(1M),
345 345 \fBprstat\fR(1M), \fBpsrset\fR(1M), \fBvmstat\fR(1M), \fBcpc\fR(3CPC),
346 346 \fBcpc_open\fR(3CPC), \fBcpc_bind_cpu\fR(3CPC), \fBgethrtime\fR(3C),
347 347 \fBstrtoll\fR(3C), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
348 348 .SH NOTES
349 349 .sp
350 350 .LP
351 351 When \fBcpustat\fR is run on a Pentium 4 with HyperThreading enabled, a CPC set
352 352 is bound to only one logical CPU of each physical CPU. See
353 353 \fBcpc_bind_cpu\fR(3CPC).
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX