[PATCH v1 4/4] mm/gup: document FOLL_FORCE behavior

[David Hildenbrand <david@redhat.com>]

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