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 0EAB7C3ABC3 for ; Mon, 12 May 2025 17:19:35 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id EFB726B0198; Mon, 12 May 2025 13:19:33 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id EB7056B019A; Mon, 12 May 2025 13:19:33 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id D4CB76B0199; Mon, 12 May 2025 13:19:33 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0012.hostedemail.com [216.40.44.12]) by kanga.kvack.org (Postfix) with ESMTP id B196C6B0192 for ; Mon, 12 May 2025 13:19:33 -0400 (EDT) Received: from smtpin20.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id EC7F91CC71B for ; Mon, 12 May 2025 17:19:33 +0000 (UTC) X-FDA: 83434917426.20.628A477 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by imf23.hostedemail.com (Postfix) with ESMTP id 1760A140008 for ; Mon, 12 May 2025 17:19:29 +0000 (UTC) Authentication-Results: imf23.hostedemail.com; dkim=pass header.d=redhat.com header.s=mimecast20190719 header.b="Zyso//we"; spf=pass (imf23.hostedemail.com: domain of peterx@redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=peterx@redhat.com; dmarc=pass (policy=quarantine) header.from=redhat.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1747070371; 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=GkyjsEBVXZql//c31Uv3m9eI0pp2by/4V63M4hl5UAI=; b=vlVEM6PZG23vV7dQyydZhQ4QrARV0B2XWDaAMzMvOMEMFqEosjrhuoS8/6zEBxpNNUFHTV l2fxGRLTNIeh0p/li4R2zs2jZLVMWoo3w/har1gRj7EEfjp0V9jUb02ZJRL1Gp6cX40Onc IATk8Ae75GSsYSej++qHtY52iOc7H14= ARC-Authentication-Results: i=1; imf23.hostedemail.com; dkim=pass header.d=redhat.com header.s=mimecast20190719 header.b="Zyso//we"; spf=pass (imf23.hostedemail.com: domain of peterx@redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=peterx@redhat.com; dmarc=pass (policy=quarantine) header.from=redhat.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1747070371; a=rsa-sha256; cv=none; b=M40OfQE+2E8qkGLBbgtXQ4sSiN+izcfUhOGN+6NniT/03ivgcqjefZz86l225ID3oc1Lac U/GHp0C9I+eGI2Q5gghOq9QJjf8iZyt+THF5S87XuQ+xdzecu4VmCvLOWooBAH7cjrcdWW hPOC9VRb4Cax0FFXsbNDOUinlVyLYWE= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1747070369; h=from:from: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; bh=GkyjsEBVXZql//c31Uv3m9eI0pp2by/4V63M4hl5UAI=; b=Zyso//weekUuNi3M8Pfhp9b4fz3XC7SwofUCRzNVslMX2ZJYYf43RYRGQ+XzFnUN2aPlkk yFy6CxeqPtHjB+iI32bJrvQOqLVruULcwv7KKbOaq62w7muMFgOEnLtUAtnvuTzGoI1bse N/cy2imt15dZDzGAEAItArytUlPG4fw= Received: from mail-qk1-f199.google.com (mail-qk1-f199.google.com [209.85.222.199]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-377-F0Rd0K3LO7uTFPidyrhA_Q-1; Mon, 12 May 2025 13:19:28 -0400 X-MC-Unique: F0Rd0K3LO7uTFPidyrhA_Q-1 X-Mimecast-MFC-AGG-ID: F0Rd0K3LO7uTFPidyrhA_Q_1747070368 Received: by mail-qk1-f199.google.com with SMTP id af79cd13be357-7caee990721so1061246985a.1 for ; Mon, 12 May 2025 10:19:28 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1747070368; x=1747675168; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=GkyjsEBVXZql//c31Uv3m9eI0pp2by/4V63M4hl5UAI=; b=lEwcM9sF5iDkRJagh6NB2hXmFCZqSdrNxH9FKdJ4P53Er3Lt/AV5PNpXAAOgGteDmU K+89dtSaC50/QXgq/cFg6U2RHSLLXOHW0PN9x3LX2NEjrbSBVY1WyvbrZLYedXAAZ4y2 vYfFjiyIM0yXpXPtnTnRyAADNn4rhUSegqGo482oD15u+swB/bJEwFlmtwlxE5qEZIyV 1uMepE0IjH2Nvij/S1vGtlVFbmluWahGHHeKmIM6ha2BSmg3Y7PCXZcVpKKfOEySQC2W M9mpt9KRrAGuVwZjULfFJ4+aq4DiaL9I4/sd/SAXArRgHwW6QU38TD2kCUz2x2CPBsqS W8Kg== X-Forwarded-Encrypted: i=1; AJvYcCViV7JGkTDHkshnVOlLrP/AjzGykMVXAZrE6+5X9qpsA5lZAn1wZ7pQjivQrAYgXW2gU6KdsrtowA==@kvack.org X-Gm-Message-State: AOJu0YzvIAy75JvzOEZy9ThJDM8a2CLfltnHKqRbIZfZ/O+CJSM/ThkY CRNxoxTIFRR7snRHomcXPQiuBt/t18Os9LzJwTFhIw/4zwWbi6vr45J7bsLeN1hfAFuYP+hPGYi Z4BLPNatMS64LNpJniYKNGLiXswIDcCt0lWDQzFvXN25enrpf X-Gm-Gg: ASbGncvKzovgmJFHeL8lmUy9sT4EMpAjFaoFwWMCY6guhR9RoK7PBYurBL1EL480FGk yZhZdSQlDGyv8ye91CQg2S2/VmDOr5sqoiMvQYYoh8blEFUOxKP1NKSXRmDMm6wpSg7WOoNFnyd ZY//MdPDVQn9+dfDxrfsTBoORBI/uJJOzVXOPL8wYw9LD8BaTO+iOtArMXmS9TN588a1T4yNL29 bFqPKySssJaeeo8IjQKSK2YvEcQUSzd1O7FsqkaWQi7L9bK6UGL5cPDD479p96jEWkGL0o6uVvh X-Received: by 2002:a05:620a:2690:b0:7c5:49e8:993b with SMTP id af79cd13be357-7cd0117903amr2600636285a.56.1747070367619; Mon, 12 May 2025 10:19:27 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGhXHfrlA0sTV0PHOWBuw1s2FByKk5Y/Ebo9kg3frdH6FoHXH39u54Ko2H7v00+/RU+D2wJOA== X-Received: by 2002:a05:620a:2690:b0:7c5:49e8:993b with SMTP id af79cd13be357-7cd0117903amr2600632085a.56.1747070367162; Mon, 12 May 2025 10:19:27 -0700 (PDT) Received: from x1.com ([85.131.185.92]) by smtp.gmail.com with ESMTPSA id af79cd13be357-7cd00fde7c9sm574237485a.75.2025.05.12.10.19.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 12 May 2025 10:19:26 -0700 (PDT) From: Peter Xu To: Alejandro Colomar , linux-man@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Andrea Arcangeli , Mike Rapoport , Axel Rasmussen , Kyle Huey , linux-mm@kvack.org, peterx@redhat.com, Robert O'Callahan , Suren Baghdasaryan Subject: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe Date: Mon, 12 May 2025 13:19:21 -0400 Message-ID: <20250512171922.356408-2-peterx@redhat.com> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250512171922.356408-1-peterx@redhat.com> References: <20250512171922.356408-1-peterx@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: pQvax40N6uXbp5BRv4CahwQVPqsI8dEr-BhIE4Qc3N8_1747070368 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit content-type: text/plain; charset="US-ASCII"; x-default=true X-Rspamd-Server: rspam10 X-Stat-Signature: 6njz9acs8dsuu4i1z3yxqusqi6171jhw X-Rspamd-Queue-Id: 1760A140008 X-Rspam-User: X-HE-Tag: 1747070369-852391 X-HE-Meta: U2FsdGVkX18oHBoNd82khI0FL/mzQIIRkNN9aXweD4BNNRCI4CbYM+utIZ+DSwilGGPlqzAt1fKMl3DJwk/TSztQFhpBaiCnO6JKlRpHRtlbGdqjY65yW7H/Oti44hoH/Ylr2eh11TT1B/d5Utt207G3icxxO2twlfmYlgi11KkZi9cJ4mXxAcR7rHS4hh7kc7eX72TUwON8gdCW7SY0zYq29JzSfq850LxiAbgHMHfONkwQB8jPUQR08h/BNdBSVEjOjSjnxtoMk3ZrwNW1umsqX72Vlj2II0vfj0gGWUsbzdD0H4CROR/iho22kCivsNBdg0BXA2F1ljLWuDplxda8UDxz3Q0r38HHb78/MgJ1eNJOHgRlNi4T/Cc+XPYW40Zba8ZB+vPCzzfvFC33WZZrwXiIs/aWIjREbt0DEIooecUFvxjX5C4xpLtcYy4v1LnsHDPBpqJaznbqdkBCC0roIB/gKYf3309ltwzH7PfcblRGG6wxlNiV0K3QhmbkXL5Rtez2lkkixsB5NJxZmGzhKbkO1nUHjO9RBz5z4I4e0ZxvLdfWo73t2zQoxsNG+YQrNjW2BWKo3ekoVzCoZBKLEFSYgHKRfhf/O4ok2k9WWT10b8qMnL+rByisCqrdTh7tPBiK8dH7DD2Jf40p+R9lCdV+9IfajvNI/TqO7Qdkt9XnJwMXfw53lGfmAxKPvGGEGcp6mzuAuUqPel7ecN9vtBAjAXdMFBbosH6BY5WOa/65TbRmYNnzOGiW/TJhdgQ1O4bEvvD4SnvXov+5zIK8sbE+SDsWZNs7Wuu0etc5CM7my0QyV64t1JWdDhZ33PH1M5MJ2LmPrkpSJmFYuaUeSC8m58CwVewVM6yT1/RhGeuCMaE+C+qOag77gDMTCmU06EdSgdFM4OcqcnXofGp68mAcE++tBVn50szwvymrGKsCYm/mSKSNhPaHVjO3ILOApVsuvEYhmAa5hmu PsHYgJan 737+2nmRwAVy+kP3QA4d4O7fpZ6qCvaszbDEfN5fSCjB2n/hGPQDb91JJfCFnaSgtn0ByBNel5iqUgMw3ZGvWvQxwMBFEkuZwslymIQ9yedWSbNGH6IKAAJwLW4Pf6SRoWsIiAxbwM+fJwLBcB3sqhSUYhikON/N4U/uJO8YOotKpd7MXaJToyEhIvU8UBZtYfYCsuwKUrq7yWU73omUHvbA4ML74pqf9qK/Hrr+igClCTTDYJ93bLeDiYrCNdTAbciHY6S5NVOkOtpYyVSAGuOZ+VGdA9ZwELl7BuZQpkISiVjfOe6oRqHnSY2/r948tupjkxysJiq8XFrHSCHk8zRBhyK/ZJnfQ9nlN1VRbDLyBO/EdaVSTCCjQk0jZFmQx7AAsv7mR3qmHXQ2jko7hctMJPdMBTM6cBs7fNISRPpUG09zO6aRw7RvBspip/n+haevzqry+1roLUJofX4OA7i1vdO61nAKIN7rHxxpOmGDTrnsauUqS3G3XNMxQX/AOT+aVTd817OBYuFhdyA6Fr0xDY0b+8XfpxA0/ 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: 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. 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. Signed-off-by: Peter Xu --- man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const 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 features 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 +.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 If the application sets unsupported feature bits, the kernel will zero out the returned .I uffdio_api -- 2.49.0