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. However, the preferred way in these 63cases is to refactor the code as suggested below to avoid the open-coded 64arithmetic.) 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(), and 75kzalloc() can be replaced with kcalloc(). 76 77If no 2-factor form is available, the saturate-on-overflow helpers should 78be 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 with 83a 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-length 93 or a one-element array as a trailing array member, please refactor such 94 array usage and switch to a `flexible array member 95 <#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() functions 116explicitly ignore overflows, which may lead to unexpected results 117in callers. The respective kstrtol(), kstrtoll(), 118kstrtoul(), and kstrtoull() functions tend to be the 119correct replacements, though note that those require the string to be 120NUL or newline terminated. 121 122strcpy() 123-------- 124strcpy() performs no bounds checking on the destination buffer. This 125could result in linear overflows beyond the end of the buffer, leading to 126all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various 127compiler flags help reduce the risk of using this function, there is 128no good reason to add new uses of this function. The safe replacement 129is strscpy(), though care must be given to any cases where the return 130value of strcpy() was used, since strscpy() does not return a pointer to 131the destination, but rather a count of non-NUL bytes copied (or negative 132errno when it truncates). 133 134strncpy() on NUL-terminated strings 135----------------------------------- 136Use of strncpy() does not guarantee that the destination buffer will 137be NUL terminated. This can lead to various linear read overflows and 138other misbehavior due to the missing termination. It also NUL-pads 139the destination buffer if the source contents are shorter than the 140destination buffer size, which may be a needless performance penalty 141for callers using only NUL-terminated strings. 142 143When the destination is required to be NUL-terminated, the replacement is 144strscpy(), though care must be given to any cases where the return value 145of strncpy() was used, since strscpy() does not return a pointer to the 146destination, but rather a count of non-NUL bytes copied (or negative 147errno when it truncates). Any cases still needing NUL-padding should 148instead use strscpy_pad(). 149 150If a caller is using non-NUL-terminated strings, strtomem() should be 151used, and the destinations should be marked with the `__nonstring 152<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ 153attribute to avoid future compiler warnings. For cases still needing 154NUL-padding, strtomem_pad() can be used. 155 156strlcpy() 157--------- 158strlcpy() reads the entire source buffer first (since the return value 159is meant to match that of strlen()). This read may exceed the destination 160size limit. This is both inefficient and can lead to linear read overflows 161if 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 specifier 166------------------- 167Traditionally, using "%p" in format strings would lead to regular address 168exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to 169be exploitable, all "%p" uses in the kernel are being printed as a hashed 170value, rendering them unusable for addressing. New uses of "%p" should not 171be added to the kernel. For text addresses, using "%pS" is likely better, 172as it produces the more useful symbol name instead. For nearly everything 173else, 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 pointer 178 itself is important. Maybe it should be removed entirely? 179- If you really think the true pointer value is important, why is some 180 system state or user privilege level considered "special"? If you think 181 you can justify it (in comments and commit log) well enough to stand 182 up to Linus's scrutiny, maybe you can use "%px", along with making sure 183 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_pointers 187<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_". 188 189Variable Length Arrays (VLAs) 190----------------------------- 191Using stack VLAs produces much worse machine code than statically 192sized stack arrays. While these non-trivial `performance issues 193<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to 194eliminate VLAs, they are also a security risk. Dynamic growth of a stack 195array may exceed the remaining memory in the stack segment. This could 196lead to a crash, possible overwriting sensitive contents at the end of the 197stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting 198memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) 199 200Implicit switch case fall-through 201--------------------------------- 202The C language allows switch cases to fall through to the next case 203when 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 missing 205break is intentional or a bug. For example, it's not obvious just from 206looking at the code if `STATE_ONE` is intentionally designed to fall 207through 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" statements 220<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow 221implicit fall-through. In order to identify intentional fall-through 222cases, we have adopted a pseudo-keyword macro "fallthrough" which 223expands 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 by 226C compilers, static analyzers, and IDEs, we can switch to using that syntax 227for 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 arrays 238---------------------------------- 239There is a regular need in the kernel to provide a way to declare having 240a dynamically sized set of trailing elements in a structure. Kernel code 241should 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 should 243no longer be used. 244 245In older C code, dynamically sized trailing elements were done by specifying 246a 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 to 254remove the size of the single trailing element to get a correct size of 255the "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 of 257size 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 by 265both styles, like not being able to detect when such an array is accidentally 266being used _not_ at the end of a structure (which could happen directly, or 267when such a struct was in unions, structs of structs, etc). 268 269C99 introduced "flexible array members", which lacks a numeric size for 270the 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 elements 278to be declared. It allows the compiler to generate errors when the 279flexible array does not occur last in the structure, which helps to prevent 280some kind of `undefined behavior 281<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ 282bugs from being inadvertently introduced to the codebase. It also allows 283the 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 the 286sizeof() 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 might 302have thought it represents the total size in bytes of the dynamic memory recently 303allocated for the trailing array ``items``. Here are a couple examples of this 304issue: `link 1 305<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, 306`link 2 307<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 arrays 313occupy at least as much space as a single object of the type 314<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, 315hence they contribute to the size of the enclosing structure. This is prone 316to error every time people want to calculate the total size of dynamic memory 317to 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 using 333the struct_size() helper, otherwise we would have --unintentionally-- allocated 334memory for one too many ``items`` objects. The cleanest and least error-prone way 335to implement this is through the use of a `flexible array member`, together with 336struct_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() for 352use in UAPI headers.) Those cases are when the flexible array is either 353alone in a struct or is part of a union. These are disallowed by the C99 354specification, but for no technical reason (as can be seen by both the 355existing use of such arrays in those places and the work-around that 356DECLARE_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