[1/4] userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
diff mbox series

Message ID 20210304015947.517713-2-peterx@redhat.com
State New, archived
Headers show
Series
  • man2: udpate mm/userfaultfd manpages to latest
Related show

Commit Message

Peter Xu March 4, 2021, 1:59 a.m. UTC
UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.

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

Comments

Mike Rapoport March 4, 2021, 6:38 a.m. UTC | #1
On Wed, Mar 03, 2021 at 08:59:44PM -0500, Peter Xu wrote:
> UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.
> 
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
>  man2/userfaultfd.2 | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index e7dc9f813..2d14effc6 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -77,6 +77,12 @@ 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 fault

                                                          Maybe faulting? ^

> +thread ID information into the fault message.  One needs to enable this feature
> +explicitly using the
> +.BR UFFD_FEATURE_THREAD_ID
> +feature bit when initializing the userfaultfd context, otherwise disabled.

             "... otherwise 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 +235,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 +367,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.26.2
>
Alejandro Colomar (man-pages) March 4, 2021, 9:22 a.m. UTC | #2
Hello Peter,

On 3/4/21 2:59 AM, Peter Xu wrote:
> UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.
> 
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
>   man2/userfaultfd.2 | 12 ++++++++++++
>   1 file changed, 12 insertions(+)
> 
> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index e7dc9f813..2d14effc6 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -77,6 +77,12 @@ 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 fault
> +thread ID information into the fault message.  One needs to enable this feature
> +explicitly using the
> +.BR UFFD_FEATURE_THREAD_ID

This should use [.B] and not [.BR].
.BR is for alternate Bold and Roman.
.B is for bold.

(There are more appearances of this in the other patches.)

Thanks,

Alex
Peter Xu March 4, 2021, 3:50 p.m. UTC | #3
On Thu, Mar 04, 2021 at 10:22:18AM +0100, Alejandro Colomar (man-pages) wrote:
> Hello Peter,

Hi, Alex,

> 
> On 3/4/21 2:59 AM, Peter Xu wrote:
> > UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.
> > 
> > Signed-off-by: Peter Xu <peterx@redhat.com>
> > ---
> >   man2/userfaultfd.2 | 12 ++++++++++++
> >   1 file changed, 12 insertions(+)
> > 
> > diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> > index e7dc9f813..2d14effc6 100644
> > --- a/man2/userfaultfd.2
> > +++ b/man2/userfaultfd.2
> > @@ -77,6 +77,12 @@ 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 fault
> > +thread ID information into the fault message.  One needs to enable this feature
> > +explicitly using the
> > +.BR UFFD_FEATURE_THREAD_ID
> 
> This should use [.B] and not [.BR].
> .BR is for alternate Bold and Roman.
> .B is for bold.
> 
> (There are more appearances of this in the other patches.)

Yeah I got a bit confused when differenciating those two, since I also see
similar usage, e.g.:

.BR O_CLOEXEC

I'll fix all of them appeared in current patchset.  Let me know if you also
want me to fix all the existing uses of ".BR" too where ".B" would suffice.
Otherwise I won't touch them since I can't say they're wrong either (I think
most of them should generate the same output with either ".BR" or ".B" if
there's only one word?).

Thanks,
Peter Xu March 4, 2021, 3:53 p.m. UTC | #4
On Thu, Mar 04, 2021 at 08:38:09AM +0200, Mike Rapoport wrote:
> On Wed, Mar 03, 2021 at 08:59:44PM -0500, Peter Xu wrote:
> > UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.
> > 
> > Signed-off-by: Peter Xu <peterx@redhat.com>
> > ---
> >  man2/userfaultfd.2 | 12 ++++++++++++
> >  1 file changed, 12 insertions(+)
> > 
> > diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> > index e7dc9f813..2d14effc6 100644
> > --- a/man2/userfaultfd.2
> > +++ b/man2/userfaultfd.2
> > @@ -77,6 +77,12 @@ 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 fault
> 
>                                                           Maybe faulting? ^

Ok.

> 
> > +thread ID information into the fault message.  One needs to enable this feature
> > +explicitly using the
> > +.BR UFFD_FEATURE_THREAD_ID
> > +feature bit when initializing the userfaultfd context, otherwise disabled.
> 
>              "... otherwise thread ID reporting is disabled" ^

I changed to "... By default, thread ID reporting is diabled."

Thanks!
Alejandro Colomar (man-pages) March 4, 2021, 6:13 p.m. UTC | #5
Hi Peter,

On 3/4/21 4:50 PM, Peter Xu wrote:
> On Thu, Mar 04, 2021 at 10:22:18AM +0100, Alejandro Colomar (man-pages) wrote:
>>> +.BR UFFD_FEATURE_THREAD_ID
>>
>> This should use [.B] and not [.BR].
>> .BR is for alternate Bold and Roman.
>> .B is for bold.
>>
>> (There are more appearances of this in the other patches.)
> 
> Yeah I got a bit confused when differenciating those two, since I also see
> similar usage, e.g.:
> 
> .BR O_CLOEXEC

Yes, these are minor imperfections that got into the manual pages, and 
we don't remove them due to the churn that it would create (and 
possibility of introducing other bugs while doing such a big scripted 
change that couldn't be easily reviewed (thousands of lines)).  So as we 
still have those lines, they tend to confuse.

> 
> I'll fix all of them appeared in current patchset.  Let me know if you also
> want me to fix all the existing uses of ".BR" too where ".B" would suffice.
> Otherwise I won't touch them since I can't say they're wrong either (I think
> most of them should generate the same output with either ".BR" or ".B" if
> there's only one word?).

Our current non-written guidelines are:
We are fixing the existing ones as we modify code near them,
but leave untouched code that is far from what we are changing, even on 
the same page.

Thanks,

Alex

Patch
diff mbox series

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index e7dc9f813..2d14effc6 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -77,6 +77,12 @@  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 fault
+thread ID information into the fault message.  One needs to enable this feature
+explicitly using the
+.BR UFFD_FEATURE_THREAD_ID
+feature bit when initializing the userfaultfd context, otherwise 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 +235,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 +367,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