| Message ID | 20230919190206.388896-6-axelrasmussen@google.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [01/10] userfaultfd.2: briefly mention two-step feature handshake process | expand |
Hi Axel, On Tue, Sep 19, 2023 at 12:02:01PM -0700, Axel Rasmussen wrote: > Fully describe how UFFDIO_API can be used to perform a two-step feature > handshake, and also note the case where this isn't necessary (programs > which don't depend on any extra features). > > This lets us clean up an old FIXME asking for this to be described. > > Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> > --- > man2/ioctl_userfaultfd.2 | 37 +++++++++++++++++++++---------------- > 1 file changed, 21 insertions(+), 16 deletions(-) > > diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 > index 339adf8fe..e91a1dfc8 100644 > --- a/man2/ioctl_userfaultfd.2 > +++ b/man2/ioctl_userfaultfd.2 > @@ -83,7 +83,6 @@ struct uffdio_api { > The > .I api > field denotes the API version requested by the application. > -.PP > The kernel verifies that it can support the requested API version, > and sets the > .I features > @@ -93,6 +92,25 @@ fields to bit masks representing all the available features and the generic > .BR ioctl (2) > operations available. > .PP > +After Linux 4.11, "After" to me means that you're not including 4.11. You probably mean "Since", which would be inclusive? Or do you actually mean since 4.12? In any case, "since" is more commonly used, so I prefer that wording, for consistency. Thanks, Alex > +applications should use the > +.I features > +field to perform a two-step handshake. > +First, > +.BR UFFDIO_API > +is called with the > +.I features > +field set to zero. > +The kernel responsds by setting all supported feature bits. > +.PP > +Applications which do not require any specific features > +can begin using the userfaultfd immediately. > +Applications which do need specific features > +should call > +.BR UFFDIO_API > +again with a subset of the reported feature bits set > +to enable those features. > +.PP > Before Linux 4.11, the > .I features > field must be initialized to zero before the call to > @@ -102,24 +120,11 @@ and zero (i.e., no feature bits) is placed in the > field by the kernel upon return from > .BR ioctl (2). > .PP > -Starting from Linux 4.11, the > -.I features > -field can be used to ask whether particular features are supported > -and explicitly enable userfaultfd features that are disabled by default. > -The kernel always reports all the available features in the > -.I features > -field. > -.PP > -To enable userfaultfd features the application should set > -a bit corresponding to each feature it wants to enable in the > -.I features > -field. > -If the kernel supports all the requested features it will enable them. > -Otherwise it will zero out the returned > +If the application sets unsupported feature bits, > +the kernel will zero out the returned > .I uffdio_api > structure and return > .BR EINVAL . > -.\" FIXME add more details about feature negotiation and enablement > .PP > The following feature bits may be set: > .TP > -- > 2.42.0.459.ge4e396fd5e-goog >
On Tue, Sep 19, 2023 at 12:02:01PM -0700, Axel Rasmussen wrote: > Fully describe how UFFDIO_API can be used to perform a two-step feature > handshake, and also note the case where this isn't necessary (programs > which don't depend on any extra features). > > This lets us clean up an old FIXME asking for this to be described. > > Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> Reviewed-by: Mike Rapoport (IBM) <rppt@kernel.org> > --- > man2/ioctl_userfaultfd.2 | 37 +++++++++++++++++++++---------------- > 1 file changed, 21 insertions(+), 16 deletions(-) > > diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 > index 339adf8fe..e91a1dfc8 100644 > --- a/man2/ioctl_userfaultfd.2 > +++ b/man2/ioctl_userfaultfd.2 > @@ -83,7 +83,6 @@ struct uffdio_api { > The > .I api > field denotes the API version requested by the application. > -.PP > The kernel verifies that it can support the requested API version, > and sets the > .I features > @@ -93,6 +92,25 @@ fields to bit masks representing all the available features and the generic > .BR ioctl (2) > operations available. > .PP > +After Linux 4.11, > +applications should use the > +.I features > +field to perform a two-step handshake. > +First, > +.BR UFFDIO_API > +is called with the > +.I features > +field set to zero. > +The kernel responsds by setting all supported feature bits. > +.PP > +Applications which do not require any specific features > +can begin using the userfaultfd immediately. > +Applications which do need specific features > +should call > +.BR UFFDIO_API > +again with a subset of the reported feature bits set > +to enable those features. > +.PP > Before Linux 4.11, the > .I features > field must be initialized to zero before the call to > @@ -102,24 +120,11 @@ and zero (i.e., no feature bits) is placed in the > field by the kernel upon return from > .BR ioctl (2). > .PP > -Starting from Linux 4.11, the > -.I features > -field can be used to ask whether particular features are supported > -and explicitly enable userfaultfd features that are disabled by default. > -The kernel always reports all the available features in the > -.I features > -field. > -.PP > -To enable userfaultfd features the application should set > -a bit corresponding to each feature it wants to enable in the > -.I features > -field. > -If the kernel supports all the requested features it will enable them. > -Otherwise it will zero out the returned > +If the application sets unsupported feature bits, > +the kernel will zero out the returned > .I uffdio_api > structure and return > .BR EINVAL . > -.\" FIXME add more details about feature negotiation and enablement > .PP > The following feature bits may be set: > .TP > -- > 2.42.0.459.ge4e396fd5e-goog > >
Hi Mike, On Mon, Oct 09, 2023 at 11:42:47AM +0300, Mike Rapoport wrote: > On Tue, Sep 19, 2023 at 12:02:01PM -0700, Axel Rasmussen wrote: > > Fully describe how UFFDIO_API can be used to perform a two-step feature > > handshake, and also note the case where this isn't necessary (programs > > which don't depend on any extra features). > > > > This lets us clean up an old FIXME asking for this to be described. > > > > Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> > > Reviewed-by: Mike Rapoport (IBM) <rppt@kernel.org> Since v2 is unchanged, I've added this tag. Thanks for the review! Cheers, Alex > > > --- > > man2/ioctl_userfaultfd.2 | 37 +++++++++++++++++++++---------------- > > 1 file changed, 21 insertions(+), 16 deletions(-) > > > > diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 > > index 339adf8fe..e91a1dfc8 100644 > > --- a/man2/ioctl_userfaultfd.2 > > +++ b/man2/ioctl_userfaultfd.2 > > @@ -83,7 +83,6 @@ struct uffdio_api { > > The > > .I api > > field denotes the API version requested by the application. > > -.PP > > The kernel verifies that it can support the requested API version, > > and sets the > > .I features > > @@ -93,6 +92,25 @@ fields to bit masks representing all the available features and the generic > > .BR ioctl (2) > > operations available. > > .PP > > +After Linux 4.11, > > +applications should use the > > +.I features > > +field to perform a two-step handshake. > > +First, > > +.BR UFFDIO_API > > +is called with the > > +.I features > > +field set to zero. > > +The kernel responsds by setting all supported feature bits. s/responsds/responds/ amended. > > +.PP > > +Applications which do not require any specific features > > +can begin using the userfaultfd immediately. > > +Applications which do need specific features > > +should call > > +.BR UFFDIO_API > > +again with a subset of the reported feature bits set > > +to enable those features. > > +.PP > > Before Linux 4.11, the > > .I features > > field must be initialized to zero before the call to > > @@ -102,24 +120,11 @@ and zero (i.e., no feature bits) is placed in the > > field by the kernel upon return from > > .BR ioctl (2). > > .PP > > -Starting from Linux 4.11, the > > -.I features > > -field can be used to ask whether particular features are supported > > -and explicitly enable userfaultfd features that are disabled by default. > > -The kernel always reports all the available features in the > > -.I features > > -field. > > -.PP > > -To enable userfaultfd features the application should set > > -a bit corresponding to each feature it wants to enable in the > > -.I features > > -field. > > -If the kernel supports all the requested features it will enable them. > > -Otherwise it will zero out the returned > > +If the application sets unsupported feature bits, > > +the kernel will zero out the returned > > .I uffdio_api > > structure and return > > .BR EINVAL . > > -.\" FIXME add more details about feature negotiation and enablement > > .PP > > The following feature bits may be set: > > .TP > > -- > > 2.42.0.459.ge4e396fd5e-goog > > > > > > -- > Sincerely yours, > Mike.
diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index 339adf8fe..e91a1dfc8 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -83,7 +83,6 @@ struct uffdio_api { The .I api field denotes the API version requested by the application. -.PP The kernel verifies that it can support the requested API version, and sets the .I features @@ -93,6 +92,25 @@ fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. .PP +After Linux 4.11, +applications should use the +.I features +field to perform a two-step handshake. +First, +.BR UFFDIO_API +is called with the +.I features +field set to zero. +The kernel responsds by setting all supported feature bits. +.PP +Applications which do not require any specific features +can begin using the userfaultfd immediately. +Applications which do need specific features +should call +.BR UFFDIO_API +again with a subset of the reported feature bits set +to enable those features. +.PP Before Linux 4.11, the .I features field must be initialized to zero before the call to @@ -102,24 +120,11 @@ and zero (i.e., no feature bits) is placed in the field by the kernel upon return from .BR ioctl (2). .PP -Starting from Linux 4.11, the -.I features -field can be used to ask whether particular features are supported -and explicitly enable userfaultfd features that are disabled by default. -The kernel always reports all the available features in the -.I features -field. -.PP -To enable userfaultfd features the application should set -a bit corresponding to each feature it wants to enable in the -.I features -field. -If the kernel supports all the requested features it will enable them. -Otherwise it will zero out the returned +If the application sets unsupported feature bits, +the kernel will zero out the returned .I uffdio_api structure and return .BR EINVAL . -.\" FIXME add more details about feature negotiation and enablement .PP The following feature bits may be set: .TP
Fully describe how UFFDIO_API can be used to perform a two-step feature handshake, and also note the case where this isn't necessary (programs which don't depend on any extra features). This lets us clean up an old FIXME asking for this to be described. Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> --- man2/ioctl_userfaultfd.2 | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-)