GFP Flags and Allocation Contexts

Every time the Linux kernel asks for memory, it must declare how the allocator is allowed to behave while satisfying the request — may it sleep, may it start disk I/O, may it recurse into the filesystem, may it dip into emergency reserves, which physical zone may it draw from. That declaration is a GFP mask: a gfp_t bitfield where “GFP” stands for get free pages, the name of the underlying allocator entry point. The mask is not a hint the allocator may ignore — it is a hard contract. Pass GFP_KERNEL (which permits sleeping) from interrupt context and you invite a “sleeping function called from invalid context” splat or an outright deadlock; pass GFP_ATOMIC everywhere “to be safe” and you needlessly drain the kernel’s emergency reserves. The header that defines every bit — include/linux/gfp_types.h — is one of the most heavily-commented files in the tree precisely because getting the flag wrong is a classic, dangerous kernel bug (per the kernel memory-allocation guide).

This note covers the flag vocabulary and, more importantly, the allocation contexts that dictate which flags are legal. It also covers the two things a flat list of constants cannot teach: how the mask is mechanically translated into allocator behaviour by gfp_to_alloc_flags(), and how the modern scope API — memalloc_nofs_save() / memalloc_noio_save() — has replaced hand-passed GFP_NOFS/GFP_NOIO as the recommended way to express reclaim-recursion constraints.

Version pin. All definitions are pinned to Linux 6.12, a maintained long-term-support (LTS) branch; mainline is on the 7.x series as of 2026-09. include/linux/gfp_types.h is byte-for-byte identical at v6.12 and v6.18 (re-verified by diff of both raw files, 2026-09-04), so every combination below holds unchanged across both LTS branches. At v7.1 the bit assignments and every composite macro are still unchanged — the only diffs are documentation-comment edits plus the removal of the CONFIG_SLAB_OBJ_EXT guard around ___GFP_NO_OBJ_EXT. One of those comment edits is substantive and dated below: v7.1 tightens the stated GFP_ATOMIC calling-context restriction to name PREEMPT_RT. For the watermark machinery these flags steer, see Watermarks and the Allocation Fast Path; for the allocator they feed, The Buddy Allocator; for the slow-path behavior they unlock, Direct Reclaim; for what happens when even that fails, The OOM Killer.

Mental Model — A Mask Is Three Questions

Think of a GFP mask as the allocator interrogating the caller about three independent axes, each encoded in a group of bits:

flowchart TB
  CALL["Caller wants memory<br/>kmalloc / alloc_pages / kmem_cache_alloc"]
  subgraph Q1["WHERE? — zone modifiers (low 4 bits)"]
    Z["__GFP_DMA / __GFP_DMA32<br/>__GFP_HIGHMEM / __GFP_MOVABLE<br/>(which physical zone is acceptable)"]
  end
  subgraph Q2["HOW HARD? — reclaim + watermark modifiers"]
    R["__GFP_DIRECT_RECLAIM (may I sleep & reclaim?)<br/>__GFP_KSWAPD_RECLAIM (may I wake kswapd?)<br/>__GFP_IO / __GFP_FS (may reclaim do I/O / call the FS?)<br/>__GFP_HIGH / __GFP_MEMALLOC (may I use reserves?)"]
  end
  subgraph Q3["WHAT ELSE? — action + retry modifiers"]
    A["__GFP_ZERO (pre-zero it)<br/>__GFP_COMP (compound page)<br/>__GFP_ACCOUNT (charge to memcg)<br/>__GFP_NORETRY / __GFP_RETRY_MAYFAIL / __GFP_NOFAIL (give-up policy)"]
  end
  CALL --> Q1 & Q2 & Q3
  Q2 -->|"the axis that depends on CONTEXT"| CTX["Atomic context?<br/>→ must clear __GFP_DIRECT_RECLAIM"]

The three questions a GFP mask answers. What it shows: zone modifiers (where the page may come from), reclaim/watermark modifiers (how aggressively the allocator may work to find it), and action/retry modifiers (what to do with it and when to give up). The insight: only the middle axis is constrained by execution context — the zone and action bits are about what you want, but the reclaim bits are about what is legal where you are calling from. Calling context is the whole reason the named combinations like GFP_KERNEL and GFP_ATOMIC exist: they pre-package the legal reclaim settings for a context so callers do not assemble them by hand.

The kernel documentation states the rule directly: “It is recommended that subsystems start with one of these combinations and then set/clear __GFP_FOO flags as necessary” (gfp_types.h). You almost never build a mask bit-by-bit; you pick a named combination and tweak.

The Bit Layout — What a gfp_t Actually Is

Before the vocabulary, the substrate. A gfp_t is unsigned int __bitwise — a 32-bit word in which each flag owns exactly one bit. The bit positions are not written as literals anywhere; they are assigned by a plain C enum at the top of include/linux/gfp_types.h, so a flag’s numeric value is a function of its position in that enum:

enum {
	___GFP_DMA_BIT,          /* 0 */
	___GFP_HIGHMEM_BIT,      /* 1 */
	___GFP_DMA32_BIT,        /* 2 */
	___GFP_MOVABLE_BIT,      /* 3 */
	___GFP_RECLAIMABLE_BIT,  /* 4 */
	...
	___GFP_ZEROTAGS_BIT,     /* 23 */
#ifdef CONFIG_KASAN_HW_TAGS
	___GFP_SKIP_ZERO_BIT,    /* 24, only with KASAN hardware tags */
	___GFP_SKIP_KASAN_BIT,   /* 25 */
#endif
#ifdef CONFIG_LOCKDEP
	___GFP_NOLOCKDEP_BIT,    /* only with lockdep */
#endif
#ifdef CONFIG_SLAB_OBJ_EXT
	___GFP_NO_OBJ_EXT_BIT,
#endif
	___GFP_LAST_BIT
};
#define ___GFP_DMA  BIT(___GFP_DMA_BIT)

Two consequences follow immediately. First, bits 0–23 are unconditional and therefore stable across kernel configurations, while everything from bit 24 up is CONFIG-dependent — which is why __GFP_SKIP_KASAN is #defined to a literal 0 when CONFIG_KASAN_HW_TAGS is off, and why a composite that mentions it (GFP_HIGHUSER_MOVABLE) has a different numeric value on a KASAN-hardware-tags kernel than on an ordinary one. Second, __GFP_BITS_SHIFT is just ___GFP_LAST_BIT and __GFP_BITS_MASK is (1 << __GFP_BITS_SHIFT) - 1, so the set of legal bits is derived rather than hard-coded.

packet-beta
0-3: "ZONE"
4: "RCLM"
5: "HIGH"
6-7: "IO+FS"
8: "ZERO"
9: "rsvd"
10-11: "RECLAIM"
12: "WR"
13: "NOWARN"
14-16: "RETRY POLICY"
17: "MEMALLOC"
18: "COMP"
19: "NOMEMALLOC"
20-22: "PLACEMENT"
23: "TAGS"
24-31: "config-gated / unused"

The gfp_t word at v6.12, drawn to bit accuracy. What it shows: the flags are not scattered — related flags are adjacent, because the enum was written in functional order. ZONE is bits 0–3 (GFP_ZONEMASK), the two reclaim-recursion gates __GFP_IO/__GFP_FS are 6–7, the two reclaim permissions are 10–11, and the three mutually-competing retry policies are 14–16. The insight: bit 9 is a hole — the header literally says ___GFP_UNUSED_BIT, /* 0x200u unused */. It is the grave of __GFP_ATOMIC, removed in 6.3 (see below); the enum position was retained rather than renumbered so that every other flag’s numeric value stayed stable, which matters because those numbers appear in dmesg, in tracepoints, and in tools/perf/builtin-kmem.c.

The exhaustive per-bit reference. Hex values are computed from the enum positions above and independently cross-checked against a real dmesg OOM header (worked below), which printed gfp_mask=0x140dca(GFP_HIGHUSER_MOVABLE|__GFP_ZERO|__GFP_COMP) — a value this table reproduces exactly.

