[PATCH v2 0/2] UFFDIO_API.2const: Two man page updates

[PATCH v2 0/2] UFFDIO_API.2const: Two man page updates

[Peter Xu]

v2:
- Added tags
- One fix on semantic newlines [Alejandro]
- Replace "0" with "zero" [Alejandro]
- Added Fixes for both commits [Alejandro]
- Renamed the subject of patch 2 to contain UFFD_FEATURE_MOVE [Alejandro]

The first patch updates the page on two-steps handshake, removing the
misleading paragraph and replacing it with a paragraph explaining the
correct way to probe the userfaultfd features.

The second patch is a small touch up on the same man page that misses the
newly added UFFDIO_MOVE feature.

Thanks,

Peter Xu (2):
  UFFDIO_API.2const: Update userfaultfd handshake and feature probe
  UFFDIO_API.2const: Add an entry for UFFDIO_FEATURE_MOVE

 man/man2const/UFFDIO_API.2const | 50 ++++++++++++++++++++-------------
 1 file changed, 31 insertions(+), 19 deletions(-)

-- 
2.49.0

[PATCH v2 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe

[Peter Xu]

There's a confusing paragraph in the man page on two-steps handshake for
userfaultfd UFFDIO_API ioctl.  In reality, after a successful UFFDIO_API
ioctl, the userfaultfd will be locked up on the features and any further
UFFDIO_API on top of an initialized userfaultfd would fail.

Modify the UFFDIO_API(2const) man page to reflect the reality.  Instead,
add a paragraph explaining the right way to probe userfaultfd features.
Add that only after the "Before Linux 4.11" paragraph, as the old kernel
doesn't support any feature anyway.

Fixes: a252b3345 ("ioctl_userfaultfd.2: Describe two-step feature handshake")
Reviewed-by: Kyle Huey <khuey@kylehuey.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
---
 man/man2const/UFFDIO_API.2const | 44 +++++++++++++++++++--------------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
index 54b34a1bc..aca27dc5c 100644
--- a/man/man2const/UFFDIO_API.2const
+++ b/man/man2const/UFFDIO_API.2const
@@ -42,25 +42,6 @@ fields to bit masks representing all the available features and the generic
 .BR ioctl (2)
 operations available.
 .P
-Since Linux 4.11,
-applications should use the
-.I features
-field to perform a two-step handshake.
-First,
-.B UFFDIO_API
-is called with the
-.I features
-field set to zero.
-The kernel responds by setting all supported feature bits.
-.P
-Applications which do not require any specific features
-can begin using the userfaultfd immediately.
-Applications which do need specific features
-should call
-.B UFFDIO_API
-again with a subset of the reported feature bits set
-to enable those features.
-.P
 Before Linux 4.11, the
 .I features
 field must be initialized to zero before the call to
@@ -70,6 +51,31 @@ and zero (i.e., no feature bits) is placed in the
 field by the kernel upon return from
 .BR ioctl (2).
 .P
+Since Linux 4.11,
+userfaultfd supports features that need to be enabled explicitly.
+To enable any of the features,
+one needs to set the corresponding feature bits in
+.I features
+when issuing the
+.B UFFDIO_API
+ioctl.
+.P
+For historical reasons,
+a temporary userfaultfd is needed to probe
+what userfaultfd features the kernel supports.
+The application needs to create a temporary userfaultfd,
+issue an
+.B UFFDIO_API
+ioctl with
+.I features
+set to zero.
+After the
+.B UFFDIO_API
+ioctl returns successfully,
+.I features
+should contain all the userfaultfd features that the kernel supports.
+The temporary userfaultfd can be safely closed after the probe.
+.P
 If the application sets unsupported feature bits,
 the kernel will zero out the returned
 .I uffdio_api
-- 
2.49.0

Re: [PATCH v2 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe

[Alejandro Colomar]

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

Hi Peter,

On Wed, May 14, 2025 at 01:26:29PM -0400, Peter Xu wrote:
> There's a confusing paragraph in the man page on two-steps handshake for
> userfaultfd UFFDIO_API ioctl.  In reality, after a successful UFFDIO_API
> ioctl, the userfaultfd will be locked up on the features and any further
> UFFDIO_API on top of an initialized userfaultfd would fail.
> 
> Modify the UFFDIO_API(2const) man page to reflect the reality.  Instead,
> add a paragraph explaining the right way to probe userfaultfd features.
> Add that only after the "Before Linux 4.11" paragraph, as the old kernel
> doesn't support any feature anyway.
> 
> Fixes: a252b3345 ("ioctl_userfaultfd.2: Describe two-step feature handshake")
> Reviewed-by: Kyle Huey <khuey@kylehuey.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>

Thanks!  I've applied the patch.


Have a lovely day!
Alex

> ---
>  man/man2const/UFFDIO_API.2const | 44 +++++++++++++++++++--------------
>  1 file changed, 25 insertions(+), 19 deletions(-)
> 
> diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
> index 54b34a1bc..aca27dc5c 100644
> --- a/man/man2const/UFFDIO_API.2const
> +++ b/man/man2const/UFFDIO_API.2const
> @@ -42,25 +42,6 @@ fields to bit masks representing all the available features and the generic
>  .BR ioctl (2)
>  operations available.
>  .P
> -Since Linux 4.11,
> -applications should use the
> -.I features
> -field to perform a two-step handshake.
> -First,
> -.B UFFDIO_API
> -is called with the
> -.I features
> -field set to zero.
> -The kernel responds by setting all supported feature bits.
> -.P
> -Applications which do not require any specific features
> -can begin using the userfaultfd immediately.
> -Applications which do need specific features
> -should call
> -.B UFFDIO_API
> -again with a subset of the reported feature bits set
> -to enable those features.
> -.P
>  Before Linux 4.11, the
>  .I features
>  field must be initialized to zero before the call to
> @@ -70,6 +51,31 @@ and zero (i.e., no feature bits) is placed in the
>  field by the kernel upon return from
>  .BR ioctl (2).
>  .P
> +Since Linux 4.11,
> +userfaultfd supports features that need to be enabled explicitly.
> +To enable any of the features,
> +one needs to set the corresponding feature bits in
> +.I features
> +when issuing the
> +.B UFFDIO_API
> +ioctl.
> +.P
> +For historical reasons,
> +a temporary userfaultfd is needed to probe
> +what userfaultfd features the kernel supports.
> +The application needs to create a temporary userfaultfd,
> +issue an
> +.B UFFDIO_API
> +ioctl with
> +.I features
> +set to zero.
> +After the
> +.B UFFDIO_API
> +ioctl returns successfully,
> +.I features
> +should contain all the userfaultfd features that the kernel supports.
> +The temporary userfaultfd can be safely closed after the probe.
> +.P
>  If the application sets unsupported feature bits,
>  the kernel will zero out the returned
>  .I uffdio_api
> -- 
> 2.49.0
> 

-- 
<https://www.alejandro-colomar.es/>

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

[PATCH v2 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_FEATURE_MOVE

[Peter Xu]

Add the entry for UFFDIO_MOVE ioctl in UFFDIO_API man page.

Fixes: d7dec35a3b19 ("man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")
Reviewed-by: Suren Baghdasaryan <surenb@google.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
---
 man/man2const/UFFDIO_API.2const | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
index aca27dc5c..682df4316 100644
--- a/man/man2const/UFFDIO_API.2const
+++ b/man/man2const/UFFDIO_API.2const
@@ -205,6 +205,12 @@ ioctl.
 If this feature bit is set,
 the write protection faults would be asynchronously resolved
 by the kernel.
+.TP
+.BR UFFD_FEATURE_MOVE " (since Linux 6.8)"
+If this feature bit is set,
+the kernel supports resolving faults with the
+.B UFFDIO_MOVE
+ioctl.
 .P
 The returned
 .I argp->ioctls
-- 
2.49.0

Re: [PATCH v2 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_FEATURE_MOVE

[Alejandro Colomar]

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

Hi Peter,

On Wed, May 14, 2025 at 01:26:30PM -0400, Peter Xu wrote:
> Add the entry for UFFDIO_MOVE ioctl in UFFDIO_API man page.
> 
> Fixes: d7dec35a3b19 ("man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")
> Reviewed-by: Suren Baghdasaryan <surenb@google.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>

Thanks!  I've applied the patch.


Cheers,
Alex

> ---
>  man/man2const/UFFDIO_API.2const | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
> index aca27dc5c..682df4316 100644
> --- a/man/man2const/UFFDIO_API.2const
> +++ b/man/man2const/UFFDIO_API.2const
> @@ -205,6 +205,12 @@ ioctl.
>  If this feature bit is set,
>  the write protection faults would be asynchronously resolved
>  by the kernel.
> +.TP
> +.BR UFFD_FEATURE_MOVE " (since Linux 6.8)"
> +If this feature bit is set,
> +the kernel supports resolving faults with the
> +.B UFFDIO_MOVE
> +ioctl.
>  .P
>  The returned
>  .I argp->ioctls
> -- 
> 2.49.0
> 

-- 
<https://www.alejandro-colomar.es/>

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