Documentation/core-api/memory-allocation.rst

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