memory-allocation.rst 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  1. .. _memory_allocation:
  2. =======================
  3. Memory Allocation Guide
  4. =======================
  5. Linux provides a variety of APIs for memory allocation. You can
  6. allocate small chunks using `kmalloc` or `kmem_cache_alloc` families,
  7. large virtually contiguous areas using `vmalloc` and its derivatives,
  8. or you can directly request pages from the page allocator with
  9. `alloc_pages`. It is also possible to use more specialized allocators,
  10. for instance `cma_alloc` or `zs_malloc`.
  11. Most of the memory allocation APIs use GFP flags to express how that
  12. memory should be allocated. The GFP acronym stands for "get free
  13. pages", the underlying memory allocation function.
  14. Diversity of the allocation APIs combined with the numerous GFP flags
  15. makes the question "How should I allocate memory?" not that easy to
  16. answer, although very likely you should use
  17. ::
  18. kzalloc(<size>, GFP_KERNEL);
  19. Of course there are cases when other allocation APIs and different GFP
  20. flags must be used.
  21. Get Free Page flags
  22. ===================
  23. The GFP flags control the allocators behavior. They tell what memory
  24. zones can be used, how hard the allocator should try to find free
  25. memory, whether the memory can be accessed by the userspace etc. The
  26. :ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>` provides
  27. reference documentation for the GFP flags and their combinations and
  28. here we briefly outline their recommended usage:
  29. * Most of the time ``GFP_KERNEL`` is what you need. Memory for the
  30. kernel data structures, DMAable memory, inode cache, all these and
  31. many other allocations types can use ``GFP_KERNEL``. Note, that
  32. using ``GFP_KERNEL`` implies ``GFP_RECLAIM``, which means that
  33. direct reclaim may be triggered under memory pressure; the calling
  34. context must be allowed to sleep.
  35. * If the allocation is performed from an atomic context, e.g interrupt
  36. handler, use ``GFP_NOWAIT``. This flag prevents direct reclaim and
  37. IO or filesystem operations. Consequently, under memory pressure
  38. ``GFP_NOWAIT`` allocation is likely to fail. Allocations which
  39. have a reasonable fallback should be using ``GFP_NOWARN``.
  40. * If you think that accessing memory reserves is justified and the kernel
  41. will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``.
  42. * Untrusted allocations triggered from userspace should be a subject
  43. of kmem accounting and must have ``__GFP_ACCOUNT`` bit set. There
  44. is the handy ``GFP_KERNEL_ACCOUNT`` shortcut for ``GFP_KERNEL``
  45. allocations that should be accounted.
  46. * Userspace allocations should use either of the ``GFP_USER``,
  47. ``GFP_HIGHUSER`` or ``GFP_HIGHUSER_MOVABLE`` flags. The longer
  48. the flag name the less restrictive it is.
  49. ``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory
  50. will be directly accessible by the kernel and implies that the
  51. data is movable.
  52. ``GFP_HIGHUSER`` means that the allocated memory is not movable,
  53. but it is not required to be directly accessible by the kernel. An
  54. example may be a hardware allocation that maps data directly into
  55. userspace but has no addressing limitations.
  56. ``GFP_USER`` means that the allocated memory is not movable and it
  57. must be directly accessible by the kernel.
  58. You may notice that quite a few allocations in the existing code
  59. specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to
  60. prevent recursion deadlocks caused by direct memory reclaim calling
  61. back into the FS or IO paths and blocking on already held
  62. resources. Since 4.12 the preferred way to address this issue is to
  63. use new scope APIs described in
  64. :ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
  65. Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They are
  66. used to ensure that the allocated memory is accessible by hardware
  67. with limited addressing capabilities. So unless you are writing a
  68. driver for a device with such restrictions, avoid using these flags.
  69. And even with hardware with restrictions it is preferable to use
  70. `dma_alloc*` APIs.
  71. GFP flags and reclaim behavior
  72. ------------------------------
  73. Memory allocations may trigger direct or background reclaim and it is
  74. useful to understand how hard the page allocator will try to satisfy that
  75. or another request.
  76. * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_
  77. attempt to free memory at all. The most light weight mode which even
  78. doesn't kick the background reclaim. Should be used carefully because it
  79. might deplete the memory and the next user might hit the more aggressive
  80. reclaim.
  81. * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic
  82. allocation without any attempt to free memory from the current
  83. context but can wake kswapd to reclaim memory if the zone is below
  84. the low watermark. Can be used from either atomic contexts or when
  85. the request is a performance optimization and there is another
  86. fallback for a slow path.
  87. * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) -
  88. non sleeping allocation with an expensive fallback so it can access
  89. some portion of memory reserves. Usually used from interrupt/bottom-half
  90. context with an expensive slow path fallback.
  91. * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
  92. **default** page allocator behavior is used. That means that not costly
  93. allocation requests are basically no-fail but there is no guarantee of
  94. that behavior so failures have to be checked properly by callers
  95. (e.g. OOM killer victim is allowed to fail currently).
  96. * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior
  97. and all allocation requests fail early rather than cause disruptive
  98. reclaim (one round of reclaim in this implementation). The OOM killer
  99. is not invoked.
  100. * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator
  101. behavior and all allocation requests try really hard. The request
  102. will fail if the reclaim cannot make any progress. The OOM killer
  103. won't be triggered.
  104. * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
  105. and all allocation requests will loop endlessly until they succeed.
  106. This might be really dangerous especially for larger orders.
  107. Selecting memory allocator
  108. ==========================
  109. The most straightforward way to allocate memory is to use a function
  110. from the kmalloc() family. And, to be on the safe side it's best to use
  111. routines that set memory to zero, like kzalloc(). If you need to
  112. allocate memory for an array, there are kmalloc_array() and kcalloc()
  113. helpers. The helpers struct_size(), array_size() and array3_size() can
  114. be used to safely calculate object sizes without overflowing.
  115. The maximal size of a chunk that can be allocated with `kmalloc` is
  116. limited. The actual limit depends on the hardware and the kernel
  117. configuration, but it is a good practice to use `kmalloc` for objects
  118. smaller than page size.
  119. The address of a chunk allocated with `kmalloc` is aligned to at least
  120. ARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, the
  121. alignment is also guaranteed to be at least the respective size.
  122. For large allocations you can use vmalloc() and vzalloc(), or directly
  123. request pages from the page allocator. The memory allocated by `vmalloc`
  124. and related functions is not physically contiguous.
  125. If you are not sure whether the allocation size is too large for
  126. `kmalloc`, it is possible to use kvmalloc() and its derivatives. It will
  127. try to allocate memory with `kmalloc` and if the allocation fails it
  128. will be retried with `vmalloc`. There are restrictions on which GFP
  129. flags can be used with `kvmalloc`; please see kvmalloc_node() reference
  130. documentation. Note that `kvmalloc` may return memory that is not
  131. physically contiguous.
  132. If you need to allocate many identical objects you can use the slab
  133. cache allocator. The cache should be set up with kmem_cache_create() or
  134. kmem_cache_create_usercopy() before it can be used. The second function
  135. should be used if a part of the cache might be copied to the userspace.
  136. After the cache is created kmem_cache_alloc() and its convenience
  137. wrappers can allocate memory from that cache.
  138. When the allocated memory is no longer needed it must be freed. You can
  139. use kvfree() for the memory allocated with `kmalloc`, `vmalloc` and
  140. `kvmalloc`. The slab caches should be freed with kmem_cache_free(). And
  141. don't forget to destroy the cache with kmem_cache_destroy().