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: 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
  71 The devstat subsystem is an interface for recording device
  72 statistics, as its name implies.  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.  The caller is expected to have already allocated \fBand zeroed\fR
  83 the devstat structure before calling this function.
  84 .Fn devstat_add_entry
  85 takes several arguments:
  86 .Bl -tag -width device_type
  87 .It ds
  88 The
  89 .Va devstat
  90 structure, allocated and zeroed by the client.
  91 .It dev_name
  92 The device name. e.g. da, cd, sa.
  93 .It unit_number
  94 Device unit number.
  95 .It block_size
  96 Block size of the device, if supported.  If the device does not support a
  97 block size, or if the blocksize is unknown at the time the device is added
  98 to the
  99 .Nm
 100 list, it should be set to 0.
 101 .It flags
 102 Flags indicating operations supported or not supported by the device.  See
 103 below for details.
 104 .It device_type
 105 The device type.  This is broken into three sections:  base device type
 106 (e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI
 107 or other) and a passthrough flag to indicate passthrough devices.  See below
 108 for a complete list of types.
 109 .It priority
 110 The device priority.  The priority is used to determine how devices are
 111 sorted within
 112 .Nm devstat Ns 's
 113 list of devices.  Devices are sorted first by priority (highest to lowest),
 114 and then by attach order.  See below for a complete list of available
 115 priorities.
 116 .El
 117 .Pp
 118 .Fn devstat_remove_entry
 119 removes a device from the
 120 .Nm
 121 subsystem.  It takes the devstat structure for the device in question as
 122 an argument.  The
 123 .Nm
 124 generation number is incremented and the number of devices is decremented.
 125 .Pp
 126 .Fn devstat_start_transaction
 127 registers the start of a transaction with the
 128 .Nm
 129 subsystem.  The busy count is incremented with each transaction start.
 130 When a device goes from idle to busy, the system uptime is recorded in the
 131 .Va start_time
 132 field of the
 133 .Va devstat
 134 structure.
 135 .Pp
 136 .Fn devstat_end_transaction
 137 registers the end of a transaction with the
 138 .Nm
 139 subsystem.  It takes four arguments:
 140 .Bl -tag -width tag_type
 141 .It ds
 142 The
 143 .Va devstat
 144 structure for the device in question.
 145 .It bytes
 146 The number of bytes transferred in this transaction.
 147 .It tag_type
 148 Transaction tag type.  See below for tag types.
 149 .It flags
 150 Transaction flags indicating whether the transaction was a read, write, or
 151 whether no data was transferred.
 152 .El
 153 .Pp
 154 .Fn devstat_end_transaction_buf
 155 is a wrapper for
 156 .Fn devstat_end_transaction
 157 which pulls all the information from a
 158 .Va "struct buf"
 159 which is ready for
 160 .Fn biodone .
 161 .Pp
 162 The
 163 .Va devstat
 164 structure is composed of the following fields:
 165 .Bl -tag -width dev_creation_time
 166 .It dev_links
 167 Each
 168 .Va devstat
 169 structure is placed in a linked list when it is registered.  The
 170 .Va dev_links
 171 field contains a pointer to the next entry in the list of
 172 .Va devstat
 173 structures.
 174 .It device_number
 175 The device number is a unique identifier for each device.  The device
 176 number is incremented for each new device that is registered.  The device
 177 number is currently only a 32-bit integer, but it could be enlarged if
 178 someone has a system with more than four billion device arrival events.
 179 .It device_name
 180 The device name is a text string given by the registering driver to
 181 identify itself.  (e.g.\&
 182 .Dq da ,
 183 .Dq cd ,
 184 .Dq sa ,
 185 etc.)
 186 .It unit_number
 187 The unit number identifies the particular instance of the peripheral driver
 188 in question.
 189 .It bytes_written
 190 This is the number of bytes that have been written to the device.  This
 191 number is currently an unsigned 64 bit integer.  This will hopefully
 192 eliminate the counter wrap that would come very quickly on some systems if
 193 32 bit integers were used.
 194 .It bytes_read
 195 This is the number of bytes that have been read from the device.
 196 .It bytes_freed
 197 This is the number of bytes that have been freed/erased on the device.
 198 .It num_reads
 199 This is the number of reads from the device.
 200 .It num_writes
 201 This is the number of writes to the device.
 202 .It num_frees
 203 This is the number of free/erase operations on the device.
 204 .It num_other
 205 This is the number of transactions to the device which are neither reads or
 206 writes.  For instance,
 207 .Tn SCSI
 208 drivers often send a test unit ready command to
 209 .Tn SCSI
 210 devices.  The test unit ready command does not read or write any data.  It
 211 merely causes the device to return its status.
 212 .It busy_count
 213 This is the current number of outstanding transactions for the device.
 214 This should never go below zero, and on an idle device it should be zero.
 215 If either one of these conditions is not true, it indicates a problem in
 216 the way
 217 .Fn devstat_start_transaction
 218 and
 219 .Fn devstat_end_transaction
 220 are being called in client code.  There should be one and only one
 221 transaction start event and one transaction end event for each transaction.
 222 .It block_size
 223 This is the block size of the device, if the device has a block size.
 224 .It tag_types
 225 This is an array of counters to record the number of various tag types that
 226 are sent to a device.  See below for a list of tag types.
 227 .It dev_creation_time
 228 This is the time, as reported by
 229 .Fn getmicrotime
 230 that the device was registered.
 231 .It busy_time
 232 This is the amount of time that the device busy count has been greater than
 233 zero.  This is only updated when the busy count returns to zero.
 234 .It start_time
 235 This is the time, as reported by
 236 .Fn getmicrouptime
 237 that the device busy count went from zero to one.
 238 .It last_comp_time
 239 This is the time as reported by
 240 .Fn getmicrouptime
 241 that a transaction last completed.  It is used along with
 242 .Va start_time
 243 to calculate the device busy time.
 244 .It flags
 245 These flags indicate which statistics measurements are supported by a
 246 particular device.  These flags are primarily intended to serve as an aid
 247 to userland programs that decipher the statistics.
 248 .It device_type
 249 This is the device type.  It consists of three parts:  the device type
 250 (e.g. direct access, CDROM, sequential access, etc.), the interface (IDE,
 251 SCSI or other) and whether or not the device in question is a passthrough
 252 driver.  See below for a complete list of device types.
 253 .It priority
 254 This is the priority.  This is the first parameter used to determine where
 255 to insert a device in the
 256 .Nm
 257 list.  The second parameter is attach order.  See below for a list of
 258 available priorities.
 259 .El
 260 .Pp
 261 Each device is given a device type.  Passthrough devices have the same
 262 underlying device type and interface as the device they provide an
 263 interface for, but they also have the passthrough flag set.  The base
 264 device types are identical to the
 265 .Tn SCSI
 266 device type numbers, so with
 267 .Tn SCSI
 268 peripherals, the device type returned from an inquiry is usually ORed with
 269 the
 270 .Tn SCSI
 271 interface type and the passthrough flag if appropriate.  The device type
 272 flags are as follows:
 273 .Bd -literal -offset indent
 274 typedef 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
 299 Devices have a priority associated with them, which controls roughly where
 300 they are placed in the
 301 .Nm
 302 list.  The priorities are as follows:
 303 .Bd -literal -offset indent
 304 typedef 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
 318 Each device has associated with it flags to indicate what operations are
 319 supported or not supported.  The
 320 .Va devstat_support_flags
 321 values are as follows:
 322 .Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
 323 .It DEVSTAT_ALL_SUPPORTED
 324 Every statistic type is supported by the device.
 325 .It DEVSTAT_NO_BLOCKSIZE
 326 This device does not have a blocksize.
 327 .It DEVSTAT_NO_ORDERED_TAGS
 328 This device does not support ordered tags.
 329 .It DEVSTAT_BS_UNAVAILABLE
 330 This device supports a blocksize, but it is currently unavailable.  This
 331 flag is most often used with removable media drives.
 332 .El
 333 .Pp
 334 Transactions to a device fall into one of three categories, which are
 335 represented in the
 336 .Va flags
 337 passed into
 338 .Fn devstat_end_transaction .
 339 The transaction types are as follows:
 340 .Bd -literal -offset indent
 341 typedef 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
 349 There are four possible values for the
 350 .Va tag_type
 351 argument to
 352 .Fn devstat_end_transaction :
 353 .Bl -tag -width DEVSTAT_TAG_ORDERED
 354 .It DEVSTAT_TAG_SIMPLE
 355 The transaction had a simple tag.
 356 .It DEVSTAT_TAG_HEAD
 357 The transaction had a head of queue tag.
 358 .It DEVSTAT_TAG_ORDERED
 359 The transaction had an ordered tag.
 360 .It DEVSTAT_TAG_NONE
 361 The device doesn't support tags.
 362 .El
 363 .Pp
 364 The tag type values correspond to the lower four bits of the
 365 .Tn SCSI
 366 tag definitions.  In CAM, for instance, the
 367 .Va tag_action
 368 from the CCB is ORed with 0xf to determine the tag type to pass in to
 369 .Fn devstat_end_transaction .
 370 .Pp
 371 There is a macro,
 372 .Dv DEVSTAT_VERSION
 373 that is defined in
 374 .In sys/devicestat.h .
 375 This is the current version of the
 376 .Nm
 377 subsystem, and it should be incremented each time a change is made that
 378 would require recompilation of userland programs that access
 379 .Nm
 380 statistics.  Userland programs use this version, via the
 381 .Va kern.devstat.version
 382 .Nm sysctl
 383 variable to determine whether they are in sync with the kernel
 384 .Nm
 385 structures.
 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
 393 The
 394 .Nm
 395 statistics system appeared in
 396 .Fx 3.0 .
 397 .Sh AUTHORS
 398 .An Kenneth Merry Aq ken@FreeBSD.org
 399 .Sh BUGS
 400 There may be a need for some of the list manipulation code to be
 401 inside a critical section to ensure, for example, that the list of devices
 402 is not changed while someone is fetching the
 403 .Va kern.devstat.all
 404 .Nm sysctl
 405 variable.
 406 .Pp
 407 It is impossible with the current
 408 .Nm
 409 architecture to accurately measure time per transaction.  The only feasible
 410 way to accurately measure time per transaction would be to record a
 411 timestamp for every transaction.  This measurement is probably not
 412 worthwhile for most people as it would adversely affect the performance of
 413 the system and cost space to store the timestamps for individual
 414 transactions.