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. Users of this flag need
49     to provide a suitable fallback to cope with such failures where
51   * If you think that accessing memory reserves is justified and the kernel
61     ``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory
65     ``GFP_HIGHUSER`` means that the allocated memory is not movable,
66     but it is not required to be directly accessible by the kernel. An
70     ``GFP_USER`` means that the allocated memory is not movable and it
74 specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to
75 prevent recursion deadlocks caused by direct memory reclaim calling
77 resources. Since 4.12 the preferred way to address this issue is to
79 :ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
82 used to ensure that the allocated memory is accessible by hardware
85 And even with hardware with restrictions it is preferable to use
89 ------------------------------
90 Memory allocations may trigger direct or background reclaim and it is
91 useful to understand how hard the page allocator will try to satisfy that
94   * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_
95     attempt to free memory at all. The most light weight mode which even
97     might deplete the memory and the next user might hit the more aggressive
100   * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic
101     allocation without any attempt to free memory from the current
102     context but can wake kswapd to reclaim memory if the zone is below
107   * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) -
109     some portion of memory reserves. Usually used from interrupt/bottom-half
112   * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
114     allocation requests are basically no-fail but there is no guarantee of
115     that behavior so failures have to be checked properly by callers
116     (e.g. OOM killer victim is allowed to fail currently).
118   * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior
123   * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator
128   * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
132 Selecting memory allocator
135 The most straightforward way to allocate memory is to use a function
136 from the kmalloc() family. And, to be on the safe side it's best to use
137 routines that set memory to zero, like kzalloc(). If you need to
138 allocate memory for an array, there are kmalloc_array() and kcalloc()
140 be used to safely calculate object sizes without overflowing.
144 configuration, but it is a good practice to use `kmalloc` for objects
147 The address of a chunk allocated with `kmalloc` is aligned to at least
149 alignment is also guaranteed to be at least the respective size. For other
150 sizes, the alignment is guaranteed to be at least the largest power-of-two
154 to kmalloc_array(): a helper for resizing arrays is provided in the form of
158 request pages from the page allocator. The memory allocated by `vmalloc`
162 `kmalloc`, it is possible to use kvmalloc() and its derivatives. It will
163 try to allocate memory with `kmalloc` and if the allocation fails it
166 documentation. Note that `kvmalloc` may return memory that is not
169 If you need to allocate many identical objects you can use the slab
172 should be used if a part of the cache might be copied to the userspace.
174 wrappers can allocate memory from that cache.
176 When the allocated memory is no longer needed it must be freed.
180 or `kvfree`, where the latter two might be more convenient thanks to not
183 The same rules apply to _bulk and _rcu flavors of freeing functions.
185 Memory allocated by `vmalloc` can be freed with `vfree` or `kvfree`.
186 Memory allocated by `kvmalloc` can be freed with `kvfree`.