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