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@xxxxxxxxxx>
---
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
