| blob | 90d9e3681339e3dc15c4ad67233664f1268d3d6a |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1999 Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH BUSSTAT 8 "Nov 1, 1999"
7 .SH NAME
8 busstat \- report bus-related performance statistics
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBbusstat\fR \fB-e\fR \fIdevice-inst\fR | \fB-h\fR | \fB-l\fR
13 .fi
15 .LP
16 .nf
17 \fBbusstat\fR [\fB-a\fR] [\fB-n\fR]
18 [\fB-w \fR \fIdevice-inst\fR [,pic0=\fIevent\fR,pic\fIn\fR=\fIevent\fR ]]...
19 [\fB-r\fR \fIdevice-inst\fR]... [\fIinterval \fR [\fIcount\fR]]
20 .fi
22 .SH DESCRIPTION
23 .sp
24 .LP
25 \fBbusstat\fR provides access to the bus-related performance counters in the
26 system. These performance counters allow for the measurement of statistics like
27 hardware clock cycles, bus statistics including \fBDMA\fR and cache coherency
28 transactions on a multiprocessor system. Each bus device that supports these
29 counters can be programmed to count a number of events from a specified list.
30 Each device supports one or more Performance Instrumentation Counters
31 (\fBPIC\fR) that are capable of counting events independently of each other.
32 .sp
33 .LP
34 Separate events can be selected for each \fBPIC\fR on each instance of these
35 devices. \fBbusstat\fR summarizes the counts over the last interval seconds,
36 repeating forever. If a count is given, the statistics are repeated count
37 times.
38 .sp
39 .LP
40 Only root users can program these counters. Non-root users have the option of
41 reading the counters that have been programmed by a root user.
42 .sp
43 .LP
44 The default value for the \fIinterval\fR argument is 1 second, and the default
45 \fIcount\fR is unlimited.
46 .sp
47 .LP
48 The devices that export these counters are highly platform-dependent and the
49 data may be difficult to interpret without an in-depth understanding of the
50 operation of the components that are being measured and of the system they
51 reside in.
52 .SH OPTIONS
53 .sp
54 .LP
55 The following options are supported:
56 .sp
57 .ne 2
58 .na
59 \fB\fB-a\fR\fR
60 .ad
61 .sp .6
62 .RS 4n
63 Display absolute counter values. The default is \fBdelta\fR values.
64 .RE
66 .sp
67 .ne 2
68 .na
69 \fB\fB-e\fR \fIdevice-inst\fR\fR
70 .ad
71 .sp .6
72 .RS 4n
73 Display the list of events that the specified device supports for each pic.
74 .sp
75 Specify \fIdevice-inst\fR as device (\fBname\fR) followed by an optional
76 instance number. If an instance number is specified, the events for that
77 instance are displayed. If no instance number is specified, the events for the
78 first instance of the specified device are displayed.
79 .RE
81 .sp
82 .ne 2
83 .na
84 \fB\fB-h\fR\fR
85 .ad
86 .sp .6
87 .RS 4n
88 Print a usage message.
89 .RE
91 .sp
92 .ne 2
93 .na
94 \fB\fB-l\fR\fR
95 .ad
96 .sp .6
97 .RS 4n
98 List the devices in the system which support performance counters.
99 .RE
101 .sp
102 .ne 2
103 .na
104 \fB\fB-n\fR\fR
105 .ad
106 .sp .6
107 .RS 4n
108 Do not display a title in the output. The default is to display titles.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fB-r\fR \fIdevice-inst\fR\fR
115 .ad
116 .sp .6
117 .RS 4n
118 Read and display all \fBpic\fR values for the specified device
119 .sp
120 Specify \fIdevice-inst\fR as \fIdevice\fR (\fBname\fR) followed by \fIinstance
121 number\fR, if specifying an instance number of a device whose counters are to
122 be read and displayed. If all instances of this device are to be read, use
123 \fIdevice\fR (\fBname\fR) without an instance number. All \fBpic\fR values will
124 be sampled when using the \fB-r\fR option.
125 .RE
127 .sp
128 .ne 2
129 .na
130 \fB\fB-w\fR \fIdevice-inst\fR [,pic0=\fIevent\fR] [,pic\fIn\fR=\fIevent\fR] \fR
131 .ad
132 .sp .6
133 .RS 4n
134 Program (write) the specified devices to count the specified events. Write
135 access to the counters is restricted to root users only. Non-root users can use
136 \fB-r\fR option.
137 .sp
138 Specify \fIdevice-inst\fR as \fIdevice\fR (\fBname\fR) followed by an optional
139 \fIinstance number\fR. If specifying an instance number of a device to program
140 these events on. If all instances of this device are to be programmed the same,
141 then use \fIdevice\fR without an instance number. Specify an event to be
142 counted for a specified \fBpic\fR by providing a comma separated list of
143 \fBpic\fIn\fR=\fR\fIevent\fR values.
144 .sp
145 The \fB-e\fR option displays all valid event names for each device. Any devices
146 that are programmed will be sampled every interval seconds and repeated count
147 times. It is recommended that the interval specified is small enough to ensure
148 that counter wraparound will be detected. The rate at which counters
149 wraparound varies from device to device. If a user is programming events using
150 the \fB-w\fR option and \fBbusstat\fR detects that another user has changed the
151 events that are being counted, the tool will terminate as the programmed
152 devices are now being controlled by another user. Only one user can be
153 programming a device instance at any one time. Extra devices can be sampled
154 using the \fB-r\fR option. Using multiple instances of the \fB-w\fR option on
155 the same command line, with the same \fIdevice-inst\fR specifying a different
156 list of events for the \fBpic\fRs will give the effect of multiplexing for that
157 device. \fBbusstat\fR will switch between the list of events for that device
158 every interval seconds. Event can be a string representing the event name, or
159 even a number representing the bit pattern to be programmed into the
160 Performance Control Register (\fBPCR\fR). This assumes explicit knowledge of
161 the meaning of the control register bits for a device. The number can be
162 specified in hexadecimal, decimal, or octal, using the usual conventions of
163 \fBstrtol\fR(3C).
164 .RE
166 .SH EXIT STATUS
167 .sp
168 .LP
169 The following exit values are returned:
170 .sp
171 .ne 2
172 .na
173 \fB0\fR
174 .ad
175 .RS 5n
176 Successful completion.
177 .RE
179 .sp
180 .ne 2
181 .na
182 \fB1\fR
183 .ad
184 .RS 5n
185 An error occurred.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB2\fR
192 .ad
193 .RS 5n
194 Another user is writing to the same devices.
195 .RE
197 .SH EXAMPLES
198 .SS "SPARC Only"
199 .LP
200 \fBExample 1 \fRProgramming and monitoring the Address Controller counters
201 .sp
202 .LP
203 In this example, \fBac0\fR refers to the Address Controller instance 0. The
204 counters are programmed to count Memory Bank stalls on an Ultra Enterprise
205 system at 10 second intervals with the values displayed in absolute form
206 instead of deltas.
208 .sp
209 .in +2
210 .nf
211 # busstat -a -w ac0,pic0=mem_bank0_stall,pic1=mem_bank1_stall 10
212 time dev event0 pic0 event1 pic1
213 10 ac0 mem_bank0_stall 1234 mem_bank1_stall 5678
214 20 ac0 mem_bank0_stall 5678 mem_bank1_stall 12345
215 30 ac0 mem_bank0_stall 12345 mem_bank1_stall 56789
216 \&...
217 .fi
218 .in -2
219 .sp
221 .sp
222 .LP
223 For a complete list of the supported events for a device, use the \fB-e\fR
224 option.
226 .LP
227 \fBExample 2 \fRProgramming and monitoring the counters on all instances of the
228 Address Controller
229 .sp
230 .LP
231 In this example, \fBac\fR refers to all \fBac\fR instances. This example
232 programs all instances of the Address Controller counters to \fBcount_clock\fR
233 cycles and \fBmem_bank0_rds\fR at 2 second intervals, 100 times, displaying the
234 values as deltas.
236 .sp
237 .in +2
238 .nf
239 # busstat -w ac,pic0=clock_cycles,pic1=mem_bank0_rds 2 100
240 time dev event0 pic0 event1 pic1
241 2 ac0 clock_cycles 167242902 mem_bank0_rds 3144
242 2 ac1 clock_cycles 167254476 mem_bank0_rds 1392
243 4 ac0 clock_cycles 168025190 mem_bank0_rds 40302
244 4 ac1 clock_cycles 168024056 mem_bank0_rds 40580
245 \&...
246 .fi
247 .in -2
248 .sp
250 .LP
251 \fBExample 3 \fRMonitoring the events being counted
252 .sp
253 .LP
254 This example monitors the events that are being counted on the sbus1 device,
255 100 times at 1 second intervals. It suggests that a root user has changed the
256 events that \fBsbus1\fR was counting to be \fBdvma_tlb_misses\fR and interrupts
257 instead of \fBpio_cycles\fR.
259 .sp
260 .in +2
261 .nf
262 % busstat -r sbus0 1 100
264 time dev event0 pic0 event1 pic1
265 1 sbus1 pio_cycles 2321 pio_cycles 2321
266 2 sbus1 pio_cycles 48 pio_cycles 48
267 3 sbus1 pio_cycles 49 pio_cycles 49
268 4 sbus1 pio_cycles 2281 pio_cycles 2281
269 5 sbus1 dvma_tlb_misses 0 interrupts 0
270 6 sbus1 dvma_tlb_misses 6 interrupts 2
271 7 sbus1 dvma_tlb_misses 8 interrupts 11
272 \&...
273 .fi
274 .in -2
275 .sp
277 .LP
278 \fBExample 4 \fREvent Multiplexing
279 .sp
280 .LP
281 This example programs \fBac0\fR to alternate between counting (clock cycles,
282 \fBmem_bank0_rds\fR) and (\fBaddr_pkts\fR, \fBdata_pkts\fR) at 2 second
283 intervals while also monitoring what \fBac1\fR is counting :
285 .sp
286 .LP
287 It shows the expected output of the above \fBbusstat\fR command. Another root
288 user on the machine has changed the events that this user had programmed and
289 \fBbusstat\fR has detected this and terminates the command with a message.
291 .sp
292 .in +2
293 .nf
294 # busstat -w ac0,pic0=clock_cycles,pic1=mem_bank0_rds \e
295 -w ac0,pic0=addr_pkts,pic1=data_pkts \e
296 -r ac1 2
298 time dev event0 pic0 event1 pic1
299 2 ac0 addr_pkts 12866 data_pkts 17015
300 2 ac1 rio_pkts 385 rio_pkts 385
301 4 ac0 clock_cycles 168018914 mem_bank0_rds 2865
302 4 ac1 rio_pkts 506 rio_pkts 506
303 6 ac0 addr_pkts 144236 data_pkts 149223
304 6 ac1 rio_pkts 522 rio_pkts 522
305 8 ac0 clock_cycles 168021245 mem_bank0_rds 2564
306 8 ac1 rio_pkts 387 rio_pkts 387
307 10 ac0 addr_pkts 144292 data_pkts 159645
308 10 ac1 rio_pkts 506 rio_pkts 506
309 12 ac0 clock_cycles 168020364 mem_bank0_rds 2665
310 12 ac1 rio_pkts 522 rio_pkts 522
311 busstat: events changed (possibly by another busstat).
312 #
313 .fi
314 .in -2
315 .sp
317 .SH SEE ALSO
318 .sp
319 .LP
320 \fBiostat\fR(8), \fBmpstat\fR(8), \fBvmstat\fR(8), \fBstrtol\fR(3C),
321 \fBattributes\fR(5)