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.

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 ,