From: Suren Baghdasaryan Date: Wed, 23 Apr 2025 19:53:09 +0000 (-0700) Subject: man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE X-Git-Tag: man-pages-6.14~13 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d7dec35a3b197d499c0bb2b078117478fe6382d1;p=thirdparty%2Fman-pages.git 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] Signed-off-by: Suren Baghdasaryan Message-ID: <20250423195309.2841410-1-surenb@google.com> Signed-off-by: Alejandro Colomar --- 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..daa122b30 --- /dev/null +++ b/man/man2const/UFFDIO_MOVE.2const @@ -0,0 +1,159 @@ +.\" Written by Andrea Arcangeli +.\" +.\" 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 " " /* Definition of " UFFD* " constants */" +.B #include +.P +.BI "int ioctl(int " fd ", UFFDIO_MOVE, struct uffdio_move *" argp ); +.P +.B #include +.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