__split_unmapped_folio(9)

📦 version 7.3.1, in nixpkgs unstable

🎀 NAME 🎀

okay so bestie, welcome to the __split_unmapped_folio(9) page from the Kernel API Manual — this one is all about splitting an unmapped @folio into lower order folios. there are two ways to do it: uniform split or non-uniform split. slay, let’s get into it 💅

✨ SYNOPSIS ✨

int __split_unmapped_folio (struct folio *folio , int new_order , struct page *split_at , struct xa_state *xas , struct address_space *mapping , enum split_type split_type );

💅 ARGUMENTS 💅

  • folio — the to-be-split folio. literally the main character about to get split into lower-order pieces.
  • new_order — the smallest order of the after split folios. this is because buddy allocator like split generates folios with orders from folio's order - 1 to new_order.
  • split_at — in buddy allocator like split, the folio containing split_at will be split until its order becomes new_order.
  • xas — an xa_state pointing to folio->mapping->i_pages, and it is locked by the caller. no cap, caller holds the lock.
  • mapping — folio->mapping. that’s it, that’s the argument.
  • split_type — tells you if the split is uniform or not (buddy allocator like split). it’s the vibe check for which split path we’re on.

🦋 DESCRIPTION 🦋

okay, so there are two modes, and they are giving very different energy:

  1. uniform split — the given folio gets split into multiple new_order small folios, where all the small folios have the same order. this is done when split_type is SPLIT_TYPE_UNIFORM. clean, even, iconic.
  2. buddy allocator like (non-uniform) split — the given folio is split into half, and one of the halves (the one containing the given page) is split into half until the given folio’s order becomes new_order. this is done when split_type is SPLIT_TYPE_NON_UNIFORM. it’s giving repeated half-splits, iykyk.

🌈 the high level flow for these two methods 🌈

  1. uniform split — xas is split with no expectation of failure, and a single __split_folio_to_order is called to split the folio into new_order along with stats update. one call, no drama, no failure arc.
  2. non-uniform split — folio_order - new_order calls to __split_folio_to_order are expected to be made in a for loop to split the folio to one lower order at a time. the folio containing split_at is split in each iteration. xas is split into half in each iteration and can fail. a failed xas split leaves split folios as is without merging them back. so yeah, failure is possible and the split folios do not get a merge-back redemption arc 😭.

after splitting, the caller’s folio reference will be transferred to the folio containing split_at. the caller needs to unlock and/or free after-split folios if necessary. so do not forget the cleanup steps, bestie — that’s the real main character energy 🫶

🌸 RETURN 🌸

  • 0 — successful.
  • <0 — failed. and if -ENOMEM is returned, the folio might be split but not to new_order, so the caller needs to check. no assuming, fr fr.

💜 SEE ALSO 💜

Kernel file ./mm/huge_memory.c is in the mix, along with:

mwah 💖 this page comes from the ./mm source/version corner, dated October 2026, and it’s the __split_unmapped_folio(9) girlie signing off. periodt 🎀✨

📦 where this page comes from