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 A7D8CC369CB for ; Wed, 23 Apr 2025 17:15:26 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id A5D346B002C; Wed, 23 Apr 2025 13:15:24 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 9BDEE6B002D; Wed, 23 Apr 2025 13:15:24 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 837E36B002F; Wed, 23 Apr 2025 13:15:24 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 5F23C6B002C for ; Wed, 23 Apr 2025 13:15:24 -0400 (EDT) Received: from smtpin26.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id 91C47141684 for ; Wed, 23 Apr 2025 17:15:25 +0000 (UTC) X-FDA: 83365959810.26.21293F0 Received: from mail-qt1-f173.google.com (mail-qt1-f173.google.com [209.85.160.173]) by imf10.hostedemail.com (Postfix) with ESMTP id B5976C0010 for ; Wed, 23 Apr 2025 17:15:23 +0000 (UTC) Authentication-Results: imf10.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=gcQ1WG5X; dmarc=pass (policy=reject) header.from=google.com; spf=pass (imf10.hostedemail.com: domain of surenb@google.com designates 209.85.160.173 as permitted sender) smtp.mailfrom=surenb@google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1745428523; a=rsa-sha256; cv=none; b=SaSQ67Ri0EzFQ0WAoXl/8m/8wTJ/XYpWgvVz20dR8Bw/aRGnjzUeGoadSfC+8f7KeM8ruw t9SlZUhxeRMt1FPZ0rpQTe5UYGqYXifwq/97HLky92Yg2TNw2QNxkOrHoy/MZgOy48P2aK tZIKPQMWndh3T9pHW5vTOBZkIDSc/Js= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1745428523; 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=iLeR6rMZJIsw6w/zOvDvjP4YsUrvPI3KmargNssoim0=; b=zAgAtmPUAL4GzXQQcyOs9uRmqF1TqIH4vb+jgVrjxirC9K+G1HT+FLhrcOLz6Ia1FNSvKX qG0KBgDOnfKO4WynPD2OEtg6v2LzjTvwks1N33HIidhM2UKZzVxuhuSanQ/ijwGuveaXFp AlLLmO7ql2v7GI2Bp6ywb5AwBMBd3aQ= ARC-Authentication-Results: i=1; imf10.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=gcQ1WG5X; dmarc=pass (policy=reject) header.from=google.com; spf=pass (imf10.hostedemail.com: domain of surenb@google.com designates 209.85.160.173 as permitted sender) smtp.mailfrom=surenb@google.com Received: by mail-qt1-f173.google.com with SMTP id d75a77b69052e-47666573242so28401cf.0 for ; Wed, 23 Apr 2025 10:15:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1745428523; x=1746033323; 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=iLeR6rMZJIsw6w/zOvDvjP4YsUrvPI3KmargNssoim0=; b=gcQ1WG5XICJJg7DoVA02A0JKW2a4BfJ7uwe06ZhzQ0HVJtf0EKgJB5DhQ1imzMFvFP grujiYzuau574bcd/A04PuvTlbIE0gr8Rk9KQR3jE1PVb/PkpN07PA4Rq7MtZJZ3PoR4 X+orpbfJbd5YRVaODvDjXKRQgyskAZwjjyYsvF1yWYYLXXdb6oy6wgx/8FwsI7b8tguR yfvnsmuDCNefJIVXU9fz1WeAC/N2b8a6FBKFOTZZ1IYycrX8LXshDytulWVzMcq9YzM0 Z3OyHAz5kE6h/jYwRenDaf8INhjM+WHrg4jtlVWCaeRBk7nxi2mnHSl631BjDD2TnMNA luWw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1745428523; x=1746033323; 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=iLeR6rMZJIsw6w/zOvDvjP4YsUrvPI3KmargNssoim0=; b=AcyBHRRqsPqU5Vr8RgkKHrj7/Ed2dlAZYmFSnd7B7HzC7ip1Jfl6HV/YLNrBsfQGzj NC8g6gTk+lX01GniUvXCK1HBz4vUvTafhCMTknS6OzWuCtVIAhoQKBYOgTmn0FnwKfav xi/BgLN96cfPViYb6yamZaAOfMDnmujjc0M3XFqMmd/mUkuNyEvefXpLNadEX2GJb1iD aPelUzTAgbi3QYNbJJH7WvUiP6JAe3E3RM0TW43ZkmESNC4V7u4+jlDYA19Z9we7e974 h/qcGJtpzohaGwnh4T6T2O0ZHjRGKM5Vuf+tXPoOfDJlr3g+zi47YYlDVKn/fsKuzusx B0yQ== X-Forwarded-Encrypted: i=1; AJvYcCWC5ZQXPmvYJWshwfXkSYZ/aD8ZEj/qpHae2IjfE8Uu+qU+wXZ3AbTknQgMbSC6lojmv1kN7NuHhA==@kvack.org X-Gm-Message-State: AOJu0YzgpsKM4ZFhwCMBc69srTD75sZJQ7jX+oApuucB82ledquH2AfI Tx4h2/1GBb68zpzEnRQz9v5VX5TrlaO0e8ILdwuNlvfLgZfUczjrjr8nbSJqGGGK9TWJPQjXhOl 6XSQSYG95gDAUzEPZl276HE8nbc5QkzgJdm4V X-Gm-Gg: ASbGncujFwR8WNGpM7xEk1JUsUerlCFuz9c9th6oZSpLLo2tIklFCSePDYee3mahz3d xQMIhJs0pLbd7lAiCHJ8a18ZwUqWaCbqmU/K522Ef8D6TQCdRqRBkW0j9RTq91qHUSOPtGYZGFg NORh/wC+EtzkjhXXRfIx5165LYM3jE7HVc4gZ2aqK0vFC5yKGprDfqZrs11FObv9A= X-Google-Smtp-Source: AGHT+IFv5PN1d8B4wYTtRYDsNkrW8O+cIRqsm2+Ekmc6KR5sy5YZ+32qZipIM2X7yMDVi9OqFaVv9jQM6xIPpcdYc7A= X-Received: by 2002:a05:622a:14ca:b0:47d:4e8a:97f0 with SMTP id d75a77b69052e-47d4e8a98f5mr3855971cf.29.1745428522409; Wed, 23 Apr 2025 10:15:22 -0700 (PDT) MIME-Version: 1.0 References: <20250423011203.2559210-1-surenb@google.com> <4xxeauieht3kdepkgsc73xroo42zkltepxpzce6yir2zouzr7w@tjp5t43tr7pk> In-Reply-To: <4xxeauieht3kdepkgsc73xroo42zkltepxpzce6yir2zouzr7w@tjp5t43tr7pk> From: Suren Baghdasaryan Date: Wed, 23 Apr 2025 10:15:10 -0700 X-Gm-Features: ATxdqUHMNVPecvSKEztIWpWzNzMrUPORLp04P0ezN47hC0c9OqqzNGvQTTIARfs 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: B5976C0010 X-Stat-Signature: cucmp8dmajpf4oo5dg96jg1kp1g9ahu5 X-Rspam-User: X-HE-Tag: 1745428523-542554 X-HE-Meta: U2FsdGVkX1/694pdVqoroebIUYpDxV52/dP12W0GUXp5FFU+B32l5f2qlB0WNDyMNfyhFDPu7YPcpWOR3JY07MYu/ZZeEcUIO8KG8M0s+gwMvShxlXY55KoEnwIEga8OIddf/CW6aDOPsdGmU36ToPtaJNqEaqVm1V1T+Y4rjGwCl+/efCbbHDrzHlid/0XqMu9KI8JIoV2Qz5fjnC1uRbNMrGPzaJ06vO0gCyTzc9gjasL5r0162B5tAKF/iJlrxc4rvsVXpBOvfwsmBWSCY8CbEXr4/3IV+WTiFxRWYpKoXveT2+eUWOnm7xsB2yZdcQ/xuv5qZX0Miv1f0lSu9E2RUmVgUKbs+vrEFu1zRR7FT8LjP7z59g6D1Um6hD1c/iu3+d9KXDQqc/d4SQf+EVXbU+SynE2lgLAn2yTTaWzDU35SOk7tylffYmKT4lj1B5Xx1LphTowRHtMao/Ooqg55QA6f4X1JcVrpOBKnQtTIwb4SBAaebvAgUolIfN533yl8myQCKDWD0+oUM/KIVAk/mG7CoTyFmkSGZDYIJtgylcAtNT6sHkv399iGXCO4wQ9YmJVkUWRTgZ7aRAE+Imqk50pRs30r81EfrNHsYQTitp3GALI4kfJV0l61XfsGlXAqvD2J4dd/g/klyekrYduTh4bVFQ5XWioPftSNPJZ/EZVTdn6zaaiN+gsnyFaNIxejWU+4XsCIDoaG+yrv1ajXT+g4s2QldhSrpnyLJzlO4DJaPZ4wdmTcRgmN+nKZimeSZ7JsFj6MBuTBrlLpvSD2mn2x9emC24r3w3SkHYP72p5KXtC3z6HcTsFwmFyEhgtZppqDLsBRD36D4bkmoUrKaAkpYlrt+cc9gHoTSynlUHYwAzML+N+R1rJYzoca/d5he/yikl0i0pwP+GtQtKNRb/B85yihGI9E5lGKrV4x9Pm+PDfwjHhJWz69jmQAkh32wt+5bFM16Iccg1u pcC87D3d r4SHvYgERrFVvOW5jfiQkZPEKKNc2VvtR7pW/wmjng4pV/Desqapbk5MSGyCGzZVXGEZdszhiIcLfqAX9fULxyzTqvPKWcCAtZV/H8kjk9whWNujwYwlq9aTE0RR/DwKBTeKMSOOijTORsDs7b552lwdsjBvlGhafchaCZw7qxgfH128xbBzW7t9Ok5x4VdLbneAUlo0t428vdUtszTMXiXxjIPIGMEwGjjR0ZEkzVRtiA3W693f6HvihZvYHVz+7ggZ0+lPrlWG4ilvaJPPFOBdK1JLjoocStfQaWpuDNlrWQ+k82q85iYnye3CVdSv0jM1Sxyn1f1O5adWzjeiqE4sjZb8aYFEE3O28L/F6I2ndj+kq6pDtbJSi0K7E2yTO8TuFid/57OUte9EhVkkxmMaP0cDbuZ1SuIqw+YsOys8NNgLZ55SUyA57oiwZfW7zmgaM 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 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. > > > 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_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_MO= VE.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). > > > +.\" 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 registere= d range > > +.SH LIBRARY > > +Standard C library > > +.RI ( libc ,\~ \-lc ) > > +.SH SYNOPSIS > > +.nf > > +.BR "#include " " /* Definition of " UFFD* " con= stants */" > > +.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? > > > +.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 registere= d > > +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'. > > $ 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're > 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. > > > +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' > > > +.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 '(' > > > +.IR errno -style > > +value). The > > Always break after '.' > > 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. > > > +.SH RETURN VALUE > > +On success, > > +0 is returned. > > +In this case, the entire area was moved. > > +.P > > +On error, \-1 is returned and > > +.I errno > > +is set to indicate the error. > > +.SH ERRORS > > +.TP > > +.B EAGAIN > > +The number of bytes moved (i.e., the value returned in the > > +.I move > > +field) > > +does not equal the value that was specified in the > > +.I len > > +field. > > +.TP > > +.B EINVAL > > +Either > > +.I dst > > +or > > +.I len > > +was not a multiple of the system page size, or the range specified by > > +.I src > > +and > > +.I len > > +or > > +.I dst > > +and > > +.I len > > +was invalid. > > +.TP > > +.B EINVAL > > +An invalid bit was specified in the > > +.I mode > > +field. > > +.TP > > +.BR ENOENT > > +The source virtual memory range has unmapped holes and > > +.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES > > +is not set. > > +.TP > > +.BR EEXIST > > +The destination virtual memory range is fully or partially > > +mapped. > > +.TP > > +.BR EBUSY > > +The pages in the source virtual memory range are either > > +pinned or not exclusive to the process. The kernel might > > +only perform lightweight checks for detecting whether the > > +pages are exclusive. To make the operation more likely to > > +succeed, KSM should be disabled, fork() should be avoided > > +or MADV_DONTFORK should be configured for the source virtual > > +memory area before fork(). > > Semantic newlines. > > This paragraph is repeating part of the information from the last > paragraph in the DESCRIPTION. Do we want to de-duplicate somehow? > > > +.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. > > > +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 > > > > -- >