Date: Sat, 9 Jul 2011 15:24:12 +0000 (UTC) From: Konstantin Belousov <kib@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r223890 - head/share/man/man9 Message-ID: <201107091524.p69FOCq6005825@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: kib Date: Sat Jul 9 15:24:12 2011 New Revision: 223890 URL: http://svn.freebsd.org/changeset/base/223890 Log: Document copyin_nofault, copyout_nofault, uiomove_nofault. Submitted by: alc Modified: head/share/man/man9/Makefile head/share/man/man9/copy.9 head/share/man/man9/uio.9 Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Sat Jul 9 15:21:10 2011 (r223889) +++ head/share/man/man9/Makefile Sat Jul 9 15:24:12 2011 (r223890) @@ -551,8 +551,10 @@ MLINKS+=config_intrhook.9 config_intrhoo 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 \ Modified: head/share/man/man9/copy.9 ============================================================================== --- head/share/man/man9/copy.9 Sat Jul 9 15:21:10 2011 (r223889) +++ head/share/man/man9/copy.9 Sat Jul 9 15:24:12 2011 (r223890) @@ -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 , Modified: head/share/man/man9/uio.9 ============================================================================== --- head/share/man/man9/uio.9 Sat Jul 9 15:21:10 2011 (r223889) +++ head/share/man/man9/uio.9 Sat Jul 9 15:24:12 2011 (r223890) @@ -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 .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 ,
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201107091524.p69FOCq6005825>