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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B9778CDB474 for ; Tue, 17 Oct 2023 23:01:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1344282AbjJQXB3 (ORCPT ); Tue, 17 Oct 2023 19:01:29 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49662 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344176AbjJQXBY (ORCPT ); Tue, 17 Oct 2023 19:01:24 -0400 Received: from mail-yw1-x114a.google.com (mail-yw1-x114a.google.com [IPv6:2607:f8b0:4864:20::114a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 74DC5A4 for ; Tue, 17 Oct 2023 16:01:22 -0700 (PDT) Received: by mail-yw1-x114a.google.com with SMTP id 00721157ae682-5a7ed6903a6so94891817b3.2 for ; Tue, 17 Oct 2023 16:01:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1697583681; x=1698188481; 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=zotUshyT9JxTsldtXKWoET48qiWRumjzDVZqgqNWkYo=; b=kf/T6LdDv4xfAdWiT02p0AlEjTHl7QjAysREP4ZFS7MQsbUKlzR+gfCov5qN7R9j8Y iN9cx/P2T45Elo/1ReAljLM5Ka5QY3WeBdTGujI7Yjrua6ojQl0Yt9O8bH6DSNKFhB7d sOrTByJVubhrBVKIhO2GCIBYV6fm3m0n1/8rj3UmKm6wcouMqm1mNk8lwZkpdFEltBgS 03hMOJCJECMPnV0evvbub713Xm+p0psHseUijIej77Luyuxm+yM8gnHCS7M7cB9ABWzm JQ9HEHC55ZXt8Z8/0UEPqdbDS9Sd2TCBWQMTtNA6FeVbmK1Mti2Ebdtn6h7jdOfBOxUa +XRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1697583681; x=1698188481; 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=zotUshyT9JxTsldtXKWoET48qiWRumjzDVZqgqNWkYo=; b=WL7rQ3gbnQWAQn+oGFawObXZDlKtfeQer6TMCvLfz/8PVcMGR5R5LdwOCw/OFtujEI nEcG4LmxwEBrg+ANn/BWmHZzL3ljY+qcKlR5knuKADAUoWS0gr1QEDS2XWAOuMI8B86Y oQFsn/+iP8Ap41QHkTq33eODTboZkcvFLggQ9XoE1dWX7V8e1iBTtiArmaJNKQc5M21I 0buvCCO8PdDorCByNY2fV5dXdq95M0xHUNfh9FVuUnpFu4mxTEE4yj9Vg58IamY1GcRe 9ElmMuTOa9ThRX41BkJlqPLP05hiPAmFDr7kSDg8TgSd+LAI8/aNOliW0r8G4GdGH/13 mSBQ== X-Gm-Message-State: AOJu0YwWqmaWpUSNmHbnZ1X4Cxj5vBjUaMaiPy9P2g2VXeBrBHyTOJ9q lpsGeodEs2vQshFt7iN8IM8NbudIuY9r2uF/vJ7z X-Google-Smtp-Source: AGHT+IG33rPX+YBy/IxDNh0Hn8HuEPXvaiympTSyyMMX5HQVRWBVdttcufnoKeE06bjlWpxR13bX53lvCE4ue3giXDWV X-Received: from axel.svl.corp.google.com ([2620:15c:2a3:200:cd04:35d6:a586:5c86]) (user=axelrasmussen job=sendgmr) by 2002:a81:4f92:0:b0:57a:118a:f31 with SMTP id d140-20020a814f92000000b0057a118a0f31mr84700ywb.7.1697583681778; Tue, 17 Oct 2023 16:01:21 -0700 (PDT) Date: Tue, 17 Oct 2023 16:01:10 -0700 In-Reply-To: <20231017230110.3170850-1-axelrasmussen@google.com> Mime-Version: 1.0 References: <20231017230110.3170850-1-axelrasmussen@google.com> X-Mailer: git-send-email 2.42.0.655.g421f12c284-goog Message-ID: <20231017230110.3170850-4-axelrasmussen@google.com> Subject: [PATCH v3 3/3] ioctl_userfaultfd.2: document new UFFDIO_POISON ioctl From: Axel Rasmussen To: Alejandro Colomar , Mike Rapoport , 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" Precedence: bulk List-ID: X-Mailing-List: linux-man@vger.kernel.org This is a new feature recently added to the kernel. So, document the new ioctl the same way we do other UFFDIO_* ioctls. Also note the corresponding new ioctl flag we can return in response to a UFFDIO_REGISTER call. Reviewed-by: Mike Rapoport (IBM) Signed-off-by: Axel Rasmussen --- man2/ioctl_userfaultfd.2 | 124 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 118 insertions(+), 6 deletions(-) diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index 40528001e..a9131515c 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -405,6 +405,11 @@ operation is supported. The .B UFFDIO_CONTINUE operation is supported. +.TP +.B 1 << _UFFDIO_POISON +The +.B UFFDIO_POISON +operation is supported. .PP This .BR ioctl (2) @@ -886,6 +891,12 @@ does not equal the value that was specified in the .I range.len field. .TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B EFAULT +No existing page could be found in the page cache for the given range. +.TP .B EINVAL Either .I range.start @@ -900,9 +911,6 @@ An invalid bit was specified in the .I mode field. .TP -.B EEXIST -One or more pages were already mapped in the given range. -.TP .B ENOENT The faulting process has changed its virtual memory layout simultaneously with an outstanding @@ -912,14 +920,118 @@ operation. .B ENOMEM Allocating memory needed to setup the page table mappings failed. .TP -.B EFAULT -No existing page could be found in the page cache for the given range. -.TP .B ESRCH The faulting process has exited at the time of a .B UFFDIO_CONTINUE operation. .\" +.SS UFFDIO_POISON +(Since Linux 6.6.) +Mark an address range as "poisoned". +Future accesses to these addresses will raise a +.B SIGBUS +signal. +Unlike +.B MADV_HWPOISON +this works by installing page table entries, +rather than "really" poisoning the underlying physical pages. +This means it only affects this particular address space. +.PP +The +.I argp +argument is a pointer to a +.I uffdio_poison +structure as shown below: +.PP +.in +4n +.EX +struct uffdio_poison { + struct uffdio_range range; + /* Range to install poison PTE markers in */ + __u64 mode; /* Flags controlling the behavior of poison */ + __s64 updated; /* Number of bytes poisoned, or negated error */ +}; +.EE +.in +.PP +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_POISON +operation: +.TP +.B UFFDIO_POISON_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.PP +The +.I updated +field is used by the kernel +to return the number of bytes that were actually poisoned, +or an error in the same manner as +.BR UFFDIO_COPY . +If the value returned in the +.I updated +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I updated +field is output-only; +it is not read by the +.B UFFDIO_POISON +operation. +.PP +This +.BR ioctl (2) +operation returns 0 on success. +In this case, +the entire area was poisoned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes mapped +(i.e., the value returned in the +.I updated +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B ENOENT +The faulting process has changed its virtual memory layout simultaneously with +an outstanding +.B UFFDIO_POISON +operation. +.TP +.B ENOMEM +Allocating memory for page table entries failed. +.TP +.B ESRCH +The faulting process has exited at the time of a +.B UFFDIO_POISON +operation. +.\" .SH RETURN VALUE See descriptions of the individual operations, above. .SH ERRORS -- 2.42.0.655.g421f12c284-goog