[src/trunk]: src/share/man/man9 New man page bufferio(9) for I/O transfer vie...

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

details:   https://anonhg.NetBSD.org/src/rev/34b1c2fb7573
branches:  trunk
changeset: 336997:34b1c2fb7573
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun Mar 29 20:56:01 2015 +0000

description:
New man page bufferio(9) for I/O transfer view of struct buf.

Move biowait/biodone from buffercache(9) man page.

diffstat:

 share/man/man9/buffercache.9 |   30 +---
 share/man/man9/bufferio.9    |  390 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 392 insertions(+), 28 deletions(-)

diffs (truncated from 456 to 300 lines):

diff -r e25b086ffb4f -r 34b1c2fb7573 share/man/man9/buffercache.9
--- a/share/man/man9/buffercache.9      Sun Mar 29 19:42:15 2015 +0000
+++ b/share/man/man9/buffercache.9      Sun Mar 29 20:56:01 2015 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: buffercache.9,v 1.27 2015/03/28 19:24:04 maxv Exp $
+.\"     $NetBSD: buffercache.9,v 1.28 2015/03/29 20:56:01 riastradh Exp $
 .\"
 .\" Copyright (c)2003 YAMAMOTO Takashi,
 .\" All rights reserved.
@@ -115,9 +115,7 @@
 .Nm geteblk ,
 .Nm incore ,
 .Nm allocbuf ,
-.Nm brelse ,
-.Nm biodone ,
-.Nm biowait
+.Nm brelse
 .Nd buffer cache interfaces
 .\" ------------------------------------------------------------
 .Sh SYNOPSIS
@@ -146,10 +144,6 @@
 .Fn allocbuf "buf_t *bp" "int size" "int preserve"
 .Ft void
 .Fn brelse "buf_t *bp" "int set"
-.Ft void
-.Fn biodone "buf_t *bp"
-.Ft int
-.Fn biowait "buf_t *bp"
 .\" ------------------------------------------------------------
 .Sh DESCRIPTION
 The
@@ -319,18 +313,6 @@
 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 .It Fn brelse "bp" "set"
 Unbusy a buffer and release it to the free lists.
-.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-.It Fn biodone "bp"
-Mark I/O complete on a buffer.
-If a callback has been requested by
-.Dv B_CALL ,
-do so.
-Otherwise, wakeup waiters.
-.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-.It Fn biowait "bp"
-Wait for operations on the buffer to complete.
-When they do, extract and return the I/O's error value.
-.El
 .\" ------------------------------------------------------------
 .Sh CODE REFERENCES
 The buffer cache subsystem is implemented within the file
@@ -359,11 +341,3 @@
 .Fn bread
 and its variants
 don't use a specified credential.
