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
--- 11 unchanged lines hidden (view full) ---
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: head/share/man/man9/devstat.9 119964 2003-09-10 19:24:35Z ru $
29.\"
30.Dd May 22, 1998
31.Dt DEVSTAT 9
32.Os
33.Sh NAME
34.Nm devstat ,
35.Nm devstat_add_entry ,
36.Nm devstat_end_transaction ,
--- 26 unchanged lines hidden (view full) ---
63.Fc
64.Ft void
65.Fo devstat_end_transaction_bio
66.Fa "struct devstat *ds"
67.Fa "struct bio *bp"
68.Fc
69.Sh DESCRIPTION
70The devstat subsystem is an interface for recording device
71statistics, as its name implies. The idea is to keep reasonably detailed
72statistics while utilizing a minimum amount of CPU time to record them.
73Thus, no statistical calculations are actually performed in the kernel
74portion of the
75.Nm
76code. Instead, that is left for user programs to handle.
77.Pp
78.Fn devstat_add_entry
79registers a device with the
80.Nm
81subsystem. The caller is expected to have already allocated \fBand zeroed\fR
82the devstat structure before calling this function.
83.Fn devstat_add_entry
84takes several arguments:
85.Bl -tag -width device_type
86.It ds
87The
88.Va devstat
89structure, allocated and zeroed by the client.
90.It dev_name
91The device name. e.g. da, cd, sa.
92.It unit_number
93Device unit number.
94.It block_size
95Block size of the device, if supported. If the device does not support a
96block size, or if the blocksize is unknown at the time the device is added
97to the
98.Nm
99list, it should be set to 0.
100.It flags
101Flags indicating operations supported or not supported by the device. See
102below for details.
103.It device_type
104The device type. This is broken into three sections: base device type
105(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI
106or other) and a pass-through flag to indicate pas-through devices. See below
107for a complete list of types.
108.It priority
109The device priority. The priority is used to determine how devices are
110sorted within
111.Nm devstat Ns 's
112list of devices. Devices are sorted first by priority (highest to lowest),
113and then by attach order. See below for a complete list of available
114priorities.
115.El
116.Pp
117.Fn devstat_remove_entry
118removes a device from the
119.Nm
120subsystem. It takes the devstat structure for the device in question as
121an argument. The
122.Nm
123generation number is incremented and the number of devices is decremented.
124.Pp
125.Fn devstat_start_transaction
126registers the start of a transaction with the
127.Nm
128subsystem. The busy count is incremented with each transaction start.
129When a device goes from idle to busy, the system uptime is recorded in the
130.Va start_time
131field of the
132.Va devstat
133structure.
134.Pp
135.Fn devstat_end_transaction
136registers the end of a transaction with the
137.Nm
138subsystem. It takes four arguments:
139.Bl -tag -width tag_type
140.It ds
141The
142.Va devstat
143structure for the device in question.
144.It bytes
145The number of bytes transferred in this transaction.
146.It tag_type
147Transaction tag type. See below for tag types.
148.It flags
149Transaction flags indicating whether the transaction was a read, write, or
150whether no data was transferred.
151.El
152.Pp
153.Fn devstat_end_transaction_bio
154is a wrapper for
155.Fn devstat_end_transaction
156which pulls all the information from a
157.Va "struct bio"
158which is ready for biodone().
159.Pp
160The
161.Va devstat
162structure is composed of the following fields:
163.Bl -tag -width dev_creation_time
164.It dev_links
165Each
166.Va devstat
167structure is placed in a linked list when it is registered. The
168.Va dev_links
169field contains a pointer to the next entry in the list of
170.Va devstat
171structures.
172.It device_number
173The device number is a unique identifier for each device. The device
174number is incremented for each new device that is registered. The device
175number is currently only a 32-bit integer, but it could be enlarged if
176someone has a system with more than four billion device arrival events.
177.It device_name
178The device name is a text string given by the registering driver to
179identify itself. (e.g.\&
180.Dq da ,
181.Dq cd ,
182.Dq sa ,
183etc.)
184.It unit_number
185The unit number identifies the particular instance of the peripheral driver
186in question.
187.It bytes_written
188This is the number of bytes that have been written to the device. This
189number is currently an unsigned 64 bit integer. This will hopefully
190eliminate the counter wrap that would come very quickly on some systems if
19132 bit integers were used.
192.It bytes_read
193This is the number of bytes that have been read from the device.
194.It bytes_freed
195This is the number of bytes that have been freed/erased on the device.
196.It num_reads
197This is the number of reads from the device.
198.It num_writes
199This is the number of writes to the device.
200.It num_frees
201This is the number of free/erase operations on the device.
202.It num_other
203This is the number of transactions to the device which are neither reads or
204writes. For instance,
205.Tn SCSI
206drivers often send a test unit ready command to
207.Tn SCSI
208devices. The test unit ready command does not read or write any data. It
209merely causes the device to return its status.
210.It busy_count
211This is the current number of outstanding transactions for the device.
212This should never go below zero, and on an idle device it should be zero.
213If either one of these conditions is not true, it indicates a problem in
214the way
215.Fn devstat_start_transaction
216and
217.Fn devstat_end_transaction
218are being called in client code. There should be one and only one
219transaction start event and one transaction end event for each transaction.
220.It block_size
221This is the block size of the device, if the device has a block size.
222.It tag_types
223This is an array of counters to record the number of various tag types that
224are sent to a device. See below for a list of tag types.
225.It dev_creation_time
226This is the time, as reported by
227.Fn getmicrotime
228that the device was registered.
229.It busy_time
230This is the amount of time that the device busy count has been greater than
231zero. This is only updated when the busy count returns to zero.
232.It start_time
233This is the time, as reported by
234.Fn getmicrouptime
235that the device busy count went from zero to one.
236.It last_comp_time
237This is the time as reported by
238.Fn getmicrouptime
239that a transaction last completed. It is used along with
240.Va start_time
241to calculate the device busy time.
242.It flags
243These flags indicate which statistics measurements are supported by a
244particular device. These flags are primarily intended to serve as an aid
245to userland programs that decipher the statistics.
246.It device_type
247This is the device type. It consists of three parts: the device type
248(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE,
249SCSI or other) and whether or not the device in question is a pass-through
250driver. See below for a complete list of device types.
251.It priority
252This is the priority. This is the first parameter used to determine where
253to insert a device in the
254.Nm
255list. The second parameter is attach order. See below for a list of
256available priorities.
257.El
258.Pp
259Each device is given a device type. Pass-through devices have the same
260underlying device type and interface as the device they provide an
261interface for, but they also have the pass-through flag set. The base
262device types are identical to the
263.Tn SCSI
264device type numbers, so with
265.Tn SCSI
266peripherals, the device type returned from an inquiry is usually ORed with
267the
268.Tn SCSI
269interface type and the pass-through flag if appropriate. The device type
270flags are as follows:
271.Bd -literal -offset indent
272typedef enum {
273 DEVSTAT_TYPE_DIRECT = 0x000,
274 DEVSTAT_TYPE_SEQUENTIAL = 0x001,
275 DEVSTAT_TYPE_PRINTER = 0x002,
276 DEVSTAT_TYPE_PROCESSOR = 0x003,
277 DEVSTAT_TYPE_WORM = 0x004,
--- 14 unchanged lines hidden (view full) ---
292 DEVSTAT_TYPE_IF_MASK = 0x0f0,
293 DEVSTAT_TYPE_PASS = 0x100
294} devstat_type_flags;
295.Ed
296.Pp
297Devices have a priority associated with them, which controls roughly where
298they are placed in the
299.Nm
300list. The priorities are as follows:
301.Bd -literal -offset indent
302typedef enum {
303 DEVSTAT_PRIORITY_MIN = 0x000,
304 DEVSTAT_PRIORITY_OTHER = 0x020,
305 DEVSTAT_PRIORITY_PASS = 0x030,
306 DEVSTAT_PRIORITY_FD = 0x040,
307 DEVSTAT_PRIORITY_WFD = 0x050,
308 DEVSTAT_PRIORITY_TAPE = 0x060,
309 DEVSTAT_PRIORITY_CD = 0x090,
310 DEVSTAT_PRIORITY_DISK = 0x110,
311 DEVSTAT_PRIORITY_ARRAY = 0x120,
312 DEVSTAT_PRIORITY_MAX = 0xfff
313} devstat_priority;
314.Ed
315.Pp
316Each device has associated with it flags to indicate what operations are
317supported or not supported. The
318.Va devstat_support_flags
319values are as follows:
320.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
321.It DEVSTAT_ALL_SUPPORTED
322Every statistic type is supported by the device.
323.It DEVSTAT_NO_BLOCKSIZE
324This device does not have a blocksize.
325.It DEVSTAT_NO_ORDERED_TAGS
326This device does not support ordered tags.
327.It DEVSTAT_BS_UNAVAILABLE
328This device supports a blocksize, but it is currently unavailable. This
329flag is most often used with removable media drives.
330.El
331.Pp
332Transactions to a device fall into one of three categories, which are
333represented in the
334.Va flags
335passed into
336.Fn devstat_end_transaction .
--- 19 unchanged lines hidden (view full) ---
356.It DEVSTAT_TAG_ORDERED
357The transaction had an ordered tag.
358.It DEVSTAT_TAG_NONE
359The device doesn't support tags.
360.El
361.Pp
362The tag type values correspond to the lower four bits of the
363.Tn SCSI
364tag definitions. In CAM, for instance, the
365.Va tag_action
366from the CCB is ORed with 0xf to determine the tag type to pass in to
367.Fn devstat_end_transaction .
368.Pp
369There is a macro,
370.Dv DEVSTAT_VERSION
371that is defined in
372.In sys/devicestat.h .
373This is the current version of the
374.Nm
375subsystem, and it should be incremented each time a change is made that
376would require recompilation of userland programs that access
377.Nm
378statistics. Userland programs use this version, via the
379.Va kern.devstat.version
380.Nm sysctl
381variable to determine whether they are in sync with the kernel
382.Nm
383structures.
384.Sh SEE ALSO
385.Xr systat 1 ,
386.Xr devstat 3 ,
--- 15 unchanged lines hidden (view full) ---
402list manipulation code to insure, for example, that the list of devices
403is not changed while someone is fetching the
404.Va kern.devstat.all
405.Nm sysctl
406variable.
407.Pp
408It is impossible with the current
409.Nm
410architecture to accurately measure time per transaction. The only feasible
411way to accurately measure time per transaction would be to record a
412timestamp for every transaction. This measurement is probably not
413worthwhile for most people as it would adversely affect the performance of
414the system and cost space to store the timestamps for individual
415transactions.
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
--- 11 unchanged lines hidden (view full) ---
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: head/share/man/man9/devstat.9 119964 2003-09-10 19:24:35Z ru $
29.\"
30.Dd May 22, 1998
31.Dt DEVSTAT 9
32.Os
33.Sh NAME
34.Nm devstat ,
35.Nm devstat_add_entry ,
36.Nm devstat_end_transaction ,
--- 26 unchanged lines hidden (view full) ---
63.Fc
64.Ft void
65.Fo devstat_end_transaction_bio
66.Fa "struct devstat *ds"
67.Fa "struct bio *bp"
68.Fc
69.Sh DESCRIPTION
70The devstat subsystem is an interface for recording device
71statistics, as its name implies. The idea is to keep reasonably detailed
72statistics while utilizing a minimum amount of CPU time to record them.
73Thus, no statistical calculations are actually performed in the kernel
74portion of the
75.Nm
76code. Instead, that is left for user programs to handle.
77.Pp
78.Fn devstat_add_entry
79registers a device with the
80.Nm
81subsystem. The caller is expected to have already allocated \fBand zeroed\fR
82the devstat structure before calling this function.
83.Fn devstat_add_entry
84takes several arguments:
85.Bl -tag -width device_type
86.It ds
87The
88.Va devstat
89structure, allocated and zeroed by the client.
90.It dev_name
91The device name. e.g. da, cd, sa.
92.It unit_number
93Device unit number.
94.It block_size
95Block size of the device, if supported. If the device does not support a
96block size, or if the blocksize is unknown at the time the device is added
97to the
98.Nm
99list, it should be set to 0.
100.It flags
101Flags indicating operations supported or not supported by the device. See
102below for details.
103.It device_type
104The device type. This is broken into three sections: base device type
105(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI
106or other) and a pass-through flag to indicate pas-through devices. See below
107for a complete list of types.
108.It priority
109The device priority. The priority is used to determine how devices are
110sorted within
111.Nm devstat Ns 's
112list of devices. Devices are sorted first by priority (highest to lowest),
113and then by attach order. See below for a complete list of available
114priorities.
115.El
116.Pp
117.Fn devstat_remove_entry
118removes a device from the
119.Nm
120subsystem. It takes the devstat structure for the device in question as
121an argument. The
122.Nm
123generation number is incremented and the number of devices is decremented.
124.Pp
125.Fn devstat_start_transaction
126registers the start of a transaction with the
127.Nm
128subsystem. The busy count is incremented with each transaction start.
129When a device goes from idle to busy, the system uptime is recorded in the
130.Va start_time
131field of the
132.Va devstat
133structure.
134.Pp
135.Fn devstat_end_transaction
136registers the end of a transaction with the
137.Nm
138subsystem. It takes four arguments:
139.Bl -tag -width tag_type
140.It ds
141The
142.Va devstat
143structure for the device in question.
144.It bytes
145The number of bytes transferred in this transaction.
146.It tag_type
147Transaction tag type. See below for tag types.
148.It flags
149Transaction flags indicating whether the transaction was a read, write, or
150whether no data was transferred.
151.El
152.Pp
153.Fn devstat_end_transaction_bio
154is a wrapper for
155.Fn devstat_end_transaction
156which pulls all the information from a
157.Va "struct bio"
158which is ready for biodone().
159.Pp
160The
161.Va devstat
162structure is composed of the following fields:
163.Bl -tag -width dev_creation_time
164.It dev_links
165Each
166.Va devstat
167structure is placed in a linked list when it is registered. The
168.Va dev_links
169field contains a pointer to the next entry in the list of
170.Va devstat
171structures.
172.It device_number
173The device number is a unique identifier for each device. The device
174number is incremented for each new device that is registered. The device
175number is currently only a 32-bit integer, but it could be enlarged if
176someone has a system with more than four billion device arrival events.
177.It device_name
178The device name is a text string given by the registering driver to
179identify itself. (e.g.\&
180.Dq da ,
181.Dq cd ,
182.Dq sa ,
183etc.)
184.It unit_number
185The unit number identifies the particular instance of the peripheral driver
186in question.
187.It bytes_written
188This is the number of bytes that have been written to the device. This
189number is currently an unsigned 64 bit integer. This will hopefully
190eliminate the counter wrap that would come very quickly on some systems if
19132 bit integers were used.
192.It bytes_read
193This is the number of bytes that have been read from the device.
194.It bytes_freed
195This is the number of bytes that have been freed/erased on the device.
196.It num_reads
197This is the number of reads from the device.
198.It num_writes
199This is the number of writes to the device.
200.It num_frees
201This is the number of free/erase operations on the device.
202.It num_other
203This is the number of transactions to the device which are neither reads or
204writes. For instance,
205.Tn SCSI
206drivers often send a test unit ready command to
207.Tn SCSI
208devices. The test unit ready command does not read or write any data. It
209merely causes the device to return its status.
210.It busy_count
211This is the current number of outstanding transactions for the device.
212This should never go below zero, and on an idle device it should be zero.
213If either one of these conditions is not true, it indicates a problem in
214the way
215.Fn devstat_start_transaction
216and
217.Fn devstat_end_transaction
218are being called in client code. There should be one and only one
219transaction start event and one transaction end event for each transaction.
220.It block_size
221This is the block size of the device, if the device has a block size.
222.It tag_types
223This is an array of counters to record the number of various tag types that
224are sent to a device. See below for a list of tag types.
225.It dev_creation_time
226This is the time, as reported by
227.Fn getmicrotime
228that the device was registered.
229.It busy_time
230This is the amount of time that the device busy count has been greater than
231zero. This is only updated when the busy count returns to zero.
232.It start_time
233This is the time, as reported by
234.Fn getmicrouptime
235that the device busy count went from zero to one.
236.It last_comp_time
237This is the time as reported by
238.Fn getmicrouptime
239that a transaction last completed. It is used along with
240.Va start_time
241to calculate the device busy time.
242.It flags
243These flags indicate which statistics measurements are supported by a
244particular device. These flags are primarily intended to serve as an aid
245to userland programs that decipher the statistics.
246.It device_type
247This is the device type. It consists of three parts: the device type
248(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE,
249SCSI or other) and whether or not the device in question is a pass-through
250driver. See below for a complete list of device types.
251.It priority
252This is the priority. This is the first parameter used to determine where
253to insert a device in the
254.Nm
255list. The second parameter is attach order. See below for a list of
256available priorities.
257.El
258.Pp
259Each device is given a device type. Pass-through devices have the same
260underlying device type and interface as the device they provide an
261interface for, but they also have the pass-through flag set. The base
262device types are identical to the
263.Tn SCSI
264device type numbers, so with
265.Tn SCSI
266peripherals, the device type returned from an inquiry is usually ORed with
267the
268.Tn SCSI
269interface type and the pass-through flag if appropriate. The device type
270flags are as follows:
271.Bd -literal -offset indent
272typedef enum {
273 DEVSTAT_TYPE_DIRECT = 0x000,
274 DEVSTAT_TYPE_SEQUENTIAL = 0x001,
275 DEVSTAT_TYPE_PRINTER = 0x002,
276 DEVSTAT_TYPE_PROCESSOR = 0x003,
277 DEVSTAT_TYPE_WORM = 0x004,
--- 14 unchanged lines hidden (view full) ---
292 DEVSTAT_TYPE_IF_MASK = 0x0f0,
293 DEVSTAT_TYPE_PASS = 0x100
294} devstat_type_flags;
295.Ed
296.Pp
297Devices have a priority associated with them, which controls roughly where
298they are placed in the
299.Nm
300list. The priorities are as follows:
301.Bd -literal -offset indent
302typedef enum {
303 DEVSTAT_PRIORITY_MIN = 0x000,
304 DEVSTAT_PRIORITY_OTHER = 0x020,
305 DEVSTAT_PRIORITY_PASS = 0x030,
306 DEVSTAT_PRIORITY_FD = 0x040,
307 DEVSTAT_PRIORITY_WFD = 0x050,
308 DEVSTAT_PRIORITY_TAPE = 0x060,
309 DEVSTAT_PRIORITY_CD = 0x090,
310 DEVSTAT_PRIORITY_DISK = 0x110,
311 DEVSTAT_PRIORITY_ARRAY = 0x120,
312 DEVSTAT_PRIORITY_MAX = 0xfff
313} devstat_priority;
314.Ed
315.Pp
316Each device has associated with it flags to indicate what operations are
317supported or not supported. The
318.Va devstat_support_flags
319values are as follows:
320.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
321.It DEVSTAT_ALL_SUPPORTED
322Every statistic type is supported by the device.
323.It DEVSTAT_NO_BLOCKSIZE
324This device does not have a blocksize.
325.It DEVSTAT_NO_ORDERED_TAGS
326This device does not support ordered tags.
327.It DEVSTAT_BS_UNAVAILABLE
328This device supports a blocksize, but it is currently unavailable. This
329flag is most often used with removable media drives.
330.El
331.Pp
332Transactions to a device fall into one of three categories, which are
333represented in the
334.Va flags
335passed into
336.Fn devstat_end_transaction .
--- 19 unchanged lines hidden (view full) ---
356.It DEVSTAT_TAG_ORDERED
357The transaction had an ordered tag.
358.It DEVSTAT_TAG_NONE
359The device doesn't support tags.
360.El
361.Pp
362The tag type values correspond to the lower four bits of the
363.Tn SCSI
364tag definitions. In CAM, for instance, the
365.Va tag_action
366from the CCB is ORed with 0xf to determine the tag type to pass in to
367.Fn devstat_end_transaction .
368.Pp
369There is a macro,
370.Dv DEVSTAT_VERSION
371that is defined in
372.In sys/devicestat.h .
373This is the current version of the
374.Nm
375subsystem, and it should be incremented each time a change is made that
376would require recompilation of userland programs that access
377.Nm
378statistics. Userland programs use this version, via the
379.Va kern.devstat.version
380.Nm sysctl
381variable to determine whether they are in sync with the kernel
382.Nm
383structures.
384.Sh SEE ALSO
385.Xr systat 1 ,
386.Xr devstat 3 ,
--- 15 unchanged lines hidden (view full) ---
402list manipulation code to insure, for example, that the list of devices
403is not changed while someone is fetching the
404.Va kern.devstat.all
405.Nm sysctl
406variable.
407.Pp
408It is impossible with the current
409.Nm
410architecture to accurately measure time per transaction. The only feasible
411way to accurately measure time per transaction would be to record a
412timestamp for every transaction. This measurement is probably not
413worthwhile for most people as it would adversely affect the performance of
414the system and cost space to store the timestamps for individual
415transactions.