Next round of fixing all kinds of spelling mistakes.
[dragonfly.git] / 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 biodone().
160 .Pp
161 The
162 .Va devstat
163 structure is composed of the following fields:
164 .Bl -tag -width dev_creation_time
165 .It dev_links
166 Each
167 .Va devstat
168 structure is placed in a linked list when it is registered.  The
169 .Va dev_links
170 field contains a pointer to the next entry in the list of
171 .Va devstat
172 structures.
173 .It device_number
174 The device number is a unique identifier for each device.  The device
175 number is incremented for each new device that is registered.  The device
176 number is currently only a 32-bit integer, but it could be enlarged if
177 someone has a system with more than four billion device arrival events.
178 .It device_name
179 The device name is a text string given by the registering driver to
180 identify itself.  (e.g.\&
181 .Dq da ,
182 .Dq cd ,
183 .Dq sa ,
184 etc.)
185 .It unit_number
186 The unit number identifies the particular instance of the peripheral driver
187 in question.
188 .It bytes_written
189 This is the number of bytes that have been written to the device.  This
190 number is currently an unsigned 64 bit integer.  This will hopefully
191 eliminate the counter wrap that would come very quickly on some systems if
192 32 bit integers were used.
193 .It bytes_read
194 This is the number of bytes that have been read from the device.
195 .It bytes_freed
196 This is the number of bytes that have been freed/erased on the device.
197 .It num_reads
198 This is the number of reads from the device.
199 .It num_writes
200 This is the number of writes to the device.
201 .It num_frees
202 This is the number of free/erase operations on the device.
203 .It num_other
204 This is the number of transactions to the device which are neither reads or
205 writes.  For instance,
206 .Tn SCSI
207 drivers often send a test unit ready command to
208 .Tn SCSI
209 devices.  The test unit ready command does not read or write any data.  It
210 merely causes the device to return its status.
211 .It busy_count
212 This is the current number of outstanding transactions for the device.
213 This should never go below zero, and on an idle device it should be zero.
214 If either one of these conditions is not true, it indicates a problem in
215 the way
216 .Fn devstat_start_transaction
217 and
218 .Fn devstat_end_transaction
219 are being called in client code.  There should be one and only one
220 transaction start event and one transaction end event for each transaction.
221 .It block_size
222 This is the block size of the device, if the device has a block size.
223 .It tag_types
224 This is an array of counters to record the number of various tag types that
225 are sent to a device.  See below for a list of tag types.
226 .It dev_creation_time
227 This is the time, as reported by
228 .Fn getmicrotime
229 that the device was registered.
230 .It busy_time
231 This is the amount of time that the device busy count has been greater than
232 zero.  This is only updated when the busy count returns to zero.
233 .It start_time
234 This is the time, as reported by
235 .Fn getmicrouptime
236 that the device busy count went from zero to one.
237 .It last_comp_time
238 This is the time as reported by
239 .Fn getmicrouptime
240 that a transaction last completed.  It is used along with
241 .Va start_time
242 to calculate the device busy time.
243 .It flags
244 These flags indicate which statistics measurements are supported by a
245 particular device.  These flags are primarily intended to serve as an aid
246 to userland programs that decipher the statistics.
247 .It device_type
248 This is the device type.  It consists of three parts:  the device type
249 (e.g. direct access, CDROM, sequential access, etc.), the interface (IDE,
250 SCSI or other) and whether or not the device in question is a passthrough
251 driver.  See below for a complete list of device types.
252 .It priority
253 This is the priority.  This is the first parameter used to determine where
254 to insert a device in the
255 .Nm
256 list.  The second parameter is attach order.  See below for a list of
257 available priorities.
258 .El
259 .Pp
260 Each device is given a device type.  Passthrough devices have the same
261 underlying device type and interface as the device they provide an
262 interface for, but they also have the passthrough flag set.  The base
263 device types are identical to the
264 .Tn SCSI
265 device type numbers, so with
266 .Tn SCSI
267 peripherals, the device type returned from an inquiry is usually ORed with
268 the
269 .Tn SCSI
270 interface type and the passthrough flag if appropriate.  The device type
271 flags are as follows:
272 .Bd -literal -offset indent
273 typedef enum {
274         DEVSTAT_TYPE_DIRECT     = 0x000,
275         DEVSTAT_TYPE_SEQUENTIAL = 0x001,
276         DEVSTAT_TYPE_PRINTER    = 0x002,
277         DEVSTAT_TYPE_PROCESSOR  = 0x003,
278         DEVSTAT_TYPE_WORM       = 0x004,
279         DEVSTAT_TYPE_CDROM      = 0x005,
280         DEVSTAT_TYPE_SCANNER    = 0x006,
281         DEVSTAT_TYPE_OPTICAL    = 0x007,
282         DEVSTAT_TYPE_CHANGER    = 0x008,
283         DEVSTAT_TYPE_COMM       = 0x009,
284         DEVSTAT_TYPE_ASC0       = 0x00a,
285         DEVSTAT_TYPE_ASC1       = 0x00b,
286         DEVSTAT_TYPE_STORARRAY  = 0x00c,
287         DEVSTAT_TYPE_ENCLOSURE  = 0x00d,
288         DEVSTAT_TYPE_FLOPPY     = 0x00e,
289         DEVSTAT_TYPE_MASK       = 0x00f,
290         DEVSTAT_TYPE_IF_SCSI    = 0x010,
291         DEVSTAT_TYPE_IF_IDE     = 0x020,
292         DEVSTAT_TYPE_IF_OTHER   = 0x030,
293         DEVSTAT_TYPE_IF_MASK    = 0x0f0,
294         DEVSTAT_TYPE_PASS       = 0x100
295 } devstat_type_flags;
296 .Ed
297 .Pp
298 Devices have a priority associated with them, which controls roughly where
299 they are placed in the
300 .Nm
301 list.  The priorities are as follows:
302 .Bd -literal -offset indent
303 typedef enum {
304         DEVSTAT_PRIORITY_MIN    = 0x000,
305         DEVSTAT_PRIORITY_OTHER  = 0x020,
306         DEVSTAT_PRIORITY_PASS   = 0x030,
307         DEVSTAT_PRIORITY_FD     = 0x040,
308         DEVSTAT_PRIORITY_WFD    = 0x050,
309         DEVSTAT_PRIORITY_TAPE   = 0x060,
310         DEVSTAT_PRIORITY_CD     = 0x090,
311         DEVSTAT_PRIORITY_DISK   = 0x110,
312         DEVSTAT_PRIORITY_ARRAY  = 0x120,
313         DEVSTAT_PRIORITY_MAX    = 0xfff
314 } devstat_priority;
315 .Ed
316 .Pp
317 Each device has associated with it flags to indicate what operations are
318 supported or not supported.  The
319 .Va devstat_support_flags
320 values are as follows:
321 .Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
322 .It DEVSTAT_ALL_SUPPORTED
323 Every statistic type is supported by the device.
324 .It DEVSTAT_NO_BLOCKSIZE
325 This device does not have a blocksize.
326 .It DEVSTAT_NO_ORDERED_TAGS
327 This device does not support ordered tags.
328 .It DEVSTAT_BS_UNAVAILABLE
329 This device supports a blocksize, but it is currently unavailable.  This
330 flag is most often used with removable media drives.
331 .El
332 .Pp
333 Transactions to a device fall into one of three categories, which are
334 represented in the
335 .Va flags
336 passed into
337 .Fn devstat_end_transaction .
338 The transaction types are as follows:
339 .Bd -literal -offset indent
340 typedef enum {
341         DEVSTAT_NO_DATA = 0x00,
342         DEVSTAT_READ    = 0x01,
343         DEVSTAT_WRITE   = 0x02,
344         DEVSTAT_FREE    = 0x03
345 } devstat_trans_flags;
346 .Ed
347 .Pp
348 There are four possible values for the
349 .Va tag_type
350 argument to
351 .Fn devstat_end_transaction :
352 .Bl -tag -width DEVSTAT_TAG_ORDERED
353 .It DEVSTAT_TAG_SIMPLE
354 The transaction had a simple tag.
355 .It DEVSTAT_TAG_HEAD
356 The transaction had a head of queue tag.
357 .It DEVSTAT_TAG_ORDERED
358 The transaction had an ordered tag.
359 .It DEVSTAT_TAG_NONE
360 The device doesn't support tags.
361 .El
362 .Pp
363 The tag type values correspond to the lower four bits of the
364 .Tn SCSI
365 tag definitions.  In CAM, for instance, the
366 .Va tag_action
367 from the CCB is ORed with 0xf to determine the tag type to pass in to
368 .Fn devstat_end_transaction .
369 .Pp
370 There is a macro,
371 .Dv DEVSTAT_VERSION
372 that is defined in
373 .In sys/devicestat.h .
374 This is the current version of the
375 .Nm
376 subsystem, and it should be incremented each time a change is made that
377 would require recompilation of userland programs that access
378 .Nm
379 statistics.  Userland programs use this version, via the
380 .Va kern.devstat.version
381 .Nm sysctl
382 variable to determine whether they are in sync with the kernel
383 .Nm
384 structures.
385 .Sh SEE ALSO
386 .Xr systat 1 ,
387 .Xr devstat 3 ,
388 .Xr iostat 8 ,
389 .Xr rpc.rstatd 8 ,
390 .Xr vmstat 8
391 .Sh HISTORY
392 The
393 .Nm
394 statistics system appeared in
395 .Fx 3.0 .
396 .Sh AUTHORS
397 .An Kenneth Merry Aq ken@FreeBSD.org
398 .Sh BUGS
399 There may be a need for some of the list manipulation code to be
400 inside a critical section to ensure, for example, that the list of devices
401 is not changed while someone is fetching the
402 .Va kern.devstat.all
403 .Nm sysctl
404 variable.
405 .Pp
406 It is impossible with the current
407 .Nm
408 architecture to accurately measure time per transaction.  The only feasible
409 way to accurately measure time per transaction would be to record a
410 timestamp for every transaction.  This measurement is probably not
411 worthwhile for most people as it would adversely affect the performance of
412 the system and cost space to store the timestamps for individual
413 transactions.