vault

GFP Flags and Allocation Contexts

15 min read

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. All definitions are pinned to Linux 6.12 LTS (include/linux/gfp_types.h); the file is byte-for-byte identical in 6.18 LTS (verified against both tags, 2026-06-02), so every combination below holds for both current LTS branches. 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.

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 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.”

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.

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.

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”, authored 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 both 6.12 and 6.18 LTS. The commit’s rationale: “__GFP_ATOMIC serves little purpose. Its main effect is to set ALLOC_HARDER… It is always paired with __GFP_HIGH… It is probable that other users of __GFP_HIGH should benefit from the other little bonuses.” 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.

Uncertain

Verify: the exact internal ALLOC_* flag bits (ALLOC_MIN_RESERVE, ALLOC_NON_BLOCK, ALLOC_HIGHATOMIC) and their precise watermark effects are implementation details of mm/internal.h / page_alloc.c that shift between releases. The mapping __GFP_HIGH → ALLOC_MIN_RESERVE and __GFP_KSWAPD_RECLAIM → ALLOC_KSWAPD is confirmed by BUILD_BUG_ON assertions in gfp_to_alloc_flags() at v6.12, but the downstream watermark-lowering arithmetic should be read from the v6.12/v6.18 source if a precise number is needed. Reason: internal flags are not a stable API. To resolve: read mm/internal.h at the pinned tag. uncertain

Choosing a Flag — A Decision Path

  • 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

Graph View

Backlinks