On Mon, Feb 1, 2021 at 12:07 PM Peter Xu [off-list ref] wrote:

On Thu, Jan 28, 2021 at 02:48:18PM -0800, Axel Rasmussen wrote:

quoted

Reword / reorganize things a little bit into "lists", so new features /
modes / ioctls can sort of just be appended.

Describe how UFFDIO_REGISTER_MODE_MINOR and UFFDIO_CONTINUE can be used
to intercept and resolve minor faults. Make it clear that COPY and
ZEROPAGE are used for MISSING faults, whereas CONTINUE is used for MINOR
faults.

Bare with me since I'm not native speaker.. but I'm pointing out things that
reads odd to me.  Feel free to argue. :)

No worries, that is true for many people in the community. I'm happy
to reword to make things as clear as possible. :)

[...]

quoted

+Resolving Userfaults
+--------------------
+
+There are three basic ways to resolve userfaults:
+
+- ``UFFDIO_COPY`` atomically copies some existing page contents from
+  userspace.
+
+- ``UFFDIO_ZEROPAGE`` atomically zeros the new page.
+
+- ``UFFDIO_CONTINUE`` maps an existing, previously-populated page.
+
+These operations are atomic in the sense that they guarantee nothing can
+see a half-populated page, since readers will keep userfaulting until the
+operation has finished.
+
+By default, these wake up userfaults blocked on the range in question.
+They support a ``UFFDIO_*_MODE_DONTWAKE`` ``mode`` flag, which indicates
+that waking will be done separately at some later time.
+
+Which of these are used depends on the kind of fault:

Maybe:

"We should choose the ioctl depending on the kind of the page fault, and what
 we'd like to do with it:"

?

quoted

+
+- For ``UFFDIO_REGISTER_MODE_MISSING`` faults, a new page has to be
+  provided. This can be done with either ``UFFDIO_COPY`` or

UFFDIO_ZEROPAGE does not need a new page.

quoted

+  ``UFFDIO_ZEROPAGE``. The default (non-userfaultfd) behavior would be to
+  provide a zero page, but in userfaultfd this is left up to userspace.

"By default, kernel will provide a zero page for a missing fault.  With
 userfaultfd, the userspace could decide which content to provide before the
 faulted thread continues." ?

quoted

+
+- For ``UFFDIO_REGISTER_MODE_MINOR`` faults, an existing page already

"page cache existed"?

quoted

+  exists. Userspace needs to ensure its contents are correct (if it needs
+  to be modified, by writing directly to the non-userfaultfd-registered
+  side of shared memory), and then issue ``UFFDIO_CONTINUE`` to resolve
+  the fault.

"... Userspace can modify the page content before asking the faulted thread to
 continue the fault with UFFDIO_CONTINUE ioctl." ?

I agree with all the comments; these areas can be clarified. I didn't
take the suggestions exactly as-is, but I did reword these parts in my
v4. Let me know if further changes would be useful.

--
Peter Xu