[PATCH 0/5] Merged patches from others

[PATCH 0/5] Merged patches from others

[Alejandro Colomar]

Hi Michael,

These are the patches I have merged from others.

Cheers,

Alex


Alyssa Ross (1):
  scanf.3: clarify that %n supports type modifiers

Peter Xu (4):
  userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
  userfaultfd.2: Add write-protect mode
  ioctl_userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
  ioctl_userfaultfd.2: Add write-protect mode docs

 man2/ioctl_userfaultfd.2 |  91 ++++++++++++++++++++++++++++-
 man2/userfaultfd.2       | 121 +++++++++++++++++++++++++++++++++++++--
 man3/scanf.3             |   4 +-
 3 files changed, 208 insertions(+), 8 deletions(-)

-- 
2.31.0

[PATCH 1/5] scanf.3: clarify that %n supports type modifiers

[Alejandro Colomar]

From: Alyssa Ross <hi@alyssa.is>

My initial reading of this was that type modifiers were probably not
supported.  But they are, and this is actually documented further up,
in the type modifiers documentation.  But to make it clearer, let's
copy the language that printf(3) has in its %n section.

Signed-off-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/scanf.3 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man3/scanf.3 b/man3/scanf.3
index e6d00c9f1..bd49a6caf 100644
--- a/man3/scanf.3
+++ b/man3/scanf.3
@@ -526,7 +526,9 @@ the next pointer must be a pointer to a pointer to
 Nothing is expected; instead, the number of characters consumed thus far
 from the input is stored through the next pointer, which must be a pointer
 to
-.IR int .
+.IR int ,
+or variant whose size matches the (optionally)
+supplied integer length modifier.
 This is
 .I not
 a conversion and does
-- 
2.31.0

[PATCH 2/5] userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs

[Alejandro Colomar]

From: Peter Xu <peterx@redhat.com>

UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.

Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
[alx: srcfix]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/userfaultfd.2 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index fa1b6514f..8245253c3 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -77,6 +77,13 @@ 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 events are flushed.
 .\"
+.PP
+Since Linux 4.14, userfaultfd page fault message can selectively embed
+faulting thread ID information into the fault message.
+One needs to enable this feature explicitly using the
+.B UFFD_FEATURE_THREAD_ID
+feature bit when initializing the userfaultfd context.
+By default, thread ID reporting is disabled.
 .SS Usage
 The userfaultfd mechanism is designed to allow a thread in a multithreaded
 program to perform user-space paging for the other threads in the process.
