Re: [PATCH v2] docs/vm: add documentation of memory models

[Randy Dunlap <rdunlap@infradead.org>]

On 4/25/19 2:37 PM, Mike Rapoport wrote:
> Describe what {FLAT,DISCONTIG,SPARSE}MEM are and how they manage to
> maintain pfn <-> struct page correspondence.
> 
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> v2 changes:
> * spelling/grammar fixes
> * added note about deprectation of DISCONTIGMEM

                     deprecation

and a few more comments below...


> * added a paragraph about 'struct vmem_altmap'
> 
>  Documentation/vm/index.rst        |   1 +
>  Documentation/vm/memory-model.rst | 183 ++++++++++++++++++++++++++++++++++++++
>  2 files changed, 184 insertions(+)
>  create mode 100644 Documentation/vm/memory-model.rst
> 
> diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst
> index b58cc3b..e8d943b 100644
> --- a/Documentation/vm/index.rst
> +++ b/Documentation/vm/index.rst
> @@ -37,6 +37,7 @@ descriptions of data structures and algorithms.
>     hwpoison
>     hugetlbfs_reserv
>     ksm
> +   memory-model
>     mmu_notifier
>     numa
>     overcommit-accounting
> diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst
> new file mode 100644
> index 0000000..0b4cf19
> --- /dev/null
> +++ b/Documentation/vm/memory-model.rst
> @@ -0,0 +1,183 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _physical_memory_model:
> +
> +=====================
> +Physical Memory Model
> +=====================
> +
> +Physical memory in a system may be addressed in different ways. The
> +simplest case is when the physical memory starts at address 0 and
> +spans a contiguous range up to the maximal address. It could be,
> +however, that this range contains small holes that are not accessible
> +for the CPU. Then there could be several contiguous ranges at
> +completely distinct addresses. And, don't forget about NUMA, where
> +different memory banks are attached to different CPUs.
> +
> +Linux abstracts this diversity using one of the three memory models:
> +FLATMEM, DISCONTIGMEM and SPARSEMEM. Each architecture defines what
> +memory models it supports, what is the default memory model and

                              what the default memory model is and

> +whether it possible to manually override that default.

   whether it is possible

> +
> +.. note::
> +   At time of this writing, DISCONTIGMEM is considered deprecated,
> +   although it is still in use by several architectures

end with '.'

> +
> +All the memory models track the status of physical page frames using
> +:c:type:`struct page` arranged in one or more arrays.
> +
> +Regardless of the selected memory model, there exists one-to-one
> +mapping between the physical page frame number (PFN) and the
> +corresponding `struct page`.
> +
> +Each memory model defines :c:func:`pfn_to_page` and :c:func:`page_to_pfn`
> +helpers that allow the conversion from PFN to `struct page` and vice
> +versa.

[snip]


thanks.
-- 
~Randy