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
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 $
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
46 .Fa "struct devstat *ds"
47 .Fa "const char *dev_name"
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"
55 .Fn devstat_remove_entry "struct devstat *ds"
57 .Fn devstat_start_transaction "struct devstat *ds"
59 .Fo devstat_end_transaction
60 .Fa "struct devstat *ds"
62 .Fa "devstat_tag_type tag_type"
63 .Fa "devstat_trans_flags flags"
66 .Fo devstat_end_transaction_buf
67 .Fa "struct devstat *ds"
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
77 code. Instead, that is left for user programs to handle.
80 registers a device with the
82 subsystem. The caller is expected to have already allocated \fBand zeroed\fR
83 the devstat structure before calling this function.
85 takes several arguments:
86 .Bl -tag -width device_type
90 structure, allocated and zeroed by the client.
92 The device name. e.g. da, cd, sa.
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
100 list, it should be set to 0.
102 Flags indicating operations supported or not supported by the device. See
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.
110 The device priority. The priority is used to determine how devices are
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
118 .Fn devstat_remove_entry
119 removes a device from the
121 subsystem. It takes the devstat structure for the device in question as
124 generation number is incremented and the number of devices is decremented.
126 .Fn devstat_start_transaction
127 registers the start of a transaction with the
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
136 .Fn devstat_end_transaction
137 registers the end of a transaction with the
139 subsystem. It takes four arguments:
140 .Bl -tag -width tag_type
144 structure for the device in question.
146 The number of bytes transferred in this transaction.
148 Transaction tag type. See below for tag types.
150 Transaction flags indicating whether the transaction was a read, write, or
151 whether no data was transferred.
154 .Fn devstat_end_transaction_buf
156 .Fn devstat_end_transaction
157 which pulls all the information from a
164 structure is composed of the following fields:
165 .Bl -tag -width dev_creation_time
169 structure is placed in a linked list when it is registered. The
171 field contains a pointer to the next entry in the list of
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.
180 The device name is a text string given by the registering driver to
181 identify itself. (e.g.\&
187 The unit number identifies the particular instance of the peripheral driver
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.
195 This is the number of bytes that have been read from the device.
197 This is the number of bytes that have been freed/erased on the device.
199 This is the number of reads from the device.
201 This is the number of writes to the device.
203 This is the number of free/erase operations on the device.
205 This is the number of transactions to the device which are neither reads or
206 writes. For instance,
208 drivers often send a test unit ready command to
210 devices. The test unit ready command does not read or write any data. It
211 merely causes the device to return its status.
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
217 .Fn devstat_start_transaction
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.
223 This is the block size of the device, if the device has a block size.
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
230 that the device was registered.
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.
235 This is the time, as reported by
237 that the device busy count went from zero to one.
239 This is the time as reported by
241 that a transaction last completed. It is used along with
243 to calculate the device busy time.
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.
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.
254 This is the priority. This is the first parameter used to determine where
255 to insert a device in the
257 list. The second parameter is attach order. See below for a list of
258 available priorities.
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
266 device type numbers, so with
268 peripherals, the device type returned from an inquiry is usually ORed with
271 interface type and the passthrough flag if appropriate. The device type
272 flags are as follows:
273 .Bd -literal -offset indent
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;
299 Devices have a priority associated with them, which controls roughly where
300 they are placed in the
302 list. The priorities are as follows:
303 .Bd -literal -offset indent
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
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.
334 Transactions to a device fall into one of three categories, which are
338 .Fn devstat_end_transaction .
339 The transaction types are as follows:
340 .Bd -literal -offset indent
342 DEVSTAT_NO_DATA = 0x00,
344 DEVSTAT_WRITE = 0x02,
346 } devstat_trans_flags;
349 There are four possible values for the
352 .Fn devstat_end_transaction :
353 .Bl -tag -width DEVSTAT_TAG_ORDERED
354 .It DEVSTAT_TAG_SIMPLE
355 The transaction had a simple tag.
357 The transaction had a head of queue tag.
358 .It DEVSTAT_TAG_ORDERED
359 The transaction had an ordered tag.
361 The device doesn't support tags.
364 The tag type values correspond to the lower four bits of the
366 tag definitions. In CAM, for instance, the
368 from the CCB is ORed with 0xf to determine the tag type to pass in to
369 .Fn devstat_end_transaction .
374 .In sys/devicestat.h .
375 This is the current version of the
377 subsystem, and it should be incremented each time a change is made that
378 would require recompilation of userland programs that access
380 statistics. Userland programs use this version, via the
381 .Va kern.devstat.version
383 variable to determine whether they are in sync with the kernel
395 statistics system appeared in
398 .An Kenneth Merry Aq ken@FreeBSD.org
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
407 It is impossible with the current
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