@@ -229,6 +236,9 @@ struct uffd_msg {
         struct {
             __u64 flags;    /* Flags describing fault */
             __u64 address;  /* Faulting address */
+            union {
+                __u32 ptid; /* Thread ID of the fault */
+            } feat;
         } pagefault;
 
         struct {            /* Since Linux 4.11 */
@@ -358,6 +368,9 @@ otherwise it is a read fault.
 .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
 .RE
 .TP
+.I pagefault.feat.pid
+The thread ID that triggered the page fault.
+.TP
 .I fork.ufd
 The file descriptor associated with the userfault object
 created for the child created by
-- 
2.31.0

[PATCH 3/5] userfaultfd.2: Add write-protect mode

[Alejandro Colomar]

From: Peter Xu <peterx@redhat.com>

Write-protect mode is supported starting from Linux 5.7.

Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/userfaultfd.2 | 108 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 104 insertions(+), 4 deletions(-)

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 8245253c3..0e9206424 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -78,6 +78,32 @@ all memory ranges that were registered with the object are unregistered
 and unread events are flushed.
 .\"
 .PP
+Userfaultfd supports two modes of registration:
+.TP
+.BR UFFDIO_REGISTER_MODE_MISSING " (since 4.10)"
+When registered with
+.B 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
+.B UFFDIO_COPY
+or an
+.B UFFDIO_ZEROPAGE
+ioctl.
+.TP
+.BR UFFDIO_REGISTER_MODE_WP " (since 5.7)"
+When registered with
+.B 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 write-unprotect the page using an
+.B UFFDIO_WRITEPROTECT
+ioctl.
+.PP
+Multiple modes can be enabled at the same time for the same memory range.
+.PP
 Since Linux 4.14, userfaultfd page fault message can selectively embed
 faulting thread ID information into the fault message.
 One needs to enable this feature explicitly using the
@@ -107,7 +133,7 @@ the process that monitors userfaultfd and handles page faults
 needs to be aware of the changes in the virtual memory layout
 of the faulting process to avoid memory corruption.
 .PP
-Starting from Linux 4.11,
+Since Linux 4.11,
 userfaultfd can also notify the fault-handling threads about changes
 in the virtual memory layout of the faulting process.
 In addition, if the faulting process invokes
@@ -144,6 +170,17 @@ single threaded non-cooperative userfaultfd manager implementations.
 .\" and limitations remaining in 4.11
 .\" Maybe it's worth adding a dedicated sub-section...
 .\"
+.PP
+Since Linux 5.7, userfaultfd is able to do
+synchronous page dirty tracking using the new write-protect 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 refer to "Userfaultfd write-protect mode" section.
 .SS Userfaultfd operation
 After the userfaultfd object is created with
 .BR userfaultfd (),
@@ -179,7 +216,7 @@ or
 .BR ioctl (2)
 operations to resolve the page fault.
 .PP
-Starting from Linux 4.14, if the application sets the
+Since Linux 4.14, if the application sets the
 .B UFFD_FEATURE_SIGBUS
 feature bit using the
 .B UFFDIO_API
@@ -219,6 +256,65 @@ 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 5.7)
+Since Linux 5.7, userfaultfd supports write-protect mode.
+The user needs to first check availability of this feature using
+.B UFFDIO_API
+ioctl against the feature bit
+.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
+before using this feature.
+.PP
+To register with userfaultfd write-protect mode, the user needs to initiate the
+.B UFFDIO_REGISTER
+ioctl with mode
+.B 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
+.B UFFDIO_REGISTER
+with the mode set to
+.BR "UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP" .
+When there is only
+.B UFFDIO_REGISTER_MODE_WP
+registered, the userspace will
+.I not
+receive any message when a missing page is written.
+Instead, the userspace will only receive a write-protect page fault message
+when an existing but write-protected page got written.
+.PP
+After the
+.B UFFDIO_REGISTER
+ioctl completed with
+.B UFFDIO_REGISTER_MODE_WP
+mode set,
+the user can write-protect any existing memory within the range using the ioctl
+.B UFFDIO_WRITEPROTECT
+where
+.I uffdio_writeprotect.mode
+should be set to
+.BR UFFDIO_WRITEPROTECT_MODE_WP .
+.PP
+When a write-protect event happens,
+the userspace will receive a page fault message whose
+.I uffd_msg.pagefault.flags
+will be with
+.B UFFD_PAGEFAULT_FLAG_WP
+flag set.
+Note: since only writes can trigger such kind of fault,
+write-protect messages will always be with
+.B UFFD_PAGEFAULT_FLAG_WRITE
+bit set too along with bit
+.BR UFFD_PAGEFAULT_FLAG_WP .
+.PP
+To resolve a write-protection page fault, the user should initiate another
+.B UFFDIO_WRITEPROTECT
+ioctl, whose
+.I uffd_msg.pagefault.flags
+should have the flag
+.B UFFDIO_WRITEPROTECT_MODE_WP
+cleared upon the faulted page or range.
+.PP
+Write-protect mode only supports private anonymous memory.
 .SS Reading from the userfaultfd structure
 Each
 .BR read (2)
@@ -364,8 +460,12 @@ flag (see
 .BR ioctl_userfaultfd (2))
 and this flag is set, this a write fault;
 otherwise it is a read fault.
-.\"
-.\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
+.TP
+.B UFFD_PAGEFAULT_FLAG_WP
+If the address is in a range that was registered with the
+.B UFFDIO_REGISTER_MODE_WP
+flag, when this bit is set it means it's a write-protect fault.
+Otherwise it's a page missing fault.
 .RE
 .TP
 .I pagefault.feat.pid
-- 
2.31.0

[PATCH 4/5] ioctl_userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs

[Alejandro Colomar]

From: Peter Xu <peterx@redhat.com>

UFFD_FEATURE_THREAD_ID is supported in Linux 4.14.

Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_userfaultfd.2 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index 9120bdf40..014c0b5c1 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -208,6 +208,11 @@ signal will be sent to the faulting process.
 Applications using this
 feature will not require the use of a userfaultfd monitor for processing
 memory accesses to the regions registered with userfaultfd.
+.TP
+.BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)"
+If this feature bit is set,
+.I uffd_msg.pagefault.feat.ptid
+will be set to the faulted thread ID for each page fault message.
 .PP
 The returned
 .I ioctls