Bit	Hex	Flag	Axis	What it grants or requests
0	0x000001	__GFP_DMA	zone	Must come from ZONE_DMA (lowest 16 MiB on x86-64). Legacy.
1	0x000002	__GFP_HIGHMEM	zone	ZONE_HIGHMEM acceptable — page need not be kernel-addressable.
2	0x000004	__GFP_DMA32	zone	Must be 32-bit addressable.
3	0x000008	__GFP_MOVABLE	zone + mobility	ZONE_MOVABLE allowed; page “can be moved by page migration during memory compaction or can be reclaimed”.
4	0x000010	__GFP_RECLAIMABLE	mobility	Slab pages with SLAB_RECLAIM_ACCOUNT — freeable via shrinkers.
5	0x000020	__GFP_HIGH	watermark	Caller is high-priority; “granting the request is necessary before the system can make forward progress”.
6	0x000040	__GFP_IO	reclaim recursion	Reclaim “can start physical IO”.
7	0x000080	__GFP_FS	reclaim recursion	Reclaim “can call down to the low-level FS”.
8	0x000100	__GFP_ZERO	action	“Returns a zeroed page on success.”
9	0x000200	(unused)	—	Hole left by the 6.3 removal of __GFP_ATOMIC.
10	0x000400	__GFP_DIRECT_RECLAIM	reclaim	“The caller may enter direct reclaim” — the bit that permits sleeping.
11	0x000800	__GFP_KSWAPD_RECLAIM	reclaim	May wake kswapd at the low watermark and let it reclaim to the high watermark.
12	0x001000	__GFP_WRITE	placement	Caller intends to dirty the page; spread such pages across zones.
13	0x002000	__GFP_NOWARN	action	Suppress the page allocation failure splat.
14	0x004000	__GFP_RETRY_MAYFAIL	retry policy	Try hard (wait for compaction and page-out) but may still fail.
15	0x008000	__GFP_NOFAIL	retry policy	“The VM implementation must retry infinitely.”
16	0x010000	__GFP_NORETRY	retry policy	One lightweight round of reclaim, no OOM killer, expect failure.
17	0x020000	__GFP_MEMALLOC	watermark	“Allows access to all memory” — total reserve bypass.
18	0x040000	__GFP_COMP	action	Allocate a compound page with proper metadata.
19	0x080000	__GFP_NOMEMALLOC	watermark	Explicitly forbid reserves; takes precedence over __GFP_MEMALLOC.
20	0x100000	__GFP_HARDWALL	placement	Enforce the cpuset memory policy.
21	0x200000	__GFP_THISNODE	placement	“Forces the allocation to be satisfied from the requested node with no fallbacks or placement policy enforcements.”
22	0x400000	__GFP_ACCOUNT	accounting	Charge to the current task’s memcg kernel-memory accounting.
23	0x800000	__GFP_ZEROTAGS	action	Zero memory tags alongside the data (arm64 MTE).
24+	config	__GFP_SKIP_ZERO, __GFP_SKIP_KASAN, __GFP_NOLOCKDEP, __GFP_NO_OBJ_EXT	debug/config	Present only under CONFIG_KASAN_HW_TAGS, CONFIG_LOCKDEP, CONFIG_SLAB_OBJ_EXT respectively; otherwise defined as literal 0.

Knowing the hex is not academic trivia — it is how you read an OOM report or a page allocation failure splat. The kernel prints the raw value first and the symbolic decode second (via the %pGg printk specifier), and when the symbolic decode is truncated or you are reading a tracepoint dump, the raw number is all you have.

The Named Combinations — The 99% of Real Code

These macros, quoted verbatim from gfp_types.h at v6.12 (identical at v6.18), are what actual callers use:

#define GFP_ATOMIC         (__GFP_HIGH|__GFP_KSWAPD_RECLAIM)
#define GFP_KERNEL         (__GFP_RECLAIM | __GFP_IO | __GFP_FS)
#define GFP_KERNEL_ACCOUNT (GFP_KERNEL | __GFP_ACCOUNT)
#define GFP_NOWAIT         (__GFP_KSWAPD_RECLAIM | __GFP_NOWARN)
#define GFP_NOIO           (__GFP_RECLAIM)
#define GFP_NOFS           (__GFP_RECLAIM | __GFP_IO)
#define GFP_USER           (__GFP_RECLAIM | __GFP_IO | __GFP_FS | __GFP_HARDWALL)
#define GFP_DMA            __GFP_DMA
#define GFP_DMA32          __GFP_DMA32
#define GFP_HIGHUSER       (GFP_USER | __GFP_HIGHMEM)
#define GFP_HIGHUSER_MOVABLE (GFP_HIGHUSER | __GFP_MOVABLE | __GFP_SKIP_KASAN)

Reading these definitions is the fastest way to understand the flags, because each combination is a deliberate composition. Note __GFP_RECLAIM is itself shorthand: #define __GFP_RECLAIM ((__force gfp_t)(___GFP_DIRECT_RECLAIM|___GFP_KSWAPD_RECLAIM)) — i.e. “both kinds of reclaim allowed.”

Written out as bits, the family structure becomes obvious in a way the macro definitions hide. Every cell below is derived from the enum positions in the previous section; the composite hex values were computed from those positions and are what the kernel prints in dmesg.

Composite	Hex	zone	HIGH	IO	FS	DIRECT	KSWAPD	HARDWALL	other	May sleep?	Reserves?
GFP_ATOMIC	0x000820	normal	●				●			no	yes (min/2, then /4 more)
GFP_NOWAIT	0x002800	normal					●		NOWARN	no	no
GFP_NOIO	0x000c00	normal				●	●			yes	no
GFP_NOFS	0x000c40	normal		●		●	●			yes	no
GFP_KERNEL	0x000cc0	normal		●	●	●	●			yes	no
GFP_KERNEL_ACCOUNT	0x400cc0	normal		●	●	●	●		ACCOUNT	yes	no
GFP_USER	0x100cc0	normal		●	●	●	●	●		yes	no
GFP_HIGHUSER	0x100cc2	+highmem		●	●	●	●	●		yes	no
GFP_HIGHUSER_MOVABLE	0x100cca	+movable		●	●	●	●	●	SKIP_KASAN	yes	no
GFP_TRANSHUGE_LIGHT	0x1c20ca	+movable		●	●			●	COMP, NOMEMALLOC, NOWARN	no	forbidden
GFP_TRANSHUGE	0x1c24ca	+movable		●	●	●		●	COMP, NOMEMALLOC, NOWARN	yes	forbidden
GFP_DMA	0x000001	DMA only								n/a — zone only	n/a

Reading the matrix downward is the fastest way to internalise the family. GFP_NOIO → GFP_NOFS → GFP_KERNEL is a strict ladder: each adds one recursion permission (__GFP_IO, then __GFP_FS) to the same sleeping base. GFP_KERNEL → GFP_USER → GFP_HIGHUSER → GFP_HIGHUSER_MOVABLE is a second ladder, adding cpuset enforcement and then loosening the zone constraint one step at a time — which is exactly what the kernel doc means by “the longer the flag name the less restrictive it is”. And the two non-sleeping masks are distinguished by a single bit: GFP_ATOMIC has __GFP_HIGH (0x20) and GFP_NOWAIT does not. That one bit is the entire difference between “may spend the emergency reserve” and “must succeed on ordinary free memory”.

Two entries in that table deserve a note because they are frequently mis-taught. GFP_TRANSHUGE_LIGHT is defined as (GFP_HIGHUSER_MOVABLE | __GFP_COMP | __GFP_NOMEMALLOC | __GFP_NOWARN) & ~__GFP_RECLAIM — note the subtraction: it deliberately clears both reclaim bits, so a transparent-huge-page allocation in the page-fault path will not even wake kswapd. The header explains why: “The _LIGHT version does not attempt reclaim/compaction at all and is by default used in page fault path, while the non-light is used by khugepaged.” A THP has a cheap fallback (four-kilobyte pages), so stalling a page fault to obtain one would be a bad trade. GFP_TRANSHUGE adds back only __GFP_DIRECT_RECLAIM, not __GFP_KSWAPD_RECLAIM. Both carry __GFP_NOMEMALLOC, permanently forbidding reserves. See Transparent Huge Pages.

And GFP_DMA32 carries a documented trap: “Note that kmalloc(..., GFP_DMA32) does not return DMA32 memory because the DMA32 kmalloc cache array is not implemented. (Reason: there is no such user in kernel).” The flag silently does nothing on the slab path. Use the DMA API instead.

GFP_KERNEL — the default, sleepable allocation

GFP_KERNEL = __GFP_RECLAIM | __GFP_IO | __GFP_FS. It permits direct reclaim (so the call may sleep), permits reclaim to start physical I/O (__GFP_IO) and to recurse into the filesystem (__GFP_FS), and permits waking kswapd. It draws from ZONE_NORMAL or lower (no __GFP_HIGHMEM), so the page is directly addressable by the kernel. The kernel-doc is blunt: “Most of the time GFP_KERNEL is what you need… using GFP_KERNEL implies __GFP_RECLAIM, which means that direct reclaim may be triggered under memory pressure; the calling context must be allowed to sleep” (memory-allocation guide). Use it from process context with no spinlock held — system-call handlers, kernel threads, workqueue callbacks.

Because GFP_KERNEL allows the allocator to do everything in its power short of accessing reserves, “not-costly” (order ≤ PAGE_ALLOC_COSTLY_ORDER, i.e. ≤ 8 pages) GFP_KERNEL requests are effectively no-fail in practice — the allocator will reclaim, compact, and finally invoke the OOM killer rather than return NULL for a small request. The header still warns callers to check for NULL because that behavior is not guaranteed.

GFP_ATOMIC — non-sleeping, may touch reserves

