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_remove_entry ,
39 .Nm devstat_start_transaction
40 .Nd kernel interface for keeping device statistics
45 .Fa "struct devstat *ds"
46 .Fa "const char *dev_name"
48 .Fa "uint32_t block_size"
49 .Fa "devstat_support_flags flags"
50 .Fa "devstat_type_flags device_type"
51 .Fa "devstat_priority priority"
54 .Fn devstat_remove_entry "struct devstat *ds"
56 .Fn devstat_start_transaction "struct devstat *ds"
58 .Fo devstat_end_transaction
59 .Fa "struct devstat *ds"
61 .Fa "devstat_tag_type tag_type"
62 .Fa "devstat_trans_flags flags"
65 .Fo devstat_end_transaction_bio
66 .Fa "struct devstat *ds"
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
78 Instead, that is left for user programs to handle.
81 registers a device with the
84 The caller is expected to have already allocated \fBand zeroed\fR
85 the devstat structure before calling this function.
87 takes several arguments:
88 .Bl -tag -width device_type
92 structure, allocated and zeroed by the client.
94 The device name, e.g.\& da, cd, sa.
98 Block size of the device, if supported.
99 If the device does not support a
100 block size, or if the blocksize is unknown at the time the device is added
103 list, it should be set to 0.
105 Flags indicating operations supported or not supported by the device.
106 See below for details.
109 This is broken into three sections: base device type
110 (e.g.\& direct access, CDROM, sequential access), interface type (IDE, SCSI
111 or other) and a pass-through flag to indicate pas-through devices.
112 See below for a complete list of types.
115 The priority is used to determine how devices are
119 Devices are sorted first by priority (highest to lowest),
120 and then by attach order.
121 See below for a complete list of available
125 .Fn devstat_remove_entry
126 removes a device from the
129 It takes the devstat structure for the device in question as
133 generation number is incremented and the number of devices is decremented.
135 .Fn devstat_start_transaction
136 registers the start of a transaction with the
139 The busy count is incremented with each transaction start.
140 When a device goes from idle to busy, the system uptime is recorded in the
146 .Fn devstat_end_transaction
147 registers the end of a transaction with the
150 It takes four arguments:
151 .Bl -tag -width tag_type
155 structure for the device in question.
157 The number of bytes transferred in this transaction.
159 Transaction tag type.
160 See below for tag types.
162 Transaction flags indicating whether the transaction was a read, write, or
163 whether no data was transferred.
166 .Fn devstat_end_transaction_bio
168 .Fn devstat_end_transaction
169 which pulls all the information from a
171 which is ready for biodone().
175 structure is composed of the following fields:
176 .Bl -tag -width dev_creation_time
180 structure is placed in a linked list when it is registered.
183 field contains a pointer to the next entry in the list of
187 The device number is a unique identifier for each device.
189 number is incremented for each new device that is registered.
191 number is currently only a 32-bit integer, but it could be enlarged if
192 someone has a system with more than four billion device arrival events.
194 The device name is a text string given by the registering driver to
202 The unit number identifies the particular instance of the peripheral driver
205 This is the number of bytes that have been written to the device.
206 This number is currently an unsigned 64 bit integer.
208 eliminate the counter wrap that would come very quickly on some systems if
209 32 bit integers were used.
211 This is the number of bytes that have been read from the device.
213 This is the number of bytes that have been freed/erased on the device.
215 This is the number of reads from the device.
217 This is the number of writes to the device.
219 This is the number of free/erase operations on the device.
221 This is the number of transactions to the device which are neither reads or
225 drivers often send a test unit ready command to
228 The test unit ready command does not read or write any data.
229 It merely causes the device to return its status.
231 This is the current number of outstanding transactions for the device.
232 This should never go below zero, and on an idle device it should be zero.
233 If either one of these conditions is not true, it indicates a problem in
235 .Fn devstat_start_transaction
237 .Fn devstat_end_transaction
238 are being called in client code.
239 There should be one and only one
240 transaction start event and one transaction end event for each transaction.
242 This is the block size of the device, if the device has a block size.
244 This is an array of counters to record the number of various tag types that
245 are sent to a device.
246 See below for a list of tag types.
247 .It dev_creation_time
248 This is the time, as reported by
250 that the device was registered.
252 This is the amount of time that the device busy count has been greater than
254 This is only updated when the busy count returns to zero.
256 This is the time, as reported by
258 that the device busy count went from zero to one.
260 This is the time as reported by
262 that a transaction last completed.
263 It is used along with
265 to calculate the device busy time.
267 These flags indicate which statistics measurements are supported by a
269 These flags are primarily intended to serve as an aid
270 to userland programs that decipher the statistics.
272 This is the device type.
273 It consists of three parts: the device type
274 (e.g.\& direct access, CDROM, sequential access, etc.), the interface (IDE,
275 SCSI or other) and whether or not the device in question is a pass-through
277 See below for a complete list of device types.
279 This is the priority.
280 This is the first parameter used to determine where
281 to insert a device in the
284 The second parameter is attach order.
285 See below for a list of
286 available priorities.
289 Each device is given a device type.
290 Pass-through devices have the same
291 underlying device type and interface as the device they provide an
292 interface for, but they also have the pass-through flag set.
294 device types are identical to the
296 device type numbers, so with
298 peripherals, the device type returned from an inquiry is usually ORed with
301 interface type and the pass-through flag if appropriate.
303 flags are as follows:
304 .Bd -literal -offset indent
306 DEVSTAT_TYPE_DIRECT = 0x000,
307 DEVSTAT_TYPE_SEQUENTIAL = 0x001,
308 DEVSTAT_TYPE_PRINTER = 0x002,
309 DEVSTAT_TYPE_PROCESSOR = 0x003,
310 DEVSTAT_TYPE_WORM = 0x004,
311 DEVSTAT_TYPE_CDROM = 0x005,
312 DEVSTAT_TYPE_SCANNER = 0x006,
313 DEVSTAT_TYPE_OPTICAL = 0x007,
314 DEVSTAT_TYPE_CHANGER = 0x008,
315 DEVSTAT_TYPE_COMM = 0x009,
316 DEVSTAT_TYPE_ASC0 = 0x00a,
317 DEVSTAT_TYPE_ASC1 = 0x00b,
318 DEVSTAT_TYPE_STORARRAY = 0x00c,
319 DEVSTAT_TYPE_ENCLOSURE = 0x00d,
320 DEVSTAT_TYPE_FLOPPY = 0x00e,
321 DEVSTAT_TYPE_MASK = 0x00f,
322 DEVSTAT_TYPE_IF_SCSI = 0x010,
323 DEVSTAT_TYPE_IF_IDE = 0x020,
324 DEVSTAT_TYPE_IF_OTHER = 0x030,
325 DEVSTAT_TYPE_IF_MASK = 0x0f0,
326 DEVSTAT_TYPE_PASS = 0x100
327 } devstat_type_flags;
330 Devices have a priority associated with them, which controls roughly where
331 they are placed in the
334 The priorities are as follows:
335 .Bd -literal -offset indent
337 DEVSTAT_PRIORITY_MIN = 0x000,
338 DEVSTAT_PRIORITY_OTHER = 0x020,
339 DEVSTAT_PRIORITY_PASS = 0x030,
340 DEVSTAT_PRIORITY_FD = 0x040,
341 DEVSTAT_PRIORITY_WFD = 0x050,
342 DEVSTAT_PRIORITY_TAPE = 0x060,
343 DEVSTAT_PRIORITY_CD = 0x090,
344 DEVSTAT_PRIORITY_DISK = 0x110,
345 DEVSTAT_PRIORITY_ARRAY = 0x120,
346 DEVSTAT_PRIORITY_MAX = 0xfff
350 Each device has associated with it flags to indicate what operations are
351 supported or not supported.
353 .Va devstat_support_flags
354 values are as follows:
355 .Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
356 .It DEVSTAT_ALL_SUPPORTED
357 Every statistic type is supported by the device.
358 .It DEVSTAT_NO_BLOCKSIZE
359 This device does not have a blocksize.
360 .It DEVSTAT_NO_ORDERED_TAGS
361 This device does not support ordered tags.
362 .It DEVSTAT_BS_UNAVAILABLE
363 This device supports a blocksize, but it is currently unavailable.
365 flag is most often used with removable media drives.
368 Transactions to a device fall into one of three categories, which are
372 .Fn devstat_end_transaction .
373 The transaction types are as follows:
374 .Bd -literal -offset indent
376 DEVSTAT_NO_DATA = 0x00,
378 DEVSTAT_WRITE = 0x02,
380 } devstat_trans_flags;
383 There are four possible values for the
386 .Fn devstat_end_transaction :
387 .Bl -tag -width DEVSTAT_TAG_ORDERED
388 .It DEVSTAT_TAG_SIMPLE
389 The transaction had a simple tag.
391 The transaction had a head of queue tag.
392 .It DEVSTAT_TAG_ORDERED
393 The transaction had an ordered tag.
395 The device does not support tags.
398 The tag type values correspond to the lower four bits of the
401 In CAM, for instance, the
403 from the CCB is ORed with 0xf to determine the tag type to pass in to
404 .Fn devstat_end_transaction .
409 .In sys/devicestat.h .
410 This is the current version of the
412 subsystem, and it should be incremented each time a change is made that
413 would require recompilation of userland programs that access
416 Userland programs use this version, via the
417 .Va kern.devstat.version
419 variable to determine whether they are in sync with the kernel
431 statistics system appeared in
434 .An Kenneth Merry Aq ken@FreeBSD.org
436 There may be a need for
438 protection around some of the
440 list manipulation code to ensure, for example, that the list of devices
441 is not changed while someone is fetching the
446 It is impossible with the current
448 architecture to accurately measure time per transaction.
450 way to accurately measure time per transaction would be to record a
451 timestamp for every transaction.
452 This measurement is probably not
453 worthwhile for most people as it would adversely affect the performance of
454 the system and cost space to store the timestamps for individual