-- 
2.31.0

[PATCH 5/5] ioctl_userfaultfd.2: Add write-protect mode docs

[Alejandro Colomar]

From: Peter Xu <peterx@redhat.com>

Userfaultfd write-protect mode is supported starting from Linux 5.7.

Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
[alx: ffix + srcfix]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_userfaultfd.2 | 86 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 83 insertions(+), 3 deletions(-)

diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index 014c0b5c1..c29e0bb6a 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -234,6 +234,11 @@ operation is supported.
 The
 .B UFFDIO_UNREGISTER
 operation is supported.
+.TP
+.B 1 << _UFFDIO_WRITEPROTECT
+The
+.B UFFDIO_WRITEPROTECT
+operation is supported.
 .PP
 This
 .BR ioctl (2)
@@ -322,9 +327,6 @@ Track page faults on missing pages.
 .B UFFDIO_REGISTER_MODE_WP
 Track page faults on write-protected pages.
 .PP
-Currently, the only supported mode is
-.BR UFFDIO_REGISTER_MODE_MISSING .
-.PP
 If the operation is successful, the kernel modifies the
 .I ioctls
 bit-mask field to indicate which
@@ -443,6 +445,16 @@ operation:
 .TP
 .B UFFDIO_COPY_MODE_DONTWAKE
 Do not wake up the thread that waits for page-fault resolution
+.TP
+.B UFFDIO_COPY_MODE_WP
+Copy the page with read-only permission.
+This allows the user to trap the next write to the page,
+which will block and generate another write-protect userfault message.
+This is only used when both
+.B UFFDIO_REGISTER_MODE_MISSING
+and
+.B UFFDIO_REGISTER_MODE_WP
+modes are enabled for the registered range.
 .PP
 The
 .I copy
@@ -654,6 +666,74 @@ field of the
 structure was not a multiple of the system page size; or
 .I len
 was zero; or the specified range was otherwise invalid.
+.SS UFFDIO_WRITEPROTECT (Since Linux 5.7)
+Write-protect or write-unprotect an userfaultfd registered memory range
+registered with mode
+.BR UFFDIO_REGISTER_MODE_WP .
+.PP
+The
+.I argp
+argument is a pointer to a
+.I uffdio_range
+structure as shown below:
+.PP
+.in +4n
+.EX
+struct uffdio_writeprotect {
+    struct uffdio_range range; /* Range to change write permission*/
+    __u64 mode;                /* Mode to change write permission */
+};
+.EE
+.in
+.PP
+There're two mode bits that are supported in this structure:
+.TP
+.B UFFDIO_WRITEPROTECT_MODE_WP
+When this mode bit is set,
+the ioctl will be a write-protect operation upon the memory range specified by
+.IR range .
+Otherwise it'll be a write-unprotect operation upon the specified range,
+which can be used to resolve an userfaultfd write-protect page fault.
+.TP
+.B UFFDIO_WRITEPROTECT_MODE_DONTWAKE
+When this mode bit is set,
+do not wake up any thread that waits for
+page-fault resolution after the operation.
+This could only be specified if
+.B UFFDIO_WRITEPROTECT_MODE_WP
+is not specified.
+.PP
+This
+.BR ioctl (2)
+operation returns 0 on success.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+Possible errors include:
+.TP
+.B EINVAL
+The
+.I start
+or the
+.I len
+field of the
+.I ufdio_range
+structure was not a multiple of the system page size; or
+.I len
+was zero; or the specified range was otherwise invalid.
+.TP
+.B EAGAIN
+The process was interrupted; retry this call.
+.TP
+.B ENOENT
+The range specified in
+.I range
+is not valid.
+For example, the virtual address does not exist,
+or not registered with userfaultfd write-protect mode.
+.TP
+.B EFAULT
+Encountered a generic fault during processing.
 .SH RETURN VALUE
 See descriptions of the individual operations, above.
 .SH ERRORS
