memory-model.rst 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219
  1. .. SPDX-License-Identifier: GPL-2.0
  2. .. _physical_memory_model:
  3. =====================
  4. Physical Memory Model
  5. =====================
  6. Physical memory in a system may be addressed in different ways. The
  7. simplest case is when the physical memory starts at address 0 and
  8. spans a contiguous range up to the maximal address. It could be,
  9. however, that this range contains small holes that are not accessible
  10. for the CPU. Then there could be several contiguous ranges at
  11. completely distinct addresses. And, don't forget about NUMA, where
  12. different memory banks are attached to different CPUs.
  13. Linux abstracts this diversity using one of the three memory models:
  14. FLATMEM, DISCONTIGMEM and SPARSEMEM. Each architecture defines what
  15. memory models it supports, what the default memory model is and
  16. whether it is possible to manually override that default.
  17. .. note::
  18. At time of this writing, DISCONTIGMEM is considered deprecated,
  19. although it is still in use by several architectures.
  20. All the memory models track the status of physical page frames using
  21. struct page arranged in one or more arrays.
  22. Regardless of the selected memory model, there exists one-to-one
  23. mapping between the physical page frame number (PFN) and the
  24. corresponding `struct page`.
  25. Each memory model defines :c:func:`pfn_to_page` and :c:func:`page_to_pfn`
  26. helpers that allow the conversion from PFN to `struct page` and vice
  27. versa.
  28. FLATMEM
  29. =======
  30. The simplest memory model is FLATMEM. This model is suitable for
  31. non-NUMA systems with contiguous, or mostly contiguous, physical
  32. memory.
  33. In the FLATMEM memory model, there is a global `mem_map` array that
  34. maps the entire physical memory. For most architectures, the holes
  35. have entries in the `mem_map` array. The `struct page` objects
  36. corresponding to the holes are never fully initialized.
  37. To allocate the `mem_map` array, architecture specific setup code should
  38. call :c:func:`free_area_init` function. Yet, the mappings array is not
  39. usable until the call to :c:func:`memblock_free_all` that hands all the
  40. memory to the page allocator.
  41. If an architecture enables `CONFIG_ARCH_HAS_HOLES_MEMORYMODEL` option,
  42. it may free parts of the `mem_map` array that do not cover the
  43. actual physical pages. In such case, the architecture specific
  44. :c:func:`pfn_valid` implementation should take the holes in the
  45. `mem_map` into account.
  46. With FLATMEM, the conversion between a PFN and the `struct page` is
  47. straightforward: `PFN - ARCH_PFN_OFFSET` is an index to the
  48. `mem_map` array.
  49. The `ARCH_PFN_OFFSET` defines the first page frame number for
  50. systems with physical memory starting at address different from 0.
  51. DISCONTIGMEM
  52. ============
  53. The DISCONTIGMEM model treats the physical memory as a collection of
  54. `nodes` similarly to how Linux NUMA support does. For each node Linux
  55. constructs an independent memory management subsystem represented by
  56. `struct pglist_data` (or `pg_data_t` for short). Among other
  57. things, `pg_data_t` holds the `node_mem_map` array that maps
  58. physical pages belonging to that node. The `node_start_pfn` field of
  59. `pg_data_t` is the number of the first page frame belonging to that
  60. node.
  61. The architecture setup code should call :c:func:`free_area_init_node` for
  62. each node in the system to initialize the `pg_data_t` object and its
  63. `node_mem_map`.
  64. Every `node_mem_map` behaves exactly as FLATMEM's `mem_map` -
  65. every physical page frame in a node has a `struct page` entry in the
  66. `node_mem_map` array. When DISCONTIGMEM is enabled, a portion of the
  67. `flags` field of the `struct page` encodes the node number of the
  68. node hosting that page.
  69. The conversion between a PFN and the `struct page` in the
  70. DISCONTIGMEM model became slightly more complex as it has to determine
  71. which node hosts the physical page and which `pg_data_t` object
  72. holds the `struct page`.
  73. Architectures that support DISCONTIGMEM provide :c:func:`pfn_to_nid`
  74. to convert PFN to the node number. The opposite conversion helper
  75. :c:func:`page_to_nid` is generic as it uses the node number encoded in
  76. page->flags.
  77. Once the node number is known, the PFN can be used to index
  78. appropriate `node_mem_map` array to access the `struct page` and
  79. the offset of the `struct page` from the `node_mem_map` plus
  80. `node_start_pfn` is the PFN of that page.
  81. SPARSEMEM
  82. =========
  83. SPARSEMEM is the most versatile memory model available in Linux and it
  84. is the only memory model that supports several advanced features such
  85. as hot-plug and hot-remove of the physical memory, alternative memory
  86. maps for non-volatile memory devices and deferred initialization of
  87. the memory map for larger systems.
  88. The SPARSEMEM model presents the physical memory as a collection of
  89. sections. A section is represented with struct mem_section
  90. that contains `section_mem_map` that is, logically, a pointer to an
  91. array of struct pages. However, it is stored with some other magic
  92. that aids the sections management. The section size and maximal number
  93. of section is specified using `SECTION_SIZE_BITS` and
  94. `MAX_PHYSMEM_BITS` constants defined by each architecture that
  95. supports SPARSEMEM. While `MAX_PHYSMEM_BITS` is an actual width of a
  96. physical address that an architecture supports, the
  97. `SECTION_SIZE_BITS` is an arbitrary value.
  98. The maximal number of sections is denoted `NR_MEM_SECTIONS` and
  99. defined as
  100. .. math::
  101. NR\_MEM\_SECTIONS = 2 ^ {(MAX\_PHYSMEM\_BITS - SECTION\_SIZE\_BITS)}
  102. The `mem_section` objects are arranged in a two-dimensional array
  103. called `mem_sections`. The size and placement of this array depend
  104. on `CONFIG_SPARSEMEM_EXTREME` and the maximal possible number of
  105. sections:
  106. * When `CONFIG_SPARSEMEM_EXTREME` is disabled, the `mem_sections`
  107. array is static and has `NR_MEM_SECTIONS` rows. Each row holds a
  108. single `mem_section` object.
  109. * When `CONFIG_SPARSEMEM_EXTREME` is enabled, the `mem_sections`
  110. array is dynamically allocated. Each row contains PAGE_SIZE worth of
  111. `mem_section` objects and the number of rows is calculated to fit
  112. all the memory sections.
  113. The architecture setup code should call sparse_init() to
  114. initialize the memory sections and the memory maps.
  115. With SPARSEMEM there are two possible ways to convert a PFN to the
  116. corresponding `struct page` - a "classic sparse" and "sparse
  117. vmemmap". The selection is made at build time and it is determined by
  118. the value of `CONFIG_SPARSEMEM_VMEMMAP`.
  119. The classic sparse encodes the section number of a page in page->flags
  120. and uses high bits of a PFN to access the section that maps that page
  121. frame. Inside a section, the PFN is the index to the array of pages.
  122. The sparse vmemmap uses a virtually mapped memory map to optimize
  123. pfn_to_page and page_to_pfn operations. There is a global `struct
  124. page *vmemmap` pointer that points to a virtually contiguous array of
  125. `struct page` objects. A PFN is an index to that array and the
  126. offset of the `struct page` from `vmemmap` is the PFN of that
  127. page.
  128. To use vmemmap, an architecture has to reserve a range of virtual
  129. addresses that will map the physical pages containing the memory
  130. map and make sure that `vmemmap` points to that range. In addition,
  131. the architecture should implement :c:func:`vmemmap_populate` method
  132. that will allocate the physical memory and create page tables for the
  133. virtual memory map. If an architecture does not have any special
  134. requirements for the vmemmap mappings, it can use default
  135. :c:func:`vmemmap_populate_basepages` provided by the generic memory
  136. management.
  137. The virtually mapped memory map allows storing `struct page` objects
  138. for persistent memory devices in pre-allocated storage on those
  139. devices. This storage is represented with struct vmem_altmap
  140. that is eventually passed to vmemmap_populate() through a long chain
  141. of function calls. The vmemmap_populate() implementation may use the
  142. `vmem_altmap` along with :c:func:`vmemmap_alloc_block_buf` helper to
  143. allocate memory map on the persistent memory device.
  144. ZONE_DEVICE
  145. ===========
  146. The `ZONE_DEVICE` facility builds upon `SPARSEMEM_VMEMMAP` to offer
  147. `struct page` `mem_map` services for device driver identified physical
  148. address ranges. The "device" aspect of `ZONE_DEVICE` relates to the fact
  149. that the page objects for these address ranges are never marked online,
  150. and that a reference must be taken against the device, not just the page
  151. to keep the memory pinned for active use. `ZONE_DEVICE`, via
  152. :c:func:`devm_memremap_pages`, performs just enough memory hotplug to
  153. turn on :c:func:`pfn_to_page`, :c:func:`page_to_pfn`, and
  154. :c:func:`get_user_pages` service for the given range of pfns. Since the
  155. page reference count never drops below 1 the page is never tracked as
  156. free memory and the page's `struct list_head lru` space is repurposed
  157. for back referencing to the host device / driver that mapped the memory.
  158. While `SPARSEMEM` presents memory as a collection of sections,
  159. optionally collected into memory blocks, `ZONE_DEVICE` users have a need
  160. for smaller granularity of populating the `mem_map`. Given that
  161. `ZONE_DEVICE` memory is never marked online it is subsequently never
  162. subject to its memory ranges being exposed through the sysfs memory
  163. hotplug api on memory block boundaries. The implementation relies on
  164. this lack of user-api constraint to allow sub-section sized memory
  165. ranges to be specified to :c:func:`arch_add_memory`, the top-half of
  166. memory hotplug. Sub-section support allows for 2MB as the cross-arch
  167. common alignment granularity for :c:func:`devm_memremap_pages`.
  168. The users of `ZONE_DEVICE` are:
  169. * pmem: Map platform persistent memory to be used as a direct-I/O target
  170. via DAX mappings.
  171. * hmm: Extend `ZONE_DEVICE` with `->page_fault()` and `->page_free()`
  172. event callbacks to allow a device-driver to coordinate memory management
  173. events related to device-memory, typically GPU memory. See
  174. Documentation/vm/hmm.rst.
  175. * p2pdma: Create `struct page` objects to allow peer devices in a
  176. PCI/-E topology to coordinate direct-DMA operations between themselves,
  177. i.e. bypass host memory.