Attachment #115547 for bug #157316

View | Details | Raw Unified | Return to bug 157316 | Differences between
Collapse All | Expand All




.\"
.\" $FreeBSD$
.\"
.Dd May 22, 2011
.Dt DEVSTAT 9
.Os
.Sh NAME
.Nm devstat ,
.Nm devstat_add_entry ,
.Nm devstat_end_transaction ,
.Nm devstat_end_transaction_bio ,
.Nm devstat_new_entry ,
.Nm devstat_remove_entry ,
.Nm devstat_start_transaction ,
.Nm devstat_start_transaction_bio
.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
.Fn devstat_start_transaction "struct devstat *ds" "struct bintime *now"
.Ft void
.Fn devstat_start_transaction_bio "struct devstat *ds" "struct bio *bp"
.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
registers a device with the
.Nm
subsystem and returns a pointer to the allocated and initialized
.Va devstat
structure.
It takes several arguments:
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

.Nm
subsystem.
It takes the devstat structure for the device in question as
an argument and frees used memory back to the system.
The
.Nm
generation number is incremented and the number of devices is decremented.

registers the start of a transaction with the
.Nm
subsystem.
The start count is incremented with each transaction start.
When a device goes from idle to busy, the system uptime is recorded in the
.Va busy_from
field of the
.Va devstat
structure.
The caller can override the time value by specifying a non-NULL
timestamp argument
.Va now
to the function.
.Pp
.Fn devstat_end_transaction
registers the end of a transaction with the
.Nm
subsystem.
The end count is incremented with each transaction end.
It takes several 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
The current timestamp.
.It then
The timestamp of when this transaction started.
.El
.Pp
.Fn devstat_start_transaction_bio
and
.Fn devstat_end_transaction_bio
are wrappers for
.Fn devstat_start_transaction
and
.Fn devstat_end_transaction
respectively
which pull all the information from a
.Va "struct bio"
which is ready for biodone().
.Pp

.It unit_number
The unit number identifies the particular instance of the peripheral driver
in question.
.It bytes[flags]
This is the number of bytes that have been written, read or freed/erased on
the device according to a transaction type specified in flags index.
See below for transaction types.
This number is currently an unsigned 64 bit integer.
This will hopefully
eliminate the counter wrap that would come very quickly on some systems if
32 bit integers were used.
.It operations[flags]
This is the number of read, write or free/erase operations on the device
according to a transaction type specified in flags index.
.It duration[[flags]
The duration of read, write or free/erase operations on the device
according to a transaction type specified in flags index.
.It start_count , end_count
This are numbers of started and completed transactions for the device,
which are updated in the
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
paths respectively.
On an idle device their values should be equal.
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 binuptime
that the device was registered.
.It busy_time
This is the amount of time that the device was busy.
This is only updated during the ending of a transaction.
.It busy_from
This is the system time, as reported by
.Xr binuptime
when starting a transaction of a device that goes from idle to busy.
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.

	DEVSTAT_WRITE	= 0x02,
	DEVSTAT_FREE	= 0x03
} devstat_trans_flags;
#define	DEVSTAT_N_TRANS_FLAGS	4
.Ed
.Pp
DEVSTAT_NO_DATA is a type 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.
.Pp
There are four possible values for the
.Va tag_type
argument to

Return to bug 157316

Lines 27-49 Link Here

(-)devstat.9 (-70 / +71 lines)
27	.\"	27	.\"
28	.\" $FreeBSD$	28	.\" $FreeBSD$
29	.\"	29	.\"
30	.Dd May 22, 1998	30	.Dd May 22, 2011
31	.Dt DEVSTAT 9	31	.Dt DEVSTAT 9
32	.Os	32	.Os
33	.Sh NAME	33	.Sh NAME
34	.Nm devstat ,	34	.Nm devstat ,
35	.Nm devstat_add_entry ,
36	.Nm devstat_end_transaction ,	35	.Nm devstat_end_transaction ,
37	.Nm devstat_end_transaction_bio ,	36	.Nm devstat_end_transaction_bio ,
		37	.Nm devstat_new_entry ,
38	.Nm devstat_remove_entry ,	38	.Nm devstat_remove_entry ,
39	.Nm devstat_start_transaction	39	.Nm devstat_start_transaction ,
		40	.Nm devstat_start_transaction_bio
