Re: [PATCH v4 01/15] docs/mm: add document for swap table

[Chris Li]

Hi Andrew,

Can you please apply this incremental fix up commit on the document
patch of the swap table series?
Just folding it into the original patch is fine.

Here is the change log:
- Move the swap table document to the mm main section. [SeongJae Park]
- Rewrite the swap table size sentence for easier to understand. [ Barry]

Thanks

Chris

On Thu, Sep 18, 2025 at 2:35 PM Barry Song <21cnbao@xxxxxxxxx> wrote:
>
> > > I’m not entirely sure what you mean by “page table page.”
> >
> > The page that gets pointed by the page table, or the page that holds the PTE.
> >
> > > My understanding is that you’re saying:
> > > The swap table contains an array of pointers, each the same size as a PTE,
> > > so its total size typically matches a PTE page table—one page on modern
> > > 64-bit systems.
> >
> > That sounds good. Thanks for the suggestion.
> > I take your suggestion with some small modifications, mostly to
> > clarify the total size is the total size of one cluster of swap
> > tables. The total size of all swap tables in a swap file is much
> > bigger.
> >
> > How about this:
> >
> > A swap table is an array of pointers. Each pointer is the same size as a PTE.
> > The size of a swap table for one swap cluster typically matches a PTE
> > page table,
> > which is one page on modern 64-bit systems.
>
> Acked.
>
> >
> > Chris
>
> Thanks
> Barry
From b03a9b53dfcb1558feb01188f657340bc3414a22 Mon Sep 17 00:00:00 2001
From: Chris Li <chrisl@xxxxxxxxxx>
Date: Fri, 19 Sep 2025 18:12:04 -0700
Subject: [PATCH] SQUASH: docs: fix up for the swap table document

Make swap table into the main section.

Adjust wording on the swap table size vs PTE page table size.

Signed-off-by: Chris Li <chrisl@xxxxxxxxxx>
---
 Documentation/mm/index.rst      | 2 +-
 Documentation/mm/swap-table.rst | 9 +++------
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
index 828ad9b019b3..ba6a8872849b 100644
--- a/Documentation/mm/index.rst
+++ b/Documentation/mm/index.rst
@@ -20,6 +20,7 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
    highmem
    page_reclaim
    swap
+   swap-table
    page_cache
    shmfs
    oom
@@ -57,7 +58,6 @@ documentation, or deleted if it has served its purpose.
    page_table_check
    remap_file_pages
    split_page_table_lock
-   swap-table
    transhuge
    unevictable-lru
    vmalloced-kernel-stacks
diff --git a/Documentation/mm/swap-table.rst b/Documentation/mm/swap-table.rst
index acae6ceb4f7b..da10bb7a0dc3 100644
--- a/Documentation/mm/swap-table.rst
+++ b/Documentation/mm/swap-table.rst
@@ -50,12 +50,9 @@ Swap cache lookup within the cluster can be a very simple array lookup.
 
 We give such a per-cluster swap cache value array a name: the swap table.
 
-Each swap cluster contains 512 entries, so a swap table stores one cluster
-worth of swap cache values, which is exactly one page. This is not
-coincidental because the cluster size is determined by the huge page size.
-The swap table is holding an array of pointers. The pointer has the same
-size as the PTE. The size of the swap table should match to the second
-last level of the page table page, exactly one page.
+A swap table is an array of pointers. Each pointer is the same size as a
+PTE. The size of a swap table for one swap cluster typically matches a PTE
+page table, which is one page on modern 64-bit systems.
 
 With swap table, swap cache lookup can achieve great locality, simpler,
 and faster.
-- 
2.51.0.470.ga7dc726c21-goog