GFP_ATOMIC = __GFP_HIGH | __GFP_KSWAPD_RECLAIM. Critically, it does not contain __GFP_DIRECT_RECLAIM — so the allocator will never sleep. It does contain __GFP_KSWAPD_RECLAIM, so it will wake kswapd to reclaim asynchronously in the background, but it will not wait for the result. The __GFP_HIGH bit is the “high priority” marker: it grants access to a slice of emergency reserves below the normal watermark, on the theory that the caller needs the allocation to make forward progress (the header’s example: “creating an IO context to clean pages and requests from atomic context”).

GFP_ATOMIC is for callers that cannot sleep but cannot easily tolerate failure — interrupt handlers and softirqs that must allocate to make progress, with an expensive fallback. The kernel-doc frames it precisely: “If you think that accessing memory reserves is justified and the kernel will be stressed unless allocation succeeds, you may use GFP_ATOMIC.” Because it spends reserves, overusing GFP_ATOMIC is a real problem — it depletes the buffer that genuinely-atomic callers rely on. See Watermarks and the Allocation Fast Path for how __GFP_HIGH lowers the watermark the request must clear.

GFP_NOWAIT — non-sleeping, no reserves

GFP_NOWAIT = __GFP_KSWAPD_RECLAIM | __GFP_NOWARN. Like GFP_ATOMIC it cannot sleep (no __GFP_DIRECT_RECLAIM) and can wake kswapd, but unlike GFP_ATOMIC it has no __GFP_HIGH — so it gets no access to reserves and must succeed entirely on the free pages already above the watermark. It is therefore “very likely to fail to allocate memory, even for very small allocations” (header comment). The __GFP_NOWARN bit suppresses the failure splat, because failure is expected and the caller is required to have a fallback.

A persistent misconception is that GFP_NOWAIT does nothing under pressure. It does one thing: it wakes kswapd (__GFP_KSWAPD_RECLAIM) so that future allocations benefit, even though this one will not wait. The kernel-doc names this exact mode: “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.”

GFP_USER, GFP_HIGHUSER, GFP_HIGHUSER_MOVABLE — user-facing pages

GFP_USER adds __GFP_HARDWALL, which enforces the cpuset memory policy — userspace allocations must respect the set of NUMA nodes the task’s cpuset permits (kernel-internal GFP_KERNEL allocations are exempt). GFP_HIGHUSER adds __GFP_HIGHMEM (the page need not be kernel-addressable; it may live in high memory and be kmap()-ed on demand). GFP_HIGHUSER_MOVABLE further adds __GFP_MOVABLE, marking the page as relocatable by compaction and migration — this is the flag behind ordinary anonymous and page-cache pages, the ones that land on the LRU.

GFP_KERNEL_ACCOUNT — the container flag

GFP_KERNEL_ACCOUNT = GFP_KERNEL | __GFP_ACCOUNT. The __GFP_ACCOUNT bit charges the allocation to the current task’s memory cgroup’s kernel-memory accounting. The kernel-doc rule: “Untrusted allocations triggered from userspace should be a subject of kmem accounting and must have __GFP_ACCOUNT bit set.” This is the mechanism that makes a process’s kernel-side memory (page tables, sockets, dentries created on its behalf) count against its container’s memory.max.

GFP_NOFS / GFP_NOIO — breaking reclaim recursion

GFP_NOFS = __GFP_RECLAIM | __GFP_IO (i.e. GFP_KERNEL minus __GFP_FS). GFP_NOIO = __GFP_RECLAIM alone (minus both __GFP_FS and __GFP_IO). These exist to break a reclaim recursion deadlock. Consider a filesystem that, while holding a transaction lock, allocates memory. If that allocation triggers direct reclaim, and reclaim tries to write back a dirty page belonging to the same filesystem, reclaim calls back into the FS — which tries to take the lock the original caller already holds. Deadlock. Clearing __GFP_FS tells reclaim “do not recurse into the filesystem layer”; clearing __GFP_IO (which implies clearing __GFP_FS too) goes further and forbids starting any physical I/O, so reclaim is limited to dropping clean pages and slab.

The modern kernel discourages passing GFP_NOFS/GFP_NOIO directly. Since Linux 4.12 the preferred mechanism is the scope API — memalloc_nofs_save()/memalloc_nofs_restore() and memalloc_noio_save()/memalloc_noio_restore() — which marks a critical section so that “any allocation from that scope will inherently drop __GFP_FS respectively __GFP_IO from the given mask so no memory allocation can recurse back in the FS/IO” (GFP-from-FS/IO doc). The doc explains why: explicit GFP_NOFS led to “abuses when the restricted gfp mask is used ‘just in case’,” and over-restricting reclaim causes over-reclaim and other pathologies. The scope API confines the restriction to exactly the code that needs it.

This is important enough — and stale enough in most secondary write-ups — that it gets its own section below. The Scope API — What Replaced GFP_NOFS and GFP_NOIO covers the mechanism, the nesting rules, a real filesystem caller, and the one place the scope API is not optional.

The Modifier Bits — __GFP_*

The named combinations are built from these. Grouped by the documentation’s own headings:

Zone modifiers (low four bits, in mmzone.h order): __GFP_DMA, __GFP_HIGHMEM, __GFP_DMA32, __GFP_MOVABLE. These select which zone is acceptable. GFP_DMA/GFP_DMA32 “exist for historical reasons and should be avoided where possible” — GFP_DMA forces ZONE_DMA (the lowest 16 MiB on x86-64), used by ancient ISA-era devices and a few drivers that abuse it as an emergency reserve.

Page-mobility/placement hints: __GFP_MOVABLE (also a zone modifier — the page “can be moved by page migration during memory compaction or can be reclaimed”); __GFP_RECLAIMABLE (for slab allocations with SLAB_RECLAIM_ACCOUNT, freeable via shrinkers); __GFP_WRITE (caller intends to dirty the page — spread such pages across zones for fair dirty distribution); __GFP_HARDWALL (enforce cpuset policy); __GFP_THISNODE (“forces the allocation to be satisfied from the requested node with no fallbacks”); __GFP_ACCOUNT (charge to memcg).

Watermark modifiers — access to emergency reserves: __GFP_HIGH (“the caller is high-priority and… granting the request is necessary before the system can make forward progress”); __GFP_MEMALLOC (“allows access to all memory” — reserved for the MM itself and code that guarantees it will free memory shortly, e.g. swap-over-NFS); __GFP_NOMEMALLOC (explicitly forbids reserves, and takes precedence over __GFP_MEMALLOC if both are set).

Reclaim modifiers — and here is the most important caveat in the whole header: “all the following flags are only applicable to sleepable allocations (e.g. GFP_NOWAIT and GFP_ATOMIC will ignore them).”

• __GFP_IO — reclaim “can start physical IO.”
• __GFP_FS — reclaim “can call down to the low-level FS”; clearing it “avoids the allocator recursing into the filesystem which might already be holding locks.”
• __GFP_DIRECT_RECLAIM — “the caller may enter direct reclaim” (the bit that permits sleeping; see context section below).
• __GFP_KSWAPD_RECLAIM — “the caller wants to wake kswapd when the low watermark is reached and have it reclaim pages until the high watermark is reached.” See kswapd and Background Reclaim.
• __GFP_NORETRY — try only very lightweight reclaim, avoid the OOM killer, expect failure; “suitable when failure can easily be handled at small cost.”
• __GFP_RETRY_MAYFAIL — retry harder than __GFP_NORETRY (wait for compaction and page-out), but still may fail “only when there is genuinely little unused memory”; failure “indicates that the system is likely to need to use the OOM killer soon.”
• __GFP_NOFAIL — “the VM implementation must retry infinitely: the caller cannot handle allocation failures… Testing for failure is pointless.” It “must be blockable and used together with __GFP_DIRECT_RECLAIM” and “should never be used in non-sleepable contexts.” Order > 1 buddy allocations with __GFP_NOFAIL are unsupported — use kvmalloc() instead.

The three retry modifiers override the allocator’s default give-up policy, which depends on request size: “!costly allocations are too essential to fail so they are implicitly non-failing by default… while costly requests try to be not disruptive and back off even without invoking the OOM killer.” All three “must be used along with __GFP_DIRECT_RECLAIM.”

Action modifiers: __GFP_NOWARN (suppress failure reports); __GFP_COMP (allocate a compound page with proper metadata); __GFP_ZERO (“returns a zeroed page on success”); __GFP_ZEROTAGS, __GFP_SKIP_ZERO, __GFP_SKIP_KASAN (memory-tagging / KASAN interactions, only meaningful in HW_TAGS mode).

Why Atomic Context Cannot Sleep — The Mechanical Reason

The task that most often confuses newcomers: why must GFP_ATOMIC/GFP_NOWAIT clear __GFP_DIRECT_RECLAIM? The answer is a chain of mechanism, not a convention.

