| pmcstat.8 (169069) | pmcstat.8 (174396) |
|---|---|
| 1.\" Copyright (c) 2003-2007 Joseph Koshy. All rights reserved. | 1.\" Copyright (c) 2003-2007 Joseph Koshy 2.\" Copyright (c) 2007 The FreeBSD Foundation 3.\" 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 --- 6 unchanged lines hidden (view full) --- 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.\" | 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 --- 6 unchanged lines hidden (view full) --- 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.\" |
| 24.\" $FreeBSD: head/usr.sbin/pmcstat/pmcstat.8 169069 2007-04-27 12:09:31Z jkoshy $ | 26.\" $FreeBSD: head/usr.sbin/pmcstat/pmcstat.8 174396 2007-12-07 08:26:21Z jkoshy $ |
| 25.\" 26.Dd April 23, 2007 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 | 27.\" 28.Dd April 23, 2007 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 |
|
| 37.Op Fl M Ar mapfilename | 40.Op Fl M Ar mapfilename |
| 41.Op Fl N |
|
| 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-spec 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 process-spec 54.Op Fl v 55.Op Fl w Ar secs | 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 n Ar rate 52.Op Fl o Ar outputfile 53.Op Fl p Ar event-spec 54.Op Fl q 55.Op Fl r Ar fsroot 56.Op Fl s Ar event-spec 57.Op Fl t Ar process-spec 58.Op Fl v 59.Op Fl w Ar secs |
| 60.Op Fl z Ar graphdepth |
|
| 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 --- 54 unchanged lines hidden (view full) --- 118.It Fl E 119Toggle showing per-process counts at the time a tracked process 120exits for subsequent process-mode PMCs specified on the command line. 121This option is useful for mapping the performance characteristics of a 122complex pipeline of processes when used in conjunction with the 123.Fl d 124option. 125The default is to not to enable per-process tracking. | 61.Op Ar command Op Ar args 62.Sh DESCRIPTION 63The 64.Nm 65utility measures system performance using the facilities provided by 66.Xr hwpmc 4 . 67.Pp 68The --- 54 unchanged lines hidden (view full) --- 123.It Fl E 124Toggle showing per-process counts at the time a tracked process 125exits for subsequent process-mode PMCs specified on the command line. 126This option is useful for mapping the performance characteristics of a 127complex pipeline of processes when used in conjunction with the 128.Fl d 129option. 130The default is to not to enable per-process tracking. |
| 131.It Fl G Ar pathname 132Print callchain information to file 133.Ar pathname . 134If argument 135.Ar pathname 136is a 137.Dq Li - 138this information is sent to the output file specified by the 139.Fl o 140option. |
|
| 126.It Fl M Ar mapfilename 127Write the mapping between executable objects encountered in the event 128log and the abbreviated pathnames used for 129.Xr gprof 1 130profiles to file 131.Ar mapfilename . 132If this option is not specified, mapping information is not written. 133Argument 134.Ar mapfilename 135may be a 136.Dq Li - 137in which case this mapping information is sent to the output 138file configured by the 139.Fl o 140option. | 141.It Fl M Ar mapfilename 142Write the mapping between executable objects encountered in the event 143log and the abbreviated pathnames used for 144.Xr gprof 1 145profiles to file 146.Ar mapfilename . 147If this option is not specified, mapping information is not written. 148Argument 149.Ar mapfilename 150may be a 151.Dq Li - 152in which case this mapping information is sent to the output 153file configured by the 154.Fl o 155option. |
| 156.It Fl N 157Toggle capturing callchain information for subsequent sampling PMCs. 158The default is for sampling PMCs to capture callchain information. |
|
| 141.It Fl O Ar logfilename 142Send logging output to file 143.Ar logfilename . 144If 145.Ar logfilename 146is of the form 147.Ar hostname Ns : Ns Ar port , 148where --- 38 unchanged lines hidden (view full) --- 187Set the cpus for subsequent system mode PMCs specified on the 188command line to 189.Ar cpu-spec . 190Argument 191.Ar cpu-spec 192is a comma separated list of CPU numbers, or the literal 193.Sq * 194denoting all CPUs. | 159.It Fl O Ar logfilename 160Send logging output to file 161.Ar logfilename . 162If 163.Ar logfilename 164is of the form 165.Ar hostname Ns : Ns Ar port , 166where --- 38 unchanged lines hidden (view full) --- 205Set the cpus for subsequent system mode PMCs specified on the 206command line to 207.Ar cpu-spec . 208Argument 209.Ar cpu-spec 210is a comma separated list of CPU numbers, or the literal 211.Sq * 212denoting all CPUs. |
| 195The default is to allocate system mode PMCs on all CPUs. | 213The default is to allocate system mode PMCs on all active CPUs in 214the system. |
| 196.It Fl d 197Toggle between process mode PMCs measuring events for the target 198process' current and future children or only measuring events for 199the target process. 200The default is to measure events for the target process alone. 201.It Fl g | 215.It Fl d 216Toggle between process mode PMCs measuring events for the target 217process' current and future children or only measuring events for 218the target process. 219The default is to measure events for the target process alone. 220.It Fl g |
| 202Produce flat execution profiles in a format compatible with | 221Produce profiles in a format compatible with |
| 203.Xr gprof 1 . 204A separate profile file is generated for each executable object 205encountered. 206Profile files are placed in sub-directories named by their PMC 207event name. 208.It Fl k Ar kerneldir 209Set the pathname of the kernel directory to argument 210.Ar kerneldir . --- 7 unchanged lines hidden (view full) --- 218PMCs specified on the command line. 219The default is to configure PMCs to sample the CPU's instruction 220pointer every 65536 events. 221.It Fl o Ar outputfile 222Send counter readings and textual representations of logged data 223to file 224.Ar outputfile . 225The default is to send output to | 222.Xr gprof 1 . 223A separate profile file is generated for each executable object 224encountered. 225Profile files are placed in sub-directories named by their PMC 226event name. 227.It Fl k Ar kerneldir 228Set the pathname of the kernel directory to argument 229.Ar kerneldir . --- 7 unchanged lines hidden (view full) --- 237PMCs specified on the command line. 238The default is to configure PMCs to sample the CPU's instruction 239pointer every 65536 events. 240.It Fl o Ar outputfile 241Send counter readings and textual representations of logged data 242to file 243.Ar outputfile . 244The default is to send output to |
| 226.Pa stderr . | 245.Pa stderr 246when collecting live data and to 247.Pa stdout 248when processing a pre-existing logfile. |
| 227.It Fl p Ar event-spec 228Allocate a process mode counting PMC measuring hardware events 229specified in 230.Ar event-spec . 231.It Fl q 232Decrease verbosity. 233.It Fl r Ar fsroot 234Set the top of the filesystem hierarchy under which executables --- 17 unchanged lines hidden (view full) --- 252.It Fl w Ar secs 253Print the values of all counting mode PMCs every 254.Ar secs 255seconds. 256The argument 257.Ar secs 258may be a fractional value. 259The default interval is 5 seconds. | 249.It Fl p Ar event-spec 250Allocate a process mode counting PMC measuring hardware events 251specified in 252.Ar event-spec . 253.It Fl q 254Decrease verbosity. 255.It Fl r Ar fsroot 256Set the top of the filesystem hierarchy under which executables --- 17 unchanged lines hidden (view full) --- 274.It Fl w Ar secs 275Print the values of all counting mode PMCs every 276.Ar secs 277seconds. 278The argument 279.Ar secs 280may be a fractional value. 281The default interval is 5 seconds. |
| 282.It Fl z Ar graphdepth 283When printing system-wide callgraphs, limit callgraphs to the depth 284specified by argument 285.Ar graphdepth . |
|
| 260.El 261.Pp 262If 263.Ar command 264is specified, it is executed using 265.Xr execvp 3 . 266.Sh EXAMPLES 267To perform system-wide statistical sampling on an AMD Athlon CPU with --- 13 unchanged lines hidden (view full) --- 281.Dq emacs 282use: 283.Dl "pmcstat -t '^emacs$' -p instructions" 284.Pp 285To count instruction tlb-misses on CPUs 0 and 2 on a Intel 286Pentium Pro/Pentium III SMP system use: 287.Dl "pmcstat -c 0,2 -s p6-itlb-miss" 288.Pp | 286.El 287.Pp 288If 289.Ar command 290is specified, it is executed using 291.Xr execvp 3 . 292.Sh EXAMPLES 293To perform system-wide statistical sampling on an AMD Athlon CPU with --- 13 unchanged lines hidden (view full) --- 307.Dq emacs 308use: 309.Dl "pmcstat -t '^emacs$' -p instructions" 310.Pp 311To count instruction tlb-misses on CPUs 0 and 2 on a Intel 312Pentium Pro/Pentium III SMP system use: 313.Dl "pmcstat -c 0,2 -s p6-itlb-miss" 314.Pp |
| 315To collect profiling information for a specific process with pid 1234 316based on instruction cache misses seen by it use: 317.Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out" 318.Pp |
|
| 289To perform system-wide sampling on all configured processors 290based on processor instructions retired use: 291.Dl "pmcstat -S instructions -O /tmp/sample.out" | 319To perform system-wide sampling on all configured processors 320based on processor instructions retired use: 321.Dl "pmcstat -S instructions -O /tmp/sample.out" |
| 322If callgraph capture is not desired use: 323.Dl "pmcstat -N -S instructions -O /tmp/sample.out" |
|
| 292.Pp 293To send the generated event log to a remote machine use: 294.Dl "pmcstat -S instructions -O remotehost:port" 295On the remote machine, the sample log can be collected using 296.Xr nc 1 : 297.Dl "nc -l remotehost port > /tmp/sample.out" 298.Pp 299To generate 300.Xr gprof 1 | 324.Pp 325To send the generated event log to a remote machine use: 326.Dl "pmcstat -S instructions -O remotehost:port" 327On the remote machine, the sample log can be collected using 328.Xr nc 1 : 329.Dl "nc -l remotehost port > /tmp/sample.out" 330.Pp 331To generate 332.Xr gprof 1 |
| 301compatible flat profiles from a sample file use: | 333compatible profiles from a sample file use: |
| 302.Dl "pmcstat -R /tmp/sample.out -g" | 334.Dl "pmcstat -R /tmp/sample.out -g" |
| 335.Pp 336To print a system-wide profile with callgraphs to file 337.Pa "foo.graph" 338use: 339.Dl "pmcstat -R /tmp/sample.out -G foo.graph" |
|
| 303.Sh DIAGNOSTICS 304.Ex -std | 340.Sh DIAGNOSTICS 341.Ex -std |
| 342.Sh COMPATIBILITY 343Due to the limitations of the 344.Pa gmon.out 345file format, 346.Xr gprof 1 347compatible profiles generated by the 348.Fl g 349option do not contain information about calls that cross executable 350boundaries. 351The generated 352.Pa gmon.out 353files are also only meaningful for native executables. |
|
| 305.Sh SEE ALSO 306.Xr gprof 1 , 307.Xr nc 1 , 308.Xr execvp 3 , 309.Xr pmc 3 , 310.Xr pmclog 3 , 311.Xr hwpmc 4 , 312.Xr pmccontrol 8 , --- 16 unchanged lines hidden --- | 354.Sh SEE ALSO 355.Xr gprof 1 , 356.Xr nc 1 , 357.Xr execvp 3 , 358.Xr pmc 3 , 359.Xr pmclog 3 , 360.Xr hwpmc 4 , 361.Xr pmccontrol 8 , --- 16 unchanged lines hidden --- |