hmm.rst 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435
  1. .. _hmm:
  2. =====================================
  3. Heterogeneous Memory Management (HMM)
  4. =====================================
  5. Provide infrastructure and helpers to integrate non-conventional memory (device
  6. memory like GPU on board memory) into regular kernel path, with the cornerstone
  7. of this being specialized struct page for such memory (see sections 5 to 7 of
  8. this document).
  9. HMM also provides optional helpers for SVM (Share Virtual Memory), i.e.,
  10. allowing a device to transparently access program addresses coherently with
  11. the CPU meaning that any valid pointer on the CPU is also a valid pointer
  12. for the device. This is becoming mandatory to simplify the use of advanced
  13. heterogeneous computing where GPU, DSP, or FPGA are used to perform various
  14. computations on behalf of a process.
  15. This document is divided as follows: in the first section I expose the problems
  16. related to using device specific memory allocators. In the second section, I
  17. expose the hardware limitations that are inherent to many platforms. The third
  18. section gives an overview of the HMM design. The fourth section explains how
  19. CPU page-table mirroring works and the purpose of HMM in this context. The
  20. fifth section deals with how device memory is represented inside the kernel.
  21. Finally, the last section presents a new migration helper that allows
  22. leveraging the device DMA engine.
  23. .. contents:: :local:
  24. Problems of using a device specific memory allocator
  25. ====================================================
  26. Devices with a large amount of on board memory (several gigabytes) like GPUs
  27. have historically managed their memory through dedicated driver specific APIs.
  28. This creates a disconnect between memory allocated and managed by a device
  29. driver and regular application memory (private anonymous, shared memory, or
  30. regular file backed memory). From here on I will refer to this aspect as split
  31. address space. I use shared address space to refer to the opposite situation:
  32. i.e., one in which any application memory region can be used by a device
  33. transparently.
  34. Split address space happens because devices can only access memory allocated
  35. through a device specific API. This implies that all memory objects in a program
  36. are not equal from the device point of view which complicates large programs
  37. that rely on a wide set of libraries.
  38. Concretely, this means that code that wants to leverage devices like GPUs needs
  39. to copy objects between generically allocated memory (malloc, mmap private, mmap
  40. share) and memory allocated through the device driver API (this still ends up
  41. with an mmap but of the device file).
  42. For flat data sets (array, grid, image, ...) this isn't too hard to achieve but
  43. for complex data sets (list, tree, ...) it's hard to get right. Duplicating a
  44. complex data set needs to re-map all the pointer relations between each of its
  45. elements. This is error prone and programs get harder to debug because of the
  46. duplicate data set and addresses.
  47. Split address space also means that libraries cannot transparently use data
  48. they are getting from the core program or another library and thus each library
  49. might have to duplicate its input data set using the device specific memory
  50. allocator. Large projects suffer from this and waste resources because of the
  51. various memory copies.
  52. Duplicating each library API to accept as input or output memory allocated by
  53. each device specific allocator is not a viable option. It would lead to a
  54. combinatorial explosion in the library entry points.
  55. Finally, with the advance of high level language constructs (in C++ but in
  56. other languages too) it is now possible for the compiler to leverage GPUs and
  57. other devices without programmer knowledge. Some compiler identified patterns
  58. are only do-able with a shared address space. It is also more reasonable to use
  59. a shared address space for all other patterns.
  60. I/O bus, device memory characteristics
  61. ======================================
  62. I/O buses cripple shared address spaces due to a few limitations. Most I/O
  63. buses only allow basic memory access from device to main memory; even cache
  64. coherency is often optional. Access to device memory from a CPU is even more
  65. limited. More often than not, it is not cache coherent.
  66. If we only consider the PCIE bus, then a device can access main memory (often
  67. through an IOMMU) and be cache coherent with the CPUs. However, it only allows
  68. a limited set of atomic operations from the device on main memory. This is worse
  69. in the other direction: the CPU can only access a limited range of the device
  70. memory and cannot perform atomic operations on it. Thus device memory cannot
  71. be considered the same as regular memory from the kernel point of view.
  72. Another crippling factor is the limited bandwidth (~32GBytes/s with PCIE 4.0
  73. and 16 lanes). This is 33 times less than the fastest GPU memory (1 TBytes/s).
  74. The final limitation is latency. Access to main memory from the device has an
  75. order of magnitude higher latency than when the device accesses its own memory.
  76. Some platforms are developing new I/O buses or additions/modifications to PCIE
  77. to address some of these limitations (OpenCAPI, CCIX). They mainly allow
  78. two-way cache coherency between CPU and device and allow all atomic operations the
  79. architecture supports. Sadly, not all platforms are following this trend and
  80. some major architectures are left without hardware solutions to these problems.
  81. So for shared address space to make sense, not only must we allow devices to
  82. access any memory but we must also permit any memory to be migrated to device
  83. memory while the device is using it (blocking CPU access while it happens).
  84. Shared address space and migration
  85. ==================================
  86. HMM intends to provide two main features. The first one is to share the address
  87. space by duplicating the CPU page table in the device page table so the same
  88. address points to the same physical memory for any valid main memory address in
  89. the process address space.
  90. To achieve this, HMM offers a set of helpers to populate the device page table
  91. while keeping track of CPU page table updates. Device page table updates are
  92. not as easy as CPU page table updates. To update the device page table, you must
  93. allocate a buffer (or use a pool of pre-allocated buffers) and write GPU
  94. specific commands in it to perform the update (unmap, cache invalidations, and
  95. flush, ...). This cannot be done through common code for all devices. Hence
  96. why HMM provides helpers to factor out everything that can be while leaving the
  97. hardware specific details to the device driver.
  98. The second mechanism HMM provides is a new kind of ZONE_DEVICE memory that
  99. allows allocating a struct page for each page of device memory. Those pages
  100. are special because the CPU cannot map them. However, they allow migrating
  101. main memory to device memory using existing migration mechanisms and everything
  102. looks like a page that is swapped out to disk from the CPU point of view. Using a
  103. struct page gives the easiest and cleanest integration with existing mm
  104. mechanisms. Here again, HMM only provides helpers, first to hotplug new ZONE_DEVICE
  105. memory for the device memory and second to perform migration. Policy decisions
  106. of what and when to migrate is left to the device driver.
  107. Note that any CPU access to a device page triggers a page fault and a migration
  108. back to main memory. For example, when a page backing a given CPU address A is
  109. migrated from a main memory page to a device page, then any CPU access to
  110. address A triggers a page fault and initiates a migration back to main memory.
  111. With these two features, HMM not only allows a device to mirror process address
  112. space and keeps both CPU and device page tables synchronized, but also
  113. leverages device memory by migrating the part of the data set that is actively being
  114. used by the device.
  115. Address space mirroring implementation and API
  116. ==============================================
  117. Address space mirroring's main objective is to allow duplication of a range of
  118. CPU page table into a device page table; HMM helps keep both synchronized. A
  119. device driver that wants to mirror a process address space must start with the
  120. registration of a mmu_interval_notifier::
  121. int mmu_interval_notifier_insert(struct mmu_interval_notifier *interval_sub,
  122. struct mm_struct *mm, unsigned long start,
  123. unsigned long length,
  124. const struct mmu_interval_notifier_ops *ops);
  125. During the ops->invalidate() callback the device driver must perform the
  126. update action to the range (mark range read only, or fully unmap, etc.). The
  127. device must complete the update before the driver callback returns.
  128. When the device driver wants to populate a range of virtual addresses, it can
  129. use::
  130. int hmm_range_fault(struct hmm_range *range);
  131. It will trigger a page fault on missing or read-only entries if write access is
  132. requested (see below). Page faults use the generic mm page fault code path just
  133. like a CPU page fault.
  134. Both functions copy CPU page table entries into their pfns array argument. Each
  135. entry in that array corresponds to an address in the virtual range. HMM
  136. provides a set of flags to help the driver identify special CPU page table
  137. entries.
  138. Locking within the sync_cpu_device_pagetables() callback is the most important
  139. aspect the driver must respect in order to keep things properly synchronized.
  140. The usage pattern is::
  141. int driver_populate_range(...)
  142. {
  143. struct hmm_range range;
  144. ...
  145. range.notifier = &interval_sub;
  146. range.start = ...;
  147. range.end = ...;
  148. range.hmm_pfns = ...;
  149. if (!mmget_not_zero(interval_sub->notifier.mm))
  150. return -EFAULT;
  151. again:
  152. range.notifier_seq = mmu_interval_read_begin(&interval_sub);
  153. mmap_read_lock(mm);
  154. ret = hmm_range_fault(&range);
  155. if (ret) {
  156. mmap_read_unlock(mm);
  157. if (ret == -EBUSY)
  158. goto again;
  159. return ret;
  160. }
  161. mmap_read_unlock(mm);
  162. take_lock(driver->update);
  163. if (mmu_interval_read_retry(&ni, range.notifier_seq) {
  164. release_lock(driver->update);
  165. goto again;
  166. }
  167. /* Use pfns array content to update device page table,
  168. * under the update lock */
  169. release_lock(driver->update);
  170. return 0;
  171. }
  172. The driver->update lock is the same lock that the driver takes inside its
  173. invalidate() callback. That lock must be held before calling
  174. mmu_interval_read_retry() to avoid any race with a concurrent CPU page table
  175. update.
  176. Leverage default_flags and pfn_flags_mask
  177. =========================================
  178. The hmm_range struct has 2 fields, default_flags and pfn_flags_mask, that specify
  179. fault or snapshot policy for the whole range instead of having to set them
  180. for each entry in the pfns array.
  181. For instance if the device driver wants pages for a range with at least read
  182. permission, it sets::
  183. range->default_flags = HMM_PFN_REQ_FAULT;
  184. range->pfn_flags_mask = 0;
  185. and calls hmm_range_fault() as described above. This will fill fault all pages
  186. in the range with at least read permission.
  187. Now let's say the driver wants to do the same except for one page in the range for
  188. which it wants to have write permission. Now driver set::
  189. range->default_flags = HMM_PFN_REQ_FAULT;
  190. range->pfn_flags_mask = HMM_PFN_REQ_WRITE;
  191. range->pfns[index_of_write] = HMM_PFN_REQ_WRITE;
  192. With this, HMM will fault in all pages with at least read (i.e., valid) and for the
  193. address == range->start + (index_of_write << PAGE_SHIFT) it will fault with
  194. write permission i.e., if the CPU pte does not have write permission set then HMM
  195. will call handle_mm_fault().
  196. After hmm_range_fault completes the flag bits are set to the current state of
  197. the page tables, ie HMM_PFN_VALID | HMM_PFN_WRITE will be set if the page is
  198. writable.
  199. Represent and manage device memory from core kernel point of view
  200. =================================================================
  201. Several different designs were tried to support device memory. The first one
  202. used a device specific data structure to keep information about migrated memory
  203. and HMM hooked itself in various places of mm code to handle any access to
  204. addresses that were backed by device memory. It turns out that this ended up
  205. replicating most of the fields of struct page and also needed many kernel code
  206. paths to be updated to understand this new kind of memory.
  207. Most kernel code paths never try to access the memory behind a page
  208. but only care about struct page contents. Because of this, HMM switched to
  209. directly using struct page for device memory which left most kernel code paths
  210. unaware of the difference. We only need to make sure that no one ever tries to
  211. map those pages from the CPU side.
  212. Migration to and from device memory
  213. ===================================
  214. Because the CPU cannot access device memory directly, the device driver must
  215. use hardware DMA or device specific load/store instructions to migrate data.
  216. The migrate_vma_setup(), migrate_vma_pages(), and migrate_vma_finalize()
  217. functions are designed to make drivers easier to write and to centralize common
  218. code across drivers.
  219. Before migrating pages to device private memory, special device private
  220. ``struct page`` need to be created. These will be used as special "swap"
  221. page table entries so that a CPU process will fault if it tries to access
  222. a page that has been migrated to device private memory.
  223. These can be allocated and freed with::
  224. struct resource *res;
  225. struct dev_pagemap pagemap;
  226. res = request_free_mem_region(&iomem_resource, /* number of bytes */,
  227. "name of driver resource");
  228. pagemap.type = MEMORY_DEVICE_PRIVATE;
  229. pagemap.range.start = res->start;
  230. pagemap.range.end = res->end;
  231. pagemap.nr_range = 1;
  232. pagemap.ops = &device_devmem_ops;
  233. memremap_pages(&pagemap, numa_node_id());
  234. memunmap_pages(&pagemap);
  235. release_mem_region(pagemap.range.start, range_len(&pagemap.range));
  236. There are also devm_request_free_mem_region(), devm_memremap_pages(),
  237. devm_memunmap_pages(), and devm_release_mem_region() when the resources can
  238. be tied to a ``struct device``.
  239. The overall migration steps are similar to migrating NUMA pages within system
  240. memory (see :ref:`Page migration <page_migration>`) but the steps are split
  241. between device driver specific code and shared common code:
  242. 1. ``mmap_read_lock()``
  243. The device driver has to pass a ``struct vm_area_struct`` to
  244. migrate_vma_setup() so the mmap_read_lock() or mmap_write_lock() needs to
  245. be held for the duration of the migration.
  246. 2. ``migrate_vma_setup(struct migrate_vma *args)``
  247. The device driver initializes the ``struct migrate_vma`` fields and passes
  248. the pointer to migrate_vma_setup(). The ``args->flags`` field is used to
  249. filter which source pages should be migrated. For example, setting
  250. ``MIGRATE_VMA_SELECT_SYSTEM`` will only migrate system memory and
  251. ``MIGRATE_VMA_SELECT_DEVICE_PRIVATE`` will only migrate pages residing in
  252. device private memory. If the latter flag is set, the ``args->pgmap_owner``
  253. field is used to identify device private pages owned by the driver. This
  254. avoids trying to migrate device private pages residing in other devices.
  255. Currently only anonymous private VMA ranges can be migrated to or from
  256. system memory and device private memory.
  257. One of the first steps migrate_vma_setup() does is to invalidate other
  258. device's MMUs with the ``mmu_notifier_invalidate_range_start(()`` and
  259. ``mmu_notifier_invalidate_range_end()`` calls around the page table
  260. walks to fill in the ``args->src`` array with PFNs to be migrated.
  261. The ``invalidate_range_start()`` callback is passed a
  262. ``struct mmu_notifier_range`` with the ``event`` field set to
  263. ``MMU_NOTIFY_MIGRATE`` and the ``migrate_pgmap_owner`` field set to
  264. the ``args->pgmap_owner`` field passed to migrate_vma_setup(). This is
  265. allows the device driver to skip the invalidation callback and only
  266. invalidate device private MMU mappings that are actually migrating.
  267. This is explained more in the next section.
  268. While walking the page tables, a ``pte_none()`` or ``is_zero_pfn()``
  269. entry results in a valid "zero" PFN stored in the ``args->src`` array.
  270. This lets the driver allocate device private memory and clear it instead
  271. of copying a page of zeros. Valid PTE entries to system memory or
  272. device private struct pages will be locked with ``lock_page()``, isolated
  273. from the LRU (if system memory since device private pages are not on
  274. the LRU), unmapped from the process, and a special migration PTE is
  275. inserted in place of the original PTE.
  276. migrate_vma_setup() also clears the ``args->dst`` array.
  277. 3. The device driver allocates destination pages and copies source pages to
  278. destination pages.
  279. The driver checks each ``src`` entry to see if the ``MIGRATE_PFN_MIGRATE``
  280. bit is set and skips entries that are not migrating. The device driver
  281. can also choose to skip migrating a page by not filling in the ``dst``
  282. array for that page.
  283. The driver then allocates either a device private struct page or a
  284. system memory page, locks the page with ``lock_page()``, and fills in the
  285. ``dst`` array entry with::
  286. dst[i] = migrate_pfn(page_to_pfn(dpage)) | MIGRATE_PFN_LOCKED;
  287. Now that the driver knows that this page is being migrated, it can
  288. invalidate device private MMU mappings and copy device private memory
  289. to system memory or another device private page. The core Linux kernel
  290. handles CPU page table invalidations so the device driver only has to
  291. invalidate its own MMU mappings.
  292. The driver can use ``migrate_pfn_to_page(src[i])`` to get the
  293. ``struct page`` of the source and either copy the source page to the
  294. destination or clear the destination device private memory if the pointer
  295. is ``NULL`` meaning the source page was not populated in system memory.
  296. 4. ``migrate_vma_pages()``
  297. This step is where the migration is actually "committed".
  298. If the source page was a ``pte_none()`` or ``is_zero_pfn()`` page, this
  299. is where the newly allocated page is inserted into the CPU's page table.
  300. This can fail if a CPU thread faults on the same page. However, the page
  301. table is locked and only one of the new pages will be inserted.
  302. The device driver will see that the ``MIGRATE_PFN_MIGRATE`` bit is cleared
  303. if it loses the race.
  304. If the source page was locked, isolated, etc. the source ``struct page``
  305. information is now copied to destination ``struct page`` finalizing the
  306. migration on the CPU side.
  307. 5. Device driver updates device MMU page tables for pages still migrating,
  308. rolling back pages not migrating.
  309. If the ``src`` entry still has ``MIGRATE_PFN_MIGRATE`` bit set, the device
  310. driver can update the device MMU and set the write enable bit if the
  311. ``MIGRATE_PFN_WRITE`` bit is set.
  312. 6. ``migrate_vma_finalize()``
  313. This step replaces the special migration page table entry with the new
  314. page's page table entry and releases the reference to the source and
  315. destination ``struct page``.
  316. 7. ``mmap_read_unlock()``
  317. The lock can now be released.
  318. Memory cgroup (memcg) and rss accounting
  319. ========================================
  320. For now, device memory is accounted as any regular page in rss counters (either
  321. anonymous if device page is used for anonymous, file if device page is used for
  322. file backed page, or shmem if device page is used for shared memory). This is a
  323. deliberate choice to keep existing applications, that might start using device
  324. memory without knowing about it, running unimpacted.
  325. A drawback is that the OOM killer might kill an application using a lot of
  326. device memory and not a lot of regular system memory and thus not freeing much
  327. system memory. We want to gather more real world experience on how applications
  328. and system react under memory pressure in the presence of device memory before
  329. deciding to account device memory differently.
  330. Same decision was made for memory cgroup. Device memory pages are accounted
  331. against same memory cgroup a regular page would be accounted to. This does
  332. simplify migration to and from device memory. This also means that migration
  333. back from device memory to regular memory cannot fail because it would
  334. go above memory cgroup limit. We might revisit this choice latter on once we
  335. get more experience in how device memory is used and its impact on memory
  336. resource control.
  337. Note that device memory can never be pinned by a device driver nor through GUP
  338. and thus such memory is always free upon process exit. Or when last reference
  339. is dropped in case of shared memory or file backed memory.