1. Direct reclaim blocks. When the fast path fails to find free pages above the watermark, the slow path may enter direct reclaim — the allocating task itself scans LRU lists, writes dirty pages to disk, waits for I/O, possibly waits on locks. Every one of those is a sleeping operation: the task is descheduled and the CPU runs something else until the work completes.

2. Sleeping requires a schedulable task context. schedule() switches away from the current task and back later. That only works if there is a resumable task context to return to and it is safe to run the scheduler. Two contexts violate that:

   • Interrupt / softirq context. An interrupt handler runs “borrowed” on whatever task happened to be executing; there is no thread of its own to put to sleep, and the scheduler must not run with interrupts in this state. Calling a blocking function here corrupts the system.
   • Holding a spinlock (or other preemption-disabled region). A spinlock disables preemption on its CPU; another CPU spinning to acquire the same lock will spin forever if the holder sleeps and never gets rescheduled — a classic deadlock. See kernel synchronization for the spinlock-vs-sleep rules.

3. Therefore the allocator must not enter direct reclaim from those contexts — which means the GFP mask must not carry __GFP_DIRECT_RECLAIM. GFP_ATOMIC and GFP_NOWAIT encode exactly this: no __GFP_DIRECT_RECLAIM, so gfp_to_alloc_flags() in page_alloc.c sets ALLOC_NON_BLOCK and the allocator takes a path that never calls schedule(). The kernel-doc states the rule operationally: “If the allocation is performed from an atomic context, e.g interrupt handler, use GFP_NOWAIT.”

The cost of getting this wrong is not subtle: with CONFIG_DEBUG_ATOMIC_SLEEP, might_sleep() inside the reclaim path fires a loud “BUG: sleeping function called from invalid context” backtrace; without it, you get an intermittent hard-to-reproduce deadlock.

The annotation that produces that warning is might_alloc(), declared in include/linux/sched/mm.h and called at the top of the allocator entry points. It is three lines, and each does distinct work:

static inline void might_alloc(gfp_t gfp_mask)
{
	fs_reclaim_acquire(gfp_mask);   /* take a fake lockdep lock named "fs_reclaim" */
	fs_reclaim_release(gfp_mask);   /* release it immediately */
	might_sleep_if(gfpflags_allow_blocking(gfp_mask));
}

gfpflags_allow_blocking() is literally !!(gfp_flags & __GFP_DIRECT_RECLAIM) (include/linux/gfp.h) — the sleeping question reduced to one bit test. might_sleep_if() then raises the “sleeping function called from invalid context” splat if that bit is set while preemption is disabled or we are in interrupt context.

The fs_reclaim_acquire/release pair is subtler and is the mechanism that catches the other class of GFP bug. It acquires and immediately releases a fake lockdep lock called fs_reclaim, which exists only so lockdep can reason about reclaim recursion as if it were a real lock ordering. The gate is __need_reclaim() in mm/page_alloc.c: the fake lock is taken only when __GFP_DIRECT_RECLAIM is set, the task is not already PF_MEMALLOC, and __GFP_NOLOCKDEP is not set — and the fs_reclaim map itself is acquired only if __GFP_FS survives current_gfp_context(). Reclaim’s own code takes the same fake lock. So if a filesystem holds lock L and then does a __GFP_FS allocation, lockdep records L → fs_reclaim; if reclaim ever takes L while inside reclaim, it records fs_reclaim → L, and the cycle is reported as a potential deadlock the first time either order is observed, without the deadlock ever actually happening. That is the single most valuable debugging property of the whole GFP system, and it is why CONFIG_LOCKDEP kernels should be part of any filesystem or block-driver test matrix.

flowchart TB
    START["caller: kmalloc gfp"]
    MA["might_alloc gfp"]
    B{"__GFP_DIRECT_RECLAIM set?"}
    NB["no fake lock, no might_sleep<br/>allocator takes the ALLOC_NON_BLOCK path"]
    LD{"already PF_MEMALLOC?<br/>or __GFP_NOLOCKDEP?"}
    SKIP["skip lockdep annotation<br/>(we are inside reclaim already)"]
    CTX["current_gfp_context gfp<br/>applies the active scope:<br/>PF_MEMALLOC_NOIO clears IO and FS<br/>PF_MEMALLOC_NOFS clears FS<br/>PF_MEMALLOC_PIN clears MOVABLE"]
    FS{"__GFP_FS still set<br/>after the scope?"}
    ACQ["acquire+release the fake<br/>fs_reclaim lockdep map"]
    NOACQ["mmu_notifier map only"]
    MS["might_sleep_if true:<br/>splat if preemption disabled<br/>or in interrupt context"]
    START --> MA --> B
    B -->|"no"| NB
    B -->|"yes"| LD
    LD -->|"yes"| SKIP
    LD -->|"no"| CTX --> FS
    FS -->|"yes"| ACQ
    FS -->|"no"| NOACQ
    ACQ --> MS
    NOACQ --> MS

How a GFP mask is checked before a single page is touched. What it shows: two independent debug paths hang off the mask — might_sleep_if() guards the context rule (may I sleep here?), and the fs_reclaim fake lockdep map guards the recursion rule (may reclaim call back into me?). The insight: current_gfp_context() is applied before the lockdep check, which means the scope API is not merely advisory bookkeeping — an active memalloc_nofs_save() scope genuinely changes what lockdep will and will not complain about, exactly as if the caller had passed GFP_NOFS by hand.

From Mask to Behaviour — gfp_to_alloc_flags() and the Watermark Arithmetic

A GFP mask is not consumed directly by the allocator’s hot loop. It is first translated into a second, internal bitfield — alloc_flags, the ALLOC_* constants in mm/internal.h — by gfp_to_alloc_flags() in mm/page_alloc.c. Understanding this translation is what turns “GFP_ATOMIC can use reserves” from a slogan into a number.

static inline unsigned int
gfp_to_alloc_flags(gfp_t gfp_mask, unsigned int order)
{
	unsigned int alloc_flags = ALLOC_WMARK_MIN | ALLOC_CPUSET;
 
	BUILD_BUG_ON(__GFP_HIGH != (__force gfp_t) ALLOC_MIN_RESERVE);
	BUILD_BUG_ON(__GFP_KSWAPD_RECLAIM != (__force gfp_t) ALLOC_KSWAPD);
 
	alloc_flags |= (__force int)
		(gfp_mask & (__GFP_HIGH | __GFP_KSWAPD_RECLAIM));
 
	if (!(gfp_mask & __GFP_DIRECT_RECLAIM)) {
		if (!(gfp_mask & __GFP_NOMEMALLOC)) {
			alloc_flags |= ALLOC_NON_BLOCK;
			if (order > 0)
				alloc_flags |= ALLOC_HIGHATOMIC;
		}
		if (alloc_flags & ALLOC_MIN_RESERVE)
			alloc_flags &= ~ALLOC_CPUSET;
	} else if (unlikely(rt_or_dl_task(current)) && in_task())
		alloc_flags |= ALLOC_MIN_RESERVE;
 
	alloc_flags = gfp_to_alloc_flags_cma(gfp_mask, alloc_flags);
	return alloc_flags;
}

The two BUILD_BUG_ON lines are the cleverest thing in the function and worth pausing on. ALLOC_MIN_RESERVE is 0x20 and __GFP_HIGH is 0x20; ALLOC_KSWAPD is 0x800 and __GFP_KSWAPD_RECLAIM is 0x800. The numeric values were deliberately chosen to coincide, so those two GFP bits can be copied straight across with a single mask-and-OR instead of two conditional branches — and the BUILD_BUG_ONs make the build fail if anyone ever renumbers either enum and breaks the coincidence. This is also a nice cross-check on the bit table above: __GFP_HIGH at bit 5 is 0x20, matching ALLOC_MIN_RESERVE.

GFP input	Resulting alloc_flags	Effect
always	ALLOC_WMARK_MIN | ALLOC_CPUSET	Slow-path baseline: check against the min watermark and enforce cpusets.
__GFP_HIGH	ALLOC_MIN_RESERVE (0x20)	Halves the effective min watermark.
__GFP_KSWAPD_RECLAIM	ALLOC_KSWAPD (0x800)	Permits waking kswapd.
no __GFP_DIRECT_RECLAIM, no __GFP_NOMEMALLOC	ALLOC_NON_BLOCK (0x10)	Cuts a further quarter off the already-halved min.
the above and order > 0	ALLOC_HIGHATOMIC (0x200)	May take pages from the MIGRATE_HIGHATOMIC pageblock reserve.
__GFP_HIGH and non-blocking	clears ALLOC_CPUSET	Atomic high-priority requests ignore cpuset limits rather than fail.
__GFP_MEMALLOC, or PF_MEMALLOC task	ALLOC_NO_WATERMARKS (0x04)	Watermarks skipped entirely (via __gfp_pfmemalloc_flags()).
task is an OOM victim	ALLOC_OOM (0x08)	Halves min again so the corpse can allocate enough to finish dying.
__GFP_NOMEMALLOC	returns 0 from __gfp_pfmemalloc_flags()	Hard veto — checked first, so it beats __GFP_MEMALLOC.
real-time or deadline task, in task context	ALLOC_MIN_RESERVE	RT tasks get reserve access even on a sleeping allocation.

