lkml.org 
[lkml]   [2017]   [Apr]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Review request: draft userfaultfd(2) manual page
On Fri, Apr 21, 2017 at 08:30:55AM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Mike,
>
> On 03/21/2017 03:01 PM, Mike Rapoport wrote:
> > Hello Michael,
> >
> > On Mon, Mar 20, 2017 at 09:08:05PM +0100, Michael Kerrisk (man-pages) wrote:
> >> Hello Andrea, Mike, and all,
> >>
> >> Mike: thanks for the page that you sent. I've reworked it
> >> a bit, and also added a lot of further information,
> >> and an example program. In the process, I split the page
> >> into two pieces, with one piece describing the userfaultfd()
> >> system call and the other describing the 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 a few FIXMEs to be sorted.
> >
> > Thanks for the update. I'm adressing the FIXME points you've mentioned
> > below.
>
> Thanks!
>
> > Otherwise, everything seems the right description of the current upstream.
> > 4.11 will have quite a few updates to userfault and we'll need to udpate
> > this page and ioctl_userfaultfd(2) to address those updates. I am planning
> > to work on the man update in the next few weeks.
> >
> >> 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
> >
> > --
> > Sincerely yours,
> > Mike.
> >
> >
> >> USERFAULTFD(2) Linux Programmer's Manual USERFAULTFD(2)
> >>
> >> ┌─────────────────────────────────────────────────────┐
> >> │FIXME │
> >> ├─────────────────────────────────────────────────────┤
> >> │Need to describe close(2) semantics for userfaulfd │
> >> │file descriptor: what happens when the userfaultfd │
> >> │FD is closed? │
> >> │ │
> >> └─────────────────────────────────────────────────────┘
> >
> > When userfaultfd is closed, it unregisters all memory ranges that were
> > previously registered with it and flushes the outstanding page fault
> > events.
>
> Presumably, this is more precisely stated as, "when the last
> file descriptor referring to a userfaultfd object is closed..."?

You are right.

> I've made the text:
>
> When the last file descriptor referring to a userfaultfd object
> is closed, all memory ranges that were registered with the
> object are unregistered and unread page-fault events are
> flushed.
>
> [...]

Perfect.

> >> Reading from the userfaultfd structure
> >> ┌─────────────────────────────────────────────────────┐
> >> │FIXME │
> >> ├─────────────────────────────────────────────────────┤
> >> │are the details below correct? │
> >> └─────────────────────────────────────────────────────┘
> >
> > Yes, at least for the current upstream version. 4.11 will have quite a few
> > updates to userfaultfd.
>
> Okay.
>
> >> Each read(2) from the userfaultfd file descriptor returns one
> >> or more uffd_msg structures, each of which describes a page-
> >> fault event:
> >>
> >> struct uffd_msg {
> >> __u8 event; /* Type of event */
> >> ...
> >> union {
> >> struct {
> >> __u64 flags; /* Flags describing fault */
> >> __u64 address; /* Faulting address */
> >> } pagefault;
> >> ...
> >> } arg;
> >>
> >> /* Padding fields omitted */
> >> } __packed;
> >>
> >> If multiple events are available and the supplied buffer is
> >> large enough, read(2) returns as many events as will fit in the
> >> supplied buffer. If the buffer supplied to read(2) is smaller
> >> than the size of the uffd_msg structure, the read(2) fails with
> >> the error EINVAL.
> >>
> >> The fields set in the uffd_msg structure are as follows:
> >>
> >> event The type of event. Currently, only one value can appear
> >> in this field: UFFD_EVENT_PAGEFAULT, which indicates a
> >> page-fault event.
> >>
> >> address
> >> The address that triggered the page fault.
> >>
> >> flags A bit mask of flags that describe the event. For
> >> UFFD_EVENT_PAGEFAULT, the following flag may appear:
> >>
> >> UFFD_PAGEFAULT_FLAG_WRITE
> >> If the address is in a range that was registered
> >> with the UFFDIO_REGISTER_MODE_MISSING flag (see
> >> ioctl_userfaultfd(2)) and this flag is set, this
> >> a write fault; otherwise it is a read fault.
> >>
> >> A read(2) on a userfaultfd file descriptor can fail with the
> >> following errors:
> >>
> >> EINVAL The userfaultfd object has not yet been enabled using
> >> the UFFDIO_API ioctl(2) operation
> >>
> >> The userfaultfd file descriptor can be monitored with poll(2),
> >> select(2), and epoll(7). When events are available, the file
> >> descriptor indicates as readable.
> >>
> >>
> >> ┌─────────────────────────────────────────────────────┐
> >> │FIXME │
> >> ├─────────────────────────────────────────────────────┤
> >> │But, it seems, the object must be created with │
> >> │O_NONBLOCK. What is the rationale for this require‐ │
> >> │ment? Something needs to be said in this manual │
> >> │page. │
> >> └─────────────────────────────────────────────────────┘
> >
> > The object can be created without O_NONBLOCK, so probably the above
> > sentence can be rephrased as:
> >
> > When the userfaultfd file descriptor is opened in non-blocking mode, it can
> > be monitored with ...
>
> Yes, but why is there this requirement for poll() etc. with the
> O_NONBLOCK flag? I think something about that needs to be said in the
> man page. Sorry, my FIXME was not clear enough. I've reworded the text
> and the FIXME:
>
> If the O_NONBLOCK flag is enabled in the associated open file
> description, the userfaultfd file descriptor can be monitored
> with poll(2), select(2), and epoll(7). When events are avail‐
> able, the file descriptor indicates as readable. If the O_NON‐
> BLOCK flag is not enabled, then poll(2) (always) indicates the
> file as having a POLLERR condition, and select(2) indicates the
> file descriptor as both readable and writable.
>
> ┌─────────────────────────────────────────────────────┐
> │FIXME │
> ├─────────────────────────────────────────────────────┤
> │What is the reason for this seemingly odd behavior │
> │with respect to the O_NONBLOCK flag? (see user‐ │
> │faultfd_poll() in fs/userfaultfd.c). Something │
> │needs to be said about this. │
> └─────────────────────────────────────────────────────┘

Andrea, can you please help with this one as well?

> [...]
>
> Thanks,
>
> Michael
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

--
Sincerely yours,
Mike.

\
 
 \ /
  Last update: 2017-04-21 13:07    [W:0.165 / U:0.636 seconds]
©2003-2017 Jasper Spaans. hosted at Digital OceanAdvertise on this site