1 .. SPDX-License-Identifier: GPL-2.0
5 =====================================================================
6 Deprecated Interfaces, Language Features, Attributes, and Conventions
7 =====================================================================
9 In a perfect world, it would be possible to convert all instances of
10 some deprecated API into the new API and entirely remove the old API in
11 a single development cycle. However, due to the size of the kernel, the
12 maintainership hierarchy, and timing, it's not always feasible to do these
13 kinds of conversions at once. This means that new instances may sneak into
14 the kernel while old ones are being removed, only making the amount of
15 work to remove the API grow. In order to educate developers about what
16 has been deprecated and why, this list has been created as a place to
17 point when uses of deprecated things are proposed for inclusion in the
22 While this attribute does visually mark an interface as deprecated,
23 it `does not produce warnings during builds any more
24 <https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_
25 because one of the standing goals of the kernel is to build without
26 warnings and no one was actually doing anything to remove these deprecated
27 interfaces. While using `__deprecated` is nice to note an old API in
28 a header file, it isn't the full solution. Such interfaces must either
29 be fully removed from the kernel, or added to this file to discourage
30 others from using them in the future.
34 Use WARN() and WARN_ON() instead, and handle the "impossible"
35 error condition as gracefully as possible. While the BUG()-family
36 of APIs were originally designed to act as an "impossible situation"
37 assert and to kill a kernel thread "safely", they turn out to just be
38 too risky. (e.g. "In what order do locks need to be released? Have
39 various states been restored?") Very commonly, using BUG() will
40 destabilize a system or entirely break it, which makes it impossible
41 to debug or even get viable crash reports. Linus has `very strong
42 <https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_
44 <https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_.
46 Note that the WARN()-family should only be used for "expected to
47 be unreachable" situations. If you want to warn about "reachable
48 but undesirable" situations, please use the pr_warn()-family of
49 functions. System owners may have set the *panic_on_warn* sysctl,
50 to make sure their systems do not continue running in the face of
51 "unreachable" conditions. (For example, see commits like `this one
52 <https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)
54 open-coded arithmetic in allocator arguments
55 --------------------------------------------
56 Dynamic size calculations (especially multiplication) should not be
57 performed in memory allocator (or similar) function arguments due to the
58 risk of them overflowing. This could lead to values wrapping around and a
59 smaller allocation being made than the caller was expecting. Using those
60 allocations could lead to linear overflows of heap memory and other
61 misbehaviors. (One exception to this is literal values where the compiler
62 can warn if they might overflow. Though using literals for arguments as
63 suggested below is also harmless.)
65 For example, do not use ``count * size`` as an argument, as in::
67 foo = kmalloc(count * size, GFP_KERNEL);
69 Instead, the 2-factor form of the allocator should be used::
71 foo = kmalloc_array(count, size, GFP_KERNEL);
73 Specifically, kmalloc() can be replaced with kmalloc_array(), and
74 kzalloc() can be replaced with kcalloc().
76 If no 2-factor form is available, the saturate-on-overflow helpers should
79 bar = vmalloc(array_size(count, size));
81 Another common case to avoid is calculating the size of a structure with
82 a trailing array of others structures, as in::
84 header = kzalloc(sizeof(*header) + count * sizeof(*header->item),
87 Instead, use the helper::
89 header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
91 .. note:: If you are using struct_size() on a structure containing a zero-length
92 or a one-element array as a trailing array member, please refactor such
93 array usage and switch to a `flexible array member
94 <#zero-length-and-one-element-arrays>`_ instead.
96 For other calculations, please compose the use of the size_mul(),
97 size_add(), and size_sub() helpers. For example, in the case of::
99 foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);
101 Instead, use the helpers::
103 foo = krealloc(size_add(current_size,
105 size_sub(count, 3))), GFP_KERNEL);
107 For more details, also see array3_size() and flex_array_size(),
108 as well as the related check_mul_overflow(), check_add_overflow(),
109 check_sub_overflow(), and check_shl_overflow() family of functions.
111 simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
112 ----------------------------------------------------------------------
113 The simple_strtol(), simple_strtoll(),
114 simple_strtoul(), and simple_strtoull() functions
115 explicitly ignore overflows, which may lead to unexpected results
116 in callers. The respective kstrtol(), kstrtoll(),
117 kstrtoul(), and kstrtoull() functions tend to be the
118 correct replacements, though note that those require the string to be
119 NUL or newline terminated.
123 strcpy() performs no bounds checking on the destination buffer. This
124 could result in linear overflows beyond the end of the buffer, leading to
125 all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various
126 compiler flags help reduce the risk of using this function, there is
127 no good reason to add new uses of this function. The safe replacement
128 is strscpy(), though care must be given to any cases where the return
129 value of strcpy() was used, since strscpy() does not return a pointer to
130 the destination, but rather a count of non-NUL bytes copied (or negative
131 errno when it truncates).
133 strncpy() on NUL-terminated strings
134 -----------------------------------
135 Use of strncpy() does not guarantee that the destination buffer will
136 be NUL terminated. This can lead to various linear read overflows and
137 other misbehavior due to the missing termination. It also NUL-pads
138 the destination buffer if the source contents are shorter than the
139 destination buffer size, which may be a needless performance penalty
140 for callers using only NUL-terminated strings. The safe replacement is
141 strscpy(), though care must be given to any cases where the return value
142 of strncpy() was used, since strscpy() does not return a pointer to the
143 destination, but rather a count of non-NUL bytes copied (or negative
144 errno when it truncates). Any cases still needing NUL-padding should
145 instead use strscpy_pad().
147 If a caller is using non-NUL-terminated strings, strncpy() can
148 still be used, but destinations should be marked with the `__nonstring
149 <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_
150 attribute to avoid future compiler warnings.
154 strlcpy() reads the entire source buffer first (since the return value
155 is meant to match that of strlen()). This read may exceed the destination
156 size limit. This is both inefficient and can lead to linear read overflows
157 if a source string is not NUL-terminated. The safe replacement is strscpy(),
158 though care must be given to any cases where the return value of strlcpy()
159 is used, since strscpy() will return negative errno values when it truncates.
163 Traditionally, using "%p" in format strings would lead to regular address
164 exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to
165 be exploitable, all "%p" uses in the kernel are being printed as a hashed
166 value, rendering them unusable for addressing. New uses of "%p" should not
167 be added to the kernel. For text addresses, using "%pS" is likely better,
168 as it produces the more useful symbol name instead. For nearly everything
169 else, just do not add "%p" at all.
171 Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_:
173 - If the hashed "%p" value is pointless, ask yourself whether the pointer
174 itself is important. Maybe it should be removed entirely?
175 - If you really think the true pointer value is important, why is some
176 system state or user privilege level considered "special"? If you think
177 you can justify it (in comments and commit log) well enough to stand
178 up to Linus's scrutiny, maybe you can use "%px", along with making sure
179 you have sensible permissions.
181 And finally, know that a toggle for "%p" hashing will `not be accepted <https://lore.kernel.org/lkml/CA+55aFwieC1-nAs+NFq9RTwaR8ef9hWa4MjNBWL41F-8wM49eA@mail.gmail.com/>`_.
183 Variable Length Arrays (VLAs)
184 -----------------------------
185 Using stack VLAs produces much worse machine code than statically
186 sized stack arrays. While these non-trivial `performance issues
187 <https://git.kernel.org/linus/02361bc77888>`_ are reason enough to
188 eliminate VLAs, they are also a security risk. Dynamic growth of a stack
189 array may exceed the remaining memory in the stack segment. This could
190 lead to a crash, possible overwriting sensitive contents at the end of the
191 stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting
192 memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
194 Implicit switch case fall-through
195 ---------------------------------
196 The C language allows switch cases to fall through to the next case
197 when a "break" statement is missing at the end of a case. This, however,
198 introduces ambiguity in the code, as it's not always clear if the missing
199 break is intentional or a bug. For example, it's not obvious just from
200 looking at the code if `STATE_ONE` is intentionally designed to fall
201 through into `STATE_TWO`::
210 WARN("unknown state");
213 As there have been a long list of flaws `due to missing "break" statements
214 <https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow
215 implicit fall-through. In order to identify intentional fall-through
216 cases, we have adopted a pseudo-keyword macro "fallthrough" which
217 expands to gcc's extension `__attribute__((__fallthrough__))
218 <https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_.
219 (When the C17/C18 `[[fallthrough]]` syntax is more commonly supported by
220 C compilers, static analyzers, and IDEs, we can switch to using that syntax
221 for the macro pseudo-keyword.)
223 All switch/case blocks must end in one of:
229 * return [expression];
231 Zero-length and one-element arrays
232 ----------------------------------
233 There is a regular need in the kernel to provide a way to declare having
234 a dynamically sized set of trailing elements in a structure. Kernel code
235 should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_
236 for these cases. The older style of one-element or zero-length arrays should
239 In older C code, dynamically sized trailing elements were done by specifying
240 a one-element array at the end of a structure::
247 This led to fragile size calculations via sizeof() (which would need to
248 remove the size of the single trailing element to get a correct size of
249 the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_
250 was introduced to allow for zero-length arrays, to avoid these kinds of
258 But this led to other problems, and didn't solve some problems shared by
259 both styles, like not being able to detect when such an array is accidentally
260 being used _not_ at the end of a structure (which could happen directly, or
261 when such a struct was in unions, structs of structs, etc).
263 C99 introduced "flexible array members", which lacks a numeric size for
264 the array declaration entirely::
271 This is the way the kernel expects dynamically sized trailing elements
272 to be declared. It allows the compiler to generate errors when the
273 flexible array does not occur last in the structure, which helps to prevent
274 some kind of `undefined behavior
275 <https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_
276 bugs from being inadvertently introduced to the codebase. It also allows
277 the compiler to correctly analyze array sizes (via sizeof(),
278 `CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance,
279 there is no mechanism that warns us that the following application of the
280 sizeof() operator to a zero-length array always results in zero::
287 struct something *instance;
289 instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
290 instance->count = count;
292 size = sizeof(instance->items) * instance->count;
293 memcpy(instance->items, source, size);
295 At the last line of code above, ``size`` turns out to be ``zero``, when one might
296 have thought it represents the total size in bytes of the dynamic memory recently
297 allocated for the trailing array ``items``. Here are a couple examples of this
299 <https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
301 <https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
302 Instead, `flexible array members have incomplete type, and so the sizeof()
303 operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,
304 so any misuse of such operators will be immediately noticed at build time.
306 With respect to one-element arrays, one has to be acutely aware that `such arrays
307 occupy at least as much space as a single object of the type
308 <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,
309 hence they contribute to the size of the enclosing structure. This is prone
310 to error every time people want to calculate the total size of dynamic memory
311 to allocate for a structure containing an array of this kind as a member::
318 struct something *instance;
320 instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
321 instance->count = count;
323 size = sizeof(instance->items) * instance->count;
324 memcpy(instance->items, source, size);
326 In the example above, we had to remember to calculate ``count - 1`` when using
327 the struct_size() helper, otherwise we would have --unintentionally-- allocated
328 memory for one too many ``items`` objects. The cleanest and least error-prone way
329 to implement this is through the use of a `flexible array member`, together with
330 struct_size() and flex_array_size() helpers::
337 struct something *instance;
339 instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
340 instance->count = count;
342 memcpy(instance->items, source, flex_array_size(instance, items, instance->count));