What You Will Learn

Prerequisites

What Is the Linux Kernel Page Allocator?

The Linux kernel manages physical RAM in fixed-size chunks called pages (typically 4 KB on most architectures). Whenever kernel code — like a device driver — needs raw physical memory, it does not ask for “bytes” the way user-space malloc() does. Instead, it asks the page allocator for whole pages.

The page allocator is built on an algorithm called the buddy system. It keeps free pages organized into power-of-two sized blocks (1, 2, 4, 8, 16 pages and so on). When you request memory, the buddy system finds the smallest available block that satisfies your request, splitting larger blocks if needed, and merging (“buddying”) blocks back together when memory is freed. This design keeps allocation fast and helps reduce external fragmentation.

Page Allocator APIs You Should Know

The kernel exposes several wrapper functions around the buddy system. Each one is suited to a slightly different use case.

A point that trips up many newcomers: alloc_page() and alloc_pages() do not hand you a usable pointer directly — they return a pointer to a struct page, the kernel’s bookkeeping structure describing that physical page. To get a usable kernel virtual address, you must convert it using page_address().

A Simple, Original Example Module

Below is a small, original demo (not copied from any book) showing how these APIs are typically combined inside an LKM’s init function. Replace my_module_name with your own module’s tag for log messages.

#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/gfp.h>

#define LOGTAG "pagealloc_demo"

static void *single_page;
static void *multi_page_block;
static struct page *page_descriptor;

static int __init pagealloc_demo_init(void)
{
    /* Request a single page */
    single_page = (void *)__get_free_page(GFP_KERNEL);
    if (!single_page)
        return -ENOMEM;
    pr_info("%s: single page allocated at %pK\n", LOGTAG, single_page);

    /* Request 4 contiguous pages (order = 2 -> 2^2 = 4) */
    multi_page_block = (void *)__get_free_pages(GFP_KERNEL | __GFP_ZERO, 2);
    if (!multi_page_block) {
        free_page((unsigned long)single_page);
        return -ENOMEM;
    }
    pr_info("%s: 4-page block allocated at %pK\n", LOGTAG, multi_page_block);

    /* Request one page via the descriptor-based API */
    page_descriptor = alloc_page(GFP_KERNEL);
    if (page_descriptor)
        pr_info("%s: page_address() -> %pK\n", LOGTAG, page_address(page_descriptor));

    return 0;
}

static void __exit pagealloc_demo_exit(void)
{
    if (single_page)
        free_page((unsigned long)single_page);
    if (multi_page_block)
        free_pages((unsigned long)multi_page_block, 2);
    if (page_descriptor)
        __free_page(page_descriptor);
    pr_info("%s: module unloaded, all pages freed\n", LOGTAG);
}

module_init(pagealloc_demo_init);
module_exit(pagealloc_demo_exit);
MODULE_LICENSE("GPL");

Important: always free what you allocate, and always free it in the reverse order of allocation in your cleanup path. Forgetting this is one of the most common sources of kernel memory leaks in custom drivers.

Understanding GFP Flags in This Free Linux Kernel Course

Every page allocator call takes a GFP (Get Free Page) mask that tells the kernel how aggressively, and in what context, it is allowed to search for free memory.

Checking Physical Contiguity with Page Frame Numbers

A multi-page block returned by __get_free_pages() or alloc_pages() is guaranteed to be physically contiguous, not just virtually contiguous. You can prove this yourself by converting each page’s kernel virtual address to a physical address with virt_to_phys(), then dividing by the page size to get the Page Frame Number (PFN). Consecutive pages in a contiguous block will have consecutive PFNs.

unsigned long pfn;
phys_addr_t phys;

phys = virt_to_phys((void *)kernel_vaddr);
pfn  = PHYS_PFN(phys);
pr_info("vaddr=%pK phys=%pa pfn=%lu\n", (void *)kernel_vaddr, &phys, pfn);

Caution: virt_to_phys() only works correctly for direct-mapped (“lowmem”) kernel memory — the kind returned by the page allocator. It does not work for vmalloc() memory, I/O remapped memory, or highmem on 32-bit systems. Treating it as a general-purpose conversion is a common beginner mistake.

Page Allocator Changes in Modern Kernels (6.x and Later)

Since this free Linux kernel development course aims to stay current, it is worth knowing how the page allocator has evolved beyond older textbooks:

• Folios: Newer kernels increasingly use the folio abstraction (a wrapper around one or more physically contiguous pages) for page-cache and file-backed memory, reducing bugs related to compound pages. Driver writers allocating raw memory still mostly use the classic APIs shown above.
• GFP flag cleanups: Several legacy flags from older kernels have been removed or merged over time as the reclaim logic was simplified; always check your kernel’s <linux/gfp.h> rather than relying on old code samples.
• Stronger debug tooling: Tools like KASAN, KFENCE, and page_owner tracking make it much easier to catch use-after-free and leak bugs in allocator-based code than in older kernel versions.
• Address hashing by default: The %pK specifier hashes pointers shown in logs unless you have elevated privileges, a security hardening step worth remembering when debugging.

Real-World Use Cases

Common Mistakes and Troubleshooting

Best Practices

Security Considerations

Avoid printing raw kernel virtual or physical addresses with unrestricted format specifiers in production builds; use %pK so addresses are hashed for unprivileged users. Also avoid leaving allocated kernel pages un-zeroed if they will ever be exposed to user space or hardware, since stale data could leak previous kernel memory contents.

Performance Considerations

Requesting very large contiguous blocks (high order values) is more expensive and more likely to fail as system uptime increases and memory fragments. Where possible, prefer multiple smaller allocations or, for very large buffers, look into vmalloc() (virtually contiguous, physically scattered) as an alternative when physical contiguity is not required.

Summary / Key Takeaways

Conclusion

Understanding the page allocator is a foundational step in any serious free Linux kernel development course or free Linux device drivers course journey. Once you are comfortable with these APIs, the behaviour of higher-level allocators like kmalloc() and vmalloc() will make a lot more sense, since they all ultimately rest on the same buddy-system foundation. Keep practicing with small, original kernel modules of your own, and move on to the next lecture in this free embedded systems course series when you’re ready.

Frequently Asked Questions (FAQ)