share/man/man9/devstat.9

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