375 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3.. _deprecated:4 5=====================================================================6Deprecated Interfaces, Language Features, Attributes, and Conventions7=====================================================================8 9In a perfect world, it would be possible to convert all instances of10some deprecated API into the new API and entirely remove the old API in11a single development cycle. However, due to the size of the kernel, the12maintainership hierarchy, and timing, it's not always feasible to do these13kinds of conversions at once. This means that new instances may sneak into14the kernel while old ones are being removed, only making the amount of15work to remove the API grow. In order to educate developers about what16has been deprecated and why, this list has been created as a place to17point when uses of deprecated things are proposed for inclusion in the18kernel.19 20__deprecated21------------22While this attribute does visually mark an interface as deprecated,23it `does not produce warnings during builds any more24<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_25because one of the standing goals of the kernel is to build without26warnings and no one was actually doing anything to remove these deprecated27interfaces. While using `__deprecated` is nice to note an old API in28a header file, it isn't the full solution. Such interfaces must either29be fully removed from the kernel, or added to this file to discourage30others from using them in the future.31 32BUG() and BUG_ON()33------------------34Use WARN() and WARN_ON() instead, and handle the "impossible"35error condition as gracefully as possible. While the BUG()-family36of APIs were originally designed to act as an "impossible situation"37assert and to kill a kernel thread "safely", they turn out to just be38too risky. (e.g. "In what order do locks need to be released? Have39various states been restored?") Very commonly, using BUG() will40destabilize a system or entirely break it, which makes it impossible41to debug or even get viable crash reports. Linus has `very strong42<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_43feelings `about this44<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_.45 46Note that the WARN()-family should only be used for "expected to47be unreachable" situations. If you want to warn about "reachable48but undesirable" situations, please use the pr_warn()-family of49functions. System owners may have set the *panic_on_warn* sysctl,50to make sure their systems do not continue running in the face of51"unreachable" conditions. (For example, see commits like `this one52<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)53 54open-coded arithmetic in allocator arguments55--------------------------------------------56Dynamic size calculations (especially multiplication) should not be57performed in memory allocator (or similar) function arguments due to the58risk of them overflowing. This could lead to values wrapping around and a59smaller allocation being made than the caller was expecting. Using those60allocations could lead to linear overflows of heap memory and other61misbehaviors. (One exception to this is literal values where the compiler62can warn if they might overflow. However, the preferred way in these63cases is to refactor the code as suggested below to avoid the open-coded64arithmetic.)65 66For example, do not use ``count * size`` as an argument, as in::67 68 foo = kmalloc(count * size, GFP_KERNEL);69 70Instead, the 2-factor form of the allocator should be used::71 72 foo = kmalloc_array(count, size, GFP_KERNEL);73 74Specifically, kmalloc() can be replaced with kmalloc_array(), and75kzalloc() can be replaced with kcalloc().76 77If no 2-factor form is available, the saturate-on-overflow helpers should78be used::79 80 bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL);81 82Another common case to avoid is calculating the size of a structure with83a trailing array of others structures, as in::84 85 header = kzalloc(sizeof(*header) + count * sizeof(*header->item),86 GFP_KERNEL);87 88Instead, use the helper::89 90 header = kzalloc(struct_size(header, item, count), GFP_KERNEL);91 92.. note:: If you are using struct_size() on a structure containing a zero-length93 or a one-element array as a trailing array member, please refactor such94 array usage and switch to a `flexible array member95 <#zero-length-and-one-element-arrays>`_ instead.96 97For other calculations, please compose the use of the size_mul(),98size_add(), and size_sub() helpers. For example, in the case of::99 100 foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);101 102Instead, use the helpers::103 104 foo = krealloc(size_add(current_size,105 size_mul(chunk_size,106 size_sub(count, 3))), GFP_KERNEL);107 108For more details, also see array3_size() and flex_array_size(),109as well as the related check_mul_overflow(), check_add_overflow(),110check_sub_overflow(), and check_shl_overflow() family of functions.111 112simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()113----------------------------------------------------------------------114The simple_strtol(), simple_strtoll(),115simple_strtoul(), and simple_strtoull() functions116explicitly ignore overflows, which may lead to unexpected results117in callers. The respective kstrtol(), kstrtoll(),118kstrtoul(), and kstrtoull() functions tend to be the119correct replacements, though note that those require the string to be120NUL or newline terminated.121 122strcpy()123--------124strcpy() performs no bounds checking on the destination buffer. This125could result in linear overflows beyond the end of the buffer, leading to126all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various127compiler flags help reduce the risk of using this function, there is128no good reason to add new uses of this function. The safe replacement129is strscpy(), though care must be given to any cases where the return130value of strcpy() was used, since strscpy() does not return a pointer to131the destination, but rather a count of non-NUL bytes copied (or negative132errno when it truncates).133 134strncpy() on NUL-terminated strings135-----------------------------------136Use of strncpy() does not guarantee that the destination buffer will137be NUL terminated. This can lead to various linear read overflows and138other misbehavior due to the missing termination. It also NUL-pads139the destination buffer if the source contents are shorter than the140destination buffer size, which may be a needless performance penalty141for callers using only NUL-terminated strings.142 143When the destination is required to be NUL-terminated, the replacement is144strscpy(), though care must be given to any cases where the return value145of strncpy() was used, since strscpy() does not return a pointer to the146destination, but rather a count of non-NUL bytes copied (or negative147errno when it truncates). Any cases still needing NUL-padding should148instead use strscpy_pad().149 150If a caller is using non-NUL-terminated strings, strtomem() should be151used, and the destinations should be marked with the `__nonstring152<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_153attribute to avoid future compiler warnings. For cases still needing154NUL-padding, strtomem_pad() can be used.155 156strlcpy()157---------158strlcpy() reads the entire source buffer first (since the return value159is meant to match that of strlen()). This read may exceed the destination160size limit. This is both inefficient and can lead to linear read overflows161if a source string is not NUL-terminated. The safe replacement is strscpy(),162though care must be given to any cases where the return value of strlcpy()163is used, since strscpy() will return negative errno values when it truncates.164 165%p format specifier166-------------------167Traditionally, using "%p" in format strings would lead to regular address168exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to169be exploitable, all "%p" uses in the kernel are being printed as a hashed170value, rendering them unusable for addressing. New uses of "%p" should not171be added to the kernel. For text addresses, using "%pS" is likely better,172as it produces the more useful symbol name instead. For nearly everything173else, just do not add "%p" at all.174 175Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_:176 177- If the hashed "%p" value is pointless, ask yourself whether the pointer178 itself is important. Maybe it should be removed entirely?179- If you really think the true pointer value is important, why is some180 system state or user privilege level considered "special"? If you think181 you can justify it (in comments and commit log) well enough to stand182 up to Linus's scrutiny, maybe you can use "%px", along with making sure183 you have sensible permissions.184 185If you are debugging something where "%p" hashing is causing problems,186you can temporarily boot with the debug flag "`no_hash_pointers187<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_".188 189Variable Length Arrays (VLAs)190-----------------------------191Using stack VLAs produces much worse machine code than statically192sized stack arrays. While these non-trivial `performance issues193<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to194eliminate VLAs, they are also a security risk. Dynamic growth of a stack195array may exceed the remaining memory in the stack segment. This could196lead to a crash, possible overwriting sensitive contents at the end of the197stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting198memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)199 200Implicit switch case fall-through201---------------------------------202The C language allows switch cases to fall through to the next case203when a "break" statement is missing at the end of a case. This, however,204introduces ambiguity in the code, as it's not always clear if the missing205break is intentional or a bug. For example, it's not obvious just from206looking at the code if `STATE_ONE` is intentionally designed to fall207through into `STATE_TWO`::208 209 switch (value) {210 case STATE_ONE:211 do_something();212 case STATE_TWO:213 do_other();214 break;215 default:216 WARN("unknown state");217 }218 219As there have been a long list of flaws `due to missing "break" statements220<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow221implicit fall-through. In order to identify intentional fall-through222cases, we have adopted a pseudo-keyword macro "fallthrough" which223expands to gcc's extension `__attribute__((__fallthrough__))224<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_.225(When the C17/C18 `[[fallthrough]]` syntax is more commonly supported by226C compilers, static analyzers, and IDEs, we can switch to using that syntax227for the macro pseudo-keyword.)228 229All switch/case blocks must end in one of:230 231* break;232* fallthrough;233* continue;234* goto <label>;235* return [expression];236 237Zero-length and one-element arrays238----------------------------------239There is a regular need in the kernel to provide a way to declare having240a dynamically sized set of trailing elements in a structure. Kernel code241should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_242for these cases. The older style of one-element or zero-length arrays should243no longer be used.244 245In older C code, dynamically sized trailing elements were done by specifying246a one-element array at the end of a structure::247 248 struct something {249 size_t count;250 struct foo items[1];251 };252 253This led to fragile size calculations via sizeof() (which would need to254remove the size of the single trailing element to get a correct size of255the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_256was introduced to allow for zero-length arrays, to avoid these kinds of257size problems::258 259 struct something {260 size_t count;261 struct foo items[0];262 };263 264But this led to other problems, and didn't solve some problems shared by265both styles, like not being able to detect when such an array is accidentally266being used _not_ at the end of a structure (which could happen directly, or267when such a struct was in unions, structs of structs, etc).268 269C99 introduced "flexible array members", which lacks a numeric size for270the array declaration entirely::271 272 struct something {273 size_t count;274 struct foo items[];275 };276 277This is the way the kernel expects dynamically sized trailing elements278to be declared. It allows the compiler to generate errors when the279flexible array does not occur last in the structure, which helps to prevent280some kind of `undefined behavior281<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_282bugs from being inadvertently introduced to the codebase. It also allows283the compiler to correctly analyze array sizes (via sizeof(),284`CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance,285there is no mechanism that warns us that the following application of the286sizeof() operator to a zero-length array always results in zero::287 288 struct something {289 size_t count;290 struct foo items[0];291 };292 293 struct something *instance;294 295 instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);296 instance->count = count;297 298 size = sizeof(instance->items) * instance->count;299 memcpy(instance->items, source, size);300 301At the last line of code above, ``size`` turns out to be ``zero``, when one might302have thought it represents the total size in bytes of the dynamic memory recently303allocated for the trailing array ``items``. Here are a couple examples of this304issue: `link 1305<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,306`link 2307<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.308Instead, `flexible array members have incomplete type, and so the sizeof()309operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,310so any misuse of such operators will be immediately noticed at build time.311 312With respect to one-element arrays, one has to be acutely aware that `such arrays313occupy at least as much space as a single object of the type314<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,315hence they contribute to the size of the enclosing structure. This is prone316to error every time people want to calculate the total size of dynamic memory317to allocate for a structure containing an array of this kind as a member::318 319 struct something {320 size_t count;321 struct foo items[1];322 };323 324 struct something *instance;325 326 instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);327 instance->count = count;328 329 size = sizeof(instance->items) * instance->count;330 memcpy(instance->items, source, size);331 332In the example above, we had to remember to calculate ``count - 1`` when using333the struct_size() helper, otherwise we would have --unintentionally-- allocated334memory for one too many ``items`` objects. The cleanest and least error-prone way335to implement this is through the use of a `flexible array member`, together with336struct_size() and flex_array_size() helpers::337 338 struct something {339 size_t count;340 struct foo items[];341 };342 343 struct something *instance;344 345 instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);346 instance->count = count;347 348 memcpy(instance->items, source, flex_array_size(instance, items, instance->count));349 350There are two special cases of replacement where the DECLARE_FLEX_ARRAY()351helper needs to be used. (Note that it is named __DECLARE_FLEX_ARRAY() for352use in UAPI headers.) Those cases are when the flexible array is either353alone in a struct or is part of a union. These are disallowed by the C99354specification, but for no technical reason (as can be seen by both the355existing use of such arrays in those places and the work-around that356DECLARE_FLEX_ARRAY() uses). For example, to convert this::357 358 struct something {359 ...360 union {361 struct type1 one[0];362 struct type2 two[0];363 };364 };365 366The helper must be used::367 368 struct something {369 ...370 union {371 DECLARE_FLEX_ARRAY(struct type1, one);372 DECLARE_FLEX_ARRAY(struct type2, two);373 };374 };375