2 .\" Copyright (c) 1998, 1999 Kenneth D. Merry.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nm devstat_add_entry ,
36 .Nm devstat_end_transaction ,
37 .Nm devstat_end_transaction_bio ,
38 .Nm devstat_end_transaction_bio_bt ,
39 .Nm devstat_remove_entry ,
40 .Nm devstat_start_transaction ,
41 .Nm devstat_start_transaction_bio
42 .Nd kernel interface for keeping device statistics
47 .Fa "struct devstat *ds"
48 .Fa "const char *dev_name"
50 .Fa "uint32_t block_size"
51 .Fa "devstat_support_flags flags"
52 .Fa "devstat_type_flags device_type"
53 .Fa "devstat_priority priority"
56 .Fn devstat_remove_entry "struct devstat *ds"
58 .Fo devstat_start_transaction
59 .Fa "struct devstat *ds"
60 .Fa "const struct bintime *now"
63 .Fo devstat_start_transaction_bio
64 .Fa "struct devstat *ds"
68 .Fo devstat_end_transaction
69 .Fa "struct devstat *ds"
71 .Fa "devstat_tag_type tag_type"
72 .Fa "devstat_trans_flags flags"
73 .Fa "const struct bintime *now"
74 .Fa "const struct bintime *then"
77 .Fo devstat_end_transaction_bio
78 .Fa "struct devstat *ds"
79 .Fa "const struct bio *bp"
83 .Fo devstat_end_transaction_bio_bt
84 .Fa "struct devstat *ds"
85 .Fa "const struct bio *bp"
86 .Fa "const struct bintime *now"
89 The devstat subsystem is an interface for recording device
90 statistics, as its name implies.
91 The idea is to keep reasonably detailed
92 statistics while utilizing a minimum amount of CPU time to record them.
93 Thus, no statistical calculations are actually performed in the kernel
97 Instead, that is left for user programs to handle.
99 The historical and antiquated
101 model assumed a single active IO operation per device, which is not accurate
102 for most disk-like drivers in the 2000s and beyond.
103 New consumers of the interface should almost certainly use only the "bio"
104 variants of the start and end transacation routines.
106 .Fn devstat_add_entry
107 registers a device with the
110 The caller is expected to have already allocated \fBand zeroed\fR
111 the devstat structure before calling this function.
112 .Fn devstat_add_entry
113 takes several arguments:
114 .Bl -tag -width device_type
118 structure, allocated and zeroed by the client.
120 The device name, e.g., da, cd, sa.
124 Block size of the device, if supported.
125 If the device does not support a
126 block size, or if the blocksize is unknown at the time the device is added
129 list, it should be set to 0.
131 Flags indicating operations supported or not supported by the device.
132 See below for details.
135 This is broken into three sections: base device type
136 (e.g., direct access, CDROM, sequential access), interface type (IDE, SCSI
137 or other) and a pass-through flag to indicate pas-through devices.
138 See below for a complete list of types.
141 The priority is used to determine how devices are
145 Devices are sorted first by priority (highest to lowest),
146 and then by attach order.
147 See below for a complete list of available
151 .Fn devstat_remove_entry
152 removes a device from the
155 It takes the devstat structure for the device in question as
159 generation number is incremented and the number of devices is decremented.
161 .Fn devstat_start_transaction
162 registers the start of a transaction with the
165 Optionally, if the caller already has a
167 value available, it may be passed in
169 Usually the caller can just pass
173 and the routine will gather the current
176 The busy count is incremented with each transaction start.
177 When a device goes from idle to busy, the system uptime is recorded in the
183 .Fn devstat_start_transaction_bio
186 in the provided bio's
189 .Fn devstat_start_transaction .
191 .Fn devstat_end_transaction
192 registers the end of a transaction with the
195 It takes six arguments:
196 .Bl -tag -width tag_type
200 structure for the device in question.
202 The number of bytes transferred in this transaction.
204 Transaction tag type.
205 See below for tag types.
207 Transaction flags indicating whether the transaction was a read, write, or
208 whether no data was transferred.
212 at the end of the transaction, or
217 at the beginning of the transaction, or
225 it collects the current time from
231 the operation is not tracked in the
236 .Fn devstat_end_transaction_bio
237 is a thin wrapper for
238 .Fn devstat_end_transaction_bio_bt
244 .Fn devstat_end_transaction_bio_bt
246 .Fn devstat_end_transaction
247 which pulls all needed information from a
250 .Fn devstat_start_transaction_bio .
251 The bio must be ready for
257 must be correctly initialized).
261 structure is composed of the following fields:
262 .Bl -tag -width dev_creation_time
265 An implementation detail used to gather consistent snapshots of device
268 Number of operations started.
270 Number of operations completed.
273 can be calculated by subtracting
280 are used to get a consistent snapshot.)
281 This is the current number of outstanding transactions for the device.
282 This should never go below zero, and on an idle device it should be zero.
283 If either one of these conditions is not true, it indicates a problem.
285 There should be one and only one
286 transaction start event and one transaction end event for each transaction.
290 structure is placed in a linked list when it is registered.
293 field contains a pointer to the next entry in the list of
297 The device number is a unique identifier for each device.
299 number is incremented for each new device that is registered.
301 number is currently only a 32-bit integer, but it could be enlarged if
302 someone has a system with more than four billion device arrival events.
304 The device name is a text string given by the registering driver to
312 The unit number identifies the particular instance of the peripheral driver
315 This array contains the number of bytes that have been read (index
318 .Dv DEVSTAT_WRITE ) ,
319 freed or erased (index
322 .Dv DEVSTAT_NO_DATA ) .
323 All values are unsigned 64-bit integers.
325 This array contains the number of operations of a given type that have been
327 The indices are identical to those for
331 or "other" represents the number of transactions to the device which are
332 neither reads, writes, nor frees.
335 drivers often send a test unit ready command to
338 The test unit ready command does not read or write any data.
339 It merely causes the device to return its status.
341 This array contains the total bintime corresponding to completed operations of
343 The indices are identical to those for
346 (Operations that complete using the historical
347 .Fn devstat_end_transaction
348 API and do not provide a non-NULL
350 are not accounted for.)
352 This is the amount of time that the device busy count has been greater than
354 This is only updated when the busy count returns to zero.
356 This is the time, as reported by
358 that the device was registered.
360 This is the block size of the device, if the device has a block size.
362 This is an array of counters to record the number of various tag types that
363 are sent to a device.
364 See below for a list of tag types.
366 If the device is not busy, this was the time that a transaction last completed.
367 If the device is busy, this the most recent of either the time that the device
368 became busy, or the time that the last transaction completed.
370 These flags indicate which statistics measurements are supported by a
372 These flags are primarily intended to serve as an aid
373 to userland programs that decipher the statistics.
375 This is the device type.
376 It consists of three parts: the device type
377 (e.g., direct access, CDROM, sequential access, etc.), the interface (IDE,
378 SCSI or other) and whether or not the device in question is a pass-through
380 See below for a complete list of device types.
382 This is the priority.
383 This is the first parameter used to determine where
384 to insert a device in the
387 The second parameter is attach order.
388 See below for a list of available priorities.
391 Each device is given a device type.
392 Pass-through devices have the same underlying device type and interface as the
393 device they provide an interface for, but they also have the pass-through flag
395 The base device types are identical to the
397 device type numbers, so with
399 peripherals, the device type returned from an inquiry is usually ORed with the
401 interface type and the pass-through flag if appropriate.
403 flags are as follows:
404 .Bd -literal -offset indent
406 DEVSTAT_TYPE_DIRECT = 0x000,
407 DEVSTAT_TYPE_SEQUENTIAL = 0x001,
408 DEVSTAT_TYPE_PRINTER = 0x002,
409 DEVSTAT_TYPE_PROCESSOR = 0x003,
410 DEVSTAT_TYPE_WORM = 0x004,
411 DEVSTAT_TYPE_CDROM = 0x005,
412 DEVSTAT_TYPE_SCANNER = 0x006,
413 DEVSTAT_TYPE_OPTICAL = 0x007,
414 DEVSTAT_TYPE_CHANGER = 0x008,
415 DEVSTAT_TYPE_COMM = 0x009,
416 DEVSTAT_TYPE_ASC0 = 0x00a,
417 DEVSTAT_TYPE_ASC1 = 0x00b,
418 DEVSTAT_TYPE_STORARRAY = 0x00c,
419 DEVSTAT_TYPE_ENCLOSURE = 0x00d,
420 DEVSTAT_TYPE_FLOPPY = 0x00e,
421 DEVSTAT_TYPE_MASK = 0x00f,
422 DEVSTAT_TYPE_IF_SCSI = 0x010,
423 DEVSTAT_TYPE_IF_IDE = 0x020,
424 DEVSTAT_TYPE_IF_OTHER = 0x030,
425 DEVSTAT_TYPE_IF_MASK = 0x0f0,
426 DEVSTAT_TYPE_PASS = 0x100
427 } devstat_type_flags;
430 Devices have a priority associated with them, which controls roughly where
431 they are placed in the
434 The priorities are as follows:
435 .Bd -literal -offset indent
437 DEVSTAT_PRIORITY_MIN = 0x000,
438 DEVSTAT_PRIORITY_OTHER = 0x020,
439 DEVSTAT_PRIORITY_PASS = 0x030,
440 DEVSTAT_PRIORITY_FD = 0x040,
441 DEVSTAT_PRIORITY_WFD = 0x050,
442 DEVSTAT_PRIORITY_TAPE = 0x060,
443 DEVSTAT_PRIORITY_CD = 0x090,
444 DEVSTAT_PRIORITY_DISK = 0x110,
445 DEVSTAT_PRIORITY_ARRAY = 0x120,
446 DEVSTAT_PRIORITY_MAX = 0xfff
450 Each device has associated with it flags to indicate what operations are
451 supported or not supported.
453 .Va devstat_support_flags
454 values are as follows:
455 .Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
456 .It DEVSTAT_ALL_SUPPORTED
457 Every statistic type is supported by the device.
458 .It DEVSTAT_NO_BLOCKSIZE
459 This device does not have a blocksize.
460 .It DEVSTAT_NO_ORDERED_TAGS
461 This device does not support ordered tags.
462 .It DEVSTAT_BS_UNAVAILABLE
463 This device supports a blocksize, but it is currently unavailable.
465 flag is most often used with removable media drives.
468 Transactions to a device fall into one of three categories, which are
472 .Fn devstat_end_transaction .
473 The transaction types are as follows:
474 .Bd -literal -offset indent
476 DEVSTAT_NO_DATA = 0x00,
478 DEVSTAT_WRITE = 0x02,
480 } devstat_trans_flags;
483 There are four possible values for the
486 .Fn devstat_end_transaction :
487 .Bl -tag -width DEVSTAT_TAG_ORDERED
488 .It DEVSTAT_TAG_SIMPLE
489 The transaction had a simple tag.
491 The transaction had a head of queue tag.
492 .It DEVSTAT_TAG_ORDERED
493 The transaction had an ordered tag.
495 The device does not support tags.
498 The tag type values correspond to the lower four bits of the
501 In CAM, for instance, the
503 from the CCB is ORed with 0xf to determine the tag type to pass in to
504 .Fn devstat_end_transaction .
509 .In sys/devicestat.h .
510 This is the current version of the
512 subsystem, and it should be incremented each time a change is made that
513 would require recompilation of userland programs that access
516 Userland programs use this version, via the
517 .Va kern.devstat.version
519 variable to determine whether they are in sync with the kernel
531 statistics system appeared in
534 .An Kenneth Merry Aq Mt ken@FreeBSD.org
536 There may be a need for
538 protection around some of the
540 list manipulation code to ensure, for example, that the list of devices
541 is not changed while someone is fetching the