[PATCH v2 0/2] userfaultfd.2: Update to latest

[PATCH v2 0/2] userfaultfd.2: Update to latest

[Peter Xu]

v2:
- Use semantic newlines always in patch 1 [Alex]
- Fix s/.BR/.B/ in patch 2 [Alex]
- Rebased to http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git

Add the two missing pieces till latest 5.19-rc1: the UFFD_USER_MODE_ONLY
flag, and also the recent wr-protect support on shmem and hugetlbfs.

Please review, thanks.

Peter Xu (2):
  userfaultfd.2: Add section for UFFD_USER_MODE_ONLY
  userfaultfd.2: Update on write-protection support

 man2/userfaultfd.2 | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

-- 
2.32.0

[PATCH v2 1/2] userfaultfd.2: Add section for UFFD_USER_MODE_ONLY

[Peter Xu]

Add a paragraph for UFFD_USER_MODE_ONLY flag that was introduced in
Linux 5.11.

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

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 93dca009f..6b9412aaf 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -12,8 +12,9 @@ Standard C library
 .RI ( libc ", " \-lc )
 .SH SYNOPSIS
 .nf
-.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
-.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.BR "#include <fcntl.h>" "             /* Definition of " O_* " constants */"
+.BR "#include <sys/syscall.h>" "       /* Definition of " SYS_* " constants */"
+.BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "int syscall(SYS_userfaultfd, int " flags );
@@ -59,6 +60,15 @@ See the description of the
 .B O_NONBLOCK
 flag in
 .BR open (2).
+.TP
+.B UFFD_USER_MODE_ONLY
+This is an userfaultfd specific flag that was introduced since Linux 5.11.
+When set, the userfaultfd object will only be able to handle page faults
+originated from the userspace on the registered regions.
+When a kernel originated fault was triggered on the registered range with
+this userfaultfd, a
+.B SIGBUS
+signal will be delivered.
 .PP
 When the last file descriptor referring to a userfaultfd object is closed,
 all memory ranges that were registered with the object are unregistered
-- 
2.32.0

[PATCH v2 2/2] userfaultfd.2: Update on write-protection support

[Peter Xu]

The shmem/hugetlbfs memory types are supported for write-protection
messages very lately.  Update the man page to reflect that.

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

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 6b9412aaf..9b5ec0358 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -270,13 +270,18 @@ 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.
+Since Linux 5.7, userfaultfd supports write-protect mode for anonymous memory.
 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
+Since Linux 5.19, the write-protection mode was also supported on shmem and hugetlbfs
+memory types.
+It can be detected with the feature bit
+.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
+.PP
 To register with userfaultfd write-protect mode, the user needs to initiate the
 .B UFFDIO_REGISTER
 ioctl with mode
@@ -327,8 +332,6 @@ ioctl, whose
 should have the flag
 .B UFFDIO_WRITEPROTECT_MODE_WP
 cleared upon the faulted page or range.
-.PP
-Write-protect mode supports only private anonymous memory.
 .\"
 .SS Userfaultfd minor fault mode (since 5.13)
 Since Linux 5.13,
-- 
2.32.0

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2361 bytes --]

Hi Peter,

On 6/3/22 19:37, Peter Xu wrote:
> v2:
> - Use semantic newlines always in patch 1 [Alex]
> - Fix s/.BR/.B/ in patch 2 [Alex]
> - Rebased to http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git
> 
> Add the two missing pieces till latest 5.19-rc1: the UFFD_USER_MODE_ONLY
> flag, and also the recent wr-protect support on shmem and hugetlbfs.
> 
> Please review, thanks.
> 
> Peter Xu (2):
>    userfaultfd.2: Add section for UFFD_USER_MODE_ONLY
>    userfaultfd.2: Update on write-protection support
> 
>   man2/userfaultfd.2 | 23 ++++++++++++++++++-----
>   1 file changed, 18 insertions(+), 5 deletions(-)
> 


