On Thu, Mar 04, 2021 at 08:46:59AM +0200, Mike Rapoport wrote:

On Wed, Mar 03, 2021 at 08:59:45PM -0500, Peter Xu wrote:

quoted

Write-protect mode is supported starting from Linux 5.7.

Signed-off-by: Peter Xu <peterx@redhat.com>
---
 man2/userfaultfd.2 | 88 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 86 insertions(+), 2 deletions(-)

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 2d14effc6..8e1602d62 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2

@@ -78,6 +78,28 @@ all memory ranges that were registered with the object are unregistered
 and unread events are flushed.
 .\"
 .PP
+Currently, userfaultfd supports two modes of registration:
+.TP
+.BR UFFDIO_REGISTER_MODE_MISSING
+When registered with
+.BR UFFDIO_REGISTER_MODE_MISSING
+mode, the userspace will receive a page fault message when a missing page is
+accessed.  The faulted thread will be stopped from execution until the page
+fault is resolved from the userspace by either an
+.BR UFFDIO_COPY
+or an
+.BR UFFDIO_ZEROPAGE
+ioctl.
+.TP
+.BR UFFDIO_REGISTER_MODE_WP
+When registered with
+.BR UFFDIO_REGISTER_MODE_WP
+mode, the userspace will receive a page fault message when a write-protected
+page is written.  The faulted thread will be stopped from execution until the
+userspace un-write-protect the page using an
+.BR UFFDIO_WRITEPROTECT
+ioctl.
+.PP

I'd add a sentence about combining the modes together. Something like

"Both modes can be enabled together for the same memory range"

I mentioned it below [1].  However I agree it's indeed making more sense to
mention it when listing the modes, especially knowing that the 3rd minor mode
is coming.  I think I'll keep both, assuming a bit more verbose is still
acceptable in man pages, but changed to:

"Multiple modes can be enabled at the same time for the same memory range."

quoted

 Since Linux 4.14, userfaultfd page fault message can selectively embed fault
 thread ID information into the fault message.  One needs to enable this feature
 explicitly using the

@@ -143,6 +165,16 @@ single threaded non-cooperative userfaultfd manager implementations.
 .\" and limitations remaining in 4.11
 .\" Maybe it's worth adding a dedicated sub-section...
 .\"
+.PP
+Starting from Linux 5.7, userfaultfd is able to do synchronous page dirty
+tracking using the new write-protection register mode.  One should check
+against the feature bit
+.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
+before using this feature.  Similar to the original userfaultfd missing mode,
+the write-protect mode will generate an userfaultfd message when the protected
+page is written.  The user needs to resolve the page fault by unprotecting the
+faulted page and kick the faulted thread to continue.  For more information,
+please read the "Userfaultfd write-protect mode" section below.
 .SS Userfaultfd operation
 After the userfaultfd object is created with
 .BR userfaultfd (),

@@ -218,6 +250,54 @@ userfaultfd can be used only with anonymous private memory mappings.
 Since Linux 4.11,
 userfaultfd can be also used with hugetlbfs and shared memory mappings.
 .\"
+.SS Userfaultfd write-protect mode
+Since Linux 5.7, userfaultfd started to support write-protect mode.  The user

Maybe s/started to support/supports/

Sure.

quoted

+needs to first check availability of this feature using
+.BR UFFDIO_API
+ioctl against the feature bit
+.BR UFFD_FEATURE_PAGEFAULT_FLAG_WP .
+.PP
+To register with userfaultfd write-protect mode, the user needs to send the
+.BR UFFDIO_REGISTER
+ioctl with mode
+.BR UFFDIO_REGISTER_MODE_WP
+set.  Note that it's legal to monitor the same memory range with multiple
+modes.  For example, the user can do
+.BR UFFDIO_REGISTER
+with the mode set to
+.BR UFFDIO_REGISTER_MODE_MISSING\ |\ UFFDIO_REGISTER_MODE_WP.

[1]

Thanks,

-- 
Peter Xu