diff options
Diffstat (limited to 'share/man/man9/devstat.9')
| -rw-r--r-- | share/man/man9/devstat.9 | 455 |
1 files changed, 455 insertions, 0 deletions
diff --git a/share/man/man9/devstat.9 b/share/man/man9/devstat.9 new file mode 100644 index 0000000..ad13934 --- /dev/null +++ b/share/man/man9/devstat.9 @@ -0,0 +1,455 @@ +.\" +.\" Copyright (c) 1998, 1999 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. +.\" +.\" $FreeBSD$ +.\" +.Dd May 22, 1998 +.Dt DEVSTAT 9 +.Os +.Sh NAME +.Nm devstat , +.Nm devstat_add_entry , +.Nm devstat_end_transaction , +.Nm devstat_end_transaction_bio , +.Nm devstat_remove_entry , +.Nm devstat_start_transaction +.Nd kernel interface for keeping device statistics +.Sh SYNOPSIS +.In sys/devicestat.h +.Ft void +.Fo devstat_add_entry +.Fa "struct devstat *ds" +.Fa "const char *dev_name" +.Fa "int unit_number" +.Fa "uint32_t block_size" +.Fa "devstat_support_flags flags" +.Fa "devstat_type_flags device_type" +.Fa "devstat_priority priority" +.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 "uint32_t bytes" +.Fa "devstat_tag_type tag_type" +.Fa "devstat_trans_flags flags" +.Fc +.Ft void +.Fo devstat_end_transaction_bio +.Fa "struct devstat *ds" +.Fa "struct bio *bp" +.Fc +.Sh DESCRIPTION +The devstat subsystem is 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 pass-through flag to indicate pas-through devices. +See below for a complete list of types. +.It priority +The device priority. +The priority is used to determine how devices are +sorted within +.Nm devstat Ns 's +list of devices. +Devices are sorted first by priority (highest to lowest), +and then by attach order. +See below for a complete list of available +priorities. +.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 +.Fn devstat_end_transaction_bio +is a wrapper for +.Fn devstat_end_transaction +which pulls all the information from a +.Va "struct bio" +which is ready for biodone(). +.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 bytes_freed +This is the number of bytes that have been freed/erased on 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_frees +This is the number of free/erase operations on 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 pass-through +driver. +See below for a complete list of device types. +.It priority +This is the priority. +This is the first parameter used to determine where +to insert a device in the +.Nm +list. +The second parameter is attach order. +See below for a list of +available priorities. +.El +.Pp +Each device is given a device type. +Pass-through devices have the same +underlying device type and interface as the device they provide an +interface for, but they also have the pass-through 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 pass-through 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 +Devices have a priority associated with them, which controls roughly where +they are placed in the +.Nm +list. +The priorities are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_PRIORITY_MIN = 0x000, + DEVSTAT_PRIORITY_OTHER = 0x020, + DEVSTAT_PRIORITY_PASS = 0x030, + DEVSTAT_PRIORITY_FD = 0x040, + DEVSTAT_PRIORITY_WFD = 0x050, + DEVSTAT_PRIORITY_TAPE = 0x060, + DEVSTAT_PRIORITY_CD = 0x090, + DEVSTAT_PRIORITY_DISK = 0x110, + DEVSTAT_PRIORITY_ARRAY = 0x120, + DEVSTAT_PRIORITY_MAX = 0xfff +} devstat_priority; +.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_FREE = 0x03 +} 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 does not 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 +.In 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 +.An Kenneth Merry Aq Mt ken@FreeBSD.org +.Sh BUGS +There may be a need for +.Fn spl +protection around some of the +.Nm +list manipulation code to ensure, 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. |
