← Previous Lecture | Next Lecture →

What Are GFP Flags in the Linux Kernel?

Every time a piece of kernel code — a driver, a filesystem, a network stack, anything running inside the
kernel — needs a chunk of memory, it has to tell the memory subsystem two things: how much memory it wants,
and under what conditions that memory can be obtained. The second part is the job of GFP flags
(“Get Free Page” flags). They are bitmasks passed to allocation functions such as kmalloc(),
kzalloc(), vmalloc(), and the low-level page allocator functions, and they describe
the calling context and the allocator’s behavior.

Unlike user-space malloc(), where the C library quietly handles all the details for you, kernel
code runs in many different contexts — process context, interrupt context, with locks held, without locks held —
and each context has different rules about what the allocator is allowed to do. GFP flags exist to communicate
those rules to the memory manager.

GFP_KERNEL: The Everyday Flag

GFP_KERNEL is the flag you will use for the vast majority of allocations in driver code. It
tells the kernel: “I am running in normal process context, it is fine if you have to wait, swap something out,
or trigger reclaim to satisfy this request.” This is sometimes described as the allocation being allowed to
sleep.

Sleeping in this context simply means the calling task can be put to the back of the scheduler’s run queue
while the kernel does the work needed to free up memory — for example writing dirty pages back to disk, or
reclaiming page cache. As long as your code is not holding a spinlock, not inside an interrupt handler, and not
inside any other atomic section, GFP_KERNEL is the safe and recommended default.

GFP_ATOMIC: The Cannot-Sleep Flag

Some code paths are not allowed to sleep at all. Interrupt handlers, code that holds a spinlock, tasklets,
and softirq handlers fall into this category. If such code tries to allocate memory with GFP_KERNEL
and the allocator decides it needs to sleep to satisfy the request, the result can be a hang, a kernel warning,
or in the worst case a full system freeze.

For these atomic contexts, the kernel provides GFP_ATOMIC. This flag tells the allocator:
“Do not sleep under any circumstances. Use the small emergency memory reserve if you must, but return
immediately, even if that means failing the allocation.” Because it dips into a limited reserve,
GFP_ATOMIC allocations are more likely to fail than GFP_KERNEL ones, so your code
must always check the return value and handle a NULL pointer gracefully.

Why “Safe to Sleep” Actually Matters

A spinlock is a busy-wait lock — the CPU spins in a tight loop until the lock is free, and on a
non-preemptible kernel it can also disable preemption. If the code holding that spinlock calls into an
allocator that decides to sleep, the scheduler cannot run anything else on that CPU, including whatever
task would eventually release the lock. The system effectively deadlocks itself. This is exactly why the
rule “never use a sleeping allocation while holding a spinlock” exists, and why GFP_ATOMIC is mandatory in
that situation. With a mutex, on the other hand, the kernel already expects the holding task may sleep, so
sleeping allocations under a mutex are perfectly fine.

__GFP_ZERO and Zeroed Memory

Plain page-allocator calls return memory whose contents are undefined — it may contain leftover data from
whatever previously used those physical pages. For security and correctness, you very often want freshly
zeroed memory instead. The __GFP_ZERO flag, bitwise-ORed with GFP_KERNEL or
GFP_ATOMIC, asks the allocator to zero the pages before handing them back. In modern driver
code you will rarely set this flag directly — instead you will reach for the zeroing wrapper functions
(such as kzalloc() for slab memory) which apply __GFP_ZERO internally.

/* A simple, modern example showing the difference between
 * an allocation that is allowed to sleep and one that is not.
 * This is illustrative sample code, not taken from any book or repository. */

struct my_dev_priv {
    int id;
    char name[32];
};

/* Safe in process context: probe(), open(), ioctl() without locks held */
static int alloc_in_process_context(struct my_dev_priv **out)
{
    struct my_dev_priv *p = kzalloc(sizeof(*p), GFP_KERNEL);
    if (!p)
        return -ENOMEM;
    *out = p;
    return 0;
}

