1d3209ab83
- Implement sampling modes and logging support in hwpmc(4). - Separate MI and MD parts of hwpmc(4) and allow sharing of PMC implementations across different architectures. Add support for P4 (EMT64) style PMCs to the amd64 code. - New pmcstat(8) options: -E (exit time counts) -W (counts every context switch), -R (print log file). - pmc(3) API changes, improve our ability to keep ABI compatibility in the future. Add more 'alias' names for commonly used events. - bug fixes & documentation.
235 lines
7.0 KiB
Groff
235 lines
7.0 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 D Ar pathname
|
|
.Op Fl C
|
|
.Op Fl E
|
|
.Op Fl O Ar logfilename
|
|
.Op Fl P Ar event-spec
|
|
.Op Fl R Ar logfilename
|
|
.Op Fl S Ar event-spec
|
|
.Op Fl W
|
|
.Op Fl c Ar cpu
|
|
.Op Fl d
|
|
.Op Fl g
|
|
.Op Fl m
|
|
.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 may be configured to go to a log file for
|
|
subsequent offline analysis, or, at the expense of greater
|
|
overhead, may be configured to be processed on the fly.
|
|
.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 or incremental counts for
|
|
subsequent counting mode PMCs specified on the command line.
|
|
The default is to show incremental counts.
|
|
.It Fl D Ar pathname
|
|
Create files with per-program samples in the directory named
|
|
by
|
|
.Ar pathname .
|
|
The default is to create these files in the current directory.
|
|
.It Fl E
|
|
Toggle showing per-process counts at the time a tracked process
|
|
exits for subsequent process-mode PMCs specified on the command line.
|
|
This option is useful for mapping the performance characteristics of a
|
|
complex pipeline of processes when used in conjunction with the
|
|
.Fl d
|
|
option.
|
|
The default is to not to enable per-process tracking.
|
|
.It Fl O Ar logfilename
|
|
Send the output of sampling mode PMCs to
|
|
.Ar logfilename .
|
|
If this option is not specified and one of the logging options
|
|
is requested, then
|
|
.Nm
|
|
will print a human-readable version of the log to the configured
|
|
output file.
|
|
.It Fl P Ar event-spec
|
|
Allocate a process mode sampling PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl R Ar logfilename
|
|
Perform offline analysis using sampling data in file
|
|
.Ar logfilename .
|
|
.It Fl S Ar event-spec
|
|
Allocate a system mode sampling PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl W
|
|
Toggle logging the incremental counts seen by the threads of a
|
|
tracked process each time they are scheduled on a CPU.
|
|
This is an experimental feature intended to help analyse the
|
|
dynamic behaviour of processes in the system.
|
|
It may incur substantial overhead if enabled.
|
|
The default is for this feature to be disabled.
|
|
.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 target process.
|
|
The default is to measure events for the target process alone.
|
|
.It Fl g
|
|
Produce execution profiles in a format compatible with
|
|
.Xr gprof 1 .
|
|
.It Fl m
|
|
When producing
|
|
.Xr gprof 1
|
|
compatible execution profiles, merge profiles across multiple
|
|
invocations of the same executable.
|
|
.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 counter readings and printed representations of logged data
|
|
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 gprof 1 ,
|
|
.Xr execvp 3 ,
|
|
.Xr pmc 3 ,
|
|
.Xr hwpmc 4 ,
|
|
.Xr pmccontrol 8 ,
|
|
.Xr sysctl 8
|