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

[Alejandro Colomar <alx@kernel.org>]

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

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!


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

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