From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6167CC369CB for ; Wed, 23 Apr 2025 19:55:57 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 3ADC76B000C; Wed, 23 Apr 2025 15:55:56 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 3369F6B000D; Wed, 23 Apr 2025 15:55:56 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 1D7CC6B000E; Wed, 23 Apr 2025 15:55:56 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0013.hostedemail.com [216.40.44.13]) by kanga.kvack.org (Postfix) with ESMTP id F3FB26B000C for ; Wed, 23 Apr 2025 15:55:55 -0400 (EDT) Received: from smtpin28.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id 4C3DD1CCAF0 for ; Wed, 23 Apr 2025 19:55:56 +0000 (UTC) X-FDA: 83366364312.28.9972FA9 Received: from mail-qt1-f182.google.com (mail-qt1-f182.google.com [209.85.160.182]) by imf27.hostedemail.com (Postfix) with ESMTP id 66B9440011 for ; Wed, 23 Apr 2025 19:55:54 +0000 (UTC) Authentication-Results: imf27.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b="JbD7VaD/"; dmarc=pass (policy=reject) header.from=google.com; spf=pass (imf27.hostedemail.com: domain of surenb@google.com designates 209.85.160.182 as permitted sender) smtp.mailfrom=surenb@google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1745438154; a=rsa-sha256; cv=none; b=gxiAIIHu3NIm55t66bF7mGWUKuaAVvA5eR/ogBH9vOjp9suGZYYfMD87tpSBcM1Kt7x844 KTmy1QK3XiXHOt10Nxil4vDBc719oAQhJIbBFfuG0fMsJ1zp96dar2VFhBO32KTygUzp15 mhLo9l7+c3K3aYK4OyJs5KJJgGzbFUI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1745438154; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=78KmzxKX+QP7hrVt8iqVUWDGDiO1qztpL48ALj33Fx4=; b=BdXZgINuGRtjFROnJufCQ4S06RoMboWStD+ILAlV4ODVtKVKJown2HHaC7lGf/5aIk4bT/ /nRtOsd3jwplqTveYO1tpFiO8HJqNYLMFBhqSNSjhBb6v4O1jhH6GQZ40iFgGVTZmo7jC3 DoRynNtpKEolotIULbfabryyWIIl+TY= ARC-Authentication-Results: i=1; imf27.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b="JbD7VaD/"; dmarc=pass (policy=reject) header.from=google.com; spf=pass (imf27.hostedemail.com: domain of surenb@google.com designates 209.85.160.182 as permitted sender) smtp.mailfrom=surenb@google.com Received: by mail-qt1-f182.google.com with SMTP id d75a77b69052e-4774611d40bso64951cf.0 for ; Wed, 23 Apr 2025 12:55:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1745438153; x=1746042953; darn=kvack.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=78KmzxKX+QP7hrVt8iqVUWDGDiO1qztpL48ALj33Fx4=; b=JbD7VaD/VrpGiIM+StlypUkQMZI8ZSl2rDBTGIFha9KJqe41tplsQgdStVuXmnmQnU vBAAehTdtsSH8sjiqnIbwlhaYTKbLMFxpyB+OmdKXo7MsuStkknsPIxBtfkhb3LzmUg9 pY9tOKU32xEXd4ZaUCpedbT7faiNhYuqAlhCoQ+n8tSUpUS+oPB257HCgGzwe+yWC2x2 UIVTo4Cl9BFz5FFaZ/A2dQx9fVGEkIzoU7nMS5VBHBnc/XRfQD7LT0HPz16h14Ml0uNP LFWAna/WnG6hxC2nxYs08K60f2E6PkQIjwjX+VcE9+TJphwZTZ+xQ+8erZRNP3gT1Y6e eWKw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1745438153; x=1746042953; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=78KmzxKX+QP7hrVt8iqVUWDGDiO1qztpL48ALj33Fx4=; b=P/IGSdme7ofTaKa/cD5lB9kayWOp8xZ9jrxZpyZa6mMIA1R2IJ+BB2R8Ncyh5jnT0O kIOGFfYll+hX4zlw0FiiwC1NDlupzLE8oRaBB+OXm5hBBp3suE1oV1XhZJD1vrOSSX8B kFILghK1DzdBugc6crAGJ/Js+U+/p7+exyMPi51KZLsMQ84/JRVGZUlYHZG9d5VnL2J6 vVHGc/8bpC9dpawjJCcyIV7P1bsj99AVv+udOB6oLPD+jI5jwaMQNkD7uNNOZzErBaLH WhX1Qw2x2xZEWGuXXI9k2XDE6crJHhZl/lUKBJ1lWz0PKIGnNy/xg8uWrf9SvFh8nh65 WEeQ== X-Forwarded-Encrypted: i=1; AJvYcCWXJ2kKXSNwl5UoJhVzTw9un3XVY20D60SzsUe0Nbf0xNBHF41Ywp56hVluQ73c5sZefefOl63IUg==@kvack.org X-Gm-Message-State: AOJu0Yytce24FTSUs7Xiv/MUPuGof2fr7afuByYg5WID0wOaiNpJM0eZ FKEemD8GWVk6KpNblo7GzdZhHveHHiuMAeIjCWnl6XsI/Imk2BFe/Mm/+NtrZXptz0ekbyzUnBE 08Rs0cfd0PEUqCxfo79S042baySOkmu8FSZ/z X-Gm-Gg: ASbGncs6PvkZh+Ecq1ChVewWmG0obdti5OcRaO05ORlH/a0xqU8qPeehwwqZ7g+LW+B 0Go2WUvCBr6dE+6wbU4+K0dz0NNQYjyRVelR/fPoQfkCR2jTU6Zw9vf+fmCe8fDpBhmtQmlMe/+ r98h1gSJQIOYnGN2QUds0hlFAUONoSFgW2UzYhuPiVY0naooRNf57X X-Google-Smtp-Source: AGHT+IFCJOLKK/LNXMbyOjCy6OuNG5xYC1hq5MlCvtZlwym+/sYdVov2p6fBE8DL6Dy9bfksSxDuW3HUziFuzLlr1fY= X-Received: by 2002:a05:622a:1f1b:b0:474:bd1b:417b with SMTP id d75a77b69052e-47e7c484e28mr722401cf.26.1745438153151; Wed, 23 Apr 2025 12:55:53 -0700 (PDT) MIME-Version: 1.0 References: <20250423011203.2559210-1-surenb@google.com> <4xxeauieht3kdepkgsc73xroo42zkltepxpzce6yir2zouzr7w@tjp5t43tr7pk> In-Reply-To: From: Suren Baghdasaryan Date: Wed, 23 Apr 2025 12:55:41 -0700 X-Gm-Features: ATxdqUG7rWl7X3-0VvVLQtF2wZq5pdKr7l9Qbf7M9O79Z7aaj4e9PheL44Nx6eA Message-ID: Subject: Re: [PATCH 1/1] man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page To: Alejandro Colomar Cc: aarcange@redhat.com, lorenzo.stoakes@oracle.com, david@redhat.com, peterx@redhat.com, lokeshgidra@google.com, linux-man@vger.kernel.org, linux-mm@kvack.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Rspamd-Server: rspam06 X-Rspamd-Queue-Id: 66B9440011 X-Stat-Signature: irghbdytccwmdoh5mq4xqj1xteozahe6 X-Rspam-User: X-HE-Tag: 1745438154-561258 X-HE-Meta: U2FsdGVkX18x8mwiVxmSkOFuhRqcwvc+ODMYf+mW51gdA7NjYXJ1xNQnlGWxi39PPdWVQE6hiEkvO92PTV2AzxfPMMmN+utsbUgTNZkOfSgs+vhlL1mYoIjyF7gChyv+/kJ9e+6XsjgY3gHVoBHiufL0nrfovlA9lEdfYj1+oMrA4reFQkoIk1pzUeWAA7AHA3O//kgEqGUwa/mnLgilOVBNySj1n/MS0YYeEbxhdb+GsX7pPclOoGMHP3YiUQ94CpObHwyUhd/OKTIhT2I5cJ2h6I6qDh/XTWkl7wzw3DoGCJsMlgV8oQDEGFWRqJp5yF0V1V4LpUp9zKLA84t6p1uk/IMay1cc5Tgd3uNiIheXO+jWZMKNtI8V942jbSBudflHdZhIOqu5oTxi28b42uhSBs7vMw/aSTHXYwChrMTgB0OKfbAjQPzNxT1DDY7tifGF75dq0Tddyz2h4/tXcGApdQJ+2cT1hwfenIk9Smf/5tt9kOYbqq5mvc/3XAqYHLSSFWpD0UXJgOr8c2arjGVibNMGuXDkAYYznWNA+Kst12wtlvEWwtiwNU5Cl/koPIUFI8/X10KH39sdQBYIHU8B4Xh5i4VyDKb8ZdRm6ERLQ/UuYhfVlt9Sk5IxVt5k2pOqfT0QJOxtimjB5r/WMyIBfuildaf4DRBEamXYToDD4Mbo7omMH1vSPaiNCJjao3KwKpuOiHlPx3iKQMX/wk2LGQrYEioAKVowKndh6bBa4d/vPj5fqJONtSKlfQDBLnSUv19BhoQxqzDZeplagmiMkLyr/wQeaEzYszxDGFvZTaMqR1jEt8NTmSGB7UZycN0zK4W0vIOL2wGTcTWsgoCgPR3fqbLj+pgN9iGSfcTLk329bA1Imkx+O6hHaNFBeUpKXnB6hgoNtD0qmGkv6SOCiizfADWzh1g7Db1Wc471hQ3m+4XEJHsm2D7+eivPPUjkunGMy0dpiMw2sTb z4s5kBMt I0yHZ6QtoGsWvFoBdQlCe6TP6IP/bfAKdAArMqBsdOoabX2rRY53oZrMy6S1mTtp9VN4O06ARBrfkeBFkzwpRUbAQu438Hrm7OLQH2MLDKm8DPU/tlI/CPpmBGmZ/RfZ1DxnFAm54pf+59+CAE00zRkHo0X5i67hfwk2CwXos7ly0OSyFv4Kbaeias3a/a/lqSU6sgVFlASDns4yhudvYIAn3zxxiBwZVvpumbtF/KRVAASfDaVXEwvyDghwcLkvRKLf+oGXh7zehAeTdIV8lG498tPlCDEcM2g52YTe/q6oyvsxM5V/J4XHHVBZSKAaIE5EJFSbmY9ty7G1m4D2re434Te5Gcep8EznFjMmbPM097NsubAXvPWXQIW5b8QkJn2cD7HPUYmHxNmXn7JGpmUkRHQ/LjkWCSUWjo9vczBxSiotX/Sn2OVrv5IVJSIGbqVuL X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: On Wed, Apr 23, 2025 at 10:15=E2=80=AFAM Suren Baghdasaryan wrote: > > On Wed, Apr 23, 2025 at 1:16=E2=80=AFAM Alejandro Colomar wrote: > > > > Hi Suren, > > > > On Tue, Apr 22, 2025 at 06:12:03PM -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] > > > > > > Signed-off-by: Suren Baghdasaryan > > > > It looks good, but there are a few issues commented below. > > Thanks for the patch! > > Thanks for the feedback. Working on addressing your comments and will > post v2 today. Answers to your comments are below. Resulting v2 is posted at https://lore.kernel.org/all/20250423195309.2841410-1-surenb@google.com/ Thanks! > > > > > > > Have a lovely day! > > Alex > > > > > --- > > > 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_userfaultf= d.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 > > > > This shouldn't be there. There should be a diagnostic from the build > > system about it being spurious: that line is there only in pages that > > use tables (.TS/.TE), to let man(1) know that it should invoke tbl(1). Ack. > > > > > +.\" 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 registe= red range > > > +.SH LIBRARY > > > +Standard C library > > > +.RI ( libc ,\~ \-lc ) > > > +.SH SYNOPSIS > > > +.nf > > > +.BR "#include " " /* Definition of " UFFD* " c= onstants */" > > > +.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 */" > > > > Are we in time to name this size instead of len? Length usually refers > > to the number of non-zero characters in a string, while size refers to > > number of bytes in some object, which is more appropriate in these > > cases. > > > > If this has already been released in the kernel, don't worry about it, > > but if it hasn't, maybe we should call it size? Sorry, it was released back in 6.8. > > > > > +.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 registe= red > > > +range and optionally wake up the blocked thread. > > > > Please use semantic newlines. In this case, I'd break the line before > > 'into', and before 'and'. Ack. > > > > $ MANWIDTH=3D72 man man-pages | sed -n '/Use semantic newlines/,/^$/p' > > Use semantic newlines > > In the source of a manual page, new sentences should be started > > on new lines, long sentences should be split into lines at > > clause breaks (commas, semicolons, colons, and so on), and long > > clauses should be split at phrase boundaries. This convention, > > sometimes known as "semantic newlines", makes it easier to see > > the effect of patches, which often operate at the level of indi= =E2=80=90 > > vidual sentences, clauses, or phrases. > > > > > +.P > > > +The following value may be bitwise ORed in > > > +.I mode > > > > Please use .mode instead of mode. That makes it more obvious that we'r= e > > talking about a struct member. I know most pages don't do this, but I'= m > > planning a global change for consistency soon; since this page is new, > > we can start clean and do it as > > > > .I .mode > > > > This is done in a few cases already in fanotify(7), for example. Ack. I assume that should be done everywhere else. > > > > > +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. > > > > Please use semantic newlines. In this case, I'd break: > > > > - after ',' > > - after '.' > > - after 'useful' > > - before 'without' > > - after ',' > > - after 'of' Ack. > > > > > +.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 > > > > I'd break: > > > > - after 'kernel' > > - after ',' > > - before '(' Ack. > > > > > +.IR errno -style > > > +value). The > > > > Always break after '.' Ack. > > > > See also: > > > > > +.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(). > > > > Please use semantic newlines. > > > > Also, a few things like EBUSY and MADV_DONTFORK should be marked up. Ack. > > > > > +.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 b= y > > > +.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(). > > > > Semantic newlines. > > > > This paragraph is repeating part of the information from the last > > paragraph in the DESCRIPTION. Do we want to de-duplicate somehow? Yes, I folded this into the appropriate error code description. > > > > > +.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 > > > > UFFDIO_MOVE should be bold. Ack. > > > > > +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 > > > > > > > -- > >