1.\" 2.\" Copyright (c) 1998 Kenneth D. Merry. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $Id$ 29.\" 30.Dd May 22, 1998 31.Dt DEVSTAT 9 32.Os FreeBSD 3.0 33.Sh NAME 34.Nm devstat 35.Nd kernel interface for keeping device statistics 36.Sh SYNOPSIS 37.Fd #include <sys/devicestat.h> 38.Ft void 39.Fo devstat_add_entry 40.Fa "struct devstat *ds" 41.Fa "char *dev_name" 42.Fa "int unit_number" 43.Fa "u_int32_t block_size" 44.Fa "devstat_support_flags flags" 45.Fa "devstat_type_flags device_type" 46.Fc 47.Ft void 48.Fn devstat_remove_entry "struct devstat *ds" 49.Ft void 50.Fn devstat_start_transaction "struct devstat *ds" 51.Ft void 52.Fo devstat_end_transaction 53.Fa "struct devstat *ds" 54.Fa "u_int32_t bytes" 55.Fa "devstat_tag_type tag_type" 56.Fa "devstat_trans_flags flags" 57.Fc 58.Sh DESCRIPTION 59The devstat subsystem is basically an interface for recording device 60statistics, as its name implies. The idea is to keep reasonably detailed 61statistics while utilizing a minimum amount of CPU time to record them. 62Thus, no statistical calculations are actually performed in the kernel 63portion of the 64.Nm 65code. Instead, that is left for user programs to handle. 66.Pp 67.Fn devstat_add_entry 68registers a device with the 69.Nm 70subsystem. The caller is expected to have already allocated \fBand zeroed\fR 71the devstat structure before calling this function. 72.Fn devstat_add_entry 73takes several arguments: 74.Bl -tag -width device_type 75.It ds 76The 77.Va devstat 78structure, allocated and zeroed by the client. 79.It dev_name 80The device name. e.g. da, cd, sa. 81.It unit_number 82Device unit number. 83.It block_size 84Block size of the device, if supported. If the device does not support a 85block size, or if the blocksize is unknown at the time the device is added 86to the 87.Nm 88list, it should be set to 0. 89.It flags 90Flags indicating operations supported or not supported by the device. See 91below for details. 92.It device_type 93The device type. This is broken into three sections: base device type 94(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI 95or other) and a passthrough flag to indicate pasthrough devices. See below 96for a complete list of types. 97.El 98.Pp 99.Fn devstat_remove_entry 100removes a device from the 101.Nm 102subsystem. It takes the devstat structure for the device in question as 103an argument. The 104.Nm 105generation number is incremented and the number of devices is decremented. 106.Pp 107.Fn devstat_start_transaction 108registers the start of a transaction with the 109.Nm 110subsystem. The busy count is incremented with each transaction start. 111When a device goes from idle to busy, the system uptime is recorded in the 112.Va start_time 113field of the 114.Va devstat 115structure. 116.Pp 117.Fn devstat_end_transaction 118registers the end of a transaction with the 119.Nm 120subsystem. It takes four arguments: 121.Bl -tag -width tag_type 122.It ds 123The 124.Va devstat 125structure for the device in question. 126.It bytes 127The number of bytes transferred in this transaction. 128.It tag_type 129Transaction tag type. See below for tag types. 130.It flags 131Transaction flags indicating whether the transaction was a read, write, or 132whether no data was transferred. 133.El 134.Pp 135The 136.Va devstat 137structure is composed of the following fields: 138.Bl -tag -width dev_creation_time 139.It dev_links 140Each 141.Va devstat 142structure is placed in a linked list when it is registered. The 143.Va dev_links 144field contains a pointer to the next entry in the list of 145.Va devstat 146structures. 147.It device_number 148The device number is a unique identifier for each device. The device 149number is incremented for each new device that is registered. The device 150number is currently only a 32-bit integer, but it could be enlarged if 151someone has a system with more than four billion device arrival events. 152.It device_name 153The device name is a text string given by the registering driver to 154identify itself. (e.g. 155.Dq da , 156.Dq cd , 157.Dq sa , 158etc.) 159.It unit_number 160The unit number identifies the particular instance of the peripheral driver 161in question. 162.It bytes_written 163This is the number of bytes that have been written to the device. This 164number is currently an unsigned 64 bit integer. This will hopefully 165eliminate the counter wrap that would come very quickly on some systems if 16632 bit integers were used. 167.It bytes_read 168This is the number of bytes that have been read from the device. 169.It num_reads 170This is the number of reads from the device. 171.It num_writes 172This is the number of writes to the device. 173.It num_other 174This is the number of transactions to the device which are neither reads or 175writes. For instance, 176.Tn SCSI 177drivers often send a test unit ready command to 178.Tn SCSI 179devices. The test unit ready command does not read or write any data. It 180merely causes the device to return its status. 181.It busy_count 182This is the current number of outstanding transactions for the device. 183This should never go below zero, and on an idle device it should be zero. 184If either one of these conditions is not true, it indicates a problem in 185the way 186.Fn devstat_start_transaction 187and 188.Fn devstat_end_transaction 189are being called in client code. There should be one and only one 190transaction start event and one transaction end event for each transaction. 191.It block_size 192This is the block size of the device, if the device has a block size. 193.It tag_types 194This is an array of counters to record the number of various tag types that 195are sent to a device. See below for a list of tag types. 196.It dev_creation_time 197This is the time, as reported by 198.Fn getmicrotime 199that the device was registered. 200.It busy_time 201This is the amount of time that the device busy count has been greater than 202zero. This is only updated when the busy count returns to zero. 203.It start_time 204This is the time, as reported by 205.Fn getmicrouptime 206that the device busy count went from zero to one. 207.It last_comp_time 208This is the time as reported by 209.Fn getmicrouptime 210that a transaction last completed. It is used along with 211.Va start_time 212to calculate the device busy time. 213.It flags 214These flags indicate which statistics measurements are supported by a 215particular device. These flags are primarily intended to serve as an aid 216to userland programs that decipher the statistics. 217.It device_type 218This is the device type. It consists of three parts: the device type 219(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE, 220SCSI or other) and whether or not the device in question is a passthrough 221driver. See below for a complete list of device types. 222.El 223.Pp 224Each device is given a device type. Passthrough devices have the same 225underlying device type and interface as the device they provide an 226interface for, but they also have the passthrough flag set. The base 227device types are identical to the 228.Tn SCSI 229device type numbers, so with 230.Tn SCSI 231peripherals, the device type returned from an inquiry is usually ORed with 232the 233.Tn SCSI 234interface type and the passthrough flag if appropriate. The device type 235flags are as follows: 236.Bd -literal -offset indent 237typedef enum { 238 DEVSTAT_TYPE_DIRECT = 0x000, 239 DEVSTAT_TYPE_SEQUENTIAL = 0x001, 240 DEVSTAT_TYPE_PRINTER = 0x002, 241 DEVSTAT_TYPE_PROCESSOR = 0x003, 242 DEVSTAT_TYPE_WORM = 0x004, 243 DEVSTAT_TYPE_CDROM = 0x005, 244 DEVSTAT_TYPE_SCANNER = 0x006, 245 DEVSTAT_TYPE_OPTICAL = 0x007, 246 DEVSTAT_TYPE_CHANGER = 0x008, 247 DEVSTAT_TYPE_COMM = 0x009, 248 DEVSTAT_TYPE_ASC0 = 0x00a, 249 DEVSTAT_TYPE_ASC1 = 0x00b, 250 DEVSTAT_TYPE_STORARRAY = 0x00c, 251 DEVSTAT_TYPE_ENCLOSURE = 0x00d, 252 DEVSTAT_TYPE_FLOPPY = 0x00e, 253 DEVSTAT_TYPE_MASK = 0x00f, 254 DEVSTAT_TYPE_IF_SCSI = 0x010, 255 DEVSTAT_TYPE_IF_IDE = 0x020, 256 DEVSTAT_TYPE_IF_OTHER = 0x030, 257 DEVSTAT_TYPE_IF_MASK = 0x0f0, 258 DEVSTAT_TYPE_PASS = 0x100 259} devstat_type_flags; 260.Ed 261.Pp 262Each device has associated with it flags to indicate what operations are 263supported or not supported. The 264.Va devstat_support_flags 265values are as follows: 266.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS 267.It DEVSTAT_ALL_SUPPORTED 268Every statistic type is supported by the device. 269.It DEVSTAT_NO_BLOCKSIZE 270This device does not have a blocksize. 271.It DEVSTAT_NO_ORDERED_TAGS 272This device does not support ordered tags. 273.It DEVSTAT_BS_UNAVAILABLE 274This device supports a blocksize, but it is currently unavailable. This 275flag is most often used with removable media drives. 276.El 277.Pp 278Transactions to a device fall into one of three categories, which are 279represented in the 280.Va flags 281passed into 282.Fn devstat_end_transaction . 283The transaction types are as follows: 284.Bd -literal -offset indent 285typedef enum { 286 DEVSTAT_NO_DATA = 0x00, 287 DEVSTAT_READ = 0x01, 288 DEVSTAT_WRITE = 0x02 289} devstat_trans_flags; 290.Ed 291.Pp 292There are four possible values for the 293.Va tag_type 294argument to 295.Fn devstat_end_transaction : 296.Bl -tag -width DEVSTAT_TAG_ORDERED 297.It DEVSTAT_TAG_SIMPLE 298The transaction had a simple tag. 299.It DEVSTAT_TAG_HEAD 300The transaction had a head of queue tag. 301.It DEVSTAT_TAG_ORDERED 302The transaction had an ordered tag. 303.It DEVSTAT_TAG_NONE 304The device doesn't support tags. 305.El 306.Pp 307The tag type values correspond to the lower four bits of the 308.Tn SCSI 309tag definitions. In CAM, for instance, the 310.Va tag_action 311from the CCB is ORed with 0xf to determine the tag type to pass in to 312.Fn devstat_end_transaction . 313.Pp 314There is a macro, 315.Dv DEVSTAT_VERSION 316that is defined in 317.Aq sys/devicestat.h . 318This is the current version of the 319.Nm 320subsystem, and it should be incremented each time a change is made that 321would require recompilation of userland programs that access 322.Nm 323statistics. Userland programs use this version, via the 324.Va kern.devstat.version 325.Nm sysctl 326variable to determine whether they are in sync with the kernel 327.Nm 328structures. 329.Sh SEE ALSO 330.Xr systat 1 , 331.Xr devstat 3 , 332.Xr iostat 8 , 333.Xr rpc.rstatd 8 , 334.Xr vmstat 8 335.Sh HISTORY 336The 337.Nm 338statistics system appeared in 339.Fx 3.0 . 340.Sh AUTHORS 341Kenneth Merry 342.Aq ken@FreeBSD.ORG 343.Sh BUGS 344There may be a need for 345.Fn spl 346protection around some of the 347.Nm 348list manipulation code to insure, for example, that the list of devices 349is not changed while someone is fetching the 350.Va kern.devstat.all 351.Nm sysctl 352variable. 353.Pp 354It is impossible with the current 355.Nm 356architecture to accurately measure time per transaction. The only feasible 357way to accurately measure time per transaction would be to record a 358timestamp for every transaction. This measurement is probably not 359worthwhile for most people as it would adversely affect the performance of 360the system and cost space to store the timestamps for individual 361transactions. 362