1.\" Copyright (c) 2003-2006 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" This software is provided by Joseph Koshy ``as is'' and 13.\" any express or implied warranties, including, but not limited to, the 14.\" implied warranties of merchantability and fitness for a particular purpose 15.\" are disclaimed. in no event shall Joseph Koshy be liable 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd April 2, 2006 27.Os 28.Dt PMCSTAT 8 29.Sh NAME 30.Nm pmcstat 31.Nd "performance measurement with performance monitoring hardware" 32.Sh SYNOPSIS 33.Nm 34.Op Fl C 35.Op Fl D Ar pathname 36.Op Fl E 37.Op Fl M Ar mapfilename 38.Op Fl O Ar logfilename 39.Op Fl P Ar event-spec 40.Op Fl R Ar logfilename 41.Op Fl S Ar event-spec 42.Op Fl W 43.Op Fl c Ar cpu 44.Op Fl d 45.Op Fl g 46.Op Fl k Ar kerneldir 47.Op Fl n Ar rate 48.Op Fl o Ar outputfile 49.Op Fl p Ar event-spec 50.Op Fl q 51.Op Fl r Ar fsroot 52.Op Fl s Ar event-spec 53.Op Fl t Ar pid 54.Op Fl v 55.Op Fl w Ar secs 56.Op Ar command Op Ar args 57.Sh DESCRIPTION 58The 59.Nm 60utility measures system performance using the facilities provided by 61.Xr hwpmc 4 . 62.Pp 63The 64.Nm 65utility can measure both hardware events seen by the system as a 66whole, and those seen when a specified process is executing on the 67system's CPUs. 68If a specific process is being targeted (for example, 69if the 70.Fl t Ar pid 71option is specified, or if a command line is specified using 72.Ar command ) , 73then measurement occurs till the target process exits or 74the 75.Nm 76utility is interrupted by the user. 77If a specific process is not targeted for measurement, then 78.Nm 79will perform system-wide measurements till interrupted by the 80user. 81.Pp 82A given invocation of 83.Nm 84can mix allocations of system-mode and process-mode PMCs, of both 85counting and sampling flavors. 86The values of all counting PMCs are printed in human readable form 87at regular intervals by 88.Nm . 89The output of sampling PMCs may be configured to go to a log file for 90subsequent offline analysis, or, at the expense of greater 91overhead, may be configured to be printed in text form on the fly. 92.Pp 93Hardware events to measure are specified to 94.Nm 95using event specifier strings 96.Ar event-spec . 97The syntax of these event specifiers is machine dependent and is 98documented in 99.Xr pmc 3 . 100.Pp 101A process-mode PMC may be configured to be inheritable by the target 102process' current and future children. 103.Sh OPTIONS 104The following options are available: 105.Bl -tag -width indent 106.It Fl C 107Toggle between showing cumulative or incremental counts for 108subsequent counting mode PMCs specified on the command line. 109The default is to show incremental counts. 110.It Fl D Ar pathname 111Create files with per-program samples in the directory named 112by 113.Ar pathname . 114The default is to create these files in the current directory. 115.It Fl E 116Toggle showing per-process counts at the time a tracked process 117exits for subsequent process-mode PMCs specified on the command line. 118This option is useful for mapping the performance characteristics of a 119complex pipeline of processes when used in conjunction with the 120.Fl d 121option. 122The default is to not to enable per-process tracking. 123.It Fl M Ar mapfilename 124Write the mapping between executable objects encountered in the event 125log and the abbreviated pathnames used for 126.Xr gprof 1 127profiles to file 128.Ar mapfilename . 129If this option is not specified, mapping information is not written. 130Argument 131.Ar mapfilename 132may be a 133.Dq Li - 134in which case this mapping information is sent to the output 135file configured by the 136.Fl o 137option. 138.It Fl O Ar logfilename 139Send logging output to file 140.Ar logfilename . 141If 142.Ar logfilename 143is of the form 144.Ar hostname Ns : Ns Ar port , 145where 146.Ar hostname 147does not start with a 148.Sq \&. 149or a 150.Sq / , 151then 152.Nm 153will open a network socket to host 154.Ar hostname 155on port 156.Ar port . 157.Pp 158If the 159.Fl O 160option is not specified and one of the logging options is requested, 161then 162.Nm 163will print a textual form of the logged events to the configured 164output file. 165.It Fl P Ar event-spec 166Allocate a process mode sampling PMC measuring hardware events 167specified in 168.Ar event-spec . 169.It Fl R Ar logfilename 170Perform offline analysis using sampling data in file 171.Ar logfilename . 172.It Fl S Ar event-spec 173Allocate a system mode sampling PMC measuring hardware events 174specified in 175.Ar event-spec . 176.It Fl W 177Toggle logging the incremental counts seen by the threads of a 178tracked process each time they are scheduled on a CPU. 179This is an experimental feature intended to help analyse the 180dynamic behaviour of processes in the system. 181It may incur substantial overhead if enabled. 182The default is for this feature to be disabled. 183.It Fl c Ar cpu 184Set the cpu for subsequent system mode PMCs specified on the 185command line to 186.Ar cpu . 187The default is to allocate system mode PMCs on CPU zero. 188.It Fl d 189Toggle between process mode PMCs measuring events for the target 190process' current and future children or only measuring events for 191the target process. 192The default is to measure events for the target process alone. 193.It Fl g 194Produce flat execution profiles in a format compatible with 195.Xr gprof 1 . 196A separate profile file is generated for each executable object 197encountered. 198Profile files are placed in sub-directories named by their PMC 199event name. 200.It Fl k Ar kerneldir 201Set the pathname of the kernel directory to argument 202.Ar kerneldir . 203This directory specifies where 204.Nm 205should look for the kernel and its modules. 206The default is 207.Pa /boot/kernel . 208.It Fl n Ar rate 209Set the default sampling rate for subsequent sampling mode 210PMCs specified on the command line. 211The default is to configure PMCs to sample the CPU's instruction 212pointer every 65536 events. 213.It Fl o Ar outputfile 214Send counter readings and textual representations of logged data 215to file 216.Ar outputfile . 217The default is to send output to 218.Pa stderr . 219.It Fl p Ar event-spec 220Allocate a process mode counting PMC measuring hardware events 221specified in 222.Ar event-spec . 223.It Fl q 224Decrease verbosity. 225.It Fl r Ar fsroot 226Set the top of the filesystem hierarchy under which executables 227are located to argument 228.Ar fsroot . 229The default is 230.Pa / . 231.It Fl s Ar event-spec 232Allocate a system mode counting PMC measuring hardware events 233specified in 234.Ar event-spec . 235.It Fl t Ar pid 236Attach all process mode PMCs allocated to the process with PID 237.Ar pid . 238The option is not allowed in conjunction with specifying a 239command using 240.Ar command . 241.It Fl v 242Increase verbosity. 243.It Fl w Ar secs 244Print the values of all counting mode PMCs every 245.Ar secs 246seconds. 247The argument 248.Ar secs 249may be a fractional value. 250The default interval is 5 seconds. 251.El 252.Pp 253If 254.Ar command 255is specified, it is executed using 256.Xr execvp 3 . 257.Sh EXAMPLES 258To perform system-wide statistical sampling on an AMD Athlon CPU with 259samples taken every 32768 instruction retirals and data being sampled 260to file 261.Pa sample.stat , 262use: 263.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions" 264.Pp 265To execute 266.Nm mozilla 267and measure the number of data cache misses suffered 268by it and its children every 12 seconds on an AMD Athlon, use: 269.Dl "pmcstat -d -w 12 -p k7-dc-misses mozilla" 270.Pp 271To perform system-wide sampling based on processor instructions 272retired use: 273.Dl "pmcstat -S instructions -O /tmp/sample.out" 274.Pp 275To send the generated event log to a remote machine use: 276.Dl "pmcstat -S instructions -O remotehost:port" 277On the remote machine, the sample log can be collected using 278.Xr nc 1 : 279.Dl "nc -l remotehost port > /tmp/sample.out" 280.Pp 281To generate 282.Xr gprof 1 283compatible flat profiles from a sample file use: 284.Dl "pmcstat -R /tmp/sample.out -g" 285.Sh DIAGNOSTICS 286.Ex -std 287.Sh SEE ALSO 288.Xr gprof 1 , 289.Xr nc 1 , 290.Xr execvp 3 , 291.Xr pmc 3 , 292.Xr pmclog 3 , 293.Xr hwpmc 4 , 294.Xr pmccontrol 8 , 295.Xr sysctl 8 296.Sh HISTORY 297The 298.Nm 299utility first appeared in 300.Fx 6.0 . 301It is 302.Ud 303.Sh AUTHORS 304.An Joseph Koshy Aq jkoshy@FreeBSD.org 305.Sh BUGS 306.Nm 307cannot yet analyse 308.Xr hwpmc 4 309logs generated by non-native architectures. 310