Re: [PATCH v2 1/1] man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page

[Suren Baghdasaryan <surenb@google.com>]

On Wed, Apr 30, 2025 at 4:10 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Suren,
>
> On Wed, Apr 30, 2025 at 03:59:42PM -0700, Suren Baghdasaryan wrote:
> > On Wed, Apr 23, 2025 at 12:53 PM Suren Baghdasaryan <surenb@google.com> wrote:
> > >
> > > Documentation was extracted from the original patch written by Andrea
> > > Arcangeli and upstreamed in [1]. Minor edits were made to maintain
> > > the same documentation style as other userfaultfd ioctl commands.
> > >
> > > [1] <https://lore.kernel.org/all/20231206103702.3873743-3-surenb@google.com/>
> > >
> > > Signed-off-by: Suren Baghdasaryan <surenb@google.com>
> > > ---
> > > Changes since v1[1]
> > > - removed '\" t, per Alejandro Colomar
> > > - reformated sentences to use semantic newlines, per Alejandro Colomar
> > > - changed field names to use '.' prefix, per Alejandro Colomar
> > > - changed EBUSY, UFFDIO_MOVE and MADV_DONTFORK to be bold,
> > > per Alejandro Colomar
> > > - folded duplicate information into EBUSY error description,
> > > per Alejandro Colomar
> >
> > Hi Alex,
> > Haven't seen any feedback on this version so far. Is it ok to be
> > accepted or should I change anything else?
> > Thanks,
> > Suren.
>
> Sorry; I was traveling back to Spain the last few days.  I'll have a
> look at it tomorrow.  I had a quick look these days, and it looked good,
> but I'll confirm.  Thanks!

Sure, no rush. Thanks!

