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 EFC7CC3ABDD for ; Wed, 14 May 2025 15:59:58 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id D0FEF6B018D; Wed, 14 May 2025 11:59:57 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id C98666B018F; Wed, 14 May 2025 11:59:57 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B3BFA6B0190; Wed, 14 May 2025 11:59:57 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id 91ED16B018D for ; Wed, 14 May 2025 11:59:57 -0400 (EDT) Received: from smtpin24.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id BDBE91408E1 for ; Wed, 14 May 2025 15:59:57 +0000 (UTC) X-FDA: 83441974434.24.20C2331 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by imf11.hostedemail.com (Postfix) with ESMTP id 0F2584000C for ; Wed, 14 May 2025 15:59:55 +0000 (UTC) Authentication-Results: imf11.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=TWE8onug; spf=pass (imf11.hostedemail.com: domain of alx@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=alx@kernel.org; dmarc=pass (policy=quarantine) header.from=kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1747238396; 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=nw4CmNmAG+tZpY6fa9jaywID/Tn51iUlrKrb/HOOq1w=; b=lohXE8bXvYu8EfkSPwJEi7Pc3Nq4MJ2ENJBropsonLu/Y/HcmP96vbRqw19dY4ghByVF82 Z/dx7RAqS3re0YhV7Wp6EvoHY0A72WPXIYRjOUclw6zhV5feoPDAS3Y0l5Kn2wrpKlC/Sn GLSKeYqFMrQz7JyO4XLrUiAlMQcHvW4= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1747238396; a=rsa-sha256; cv=none; b=JmteR7KB114+EhKL6ToxQZCXe/No/FBsSuwl5x3HqvHtwf/HQeoHvz65NvL2M4RYxjdLeV cnSHMGyXaw3XjJKi7ND2XaazwxAAJkNwMWr3TDLm56GxRfkQ3jwQDdvOsgBpsA/G+tmqeP vNvcRfDPF4oM3eoMTAXdFMB28haS5ZI= ARC-Authentication-Results: i=1; imf11.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=TWE8onug; spf=pass (imf11.hostedemail.com: domain of alx@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=alx@kernel.org; dmarc=pass (policy=quarantine) header.from=kernel.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id D3AF45C594C; Wed, 14 May 2025 15:57:37 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 778E9C4CEED; Wed, 14 May 2025 15:59:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747238394; bh=HkxsrrlsqcfaJiY7c022L88luHQzOWwXnQC741NGka0=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=TWE8onugcbz50Ao7weI2Aqv17taPoevUO9o2DpBgp7cfoTXTLPEcWGJI/OVIVNXdQ +BT8fRwbXNkqoHU1Va+F32270loFzEq+mjoZZNKeTgshVX294jUthnZNXLtEfbmFz3 mtJ11/F4CNIqmnmzslIZQ/wBHEiPnSku+CZd9FJ42SUA/S8D2WVk9dJTH83znp2szj X+tYvga5mL7PMxVuhdZ4qRTnhdoie2R9RQK1IXdcRREnZmOg3JmB7BMqM3KjQkVkXS 1c3RZQdYe2ct2OWFR40DjT/mYohPKTIywowMCOQ062RSveZb4p8qrlCnV30yrFhcG1 tE9hDXcYABSzw== Date: Wed, 14 May 2025 17:59:48 +0200 From: Alejandro Colomar To: Peter Xu Cc: linux-man@vger.kernel.org, linux-kernel@vger.kernel.org, Andrea Arcangeli , Mike Rapoport , Axel Rasmussen , Kyle Huey , linux-mm@kvack.org, Robert O'Callahan , Suren Baghdasaryan Subject: Re: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe Message-ID: <6eobuzkwm6xhpis4s52dtit55fws37elv5d7zygaf64czcjag6@brz2nrc6qptu> References: <20250512171922.356408-1-peterx@redhat.com> <20250512171922.356408-2-peterx@redhat.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="yrfjxuitfb5sxxwb" Content-Disposition: inline In-Reply-To: <20250512171922.356408-2-peterx@redhat.com> X-Rspamd-Server: rspam08 X-Rspamd-Queue-Id: 0F2584000C X-Stat-Signature: nmpi6yg4dgwt1ypgubk85hukyin3mg7i X-Rspam-User: X-HE-Tag: 1747238395-537876 X-HE-Meta: U2FsdGVkX1++PZO24NDA88qPlLluAmidQ4LAdYJHV6FpMWFHAf/Flfi7PZFGMEB74Lcip2Cc7Ixv/5ENERPDxJRlw/JaOdhl05ftrUAHd7CovzMd2t6MfmwPXEbt8s1n9MK2AHxxEu91F0GSI28dhXDcR8+jniCbSSWfoN7d8uYpIhCij+zmk2MchgJaNyIin0FadN1fSXGOxAM0UaAoA+f/oJUBZq9YK8FxUjswy7z2onrfp34Ay/DWUlOGn0xjVB3KzYu/FKe2vdWzifCi87fO2iOBazgWlMWJFZ0lgYWgeEgqKVCQOyrj1Tljxb4DMoNHWLlwnKEK66QyQwYfXhb5gEyELhlT7xZ4cuxAuKn+LYRHR485mQE6fgx2ZwWjbfxECCNbDGvTKaiidwt5J11H5IglEfVTn/kaDun3utAbM12L9/mFmoJ/5YK2UV1RcIEm5mbMI7XGGMcilWttK6ywr4mCfbIQFeGo3l2CsEAOgNkB+zLN6RpAVIPTe7BNr/C7TtlFC+XoG+zIzVNud6gkKs4YUUtuHcfwp6UIj6Jkr5mut/c9aHXdd7PAWEtrb8SloL/4ZWhfyaOCWN7o7uariQikBgAdG9LNXmVLuBCwdoTwXpzir0Twr51tHZFAL5QFQlyt8eT12UUq8XYsjIc7t1IfAn8ZQVXvFKWlFfz3gCKbrXR+P1toi3a7Dee981vjZ7CW/ICYhqKTgy7QYVmNNPAXDf2NTALjz0DgzQS3Rk59oJbFLZn1Os4PLICZLl6G3hCP/3Z/5G13/QS12Gxs0AUIr/YSjbojQA63B6899uQ0970PGRO5zpxVTprHm/7GEmJEt99J5QOrmnbdr/2O22c6v7Lb5ilitvsUz7iIG/usvXWsu1MsqZZkKmYvspdjmDlG3/0M8Pk5sqIi7XOLbBgvTA7JCORopX2YlJ3UYxCbjKFtb2RZ8TWHNmsU3TgyezFKVZn/pIpgJuK DwqfWATO kvI4Qe5OKb2AInlWWA1x3UnTw5+/I01IT3Ja85bU1FIAcVuAA9X3GGXfFZO04mAgHk/HJ5M2W42SDYa/le32hm99Gi7iPeUPKE6hT4va4gwRsuEtL6ldXA+vK4Eb38tKjOPjYajKdvMs/Q+4dSfgGGmMojT1xWHbrWJy08bemhb91/Px8ZwCJ9SZvtSlDYJCCGuVU+oNZpDWMLX9HVs7S+hdbiWMi9iZtSXvfKZ681Tn5GH0I+gSVnJhKG9bu26shFiOV+BfVeccwa81NTaI54t+gaMHHOTw1C6Q/j4yKYgLrWADowstQYc0lxlq85e+jSRTAXguKAfINJMAI0r8E7LJ/CUbl/y27iYGe3esudDRMxR66J2OZ2uamsLItQS75Lq785xwKsiZ2l0ihJckfkI5pgaKlr2UirQ0dXysZojS6tGienC0I/JyRycpqXEDSF6Pu7ScW4wMhIITIIO+upIdQq3IRVwv7yMVK 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: --yrfjxuitfb5sxxwb Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable From: Alejandro Colomar To: Peter Xu Cc: linux-man@vger.kernel.org, linux-kernel@vger.kernel.org, Andrea Arcangeli , Mike Rapoport , Axel Rasmussen , Kyle Huey , linux-mm@kvack.org, Robert O'Callahan , Suren Baghdasaryan Subject: Re: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe References: <20250512171922.356408-1-peterx@redhat.com> <20250512171922.356408-2-peterx@redhat.com> MIME-Version: 1.0 In-Reply-To: <20250512171922.356408-2-peterx@redhat.com> Hi Peter, On Mon, May 12, 2025 at 01:19:21PM -0400, Peter Xu wrote: > There's a confusing paragraph in the man page on two-steps handshake for > userfaultfd UFFDIO_API ioctl. In reality, after a successful UFFDIO_API > ioctl, the userfaultfd will be locked up on the features and any further > UFFDIO_API on top of an initialized userfaultfd would fail. >=20 > Modify the UFFDIO_API(2const) man page to reflect the reality. Instead, > add a paragraph explaining the right way to probe userfaultfd features. > Add that only after the "Before Linux 4.11" paragraph, as the old kernel > doesn't support any feature anyway. >=20 > Signed-off-by: Peter Xu > --- > man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++--------------- > 1 file changed, 24 insertions(+), 19 deletions(-) >=20 > diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2= const > index 54b34a1bc..1c554107a 100644 > --- a/man/man2const/UFFDIO_API.2const > +++ b/man/man2const/UFFDIO_API.2const > @@ -42,25 +42,6 @@ fields to bit masks representing all the available fea= tures and the generic > .BR ioctl (2) > operations available. > .P > -Since Linux 4.11, > -applications should use the > -.I features > -field to perform a two-step handshake. > -First, > -.B UFFDIO_API > -is called with the > -.I features > -field set to zero. > -The kernel responds by setting all supported feature bits. > -.P > -Applications which do not require any specific features > -can begin using the userfaultfd immediately. > -Applications which do need specific features > -should call > -.B UFFDIO_API > -again with a subset of the reported feature bits set > -to enable those features. > -.P > Before Linux 4.11, the > .I features > field must be initialized to zero before the call to > @@ -70,6 +51,30 @@ and zero (i.e., no feature bits) is placed in the > field by the kernel upon return from > .BR ioctl (2). > .P > +Since Linux 4.11, > +userfaultfd supports features that need to be enabled explicitly. > +To enable any of the features, > +one needs to set the corresponding feature bits in > +.I features > +when issuing the > +.B UFFDIO_API > +ioctl. > +.P > +For historical reasons, > +a temporary userfaultfd is needed to probe > +what userfaultfd features the kernel supports. > +The application needs to create a temporary userfaultfd, > +issue an > +.B UFFDIO_API > +ioctl with > +.I features > +set to 0. After the Please use semantic newlines. Break the line after the '.'. $ 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. Also, please say "zero" instead of "0", as was in the old paragraph. That will allow git-diff(1) --color-moved to detect some movement of text. > +.B UFFDIO_API > +ioctl returns successfully, > +.I features > +should contain all the userfaultfd features that the kernel supports. > +The temporary userfaultfd can be safely closed after the probe. > +.P Thanks! Have a lovely day! Alex > If the application sets unsupported feature bits, > the kernel will zero out the returned > .I uffdio_api > --=20 > 2.49.0 >=20 --=20 --yrfjxuitfb5sxxwb Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmgkve0ACgkQ64mZXMKQ wqnL3RAArQyQl/1PS8j90oq72WHMTyButnCaNkBW3UnDNQbeIxW0tpDeJgSCjQ7i koP6uSRiI+OQxwS8k/O60cxRlL2uoLLMV0HMi/2yFI+9xqqmR4EVe2UYc1xIMId7 tg28KGCKJmrV9l1aK+KlNSxnS0aTeP8uSOPrIDk2Ucr4/00ssZNHOzO9cqh4p/9D iZSuK6G5oDPw0tuuh3yXSbzQILy9MGEO2H4V4RD6RM2F+4Okmz1OKPULBFA1JpzL 4V4zID7sYfADRV2JyMEj4JHr4ULWJVdY9lZoL7JNfkBd+b4ii1lAzsGPr4w+CASo xfBpE76BIuLyaJGfdjOP4U5m1TdiynUXNmWlcBkgRbvr/35aHFyD/ipAruGGf3cD 8Mw3c86k+QJe0/ZWKrK/CwKIq7u6Ol2vRb0rGuBORaIdS5DaTPcI+3Ss/QBMQfxX LFQ0mAsxNGxwy+JzajxBaTYd4nSZ9V+UpEdB9MO1bbo0SXiYBcDtCPU56aOKHYag GC6BKzZILWxdgMFwEaDPp+LkRAt4MD7WA+dfymnLdTl/I6Gdae97CdjeVnQokeJF IOa8lazizcfwt55fLQoNKcxov9oxnPNy7sE4EOjkPw1AMBbWXW4h/ABzm2ut0bub PDgVetkCBGTlWAxJZhvlt7dsDdh3CMPTnrOITTvLxnbq4cDgNYM= =o9YP -----END PGP SIGNATURE----- --yrfjxuitfb5sxxwb--