Documentation/core-api/memory-allocation.rst

4 Memory Allocation Guide
7 Linux provides a variety of APIs for memory allocation. You can
11 `alloc_pages`. It is also possible to use more specialized allocators,
14 Most of the memory allocation APIs use GFP flags to express how that
15 memory should be allocated. The GFP acronym stands for "get free
16 pages", the underlying memory allocation function.
19 makes the question "How should I allocate memory?" not that easy to
32 The GFP flags control the allocators behavior. They tell what memory
33 zones can be used, how hard the allocator should try to find free
34 memory, whether the memory can be accessed by the userspace etc. The
35 :ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>` provides
39   * Most of the time ``GFP_KERNEL`` is what you need. Memory for the
40     kernel data structures, DMAable memory, inode cache, all these and
43     direct reclaim may be triggered under memory pressure; the calling
44     context must be allowed to sleep.
47     IO or filesystem operations. Consequently, under memory pressure
48     ``GFP_NOWAIT`` allocation is likely to fail. Allocations which
50   * If you think that accessing memory reserves is justified and the kernel
60     ``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory
64     ``GFP_HIGHUSER`` means that the allocated memory is not movable,
65     but it is not required to be directly accessible by the kernel. An
69     ``GFP_USER`` means that the allocated memory is not movable and it
73 specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to
74 prevent recursion deadlocks caused by direct memory reclaim calling
76 resources. Since 4.12 the preferred way to address this issue is to
78 :ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
81 used to ensure that the allocated memory is accessible by hardware
84 And even with hardware with restrictions it is preferable to use
88 ------------------------------
89 Memory allocations may trigger direct or background reclaim and it is
90 useful to understand how hard the page allocator will try to satisfy that
93   * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_
94     attempt to free memory at all. The most light weight mode which even
96     might deplete the memory and the next user might hit the more aggressive
99   * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic
100     allocation without any attempt to free memory from the current
101     context but can wake kswapd to reclaim memory if the zone is below
106   * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) -
108     some portion of memory reserves. Usually used from interrupt/bottom-half
111   * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
113     allocation requests are basically no-fail but there is no guarantee of
114     that behavior so failures have to be checked properly by callers
115     (e.g. OOM killer victim is allowed to fail currently).
117   * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior
122   * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator
127   * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
131 Selecting memory allocator
134 The most straightforward way to allocate memory is to use a function
135 from the kmalloc() family. And, to be on the safe side it's best to use
136 routines that set memory to zero, like kzalloc(). If you need to
137 allocate memory for an array, there are kmalloc_array() and kcalloc()
139 be used to safely calculate object sizes without overflowing.
143 configuration, but it is a good practice to use `kmalloc` for objects
146 The address of a chunk allocated with `kmalloc` is aligned to at least
148 alignment is also guaranteed to be at least the respective size.
151 to kmalloc_array(): a helper for resizing arrays is provided in the form of
155 request pages from the page allocator. The memory allocated by `vmalloc`
159 `kmalloc`, it is possible to use kvmalloc() and its derivatives. It will
160 try to allocate memory with `kmalloc` and if the allocation fails it
163 documentation. Note that `kvmalloc` may return memory that is not
166 If you need to allocate many identical objects you can use the slab
169 should be used if a part of the cache might be copied to the userspace.
171 wrappers can allocate memory from that cache.
173 When the allocated memory is no longer needed it must be freed.
177 or `kvfree`, where the latter two might be more convenient thanks to not
180 The same rules apply to _bulk and _rcu flavors of freeing functions.
182 Memory allocated by `vmalloc` can be freed with `vfree` or `kvfree`.
183 Memory allocated by `kvmalloc` can be freed with `kvfree`.