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 <[email protected]>
Signed-off-by: Fabio M. De Francesco <[email protected]>
---
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
On Fri, Dec 15, 2023 at 01:00:12PM +0100, Fabio M. De Francesco wrote:
> +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.
This text is verbatim from include/linux/mm_types.h. It seems sad
to have kernel-doc and then replicate it in an rst file.
> +As Matthew Wilcox explains in his introduction to folios, the need for
oof, no, don't mention my name.
> +`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.
This was exactly the kind of documentation I was hoping you wouldn't
write ;-( It's documentation that makes sense today, but won't in five
years time.
We want to say something like,
A folio represents a single memory allocation. It may be composed of
several pages ...
On Friday, 15 December 2023 15:36:21 CET Matthew Wilcox wrote:
> On Fri, Dec 15, 2023 at 01:00:12PM +0100, Fabio M. De Francesco wrote:
> > +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.
>
> This text is verbatim from include/linux/mm_types.h. It seems sad
> to have kernel-doc and then replicate it in an rst file.
Actually, I took this text from the private email you sent me. I thought you
were asking to use exactly this words. And so I acted accordingly to what it
seemed to me you had suggested.
Furthermore I had forgotten that these words are in kernel-doc exactly because
I copy-pasted from your email.
OK. I can explain what a folio is by using different words and elaborating a
bit.
> > +As Matthew Wilcox explains in his introduction to folios, the need for
>
> oof, no, don't mention my name.
>
> > +`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.
>
> This was exactly the kind of documentation I was hoping you wouldn't
> write ;-( It's documentation that makes sense today, but won't in five
> years time.
I wanted to explain why you introduced folios. If you think that the
historical perspective is not what future developers will need in the next 5
years, I can think of something else.
> We want to say something like,
>
> A folio represents a single memory allocation. It may be composed of
> several pages ...
Ah, OK. I think I got it.
Thanks for your comments.
Fabio