From patchwork Tue Oct 3 19:45:43 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Axel Rasmussen X-Patchwork-Id: 148046 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:612c:2a8e:b0:403:3b70:6f57 with SMTP id in14csp2312980vqb; Tue, 3 Oct 2023 12:46:15 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGWjcBLFs9blrArsaGS1qWyhFUqrnpZWqpwC2k7GIKpfwAd5KdyzvQwk5RdncRmXV4WTqMw X-Received: by 2002:a05:6358:6f08:b0:132:f294:77fe with SMTP id r8-20020a0563586f0800b00132f29477femr435373rwn.2.1696362374928; Tue, 03 Oct 2023 12:46:14 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1696362374; cv=none; d=google.com; s=arc-20160816; b=O047eMXIlEr4CEAr4asnOj6T70yfaKMhNwBgZwwjIhhDwu+Ij2bsqWk12zT5z/syGs 9DGBfPOoZGi+oL5jgjYF3IeQESOzsYa2OHrKclU6n2rUlWHaCh2iCwmm9Nge2Zqw6IWU liT25y9Jwg078fyDj0Dky5A9F5mMws61Qy8aKZhu7584tsg7usitIllaq+2cGcIcRFMZ Z2o0Y4DK+LvyDoFTZO7jFbDP81+mU7LfIKmLRCNJtzred0I95KM5sN+xuQSl4fbUK6NU qQQg6wubE2qFlL9UUP5ecBznUF7J9zy7Ok0U4zsJ63zVcGh8AOz/SfgvssRlX4HCE75h X05w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:from:subject:message-id:references :mime-version:in-reply-to:date:dkim-signature; bh=LZEL2BMjxz1i5idDbV1660WVS0O86XmSCyt1X5bcmDM=; fh=SqwPTGdhTS3wVH9FltNQ4n/lDM1p3ApEDnroT8zra0U=; b=sy04jfQ16OnyXdwYxt5mpM3aF+WNhe/+t7hD3axX/P3zkkwyUgLUV5nS6bB4FkOadI /Px8vCGLgg6oQEZqRHUoCXFIw/fqyG1Ybd1GSWuieZc5ZD4+CWMY3XFN5y6ZExpv2Mhh o9LP4NN3gGWsq66alHjIV/zu60mOB5aQZjG0WU/0Sy5T5hld02D8IwQZZDfvDe4IX4Qj a9HhhHbac541MGnLQlIPrsH/SC59khlSyk9NBeZEIKyYXVKifL+v/i1QHbNy2oSLtMem 1jL3z5lBJFPOXZU1upYxVUNa6OyG1fYxyLdhvH0uBJMTU3Ut+ybXhRf8Iz+oZYnhcIxA HGdw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20230601 header.b=Mq+RXsAd; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:2 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: from agentk.vger.email (agentk.vger.email. [2620:137:e000::3:2]) by mx.google.com with ESMTPS id k10-20020aa788ca000000b0068e47f319d9si2262356pff.280.2023.10.03.12.46.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 03 Oct 2023 12:46:14 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:2 as permitted sender) client-ip=2620:137:e000::3:2; Authentication-Results: mx.google.com; dkim=pass header.i=@google.com header.s=20230601 header.b=Mq+RXsAd; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:2 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: from out1.vger.email (depot.vger.email [IPv6:2620:137:e000::3:0]) by agentk.vger.email (Postfix) with ESMTP id B458C818CCB9; Tue, 3 Oct 2023 12:46:09 -0700 (PDT) X-Virus-Status: Clean X-Virus-Scanned: clamav-milter 0.103.10 at agentk.vger.email Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S240966AbjJCTqB (ORCPT + 17 others); Tue, 3 Oct 2023 15:46:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38972 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230502AbjJCTqA (ORCPT ); Tue, 3 Oct 2023 15:46:00 -0400 Received: from mail-yb1-xb4a.google.com (mail-yb1-xb4a.google.com [IPv6:2607:f8b0:4864:20::b4a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EE990A1 for ; Tue, 3 Oct 2023 12:45:56 -0700 (PDT) Received: by mail-yb1-xb4a.google.com with SMTP id 3f1490d57ef6-d81ff714678so1611925276.2 for ; Tue, 03 Oct 2023 12:45:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1696362356; x=1696967156; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=LZEL2BMjxz1i5idDbV1660WVS0O86XmSCyt1X5bcmDM=; b=Mq+RXsAdEu8Agt8QFclfS9ZJWQeyPjWgzORyR7dQ5ZrZPp2vHmiXbJ8Hq0EpBo7Bjm DYaSmQPC1pDTdIxAGyi+usEAYI7R/RqxhbshCoE/FO/i6WfTuEF/WukwvjRfHVN85UrN v4fae/nl9HnRZZnb5Mi3EijH5EH3/ntBGOSXkDECrLT7KvigehvgWLyP5bvP78N889rC OGsVX1N6VIlUQF5Y7NU1C5vUlAhG4YW77ueRx0S2I1zYYj5Qcv5vKOsDRiglJTFK7Z8p sfnQH9Tj3M8uHD3OHsapFSGsUwwvZeyCSw1l+DN30ac1rAIHut9N5EwZb3pL9nZWitjx A2gg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696362356; x=1696967156; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=LZEL2BMjxz1i5idDbV1660WVS0O86XmSCyt1X5bcmDM=; b=YtdPZ5mg32s/covbxD7CDZewpebcO6SfcJZDiNswGVTR6I1So7/yCMbDWGhpeROF4A +s+kBGjjt95SGJxOoavZpp5HrX09SsUcWtHeU4b8rlIYLy99lTrU70VE/KRcEnxtDOjB qom/1779XDaEjRNOiCCt+HOMIY09lcfKOOoECx3fLRneSd4k6zxtCqhxwiz9DjvERfzE UVFLEI7+dK74E/0ZfEf7aKW/WenFw117vIRKzfO2ct/O6g6iyCZFTs4XYdS6uqs8ezNK 4Hpp0Qx11AHy8fhsClC2niDF5GowVOx9bY2ZN8Oqnor13aYYnVgAUJ6dqu8KPrIRfib5 mP4Q== X-Gm-Message-State: AOJu0YwLQsBwSx820dSwZ5HANJpLkx9J+JYhOOyy+fv1NTUftODLfUhJ XLbmXBy3UREngV9Ur+cSJjGKJsElrIioLsP/rSAL X-Received: from axel.svl.corp.google.com ([2620:15c:2a3:200:6577:b8c1:dd2d:1c93]) (user=axelrasmussen job=sendgmr) by 2002:a25:d816:0:b0:d7b:9fad:6b9e with SMTP id p22-20020a25d816000000b00d7b9fad6b9emr3353ybg.1.1696362356219; Tue, 03 Oct 2023 12:45:56 -0700 (PDT) Date: Tue, 3 Oct 2023 12:45:43 -0700 In-Reply-To: <20231003194547.2237424-1-axelrasmussen@google.com> Mime-Version: 1.0 References: <20231003194547.2237424-1-axelrasmussen@google.com> X-Mailer: git-send-email 2.42.0.609.gbb76f46606-goog Message-ID: <20231003194547.2237424-2-axelrasmussen@google.com> Subject: [PATCH v2 1/5] ioctl_userfaultfd.2: describe two-step feature handshake From: Axel Rasmussen To: Alejandro Colomar , Peter Xu Cc: linux-man@vger.kernel.org, linux-mm@kvack.org, linux-kernel@vger.kernel.org, Axel Rasmussen X-Spam-Status: No, score=-8.4 required=5.0 tests=DKIMWL_WL_MED,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on agentk.vger.email Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (agentk.vger.email [0.0.0.0]); Tue, 03 Oct 2023 12:46:09 -0700 (PDT) X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1778764873678422766 X-GMAIL-MSGID: 1778764873678422766 Fully describe how UFFDIO_API can be used to perform a two-step feature handshake, and also note the case where this isn't necessary (programs which don't depend on any extra features). This lets us clean up an old FIXME asking for this to be described. Signed-off-by: Axel Rasmussen --- man2/ioctl_userfaultfd.2 | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index b5281ec4c..ef352a69d 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -82,7 +82,6 @@ struct uffdio_api { The .I api field denotes the API version requested by the application. -.PP The kernel verifies that it can support the requested API version, and sets the .I features @@ -92,6 +91,25 @@ fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. .PP +Since Linux 4.11, +applications should use the +.I features +field to perform a two-step handshake. +First, +.BR UFFDIO_API +is called with the +.I features +field set to zero. +The kernel responsds by setting all supported feature bits. +.PP +Applications which do not require any specific features +can begin using the userfaultfd immediately. +Applications which do need specific features +should call +.BR UFFDIO_API +again with a subset of the reported feature bits set +to enable those features. +.PP Before Linux 4.11, the .I features field must be initialized to zero before the call to @@ -101,24 +119,11 @@ and zero (i.e., no feature bits) is placed in the field by the kernel upon return from .BR ioctl (2). .PP -Starting from Linux 4.11, the -.I features -field can be used to ask whether particular features are supported -and explicitly enable userfaultfd features that are disabled by default. -The kernel always reports all the available features in the -.I features -field. -.PP -To enable userfaultfd features the application should set -a bit corresponding to each feature it wants to enable in the -.I features -field. -If the kernel supports all the requested features it will enable them. -Otherwise it will zero out the returned +If the application sets unsupported feature bits, +the kernel will zero out the returned .I uffdio_api structure and return .BR EINVAL . -.\" FIXME add more details about feature negotiation and enablement .PP The following feature bits may be set: .TP