]>
Commit | Line | Data |
---|---|---|
cd7198fc | 1 | .. _memory_allocation: |
acf0f57a | 2 | |
52272c92 MR |
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. Allocations which | |
49 | have a reasonable fallback should be using ``GFP_NOWARN``. | |
50 | * If you think that accessing memory reserves is justified and the kernel | |
51 | will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``. | |
52 | * Untrusted allocations triggered from userspace should be a subject | |
53 | of kmem accounting and must have ``__GFP_ACCOUNT`` bit set. There | |
54 | is the handy ``GFP_KERNEL_ACCOUNT`` shortcut for ``GFP_KERNEL`` | |
55 | allocations that should be accounted. | |
56 | * Userspace allocations should use either of the ``GFP_USER``, | |
57 | ``GFP_HIGHUSER`` or ``GFP_HIGHUSER_MOVABLE`` flags. The longer | |
58 | the flag name the less restrictive it is. | |
59 | ||
60 | ``GFP_HIGHUSER_MOVABLE`` does not require that allocated memory | |
61 | will be directly accessible by the kernel and implies that the | |
62 | data is movable. | |
63 | ||
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 | |
66 | example may be a hardware allocation that maps data directly into | |
67 | userspace but has no addressing limitations. | |
68 | ||
69 | ``GFP_USER`` means that the allocated memory is not movable and it | |
70 | must be directly accessible by the kernel. | |
71 | ||
72 | You may notice that quite a few allocations in the existing code | |
73 | specify ``GFP_NOIO`` or ``GFP_NOFS``. Historically, they were used to | |
74 | prevent recursion deadlocks caused by direct memory reclaim calling | |
75 | back into the FS or IO paths and blocking on already held | |
76 | resources. Since 4.12 the preferred way to address this issue is to | |
77 | use new scope APIs described in | |
78 | :ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`. | |
79 | ||
80 | Other legacy GFP flags are ``GFP_DMA`` and ``GFP_DMA32``. They are | |
81 | used to ensure that the allocated memory is accessible by hardware | |
82 | with limited addressing capabilities. So unless you are writing a | |
83 | driver for a device with such restrictions, avoid using these flags. | |
84 | And even with hardware with restrictions it is preferable to use | |
85 | `dma_alloc*` APIs. | |
86 | ||
87 | Selecting memory allocator | |
88 | ========================== | |
89 | ||
90 | The most straightforward way to allocate memory is to use a function | |
91 | from the :c:func:`kmalloc` family. And, to be on the safe size it's | |
92 | best to use routines that set memory to zero, like | |
93 | :c:func:`kzalloc`. If you need to allocate memory for an array, there | |
94 | are :c:func:`kmalloc_array` and :c:func:`kcalloc` helpers. | |
95 | ||
96 | The maximal size of a chunk that can be allocated with `kmalloc` is | |
97 | limited. The actual limit depends on the hardware and the kernel | |
98 | configuration, but it is a good practice to use `kmalloc` for objects | |
99 | smaller than page size. | |
100 | ||
59bb4798 VB |
101 | The address of a chunk allocated with `kmalloc` is aligned to at least |
102 | ARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, the | |
103 | alignment is also guaranteed to be at least the respective size. | |
104 | ||
52272c92 MR |
105 | For large allocations you can use :c:func:`vmalloc` and |
106 | :c:func:`vzalloc`, or directly request pages from the page | |
107 | allocator. The memory allocated by `vmalloc` and related functions is | |
108 | not physically contiguous. | |
109 | ||
110 | If you are not sure whether the allocation size is too large for | |
111 | `kmalloc`, it is possible to use :c:func:`kvmalloc` and its | |
112 | derivatives. It will try to allocate memory with `kmalloc` and if the | |
113 | allocation fails it will be retried with `vmalloc`. There are | |
114 | restrictions on which GFP flags can be used with `kvmalloc`; please | |
115 | see :c:func:`kvmalloc_node` reference documentation. Note that | |
116 | `kvmalloc` may return memory that is not physically contiguous. | |
117 | ||
118 | If you need to allocate many identical objects you can use the slab | |
119 | cache allocator. The cache should be set up with | |
98e5f349 MR |
120 | :c:func:`kmem_cache_create` or :c:func:`kmem_cache_create_usercopy` |
121 | before it can be used. The second function should be used if a part of | |
122 | the cache might be copied to the userspace. After the cache is | |
123 | created :c:func:`kmem_cache_alloc` and its convenience wrappers can | |
124 | allocate memory from that cache. | |
52272c92 MR |
125 | |
126 | When the allocated memory is no longer needed it must be freed. You | |
127 | can use :c:func:`kvfree` for the memory allocated with `kmalloc`, | |
128 | `vmalloc` and `kvmalloc`. The slab caches should be freed with | |
129 | :c:func:`kmem_cache_free`. And don't forget to destroy the cache with | |
130 | :c:func:`kmem_cache_destroy`. |