I think the patch below would improve a little bit the wording (and 
newlines).  I still have a bit of trouble understanding "When a 
kernel-originated fault was triggered on the registered range with this 
userfaultfd".  Did you maybe mean "range registered" instead of 
"registered range"?

Thanks,

Alex


diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 9b5ec0358..0c0a4f687 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -62,11 +62,11 @@ flag in
  .BR open (2).
  .TP
  .B UFFD_USER_MODE_ONLY
-This is an userfaultfd specific flag that was introduced since Linux 5.11.
-When set, the userfaultfd object will only be able to handle page faults
-originated from the userspace on the registered regions.
-When a kernel originated fault was triggered on the registered range with
-this userfaultfd, a
+This is an userfaultfd-specific flag that was introduced in Linux 5.11.
+When set, the userfaultfd object will only be able to handle
+page faults originated from the user space on the registered regions.
+When a kernel-originated fault was triggered
+on the registered range with this userfaultfd, a
  .B SIGBUS
  signal will be delivered.
  .PP
@@ -277,8 +277,9 @@ ioctl against the feature bit
  .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
  before using this feature.
  .PP
-Since Linux 5.19, the write-protection mode was also supported on shmem 
and hugetlbfs
-memory types.
+Since Linux 5.19,
+the write-protection mode was also supported on
+shmem and hugetlbfs memory types.
  It can be detected with the feature bit
  .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
  .PP


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Peter Xu]

On Mon, Jun 06, 2022 at 08:52:25PM +0200, Alejandro Colomar wrote:
> Hi Peter,

Hi, Alex,

> 
> On 6/3/22 19:37, Peter Xu wrote:
> > v2:
> > - Use semantic newlines always in patch 1 [Alex]
> > - Fix s/.BR/.B/ in patch 2 [Alex]
> > - Rebased to http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git
> > 
> > Add the two missing pieces till latest 5.19-rc1: the UFFD_USER_MODE_ONLY
> > flag, and also the recent wr-protect support on shmem and hugetlbfs.
> > 
> > Please review, thanks.
> > 
> > Peter Xu (2):
> >    userfaultfd.2: Add section for UFFD_USER_MODE_ONLY
> >    userfaultfd.2: Update on write-protection support
> > 
> >   man2/userfaultfd.2 | 23 ++++++++++++++++++-----
> >   1 file changed, 18 insertions(+), 5 deletions(-)
> > 
> 
> 
> I think the patch below would improve a little bit the wording (and
> newlines).  I still have a bit of trouble understanding "When a
> kernel-originated fault was triggered on the registered range with this
> userfaultfd".  Did you maybe mean "range registered" instead of "registered
> range"?

Since I'm not a native speaker I don't immediately see the difference
between the two..  What I wanted to express is all the memory ranges that
we registered with UFFDIO_REGISTER ioctl, and further it was trying to
describe what the kernel will do when there're any page faults that were
triggered upon those ranges from a kernel context.

It's always challenging for me to grasp how you prefer the newlines are
made, but anyway below changes looks good to me.  Thanks,

> 
> Thanks,
> 
> Alex
> 
> 
> diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> index 9b5ec0358..0c0a4f687 100644
> --- a/man2/userfaultfd.2
> +++ b/man2/userfaultfd.2
> @@ -62,11 +62,11 @@ flag in
>  .BR open (2).
>  .TP
>  .B UFFD_USER_MODE_ONLY
> -This is an userfaultfd specific flag that was introduced since Linux 5.11.
> -When set, the userfaultfd object will only be able to handle page faults
> -originated from the userspace on the registered regions.
> -When a kernel originated fault was triggered on the registered range with
> -this userfaultfd, a
> +This is an userfaultfd-specific flag that was introduced in Linux 5.11.
> +When set, the userfaultfd object will only be able to handle
> +page faults originated from the user space on the registered regions.
> +When a kernel-originated fault was triggered
> +on the registered range with this userfaultfd, a
>  .B SIGBUS
>  signal will be delivered.
>  .PP
> @@ -277,8 +277,9 @@ ioctl against the feature bit
>  .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
>  before using this feature.
>  .PP
> -Since Linux 5.19, the write-protection mode was also supported on shmem and
> hugetlbfs
> -memory types.
> +Since Linux 5.19,
> +the write-protection mode was also supported on
> +shmem and hugetlbfs memory types.
>  It can be detected with the feature bit
>  .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
>  .PP
> 
> 
> -- 
> Alejandro Colomar
> <http://www.alejandro-colomar.es/>




