userfaultfd.2: Update to latest
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
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
@@ -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
PATCH v2 2/2 userfaultfd.2: Update on write-protection support
In reply to Peter XuThe 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
@@ -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
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.gitAdd the two missing pieces till latest 5.19-rc1: the
UFFD_USER_MODE_ONLYflag, and also the recent wr-protect support on shmem and hugetlbfs.
Quoted 9 lines
Please review, thanks.
Peter Xu (2):
userfaultfd.2: Add section forUFFD_USER_MODE_ONLYuserfaultfd.2: Update on write-protection supportman2/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
@@ -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/>
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.gitAdd the two missing pieces till latest 5.19-rc1: the
UFFD_USER_MODE_ONLYflag, and also the recent wr-protect support on shmem and hugetlbfs.Quoted 9 lines
Please review, thanks.
Peter Xu (2):
userfaultfd.2: Add section forUFFD_USER_MODE_ONLYuserfaultfd.2: Update on write-protection supportman2/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@@ -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 andhugetlbfs
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 . .PPSignature · 3 lines
-- Alejandro Colomar <http://www.alejandro-colomar.es/>
Signature · 1 line
Peter Xu
[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
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:
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
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
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:
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
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:
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
@@ -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/>
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:
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
* 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
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/>
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.gitAdd the two missing pieces till latest 5.19-rc1: the
UFFD_USER_MODE_ONLYflag, and also the recent wr-protect support on shmem and hugetlbfs.Quoted 9 lines
Please review, thanks.
Peter Xu (2):
userfaultfd.2: Add section forUFFD_USER_MODE_ONLYuserfaultfd.2: Update on write-protection supportman2/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_REGISTERioctl, 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@@ -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 andhugetlbfs
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