Then, in __zone_watermark_ok(), those flags become actual arithmetic on the watermark the request must clear:

if (unlikely(alloc_flags & ALLOC_RESERVES)) {
	if (alloc_flags & ALLOC_MIN_RESERVE) {
		min -= min / 2;                  /* __GFP_HIGH: 50% of min */
		if (alloc_flags & ALLOC_NON_BLOCK)
			min -= min / 4;          /* + non-blocking: 25% more */
	}
	if (alloc_flags & ALLOC_OOM)
		min -= min / 2;                  /* OOM victim: half again */
}
if (free_pages <= min + z->lowmem_reserve[highest_zoneidx])
	return false;

Walk the arithmetic with a concrete number. Take the Node 0 Normal zone from the real OOM capture in The OOM Killer, where min:451700kB:

Caller	alloc_flags	Effective min	Value at min = 451,700 kB
GFP_KERNEL (ordinary)	ALLOC_WMARK_MIN	min	451,700 kB
GFP_NOWAIT	+ALLOC_NON_BLOCK	min (no ALLOC_MIN_RESERVE, so the /4 is never reached)	451,700 kB
GFP_ATOMIC	+ALLOC_MIN_RESERVE +ALLOC_NON_BLOCK	min/2 − min/8 = 3/8 of min	169,387 kB
OOM victim with __GFP_HIGH	+ALLOC_OOM	3/8 then halved again	84,693 kB
__GFP_MEMALLOC	ALLOC_NO_WATERMARKS	none	0

The reserve ladder, as real kilobytes on a 128 GB machine. What it shows: GFP_ATOMIC does not get “the reserve” — it gets permission to allocate down to three-eighths of the min watermark, roughly 280 MB deeper than an ordinary GFP_KERNEL caller on this box. The insight: this is exactly why the kernel doc warns against reflexive GFP_ATOMIC. That 280 MB is a shared, finite buffer sized for genuinely un-deferrable allocations; every driver that uses GFP_ATOMIC “to be safe” is spending it. And note row two — GFP_NOWAIT gets no watermark relief at all, because the min/4 discount is nested inside the ALLOC_MIN_RESERVE branch. The in-tree comment says so explicitly: “Other non-blocking allocations requests such as GFP_NOWAIT or (GFP_KERNEL & ~__GFP_DIRECT_RECLAIM) do not get access to the min reserve.”

The Scope API — What Replaced GFP_NOFS and GFP_NOIO

If a write-up presents raw GFP_NOFS/GFP_NOIO as current best practice, it is stale.

Since Linux 4.12 the recommended mechanism is the scope API. The gfp_types.h header now says so at each macro: “Please try to avoid using this flag directly and instead use memalloc_nofs_{save,restore} to mark the whole scope which cannot/shouldn’t recurse into the FS layer with a short explanation why.”

The problem the flags were solving

Restate it precisely, because the fix only makes sense against the exact failure. A filesystem takes a transaction lock L, then allocates memory. The allocation is GFP_KERNEL, so it may enter direct reclaim. Reclaim looks for something to evict, finds a dirty page belonging to this same filesystem, and calls the filesystem’s writeback path to clean it. That path tries to take L. L is held by the task that is currently inside reclaim, in its own allocation. The task deadlocks against itself. Clearing __GFP_FS forbids reclaim from calling into the filesystem at all; clearing __GFP_IO goes further and forbids reclaim from starting any physical I/O, leaving it only clean pages and slab to drop.

sequenceDiagram
    autonumber
    participant T as "filesystem task"
    participant FS as "FS transaction lock L"
    participant AL as "page allocator"
    participant RC as "direct reclaim"
    participant WB as "FS writeback path"

    rect rgb(250, 235, 235)
    Note over T,WB: WRONG — GFP_KERNEL inside the transaction
    T->>FS: acquire L
    T->>AL: kmalloc(size, GFP_KERNEL)
    AL->>RC: fast path missed, enter direct reclaim
    RC->>WB: writepage on a dirty page of THIS fs
    WB->>FS: acquire L
    Note over FS,WB: L is held by T, which is blocked<br/>inside its own allocation — self-deadlock
    end

    rect rgb(235, 245, 235)
    Note over T,WB: RIGHT — scope API around the transaction
    T->>T: flags = memalloc_nofs_save()
    T->>FS: acquire L
    T->>AL: kmalloc(size, GFP_KERNEL)
    AL->>AL: current_gfp_context() clears __GFP_FS
    AL->>RC: enter direct reclaim WITHOUT __GFP_FS
    RC-->>AL: drops clean pages and slab only,<br/>never calls the FS
    AL-->>T: page (or NULL)
    T->>FS: release L
    T->>T: memalloc_nofs_restore(flags)
    end

The reclaim-recursion deadlock and the scope fix, side by side. What it shows: the deadlock is a genuine lock cycle — L → fs_reclaim → L — not a resource shortage, which is why it manifests as a permanent hang rather than an allocation failure. The insight: the scope API does not change what the caller asks for. The caller still writes GFP_KERNEL. The restriction is applied by the allocator, from task state, at the moment of allocation — which is precisely what makes it work across layer boundaries the caller cannot see.

The mechanism

The whole thing is about fifteen lines. memalloc_nofs_save() sets a per-task process flag; current_gfp_context(), called at the top of the allocator, subtracts the corresponding GFP bits from whatever mask was passed in. Both live in include/linux/sched/mm.h:

static inline unsigned memalloc_flags_save(unsigned flags)
{
	unsigned oldflags = ~current->flags & flags;   /* only the bits WE set */
	current->flags |= flags;
	return oldflags;
}
 
static inline unsigned int memalloc_nofs_save(void)
{
	return memalloc_flags_save(PF_MEMALLOC_NOFS);
}
 
static inline gfp_t current_gfp_context(gfp_t flags)
{
	unsigned int pflags = READ_ONCE(current->flags);
 
	if (unlikely(pflags & (PF_MEMALLOC_NOIO | PF_MEMALLOC_NOFS | PF_MEMALLOC_PIN))) {
		/* NOIO implies both NOIO and NOFS and it is a weaker context
		 * so always make sure it makes precedence */
		if (pflags & PF_MEMALLOC_NOIO)
			flags &= ~(__GFP_IO | __GFP_FS);
		else if (pflags & PF_MEMALLOC_NOFS)
			flags &= ~__GFP_FS;
 
		if (pflags & PF_MEMALLOC_PIN)
			flags &= ~__GFP_MOVABLE;
	}
	return flags;
}

The line that makes the API safe is unsigned oldflags = ~current->flags & flags;. The saved value is only the bits this call actually newly set — if the flag was already set by an outer scope, oldflags is zero, and the matching restore() clears nothing. That is what makes the API safely nestable, which the documentation states as a guarantee: “the proper pairing of save/restore functions allows nesting so it is safe to call memalloc_noio_save or memalloc_noio_restore respectively from an existing NOIO or NOFS scope” (GFP-from-FS/IO doc). A naive “save the old value, restore it verbatim” implementation would let an inner scope’s restore cancel an outer scope’s protection — a bug class this design makes unrepresentable.

Note also the ordering comment: PF_MEMALLOC_NOIO takes precedence over PF_MEMALLOC_NOFS because NOIO is the weaker (more restrictive) context, and it clears __GFP_FS as well as __GFP_IO — the implication NOIO ⟹ NOFS is enforced here, once, rather than being every caller’s responsibility.

Scope function	Process flag	Effect on every allocation in scope	Since
memalloc_noio_save() / _restore()	PF_MEMALLOC_NOIO	clears __GFP_IO and __GFP_FS	3.9
memalloc_nofs_save() / _restore()	PF_MEMALLOC_NOFS	clears __GFP_FS	4.12
memalloc_noreclaim_save() / _restore()	PF_MEMALLOC	implicitly adds __GFP_MEMALLOC: no reclaim entered, all reserves available	4.12
memalloc_pin_save() / _restore()	PF_MEMALLOC_PIN	clears __GFP_MOVABLE — constrains to zones that allow long-term pinning	—

Version claims here were established by existence-check against the pinned trees rather than from changelog prose: memalloc_noio_save is absent from include/linux/sched.h at the v3.8 tag and present at v3.9; memalloc_nofs_save is absent from include/linux/sched/mm.h at v4.11 and present at v4.12. The 4.12 date is corroborated by the in-tree doc’s own wording (“Since 4.12 we do have a generic scope API”) and by commit 7dea19f9ee63, “mm: introduce memalloc_nofs_{save,restore} API”, Michal Hocko, dated 2017-05-03. memalloc_noreclaim_save() arrived alongside it in commit 499118e966f1 from Vlastimil Babka.

