Man page describing the in kernel device statistics routines.

Submitted by:	"Kenneth D. Merry" <ken@plutotech.com>

1 files changed, 361 insertions, 0 deletions

diff --git a/share/man/man9/devstat.9 b/share/man/man9/devstat.9
new file mode 100644
index 0000000..25a3088
--- /dev/null
+++ b/share/man/man9/devstat.9
@@ -0,0 +1,361 @@
+.\"
+.\" Copyright (c) 1998 Kenneth D. Merry.
+.\" 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. 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 AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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 May 22, 1998
+.Dt DEVSTAT 9
+.Os FreeBSD 3.0
+.Sh NAME
+.Nm devstat
+.Nd kernel interface for keeping device statistics
+.Sh SYNOPSIS
+.Fd #include <sys/devicestat.h>
+.Ft void
+.Fo devstat_add_entry
+.Fa "struct devstat *ds"
+.Fa "char *dev_name"
+.Fa "int unit_number"
+.Fa "u_int32_t block_size"
+.Fa "devstat_support_flags flags"
+.Fa "devstat_type_flags device_type"
+.Fc
+.Ft void
+.Fn devstat_remove_entry "struct devstat *ds"
+.Ft void
+.Fn devstat_start_transaction "struct devstat *ds"
+.Ft void
+.Fo devstat_end_transaction
+.Fa "struct devstat *ds"
+.Fa "u_int32_t bytes"
+.Fa "devstat_tag_type tag_type"
+.Fa "devstat_trans_flags flags"
+.Fc
+.Sh DESCRIPTION
+The devstat subsystem is basically an interface for recording device
+statistics, as its name implies.  The idea is to keep reasonably detailed
+statistics while utilizing a minimum amount of CPU time to record them.
+Thus, no statistical calculations are actually performed in the kernel
+portion of the
+.Nm
+code.  Instead, that is left for user programs to handle.
+.Pp
+.Fn devstat_add_entry
+registers a device with the
+.Nm
+subsystem.  The caller is expected to have already allocated \fBand zeroed\fR
+the devstat structure before calling this function.
+.Fn devstat_add_entry
+takes several arguments:
+.Bl -tag -width device_type
+.It ds
+The
+.Va devstat
+structure, allocated and zeroed by the client.
+.It dev_name
+The device name. e.g. da, cd, sa.
+.It unit_number
+Device unit number.
+.It block_size
+Block size of the device, if supported.  If the device does not support a
+block size, or if the blocksize is unknown at the time the device is added
+to the
+.Nm
+list, it should be set to 0.
+.It flags
+Flags indicating operations supported or not supported by the device.  See
+below for details.
+.It device_type
+The device type.  This is broken into three sections:  base device type
+(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI
+or other) and a passthrough flag to indicate pasthrough devices.  See below
+for a complete list of types.
+.El
+.Pp
+.Fn devstat_remove_entry
+removes a device from the
+.Nm
+subsystem.  It takes the devstat structure for the device in question as
+an argument.  The
+.Nm
+generation number is incremented and the number of devices is decremented.
+.Pp
+.Fn devstat_start_transaction
+registers the start of a transaction with the
+.Nm
+subsystem.  The busy count is incremented with each transaction start.
+When a device goes from idle to busy, the system uptime is recorded in the
+.Va start_time
+field of the
+.Va devstat
+structure.
+.Pp
+.Fn devstat_end_transaction
+registers the end of a transaction with the
+.Nm
+subsystem.  It takes four arguments:
+.Bl -tag -width tag_type
+.It ds
+The
+.Va devstat
+structure for the device in question.
+.It bytes
+The number of bytes transferred in this transaction.
+.It tag_type
+Transaction tag type.  See below for tag types.
+.It flags
+Transaction flags indicating whether the transaction was a read, write, or
+whether no data was transferred.
+.El
+.Pp
+The
+.Va devstat
+structure is composed of the following fields:
+.Bl -tag -width dev_creation_time
+.It dev_links
+Each
+.Va devstat
+structure is placed in a linked list when it is registered.  The
+.Va dev_links
+field contains a pointer to the next entry in the list of
+.Va devstat
+structures.
+.It device_number
+The device number is a unique identifier for each device.  The device
+number is incremented for each new device that is registered.  The device
+number is currently only a 32-bit integer, but it could be enlarged if
+someone has a system with more than four billion device arrival events.
+.It device_name
+The device name is a text string given by the registering driver to
+identify itself.  (e.g. 
+.Dq da ,
+.Dq cd ,
+.Dq sa ,
+etc.)
+.It unit_number
+The unit number identifies the particular instance of the peripheral driver
+in question.
+.It bytes_written
+This is the number of bytes that have been written to the device.  This
+number is currently an unsigned 64 bit integer.  This will hopefully
+eliminate the counter wrap that would come very quickly on some systems if
+32 bit integers were used.
+.It bytes_read
+This is the number of bytes that have been read from the device.
+.It num_reads
+This is the number of reads from the device.
+.It num_writes
+This is the number of writes to the device.
+.It num_other
+This is the number of transactions to the device which are neither reads or
+writes.  For instance,
+.Tn SCSI
+drivers often send a test unit ready command to
+.Tn SCSI
+devices.  The test unit ready command does not read or write any data.  It
+merely causes the device to return its status.
+.It busy_count
+This is the current number of outstanding transactions for the device.
+This should never go below zero, and on an idle device it should be zero.
+If either one of these conditions is not true, it indicates a problem in
+the way
+.Fn devstat_start_transaction
+and
+.Fn devstat_end_transaction
+are being called in client code.  There should be one and only one
+transaction start event and one transaction end event for each transaction.
+.It block_size
+This is the block size of the device, if the device has a block size.
+.It tag_types
+This is an array of counters to record the number of various tag types that
+are sent to a device.  See below for a list of tag types.
+.It dev_creation_time
+This is the time, as reported by
+.Fn getmicrotime
+that the device was registered.
+.It busy_time
+This is the amount of time that the device busy count has been greater than
+zero.  This is only updated when the busy count returns to zero.
+.It start_time
+This is the time, as reported by
+.Fn getmicrouptime
+that the device busy count went from zero to one.
+.It last_comp_time
+This is the time as reported by
+.Fn getmicrouptime
+that a transaction last completed.  It is used along with
+.Va start_time
+to calculate the device busy time.
+.It flags
+These flags indicate which statistics measurements are supported by a
+particular device.  These flags are primarily intended to serve as an aid
+to userland programs that decipher the statistics.
+.It device_type
+This is the device type.  It consists of three parts:  the device type
+(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE,
+SCSI or other) and whether or not the device in question is a passthrough
+driver.  See below for a complete list of device types.
+.El
+.Pp
+Each device is given a device type.  Passthrough devices have the same
+underlying device type and interface as the device they provide an
+interface for, but they also have the passthrough flag set.  The base
+device types are identical to the
+.Tn SCSI
+device type numbers, so with
+.Tn SCSI
+peripherals, the device type returned from an inquiry is usually ORed with
+the
+.Tn SCSI
+interface type and the passthrough flag if appropriate.  The device type
+flags are as follows:
+.Bd -literal -offset indent
+typedef enum {
+	DEVSTAT_TYPE_DIRECT	= 0x000,
+	DEVSTAT_TYPE_SEQUENTIAL	= 0x001,
+	DEVSTAT_TYPE_PRINTER	= 0x002,
+	DEVSTAT_TYPE_PROCESSOR	= 0x003,
+	DEVSTAT_TYPE_WORM	= 0x004,
+	DEVSTAT_TYPE_CDROM	= 0x005,
+	DEVSTAT_TYPE_SCANNER	= 0x006,
+	DEVSTAT_TYPE_OPTICAL	= 0x007,
+	DEVSTAT_TYPE_CHANGER	= 0x008,
+	DEVSTAT_TYPE_COMM	= 0x009,
+	DEVSTAT_TYPE_ASC0	= 0x00a,
+	DEVSTAT_TYPE_ASC1	= 0x00b,
+	DEVSTAT_TYPE_STORARRAY	= 0x00c,
+	DEVSTAT_TYPE_ENCLOSURE	= 0x00d,
+	DEVSTAT_TYPE_FLOPPY	= 0x00e,
+	DEVSTAT_TYPE_MASK	= 0x00f,
+	DEVSTAT_TYPE_IF_SCSI	= 0x010,
+	DEVSTAT_TYPE_IF_IDE	= 0x020,
+	DEVSTAT_TYPE_IF_OTHER	= 0x030,
+	DEVSTAT_TYPE_IF_MASK	= 0x0f0,
+	DEVSTAT_TYPE_PASS	= 0x100
+} devstat_type_flags;
+.Ed
+.Pp
+Each device has associated with it flags to indicate what operations are
+supported or not supported.  The
+.Va devstat_support_flags
+values are as follows:
+.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
+.It DEVSTAT_ALL_SUPPORTED
+Every statistic type is supported by the device.
+.It DEVSTAT_NO_BLOCKSIZE
+This device does not have a blocksize.
+.It DEVSTAT_NO_ORDERED_TAGS
+This device does not support ordered tags.
+.It DEVSTAT_BS_UNAVAILABLE
+This device supports a blocksize, but it is currently unavailable.  This
+flag is most often used with removable media drives.
+.El
+.Pp
+Transactions to a device fall into one of three categories, which are
+represented in the
+.Va flags
+passed into
+.Fn devstat_end_transaction .
+The transaction types are as follows:
+.Bd -literal -offset indent
+typedef enum { 
+	DEVSTAT_NO_DATA	= 0x00,
+	DEVSTAT_READ	= 0x01,
+	DEVSTAT_WRITE	= 0x02
+} devstat_trans_flags;
+.Ed
+.Pp
+There are four possible values for the
+.Va tag_type
+argument to
+.Fn devstat_end_transaction :
+.Bl -tag -width DEVSTAT_TAG_ORDERED
+.It DEVSTAT_TAG_SIMPLE
+The transaction had a simple tag.
+.It DEVSTAT_TAG_HEAD
+The transaction had a head of queue tag.
+.It DEVSTAT_TAG_ORDERED
+The transaction had an ordered tag.
+.It DEVSTAT_TAG_NONE
+The device doesn't support tags.
+.El
+.Pp
+The tag type values correspond to the lower four bits of the
+.Tn SCSI
+tag definitions.  In CAM, for instance, the
+.Va tag_action
+from the CCB is ORed with 0xf to determine the tag type to pass in to
+.Fn devstat_end_transaction .
+.Pp
+There is a macro,
+.Dv DEVSTAT_VERSION
+that is defined in
+.Aq sys/devicestat.h .
+This is the current version of the
+.Nm
+subsystem, and it should be incremented each time a change is made that
+would require recompilation of userland programs that access
+.Nm
+statistics.  Userland programs use this version, via the
+.Va kern.devstat.version
+.Nm sysctl
+variable to determine whether they are in sync with the kernel
+.Nm
+structures.
+.Sh SEE ALSO
+.Xr systat 1 ,
+.Xr devstat 3 ,
+.Xr iostat 8 ,
+.Xr rpc.rstatd 8 ,
+.Xr vmstat 8
+.Sh HISTORY
+The
+.Nm
+statistics system appeared in
+.Fx 3.0 .
+.Sh AUTHORS
+Kenneth Merry
+.Aq ken@FreeBSD.ORG
+.Sh BUGS
+There may be a need for
+.Fn spl
+protection around some of the
+.Nm
+list manipulation code to insure, for example, that the list of devices
+is not changed while someone is fetching the
+.Va kern.devstat.all
+.Nm sysctl
+variable.
+.Pp
+It is impossible with the current
+.Nm
+architecture to accurately measure time per transaction.  The only feasible
+way to accurately measure time per transaction would be to record a
+timestamp for every transaction.  This measurement is probably not
+worthwhile for most people as it would adversely affect the performance of
+the system and cost space to store the timestamps for individual
+transactions.