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.\"
| 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: stable/10/usr.sbin/pmcstat/pmcstat.8 288495 2015-10-02 14:11:44Z vangyzen $
| 26.\" $FreeBSD: stable/10/usr.sbin/pmcstat/pmcstat.8 294046 2016-01-14 22:02:21Z jtl $
|
27.\"
| 27.\"
|
28.Dd May 27, 2015
| 28.Dd November 18, 2015
|
29.Dt PMCSTAT 8
30.Os
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 F Ar pathname
40.Op Fl G Ar pathname
41.Op Fl M Ar mapfilename
42.Op Fl N
43.Op Fl O Ar logfilename
44.Op Fl P Ar event-spec
45.Op Fl R Ar logfilename
46.Op Fl S Ar event-spec
47.Op Fl T
48.Op Fl W
49.Op Fl a Ar pathname
50.Op Fl c Ar cpu-spec
51.Op Fl d
| 29.Dt PMCSTAT 8
30.Os
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 F Ar pathname
40.Op Fl G Ar pathname
41.Op Fl M Ar mapfilename
42.Op Fl N
43.Op Fl O Ar logfilename
44.Op Fl P Ar event-spec
45.Op Fl R Ar logfilename
46.Op Fl S Ar event-spec
47.Op Fl T
48.Op Fl W
49.Op Fl a Ar pathname
50.Op Fl c Ar cpu-spec
51.Op Fl d
|
| 52.Op Fl e
|
52.Op Fl f Ar pluginopt
53.Op Fl g
54.Op Fl k Ar kerneldir
55.Op Fl l Ar secs
56.Op Fl m Ar pathname
57.Op Fl n Ar rate
58.Op Fl o Ar outputfile
59.Op Fl p Ar event-spec
60.Op Fl q
61.Op Fl r Ar fsroot
62.Op Fl s Ar event-spec
63.Op Fl t Ar process-spec
64.Op Fl v
65.Op Fl w Ar secs
66.Op Fl z Ar graphdepth
67.Op Ar command Op Ar args
68.Sh DESCRIPTION
69The
70.Nm
71utility measures system performance using the facilities provided by
72.Xr hwpmc 4 .
73.Pp
74The
75.Nm
76utility can measure both hardware events seen by the system as a
77whole, and those seen when a specified set of processes are executing
78on the system's CPUs.
79If a specific set of processes is being targeted (for example,
80if the
81.Fl t Ar process-spec
82option is specified, or if a command line is specified using
83.Ar command ) ,
84then measurement occurs till
85.Ar command
86exits, or till all target processes specified by the
87.Fl t Ar process-spec
88options exit, or till the
89.Nm
90utility is interrupted by the user.
91If a specific set of processes is not targeted for measurement, then
92.Nm
93will perform system-wide measurements till interrupted by the
94user.
95.Pp
96A given invocation of
97.Nm
98can mix allocations of system-mode and process-mode PMCs, of both
99counting and sampling flavors.
100The values of all counting PMCs are printed in human readable form
101at regular intervals by
102.Nm .
103The output of sampling PMCs may be configured to go to a log file for
104subsequent offline analysis, or, at the expense of greater
105overhead, may be configured to be printed in text form on the fly.
106.Pp
107Hardware events to measure are specified to
108.Nm
109using event specifier strings
110.Ar event-spec .
111The syntax of these event specifiers is machine dependent and is
112documented in
113.Xr pmc 3 .
114.Pp
115A process-mode PMC may be configured to be inheritable by the target
116process' current and future children.
117.Sh OPTIONS
118The following options are available:
119.Bl -tag -width indent
120.It Fl C
121Toggle between showing cumulative or incremental counts for
122subsequent counting mode PMCs specified on the command line.
123The default is to show incremental counts.
124.It Fl D Ar pathname
125Create files with per-program samples in the directory named
126by
127.Ar pathname .
128The default is to create these files in the current directory.
129.It Fl E
130Toggle showing per-process counts at the time a tracked process
131exits for subsequent process-mode PMCs specified on the command line.
132This option is useful for mapping the performance characteristics of a
133complex pipeline of processes when used in conjunction with the
134.Fl d
135option.
136The default is to not to enable per-process tracking.
137.It Fl F Ar pathname
138Print calltree (Kcachegrind) information to file
139.Ar pathname .
140If argument
141.Ar pathname
142is a
143.Dq Li -
144this information is sent to the output file specified by the
145.Fl o
146option.
147.It Fl G Ar pathname
148Print callchain information to file
149.Ar pathname .
150If argument
151.Ar pathname
152is a
153.Dq Li -
154this information is sent to the output file specified by the
155.Fl o
156option.
157.It Fl M Ar mapfilename
158Write the mapping between executable objects encountered in the event
159log and the abbreviated pathnames used for
160.Xr gprof 1
161profiles to file
162.Ar mapfilename .
163If this option is not specified, mapping information is not written.
164Argument
165.Ar mapfilename
166may be a
167.Dq Li -
168in which case this mapping information is sent to the output
169file configured by the
170.Fl o
171option.
172.It Fl N
173Toggle capturing callchain information for subsequent sampling PMCs.
174The default is for sampling PMCs to capture callchain information.
175.It Fl O Ar logfilename
176Send logging output to file
177.Ar logfilename .
178If
179.Ar logfilename
180is of the form
181.Ar hostname Ns : Ns Ar port ,
182where
183.Ar hostname
184does not start with a
185.Ql \&.
186or a
187.Ql / ,
188then
189.Nm
190will open a network socket to host
191.Ar hostname
192on port
193.Ar port .
194.Pp
195If the
196.Fl O
197option is not specified and one of the logging options is requested,
198then
199.Nm
200will print a textual form of the logged events to the configured
201output file.
202.It Fl P Ar event-spec
203Allocate a process mode sampling PMC measuring hardware events
204specified in
205.Ar event-spec .
206.It Fl R Ar logfilename
207Perform offline analysis using sampling data in file
208.Ar logfilename .
209.It Fl S Ar event-spec
210Allocate a system mode sampling PMC measuring hardware events
211specified in
212.Ar event-spec .
213.It Fl T
214Use a top like mode for sampling PMCs. The following hotkeys
215can be used: 'c+a' switch to accumulative mode, 'c+d' switch
216to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
217PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
218is seen as a dot.
219.It Fl W
220Toggle logging the incremental counts seen by the threads of a
221tracked process each time they are scheduled on a CPU.
222This is an experimental feature intended to help analyse the
223dynamic behaviour of processes in the system.
224It may incur substantial overhead if enabled.
225The default is for this feature to be disabled.
226.It Fl a Ar pathname
227Perform a symbol and file:line lookup for each address in each
228callgraph and save the output to
229.Ar pathname .
230Unlike
231.Fl m
232that only resolves the first symbol in the graph, this resolves
233every node in the callgraph, or prints out addresses if no
234lookup information is available.
235This option requires the
236.Fl R
237option to read in samples that were previously collected and
238saved with the
239.Fl O
240option.
241.It Fl c Ar cpu-spec
242Set the cpus for subsequent system mode PMCs specified on the
243command line to
244.Ar cpu-spec .
245Argument
246.Ar cpu-spec
247is a comma separated list of CPU numbers, or the literal
248.Sq *
249denoting all available CPUs.
250The default is to allocate system mode PMCs on all available
251CPUs.
252.It Fl d
253Toggle between process mode PMCs measuring events for the target
254process' current and future children or only measuring events for
255the target process.
256The default is to measure events for the target process alone.
257(it has to be passed in the command line prior to
258.Fl p ,
259.Fl s ,
260.Fl P ,
261or
262.Fl S ) .
| 53.Op Fl f Ar pluginopt
54.Op Fl g
55.Op Fl k Ar kerneldir
56.Op Fl l Ar secs
57.Op Fl m Ar pathname
58.Op Fl n Ar rate
59.Op Fl o Ar outputfile
60.Op Fl p Ar event-spec
61.Op Fl q
62.Op Fl r Ar fsroot
63.Op Fl s Ar event-spec
64.Op Fl t Ar process-spec
65.Op Fl v
66.Op Fl w Ar secs
67.Op Fl z Ar graphdepth
68.Op Ar command Op Ar args
69.Sh DESCRIPTION
70The
71.Nm
72utility measures system performance using the facilities provided by
73.Xr hwpmc 4 .
74.Pp
75The
76.Nm
77utility can measure both hardware events seen by the system as a
78whole, and those seen when a specified set of processes are executing
79on the system's CPUs.
80If a specific set of processes is being targeted (for example,
81if the
82.Fl t Ar process-spec
83option is specified, or if a command line is specified using
84.Ar command ) ,
85then measurement occurs till
86.Ar command
87exits, or till all target processes specified by the
88.Fl t Ar process-spec
89options exit, or till the
90.Nm
91utility is interrupted by the user.
92If a specific set of processes is not targeted for measurement, then
93.Nm
94will perform system-wide measurements till interrupted by the
95user.
96.Pp
97A given invocation of
98.Nm
99can mix allocations of system-mode and process-mode PMCs, of both
100counting and sampling flavors.
101The values of all counting PMCs are printed in human readable form
102at regular intervals by
103.Nm .
104The output of sampling PMCs may be configured to go to a log file for
105subsequent offline analysis, or, at the expense of greater
106overhead, may be configured to be printed in text form on the fly.
107.Pp
108Hardware events to measure are specified to
109.Nm
110using event specifier strings
111.Ar event-spec .
112The syntax of these event specifiers is machine dependent and is
113documented in
114.Xr pmc 3 .
115.Pp
116A process-mode PMC may be configured to be inheritable by the target
117process' current and future children.
118.Sh OPTIONS
119The following options are available:
120.Bl -tag -width indent
121.It Fl C
122Toggle between showing cumulative or incremental counts for
123subsequent counting mode PMCs specified on the command line.
124The default is to show incremental counts.
125.It Fl D Ar pathname
126Create files with per-program samples in the directory named
127by
128.Ar pathname .
129The default is to create these files in the current directory.
130.It Fl E
131Toggle showing per-process counts at the time a tracked process
132exits for subsequent process-mode PMCs specified on the command line.
133This option is useful for mapping the performance characteristics of a
134complex pipeline of processes when used in conjunction with the
135.Fl d
136option.
137The default is to not to enable per-process tracking.
138.It Fl F Ar pathname
139Print calltree (Kcachegrind) information to file
140.Ar pathname .
141If argument
142.Ar pathname
143is a
144.Dq Li -
145this information is sent to the output file specified by the
146.Fl o
147option.
148.It Fl G Ar pathname
149Print callchain information to file
150.Ar pathname .
151If argument
152.Ar pathname
153is a
154.Dq Li -
155this information is sent to the output file specified by the
156.Fl o
157option.
158.It Fl M Ar mapfilename
159Write the mapping between executable objects encountered in the event
160log and the abbreviated pathnames used for
161.Xr gprof 1
162profiles to file
163.Ar mapfilename .
164If this option is not specified, mapping information is not written.
165Argument
166.Ar mapfilename
167may be a
168.Dq Li -
169in which case this mapping information is sent to the output
170file configured by the
171.Fl o
172option.
173.It Fl N
174Toggle capturing callchain information for subsequent sampling PMCs.
175The default is for sampling PMCs to capture callchain information.
176.It Fl O Ar logfilename
177Send logging output to file
178.Ar logfilename .
179If
180.Ar logfilename
181is of the form
182.Ar hostname Ns : Ns Ar port ,
183where
184.Ar hostname
185does not start with a
186.Ql \&.
187or a
188.Ql / ,
189then
190.Nm
191will open a network socket to host
192.Ar hostname
193on port
194.Ar port .
195.Pp
196If the
197.Fl O
198option is not specified and one of the logging options is requested,
199then
200.Nm
201will print a textual form of the logged events to the configured
202output file.
203.It Fl P Ar event-spec
204Allocate a process mode sampling PMC measuring hardware events
205specified in
206.Ar event-spec .
207.It Fl R Ar logfilename
208Perform offline analysis using sampling data in file
209.Ar logfilename .
210.It Fl S Ar event-spec
211Allocate a system mode sampling PMC measuring hardware events
212specified in
213.Ar event-spec .
214.It Fl T
215Use a top like mode for sampling PMCs. The following hotkeys
216can be used: 'c+a' switch to accumulative mode, 'c+d' switch
217to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
218PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
219is seen as a dot.
220.It Fl W
221Toggle logging the incremental counts seen by the threads of a
222tracked process each time they are scheduled on a CPU.
223This is an experimental feature intended to help analyse the
224dynamic behaviour of processes in the system.
225It may incur substantial overhead if enabled.
226The default is for this feature to be disabled.
227.It Fl a Ar pathname
228Perform a symbol and file:line lookup for each address in each
229callgraph and save the output to
230.Ar pathname .
231Unlike
232.Fl m
233that only resolves the first symbol in the graph, this resolves
234every node in the callgraph, or prints out addresses if no
235lookup information is available.
236This option requires the
237.Fl R
238option to read in samples that were previously collected and
239saved with the
240.Fl O
241option.
242.It Fl c Ar cpu-spec
243Set the cpus for subsequent system mode PMCs specified on the
244command line to
245.Ar cpu-spec .
246Argument
247.Ar cpu-spec
248is a comma separated list of CPU numbers, or the literal
249.Sq *
250denoting all available CPUs.
251The default is to allocate system mode PMCs on all available
252CPUs.
253.It Fl d
254Toggle between process mode PMCs measuring events for the target
255process' current and future children or only measuring events for
256the target process.
257The default is to measure events for the target process alone.
258(it has to be passed in the command line prior to
259.Fl p ,
260.Fl s ,
261.Fl P ,
262or
263.Fl S ) .
|
| 264.It Fl e
265Specify that the gprof profile files will use a wide history counter.
266These files are produced in a format compatible with
267.Xr gprof 1 .
268However, other tools that cannot fully parse a BSD-style
269gmon header might be unable to correctly parse these files.
|
263.It Fl f Ar pluginopt
264Pass option string to the active plugin.
265.br
266threshold=<float> do not display cost under specified value (Top).
267.br
268skiplink=0|1 replace node with cost under threshold by a dot (Top).
269.It Fl g
270Produce profiles in a format compatible with
271.Xr gprof 1 .
272A separate profile file is generated for each executable object
273encountered.
274Profile files are placed in sub-directories named by their PMC
275event name.
276.It Fl k Ar kerneldir
277Set the pathname of the kernel directory to argument
278.Ar kerneldir .
279This directory specifies where
280.Nm
281should look for the kernel and its modules.
282The default is to use the path of the running kernel obtained from the
283.Va kern.bootfile
284sysctl.
285.It Fl l Ar secs
286Set system-wide performance measurement duration for
287.Ar secs
288seconds.
289The argument
290.Ar secs
291may be a fractional value.
292.It Fl m Ar pathname
293Print the sampled PCs with the name, the start and ending addresses
294of the function within they live.
295The
296.Ar pathname
297argument is mandatory and indicates where the information will be stored.
298If argument
299.Ar pathname
300is a
301.Dq Li -
302this information is sent to the output file specified by the
303.Fl o
304option.
305This option requires the
306.Fl R
307option to read in samples that were previously collected and
308saved with the
309.Fl O
310option.
311.It Fl n Ar rate
312Set the default sampling rate for subsequent sampling mode
313PMCs specified on the command line.
314The default is to configure PMCs to sample the CPU's instruction
315pointer every 65536 events.
316.It Fl o Ar outputfile
317Send counter readings and textual representations of logged data
318to file
319.Ar outputfile .
320The default is to send output to
321.Pa stderr
322when collecting live data and to
323.Pa stdout
324when processing a pre-existing logfile.
325.It Fl p Ar event-spec
326Allocate a process mode counting PMC measuring hardware events
327specified in
328.Ar event-spec .
329.It Fl q
330Decrease verbosity.
331.It Fl r Ar fsroot
332Set the top of the filesystem hierarchy under which executables
333are located to argument
334.Ar fsroot .
335The default is
336.Pa / .
337.It Fl s Ar event-spec
338Allocate a system mode counting PMC measuring hardware events
339specified in
340.Ar event-spec .
341.It Fl t Ar process-spec
342Attach process mode PMCs to the processes named by argument
343.Ar process-spec .
344Argument
345.Ar process-spec
346may be a non-negative integer denoting a specific process id, or a
347regular expression for selecting processes based on their command names.
348.It Fl v
349Increase verbosity.
350.It Fl w Ar secs
351Print the values of all counting mode PMCs or sampling mode PMCs
352for top mode every
353.Ar secs
354seconds.
355The argument
356.Ar secs
357may be a fractional value.
358The default interval is 5 seconds.
359.It Fl z Ar graphdepth
360When printing system-wide callgraphs, limit callgraphs to the depth
361specified by argument
362.Ar graphdepth .
363.El
364.Pp
365If
366.Ar command
367is specified, it is executed using
368.Xr execvp 3 .
369.Sh EXAMPLES
370To perform system-wide statistical sampling on an AMD Athlon CPU with
371samples taken every 32768 instruction retirals and data being sampled
372to file
373.Pa sample.stat ,
374use:
375.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
376.Pp
377To execute
378.Nm firefox
379and measure the number of data cache misses suffered
380by it and its children every 12 seconds on an AMD Athlon, use:
381.Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
382.Pp
383To measure instructions retired for all processes named
384.Dq emacs
385use:
386.Dl "pmcstat -t '^emacs$' -p instructions"
387.Pp
388To measure instructions retired for processes named
389.Dq emacs
390for a period of 10 seconds use:
391.Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
392.Pp
393To count instruction tlb-misses on CPUs 0 and 2 on a Intel
394Pentium Pro/Pentium III SMP system use:
395.Dl "pmcstat -c 0,2 -s p6-itlb-miss"
396.Pp
397To collect profiling information for a specific process with pid 1234
398based on instruction cache misses seen by it use:
399.Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
400.Pp
401To perform system-wide sampling on all configured processors
402based on processor instructions retired use:
403.Dl "pmcstat -S instructions -O /tmp/sample.out"
404If callgraph capture is not desired use:
405.Dl "pmcstat -N -S instructions -O /tmp/sample.out"
406.Pp
407To send the generated event log to a remote machine use:
408.Dl "pmcstat -S instructions -O remotehost:port"
409On the remote machine, the sample log can be collected using
410.Xr nc 1 :
411.Dl "nc -l remotehost port > /tmp/sample.out"
412.Pp
413To generate
414.Xr gprof 1
415compatible profiles from a sample file use:
416.Dl "pmcstat -R /tmp/sample.out -g"
417.Pp
418To print a system-wide profile with callgraphs to file
419.Pa "foo.graph"
420use:
421.Dl "pmcstat -R /tmp/sample.out -G foo.graph"
422.Sh DIAGNOSTICS
423If option
424.Fl v
425is specified,
426.Nm
427may issue the following diagnostic messages:
428.Bl -diag
429.It "#callchain/dubious-frames"
430The number of callchain records that had an
431.Dq impossible
432value for a return address.
433.It "#exec handling errors"
434The number of
435.Xr exec 2
436events in the log file that named executables that could not be
437analyzed.
438.It "#exec/elf"
439The number of
440.Xr exec 2
441events that named ELF executables.
442.It "#exec/unknown"
443The number of
444.Xr exec 2
445events that named executables with unrecognized formats.
446.It "#samples/total"
447The total number of samples in the log file.
448.It "#samples/unclaimed"
449The number of samples that could not be correlated to a known
450executable object (i.e., to an executable, shared library, the
451kernel or the runtime loader).
452.It "#samples/unknown-object"
453The number of samples that were associated with an executable
454with an unrecognized object format.
455.El
456.Pp
457.Ex -std
458.Sh COMPATIBILITY
459Due to the limitations of the
460.Pa gmon.out
461file format,
462.Xr gprof 1
463compatible profiles generated by the
464.Fl g
465option do not contain information about calls that cross executable
466boundaries.
467The generated
468.Pa gmon.out
469files are also only meaningful for native executables.
470.Sh SEE ALSO
471.Xr gprof 1 ,
472.Xr nc 1 ,
473.Xr execvp 3 ,
474.Xr pmc 3 ,
475.Xr pmclog 3 ,
476.Xr hwpmc 4 ,
477.Xr pmccontrol 8 ,
478.Xr sysctl 8
479.Sh HISTORY
480The
481.Nm
482utility first appeared in
483.Fx 6.0 .
484It is
485.Ud
486.Sh AUTHORS
487.An Joseph Koshy Aq jkoshy@FreeBSD.org
488.Sh BUGS
489The
490.Nm
491utility cannot yet analyse
492.Xr hwpmc 4
493logs generated by non-native architectures.
| 270.It Fl f Ar pluginopt
271Pass option string to the active plugin.
272.br
273threshold=<float> do not display cost under specified value (Top).
274.br
275skiplink=0|1 replace node with cost under threshold by a dot (Top).
276.It Fl g
277Produce profiles in a format compatible with
278.Xr gprof 1 .
279A separate profile file is generated for each executable object
280encountered.
281Profile files are placed in sub-directories named by their PMC
282event name.
283.It Fl k Ar kerneldir
284Set the pathname of the kernel directory to argument
285.Ar kerneldir .
286This directory specifies where
287.Nm
288should look for the kernel and its modules.
289The default is to use the path of the running kernel obtained from the
290.Va kern.bootfile
291sysctl.
292.It Fl l Ar secs
293Set system-wide performance measurement duration for
294.Ar secs
295seconds.
296The argument
297.Ar secs
298may be a fractional value.
299.It Fl m Ar pathname
300Print the sampled PCs with the name, the start and ending addresses
301of the function within they live.
302The
303.Ar pathname
304argument is mandatory and indicates where the information will be stored.
305If argument
306.Ar pathname
307is a
308.Dq Li -
309this information is sent to the output file specified by the
310.Fl o
311option.
312This option requires the
313.Fl R
314option to read in samples that were previously collected and
315saved with the
316.Fl O
317option.
318.It Fl n Ar rate
319Set the default sampling rate for subsequent sampling mode
320PMCs specified on the command line.
321The default is to configure PMCs to sample the CPU's instruction
322pointer every 65536 events.
323.It Fl o Ar outputfile
324Send counter readings and textual representations of logged data
325to file
326.Ar outputfile .
327The default is to send output to
328.Pa stderr
329when collecting live data and to
330.Pa stdout
331when processing a pre-existing logfile.
332.It Fl p Ar event-spec
333Allocate a process mode counting PMC measuring hardware events
334specified in
335.Ar event-spec .
336.It Fl q
337Decrease verbosity.
338.It Fl r Ar fsroot
339Set the top of the filesystem hierarchy under which executables
340are located to argument
341.Ar fsroot .
342The default is
343.Pa / .
344.It Fl s Ar event-spec
345Allocate a system mode counting PMC measuring hardware events
346specified in
347.Ar event-spec .
348.It Fl t Ar process-spec
349Attach process mode PMCs to the processes named by argument
350.Ar process-spec .
351Argument
352.Ar process-spec
353may be a non-negative integer denoting a specific process id, or a
354regular expression for selecting processes based on their command names.
355.It Fl v
356Increase verbosity.
357.It Fl w Ar secs
358Print the values of all counting mode PMCs or sampling mode PMCs
359for top mode every
360.Ar secs
361seconds.
362The argument
363.Ar secs
364may be a fractional value.
365The default interval is 5 seconds.
366.It Fl z Ar graphdepth
367When printing system-wide callgraphs, limit callgraphs to the depth
368specified by argument
369.Ar graphdepth .
370.El
371.Pp
372If
373.Ar command
374is specified, it is executed using
375.Xr execvp 3 .
376.Sh EXAMPLES
377To perform system-wide statistical sampling on an AMD Athlon CPU with
378samples taken every 32768 instruction retirals and data being sampled
379to file
380.Pa sample.stat ,
381use:
382.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
383.Pp
384To execute
385.Nm firefox
386and measure the number of data cache misses suffered
387by it and its children every 12 seconds on an AMD Athlon, use:
388.Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
389.Pp
390To measure instructions retired for all processes named
391.Dq emacs
392use:
393.Dl "pmcstat -t '^emacs$' -p instructions"
394.Pp
395To measure instructions retired for processes named
396.Dq emacs
397for a period of 10 seconds use:
398.Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
399.Pp
400To count instruction tlb-misses on CPUs 0 and 2 on a Intel
401Pentium Pro/Pentium III SMP system use:
402.Dl "pmcstat -c 0,2 -s p6-itlb-miss"
403.Pp
404To collect profiling information for a specific process with pid 1234
405based on instruction cache misses seen by it use:
406.Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
407.Pp
408To perform system-wide sampling on all configured processors
409based on processor instructions retired use:
410.Dl "pmcstat -S instructions -O /tmp/sample.out"
411If callgraph capture is not desired use:
412.Dl "pmcstat -N -S instructions -O /tmp/sample.out"
413.Pp
414To send the generated event log to a remote machine use:
415.Dl "pmcstat -S instructions -O remotehost:port"
416On the remote machine, the sample log can be collected using
417.Xr nc 1 :
418.Dl "nc -l remotehost port > /tmp/sample.out"
419.Pp
420To generate
421.Xr gprof 1
422compatible profiles from a sample file use:
423.Dl "pmcstat -R /tmp/sample.out -g"
424.Pp
425To print a system-wide profile with callgraphs to file
426.Pa "foo.graph"
427use:
428.Dl "pmcstat -R /tmp/sample.out -G foo.graph"
429.Sh DIAGNOSTICS
430If option
431.Fl v
432is specified,
433.Nm
434may issue the following diagnostic messages:
435.Bl -diag
436.It "#callchain/dubious-frames"
437The number of callchain records that had an
438.Dq impossible
439value for a return address.
440.It "#exec handling errors"
441The number of
442.Xr exec 2
443events in the log file that named executables that could not be
444analyzed.
445.It "#exec/elf"
446The number of
447.Xr exec 2
448events that named ELF executables.
449.It "#exec/unknown"
450The number of
451.Xr exec 2
452events that named executables with unrecognized formats.
453.It "#samples/total"
454The total number of samples in the log file.
455.It "#samples/unclaimed"
456The number of samples that could not be correlated to a known
457executable object (i.e., to an executable, shared library, the
458kernel or the runtime loader).
459.It "#samples/unknown-object"
460The number of samples that were associated with an executable
461with an unrecognized object format.
462.El
463.Pp
464.Ex -std
465.Sh COMPATIBILITY
466Due to the limitations of the
467.Pa gmon.out
468file format,
469.Xr gprof 1
470compatible profiles generated by the
471.Fl g
472option do not contain information about calls that cross executable
473boundaries.
474The generated
475.Pa gmon.out
476files are also only meaningful for native executables.
477.Sh SEE ALSO
478.Xr gprof 1 ,
479.Xr nc 1 ,
480.Xr execvp 3 ,
481.Xr pmc 3 ,
482.Xr pmclog 3 ,
483.Xr hwpmc 4 ,
484.Xr pmccontrol 8 ,
485.Xr sysctl 8
486.Sh HISTORY
487The
488.Nm
489utility first appeared in
490.Fx 6.0 .
491It is
492.Ud
493.Sh AUTHORS
494.An Joseph Koshy Aq jkoshy@FreeBSD.org
495.Sh BUGS
496The
497.Nm
498utility cannot yet analyse
499.Xr hwpmc 4
500logs generated by non-native architectures.
|