Why scopes beat flags — in the author’s own words

Hocko’s commit message enumerates the five reasons GFP_NOFS was actually being used in the tree, and the list is the argument:

• to prevent from deadlocks when the lock held by the allocation context would be needed during the memory reclaim
• to prevent from stack overflows during the reclaim because the allocation is performed from a deep context already
• to prevent lockups when the allocation context depends on other reclaimers to make a forward progress indirectly
• just in case because this would be safe from the fs POV
• silence lockdep false positives

The last two are not reasons; they are habits. And the cost is stated plainly: “Memory reclaim is much weaker (especially during heavy FS metadata workloads), OOM killer cannot be invoked because the MM layer doesn’t have enough information about how much memory is freeable by the FS layer.” That second clause is not rhetorical — it is literally gate 4 of out_of_memory(), which returns early for any allocation lacking __GFP_FS (see The OOM Killer). An over-broad GFP_NOFS habit silently disables the machine’s last-resort recovery for that call path.

The other argument is a layering one, and it is the decisive practical point: “this also helps code paths where FS layer interacts with other layers (e.g. crypto, security modules, MM etc…) and there is no easy way to convey the allocation context between the layers.” A flag has to be threaded through every function signature between the transaction and the allocation. A scope does not.

A real caller

jbd2, the ext4 journal, is the canonical example, and it is exactly three lines of code across two files. When a journal handle is opened in start_this_handle() (fs/jbd2/transaction.c):

	/*
	 * Ensure that no allocations done while the transaction is open are
	 * going to recurse back to the fs layer.
	 */
	handle->saved_alloc_context = memalloc_nofs_save();
	return 0;

and when it is stopped:

	/*
	 * Scope of the GFP_NOFS context is over here and so we can restore the
	 * original alloc context.
	 */
	memalloc_nofs_restore(handle->saved_alloc_context);

The saved cookie lives on the handle, not on the stack, because a journal handle outlives the function that created it — which is itself a small demonstration of why threading a GFP flag through would have been impractical. XFS does the same through xfs_trans_set_context(), and its comment records a second motivation for the ordering: it allocates the transaction object before entering the scope “so that we avoid lockdep false positives by doing GFP_KERNEL allocations inside sb_start_intwrite()” (fs/xfs/xfs_trans.c).

The one place the scope API is not optional

vmalloc() does not honour a GFP_NOFS mask passed to it. The in-tree doc is unambiguous: “vmalloc doesn’t support GFP_NOFS semantic because there are hardcoded GFP_KERNEL allocations deep inside the allocator which are quite non-trivial to fix up. That means that calling vmalloc with GFP_NOFS/GFP_NOIO is almost always a bug.” Those internal GFP_KERNEL allocations (page tables, the vm_struct) ignore your mask entirely — but they do go through current_gfp_context(), so they do respect an active scope. The recommended fix is therefore to wrap the vmalloc() call in memalloc_nofs_save()/restore() “with a comment explaining the problem”. This is the clearest possible demonstration that the two mechanisms are not equivalent: one is a parameter that a callee may ignore, the other is task state that no callee can escape.

__GFP_NOFAIL and the Retry Policies

The default give-up policy is not a constant; it depends on the request size. The header states the rule and the reason: “We have a concept of so-called costly allocations (with order > PAGE_ALLOC_COSTLY_ORDER). !costly allocations are too essential to fail so they are implicitly non-failing by default (with some exceptions like OOM victims might fail so the caller still has to check for failures) while costly requests try to be not disruptive and back off even without invoking the OOM killer.” PAGE_ALLOC_COSTLY_ORDER is 3, so “costly” means more than eight contiguous pages.

The three retry modifiers override that default, and all three “must be used along with __GFP_DIRECT_RECLAIM” — they are meaningless on a mask that cannot sleep.

flowchart TB
    REQ["allocation reaches<br/>__alloc_pages_slowpath"]
    DR{"__GFP_DIRECT_RECLAIM?"}
    NB["no reclaim possible:<br/>return NULL immediately"]
    RECL["wake kswapd, direct reclaim,<br/>direct compaction"]
    NORETRY{"__GFP_NORETRY?"}
    OUT1["nopage: give up.<br/>OOM killer never invoked"]
    COSTLY{"order greater than 3<br/>i.e. costly?"}
    MAYFAIL{"__GFP_RETRY_MAYFAIL<br/>and compaction possible?"}
    OUT2["nopage: back off quietly,<br/>no OOM kill for costly orders"]
    RETRY{"should_reclaim_retry<br/>under 16 no-progress loops?"}
    OOM["__alloc_pages_may_oom<br/>see The OOM Killer"]
    NOFAIL{"__GFP_NOFAIL?"}
    FAILW["warn_alloc:<br/>'page allocation failure: order:N'<br/>return NULL"]
    CANSLEEP{"can_direct_reclaim?"}
    LEAK["return NULL ANYWAY —<br/>the nofail contract is<br/>silently broken"]
    FALLBACK["__alloc_pages_cpuset_fallback<br/>with ALLOC_MIN_RESERVE<br/>then cond_resched and retry FOREVER"]

    REQ --> DR
    DR -->|"no"| NB
    DR -->|"yes"| RECL --> NORETRY
    NORETRY -->|"yes"| OUT1
    NORETRY -->|"no"| COSTLY
    COSTLY -->|"yes"| MAYFAIL
    MAYFAIL -->|"no"| OUT2
    MAYFAIL -->|"yes"| RETRY
    COSTLY -->|"no"| RETRY
    RETRY -->|"yes"| RECL
    RETRY -->|"no"| OOM
    OOM -->|"still nothing"| NOFAIL
    NOFAIL -->|"no"| FAILW
    NOFAIL -->|"yes"| CANSLEEP
    CANSLEEP -->|"no"| LEAK
    CANSLEEP -->|"yes"| FALLBACK
    FALLBACK --> RECL

The give-up decision tree in __alloc_pages_slowpath(). What it shows: four distinct exits — an immediate NULL for non-sleeping masks, an early NULL for __GFP_NORETRY, a quiet back-off for costly orders, and an infinite loop for __GFP_NOFAIL. The insight: follow the CANSLEEP → no branch. If __GFP_NOFAIL is combined with a non-sleeping mask, the allocator returns NULL regardless, with the source comment “we disregard these unreasonable nofail requests and still return NULL”. A caller that took the __GFP_NOFAIL documentation at face value (“Testing for failure is pointless”) and skipped its NULL check will dereference a null pointer. This is the sharpest edge in the whole GFP system, and it is invisible from the flag’s own kernel-doc.

Modifier	Reclaim effort	OOM killer?	Can return NULL?	Documented use
(none, order ≤ 3)	full: reclaim, compaction, up to 16 retry loops	yes	in practice rarely — but “no guarantee of that behavior so failures have to be checked”	the default; GFP_KERNEL
(none, order > 3)	full, then backs off	no	yes, readily	large buffers
__GFP_NORETRY	“only very lightweight memory direct reclaim”	no	yes, likely under pressure	“when failure can easily be handled at small cost, such as reduced throughput”
__GFP_RETRY_MAYFAIL	waits for compaction and page-out; a larger retry limit than NORETRY	no	yes, “but only when there is genuinely little unused memory”	large allocations with a slow fallback; failure “indicates that the system is likely to need to use the OOM killer soon”
__GFP_NOFAIL	infinite	yes, repeatedly	only if misused (see above)	“only when there is no reasonable failure policy”

Four constraints on __GFP_NOFAIL that the header states and that are worth memorising, because violating any of them is a real bug:

1. It must be blockable. “It must be blockable and used together with __GFP_DIRECT_RECLAIM. It should never be used in non-sleepable contexts.” Enforced only by the silent-NULL behaviour traced above.
2. Order > 1 from the buddy allocator is unsupported. “Allocating pages from the buddy with __GFP_NOFAIL and order > 1 is not supported. Please consider using kvmalloc() instead.” An infinite loop waiting for a large contiguous run is a hang, not a retry.
3. It gets ALLOC_MIN_RESERVE, not ALLOC_NO_WATERMARKS. The retry loop calls __alloc_pages_cpuset_fallback(gfp_mask, order, ALLOC_MIN_RESERVE, ac) with the comment: “Help non-failing allocations by giving some access to memory reserves normally used for high priority non-blocking allocations but do not use ALLOC_NO_WATERMARKS because this could deplete whole memory reserves which would just make the situation worse.”
4. kvmalloc() handles it by rewriting your mask. kmalloc_gfp_adjust() in mm/util.c strips __GFP_NOFAIL for requests larger than a page, adds __GFP_NOWARN and (absent __GFP_RETRY_MAYFAIL) __GFP_NORETRY, with the comment “nofail semantic is implemented by the vmalloc fallback”. So kvmalloc(big, GFP_KERNEL | __GFP_NOFAIL) does not loop in the buddy allocator at all — it fails fast to vmalloc, which is the correct way to honour a no-fail contract for a large request. kvmalloc() also documents its own mask restrictions: “GFP_NOWAIT and GFP_ATOMIC are not supported, neither is the __GFP_NORETRY modifier.”

