Re: [PATCH] mm,doc: Add new documentation structure

[John Hubbard <jhubbard@nvidia.com>]

On 5/2/22 11:30 PM, Matthew Wilcox (Oracle) wrote:
> 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>`.

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.


thanks,

-- 
John Hubbard
NVIDIA

> +
> +.. 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
> +======================================