The Core Page Allocator APIs

The kernel exposes a small family of exported, low-level allocation routines that any module or driver can call. They all live under include/linux/gfp.h and ultimately route through the buddy allocator we studied previously. Every one of them takes two key ideas as input: a GFP mask (explained below) describing the allocation context, and (for the “pages” variants) an order describing how many page frames to grab.

The single most important gotcha for beginners: alloc_page() and alloc_pages() do not hand you a usable memory address directly. They return a pointer to the kernel’s internal bookkeeping structure that describes that memory — generally called the page structure. To turn that into a real, usable kernel logical address, you must pass it through the address-conversion helper that every Linux kernel textbook and the kernel source itself documents, commonly known by the name page_address().

A Note for Modern Kernels: Folios

If you go digging through a very recent kernel source tree, you’ll notice memory-management code increasingly working with a newer data structure called a folio rather than directly with struct page. This is part of an ongoing, multi-year kernel-wide effort to simplify and shrink page-tracking metadata. For driver and module developers today, the classic APIs in the table above still work exactly as documented and remain the right starting point to learn the page allocator; folios mainly matter once you start working deep inside filesystem or core memory-management code.

Understanding GFP Flags

Every page allocator API call requires a GFP mask as its first argument — short for “Get Free Page” flags. GFP flags tell the memory-management subsystem how it is allowed to behave while trying to satisfy your request: can it pause and wait for memory to free up? Can it trigger reclaim? Which zone should it prefer?

There are many GFP flags used internally by core kernel code, but as a module or driver developer, two flags cover the overwhelming majority of real situations.

Why this rule matters so much: calling a sleeping-capable GFP_KERNEL allocation from inside an interrupt handler can deadlock or crash the kernel, because there’s no process context to put to sleep and resume later. Always match the flag to the context you are actually running in.

A Simple Kernel Module Example

Below is an original, simple example skeleton showing how these APIs typically appear together inside a kernel module’s init and exit functions. Build and test this only inside a disposable virtual machine while you’re learning.

#include <linux/module.h>
#include <linux/init.h>
#include <linux/gfp.h>
#include <linux/mm.h>

static unsigned long my_page;
static struct page *my_struct_page;

static int __init my_alloc_init(void)
{
    my_page = get_zeroed_page(GFP_KERNEL);
    if (!my_page)
        return -ENOMEM;

    my_struct_page = alloc_page(GFP_KERNEL);
    if (!my_struct_page) {
        free_page(my_page);
        return -ENOMEM;
    }

    pr_info("ep_alloc: zeroed page at %lx\n", my_page);
    pr_info("ep_alloc: page_address = %lx\n",
            (unsigned long)page_address(my_struct_page));
    return 0;
}

static void __exit my_alloc_exit(void)
{
    free_page(my_page);
    __free_page(my_struct_page);
    pr_info("ep_alloc: memory released\n");
}

module_init(my_alloc_init);
module_exit(my_alloc_exit);
MODULE_LICENSE("GPL");

Notice the discipline: every successful allocation has a matching free call in the exit path, and every failure path frees whatever was already allocated before returning an error. This pairing discipline is one of the most important habits to build early as a kernel developer.

Common Mistakes and Troubleshooting

Best Practices

Performance and Security Considerations

Performance: because these APIs go straight to the buddy allocator, they are extremely fast (logarithmic complexity), but high-order requests become progressively less likely to succeed instantly as the system runs and memory fragments — plan accordingly for long-running embedded deployments.

Security: remember that __get_free_page(), __get_free_pages(), alloc_page(), and alloc_pages() all return memory with random leftover content. Never share such memory with user space or another subsystem without explicitly zeroing it first — use get_zeroed_page() or an explicit memset when the destination is untrusted, to avoid leaking stale kernel data.

Summary / Key Takeaways

Conclusion

You now know how to call the kernel’s low-level page allocator APIs correctly, how to pick the right GFP flag for your context, and the most common mistakes to avoid. This knowledge directly carries into driver development, where DMA buffers, ring buffers, and other contiguous-memory needs are built on exactly these primitives. In the next lecture of this free Linux kernel development course, we will look at the SLAB/SLUB allocator that sits on top of the buddy system for smaller, more frequent allocations.

Frequently Asked Questions