busstat

Synopsis

Description

busstat provides access to the bus-related performance counters in the system. These performance
counters allow for the measurement of statistics like hardware clock cycles, bus
statistics including DMA and cache coherency transactions on a multiprocessor system. Each
bus device that supports these counters can be programmed to count a number
of events from a specified list. Each device supports one or more
Performance Instrumentation Counters (PIC) that are capable of counting events independently of
each other.

Separate events can be selected for each PIC on each instance of
these devices. busstat summarizes the counts over the last interval seconds, repeating
forever. If a count is given, the statistics are repeated count times.

Only root users can program these counters. Non-root users have the
option of reading the counters that have been programmed by a root
user.

The default value for the interval argument is 1 second, and the
default count is unlimited.

The devices that export these counters are highly platform-dependent and the data
may be difficult to interpret without an in-depth understanding of the operation
of the components that are being measured and of the system they
reside in.

Options

The following options are supported:

-a

Display absolute counter values. The default is delta values.

-edevice-inst

Display the list of events that the specified device supports for each pic.

Specify device-inst as device (name) followed by an optional instance number. If an instance number is specified, the events for that instance are displayed. If no instance number is specified, the events for the first instance of the specified device are displayed.

-h

Print a usage message.

-l

List the devices in the system which support performance counters.

-n

Do not display a title in the output. The default is to display titles.

-rdevice-inst

Read and display all pic values for the specified device

Specify device-inst as device (name) followed by instance number, if specifying an instance number of a device whose counters are to be read and displayed. If all instances of this device are to be read, use device (name) without an instance number. All pic values will be sampled when using the -r option.

-wdevice-inst [,pic0=event] [,picn=event]

Program (write) the specified devices to count the specified events. Write access to the counters is restricted to root users only. Non-root users can use -r option.

Specify device-inst as device (name) followed by an optional instance number. If specifying an instance number of a device to program these events on. If all instances of this device are to be programmed the same, then use device without an instance number. Specify an event to be counted for a specified pic by providing a comma separated list of picn=event values.

The -e option displays all valid event names for each device. Any devices that are programmed will be sampled every interval seconds and repeated count times. It is recommended that the interval specified is small enough to ensure that counter wraparound will be detected. The rate at which counters wraparound varies from device to device. If a user is programming events using the -w option and busstat detects that another user has changed the events that are being counted, the tool will terminate as the programmed devices are now being controlled by another user. Only one user can be programming a device instance at any one time. Extra devices can be sampled using the -r option. Using multiple instances of the -w option on the same command line, with the same device-inst specifying a different list of events for the pics will give the effect of multiplexing for that device. busstat will switch between the list of events for that device every interval seconds. Event can be a string representing the event name, or even a number representing the bit pattern to be programmed into the Performance Control Register (PCR). This assumes explicit knowledge of the meaning of the control register bits for a device. The number can be specified in hexadecimal, decimal, or octal, using the usual conventions of strtol(3C).

Exit Status

The following exit values are returned:

0

Successful completion.

1

An error occurred.

2

Another user is writing to the same devices.

Examples

SPARC Only

Example 1 Programming and monitoring the Address Controller counters

In this example, ac0 refers to the Address Controller instance 0. The
counters are programmed to count Memory Bank stalls on an Ultra Enterprise
system at 10 second intervals with the values displayed in absolute form
instead of deltas.

For a complete list of the supported events for a device, use
the -e option.

Example 2 Programming and monitoring the counters on all instances of the Address Controller

In this example, ac refers to all ac instances. This example programs
all instances of the Address Controller counters to count_clock cycles and mem_bank0_rds
at 2 second intervals, 100 times, displaying the values as deltas.

This example monitors the events that are being counted on the
sbus1 device, 100 times at 1 second intervals. It suggests that a
root user has changed the events that sbus1 was counting to be
dvma_tlb_misses and interrupts instead of pio_cycles.

This example programs ac0 to alternate between counting (clock cycles, mem_bank0_rds) and
(addr_pkts, data_pkts) at 2 second intervals while also monitoring what ac1 is
counting :

It shows the expected output of the above busstat command. Another root
user on the machine has changed the events that this user had
programmed and busstat has detected this and terminates the command with a
message.