-- 
2.31.0

Re: [PATCH 1/5] scanf.3: clarify that %n supports type modifiers

[Michael Kerrisk (man-pages)]

Hello Alex and Alyssa,

On 4/5/21 3:13 PM, Alejandro Colomar wrote:
> From: Alyssa Ross <hi@alyssa.is>
> 
> My initial reading of this was that type modifiers were probably not
> supported.  But they are, and this is actually documented further up,
> in the type modifiers documentation.  But to make it clearer, let's
> copy the language that printf(3) has in its %n section.
> 
> Signed-off-by: Alyssa Ross <hi@alyssa.is>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man3/scanf.3 | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/scanf.3 b/man3/scanf.3
> index e6d00c9f1..bd49a6caf 100644
> --- a/man3/scanf.3
> +++ b/man3/scanf.3
> @@ -526,7 +526,9 @@ the next pointer must be a pointer to a pointer to
>  Nothing is expected; instead, the number of characters consumed thus far
>  from the input is stored through the next pointer, which must be a pointer
>  to
> -.IR int .
> +.IR int ,
> +or variant whose size matches the (optionally)
> +supplied integer length modifier.
>  This is
>  .I not
>  a conversion and does

Thanks. Patch applied.

Cheers,

Michael


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

Re: [PATCH 2/5] userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs

[Michael Kerrisk (man-pages)]

Hello Alex, and Peter,

Please take note below.

