Re: Review request: draft ioctl_userfaultfd(2) manual page

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hello Michael,

On Mon, Mar 20, 2017 at 09:11:07PM +0100, Michael Kerrisk (man-pages) wrote:
> Hello Andrea, Mike, and all,
> 
> Mike: here's the split out page that describes the 
> userfaultfd ioctl() operations.
> 
> I'd like to get review input, especially from you and
> Andrea, but also anyone else, for the current version
> of this page, which includes quite a few FIXMEs to be
> sorted.
> 
> I've shown the rendered version of the page below. 
> The groff source is attached, and can also be found
> at the branch here:
> 
> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_userfaultfd
> 
> The new ioctl_userfaultfd(2) page follows this mail.
> 
> Cheers,
> 
> Michael
> 
> NAME
>        userfaultfd - create a file descriptor for handling page faults in user
>        space
> 
> SYNOPSIS
>        #include <sys/ioctl.h>
> 
>        int ioctl(int fd, int cmd, ...);
> 
> DESCRIPTION
>        Various ioctl(2) operations can be performed on  a  userfaultfd  object
>        (created by a call to userfaultfd(2)) using calls of the form:
> 
>            ioctl(fd, cmd, argp);
> 
>        In  the  above,  fd  is  a  file  descriptor referring to a userfaultfd
>        object, cmd is one of the commands listed below, and argp is a  pointer
>        to a data structure that is specific to cmd.
> 
>        The  various  ioctl(2) operations are described below.  The UFFDIO_API,
>        UFFDIO_REGISTER, and UFFDIO_UNREGISTER operations are used to configure
>        userfaultfd behavior.  These operations allow the caller to choose what
>        features will be enabled and what kinds of events will be delivered  to
>        the application.  The remaining operations are range operations.  These
>        operations enable the calling application to resolve page-fault  events
>        in a consistent way.
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │Above: What does "consistent" mean?                  │
>        │                                                     │
>        └─────────────────────────────────────────────────────┘

Andrea, can you please help with this one?
 
>    UFFDIO_API
>        (Since Linux 4.3.)  Enable operation of the userfaultfd and perform API
>        handshake.  The argp argument is a pointer to a  uffdio_api  structure,
>        defined as:
> 
>            struct uffdio_api {
>                __u64 api;        /* Requested API version (input) */
>                __u64 features;   /* Must be zero */
>                __u64 ioctls;     /* Available ioctl() operations (output) */
>            };
> 
>        The  api  field  denotes  the API version requested by the application.
>        Before the call, the features field must be initialized to zero.
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │Above: Why must the 'features' field be  initialized │
>        │to zero?                                             │
>        └─────────────────────────────────────────────────────┘

Until 4.11 the only supported feature is delegation of missing page fault
and the UFFDIO_FEATURES bitmask is 0.
There's a check in uffdio_api call that the user is not trying to enable
any other functionality and it asserts that uffdio_api.featurs is zero [1].
Starting from 4.11 the features negotiation is different. Now uffdio_call
verifies that it can support features the application requested [2].


>        The  kernel verifies that it can support the requested API version, and
>        sets the features and ioctls fields to bit masks representing  all  the
>        available features and the generic ioctl(2) operations available.  Cur‐
>        rently, zero (i.e., no feature bits) is placed in the  features  field.
>        The returned ioctls field can contain the following bits:
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │This  user-space  API  seems not fully polished. Why │
>        │are there not constants defined for each of the bit- │
>        │mask values listed below?                            │
>        └─────────────────────────────────────────────────────┘
> 
>        1 << _UFFDIO_API
>               The UFFDIO_API operation is supported.
> 
>        1 << _UFFDIO_REGISTER
>               The UFFDIO_REGISTER operation is supported.
> 
>        1 << _UFFDIO_UNREGISTER
>               The UFFDIO_UNREGISTER operation is supported.

Well, I tend to agree. I believe the original intention was to use the
OR'ed mask, like UFFD_API_IOCTLS.
Andrea, can you add somthing?