The one high-profile in-tree __GFP_NOFAIL user is worth seeing, because it shows the pattern the flag was designed for: XFS allocates its transaction object with kmem_cache_zalloc(xfs_trans_cache, GFP_KERNEL | __GFP_NOFAIL). It is a small, fixed-size, order-0 slab object, allocated from sleepable process context at a point where the filesystem has no way to unwind — precisely the “no reasonable failure policy” case, and precisely not the “large buffer I would rather not check” case.

Common Misunderstanding — __GFP_ATOMIC No Longer Exists

Many textbooks and older blog posts describe a bit named __GFP_ATOMIC and explain GFP_ATOMIC as __GFP_ATOMIC | __GFP_HIGH. That bit was deleted. Commit 2973d8229b78 (“mm: discard __GFP_ATOMIC”, NeilBrown, dated 2023-01-13) removed it; verified by source inspection, __GFP_ATOMIC is present in the v6.1 and v6.2 headers and absent from v6.3 onward — so it was removed in the 6.3 release (April 2023), and is long gone from 6.12, 6.18, and 7.1. The commit’s rationale, read from the patch itself:

__GFP_ATOMIC serves little purpose. Its main effect is to set ALLOC_HARDER which adds a few little boosts to increase the chance of an allocation succeeding, one of which is to lower the water-mark at which it will succeed. It is always paired with __GFP_HIGH which sets ALLOC_HIGH which also adjusts this watermark. It is probable that other users of __GFP_HIGH should benefit from the other little bonuses that __GFP_ATOMIC gets.

The change was therefore not a pure deletion: it also “allows __GFP_HIGH allocations to ignore watermark boosting as well as GFP_ATOMIC requests”, so a handful of subsystems named in the changelog (xen, dm, md, ntfs3, hibernation, ksm, swap) gained privileges they had not had. The commit states the net effect precisely: “The net result is not change to GFP_ATOMIC allocations. Other allocations that use __GFP_HIGH will benefit from a few different extra privileges.”

Today GFP_ATOMIC is simply __GFP_HIGH | __GFP_KSWAPD_RECLAIM — the “atomic-ness” is conveyed by the absence of __GFP_DIRECT_RECLAIM, not by a positive bit. Two downstream traces of the removal survive in v6.12 and are useful sanity checks when reading older material: bit 9 of the gfp_t word is still an explicit hole (___GFP_UNUSED_BIT, /* 0x200u unused */), and ALLOC_HARDER no longer exists in mm/internal.h — it was split into the finer-grained ALLOC_MIN_RESERVE and ALLOC_NON_BLOCK documented above. Any explanation of GFP_ATOMIC that mentions ALLOC_HARDER predates 6.3.

A dated caveat on calling context. The v6.12 header says GFP_ATOMIC’s “current implementation doesn’t support NMI and few other strict non-preemptive contexts (e.g. raw_spin_lock). The same applies to GFP_NOWAIT.” At v7.1 that sentence has been sharpened to name the real-time kernel explicitly: “doesn’t support NMI, nor contexts that disable preemption under PREEMPT_RT. This includes raw_spin_lock() and plain preempt_disable()”, with a pointer to Documentation/core-api/real-time/differences.rst. The underlying rule is the same on 6.12 — under PREEMPT_RT the ordinary spinlock becomes a sleeping lock, so it is raw_spin_lock() and preempt_disable() that mark a genuinely non-preemptible region — but if you are writing for an RT kernel, read the 7.x wording rather than the 6.12 one. (As-of 2026-09.)

Previously flagged, now resolved

An earlier revision of this note carried an uncertainty callout on the internal ALLOC_* bits and their watermark effects. Resolved on 2026-09-04 by reading mm/internal.h and __zone_watermark_ok() at the v6.12 tag directly; the values and the min/2, min/4, min/2 arithmetic are transcribed in the From Mask to Behaviour section above. The caveat that motivated the flag still stands as guidance rather than doubt: ALLOC_* is not a stable API. ALLOC_HARDER existed before 6.3 and does not now; ALLOC_MIN_RESERVE/ALLOC_NON_BLOCK replaced it. Re-read mm/internal.h at whatever tag you actually run before quoting a number.

Failure Modes — How a Wrong Flag Becomes a Deadlock, Not an Error

The defining property of the GFP system is that its failure mode is asymmetric. Most bad arguments in the kernel produce an error return or a warning. A bad GFP mask produces a hang, and often not on the machine that ran the bad code — on a customer’s machine, months later, under a workload that finally made reclaim recurse. This section catalogues the ways.

Symptom	Underlying mask error	Why it is not an error return
BUG: sleeping function called from invalid context	GFP_KERNEL (or any mask with __GFP_DIRECT_RECLAIM) used in interrupt/softirq context or under a spinlock	Only a debug build catches it. Without CONFIG_DEBUG_ATOMIC_SLEEP the task calls schedule() from a context that has no schedulable thread, and the system corrupts or wedges.
Permanent hang in filesystem writeback, no OOM report	GFP_KERNEL inside a transaction that reclaim can re-enter	A genuine lock cycle L → fs_reclaim → L. Nothing fails; the task simply never returns.
possible recursive locking / inconsistent lock state from lockdep	same as above, but caught early	The fs_reclaim fake lock reported the ordering before the cycle ever closed. This is the good outcome.
Machine thrashes under FS metadata load; the OOM killer never fires	GFP_NOFS (or a memalloc_nofs_save() scope) applied too broadly	Gate 4 of out_of_memory() returns early for any allocation lacking __GFP_FS. Reclaim is weakened and the last-resort recovery is disabled. See The OOM Killer.
Sporadic order:0 allocation failures in unrelated drivers	reflexive GFP_ATOMIC in a hot path	The atomic reserve is a shared, finite pool three-eighths below min. Overuse drains it for everyone; the victims are other subsystems.
NULL dereference in code that “cannot fail”	__GFP_NOFAIL on a non-sleeping mask	__alloc_pages_slowpath() “disregard[s] these unreasonable nofail requests and still return[s] NULL”. The contract is silently voided.
Hang on a large allocation that used to work	__GFP_NOFAIL with order > 1 from the buddy allocator	Explicitly unsupported. The loop waits forever for a contiguous run that fragmentation may never produce. Use kvmalloc().
GFP_NOFS passed to vmalloc(), deadlock anyway	vmalloc has hardcoded internal GFP_KERNEL allocations	The mask is a parameter the callee may ignore. Only the scope API is inescapable.
GFP_DMA32 on a kmalloc(), DMA still fails	the DMA32 kmalloc cache array is not implemented	The flag is silently a no-op on the slab path. Use the DMA API.

Three of these deserve their own paragraph because they are the ones that reach production.

Reflexive GFP_ATOMIC is a tragedy of the commons. The reserve __GFP_HIGH unlocks is not per-caller; it is the gap between min and 3·min/8 in each zone, sized on the assumption that only genuinely un-deferrable allocations reach it. A driver that uses GFP_ATOMIC from a workqueue callback — where sleeping is perfectly legal — is spending a system-wide resource to avoid writing a fallback path. The kernel doc’s phrasing is a test you can apply: use GFP_ATOMIC only “if you think that accessing memory reserves is justified and the kernel will be stressed unless allocation succeeds”. If the honest answer is “my driver would be inconvenienced”, the right flag is GFP_NOWAIT plus a fallback.

Over-broad NOFS/NOIO scopes are the modern version of the same mistake. The scope API made the correct thing easy, but it also made it easy to wrap far more code than the critical section. Hocko’s commit message names “just in case because this would be safe from the fs POV” and “silence lockdep false positives” as two of the five real-world reasons GFP_NOFS was being used — neither is a reason, and the second actively suppresses the tool that would have found the real bug. The doc’s requirement that every scope carry “a short explanation why” is the countermeasure: if you cannot write the sentence, you do not need the scope.

__GFP_NOFAIL is a contract with a hole in it. Its kernel-doc says “Testing for failure is pointless”, and for a correctly-used order-0 sleepable allocation that is true. But the flag is not self-enforcing: combine it with a non-sleeping mask and you get NULL with no warning, no WARN_ON, and no diagnostic beyond a source comment. The defensive habit is to keep the NULL check anyway — it costs a branch that the compiler will predict perfectly, and it converts a null-pointer oops into a graceful failure if someone later changes the mask.

Choosing a Flag — A Decision Path

