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

[Suren Baghdasaryan <surenb@google.com>]

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>
---
 man/man2/ioctl_userfaultfd.2     |   2 +
 man/man2const/UFFDIO_MOVE.2const | 149 +++++++++++++++++++++++++++++++
 2 files changed, 151 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..ebeefde22
--- /dev/null
+++ b/man/man2const/UFFDIO_MOVE.2const
@@ -0,0 +1,149 @@
+'\" t
+.\" 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.
+.P
+The operation may fail for various reasons. Usually, remapping of
+pages that are not exclusive to the given process fail; once KSM
+might deduplicate pages or fork() COW-shares pages during fork()
+with child processes, they are no longer exclusive. Further, the
+kernel might only perform lightweight checks for detecting whether
+the pages are exclusive, and return -EBUSY in case that check fails.
+To make the operation more likely to succeed, KSM should be
+disabled, fork() should be avoided or MADV_DONTFORK should be
+configured for the source VMA before fork().
+.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. 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 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 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