> 
> 
>               ┌─────────────────────────────────────────────────────┐
>               │FIXME                                                │
>               ├─────────────────────────────────────────────────────┤
>               │Is  the above description of the 'ioctls' field cor‐ │
>               │rect?  Does more need to be said?                    │
>               │                                                     │
>               └─────────────────────────────────────────────────────┘

This is correct. I wouldn't add anything else.
 
>        This ioctl(2) operation returns 0 on success.  On error, -1 is returned
>        and  errno  is set to indicate the cause of the error.  Possible errors
>        include:
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
G>        ├─────────────────────────────────────────────────────┤
>        │Is the following error list correct?                 │
>        │                                                     │
>        └─────────────────────────────────────────────────────┘

There's also -EFAULT in case copy_{from,to}_user fails.

> 
>        EINVAL The userfaultfd has already been  enabled  by  a  previous  UFF‐
>               DIO_API operation.
> 
>        EINVAL The  API  version requested in the api field is not supported by
>               this kernel, or the features field was not zero.
>
>               ┌─────────────────────────────────────────────────────┐
>               │FIXME                                                │
>               ├─────────────────────────────────────────────────────┤
>               │In the above error case, the  returned  'uffdio_api' │
>               │structure  zeroed out. Why is this done? This should │
>               │be explained in the manual page.                     │
>               │                                                     │
>               └─────────────────────────────────────────────────────┘
 
In my understanding the uffdio_api structure is zeroed to allow the caller
to distinguish the reasons for -EINVAL.

>    UFFDIO_REGISTER
>        (Since Linux 4.3.)  Register a memory  address  range  with  the  user‐
>        faultfd  object.   The  argp argument is a pointer to a uffdio_register
>        structure, defined as:
> 
>            struct uffdio_range {
>                __u64 start;    /* Start of range */
>                __u64 len;      /* Length of rnage (bytes) */
>            };
> 
>            struct uffdio_register {
>                struct uffdio_range range;
>                __u64 mode;     /* Desired mode of operation (input) */
>                __u64 ioctls;   /* Available ioctl() operations (output) */
>            };
> 
> 
>        The range field defines a memory range starting at start and continuing
>        for len bytes that should be handled by the userfaultfd.
> 
>        The  mode  field  defines the mode of operation desired for this memory
>        region.  The following values may be bitwise  ORed  to  set  the  user‐
>        faultfd mode for the specified range:
> 
>        UFFDIO_REGISTER_MODE_MISSING
>               Track page faults on missing pages.
> 
>        UFFDIO_REGISTER_MODE_WP
>               Track page faults on write-protected pages.
> 
>        Currently, the only supported mode is UFFDIO_REGISTER_MODE_MISSING.
> 
>        If the operation is successful, the kernel modifies the ioctls bit-mask
>        field to indicate which ioctl(2) operations are available for the spec‐
>        ified range.  This returned bit mask is as for UFFDIO_API.
> 
>        This ioctl(2) operation returns 0 on success.  On error, -1 is returned
>        and errno is set to indicate the cause of the error.   Possible  errors
>        include:
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │Is the following error list correct?                 │
>        │                                                     │
>        └─────────────────────────────────────────────────────┘

Here again it maybe -EFAULT to indicate copy_{from,to}_user failure.
And, UFFDIO_REGISTER may return -ENOMEM if the process is exiting and the
mm_struct has gone by the time userfault grabs it. 
 
>        EBUSY  A  mapping  in  the  specified  range is registered with another
>               userfaultfd object.
> 
>        EINVAL An invalid or unsupported bit was specified in the  mode  field;
>               or the mode field was zero.
> 
>        EINVAL There is no mapping in the specified address range.
> 
>        EINVAL range.start  or  range.len  is not a multiple of the system page
>               size; or, range.len is  zero;  or  these  fields  are  otherwise
>               invalid.
> 
>        EINVAL There as an incompatible mapping in the specified address range.
> 
> 
>               ┌─────────────────────────────────────────────────────┐
>               │FIXME                                                │
>               ├─────────────────────────────────────────────────────┤
>               │Above: What does "incompatible" mean?                │
>               │                                                     │
>               └─────────────────────────────────────────────────────┘

