| 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 --- 11 unchanged lines hidden (view full) --- 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: head/share/man/man9/devstat.9 121380 2003-10-23 01:54:06Z hmp $ |
| 29.\" 30.Dd May 22, 1998 31.Dt DEVSTAT 9 32.Os 33.Sh NAME 34.Nm devstat , 35.Nm devstat_add_entry , 36.Nm devstat_end_transaction , --- 26 unchanged lines hidden (view full) --- 63.Fc 64.Ft void 65.Fo devstat_end_transaction_bio 66.Fa "struct devstat *ds" 67.Fa "struct bio *bp" 68.Fc 69.Sh DESCRIPTION 70The devstat subsystem is an interface for recording device |
| 71statistics, as its name implies. 72The 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. 83The caller is expected to have already allocated \fBand zeroed\fR |
| 84the devstat structure before calling this function. 85.Fn devstat_add_entry 86takes several arguments: 87.Bl -tag -width device_type 88.It ds 89The 90.Va devstat 91structure, allocated and zeroed by the client. 92.It dev_name 93The device name. e.g. da, cd, sa. 94.It unit_number 95Device unit number. 96.It block_size |
| 97Block size of the device, if supported. 98If the device does not support a |
| 99block size, or if the blocksize is unknown at the time the device is added 100to the 101.Nm 102list, it should be set to 0. 103.It flags |
| 104Flags indicating operations supported or not supported by the device. 105See below for details. |
| 106.It device_type |
| 107The device type. 108This is broken into three sections: base device type |
| 109(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI |
| 110or other) and a pass-through flag to indicate pas-through devices. 111See below for a complete list of types. |
| 112.It priority |
| 113The device priority. 114The priority is used to determine how devices are |
| 115sorted within 116.Nm devstat Ns 's |
| 117list of devices. 118Devices are sorted first by priority (highest to lowest), 119and then by attach order. 120See below for a complete list of available |
| 121priorities. 122.El 123.Pp 124.Fn devstat_remove_entry 125removes a device from the 126.Nm |
| 127subsystem. 128It takes the devstat structure for the device in question as 129an argument. 130The |
| 131.Nm 132generation number is incremented and the number of devices is decremented. 133.Pp 134.Fn devstat_start_transaction 135registers the start of a transaction with the 136.Nm |
| 137subsystem. 138The busy count is incremented with each transaction start. |
| 139When a device goes from idle to busy, the system uptime is recorded in the 140.Va start_time 141field of the 142.Va devstat 143structure. 144.Pp 145.Fn devstat_end_transaction 146registers the end of a transaction with the 147.Nm |
| 148subsystem. 149It takes four arguments: |
| 150.Bl -tag -width tag_type 151.It ds 152The 153.Va devstat 154structure for the device in question. 155.It bytes 156The number of bytes transferred in this transaction. 157.It tag_type |
| 158Transaction tag type. 159See below for tag types. |
| 160.It flags 161Transaction flags indicating whether the transaction was a read, write, or 162whether no data was transferred. 163.El 164.Pp 165.Fn devstat_end_transaction_bio 166is a wrapper for 167.Fn devstat_end_transaction 168which pulls all the information from a 169.Va "struct bio" 170which is ready for biodone(). 171.Pp 172The 173.Va devstat 174structure is composed of the following fields: 175.Bl -tag -width dev_creation_time 176.It dev_links 177Each 178.Va devstat |
| 179structure is placed in a linked list when it is registered. 180The |
| 181.Va dev_links 182field contains a pointer to the next entry in the list of 183.Va devstat 184structures. 185.It device_number |
| 186The device number is a unique identifier for each device. 187The device 188number is incremented for each new device that is registered. 189The device |
| 190number is currently only a 32-bit integer, but it could be enlarged if 191someone has a system with more than four billion device arrival events. 192.It device_name 193The device name is a text string given by the registering driver to |
| 194identify itself. 195(e.g.\& |
| 196.Dq da , 197.Dq cd , 198.Dq sa , 199etc.) 200.It unit_number 201The unit number identifies the particular instance of the peripheral driver 202in question. 203.It bytes_written |
| 204This is the number of bytes that have been written to the device. 205This number is currently an unsigned 64 bit integer. 206This will hopefully |
| 207eliminate the counter wrap that would come very quickly on some systems if 20832 bit integers were used. 209.It bytes_read 210This is the number of bytes that have been read from the device. 211.It bytes_freed 212This is the number of bytes that have been freed/erased on the device. 213.It num_reads 214This is the number of reads from the device. 215.It num_writes 216This is the number of writes to the device. 217.It num_frees 218This is the number of free/erase operations on the device. 219.It num_other 220This is the number of transactions to the device which are neither reads or |
| 221writes. 222For instance, |
| 223.Tn SCSI 224drivers often send a test unit ready command to 225.Tn SCSI |
| 226devices. 227The test unit ready command does not read or write any data. 228It merely causes the device to return its status. |
| 229.It busy_count 230This is the current number of outstanding transactions for the device. 231This should never go below zero, and on an idle device it should be zero. 232If either one of these conditions is not true, it indicates a problem in 233the way 234.Fn devstat_start_transaction 235and 236.Fn devstat_end_transaction |
| 237are being called in client code. 238There should be one and only one |
| 239transaction start event and one transaction end event for each transaction. 240.It block_size 241This is the block size of the device, if the device has a block size. 242.It tag_types 243This is an array of counters to record the number of various tag types that |
| 244are sent to a device. 245See below for a list of tag types. |
| 246.It dev_creation_time 247This is the time, as reported by 248.Fn getmicrotime 249that the device was registered. 250.It busy_time 251This is the amount of time that the device busy count has been greater than |
| 252zero. 253This is only updated when the busy count returns to zero. |
| 254.It start_time 255This is the time, as reported by 256.Fn getmicrouptime 257that the device busy count went from zero to one. 258.It last_comp_time 259This is the time as reported by 260.Fn getmicrouptime |
| 261that a transaction last completed. 262It is used along with |
| 263.Va start_time 264to calculate the device busy time. 265.It flags 266These flags indicate which statistics measurements are supported by a |
| 267particular device. 268These flags are primarily intended to serve as an aid |
| 269to userland programs that decipher the statistics. 270.It device_type |
| 271This is the device type. 272It consists of three parts: the device type |
| 273(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE, 274SCSI or other) and whether or not the device in question is a pass-through |
| 275driver. 276See below for a complete list of device types. |
| 277.It priority |
| 278This is the priority. 279This is the first parameter used to determine where |
| 280to insert a device in the 281.Nm |
| 282list. 283The second parameter is attach order. 284See below for a list of |
| 285available priorities. 286.El 287.Pp |
| 288Each device is given a device type. 289Pass-through devices have the same |
| 290underlying device type and interface as the device they provide an |
| 291interface for, but they also have the pass-through flag set. 292The base |
| 293device types are identical to the 294.Tn SCSI 295device type numbers, so with 296.Tn SCSI 297peripherals, the device type returned from an inquiry is usually ORed with 298the 299.Tn SCSI |
| 300interface type and the pass-through flag if appropriate. 301The device type |
| 302flags are as follows: 303.Bd -literal -offset indent 304typedef enum { 305 DEVSTAT_TYPE_DIRECT = 0x000, 306 DEVSTAT_TYPE_SEQUENTIAL = 0x001, 307 DEVSTAT_TYPE_PRINTER = 0x002, 308 DEVSTAT_TYPE_PROCESSOR = 0x003, 309 DEVSTAT_TYPE_WORM = 0x004, --- 14 unchanged lines hidden (view full) --- 324 DEVSTAT_TYPE_IF_MASK = 0x0f0, 325 DEVSTAT_TYPE_PASS = 0x100 326} devstat_type_flags; 327.Ed 328.Pp 329Devices have a priority associated with them, which controls roughly where 330they are placed in the 331.Nm |
| 332list. 333The priorities are as follows: |
| 334.Bd -literal -offset indent 335typedef enum { 336 DEVSTAT_PRIORITY_MIN = 0x000, 337 DEVSTAT_PRIORITY_OTHER = 0x020, 338 DEVSTAT_PRIORITY_PASS = 0x030, 339 DEVSTAT_PRIORITY_FD = 0x040, 340 DEVSTAT_PRIORITY_WFD = 0x050, 341 DEVSTAT_PRIORITY_TAPE = 0x060, 342 DEVSTAT_PRIORITY_CD = 0x090, 343 DEVSTAT_PRIORITY_DISK = 0x110, 344 DEVSTAT_PRIORITY_ARRAY = 0x120, 345 DEVSTAT_PRIORITY_MAX = 0xfff 346} devstat_priority; 347.Ed 348.Pp 349Each device has associated with it flags to indicate what operations are |
| 350supported or not supported. 351The |
| 352.Va devstat_support_flags 353values are as follows: 354.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS 355.It DEVSTAT_ALL_SUPPORTED 356Every statistic type is supported by the device. 357.It DEVSTAT_NO_BLOCKSIZE 358This device does not have a blocksize. 359.It DEVSTAT_NO_ORDERED_TAGS 360This device does not support ordered tags. 361.It DEVSTAT_BS_UNAVAILABLE |
| 362This device supports a blocksize, but it is currently unavailable. 363This |
| 364flag is most often used with removable media drives. 365.El 366.Pp 367Transactions to a device fall into one of three categories, which are 368represented in the 369.Va flags 370passed into 371.Fn devstat_end_transaction . --- 19 unchanged lines hidden (view full) --- 391.It DEVSTAT_TAG_ORDERED 392The transaction had an ordered tag. 393.It DEVSTAT_TAG_NONE 394The device doesn't support tags. 395.El 396.Pp 397The tag type values correspond to the lower four bits of the 398.Tn SCSI |
| 399tag definitions. 400In CAM, for instance, the |
| 401.Va tag_action 402from the CCB is ORed with 0xf to determine the tag type to pass in to 403.Fn devstat_end_transaction . 404.Pp 405There is a macro, 406.Dv DEVSTAT_VERSION 407that is defined in 408.In sys/devicestat.h . 409This is the current version of the 410.Nm 411subsystem, and it should be incremented each time a change is made that 412would require recompilation of userland programs that access 413.Nm |
| 414statistics. 415Userland programs use this version, via the |
| 416.Va kern.devstat.version 417.Nm sysctl 418variable to determine whether they are in sync with the kernel 419.Nm 420structures. 421.Sh SEE ALSO 422.Xr systat 1 , 423.Xr devstat 3 , --- 15 unchanged lines hidden (view full) --- 439list manipulation code to insure, for example, that the list of devices 440is not changed while someone is fetching the 441.Va kern.devstat.all 442.Nm sysctl 443variable. 444.Pp 445It is impossible with the current 446.Nm |
| 447architecture to accurately measure time per transaction. 448The only feasible |
| 449way to accurately measure time per transaction would be to record a |
| 450timestamp for every transaction. 451This measurement is probably not |
| 452worthwhile for most people as it would adversely affect the performance of 453the system and cost space to store the timestamps for individual 454transactions. |