Attachment #115546 for bug #157316




	device_set_desc.9 device_set_desc_copy.9
MLINKS+=device_set_flags.9 device_get_flags.9
MLINKS+=devstat.9 devicestat.9 \
	devstat.9 devstat_new_entry.9 \
	devstat.9 devstat_end_transaction.9 \
	devstat.9 devstat_end_transaction_bio.9 \
	devstat.9 devstat_remove_entry.9 \
	devstat.9 devstat_start_transaction.9 \
	devstat.9 devstat_start_transaction_bio.9
MLINKS+=disk.9 disk_alloc.9 \
	disk.9 disk_create.9 \
	disk.9 disk_destroy.9 \




.Nd kernel interface for keeping device statistics
.Sh SYNOPSIS
.In sys/devicestat.h
.Ft struct devstat *
.Fo devstat_new_entry
.Fa "const void *dev_name"
.Fa "const char *dev_name"
.Fa "int unit_number"
.Fa "u_int32_t block_size"
.Fa "devstat_support_flags flags"

.Ft void
.Fn devstat_remove_entry "struct devstat *ds"
.Ft void
.Fo devstat_start_transaction
.Fa "struct devstat *ds"
.Fa "struct bintime *now"
.Fc
.Ft void
.Fo devstat_start_transaction_bio
.Fa "struct devstat *ds"
.Fa "struct bio *bp"
.Fc
.Ft void
.Fo devstat_end_transaction
.Fa "struct devstat *ds"
.Fa "u_int32_t bytes"
.Fa "devstat_tag_type tag_type"
.Fa "devstat_trans_flags flags"
.Fa "struct bintime *now"
.Fa "struct bintime *then"
.Fc
.Ft void
.Fo devstat_end_transaction_bio

code.
Instead, that is left for user programs to handle.
.Pp
.Fn devstat_new_entry
allocates and initializes
.Va devstat
structure and returns a pointer to it.
.Fn devstat_new_entry
the devstat structure before calling this function.
.Fn devstat_add_entry
takes several arguments:
.Bl -tag -width device_type
.It ds
The
.Va devstat
structure, allocated and zeroed by the client.
.It dev_name
The device name, e.g.\& da, cd, sa.
.It unit_number

registers the end of a transaction with the
.Nm
subsystem.
It takes six arguments:
.Bl -tag -width tag_type
.It ds
The

.It flags
Transaction flags indicating whether the transaction was a read, write, or
whether no data was transferred.
.It now
Time when transaction started.
.It then
Time when transation ended.
.El
.Pp
.Fn devstat_start_transaction_bio
and
.Fn devstat_end_transaction_bio
are wrappers for
.Fn devstart_start_transaction
and 
.Fn devstat_end_transaction
respectively, which pull all the information from a
.Va "struct bio"
which is ready for biodone().
.Pp

This will hopefully
eliminate the counter wrap that would come very quickly on some systems if
32 bit integers were used.
.It bytes_read
This is the number of bytes that have been read from the device.
.It bytes_freed
This is the number of bytes that have been freed/erased on the device.
.It num_reads
This is the number of reads from the device.
.It num_writes
This is the number of writes to the device.
.It num_frees
This is the number of free/erase operations on the device.
.It num_other
This is the number of transactions to the device which are neither reads or
writes.
For instance,
.Tn SCSI
drivers often send a test unit ready command to
.Tn SCSI
devices.
The test unit ready command does not read or write any data.
It merely causes the device to return its status.
.It busy_count
This is the current number of outstanding transactions for the device.
This should never go below zero, and on an idle device it should be zero.
If either one of these conditions is not true, it indicates a problem in
the way
.Fn devstat_start_transaction
and
.Fn devstat_end_transaction
are being called in client code.
There should be one and only one
transaction start event and one transaction end event for each transaction.
.It block_size
This is the block size of the device, if the device has a block size.
.It tag_types
This is an array of counters to record the number of various tag types that
are sent to a device.
See below for a list of tag types.
.It creation_time
This is the time, as reported by
.Fn getmicrotime
that the device was created.
.It busy_time
This is the amount of time that the device busy count has been greater than
zero.
This is only updated when the busy count returns to zero.
.It start_time
This is the time, as reported by
.Fn getmicrouptime
that the device busy count went from zero to one.
.It last_comp_time
This is the time as reported by
.Fn getmicrouptime
that a transaction last completed.
It is used along with
.Va start_time
to calculate the device busy time.
.It flags
These flags indicate which statistics measurements are supported by a
particular device.

