v2 changes:
- Fix wordings as suggested [MikeR]
- convert ".BR" to ".B" where proper for the patchset [Alex]
- rearrange a few lines in the last two patches where they got messed up
- document more things, e.g. UFFDIO_COPY_MODE_WP; and also on how to resolve a
wr-protect page fault.
There're two features missing in current manpage, namely:
(1) Userfaultfd Thread-ID feature
(2) Userfaultfd write protect mode
There's also a 3rd one which was just contributed from Axel - Axel, I think it
would be great if you can add that part too, probably after the whole
hugetlbfs/shmem minor mode reaches the linux master branch.
Please review, thanks.
Peter Xu (4):
userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
userfaultfd.2: Add write-protect mode
ioctl_userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
ioctl_userfaultfd.2: Add write-protect mode docs
man2/ioctl_userfaultfd.2 | 81 ++++++++++++++++++++++++++--
man2/userfaultfd.2 | 111 ++++++++++++++++++++++++++++++++++++++-
2 files changed, 187 insertions(+), 5 deletions(-)
--
2.26.2
UFFD_FEATURE_THREAD_ID is supported in Linux 4.14.
Signed-off-by: Peter Xu <[email protected]>
---
man2/ioctl_userfaultfd.2 | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index 47ae5f473..b58983fe7 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -208,6 +208,11 @@ signal will be sent to the faulting process.
Applications using this
feature will not require the use of a userfaultfd monitor for processing
memory accesses to the regions registered with userfaultfd.
+.TP
+.BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)"
+If this feature bit is set,
+.I uffd_msg.pagefault.feat.ptid
+Will be set to the faulted thread ID for each page fault message.
.PP
The returned
.I ioctls
--
2.26.2
Userfaultfd write-protect mode is supported starting from Linux 5.7.
Signed-off-by: Peter Xu <[email protected]>
---
man2/ioctl_userfaultfd.2 | 76 ++++++++++++++++++++++++++++++++++++++--
1 file changed, 73 insertions(+), 3 deletions(-)
diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index b58983fe7..7497e63c4 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -234,6 +234,11 @@ operation is supported.
The
.B UFFDIO_UNREGISTER
operation is supported.
+.TP
+.B 1 << _UFFDIO_WRITEPROTECT
+The
+.B UFFDIO_WRITEPROTECT
+operation is supported.
.PP
This
.BR ioctl (2)
@@ -322,9 +327,6 @@ Track page faults on missing pages.
.B UFFDIO_REGISTER_MODE_WP
Track page faults on write-protected pages.
.PP
-Currently, the only supported mode is
-.BR UFFDIO_REGISTER_MODE_MISSING .
-.PP
If the operation is successful, the kernel modifies the
.I ioctls
bit-mask field to indicate which
@@ -443,6 +445,11 @@ operation:
.TP
.B UFFDIO_COPY_MODE_DONTWAKE
Do not wake up the thread that waits for page-fault resolution
+.TP
+.B UFFDIO_COPY_MODE_WP
+Do not set write permission when copying the page. The next write to the page
+will trigger a write fault. This can be used in conjunction with write-protect
+mode so that there will be another message generated when the page is written again.
.PP
The
.I copy
@@ -654,6 +661,69 @@ field of the
structure was not a multiple of the system page size; or
.I len
was zero; or the specified range was otherwise invalid.
+.SS UFFDIO_WRITEPROTECT
+(Since Linux 5.7) Do write-protect or write-unprotect for an userfaultfd
+registered memory range with mode
+.BR UFFDIO_REGISTER_MODE_WP .
+.PP
+The
+.I argp
+argument is a pointer to a
+.I uffdio_range
+structure as shown below:
+.PP
+.in +4n
+.EX
+struct uffdio_writeprotect {
+ struct uffdio_range range; /* Range to change write permission */
+ __u64 mode; /* Mode to change write permission */
+};
+.EE
+.in
+There're two modes that are supported in this structure:
+.TP
+.B UFFDIO_WRITEPROTECT_MODE_WP
+When this mode bit is set, the ioctl will be a write-protect operation upon the
+memory range specified by
+.IR range .
+Otherwise it'll be a write-unprotect operation upon the specified range.
+.TP
+.B UFFDIO_WRITEPROTECT_MODE_DONTWAKE
+Do not wake up the thread that waits for page-fault resolution after the
+operation. This could only be specified if
+.B UFFDIO_WRITEPROTECT_MODE_WP
+is not specified (in a resolving stage, not protecting stage).
+.PP
+This
+.BR ioctl (2)
+operation returns 0 on success.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+Possible errors include:
+.TP
+.B EINVAL
+The
+.I start
+or the
+.I len
+field of the
+.I ufdio_range
+structure was not a multiple of the system page size; or
+.I len
+was zero; or the specified range was otherwise invalid.
+.TP
+.B EAGAIN
+The process was interrupted and need to retry.
+.TP
+.B ENOENT
+The range specified in
+.I range
+is not valid. E.g., the virtual address does not exist, or not registered with
+userfaultfd write-protect mode.
+.TP
+.B EFAULT
+Encountered a generic fault during processing.
.SH RETURN VALUE
See descriptions of the individual operations, above.
.SH ERRORS
--
2.26.2
On Thu, Mar 4, 2021 at 8:31 AM Peter Xu <[email protected]> wrote:
>
> v2 changes:
> - Fix wordings as suggested [MikeR]
> - convert ".BR" to ".B" where proper for the patchset [Alex]
> - rearrange a few lines in the last two patches where they got messed up
> - document more things, e.g. UFFDIO_COPY_MODE_WP; and also on how to resolve a
> wr-protect page fault.
>
> There're two features missing in current manpage, namely:
>
> (1) Userfaultfd Thread-ID feature
> (2) Userfaultfd write protect mode
>
> There's also a 3rd one which was just contributed from Axel - Axel, I think it
> would be great if you can add that part too, probably after the whole
> hugetlbfs/shmem minor mode reaches the linux master branch.
Ack, this is on my list of "todos". Agree it makes sense to wait until
the code is in Linus' tree, then I'll send a patch for the man pages.
>
> Please review, thanks.
>
> Peter Xu (4):
> userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
> userfaultfd.2: Add write-protect mode
> ioctl_userfaultfd.2: Add UFFD_FEATURE_THREAD_ID docs
> ioctl_userfaultfd.2: Add write-protect mode docs
>
> man2/ioctl_userfaultfd.2 | 81 ++++++++++++++++++++++++++--
> man2/userfaultfd.2 | 111 ++++++++++++++++++++++++++++++++++++++-
> 2 files changed, 187 insertions(+), 5 deletions(-)
>
> --
> 2.26.2
>
>