Originally, it is a part of the Linux Kernel source code, so it will be treated as GPLv2 (recognition that it should be).
https://www.kernel.org/doc/html/latest/index.html
Licensing documentation
The following describes the license of the Linux kernel source code (GPLv2), how to properly mark the license of individual files in the source tree, as well as links to the full license text.
https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing
https://www.kernel.org/doc/html/latest/_sources/core-api/memory-allocation.rst.txt
Memory Allocation Guide
Linux provides a variety of APIs for memory allocation. You can allocate small chunks using
kmalloc
orkmem_cache_alloc
families, large virtually contiguous areas usingvmalloc
and its derivatives, or you can directly request pages from the page allocator withalloc_pages
. It is also possible to use more specialized allocators, for instancecma_alloc
orzs_malloc
.
Linux provides various APIs for memory allocation. If you want to reserve small chunks, you can use kmalloc
or kmem_cache_alloc
familiy. You can use vmalloc
and its derivations to reserve a large virtual contiguous area. You can also request pages directly from the page allocator using ʻalloc_pages. You can also use
sma_alloc,
zs_malloc`, etc. as more special allocators.
.
Most of the memory allocation APIs use GFP flags to express how that memory should be allocated. The GFP acronym stands for "get free pages", the underlying memory allocation function.
Most memory allocation APIs use the GFP flag to represent how that memory is allocated. The word GFP stands for "get free pages", the underlying memory allocation feature.
.
Diversity of the allocation APIs combined with the numerous GFP flags makes the question "How should I allocate memory?" not that easy to answer, although very likely you should use 'kzalloc(
Due to the diversification of allocation APIs combined with a large number of GFP flags, it is not easy to answer "Which memory allocation function should I use?", But I'm afraid, kzalloc (<size>, GFP_KERNEL" ) "
Will be available.
Of course there are cases when other allocation APIs and different GFP flags must be used.
Of course, you may need to use a GFP flag that is different from other allocation APIs.
Get Free Page flags
The GFP flags control the allocators behavior. They tell what memory zones can be used, how hard the allocator should try to find free memory, whether the memory can be accessed by the userspace etc. The
Documentation/core-api/mm-api.rst <mm-api-gfp-flags>
provides reference documentation for the GFP flags and their combinations and here we briefly outline their recommended usage:
The GFP flag controls the behavior of the allocator. It describes the available memory zones, how the allocator tries to find free memory, how hard it is for the allocator to find free memory, and whether the memory can be accessed from user space. Documentation / core-api / mm-api.rst <mm-api-gfp-flags>
provides reference documentation for GFP glags, how to combine them, and an outline of 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 useGFP_KERNEL
. Note, that usingGFP_KERNEL
impliesGFP_RECLAIM
, which means that direct reclaim may be triggered under memory pressure; the calling context must be allowed to sleep.
GFP_KERNEL
. You can use GFP_KERNEL'for kernel data structures, DMA-processable memory, inode cache, and all other aallocation types. Note that using ‘GFP_KERNEL
means ‘GFP_RECLAIM`. This means that in low memory conditions, direct reuse can be triggered. 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 pressureGFP_NOWAIT
allocation is likely to fail. Allocations which have a reasonable fallback should be usingGFP_NOWARN
.
GFP_NOWAIT
, for example, for interrupt handlers. This flag prevents direct reuse and IO, file system operations. As a result, "GFP_NOWAIT" allocation may fail in low memory conditions. Assignments with proper fallback should use GFP_NOWARM
.
- If you think that accessing memory reserves is justified and the kernel will be stressed unless allocation succeeds, you may use
GFP_ATOMIC
.
GFP_ATOMIC
if memory reserved access is justified and the kernel is not stressed.
- Untrusted allocations triggered from userspace should be a subject of kmem accounting and must have
__GFP_ACCOUNT
bit set. There is the handyGFP_KERNEL_ACCOUNT
shortcut forGFP_KERNEL
allocations that should be accounted.
__GPF_ACCOUNT
bit. The GFP_KERNEL_ACCOUNT
shortcut is useful when assigning GFP_KERNEL
.
- Userspace allocations should use either of the
GFP_USER
,GFP_HIGHUSER
orGFP_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.
GFP_USER
, GFTP_HIGHUSER {
or GFP_HIGHUSER_MOVABLE
flag to secure user space. The longer the flag name, the less restrictive it is.
‘GFP_HIGHUSER_MOVALBLEdoes not require a direct reference to the allocated memory from the kernel and the data is portable.
GHP_HIGHUSER does not have the data it reserves portable, but it is not directly accessed by the kernel. For example, hardware allocation directly maps userspace, but there are no restrictions on addressing. ‘GFP_USER
means that the allocated memory is not portable and is referenced directly by the kernel.You may notice that quite a few allocations in the existing code specify GFP_NOIO
or GFP_NOFS
. Historically, they were used to prevent recursion deadlocks caused by direct memory reclaim calling back into the FS or IO paths and blocking on already held resources. Since 4.12 the preferred way to address this issue is to use new scope APIs described in
Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>
.
In the code that already exists, you may be able to find some allocations, especially where GFP_NOIO
and GFP_NOFS
are present. Historically, they have been used to prevent direct memory reuse callbacks to FS and IO paths and recursive deadlocks caused by blocks of resources already held. As of 4.12, the recommended way to address this issue is to use the new scope API described in Documentation / core-api / gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>
.
.
Other legacy GFP flags are
GFP_DMA
andGFP_DMA32
. They are used to ensure that the allocated memory is accessible by hardware with limited addressing capabilities. So unless you are writing a driver for a device with such restrictions, avoid using these flags. And even with hardware with restrictions it is preferable to usedma_alloc*
APIs.
The other legacy GFP flags are "GFP_DMA" and "GFP_DMA32". They are used to ensure that the allocated memory is accessible to hardware with limited addressing capabilities. Therefore, avoid using these flags unless you are writing a driver for such a restricted device. We also recommend using the dma_alloc *
API, even if you have limited hardware.
Selecting memory allocator
The most straightforward way to allocate memory is to use a function from the kmalloc() family. And, to be on the safe side it's best to use routines that set memory to zero, like kzalloc(). If you need to allocate memory for an array, there are kmalloc_array() and kcalloc() helpers. The helpers struct_size(), array_size() and array3_size() can be used to safely calculate object sizes without overflowing.
The easiest way to allocate memory is to use the kmalloc () family of functions. For safety, it is best to use a routine that sets memory to zero, such as kzalloc (). If you need to allocate memory for an array, you can also use the kmalloc_array () and kcalloc () helpers. The g helper can safely calculate the object size without overflowing using struct_size (), array_size (), array3_size ().
.
The maximal size of a chunk that can be allocated with
kmalloc
is limited. The actual limit depends on the hardware and the kernel configuration, but it is a good practice to usekmalloc
for objects smaller than page size.
There is a limit to the maximum chunk size that can be allocated with kmalloc
. The actual limit depends on your hardware and kernel configuration, but we recommend using "kmalloc" for objects smaller than the page size.
.
The address of a chunk allocated with
kmalloc
is aligned to at least ARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, the alignment is also guaranteed to be at least the respective size.
The chunk addresses assigned by kmalloc
are aligned to at least ARCH_KMALLOC_MINALIGN bytes. For powers of 2, the placement is guaranteed to be at least each size.
.
For large allocations you can use vmalloc() and vzalloc(), or directly request pages from the page allocator. The memory allocated by
vmalloc
and related functions is not physically contiguous.
For large allocations, you can use vmalloc () and vzalloc (), or you can request the page directly from the page allocator. The memory allocated by the function associated with vmalloc
is not physically contiguous.
.
If you are not sure whether the allocation size is too large for
kmalloc
, it is possible to use kvmalloc() and its derivatives. It will try to allocate memory withkmalloc
and if the allocation fails it will be retried withvmalloc
. There are restrictions on which GFP flags can be used withkvmalloc
; please see kvmalloc_node() reference documentation. Note thatkvmalloc
may return memory that is not physically contiguous.
If you're not sure if the allocation size is too large for "kmalloc", you can use kvmalloc () and its derived classes. If you try to allocate memory with kmalloc
and the allocation fails, it will be retried with vmalloc
. There are restrictions on the GFP flags that can be used with kvmalloc
. See the reference documentation for kvmalloc_node (). Note that kvmalloc
may return memory that is not physically contiguous.
If you need to allocate many identical objects you can use the slab cache allocator. The cache should be set up with kmem_cache_create() or kmem_cache_create_usercopy() before it can be used. The second function should be used if a part of the cache might be copied to the userspace. After the cache is created kmem_cache_alloc() and its convenience wrappers can allocate memory from that cache.
If you need to allocate many identical objects, you can use the slab cache allocator. The cache must be set with kmem_cache_create () or kmem_cache_create_usercopy () before it can be used. The second function should be used when part of the cache can be copied to user space. After the cache is created, kmem_cache_alloc () and a convenient wrapper function can allocate memory from the cache.
When the allocated memory is no longer needed it must be freed. You can use kvfree() for the memory allocated with
kmalloc
,vmalloc
andkvmalloc
. The slab caches should be freed with kmem_cache_free(). And don't forget to destroy the cache with kmem_cache_destroy().
When you no longer need the allocated memory, you need to free it. kmalloc
, vmalloc
And you can use kvfree ()
for the memory allocated by kvmalloc
. The slab cache can be freed by kmem_cache_free (). Also, don't forget to destroy the cache with kmem_cache_destroy ().
Recommended Posts