/* Required inside an interrupt handler or while holding a spinlock */
static int alloc_in_atomic_context(struct my_dev_priv **out)
{
    struct my_dev_priv *p = kzalloc(sizeof(*p), GFP_ATOMIC);
    if (!p)
        return -ENOMEM;
    *out = p;
    return 0;
}

What Changed in Recent Kernels

The core GFP_KERNEL / GFP_ATOMIC distinction has stayed stable for decades because it reflects a
fundamental scheduling constraint, not an implementation detail — so the concepts you learn here remain
valid on the latest mainline kernels. A few things worth knowing if you are working on a current kernel
tree:

• The slab allocator landscape has simplified: SLAB and SLOB were removed from the mainline kernel,
  leaving SLUB as the single slab allocator, so kmalloc()/kzalloc() behavior is
  now more uniform across configurations.
• Memory allocation profiling/tracking infrastructure has been strengthened in recent releases, making
  it easier to see exactly which call site is responsible for a given allocation when debugging leaks.
• The GFP flag definitions and their documentation in include/linux/gfp_types.h (the flags
  themselves moved out of the older gfp.h location in newer trees) remain the authoritative,
  always-current reference — always check your own kernel source tree rather than relying purely on books.

Common Mistakes to Avoid

• Using GFP_KERNEL inside an interrupt handler — this is one of the most common causes of
  kernel warnings like “scheduling while atomic” or “sleeping function called from invalid context”.
• Forgetting that GFP_ATOMIC allocations can fail more often, and not checking the return
  value before dereferencing the pointer.
• Holding a spinlock across a call that internally allocates with GFP_KERNEL — including
  some library or subsystem helper functions that are not obviously allocation-related.
• Assuming a mutex and a spinlock behave the same way with respect to sleeping — they do not.

Best Practices

• Default to GFP_KERNEL unless you have a concrete reason — usually an atomic context —
  to use something else.
• Prefer the zeroing variants (kzalloc(), etc.) over manually OR-ing in __GFP_ZERO
  unless you are working directly with the low-level page allocator.
• Always check allocation return values, especially for GFP_ATOMIC.
• When unsure whether a function you are calling might sleep, check its documentation or source before
  calling it while holding a spinlock.

Summary / Key Takeaways

• GFP flags tell the kernel’s memory allocator what context an allocation is happening in.
• GFP_KERNEL is for process context where sleeping is acceptable; it is the common case.
• GFP_ATOMIC is mandatory in interrupt context or while holding a spinlock, and never sleeps.
• __GFP_ZERO requests zeroed memory and is normally applied for you by wrapper functions
  like kzalloc().
• These rules have remained stable across kernel versions because they reflect scheduling fundamentals,
  not version-specific implementation details.

FAQ

Q1. What does GFP stand for in the Linux kernel?
It stands for “Get Free Page,” reflecting the flags’ origin in the page allocator, though they are now used
across all kernel memory allocation interfaces.

Q2. Can I use GFP_KERNEL in an interrupt handler?
No. Interrupt handlers must not sleep, and GFP_KERNEL allocations are allowed to sleep, so this combination
can hang or crash the system. Use GFP_ATOMIC instead.

Q3. Why does GFP_ATOMIC fail more often than GFP_KERNEL?
Because it cannot wait for reclaim to free up memory; it can only use a small reserved pool, so under memory
pressure it is more likely to come back empty.

Q4. Is it safe to allocate memory with GFP_KERNEL while holding a mutex?
Yes, holding a mutex does not prevent the task from sleeping, so GFP_KERNEL is fine there, unlike with a
spinlock.

Q5. Do I need to manually add __GFP_ZERO when using kzalloc()?
No, kzalloc() already applies zeroing internally; you only need to think about __GFP_ZERO if
you are working directly with the lower-level page allocator functions.

Q6. Where can I find the current list of GFP flags in the kernel source?
In recent kernel trees the canonical definitions live in include/linux/gfp_types.h, with
detailed explanatory comments alongside them — always prefer checking your own kernel tree over older
printed references.

Q7. What happens if a GFP_ATOMIC allocation fails?
Your code must check for a NULL return and handle it gracefully — typically by returning an error such as
-ENOMEM up the call chain rather than dereferencing a NULL pointer.

← Previous Lecture | Next Lecture →