[src/trunk]: src/share/man/man9 Mention problems which disk api have with con...

[haad <haad%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f054e62d80e4
branches:  trunk
changeset: 750399:f054e62d80e4
user:      haad <haad%NetBSD.org@localhost>
date:      Wed Dec 30 00:08:01 2009 +0000

description:
Mention problems which disk api have with concurrent usage remove splbio
line from man page because it is not true anymore, mention disk_isbusy and
add dm driver to references.

diffstat:

 share/man/man9/disk.9 |  51 +++++++++++++++++++++++++++++++++++++--------------
 1 files changed, 37 insertions(+), 14 deletions(-)

diffs (147 lines):

diff -r e6a604183edc -r f054e62d80e4 share/man/man9/disk.9
--- a/share/man/man9/disk.9     Tue Dec 29 23:37:47 2009 +0000
+++ b/share/man/man9/disk.9     Wed Dec 30 00:08:01 2009 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: disk.9,v 1.32 2009/05/20 06:38:39 wiz Exp $
+.\"    $NetBSD: disk.9,v 1.33 2009/12/30 00:08:01 haad Exp $
 .\"
 .\" Copyright (c) 1995, 1996 Jason R. Thorpe.
 .\" All rights reserved.
@@ -30,7 +30,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 19, 2009
+.Dd December 30, 2009
 .Dt DISK 9
 .Os
 .Sh NAME
@@ -42,6 +42,7 @@
 .Nm disk_destroy ,
 .Nm disk_busy ,
 .Nm disk_unbusy ,
+.Nm disk_isbusy ,
 .Nm disk_find ,
 .Nm disk_blocksize
 .Nd generic disk framework
@@ -63,6 +64,8 @@
 .Fn disk_busy "struct disk *"
 .Ft void
 .Fn disk_unbusy "struct disk *" "long bcount" "int read"
+.Ft bool
+.Fn disk_isbusy "struct disk *"
 .Ft struct disk *
 .Fn disk_find "const char *"
 .Ft void
@@ -127,8 +130,10 @@
 Drivers which currently make use of the detachment
 capability of the framework are the
 .Nm ccd
+,
+.Nm vnd
 and
-.Nm vnd
+.Nm dm
 pseudo-device drivers.
 .Pp
 The following is a brief description of each function in the framework:
@@ -181,6 +186,10 @@
 specifies the direction of I/O;
 if non-zero it means reading from the disk,
 otherwise it means writing to the disk.
+.It Fn disk_isbusy
+Returns 
+.Ar true 
+if disk is marked as busy and false if it is not.
 .It Fn disk_find
 Return a pointer to the disk structure corresponding to the name provided,
 or NULL if the disk does not exist.
@@ -374,6 +383,14 @@
 and
 .Fn disk_unbusy
 routines.
+Because 
+.Nm struct disk 
+is part of device driver private data it needs to be guarded. Mutual exclusion
+must be done by driver 
+.Fn disk_busy
+and
+.Fn disk_unbusy
+are not thread safe.
 The
 .Fn disk_busy
 routine should be called immediately before a command to the disk is
@@ -392,7 +409,9 @@
        [ . . . ]
 
        /* Tell the disk framework we're going busy. */
+       mutex_enter(\*[Am]sc-\*[Gt]sc_dk_mtx);
        disk_busy(\*[Am]sc-\*[Gt]sc_dk);
+       mutex_exit(\*[Am]sc-\*[Gt]sc_dk_mtx);
 
        /* Send command to the drive. */
        [ . . . ]
@@ -403,10 +422,6 @@
 .Fn disk_busy
 is called, a timestamp is taken if the disk's busy counter moves from
 0 to 1, indicating the disk has gone from an idle to non-idle state.
-Note that
-.Fn disk_busy
-must be called at
-.Fn splbio .
 At the end of a transaction, the
 .Fn disk_unbusy
 routine should be called.
@@ -451,19 +466,23 @@
 
        [ . . . ]
 
+       mutex_enter(\*[Am]sc-\*[Gt]sc_dk_mtx);
        /* Notify the disk framework that we've completed the transfer. */
        disk_unbusy(\*[Am]sc-\*[Gt]sc_dk, nbytes,
            bp != NULL ? bp-\*[Gt]b_flags \*[Am] B_READ : 0);
+       mutex_exit(\*[Am]sc-\*[Gt]sc_dk_mtx);
 
        [ . . . ]
 }
 .Ed
 .Pp
-Like
-.Fn disk_busy ,
+.Fn disk_isbusy 
+is used to get status of disk device it returns true if device is currently busy
+and false if it is not. Like 
+.Fn disk_busy
+and
 .Fn disk_unbusy
-must be called at
-.Fn splbio .
+it requires explicit locking from user side.
 .Sh CODE REFERENCES
 This section describes places within the
 .Nx
@@ -489,17 +508,21 @@
 The
 .Nx
 .Nm ccd
+,
+.Nm vnd
 and
-.Nm vnd
+.Nm dm
 drivers use the detachment capability of the framework.
 They are located in
 .Pa sys/dev/ccd.c
+,
+.Pa sys/dev/vnd.c
 and
-.Pa sys/dev/vnd.c .
+.Pa sys/dev/dm/device-mapper.c .
 .Sh SEE ALSO
 .Xr ccd 4 ,
 .Xr vnd 4 ,
-.Xr spl 9
+.Xr dm 4
 .Sh HISTORY
 The
 .Nx