Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH RESEND] docs/core-api: memory-allocation: describe reclaim behaviour
@ 2020-07-19 15:36 Mike Rapoport
  2020-07-23 20:09 ` Jonathan Corbet
  0 siblings, 1 reply; 2+ messages in thread
From: Mike Rapoport @ 2020-07-19 15:36 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-doc, linux-kernel, Mike Rapoport, Mike Rapoport, Michal Hocko

From: Mike Rapoport <rppt@linux.ibm.com>

Changelog of commit dcda9b04713c ("mm, tree wide: replace __GFP_REPEAT by
__GFP_RETRY_MAYFAIL with more useful semantic") has very nice description
of GFP flags that affect reclaim behaviour of the page allocator.

It would be pity to keep this description buried in the log so let's expose
it in the Documentation/ as well.

Cc: Michal Hocko <mhocko@suse.com>
Acked-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
---
 Documentation/core-api/memory-allocation.rst | 44 ++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 4aa82ddd01b8..4446a1ac36cc 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -84,6 +84,50 @@ driver for a device with such restrictions, avoid using these flags.
 And even with hardware with restrictions it is preferable to use
 `dma_alloc*` APIs.
 
+GFP flags and reclaim behavior
+------------------------------
+Memory allocations may trigger direct or background reclaim and it is
+useful to understand how hard the page allocator will try to satisfy that
+or another request.
+
+  * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_
+    attempt to free memory at all. The most light weight mode which even
+    doesn't kick the background reclaim. Should be used carefully because it
+    might deplete the memory and the next user might hit the more aggressive
+    reclaim.
+
+  * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic
+    allocation without any attempt to free memory from the current
+    context but can wake kswapd to reclaim memory if the zone is below
+    the low watermark. Can be used from either atomic contexts or when
+    the request is a performance optimization and there is another
+    fallback for a slow path.
+
+  * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) -
+    non sleeping allocation with an expensive fallback so it can access
+    some portion of memory reserves. Usually used from interrupt/bottom-half
+    context with an expensive slow path fallback.
+
+  * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
+    **default** page allocator behavior is used. That means that not costly
+    allocation requests are basically no-fail but there is no guarantee of
+    that behavior so failures have to be checked properly by callers
+    (e.g. OOM killer victim is allowed to fail currently).
+
+  * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior
+    and all allocation requests fail early rather than cause disruptive
+    reclaim (one round of reclaim in this implementation). The OOM killer
+    is not invoked.
+
+  * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator
+    behavior and all allocation requests try really hard. The request
+    will fail if the reclaim cannot make any progress. The OOM killer
+    won't be triggered.
+
+  * ``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.
+
 Selecting memory allocator
 ==========================
 
-- 
2.25.4


^ permalink raw reply	[flat|nested] 2+ messages in thread

* Re: [PATCH RESEND] docs/core-api: memory-allocation: describe reclaim behaviour
  2020-07-19 15:36 [PATCH RESEND] docs/core-api: memory-allocation: describe reclaim behaviour Mike Rapoport
@ 2020-07-23 20:09 ` Jonathan Corbet
  0 siblings, 0 replies; 2+ messages in thread
From: Jonathan Corbet @ 2020-07-23 20:09 UTC (permalink / raw)
  To: Mike Rapoport; +Cc: linux-doc, linux-kernel, Mike Rapoport, Michal Hocko

On Sun, 19 Jul 2020 18:36:41 +0300
Mike Rapoport <rppt@kernel.org> wrote:

> From: Mike Rapoport <rppt@linux.ibm.com>
> 
> Changelog of commit dcda9b04713c ("mm, tree wide: replace __GFP_REPEAT by
> __GFP_RETRY_MAYFAIL with more useful semantic") has very nice description
> of GFP flags that affect reclaim behaviour of the page allocator.
> 
> It would be pity to keep this description buried in the log so let's expose
> it in the Documentation/ as well.
> 
> Cc: Michal Hocko <mhocko@suse.com>
> Acked-by: Michal Hocko <mhocko@suse.com>
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
>  Documentation/core-api/memory-allocation.rst | 44 ++++++++++++++++++++
>  1 file changed, 44 insertions(+)

Applied, thanks.

I'm not quite sure how this fell through the cracks before, sorry about
that.

jon

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, back to index

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-19 15:36 [PATCH RESEND] docs/core-api: memory-allocation: describe reclaim behaviour Mike Rapoport
2020-07-23 20:09 ` Jonathan Corbet

Linux-Doc Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-doc/0 linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ https://lore.kernel.org/linux-doc \
		linux-doc@vger.kernel.org
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-doc


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git