[PATCH] mm,doc: Add new documentation structure

Closely following the outline of Mel Gorman's book "Understanding the
Linux Virtual Memory Manager", add a new outline.  Preserve the current
contents of the mm underneath the new outline so we can transition those
documents to a more sensible place later.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
  Documentation/vm/bootmem.rst         |  5 +++++
  Documentation/vm/index.rst           | 27 +++++++++++++++++++++++----
  Documentation/vm/oom.rst             |  5 +++++
  Documentation/vm/page_allocation.rst |  5 +++++
  Documentation/vm/page_cache.rst      |  5 +++++
  Documentation/vm/page_reclaim.rst    |  5 +++++
  Documentation/vm/page_tables.rst     |  5 +++++
  Documentation/vm/physical_memory.rst |  5 +++++
  Documentation/vm/process_addrs.rst   |  5 +++++
  Documentation/vm/shmfs.rst           |  5 +++++
  Documentation/vm/slab.rst            |  5 +++++
  Documentation/vm/swap.rst            |  5 +++++
  Documentation/vm/vmalloc.rst         |  5 +++++
  13 files changed, 83 insertions(+), 4 deletions(-)
  create mode 100644 Documentation/vm/bootmem.rst
  create mode 100644 Documentation/vm/oom.rst
  create mode 100644 Documentation/vm/page_allocation.rst
  create mode 100644 Documentation/vm/page_cache.rst
  create mode 100644 Documentation/vm/page_reclaim.rst
  create mode 100644 Documentation/vm/page_tables.rst
  create mode 100644 Documentation/vm/physical_memory.rst
  create mode 100644 Documentation/vm/process_addrs.rst
  create mode 100644 Documentation/vm/shmfs.rst
  create mode 100644 Documentation/vm/slab.rst
  create mode 100644 Documentation/vm/swap.rst
  create mode 100644 Documentation/vm/vmalloc.rst

diff --git a/Documentation/vm/bootmem.rst b/Documentation/vm/bootmem.rst
new file mode 100644
index 000000000000..eb2b31eedfa1
--- /dev/null
+++ b/Documentation/vm/bootmem.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Boot Memory
+===========

diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst
index 44365c4574a3..bc495a846871 100644
--- a/Documentation/vm/index.rst
+++ b/Documentation/vm/index.rst

@@ -2,12 +2,32 @@
  Linux Memory Management Documentation
  =====================================
  
+This is a guide to understanding the memory management subsystem
+of Linux.  If you are looking for advice on simply allocating memory,
+see the :ref:`memory_allocation`.  For controlling and tuning guides,
+see the :doc:`admin guide <../admin-guide/mm/index>`.

+
+.. toctree::
+   :maxdepth: 1
+
+   physical_memory
+   page_tables
+   process_addrs
+   bootmem
+   page_allocation
+   vmalloc
+   slab
+   highmem
+   page_reclaim
+   swap
+   page_cache
+   shmfs
+   oom
+
  This is a collection of documents about the Linux memory management (mm)
  subsystem internals with different level of details ranging from notes and
  mailing list responses for elaborating descriptions of data structures and
-algorithms.  If you are looking for advice on simply allocating memory, see the
-:ref:`memory_allocation`.  For controlling and tuning guides, see the
-:doc:`admin guide <../admin-guide/mm/index>`.
+algorithms.
  
  .. toctree::
     :maxdepth: 1

@@ -18,7 +38,6 @@ algorithms.  If you are looking for advice on simply allocating memory, see the
     damon/index
     free_page_reporting
     frontswap
-   highmem
     hmm
     hwpoison
     hugetlbfs_reserv

diff --git a/Documentation/vm/oom.rst b/Documentation/vm/oom.rst
new file mode 100644
index 000000000000..18e9e40c1ec1
--- /dev/null
+++ b/Documentation/vm/oom.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+Out Of Memory Handling
+======================

diff --git a/Documentation/vm/page_allocation.rst b/Documentation/vm/page_allocation.rst
new file mode 100644
index 000000000000..d9b4495561f1
--- /dev/null
+++ b/Documentation/vm/page_allocation.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Page Allocation
+===============

diff --git a/Documentation/vm/page_cache.rst b/Documentation/vm/page_cache.rst
new file mode 100644
index 000000000000..75eba7c431b2
--- /dev/null
+++ b/Documentation/vm/page_cache.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========
+Page Cache
+==========

diff --git a/Documentation/vm/page_reclaim.rst b/Documentation/vm/page_reclaim.rst
new file mode 100644
index 000000000000..50a30b7f8ac3
--- /dev/null
+++ b/Documentation/vm/page_reclaim.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Page Reclaim
+============

