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.5 2007/05/17 08:19:02 swildner 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 passthrough 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 160.Fn biodone . 161.Pp 162The 163.Va devstat 164structure is composed of the following fields: 165.Bl -tag -width dev_creation_time 166.It dev_links 167Each 168.Va devstat 169structure is placed in a linked list when it is registered. The 170.Va dev_links 171field contains a pointer to the next entry in the list of 172.Va devstat 173structures. 174.It device_number 175The device number is a unique identifier for each device. The device 176number is incremented for each new device that is registered. The device 177number is currently only a 32-bit integer, but it could be enlarged if 178someone has a system with more than four billion device arrival events. 179.It device_name 180The device name is a text string given by the registering driver to 181identify itself. (e.g.\& 182.Dq da , 183.Dq cd , 184.Dq sa , 185etc.) 186.It unit_number 187The unit number identifies the particular instance of the peripheral driver 188in question. 189.It bytes_written 190This is the number of bytes that have been written to the device. This 191number is currently an unsigned 64 bit integer. This will hopefully 192eliminate the counter wrap that would come very quickly on some systems if 19332 bit integers were used. 194.It bytes_read 195This is the number of bytes that have been read from the device. 196.It bytes_freed 197This is the number of bytes that have been freed/erased on the device. 198.It num_reads 199This is the number of reads from the device. 200.It num_writes 201This is the number of writes to the device. 202.It num_frees 203This is the number of free/erase operations on the device. 204.It num_other 205This is the number of transactions to the device which are neither reads or 206writes. For instance, 207.Tn SCSI 208drivers often send a test unit ready command to 209.Tn SCSI 210devices. The test unit ready command does not read or write any data. It 211merely causes the device to return its status. 212.It busy_count 213This is the current number of outstanding transactions for the device. 214This should never go below zero, and on an idle device it should be zero. 215If either one of these conditions is not true, it indicates a problem in 216the way 217.Fn devstat_start_transaction 218and 219.Fn devstat_end_transaction 220are being called in client code. There should be one and only one 221transaction start event and one transaction end event for each transaction. 222.It block_size 223This is the block size of the device, if the device has a block size. 224.It tag_types 225This is an array of counters to record the number of various tag types that 226are sent to a device. See below for a list of tag types. 227.It dev_creation_time 228This is the time, as reported by 229.Fn getmicrotime 230that the device was registered. 231.It busy_time 232This is the amount of time that the device busy count has been greater than 233zero. This is only updated when the busy count returns to zero. 234.It start_time 235This is the time, as reported by 236.Fn getmicrouptime 237that the device busy count went from zero to one. 238.It last_comp_time 239This is the time as reported by 240.Fn getmicrouptime 241that a transaction last completed. It is used along with 242.Va start_time 243to calculate the device busy time. 244.It flags 245These flags indicate which statistics measurements are supported by a 246particular device. These flags are primarily intended to serve as an aid 247to userland programs that decipher the statistics. 248.It device_type 249This is the device type. It consists of three parts: the device type 250(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE, 251SCSI or other) and whether or not the device in question is a passthrough 252driver. See below for a complete list of device types. 253.It priority 254This is the priority. This is the first parameter used to determine where 255to insert a device in the 256.Nm 257list. The second parameter is attach order. See below for a list of 258available priorities. 259.El 260.Pp 261Each device is given a device type. Passthrough devices have the same 262underlying device type and interface as the device they provide an 263interface for, but they also have the passthrough flag set. The base 264device types are identical to the 265.Tn SCSI 266device type numbers, so with 267.Tn SCSI 268peripherals, the device type returned from an inquiry is usually ORed with 269the 270.Tn SCSI 271interface type and the passthrough flag if appropriate. The device type 272flags are as follows: 273.Bd -literal -offset indent 274typedef enum { 275 DEVSTAT_TYPE_DIRECT = 0x000, 276 DEVSTAT_TYPE_SEQUENTIAL = 0x001, 277 DEVSTAT_TYPE_PRINTER = 0x002, 278 DEVSTAT_TYPE_PROCESSOR = 0x003, 279 DEVSTAT_TYPE_WORM = 0x004, 280 DEVSTAT_TYPE_CDROM = 0x005, 281 DEVSTAT_TYPE_SCANNER = 0x006, 282 DEVSTAT_TYPE_OPTICAL = 0x007, 283 DEVSTAT_TYPE_CHANGER = 0x008, 284 DEVSTAT_TYPE_COMM = 0x009, 285 DEVSTAT_TYPE_ASC0 = 0x00a, 286 DEVSTAT_TYPE_ASC1 = 0x00b, 287 DEVSTAT_TYPE_STORARRAY = 0x00c, 288 DEVSTAT_TYPE_ENCLOSURE = 0x00d, 289 DEVSTAT_TYPE_FLOPPY = 0x00e, 290 DEVSTAT_TYPE_MASK = 0x00f, 291 DEVSTAT_TYPE_IF_SCSI = 0x010, 292 DEVSTAT_TYPE_IF_IDE = 0x020, 293 DEVSTAT_TYPE_IF_OTHER = 0x030, 294 DEVSTAT_TYPE_IF_MASK = 0x0f0, 295 DEVSTAT_TYPE_PASS = 0x100 296} devstat_type_flags; 297.Ed 298.Pp 299Devices have a priority associated with them, which controls roughly where 300they are placed in the 301.Nm 302list. The priorities are as follows: 303.Bd -literal -offset indent 304typedef enum { 305 DEVSTAT_PRIORITY_MIN = 0x000, 306 DEVSTAT_PRIORITY_OTHER = 0x020, 307 DEVSTAT_PRIORITY_PASS = 0x030, 308 DEVSTAT_PRIORITY_FD = 0x040, 309 DEVSTAT_PRIORITY_WFD = 0x050, 310 DEVSTAT_PRIORITY_TAPE = 0x060, 311 DEVSTAT_PRIORITY_CD = 0x090, 312 DEVSTAT_PRIORITY_DISK = 0x110, 313 DEVSTAT_PRIORITY_ARRAY = 0x120, 314 DEVSTAT_PRIORITY_MAX = 0xfff 315} devstat_priority; 316.Ed 317.Pp 318Each device has associated with it flags to indicate what operations are 319supported or not supported. The 320.Va devstat_support_flags 321values are as follows: 322.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS 323.It DEVSTAT_ALL_SUPPORTED 324Every statistic type is supported by the device. 325.It DEVSTAT_NO_BLOCKSIZE 326This device does not have a blocksize. 327.It DEVSTAT_NO_ORDERED_TAGS 328This device does not support ordered tags. 329.It DEVSTAT_BS_UNAVAILABLE 330This device supports a blocksize, but it is currently unavailable. This 331flag is most often used with removable media drives. 332.El 333.Pp 334Transactions to a device fall into one of three categories, which are 335represented in the 336.Va flags 337passed into 338.Fn devstat_end_transaction . 339The transaction types are as follows: 340.Bd -literal -offset indent 341typedef enum { 342 DEVSTAT_NO_DATA = 0x00, 343 DEVSTAT_READ = 0x01, 344 DEVSTAT_WRITE = 0x02, 345 DEVSTAT_FREE = 0x03 346} devstat_trans_flags; 347.Ed 348.Pp 349There are four possible values for the 350.Va tag_type 351argument to 352.Fn devstat_end_transaction : 353.Bl -tag -width DEVSTAT_TAG_ORDERED 354.It DEVSTAT_TAG_SIMPLE 355The transaction had a simple tag. 356.It DEVSTAT_TAG_HEAD 357The transaction had a head of queue tag. 358.It DEVSTAT_TAG_ORDERED 359The transaction had an ordered tag. 360.It DEVSTAT_TAG_NONE 361The device doesn't support tags. 362.El 363.Pp 364The tag type values correspond to the lower four bits of the 365.Tn SCSI 366tag definitions. In CAM, for instance, the 367.Va tag_action 368from the CCB is ORed with 0xf to determine the tag type to pass in to 369.Fn devstat_end_transaction . 370.Pp 371There is a macro, 372.Dv DEVSTAT_VERSION 373that is defined in 374.In sys/devicestat.h . 375This is the current version of the 376.Nm 377subsystem, and it should be incremented each time a change is made that 378would require recompilation of userland programs that access 379.Nm 380statistics. Userland programs use this version, via the 381.Va kern.devstat.version 382.Nm sysctl 383variable to determine whether they are in sync with the kernel 384.Nm 385structures. 386.Sh SEE ALSO 387.Xr systat 1 , 388.Xr devstat 3 , 389.Xr iostat 8 , 390.Xr rpc.rstatd 8 , 391.Xr vmstat 8 392.Sh HISTORY 393The 394.Nm 395statistics system appeared in 396.Fx 3.0 . 397.Sh AUTHORS 398.An Kenneth Merry Aq ken@FreeBSD.org 399.Sh BUGS 400There may be a need for some of the list manipulation code to be 401inside a critical section to ensure, for example, that the list of devices 402is not changed while someone is fetching the 403.Va kern.devstat.all 404.Nm sysctl 405variable. 406.Pp 407It is impossible with the current 408.Nm 409architecture to accurately measure time per transaction. The only feasible 410way to accurately measure time per transaction would be to record a 411timestamp for every transaction. This measurement is probably not 412worthwhile for most people as it would adversely affect the performance of 413the system and cost space to store the timestamps for individual 414transactions. 415