>
>
> Have a lovely night!
> Alex
>
> >
> > >
> > > [1] https://lore.kernel.org/all/20250423011203.2559210-1-surenb@google.com/
> > >
> > >  man/man2/ioctl_userfaultfd.2     |   2 +
> > >  man/man2const/UFFDIO_MOVE.2const | 153 +++++++++++++++++++++++++++++++
> > >  2 files changed, 155 insertions(+)
> > >  create mode 100644 man/man2const/UFFDIO_MOVE.2const
> > >
> > > diff --git a/man/man2/ioctl_userfaultfd.2 b/man/man2/ioctl_userfaultfd.2
> > > index 3cb1b8305..5ec08ca55 100644
> > > --- a/man/man2/ioctl_userfaultfd.2
> > > +++ b/man/man2/ioctl_userfaultfd.2
> > > @@ -69,6 +69,8 @@ events.
> > >  .TQ
> > >  .BR UFFDIO_COPY (2const)
> > >  .TQ
> > > +.BR UFFDIO_MOVE (2const)
> > > +.TQ
> > >  .BR UFFDIO_ZEROPAGE (2const)
> > >  .TQ
> > >  .BR UFFDIO_WAKE (2const)
> > > diff --git a/man/man2const/UFFDIO_MOVE.2const b/man/man2const/UFFDIO_MOVE.2const
> > > new file mode 100644
> > > index 000000000..77b0ca781
> > > --- /dev/null
> > > +++ b/man/man2const/UFFDIO_MOVE.2const
> > > @@ -0,0 +1,153 @@
> > > +.\" Written by Andrea Arcangeli <aarcange@redhat.com>
> > > +.\"
> > > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > > +.\"
> > > +.TH UFFDIO_MOVE 2const (date) "Linux man-pages (unreleased)"
> > > +.SH NAME
> > > +UFFDIO_MOVE
> > > +\-
> > > +atomically move a continuous memory chunk into the userfault registered range
> > > +.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_MOVE, struct uffdio_move *" argp );
> > > +.P
> > > +.B #include <linux/userfaultfd.h>
> > > +.P
> > > +.fi
> > > +.EX
> > > +.B struct uffdio_move {
> > > +.BR "    __u64  dst;" "   /* Destination of move */"
> > > +.BR "    __u64  src;" "   /* Source of move */"
> > > +.BR "    __u64  len;" "   /* Number of bytes to move */"
> > > +.BR "    __u64  mode;" "  /* Flags controlling behavior of move */"
> > > +.BR "    __s64  move;" "  /* Number of bytes moved, or negated error */"
> > > +.B };
> > > +.EE
> > > +.SH DESCRIPTION
> > > +Atomically move a continuous memory chunk
> > > +into the userfault registered range
> > > +and optionally wake up the blocked thread.
> > > +.P
> > > +The following value may be bitwise ORed in
> > > +.I .mode
> > > +to change the behavior of the
> > > +.B UFFDIO_MOVE
> > > +operation:
> > > +.TP
> > > +.B UFFDIO_MOVE_MODE_DONTWAKE
> > > +Do not wake up the thread that waits for page-fault resolution
> > > +.TP
> > > +.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
> > > +Allow holes in the source virtual range that is being moved.
> > > +When not specified, the holes will result in
> > > +.B ENOENT
> > > +error.
> > > +When specified,
> > > +the holes will be accounted as successfully moved memory.
> > > +This is mostly useful
> > > +to move hugepage aligned virtual regions
> > > +without knowing if there are transparent hugepages in the regions or not,
> > > +but preventing the risk of
> > > +having to split the hugepage during the operation.
> > > +.P
> > > +The
> > > +.I .move
> > > +field is used by the kernel
> > > +to return the number of bytes that was actually moved,
> > > +or an error
> > > +(a negated
> > > +.IR errno -style
> > > +value).
> > > +The
> > > +.I .move
> > > +field is output-only;
> > > +it is not read by the
> > > +.B UFFDIO_MOVE
> > > +operation.
> > > +.SH RETURN VALUE
> > > +On success,
> > > +0 is returned.
> > > +In this case, the entire area was moved.
> > > +.P
> > > +On error, \-1 is returned and
> > > +.I errno
> > > +is set to indicate the error.
> > > +.SH ERRORS
> > > +.TP
> > > +.B EAGAIN
> > > +The number of bytes moved (i.e., the value returned in the
> > > +.I .move
> > > +field)
> > > +does not equal the value that was specified in the
> > > +.I .len
> > > +field.
> > > +.TP
> > > +.B EINVAL
> > > +Either
> > > +.I .dst
> > > +or
> > > +.I .len
> > > +was not a multiple of the system page size, or the range specified by
> > > +.I .src
> > > +and
> > > +.I .len
> > > +or
> > > +.I .dst
> > > +and
> > > +.I .len
> > > +was invalid.
> > > +.TP
> > > +.B EINVAL
> > > +An invalid bit was specified in the
> > > +.I .mode
> > > +field.
> > > +.TP
> > > +.BR ENOENT
> > > +The source virtual memory range has unmapped holes and
> > > +.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
> > > +is not set.
> > > +.TP
> > > +.BR EEXIST
> > > +The destination virtual memory range is fully or partially
> > > +mapped.
> > > +.TP
> > > +.BR EBUSY
> > > +The pages in the source virtual memory range are either
> > > +pinned or not exclusive to the process.
> > > +Once KSM deduplicates pages
> > > +or fork() COW-shares pages during fork() with child processes,
> > > +they are no longer exclusive.
> > > +The kernel might only perform lightweight checks
> > > +for detecting whether the pages are exclusive.
> > > +To make the operation more likely to succeed,
> > > +KSM should be disabled,
> > > +fork() should be avoided
> > > +or
> > > +.B MADV_DONTFORK
> > > +should be configured
> > > +for the source virtual memory area
> > > +before fork().
> > > +.TP
> > > +.BR ENOMEM
> > > +Allocating memory needed for the operation failed.
> > > +.TP
> > > +.BR ESRCH
> > > +The target process has exited at the time of a
> > > +.B UFFDIO_MOVE
> > > +operation.
> > > +.SH STANDARDS
> > > +Linux.
> > > +.SH HISTORY
> > > +Linux 6.8.
> > > +.SH SEE ALSO
> > > +.BR ioctl (2),
> > > +.BR ioctl_userfaultfd (2),
> > > +.BR userfaultfd (2)
> > > +.P
> > > +.I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst
> > >
> > > base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510
> > > --
> > > 2.49.0.805.g082f7c87e0-goog
> > >
> >
>
> --
> <https://www.alejandro-colomar.es/>