From owner-freebsd-doc@FreeBSD.ORG Wed May 25 12:50:09 2011 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A7DC0106566C for ; Wed, 25 May 2011 12:50:09 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 841168FC12 for ; Wed, 25 May 2011 12:50:09 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id p4PCo9GP054562 for ; Wed, 25 May 2011 12:50:09 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id p4PCo9GN054561; Wed, 25 May 2011 12:50:09 GMT (envelope-from gnats) Resent-Date: Wed, 25 May 2011 12:50:09 GMT Resent-Message-Id: <201105251250.p4PCo9GN054561@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Roman Bogorodskiy Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id CAD1C106566C for ; Wed, 25 May 2011 12:41:41 +0000 (UTC) (envelope-from novel@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id BA4A08FC08 for ; Wed, 25 May 2011 12:41:41 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id p4PCfft9053779 for ; Wed, 25 May 2011 12:41:41 GMT (envelope-from novel@freefall.freebsd.org) Received: (from novel@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id p4PCffiO053778; Wed, 25 May 2011 12:41:41 GMT (envelope-from novel) Message-Id: <201105251241.p4PCffiO053778@freefall.freebsd.org> Date: Wed, 25 May 2011 12:41:41 GMT From: Roman Bogorodskiy To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/157316: [patch] update devstat(9) man page X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Roman Bogorodskiy List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 25 May 2011 12:50:09 -0000 >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: