[PATCH man-pages 0/2] some more userfault pages updates

[PATCH man-pages 0/2] some more userfault pages updates

[Mike Rapoport]

Hi Michael,

Here are some more updates to {ioctl_}userfaultfd.2 pages.

Mike Rapoport (2):
  userfaultfd.2: start documenting non-cooperative events
  ioctl_userfaultfd.2: start adding details about userfaultfd features

 man2/ioctl_userfaultfd.2 |  53 ++++++++++++++++++-
 man2/userfaultfd.2       | 135 ++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 179 insertions(+), 9 deletions(-)

-- 
1.9.1

[PATCH man-pages 1/2] userfaultfd.2: start documenting non-cooperative events

[Mike Rapoport]

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
---
 man2/userfaultfd.2 | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 128 insertions(+), 7 deletions(-)

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index cfea5cb..44af3e4 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -75,7 +75,7 @@ flag in
 .PP
 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.
+and unread events are flushed.
 .\"
 .SS Usage
 The userfaultfd mechanism is designed to allow a thread in a multithreaded
@@ -99,6 +99,20 @@ In such non-cooperative mode,
 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.
+
+Starting from Linux 4.11,
+userfaultfd may notify the fault-handling threads about changes
+in the virtual memory layout of the faulting process.
+In addition, if the faulting process invokes
+.BR fork (2)
+system call,
+the userfaultfd objects associated with the parent may be duplicated
+into the child process and the userfaultfd monitor will be notified
+about the file descriptor associated with the userfault objects
+created for the child process,
+which allows userfaultfd monitor to perform user-space paging
+for the child process.
+
 .\" FIXME elaborate about non-cooperating mode, describe its limitations
 .\" for kernels before 4.11, features added in 4.11
 .\" and limitations remaining in 4.11
@@ -144,6 +158,10 @@ Details of the various
 operations can be found in
 .BR ioctl_userfaultfd (2).
 
+Since Linux 4.11, events other than page-fault may enabled during
+.B UFFDIO_API
+operation.
+
 Up to Linux 4.11,
 userfaultfd can be used only with anonymous private memory mappings.
 
@@ -156,7 +174,8 @@ Each
 .BR read (2)
 from the userfaultfd file descriptor returns one or more
 .I uffd_msg
-structures, each of which describes a page-fault event:
+structures, each of which describes a page-fault event
+or an event required for the non-cooperative userfaultfd usage:
 
 .nf
 .in +4n
@@ -168,6 +187,23 @@ struct uffd_msg {
             __u64 flags;        /* Flags describing fault */
             __u64 address;      /* Faulting address */
         } pagefault;
+        struct {
+            __u32 ufd;          /* userfault file descriptor
+                                   of the child process */
+        } fork;                 /* since Linux 4.11 */
+        struct {
+            __u64 from;         /* old address of the
+                                   remapped area */
+            __u64 to;           /* new address of the
+                                   remapped area */
+            __u64 len;          /* original mapping length */
+        } remap;                /* since Linux 4.11 */
+        struct {
+            __u64 start;        /* start address of the
+                                   removed area */
+            __u64 end;          /* end address of the
+                                   removed area */
+        } remove;               /* since Linux 4.11 */
         ...
     } arg;
 
@@ -194,14 +230,73 @@ structure are as follows:
 .TP
 .I event
 The type of event.
-Currently, only one value can appear in this field:
-.BR UFFD_EVENT_PAGEFAULT ,
-which indicates a page-fault event.
+Depending of the event type,
+different fields of the
+.I arg
+union represent details required for the event processing.
+The non-page-fault events are generated only when appropriate feature
+is enabled during API handshake with
+.B UFFDIO_API
+.BR ioctl (2).
+
+The following values can appear in the
+.I event
+field:
+.RS
+.TP
+.B UFFD_EVENT_PAGEFAULT
+A page-fault event.
+The page-fault details are available in the
+.I pagefault
+field.
 .TP
-.I address
+.B UFFD_EVENT_FORK
+Generated when the faulting process invokes
+.BR fork (2)
+system call.
+The event details are available in the
+.I fork
+field.
+.\" FIXME descirbe duplication of userfault file descriptor during fork
+.TP
+.B UFFD_EVENT_REMAP
+Generated when the faulting process invokes
+.BR mremap (2)
+system call.
+The event details are available in the
+.I remap
+field.
+.TP
+.B UFFD_EVENT_REMOVE
+Generated when the faulting process invokes
+.BR madvise (2)
+system call with
+.BR MADV_DONTNEED
+or
+.BR MADV_REMOVE
+advice.
+The event details are available in the
+.I remove
+field.
+.TP
+.B UFFD_EVENT_UNMAP
+Generated when the faulting process unmaps a memory range,
+either explicitly using
+.BR munmap (2)
+system call or implicitly during
+.BR mmap (2)
+or
+.BR mremap (2)
+system calls.
+The event details are available in the
+.I remove
+field.
+.RE
+.TP
+.I pagefault.address
 The address that triggered the page fault.
 .TP
-.I flags
+.I pagefault.flags
 A bit mask of flags that describe the event.
 For
 .BR UFFD_EVENT_PAGEFAULT ,
@@ -218,6 +313,32 @@ otherwise it is a read fault.
 .\"
 .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
 .RE
+.TP
+.I fork.ufd
+The file descriptor associated with the userfault object
+created for the child process
+.TP
+.I remap.from
+The original address of the memory range that was remapped using
+.BR mremap (2).
+.TP
+.I remap.to
+The new address of the memory range that was remapped using
+.BR mremap (2).
+.TP
+.I remap.len
+The original length of the the memory range that was remapped using
+.BR mremap (2).
+.TP
+.I remove.start
+The start address of the memory range that was freed using
+.BR madvise (2)
+or unmapped
+.TP
+.I remove.end
+The end address of the memory range that was freed using
+.BR madvise (2)
+or unmapped
 .PP
 A
 .BR read (2)
-- 
1.9.1

Re: [PATCH man-pages 1/2] userfaultfd.2: start documenting non-cooperative events

[Michael Kerrisk (man-pages)]

Hi Mike,

I've applied this, but have some questions/points I think 
further clarification.

On 04/27/2017 04:14 PM, Mike Rapoport wrote:
> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> ---
>  man2/userfaultfd.2 | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 128 insertions(+), 7 deletions(-)
> 
> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index cfea5cb..44af3e4 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -75,7 +75,7 @@ flag in
>  .PP
>  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.
> +and unread events are flushed.
>  .\"
>  .SS Usage
>  The userfaultfd mechanism is designed to allow a thread in a multithreaded
> @@ -99,6 +99,20 @@ In such non-cooperative mode,
>  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.
> +
> +Starting from Linux 4.11,
> +userfaultfd may notify the fault-handling threads about changes
> +in the virtual memory layout of the faulting process.
> +In addition, if the faulting process invokes
> +.BR fork (2)
> +system call,
> +the userfaultfd objects associated with the parent may be duplicated
> +into the child process and the userfaultfd monitor will be notified
> +about the file descriptor associated with the userfault objects

What does "notified about the file descriptor" mean?

> +created for the child process,
> +which allows userfaultfd monitor to perform user-space paging
> +for the child process.
> +
>  .\" FIXME elaborate about non-cooperating mode, describe its limitations
>  .\" for kernels before 4.11, features added in 4.11
>  .\" and limitations remaining in 4.11
> @@ -144,6 +158,10 @@ Details of the various
>  operations can be found in
>  .BR ioctl_userfaultfd (2).
>  
> +Since Linux 4.11, events other than page-fault may enabled during
> +.B UFFDIO_API
> +operation.
> +
>  Up to Linux 4.11,
>  userfaultfd can be used only with anonymous private memory mappings.
>  
> @@ -156,7 +174,8 @@ Each
>  .BR read (2)
>  from the userfaultfd file descriptor returns one or more
>  .I uffd_msg
> -structures, each of which describes a page-fault event:
> +structures, each of which describes a page-fault event
> +or an event required for the non-cooperative userfaultfd usage:
>  
>  .nf
>  .in +4n
> @@ -168,6 +187,23 @@ struct uffd_msg {
>              __u64 flags;        /* Flags describing fault */
>              __u64 address;      /* Faulting address */
>          } pagefault;
> +        struct {
> +            __u32 ufd;          /* userfault file descriptor
> +                                   of the child process */
> +        } fork;                 /* since Linux 4.11 */
> +        struct {
> +            __u64 from;         /* old address of the
> +                                   remapped area */
> +            __u64 to;           /* new address of the
> +                                   remapped area */
> +            __u64 len;          /* original mapping length */
> +        } remap;                /* since Linux 4.11 */
> +        struct {
> +            __u64 start;        /* start address of the
> +                                   removed area */
> +            __u64 end;          /* end address of the
> +                                   removed area */
> +        } remove;               /* since Linux 4.11 */
>          ...
>      } arg;
>  
> @@ -194,14 +230,73 @@ structure are as follows:
>  .TP
>  .I event
>  The type of event.
> -Currently, only one value can appear in this field:
> -.BR UFFD_EVENT_PAGEFAULT ,
> -which indicates a page-fault event.
> +Depending of the event type,
> +different fields of the
> +.I arg
> +union represent details required for the event processing.
> +The non-page-fault events are generated only when appropriate feature
> +is enabled during API handshake with
> +.B UFFDIO_API
> +.BR ioctl (2).
> +
> +The following values can appear in the
> +.I event
> +field:
> +.RS
> +.TP
> +.B UFFD_EVENT_PAGEFAULT
> +A page-fault event.
> +The page-fault details are available in the
> +.I pagefault
> +field.
>  .TP
> -.I address
> +.B UFFD_EVENT_FORK
> +Generated when the faulting process invokes
> +.BR fork (2)
> +system call.
> +The event details are available in the
> +.I fork
> +field.
> +.\" FIXME descirbe duplication of userfault file descriptor during fork
> +.TP
> +.B UFFD_EVENT_REMAP
> +Generated when the faulting process invokes
> +.BR mremap (2)
> +system call.
> +The event details are available in the
> +.I remap
> +field.
> +.TP
> +.B UFFD_EVENT_REMOVE
> +Generated when the faulting process invokes
> +.BR madvise (2)
> +system call with
> +.BR MADV_DONTNEED
> +or
> +.BR MADV_REMOVE
> +advice.
> +The event details are available in the
> +.I remove
> +field.
> +.TP
> +.B UFFD_EVENT_UNMAP
> +Generated when the faulting process unmaps a memory range,
> +either explicitly using
> +.BR munmap (2)
> +system call or implicitly during
> +.BR mmap (2)
> +or
> +.BR mremap (2)
> +system calls.
> +The event details are available in the
> +.I remove
> +field.
> +.RE
> +.TP
> +.I pagefault.address
>  The address that triggered the page fault.
>  .TP
> -.I flags
> +.I pagefault.flags
>  A bit mask of flags that describe the event.
>  For
>  .BR UFFD_EVENT_PAGEFAULT ,
> @@ -218,6 +313,32 @@ otherwise it is a read fault.
>  .\"
>  .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
>  .RE
> +.TP
> +.I fork.ufd
> +The file descriptor associated with the userfault object
> +created for the child process
> +.TP
> +.I remap.from
> +The original address of the memory range that was remapped using
> +.BR mremap (2).
> +.TP
> +.I remap.to
> +The new address of the memory range that was remapped using
> +.BR mremap (2).
> +.TP
> +.I remap.len
> +The original length of the the memory range that was remapped using
> +.BR mremap (2).
> +.TP
> +.I remove.start
> +The start address of the memory range that was freed using
> +.BR madvise (2)
> +or unmapped
> +.TP
> +.I remove.end
> +The end address of the memory range that was freed using
> +.BR madvise (2)
> +or unmapped
>  .PP
>  A
>  .BR read (2)

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 man-pages 1/2] userfaultfd.2: start documenting non-cooperative events

[Mike Rapoprt]

On April 27, 2017 8:26:16 PM GMT+03:00, "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> wrote:
>Hi Mike,
>
>I've applied this, but have some questions/points I think 
>further clarification.
>
>On 04/27/2017 04:14 PM, Mike Rapoport wrote:
>> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
>> ---
>>  man2/userfaultfd.2 | 135
>++++++++++++++++++++++++++++++++++++++++++++++++++---
>>  1 file changed, 128 insertions(+), 7 deletions(-)
>> 
>> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
>> index cfea5cb..44af3e4 100644
>> --- a/man2/userfaultfd.2
>> +++ b/man2/userfaultfd.2
>> @@ -75,7 +75,7 @@ flag in
>>  .PP
>>  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.
>> +and unread events are flushed.
>>  .\"
>>  .SS Usage
>>  The userfaultfd mechanism is designed to allow a thread in a
>multithreaded
>> @@ -99,6 +99,20 @@ In such non-cooperative mode,
>>  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.
>> +
>> +Starting from Linux 4.11,
>> +userfaultfd may notify the fault-handling threads about changes
>> +in the virtual memory layout of the faulting process.
>> +In addition, if the faulting process invokes
>> +.BR fork (2)
>> +system call,
>> +the userfaultfd objects associated with the parent may be duplicated
>> +into the child process and the userfaultfd monitor will be notified
>> +about the file descriptor associated with the userfault objects
>
>What does "notified about the file descriptor" mean?

Well, seems that I've made this one really awkward :)
When the monitored process forks, all the userfault objects associated​ with it are duplicated into the child process. For each duplicated object, userfault generates event of type UFFD_EVENT_FORK and the uffdio_msg for this event contains the file descriptor that should be used to manipulate the duplicated userfault object.
Hope this clarifies.

>> +created for the child process,
>> +which allows userfaultfd monitor to perform user-space paging
>> +for the child process.
>> +
>>  .\" FIXME elaborate about non-cooperating mode, describe its
>limitations
>>  .\" for kernels before 4.11, features added in 4.11
>>  .\" and limitations remaining in 4.11
>> @@ -144,6 +158,10 @@ Details of the various
>>  operations can be found in
>>  .BR ioctl_userfaultfd (2).
>>  
>> +Since Linux 4.11, events other than page-fault may enabled during
>> +.B UFFDIO_API
>> +operation.
>> +
>>  Up to Linux 4.11,
>>  userfaultfd can be used only with anonymous private memory mappings.
>>  
>> @@ -156,7 +174,8 @@ Each
>>  .BR read (2)
>>  from the userfaultfd file descriptor returns one or more
>>  .I uffd_msg
>> -structures, each of which describes a page-fault event:
>> +structures, each of which describes a page-fault event
>> +or an event required for the non-cooperative userfaultfd usage:
>>  
>>  .nf
>>  .in +4n
>> @@ -168,6 +187,23 @@ struct uffd_msg {
>>              __u64 flags;        /* Flags describing fault */
>>              __u64 address;      /* Faulting address */
>>          } pagefault;
>> +        struct {
>> +            __u32 ufd;          /* userfault file descriptor
>> +                                   of the child process */
>> +        } fork;                 /* since Linux 4.11 */
>> +        struct {
>> +            __u64 from;         /* old address of the
>> +                                   remapped area */
>> +            __u64 to;           /* new address of the
>> +                                   remapped area */
>> +            __u64 len;          /* original mapping length */
>> +        } remap;                /* since Linux 4.11 */
>> +        struct {
>> +            __u64 start;        /* start address of the
>> +                                   removed area */
>> +            __u64 end;          /* end address of the
>> +                                   removed area */
>> +        } remove;               /* since Linux 4.11 */
>>          ...
>>      } arg;
>>  
>> @@ -194,14 +230,73 @@ structure are as follows:
>>  .TP
>>  .I event
>>  The type of event.
>> -Currently, only one value can appear in this field:
>> -.BR UFFD_EVENT_PAGEFAULT ,
>> -which indicates a page-fault event.
>> +Depending of the event type,
>> +different fields of the
>> +.I arg
>> +union represent details required for the event processing.
>> +The non-page-fault events are generated only when appropriate
>feature
>> +is enabled during API handshake with
>> +.B UFFDIO_API
>> +.BR ioctl (2).
>> +
>> +The following values can appear in the
>> +.I event
>> +field:
>> +.RS
>> +.TP
>> +.B UFFD_EVENT_PAGEFAULT
>> +A page-fault event.
>> +The page-fault details are available in the
>> +.I pagefault
>> +field.
>>  .TP
>> -.I address
>> +.B UFFD_EVENT_FORK
>> +Generated when the faulting process invokes
>> +.BR fork (2)
>> +system call.
>> +The event details are available in the
>> +.I fork
>> +field.
>> +.\" FIXME descirbe duplication of userfault file descriptor during
>fork
>> +.TP
>> +.B UFFD_EVENT_REMAP
>> +Generated when the faulting process invokes
>> +.BR mremap (2)
>> +system call.
>> +The event details are available in the
>> +.I remap
>> +field.
>> +.TP
>> +.B UFFD_EVENT_REMOVE
>> +Generated when the faulting process invokes
>> +.BR madvise (2)
>> +system call with
>> +.BR MADV_DONTNEED
>> +or
>> +.BR MADV_REMOVE
>> +advice.
>> +The event details are available in the
>> +.I remove
>> +field.
>> +.TP
>> +.B UFFD_EVENT_UNMAP
>> +Generated when the faulting process unmaps a memory range,
>> +either explicitly using
>> +.BR munmap (2)
>> +system call or implicitly during
>> +.BR mmap (2)
>> +or
>> +.BR mremap (2)
>> +system calls.
>> +The event details are available in the
>> +.I remove
>> +field.
>> +.RE
>> +.TP
>> +.I pagefault.address
>>  The address that triggered the page fault.
>>  .TP
>> -.I flags
>> +.I pagefault.flags
>>  A bit mask of flags that describe the event.
>>  For
>>  .BR UFFD_EVENT_PAGEFAULT ,
>> @@ -218,6 +313,32 @@ otherwise it is a read fault.
>>  .\"
>>  .\" UFFD_PAGEFAULT_FLAG_WP is not yet supported.
>>  .RE
>> +.TP
>> +.I fork.ufd
>> +The file descriptor associated with the userfault object
>> +created for the child process
>> +.TP
>> +.I remap.from
>> +The original address of the memory range that was remapped using
>> +.BR mremap (2).
>> +.TP
>> +.I remap.to
>> +The new address of the memory range that was remapped using
>> +.BR mremap (2).
>> +.TP
>> +.I remap.len
>> +The original length of the the memory range that was remapped using
>> +.BR mremap (2).
>> +.TP
>> +.I remove.start
>> +The start address of the memory range that was freed using
>> +.BR madvise (2)
>> +or unmapped
>> +.TP
>> +.I remove.end
>> +The end address of the memory range that was freed using
>> +.BR madvise (2)
>> +or unmapped
>>  .PP
>>  A
>>  .BR read (2)
>
>Cheers,
>
>Michael

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [PATCH man-pages 1/2] userfaultfd.2: start documenting non-cooperative events

[Michael Kerrisk (man-pages)]

Hi Mike,

On 04/28/2017 11:45 AM, Mike Rapoprt wrote:
> 
> 
> On April 27, 2017 8:26:16 PM GMT+03:00, "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> wrote:
>> Hi Mike,
>>
>> I've applied this, but have some questions/points I think 
>> further clarification.
>>
>> On 04/27/2017 04:14 PM, Mike Rapoport wrote:
>>> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
>>> ---
>>>  man2/userfaultfd.2 | 135
>> ++++++++++++++++++++++++++++++++++++++++++++++++++---
>>>  1 file changed, 128 insertions(+), 7 deletions(-)
>>>
>>> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
>>> index cfea5cb..44af3e4 100644
>>> --- a/man2/userfaultfd.2
>>> +++ b/man2/userfaultfd.2
>>> @@ -75,7 +75,7 @@ flag in
>>>  .PP
>>>  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.
>>> +and unread events are flushed.
>>>  .\"
>>>  .SS Usage
>>>  The userfaultfd mechanism is designed to allow a thread in a
>> multithreaded
>>> @@ -99,6 +99,20 @@ In such non-cooperative mode,
>>>  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.
>>> +
>>> +Starting from Linux 4.11,
>>> +userfaultfd may notify the fault-handling threads about changes
>>> +in the virtual memory layout of the faulting process.
>>> +In addition, if the faulting process invokes
>>> +.BR fork (2)
>>> +system call,
>>> +the userfaultfd objects associated with the parent may be duplicated
>>> +into the child process and the userfaultfd monitor will be notified
>>> +about the file descriptor associated with the userfault objects
>>
>> What does "notified about the file descriptor" mean?
> 
> Well, seems that I've made this one really awkward :)
> When the monitored process forks, all the userfault objects
> associated​ with it are duplicated into the child process. For each
> duplicated object, userfault generates event of type UFFD_EVENT_FORK
> and the uffdio_msg for this event contains the file descriptor that
> should be used to manipulate the duplicated userfault object.
> Hope this clarifies.

Yes, it's clearer now.

Mostly what was needed here was a forward reference that mentions
UFFD_EVENT_FORK explicitly. I added that, and also enhanced the
text on UFFD_EVENT_FORK a little.

Also, it's not just fork(2) for which UFFD_EVENT_FORK is generated,
right? It can also be a clone(2) cal that does not specify
CLONE_VM, right?

Could you review my changes in commit 522ab2ff6fc9010432a
to make sure they are okay.

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 man-pages 1/2] userfaultfd.2: start documenting non-cooperative events

[Mike Rapoport]

On Mon, May 01, 2017 at 08:34:16PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Mike,
> 
> On 04/28/2017 11:45 AM, Mike Rapoprt wrote:
> > 
> > 
> > On April 27, 2017 8:26:16 PM GMT+03:00, "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> wrote:
> >> Hi Mike,
> >>
> >> I've applied this, but have some questions/points I think 
> >> further clarification.
> >>
> >> On 04/27/2017 04:14 PM, Mike Rapoport wrote:
> >>> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> >>> ---
> >>>  man2/userfaultfd.2 | 135
> >> ++++++++++++++++++++++++++++++++++++++++++++++++++---
> >>>  1 file changed, 128 insertions(+), 7 deletions(-)
> >>>
> >>> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> >>> index cfea5cb..44af3e4 100644
> >>> --- a/man2/userfaultfd.2
> >>> +++ b/man2/userfaultfd.2
> >>> @@ -75,7 +75,7 @@ flag in
> >>>  .PP
> >>>  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.
> >>> +and unread events are flushed.
> >>>  .\"
> >>>  .SS Usage
> >>>  The userfaultfd mechanism is designed to allow a thread in a
> >> multithreaded
> >>> @@ -99,6 +99,20 @@ In such non-cooperative mode,
> >>>  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.
> >>> +
> >>> +Starting from Linux 4.11,
> >>> +userfaultfd may notify the fault-handling threads about changes
> >>> +in the virtual memory layout of the faulting process.
> >>> +In addition, if the faulting process invokes
> >>> +.BR fork (2)
> >>> +system call,
> >>> +the userfaultfd objects associated with the parent may be duplicated
> >>> +into the child process and the userfaultfd monitor will be notified
> >>> +about the file descriptor associated with the userfault objects
> >>
> >> What does "notified about the file descriptor" mean?
> > 
> > Well, seems that I've made this one really awkward :)
> > When the monitored process forks, all the userfault objects
> > associated​ with it are duplicated into the child process. For each
> > duplicated object, userfault generates event of type UFFD_EVENT_FORK
> > and the uffdio_msg for this event contains the file descriptor that
> > should be used to manipulate the duplicated userfault object.
> > Hope this clarifies.
> 
> Yes, it's clearer now.
> 
> Mostly what was needed here was a forward reference that mentions
> UFFD_EVENT_FORK explicitly. I added that, and also enhanced the
> text on UFFD_EVENT_FORK a little.
> 
> Also, it's not just fork(2) for which UFFD_EVENT_FORK is generated,
> right? It can also be a clone(2) cal that does not specify
> CLONE_VM, right?

Yes.
 
> Could you review my changes in commit 522ab2ff6fc9010432a
> to make sure they are okay.

Yes, thats correct and with your updates the text is much clearer. Thanks.
 
> 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 man-pages 1/2] userfaultfd.2: start documenting non-cooperative events

[Michael Kerrisk (man-pages)]

On 05/02/2017 11:22 AM, Mike Rapoport wrote:
> On Mon, May 01, 2017 at 08:34:16PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Mike,
>>
>> On 04/28/2017 11:45 AM, Mike Rapoprt wrote:
>>>
>>>
>>> On April 27, 2017 8:26:16 PM GMT+03:00, "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> wrote:
>>>> Hi Mike,
>>>>
>>>> I've applied this, but have some questions/points I think 
>>>> further clarification.
>>>>
>>>> On 04/27/2017 04:14 PM, Mike Rapoport wrote:
>>>>> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
>>>>> ---
>>>>>  man2/userfaultfd.2 | 135
>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++---
>>>>>  1 file changed, 128 insertions(+), 7 deletions(-)
>>>>>
>>>>> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
>>>>> index cfea5cb..44af3e4 100644
>>>>> --- a/man2/userfaultfd.2
>>>>> +++ b/man2/userfaultfd.2
>>>>> @@ -75,7 +75,7 @@ flag in
>>>>>  .PP
>>>>>  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.
>>>>> +and unread events are flushed.
>>>>>  .\"
>>>>>  .SS Usage
>>>>>  The userfaultfd mechanism is designed to allow a thread in a
>>>> multithreaded
>>>>> @@ -99,6 +99,20 @@ In such non-cooperative mode,
>>>>>  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.
>>>>> +
>>>>> +Starting from Linux 4.11,
>>>>> +userfaultfd may notify the fault-handling threads about changes
>>>>> +in the virtual memory layout of the faulting process.
>>>>> +In addition, if the faulting process invokes
>>>>> +.BR fork (2)
>>>>> +system call,
>>>>> +the userfaultfd objects associated with the parent may be duplicated
>>>>> +into the child process and the userfaultfd monitor will be notified
>>>>> +about the file descriptor associated with the userfault objects
>>>>
>>>> What does "notified about the file descriptor" mean?
>>>
>>> Well, seems that I've made this one really awkward :)
>>> When the monitored process forks, all the userfault objects
>>> associated​ with it are duplicated into the child process. For each
>>> duplicated object, userfault generates event of type UFFD_EVENT_FORK
>>> and the uffdio_msg for this event contains the file descriptor that
>>> should be used to manipulate the duplicated userfault object.
>>> Hope this clarifies.
>>
>> Yes, it's clearer now.
>>
>> Mostly what was needed here was a forward reference that mentions
>> UFFD_EVENT_FORK explicitly. I added that, and also enhanced the
>> text on UFFD_EVENT_FORK a little.
>>
>> Also, it's not just fork(2) for which UFFD_EVENT_FORK is generated,
>> right? It can also be a clone(2) cal that does not specify
>> CLONE_VM, right?
> 
> Yes.
>  
>> Could you review my changes in commit 522ab2ff6fc9010432a
>> to make sure they are okay.
> 
> Yes, thats correct and with your updates the text is much clearer. Thanks.

Thanks for checking!

Cheers,

Michael


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

[PATCH man-pages 2/2] ioctl_userfaultfd.2: start adding details about userfaultfd features

[Mike Rapoport]

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
---
 man2/ioctl_userfaultfd.2 | 53 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index 42bf7a7..cdc07e0 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -121,22 +121,70 @@ and explicitly enable userfaultfd features that are disabled by default.
 The kernel always reports all the available features in the
 .I features
 field.
+
+To enable userfaultfd features the application should set
+a bit corresponding to each feature it wants to enable in the
+.I features
+field.
+If the kernel supports all the requested features it will enable them.
+Otherwise it will zero out the returned
+.I uffdio_api
+structure and return
+.BR EINVAL .
 .\" FIXME add more details about feature negotiation and enablement
 
 Since Linux 4.11, the following feature bits may be set:
 .TP
 .B UFFD_FEATURE_EVENT_FORK
+When this feature is enabled,
+the userfaultfd objects associated with a parent process are duplicated
+into the child process during
+.BR fork (2)
+system call and the
+.I UFFD_EVENT_FORK
+is delivered to the userfaultfd monitor
 .TP
 .B UFFD_FEATURE_EVENT_REMAP
+If this feature is enabled,
+when the faulting process invokes
+.BR mremap (2)
+system call
+the userfaultfd monitor will receive an event of type
+.I UFFD_EVENT_REMAP.
 .TP
 .B UFFD_FEATURE_EVENT_REMOVE
+If this feature is enabled,
+when the faulting process calls
+.BR madvise(2)
+system call with
+.I MADV_DONTNEED
+or
+.I MADV_REMOVE
+advice to free a virtual memory area
+the userfaultfd monitor will receive an event of type
+.I UFFD_EVENT_REMOVE.
 .TP
 .B UFFD_FEATURE_EVENT_UNMAP
+If this feature is enabled,
+when the faulting process unmaps virtual memory either explicitly with
+.BR munmap (2)
+system call, or implicitly either during
+.BR mmap (2)
+or
+.BR mremap (2)
+system call,
+the userfaultfd monitor will receive an event of type
+.I UFFD_EVENT_UNMAP
 .TP
 .B UFFD_FEATURE_MISSING_HUGETLBFS