On 4/5/21 3:13 PM, Alejandro Colomar wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.
> 
> Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> [alx: srcfix]
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/userfaultfd.2 | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index fa1b6514f..8245253c3 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -77,6 +77,13 @@ 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 events are flushed.
>  .\"
> +.PP
> +Since Linux 4.14, userfaultfd page fault message can selectively embed
> +faulting thread ID information into the fault message.
> +One needs to enable this feature explicitly using the
> +.B UFFD_FEATURE_THREAD_ID
> +feature bit when initializing the userfaultfd context.
> +By default, thread ID reporting is disabled.
>  .SS Usage
>  The userfaultfd mechanism is designed to allow a thread in a multithreaded
>  program to perform user-space paging for the other threads in the process.
> @@ -229,6 +236,9 @@ struct uffd_msg {
>          struct {
>              __u64 flags;    /* Flags describing fault */
>              __u64 address;  /* Faulting address */
> +            union {
> +                __u32 ptid; /* Thread ID of the fault */
> +            } feat;
>          } pagefault;
>  
>          struct {            /* Since Linux 4.11 */
> @@ -358,6 +368,9 @@ otherwise it is a read fault.
>  .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
>  .RE
>  .TP
> +.I pagefault.feat.pid
> +The thread ID that triggered the page fault.
> +.TP
>  .I fork.ufd
>  The file descriptor associated with the userfault object
>  created for the child created by
 
Thanks. I've applied the patch, but I made a few tweaks afterwards,
as per the patch below. Notably, I changed "message" to
"notification", since that seems more consistent with the
language in the rest of the page. Is it okay, Peter?

Cheers,

Michael

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 8245253c3..eb2c6d5f9 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -78,8 +78,10 @@ all memory ranges that were registered with the object are unregistered
 and unread events are flushed.
 .\"
 .PP
-Since Linux 4.14, userfaultfd page fault message can selectively embed
-faulting thread ID information into the fault message.
+Since Linux 4.14,
+.\" commit 9d4ac934829ac58c5109c49e6dfe677300e5e652
+a userfaultfd page fault notification can selectively embed the
+faulting thread ID information in the notification.
 One needs to enable this feature explicitly using the
 .B UFFD_FEATURE_THREAD_ID
 feature bit when initializing the userfaultfd context.


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

Re: [PATCH 2/5] userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs

[Michael Kerrisk (man-pages)]

> Thanks. I've applied the patch, but I made a few tweaks afterwards,
> as per the patch below. Notably, I changed "message" to
> "notification", since that seems more consistent with the
> language in the rest of the page. Is it okay, Peter?

Hmmm -- ignore this. For now, I reverted the patch below,
since it causes the following patch to break.

Cheers,

Michael

> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index 8245253c3..eb2c6d5f9 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -78,8 +78,10 @@ all memory ranges that were registered with the object are unregistered
>  and unread events are flushed.
>  .\"
>  .PP
> -Since Linux 4.14, userfaultfd page fault message can selectively embed
> -faulting thread ID information into the fault message.
> +Since Linux 4.14,
> +.\" commit 9d4ac934829ac58c5109c49e6dfe677300e5e652
> +a userfaultfd page fault notification can selectively embed the
> +faulting thread ID information in the notification.
>  One needs to enable this feature explicitly using the
>  .B UFFD_FEATURE_THREAD_ID
>  feature bit when initializing the userfaultfd context.
> 
> 


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

Re: [PATCH 3/5] userfaultfd.2: Add write-protect mode

[Michael Kerrisk (man-pages)]

Hello Alex, Peter,

I've applied the patch below, but I have some questions.

On 4/5/21 3:13 PM, Alejandro Colomar wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> Write-protect mode is supported starting from Linux 5.7.
> 
> Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/userfaultfd.2 | 108 +++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 104 insertions(+), 4 deletions(-)
> 
> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index 8245253c3..0e9206424 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -78,6 +78,32 @@ all memory ranges that were registered with the object are unregistered
>  and unread events are flushed.
>  .\"
>  .PP
> +Userfaultfd supports two modes of registration:
> +.TP
> +.BR UFFDIO_REGISTER_MODE_MISSING " (since 4.10)"
> +When registered with
> +.B 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
> +.B UFFDIO_COPY
> +or an
> +.B UFFDIO_ZEROPAGE
> +ioctl.
> +.TP
> +.BR UFFDIO_REGISTER_MODE_WP " (since 5.7)"
> +When registered with
> +.B 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 write-unprotect the page using an
> +.B UFFDIO_WRITEPROTECT
> +ioctl.
> +.PP
> +Multiple modes can be enabled at the same time for the same memory range.
> +.PP
>  Since Linux 4.14, userfaultfd page fault message can selectively embed
>  faulting thread ID information into the fault message.
>  One needs to enable this feature explicitly using the
> @@ -107,7 +133,7 @@ the process that monitors userfaultfd and handles page faults
>  needs to be aware of the changes in the virtual memory layout
>  of the faulting process to avoid memory corruption.
>  .PP
> -Starting from Linux 4.11,
> +Since Linux 4.11,
>  userfaultfd can also notify the fault-handling threads about changes
>  in the virtual memory layout of the faulting process.
>  In addition, if the faulting process invokes
> @@ -144,6 +170,17 @@ single threaded non-cooperative userfaultfd manager implementations.
>  .\" and limitations remaining in 4.11
>  .\" Maybe it's worth adding a dedicated sub-section...
>  .\"
> +.PP
> +Since Linux 5.7, userfaultfd is able to do
> +synchronous page dirty tracking using the new write-protect 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

You use "user-space" elsewhere, but "the user" here. What is the difference?

More generally, What is "the user" in this context? I think you 
really mean  something like "the trap-handling thread"" or something
like that? The same statement applies for various pieces below.

> +kick the faulted thread to continue.

What does "kick" mean here. This should be explained.

> +For more information, please refer to "Userfaultfd write-protect mode" section.
>  .SS Userfaultfd operation
>  After the userfaultfd object is created with
>  .BR userfaultfd (),
> @@ -179,7 +216,7 @@ or
>  .BR ioctl (2)
>  operations to resolve the page fault.
>  .PP
> -Starting from Linux 4.14, if the application sets the
> +Since Linux 4.14, if the application sets the
>  .B UFFD_FEATURE_SIGBUS
>  feature bit using the
>  .B UFFDIO_API
> @@ -219,6 +256,65 @@ 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 5.7)
> +Since Linux 5.7, userfaultfd supports write-protect mode.
> +The user needs to first check availability of this feature using
> +.B UFFDIO_API
> +ioctl against the feature bit
> +.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
> +before using this feature.
> +.PP
> +To register with userfaultfd write-protect mode, the user needs to initiate the

You use "user-space" elsewhere, but "the user" here. What is the difference?

> +.B UFFDIO_REGISTER
> +ioctl with mode
> +.B 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

You use "user-space" elsewhere, but "the user" here. What is the difference?

> +.B UFFDIO_REGISTER
> +with the mode set to
> +.BR "UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP" .
> +When there is only
> +.B UFFDIO_REGISTER_MODE_WP
> +registered, the userspace will
> +.I not
> +receive any message when a missing page is written.
> +Instead, the userspace will only receive a write-protect page fault message
> +when an existing but write-protected page got written.

The wording here is a bit off. What does it mean: "an existing but 
write-protected page"?

> +.PP
> +After the
> +.B UFFDIO_REGISTER
> +ioctl completed with
> +.B UFFDIO_REGISTER_MODE_WP
> +mode set,
> +the user can write-protect any existing memory within the range using the ioctl

You use "user-space" elsewhere, but "the user" here. What is the difference?

> +.B UFFDIO_WRITEPROTECT
> +where
> +.I uffdio_writeprotect.mode
> +should be set to
> +.BR UFFDIO_WRITEPROTECT_MODE_WP .
> +.PP
> +When a write-protect event happens,
> +the userspace will receive a page fault message whose
> +.I uffd_msg.pagefault.flags
> +will be with
> +.B UFFD_PAGEFAULT_FLAG_WP
> +flag set.
> +Note: since only writes can trigger such kind of fault,
> +write-protect messages will always be with
> +.B UFFD_PAGEFAULT_FLAG_WRITE
> +bit set too along with bit
> +.BR UFFD_PAGEFAULT_FLAG_WP .
> +.PP
> +To resolve a write-protection page fault, the user should initiate another

You use "user-space" elsewhere, but "the user" here. What is the difference?

> +.B UFFDIO_WRITEPROTECT
> +ioctl, whose
> +.I uffd_msg.pagefault.flags
> +should have the flag
> +.B UFFDIO_WRITEPROTECT_MODE_WP
> +cleared upon the faulted page or range.
> +.PP
> +Write-protect mode only supports private anonymous memory.
>  .SS Reading from the userfaultfd structure
>  Each
>  .BR read (2)
> @@ -364,8 +460,12 @@ flag (see
>  .BR ioctl_userfaultfd (2))
>  and this flag is set, this a write fault;
>  otherwise it is a read fault.
> -.\"
> -.\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
> +.TP
> +.B UFFD_PAGEFAULT_FLAG_WP
> +If the address is in a range that was registered with the
> +.B UFFDIO_REGISTER_MODE_WP
> +flag, when this bit is set it means it's a write-protect fault.
> +Otherwise it's a page missing fault.
>  .RE
>  .TP
>  .I pagefault.feat.pid

Thanks,

Michael


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

Re: [PATCH 4/5] ioctl_userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs

[Michael Kerrisk (man-pages)]

Hello Alex, Peter.

On 4/5/21 3:13 PM, Alejandro Colomar wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> UFFD_FEATURE_THREAD_ID is supported in Linux 4.14.
> 
> Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied. 

Thanks,

Michael

> ---
>  man2/ioctl_userfaultfd.2 | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
> index 9120bdf40..014c0b5c1 100644
> --- a/man2/ioctl_userfaultfd.2
> +++ b/man2/ioctl_userfaultfd.2
> @@ -208,6 +208,11 @@ signal will be sent to the faulting process.
>  Applications using this
>  feature will not require the use of a userfaultfd monitor for processing
>  memory accesses to the regions registered with userfaultfd.
> +.TP
> +.BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)"
> +If this feature bit is set,
> +.I uffd_msg.pagefault.feat.ptid
> +will be set to the faulted thread ID for each page fault message.
>  .PP
>  The returned
>  .I ioctls
> 


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

