Skip to contentSkip to conversation

userfaultfd.2: Update to latest

PATCH In review Peter Xu 5 participants 13 messages Jun 3, 2022 – Jun 15, 2022

Subsystems (2)
lore
Share & tools
lore

Peter Xu

author
#0 lore raw

v2 cover userfaultfd.2: Update to latest

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(-)
Signature · 1 line
2.32.0
author
#1 lore raw

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

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

---
 man2/userfaultfd.2 | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)
man2/userfaultfd.2 +12 -2
index 93dca009f..6b9412aaf 100644
@@ -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
Signature · 1 line
2.32.0
author
#2 lore raw

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

In reply to Peter Xu

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

---
 man2/userfaultfd.2 | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
man2/userfaultfd.2 +6 -3
index 6b9412aaf..9b5ec0358 100644
@@ -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,
Signature · 1 line
2.32.0
#3 lore raw
In reply to Peter Xu

Hi Peter,

Quoted 8 lines · 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.

Quoted 9 lines

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

man2/userfaultfd.2 +8 -7
index 9b5ec0358..0c0a4f687 100644
@@ -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
Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
author
#4 lore raw
Quoted 1 line · Alejandro Colomar

Hi Peter,

Hi, Alex,

Quoted 21 lines · Peter Xu
Quoted 8 lines

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.

Quoted 9 lines

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(-)
Quoted 5 lines

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,

Quoted 45 lines

Thanks,

Alex

man2/userfaultfd.2 +5 -6
index 9b5ec0358..0c0a4f687 100644
@@ -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

man2/userfaultfd.2 +3 -1
-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
Signature · 3 lines
-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>
Signature · 1 line
Peter Xu
#5 lore raw

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

Quoted 8 lines · Peter Xu
Quoted 5 lines

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]

Quoted 2 lines

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

#6 lore raw

Hi, Peter and Branden!

Quoted 9 lines · G. Branden Robinson

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

Quoted 6 lines · Peter Xu
Quoted 5 lines

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"?

Quoted 8 lines
Quoted 2 lines

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

Quoted 3 lines
Quoted 3 lines

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.

Quoted 3 lines

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

;-)

Quoted 2 lines

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

Yup, thanks for your work Peter!

Quoted 6 lines

Regards,
Branden

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

Yes :)

Quoted 1 line

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

Cheers,

Alex

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
author
#7 lore raw

Hi, Alex & all,

Quoted 20 lines · Alejandro Colomar

Hi, Peter and Branden!

Quoted 9 lines · G. Branden Robinson

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

Quoted 6 lines · Peter Xu
Quoted 5 lines

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"?

Quoted 8 lines
Quoted 2 lines

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.

Quoted 8 lines

[...]

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. :)

Quoted 11 lines

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

Quoted 3 lines
Quoted 3 lines

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. :-)

Quoted 18 lines

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.

Quoted 2 lines

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,

Signature · 1 line
Peter Xu
#8 lore raw

Hi Peter!

Quoted 11 lines · Peter Xu
Quoted 1 line

"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. :)

Quoted 6 lines

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

Quoted 1 line
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
Quoted 2 lines

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! :)

Quoted 27 lines
Quoted 19 lines

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.

Quoted 2 lines

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!

Quoted 7 lines

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

man2/userfaultfd.2 +8 -7
index 9b5ec0358..0c0a4f687 100644
@@ -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
Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
author
#9 lore raw
Quoted 58 lines · Alejandro Colomar

Hi Peter!

Quoted 11 lines · Peter Xu
Quoted 1 line

"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. :)

Quoted 6 lines

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

Quoted 1 line
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
Quoted 2 lines

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! :)

Quoted 32 lines
Quoted 19 lines

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.

Quoted 2 lines

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.

Quoted 8 lines
Quoted 2 lines

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.

Quoted 5 lines

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

Cheers!

Thanks again!

Signature · 1 line
Peter Xu
#10 lore raw
In reply to G. Branden Robinson

* G. Branden Robinson <[email protected]>, 2022-06-06, 16:33:

Quoted 6 lines
Quoted 3 lines · Peter Xu
Quoted 1 line

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)).

Signature · 1 line
Jakub Wilk
#11 lore raw

Hi Jakub!

Quoted 8 lines · Jakub Wilk

* G. Branden Robinson <[email protected]>, 2022-06-06, 16:33:

Quoted 6 lines
Quoted 3 lines · Peter Xu
Quoted 1 line

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.

Quoted 8 lines

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

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
#12 lore raw
In reply to Peter Xu
Quoted 33 lines · Peter Xu
Quoted 1 line · Alejandro Colomar

Hi Peter,

Hi, Alex,

Quoted 21 lines · Peter Xu
Quoted 8 lines

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.

Quoted 9 lines

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(-)
Quoted 5 lines

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"?

Quoted 8 lines

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 ..."

Quoted 53 lines
Quoted 44 lines

Thanks,

Alex

man2/userfaultfd.2 +5 -6
index 9b5ec0358..0c0a4f687 100644
@@ -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

man2/userfaultfd.2 +3 -2
-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
 
 
--
Quoted 2 lines

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

--
Peter Xu