man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page

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/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

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

[1] https://lore.kernel.org/all/[email protected]/

 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

man/man2/ioctl_userfaultfd.2 +2 -0

index 3cb1b8305..5ec08ca55 100644
@@ -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)

man/man2const/UFFDIO_MOVE.2const new file +153 -0

new file mode 100644
index 000000000..77b0ca781
@@ -0,0 +1,153 @@
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" 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

Quoted 8 lines · Suren Baghdasaryan

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/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

Quoted 9 lines

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

Quoted 186 lines

[1] https://lore.kernel.org/all/[email protected]/

 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

man/man2/ioctl_userfaultfd.2 +2 -0

index 3cb1b8305..5ec08ca55 100644
@@ -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)

man/man2const/UFFDIO_MOVE.2const new file +153 -0

new file mode 100644
index 000000000..77b0ca781
@@ -0,0 +1,153 @@
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" 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

Hi Suren,

Quoted 19 lines · Suren Baghdasaryan

Quoted 8 lines · Suren Baghdasaryan

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/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

Quoted 9 lines

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

Quoted 5 lines

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

Quoted 182 lines

Quoted 182 lines

[1] https://lore.kernel.org/all/[email protected]/

 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

man/man2/ioctl_userfaultfd.2 +2 -0

index 3cb1b8305..5ec08ca55 100644
@@ -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)

man/man2const/UFFDIO_MOVE.2const new file +153 -0

new file mode 100644
index 000000000..77b0ca781
@@ -0,0 +1,153 @@
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" 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

Quoted 5 lines

Quoted 4 lines

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510 --
2.49.0.805.g082f7c87e0-goog

--
<https://www.alejandro-colomar.es/>

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/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

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

[1] https://lore.kernel.org/all/[email protected]/

 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

man/man2/ioctl_userfaultfd.2 +2 -0

index 3cb1b8305..5ec08ca55 100644
@@ -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)

man/man2const/UFFDIO_MOVE.2const new file +153 -0

new file mode 100644
index 000000000..77b0ca781
@@ -0,0 +1,153 @@
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" 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

Signature · 1 line

2.49.0.805.g082f7c87e0-goog

Hi Suren,

Quoted 7 lines · Suren Baghdasaryan

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/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

I've formatted references to fork(2). I also fixed a few places with s/BR/B/. Other than that, the patch was fine; I've applied it. Thanks!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=d7dec35a3b197d499c0bb2b078117478fe6382d1>
Below is the diff with which I amended the patch.

Have a lovely day!
Alex

man/man2const/UFFDIO_MOVE.2const +14 -8

index 77b0ca781..daa122b30 100644
@@ -108,36 +108,42 @@ .SH ERRORS
 .I .mode
 field.
 .TP
-.BR ENOENT
+.B ENOENT
 The source virtual memory range has unmapped holes and
 .B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
 is not set.
 .TP
-.BR EEXIST
+.B EEXIST
 The destination virtual memory range is fully or partially
 mapped.
 .TP
-.BR EBUSY
+.B 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,
+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,
-fork() should be avoided
+.BR fork (2)
+should be avoided
 or
 .B MADV_DONTFORK
 should be configured
 for the source virtual memory area
-before fork().
+before
+.BR fork (2).
 .TP
-.BR ENOMEM
+.B ENOMEM
 Allocating memory needed for the operation failed.
 .TP
-.BR ESRCH
+.B ESRCH
 The target process has exited at the time of a
 .B UFFDIO_MOVE
 operation.

Quoted 192 lines

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

[1] https://lore.kernel.org/all/[email protected]/

 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

man/man2/ioctl_userfaultfd.2 +2 -0

index 3cb1b8305..5ec08ca55 100644
@@ -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)

man/man2const/UFFDIO_MOVE.2const new file +153 -0

new file mode 100644
index 000000000..77b0ca781
@@ -0,0 +1,153 @@
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" 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

Quoted 4 lines

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510 --
2.49.0.805.g082f7c87e0-goog

--
<https://www.alejandro-colomar.es/>

Hi Suren,

Quoted 4 lines · Suren Baghdasaryan

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.

Quoted 3 lines

[1] <https://lore.kernel.org/all/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

I've formatted references to fork(2). I also fixed a few places with s/BR/B/. Other than that, the patch was fine; I've applied it. Thanks!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=d7dec35a3b197d499c0bb2b078117478fe6382d1>
Below is the diff with which I amended the patch.

Have a lovely day!
Alex

man/man2const/UFFDIO_MOVE.2const +14 -8

index 77b0ca781..daa122b30 100644
@@ -108,36 +108,42 @@ .SH ERRORS
 .I .mode
 field.
 .TP
-.BR ENOENT
+.B ENOENT
 The source virtual memory range has unmapped holes and
 .B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
 is not set.
 .TP
-.BR EEXIST
+.B EEXIST
 The destination virtual memory range is fully or partially
 mapped.
 .TP
-.BR EBUSY
+.B 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,
+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,
-fork() should be avoided
+.BR fork (2)
+should be avoided
 or
 .B MADV_DONTFORK
 should be configured
 for the source virtual memory area
-before fork().
+before
+.BR fork (2).
 .TP
-.BR ENOMEM
+.B ENOMEM
 Allocating memory needed for the operation failed.
 .TP
-.BR ESRCH
+.B ESRCH
 The target process has exited at the time of a
 .B UFFDIO_MOVE
 operation.

Quoted 192 lines

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

[1] https://lore.kernel.org/all/[email protected]/

 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

man/man2/ioctl_userfaultfd.2 +2 -0

index 3cb1b8305..5ec08ca55 100644
@@ -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)

man/man2const/UFFDIO_MOVE.2const new file +153 -0

new file mode 100644
index 000000000..77b0ca781
@@ -0,0 +1,153 @@
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" 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

Quoted 4 lines

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510 --
2.49.0.805.g082f7c87e0-goog

--
<https://www.alejandro-colomar.es/>