Re: [PATCH 5/5] ioctl_userfaultfd.2: Add write-protect mode docs

[Michael Kerrisk (man-pages)]

Hello Alex, Peter,

I've applied the patch below, but I have some questions.

On 4/5/21 3:13 PM, Alejandro Colomar wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> Userfaultfd write-protect mode is supported starting from Linux 5.7.
> 
> Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> [alx: ffix + srcfix]
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/ioctl_userfaultfd.2 | 86 ++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 83 insertions(+), 3 deletions(-)
> 
> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
> index 014c0b5c1..c29e0bb6a 100644
> --- a/man2/ioctl_userfaultfd.2
> +++ b/man2/ioctl_userfaultfd.2
> @@ -234,6 +234,11 @@ operation is supported.
>  The
>  .B UFFDIO_UNREGISTER
>  operation is supported.
> +.TP
> +.B 1 << _UFFDIO_WRITEPROTECT
> +The
> +.B UFFDIO_WRITEPROTECT
> +operation is supported.
>  .PP
>  This
>  .BR ioctl (2)
> @@ -322,9 +327,6 @@ Track page faults on missing pages.
>  .B UFFDIO_REGISTER_MODE_WP
>  Track page faults on write-protected pages.
>  .PP
> -Currently, the only supported mode is
> -.BR UFFDIO_REGISTER_MODE_MISSING .
> -.PP
>  If the operation is successful, the kernel modifies the
>  .I ioctls
>  bit-mask field to indicate which
> @@ -443,6 +445,16 @@ operation:
>  .TP
>  .B UFFDIO_COPY_MODE_DONTWAKE
>  Do not wake up the thread that waits for page-fault resolution
> +.TP
> +.B UFFDIO_COPY_MODE_WP
> +Copy the page with read-only permission.
> +This allows the user to trap the next write to the page,

