folio_split_unmapped(9)

📦 version 7.3.1, in nixpkgs unstable

✨ folio_split_unmapped 💅

okay so bestie, welcome to the folio_split_unmapped(9) page from the Kernel API Manual — yes, that one, the one that lives in the kernel docs and that you're gonna read at 2am. let's get into it 🫶

🌸 NAME 🌸

folio_split_unmapped — split a large anon folio that is already unmapped. that's it. that's the vibe. no cap ✨

🎀 SYNOPSIS 🎀

int folio_split_unmapped (struct folio *folio , unsigned int new_order
);

literally the whole signature right there, look at her go 💖

🦋 ARGUMENTS 🦋

  • folio — the folio to split. this is the main character of the function, obviously 👑
  • new_order — the order of folios after split. i.e. what size we're coming out the other side with ✨

🌈 DESCRIPTION 🌈

okay so, real talk. this function is a helper for splitting folios that have already been unmapped. the use case? listen — the device or the CPU can straight up refuse to migrate THP pages in the middle of migration, and it's because of allocation issues on either side 😭 fr fr, not their fault.

ngl, there are rules about locking and you should absolutely respect them:

  • anon_vma_lock is not required to be held 🙈
  • mmap_read_lock or mmap_write_lock should be held
  • folio is expected to be locked by the caller
  • device-private and non device-private folios are supported, along with folios that are in the swapcache 💜
  • folio should also be unmapped and isolated from LRU (if applicable)
lowkey important: this function doesn't do the whole glow-up for you. read the next bit carefully 👇

Upon return, bestie:

  • the folio is not remapped
  • split folios are not added to LRU
  • free_folio_and_swap_cache is not called
  • and the new folios remain locked 💅

so yeah, it splits, but it leaves the rest of the chores to you. iconic behaviour honestly 🎀

💀 RETURN 💀

  • 0 on success — slay 💖
  • -EAGAIN if the folio cannot be split (e.g., due to insufficient reference count or extra pins) — not slay, but like, it happens 😭

🧚 SEE ALSO 🧚

Kernel file ./mm/huge_memory.c and friends, iykyk:

k that's the page bestie 🌸 this one's from the ./mm source tree, dated October 2026, and it's about as unfiltered as folio_split_unmapped(9) gets. go forth and split responsibly, mwah 💋

📦 where this page comes from