linux-kernel - [PATCH] Documentation/mm: Describe folios in physical

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20231215120022.2010667-1-fabio.maria.de.francesco@linux.intel.com>
Date: Fri, 15 Dec 2023 13:00:12 +0100
From: "Fabio M. De Francesco" <fabio.maria.de.francesco@...ux.intel.com>
To: Jonathan Corbet <corbet@....net>,
	"Mike Rapoport (IBM)" <rppt@...nel.org>,
	Bagas Sanjaya <bagasdotme@...il.com>,
	Lorenzo Stoakes <lstoakes@...il.com>,
	Lukas Bulwahn <lukas.bulwahn@...il.com>,
	"Fabio M. De Francesco" <fabio.maria.de.francesco@...ux.intel.com>,
	Kim Phillips <kim.phillips@....com>,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org
Cc: Matthew Wilcox <willy@...radead.org>
Subject: [PATCH] Documentation/mm: Describe folios in physical_memory.rst

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@...radead.org>
Signed-off-by: Fabio M. De Francesco <fabio.maria.de.francesco@...ux.intel.com>
---
 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