-- 
Peter Xu

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 4251 bytes --]

[CC list trimmed since this is solely about English and *roff]

At 2022-06-06T15:40:08-0400, Peter Xu wrote:
> > I think the patch below would improve a little bit the wording (and
> > newlines).  I still have a bit of trouble understanding "When a
> > kernel-originated fault was triggered on the registered range with
> > this userfaultfd".  Did you maybe mean "range registered" instead of
> > "registered range"?
> 
> Since I'm not a native speaker I don't immediately see the difference
> between the two.

Short answer: I think your existing wording is acceptable.

As a native speaker (but not a trained linguist) I think I can speak to
the subject: both forms are equivalent in this application.  In standard
English, adjectives usually precede the nouns they modify.  Exceptions
include noun phrases borrowed from other languages, like "danse
macabre", word order reversals for poetic dramatic effect ("I sing the
body electric"), or clarity in cases where compound adjectives need to
be applied disjunctively instead of conjunctively, as in "this race is
open to runners fast and slow".  (Any given runner is fast or slow, not
both simultaneously.  In everyday spoken language, this point of clarity
is frequently overlooked, but it's helpful in formal communication.)

In the instant case, "registered range", "registered" is an attributive
adjective modifying "range".  When the order is reversed, it is a
shorter form (but still standard) of "range that is registered", where
the "registered" serves as more of a predicate adjective, albeit in a
restrictive clause.[1]

"Registered" is the past participle form of the infinitive verb "[to]
register", and it is extremely common for participles present and
past[2] to be used as adjectives.  It is not universally the case,
however.[3]

> It's always challenging for me to grasp how you prefer the newlines
> are made, but anyway below changes looks good to me.