Up to 4.10 userfault context may be registered only for MAP_ANONYMOUS |
MAP_PRIVATE mappings.

>    UFFDIO_UNREGISTER
>        (Since Linux 4.3.)  Unregister a memory address range from userfaultfd.
>        The address range to unregister is specified in the uffdio_range struc‐
>        ture pointed to by argp.
> 
>        This ioctl(2) operation returns 0 on success.  On error, -1 is returned
>        and errno is set to indicate the cause of the error.   Possible  errors
>        include:
> 
>        EINVAL Either  the  start or the len field of the ufdio_range structure
>               was not a multiple of the system page size; or the len field was
>               zero; or these fields were otherwise invalid.
> 
>        EINVAL There as an incompatible mapping in the specified address range.
> 
> 
>               ┌─────────────────────────────────────────────────────┐
>               │FIXME                                                │
>               ├─────────────────────────────────────────────────────┤
>               │Above: What does "incompatible" mean?                │
>               └─────────────────────────────────────────────────────┘

The same comments as for UFFDIO_REGISTER apply here as well.

>        EINVAL There was no mapping in the specified address range.
> 
>    UFFDIO_COPY
>        (Since  Linux 4.3.)  Atomically copy a continuous memory chunk into the
>        userfault registered range and optionally wake up the  blocked  thread.
>        The  source  and  destination addresses and the number of bytes to copy
>        are specified by the src, dst, and len fields of the uffdio_copy struc‐
>        ture pointed to by argp:
> 
>            struct uffdio_copy {
>                __u64 dst;    /* Source of copy */
>                __u64 src;    /* Destinate of copy */
>                __u64 len;    /* Number of bytes to copy */
>                __u64 mode;   /* Flags controlling behavior of copy */
>                __s64 copy;   /* Number of bytes copied, or negated error */
>            };
> 
>        The  following value may be bitwise ORed in mode to change the behavior
>        of the UFFDIO_COPY operation:
> 
>        UFFDIO_COPY_MODE_DONTWAKE
>               Do not wake up the thread that waits for page-fault resolution
> 
>        The copy field is used by the kernel to return the number of bytes that
>        was actually copied, or an error (a negated errno-style value).
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │Above:  Why is the 'copy' field used to return error │
>        │values?  This should  be  explained  in  the  manual │
>        │page.                                                │
>        └─────────────────────────────────────────────────────┘

Andrea, can you help with this one, please?

