diff options
author | jkoshy <jkoshy@FreeBSD.org> | 2007-12-07 08:26:21 +0000 |
---|---|---|
committer | jkoshy <jkoshy@FreeBSD.org> | 2007-12-07 08:26:21 +0000 |
commit | 2aef7957ec96361c7cf73dee65ee4512b39e1de5 (patch) | |
tree | 6048997529363b686719d6493260bacb261191c8 /usr.sbin/pmcstat/pmcstat.8 | |
parent | 72c27d71d82569aec187c30f6ff208631abc02f4 (diff) | |
download | FreeBSD-src-2aef7957ec96361c7cf73dee65ee4512b39e1de5.zip FreeBSD-src-2aef7957ec96361c7cf73dee65ee4512b39e1de5.tar.gz |
Introduce pmcstat(8) changes for summarizing hwpmc(4) callchain records in
in textual form and in gmon.out format.
Update manual page.
Sponsored by: FreeBSD Foundation and Google Inc.
Diffstat (limited to 'usr.sbin/pmcstat/pmcstat.8')
-rw-r--r-- | usr.sbin/pmcstat/pmcstat.8 | 59 |
1 files changed, 54 insertions, 5 deletions
diff --git a/usr.sbin/pmcstat/pmcstat.8 b/usr.sbin/pmcstat/pmcstat.8 index 951dba6..16cd876 100644 --- a/usr.sbin/pmcstat/pmcstat.8 +++ b/usr.sbin/pmcstat/pmcstat.8 @@ -1,4 +1,6 @@ -.\" Copyright (c) 2003-2007 Joseph Koshy. All rights reserved. +.\" Copyright (c) 2003-2007 Joseph Koshy +.\" Copyright (c) 2007 The FreeBSD Foundation +.\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -34,7 +36,9 @@ .Op Fl C .Op Fl D Ar pathname .Op Fl E +.Op Fl G Ar pathname .Op Fl M Ar mapfilename +.Op Fl N .Op Fl O Ar logfilename .Op Fl P Ar event-spec .Op Fl R Ar logfilename @@ -53,6 +57,7 @@ .Op Fl t Ar process-spec .Op Fl v .Op Fl w Ar secs +.Op Fl z Ar graphdepth .Op Ar command Op Ar args .Sh DESCRIPTION The @@ -123,6 +128,16 @@ complex pipeline of processes when used in conjunction with the .Fl d option. The default is to not to enable per-process tracking. +.It Fl G Ar pathname +Print callchain information to file +.Ar pathname . +If argument +.Ar pathname +is a +.Dq Li - +this information is sent to the output file specified by the +.Fl o +option. .It Fl M Ar mapfilename Write the mapping between executable objects encountered in the event log and the abbreviated pathnames used for @@ -138,6 +153,9 @@ in which case this mapping information is sent to the output file configured by the .Fl o option. +.It Fl N +Toggle capturing callchain information for subsequent sampling PMCs. +The default is for sampling PMCs to capture callchain information. .It Fl O Ar logfilename Send logging output to file .Ar logfilename . @@ -192,14 +210,15 @@ Argument is a comma separated list of CPU numbers, or the literal .Sq * denoting all CPUs. -The default is to allocate system mode PMCs on all CPUs. +The default is to allocate system mode PMCs on all active CPUs in +the system. .It Fl d Toggle between process mode PMCs measuring events for the target process' current and future children or only measuring events for the target process. The default is to measure events for the target process alone. .It Fl g -Produce flat execution profiles in a format compatible with +Produce profiles in a format compatible with .Xr gprof 1 . A separate profile file is generated for each executable object encountered. @@ -223,7 +242,10 @@ Send counter readings and textual representations of logged data to file .Ar outputfile . The default is to send output to -.Pa stderr . +.Pa stderr +when collecting live data and to +.Pa stdout +when processing a pre-existing logfile. .It Fl p Ar event-spec Allocate a process mode counting PMC measuring hardware events specified in @@ -257,6 +279,10 @@ The argument .Ar secs may be a fractional value. The default interval is 5 seconds. +.It Fl z Ar graphdepth +When printing system-wide callgraphs, limit callgraphs to the depth +specified by argument +.Ar graphdepth . .El .Pp If @@ -286,9 +312,15 @@ To count instruction tlb-misses on CPUs 0 and 2 on a Intel Pentium Pro/Pentium III SMP system use: .Dl "pmcstat -c 0,2 -s p6-itlb-miss" .Pp +To collect profiling information for a specific process with pid 1234 +based on instruction cache misses seen by it use: +.Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out" +.Pp To perform system-wide sampling on all configured processors based on processor instructions retired use: .Dl "pmcstat -S instructions -O /tmp/sample.out" +If callgraph capture is not desired use: +.Dl "pmcstat -N -S instructions -O /tmp/sample.out" .Pp To send the generated event log to a remote machine use: .Dl "pmcstat -S instructions -O remotehost:port" @@ -298,10 +330,27 @@ On the remote machine, the sample log can be collected using .Pp To generate .Xr gprof 1 -compatible flat profiles from a sample file use: +compatible profiles from a sample file use: .Dl "pmcstat -R /tmp/sample.out -g" +.Pp +To print a system-wide profile with callgraphs to file +.Pa "foo.graph" +use: +.Dl "pmcstat -R /tmp/sample.out -G foo.graph" .Sh DIAGNOSTICS .Ex -std +.Sh COMPATIBILITY +Due to the limitations of the +.Pa gmon.out +file format, +.Xr gprof 1 +compatible profiles generated by the +.Fl g +option do not contain information about calls that cross executable +boundaries. +The generated +.Pa gmon.out +files are also only meaningful for native executables. .Sh SEE ALSO .Xr gprof 1 , .Xr nc 1 , |