If it helps, here is a snippet of recommendations for *roff input from
the GNU Troff Manual.

   * Follow sentence endings in input with newlines to ease their
     recognition.  It is frequently convenient to break after colons and
     semicolons as well, as these typically precede independent clauses.
     Consider breaking after commas; they often occur in lists that
     become easy to scan when itemized by line, or constitute
     supplements to the sentence that are added, deleted, or updated to
     clarify it.  Parenthetical and quoted phrases are also good
     candidates for placement on input lines by themselves.  In filled
     text, spaces and newlines are interchangeable; place breaks where
     it aids your purpose.

   * Set your text editor's line length to 72 characters or fewer.
     This limit, combined with the previous advice regarding breaking
     around punctuation, makes it less common that an input line will
     wrap in your text editor, and thus will help you perceive
     excessively long constructions in your text.  Recall that natural
     languages originate in speech, not writing, and that punctuation is
     correlated with pauses for breathing and changes in prosody.

   * Use '\&' after '!', '?', and '.' if they are followed by space,
     tab, or newline characters and don't end a sentence.

   * In filled text lines, use '\&' before '.' and ''' if they are
     preceded by space, so that reflowing the input doesn't turn them
     into control lines.

What Alex terms "semantic newlines" are a venerable practice in
composition of *roff documents, and have been passed down from Brian
Kernighan of Bell Labs and C programming fame.  Slightly less famously,
he rewrote the Unix Version 7 troff program to be device-independent.

So we can safely say that it's a 40-year tradition, at least.  To some,
however, its age may not recommend it. ;-)  Fault-handling in user mode
is certainly arriving none too soon.  Thank you for your work on it.

Regards,
Branden

[1] https://owl.purdue.edu/owl/general_writing/grammar/that_vs_which.html
[2] See what I did there?
[3] https://english.stackexchange.com/questions/264236/can-any-verbs-present-and-past-participles-be-used-as-adjectives

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Axel Rasmussen]

On Mon, Jun 6, 2022 at 12:40 PM Peter Xu <peterx@redhat.com> wrote:
>
> On Mon, Jun 06, 2022 at 08:52:25PM +0200, Alejandro Colomar wrote:
> > Hi Peter,
>
> Hi, Alex,
>
> >
> > On 6/3/22 19:37, Peter Xu wrote:
> > > v2:
> > > - Use semantic newlines always in patch 1 [Alex]
> > > - Fix s/.BR/.B/ in patch 2 [Alex]
> > > - Rebased to http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git
> > >
> > > Add the two missing pieces till latest 5.19-rc1: the UFFD_USER_MODE_ONLY
> > > flag, and also the recent wr-protect support on shmem and hugetlbfs.
> > >
> > > Please review, thanks.
> > >
> > > Peter Xu (2):
> > >    userfaultfd.2: Add section for UFFD_USER_MODE_ONLY
> > >    userfaultfd.2: Update on write-protection support
> > >
> > >   man2/userfaultfd.2 | 23 ++++++++++++++++++-----
> > >   1 file changed, 18 insertions(+), 5 deletions(-)
> > >
> >
> >
> > I think the patch below would improve a little bit the wording (and
> > newlines).  I still have a bit of trouble understanding "When a
> > kernel-originated fault was triggered on the registered range with this
> > userfaultfd".  Did you maybe mean "range registered" instead of "registered
> > range"?
>
> Since I'm not a native speaker I don't immediately see the difference
> between the two..  What I wanted to express is all the memory ranges that
> we registered with UFFDIO_REGISTER ioctl, and further it was trying to
> describe what the kernel will do when there're any page faults that were
> triggered upon those ranges from a kernel context.
>
> It's always challenging for me to grasp how you prefer the newlines are
> made, but anyway below changes looks good to me.  Thanks,

I think "range registered" Alejandro suggested is a bit more natural,
just because that's the way you'd say it if we were slightly more
verbose:

"When a kernel-originated fault was triggered on the range [that was
previously] registered with this userfaultfd, ..."

Of course leaving out "that was previously" is fine, but I think the
ordering "range registered" remains more natural.

Another alternative I find equally natural which keeps the existing
ordering might be something like:

"... on the userfaultfd-registered range ..."

>
> >
> > Thanks,
> >
> > Alex
> >
> >
> > diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
> > index 9b5ec0358..0c0a4f687 100644
> > --- a/man2/userfaultfd.2
> > +++ b/man2/userfaultfd.2
> > @@ -62,11 +62,11 @@ flag in
> >  .BR open (2).
> >  .TP
> >  .B UFFD_USER_MODE_ONLY
> > -This is an userfaultfd specific flag that was introduced since Linux 5.11.
> > -When set, the userfaultfd object will only be able to handle page faults
> > -originated from the userspace on the registered regions.
> > -When a kernel originated fault was triggered on the registered range with
> > -this userfaultfd, a
> > +This is an userfaultfd-specific flag that was introduced in Linux 5.11.
> > +When set, the userfaultfd object will only be able to handle
> > +page faults originated from the user space on the registered regions.
> > +When a kernel-originated fault was triggered
> > +on the registered range with this userfaultfd, a
> >  .B SIGBUS
> >  signal will be delivered.
> >  .PP
> > @@ -277,8 +277,9 @@ ioctl against the feature bit
> >  .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
> >  before using this feature.
> >  .PP
> > -Since Linux 5.19, the write-protection mode was also supported on shmem and
> > hugetlbfs
> > -memory types.
> > +Since Linux 5.19,
> > +the write-protection mode was also supported on
> > +shmem and hugetlbfs memory types.
> >  It can be detected with the feature bit
> >  .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
> >  .PP
> >
> >
> > --
> > Alejandro Colomar
> > <http://www.alejandro-colomar.es/>
>
>
>
>
> --
> Peter Xu
>

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3347 bytes --]

Hi, Peter and Branden!

On 6/6/22 23:33, G. Branden Robinson wrote:
> [CC list trimmed since this is solely about English and *roff]
> 
> At 2022-06-06T15:40:08-0400, Peter Xu wrote:
>>> I think the patch below would improve a little bit the wording (and
>>> newlines).  I still have a bit of trouble understanding "When a
>>> kernel-originated fault was triggered on the registered range with
>>> this userfaultfd".  Did you maybe mean "range registered" instead of
>>> "registered range"?
>>
>> Since I'm not a native speaker I don't immediately see the difference
>> between the two.
> 
> Short answer: I think your existing wording is acceptable.
> 
> As a native speaker (but not a trained linguist) I think I can speak to
> the subject: both forms are equivalent in this application.  In standard
> English, adjectives usually precede the nouns they modify.
[...]

But in this case,

"When a kernel-originated fault was triggered on the registered range 
with this userfaultfd"

"registered" is not acting as an adjective, but as a verb.  Maybe Peter 
was confused by that; I didn't consider that option.  I'm actually 
surprised that you were, Branden, but I guess it was just a neuron going 
crazy, as mine with \c the other day :p


> 
>> It's always challenging for me to grasp how you prefer the newlines
>> are made, but anyway below changes looks good to me.

Sorry, Peter.  I'll take that into account, and try to help as much as I 
can.  Apart from what Branden has already added to this thread, the 
following man-pages commit has some more details, quoted from B. W. 
Kernighan, and may help you understand what I want:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?h=alx/main&id=6ff6f43d68164f99a8c3fb66f4525d145571310c>

I have a long-standing discussion with Branden regarding how much should 
I push for semantic newlines.  The origin of using semantic newlines is 
only to simplify diffs (and it does that very well), but for some 
reason, my brain reads the text better too when organized that way, as 
opposed to normal prose-like text flow.  There I seem to disagree with 
Branden, who prefers to read my emails as if they were a book.  Maybe I 
need semantic newlines to understand the text better, because there are 
a lot of technical terms that I don't know, and having less load on my 
brain (because I don't need to calculate phrase boundaries) makes it 
easier; it's especially useful when text is under development, where it 
may have mistakes that make it even more difficult to read.

But, just do what you can.  I'll try to do the rest, and ask you if I 
don't understand something.

> 
> So we can safely say that it's a 40-year tradition, at least.  To some,
> however, its age may not recommend it. ;-)

;-)

> Fault-handling in user mode
> is certainly arriving none too soon.  Thank you for your work on it.

Yup, thanks for your work Peter!

> 
> Regards,
> Branden
> 
> [1] https://owl.purdue.edu/owl/general_writing/grammar/that_vs_which.html
> [2] See what I did there?

Yes :)

> [3] https://english.stackexchange.com/questions/264236/can-any-verbs-present-and-past-participles-be-used-as-adjectives

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Jakub Wilk]

* G. Branden Robinson <g.branden.robinson@gmail.com>, 2022-06-06, 16:33:
>At 2022-06-06T15:40:08-0400, Peter Xu wrote:
>>>I think the patch below would improve a little bit the wording (and 
>>>newlines).  I still have a bit of trouble understanding "When a 
>>>kernel-originated fault was triggered on the registered range with 
>>>this userfaultfd".  Did you maybe mean "range registered" instead of 
>>>"registered range"?
>>
>>Since I'm not a native speaker I don't immediately see the difference 
>>between the two.
>
>Short answer: I think your existing wording is acceptable.

I think you missed the context. You get a different parse tree when you 
swap the words:

   ...triggered (on the registered range) (with this userfaultfd).

vs

   ...triggered (on the range (registered with this userfaultfd)).

-- 
Jakub Wilk

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1223 bytes --]

Hi Jakub!

On 6/7/22 11:17, Jakub Wilk wrote:
> * G. Branden Robinson <g.branden.robinson@gmail.com>, 2022-06-06, 16:33:
>> At 2022-06-06T15:40:08-0400, Peter Xu wrote:
>>>> I think the patch below would improve a little bit the wording (and 
>>>> newlines).  I still have a bit of trouble understanding "When a 
>>>> kernel-originated fault was triggered on the registered range with 
>>>> this userfaultfd".  Did you maybe mean "range registered" instead of 
>>>> "registered range"?
>>>
>>> Since I'm not a native speaker I don't immediately see the difference 
>>> between the two.
>>
>> Short answer: I think your existing wording is acceptable.
> 
> I think you missed the context. You get a different parse tree when you 
> swap the words:
> 
>    ...triggered (on the registered range) (with this userfaultfd).
> 
> vs
> 
>    ...triggered (on the range (registered with this userfaultfd)).
> 

Thanks, that's a very nice way to show it!  It may help Peter too. 
Basically, the places where you can parenthesize sentences as if they 
were mathematical expressions is where lines breaks should go :)


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Peter Xu]

Hi, Alex & all,

On Tue, Jun 07, 2022 at 11:08:42AM +0200, Alejandro Colomar wrote:
> Hi, Peter and Branden!
> 
> On 6/6/22 23:33, G. Branden Robinson wrote:
> > [CC list trimmed since this is solely about English and *roff]
> > 
> > At 2022-06-06T15:40:08-0400, Peter Xu wrote:
> > > > I think the patch below would improve a little bit the wording (and
> > > > newlines).  I still have a bit of trouble understanding "When a
> > > > kernel-originated fault was triggered on the registered range with
> > > > this userfaultfd".  Did you maybe mean "range registered" instead of
> > > > "registered range"?
> > > 
> > > Since I'm not a native speaker I don't immediately see the difference
> > > between the two.
> > 
> > Short answer: I think your existing wording is acceptable.
> > 
> > As a native speaker (but not a trained linguist) I think I can speak to
> > the subject: both forms are equivalent in this application.  In standard
> > English, adjectives usually precede the nouns they modify.
> [...]
> 
> But in this case,
> 
> "When a kernel-originated fault was triggered on the registered range with
> this userfaultfd"
> 
> "registered" is not acting as an adjective, but as a verb.

I wanted to use it as an adjective, but after you questioned this one I'm
not sure any more on my English school knowledges. :)

> Maybe Peter was confused by that; I didn't consider that option.  I'm
> actually surprised that you were, Branden, but I guess it was just a
> neuron going crazy, as mine with \c the other day :p
> 
> 
> > 
> > > It's always challenging for me to grasp how you prefer the newlines
> > > are made, but anyway below changes looks good to me.
> 
> Sorry, Peter.  I'll take that into account, and try to help as much as I
> can.

You're greatly helpful start from the beginning, and I just hope you can
still bare with me. :-)

> Apart from what Branden has already added to this thread, the
> following man-pages commit has some more details, quoted from B. W.
> Kernighan, and may help you understand what I want:
> 
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?h=alx/main&id=6ff6f43d68164f99a8c3fb66f4525d145571310c>
> 
> I have a long-standing discussion with Branden regarding how much should I
> push for semantic newlines.  The origin of using semantic newlines is only
> to simplify diffs (and it does that very well), but for some reason, my
> brain reads the text better too when organized that way, as opposed to
> normal prose-like text flow.  There I seem to disagree with Branden, who
> prefers to read my emails as if they were a book.  Maybe I need semantic
> newlines to understand the text better, because there are a lot of technical
> terms that I don't know, and having less load on my brain (because I don't
> need to calculate phrase boundaries) makes it easier; it's especially useful
> when text is under development, where it may have mistakes that make it even
> more difficult to read.
> 
> But, just do what you can.  I'll try to do the rest, and ask you if I don't
> understand something.

Yes IMHO that'll be the best way to go with the rest of the community too,
because afaict not all community developers will be able to quickly get
used to the rules on man page repository - you're working with a bunch of
people using in most cases C compilers which has a much looser syntax!

It'll be great if you could help tune the bits after the content being
contributed by others as long as the modified version has the correct
meanings.  Not sure whether it'll have scaling problem but hopefully the
man pages won't be updated drastically so it won't overload you so easily.

Thanks again for all the helps,

-- 
Peter Xu

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4736 bytes --]

Hi Peter!

On 6/7/22 16:29, Peter Xu wrote:
>> "registered" is not acting as an adjective, but as a verb.
> 
> I wanted to use it as an adjective, but after you questioned this one I'm
> not sure any more on my English school knowledges. :)
> 
>> Maybe Peter was confused by that; I didn't consider that option.  I'm
>> actually surprised that you were, Branden, but I guess it was just a
>> neuron going crazy, as mine with \c the other day :p
>>
>>
>>>
>>>> It's always challenging for me to grasp how you prefer the newlines
>>>> are made, but anyway below changes looks good to me.
>>
>> Sorry, Peter.  I'll take that into account, and try to help as much as I
>> can.
> 
> You're greatly helpful start from the beginning, and I just hope you can
> still bare with me. :-)

Sure! :)


> 
>> Apart from what Branden has already added to this thread, the
>> following man-pages commit has some more details, quoted from B. W.
>> Kernighan, and may help you understand what I want:
>>
>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?h=alx/main&id=6ff6f43d68164f99a8c3fb66f4525d145571310c>
>>
>> I have a long-standing discussion with Branden regarding how much should I
>> push for semantic newlines.  The origin of using semantic newlines is only
>> to simplify diffs (and it does that very well), but for some reason, my
>> brain reads the text better too when organized that way, as opposed to
>> normal prose-like text flow.  There I seem to disagree with Branden, who
>> prefers to read my emails as if they were a book.  Maybe I need semantic
>> newlines to understand the text better, because there are a lot of technical
>> terms that I don't know, and having less load on my brain (because I don't
>> need to calculate phrase boundaries) makes it easier; it's especially useful
>> when text is under development, where it may have mistakes that make it even
>> more difficult to read.
>>
>> But, just do what you can.  I'll try to do the rest, and ask you if I don't
>> understand something.
> 
> Yes IMHO that'll be the best way to go with the rest of the community too,
> because afaict not all community developers will be able to quickly get
> used to the rules on man page repository - you're working with a bunch of
> people using in most cases C compilers which has a much looser syntax!
> 
> It'll be great if you could help tune the bits after the content being
> contributed by others as long as the modified version has the correct
> meanings.  Not sure whether it'll have scaling problem but hopefully the
> man pages won't be updated drastically so it won't overload you so easily.
 >
 > Thanks again for all the helps,
 >

Yes, if I just fix all of them, programmers never learn how to write 
proper manual pages, and I'll have to fix them forever (and sometimes, 
when I recevie huge patches, such as new pages, it doesn't scale very 
well).  But I can't put too much pressure either.  It's difficult, but I 
try to adapt to each of you.


In this case, I applied both of your patches, and on top of them, I 
applied the following one.

Cheers!

Alex

---

     userfaultfd.2: Minor tweaks to Peter's patches

     Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
     Cc: Peter Xu <peterx@redhat.com>

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 9b5ec0358..0c0a4f687 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -62,11 +62,11 @@ flag in
  .BR open (2).
  .TP
  .B UFFD_USER_MODE_ONLY
-This is an userfaultfd specific flag that was introduced since Linux 5.11.
-When set, the userfaultfd object will only be able to handle page faults
-originated from the userspace on the registered regions.
-When a kernel originated fault was triggered on the registered range with
-this userfaultfd, a
+This is an userfaultfd-specific flag that was introduced in Linux 5.11.
+When set, the userfaultfd object will only be able to handle
+page faults originated from the user space on the registered regions.
+When a kernel-originated fault was triggered
+on the registered range with this userfaultfd, a
  .B SIGBUS
  signal will be delivered.
  .PP
@@ -277,8 +277,9 @@ ioctl against the feature bit
  .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
  before using this feature.
  .PP
-Since Linux 5.19, the write-protection mode was also supported on shmem 
and hugetlbfs
-memory types.
+Since Linux 5.19,
+the write-protection mode was also supported on
+shmem and hugetlbfs memory types.
  It can be detected with the feature bit
  .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
  .PP


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Peter Xu]

On Wed, Jun 15, 2022 at 03:39:11PM +0200, Alejandro Colomar wrote:
> Hi Peter!
> 
> On 6/7/22 16:29, Peter Xu wrote:
> > > "registered" is not acting as an adjective, but as a verb.
> > 
> > I wanted to use it as an adjective, but after you questioned this one I'm
> > not sure any more on my English school knowledges. :)
> > 
> > > Maybe Peter was confused by that; I didn't consider that option.  I'm
> > > actually surprised that you were, Branden, but I guess it was just a
> > > neuron going crazy, as mine with \c the other day :p
> > > 
> > > 
> > > > 
> > > > > It's always challenging for me to grasp how you prefer the newlines
> > > > > are made, but anyway below changes looks good to me.
> > > 
> > > Sorry, Peter.  I'll take that into account, and try to help as much as I
> > > can.
> > 
> > You're greatly helpful start from the beginning, and I just hope you can
> > still bare with me. :-)
> 
> Sure! :)
> 
> 
> > 
> > > Apart from what Branden has already added to this thread, the
> > > following man-pages commit has some more details, quoted from B. W.
> > > Kernighan, and may help you understand what I want:
> > > 
> > > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?h=alx/main&id=6ff6f43d68164f99a8c3fb66f4525d145571310c>
> > > 
> > > I have a long-standing discussion with Branden regarding how much should I
> > > push for semantic newlines.  The origin of using semantic newlines is only
> > > to simplify diffs (and it does that very well), but for some reason, my
> > > brain reads the text better too when organized that way, as opposed to
> > > normal prose-like text flow.  There I seem to disagree with Branden, who
> > > prefers to read my emails as if they were a book.  Maybe I need semantic
> > > newlines to understand the text better, because there are a lot of technical
> > > terms that I don't know, and having less load on my brain (because I don't
> > > need to calculate phrase boundaries) makes it easier; it's especially useful
> > > when text is under development, where it may have mistakes that make it even
> > > more difficult to read.
> > > 
> > > But, just do what you can.  I'll try to do the rest, and ask you if I don't
> > > understand something.
> > 
> > Yes IMHO that'll be the best way to go with the rest of the community too,
> > because afaict not all community developers will be able to quickly get
> > used to the rules on man page repository - you're working with a bunch of
> > people using in most cases C compilers which has a much looser syntax!
> > 
> > It'll be great if you could help tune the bits after the content being
> > contributed by others as long as the modified version has the correct
> > meanings.  Not sure whether it'll have scaling problem but hopefully the
> > man pages won't be updated drastically so it won't overload you so easily.
> >
> > Thanks again for all the helps,
> >
> 
> Yes, if I just fix all of them, programmers never learn how to write proper
> manual pages, and I'll have to fix them forever (and sometimes, when I
> recevie huge patches, such as new pages, it doesn't scale very well).  But I
> can't put too much pressure either.  It's difficult, but I try to adapt to
> each of you.

Thanks. I was imaging man page updates were rare at least for now, but I
could be completely wrong. Sorry to have made it a feel like adding those
burdens to maintainers only and treating it as deserved.  That's not for
granted for sure and I'd personally cherish a lot on all man page works -
it's really in most cases the only place to connect user and kernel
developers.. where my role stand in between the two.

I can also understand the challenges here as being the man page
maintainers.  It's not like other projects, the contributors are more
scattered, many coming from kernel feature contributors but not man page
developers constantly working on the project.

> 
> In this case, I applied both of your patches, and on top of them, I applied
> the following one.
> 
> Cheers!

Thanks again!

-- 
Peter Xu