>        If  the  value returned in copy doesn't match the value that was speci‐
>        fied in len, the operation fails with the error EAGAIN.  The copy field
>        is output-only; it is not read by the UFFDIO_COPY operation.
> 
>        This ioctl(2) operation returns 0 on success.  In this case, the entire
>        area was copied.  On error, -1 is returned and errno is set to indicate
>        the cause of the error.  Possible errors include:
> 
>        EAGAIN The number of bytes copied (i.e., the value returned in the copy
>               field) does not equal the value that was specified  in  the  len
>               field.
> 
>        EINVAL Either dst or len was not a multiple of the system page size, or
>               the range specified by src and len or dst and len was invalid.
> 
>        EINVAL An invalid bit was specified in the mode field.
> 
>    UFFDIO_ZEROPAGE
>        (Since Linux 4.3.)  Zero out  a  memory  range  registered  with  user‐
>        faultfd.   The  requested  range is specified by the range field of the
>        uffdio_zeropage structure pointed to by argp:
> 
>            struct uffdio_zeropage {
>                struct uffdio_range range;
>                __u64 mode;     /* Flags controlling behavior of copy */
>                __s64 zeropage; /* Number of bytes zeroed, or negated error */
>            };
> 
>        The following value may be bitwise ORed in mode to change the  behavior
>        of the UFFDIO_ZERO operation:
> 
>        UFFDIO_ZEROPAGE_MODE_DONTWAKE
>               Do not wake up the thread that waits for page-fault resolution.
> 
>        The  zeropage field is used by the kernel to return the number of bytes
>        that was actually zeroed, or an  error  in  the  same  manner  as  UFF‐
>        DIO_COPY.
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │Why  is  the  'zeropage'  field used to return error │
>        │values?  This should  be  explained  in  the  manual │
>        │page.                                                │
>        └─────────────────────────────────────────────────────┘
>        If  the  value  returned  in the zeropage field doesn't match the value
>        that was specified in range.len, the operation  fails  with  the  error
>        EAGAIN.   The zeropage field is output-only; it is not read by the UFF‐
>        DIO_ZERO operation.
> 
>        This ioctl(2) operation returns 0 on success.  In this case, the entire
>        area was zeroed.  On error, -1 is returned and errno is set to indicate
>        the cause of the error.  Possible errors include:
> 
>        EAGAIN The number of bytes zeroed (i.e.,  the  value  returned  in  the
>               zeropage  field)  does not equal the value that was specified in
>               the range.len field.
> 
>        EINVAL Either range.start or range.len was not a multiple of the system
>               page  size;  or  range.len  was zero; or the range specified was
>               invalid.
> 
>        EINVAL An invalid bit was specified in the mode field.
> 
>    UFFDIO_WAKE
>        (Since Linux 4.3.)  Wake up the thread waiting for  page-fault  resolu‐
>        tion  on  a  specified  memory  address  range.  The argp argument is a
>        pointer to a uffdio_range structure (shown above)  that  specifies  the
>        address range.
> 
> 
>        ┌─────────────────────────────────────────────────────┐
>        │FIXME                                                │
>        ├─────────────────────────────────────────────────────┤
>        │Need more detail here. How is the UFFDIO_WAKE opera‐ │
>        │tion used?                                           │
>        └─────────────────────────────────────────────────────┘

The UFFDIO_WAKE operation is used in conjunction with
UFFDIO_{COPY,ZEROPAGE} operations that have
UFFDIO_{COPY,ZEROPAGE}_MODE_DONTWAKE bit set in the mode field.
The userfault monitor can perform several UFFDIO_{COPY,ZEROPAGE} calls in a
batch and then explicitly wake up the faulting thread using UFFDIO_WAKE.

>        This ioctl(2) operation returns 0 on success.  On error, -1 is returned
>        and  errno  is set to indicate the cause of the error.  Possible errors
>        include:
> 
>        EINVAL The start or the len field of the ufdio_range structure was  not
>               a  multiple  of  the  system  page size; or len was zero; or the
>               specified range was otherwise invalid.
> 
> RETURN VALUE
>        See descriptions of the individual operations, above.
> 
> ERRORS
>        See descriptions of the individual operations, above.  In addition, the
>        following  general errors can occur for all of the operations described
>        above:
> 
>        EFAULT argp does not point to a valid memory address.
> 
>        EINVAL (For all operations except UFFDIO_API.)  The userfaultfd  object
>               has not yet been enabled (via the UFFDIO_API operation).
> 
> CONFORMING TO
>        These ioctl(2) operations are Linux-specific.
> 
> EXAMPLE
>        See userfaultfd(2).
> 
> SEE ALSO
>        ioctl(2), mmap(2), userfaultfd(2)
> 
>        Documentation/vm/userfaultfd.txt in the Linux kernel source tree
> 

[1] http://lxr.free-electrons.com/source/fs/userfaultfd.c#L1199
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/userfaultfd.c#n1680

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@xxxxxxxxx.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@xxxxxxxxx";> email@xxxxxxxxx </a>



[Index of Archives]     [Linux ARM Kernel]     [Linux ARM]     [Linux Omap]     [Fedora ARM]     [IETF Annouce]     [Bugtraq]     [Linux OMAP]     [Linux MIPS]     [eCos]     [Asterisk Internet PBX]     [Linux API]
  Powered by Linux