ebccf1e3a6
and documentation into -CURRENT. Bump FreeBSD_version. Reviewed by: alc, jhb (kernel changes)
197 lines
5.6 KiB
Groff
197 lines
5.6 KiB
Groff
.\" Copyright (c) 2003 Joseph Koshy. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" This software is provided by Joseph Koshy ``as is'' and
|
|
.\" any express or implied warranties, including, but not limited to, the
|
|
.\" implied warranties of merchantability and fitness for a particular purpose
|
|
.\" are disclaimed. in no event shall Joseph Koshy be liable
|
|
.\" for any direct, indirect, incidental, special, exemplary, or consequential
|
|
.\" damages (including, but not limited to, procurement of substitute goods
|
|
.\" or services; loss of use, data, or profits; or business interruption)
|
|
.\" however caused and on any theory of liability, whether in contract, strict
|
|
.\" liability, or tort (including negligence or otherwise) arising in any way
|
|
.\" out of the use of this software, even if advised of the possibility of
|
|
.\" such damage.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd Dec 15, 2003
|
|
.Os
|
|
.Dt PMCSTAT 8
|
|
.Sh NAME
|
|
.Nm pmcstat
|
|
.Nd performance measurement with performance monitoring hardware
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl C
|
|
.Op Fl O Ar logfilename
|
|
.Op Fl P Ar event-spec
|
|
.Op Fl S Ar event-spec
|
|
.Op Fl c Ar cpu
|
|
.Op Fl d
|
|
.Op Fl n Ar count
|
|
.Op Fl o Ar outputfile
|
|
.Op Fl p Ar event-spec
|
|
.Op Fl s Ar event-spec
|
|
.Op Fl t Ar pid
|
|
.Op Fl w Ar interval
|
|
.Op command Op args
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility measures system performance using the facilities provided by
|
|
.Xr hwpmc 4 .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility can measure both hardware events seen by the system as a
|
|
whole, and those seen when a specified process is executing on the
|
|
system's CPUs.
|
|
If a specific process is being targeted (for example,
|
|
if the
|
|
.Fl t Ar pid
|
|
option is specified, or if a command line is specified using
|
|
.Ar command ) ,
|
|
then measurement occurs till the target process exits or
|
|
the
|
|
.Nm
|
|
utility is interrupted by the user.
|
|
If a specific process is not targeted for measurement, then
|
|
.Nm
|
|
will perform system-wide measurements till interrupted by the
|
|
user.
|
|
.Pp
|
|
A given invocation of
|
|
.Nm
|
|
can mix allocations of system-mode and process-mode PMCs, of both
|
|
counting and sampling flavors.
|
|
The values of all counting PMCs are printed in human readable form
|
|
at regular intervals by
|
|
.Nm .
|
|
The output of sampling PMCs is configured to go to log file, for later
|
|
analysis by tools like
|
|
.Xr pmcreport 8 .
|
|
.Pp
|
|
Hardware events to measure are specified to
|
|
.Nm
|
|
using event specifier strings
|
|
.Ar event-spec .
|
|
The syntax of these event specifiers is machine dependent and is
|
|
documented in
|
|
.Xr pmc 3 .
|
|
.Pp
|
|
A process-mode PMC may be configured to be inheritable by the target
|
|
process' current and future children.
|
|
.Sh OPTIONS
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl C
|
|
Toggle between showing cumulative and incremental counts for
|
|
subsequent counting mode PMCs specified on the command line.
|
|
The default is to show incremental counts.
|
|
.It Fl O Ar logfilename
|
|
Send the output of sampling mode PMCs to
|
|
.Ar logfilename .
|
|
The default file name is
|
|
.Pa pmcstat.out ,
|
|
in the current directory.
|
|
.It Fl P Ar event-spec
|
|
Allocate a process mode sampling PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl S Ar event-spec
|
|
Allocate a system mode sampling PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl c Ar cpu
|
|
Set the cpu for subsequent system mode PMCs specified on the
|
|
command line to
|
|
.Ar cpu .
|
|
The default is to allocate system mode PMCs on CPU zero.
|
|
.It Fl d
|
|
Toggle between process mode PMCs measuring events for the target
|
|
process' current and future children or only measuring events for
|
|
the attached process.
|
|
The default is to measure events for the target process alone.
|
|
.It Fl n Ar rate
|
|
Set the default sampling rate for subsequent sampling mode
|
|
PMCs specified on the command line.
|
|
The default is to configure PMCs to sample the CPU's instruction
|
|
pointer every 65536 events.
|
|
.It Fl o Ar outputfile
|
|
Send the periodic counter output of
|
|
.Nm
|
|
to file
|
|
.Ar outputfile .
|
|
The default is to send output to
|
|
.Pa stderr .
|
|
.It Fl p Ar event-spec
|
|
Allocate a process mode counting PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl s Ar event-spec
|
|
Allocate a system mode counting PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl t Ar pid
|
|
Attach all process mode PMCs allocated to the process with PID
|
|
.Ar pid .
|
|
The option is not allowed in conjunction with specifying a
|
|
command using
|
|
.Ar command .
|
|
.It Fl w Ar secs
|
|
Print the values of all counting mode PMCs every
|
|
.Ar secs
|
|
seconds.
|
|
The argument
|
|
.Ar secs
|
|
may be a fractional value.
|
|
The default interval is 5 seconds.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Ar command
|
|
is specified, it is executed using
|
|
.Xr execvp 3 .
|
|
.Sh EXAMPLES
|
|
To perform system-wide statistical sampling on an AMD Athlon CPU with
|
|
samples taken every 32768 instruction retirals and data being sampled
|
|
to file
|
|
.Dq sample.stat ,
|
|
use:
|
|
.Dl pmccstat -O sample.stat -n 32768 -S k7-retired-instructions
|
|
.Pp
|
|
To execute
|
|
.Dq mozilla
|
|
and measure the number of data cache misses suffered
|
|
by it and its children every 12 seconds on an AMD Athlon, use:
|
|
.Dl pmcstat -d -w 12 -p k7-dc-misses mozilla
|
|
.Sh DIAGNOSTICS
|
|
.Ex -std pmcstat
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility is proposed to be integrated into
|
|
.Fx
|
|
sometime after
|
|
.Fx 5.2 .
|
|
.Nm
|
|
.Bt
|
|
.Sh AUTHORS
|
|
.An Joseph Koshy Aq jkoshy@FreeBSD.org
|
|
.Sh SEE ALSO
|
|
.Xr execvp 3 ,
|
|
.Xr pmc 3 ,
|
|
.Xr hwpmc 4 ,
|
|
.Xr pmccontrol 8 ,
|
|
.Xr pmcreport 8 ,
|
|
.Xr sysctl 8
|