[PATCH] docs: Introduce deprecated APIs list

From: Kees Cook
Date: Tue Oct 16 2018 - 22:17:14 EST

As discussed in the "API replacement/deprecation" thread[1], this
makes an effort to document what things shouldn't get (re)added to the
kernel, by introducing Documentation/process/deprecated.rst. It also
adds the overflow kerndoc to ReST output, and tweaks the struct_size()
documentation to parse correctly.

[1] https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2018-September/005282.html

Signed-off-by: Kees Cook <keescook@xxxxxxxxxxxx>
Documentation/driver-api/basics.rst | 3 +
Documentation/process/deprecated.rst | 99 ++++++++++++++++++++++++++++
Documentation/process/index.rst | 1 +
include/linux/overflow.h | 2 +-
4 files changed, 104 insertions(+), 1 deletion(-)
create mode 100644 Documentation/process/deprecated.rst

diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 826e85d50a16..e970fadf4d1a 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -121,6 +121,9 @@ Kernel utility functions
.. kernel-doc:: kernel/rcu/update.c

+.. kernel-doc:: include/linux/overflow.h
+ :internal:
Device Resource Management

diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
new file mode 100644
index 000000000000..95e261224a81
--- /dev/null
+++ b/Documentation/process/deprecated.rst
@@ -0,0 +1,99 @@
+.. SPDX-License-Identifier: GPL-2.0
+Deprecated Interfaces, Language Features, Attributes, and Conventions
+In a perfect world, it would be possible to convert all instances of
+some deprecated API into the new API and entirely remove the old API in
+a single development cycle. However, due to the size of the kernel, the
+maintainership hierarchy, and timing, it's not always feasible to do these
+kinds of conversions at once. This means that new instances may sneak into
+the kernel while old ones are being removed, only making the amount of
+work to remove the API grow. In order to educate developers about what
+has been deprecated and why, this list has been created as a place to
+point when uses of deprecated things are proposed for inclusion in the
+While this attribute does visually mark an interface as deprecated,
+it `does not produce warnings during builds any more
+because one of the standing goals of the kernel is to build without
+warnings and no one was actually doing anything to remove these deprecated
+interfaces. While using `__deprecated` is nice to note an old API in
+a header file, it isn't the full solution. Such interfaces must either
+be fully removed from the kernel, or added to this file to discourage
+others from using them in the future.
+open-coded arithmetic in allocator arguments
+Dynamic size calculations (especially multiplication)
+should not be performed in memory allocator (or similar)
+function arguments.
+For example, do not use ``rows * cols`` as an argument, as in:
+``kmalloc(rows * cols, GFP_KERNEL)``.
+Instead, the 2-factor form of the allocator should be used:
+``kmalloc_array(rows, cols, GFP_KERNEL)``.
+If no 2-factor form is available, the saturate-on-overflow helpers should
+be used:
+``vmalloc(array_size(rows, cols))``.
+See :c:func:`array_size`, :c:func:`array3_size`, and :c:func:`struct_size`,
+for more details as well as the related :c:func:`check_add_overflow` and
+:c:func:`check_mul_overflow` family of functions.
+simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
+The :c:func:`simple_strtol`, :c:func:`simple_strtoll`,
+:c:func:`simple_strtoul`, and :c:func:`simple_strtoull` functions
+explicitly ignore overflows, which may lead to unexpected results
+in callers. The respective :c:func:`kstrtol`, :c:func:`kstrtoll`,
+:c:func:`kstrtoul`, and :c:func:`kstrtoull` functions tend to be the
+correct replacements, though note that those require the string to be
+NUL or newline terminated.
+:c:func:`strcpy` performs no bounds checking on the destination
+buffer. This could result in linear overflows beyond the
+end of the buffer, leading to all kinds of misbehaviors. While
+`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the
+risk of using this function, there is no good reason to add new uses of
+this function. The safe replacement is :c:func:`strscpy`.
+strncpy() on NUL-terminated strings
+Use of :c:func:`strncpy` does not guarantee that the destination buffer
+will be NUL terminated. This can lead to various linear read overflows
+and other misbehavior due to the missing termination. It also NUL-pads the
+destination buffer if the source contents are shorter than the destination
+buffer size, which may be a needless performance penalty for callers using
+only NUL-terminated strings. The safe replacement is :c:func:`strscpy`.
+(Users of :c:func:`strscpy` still needing NUL-padding will need an
+explicit :c:func:`memset` added.)
+If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can
+still be used, but destinations should be marked with the `__nonstring
+attribute to avoid future compiler warnings.
+:c:func:`strlcpy` reads the entire source buffer first, possibly exceeding
+the given limit of bytes to copy. This is inefficient and can lead to
+linear read overflows if a source string is not NUL-terminated. The
+safe replacement is :c:func:`strscpy`.
+Variable Length Arrays (VLAs)
+Using stack VLAs produces much worse machine code than statically
+sized stack arrays. While these non-trivial `performance issues
+<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to
+eliminate VLAs, they are also a security risk. Dynamic growth of a stack
+array may exceed the remaining memory in the stack segment. This could
+lead to a crash, possible overwriting sensitive contents at the end of the
+stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting
+memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 9ae3e317bddf..b4de2c682255 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -41,6 +41,7 @@ Other guides to the community that are of interest to most developers are:
+ deprecated

These are some overall technical guides that have been put here for now for
lack of a better place.
diff --git a/include/linux/overflow.h b/include/linux/overflow.h
index 40b48e2133cb..2f224f43dd06 100644
--- a/include/linux/overflow.h
+++ b/include/linux/overflow.h
@@ -291,7 +291,7 @@ static inline __must_check size_t __ab_c_size(size_t n, size_t size, size_t c)

- * struct_size() - Calculate size of structure with trailing array.
+ * function struct_size() - Calculate size of structure with trailing array.
* @p: Pointer to the structure.
* @member: Name of the array member.
* @n: Number of elements in the array.

Kees Cook
Pixel Security