What is "the user" in this context? I think you really mean 
something like "the fault-handling thread"" or something
like that?

> +which will block and generate another write-protect userfault message.
> +This is only used when both
> +.B UFFDIO_REGISTER_MODE_MISSING
> +and
> +.B UFFDIO_REGISTER_MODE_WP
> +modes are enabled for the registered range.
>  .PP
>  The
>  .I copy
> @@ -654,6 +666,74 @@ field of the
>  structure was not a multiple of the system page size; or
>  .I len
>  was zero; or the specified range was otherwise invalid.
> +.SS UFFDIO_WRITEPROTECT (Since Linux 5.7)
> +Write-protect or write-unprotect an userfaultfd registered memory range
> +registered with mode
> +.BR UFFDIO_REGISTER_MODE_WP .
> +.PP
> +The
> +.I argp
> +argument is a pointer to a
> +.I uffdio_range
> +structure as shown below:
> +.PP
> +.in +4n
> +.EX
> +struct uffdio_writeprotect {
> +    struct uffdio_range range; /* Range to change write permission*/
> +    __u64 mode;                /* Mode to change write permission */
> +};
> +.EE
> +.in
> +.PP
> +There're two mode bits that are supported in this structure:
> +.TP
> +.B UFFDIO_WRITEPROTECT_MODE_WP
> +When this mode bit is set,
> +the ioctl will be a write-protect operation upon the memory range specified by
> +.IR range .
> +Otherwise it'll be a write-unprotect operation upon the specified range,
> +which can be used to resolve an userfaultfd write-protect page fault.
> +.TP
> +.B UFFDIO_WRITEPROTECT_MODE_DONTWAKE
> +When this mode bit is set,
> +do not wake up any thread that waits for
> +page-fault resolution after the operation.
> +This could only be specified if
> +.B UFFDIO_WRITEPROTECT_MODE_WP
> +is not specified.
> +.PP
> +This
> +.BR ioctl (2)
> +operation returns 0 on success.
> +On error, \-1 is returned and
> +.I errno
> +is set to indicate the error.
> +Possible errors include:
> +.TP
> +.B EINVAL
> +The
> +.I start
> +or the
> +.I len
> +field of the
> +.I ufdio_range
> +structure was not a multiple of the system page size; or
> +.I len
> +was zero; or the specified range was otherwise invalid.
> +.TP
> +.B EAGAIN
> +The process was interrupted; retry this call.
> +.TP
> +.B ENOENT
> +The range specified in
> +.I range
> +is not valid.
> +For example, the virtual address does not exist,
> +or not registered with userfaultfd write-protect mode.
> +.TP
> +.B EFAULT
> +Encountered a generic fault during processing.
>  .SH RETURN VALUE
>  See descriptions of the individual operations, above.
>  .SH ERRORS

