physio(9) from NetBSD

2 files changed, 149 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 85d734c8e11..1780a65b7ca 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.35 2001/03/16 02:32:48 csapuntz Exp $
+#	$OpenBSD: Makefile,v 1.36 2001/06/20 16:47:32 millert Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -7,7 +7,7 @@ MAN=	audio.9 boot.9 bus_dma.9 bus_space.9 \
 	copy.9 crypto.9 ctxsw.9 disk.9 disklabel.9 \
 	dopowerhooks.9 doshutdownhooks.9 fetch.9 fork1.9 \
 	extent.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 kthread.9 \
-	malloc.9 md5.9 microtime.9 panic.9 pfind.9 pool.9 \
+	malloc.9 md5.9 microtime.9 panic.9 pfind.9 physio.9 pool.9 \
 	powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
 	ratecheck.9 resettodr.9 random.9 shutdownhook_establish.9 \
 	sleep.9 spl.9 store.9 style.9 time.9 timeout.9 uvm.9 \
diff --git a/share/man/man9/physio.9 b/share/man/man9/physio.9
new file mode 100644
index 00000000000..8199f897477
--- /dev/null
+++ b/share/man/man9/physio.9
@@ -0,0 +1,147 @@
+.\"	$OpenBSD: physio.9,v 1.1 2001/06/20 16:47:32 millert Exp $
+.\"	$NetBSD: physio.9,v 1.5 1999/03/16 00:40:47 garbled Exp $
+.\"
+.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Paul Kranenburg.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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 June 15, 1996
+.Dt PHYSIO 9
+.Os
+.Sh NAME
+.Nm physio
+.Nd initiate I/O on raw devices
+.Sh SYNOPSIS
+.Ft int
+.Fo "physio"
+.Fa "void (*strategy)(struct buf *)"
+.Fa "struct buf *bp"
+.Fa "dev_t dev"
+.Fa "int flags"
+.Fa "void (*minphys)(struct buf *)"
+.Fa "struct uio *uio"
+.Fc
+.Sh DESCRIPTION
+.Fn physio
+is a helper function typically called from character device read and write
+routines to start I/O on a user process buffer.
+It calls back on the provided
+.Fa strategy
+routine one or more times to complete the transfer described by
+.Fa uio .
+The maximum amount of data to transfer with each call to
+.Fa strategy
+is determined by the
+.Fa minphys
+routine.
+Since
+.Fa uio
+normally describes user space addresses,
+.Fn physio
+needs to lock the appropriate data area into memory before each transaction
+with
+.Fa strategy ( see the
+.Fn uvm_vslock
+and
+.Fn uvm_vsunlock
+functions in
+.Xr uvm 9 ).
+.Fn physio
+always awaits the completion of the entire requested transfer before
+returning, unless an error condition is detected earlier.
+In all cases, the buffer passed in
+.Fa bp
+is locked (marked as
+.Dq busy )
+for the duration of the entire transfer.
+.Pp
+A break-down of the arguments follows:
+.Bl -tag -width indent
+.It Fa strategy
+The device strategy routine to call for each chunk of data to initiate
+device I/O.
+.It Fa bp
+The buffer to use with the strategy routine.
+The buffer flags will have
+.Dv B_BUSY ,
+.Dv B_PHYS ,
+and
+.Dv B_RAW
+set when passed to the strategy routine.
+If
+.Dv NULL ,
+a buffer is allocated from a system pool.
+.It Fa dev
+The device number identifying the device to interact with.
+.It Fa flags
+Direction of transfer; the only valid settings are
+.Dv B_READ
+or
+.Dv B_WRITE .
+.It Fa minphys
+A device specific routine called to determine the maximum transfer size
+that the device's strategy routine can handle.
+.It Fa uio
+The description of the entire transfer as requested by the user process.
+Currently, the results of passing a
+.Fa uio
+structure with the
+.Sq uio_segflg
+set to anything other than
+.Dv UIO_USERSPACE ,
+are undefined.
+.El
+.Pp
+.Sh RETURN VALUES
+If successful
+.Fn physio
+returns 0.
+.Er EFAULT
+is returned if the address range described by
+.Fa uio
+is not accessable by the requesting process.
+.Fn physio
+will return any error resulting from calls to the device strategy routine,
+by examining the
+.Dv B_ERROR
+buffer flag and the
+.Sq b_error
+field.
+Note that the actual transfer size may be less than requested by
+.Fa uio
+if the device signals an
+.Dq end of file
+condition.
+.Sh SEE ALSO
+.Xr read 2 ,
+.Xr write 2