Add a man page for the perfmon driver.

2 files changed, 196 insertions, 2 deletions

diff --git a/share/man/man4/man4.i386/Makefile b/share/man/man4/man4.i386/Makefile
index 8872368..b9fe3b5 100644
--- a/share/man/man4/man4.i386/Makefile
+++ b/share/man/man4/man4.i386/Makefile
@@ -1,9 +1,10 @@
-#	@(#)Makefile	0.1 (RWGrimes) 3/25/93
+#	$Id$
 
 MAN4=   aha.4 ahb.4 ahc.4 apm.4 ar.4 asc.4 bt.4 cx.4 cy.4 dgb.4 \
 	ed.4 gsc.4 fdc.4 fe.4 ie.4 io.4 \
 	joy.4 keyboard.4 labpc.4 lp.4 lpt.4 matcd.4 mcd.4 mem.4 meteor.4 \
-	mse.4 mtio.4 nca.4 npx.4 pcvt.4 qcam.4 scd.4 screen.4 sea.4 si.4 sio.4 \
+	mse.4 mtio.4 nca.4 npx.4 pcvt.4 perfmon.4 \
+	qcam.4 scd.4 screen.4 sea.4 si.4 sio.4 \
 	spkr.4 tw.4 uha.4 vx.4 wd.4
 
 MLINKS=		aha.4 ../aha.4
@@ -36,6 +37,7 @@ MLINKS+=	mtio.4 ../mtio.4
 MLINKS+=	nca.4 ../nca.4
 MLINKS+=	npx.4 ../npx.4
 MLINKS+=	pcvt.4 ../pcvt.4
+MLINKS+=	perfmon.4 ../perfmon.4
 MLINKS+=	qcam.4 ../qcam.4
 MLINKS+=	scd.4 ../scd.4
 MLINKS+=	screen.4 ../screen.4