40	.Nd kernel interface for keeping device statistics	41	.Nd kernel interface for keeping device statistics
41	.Sh SYNOPSIS	42	.Sh SYNOPSIS
42	.In sys/devicestat.h	43	.In sys/devicestat.h
43	.Ft void	44	.Ft "struct devstat *"
44	.Fo devstat_add_entry	45	.Fo devstat_new_entry
45	.Fa "struct devstat *ds"	46	.Fa "const void *dev_name"
46	.Fa "const char *dev_name"
47	.Fa "int unit_number"	47	.Fa "int unit_number"
48	.Fa "u_int32_t block_size"	48	.Fa "u_int32_t block_size"
49	.Fa "devstat_support_flags flags"	49	.Fa "devstat_support_flags flags"
Lines 53-65 Link Here
53	.Ft void	53	.Ft void
54	.Fn devstat_remove_entry "struct devstat *ds"	54	.Fn devstat_remove_entry "struct devstat *ds"
55	.Ft void	55	.Ft void
56	.Fn devstat_start_transaction "struct devstat *ds"	56	.Fn devstat_start_transaction "struct devstat ds" "struct bintime now"
57	.Ft void	57	.Ft void
		58	.Fn devstat_start_transaction_bio "struct devstat ds" "struct bio bp"
		59	.Ft void
58	.Fo devstat_end_transaction	60	.Fo devstat_end_transaction
59	.Fa "struct devstat *ds"	61	.Fa "struct devstat *ds"
60	.Fa "u_int32_t bytes"	62	.Fa "u_int32_t bytes"
61	.Fa "devstat_tag_type tag_type"	63	.Fa "devstat_tag_type tag_type"
62	.Fa "devstat_trans_flags flags"	64	.Fa "devstat_trans_flags flags"
		65	.Fa "struct bintime *now"
		66	.Fa "struct bintime *then"
63	.Fc	67	.Fc
64	.Ft void	68	.Ft void
65	.Fo devstat_end_transaction_bio	69	.Fo devstat_end_transaction_bio
Lines 77-95 Link Here
77	code.	81	code.
78	Instead, that is left for user programs to handle.	82	Instead, that is left for user programs to handle.
79	.Pp	83	.Pp
80	.Fn devstat_add_entry	84	.Fn devstat_new_entry
81	registers a device with the	85	registers a device with the
82	.Nm	86	.Nm
83	subsystem.	87	subsystem and returns a pointer to the allocated and initialized
84	The caller is expected to have already allocated \fBand zeroed\fR	88	.Va devstat
85	the devstat structure before calling this function.	89	structure.
86	.Fn devstat_add_entry	90	It takes several arguments:
87	takes several arguments:
88	.Bl -tag -width device_type	91	.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	92	.It dev_name
94	The device name, e.g.\& da, cd, sa.	93	The device name, e.g.\& da, cd, sa.
95	.It unit_number	94	.It unit_number
Lines 127-133 Link Here
127	.Nm	126	.Nm
128	subsystem.	127	subsystem.
129	It takes the devstat structure for the device in question as	128	It takes the devstat structure for the device in question as
130	an argument.	129	an argument and frees used memory back to the system.
131	The	130	The
132	.Nm	131	.Nm
133	generation number is incremented and the number of devices is decremented.	132	generation number is incremented and the number of devices is decremented.
Lines 136-153 Link Here
136	registers the start of a transaction with the	135	registers the start of a transaction with the
137	.Nm	136	.Nm
138	subsystem.	137	subsystem.
139	The busy count is incremented with each transaction start.	138	The start count is incremented with each transaction start.
140	When a device goes from idle to busy, the system uptime is recorded in the	139	When a device goes from idle to busy, the system uptime is recorded in the
141	.Va start_time	140	.Va busy_from
142	field of the	141	field of the
143	.Va devstat	142	.Va devstat
144	structure.	143	structure.
		144	The caller can override the time value by specifying a non-NULL
		145	timestamp argument
		146	.Va now
		147	to the function.
145	.Pp	148	.Pp
146	.Fn devstat_end_transaction	149	.Fn devstat_end_transaction
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	The end count is incremented with each transaction end.
		154	It takes several arguments:
151	.Bl -tag -width tag_type	155	.Bl -tag -width tag_type
152	.It ds	156	.It ds
153	The	157	The
Lines 161-172 Link Here
161	.It flags	165	.It flags
162	Transaction flags indicating whether the transaction was a read, write, or	166	Transaction flags indicating whether the transaction was a read, write, or
163	whether no data was transferred.	167	whether no data was transferred.
		168	.It now
		169	The current timestamp.
		170	.It then
		171	The timestamp of when this transaction started.
164	.El	172	.El
165	.Pp	173	.Pp
		174	.Fn devstat_start_transaction_bio
		175	and
