Document copyin_nofault, copyout_nofault, uiomove_nofault.

Submitted by:	alc

3 files changed, 84 insertions, 22 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 815ddd0..e6adcf4 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -551,8 +551,10 @@ MLINKS+=config_intrhook.9 config_intrhook_disestablish.9 \
 	config_intrhook.9 config_intrhook_establish.9
 MLINKS+=contigmalloc.9 contigfree.9
 MLINKS+=copy.9 copyin.9 \
+	copy.9 copyin_nofault.9 \
 	copy.9 copyinstr.9 \
 	copy.9 copyout.9 \
+	copy.9 copyout_nofault.9 \
 	copy.9 copystr.9
 MLINKS+=critical_enter.9 critical.9 \
 	critical_enter.9 critical_exit.9
@@ -1284,7 +1286,8 @@ MLINKS+=uidinfo.9 uifind.9 \
 	uidinfo.9 uifree.9 \
 	uidinfo.9 uihashinit.9 \
 	uidinfo.9 uihold.9
-MLINKS+=uio.9 uiomove.9
+MLINKS+=uio.9 uiomove.9 \
+	uio.9 uiomove_nofault.9
 MLINKS+=usbdi.9 usbd_do_request.9 \
 	usbdi.9 usbd_do_request_flags.9 \
 	usbdi.9 usbd_errstr.9 \
diff --git a/share/man/man9/copy.9 b/share/man/man9/copy.9
index b6b975f..37c7a0c 100644
--- a/share/man/man9/copy.9
+++ b/share/man/man9/copy.9
@@ -34,13 +34,15 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 7, 1996
+.Dd July 9, 2011
 .Dt COPY 9
 .Os
 .Sh NAME
 .Nm copy ,
 .Nm copyin ,
+.Nm copyin_nofault ,
 .Nm copyout ,
+.Nm copyout_nofault ,
 .Nm copystr ,
 .Nm copyinstr
 .Nd kernel copy functions
@@ -50,8 +52,12 @@
 .Ft int
 .Fn copyin "const void *uaddr" "void *kaddr" "size_t len"
 .Ft int
+.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len"
+.Ft int
 .Fn copyout "const void *kaddr" "void *uaddr" "size_t len"
 .Ft int
+.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len"
+.Ft int
 .Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done"
 .Ft int
 .Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done"
@@ -67,25 +73,40 @@ All but
 copy data from user-space to kernel-space or vice-versa.
 .Pp
 The
-.Nm
-routines provide the following functionality:
-.Bl -tag -width "copyoutstr()"
-.It Fn copyin
-Copies
+.Fn copyin
+and
+.Fn copyin_nofault
+functions copy
 .Fa len
 bytes of data from the user-space address
 .Fa uaddr
 to the kernel-space address
 .Fa kaddr .
-.It Fn copyout
-Copies
+.Pp
+The
+.Fn copyout
+and
+.Fn copyout_nofault
+functions copy
 .Fa len
 bytes of data from the kernel-space address
 .Fa kaddr
 to the user-space address
 .Fa uaddr .
-.It Fn copystr
-Copies a NUL-terminated string, at most
+.Pp
+The
+.Fn copyin_nofault
+and
+.Fn copyout_nofault
+functions require that the kernel-space and user-space data be
+accessible without incurring a page fault.
+The source and destination addresses must be physically mapped for
+read and write access, respectively, and neither the source nor
+destination addresses may be pageable.
+.Pp
+The
+.Fn copystr
+function copies a NUL-terminated string, at most
 .Fa len
 bytes long, from kernel-space address
 .Fa kfaddr
@@ -98,8 +119,10 @@ NUL, is returned in
 .Fa done
 is
 .No non- Ns Dv NULL ) .
-.It Fn copyinstr
-Copies a NUL-terminated string, at most
+.Pp
+The
+.Fn copyinstr
+function copies a NUL-terminated string, at most
 .Fa len
 bytes long, from user-space address
 .Fa uaddr