diff --git a/Documentation/vm/page_tables.rst b/Documentation/vm/page_tables.rst
new file mode 100644
index 000000000000..96939571d7bc
--- /dev/null
+++ b/Documentation/vm/page_tables.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Page Tables
+===========

diff --git a/Documentation/vm/physical_memory.rst b/Documentation/vm/physical_memory.rst
new file mode 100644
index 000000000000..2ab7b8c1c863
--- /dev/null
+++ b/Documentation/vm/physical_memory.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Physical Memory
+===============

diff --git a/Documentation/vm/process_addrs.rst b/Documentation/vm/process_addrs.rst
new file mode 100644
index 000000000000..e8618fbc62c9
--- /dev/null
+++ b/Documentation/vm/process_addrs.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+Process Addresses
+=================

diff --git a/Documentation/vm/shmfs.rst b/Documentation/vm/shmfs.rst
new file mode 100644
index 000000000000..8b01ebb4c30e
--- /dev/null
+++ b/Documentation/vm/shmfs.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Shared Memory Filesystem
+========================

diff --git a/Documentation/vm/slab.rst b/Documentation/vm/slab.rst
new file mode 100644
index 000000000000..87d5a5bb172f
--- /dev/null
+++ b/Documentation/vm/slab.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Slab Allocation
+===============

diff --git a/Documentation/vm/swap.rst b/Documentation/vm/swap.rst
new file mode 100644
index 000000000000..78819bd4d745
--- /dev/null
+++ b/Documentation/vm/swap.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+Swap
+====

diff --git a/Documentation/vm/vmalloc.rst b/Documentation/vm/vmalloc.rst
new file mode 100644
index 000000000000..363fe20d6b9f
--- /dev/null
+++ b/Documentation/vm/vmalloc.rst

@@ -0,0 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+Virtually Contiguous Memory Allocation
+======================================

On Wed, May 04, 2022 at 06:12:09AM -0700, John Hubbard wrote:

quoted

This needs to be properly merged with the existing index. Otherwise
the result here is very confusing because there are two summaries
and no explanation of what is going on here.

If I get a moment today, I'll take a quick shot at at merging them,
and post some suggestions here, but just wanted to point that out
before this goes in as-is.

John and I have chatted to understand what he was getting at here,
but haven't had a chance to review this change in-person yet.

+++ b/Documentation/vm/index.rst

@@ -2,6 +2,9 @@
  Linux Memory Management Documentation
  =====================================

+Memory Management Guide
+=======================
+
  This is a guide to understanding the memory management subsystem
  of Linux.  If you are looking for advice on simply allocating memory,
  see the :ref:`memory_allocation`.  For controlling and tuning guides,

@@ -24,10 +27,14 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
     shmfs
     oom
  
-This is a collection of documents about the Linux memory management (mm)
-subsystem internals with different level of details ranging from notes and
-mailing list responses for elaborating descriptions of data structures and
-algorithms.
+Legacy Documentation
+====================
+
+This is a collection of older documents about the Linux memory management
+(mm) subsystem internals with different level of details ranging from
+notes and mailing list responses for elaborating descriptions of data
+structures and algorithms.  It should all be integrated nicely into the
+above structured documentation, or deleted if it has served its purpose.
  
  .. toctree::
     :maxdepth: 1

On Wed, May 04, 2022 at 06:12:09AM -0700, John Hubbard wrote:

quoted

This needs to be properly merged with the existing index. Otherwise
the result here is very confusing because there are two summaries
and no explanation of what is going on here.

If I get a moment today, I'll take a quick shot at at merging them,
and post some suggestions here, but just wanted to point that out
before this goes in as-is.

John and I have chatted to understand what he was getting at here,
but haven't had a chance to review this change in-person yet.

+++ b/Documentation/vm/index.rst

@@ -2,6 +2,9 @@
 Linux Memory Management Documentation
 =====================================

+Memory Management Guide
+=======================
+
 This is a guide to understanding the memory management subsystem
 of Linux.  If you are looking for advice on simply allocating memory,
 see the :ref:`memory_allocation`.  For controlling and tuning guides,

@@ -24,10 +27,14 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
    shmfs
    oom
 
-This is a collection of documents about the Linux memory management (mm)
-subsystem internals with different level of details ranging from notes and
-mailing list responses for elaborating descriptions of data structures and
-algorithms.
+Legacy Documentation
+====================
+
+This is a collection of older documents about the Linux memory management
+(mm) subsystem internals with different level of details ranging from

+notes and mailing list responses for elaborating descriptions of data
+structures and algorithms.  It should all be integrated nicely into the
+above structured documentation, or deleted if it has served its purpose.
 
 .. toctree::
    :maxdepth: 1