1.. SPDX-License-Identifier: GPL-2.0 2 3.. _deprecated: 4 5===================================================================== 6Deprecated Interfaces, Language Features, Attributes, and Conventions 7===================================================================== 8 9In a perfect world, it would be possible to convert all instances of 10some deprecated API into the new API and entirely remove the old API in 11a single development cycle. However, due to the size of the kernel, the 12maintainership hierarchy, and timing, it's not always feasible to do these 13kinds of conversions at once. This means that new instances may sneak into 14the kernel while old ones are being removed, only making the amount of 15work to remove the API grow. In order to educate developers about what 16has been deprecated and why, this list has been created as a place to 17point when uses of deprecated things are proposed for inclusion in the 18kernel. 19 20__deprecated 21------------ 22While this attribute does visually mark an interface as deprecated, 23it `does not produce warnings during builds any more 24<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ 25because one of the standing goals of the kernel is to build without 26warnings and no one was actually doing anything to remove these deprecated 27interfaces. While using `__deprecated` is nice to note an old API in 28a header file, it isn't the full solution. Such interfaces must either 29be fully removed from the kernel, or added to this file to discourage 30others 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()-family 36of APIs were originally designed to act as an "impossible situation" 37assert and to kill a kernel thread "safely", they turn out to just be 38too risky. (e.g. "In what order do locks need to be released? Have 39various states been restored?") Very commonly, using BUG() will 40destabilize a system or entirely break it, which makes it impossible 41to 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/>`_ 43feelings `about this 44<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 to 47be unreachable" situations. If you want to warn about "reachable 48but undesirable" situations, please use the pr_warn()-family of 49functions. System owners may have set the *panic_on_warn* sysctl, 50to 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>`_.) 53 54open-coded arithmetic in allocator arguments 55-------------------------------------------- 56Dynamic size calculations (especially multiplication) should not be 57performed in memory allocator (or similar) function arguments due to the 58risk of them overflowing. This could lead to values wrapping around and a 59smaller allocation being made than the caller was expecting. Using those 60allocations could lead to linear overflows of heap memory and other 61misbehaviors. (One exception to this is literal values where the compiler 62can warn if they might overflow. Though using literals for arguments as 63suggested below is also harmless.) 64 65For example, do not use ``count * size`` as an argument, as in:: 66 67 foo = kmalloc(count * size, GFP_KERNEL); 68 69Instead, the 2-factor form of the allocator should be used:: 70 71 foo = kmalloc_array(count, size, GFP_KERNEL); 72 73Specifically, kmalloc() can be replaced with kmalloc_array(), and 74kzalloc() can be replaced with kcalloc(). 75 76If no 2-factor form is available, the saturate-on-overflow helpers should 77be used:: 78 79 bar = vmalloc(array_size(count, size)); 80 81Another common case to avoid is calculating the size of a structure with 82a trailing array of others structures, as in:: 83 84 header = kzalloc(sizeof(*header) + count * sizeof(*header->item), 85 GFP_KERNEL); 86 87Instead, use the helper:: 88 89 header = kzalloc(struct_size(header, item, count), GFP_KERNEL); 90 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. 95 96For other calculations, please compose the use of the size_mul(), 97size_add(), and size_sub() helpers. For example, in the case of:: 98 99 foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); 100 101Instead, use the helpers:: 102 103 foo = krealloc(size_add(current_size, 104 size_mul(chunk_size, 105 size_sub(count, 3))), GFP_KERNEL); 106 107For more details, also see array3_size() and flex_array_size(), 108as well as the related check_mul_overflow(), check_add_overflow(), 109check_sub_overflow(), and check_shl_overflow() family of functions. 110 111simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() 112---------------------------------------------------------------------- 113The simple_strtol(), simple_strtoll(), 114simple_strtoul(), and simple_strtoull() functions 115explicitly ignore overflows, which may lead to unexpected results 116in callers. The respective kstrtol(), kstrtoll(), 117kstrtoul(), and kstrtoull() functions tend to be the 118correct replacements, though note that those require the string to be 119NUL or newline terminated. 120 121strcpy() 122-------- 123strcpy() performs no bounds checking on the destination buffer. This 124could result in linear overflows beyond the end of the buffer, leading to 125all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various 126compiler flags help reduce the risk of using this function, there is 127no good reason to add new uses of this function. The safe replacement 128is strscpy(), though care must be given to any cases where the return 129value of strcpy() was used, since strscpy() does not return a pointer to 130the destination, but rather a count of non-NUL bytes copied (or negative 131errno when it truncates). 132 133strncpy() on NUL-terminated strings 134----------------------------------- 135Use of strncpy() does not guarantee that the destination buffer will 136be NUL terminated. This can lead to various linear read overflows and 137other misbehavior due to the missing termination. It also NUL-pads 138the destination buffer if the source contents are shorter than the 139destination buffer size, which may be a needless performance penalty 140for callers using only NUL-terminated strings. The safe replacement is 141strscpy(), though care must be given to any cases where the return value 142of strncpy() was used, since strscpy() does not return a pointer to the 143destination, but rather a count of non-NUL bytes copied (or negative 144errno when it truncates). Any cases still needing NUL-padding should 145instead use strscpy_pad(). 146 147If a caller is using non-NUL-terminated strings, strncpy() can 148still be used, but destinations should be marked with the `__nonstring 149<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ 150attribute to avoid future compiler warnings. 151 152strlcpy() 153--------- 154strlcpy() reads the entire source buffer first (since the return value 155is meant to match that of strlen()). This read may exceed the destination 156size limit. This is both inefficient and can lead to linear read overflows 157if a source string is not NUL-terminated. The safe replacement is strscpy(), 158though care must be given to any cases where the return value of strlcpy() 159is used, since strscpy() will return negative errno values when it truncates. 160 161%p format specifier 162------------------- 163Traditionally, using "%p" in format strings would lead to regular address 164exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to 165be exploitable, all "%p" uses in the kernel are being printed as a hashed 166value, rendering them unusable for addressing. New uses of "%p" should not 167be added to the kernel. For text addresses, using "%pS" is likely better, 168as it produces the more useful symbol name instead. For nearly everything 169else, just do not add "%p" at all. 170 171Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_: 172 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. 180 181And 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/>`_. 182 183Variable Length Arrays (VLAs) 184----------------------------- 185Using stack VLAs produces much worse machine code than statically 186sized stack arrays. While these non-trivial `performance issues 187<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to 188eliminate VLAs, they are also a security risk. Dynamic growth of a stack 189array may exceed the remaining memory in the stack segment. This could 190lead to a crash, possible overwriting sensitive contents at the end of the 191stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting 192memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) 193 194Implicit switch case fall-through 195--------------------------------- 196The C language allows switch cases to fall through to the next case 197when a "break" statement is missing at the end of a case. This, however, 198introduces ambiguity in the code, as it's not always clear if the missing 199break is intentional or a bug. For example, it's not obvious just from 200looking at the code if `STATE_ONE` is intentionally designed to fall 201through into `STATE_TWO`:: 202 203 switch (value) { 204 case STATE_ONE: 205 do_something(); 206 case STATE_TWO: 207 do_other(); 208 break; 209 default: 210 WARN("unknown state"); 211 } 212 213As 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 215implicit fall-through. In order to identify intentional fall-through 216cases, we have adopted a pseudo-keyword macro "fallthrough" which 217expands 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 220C compilers, static analyzers, and IDEs, we can switch to using that syntax 221for the macro pseudo-keyword.) 222 223All switch/case blocks must end in one of: 224 225* break; 226* fallthrough; 227* continue; 228* goto <label>; 229* return [expression]; 230 231Zero-length and one-element arrays 232---------------------------------- 233There is a regular need in the kernel to provide a way to declare having 234a dynamically sized set of trailing elements in a structure. Kernel code 235should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_ 236for these cases. The older style of one-element or zero-length arrays should 237no longer be used. 238 239In older C code, dynamically sized trailing elements were done by specifying 240a one-element array at the end of a structure:: 241 242 struct something { 243 size_t count; 244 struct foo items[1]; 245 }; 246 247This led to fragile size calculations via sizeof() (which would need to 248remove the size of the single trailing element to get a correct size of 249the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ 250was introduced to allow for zero-length arrays, to avoid these kinds of 251size problems:: 252 253 struct something { 254 size_t count; 255 struct foo items[0]; 256 }; 257 258But this led to other problems, and didn't solve some problems shared by 259both styles, like not being able to detect when such an array is accidentally 260being used _not_ at the end of a structure (which could happen directly, or 261when such a struct was in unions, structs of structs, etc). 262 263C99 introduced "flexible array members", which lacks a numeric size for 264the array declaration entirely:: 265 266 struct something { 267 size_t count; 268 struct foo items[]; 269 }; 270 271This is the way the kernel expects dynamically sized trailing elements 272to be declared. It allows the compiler to generate errors when the 273flexible array does not occur last in the structure, which helps to prevent 274some kind of `undefined behavior 275<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ 276bugs from being inadvertently introduced to the codebase. It also allows 277the compiler to correctly analyze array sizes (via sizeof(), 278`CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance, 279there is no mechanism that warns us that the following application of the 280sizeof() operator to a zero-length array always results in zero:: 281 282 struct something { 283 size_t count; 284 struct foo items[0]; 285 }; 286 287 struct something *instance; 288 289 instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); 290 instance->count = count; 291 292 size = sizeof(instance->items) * instance->count; 293 memcpy(instance->items, source, size); 294 295At the last line of code above, ``size`` turns out to be ``zero``, when one might 296have thought it represents the total size in bytes of the dynamic memory recently 297allocated for the trailing array ``items``. Here are a couple examples of this 298issue: `link 1 299<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, 300`link 2 301<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_. 302Instead, `flexible array members have incomplete type, and so the sizeof() 303operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, 304so any misuse of such operators will be immediately noticed at build time. 305 306With respect to one-element arrays, one has to be acutely aware that `such arrays 307occupy at least as much space as a single object of the type 308<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, 309hence they contribute to the size of the enclosing structure. This is prone 310to error every time people want to calculate the total size of dynamic memory 311to allocate for a structure containing an array of this kind as a member:: 312 313 struct something { 314 size_t count; 315 struct foo items[1]; 316 }; 317 318 struct something *instance; 319 320 instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL); 321 instance->count = count; 322 323 size = sizeof(instance->items) * instance->count; 324 memcpy(instance->items, source, size); 325 326In the example above, we had to remember to calculate ``count - 1`` when using 327the struct_size() helper, otherwise we would have --unintentionally-- allocated 328memory for one too many ``items`` objects. The cleanest and least error-prone way 329to implement this is through the use of a `flexible array member`, together with 330struct_size() and flex_array_size() helpers:: 331 332 struct something { 333 size_t count; 334 struct foo items[]; 335 }; 336 337 struct something *instance; 338 339 instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); 340 instance->count = count; 341 342 memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); 343