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 BF233E8FDAF for ; Tue, 3 Oct 2023 19:45:59 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 556FE8D0087; Tue, 3 Oct 2023 15:45:59 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 4DFDF8D0003; Tue, 3 Oct 2023 15:45:59 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 3815C8D0087; Tue, 3 Oct 2023 15:45:59 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0013.hostedemail.com [216.40.44.13]) by kanga.kvack.org (Postfix) with ESMTP id 1F5408D0003 for ; Tue, 3 Oct 2023 15:45:59 -0400 (EDT) Received: from smtpin08.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id D424E1A02DE for ; Tue, 3 Oct 2023 19:45:58 +0000 (UTC) X-FDA: 81305180796.08.AC13335 Received: from mail-yb1-f202.google.com (mail-yb1-f202.google.com [209.85.219.202]) by imf10.hostedemail.com (Postfix) with ESMTP id 0BDC3C0024 for ; Tue, 3 Oct 2023 19:45:56 +0000 (UTC) Authentication-Results: imf10.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b="AxsxqF/m"; dmarc=pass (policy=reject) header.from=google.com; spf=pass (imf10.hostedemail.com: domain of 3dG8cZQ0KCPMVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com designates 209.85.219.202 as permitted sender) smtp.mailfrom=3dG8cZQ0KCPMVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1696362357; 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=LZEL2BMjxz1i5idDbV1660WVS0O86XmSCyt1X5bcmDM=; b=wfhLOibPAqRQdt6jRoYrBs3GnIpJnHtpybJ+8RK2lHc5Fd1B6eLOpHcLoFTerhxwGZXq40 LMYOlZklQBeFaf8mlFYZWytR7Beefts8n0Qq/pmYNPU1tqdvIIZRRw37QHSvjT75I6EKe+ HT4Zpz5sP2z2G5MWW2W/qrFpPYW5p5g= ARC-Authentication-Results: i=1; imf10.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b="AxsxqF/m"; dmarc=pass (policy=reject) header.from=google.com; spf=pass (imf10.hostedemail.com: domain of 3dG8cZQ0KCPMVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com designates 209.85.219.202 as permitted sender) smtp.mailfrom=3dG8cZQ0KCPMVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1696362357; a=rsa-sha256; cv=none; b=vjdZPyYmKhhm5QXWj3DhXKM2gK8yFHPGYe8tosaQxRilzAbnJv2ptiET+db4vWF6RHvduU X7Y53QdjR+n7H/u0ezF7X1sALgMLT8DjHTMjwdypWs59/lMF00TVQ3jv4IlUBEvkDG7C4a 1qvJJ5v5UDXK/1UFZ16d8EwY7oGkSXU= Received: by mail-yb1-f202.google.com with SMTP id 3f1490d57ef6-d8660e23801so1607731276.3 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=kvack.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=AxsxqF/m0cSiLwj15noVP/yHXahaNjPFFo+b27yZvchJJR3O390fLxsg86QTWFL3F9 tlY8XA4VkUUVD6MCA+4fmq6CS9fqkdfdcu4Jk7wFyLli4pK/6zKWbfpKm8Idy4ZnNuHs EpfEeTTqOPuGNPT3CB3zImnwLsBmdevBg+/7+JJFpcDoxpQw9r0G1vuA3blEORKfqv1A /R1DyL/1LE6NxVwNQzkeiJpCpkVhFVPYognVtKbWyDtmPbChK+cFoPLhMbZanqsSIv3b 8OK/ry1XqVIdw82mxZbQcaKoXDPn2b5MEbjzSektnBcpoaGvDYrqkDDUwNQSlwJpDXYX bavg== 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=QDyUMTpO5ofD8d4lFRc+mN/YaDbtvC1kFzbnTjTCdu2rjnyH1B49xaHkdUYMyFkmmL l8m/l6xsEYgBurDzhU7qBcZzMHg99qDwTTVCDDOWf5mIE40P7JvuUsrJ6F01lj66Q/jR /y1X6VTBbqQtQj1QA8araRzH9VVgPvaFGaaEQpAJHW+Jk9poTf6P3Vu2s+DQMRI1awyJ z+Qad8wu/ZBV707QUGi4C1kQRmsB1iOp7E+EWtsDzuHDJogxFd9W6etGZ6SV8oAc36KA BKT0YWi2MN4V42kNL/fKwqMzCtqKycFs5HUG5WnRKRunDFMG0krXHo8tr5t5zaJtCFrC slOw== X-Gm-Message-State: AOJu0Yxo7kd8R3UD2lGez1XfoZ9rGsoVJrznvXggoMPh7qTZQzFCKo+Y CFwVpU2/FVZHAeUghY2jREnJv5K04aN9eq/oSHX5 X-Google-Smtp-Source: AGHT+IGkq/Yho3MXhu4mjlOqZnh1sbMKJRwQFyyu29+TZYNFidmM+AVkw+octliNf2IRJpTmHxGFJHSGs+YhAb5n0ehq 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 Content-Type: text/plain; charset="UTF-8" X-Rspam-User: X-Stat-Signature: gk7nto8ypo1ttguu3g7sbgb96di8qkh5 X-Rspamd-Server: rspam07 X-Rspamd-Queue-Id: 0BDC3C0024 X-HE-Tag: 1696362356-479227 X-HE-Meta: U2FsdGVkX19LgNiVnn6wbI410ZqhC+V64Fzmu1boR+c1RnCyytHb3khiE9u83hreTvlmpzYOUUrRKvdv7KD3UrzvJLoDPP00VwbcwTA9/PpRfee+akH1kuZ7JC9dwUT5X2u2gm1tiMVu5p6jNHbp+PCkcLrOuuX0XN/tcS9WyIHekt22M3jDRIFIJxxPYJENXtLSD8L0wRq56IYTS9CfdhMt67M+qw08bUFNbh8UHXE7HMcBxKmMOYR5YPpKXhGbHEMQMSqxFiKHyqIHapjvXtz3m0jVjs5EJ7RLazagmD07ZSeXDDUNE4PRwup9hQjDXS3FNJDl7sbEMk+7cNq5yLs4l/bpew0pcKAl1mpxhJA7FPfRP67D+nrUxc6WzvyTkFRRBJjQCjvz97nXPipLJdQV1QXuAvtoQEb/7oiM13qCkX1gBruQlyap3Z84CYQfdXJY5psMFPKqrYaFfUYmtjq7X8YQby2VDN3f/a4NNnUxYfhdsMEdnMcqTDnSqS6B5zG7+HFeUs2Vd/7BeG30YRFSG/nwyYcLLZAgni8V6rrfnhir6G9jlLJbfvFrcrYj31D8RsD5Tzz5lWwHxVUoLnNlWzuM+iaBr23PKJGJfvaOzPIjuD9rPqRgYhHECk+4NKD8odctiGgURovrCY1f9y58+uDS6pMxC6LEZw7d0pIfShqck7yiB44L/gbImb8mD8v+Xll86YohfOl/I9qHPSd0vpNU3Z5enTacPFRuo0iyRyt60RN56x0kVWdi5BUQTjUEzTG7TWFCBbCNCZNzmdKZ2MHkoLc9tpdXCXtC6euyLFRUTtGJ2YvUexTgpqG7YAq5XFxWtuDKobZYoGMXT7fwDbj+C3CzST+tniguB62Zdt4SMSUf27KJSjZLRg9ml/L/M0ASxNHBoBv+nhmi4GjNmpUePpoOn4WYouMjgi2joszdTe+sHQoJ2B9fJLamUxW28bNAFqwObJapH1y CjgcJDE8 JKgsuXkCqCXrwTO3gw2K8FxV9tbUvR+QMrLEFalNYI25+roHu10wZrKYkX0e17qn7gXO4UaNfjBBGRv1RHXmDd1yn0gM9Yc9Cv6CGroWEpIekJu1YzrlQJC2thoKga1mpa88Sx54Aj5rR4NuQsLmqkDFWEsKXeuULhfZeV1wAzC7soFoDTRe3HXAi4Qz+bcQvNvVa6LA3WbFunsW0TmNrNKc8QovusulVL0Y/MSeOeJsnvMyHGGqpBASxCf2toqPTgTzgtWc2apY5B6arFGgeecQlpBZWqXTwekiRCrM+7mnpO51onXzfZHFZX+CsPnOBRcFoqRViskly4dIzz2cOnnKFtKFEiPVhtPbURVchY4LuI8jNMRGx/Fn1rPjoSv5xh+CGPw0NbLTtv5lyp8R7uQns19d/QS8t0DoVIe1xNjQPsvms1qnWr25TjRhgiGvEjKIBcws9e+8MyQXFilu4gDfBkbuE9rbYLxxxLHb3N8EaTjLrzcZ1sCAc//6HnLvaoZ4GwaIpd1AzJkN0fPV0+Q2RgeYOXkp2qVzsigHAh+TTRM9+U1SJ/PT2nrJRuYwBmjOgx/123dQVAMtYzeAZGHwJzB0rKr08ze/xkG5Wtr0ltJU= X-Bogosity: Ham, tests=bogofilter, spamicity=0.006867, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: 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 -- 2.42.0.609.gbb76f46606-goog