Documentation/mm/physical_memory.rst contains stubs and one of them is an empty subsection about folios. Fill that stub with information that describe what a folio is and why it was introduced. This patch contains text written by Matthew Wilcox. The text comes from his commit messages and from other sources. I just adaptet and included it for the purposes of this patch. The patch contains also some lines written by Jonathan Corbet in lwn.net. Thanks to both of them. Suggested-by: Matthew Wilcox <willy@xxxxxxxxxxxxx> Signed-off-by: Fabio M. De Francesco <fabio.maria.de.francesco@xxxxxxxxxxxxxxx> --- Documentation/mm/physical_memory.rst | 31 +++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 531e73b003dd..5928a1795aab 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -357,9 +357,34 @@ Pages Folios ====== -.. admonition:: Stub - - This section is incomplete. Please list and describe the appropriate fields. +A folio is a physically, virtually and logically contiguous set of bytes. +It is a power-of-two in size, and it is aligned to that same power-of-two. +It is at least as large as %PAGE_SIZE. If it is in the page cache, it is +at a file offset which is a multiple of that power-of-two. It may be +mapped into userspace at an address which is at an arbitrary page offset, +but its kernel virtual address is aligned to its size. + +As Matthew Wilcox explains in his introduction to folios, the need for +`struct folio` arises mostly to address issues with the use of compound +pages. It is often unclear whether a function operates on an individual +page, or an entire compound page. + +"A function which has a `struct page` pointer argument might be +expecting a head or base page and will BUG if given a tail page. It might +work with any kind of page and operate on %PAGE_SIZE bytes. It might work +with any kind of page and operate on page_size() bytes if given a head +page but %PAGE_SIZE bytes if given a base or tail page. It might operate +on page_size() bytes if passed a head or tail page. We have examples of +all of these today.". + +A pointer to folio points to a page that is never a tail page. It +represents an entire compound page. Therefore, there is no need to call +compound_head() to get a pointer to the head. Folios has eliminted the +need to unnecessary calls and has avoided bugs related to the misuse of +pages passed to functions. Furthermore, the inline compound_head() makes +the kernel bigger and slows things down. + +The folio APIs are described in the "Memory Management APIs" document. .. _initialization: -- 2.43.0
