Re: [PATCH v2 3/6] UFFDIO_SET_MODE.2const: New page

[Alejandro Colomar <alx@kernel.org>]

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

On 2026-05-26T14:41:46+0100, Kiryl Shutsemau wrote:
> Document the UFFDIO_SET_MODE ioctl (since Linux 7.2). It toggles
> userfaultfd feature bits at runtime; currently only UFFD_FEATURE_RWP_ASYNC
> is toggleable, and enabling it requires UFFD_FEATURE_RWP to have been
> negotiated at UFFDIO_API time.
> 
> Describe the uffdio_set_mode struct (enable/disable pair, must not
> overlap), the serialization against in-flight page faults that lets a
> single userfaultfd switch between async detection and synchronous
> eviction without re-registering its ranges, and the EINVAL/EFAULT
> errors returned by the kernel.
> 
> Signed-off-by: Kiryl Shutsemau <kas@kernel.org>
> Acked-by: Mike Rapoport (Microsoft) <rppt@kernel.org>

Patch applied; thanks!


Cheers,
Alex

> ---
>  man/man2const/UFFDIO_SET_MODE.2const | 98 ++++++++++++++++++++++++++++
>  1 file changed, 98 insertions(+)
>  create mode 100644 man/man2const/UFFDIO_SET_MODE.2const
> 
> diff --git a/man/man2const/UFFDIO_SET_MODE.2const b/man/man2const/UFFDIO_SET_MODE.2const
> new file mode 100644
> index 000000000000..b71632011a4c
> --- /dev/null
> +++ b/man/man2const/UFFDIO_SET_MODE.2const
> @@ -0,0 +1,98 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH UFFDIO_SET_MODE 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +UFFDIO_SET_MODE
> +\-
> +toggle userfaultfd runtime mode bits
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/userfaultfd.h>" "  /* Definition of " UFFD* " constants */"
> +.B #include <sys/ioctl.h>
> +.P
> +.BI "int ioctl(int " fd ", UFFDIO_SET_MODE, struct uffdio_set_mode *" argp );
> +.P
> +.B #include <linux/userfaultfd.h>
> +.P
> +.fi
> +.EX
> +.B struct uffdio_set_mode {
> +.BR "    __u64  enable;" "   /* Feature bits to set */"
> +.BR "    __u64  disable;" "  /* Feature bits to clear */"
> +.B };
> +.EE
> +.SH DESCRIPTION
> +Toggle userfaultfd features that may be flipped at runtime.
> +.P
> +Bits set in
> +.I enable
> +turn the named features on;
> +bits set in
> +.I disable
> +turn them off.
> +The two fields must not overlap.
> +Today only
> +.B UFFD_FEATURE_RWP_ASYNC
> +is a valid bit in either field;
> +any other bit causes the ioctl to fail with
> +.BR EINVAL .
> +Enabling
> +.B UFFD_FEATURE_RWP_ASYNC
> +also requires
> +.B UFFD_FEATURE_RWP
> +to have been negotiated at
> +.BR UFFDIO_API (2const)
> +time.
> +.P
> +The operation is serialized against in-flight page faults,
> +so the new mode takes effect
> +only after every fault that started before the call has finished,
> +and any fault that starts after the call observes the new mode.
> +This allows a single userfaultfd
> +to switch between lightweight async detection
> +and synchronous eviction
> +without re-registering its ranges.
> +.SH RETURN VALUE
> +On success,
> +0 is returned.
> +On error, \-1 is returned and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +A bit other than
> +.B UFFD_FEATURE_RWP_ASYNC
> +was specified in
> +.I enable
> +or
> +.IR disable ;
> +the two fields overlap;
> +or
> +.B UFFD_FEATURE_RWP_ASYNC
> +was requested without
> +.B UFFD_FEATURE_RWP
> +having been negotiated.
> +.TP
> +.B EFAULT
> +.I argp
> +refers to an address that is outside the calling process's
> +accessible address space.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 7.2.
> +.SH EXAMPLES
> +See
> +.BR userfaultfd (2).
> +.SH SEE ALSO
> +.BR ioctl (2),
> +.BR ioctl_userfaultfd (2),
> +.BR userfaultfd (2)
> +.P
> +.I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst
> -- 
> 2.54.0
> 

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

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