Date: Wed, 25 May 2011 12:41:41 GMT From: Roman Bogorodskiy <novel@FreeBSD.org> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/157316: [patch] update devstat(9) man page Message-ID: <201105251241.p4PCffiO053778@freefall.freebsd.org> Resent-Message-ID: <201105251250.p4PCo9GN054561@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 157316
>Category: docs
>Synopsis: [patch] update devstat(9) man page
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Wed May 25 12:50:09 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator: Roman Bogorodskiy
>Release: FreeBSD 8.2-STABLE i386
>Organization:
>Environment:
System: FreeBSD freefall.freebsd.org 8.2-STABLE FreeBSD 8.2-STABLE #4 r220774: Mon Apr 18 13:56:14 UTC 2011 simon@freefall.freebsd.org:/usr/obj/usr/src/sys/FREEFALL i386
>Description:
devstat(9) manual page is out of date: it mentions devstat_add_entry()
which was deprecated long around (in 5.x times IIRC) and now it's not
even defined in sys/devicestat.h.
I made some changes to devstat(9) manual page:
* replaced devstat_add_entry with devstat_new_entry
* fixed other function prototypes
* added documentation for devstat_start_transaction_bio()
* synced MLINKS with currently available functions
* Removed some fields from 'struct devstat' description
Note: 'struct devstat' description in manual page now
misses a number of fields defined in the original struct. I don't
have enough devstat(9) subsystem knowledge to provide a
meaningful description for those fields.
>How-To-Repeat:
>Fix:
--- devstat_9.diff begins here ---
Index: Makefile
===================================================================
RCS file: /home/ncvs/src/share/man/man9/Makefile,v
retrieving revision 1.390
diff -u -r1.390 Makefile
--- Makefile 5 May 2011 14:13:08 -0000 1.390
+++ Makefile 25 May 2011 11:14:36 -0000
@@ -592,10 +592,12 @@
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_add_entry.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.9 \
+ devstat.9 devstat_start_transaction_bio.9
MLINKS+=disk.9 disk_alloc.9 \
disk.9 disk_create.9 \
disk.9 disk_destroy.9 \
Index: devstat.9
===================================================================
RCS file: /home/ncvs/src/share/man/man9/devstat.9,v
retrieving revision 1.23
diff -u -r1.23 devstat.9
--- devstat.9 28 Aug 2010 16:32:01 -0000 1.23
+++ devstat.9 25 May 2011 11:14:36 -0000
@@ -40,10 +40,9 @@
.Nd kernel interface for keeping device statistics
.Sh SYNOPSIS
.In sys/devicestat.h
-.Ft void
-.Fo devstat_add_entry
-.Fa "struct devstat *ds"
-.Fa "const char *dev_name"
+.Ft struct devstat *
+.Fo devstat_new_entry
+.Fa "const void *dev_name"
.Fa "int unit_number"
.Fa "u_int32_t block_size"
.Fa "devstat_support_flags flags"
@@ -53,13 +52,23 @@
.Ft void
.Fn devstat_remove_entry "struct devstat *ds"
.Ft void
-.Fn devstat_start_transaction "struct devstat *ds"
+.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
@@ -77,19 +86,13 @@
code.
Instead, that is left for user programs to handle.
.Pp
-.Fn devstat_add_entry
-registers a device with the
-.Nm
-subsystem.
-The caller is expected to have already allocated \fBand zeroed\fR
-the devstat structure before calling this function.
-.Fn devstat_add_entry
+.Fn devstat_new_entry
+allocates and initializes
+.Va devstat
+structure and returns a pointer to it.
+.Fn devstat_new_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
@@ -147,7 +150,7 @@
registers the end of a transaction with the
.Nm
subsystem.
-It takes four arguments:
+It takes six arguments:
.Bl -tag -width tag_type
.It ds
The
@@ -161,12 +164,20 @@
.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
-is a wrapper for
+are wrappers for
+.Fn devstart_start_transaction
+and
.Fn devstat_end_transaction
-which pulls all the information from a
+respectively, which pull all the information from a
.Va "struct bio"
which is ready for biodone().
.Pp
@@ -207,62 +218,20 @@
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 dev_creation_time
+.It creation_time
This is the time, as reported by
.Fn getmicrotime
-that the device was registered.
+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.
@@ -284,6 +253,8 @@
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.
--- devstat_9.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201105251241.p4PCffiO053778>