The second parameter is attach order.
See below for a list of
available priorities.
.It id
Identification for GEOM nodes.
.El
.Pp
Each device is given a device type.

Return to bug 157316

Lines 592-601 Link Here

(-)Makefile (-2 / +4 lines)
592	device_set_desc.9 device_set_desc_copy.9	592	device_set_desc.9 device_set_desc_copy.9
593	MLINKS+=device_set_flags.9 device_get_flags.9	593	MLINKS+=device_set_flags.9 device_get_flags.9
594	MLINKS+=devstat.9 devicestat.9 \	594	MLINKS+=devstat.9 devicestat.9 \
595	devstat.9 devstat_add_entry.9 \	595	devstat.9 devstat_new_entry.9 \
596	devstat.9 devstat_end_transaction.9 \	596	devstat.9 devstat_end_transaction.9 \
		597	devstat.9 devstat_end_transaction_bio.9 \
597	devstat.9 devstat_remove_entry.9 \	598	devstat.9 devstat_remove_entry.9 \
598	devstat.9 devstat_start_transaction.9	599	devstat.9 devstat_start_transaction.9 \
		600	devstat.9 devstat_start_transaction_bio.9
599	MLINKS+=disk.9 disk_alloc.9 \	601	MLINKS+=disk.9 disk_alloc.9 \
600	disk.9 disk_create.9 \	602	disk.9 disk_create.9 \
601	disk.9 disk_destroy.9 \	603	disk.9 disk_destroy.9 \

Lines 40-49 Link Here

(-)devstat.9 (-63 / +34 lines)
40	.Nd kernel interface for keeping device statistics	40	.Nd kernel interface for keeping device statistics
41	.Sh SYNOPSIS	41	.Sh SYNOPSIS
42	.In sys/devicestat.h	42	.In sys/devicestat.h
43	.Ft void	43	.Ft struct devstat *
44	.Fo devstat_add_entry	44	.Fo devstat_new_entry
45	.Fa "struct devstat *ds"	45	.Fa "const void *dev_name"
46	.Fa "const char *dev_name"
47	.Fa "int unit_number"	46	.Fa "int unit_number"
48	.Fa "u_int32_t block_size"	47	.Fa "u_int32_t block_size"
49	.Fa "devstat_support_flags flags"	48	.Fa "devstat_support_flags flags"
Lines 53-65 Link Here
53	.Ft void	52	.Ft void
54	.Fn devstat_remove_entry "struct devstat *ds"	53	.Fn devstat_remove_entry "struct devstat *ds"
55	.Ft void	54	.Ft void
56	.Fn devstat_start_transaction "struct devstat *ds"	55	.Fo devstat_start_transaction
		56	.Fa "struct devstat *ds"
		57	.Fa "struct bintime *now"
		58	.Fc
		59	.Ft void
		60	.Fo devstat_start_transaction_bio
		61	.Fa "struct devstat *ds"
		62	.Fa "struct bio *bp"
		63	.Fc
57	.Ft void	64	.Ft void
58	.Fo devstat_end_transaction	65	.Fo devstat_end_transaction
59	.Fa "struct devstat *ds"	66	.Fa "struct devstat *ds"
60	.Fa "u_int32_t bytes"	67	.Fa "u_int32_t bytes"
61	.Fa "devstat_tag_type tag_type"	68	.Fa "devstat_tag_type tag_type"
62	.Fa "devstat_trans_flags flags"	69	.Fa "devstat_trans_flags flags"
		70	.Fa "struct bintime *now"
		71	.Fa "struct bintime *then"
