362 lines
12 KiB
Groff
362 lines
12 KiB
Groff
.\"
|
|
.\" 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.
|