Something went wrong. Try again.
(I'm so sorry!) Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
Something went wrong. Try again.
9.8 kB · 206 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207.. _memory_allocation:
=======================Memory Allocation Guide=======================
Linux provides a variety of APIs for memory allocation. You canallocate small chunks using `kmalloc` or `kmem_cache_alloc` families,large virtually contiguous areas using `vmalloc` and its derivatives,or you can directly request pages from the page allocator with`alloc_pages`. It is also possible to use more specialized allocators,for instance `cma_alloc` or `zs_malloc`.
Most of the memory allocation APIs use GFP flags to express how thatmemory should be allocated. The GFP acronym stands for "get freepages", the underlying memory allocation function.
Diversity of the allocation APIs combined with the numerous GFP flagsmakes the question "How should I allocate memory?" not that easy toanswer, although very likely you should use
::
kzalloc_obj(<VAR_OR_TYPE>);
if you need memory for an object and
::
kzalloc(<size>, GFP_KERNEL);
if you need memory for a buffer.
Of course there are cases when other allocation APIs and different GFPflags must be used.
Get Free Page flags===================
The GFP flags control the allocators behavior. They tell what memoryzones can be used, how hard the allocator should try to find freememory, whether the memory can be accessed by the userspace etc. The:ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>` providesreference documentation for the GFP flags and their combinations andhere we briefly outline their recommended usage:
* Most of the time ``GFP_KERNEL`` is what you need. Memory for the kernel data structures, DMAable memory, inode cache, all these and many other allocations types can use ``GFP_KERNEL``. Note, that using ``GFP_KERNEL`` implies ``GFP_RECLAIM``, which means that direct reclaim may be triggered under memory pressure; the calling context must be allowed to sleep. * If the allocation is performed from an atomic context, e.g interrupt handler, use ``GFP_NOWAIT``. This flag prevents direct reclaim and IO or filesystem operations. Consequently, under memory pressure ``GFP_NOWAIT`` allocation is likely to fail. Users of this flag need to provide a suitable fallback to cope with such failures where appropriate. * If you think that accessing memory reserves is justified and the kernel will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``. * Untrusted allocations triggered from userspace should be a subject of kmem accounting and must have ``__GFP_ACCOUNT`` bit set. There is the handy ``GFP_KERNEL_ACCOUNT`` shortcut for ``GFP_KERNEL`` allocations that should be accounted. * Userspace allocations should use either of the ``GFP_USER``, ``GFP_HIGHUSER`` or ``GFP_HIGHUSER_MOVABLE`` flags. The longer the flag name the less restrictive it is.
``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory will be directly accessible by the kernel and implies that the data is movable.
``GFP_HIGHUSER`` means that the allocated memory is not movable, but it is not required to be directly accessible by the kernel. An example may be a hardware allocation that maps data directly into userspace but has no addressing limitations.
``GFP_USER`` means that the allocated memory is not movable and it must be directly accessible by the kernel.
You may notice that quite a few allocations in the existing codespecify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used toprevent recursion deadlocks caused by direct memory reclaim callingback into the FS or IO paths and blocking on already heldresources. Since 4.12 the preferred way to address this issue is touse new scope APIs described in:ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They areused to ensure that the allocated memory is accessible by hardwarewith limited addressing capabilities. So unless you are writing adriver for a device with such restrictions, avoid using these flags.And even with hardware with restrictions it is preferable to use`dma_alloc*` APIs.
GFP flags and reclaim behavior------------------------------Memory allocations may trigger direct or background reclaim and it isuseful to understand how hard the page allocator will try to satisfy thator another request.
* ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_ attempt to free memory at all. The most light weight mode which even doesn't kick the background reclaim. Should be used carefully because it might deplete the memory and the next user might hit the more aggressive reclaim.
* ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic allocation without any attempt to free memory from the current context but can wake kswapd to reclaim memory if the zone is below the low watermark. Can be used from either atomic contexts or when the request is a performance optimization and there is another fallback for a slow path.
* ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) - non sleeping allocation with an expensive fallback so it can access some portion of memory reserves. Usually used from interrupt/bottom-half context with an expensive slow path fallback.
* ``GFP_KERNEL`` - both background and direct reclaim are allowed and the **default** page allocator behavior is used. That means that not costly allocation requests are basically no-fail but there is no guarantee of that behavior so failures have to be checked properly by callers (e.g. OOM killer victim is allowed to fail currently).
* ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior and all allocation requests fail early rather than cause disruptive reclaim (one round of reclaim in this implementation). The OOM killer is not invoked.
* ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator behavior and all allocation requests try really hard. The request will fail if the reclaim cannot make any progress. The OOM killer won't be triggered.
* ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior and all allocation requests will loop endlessly until they succeed. This might be really dangerous especially for larger orders.
Selecting memory allocator==========================
The most straightforward way to allocate memory is to use a functionfrom the kmalloc() family. And, to be on the safe side it's best to useroutines that set memory to zero, like kzalloc(). If you need toallocate memory for an array, there are kmalloc_array() and kcalloc()helpers. The helpers struct_size(), array_size() and array3_size() canbe used to safely calculate object sizes without overflowing.
Since 7.0 there are type aware kmalloc-family helpers that let you safely andconveniently allocate a single object or arrays of objects with kzalloc_obj()and kmalloc_obj() and their array versions kzalloc_objs() andkmalloc_objs(). These helpers only need the type of the object that should beallocated and the count of elements in the array for the array versions.
As of v7.2, vast majority of the memory allocations use kzalloc_obj().
The address of a chunk allocated with `kmalloc` is aligned to at leastARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, thealignment is also guaranteed to be at least the respective size. For othersizes, the alignment is guaranteed to be at least the largest power-of-twodivisor of the size.
Chunks allocated with kmalloc() can be resized with krealloc(). Similarlyto kmalloc_array(): a helper for resizing arrays is provided in the form ofkrealloc_array().
`kmalloc` always allocates physically contiguous memory and the maximal size ofa chunk that can be allocated with `kmalloc` is limited by `KMALLOC_MAX_SIZE`,which matches the page allocator's MAX_PAGE_ORDER limit.
Internally, the slab allocator differentiates allocations of different ordersand delegates larger allocations to the page allocator, but for the users of`kmalloc` family it is entirely transparent.
For large allocations that do not require physically contiguous memory you canuse vmalloc() and vzalloc() family.
If you are not sure whether the allocation size is too large for`kmalloc`, it is possible to use kvmalloc() and its derivatives. It willtry to allocate memory with `kmalloc` and if the allocation fails itwill be retried with `vmalloc`. There are restrictions on which GFPflags can be used with `kvmalloc`; please see kvmalloc_node() referencedocumentation. Note that `kvmalloc` may return memory that is notphysically contiguous.
If you need to allocate many identical objects you can use the slabcache allocator. The cache should be set up with kmem_cache_create() orkmem_cache_create_usercopy() before it can be used. The second functionshould be used if a part of the cache might be copied to the userspace.After the cache is created kmem_cache_alloc() and its conveniencewrappers can allocate memory from that cache.
When the allocated memory is no longer needed it must be freed.
Objects allocated by `kmalloc` can be freed by `kfree` or `kvfree`. Objectsallocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`, `kfree`or `kvfree`, where the latter two might be more convenient thanks to notneeding the kmem_cache pointer.
The same rules apply to _bulk and _rcu flavors of freeing functions.
Memory allocated by `vmalloc` can be freed with `vfree` or `kvfree`.Memory allocated by `kvmalloc` can be freed with `kvfree`.Caches created by `kmem_cache_create` should be freed with`kmem_cache_destroy` only after freeing all the allocated objects first.