1.. _memory_allocation:
  2
  3=======================
  4Memory Allocation Guide
  5=======================
  6
  7Linux provides a variety of APIs for memory allocation. You can
  8allocate small chunks using `kmalloc` or `kmem_cache_alloc` families,
  9large virtually contiguous areas using `vmalloc` and its derivatives,
 10or you can directly request pages from the page allocator with
 11`alloc_pages`. It is also possible to use more specialized allocators,
 12for instance `cma_alloc` or `zs_malloc`.
 13
 14Most of the memory allocation APIs use GFP flags to express how that
 15memory should be allocated. The GFP acronym stands for "get free
 16pages", the underlying memory allocation function.
 17
 18Diversity of the allocation APIs combined with the numerous GFP flags
 19makes the question "How should I allocate memory?" not that easy to
 20answer, although very likely you should use
 21
 22::
 23
 24  kzalloc(<size>, GFP_KERNEL);
 25
 26Of course there are cases when other allocation APIs and different GFP
 27flags must be used.
 28
 29Get Free Page flags
 30===================
 31
 32The GFP flags control the allocators behavior. They tell what memory
 33zones can be used, how hard the allocator should try to find free
 34memory, whether the memory can be accessed by the userspace etc. The
 35:ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>` provides
 36reference documentation for the GFP flags and their combinations and
 37here 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. Allocations which
 49    have a reasonable fallback should be using ``GFP_NOWARN``.
 50  * If you think that accessing memory reserves is justified and the kernel
 51    will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``.
 52  * Untrusted allocations triggered from userspace should be a subject
 53    of kmem accounting and must have ``__GFP_ACCOUNT`` bit set. There
 54    is the handy ``GFP_KERNEL_ACCOUNT`` shortcut for ``GFP_KERNEL``
 55    allocations that should be accounted.
 56  * Userspace allocations should use either of the ``GFP_USER``,
 57    ``GFP_HIGHUSER`` or ``GFP_HIGHUSER_MOVABLE`` flags. The longer
 58    the flag name the less restrictive it is.
 59
 60    ``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory
 61    will be directly accessible by the kernel and implies that the
 62    data is movable.
 63
 64    ``GFP_HIGHUSER`` means that the allocated memory is not movable,
 65    but it is not required to be directly accessible by the kernel. An
 66    example may be a hardware allocation that maps data directly into
 67    userspace but has no addressing limitations.
 68
 69    ``GFP_USER`` means that the allocated memory is not movable and it
 70    must be directly accessible by the kernel.
 71
 72You may notice that quite a few allocations in the existing code
 73specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to
 74prevent recursion deadlocks caused by direct memory reclaim calling
 75back into the FS or IO paths and blocking on already held
 76resources. Since 4.12 the preferred way to address this issue is to
 77use new scope APIs described in
 78:ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
 79
 80Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They are
 81used to ensure that the allocated memory is accessible by hardware
 82with limited addressing capabilities. So unless you are writing a
 83driver for a device with such restrictions, avoid using these flags.
 84And even with hardware with restrictions it is preferable to use
 85`dma_alloc*` APIs.
 86
 87Selecting memory allocator
 88==========================
 89
 90The most straightforward way to allocate memory is to use a function
 91from the :c:func:`kmalloc` family. And, to be on the safe size it's
 92best to use routines that set memory to zero, like
 93:c:func:`kzalloc`. If you need to allocate memory for an array, there
 94are :c:func:`kmalloc_array` and :c:func:`kcalloc` helpers.
 95
 96The maximal size of a chunk that can be allocated with `kmalloc` is
 97limited. The actual limit depends on the hardware and the kernel
 98configuration, but it is a good practice to use `kmalloc` for objects
 99smaller than page size.
100
101The address of a chunk allocated with `kmalloc` is aligned to at least
102ARCH_KMALLOC_MINALIGN bytes.  For sizes which are a power of two, the
103alignment is also guaranteed to be at least the respective size.
104
105For large allocations you can use :c:func:`vmalloc` and
106:c:func:`vzalloc`, or directly request pages from the page
107allocator. The memory allocated by `vmalloc` and related functions is
108not physically contiguous.
109
110If you are not sure whether the allocation size is too large for
111`kmalloc`, it is possible to use :c:func:`kvmalloc` and its
112derivatives. It will try to allocate memory with `kmalloc` and if the
113allocation fails it will be retried with `vmalloc`. There are
114restrictions on which GFP flags can be used with `kvmalloc`; please
115see :c:func:`kvmalloc_node` reference documentation. Note that
116`kvmalloc` may return memory that is not physically contiguous.
117
118If you need to allocate many identical objects you can use the slab
119cache allocator. The cache should be set up with
120:c:func:`kmem_cache_create` or :c:func:`kmem_cache_create_usercopy`
121before it can be used. The second function should be used if a part of
122the cache might be copied to the userspace.  After the cache is
123created :c:func:`kmem_cache_alloc` and its convenience wrappers can
124allocate memory from that cache.
125
126When the allocated memory is no longer needed it must be freed. You
127can use :c:func:`kvfree` for the memory allocated with `kmalloc`,
128`vmalloc` and `kvmalloc`. The slab caches should be freed with
129:c:func:`kmem_cache_free`. And don't forget to destroy the cache with
130:c:func:`kmem_cache_destroy`.