49874f6ea3
Kernel changes: Inform hwpmc of executable objects brought into the system by kldload() and mmap(), and of their removal by kldunload() and munmap(). A helper function linker_hwpmc_list_objects() has been added to "sys/kern/kern_linker.c" and is used by hwpmc to retrieve the list of currently loaded kernel modules. The unused `MAPPINGCHANGE' event has been deprecated in favour of separate `MAP_IN' and `MAP_OUT' events; this change reduces space wastage in the log. Bump the hwpmc's ABI version to "2.0.00". Teach hwpmc(4) to handle the map change callbacks. Change the default per-cpu sample buffer size to hold 32 samples (up from 16). Increment __FreeBSD_version. libpmc(3) changes: Update libpmc(3) to deal with the new events in the log file; bring the pmclog(3) manual page in sync with the code. pmcstat(8) changes: Introduce new options to pmcstat(8): "-r" (root fs path), "-M" (mapfile name), "-q"/"-v" (verbosity control). Option "-k" now takes a kernel directory as its argument but will also work with the older invocation syntax. Rework string handling in pmcstat(8) to use an opaque type for interned strings. Clean up ELF parsing code and add support for tracking dynamic object mappings reported by a v2.0.00 hwpmc(4). Report statistics at the end of a log conversion run depending on the requested verbosity level. Reviewed by: jhb, dds (kernel parts of an earlier patch) Tested by: gallatin (earlier patch)
283 lines
8.2 KiB
Groff
283 lines
8.2 KiB
Groff
.\" Copyright (c) 2003-2006 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 March 26, 2006
|
|
.Os
|
|
.Dt PMCSTAT 8
|
|
.Sh NAME
|
|
.Nm pmcstat
|
|
.Nd "performance measurement with performance monitoring hardware"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl C
|
|
.Op Fl D Ar pathname
|
|
.Op Fl E
|
|
.Op Fl M Ar mapfilename
|
|
.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 k Ar kerneldir
|
|
.Op Fl n Ar rate
|
|
.Op Fl o Ar outputfile
|
|
.Op Fl p Ar event-spec
|
|
.Op Fl q
|
|
.Op Fl r Ar fsroot
|
|
.Op Fl s Ar event-spec
|
|
.Op Fl t Ar pid
|
|
.Op Fl v
|
|
.Op Fl w Ar secs
|
|
.Op Ar command Op Ar 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 printed in text form 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 M Ar mapfilename
|
|
Write the mapping between executable objects encountered in the event
|
|
log and the abbreviated pathnames used for
|
|
.Xr gprof 1
|
|
profiles to file
|
|
.Ar mapfilename .
|
|
If this option is not specified, mapping information is not written.
|
|
Argument
|
|
.Ar mapfilename
|
|
may be a
|
|
.Dq Li -
|
|
in which case this mapping information is sent to the output
|
|
file configured by the
|
|
.Fl o
|
|
option.
|
|
.It Fl O Ar logfilename
|
|
Send logging output to file
|
|
.Ar logfilename .
|
|
If this option is not specified and one of the logging options
|
|
is requested, then
|
|
.Nm
|
|
will print a textual form of the logged events 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 flat execution profiles in a format compatible with
|
|
.Xr gprof 1 .
|
|
A separate profile file is generated for each executable object
|
|
encountered.
|
|
Profile files are placed in sub-directories named by their PMC
|
|
event name.
|
|
.It Fl k Ar kerneldir
|
|
Set the pathname of the kernel directory to argument
|
|
.Ar kerneldir .
|
|
This directory specifies where
|
|
.Nm
|
|
should look for the kernel and its modules.
|
|
The default is
|
|
.Pa /boot/kernel .
|
|
.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 textual 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 q
|
|
Decrease verbosity.
|
|
.It Fl r Ar fsroot
|
|
Set the top of the filesystem hierarchy under which executables
|
|
are located to argument
|
|
.Ar fsroot .
|
|
The default is
|
|
.Pa / .
|
|
.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 v
|
|
Increase verbosity.
|
|
.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
|
|
.Pa sample.stat ,
|
|
use:
|
|
.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
|
|
.Pp
|
|
To execute
|
|
.Nm 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"
|
|
.Pp
|
|
To collect a system-wide samples driven by processor instructions executed
|
|
use:
|
|
.Dl "pmcstat -S instructions -O /tmp/sample.out"
|
|
.Pp
|
|
To generate
|
|
.Xr gprof 1
|
|
compatible flat profiles from a sample file use:
|
|
.Dl "pmcstat -R /tmp/sample.out -g"
|
|
.Sh DIAGNOSTICS
|
|
.Ex -std
|
|
.Sh SEE ALSO
|
|
.Xr gprof 1 ,
|
|
.Xr execvp 3 ,
|
|
.Xr pmc 3 ,
|
|
.Xr pmclog 3 ,
|
|
.Xr hwpmc 4 ,
|
|
.Xr pmccontrol 8 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Fx 6.0 .
|
|
It is
|
|
.Ud
|
|
.Sh AUTHORS
|
|
.An Joseph Koshy Aq jkoshy@FreeBSD.org
|
|
.Sh BUGS
|
|
On AMD64 platforms
|
|
.Nm
|
|
does not yet handle profiles with samples from 32 bit executables.
|