-.Pp
-Because
-.Fn biodone
-and
-.Fn biowait
-do not really belong to
-.Nm ,
-they shouldn't be documented here.
diff -r e25b086ffb4f -r 34b1c2fb7573 share/man/man9/bufferio.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/bufferio.9 Sun Mar 29 20:56:01 2015 +0000
@@ -0,0 +1,390 @@
+.\"    $NetBSD: bufferio.9,v 1.1 2015/03/29 20:56:01 riastradh Exp $
+.\"
+.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Taylor R. Campbell.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd March 29, 2015
+.Dt BUFFERIO 9
+.Os
+.Sh NAME
+.Nm BUFFERIO ,
+.Nm biodone ,
+.Nm biowait ,
+.Nm getiobuf ,
+.Nm putiobuf ,
+.Nm nestiobuf_setup ,
+.Nm nestiobuf_done
+.Nd block I/O buffer transfers
+.Sh SYNOPSIS
+.In sys/buf.h
+.Ft void
+.Fn biodone "struct buf *bp"
+.Ft int
+.Fn biowait "struct buf *bp"
+.Ft struct buf *
+.Fn getiobuf "struct vnode *vp" "bool waitok"
+.Ft void
+.Fn putiobuf "struct buf *bp"
+.Ft void
+.Fn nestiobuf_setup "struct buf *mbp" "struct buf *bp" "int offset" \
+        "size_t size"
+.Ft void
+.Fn nestiobuf_done "struct buf *mbp" "int donebytes" "int error"
+.Sh DESCRIPTION
+The
+.Nm
+subsystem manages block I/O buffer transfers, described by the
+.Vt "struct buf"
+structure, which serves multiple purposes between users in
+.Nm ,
+users in
+.Xr buffercache 9 ,
+and users in block device drivers to execute transfers to physical
+disks.
+.Sh BLOCK DEVICE USERS
+Users of
+.Nm
+wishing to submit a buffer for block I/O transfer must obtain a
+.Vt "struct buf" ,
+e.g. via
+.Fn getiobuf ,
+fill its parameters, and submit it to a block device with
+.Xr bdev_strategy 9 ,
+usually via
+.Xr VOP_STRATEGY 9 .
+.Pp
+The parameters to an I/O transfer described by
+.Fa bp
+are specified by the following
+.Vt "struct buf"
+fields:
+.Bl -tag -offset abcd
+.It Fa bp Ns Li "->b_flags"
+Flags specifying the type of transfer.
+.Bl -tag -compact
+.It Dv B_READ
+Transfer is read from device.
+If not set, transfer is write to device.
+.It Dv B_ASYNC
+Asynchronous I/O.
+Caller must provide
+.Fa bp Ns Li "->b_iodone"
+and must not call
+.Fn biowait bp .
+.El
+.It Fa bp Ns Li "->b_data"
+Pointer to kernel virtual address of source/target for transfer.
+.It Fa bp Ns Li "->b_bcount"
+Nonnegative number of bytes requested for transfer.
+.It Fa bp Ns Li "->b_blkno"
+Block number at which to do transfer.
+.It Fa bp Ns Li "->b_iodone"
+If
+.Dv B_ASYNC
+is set in
+.Fa bp Ns Li "->b_flags" ,
+an I/O completion callback.
+.El
+.Pp
+Additionally, if the I/O transfer is a write associated with a
+.Xr vnode 9
+.Fa vp ,
+then before the user submits it to a block device, the user must
+increment
+.Fa vp Ns Li "->v_numoutput" .
+The user must not acquire
+.Fa vp Ns No 's
+vnode lock between incrementing
+.Fa vp Ns Li "->v_numoutput"
+and submitting
+.Fa bp
+to a block device -- doing so will likely cause deadlock with the
+syncer.
+.Pp
+Block I/O transfers may be synchronous or asynchronous:
+.Bl -dash
+.It
+If synchronous, after submitting the transfer to a block device, the
+user must call
+.Fn biowait bp
+in order to wait until the transfer has completed.
+.It
+If asynchronous, the user must set
+.Dv B_ASYNC
+in
+.Fa bp Ns Li "->b_flags"
+and provide
+.Fa bp Ns Li "->b_iodone" .
+After submitting the transfer to a block device,
+.Fa bp Ns Li "->b_iodone"
+will eventually be called with
+.Fa bp
+as its argument when the transfer has completed.
+The user
+.Em may not
+call
+.Fn biowait bp
+in this case.
+.El
+.Sh NESTED I/O TRANSFERS
+Sometimes an I/O transfer from a single buffer in memory cannot go to a
+single location on a block device: it must be split up into smaller
+transfers for each segment of the memory buffer.
+.Pp
+After initializing the
+.Li b_flags ,
+.Li b_data ,
+and
+.Li b_bcount
+parameters of an I/O transfer for the buffer, called the
+.Em master
+buffer, the user can issue smaller transfers for segments of the buffer
+using
+.Fn nestiobuf_setup .
+The nested I/O transfers are asynchronous -- when they complete, they
+debit from the amount of work left to be done in the master buffer.
+If any segments of the buffer were skipped, the user can report this
+with
+.Fn nestiobuf_done
+to debit the skipped part of the work.
+.Pp
+The master buffer's I/O transfer is completed when all nested buffers'
+I/O transfers are completed, and if
+.Fn nestiobuf_done
+is called in the case of skipped segments.
+.Pp
+For writes associated with a vnode
+.Fa vp ,
+.Fn nestiobuf_setup
+accounts for
+.Fa vp Ns Li "->v_numoutput" ,
+so the caller is not allowed to acquire
+.Fa vp Ns No 's
+vnode lock before submitting the nested I/O transfer to a block
+device.
+However, the caller is responsible for accounting the master buffer in
+.Fa vp Ns Li "->v_numoutput" .
+This must be done very carefully because after incrementing
+.Fa vp Ns Li "->v_numoutput" ,
+the caller is not allowed to acquire
+.Fa vp Ns No 's
+vnode lock before either calling
+.Fn nestiobuf_done
+or submitting the last nested I/O transfer to a block device.
+.Pp
+For example:
+.Bd -literal -offset abcd
+\&struct buf *mbp, *bp;
+\&size_t skipped = 0;
+\&unsigned i;
+\&int error = 0;
+\&
+\&mbp = getiobuf(vp, true);
+\&mbp->b_data = data;
+\&mbp->b_resid = mbp->b_bcount = datalen;
+\&mbp->b_flags = B_WRITE;
+\&
+\&KASSERT(i < nsegs);
+\&for (i = 0; i < nsegs; i++) {
+\&     struct vnode *devvp;
+\&     daddr_t blkno;
+\&
+\&     vn_lock(vp, LK_EXCLUSIVE | LK_RETRY);
+\&     error = VOP_BMAP(vp, i*segsz, &devvp, &blkno, NULL);
+\&     VOP_UNLOCK(vp);
+\&     if (error == 0 && nbn == -1)
+\&             error = EIO;
+\&     if (error) {
+\&             skipped += segsz;
+\&             break;
+\&     }
+\&
+\&     bp = getiobuf(vp, true);
+\&     nestiobuf_setup(bp, mbp, i*segsz, segsz);
+\&     bp->b_blkno = blkno;
+\&     if (i == nsegs - 1)     /* Last segment.  */
+\&             break;
+\&     VOP_STRATEGY(devvp, bp);
+\&}
+\&
+\&/*