diff options
| author | Peter Xu <peterx@redhat.com> | 2025-05-14 13:26:29 -0400 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2025-05-18 10:17:01 +0200 |
| commit | 6a949e9b08fd1ad4e77584276b9566e45fc07a93 (patch) | |
| tree | 3616a7a3747e5ab3b2a50a5ebf2721451008eebe /man/man2const/UFFDIO_API.2const | |
| parent | f99f884ddb8161dd9e16eeda7bee49fc2bff78be (diff) | |
| download | man-pages-6a949e9b08fd1ad4e77584276b9566e45fc07a93.tar.gz | |
man/man2const/UFFDIO_API.2const: Update userfaultfd handshake and feature probe
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>
Message-ID: <20250514172630.569788-2-peterx@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man/man2const/UFFDIO_API.2const')
| -rw-r--r-- | man/man2const/UFFDIO_API.2const | 44 |
1 files changed, 25 insertions, 19 deletions
diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const index 2f5f7bc179..c1050fad78 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 |