Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   David Hildenbrand <david@redhat.com>
To:     linux-kernel@vger.kernel.org
Cc:     linux-mm@kvack.org, linux-fsdevel@vger.kernel.org,
        David Hildenbrand <david@redhat.com>,
        Andrew Morton <akpm@linux-foundation.org>,
        Linus Torvalds <torvalds@linux-foundation.org>,
        liubo <liubo254@huawei.com>, Peter Xu <peterx@redhat.com>,
        Matthew Wilcox <willy@infradead.org>,
        Hugh Dickins <hughd@google.com>,
        Jason Gunthorpe <jgg@ziepe.ca>,
        John Hubbard <jhubbard@nvidia.com>
Subject: [PATCH v1 4/4] mm/gup: document FOLL_FORCE behavior
Date:   Thu, 27 Jul 2023 23:28:45 +0200
Message-ID: <20230727212845.135673-5-david@redhat.com>
In-Reply-To: <20230727212845.135673-1-david@redhat.com>
References: <20230727212845.135673-1-david@redhat.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

As suggested by Peter, let's document FOLL_FORCE handling and make it
clear that without FOLL_FORCE, we will always trigger NUMA-hinting
faults when stumbling over a PROT_NONE-mapped PTE.

Also add a comment regarding follow_page() and its interaction with
FOLL_FORCE.

Let's place the doc next to the definition, where it certainly can't be
missed.

Signed-off-by: David Hildenbrand <david@redhat.com>
---
 include/linux/mm_types.h | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/include/linux/mm_types.h b/include/linux/mm_types.h
index 2fa6fcc740a1..96cf78686c29 100644
--- a/include/linux/mm_types.h
+++ b/include/linux/mm_types.h
@@ -1243,7 +1243,30 @@ enum {
 	FOLL_GET = 1 << 1,
 	/* give error on hole if it would be zero */
 	FOLL_DUMP = 1 << 2,
-	/* get_user_pages read/write w/o permission */
+	/*
+	 * Make get_user_pages() and friends ignore some VMA+PTE permissions.
+	 *
+	 * This flag should primarily only be used by ptrace and some
+	 * GUP-internal functionality, such as for mlock handling.
+	 *
+	 * Without this flag, these functions always trigger page faults
+	 * (such as NUMA hinting faults) when stumbling over a
+	 * PROT_NONE-mapped PTE.
+	 *
+	 * !FOLL_WRITE: succeed even if the PTE is PROT_NONE
+	 * * Rejected if the VMA is currently not readable and it cannot
+	 *   become readable
+	 *
+	 * FOLL_WRITE: succeed even if the PTE is not writable.
+	 *  * Rejected if the VMA is currently not writable and
+	 *   * it is a hugetlb mapping
+	 *   * it is not a COW mapping that could become writable
+	 *
+	 * Note: follow_page() does not accept FOLL_FORCE. Historically,
+	 * follow_page() behaved similar to FOLL_FORCE without FOLL_WRITE:
+	 * succeed even if the PTE is PROT_NONE and FOLL_WRITE is not set.
+	 * However, VMA permissions are not checked.
+	 */
 	FOLL_FORCE = 1 << 3,
 	/*
 	 * if a disk transfer is needed, start the IO and return without waiting
-- 
2.41.0