1.\" Copyright (c) 2003-2008 Joseph Koshy 2.\" Copyright (c) 2007 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" This software is provided by Joseph Koshy ``as is'' and 15.\" any express or implied warranties, including, but not limited to, the 16.\" implied warranties of merchantability and fitness for a particular purpose 17.\" are disclaimed. in no event shall Joseph Koshy be liable 18.\" for any direct, indirect, incidental, special, exemplary, or consequential 19.\" damages (including, but not limited to, procurement of substitute goods 20.\" or services; loss of use, data, or profits; or business interruption) 21.\" however caused and on any theory of liability, whether in contract, strict 22.\" liability, or tort (including negligence or otherwise) arising in any way 23.\" out of the use of this software, even if advised of the possibility of 24.\" such damage. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd September 19, 2008 29.Os 30.Dt PMCSTAT 8 31.Sh NAME 32.Nm pmcstat 33.Nd "performance measurement with performance monitoring hardware" 34.Sh SYNOPSIS 35.Nm 36.Op Fl C 37.Op Fl D Ar pathname 38.Op Fl E 39.Op Fl G Ar pathname 40.Op Fl M Ar mapfilename 41.Op Fl N 42.Op Fl O Ar logfilename 43.Op Fl P Ar event-spec 44.Op Fl R Ar logfilename 45.Op Fl S Ar event-spec 46.Op Fl W 47.Op Fl c Ar cpu-spec 48.Op Fl d 49.Op Fl g 50.Op Fl k Ar kerneldir 51.Op Fl m Ar pathname 52.Op Fl n Ar rate 53.Op Fl o Ar outputfile 54.Op Fl p Ar event-spec 55.Op Fl q 56.Op Fl r Ar fsroot 57.Op Fl s Ar event-spec 58.Op Fl t Ar process-spec 59.Op Fl v 60.Op Fl w Ar secs 61.Op Fl z Ar graphdepth 62.Op Ar command Op Ar args 63.Sh DESCRIPTION 64The 65.Nm 66utility measures system performance using the facilities provided by 67.Xr hwpmc 4 . 68.Pp 69The 70.Nm 71utility can measure both hardware events seen by the system as a 72whole, and those seen when a specified set of processes are executing 73on the system's CPUs. 74If a specific set of processes is being targeted (for example, 75if the 76.Fl t Ar process-spec 77option is specified, or if a command line is specified using 78.Ar command ) , 79then measurement occurs till 80.Ar command 81exits, or till all target processes specified by the 82.Fl t Ar process-spec 83options exit, or till the 84.Nm 85utility is interrupted by the user. 86If a specific set of processes is not targeted for measurement, then 87.Nm 88will perform system-wide measurements till interrupted by the 89user. 90.Pp 91A given invocation of 92.Nm 93can mix allocations of system-mode and process-mode PMCs, of both 94counting and sampling flavors. 95The values of all counting PMCs are printed in human readable form 96at regular intervals by 97.Nm . 98The output of sampling PMCs may be configured to go to a log file for 99subsequent offline analysis, or, at the expense of greater 100overhead, may be configured to be printed in text form on the fly. 101.Pp 102Hardware events to measure are specified to 103.Nm 104using event specifier strings 105.Ar event-spec . 106The syntax of these event specifiers is machine dependent and is 107documented in 108.Xr pmc 3 . 109.Pp 110A process-mode PMC may be configured to be inheritable by the target 111process' current and future children. 112.Sh OPTIONS 113The following options are available: 114.Bl -tag -width indent 115.It Fl C 116Toggle between showing cumulative or incremental counts for 117subsequent counting mode PMCs specified on the command line. 118The default is to show incremental counts. 119.It Fl D Ar pathname 120Create files with per-program samples in the directory named 121by 122.Ar pathname . 123The default is to create these files in the current directory. 124.It Fl E 125Toggle showing per-process counts at the time a tracked process 126exits for subsequent process-mode PMCs specified on the command line. 127This option is useful for mapping the performance characteristics of a 128complex pipeline of processes when used in conjunction with the 129.Fl d 130option. 131The default is to not to enable per-process tracking. 132.It Fl G Ar pathname 133Print callchain information to file 134.Ar pathname . 135If argument 136.Ar pathname 137is a 138.Dq Li - 139this information is sent to the output file specified by the 140.Fl o 141option. 142.It Fl M Ar mapfilename 143Write the mapping between executable objects encountered in the event 144log and the abbreviated pathnames used for 145.Xr gprof 1 146profiles to file 147.Ar mapfilename . 148If this option is not specified, mapping information is not written. 149Argument 150.Ar mapfilename 151may be a 152.Dq Li - 153in which case this mapping information is sent to the output 154file configured by the 155.Fl o 156option. 157.It Fl N 158Toggle capturing callchain information for subsequent sampling PMCs. 159The default is for sampling PMCs to capture callchain information. 160.It Fl O Ar logfilename 161Send logging output to file 162.Ar logfilename . 163If 164.Ar logfilename 165is of the form 166.Ar hostname Ns : Ns Ar port , 167where 168.Ar hostname 169does not start with a 170.Ql \&. 171or a 172.Ql / , 173then 174.Nm 175will open a network socket to host 176.Ar hostname 177on port 178.Ar port . 179.Pp 180If the 181.Fl O 182option is not specified and one of the logging options is requested, 183then 184.Nm 185will print a textual form of the logged events to the configured 186output file. 187.It Fl P Ar event-spec 188Allocate a process mode sampling PMC measuring hardware events 189specified in 190.Ar event-spec . 191.It Fl R Ar logfilename 192Perform offline analysis using sampling data in file 193.Ar logfilename . 194.It Fl S Ar event-spec 195Allocate a system mode sampling PMC measuring hardware events 196specified in 197.Ar event-spec . 198.It Fl W 199Toggle logging the incremental counts seen by the threads of a 200tracked process each time they are scheduled on a CPU. 201This is an experimental feature intended to help analyse the 202dynamic behaviour of processes in the system. 203It may incur substantial overhead if enabled. 204The default is for this feature to be disabled. 205.It Fl c Ar cpu-spec 206Set the cpus for subsequent system mode PMCs specified on the 207command line to 208.Ar cpu-spec . 209Argument 210.Ar cpu-spec 211is a comma separated list of CPU numbers, or the literal 212.Sq * 213denoting all unhalted CPUs. 214The default is to allocate system mode PMCs on all unhalted 215CPUs. 216.It Fl d 217Toggle between process mode PMCs measuring events for the target 218process' current and future children or only measuring events for 219the target process. 220The default is to measure events for the target process alone. 221.It Fl g 222Produce profiles in a format compatible with 223.Xr gprof 1 . 224A separate profile file is generated for each executable object 225encountered. 226Profile files are placed in sub-directories named by their PMC 227event name. 228.It Fl k Ar kerneldir 229Set the pathname of the kernel directory to argument 230.Ar kerneldir . 231This directory specifies where 232.Nm 233should look for the kernel and its modules. 234The default is 235.Pa /boot/kernel . 236.It Fl m Ar pathname 237Print the sampled PCs with the name, the start and ending addresses 238of the function within they live. 239The 240.Ar pathname 241argument is mandatory and indicates where informations will be stored. 242If argument 243.Ar pathname 244is a 245.Dq Li - 246this information is sent to the output file specified by the 247.Fl o 248option. 249.It Fl n Ar rate 250Set the default sampling rate for subsequent sampling mode 251PMCs specified on the command line. 252The default is to configure PMCs to sample the CPU's instruction 253pointer every 65536 events. 254.It Fl o Ar outputfile 255Send counter readings and textual representations of logged data 256to file 257.Ar outputfile . 258The default is to send output to 259.Pa stderr 260when collecting live data and to 261.Pa stdout 262when processing a pre-existing logfile. 263.It Fl p Ar event-spec 264Allocate a process mode counting PMC measuring hardware events 265specified in 266.Ar event-spec . 267.It Fl q 268Decrease verbosity. 269.It Fl r Ar fsroot 270Set the top of the filesystem hierarchy under which executables 271are located to argument 272.Ar fsroot . 273The default is 274.Pa / . 275.It Fl s Ar event-spec 276Allocate a system mode counting PMC measuring hardware events 277specified in 278.Ar event-spec . 279.It Fl t Ar process-spec 280Attach process mode PMCs to the processes named by argument 281.Ar process-spec . 282Argument 283.Ar process-spec 284may be a non-negative integer denoting a specific process id, or a 285regular expression for selecting processes based on their command names. 286.It Fl v 287Increase verbosity. 288.It Fl w Ar secs 289Print the values of all counting mode PMCs every 290.Ar secs 291seconds. 292The argument 293.Ar secs 294may be a fractional value. 295The default interval is 5 seconds. 296.It Fl z Ar graphdepth 297When printing system-wide callgraphs, limit callgraphs to the depth 298specified by argument 299.Ar graphdepth . 300.El 301.Pp 302If 303.Ar command 304is specified, it is executed using 305.Xr execvp 3 . 306.Sh EXAMPLES 307To perform system-wide statistical sampling on an AMD Athlon CPU with 308samples taken every 32768 instruction retirals and data being sampled 309to file 310.Pa sample.stat , 311use: 312.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions" 313.Pp 314To execute 315.Nm mozilla 316and measure the number of data cache misses suffered 317by it and its children every 12 seconds on an AMD Athlon, use: 318.Dl "pmcstat -d -w 12 -p k7-dc-misses mozilla" 319.Pp 320To measure instructions retired for all processes named 321.Dq emacs 322use: 323.Dl "pmcstat -t '^emacs$' -p instructions" 324.Pp 325To measure instructions retired for processes named 326.Dq emacs 327for a period of 10 seconds use: 328.Dl "pmcstat -t '^emacs$' -p instructions sleep 10" 329.Pp 330To count instruction tlb-misses on CPUs 0 and 2 on a Intel 331Pentium Pro/Pentium III SMP system use: 332.Dl "pmcstat -c 0,2 -s p6-itlb-miss" 333.Pp 334To collect profiling information for a specific process with pid 1234 335based on instruction cache misses seen by it use: 336.Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out" 337.Pp 338To perform system-wide sampling on all configured processors 339based on processor instructions retired use: 340.Dl "pmcstat -S instructions -O /tmp/sample.out" 341If callgraph capture is not desired use: 342.Dl "pmcstat -N -S instructions -O /tmp/sample.out" 343.Pp 344To send the generated event log to a remote machine use: 345.Dl "pmcstat -S instructions -O remotehost:port" 346On the remote machine, the sample log can be collected using 347.Xr nc 1 : 348.Dl "nc -l remotehost port > /tmp/sample.out" 349.Pp 350To generate 351.Xr gprof 1 352compatible profiles from a sample file use: 353.Dl "pmcstat -R /tmp/sample.out -g" 354.Pp 355To print a system-wide profile with callgraphs to file 356.Pa "foo.graph" 357use: 358.Dl "pmcstat -R /tmp/sample.out -G foo.graph" 359.Sh DIAGNOSTICS 360If option 361.Fl v 362is specified, 363.Nm 364may issue the following diagnostic messages: 365.Bl -diag -width indent 366.It "#callchain/dubious-frames" 367The number of callchain records that had an 368.Dq impossible 369value for a return address. 370.It "#exec handling errors" 371The number of 372.Xr exec 2 373events in the log file that named executables that could not be 374analyzed. 375.It "#exec/elf" 376The number of 377.Xr exec 2 378events that named ELF executables. 379.It "#exec/unknown" 380The number of 381.Xr exec 2 382events that named executables with unrecognized formats. 383.It "#samples/total" 384The total number of samples in the log file. 385.It "#samples/unclaimed" 386The number of samples that could not be correlated to a known 387executable object (i.e., to an executable, shared library, the 388kernel or the runtime loader). 389.It "#samples/unknown-object" 390The number of samples that were associated with an executable 391with an unrecognized object format. 392.El 393.Pp 394.Ex -std 395.Sh COMPATIBILITY 396Due to the limitations of the 397.Pa gmon.out 398file format, 399.Xr gprof 1 400compatible profiles generated by the 401.Fl g 402option do not contain information about calls that cross executable 403boundaries. 404The generated 405.Pa gmon.out 406files are also only meaningful for native executables. 407.Sh SEE ALSO 408.Xr gprof 1 , 409.Xr nc 1 , 410.Xr execvp 3 , 411.Xr pmc 3 , 412.Xr pmclog 3 , 413.Xr hwpmc 4 , 414.Xr pmccontrol 8 , 415.Xr sysctl 8 416.Sh HISTORY 417The 418.Nm 419utility first appeared in 420.Fx 6.0 . 421It is 422.Ud 423.Sh AUTHORS 424.An Joseph Koshy Aq jkoshy@FreeBSD.org 425.Sh BUGS 426The 427.Nm 428utility cannot yet analyse 429.Xr hwpmc 4 430logs generated by non-native architectures. 431