uperf docs

2 files changed, 196 insertions, 2 deletions

diff --git a/share/man/man4/man4.sparc64/Makefile b/share/man/man4/man4.sparc64/Makefile
index f88700f94b3..037283a7ba2 100644
--- a/share/man/man4/man4.sparc64/Makefile
+++ b/share/man/man4/man4.sparc64/Makefile
@@ -1,9 +1,9 @@
-#	$OpenBSD: Makefile,v 1.14 2002/01/25 04:49:37 jason Exp $
+#	$OpenBSD: Makefile,v 1.15 2002/01/31 03:04:28 jason Exp $
 
 # TODO: auxio.4 beeper.4 clock.4 ebus.4 pcons.4 psycho.4 sbus.4 timer.4
 MAN=	audioce.4 audiocs.4 autoconf.4 be.4 cgsix.4 cgthree.4 comkbd.4 \
 	esp.4 gem.4 hme.4 intro.4 le.4 magma.4 mem.4 openprom.4 pcons.4 \
-	qe.4 qec.4 sab.4 spif.4 vgafb.4 zs.4
+	qe.4 qec.4 sab.4 spif.4 uperf.4 vgafb.4 zs.4
 MLINKS=	mem.4 kmem.4 \
 	sab.4 sabtty.4 \
 	zs.4 zstty.4 \