63	.Fc	72	.Fc
64	.Ft void	73	.Ft void
65	.Fo devstat_end_transaction_bio	74	.Fo devstat_end_transaction_bio
Lines 77-95 Link Here
77	code.	86	code.
78	Instead, that is left for user programs to handle.	87	Instead, that is left for user programs to handle.
79	.Pp	88	.Pp
80	.Fn devstat_add_entry	89	.Fn devstat_new_entry
81	registers a device with the	90	allocates and initializes
82	.Nm	91	.Va devstat
83	subsystem.	92	structure and returns a pointer to it.
84	The caller is expected to have already allocated \fBand zeroed\fR	93	.Fn devstat_new_entry
85	the devstat structure before calling this function.
86	.Fn devstat_add_entry
87	takes several arguments:	94	takes several arguments:
88	.Bl -tag -width device_type	95	.Bl -tag -width device_type
89	.It ds
90	The
91	.Va devstat
92	structure, allocated and zeroed by the client.
93	.It dev_name	96	.It dev_name
94	The device name, e.g.\& da, cd, sa.	97	The device name, e.g.\& da, cd, sa.
95	.It unit_number	98	.It unit_number
Lines 147-153 Link Here
147	registers the end of a transaction with the	150	registers the end of a transaction with the
148	.Nm	151	.Nm
149	subsystem.	152	subsystem.
150	It takes four arguments:	153	It takes six arguments:
151	.Bl -tag -width tag_type	154	.Bl -tag -width tag_type
152	.It ds	155	.It ds
153	The	156	The
Lines 161-172 Link Here
161	.It flags	164	.It flags
162	Transaction flags indicating whether the transaction was a read, write, or	165	Transaction flags indicating whether the transaction was a read, write, or
163	whether no data was transferred.	166	whether no data was transferred.
		167	.It now
		168	Time when transaction started.
		169	.It then
		170	Time when transation ended.
164	.El	171	.El
165	.Pp	172	.Pp
		173	.Fn devstat_start_transaction_bio
		174	and
166	.Fn devstat_end_transaction_bio	175	.Fn devstat_end_transaction_bio
167	is a wrapper for	176	are wrappers for
		177	.Fn devstart_start_transaction
		178	and
168	.Fn devstat_end_transaction	179	.Fn devstat_end_transaction
169	which pulls all the information from a	180	respectively, which pull all the information from a
170	.Va "struct bio"	181	.Va "struct bio"
171	which is ready for biodone().	182	which is ready for biodone().
172	.Pp	183	.Pp
Lines 207-268 Link Here
207	This will hopefully	218	This will hopefully
208	eliminate the counter wrap that would come very quickly on some systems if	219	eliminate the counter wrap that would come very quickly on some systems if
209	32 bit integers were used.	220	32 bit integers were used.
210	.It bytes_read
211	This is the number of bytes that have been read from the device.
212	.It bytes_freed
213	This is the number of bytes that have been freed/erased on the device.
214	.It num_reads
215	This is the number of reads from the device.
216	.It num_writes
217	This is the number of writes to the device.
218	.It num_frees
219	This is the number of free/erase operations on the device.
220	.It num_other
221	This is the number of transactions to the device which are neither reads or
222	writes.
223	For instance,
224	.Tn SCSI
225	drivers often send a test unit ready command to
226	.Tn SCSI
227	devices.
228	The test unit ready command does not read or write any data.
229	It merely causes the device to return its status.
230	.It busy_count
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
234	the way
235	.Fn devstat_start_transaction
236	and
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.
241	.It block_size	221	.It block_size
242	This is the block size of the device, if the device has a block size.	222	This is the block size of the device, if the device has a block size.
243	.It tag_types	223	.It tag_types
244	This is an array of counters to record the number of various tag types that	224	This is an array of counters to record the number of various tag types that
245	are sent to a device.	225	are sent to a device.
246	See below for a list of tag types.	226	See below for a list of tag types.
247	.It dev_creation_time	227	.It creation_time
248	This is the time, as reported by	228	This is the time, as reported by
249	.Fn getmicrotime	229	.Fn getmicrotime
250	that the device was registered.	230	that the device was created.
251	.It busy_time	231	.It busy_time
252	This is the amount of time that the device busy count has been greater than	232	This is the amount of time that the device busy count has been greater than
253	zero.	233	zero.
254	This is only updated when the busy count returns to zero.	234	This is only updated when the busy count returns to zero.
255	.It start_time
256	This is the time, as reported by
257	.Fn getmicrouptime
258	that the device busy count went from zero to one.
259	.It last_comp_time
260	This is the time as reported by
261	.Fn getmicrouptime
262	that a transaction last completed.
263	It is used along with
264	.Va start_time
265	to calculate the device busy time.
266	.It flags	235	.It flags
267	These flags indicate which statistics measurements are supported by a	236	These flags indicate which statistics measurements are supported by a
268	particular device.	237	particular device.
Lines 284-289 Link Here
284	The second parameter is attach order.	253	The second parameter is attach order.
285	See below for a list of	254	See below for a list of
286	available priorities.	255	available priorities.
		256	.It id
		257	Identification for GEOM nodes.
287	.El	258	.El
288	.Pp	259	.Pp
289	Each device is given a device type.	260	Each device is given a device type.