Understanding Linux Kernel Folio: From Page to Folio and Its Design Rationale

Phil Karlton famously said, “There are only two hard things in Computer Science: cache invalidation and naming things.” The article begins with this quote to illustrate how naming in kernel code should be self‑explanatory.

In the Linux kernel, memory is traditionally described in units of struct page , each representing a 4 KB base page. However, modern kernels also need to handle larger, contiguous memory objects such as Transparent Huge Pages (THP) and HugeTLB pages, which are composed of multiple base pages. These are called compound pages .

Before the introduction of folio , the kernel used several ad‑hoc mechanisms to manage compound pages:

Mark the head page with the PG_head flag: page->flags |= (1UL << PG_head);

Set the last bit of compound_head on tail pages: page->compound_head |= 1UL;

Store the order of the compound page in compound_order of the second page.

Store a destructor function pointer in compound_dtor of the second page.

These tricks allowed the kernel to answer questions such as:

Do N pages form a compound object?

Which page is the head (page[0])?

Which pages are tails (page[1]…page[N‑1])?

How many pages are in the object?

If I am a tail, who is my head?

How should the whole object be released?

Because the same APIs (e.g., get_page() , lock_page() ) were used for both single pages and compound pages, developers often struggled to know whether they were operating on an individual page or an entire collection.

The kernel introduced struct folio to give a clear, collection‑oriented abstraction. A folio represents a power‑of‑two sized, physically and virtually contiguous set of bytes, at least as large as %PAGE_SIZE . It is essentially a renamed struct page with the same layout, but its semantics convey “this is a whole collection”.

Key API changes include:

void folio_get(struct folio *folio);

void folio_lock(struct folio *folio);

void folio_wait_bit(struct folio *folio, int bit_nr);

void folio_wait_writeback(struct folio *folio);

struct page *folio_page(struct folio *folio, unsigned int n);

These functions force callers to be explicit about whether they are dealing with a whole folio or a single page, eliminating the ambiguous “xxx/yyy” situation described in the article.

Because the underlying data layout is unchanged, existing code can still cast between struct page * and struct folio * , but such casts are considered a “bad smell”. The preferred approach is to use the folio‑specific APIs, which handle reference counting, LRU management, memory cgroup accounting, write‑back, and reverse‑mapping uniformly for both normal pages and THP/huge pages.

The article also lists several kernel subsystems where folios are now the primary unit of work: LRU vectors, refcount/lock handling, memory‑cgroup charging, write‑back bits, page‑cache insertion/removal, and rmap operations. By treating these as collections, the kernel code becomes clearer and less error‑prone.

In summary, the folio abstraction resolves the naming and semantic confusion around compound pages, provides a unified interface for collection‑level operations, and aligns with the kernel’s goal of “don’t make me think”.