Document copyin_nofault, copyout_nofault, uiomove_nofault.
Submitted by: alc
This commit is contained in:
parent
2801687d56
commit
6847f7cfb3
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=223890
@ -551,8 +551,10 @@ MLINKS+=config_intrhook.9 config_intrhook_disestablish.9 \
|
|||||||
config_intrhook.9 config_intrhook_establish.9
|
config_intrhook.9 config_intrhook_establish.9
|
||||||
MLINKS+=contigmalloc.9 contigfree.9
|
MLINKS+=contigmalloc.9 contigfree.9
|
||||||
MLINKS+=copy.9 copyin.9 \
|
MLINKS+=copy.9 copyin.9 \
|
||||||
|
copy.9 copyin_nofault.9 \
|
||||||
copy.9 copyinstr.9 \
|
copy.9 copyinstr.9 \
|
||||||
copy.9 copyout.9 \
|
copy.9 copyout.9 \
|
||||||
|
copy.9 copyout_nofault.9 \
|
||||||
copy.9 copystr.9
|
copy.9 copystr.9
|
||||||
MLINKS+=critical_enter.9 critical.9 \
|
MLINKS+=critical_enter.9 critical.9 \
|
||||||
critical_enter.9 critical_exit.9
|
critical_enter.9 critical_exit.9
|
||||||
@ -1284,7 +1286,8 @@ MLINKS+=uidinfo.9 uifind.9 \
|
|||||||
uidinfo.9 uifree.9 \
|
uidinfo.9 uifree.9 \
|
||||||
uidinfo.9 uihashinit.9 \
|
uidinfo.9 uihashinit.9 \
|
||||||
uidinfo.9 uihold.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 \
|
MLINKS+=usbdi.9 usbd_do_request.9 \
|
||||||
usbdi.9 usbd_do_request_flags.9 \
|
usbdi.9 usbd_do_request_flags.9 \
|
||||||
usbdi.9 usbd_errstr.9 \
|
usbdi.9 usbd_errstr.9 \
|
||||||
|
@ -34,13 +34,15 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd January 7, 1996
|
.Dd July 9, 2011
|
||||||
.Dt COPY 9
|
.Dt COPY 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm copy ,
|
.Nm copy ,
|
||||||
.Nm copyin ,
|
.Nm copyin ,
|
||||||
|
.Nm copyin_nofault ,
|
||||||
.Nm copyout ,
|
.Nm copyout ,
|
||||||
|
.Nm copyout_nofault ,
|
||||||
.Nm copystr ,
|
.Nm copystr ,
|
||||||
.Nm copyinstr
|
.Nm copyinstr
|
||||||
.Nd kernel copy functions
|
.Nd kernel copy functions
|
||||||
@ -50,8 +52,12 @@
|
|||||||
.Ft int
|
.Ft int
|
||||||
.Fn copyin "const void *uaddr" "void *kaddr" "size_t len"
|
.Fn copyin "const void *uaddr" "void *kaddr" "size_t len"
|
||||||
.Ft int
|
.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"
|
.Fn copyout "const void *kaddr" "void *uaddr" "size_t len"
|
||||||
.Ft int
|
.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"
|
.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done"
|
||||||
.Ft int
|
.Ft int
|
||||||
.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done"
|
.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.
|
copy data from user-space to kernel-space or vice-versa.
|
||||||
.Pp
|
.Pp
|
||||||
The
|
The
|
||||||
.Nm
|
.Fn copyin
|
||||||
routines provide the following functionality:
|
and
|
||||||
.Bl -tag -width "copyoutstr()"
|
.Fn copyin_nofault
|
||||||
.It Fn copyin
|
functions copy
|
||||||
Copies
|
|
||||||
.Fa len
|
.Fa len
|
||||||
bytes of data from the user-space address
|
bytes of data from the user-space address
|
||||||
.Fa uaddr
|
.Fa uaddr
|
||||||
to the kernel-space address
|
to the kernel-space address
|
||||||
.Fa kaddr .
|
.Fa kaddr .
|
||||||
.It Fn copyout
|
.Pp
|
||||||
Copies
|
The
|
||||||
|
.Fn copyout
|
||||||
|
and
|
||||||
|
.Fn copyout_nofault
|
||||||
|
functions copy
|
||||||
.Fa len
|
.Fa len
|
||||||
bytes of data from the kernel-space address
|
bytes of data from the kernel-space address
|
||||||
.Fa kaddr
|
.Fa kaddr
|
||||||
to the user-space address
|
to the user-space address
|
||||||
.Fa uaddr .
|
.Fa uaddr .
|
||||||
.It Fn copystr
|
.Pp
|
||||||
Copies a NUL-terminated string, at most
|
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
|
.Fa len
|
||||||
bytes long, from kernel-space address
|
bytes long, from kernel-space address
|
||||||
.Fa kfaddr
|
.Fa kfaddr
|
||||||
@ -98,8 +119,10 @@ NUL, is returned in
|
|||||||
.Fa done
|
.Fa done
|
||||||
is
|
is
|
||||||
.No non- Ns Dv NULL ) .
|
.No non- Ns Dv NULL ) .
|
||||||
.It Fn copyinstr
|
.Pp
|
||||||
Copies a NUL-terminated string, at most
|
The
|
||||||
|
.Fn copyinstr
|
||||||
|
function copies a NUL-terminated string, at most
|
||||||
.Fa len
|
.Fa len
|
||||||
bytes long, from user-space address
|
bytes long, from user-space address
|
||||||
.Fa uaddr
|
.Fa uaddr
|
||||||
@ -121,7 +144,6 @@ is
|
|||||||
.\" The number of bytes actually copied, including the terminating
|
.\" The number of bytes actually copied, including the terminating
|
||||||
.\" NUL, is returned in
|
.\" NUL, is returned in
|
||||||
.\" .Fa *done .
|
.\" .Fa *done .
|
||||||
.El
|
|
||||||
.Sh RETURN VALUES
|
.Sh RETURN VALUES
|
||||||
The
|
The
|
||||||
.Nm
|
.Nm
|
||||||
@ -129,7 +151,13 @@ functions return 0 on success or
|
|||||||
.Er EFAULT
|
.Er EFAULT
|
||||||
if a bad address is encountered.
|
if a bad address is encountered.
|
||||||
In addition, the
|
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
|
and
|
||||||
.Fn copyinstr
|
.Fn copyinstr
|
||||||
.\" .Fn copyinstr ,
|
.\" .Fn copyinstr ,
|
||||||
|
@ -25,12 +25,13 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd March 21, 2010
|
.Dd July 9, 2011
|
||||||
.Dt UIO 9
|
.Dt UIO 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm uio ,
|
.Nm uio ,
|
||||||
.Nm uiomove
|
.Nm uiomove ,
|
||||||
|
.Nm uiomove_nofault
|
||||||
.Nd device driver I/O routines
|
.Nd device driver I/O routines
|
||||||
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
||||||
.In sys/types.h
|
.In sys/types.h
|
||||||
@ -48,11 +49,15 @@ struct uio {
|
|||||||
.Ed
|
.Ed
|
||||||
.Ft int
|
.Ft int
|
||||||
.Fn uiomove "void *buf" "int howmuch" "struct uio *uiop"
|
.Fn uiomove "void *buf" "int howmuch" "struct uio *uiop"
|
||||||
|
.Ft int
|
||||||
|
.Fn uiomove_nofault "void *buf" "int howmuch" "struct uio *uiop"
|
||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
The function
|
The functions
|
||||||
.Fn uiomove
|
.Fn uiomove
|
||||||
is used to handle transfer of data between buffers and I/O vectors
|
and
|
||||||
that might possibly also cross the user/kernel space boundary.
|
.Fn uiomove_nofault
|
||||||
|
are used to transfer data between buffers and I/O vectors that might
|
||||||
|
possibly cross the user/kernel space boundary.
|
||||||
.Pp
|
.Pp
|
||||||
As a result of any
|
As a result of any
|
||||||
.Xr read 2 ,
|
.Xr read 2 ,
|
||||||
@ -71,6 +76,8 @@ being passed.
|
|||||||
The transfer request is encoded in this structure.
|
The transfer request is encoded in this structure.
|
||||||
The driver itself should use
|
The driver itself should use
|
||||||
.Fn uiomove
|
.Fn uiomove
|
||||||
|
or
|
||||||
|
.Fn uiomove_nofault
|
||||||
to get at the data in this structure.
|
to get at the data in this structure.
|
||||||
.Pp
|
.Pp
|
||||||
The fields in the
|
The fields in the
|
||||||
@ -99,7 +106,7 @@ Do not copy, already in object.
|
|||||||
.El
|
.El
|
||||||
.It Va uio_rw
|
.It Va uio_rw
|
||||||
The direction of the desired transfer, either
|
The direction of the desired transfer, either
|
||||||
.Dv UIO_READ ,
|
.Dv UIO_READ
|
||||||
or
|
or
|
||||||
.Dv UIO_WRITE .
|
.Dv UIO_WRITE .
|
||||||
.It Va uio_td
|
.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
|
indicates that the transfer is to be made from/to a process's address
|
||||||
space.
|
space.
|
||||||
.El
|
.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
|
.Sh RETURN VALUES
|
||||||
On success
|
On success
|
||||||
.Fn uiomove
|
.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
|
.Sh EXAMPLES
|
||||||
The idea is that the driver maintains a private buffer for its data,
|
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
|
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
|
.Ed
|
||||||
.Sh ERRORS
|
.Sh ERRORS
|
||||||
.Fn uiomove
|
.Fn uiomove
|
||||||
|
and
|
||||||
|
.Fn uiomove_nofault
|
||||||
will fail and return the following error code if:
|
will fail and return the following error code if:
|
||||||
.Bl -tag -width Er
|
.Bl -tag -width Er
|
||||||
.It Bq Er EFAULT
|
.It Bq Er EFAULT
|
||||||
@ -166,6 +189,14 @@ or
|
|||||||
returned
|
returned
|
||||||
.Er EFAULT
|
.Er EFAULT
|
||||||
.El
|
.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
|
.Sh SEE ALSO
|
||||||
.Xr read 2 ,
|
.Xr read 2 ,
|
||||||
.Xr readv 2 ,
|
.Xr readv 2 ,
|
||||||
|
Loading…
Reference in New Issue
Block a user