@@ -121,7 +144,6 @@ is
 .\" The number of bytes actually copied, including the terminating
 .\" NUL, is returned in
 .\" .Fa *done .
-.El
 .Sh RETURN VALUES
 The
 .Nm
@@ -129,7 +151,13 @@ functions return 0 on success or
 .Er EFAULT
 if a bad address is encountered.
 In addition, the
-.Fn copystr ,
+.Fn copyin_nofault
+and
+.Fn copyout_nofault
+functions return
+.Er EFAULT
+if a page fault occurs, and the
+.Fn copystr
 and
 .Fn copyinstr
 .\" .Fn copyinstr ,
diff --git a/share/man/man9/uio.9 b/share/man/man9/uio.9
index fb27c9c..9d569b7 100644
--- a/share/man/man9/uio.9
+++ b/share/man/man9/uio.9
@@ -25,12 +25,13 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 21, 2010
+.Dd July 9, 2011
 .Dt UIO 9
 .Os
 .Sh NAME
 .Nm uio ,
-.Nm uiomove
+.Nm uiomove ,
+.Nm uiomove_nofault
 .Nd device driver I/O routines
 .Sh SYNOPSIS
 .In sys/types.h
@@ -48,11 +49,15 @@ struct uio {
 .Ed
 .Ft int
 .Fn uiomove "void *buf" "int howmuch" "struct uio *uiop"
+.Ft int
+.Fn uiomove_nofault "void *buf" "int howmuch" "struct uio *uiop"
 .Sh DESCRIPTION
-The function
+The functions
 .Fn uiomove
-is used to handle transfer of data between buffers and I/O vectors
-that might possibly also cross the user/kernel space boundary.
+and
+.Fn uiomove_nofault
+are used to transfer data between buffers and I/O vectors that might
+possibly cross the user/kernel space boundary.
 .Pp
 As a result of any
 .Xr read 2 ,
@@ -71,6 +76,8 @@ being passed.
 The transfer request is encoded in this structure.
 The driver itself should use
 .Fn uiomove
+or
+.Fn uiomove_nofault
 to get at the data in this structure.
 .Pp
 The fields in the
@@ -99,7 +106,7 @@ Do not copy, already in object.
 .El
 .It Va uio_rw
 The direction of the desired transfer, either
-.Dv UIO_READ ,
+.Dv UIO_READ
 or
 .Dv UIO_WRITE .
 .It Va uio_td
@@ -110,10 +117,24 @@ for the associated thread; used if
 indicates that the transfer is to be made from/to a process's address
 space.
 .El
+.Pp
+The function
+.Fn uiomove_nofault
+requires that the buffer and I/O vectors be accessible without
+incurring a page fault.
+The source and destination addresses must be physically mapped for
+read and write access, respectively, and neither the source nor
+destination addresses may be pageable.
+Thus, the function
+.Fn uiomove_nofault
+can be called from contexts where acquiring virtual memory system
+locks or sleeping are prohibited.
 .Sh RETURN VALUES
 On success
 .Fn uiomove
-will return 0, on error it will return an appropriate errno.
+and
+.Fn uiomove_nofault
+will return 0; on error they will return an appropriate error code.
 .Sh EXAMPLES
 The idea is that the driver maintains a private buffer for its data,
 and processes the request in chunks of maximal the size of this
@@ -156,6 +177,8 @@ fooread(dev_t dev, struct uio *uio, int flag)
 .Ed
 .Sh ERRORS
 .Fn uiomove
+and
+.Fn uiomove_nofault
 will fail and return the following error code if:
 .Bl -tag -width Er
 .It Bq Er EFAULT
@@ -166,6 +189,14 @@ or
 returned
 .Er EFAULT
 .El
+.Pp
+In addition,
+.Fn uiomove_nofault
+will fail and return the following error code if:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+A page fault occurs.
+.El
 .Sh SEE ALSO
 .Xr read 2 ,
 .Xr readv 2 ,