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

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

[Peter Xu]

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_MOVE

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

-- 
2.49.0

[PATCH 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.

Signed-off-by: Peter Xu <peterx@redhat.com>
---
 man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 19 deletions(-)

diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
index 54b34a1bc..1c554107a 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,30 @@ 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 0. 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 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe

[Kyle Huey]

On Mon, May 12, 2025 at 10:19 AM Peter Xu <peterx@redhat.com> 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.
>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
>  man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++---------------
>  1 file changed, 24 insertions(+), 19 deletions(-)
>
> diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
> index 54b34a1bc..1c554107a 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,30 @@ 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 0. 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
>

lgtm

Reviewed-by: Kyle Huey <khuey@kylehuey.com>

Thanks,

- Kyle

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

[Alejandro Colomar]

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

Hi Peter,

On Mon, May 12, 2025 at 01:19:21PM -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.
> 
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
>  man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++---------------
>  1 file changed, 24 insertions(+), 19 deletions(-)
> 
> diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
> index 54b34a1bc..1c554107a 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,30 @@ 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 0. After the

Please use semantic newlines.  Break the line after the '.'.

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be  started
       on  new  lines,  long  sentences  should  be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and  long
       clauses  should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier  to  see
       the effect of patches, which often operate at the level of indi‐
       vidual sentences, clauses, or phrases.

Also, please say "zero" instead of "0", as was in the old paragraph.
That will allow git-diff(1) --color-moved to detect some movement of
text.

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

Thanks!


Have a lovely day!
Alex

>  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 --]

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

[Peter Xu]

On Wed, May 14, 2025 at 05:59:48PM +0200, Alejandro Colomar wrote:
> > +.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 0. After the
> 
> Please use semantic newlines.  Break the line after the '.'.

This one was overlooked indeed, will fix it.

> 
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
>    Use semantic newlines
>        In the source of a manual page, new sentences should be  started
>        on  new  lines,  long  sentences  should  be split into lines at
>        clause breaks (commas, semicolons, colons, and so on), and  long
>        clauses  should be split at phrase boundaries.  This convention,
>        sometimes known as "semantic newlines", makes it easier  to  see
>        the effect of patches, which often operate at the level of indi‐
>        vidual sentences, clauses, or phrases.
> 
> Also, please say "zero" instead of "0", as was in the old paragraph.
> That will allow git-diff(1) --color-moved to detect some movement of
> text.

This was not part of the old text, but sure, will do.

Thanks,

-- 
Peter Xu

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

[Alejandro Colomar]

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

Hi Peter,

On Wed, May 14, 2025 at 01:21:17PM -0400, Peter Xu wrote:
> On Wed, May 14, 2025 at 05:59:48PM +0200, Alejandro Colomar wrote:
> > > +.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 0. After the
> > 
> > Please use semantic newlines.  Break the line after the '.'.
> 
> This one was overlooked indeed, will fix it.

Thanks!
 
> > 
> > $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
> >    Use semantic newlines
> >        In the source of a manual page, new sentences should be  started
> >        on  new  lines,  long  sentences  should  be split into lines at
> >        clause breaks (commas, semicolons, colons, and so on), and  long
> >        clauses  should be split at phrase boundaries.  This convention,
> >        sometimes known as "semantic newlines", makes it easier  to  see
> >        the effect of patches, which often operate at the level of indi‐
> >        vidual sentences, clauses, or phrases.
> > 
> > Also, please say "zero" instead of "0", as was in the old paragraph.
> > That will allow git-diff(1) --color-moved to detect some movement of
> > text.
> 
> This was not part of the old text, but sure, will do.

I know you've completely rewritten the paragraph, but even then, parts
of the old text remain (maybe because however you write it, some parts
need to be said).

	-.I features
	-field set to zero.

This part is kept in the new text, even if just by chance, and it might
be interesting to see that in git-diff(1) --color-moved.


Have a lovely day!
Alex

> 
> Thanks,
> 
> -- 
> Peter Xu
> 

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

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

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

[Peter Xu]

