From patchwork Tue Sep 19 19:02:01 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Axel Rasmussen X-Patchwork-Id: 13391774 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 609DDCE79A8 for ; Tue, 19 Sep 2023 19:02:27 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id E5CC86B00BA; Tue, 19 Sep 2023 15:02:26 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id E0AF86B00BB; Tue, 19 Sep 2023 15:02:26 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id CAC3F6B00BC; Tue, 19 Sep 2023 15:02:26 -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 B70536B00BA for ; Tue, 19 Sep 2023 15:02:26 -0400 (EDT) Received: from smtpin05.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay09.hostedemail.com (Postfix) with ESMTP id 912C7806AC for ; Tue, 19 Sep 2023 19:02:26 +0000 (UTC) X-FDA: 81254267892.05.F904825 Received: from mail-yw1-f202.google.com (mail-yw1-f202.google.com [209.85.128.202]) by imf21.hostedemail.com (Postfix) with ESMTP id CDBED1C000A for ; Tue, 19 Sep 2023 19:02:24 +0000 (UTC) Authentication-Results: imf21.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=miRqSbZF; spf=pass (imf21.hostedemail.com: domain of 3QPAJZQ0KCHcVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com designates 209.85.128.202 as permitted sender) smtp.mailfrom=3QPAJZQ0KCHcVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1695150144; a=rsa-sha256; cv=none; b=Vkk5+HPNdozMdsTwEZryDFYsn+K4ymJ848mXgC2vgG2dq/TZJbaqvudcj9vnEFZtFCUKQG KBGnkQtsA9Fki/j4a7EplzXVnlyPe9LoieoZux1KKdTJFnLBQjy2ySFPDtK3H+Lx6CA+6k 4Mq2vpXPgeYg0teF+xFmYEgiTZSQHvA= ARC-Authentication-Results: i=1; imf21.hostedemail.com; dkim=pass header.d=google.com header.s=20230601 header.b=miRqSbZF; spf=pass (imf21.hostedemail.com: domain of 3QPAJZQ0KCHcVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com designates 209.85.128.202 as permitted sender) smtp.mailfrom=3QPAJZQ0KCHcVsZgmVnhpnnZibjjbgZ.Xjhgdips-hhfqVXf.jmb@flex--axelrasmussen.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1695150144; 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=yByc+t8MiUd/FlhKNAv002747b3UkcfIteNK5wC98N0=; b=o41gc5BZGtwufl+6u6myzea99MQ6ygf97voW7iv4mptgNb8ZHiinOoKVqRQLoaoEHw0BhU BgOxO4THTkhRrJFeWva5kUJ608a4RacTUd8cmysJXb2a0uZLROjjQtnM4Uh5Y49BLPnuVo K32/6sEsbc5lnO4WwVdGs6H12Fv4dGs= Received: by mail-yw1-f202.google.com with SMTP id 00721157ae682-59beea5ce93so2663497b3.0 for ; Tue, 19 Sep 2023 12:02:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1695150144; x=1695754944; 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=yByc+t8MiUd/FlhKNAv002747b3UkcfIteNK5wC98N0=; b=miRqSbZF83uXZXHvw2Vx57LlCxSLL74UsDOVCJWO/JfCRLGSbrST/Kw78fQrQ9r1MZ gfpVdzYQj6N0yWLTM4jXbegKOnyy75I9uJ9rXsT6XIx2RXpMTMyWuIOgyg0Q1rofKtn5 end0x8amKHozR/4Qd9DzrpLTn3+qct/Cyz2wqOnGRbs99zZlCu1UOmvC0sV7PMMKPgOz w28V5XOJROXtZ0EODRTgwmfnmFE3qK+0m72t3rT04E3sPc1xJ3YgA4Ew0isjLtWPKxiz UMM6qgCREoNFFFH3fb3vPvXrUUg0P2aYs4/oWPPXSm+CfUyUBpukxR5+prPccY9CFVoD G64Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695150144; x=1695754944; 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=yByc+t8MiUd/FlhKNAv002747b3UkcfIteNK5wC98N0=; b=smAi7U5S0wO+wr0Mh1hW7XDlb1AZqgRG4Mk7bFFoB7MLeGlm2HaJVnYkweNBq8Kll0 GW0+EP9XnbC+oiiXcoBkcx5wTKT54hw2y535P5VoxiSsWVHsJ/4znev9pvlYIXmK1sdM vTc9F39LJcyEfFdOPpb3oxUD5e19CL/EIn+Zb6g6GuXSYX+1RO/EpNHnN/aJfsYjy5gE fbB72uViVdrlaDJxhBy6ScznFuuzWnWQx67qBGfKn/BJ7RaN4WP0tZZqvkg15g43AYsI V7EqY6NDMqvPmUgyUpsIGRVJYVp7Bo6f4Jt/NGDY1huuDDXJ0MGy6lPe3YrMbzeRLwFp z7Sw== X-Gm-Message-State: AOJu0YwAVhj6/IIprT8OESfJiq74QzPHlZnR0CrX1NJqqFP/i/e+JgY3 ktzsTO9VtOKyuJiAb7qrMiN6EqV0lQMy6saYl78M X-Google-Smtp-Source: AGHT+IFoQhXcjpZz0tNIspX2HizUbJrBHJVvEou6jQsnzb8YUr35yLjePVG0NBfJ9xY4w5XR/FlOcKZy982n0Y9YdDP2 X-Received: from axel.svl.corp.google.com ([2620:15c:2a3:200:8f5a:6a6a:cafc:a3ad]) (user=axelrasmussen job=sendgmr) by 2002:a05:690c:d8f:b0:59b:5a5b:3a91 with SMTP id da15-20020a05690c0d8f00b0059b5a5b3a91mr113072ywb.2.1695150144075; Tue, 19 Sep 2023 12:02:24 -0700 (PDT) Date: Tue, 19 Sep 2023 12:02:01 -0700 In-Reply-To: <20230919190206.388896-1-axelrasmussen@google.com> Mime-Version: 1.0 References: <20230919190206.388896-1-axelrasmussen@google.com> X-Mailer: git-send-email 2.42.0.459.ge4e396fd5e-goog Message-ID: <20230919190206.388896-6-axelrasmussen@google.com> Subject: [PATCH 05/10] 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-Rspamd-Server: rspam08 X-Rspamd-Queue-Id: CDBED1C000A X-Stat-Signature: rkpbezg8jqise5cuydfdzhacdqtuzszx X-Rspam-User: X-HE-Tag: 1695150144-425323 X-HE-Meta: U2FsdGVkX19YslEE4WWWeqhUks8rzfVrroEdLLIvbkDJMdPR4eR9arD8A4peshTVy5WN9aanN4qEjmS9a8L5W7WHglmQH1hYZgdu/+l8RsW0RuA57tQQsVIC31ioKMuPKzLvVGckDW09BSqjyGDao06iA7wpV7xilKfBLABUnIA5HRfkMxzltQX3+aDFElSiuCkowoL0XEc1rZMUbbS7BirjG+rK9a25KhRhxghQjZMcKlNL4xIP42WT5vDaT4TkTMWiKMB9a/suU+ZPsUPFIS4IQ8RWqOpMIPgS+lP9L4/VWx0izeQikIz3XW+/Q84Gzuu2Bngn3DAStSYubYuJ0/HmMSr5WAUK/NTBI24B5oGo6REZzGVky5zZxAWjisFQ7rJ04IMwbvKgiKojSzOHCwsfqC393xwiC7sJWBdccSCxPLoJ8QW2rZE/uwDDWBqmHizHWIcuaeWxjRnp9EQ1M9wbdWFPAey9HtJnjdzeTpW00Z7+f03LL+wLdcm/g5OsKYSkigRvQiBbliYq7Ii6qlOywO0epSq8DMwxPxYv+gz916wi6G1LF7rmM79RS+amnlaUa+XlJyRc/oXHA++7nMZtw25C7h+AkFXE6e4h5kfcmabZSVn/RMd1nBPpSFEACCUOiT0lhi1livJHZOOVLDySsYHxZ4C75BJLDSX4dlxGfL32Ub8vOulUqDtMZLAhdhSex8mf+W27R6YUxOadN8zFBxz4LRInj4XUQiUP6ujpIDPc3d3WlY6ZKuU8y8tgQQ0V7wLd2MW8Cs5NcNfC9LwwuP9K58bORJI8a9FQtBmxyrgRUZ3enK2oT7EZnvg/3GhlzIJDPS0YDXuVYfoP98DSP2gkPkugE21kZ6YM8/oHYsvRZfUgD9SyhJibgvImTQ2yyArdejyvo+ybs5OJERa3MVTLWdtBwPWw2O9VvVlnBl+kXLU/d1EmH4X+/NCWbeSuFHJb/xlERkpUDrl oKjIkwto VQxb45D+dwINIJzR9UbSSq0bvkpYIffwgviZDJ/fg4V/A8gfekL3u/Wk42PReoi/sQwkW/uMaP0Dozm0u41kH1u62AQmBtzfMwV0RCNj39YE5gTSZryp2RcYjd2VEfLNSZI4vKkhNl6xnKNSJqJWYBRy7q+tVRAgj4Kd+OaOaUt9UMXnLGS7CLVC0QyKkZVII9ygW7bA3VXUIOiKkvEiiOxiVMCFjQNqzgufu2PXtaQOAkWBIVGBnf94jio9za9h4i9m6/0mpxY+g8TYQXyaW+9S3TW++uWXDcw30tNAzdUd/r2I7GufoK3nGQ02vDtPn3lXg+1Lr6YUSmPTStGjFUlVMmzWzzGagOfZlEEqPJ8jj6u3FrwKZ8v9CcDPbrcSAlJHzO5u0wgr7ugWXvJjahiF/PAuMBcCZKU+f8wAgTytWYLt9M0A4Ur9aTOS3ygmrsCxtK17NjfZKM2fphS3or0HyjwJPor26smT4Znui2pigzGwRnfPr7FeANpr5fRpoNSGtd+8Du8z2LtkFabMCdgm2d1QP87KD3GbuYCo+xe69CmKfL4yEW4QZ6n7Xlm7CTYYL9ORmIFcAGkJirehdZptQDVSQKiF3j7HgXduZQOgLc1wSK0uE+IyRccPiJwKB5fHQuZPyqEYI67wCQcbfTf6dXmTgLvPEBpkI3Xw3pEhnl6gudqIK3egUKhRI4zCKPCjSTBtnz36mra4= X-Bogosity: Ham, tests=bogofilter, spamicity=0.080998, 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 Reviewed-by: Mike Rapoport (IBM) --- 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 339adf8fe..e91a1dfc8 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -83,7 +83,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 @@ -93,6 +92,25 @@ fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. .PP +After 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 @@ -102,24 +120,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