man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE

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>
Message-ID: <20250423195309.2841410-1-surenb@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/ioctl_userfaultfd.2 b/man/man2/ioctl_userfaultfd.2
index 3cb1b8305c5fef8314ca88bae6419fc785952253..5ec08ca551708ed9ccf99f24218f681547db5924 100644 (file)
--- 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 (file)
index 0000000..daa122b
--- /dev/null
+++ b/man/man2const/UFFDIO_MOVE.2const
@@ -0,0 +1,159 @@
+.\" 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
+.B ENOENT
+The source virtual memory range has unmapped holes and
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+is not set.
+.TP
+.B EEXIST
+The destination virtual memory range is fully or partially
+mapped.
+.TP
+.B EBUSY
+The pages in the source virtual memory range are either
+pinned or not exclusive to the process.
+Once KSM deduplicates pages
+or
+.BR fork (2)
+COW-shares pages during
+.BR fork (2)
+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,
+.BR fork (2)
+should be avoided
+or
+.B MADV_DONTFORK
+should be configured
+for the source virtual memory area
+before
+.BR fork (2).
+.TP
+.B ENOMEM
+Allocating memory needed for the operation failed.
+.TP
+.B 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