166	.Fn devstat_end_transaction_bio	176	.Fn devstat_end_transaction_bio
167	is a wrapper for	177	are wrappers for
		178	.Fn devstat_start_transaction
		179	and
168	.Fn devstat_end_transaction	180	.Fn devstat_end_transaction
169	which pulls all the information from a	181	respectively
		182	which pull all the information from a
170	.Va "struct bio"	183	.Va "struct bio"
171	which is ready for biodone().	184	which is ready for biodone().
172	.Pp	185	.Pp
Lines 201-268 Link Here
201	.It unit_number	214	.It unit_number
202	The unit number identifies the particular instance of the peripheral driver	215	The unit number identifies the particular instance of the peripheral driver
203	in question.	216	in question.
204	.It bytes_written	217	.It bytes[flags]
205	This is the number of bytes that have been written to the device.	218	This is the number of bytes that have been written, read or freed/erased on
		219	the device according to a transaction type specified in flags index.
		220	See below for transaction types.
206	This number is currently an unsigned 64 bit integer.	221	This number is currently an unsigned 64 bit integer.
207	This will hopefully	222	This will hopefully
208	eliminate the counter wrap that would come very quickly on some systems if	223	eliminate the counter wrap that would come very quickly on some systems if
209	32 bit integers were used.	224	32 bit integers were used.
210	.It bytes_read	225	.It operations[flags]
211	This is the number of bytes that have been read from the device.	226	This is the number of read, write or free/erase operations on the device
212	.It bytes_freed	227	according to a transaction type specified in flags index.
213	This is the number of bytes that have been freed/erased on the device.	228	.It duration[[flags]
214	.It num_reads	229	The duration of read, write or free/erase operations on the device
215	This is the number of reads from the device.	230	according to a transaction type specified in flags index.
216	.It num_writes	231	.It start_count , end_count
217	This is the number of writes to the device.	232	This are numbers of started and completed transactions for the device,
218	.It num_frees	233	which are updated in the
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	234	.Fn devstat_start_transaction
236	and	235	and
237	.Fn devstat_end_transaction	236	.Fn devstat_end_transaction
238	are being called in client code.	237	paths respectively.
239	There should be one and only one	238	On an idle device their values should be equal.
240	transaction start event and one transaction end event for each transaction.
241	.It block_size	239	.It block_size
242	This is the block size of the device, if the device has a block size.	240	This is the block size of the device, if the device has a block size.
243	.It tag_types	241	.It tag_types
244	This is an array of counters to record the number of various tag types that	242	This is an array of counters to record the number of various tag types that
245	are sent to a device.	243	are sent to a device.
246	See below for a list of tag types.	244	See below for a list of tag types.
247	.It dev_creation_time	245	.It creation_time
248	This is the time, as reported by	246	This is the time, as reported by
249	.Fn getmicrotime	247	.Fn binuptime
250	that the device was registered.	248	that the device was registered.
251	.It busy_time	249	.It busy_time
252	This is the amount of time that the device busy count has been greater than	250	This is the amount of time that the device was busy.
253	zero.	251	This is only updated during the ending of a transaction.
254	This is only updated when the busy count returns to zero.	252	.It busy_from
255	.It start_time	253	This is the system time, as reported by
256	This is the time, as reported by	254	.Xr binuptime
257	.Fn getmicrouptime	255	when starting a transaction of a device that goes from idle to busy.
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	256	.It flags
267	These flags indicate which statistics measurements are supported by a	257	These flags indicate which statistics measurements are supported by a
268	particular device.	258	particular device.
Lines 378-385 Link Here
378	DEVSTAT_WRITE = 0x02,	368	DEVSTAT_WRITE = 0x02,
379	DEVSTAT_FREE = 0x03	369	DEVSTAT_FREE = 0x03
380	} devstat_trans_flags;	370	} devstat_trans_flags;
		371	#define DEVSTAT_N_TRANS_FLAGS 4
381	.Ed	372	.Ed
382	.Pp	373	.Pp
		374	DEVSTAT_NO_DATA is a type of transactions to the device which are neither
		375	reads or writes.
		376	For instance,
		377	.Tn SCSI
		378	drivers often send a test unit ready command to
		379	.Tn SCSI
		380	devices.
		381	The test unit ready command does not read or write any data.
		382	It merely causes the device to return its status.
		383	.Pp
383	There are four possible values for the	384	There are four possible values for the
384	.Va tag_type	385	.Va tag_type
385	argument to	386	argument to