PAGE_POOL ALLOCATOR(9)

📦 version 7.3.1, in nixpkgs unstable

💅 page_pool allocator 💅

okay bestie, welcome to section 9 of the Kernel API Manual, aka the page_pool allocator, and honestly? she's iconic. 🌸

✨ the actual tea ✨

The page_pool allocator is optimized for recycling page or page fragment used by skb packet and xdp frame. recycling era fr fr 🔥

Basic use involves replacing any alloc_pages calls with page_pool_alloc, which allocate memory with or without page splitting depending on the requested memory size. that's it, that's the base vibe 💅

Now, if the driver knows that it always requires full pages or its allocations are always smaller than half a page, it can use one of the more specific API calls — and there are exactly two, no more, no cap:

  1. page_pool_alloc_pages — allocate memory without page splitting when driver knows that the memory it need is always bigger than half of the page allocated from page pool. There is no cache line dirtying for 'struct page' when a page is recycled back to the page pool. clean, no mess, we love her ✨
  2. page_pool_alloc_frag — allocate memory with page splitting when driver knows that the memory it need is always smaller than or equal to half of the page allocated from page pool. Page splitting enables memory saving and thus avoids TLB/cache miss for data access, but there also is some cost to implement page splitting, mainly some cache line dirtying/bouncing for
😭 bestie the source sentence literally trails off right there at "dirtying/bouncing for" — i'm not gonna invent the rest, so that's where it ends, periodt.

The API keeps track of in-flight pages, in order to let API users know when it is safe to free a page_pool object. so the API users must call page_pool_put_page or page_pool_free_va to free the page_pool object, or attach the page_pool object to a page_pool-aware object like skbs marked with skb_mark_for_recycle. don't skip this part, it's giving "responsible main character energy" 🫶

page_pool_put_page may be called multiple times on the same page if a page is split into multiple fragments. For the last fragment, it will either recycle the page, or in case of page->_refcount > 1, it will release the DMA mapping and in-flight state accounting. lowkey crucial, highkey underrated 💀

dma_sync_single_range_for_device is only called for the last fragment when page_pool is created with PP_FLAG_DMA_SYNC_DEV flag, so it depends on the last freed fragment to do the sync_for_device operation for all fragments in the same page when a page is split. The API user must setup pool->p.max_len and pool->p.offset correctly and ensure that page_pool_put_page is called with dma_sync_size being -1 for fragment API.

🚨 okay listen: get pool->p.max_len, pool->p.offset and that dma_sync_size of -1 wrong and nobody's having a good time. this is a requirement, not a suggestion, ngl.

🦋 SEE ALSO 🦋

that's the whole page, bestie, we ate and left zero crumbs 👑

ttyl! this came from ./include/net/page_pool and it's dated October 2026 — slay 💅✨

📦 where this page comes from