diff --git a/share/man/man4/man4.sparc64/uperf.4 b/share/man/man4/man4.sparc64/uperf.4
new file mode 100644
index 00000000000..3e70dbd3f18
--- /dev/null
+++ b/share/man/man4/man4.sparc64/uperf.4
@@ -0,0 +1,194 @@
+.\"     $OpenBSD: uperf.4,v 1.1 2002/01/31 03:04:28 jason Exp $
+.\"
+.\" Copyright (c) 2002 Jason L. Wright (jason@thought.net)
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"      This product includes software developed by Jason L. Wright
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 THE AUTHOR 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.
+.\"
+.Dd January 30, 2002
+.Dt UPERF 4 sparc64
+.Os
+.Sh NAME
+.Nm uperf
+.Nd performance counters driver
+.Sh SYNOPSIS
+.Cd "uperf* at psycho?"
+.Cd "uperf* at sbus? slot ? offset ?"
+.Sh DESCRIPTION
+Some UltraSPARC host bridges provide performance counters.
+On PCI machines, the performance counters are a part of the
+PCI host bridge, and on SBUS machines, the counters are
+a part of the system controller chip (usc or dsc).
+The
+.Nm
+driver provides access to these counters via
+.Xr ioctl 2 .
+.Sh IOCTLS
+All of the ioctl calls supported by the
+.Nm
+driver take the following structure as an argument:
+.Bd -literal -offset indent
+struct uperf_io {
+	int cnt_flags;
+	int cnt_src0;
+	int cnt_src1;
+	u_int32_t cnt_val0;
+	u_int32_t cnt_val1;
+};
+.Ed
+.Pp
+The
+.Fa cnt_flags
+field specifies which counters are being operated on and is a bit mask
+of
+.Fa UPERF_CNT0
+and/or
+.Fa UPERF_CNT1 .
+.Pp
+The
+.Fa cnt_src0
+and
+.Fa cnt_src1
+fields specify the source for the counter
+Not all counters support monitoring all sources and specifying an invalid
+source for a counter to monitor will result in an error.
+The sources are specified below:
+.Pp
+.Bl -column "XXXXXXXXXXXXXX" "description" -offset indent
+.It Em UPERFSRC_SYSCK Ta "system clock ticks"
+.It Em UPERFSRC_PRALL Ta "all p-requests"
+.It Em UPERFSRC_PRP0 Ta "p-requests from processor 0"
+.It Em UPERFSRC_PRU2S Ta "p-requests from the U2S"
+.It Em UPERFSRC_UPA128 Ta "cycles UPA 128 bit data is busy"
+.It Em UPERFSRC_UPA64 Ta "cycles UPA 64 bit data is busy"
+.It Em UPERFSRC_PIOS Ta "cycles stalled during PIO"
+.It Em UPERFSRC_MEMRI Ta "memory requests issued"
+.It Em UPERFSRC_MCBUSY Ta "cycles memory controller is busy"
+.It Em UPERFSRC_PXSH Ta "stall cycles due to pending transaction scoreboard hit"
+.It Em UPERFSRC_P0CWMR Ta "coherent write miss requests, processor 0"
+.It Em UPERFSRC_P1CWMR Ta "coherent write miss requests, processor 1"
+.It Em UPERFSRC_CIT Ta "coherent intervention transactions"
+.It Em UPERFSRC_U2SDAT Ta "data transactions on U2S"
+.It Em UPERFSRC_CRXI Ta "coherent read transactions issued"
+.It Em UPERFSRC_RDP0 Ta "read requests, processor 0"
+.It Em UPERFSRC_P0CRMR Ta "coherent read misses, processor 0"
+.It Em UPERFSRC_P0PIO Ta "PIO accesses, processor 0"
+.It Em UPERFSRC_MEMRC Ta "memory reqeusts completed"
+.It Em UPERFSRC_P1RR Ta "read reqeusts, processor 1"
+.It Em UPERFSRC_CRMP1 Ta "coherent read misses, processor 1"
+.It Em UPERFSRC_PIOP1 Ta "PIO accesses, processor 1"
+.It Em UPERFSRC_CWXI Ta "coherent write transactions issued"
+.It Em UPERFSRC_RP0 Ta "read requests, processor 0"
+.It Em UPERFSRC_SDVRA Ta "streaming DVMA read transfers, PCI bus A"
+.It Em UPERFSRC_SDVWA Ta "streaming DVMA write transfers, PCI bus A"
+.It Em UPERFSRC_CDVRA Ta "consistent DVMA read transfers, PCI bus A"
+.It Em UPERFSRC_CDVWA Ta "consistent DVMA write transfers, PCI bus A"
+.It Em UPERFSRC_SBMA Ta "streaming buffer misses, PCI bus A"
+.It Em UPERFSRC_DVA Ta "DVMA cycles, PCI bus A"
+.It Em UPERFSRC_DVWA Ta "words transferred via DVMA, PCI bus A"
+.It Em UPERFSRC_PIOA Ta "cycles consumed by PIO, bus A"
+.It Em UPERFSRC_SDVRB Ta "streaming DVMA read transfers, PCI bus B"
+.It Em UPERFSRC_SDVWB Ta "streaming DVMA write transfers, PCI bus B"
+.It Em UPERFSRC_CDVRB Ta "consistent DVMA read transfers, PCI bus B"
+.It Em UPERFSRC_CDVWB Ta "consistent DVMA write transfers, PCI bus B"
+.It Em UPERFSRC_SBMB Ta "streaming buffer misses, PCI bus B"
+.It Em UPERFSRC_DVB Ta "DVMA cycles, PCI bus B"
+.It Em UPERFSRC_DVWB Ta "words transferred via DVMA, PCI bus B"
+.It Em UPERFSRC_PIOB Ta "cycles consumed by PIO, bus B"
+.It Em UPERFSRC_TLBMISS Ta "TLB misses"
+.It Em UPERFSRC_NINTRS Ta "interrupts"
+.It Em UPERFSRC_INACK Ta "interrupt NACKS on UPA"
+.It Em UPERFSRC_PIOR Ta "PIO read transfers"
+.It Em UPERFSRC_PIOW Ta "PIO write transfers"
+.It Em UPERFSRC_MERGE Ta "merge buffer transactions"
+.It Em UPERFSRC_TBLA Ta "DMA requests retried due to tablewalks, PCI bus A"
+.It Em UPERFSRC_STCA Ta "DMA requests retries due to STC, PCI bus A"
+.It Em UPERFSRC_TBLB Ta "DMA requests retries due to tablewalks, PCI bus B"
+.It Em UPERFSRC_STCB Ta "DMA requests retries due to STC, PCI bus B"
+.El
+.Pp
+The
+.Fa cnt_val0
+and
+.Fa cnt_val1
+contain the values fetched for the counters.
+Software using this interface should be prepared to handle the counters rolling over.
+.Pp
+The 
+A
+.Nm
+device responds to the following
+.Xr ioctl 2
+calls, which are defined in
+.Aq Pa dev/sun/uperfio.h .
+.Pp
+.Bl -tag -width UPIO_GCNTSRC
+.It Dv UPIO_GCNTSRC
+.Pq Li "struct uperf_io"
+Retrieve the source the counters are monitoring.
+The
+.Fa cnt_flags
+is a bit mask for which of the counters is to be fetched.
+The result is returned in
+.Fa cnt_src0
+and/or
+.Fa cnt_src1 .
+.It Dv UPIO_SCNTSRC
+.Pq Li "struct uperf_io"
+Set the source the counters should monitor.
+This call also clears the current value of the counters that are set.
+The
+.Fa cnt_flags
+is a bit mask for which of the counters is to be set.
+The
+.Fa cnt_src0
+and/or
+.Fa cnt_src1
+fields specify the source to be set for the respective counter.
+.It Dv UPIO_CLRCNT
+.Pq Li "struct uperf_io"
+Clear the counters specified in
+.Fa cnt_flags .
+.It Dv UPIO_CLRCNT
+.Pq Li "struct uperf_io"
+Retrieve the value for the counters specified in
+.Fa cnt_flags .
+The values are returned in
+.Fa cnt_val0
+and/or
+.Fa cnt_val1 .
+.El
+.Sh SEE ALSO
+.Xr ioctl 2
+.Sh AUTHORS
+The driver was written by
+.An Jason Wright Aq jason@thought.net .
+.Sh HISTORY
+The
+.Nm
+driver was first supported in
+.Ox 3.1 .