Folios are an ambiguous term. This is partly deliberate, done with the full understanding that it makes things harder later, but easier now, and we have a harder job to do now.

As the documentation says, a folio is simply a new term for a non-tail page. That is, it represents one or more pages of memory. If it's more than one page, those pages were allocated with __GFP_COMP (i.e. are compound pages).

Folios give us a lot of type safety. Referring to page->mapping or page->index is _dangerous_. If you do that to a tail page, you'll get garbage. Maybe you'll be lucky and see TAIL_MAPPING (not true for all tail pages), but there's no equivalent poison for page->index. Similarly for page->lru, although if you do use it, you'll corrupt the compound page quickly enough that you'll probably notice. You'll probably get away with using page->private for tail pages on 64-bit, but have problems on 32-bit. etc.

But a lot of people want more type safety than that. They don't want to be able to pass a slab page to set_page_dirty() (this would be a bad thing). They don't want to be able to lock_page() a page table (_probably_ wouldn't hurt, but it's meaningless; you almost certainly meant to take the pte lock instead). There's substantial disagreement about whether anon and file memory should be of different types. I think that's a topic on which reasonable people can disagree, and we're going to have to keep disagreeing until we resolve it.

"More type safety" is how we come to the second meaning of folio, and that's not written down in the fine documentation. Folios are _only_ for anon & file memory allocations. We've already split out struct slab and struct ptdesc. More types are to come (see MatthewWilcox/Memdescs for current thoughts). This confuses people, including me. It's nonsense to write folio_test_slab(), and yet we do because folios also have the "I am not a tail page" property and so we eliminate the "this might be a tail page, I have to look up the head page first" step. Eventually with memdescs, we'll go back to calling page_test_slab() or something.