Received-SPF: pass (google.com: domain of linux-ext4-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   NeilBrown <neilb@suse.de>
To:     Andrew Morton <akpm@linux-foundation.org>,
        Theodore Ts'o <tytso@mit.edu>,
        Andreas Dilger <adilger.kernel@dilger.ca>,
        "Darrick J. Wong" <djwong@kernel.org>,
        Matthew Wilcox <willy@infradead.org>,
        Mel Gorman <mgorman@suse.com>
Date:   Tue, 14 Sep 2021 10:13:04 +1000
Subject: [PATCH 1/6] MM: improve documentation for __GFP_NOFAIL
Cc:     linux-xfs@vger.kernel.org, linux-ext4@vger.kernel.org,
        linux-fsdevel@vger.kernel.org, linux-nfs@vger.kernel.org,
        linux-mm@kvack.org, linux-kernel@vger.kernel.org
Message-ID: <163157838436.13293.8832201267053160346.stgit@noble.brown>
In-Reply-To: <163157808321.13293.486682642188075090.stgit@noble.brown>
References: <163157808321.13293.486682642188075090.stgit@noble.brown>
User-Agent: StGit/0.23
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Precedence: bulk

__GFP_NOFAIL is documented both in gfp.h and memory-allocation.rst.
The details are not entirely consistent.

This patch ensures both places state that:
 - there is a cost potentially imposed on other subsystems
 - it should only be used when there is no real alternative
 - it is preferable to an endless loop
 - it is strongly discourages for costly-order allocations.

Signed-off-by: NeilBrown <neilb@suse.de>
---
 Documentation/core-api/memory-allocation.rst |    9 ++++++++-
 include/linux/gfp.h                          |    4 ++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 5954ddf6ee13..9458ce72d31c 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -126,7 +126,14 @@ or another request.
 
   * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
     and all allocation requests will loop endlessly until they succeed.
-    This might be really dangerous especially for larger orders.
+    The allocator may provide access to memory that would otherwise be
+    reserved in order to satisfy this allocation which might adversely
+    affect other subsystems.  So it should only be used when there is no
+    reasonable failure policy and when the memory is likely to be freed
+    again in the near future.  Its use is strong discourage (via a
+    WARN_ON) for allocations larger than ``PAGE_ALLOC_COSTLY_ORDER``.
+    While this flag is best avoided, it is still preferable to endless
+    loops around the allocator.
 
 Selecting memory allocator
 ==========================
diff --git a/include/linux/gfp.h b/include/linux/gfp.h
index 55b2ec1f965a..101479373738 100644
--- a/include/linux/gfp.h
+++ b/include/linux/gfp.h
@@ -209,6 +209,10 @@ struct vm_area_struct;
  * used only when there is no reasonable failure policy) but it is
  * definitely preferable to use the flag rather than opencode endless
  * loop around allocator.
+ * Use of this flag may provide access to memory which would otherwise be
+ * reserved.  As such it must be understood that there can be a cost imposed
+ * on other subsystems as well as the obvious cost of placing the calling
+ * thread in an uninterruptible indefinite wait.
  * Using this flag for costly allocations is _highly_ discouraged.
  */
 #define __GFP_IO	((__force gfp_t)___GFP_IO)