| devstat.9 (119964) | devstat.9 (121380) |
|---|---|
| 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.\" | 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 119964 2003-09-10 19:24:35Z ru $ | 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 | 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. The idea is to keep reasonably detailed | 71statistics, as its name implies. 72The 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 76code. Instead, that is left for user programs to handle. 77.Pp 78.Fn devstat_add_entry 79registers a device with the 80.Nm | 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 |
| 81subsystem. The caller is expected to have already allocated \fBand zeroed\fR | 82subsystem. 83The 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 | 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 |
| 95Block size of the device, if supported. If the device does not support a | 97Block size of the device, if supported. 98If 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 | 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 |
| 101Flags indicating operations supported or not supported by the device. See 102below for details. | 104Flags indicating operations supported or not supported by the device. 105See below for details. |
| 103.It device_type | 106.It device_type |
| 104The device type. This is broken into three sections: base device type | 107The device type. 108This is broken into three sections: base device type |
| 105(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI | 109(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI |
| 106or other) and a pass-through flag to indicate pas-through devices. See below 107for a complete list of types. | 110or other) and a pass-through flag to indicate pas-through devices. 111See below for a complete list of types. |
| 108.It priority | 112.It priority |
| 109The device priority. The priority is used to determine how devices are | 113The device priority. 114The priority is used to determine how devices are |
| 110sorted within 111.Nm devstat Ns 's | 115sorted within 116.Nm devstat Ns '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 | 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 |
| 114priorities. 115.El 116.Pp 117.Fn devstat_remove_entry 118removes a device from the 119.Nm | 121priorities. 122.El 123.Pp 124.Fn devstat_remove_entry 125removes a device from the 126.Nm |
| 120subsystem. It takes the devstat structure for the device in question as 121an argument. The | 127subsystem. 128It takes the devstat structure for the device in question as 129an argument. 130The |
| 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 | 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 |
| 128subsystem. The busy count is incremented with each transaction start. | 137subsystem. 138The 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 | 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 |
| 138subsystem. It takes four arguments: | 148subsystem. 149It 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 | 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 |
| 147Transaction tag type. See below for tag types. | 158Transaction tag type. 159See 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_bio 154is a wrapper for 155.Fn devstat_end_transaction 156which pulls all the information from a 157.Va "struct bio" 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 | 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 |
| 167structure is placed in a linked list when it is registered. The | 179structure is placed in a linked list when it is registered. 180The |
| 168.Va dev_links 169field contains a pointer to the next entry in the list of 170.Va devstat 171structures. 172.It device_number | 181.Va dev_links 182field contains a pointer to the next entry in the list of 183.Va devstat 184structures. 185.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 | 186The device number is a unique identifier for each device. 187The device 188number is incremented for each new device that is registered. 189The 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 | 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 |
| 179identify itself. (e.g.\& | 194identify itself. 195(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 | 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 |
| 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 | 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 |
| 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 | 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 |
| 204writes. For instance, | 221writes. 222For instance, |
| 205.Tn SCSI 206drivers often send a test unit ready command to 207.Tn SCSI | 223.Tn SCSI 224drivers often send a test unit ready command to 225.Tn SCSI |
| 208devices. The test unit ready command does not read or write any data. It 209merely causes the device to return its status. | 226devices. 227The test unit ready command does not read or write any data. 228It merely 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 | 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 |
| 218are being called in client code. There should be one and only one | 237are being called in client code. 238There 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 | 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 |
| 224are sent to a device. See below for a list of tag types. | 244are sent to a device. 245See 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 | 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 |
| 231zero. This is only updated when the busy count returns to zero. | 252zero. 253This 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 | 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 |
| 239that a transaction last completed. It is used along with | 261that a transaction last completed. 262It 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 | 263.Va start_time 264to calculate the device busy time. 265.It flags 266These flags indicate which statistics measurements are supported by a |
| 244particular device. These flags are primarily intended to serve as an aid | 267particular device. 268These flags are primarily intended to serve as an aid |
| 245to userland programs that decipher the statistics. 246.It device_type | 269to userland programs that decipher the statistics. 270.It device_type |
| 247This is the device type. It consists of three parts: the device type | 271This is the device type. 272It 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 pass-through | 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 |
| 250driver. See below for a complete list of device types. | 275driver. 276See below for a complete list of device types. |
| 251.It priority | 277.It priority |
| 252This is the priority. This is the first parameter used to determine where | 278This is the priority. 279This is the first parameter used to determine where |
| 253to insert a device in the 254.Nm | 280to insert a device in the 281.Nm |
| 255list. The second parameter is attach order. See below for a list of | 282list. 283The second parameter is attach order. 284See below for a list of |
| 256available priorities. 257.El 258.Pp | 285available priorities. 286.El 287.Pp |
| 259Each device is given a device type. Pass-through devices have the same | 288Each device is given a device type. 289Pass-through devices have the same |
| 260underlying device type and interface as the device they provide an | 290underlying device type and interface as the device they provide an |
| 261interface for, but they also have the pass-through flag set. The base | 291interface for, but they also have the pass-through flag set. 292The 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 | 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 |
| 269interface type and the pass-through flag if appropriate. The device type | 300interface type and the pass-through flag if appropriate. 301The 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, --- 14 unchanged lines hidden (view full) --- 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 | 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 |
| 300list. The priorities are as follows: | 332list. 333The 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_TAPE = 0x060, 309 DEVSTAT_PRIORITY_CD = 0x090, 310 DEVSTAT_PRIORITY_DISK = 0x110, 311 DEVSTAT_PRIORITY_ARRAY = 0x120, 312 DEVSTAT_PRIORITY_MAX = 0xfff 313} devstat_priority; 314.Ed 315.Pp 316Each device has associated with it flags to indicate what operations are | 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 |
| 317supported or not supported. The | 350supported or not supported. 351The |
| 318.Va devstat_support_flags 319values are as follows: 320.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS 321.It DEVSTAT_ALL_SUPPORTED 322Every statistic type is supported by the device. 323.It DEVSTAT_NO_BLOCKSIZE 324This device does not have a blocksize. 325.It DEVSTAT_NO_ORDERED_TAGS 326This device does not support ordered tags. 327.It DEVSTAT_BS_UNAVAILABLE | 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 |
| 328This device supports a blocksize, but it is currently unavailable. This | 362This device supports a blocksize, but it is currently unavailable. 363This |
| 329flag is most often used with removable media drives. 330.El 331.Pp 332Transactions to a device fall into one of three categories, which are 333represented in the 334.Va flags 335passed into 336.Fn devstat_end_transaction . --- 19 unchanged lines hidden (view full) --- 356.It DEVSTAT_TAG_ORDERED 357The transaction had an ordered tag. 358.It DEVSTAT_TAG_NONE 359The device doesn't support tags. 360.El 361.Pp 362The tag type values correspond to the lower four bits of the 363.Tn SCSI | 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 |
| 364tag definitions. In CAM, for instance, the | 399tag definitions. 400In CAM, for instance, the |
| 365.Va tag_action 366from the CCB is ORed with 0xf to determine the tag type to pass in to 367.Fn devstat_end_transaction . 368.Pp 369There is a macro, 370.Dv DEVSTAT_VERSION 371that is defined in 372.In sys/devicestat.h . 373This is the current version of the 374.Nm 375subsystem, and it should be incremented each time a change is made that 376would require recompilation of userland programs that access 377.Nm | 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 |
| 378statistics. Userland programs use this version, via the | 414statistics. 415Userland programs use this version, via the |
| 379.Va kern.devstat.version 380.Nm sysctl 381variable to determine whether they are in sync with the kernel 382.Nm 383structures. 384.Sh SEE ALSO 385.Xr systat 1 , 386.Xr devstat 3 , --- 15 unchanged lines hidden (view full) --- 402list manipulation code to insure, for example, that the list of devices 403is not changed while someone is fetching the 404.Va kern.devstat.all 405.Nm sysctl 406variable. 407.Pp 408It is impossible with the current 409.Nm | 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 |
| 410architecture to accurately measure time per transaction. The only feasible | 447architecture to accurately measure time per transaction. 448The only feasible |
| 411way to accurately measure time per transaction would be to record a | 449way to accurately measure time per transaction would be to record a |
| 412timestamp for every transaction. This measurement is probably not | 450timestamp for every transaction. 451This measurement is probably not |
| 413worthwhile for most people as it would adversely affect the performance of 414the system and cost space to store the timestamps for individual 415transactions. | 452worthwhile for most people as it would adversely affect the performance of 453the system and cost space to store the timestamps for individual 454transactions. |