1busstat(1M) System Administration Commands busstat(1M)
2
6 busstat - report bus-related performance statistics
7
9 busstat -e device-inst | -h | -l
10 busstat [-a] [-n]
13 [-w device-inst [,pic0=event,picn=event ]]...
14 [-r device-inst]... [interval [count]]
15
18 busstat provides access to the bus-related performance counters in the
19 system. These performance counters allow for the measurement of statis‐
20 tics like hardware clock cycles, bus statistics including DMA and cache
21 coherency transactions on a multiprocessor system. Each bus device that
22 supports these counters can be programmed to count a number of events
23 from a specified list. Each device supports one or more Performance
24 Instrumentation Counters (PIC) that are capable of counting events
25 independently of each other.
26 Separate events can be selected for each PIC on each instance of these
29 devices. busstat summarizes the counts over the last interval seconds,
30 repeating forever. If a count is given, the statistics are repeated
31 count times.
32 Only root users can program these counters. Non-root users have the
35 option of reading the counters that have been programmed by a root
36 user.
37 The default value for the interval argument is 1 second, and the
40 default count is unlimited.
41 The devices that export these counters are highly platform-dependent
44 and the data may be difficult to interpret without an in-depth under‐
45 standing of the operation of the components that are being measured and
46 of the system they reside in.
47
49 The following options are supported:
50 -a
52 Display absolute counter values. The default is delta values.
54 -e device-inst
57 Display the list of events that the specified device supports
59 for each pic.
60 Specify device-inst as device (name) followed by an optional
62 instance number. If an instance number is specified, the events for
63 that instance are displayed. If no instance number is specified,
64 the events for the first instance of the specified device are dis‐
65 played.
66 -h
69 Print a usage message.
71 -l
74 List the devices in the system which support performance counters.
76 -n
79 Do not display a title in the output. The default is to display
81 titles.
82 -r device-inst
85 Read and display all pic values for the specified device
87 Specify device-inst as device (name) followed by instance number,
89 if specifying an instance number of a device whose counters are to
90 be read and displayed. If all instances of this device are to be
91 read, use device (name) without an instance number. All pic values
92 will be sampled when using the -r option.
93 -w device-inst [,pic0=event] [,picn=event]
96 Program (write) the specified devices to count the specified
98 events. Write access to the counters is restricted to root users
99 only. Non-root users can use -r option.
100 Specify device-inst as device (name) followed by an optional
102 instance number. If specifying an instance number of a device to
103 program these events on. If all instances of this device are to be
104 programmed the same, then use device without an instance number.
105 Specify an event to be counted for a specified pic by providing a
106 comma separated list of picn=event values.
107 The -e option displays all valid event names for each device. Any
109 devices that are programmed will be sampled every interval seconds
110 and repeated count times. It is recommended that the interval spec‐
111 ified is small enough to ensure that counter wraparound will be
112 detected. The rate at which counters wraparound varies from
113 device to device. If a user is programming events using the -w
114 option and busstat detects that another user has changed the events
115 that are being counted, the tool will terminate as the programmed
116 devices are now being controlled by another user. Only one user can
117 be programming a device instance at any one time. Extra devices can
118 be sampled using the -r option. Using multiple instances of the -w
119 option on the same command line, with the same device-inst specify‐
120 ing a different list of events for the pics will give the effect of
121 multiplexing for that device. busstat will switch between the list
122 of events for that device every interval seconds. Event can be a
123 string representing the event name, or even a number representing
124 the bit pattern to be programmed into the Performance Control Reg‐
125 ister (PCR). This assumes explicit knowledge of the meaning of the
126 control register bits for a device. The number can be specified in
127 hexadecimal, decimal, or octal, using the usual conventions of str‐
128 tol(3C).
129
132 The following exit values are returned:
133 0 Successful completion.
135 1 An error occurred.
138 2 Another user is writing to the same devices.
141
144 SPARC Only
145 Example 1 Programming and monitoring the Address Controller counters
146 In this example, ac0 refers to the Address Controller instance 0. The
149 counters are programmed to count Memory Bank stalls on an Ultra Enter‐
150 prise system at 10 second intervals with the values displayed in abso‐
151 lute form instead of deltas.
152 # busstat -a -w ac0,pic0=mem_bank0_stall,pic1=mem_bank1_stall 10
155 time dev event0 pic0 event1 pic1
156 10 ac0 mem_bank0_stall 1234 mem_bank1_stall 5678
157 20 ac0 mem_bank0_stall 5678 mem_bank1_stall 12345
158 30 ac0 mem_bank0_stall 12345 mem_bank1_stall 56789
159 ...
160 For a complete list of the supported events for a device, use the -e
165 option.
166 Example 2 Programming and monitoring the counters on all instances of
169 the Address Controller
170 In this example, ac refers to all ac instances. This example programs
173 all instances of the Address Controller counters to count_clock cycles
174 and mem_bank0_rds at 2 second intervals, 100 times, displaying the val‐
175 ues as deltas.
176 # busstat -w ac,pic0=clock_cycles,pic1=mem_bank0_rds 2 100
179 time dev event0 pic0 event1 pic1
180 2 ac0 clock_cycles 167242902 mem_bank0_rds 3144
181 2 ac1 clock_cycles 167254476 mem_bank0_rds 1392
182 4 ac0 clock_cycles 168025190 mem_bank0_rds 40302
183 4 ac1 clock_cycles 168024056 mem_bank0_rds 40580
184 ...
185 Example 3 Monitoring the events being counted
189 This example monitors the events that are being counted on the sbus1
192 device, 100 times at 1 second intervals. It suggests that a root user
193 has changed the events that sbus1 was counting to be dvma_tlb_misses
194 and interrupts instead of pio_cycles.
195 % busstat -r sbus0 1 100
198 time dev event0 pic0 event1 pic1
200 1 sbus1 pio_cycles 2321 pio_cycles 2321
201 2 sbus1 pio_cycles 48 pio_cycles 48
202 3 sbus1 pio_cycles 49 pio_cycles 49
203 4 sbus1 pio_cycles 2281 pio_cycles 2281
204 5 sbus1 dvma_tlb_misses 0 interrupts 0
205 6 sbus1 dvma_tlb_misses 6 interrupts 2
206 7 sbus1 dvma_tlb_misses 8 interrupts 11
207 ...
208 Example 4 Event Multiplexing
212 This example programs ac0 to alternate between counting (clock cycles,
215 mem_bank0_rds) and (addr_pkts, data_pkts) at 2 second intervals while
216 also monitoring what ac1 is counting :
217 It shows the expected output of the above busstat command. Another root
221 user on the machine has changed the events that this user had pro‐
222 grammed and busstat has detected this and terminates the command with a
223 message.
224 # busstat -w ac0,pic0=clock_cycles,pic1=mem_bank0_rds \
227 -w ac0,pic0=addr_pkts,pic1=data_pkts \
228 -r ac1 2
229 time dev event0 pic0 event1 pic1
231 2 ac0 addr_pkts 12866 data_pkts 17015
232 2 ac1 rio_pkts 385 rio_pkts 385
233 4 ac0 clock_cycles 168018914 mem_bank0_rds 2865
234 4 ac1 rio_pkts 506 rio_pkts 506
235 6 ac0 addr_pkts 144236 data_pkts 149223
236 6 ac1 rio_pkts 522 rio_pkts 522
237 8 ac0 clock_cycles 168021245 mem_bank0_rds 2564
238 8 ac1 rio_pkts 387 rio_pkts 387
239 10 ac0 addr_pkts 144292 data_pkts 159645
240 10 ac1 rio_pkts 506 rio_pkts 506
241 12 ac0 clock_cycles 168020364 mem_bank0_rds 2665
242 12 ac1 rio_pkts 522 rio_pkts 522
243 busstat: events changed (possibly by another busstat).
244 #
245
249 See attributes(5) for descriptions of the following attributes:
250 ┌─────────────────────────────┬─────────────────────────────┐
255 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
256 ├─────────────────────────────┼─────────────────────────────┤
257 │Availability │SUNWcsu │
258 └─────────────────────────────┴─────────────────────────────┘
259
261 iostat(1M), mpstat(1M), vmstat(1M), strtol(3C), attributes(5)
262SunOS 5.11 1 Nov 1999 busstat(1M)