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

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

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

[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

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

[Suren Baghdasaryan]

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.

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

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

[Alejandro Colomar]

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

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

[Suren Baghdasaryan]

On Wed, Apr 30, 2025 at 4:10 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> 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!

Sure, no rush. 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/>

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

[Alejandro Colomar]

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

Hi Suren,

On Wed, Apr 23, 2025 at 12:53:09PM -0700, Suren Baghdasaryan 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>

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


diff --git i/man/man2const/UFFDIO_MOVE.2const w/man/man2const/UFFDIO_MOVE.2const
index 77b0ca781..daa122b30 100644
--- i/man/man2const/UFFDIO_MOVE.2const
+++ w/man/man2const/UFFDIO_MOVE.2const
@@ -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.


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

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

[Lorenzo Stoakes]

On Thu, May 01, 2025 at 03:12:14PM +0200, Alejandro Colomar wrote:
> Hi Suren,
>
> On Wed, Apr 23, 2025 at 12:53:09PM -0700, Suren Baghdasaryan 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>
>
> 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

Thanks for taking Alejandro and big thanks to Suren for kindly putting this
forward after my ping, much appreciated! :)

Cheers, Lorenzo

>
>
> diff --git i/man/man2const/UFFDIO_MOVE.2const w/man/man2const/UFFDIO_MOVE.2const
> index 77b0ca781..daa122b30 100644
> --- i/man/man2const/UFFDIO_MOVE.2const
> +++ w/man/man2const/UFFDIO_MOVE.2const
> @@ -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.
>
>
> > ---
> > 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/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/>

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

[Suren Baghdasaryan]

On Thu, May 1, 2025 at 6:12 AM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Suren,
>
> On Wed, Apr 23, 2025 at 12:53:09PM -0700, Suren Baghdasaryan 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>
>
> 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.

Hi Alex,
Your changes look good. Thank you and Lorenzo for helping to sort this out.
Cheers,
Suren.

>
>
> Have a lovely day!
> Alex
>
>
> diff --git i/man/man2const/UFFDIO_MOVE.2const w/man/man2const/UFFDIO_MOVE.2const
> index 77b0ca781..daa122b30 100644
> --- i/man/man2const/UFFDIO_MOVE.2const
> +++ w/man/man2const/UFFDIO_MOVE.2const
> @@ -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.
>
>
> > ---
> > 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/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/>