1======================= 2Memory Allocation Guide 3======================= 4 5Linux provides a variety of APIs for memory allocation. You can 6allocate small chunks using `kmalloc` or `kmem_cache_alloc` families, 7large virtually contiguous areas using `vmalloc` and its derivatives, 8or you can directly request pages from the page allocator with 9`alloc_pages`. It is also possible to use more specialized allocators, 10for instance `cma_alloc` or `zs_malloc`. 11 12Most of the memory allocation APIs use GFP flags to express how that 13memory should be allocated. The GFP acronym stands for "get free 14pages", the underlying memory allocation function. 15 16Diversity of the allocation APIs combined with the numerous GFP flags 17makes the question "How should I allocate memory?" not that easy to 18answer, although very likely you should use 19 20:: 21 22 kzalloc(<size>, GFP_KERNEL); 23 24Of course there are cases when other allocation APIs and different GFP 25flags must be used. 26 27Get Free Page flags 28=================== 29 30The GFP flags control the allocators behavior. They tell what memory 31zones can be used, how hard the allocator should try to find free 32memory, whether the memory can be accessed by the userspace etc. The 33:ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>` provides 34reference documentation for the GFP flags and their combinations and 35here 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 70You may notice that quite a few allocations in the existing code 71specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to 72prevent recursion deadlocks caused by direct memory reclaim calling 73back into the FS or IO paths and blocking on already held 74resources. Since 4.12 the preferred way to address this issue is to 75use new scope APIs described in 76:ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`. 77 78Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They are 79used to ensure that the allocated memory is accessible by hardware 80with limited addressing capabilities. So unless you are writing a 81driver for a device with such restrictions, avoid using these flags. 82And even with hardware with restrictions it is preferable to use 83`dma_alloc*` APIs. 84 85Selecting memory allocator 86========================== 87 88The most straightforward way to allocate memory is to use a function 89from the :c:func:`kmalloc` family. And, to be on the safe size it's 90best to use routines that set memory to zero, like 91:c:func:`kzalloc`. If you need to allocate memory for an array, there 92are :c:func:`kmalloc_array` and :c:func:`kcalloc` helpers. 93 94The maximal size of a chunk that can be allocated with `kmalloc` is 95limited. The actual limit depends on the hardware and the kernel 96configuration, but it is a good practice to use `kmalloc` for objects 97smaller than page size. 98 99For large allocations you can use :c:func:`vmalloc` and 100:c:func:`vzalloc`, or directly request pages from the page 101allocator. The memory allocated by `vmalloc` and related functions is 102not physically contiguous. 103 104If you are not sure whether the allocation size is too large for 105`kmalloc`, it is possible to use :c:func:`kvmalloc` and its 106derivatives. It will try to allocate memory with `kmalloc` and if the 107allocation fails it will be retried with `vmalloc`. There are 108restrictions on which GFP flags can be used with `kvmalloc`; please 109see :c:func:`kvmalloc_node` reference documentation. Note that 110`kvmalloc` may return memory that is not physically contiguous. 111 112If you need to allocate many identical objects you can use the slab 113cache 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 116memory from that cache. 117 118When the allocated memory is no longer needed it must be freed. You 119can 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`. 123