diff --git a/share/man/man4/man4.i386/perfmon.4 b/share/man/man4/man4.i386/perfmon.4
new file mode 100644
index 0000000..e20679c
--- /dev/null
+++ b/share/man/man4/man4.i386/perfmon.4
@@ -0,0 +1,192 @@
+.\"
+.\" Copyright 1996 Massachusetts Institute of Technology
+.\"
+.\" Permission to use, copy, modify, and distribute this software and
+.\" its documentation for any purpose and without fee is hereby
+.\" granted, provided that both the above copyright notice and this
+.\" permission notice appear in all copies, that both the above
+.\" copyright notice and this permission notice appear in all
+.\" supporting documentation, and that the name of M.I.T. not be used
+.\" in advertising or publicity pertaining to distribution of the
+.\" software without specific, written prior permission.  M.I.T. makes
+.\" no representations about the suitability of this software for any
+.\" purpose.  It is provided "as is" without express or implied
+.\" warranty.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
+.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
+.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
+.\" SHALL M.I.T. 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.
+.\"
+.\"	$Id$
+.Dd March 26, 1996
+.Dt PERFMON 4 i386
+.Os FreeBSD 2.2
+.Sh NAME
+.Nm perfmon
+.Nd CPU performance-monitoring interface
+.Sh SYNOPSIS
+.Cd cpu \&"I586_CPU\&"
+.Cd cpu \&"I686_CPU\&"
+.Cd options PERFMON
+.Sh DESCRIPTION
+The
+.Nm perfmon
+driver provides access to the internal performance-monitoring
+capabilities of the
+.Tn Intel
+.Tn Pentium
+and
+.Tn "Pentium Pro"
+CPUs.  These processors implement two internal counters which can be
+configured to measure a variety of events for either count or duration
+(in CPU cycles), as well as a cycle counter which counts clock cycles.
+The
+.Nm
+driver provides a device-style interface to these capabilities.
+.Pp
+All access to the performance-monitoring counters is performed through
+the special device file
+.Dq Pa /dev/perfmon .
+This device supports a number of
+.Xr ioctl 2
+requests, defined in
+.Aq Pa machine/perfmon.h
+along with the definitions of the various counters for both
+.Tn Pentium
+and
+.Tn "Pentium Pro"
+processors.
+.Pp
+.Sy NOTA BENE :
+The set of available events differs from processor to processor.  It
+is the responsibility of the programmer to ensure that the event
+numbers used are the correct ones for the CPU type being measured.
+.Pp
+The following
+.Xr ioctl 2
+requests are defined:
+.Bl -tag -width PMIOTSTAMP
+.It Dv PMIOSETUP
+.Pq Li "struct pmc"
+Set up a counter with parameters and flags defined in the structure.
+The following fields are defined in
+.Li struct pmc :
+.Bl -tag -width "u_char pmc_eventx"
+.It Li "int pmc_num"
+the number of the counter in question; must be less than
+.Dv NPMC
+(currently 2).
+.It Li "u_char pmc_event"
+the particular event number to be monitored, as defined in
+.Aq Pa machine/perfmon.h .
+.It Li "u_char pmc_unit"
+the unit mask value, specific to the event type (see the
+.Tn Intel
+documentation).
+.It Li "u_char pmc_flags"
+flags modifying the operation of the counter (see below).
+.It Li "u_char pmc_mask"
+the counter mask value; essentially, this is a threshold used to
+restrict the count to events lasting more (or less) than the specified
+number of clocks.
+.El
+.Pp
+The following
+.Li pmc_flags
+values are defined:
+.Bl -tag -compact -width PMCF_USRxx
+.It Dv PMCF_USR
+count events in user mode
+.It Dv PMCF_OS
+count events in kernel mode
+.It Dv PMCF_E
+count number of events rather than their duration
+.It Dv PMCF_INV
+invert the sense of the counter mask comparison
+.El
+.It Dv PMIOGET
+.Pq Li "struct pmc"
+returns the current configuration of the specified counter.
+.It Dv PMIOSTART
+.It Dv PMIOSTOP
+.Pq Li int
+starts (stops) the specified counter.  Currently, only a counter value of
+.Dv PMC_ALL
+is supported, as the hardware starts and stops the counters as a gang.
+.It Dv PMIORESET
+.Pq Li int
+reset the specified counter to zero.  The counter should be stopped
+with
+.Dv PMIOSTOP
+before it is reset.  All counters are automatically reset by
+.Dv PMIOSETUP .
+.It Dv PMIOREAD
+.Pq Li "struct pmc_data"
+get the current value of the counter.  The
+.Li pmc_data
+structure defines two fields:
+.Pp
+.Bl -tag -compact -width "quad_t pmcd_value"
+.It Li "int pmcd_num"
+the number of the counter to read
+.It Li "int pmcd_value"
+the resulting value as a 64-bit signed integer
+.El
+.Pp
+In the future, it may be possible to use the
+.Li RDPMC
+instruction on
+.Tn "Pentium Pro"
+processors to read the counters directly.
+.It Dv PMIOTSTAMP
+.Pq Li "struct pmc_tstamp"
+read the time stamp counter.  The
+.Li pmc_tstamp
+structure defines two fields:
+.Pp
+.Bl -tag -compact -width "quad_t pmct_value"
+.It Li "int pmct_rate"
+the approximate rate of the counter, in MHz
+.It Li "quad_t pmct_value"
+the current value of the counter as a 64-bit integer
+.El
+.Pp
+It is important to note that the counter rate, as provided in the
+.Li pmct_rate
+field, is often incorrect because of calibration difficulties and
+non-integral clock rates.  This field should be considered more of a
+hint or sanity-check than an actual representation of the rate of
+clock ticks.
+.El
+.Sh FILES
+.Bl -tag -compact -width "/dev/perfmon"
+.It Pa /dev/perfmon
+character device interface to counters
+.El
+.Sh SEE ALSO
+.Rs
+.%A Intel Corporation
+.%B Pentium Pro Family Developer's Manual
+.%D January 1996
+.%V vol. 3
+.%O Operating System Writer's Manual
+.Re
+.Sh HISTORY
+The
+.Nm
+device first appeared in
+.Fx 2.2 .
+.Sh AUTHOR
+The
+.Nm
+driver was written by Garrett A. Wollman, MIT Laboratory for Computer
+Science.