From ea2ae0ecc9ad8c47ca25837823cc25679a1e4d1a Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 4 Sep 2018 17:02:24 -0700 Subject: FireWire: add a Documentation driver-api chapter Add a basic Firewire/IEEE 1394 driver API chapter to the Linux kernel documentation. Signed-off-by: Randy Dunlap Cc: Stefan Richter Cc: Takashi Sakamoto Cc: linux-doc@vger.kernel.org Cc: linux-scsi@vger.kernel.org Cc: Randy Dunlap Cc: Andrew Morton Cc: "James E.J. Bottomley" Cc: "Martin K. Petersen" Cc: Jonathan Corbet Signed-off-by: Jonathan Corbet --- Documentation/driver-api/firewire.rst | 33 +++++++++++++++++++++++++++++++++ Documentation/driver-api/index.rst | 1 + 2 files changed, 34 insertions(+) create mode 100644 Documentation/driver-api/firewire.rst (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst new file mode 100644 index 000000000000..31f0b292bb75 --- /dev/null +++ b/Documentation/driver-api/firewire.rst @@ -0,0 +1,33 @@ +=========================================== +Firewire (IEEE 1394) driver Interface Guide +=========================================== + +Introduction and Overview +========================= + +TBD + +Firewire char device data structures +==================================== + +.. kernel-doc:: include/uapi/linux/firewire-cdev.h + :internal: + +Firewire device probing and sysfs interfaces +============================================ + +.. kernel-doc:: drivers/firewire/core-device.c + :export: + +Firewire core transaction interfaces +==================================== + +.. kernel-doc:: drivers/firewire/core-transaction.c + :export: + +Firewire Isochronous I/O interfaces +=================================== + +.. kernel-doc:: drivers/firewire/core-iso.c + :export: + diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6d9f2f9fe20e..1f0cdba2b2bf 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -29,6 +29,7 @@ available subsections can be seen below. iio/index input usb/index + firewire pci spi i2c -- cgit v1.2.3 From 2f4830ef96d21e144b742c394eb12888b0e233cc Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Tue, 4 Sep 2018 17:02:25 -0700 Subject: FireWire: add driver-api Introduction section Replace the Introduction section's TBD with some useful overview text. Signed-off-by: Takashi Sakamoto Acked-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Randy Dunlap Cc: Stefan Richter Cc: Takashi Sakamoto Cc: linux-doc@vger.kernel.org Cc: linux-scsi@vger.kernel.org Cc: Randy Dunlap Cc: Andrew Morton Cc: "James E.J. Bottomley" Cc: "Martin K. Petersen" Cc: Jonathan Corbet Signed-off-by: Jonathan Corbet --- Documentation/driver-api/firewire.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst index 31f0b292bb75..94a2d7f01d99 100644 --- a/Documentation/driver-api/firewire.rst +++ b/Documentation/driver-api/firewire.rst @@ -5,17 +5,32 @@ Firewire (IEEE 1394) driver Interface Guide Introduction and Overview ========================= -TBD +The Linux FireWire subsystem adds some interfaces into the Linux system to + use/maintain+any resource on IEEE 1394 bus. + +The main purpose of these interfaces is to access address space on each node +on IEEE 1394 bus by ISO/IEC 13213 (IEEE 1212) procedure, and to control +isochronous resources on the bus by IEEE 1394 procedure. + +Two types of interfaces are added, according to consumers of the interface. A +set of userspace interfaces is available via `firewire character devices`. A set +of kernel interfaces is available via exported symbols in `firewire-core` module. Firewire char device data structures ==================================== +.. include:: /ABI/stable/firewire-cdev + :literal: + .. kernel-doc:: include/uapi/linux/firewire-cdev.h :internal: Firewire device probing and sysfs interfaces ============================================ +.. include:: /ABI/stable/sysfs-bus-firewire + :literal: + .. kernel-doc:: drivers/firewire/core-device.c :export: -- cgit v1.2.3 From 84253c8be37d5f0b54d624be1bd1b90bbbfe14b3 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Wed, 17 Oct 2018 16:45:32 -0700 Subject: docs: Introduce deprecated APIs list 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. [1] https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2018-September/005282.html Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/driver-api/basics.rst | 3 + Documentation/process/deprecated.rst | 119 +++++++++++++++++++++++++++++++++++ Documentation/process/index.rst | 1 + 3 files changed, 123 insertions(+) create mode 100644 Documentation/process/deprecated.rst (limited to 'Documentation/driver-api') 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 :export: +.. 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..0ef5a63c06ba --- /dev/null +++ b/Documentation/process/deprecated.rst @@ -0,0 +1,119 @@ +.. 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 +kernel. + +__deprecated +------------ +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 due to the +risk of them overflowing. This could lead to values wrapping around and a +smaller allocation being made than the caller was expecting. Using those +allocations could lead to linear overflows of heap memory and other +misbehaviors. (One exception to this is literal values where the compiler +can warn if they might overflow. Though using literals for arguments as +suggested below is also harmless.) + +For example, do not use ``count * size`` as an argument, as in:: + + foo = kmalloc(count * size, GFP_KERNEL); + +Instead, the 2-factor form of the allocator should be used:: + + foo = kmalloc_array(count, size, GFP_KERNEL); + +If no 2-factor form is available, the saturate-on-overflow helpers should +be used:: + + bar = vmalloc(array_size(count, size)); + +Another common case to avoid is calculating the size of a structure with +a trailing array of others structures, as in:: + + header = kzalloc(sizeof(*header) + count * sizeof(*header->item), + GFP_KERNEL); + +Instead, use the helper:: + + header = kzalloc(struct_size(header, item, count), GFP_KERNEL); + +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. + +strcpy() +-------- +: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. + +strlcpy() +--------- +: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 +`_ 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 c0b3bd25dbae..1ddde440f333 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -42,6 +42,7 @@ Other guides to the community that are of interest to most developers are: stable-kernel-rules submit-checklist kernel-docs + deprecated These are some overall technical guides that have been put here for now for lack of a better place. -- cgit v1.2.3