1.\" Copyright (c) 2003 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 July 1, 2005 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 O Ar logfilename 38.Op Fl P Ar event-spec 39.Op Fl R Ar logfilename 40.Op Fl S Ar event-spec 41.Op Fl W 42.Op Fl c Ar cpu 43.Op Fl d 44.Op Fl g 45.Op Fl k Ar kernelfile 46.Op Fl n Ar rate 47.Op Fl o Ar outputfile 48.Op Fl p Ar event-spec 49.Op Fl s Ar event-spec 50.Op Fl t Ar pid 51.Op Fl w Ar secs 52.Op Ar command Op Ar args 53.Sh DESCRIPTION 54The 55.Nm 56utility measures system performance using the facilities provided by 57.Xr hwpmc 4 . 58.Pp 59The 60.Nm 61utility can measure both hardware events seen by the system as a 62whole, and those seen when a specified process is executing on the 63system's CPUs. 64If a specific process is being targeted (for example, 65if the 66.Fl t Ar pid 67option is specified, or if a command line is specified using 68.Ar command ) , 69then measurement occurs till the target process exits or 70the 71.Nm 72utility is interrupted by the user. 73If a specific process is not targeted for measurement, then 74.Nm 75will perform system-wide measurements till interrupted by the 76user. 77.Pp 78A given invocation of 79.Nm 80can mix allocations of system-mode and process-mode PMCs, of both 81counting and sampling flavors. 82The values of all counting PMCs are printed in human readable form 83at regular intervals by 84.Nm . 85The output of sampling PMCs may be configured to go to a log file for 86subsequent offline analysis, or, at the expense of greater 87overhead, may be configured to be printed in text form on the fly. 88.Pp 89Hardware events to measure are specified to 90.Nm 91using event specifier strings 92.Ar event-spec . 93The syntax of these event specifiers is machine dependent and is 94documented in 95.Xr pmc 3 . 96.Pp 97A process-mode PMC may be configured to be inheritable by the target 98process' current and future children. 99.Sh OPTIONS 100The following options are available: 101.Bl -tag -width indent 102.It Fl C 103Toggle between showing cumulative or incremental counts for 104subsequent counting mode PMCs specified on the command line. 105The default is to show incremental counts. 106.It Fl D Ar pathname 107Create files with per-program samples in the directory named 108by 109.Ar pathname . 110The default is to create these files in the current directory. 111.It Fl E 112Toggle showing per-process counts at the time a tracked process 113exits for subsequent process-mode PMCs specified on the command line. 114This option is useful for mapping the performance characteristics of a 115complex pipeline of processes when used in conjunction with the 116.Fl d 117option. 118The default is to not to enable per-process tracking. 119.It Fl O Ar logfilename 120Send logging output to file 121.Ar logfilename . 122If this option is not specified and one of the logging options 123is requested, then 124.Nm 125will print a textual form of the logged events to the configured 126output file. 127.It Fl P Ar event-spec 128Allocate a process mode sampling PMC measuring hardware events 129specified in 130.Ar event-spec . 131.It Fl R Ar logfilename 132Perform offline analysis using sampling data in file 133.Ar logfilename . 134.It Fl S Ar event-spec 135Allocate a system mode sampling PMC measuring hardware events 136specified in 137.Ar event-spec . 138.It Fl W 139Toggle logging the incremental counts seen by the threads of a 140tracked process each time they are scheduled on a CPU. 141This is an experimental feature intended to help analyse the 142dynamic behaviour of processes in the system. 143It may incur substantial overhead if enabled. 144The default is for this feature to be disabled. 145.It Fl c Ar cpu 146Set the cpu for subsequent system mode PMCs specified on the 147command line to 148.Ar cpu . 149The default is to allocate system mode PMCs on CPU zero. 150.It Fl d 151Toggle between process mode PMCs measuring events for the target 152process' current and future children or only measuring events for 153the target process. 154The default is to measure events for the target process alone. 155.It Fl g 156Produce flat execution profiles in a format compatible with 157.Xr gprof 1 . 158A separate profile file is generated for each executable object 159encountered. 160Profile files are placed in sub-directories named by their PMC 161event name. 162.It Fl k Ar kernelfile 163Set the pathname of the kernel to argument 164.Ar kernelfile . 165The default is 166.Pa /boot/kernel/kernel . 167.It Fl n Ar rate 168Set the default sampling rate for subsequent sampling mode 169PMCs specified on the command line. 170The default is to configure PMCs to sample the CPU's instruction 171pointer every 65536 events. 172.It Fl o Ar outputfile 173Send counter readings and textual representations of logged data 174to file 175.Ar outputfile . 176The default is to send output to 177.Pa stderr . 178.It Fl p Ar event-spec 179Allocate a process mode counting PMC measuring hardware events 180specified in 181.Ar event-spec . 182.It Fl s Ar event-spec 183Allocate a system mode counting PMC measuring hardware events 184specified in 185.Ar event-spec . 186.It Fl t Ar pid 187Attach all process mode PMCs allocated to the process with PID 188.Ar pid . 189The option is not allowed in conjunction with specifying a 190command using 191.Ar command . 192.It Fl w Ar secs 193Print the values of all counting mode PMCs every 194.Ar secs 195seconds. 196The argument 197.Ar secs 198may be a fractional value. 199The default interval is 5 seconds. 200.El 201.Pp 202If 203.Ar command 204is specified, it is executed using 205.Xr execvp 3 . 206.Sh EXAMPLES 207To perform system-wide statistical sampling on an AMD Athlon CPU with 208samples taken every 32768 instruction retirals and data being sampled 209to file 210.Pa sample.stat , 211use: 212.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions" 213.Pp 214To execute 215.Nm mozilla 216and measure the number of data cache misses suffered 217by it and its children every 12 seconds on an AMD Athlon, use: 218.Dl "pmcstat -d -w 12 -p k7-dc-misses mozilla" 219.Pp 220To collect a system-wide samples driven by processor instructions executed 221use: 222.Dl "pmcstat -S instructions -O /tmp/sample.out" 223.Pp 224To generate 225.Xr gprof 1 226compatible flat profiles from a sample file use: 227.Dl "pmcstat -R /tmp/sample.out -g" 228.Sh DIAGNOSTICS 229.Ex -std 230.Sh SEE ALSO 231.Xr gprof 1 , 232.Xr execvp 3 , 233.Xr pmc 3 , 234.Xr pmclog 3 , 235.Xr hwpmc 4 , 236.Xr pmccontrol 8 , 237.Xr sysctl 8 238.Sh HISTORY 239The 240.Nm 241utility first appeared in 242.Fx 6.0 . 243It is 244.Ud 245.Sh AUTHORS 246.An Joseph Koshy Aq jkoshy@FreeBSD.org 247