1.\" 2.\" Copyright (c) 1998, 1999 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.\" $FreeBSD: src/share/man/man9/devstat.9,v 1.10.2.5 2001/12/17 11:30:18 ru Exp $ 29.\" $DragonFly: src/share/man/man9/devstat.9,v 1.2 2003/06/17 04:37:01 dillon Exp $ 30.\" 31.Dd May 22, 1998 32.Dt DEVSTAT 9 33.Os 34.Sh NAME 35.Nm devstat , 36.Nm devstat_add_entry , 37.Nm devstat_end_transaction , 38.Nm devstat_end_transaction_buf , 39.Nm devstat_remove_entry , 40.Nm devstat_start_transaction 41.Nd kernel interface for keeping device statistics 42.Sh SYNOPSIS 43.In sys/devicestat.h 44.Ft void 45.Fo devstat_add_entry 46.Fa "struct devstat *ds" 47.Fa "const char *dev_name" 48.Fa "int unit_number" 49.Fa "u_int32_t block_size" 50.Fa "devstat_support_flags flags" 51.Fa "devstat_type_flags device_type" 52.Fa "devstat_priority priority" 53.Fc 54.Ft void 55.Fn devstat_remove_entry "struct devstat *ds" 56.Ft void 57.Fn devstat_start_transaction "struct devstat *ds" 58.Ft void 59.Fo devstat_end_transaction 60.Fa "struct devstat *ds" 61.Fa "u_int32_t bytes" 62.Fa "devstat_tag_type tag_type" 63.Fa "devstat_trans_flags flags" 64.Fc 65.Ft void 66.Fo devstat_end_transaction_buf 67.Fa "struct devstat *ds" 68.Fa "struct buf *bp" 69.Fc 70.Sh DESCRIPTION 71The devstat subsystem is an interface for recording device 72statistics, as its name implies. The idea is to keep reasonably detailed 73statistics while utilizing a minimum amount of CPU time to record them. 74Thus, no statistical calculations are actually performed in the kernel 75portion of the 76.Nm 77code. Instead, that is left for user programs to handle. 78.Pp 79.Fn devstat_add_entry 80registers a device with the 81.Nm 82subsystem. The caller is expected to have already allocated \fBand zeroed\fR 83the devstat structure before calling this function. 84.Fn devstat_add_entry 85takes several arguments: 86.Bl -tag -width device_type 87.It ds 88The 89.Va devstat 90structure, allocated and zeroed by the client. 91.It dev_name 92The device name. e.g. da, cd, sa. 93.It unit_number 94Device unit number. 95.It block_size 96Block size of the device, if supported. If the device does not support a 97block size, or if the blocksize is unknown at the time the device is added 98to the 99.Nm 100list, it should be set to 0. 101.It flags 102Flags indicating operations supported or not supported by the device. See 103below for details. 104.It device_type 105The device type. This is broken into three sections: base device type 106(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI 107or other) and a passthrough flag to indicate pasthrough devices. See below 108for a complete list of types. 109.It priority 110The device priority. The priority is used to determine how devices are 111sorted within 112.Nm devstat Ns 's 113list of devices. Devices are sorted first by priority (highest to lowest), 114and then by attach order. See below for a complete list of available 115priorities. 116.El 117.Pp 118.Fn devstat_remove_entry 119removes a device from the 120.Nm 121subsystem. It takes the devstat structure for the device in question as 122an argument. The 123.Nm 124generation number is incremented and the number of devices is decremented. 125.Pp 126.Fn devstat_start_transaction 127registers the start of a transaction with the 128.Nm 129subsystem. The busy count is incremented with each transaction start. 130When a device goes from idle to busy, the system uptime is recorded in the 131.Va start_time 132field of the 133.Va devstat 134structure. 135.Pp 136.Fn devstat_end_transaction 137registers the end of a transaction with the 138.Nm 139subsystem. It takes four arguments: 140.Bl -tag -width tag_type 141.It ds 142The 143.Va devstat 144structure for the device in question. 145.It bytes 146The number of bytes transferred in this transaction. 147.It tag_type 148Transaction tag type. See below for tag types. 149.It flags 150Transaction flags indicating whether the transaction was a read, write, or 151whether no data was transferred. 152.El 153.Pp 154.Fn devstat_end_transaction_buf 155is a wrapper for 156.Fn devstat_end_transaction 157which pulls all the information from a 158.Va "struct buf" 159which is ready for biodone(). 160.Pp 161The 162.Va devstat 163structure is composed of the following fields: 164.Bl -tag -width dev_creation_time 165.It dev_links 166Each 167.Va devstat 168structure is placed in a linked list when it is registered. The 169.Va dev_links 170field contains a pointer to the next entry in the list of 171.Va devstat 172structures. 173.It device_number 174The device number is a unique identifier for each device. The device 175number is incremented for each new device that is registered. The device 176number is currently only a 32-bit integer, but it could be enlarged if 177someone has a system with more than four billion device arrival events. 178.It device_name 179The device name is a text string given by the registering driver to 180identify itself. (e.g.\& 181.Dq da , 182.Dq cd , 183.Dq sa , 184etc.) 185.It unit_number 186The unit number identifies the particular instance of the peripheral driver 187in question. 188.It bytes_written 189This is the number of bytes that have been written to the device. This 190number is currently an unsigned 64 bit integer. This will hopefully 191eliminate the counter wrap that would come very quickly on some systems if 19232 bit integers were used. 193.It bytes_read 194This is the number of bytes that have been read from the device. 195.It bytes_freed 196This is the number of bytes that have been freed/erased on the device. 197.It num_reads 198This is the number of reads from the device. 199.It num_writes 200This is the number of writes to the device. 201.It num_frees 202This is the number of free/erase operations on the device. 203.It num_other 204This is the number of transactions to the device which are neither reads or 205writes. For instance, 206.Tn SCSI 207drivers often send a test unit ready command to 208.Tn SCSI 209devices. The test unit ready command does not read or write any data. It 210merely causes the device to return its status. 211.It busy_count 212This is the current number of outstanding transactions for the device. 213This should never go below zero, and on an idle device it should be zero. 214If either one of these conditions is not true, it indicates a problem in 215the way 216.Fn devstat_start_transaction 217and 218.Fn devstat_end_transaction 219are being called in client code. There should be one and only one 220transaction start event and one transaction end event for each transaction. 221.It block_size 222This is the block size of the device, if the device has a block size. 223.It tag_types 224This is an array of counters to record the number of various tag types that 225are sent to a device. See below for a list of tag types. 226.It dev_creation_time 227This is the time, as reported by 228.Fn getmicrotime 229that the device was registered. 230.It busy_time 231This is the amount of time that the device busy count has been greater than 232zero. This is only updated when the busy count returns to zero. 233.It start_time 234This is the time, as reported by 235.Fn getmicrouptime 236that the device busy count went from zero to one. 237.It last_comp_time 238This is the time as reported by 239.Fn getmicrouptime 240that a transaction last completed. It is used along with 241.Va start_time 242to calculate the device busy time. 243.It flags 244These flags indicate which statistics measurements are supported by a 245particular device. These flags are primarily intended to serve as an aid 246to userland programs that decipher the statistics. 247.It device_type 248This is the device type. It consists of three parts: the device type 249(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE, 250SCSI or other) and whether or not the device in question is a passthrough 251driver. See below for a complete list of device types. 252.It priority 253This is the priority. This is the first parameter used to determine where 254to insert a device in the 255.Nm 256list. The second parameter is attach order. See below for a list of 257available priorities. 258.El 259.Pp 260Each device is given a device type. Passthrough devices have the same 261underlying device type and interface as the device they provide an 262interface for, but they also have the passthrough flag set. The base 263device types are identical to the 264.Tn SCSI 265device type numbers, so with 266.Tn SCSI 267peripherals, the device type returned from an inquiry is usually ORed with 268the 269.Tn SCSI 270interface type and the passthrough flag if appropriate. The device type 271flags are as follows: 272.Bd -literal -offset indent 273typedef enum { 274 DEVSTAT_TYPE_DIRECT = 0x000, 275 DEVSTAT_TYPE_SEQUENTIAL = 0x001, 276 DEVSTAT_TYPE_PRINTER = 0x002, 277 DEVSTAT_TYPE_PROCESSOR = 0x003, 278 DEVSTAT_TYPE_WORM = 0x004, 279 DEVSTAT_TYPE_CDROM = 0x005, 280 DEVSTAT_TYPE_SCANNER = 0x006, 281 DEVSTAT_TYPE_OPTICAL = 0x007, 282 DEVSTAT_TYPE_CHANGER = 0x008, 283 DEVSTAT_TYPE_COMM = 0x009, 284 DEVSTAT_TYPE_ASC0 = 0x00a, 285 DEVSTAT_TYPE_ASC1 = 0x00b, 286 DEVSTAT_TYPE_STORARRAY = 0x00c, 287 DEVSTAT_TYPE_ENCLOSURE = 0x00d, 288 DEVSTAT_TYPE_FLOPPY = 0x00e, 289 DEVSTAT_TYPE_MASK = 0x00f, 290 DEVSTAT_TYPE_IF_SCSI = 0x010, 291 DEVSTAT_TYPE_IF_IDE = 0x020, 292 DEVSTAT_TYPE_IF_OTHER = 0x030, 293 DEVSTAT_TYPE_IF_MASK = 0x0f0, 294 DEVSTAT_TYPE_PASS = 0x100 295} devstat_type_flags; 296.Ed 297.Pp 298Devices have a priority associated with them, which controls roughly where 299they are placed in the 300.Nm 301list. The priorities are as follows: 302.Bd -literal -offset indent 303typedef enum { 304 DEVSTAT_PRIORITY_MIN = 0x000, 305 DEVSTAT_PRIORITY_OTHER = 0x020, 306 DEVSTAT_PRIORITY_PASS = 0x030, 307 DEVSTAT_PRIORITY_FD = 0x040, 308 DEVSTAT_PRIORITY_WFD = 0x050, 309 DEVSTAT_PRIORITY_TAPE = 0x060, 310 DEVSTAT_PRIORITY_CD = 0x090, 311 DEVSTAT_PRIORITY_DISK = 0x110, 312 DEVSTAT_PRIORITY_ARRAY = 0x120, 313 DEVSTAT_PRIORITY_MAX = 0xfff 314} devstat_priority; 315.Ed 316.Pp 317Each device has associated with it flags to indicate what operations are 318supported or not supported. The 319.Va devstat_support_flags 320values are as follows: 321.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS 322.It DEVSTAT_ALL_SUPPORTED 323Every statistic type is supported by the device. 324.It DEVSTAT_NO_BLOCKSIZE 325This device does not have a blocksize. 326.It DEVSTAT_NO_ORDERED_TAGS 327This device does not support ordered tags. 328.It DEVSTAT_BS_UNAVAILABLE 329This device supports a blocksize, but it is currently unavailable. This 330flag is most often used with removable media drives. 331.El 332.Pp 333Transactions to a device fall into one of three categories, which are 334represented in the 335.Va flags 336passed into 337.Fn devstat_end_transaction . 338The transaction types are as follows: 339.Bd -literal -offset indent 340typedef enum { 341 DEVSTAT_NO_DATA = 0x00, 342 DEVSTAT_READ = 0x01, 343 DEVSTAT_WRITE = 0x02, 344 DEVSTAT_FREE = 0x03 345} devstat_trans_flags; 346.Ed 347.Pp 348There are four possible values for the 349.Va tag_type 350argument to 351.Fn devstat_end_transaction : 352.Bl -tag -width DEVSTAT_TAG_ORDERED 353.It DEVSTAT_TAG_SIMPLE 354The transaction had a simple tag. 355.It DEVSTAT_TAG_HEAD 356The transaction had a head of queue tag. 357.It DEVSTAT_TAG_ORDERED 358The transaction had an ordered tag. 359.It DEVSTAT_TAG_NONE 360The device doesn't support tags. 361.El 362.Pp 363The tag type values correspond to the lower four bits of the 364.Tn SCSI 365tag definitions. In CAM, for instance, the 366.Va tag_action 367from the CCB is ORed with 0xf to determine the tag type to pass in to 368.Fn devstat_end_transaction . 369.Pp 370There is a macro, 371.Dv DEVSTAT_VERSION 372that is defined in 373.Aq sys/devicestat.h . 374This is the current version of the 375.Nm 376subsystem, and it should be incremented each time a change is made that 377would require recompilation of userland programs that access 378.Nm 379statistics. Userland programs use this version, via the 380.Va kern.devstat.version 381.Nm sysctl 382variable to determine whether they are in sync with the kernel 383.Nm 384structures. 385.Sh SEE ALSO 386.Xr systat 1 , 387.Xr devstat 3 , 388.Xr iostat 8 , 389.Xr rpc.rstatd 8 , 390.Xr vmstat 8 391.Sh HISTORY 392The 393.Nm 394statistics system appeared in 395.Fx 3.0 . 396.Sh AUTHORS 397.An Kenneth Merry Aq ken@FreeBSD.org 398.Sh BUGS 399There may be a need for 400.Fn spl 401protection around some of the 402.Nm 403list manipulation code to insure, for example, that the list of devices 404is not changed while someone is fetching the 405.Va kern.devstat.all 406.Nm sysctl 407variable. 408.Pp 409It is impossible with the current 410.Nm 411architecture to accurately measure time per transaction. The only feasible 412way to accurately measure time per transaction would be to record a 413timestamp for every transaction. This measurement is probably not 414worthwhile for most people as it would adversely affect the performance of 415the system and cost space to store the timestamps for individual 416transactions. 417