usr/src/man/man1m/busstat.1m

   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 1M "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
  14
  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
  21
  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
  65
  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
  80
  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
  90
  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
 100
 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
 110
 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
 126
 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
 165
 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
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB1\fR
 183 .ad
 184 .RS 5n
 185 An error occurred.
 186 .RE
 187
 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
 196
 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.
 207
 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
 220
 221 .sp
 222 .LP
 223 For a complete list of the supported events for a device, use the \fB-e\fR
 224 option.
 225
 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.
 235
 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
 249
 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.
 258
 259 .sp
 260 .in +2
 261 .nf
 262 % busstat -r sbus0 1 100
 263
 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
 276
 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 :
 284
 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.
 290
 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
 297
 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
 316
 317 .SH SEE ALSO
 318 .sp
 319 .LP
 320 \fBiostat\fR(1M), \fBmpstat\fR(1M), \fBvmstat\fR(1M), \fBstrtol\fR(3C),
 321 \fBattributes\fR(5)