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 DBAACC369D3 for ; Wed, 23 Apr 2025 08:16:56 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 725B16B0082; Wed, 23 Apr 2025 04:16:55 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 6E04A6B0083; Wed, 23 Apr 2025 04:16:55 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 59A206B0083; Wed, 23 Apr 2025 04:16:55 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 34A5D6B002F for ; Wed, 23 Apr 2025 04:16:55 -0400 (EDT) Received: from smtpin26.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay09.hostedemail.com (Postfix) with ESMTP id E9C25817BD for ; Wed, 23 Apr 2025 08:16:55 +0000 (UTC) X-FDA: 83364602790.26.DAB35D9 Received: from sea.source.kernel.org (sea.source.kernel.org [172.234.252.31]) by imf06.hostedemail.com (Postfix) with ESMTP id 2DC4318000C for ; Wed, 23 Apr 2025 08:16:53 +0000 (UTC) Authentication-Results: imf06.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=sLqdten1; dmarc=pass (policy=quarantine) header.from=kernel.org; spf=pass (imf06.hostedemail.com: domain of alx@kernel.org designates 172.234.252.31 as permitted sender) smtp.mailfrom=alx@kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1745396214; 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: in-reply-to:in-reply-to:references:references:dkim-signature; bh=reSgmkRhPziwt+ucd0sb1n03q4QB/TMjHBGQoaFPZ6c=; b=a5CjiWnqIUZ14pKHM/wXvoYOE0BlfW8QCnMMylbIM83vjQfxwbe5bT0I11QxH92KhQ1Vvj iy8SKbX6jpXqz2rgH/hHv7mrrwZluCh6BtiBjqmbUlKrSAYEm+5HmDRULfVfVfkhPjvoJL GeYXNROIFG8Pj87f08MBX3hv60yGXgs= ARC-Authentication-Results: i=1; imf06.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=sLqdten1; dmarc=pass (policy=quarantine) header.from=kernel.org; spf=pass (imf06.hostedemail.com: domain of alx@kernel.org designates 172.234.252.31 as permitted sender) smtp.mailfrom=alx@kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1745396214; a=rsa-sha256; cv=none; b=wh6kh4CMNXHFLyRH+UnZmJ2G+MR+tCoPul61Wv9wRrBUkFQmUUCcsqlcD0W6EL5VPCn5LN htSFPDAmCykT30VDu224wQjH7JC7hBrMum6vRceaJXYoKIQgoE5a5ooko+q/9ymSQ1jtmN fhWyjYphqgXq/j249DDlPmqwTxpY9R8= Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sea.source.kernel.org (Postfix) with ESMTP id AF2BA43793; Wed, 23 Apr 2025 08:16:51 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 378E3C4CEE2; Wed, 23 Apr 2025 08:16:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1745396213; bh=5Sl215RXeQBr53fhZyphReVjBzXossBpmsXcRdbwFaM=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=sLqdten1OYxB9t5pfilDx28ogCKqw3c/HE64Ul903OGMepPgoFGQGf21jQKDmYCgK hj7T7u7zNxlJNbFpTAR89CoK7iTs8sd2MRvitMoj1eQRKbyE5uDjw/Onci+P4ZlmT6 neCAsnKjeCvYnhgsdv0XQ0iMTIolcn/O8qiXoMKumnS0cEVmRQ2ViY/U/poDFSFzAo pc61lYx56mei/8cv0FVuStSK2a2FZFbCNVE2B140WYxthUhU8+IFdwqQepdSXB0n4n c58ZZ3eP4zbnhFYB4bPpnbUw+DKUq04cMzUJOlizkrgkzZdntBHmtXDCcoJAV/sX4n qweCSrffNlXAA== Date: Wed, 23 Apr 2025 10:16:47 +0200 From: Alejandro Colomar To: Suren Baghdasaryan 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 Subject: Re: [PATCH 1/1] man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page Message-ID: <4xxeauieht3kdepkgsc73xroo42zkltepxpzce6yir2zouzr7w@tjp5t43tr7pk> References: <20250423011203.2559210-1-surenb@google.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="xonxjtufpsucecz7" Content-Disposition: inline In-Reply-To: <20250423011203.2559210-1-surenb@google.com> X-Stat-Signature: 3bha1q49m1uw66zptb9cmnsgaksuecba X-Rspamd-Queue-Id: 2DC4318000C X-Rspam-User: X-Rspamd-Server: rspam05 X-HE-Tag: 1745396213-500399 X-HE-Meta: U2FsdGVkX18H8GHcl7/ga1oppTOzOhu3pQ/We+1QxsrXKS0DionszqS81U25YyV/X/6L1/dlOa2gCIpzaFsb/bsGNMSLPx1e0X49nv5aNHeruHs6FZeJkkV6cnAZdlKFp0o33xawmjPE2m/wwh7Cf65iaTuBGLNosSOlmtD8UJOALz4WaHD2640ee+NfTfYA+vQA1mn41AQJlQwtn1brLp8VFiLSeRntJnJFwyYHSQvRYfnvRCQBO1gsUZ1yX8pw5T3N+FWR5+E2slovmXVnOJkq0zOXo44S5ddTdipSwLo/Nf9i2gnrxt7auMUKqpQZqeAx53JCKz31YvJS54jNIKUz6zsZDe7ojA/X3qfEXIt2EKvCULNSyjEm3suLL8GkXT8xbEY/4XUJi7NB8kfmS3G3Ro3oyPup1qiaL5295lzITsYxEmUMP99bopGia75qXRFvFusALB5Vxnprm4MDEwMP+2uJTXF3J6qOBui+t/5GzQ+OsmrU+fH0+PVDKi4VjuplWicNJqSCzGHXkjoegEyo6Dfn3IOxaFUGuQQRP5LjZl+SRYHq8Qa6PCP8RaBURnhENbAFOky4JS9lxBs3XCVXhrrEh6OM2bwkxCOeq9SwJ4D4M/iH7KrnDfaptbLBz44W2J44F/3ATlI5QJgGZdWPemOuuBLkdNANkX/L59Tu6c8NPFJKrBqffoP8dqB2P9zoxKcBtYNnjjzKTUoz/nJ44P6lVxedrtlLHDPET/s0ys92Av1NNjyFUQgnZz+x+HyLNVEGkG6Tb8YElm8PBz27l0pTz96lhfJnafAMTe9LP9bQHI2elUKdz73gRyxvM1jv8oKwLskG3Mdgc3D6EBVB9OPfAr2EC9U+d111n+BKc3HLkb5jciQ2dmAMADXQ+2sicZ23Y/EY6XlaF9sCY+WfmIWQ76b2W+SSCFb/oHcoDjXKuTYENHhz0JTgOl7wrboI37Crol8W/HXivgC rsFV9iw0 XHqkhmSm7rfn0fc/ArmgTx7366XJDUhTH5APBX/VD5kdZu0Hbiry7X+ev9QXtbhu2JZ4NdY9UiGrG3a78QSvsaPxDYfIwBRsR02tPmgd5M/EUi49VDpedWphb3p+KrObxgdTwya/sCVFlzkpk4I1fgh7z0RNzHm8ENnkMV5136EYi1ZeyRkMXPP0jzhXiBdvuvziL4fsn4+kd70sqsYmlmpoJrXkkMe2YvJRtxBm0OwUtku9srdrz+eP5FVSkopE7NFncVr/buvRIj4LpvoHkC5BJ4PyOmU94xepiHFRGBRlbCV8ajmuyoS44yyy2bVxsLoRe1v0vN9QBItl2W3qbtTduwkFIycPIBv4iwKRu4vecpy0l+mWKc/fUskTUefdZvJV5txH0bHysZiN3YiIydCthHQnQYguuGLTt14Wk7+tMsBfNG7LhoBbKHQQSao6jnyZs3jcnwV1BdND0ImXvRwIG9MaogZ9l71WzFiwnOLHvk+oMqWMZHPc5ukZ607ZuUKsg73B8he/zy4Tx0k19Eov39muoEUUOwuTjQSETyp1tU5fT1SvzNgKtNuZv5/hfv9slBa4sxZ76BhLD0HumZifh932kEwkFQXGc 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: --xonxjtufpsucecz7 Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable From: Alejandro Colomar To: Suren Baghdasaryan 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 Subject: Re: [PATCH 1/1] man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page References: <20250423011203.2559210-1-surenb@google.com> MIME-Version: 1.0 In-Reply-To: <20250423011203.2559210-1-surenb@google.com> 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. >=20 > [1] >=20 > Signed-off-by: Suren Baghdasaryan It looks good, but there are a few issues commented below. Thanks for the patch! 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 >=20 > 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= =2E2const > 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 registered = range > +.SH LIBRARY > +Standard C library > +.RI ( libc ,\~ \-lc ) > +.SH SYNOPSIS > +.nf > +.BR "#include " " /* Definition of " UFFD* " const= ants */" > +.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 registered > +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 >=20 > base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510 > --=20 > 2.49.0.805.g082f7c87e0-goog >=20 --=20 --xonxjtufpsucecz7 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmgIoegACgkQ64mZXMKQ wqkTExAAnwB4tkyuRXfO6azsDoy5Dh6H9IBPYCgqwmo/qMAoPPrWFem96DZ4221O FIGeqUZC28b2QPdpK6ZnGDCjjbOeCyBl7cT4gmnTIiqIz9F9aUrtacUu/AszwALJ vfAlz+u1dResmfEk3vuAU+VLhR2T0UPJNYj1pdqS6Umxo0YN6ix/YpdglNyeQWsx tQYT4BrX8CNE1r3cSwV2VxnJ3Wm/qDwVbMu54ilKkXKCoIczLuC38+JIfkGLZPrh I5+9UIE/d5bggiraoTeWJZhS/LFxCxk07xj4HAIxnOYnE/h96OdhUYYKhNM3psMu jo2in76HabgaztWVOkWK7yYO/7Jfb3WIK5H0ZrwCRmgTCxF3vhfVVNyZGof7zzE0 KwrEQcPwQ7Ks/ZNXd9gOsyb8usbyScOuletSM5AQCc6/So0qceg2czMJSAlITYkV D+wVrYaJPFOCJ2EJe81kUwvdPMOz9ZJelwm3zBaamT0wZzpOk5pOiEEgVRjYykR0 QS/JPyJvMClugXG6xg4q+4y7Agud0aqMqV51T1LqxbJb/dhMeXjeN94CpKoEMtUV xge8L8fz/ODKVoiBjqYkYUhXV9UQDjrXoonZMllhT9hCh9k+RFS9eT+09d5lQbpB NONuJeEcH93mcOnDB/+sb/N7RZXrvOC1NSCrcw2eJwO5sc6kPt8= =eh/g -----END PGP SIGNATURE----- --xonxjtufpsucecz7--