linux - Documentation/core-api/memory-allocation.rst

188 lines · 9.0 KiB

1	.. _memory_allocation:
2
3	=======================
4	Memory Allocation Guide
5	=======================
6
7	Linux provides a variety of APIs for memory allocation. You can
8	allocate small chunks using `kmalloc` or `kmem_cache_alloc` families,
9	large virtually contiguous areas using `vmalloc` and its derivatives,
10	or you can directly request pages from the page allocator with
11	`alloc_pages`. It is also possible to use more specialized allocators,
12	for instance `cma_alloc` or `zs_malloc`.
13
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.
17
18	Diversity of the allocation APIs combined with the numerous GFP flags
19	makes the question "How should I allocate memory?" not that easy to
20	answer, although very likely you should use
21
22	::
23
24	kzalloc(<size>, GFP_KERNEL);
25
26	Of course there are cases when other allocation APIs and different GFP
27	flags must be used.
28
29	Get Free Page flags
30	===================
31
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
36	reference documentation for the GFP flags and their combinations and
37	here we briefly outline their recommended usage:
38
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
41	many other allocations types can use ``GFP_KERNEL``. Note, that
42	using ``GFP_KERNEL`` implies ``GFP_RECLAIM``, which means that
43	direct reclaim may be triggered under memory pressure; the calling
44	context must be allowed to sleep.
45	* If the allocation is performed from an atomic context, e.g interrupt
46	handler, use ``GFP_NOWAIT``. This flag prevents direct reclaim and
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
50	appropriate.
51	* If you think that accessing memory reserves is justified and the kernel
52	will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``.
53	* Untrusted allocations triggered from userspace should be a subject
54	of kmem accounting and must have ``__GFP_ACCOUNT`` bit set. There
55	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 longer
59	the flag name the less restrictive it is.
60
61	``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory
62	will be directly accessible by the kernel and implies that the
63	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. An
67	example may be a hardware allocation that maps data directly into
68	userspace but has no addressing limitations.
69
70	``GFP_USER`` means that the allocated memory is not movable and it
71	must be directly accessible by the kernel.
72
73	You may notice that quite a few allocations in the existing code
74	specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to
75	prevent recursion deadlocks caused by direct memory reclaim calling
76	back into the FS or IO paths and blocking on already held
77	resources. Since 4.12 the preferred way to address this issue is to
78	use new scope APIs described in
79	:ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
80
81	Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They are
82	used to ensure that the allocated memory is accessible by hardware
83	with limited addressing capabilities. So unless you are writing a
84	driver for a device with such restrictions, avoid using these flags.
85	And even with hardware with restrictions it is preferable to use
86	`dma_alloc*` APIs.
87
88	GFP flags and reclaim behavior
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
92	or 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 even
96	doesn't kick the background reclaim. Should be used carefully because it
97	might deplete the memory and the next user might hit the more aggressive
98	reclaim.
99
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
103	the low watermark. Can be used from either atomic contexts or when
104	the request is a performance optimization and there is another
105	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 access
109	some portion of memory reserves. Usually used from interrupt/bottom-half
110	context with an expensive slow path fallback.
111
112	* ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
113	default page allocator behavior is used. That means that not costly
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).
117
118	* ``GFP_KERNEL \| __GFP_NORETRY`` - overrides the default allocator behavior
119	and all allocation requests fail early rather than cause disruptive
120	reclaim (one round of reclaim in this implementation). The OOM killer
121	is not invoked.
122
123	* ``GFP_KERNEL \| __GFP_RETRY_MAYFAIL`` - overrides the default allocator
124	behavior and all allocation requests try really hard. The request
125	will fail if the reclaim cannot make any progress. The OOM killer
126	won't be triggered.
127
128	* ``GFP_KERNEL \| __GFP_NOFAIL`` - overrides the default allocator behavior
129	and all allocation requests will loop endlessly until they succeed.
130	This might be really dangerous especially for larger orders.
131
132	Selecting memory allocator
133	==========================
134
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()
139	helpers. The helpers struct_size(), array_size() and array3_size() can
140	be used to safely calculate object sizes without overflowing.
141
142	The maximal size of a chunk that can be allocated with `kmalloc` is
143	limited. The actual limit depends on the hardware and the kernel
144	configuration, but it is a good practice to use `kmalloc` for objects
145	smaller than page size.
146
147	The address of a chunk allocated with `kmalloc` is aligned to at least
148	ARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, the
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
151	divisor of the size.
152
153	Chunks allocated with kmalloc() can be resized with krealloc(). Similarly
154	to kmalloc_array(): a helper for resizing arrays is provided in the form of
155	krealloc_array().
156
157	For large allocations you can use vmalloc() and vzalloc(), or directly
158	request pages from the page allocator. The memory allocated by `vmalloc`
159	and related functions is not physically contiguous.
160
161	If you are not sure whether the allocation size is too large for
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
164	will be retried with `vmalloc`. There are restrictions on which GFP
165	flags can be used with `kvmalloc`; please see kvmalloc_node() reference
166	documentation. Note that `kvmalloc` may return memory that is not
167	physically contiguous.
168
169	If you need to allocate many identical objects you can use the slab
170	cache allocator. The cache should be set up with kmem_cache_create() or
171	kmem_cache_create_usercopy() before it can be used. The second function
172	should be used if a part of the cache might be copied to the userspace.
173	After the cache is created kmem_cache_alloc() and its convenience
174	wrappers can allocate memory from that cache.
175
176	When the allocated memory is no longer needed it must be freed.
177
178	Objects allocated by `kmalloc` can be freed by `kfree` or `kvfree`. Objects
179	allocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`, `kfree`
180	or `kvfree`, where the latter two might be more convenient thanks to not
181	needing the kmem_cache pointer.
182
183	The same rules apply to _bulk and _rcu flavors of freeing functions.
184
185	Memory allocated by `vmalloc` can be freed with `vfree` or `kvfree`.
186	Memory allocated by `kvmalloc` can be freed with `kvfree`.
187	Caches created by `kmem_cache_create` should be freed with
188	`kmem_cache_destroy` only after freeing all the allocated objects first.