Thanks,

Michael


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

Re: [PATCH 0/5] Merged patches from others

[Michael Kerrisk (man-pages)]

On Mon, 5 Apr 2021 at 15:13, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> These are the patches I have merged from others.

Thanks, Alex! All merged and pushed now.

Cheers,

Michael

> Alyssa Ross (1):
>   scanf.3: clarify that %n supports type modifiers
>
> Peter Xu (4):
>   userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
>   userfaultfd.2: Add write-protect mode
>   ioctl_userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
>   ioctl_userfaultfd.2: Add write-protect mode docs
>
>  man2/ioctl_userfaultfd.2 |  91 ++++++++++++++++++++++++++++-
>  man2/userfaultfd.2       | 121 +++++++++++++++++++++++++++++++++++++--
>  man3/scanf.3             |   4 +-
>  3 files changed, 208 insertions(+), 8 deletions(-)
>
> --
> 2.31.0
>


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

Re: [PATCH 3/5] userfaultfd.2: Add write-protect mode

[Peter Xu]

On Mon, Apr 05, 2021 at 11:13:14PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Alex, Peter,

Hi, Michael,

[...]

> > @@ -144,6 +170,17 @@ single threaded non-cooperative userfaultfd manager implementations.
> >  .\" and limitations remaining in 4.11
> >  .\" Maybe it's worth adding a dedicated sub-section...
> >  .\"
> > +.PP
> > +Since Linux 5.7, userfaultfd is able to do
> > +synchronous page dirty tracking using the new write-protect 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
> 
> You use "user-space" elsewhere, but "the user" here. What is the difference?

I wanted to mean the same idea of user-space indeed.

> 
> More generally, What is "the user" in this context? I think you 
> really mean  something like "the trap-handling thread"" or something
> like that? The same statement applies for various pieces below.

Yes, it's just a more general wording since the trap-handling thread in the
userfaultfd world belongs to the user, or the user-space.

> 
> > +kick the faulted thread to continue.
> 
> What does "kick" mean here. This should be explained.

Sorry about that, "kick" is a very frequently used wording for developers but
probably confusing for manpage readers, it means "wake up".

> 
> > +For more information, please refer to "Userfaultfd write-protect mode" section.
> >  .SS Userfaultfd operation
> >  After the userfaultfd object is created with
> >  .BR userfaultfd (),
> > @@ -179,7 +216,7 @@ or
> >  .BR ioctl (2)
> >  operations to resolve the page fault.
> >  .PP
> > -Starting from Linux 4.14, if the application sets the
> > +Since Linux 4.14, if the application sets the
> >  .B UFFD_FEATURE_SIGBUS
> >  feature bit using the
> >  .B UFFDIO_API
> > @@ -219,6 +256,65 @@ 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 5.7)
> > +Since Linux 5.7, userfaultfd supports write-protect mode.
> > +The user needs to first check availability of this feature using
> > +.B UFFDIO_API
> > +ioctl against the feature bit
> > +.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
> > +before using this feature.
> > +.PP
> > +To register with userfaultfd write-protect mode, the user needs to initiate the
> 
> You use "user-space" elsewhere, but "the user" here. What is the difference?

(I'm skipping same questions)

[...]

> > +.B UFFDIO_REGISTER
> > +with the mode set to
> > +.BR "UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP" .
> > +When there is only
> > +.B UFFDIO_REGISTER_MODE_WP
> > +registered, the userspace will
> > +.I not
> > +receive any message when a missing page is written.
> > +Instead, the userspace will only receive a write-protect page fault message
> > +when an existing but write-protected page got written.
> 
> The wording here is a bit off. What does it mean: "an existing but 
> write-protected page"?

I wanted to emphasize the fact that this write-protect message won't be
generated if the page does not exist at all.  That belongs to the missing page
fault even if a memory write triggerred the page fault.

Thanks,

-- 
Peter Xu