+If this feature bit is set,
+the kernel supports registering userfaultfd ranges on hugetlbfs
+virtual memory areas
 .TP
 .B UFFD_FEATURE_MISSING_SHMEM
-.\" FIXME add feature description
+If this feature bit is set,
+the kernel supports registering userfaultfd ranges on tmpfs
+virtual memory areas
 
 The returned
 .I ioctls
@@ -182,7 +230,8 @@ The API version requested in the
 .I api
 field is not supported by this kernel, or the
 .I features
-field was not zero.
+field passed to the kernel includes feature bits that are not supported
+by the current kernel version.
 .\" FIXME In the above error case, the returned 'uffdio_api' structure is
 .\" zeroed out. Why is this done? This should be explained in the manual page.
 .\"
-- 
1.9.1

Re: [PATCH man-pages 2/2] ioctl_userfaultfd.2: start adding details about userfaultfd features

[Michael Kerrisk (man-pages)]

On 04/27/2017 04:14 PM, Mike Rapoport wrote:
> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>

Thanks, Mike. Applied, and lightly edited.

All changes now pushed to Git.

Cheers,

Michael

> ---
>  man2/ioctl_userfaultfd.2 | 53 ++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 51 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
> index 42bf7a7..cdc07e0 100644
> --- a/man2/ioctl_userfaultfd.2
> +++ b/man2/ioctl_userfaultfd.2
> @@ -121,22 +121,70 @@ and explicitly enable userfaultfd features that are disabled by default.
>  The kernel always reports all the available features in the
>  .I features
>  field.
> +
> +To enable userfaultfd features the application should set
> +a bit corresponding to each feature it wants to enable in the
> +.I features
> +field.
> +If the kernel supports all the requested features it will enable them.
> +Otherwise it will zero out the returned
> +.I uffdio_api
> +structure and return
> +.BR EINVAL .
>  .\" FIXME add more details about feature negotiation and enablement
>  
>  Since Linux 4.11, the following feature bits may be set:
>  .TP
>  .B UFFD_FEATURE_EVENT_FORK
> +When this feature is enabled,
> +the userfaultfd objects associated with a parent process are duplicated
> +into the child process during
> +.BR fork (2)
> +system call and the
> +.I UFFD_EVENT_FORK
> +is delivered to the userfaultfd monitor
>  .TP
>  .B UFFD_FEATURE_EVENT_REMAP
> +If this feature is enabled,
> +when the faulting process invokes
> +.BR mremap (2)
> +system call
> +the userfaultfd monitor will receive an event of type
> +.I UFFD_EVENT_REMAP.
>  .TP
>  .B UFFD_FEATURE_EVENT_REMOVE
> +If this feature is enabled,
> +when the faulting process calls
> +.BR madvise(2)
> +system call with
> +.I MADV_DONTNEED
> +or
> +.I MADV_REMOVE
> +advice to free a virtual memory area
> +the userfaultfd monitor will receive an event of type
> +.I UFFD_EVENT_REMOVE.
>  .TP
>  .B UFFD_FEATURE_EVENT_UNMAP
> +If this feature is enabled,
> +when the faulting process unmaps virtual memory either explicitly with
> +.BR munmap (2)
> +system call, or implicitly either during
> +.BR mmap (2)
> +or
> +.BR mremap (2)
> +system call,
> +the userfaultfd monitor will receive an event of type
> +.I UFFD_EVENT_UNMAP
>  .TP
>  .B UFFD_FEATURE_MISSING_HUGETLBFS
> +If this feature bit is set,
> +the kernel supports registering userfaultfd ranges on hugetlbfs
> +virtual memory areas
>  .TP
>  .B UFFD_FEATURE_MISSING_SHMEM
> -.\" FIXME add feature description
> +If this feature bit is set,
> +the kernel supports registering userfaultfd ranges on tmpfs
> +virtual memory areas
>  
>  The returned
>  .I ioctls
> @@ -182,7 +230,8 @@ The API version requested in the
>  .I api
>  field is not supported by this kernel, or the
>  .I features
> -field was not zero.
> +field passed to the kernel includes feature bits that are not supported
> +by the current kernel version.
>  .\" FIXME In the above error case, the returned 'uffdio_api' structure is
>  .\" zeroed out. Why is this done? This should be explained in the manual page.
>  .\"
> 


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