Bring a working snapshot of hwpmc(4), its associated libraries, userland utilities

and documentation into -CURRENT.

Bump FreeBSD_version.

Reviewed by:	alc, jhb (kernel changes)

1 files changed, 196 insertions, 0 deletions

diff --git a/usr.sbin/pmcstat/pmcstat.8 b/usr.sbin/pmcstat/pmcstat.8
new file mode 100644
index 0000000..75f132b
--- /dev/null
+++ b/usr.sbin/pmcstat/pmcstat.8
@@ -0,0 +1,196 @@
+.\" Copyright (c) 2003 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd Dec 15, 2003
+.Os
+.Dt PMCSTAT 8
+.Sh NAME
+.Nm pmcstat
+.Nd performance measurement with performance monitoring hardware
+.Sh SYNOPSIS
+.Nm
+.Op Fl C
+.Op Fl O Ar logfilename
+.Op Fl P Ar event-spec
+.Op Fl S Ar event-spec
+.Op Fl c Ar cpu
+.Op Fl d
+.Op Fl n Ar count
+.Op Fl o Ar outputfile
+.Op Fl p Ar event-spec
+.Op Fl s Ar event-spec
+.Op Fl t Ar pid
+.Op Fl w Ar interval
+.Op command Op args
+.Sh DESCRIPTION
+The
+.Nm
+utility measures system performance using the facilities provided by
+.Xr hwpmc 4 .
+.Pp
+The
+.Nm
+utility can measure both hardware events seen by the system as a
+whole, and those seen when a specified process is executing on the
+system's CPUs.
+If a specific process is being targeted (for example,
+if the
+.Fl t Ar pid
+option is specified, or if a command line is specified using
+.Ar command ) ,
+then measurement occurs till the target process exits or
+the
+.Nm
+utility is interrupted by the user.
+If a specific process is not targeted for measurement, then
+.Nm
+will perform system-wide measurements till interrupted by the
+user.
+.Pp
+A given invocation of
+.Nm
+can mix allocations of system-mode and process-mode PMCs, of both
+counting and sampling flavors.
+The values of all counting PMCs are printed in human readable form
+at regular intervals by
+.Nm .
+The output of sampling PMCs is configured to go to log file, for later
+analysis by tools like
+.Xr pmcreport 8 .
+.Pp
+Hardware events to measure are specified to
+.Nm
+using event specifier strings
+.Ar event-spec .
+The syntax of these event specifiers is machine dependent and is
+documented in
+.Xr pmc 3 .
+.Pp
+A process-mode PMC may be configured to be inheritable by the target
+process' current and future children.
+.Sh OPTIONS
+The following options are available:
+.Bl -tag -width indent
+.It Fl C
+Toggle between showing cumulative and incremental counts for
+subsequent counting mode PMCs specified on the command line.
+The default is to show incremental counts.
+.It Fl O Ar logfilename
+Send the output of sampling mode PMCs to
+.Ar logfilename .
+The default file name is
+.Pa pmcstat.out ,
+in the current directory.
+.It Fl P Ar event-spec
+Allocate a process mode sampling PMC measuring hardware events
+specified in
+.Ar event-spec .
+.It Fl S Ar event-spec
+Allocate a system mode sampling PMC measuring hardware events
+specified in
+.Ar event-spec .
+.It Fl c Ar cpu
+Set the cpu for subsequent system mode PMCs specified on the
+command line to
+.Ar cpu .
+The default is to allocate system mode PMCs on CPU zero.
+.It Fl d
+Toggle between process mode PMCs measuring events for the target
+process' current and future children or only measuring events for
+the attached process.
+The default is to measure events for the target process alone.
+.It Fl n Ar rate
+Set the default sampling rate for subsequent sampling mode
+PMCs specified on the command line.
+The default is to configure PMCs to sample the CPU's instruction
+pointer every 65536 events.
+.It Fl o Ar outputfile
+Send the periodic counter output of
+.Nm
+to file
+.Ar outputfile .
+The default is to send output to
+.Pa stderr .
+.It Fl p Ar event-spec
+Allocate a process mode counting PMC measuring hardware events
+specified in
+.Ar event-spec .
+.It Fl s Ar event-spec
+Allocate a system mode counting PMC measuring hardware events
+specified in
+.Ar event-spec .
+.It Fl t Ar pid
+Attach all process mode PMCs allocated to the process with PID
+.Ar pid .
+The option is not allowed in conjunction with specifying a
+command using
+.Ar command .
+.It Fl w Ar secs
+Print the values of all counting mode PMCs every
+.Ar secs
+seconds.
+The argument
+.Ar secs
+may be a fractional value.
+The default interval is 5 seconds.
+.El
+.Pp
+If
+.Ar command
+is specified, it is executed using
+.Xr execvp 3 .
+.Sh EXAMPLES
+To perform system-wide statistical sampling on an AMD Athlon CPU with
+samples taken every 32768 instruction retirals and data being sampled
+to file
+.Dq sample.stat ,
+use:
+.Dl pmccstat -O sample.stat -n 32768 -S k7-retired-instructions
+.Pp
+To execute
+.Dq mozilla
+and measure the number of data cache misses suffered
+by it and its children every 12 seconds on an AMD Athlon, use:
+.Dl pmcstat -d -w 12 -p k7-dc-misses mozilla
+.Sh DIAGNOSTICS
+.Ex -std pmcstat
+.Sh HISTORY
+The
+.Nm
+utility is proposed to be integrated into
+.Fx
+sometime after
+.Fx 5.2 .
+.Nm
+.Bt
+.Sh AUTHORS
+.An Joseph Koshy Aq jkoshy@FreeBSD.org
+.Sh SEE ALSO
+.Xr execvp 3 ,
+.Xr pmc 3 ,
+.Xr hwpmc 4 ,
+.Xr pmccontrol 8 ,
+.Xr pmcreport 8 ,
+.Xr sysctl 8