System Administration Commands                        cpustat(1M)

USAGE
     A closely related utility, cputrack(1), can be used to moni-
     tor  the  behavior of individual applications with little or
     no interference from other activities on the system.

     The cpustat utility must be run by the super-user, as  there
     is  an intrinsic conflict between the use of the CPU perfor-
     mance counters system-wide by cpustat and the use of the CPU
     performance  counters  to monitor an individual process (for
     example, by cputrack.)

     Once any instance of this utility has  started,  no  further
     per-process  or per-LWP use of the counters is allowed until
     the last instance of the utility terminates.

     The times printed by the command correspond to the wallclock
     time  when  the  hardware  counters  were  actually sampled,
     instead of when the program told the kernel to sample  them.
     The time is derived from the same timebase as gethrtime(3C).

     The processor cycle counts enabled by the -t  option  always
     apply  to both user and system modes, regardless of the set-
     tings applied to the performance counter registers.

     On some hardware platforms running in system mode using  the
     "sys"  token,  the  counters  are  implemented  using 32-bit
     registers. While the kernel attempts to catch all  overflows
     to synthesize 64-bit counters, because of hardware implemen-
     tation restrictions, overflows can be lost unless  the  sam-
     pling  interval  is kept short enough. The events most prone
     to wrap are those that count processor clock cycles. If such
     an event is of interest, sampling should occur frequently so
     that less than 4 billion clock cycles can occur between sam-
     ples.

     The output of cpustat is designed to be readily parseable by
     nawk(1)  and  perl(1), thereby allowing performance tools to
     be composed by embedding cpustat in scripts.  Alternatively,
     tools  can  be constructed directly using the same APIs that
     cpustat is built upon using the facilities of  libcpc(3LIB).
     See cpc(3CPC).

     The cpustat utility only monitors the CPUs that are accessi-
     ble  to  it  in  the  current  processor  set. Thus, several
     instances of the utility can be running on the CPUs in  dif-
     ferent  processor  sets. See psrset(1M) for more information
     about processor sets.

     Because cpustat uses LWPs bound to CPUs, the  utility  might
     have  to  be  terminated  before  the  configuration  of the
     relevant processor can be changed.

EXAMPLES
  SPARC
     Example 1: Measuring External Cache References and Misses

     The following example measures misses and references in  the
     external cache. These occur while the processor is operating
     in user mode on an UltraSPARC machine.

     example% cpustat -c EC_ref,EC_misses 1 3

         time cpu event      pic0      pic1
        1.008   0  tick     69284      1647
        1.008   1  tick     43284      1175
        2.008   0  tick    179576      1834
        2.008   1  tick    202022     12046
        3.008   0  tick     93262       384
        3.008   1  tick     63649      1118
        3.008   2 total    651077     18204

  x86
     Example 2: Measuring Branch Prediction Success on Pentium 4

     The following example  measures  branch  mispredictions  and
     total  branch instructions in user and system mode on a Pen-
     tium 4 machine.

      example% cpustat -c \
          pic12=branch_retired,emask12=0x4,pic14=branch_retired,\
          emask14=0xf,sys 1 3

         time cpu event      pic12     pic14
        1.010   1  tick       458       684
        1.010   0  tick       305       511
        2.010   0  tick       181       269
        2.010   1  tick       469       684
        3.010   0  tick       182       269
        3.010   1  tick       468       684
        3.010   2 total      2063      3101

WARNINGS
     By running the  cpustat  command,  the  super-user  forcibly
     invalidates  all  existing performance counter context. This
     can in turn cause all invocations of the  cputrack  command,
     and  other  users  of  performance  counter context, to exit
     prematurely with unspecified errors.

     If cpustat is invoked on a system that has  CPU  performance
     counters  which  are not supported by Solaris, the following
     message appears:

     cpustat: cannot access performance counters - Operation not applicable

     This error message implies that cpc_open() has failed and is
     documented in cpc_open(3CPC).  Review this documentation for
     more information about the problem and possible solutions.

     If a short interval is requested, cpustat might not be  able
     to  keep up with the desired sample rate. In this case, some
     samples might be dropped.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |          ATTRIBUTE          |
    |_____________________________|_____________________________|
    | VALUE                       |                             |
    |_____________________________|_____________________________|
    | Availability                | SUNWcpcu                    |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|


SEE ALSO
     cputrack(1),  nawk(1),  perl(1),   iostat(1M),   prstat(1M),
     psrset(1M),     vmstat(1M),    cpc(3CPC),    cpc_open(3CPC),
     cpc_bind_cpu(3CPC),       gethrtime(3C),        strtoll(3C),
     libcpc(3LIB), attributes(5)

NOTES
     When cpustat is run  on  a  Pentium  4  with  HyperThreading
     enabled,  a CPC set is bound to only one logical CPU of each
     physical CPU.  See cpc_bind_cpu(3CPC).