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