mm: document memalloc_noreclaim_save() and memalloc_pin_save()
Subsystems (2)
PATCH v2 1/1 mm: document memalloc_noreclaim_save() and memalloc_pin_save()
The memalloc_noreclaim_save() function currently has no documentation comment, so the implications of its usage are not obvious. Namely that it not only prevents entering reclaim (as the name suggests), but also allows using all memory reserves and thus should be only used in contexts that are allocating memory to free memory. This may lead to new improper usages being added.
Thus add a documenting comment, based on the description of __GFP_MEMALLOC. While at it, also document memalloc_pin_save() so that all the memalloc_ scopes are documented. For those already documented, add missing Return: descriptions, and mark Context: description per kernel-docs style guide.
In the comments describing the relevant PF_MEMALLOC flags, refer to their scope setting functions.
---
v2: fix issues that Mike pointed out
sending as replacement instead of fixup because I've used the wrong address for Kent and it became part of Cc: tag in the mm tree.
include/linux/sched.h | 9 ++++--- include/linux/sched/mm.h | 55 ++++++++++++++++++++++++++++++++++++++-- 2 files changed, 58 insertions(+), 6 deletions(-)
include/linux/sched.h +5 -4
@@ -1623,15 +1623,15 @@ extern struct pid *cad_pid;#define PF_SUPERPRIV 0x00000100/* Used super-user privileges */ #define PF_DUMPCORE 0x00000200/* Dumped core */ #define PF_SIGNALED 0x00000400/* Killed by a signal */ -#define PF_MEMALLOC 0x00000800/* Allocating memory */ +#define PF_MEMALLOC 0x00000800/* Allocating memory to free memory. See memalloc_noreclaim_save() */ #define PF_NPROC_EXCEEDED 0x00001000/* set_user() noticed that RLIMIT_NPROC was exceeded */ #define PF_USED_MATH 0x00002000/* If unset the fpu must be initialized before use */ #define PF_USER_WORKER 0x00004000/* Kernel thread cloned from userspace thread */ #define PF_NOFREEZE 0x00008000/* This thread should not be frozen */ #define PF__HOLE__00010000 0x00010000#define PF_KSWAPD 0x00020000/* I am kswapd */ -#define PF_MEMALLOC_NOFS 0x00040000/* All allocation requests will inherit GFP_NOFS */ -#define PF_MEMALLOC_NOIO 0x00080000/* All allocation requests will inherit GFP_NOIO */ +#define PF_MEMALLOC_NOFS 0x00040000/* All allocations inherit GFP_NOFS. See memalloc_nfs_save() */ +#define PF_MEMALLOC_NOIO 0x00080000/* All allocations inherit GFP_NOIO. See memalloc_noio_save() */ #define PF_LOCAL_THROTTLE 0x00100000/* Throttle writes only against the bdi I write to, * I am cleaning dirty pages from some other bdi. */ #define PF_KTHREAD 0x00200000/* I am a kernel thread */
@@ -1641,7 +1641,8 @@ extern struct pid *cad_pid;#define PF__HOLE__02000000 0x02000000#define PF_NO_SETAFFINITY 0x04000000/* Userland is not allowed to meddle with cpus_mask */ #define PF_MCE_EARLY 0x08000000/* Early kill for mce process policy */ -#define PF_MEMALLOC_PIN 0x10000000/* Allocation context constrained to zones which allow long term pinning. */ +#define PF_MEMALLOC_PIN 0x10000000/* Allocations constrained to zones which allow long term pinning. +* See memalloc_pin_save() */ #define PF__HOLE__20000000 0x20000000#define PF__HOLE__40000000 0x40000000#define PF_SUSPEND_TASK 0x80000000/* This thread called freeze_processes() and should not be frozen */
include/linux/sched/mm.h +53 -2
90 lines not on this page · raw message
Signature · 1 line
2.43.0
Andrew Morton
maintainerQuoted 4 lines · On Thu, 15 Feb 2024 10:58:28 +0100 Vlastimil Babka <[email protected]> wrote:
...
v2: fix issues that Mike pointed out
Cool.
Quoted 2 lines
sending as replacement instead of fixup because I've used the wrong address for Kent and it became part of Cc: tag in the mm tree.
akpm has editor ;)
Quoted 4 lines
+ * This function marks the beginning of the
__GFP_MEMALLOCallocation scope.
...+ * This function marks the beginning of the ~__GFP_MOVABLE allocation scope.
pet peeves. We can assume that the reader knows that this is a function! Perhaps we should teach checkpatch to whine.
Like "the function foo" and "the function foo()" in changelogs. "foo()" is enough!
Quoted 10 lines · Andrew Morton
+ * This function marks the beginning of the
__GFP_MEMALLOCallocation scope.Quoted 3 lines
...
+ * This function marks the beginning of the ~__GFP_MOVABLE allocation scope.
pet peeves. We can assume that the reader knows that this is a function! Perhaps we should teach checkpatch to whine.
Like "the function foo" and "the function
foo()" in changelogs. "foo()" is enough!
IMO: checkpatch should not be a grammar checker.
It's stupid enough as is let alone trying to get
it to analyze sentence structure.