189 lines · plain
1.. _memory_allocation:2 3=======================4Memory Allocation Guide5=======================6 7Linux provides a variety of APIs for memory allocation. You can8allocate 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 with11`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 that15memory should be allocated. The GFP acronym stands for "get free16pages", the underlying memory allocation function.17 18Diversity of the allocation APIs combined with the numerous GFP flags19makes the question "How should I allocate memory?" not that easy to20answer, although very likely you should use21 22::23 24 kzalloc(<size>, GFP_KERNEL);25 26Of course there are cases when other allocation APIs and different GFP27flags must be used.28 29Get Free Page flags30===================31 32The GFP flags control the allocators behavior. They tell what memory33zones can be used, how hard the allocator should try to find free34memory, whether the memory can be accessed by the userspace etc. The35:ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>` provides36reference documentation for the GFP flags and their combinations and37here we briefly outline their recommended usage:38 39 * Most of the time ``GFP_KERNEL`` is what you need. Memory for the40 kernel data structures, DMAable memory, inode cache, all these and41 many other allocations types can use ``GFP_KERNEL``. Note, that42 using ``GFP_KERNEL`` implies ``GFP_RECLAIM``, which means that43 direct reclaim may be triggered under memory pressure; the calling44 context must be allowed to sleep.45 * If the allocation is performed from an atomic context, e.g interrupt46 handler, use ``GFP_NOWAIT``. This flag prevents direct reclaim and47 IO or filesystem operations. Consequently, under memory pressure48 ``GFP_NOWAIT`` allocation is likely to fail. Users of this flag need49 to provide a suitable fallback to cope with such failures where50 appropriate.51 * If you think that accessing memory reserves is justified and the kernel52 will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``.53 * Untrusted allocations triggered from userspace should be a subject54 of kmem accounting and must have ``__GFP_ACCOUNT`` bit set. There55 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 longer59 the flag name the less restrictive it is.60 61 ``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory62 will be directly accessible by the kernel and implies that the63 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. An67 example may be a hardware allocation that maps data directly into68 userspace but has no addressing limitations.69 70 ``GFP_USER`` means that the allocated memory is not movable and it71 must be directly accessible by the kernel.72 73You may notice that quite a few allocations in the existing code74specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to75prevent recursion deadlocks caused by direct memory reclaim calling76back into the FS or IO paths and blocking on already held77resources. Since 4.12 the preferred way to address this issue is to78use new scope APIs described in79:ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.80 81Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They are82used to ensure that the allocated memory is accessible by hardware83with limited addressing capabilities. So unless you are writing a84driver for a device with such restrictions, avoid using these flags.85And even with hardware with restrictions it is preferable to use86`dma_alloc*` APIs.87 88GFP flags and reclaim behavior89------------------------------90Memory allocations may trigger direct or background reclaim and it is91useful to understand how hard the page allocator will try to satisfy that92or 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 even96 doesn't kick the background reclaim. Should be used carefully because it97 might deplete the memory and the next user might hit the more aggressive98 reclaim.99 100 * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic101 allocation without any attempt to free memory from the current102 context but can wake kswapd to reclaim memory if the zone is below103 the low watermark. Can be used from either atomic contexts or when104 the request is a performance optimization and there is another105 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 access109 some portion of memory reserves. Usually used from interrupt/bottom-half110 context with an expensive slow path fallback.111 112 * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the113 **default** page allocator behavior is used. That means that not costly114 allocation requests are basically no-fail but there is no guarantee of115 that behavior so failures have to be checked properly by callers116 (e.g. OOM killer victim is allowed to fail currently).117 118 * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior119 and all allocation requests fail early rather than cause disruptive120 reclaim (one round of reclaim in this implementation). The OOM killer121 is not invoked.122 123 * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator124 behavior and all allocation requests try really hard. The request125 will fail if the reclaim cannot make any progress. The OOM killer126 won't be triggered.127 128 * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior129 and all allocation requests will loop endlessly until they succeed.130 This might be really dangerous especially for larger orders.131 132Selecting memory allocator133==========================134 135The most straightforward way to allocate memory is to use a function136from the kmalloc() family. And, to be on the safe side it's best to use137routines that set memory to zero, like kzalloc(). If you need to138allocate memory for an array, there are kmalloc_array() and kcalloc()139helpers. The helpers struct_size(), array_size() and array3_size() can140be used to safely calculate object sizes without overflowing.141 142The maximal size of a chunk that can be allocated with `kmalloc` is143limited. The actual limit depends on the hardware and the kernel144configuration, but it is a good practice to use `kmalloc` for objects145smaller than page size.146 147The address of a chunk allocated with `kmalloc` is aligned to at least148ARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, the149alignment is also guaranteed to be at least the respective size. For other150sizes, the alignment is guaranteed to be at least the largest power-of-two151divisor of the size.152 153Chunks allocated with kmalloc() can be resized with krealloc(). Similarly154to kmalloc_array(): a helper for resizing arrays is provided in the form of155krealloc_array().156 157For large allocations you can use vmalloc() and vzalloc(), or directly158request pages from the page allocator. The memory allocated by `vmalloc`159and related functions is not physically contiguous.160 161If you are not sure whether the allocation size is too large for162`kmalloc`, it is possible to use kvmalloc() and its derivatives. It will163try to allocate memory with `kmalloc` and if the allocation fails it164will be retried with `vmalloc`. There are restrictions on which GFP165flags can be used with `kvmalloc`; please see kvmalloc_node() reference166documentation. Note that `kvmalloc` may return memory that is not167physically contiguous.168 169If you need to allocate many identical objects you can use the slab170cache allocator. The cache should be set up with kmem_cache_create() or171kmem_cache_create_usercopy() before it can be used. The second function172should be used if a part of the cache might be copied to the userspace.173After the cache is created kmem_cache_alloc() and its convenience174wrappers can allocate memory from that cache.175 176When the allocated memory is no longer needed it must be freed.177 178Objects allocated by `kmalloc` can be freed by `kfree` or `kvfree`. Objects179allocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`, `kfree`180or `kvfree`, where the latter two might be more convenient thanks to not181needing the kmem_cache pointer.182 183The same rules apply to _bulk and _rcu flavors of freeing functions.184 185Memory allocated by `vmalloc` can be freed with `vfree` or `kvfree`.186Memory allocated by `kvmalloc` can be freed with `kvfree`.187Caches created by `kmem_cache_create` should be freed with188`kmem_cache_destroy` only after freeing all the allocated objects first.189