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 45F61C3ABD8 for ; Wed, 14 May 2025 17:26:42 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id F3A766B01AB; Wed, 14 May 2025 13:26:40 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id EC3096B01B1; Wed, 14 May 2025 13:26:40 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id D3C3D6B01B3; Wed, 14 May 2025 13:26:40 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id B1B1F6B01AB for ; Wed, 14 May 2025 13:26:40 -0400 (EDT) Received: from smtpin03.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id CEF98E28C2 for ; Wed, 14 May 2025 17:26:40 +0000 (UTC) X-FDA: 83442192960.03.496D44E Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by imf17.hostedemail.com (Postfix) with ESMTP id 92F9D4001B for ; Wed, 14 May 2025 17:26:38 +0000 (UTC) Authentication-Results: imf17.hostedemail.com; dkim=pass header.d=redhat.com header.s=mimecast20190719 header.b=Qn3MEE2m; spf=pass (imf17.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=1747243598; 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=UUvm/u3j4WG4wsWjGgjYX26cY2cuBpZEhtt9a/KRMUQ=; b=JiamxMKat9j6M8KCpXZVQ6/SvZVdDcUnxecV0yJdjPENWG1BnwbrNNITJjc9jJXhjzbrBo Rc2lp0OjzoSmfa0/at7N+NAiXAnWYN8NMGiB/fqwhIy/VaheorQzlmpLudxi2hr68x2fGf V/P7jD/woSBbWIcasIxAAXiTYIdLJTM= ARC-Authentication-Results: i=1; imf17.hostedemail.com; dkim=pass header.d=redhat.com header.s=mimecast20190719 header.b=Qn3MEE2m; spf=pass (imf17.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=1747243598; a=rsa-sha256; cv=none; b=hRO+aWPH23zv3ajaC4ZGJUiAm4MaHI93A2GIpJ/zds4Xgkx2qR123k02kTLT6U5s1fBk6X W2vU5DS5oCQ4waIhGDNJzokW7t+tj9stypSG38Bcvq+GzN1RLk2ITZiXFqJHFxQsqEfJZC u3sXrusJulhcG4kv0oJHiY9KV/GhGXw= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1747243598; 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=UUvm/u3j4WG4wsWjGgjYX26cY2cuBpZEhtt9a/KRMUQ=; b=Qn3MEE2mzjZP39Mgrec27hI0P4uffNYGHsY5TSZmVinEVevqFQaQCcXOCPphiUDZoGcxU1 qD2CwIMFkiHgUaOr3vKDFe2TXlT9AHfI5YteXo2p6tHkoPQOG28alAqK6M1qtiviWKv3pl ng4RWOG3XSHYCpUfMcIBfKLJOZWlb/k= Received: from mail-qv1-f71.google.com (mail-qv1-f71.google.com [209.85.219.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-615-kGd7_r35NeWbQtlVOcQOAA-1; Wed, 14 May 2025 13:26:36 -0400 X-MC-Unique: kGd7_r35NeWbQtlVOcQOAA-1 X-Mimecast-MFC-AGG-ID: kGd7_r35NeWbQtlVOcQOAA_1747243596 Received: by mail-qv1-f71.google.com with SMTP id 6a1803df08f44-6f6eba61cbbso2207806d6.0 for ; Wed, 14 May 2025 10:26:36 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1747243596; x=1747848396; 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=UUvm/u3j4WG4wsWjGgjYX26cY2cuBpZEhtt9a/KRMUQ=; b=ciNU1bax35DgDn1OCB21Rw858EkYmdi/i4h7zcl6tRgL4U2b0UnfOiHoix8MqM4oXc 2D9/wDJAdM3iZZvPQyyW90Lz6ow5NRvdGYC2jwBeNgnW2EMRwcDFlXbPlVlXfSAVypAs VaGn1/soD7xa1uTXSBG4CjClYqJVoYVY3jqSxJss8FKuBRw+JQyyV4u/AFDdZarXngvT Xl3u8vua6d9y9G2srVeFZ0T7ouTPlfT4nIvT6LdZI+fcC90XySO0OkplgRXB5t8/4icr zoqGNQjDJ8DjE6v7oKsMlrTQdeGoLgPJfQsWeAsUhjL3Vbnnv42kylxyoUwByXy+RLQb /szQ== X-Gm-Message-State: AOJu0YwHUTquU0ltct3qitkgY1UYbof90UTdYEmX2+dTb+10/v+CFyWX AbefsB5jqnU3uZenQUqGQDwufAbn9ixBbpDYOC5J8gMnY+tQJaireMpsT8otLF9rZ/5Sf62aPuM 4a09ylNRfwlsKklQDQf/D9YmUpHfQrHvgZL1WtYAzJb810t9B X-Gm-Gg: ASbGnctlHAl0bYPcn3PyuFj/QnlsaRvXQPa2lt7f80fVXrlqjaOjtBTyeQTY8MuB1Rn f6vyAia4TyNojWrV2+QxDsI8VgZSPHF6ihlPFWvlWcPf/2KhPpDnG1n2fje0Aun0IXFZqlUo4dy FZIbmY6U00peNo6A6qhCpaALZtplb9ln8MH3qp6y+jB0iEw4fMJFcNz3p2Im5fV9bQaukir8YXJ ILAj/yr14kls9lUJSJCN0GZOFTeuv6ASHwc2HWApl2wiU6lMvpSbeDYYjz/CmupswT6cDbVTQA2 X-Received: by 2002:ad4:5d63:0:b0:6e8:f949:38c6 with SMTP id 6a1803df08f44-6f896ea8adamr61212516d6.33.1747243596171; Wed, 14 May 2025 10:26:36 -0700 (PDT) X-Google-Smtp-Source: AGHT+IF4VMBew+JPLH9FJWsO595OxibhOLiZJaysAzZGkfUGJuxyv2GUW6YNb7ys4nHClDclSmtNPg== X-Received: by 2002:ad4:5d63:0:b0:6e8:f949:38c6 with SMTP id 6a1803df08f44-6f896ea8adamr61212246d6.33.1747243595805; Wed, 14 May 2025 10:26:35 -0700 (PDT) Received: from x1.com ([85.131.185.92]) by smtp.gmail.com with ESMTPSA id 6a1803df08f44-6f6e39f4795sm83590536d6.30.2025.05.14.10.26.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 14 May 2025 10:26:35 -0700 (PDT) From: Peter Xu To: Alejandro Colomar , linux-man@vger.kernel.org Cc: linux-mm@kvack.org, linux-kernel@vger.kernel.org, Andrea Arcangeli , Kyle Huey , Robert O'Callahan , peterx@redhat.com, Mike Rapoport , Suren Baghdasaryan , Axel Rasmussen , Kyle Huey Subject: [PATCH v2 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe Date: Wed, 14 May 2025 13:26:29 -0400 Message-ID: <20250514172630.569788-2-peterx@redhat.com> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250514172630.569788-1-peterx@redhat.com> References: <20250514172630.569788-1-peterx@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: IsrmYHR6PoDqFeXrBl1wYxB7cS_Bk70NaNYimplqYjo_1747243596 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit content-type: text/plain; charset="US-ASCII"; x-default=true X-Stat-Signature: sq8bje7qrj3nemy8ns3btzzcdbgnwmim X-Rspam-User: X-Rspamd-Server: rspam03 X-Rspamd-Queue-Id: 92F9D4001B X-HE-Tag: 1747243598-479569 X-HE-Meta: U2FsdGVkX19y+viDZxfye78oEd7XKNETrCJ3VlmEXz7zV8KtVpfkBrbxty8U6q/hBNagtB/ENUrDQn/tPZnsi4QJAr/swUL8luq0/HUVsjWI1jlWjsu/134wecWef1o92ZmKZgEWiCQsBP4YQk5pv6mV+YVg6ZVOUOP0JZJj6gn1zUTGPFT/HPPxqmshuWE8dtfZsDav+DT2tvJ9Osa29WqqiwZrohSFZg94r4nfYf9VTt71hc2dbLQCzCzkwLK+ZQ5NyJX9LKr+m5ZSm/2Ok4jOzolgK24ES4fcsaBR+UYyt0u0/SOmcxdmv5CDEBcPOFYv/6H7me4bS6FuI8CZORGuhiYd7OtPXu/9i786qGB6oGMx6qmBCt3SgwHYeHU6et7Zc9ug6ZE7vqDUWiYXxGFKM88Fu1D3EStESSNnH5ajFL8kok1l3xkdBfFmM+kGvkDw7J/DS71WZLM9RGj2PsqtxZUPPHEgxIu+w2LIaqbo0Sr3h9Z7cPPpw0fUbclNRajEjsR/QWzspR409SQqeltDqJ/O7yKOGeukwPXRhYgiWIfj9pjAxybKKzt3oWQVh4CFjQRwnRv+ooBY2kRirYwt79b0qa3pQQbtDugH/jJpI1RRdAOj2yvarot3D0KyAo6ui6LiBly0SATBO9m9SBHE/FsNsOHJpQPWFDsHJbPW4Fr2ftXgUdLVx0QZTHgNqZzOJShGKRpqRXYJ3ZLjal1vvBmOQ3Bns31oPaLsce5m2u1gx6bNv7nqsdhUhViSngWfSMyOkLywUEE4MX1xXmSlkl5wFhsjFpO1wfouiIL+kOB91jjjp0YHMxirFMF5t03MfMvxWchbDJVNMBrZRvJZUbJxbGzD80W9XvoQUPxfolYzbeyjVGu+lvI1FrQNvBCttsJBg1wXPDqoFZ4iAkOhG1lQjV/vaVe1Yje4Ogwhkfs7ruJwXcAP4SS7aQyUij06/4ih3Omo/oKMhvo Yxxec8gJ l0PVtL2cOlmSHmERCNFt494FiZjjH7TPzEBlG9GsyU+uWrJS7B4AWWVn7+MPvIarA1Kqo8ZifILcyzrDj5xO/jKScxe/Ulm4/4OEV+kA8ZXoRBcKr1ilCCnvaxNXldXKpYUN5PSDewTYPl7qI7OhLHWnl7k+4Sc/OWGP0VasYR8sPwdzifEXWDj9R6Jl0Vjkq3zWps73CsRflwrKXwxV8LjYOfEo4nejk6uVxpgPYmu8XdznOUrpYW3UINLuD9Us7X+k3YqBXzv0EJKoKiIT7rJ80geIqNyLh3cCAMEsQ9vQ4p/E0jbwJE6RCaHQopT0A+/96eK5VWXK6opHykU3vFd9k8p30A//4X1uzf9Xp7xKPhd/JQyNp54HKadGl8/th52pU+nyYElX8pGxjMEV7pyQgGoWwZFtMS4nPA0XKotdkBfjsR/ooEm2y4K12GC9Ei4Y2e202ASHDcJ/MjYGlRUaSR06gHGeAIyqL 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. Fixes: a252b3345 ("ioctl_userfaultfd.2: Describe two-step feature handshake") Reviewed-by: Kyle Huey Signed-off-by: Peter Xu --- man/man2const/UFFDIO_API.2const | 44 +++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const index 54b34a1bc..aca27dc5c 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,31 @@ 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 zero. +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