Documentation/core-api/memory-allocation.rst

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