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: head/usr.sbin/pmcstat/pmcstat.8 145256 2005-04-19 04:01:25Z jkoshy $
.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 .
p 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.
p 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 .
p 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 .
p 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: l -tag -width indent t 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. t Fl O Ar logfilename Send the output of sampling mode PMCs to .Ar logfilename . The default file name is
a pmcstat.out , in the current directory. t Fl P Ar event-spec Allocate a process mode sampling PMC measuring hardware events specified in .Ar event-spec . t Fl S Ar event-spec Allocate a system mode sampling PMC measuring hardware events specified in .Ar event-spec . t 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. t 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. t 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. t Fl o Ar outputfile Send the periodic counter output of .Nm to file .Ar outputfile . The default is to send output to
a stderr . t Fl p Ar event-spec Allocate a process mode counting PMC measuring hardware events specified in .Ar event-spec . t Fl s Ar event-spec Allocate a system mode counting PMC measuring hardware events specified in .Ar event-spec . t 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 . t 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
p 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
p 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 t .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