Add the entry for UFFDIO_MOVE in UFFDIO_API.

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 1c554107a..17ea6f905 100644
--- a/man/man2const/UFFDIO_API.2const
+++ b/man/man2const/UFFDIO_API.2const
@@ -204,6 +204,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 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_MOVE

[Suren Baghdasaryan]

On Mon, May 12, 2025 at 10:19 AM Peter Xu <peterx@redhat.com> wrote:
>
> Add the entry for UFFDIO_MOVE in UFFDIO_API.
>
> Signed-off-by: Peter Xu <peterx@redhat.com>

Reviewed-by: Suren Baghdasaryan <surenb@google.com>

Thanks!


> ---
>  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 1c554107a..17ea6f905 100644
> --- a/man/man2const/UFFDIO_API.2const
> +++ b/man/man2const/UFFDIO_API.2const
> @@ -204,6 +204,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 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_MOVE

[Alejandro Colomar]

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

Hi Peter,

On Mon, May 12, 2025 at 01:19:22PM -0400, Peter Xu wrote:
> Add the entry for UFFDIO_MOVE in UFFDIO_API.
> 
> Signed-off-by: Peter Xu <peterx@redhat.com>

Should we add the following tag?

Fixes: d7dec35a3b19 (2025-05-01; "man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")

Also, I think the subject should mention UFFD_FEATURE_MOVE, or at least
somewhere in the commit message.


Have a lovely day!
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 1c554107a..17ea6f905 100644
> --- a/man/man2const/UFFDIO_API.2const
> +++ b/man/man2const/UFFDIO_API.2const
> @@ -204,6 +204,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 --]

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

[Peter Xu]

On Wed, May 14, 2025 at 05:02:57PM +0200, Alejandro Colomar wrote:
> Hi Peter,
> 
> On Mon, May 12, 2025 at 01:19:22PM -0400, Peter Xu wrote:
> > Add the entry for UFFDIO_MOVE in UFFDIO_API.
> > 
> > Signed-off-by: Peter Xu <peterx@redhat.com>
> 
> Should we add the following tag?
> 
> Fixes: d7dec35a3b19 (2025-05-01; "man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")

Sure.

> 
> Also, I think the subject should mention UFFD_FEATURE_MOVE, or at least
> somewhere in the commit message.

I'll rename the subject to:

  UFFDIO_API.2const: Add an entry for UFFDIO_FEATURE_MOVE

I didn't know we need Fixes for man pages.  I'll also attach a fixes for
the first patch for commit a252b3345 ("ioctl_userfaultfd.2: Describe
two-step feature handshake").

Thanks,

-- 
Peter Xu

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

[Alejandro Colomar]

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

Hi Peter,

On Wed, May 14, 2025 at 01:22:49PM -0400, Peter Xu wrote:
> On Wed, May 14, 2025 at 05:02:57PM +0200, Alejandro Colomar wrote:
> > Hi Peter,
> > 
> > On Mon, May 12, 2025 at 01:19:22PM -0400, Peter Xu wrote:
> > > Add the entry for UFFDIO_MOVE in UFFDIO_API.
> > > 
> > > Signed-off-by: Peter Xu <peterx@redhat.com>
> > 
> > Should we add the following tag?
> > 
> > Fixes: d7dec35a3b19 (2025-05-01; "man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")
> 
> Sure.
> 
> > 
> > Also, I think the subject should mention UFFD_FEATURE_MOVE, or at least
> > somewhere in the commit message.
> 
> I'll rename the subject to:
> 
>   UFFDIO_API.2const: Add an entry for UFFDIO_FEATURE_MOVE
> 
> I didn't know we need Fixes for man pages.

We don't *need* it (as you don't technically need it in any projects),
but it's nice to have.  :)

>  I'll also attach a fixes for
> the first patch for commit a252b3345 ("ioctl_userfaultfd.2: Describe
> two-step feature handshake").

Thanks!


Cheers,
Alex

> 
> Thanks,
> 
> -- 
> Peter Xu
> 

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

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