.\"     $OpenBSD: uperf.4,v 1.14 2007/05/31 19:19:57 jmc 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.
.\"
.\" 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 $Mdocdate: May 31 2007 $
.Dt UPERF 4 sparc64
.Os
.Sh NAME
.Nm uperf
.Nd performance counters driver
.Sh SYNOPSIS
.Cd "uperf* at ebus?"
.Cd "uperf* at sbus?"
.Sh DESCRIPTION
Some UltraSPARC host bridges provide performance counters on their host
bridges.
The counters are a part of the system controller chip (usc, dsc, or qsc).
On PCI machines the system controller shows up as a device on the EBus, but
on SBus machines the system controller exists in SBus space.
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:
.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 requests completed"
.It Em UPERFSRC_P1RR Ta "read requests, 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
.Nm
device responds to the following
.Xr ioctl 2
calls, which are defined in
.Aq Pa dev/sun/uperfio.h .
.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_GETCNT
.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 ,
.Xr ebus 4 ,
.Xr intro 4 ,
.Xr sbus 4
.Sh HISTORY
The
.Nm
driver was first supported in
.Ox 3.1 .
.Sh AUTHORS
The driver was written by
.An Jason Wright Aq jason@thought.net .