flowchart TB
    Q0{"Can this code sleep?<br/>process context,<br/>no spinlock held,<br/>not in IRQ or softirq"}
    Q0 -->|"no"| A1{"Do you have a<br/>clean fallback<br/>for failure?"}
    A1 -->|"yes"| GNW["GFP_NOWAIT<br/>no reserves, expects to fail,<br/>still wakes kswapd"]
    A1 -->|"no, and the kernel<br/>is stressed if this fails"| GAT["GFP_ATOMIC<br/>spends the shared reserve —<br/>justify it in a comment"]
    Q0 -->|"yes"| Q1{"Are you inside an FS<br/>transaction or a block-I/O<br/>critical section?"}
    Q1 -->|"yes"| SCOPE["wrap the section in<br/>memalloc_nofs_save / restore<br/>or memalloc_noio_save / restore<br/>then still pass GFP_KERNEL"]
    Q1 -->|"no"| Q2{"Is this allocation<br/>triggered by userspace and<br/>chargeable to a container?"}
    Q2 -->|"yes"| GKA["GFP_KERNEL_ACCOUNT"]
    Q2 -->|"no"| Q3{"Is the page for userspace<br/>rather than the kernel?"}
    Q3 -->|"yes"| Q4{"Must the kernel address it<br/>directly? Must it stay put?"}
    Q4 -->|"both yes"| GU["GFP_USER"]
    Q4 -->|"no direct access,<br/>must stay put"| GHU["GFP_HIGHUSER"]
    Q4 -->|"neither — movable"| GHM["GFP_HIGHUSER_MOVABLE<br/>ordinary anon and page-cache pages"]
    Q3 -->|"no"| Q5{"How large, and how badly<br/>do you need it?"}
    Q5 -->|"small, ordinary"| GK["GFP_KERNEL<br/>add __GFP_ZERO, or use kzalloc"]
    Q5 -->|"large, best-effort"| GNR["GFP_KERNEL plus<br/>__GFP_NORETRY and __GFP_NOWARN"]
    Q5 -->|"large, try hard,<br/>slow fallback exists"| GRM["GFP_KERNEL plus<br/>__GFP_RETRY_MAYFAIL"]
    Q5 -->|"might exceed a page,<br/>contiguity not required"| KV["kvmalloc — kmalloc then vmalloc"]
    Q5 -->|"small, truly no<br/>failure policy"| GNF["GFP_KERNEL plus __GFP_NOFAIL<br/>order 0 only, still check NULL"]

The decision tree, in the order the questions actually bind. What it shows: the first question is never “which flag?” — it is “what context am I in?”, because context is the only axis that makes a flag illegal rather than merely suboptimal. The insight: notice that the FS/IO branch does not end at a flag. The modern answer to “I am inside a transaction” is to change task state and keep passing GFP_KERNEL, which is why a decision tree drawn ten years ago would have had a GFP_NOFS leaf where this one has a scope.

Stated as prose, for the cases that come up daily:

• Process context, can sleep, ordinary kernel memory? → GFP_KERNEL. (Add __GFP_ZERO if you need it zeroed; that is what kzalloc does.)
• Same, but it is a userspace-triggered allocation that should count against a container? → GFP_KERNEL_ACCOUNT.
• Interrupt/softirq or holding a spinlock, and failure is hard to handle? → GFP_ATOMIC (spends reserves — use sparingly).
• Interrupt/softirq, but you have a clean fallback for failure? → GFP_NOWAIT (no reserves, expects to fail).
• Inside a filesystem transaction or block-I/O critical section? → use the memalloc_nofs_save() / memalloc_noio_save() scope API rather than passing GFP_NOFS/GFP_NOIO directly, and leave the allocation sites saying GFP_KERNEL.
• A large best-effort allocation you can live without? → GFP_KERNEL | __GFP_NORETRY | __GFP_NOWARN, or __GFP_RETRY_MAYFAIL if you want it to try harder first.
• Unsure whether the size exceeds what kmalloc can serve? → kvmalloc(), and free it with kvfree().

Production Notes

Decoding a mask from a log is a routine skill. When a kernel prints an allocation failure or an OOM header it emits the raw value and then the symbolic decode: gfp_mask=0x140dca(GFP_HIGHUSER_MOVABLE|__GFP_ZERO|__GFP_COMP). That decode is produced by the %pGg printk specifier and is greedy — it prefers the longest composite name that fits, which is why you see GFP_HIGHUSER_MOVABLE rather than seven __GFP_* names. When you need to go the other way, the bit table above is sufficient: 0x140dca = 0x100cca (GFP_HIGHUSER_MOVABLE) + 0x100 (__GFP_ZERO) + 0x40000 (__GFP_COMP). Two composites are worth memorising outright because they cover most reports: GFP_KERNEL is 0xcc0 and GFP_HIGHUSER_MOVABLE is 0x100cca. Seeing 0xcc0 tells you a kernel data structure failed; seeing 0x100cca tells you a user page fault failed, which is a completely different investigation.

The mask tells you whether an OOM kill was even possible. Cross-referencing with The OOM Killer: an allocation without __GFP_DIRECT_RECLAIM never reaches the OOM path at all, and an allocation without __GFP_FS is turned away at gate 4 of out_of_memory(). So gfp_mask=0x820(GFP_ATOMIC) in a page allocation failure splat means “no kill was ever going to happen here” — the correct response is to look at why the atomic reserve was empty, not at which process is fat. Likewise an order=4 failure would have been exempted for being costly. Reading the gfp_mask= and order= fields first saves the most time.

Test with lockdep on, at least somewhere. The fs_reclaim fake lock catches reclaim-recursion bugs before they deadlock, but only under CONFIG_LOCKDEP and only if the offending path is actually exercised. For filesystem and block-layer work this is not optional tooling — it is the only mechanism that turns a latent production hang into a boot-time splat on a developer’s machine. CONFIG_DEBUG_ATOMIC_SLEEP plays the same role for the sleeping-context rule.

Prefer narrowing an existing scope to adding a new one. When a reclaim-recursion warning appears, the tempting fix is another memalloc_nofs_save() around a wider region. That works and is invisible until the machine thrashes under metadata load with no OOM report. The better fix is almost always to move the allocation out of the critical section, or to narrow the scope to the few lines that genuinely hold the lock. Every scope is a small, permanent tax on the machine’s ability to reclaim.

Do not “upgrade” a mask to make a failure go away. Changing GFP_NOWAIT to GFP_ATOMIC, or adding __GFP_NOFAIL, converts a visible failure that your code was supposed to handle into an invisible cost paid by the rest of the system — a drained reserve, or an unbounded loop. Both changes look like they fixed the bug in testing. Neither did.

• Process context, can sleep, ordinary kernel memory? → GFP_KERNEL. (Add __GFP_ZERO if you need it zeroed; that is what kzalloc does.)
• Same, but it is a userspace-triggered allocation that should count against a container? → GFP_KERNEL_ACCOUNT.
• Interrupt/softirq or holding a spinlock, and failure is hard to handle? → GFP_ATOMIC (spends reserves — use sparingly).
• Interrupt/softirq, but you have a clean fallback for failure? → GFP_NOWAIT (no reserves, expects to fail).
• Inside a filesystem transaction or block-I/O critical section? → prefer the memalloc_nofs_save() / memalloc_noio_save() scope API over passing GFP_NOFS/GFP_NOIO directly.
• A large best-effort allocation you can live without? → GFP_KERNEL | __GFP_NORETRY | __GFP_NOWARN, or __GFP_RETRY_MAYFAIL if you want it to try harder first.

See Also

• Watermarks and the Allocation Fast Path — how __GFP_HIGH/__GFP_KSWAPD_RECLAIM/__GFP_DIRECT_RECLAIM map to the watermark the request must clear and to waking kswapd.
• The Buddy Allocator — the page allocator that consumes the GFP mask.
• Direct Reclaim — the sleeping reclaim path that __GFP_DIRECT_RECLAIM permits.
• kswapd and Background Reclaim — the background thread __GFP_KSWAPD_RECLAIM wakes.
• Memory Zones and Nodes — the zones the low-four-bit zone modifiers select among.
• The Memory Cgroup memcg — what __GFP_ACCOUNT / GFP_KERNEL_ACCOUNT charges.
• kmalloc and the kmalloc Caches and The Slab Allocator and SLUB — the most common callers passing GFP masks.
• Linux Kernel Synchronization MOC — the spinlock/sleep rules underlying “atomic context cannot sleep.”
• The OOM Killer — where a GFP_KERNEL allocation ends up when reclaim has nothing left, and why a mask without __GFP_FS can never get there.
• Memory Compaction — what __GFP_MOVABLE makes possible and what __GFP_RETRY_MAYFAIL waits for.
• Shrinkers and Slab Reclaim — what __GFP_RECLAIMABLE enrols a slab page into.
• Transparent Huge Pages — the caller of GFP_TRANSHUGE_LIGHT / GFP_TRANSHUGE, and why both clear __GFP_KSWAPD_RECLAIM.
• Compound Pages and Large Folios — what __GFP_COMP actually builds.
• Anonymous vs File-Backed Memory — the two page populations GFP_HIGHUSER_MOVABLE and GFP_KERNEL respectively tend to produce.
• MOC: Linux Memory Management MOC