From 1733ec77d34059cd67a7b9677fe2fd3ef977afb3 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Fri, 14 Feb 2020 18:41:32 +0100 Subject: docs: driver-api: edid: Fix list formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Without the empty lines, Sphinx renders the list as part of the running text. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/driver-api/edid.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/edid.rst b/Documentation/driver-api/edid.rst index b1b5acd501ed..7dc07942ceb2 100644 --- a/Documentation/driver-api/edid.rst +++ b/Documentation/driver-api/edid.rst @@ -11,11 +11,13 @@ Today, with the advent of Kernel Mode Setting, a graphics board is either correctly working because all components follow the standards - or the computer is unusable, because the screen remains dark after booting or it displays the wrong area. Cases when this happens are: + - The graphics board does not recognize the monitor. - The graphics board is unable to detect any EDID data. - The graphics board incorrectly forwards EDID data to the driver. - The monitor sends no or bogus EDID data. - A KVM sends its own EDID data instead of querying the connected monitor. + Adding the kernel parameter "nomodeset" helps in most cases, but causes restrictions later on. -- cgit v1.2.3 From 320bfd91a985f2b945bad611c43add8a3a359845 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Fri, 14 Feb 2020 18:41:33 +0100 Subject: docs: admin-guide: Move edid.rst from driver-api MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This document describes actions that an admin can do, rather than interfaces available to driver developers, so admin-guide seems to be a more appropriate place for it. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/edid.rst | 60 +++++++++++++++++++++++++++++++++++++ Documentation/admin-guide/index.rst | 1 + Documentation/driver-api/edid.rst | 60 ------------------------------------- Documentation/driver-api/index.rst | 1 - 4 files changed, 61 insertions(+), 61 deletions(-) create mode 100644 Documentation/admin-guide/edid.rst delete mode 100644 Documentation/driver-api/edid.rst (limited to 'Documentation/driver-api') diff --git a/Documentation/admin-guide/edid.rst b/Documentation/admin-guide/edid.rst new file mode 100644 index 000000000000..7dc07942ceb2 --- /dev/null +++ b/Documentation/admin-guide/edid.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +EDID +==== + +In the good old days when graphics parameters were configured explicitly +in a file called xorg.conf, even broken hardware could be managed. + +Today, with the advent of Kernel Mode Setting, a graphics board is +either correctly working because all components follow the standards - +or the computer is unusable, because the screen remains dark after +booting or it displays the wrong area. Cases when this happens are: + +- The graphics board does not recognize the monitor. +- The graphics board is unable to detect any EDID data. +- The graphics board incorrectly forwards EDID data to the driver. +- The monitor sends no or bogus EDID data. +- A KVM sends its own EDID data instead of querying the connected monitor. + +Adding the kernel parameter "nomodeset" helps in most cases, but causes +restrictions later on. + +As a remedy for such situations, the kernel configuration item +CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an +individually prepared or corrected EDID data set in the /lib/firmware +directory from where it is loaded via the firmware interface. The code +(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for +commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200, +1680x1050, 1920x1080) as binary blobs, but the kernel source tree does +not contain code to create these data. In order to elucidate the origin +of the built-in binary EDID blobs and to facilitate the creation of +individual data for a specific misbehaving monitor, commented sources +and a Makefile environment are given here. + +To create binary EDID and C source code files from the existing data +material, simply type "make". + +If you want to create your own EDID file, copy the file 1024x768.S, +replace the settings with your own data and add a new target to the +Makefile. Please note that the EDID data structure expects the timing +values in a different way as compared to the standard X11 format. + +X11: + HTimings: + hdisp hsyncstart hsyncend htotal + VTimings: + vdisp vsyncstart vsyncend vtotal + +EDID:: + + #define XPIX hdisp + #define XBLANK htotal-hdisp + #define XOFFSET hsyncstart-hdisp + #define XPULSE hsyncend-hsyncstart + + #define YPIX vdisp + #define YBLANK vtotal-vdisp + #define YOFFSET vsyncstart-vdisp + #define YPULSE vsyncend-vsyncstart diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index f1d0ccffbe72..5a6269fb8593 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -75,6 +75,7 @@ configure specific aspects of kernel behavior to your liking. cputopology dell_rbu device-mapper/index + edid efi-stub ext4 nfs/index diff --git a/Documentation/driver-api/edid.rst b/Documentation/driver-api/edid.rst deleted file mode 100644 index 7dc07942ceb2..000000000000 --- a/Documentation/driver-api/edid.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -==== -EDID -==== - -In the good old days when graphics parameters were configured explicitly -in a file called xorg.conf, even broken hardware could be managed. - -Today, with the advent of Kernel Mode Setting, a graphics board is -either correctly working because all components follow the standards - -or the computer is unusable, because the screen remains dark after -booting or it displays the wrong area. Cases when this happens are: - -- The graphics board does not recognize the monitor. -- The graphics board is unable to detect any EDID data. -- The graphics board incorrectly forwards EDID data to the driver. -- The monitor sends no or bogus EDID data. -- A KVM sends its own EDID data instead of querying the connected monitor. - -Adding the kernel parameter "nomodeset" helps in most cases, but causes -restrictions later on. - -As a remedy for such situations, the kernel configuration item -CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an -individually prepared or corrected EDID data set in the /lib/firmware -directory from where it is loaded via the firmware interface. The code -(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for -commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200, -1680x1050, 1920x1080) as binary blobs, but the kernel source tree does -not contain code to create these data. In order to elucidate the origin -of the built-in binary EDID blobs and to facilitate the creation of -individual data for a specific misbehaving monitor, commented sources -and a Makefile environment are given here. - -To create binary EDID and C source code files from the existing data -material, simply type "make". - -If you want to create your own EDID file, copy the file 1024x768.S, -replace the settings with your own data and add a new target to the -Makefile. Please note that the EDID data structure expects the timing -values in a different way as compared to the standard X11 format. - -X11: - HTimings: - hdisp hsyncstart hsyncend htotal - VTimings: - vdisp vsyncstart vsyncend vtotal - -EDID:: - - #define XPIX hdisp - #define XBLANK htotal-hdisp - #define XOFFSET hsyncstart-hdisp - #define XPULSE hsyncend-hsyncstart - - #define YPIX vdisp - #define YBLANK vtotal-vdisp - #define YOFFSET vsyncstart-vdisp - #define YPULSE vsyncend-vsyncstart diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 0ebe205efd0c..ea3003b3c5e5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -74,7 +74,6 @@ available subsections can be seen below. connector console dcdbas - edid eisa ipmb isa -- cgit v1.2.3 From 6505a18e66876e0f502dcba5a563bd3048094048 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 2 Mar 2020 15:26:38 -0700 Subject: docs: move core-api/ioctl.rst to driver-api/ The ioctl() documentation belongs with the rest of the driver-oriented info, so move it there. Signed-off-by: Jonathan Corbet --- Documentation/core-api/index.rst | 1 - Documentation/core-api/ioctl.rst | 253 ------------------------------------- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/ioctl.rst | 253 +++++++++++++++++++++++++++++++++++++ 4 files changed, 254 insertions(+), 254 deletions(-) delete mode 100644 Documentation/core-api/ioctl.rst create mode 100644 Documentation/driver-api/ioctl.rst (limited to 'Documentation/driver-api') diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 9836a0ac09a3..0897ad12c119 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -102,7 +102,6 @@ Documents that don't fit elsewhere or which have yet to be categorized. :maxdepth: 1 librs - ioctl .. only:: subproject and html diff --git a/Documentation/core-api/ioctl.rst b/Documentation/core-api/ioctl.rst deleted file mode 100644 index c455db0e1627..000000000000 --- a/Documentation/core-api/ioctl.rst +++ /dev/null @@ -1,253 +0,0 @@ -====================== -ioctl based interfaces -====================== - -ioctl() is the most common way for applications to interface -with device drivers. It is flexible and easily extended by adding new -commands and can be passed through character devices, block devices as -well as sockets and other special file descriptors. - -However, it is also very easy to get ioctl command definitions wrong, -and hard to fix them later without breaking existing applications, -so this documentation tries to help developers get it right. - -Command number definitions -========================== - -The command number, or request number, is the second argument passed to -the ioctl system call. While this can be any 32-bit number that uniquely -identifies an action for a particular driver, there are a number of -conventions around defining them. - -``include/uapi/asm-generic/ioctl.h`` provides four macros for defining -ioctl commands that follow modern conventions: ``_IO``, ``_IOR``, -``_IOW``, and ``_IOWR``. These should be used for all new commands, -with the correct parameters: - -_IO/_IOR/_IOW/_IOWR - The macro name specifies how the argument will be used.  It may be a - pointer to data to be passed into the kernel (_IOW), out of the kernel - (_IOR), or both (_IOWR).  _IO can indicate either commands with no - argument or those passing an integer value instead of a pointer. - It is recommended to only use _IO for commands without arguments, - and use pointers for passing data. - -type - An 8-bit number, often a character literal, specific to a subsystem - or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number` - -nr - An 8-bit number identifying the specific command, unique for a give - value of 'type' - -data_type - The name of the data type pointed to by the argument, the command number - encodes the ``sizeof(data_type)`` value in a 13-bit or 14-bit integer, - leading to a limit of 8191 bytes for the maximum size of the argument. - Note: do not pass sizeof(data_type) type into _IOR/_IOW/IOWR, as that - will lead to encoding sizeof(sizeof(data_type)), i.e. sizeof(size_t). - _IO does not have a data_type parameter. - - -Interface versions -================== - -Some subsystems use version numbers in data structures to overload -commands with different interpretations of the argument. - -This is generally a bad idea, since changes to existing commands tend -to break existing applications. - -A better approach is to add a new ioctl command with a new number. The -old command still needs to be implemented in the kernel for compatibility, -but this can be a wrapper around the new implementation. - -Return code -=========== - -ioctl commands can return negative error codes as documented in errno(3); -these get turned into errno values in user space. On success, the return -code should be zero. It is also possible but not recommended to return -a positive 'long' value. - -When the ioctl callback is called with an unknown command number, the -handler returns either -ENOTTY or -ENOIOCTLCMD, which also results in --ENOTTY being returned from the system call. Some subsystems return --ENOSYS or -EINVAL here for historic reasons, but this is wrong. - -Prior to Linux 5.5, compat_ioctl handlers were required to return --ENOIOCTLCMD in order to use the fallback conversion into native -commands. As all subsystems are now responsible for handling compat -mode themselves, this is no longer needed, but it may be important to -consider when backporting bug fixes to older kernels. - -Timestamps -========== - -Traditionally, timestamps and timeout values are passed as ``struct -timespec`` or ``struct timeval``, but these are problematic because of -incompatible definitions of these structures in user space after the -move to 64-bit time_t. - -The ``struct __kernel_timespec`` type can be used instead to be embedded -in other data structures when separate second/nanosecond values are -desired, or passed to user space directly. This is still not ideal though, -as the structure matches neither the kernel's timespec64 nor the user -space timespec exactly. The get_timespec64() and put_timespec64() helper -functions can be used to ensure that the layout remains compatible with -user space and the padding is treated correctly. - -As it is cheap to convert seconds to nanoseconds, but the opposite -requires an expensive 64-bit division, a simple __u64 nanosecond value -can be simpler and more efficient. - -Timeout values and timestamps should ideally use CLOCK_MONOTONIC time, -as returned by ktime_get_ns() or ktime_get_ts64(). Unlike -CLOCK_REALTIME, this makes the timestamps immune from jumping backwards -or forwards due to leap second adjustments and clock_settime() calls. - -ktime_get_real_ns() can be used for CLOCK_REALTIME timestamps that -need to be persistent across a reboot or between multiple machines. - -32-bit compat mode -================== - -In order to support 32-bit user space running on a 64-bit machine, each -subsystem or driver that implements an ioctl callback handler must also -implement the corresponding compat_ioctl handler. - -As long as all the rules for data structures are followed, this is as -easy as setting the .compat_ioctl pointer to a helper function such as -compat_ptr_ioctl() or blkdev_compat_ptr_ioctl(). - -compat_ptr() ------------- - -On the s390 architecture, 31-bit user space has ambiguous representations -for data pointers, with the upper bit being ignored. When running such -a process in compat mode, the compat_ptr() helper must be used to -clear the upper bit of a compat_uptr_t and turn it into a valid 64-bit -pointer. On other architectures, this macro only performs a cast to a -``void __user *`` pointer. - -In an compat_ioctl() callback, the last argument is an unsigned long, -which can be interpreted as either a pointer or a scalar depending on -the command. If it is a scalar, then compat_ptr() must not be used, to -ensure that the 64-bit kernel behaves the same way as a 32-bit kernel -for arguments with the upper bit set. - -The compat_ptr_ioctl() helper can be used in place of a custom -compat_ioctl file operation for drivers that only take arguments that -are pointers to compatible data structures. - -Structure layout ----------------- - -Compatible data structures have the same layout on all architectures, -avoiding all problematic members: - -* ``long`` and ``unsigned long`` are the size of a register, so - they can be either 32-bit or 64-bit wide and cannot be used in portable - data structures. Fixed-length replacements are ``__s32``, ``__u32``, - ``__s64`` and ``__u64``. - -* Pointers have the same problem, in addition to requiring the - use of compat_ptr(). The best workaround is to use ``__u64`` - in place of pointers, which requires a cast to ``uintptr_t`` in user - space, and the use of u64_to_user_ptr() in the kernel to convert - it back into a user pointer. - -* On the x86-32 (i386) architecture, the alignment of 64-bit variables - is only 32-bit, but they are naturally aligned on most other - architectures including x86-64. This means a structure like:: - - struct foo { - __u32 a; - __u64 b; - __u32 c; - }; - - has four bytes of padding between a and b on x86-64, plus another four - bytes of padding at the end, but no padding on i386, and it needs a - compat_ioctl conversion handler to translate between the two formats. - - To avoid this problem, all structures should have their members - naturally aligned, or explicit reserved fields added in place of the - implicit padding. The ``pahole`` tool can be used for checking the - alignment. - -* On ARM OABI user space, structures are padded to multiples of 32-bit, - making some structs incompatible with modern EABI kernels if they - do not end on a 32-bit boundary. - -* On the m68k architecture, struct members are not guaranteed to have an - alignment greater than 16-bit, which is a problem when relying on - implicit padding. - -* Bitfields and enums generally work as one would expect them to, - but some properties of them are implementation-defined, so it is better - to avoid them completely in ioctl interfaces. - -* ``char`` members can be either signed or unsigned, depending on - the architecture, so the __u8 and __s8 types should be used for 8-bit - integer values, though char arrays are clearer for fixed-length strings. - -Information leaks -================= - -Uninitialized data must not be copied back to user space, as this can -cause an information leak, which can be used to defeat kernel address -space layout randomization (KASLR), helping in an attack. - -For this reason (and for compat support) it is best to avoid any -implicit padding in data structures.  Where there is implicit padding -in an existing structure, kernel drivers must be careful to fully -initialize an instance of the structure before copying it to user -space.  This is usually done by calling memset() before assigning to -individual members. - -Subsystem abstractions -====================== - -While some device drivers implement their own ioctl function, most -subsystems implement the same command for multiple drivers. Ideally the -subsystem has an .ioctl() handler that copies the arguments from and -to user space, passing them into subsystem specific callback functions -through normal kernel pointers. - -This helps in various ways: - -* Applications written for one driver are more likely to work for - another one in the same subsystem if there are no subtle differences - in the user space ABI. - -* The complexity of user space access and data structure layout is done - in one place, reducing the potential for implementation bugs. - -* It is more likely to be reviewed by experienced developers - that can spot problems in the interface when the ioctl is shared - between multiple drivers than when it is only used in a single driver. - -Alternatives to ioctl -===================== - -There are many cases in which ioctl is not the best solution for a -problem. Alternatives include: - -* System calls are a better choice for a system-wide feature that - is not tied to a physical device or constrained by the file system - permissions of a character device node - -* netlink is the preferred way of configuring any network related - objects through sockets. - -* debugfs is used for ad-hoc interfaces for debugging functionality - that does not need to be exposed as a stable interface to applications. - -* sysfs is a good way to expose the state of an in-kernel object - that is not tied to a file descriptor. - -* configfs can be used for more complex configuration than sysfs - -* A custom file system can provide extra flexibility with a simple - user interface but adds a lot of complexity to the implementation. diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index ea3003b3c5e5..1d8c5599149b 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -17,6 +17,7 @@ available subsections can be seen below. driver-model/index basics infrastructure + ioctl early-userspace/index pm/index clk diff --git a/Documentation/driver-api/ioctl.rst b/Documentation/driver-api/ioctl.rst new file mode 100644 index 000000000000..c455db0e1627 --- /dev/null +++ b/Documentation/driver-api/ioctl.rst @@ -0,0 +1,253 @@ +====================== +ioctl based interfaces +====================== + +ioctl() is the most common way for applications to interface +with device drivers. It is flexible and easily extended by adding new +commands and can be passed through character devices, block devices as +well as sockets and other special file descriptors. + +However, it is also very easy to get ioctl command definitions wrong, +and hard to fix them later without breaking existing applications, +so this documentation tries to help developers get it right. + +Command number definitions +========================== + +The command number, or request number, is the second argument passed to +the ioctl system call. While this can be any 32-bit number that uniquely +identifies an action for a particular driver, there are a number of +conventions around defining them. + +``include/uapi/asm-generic/ioctl.h`` provides four macros for defining +ioctl commands that follow modern conventions: ``_IO``, ``_IOR``, +``_IOW``, and ``_IOWR``. These should be used for all new commands, +with the correct parameters: + +_IO/_IOR/_IOW/_IOWR + The macro name specifies how the argument will be used.  It may be a + pointer to data to be passed into the kernel (_IOW), out of the kernel + (_IOR), or both (_IOWR).  _IO can indicate either commands with no + argument or those passing an integer value instead of a pointer. + It is recommended to only use _IO for commands without arguments, + and use pointers for passing data. + +type + An 8-bit number, often a character literal, specific to a subsystem + or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number` + +nr + An 8-bit number identifying the specific command, unique for a give + value of 'type' + +data_type + The name of the data type pointed to by the argument, the command number + encodes the ``sizeof(data_type)`` value in a 13-bit or 14-bit integer, + leading to a limit of 8191 bytes for the maximum size of the argument. + Note: do not pass sizeof(data_type) type into _IOR/_IOW/IOWR, as that + will lead to encoding sizeof(sizeof(data_type)), i.e. sizeof(size_t). + _IO does not have a data_type parameter. + + +Interface versions +================== + +Some subsystems use version numbers in data structures to overload +commands with different interpretations of the argument. + +This is generally a bad idea, since changes to existing commands tend +to break existing applications. + +A better approach is to add a new ioctl command with a new number. The +old command still needs to be implemented in the kernel for compatibility, +but this can be a wrapper around the new implementation. + +Return code +=========== + +ioctl commands can return negative error codes as documented in errno(3); +these get turned into errno values in user space. On success, the return +code should be zero. It is also possible but not recommended to return +a positive 'long' value. + +When the ioctl callback is called with an unknown command number, the +handler returns either -ENOTTY or -ENOIOCTLCMD, which also results in +-ENOTTY being returned from the system call. Some subsystems return +-ENOSYS or -EINVAL here for historic reasons, but this is wrong. + +Prior to Linux 5.5, compat_ioctl handlers were required to return +-ENOIOCTLCMD in order to use the fallback conversion into native +commands. As all subsystems are now responsible for handling compat +mode themselves, this is no longer needed, but it may be important to +consider when backporting bug fixes to older kernels. + +Timestamps +========== + +Traditionally, timestamps and timeout values are passed as ``struct +timespec`` or ``struct timeval``, but these are problematic because of +incompatible definitions of these structures in user space after the +move to 64-bit time_t. + +The ``struct __kernel_timespec`` type can be used instead to be embedded +in other data structures when separate second/nanosecond values are +desired, or passed to user space directly. This is still not ideal though, +as the structure matches neither the kernel's timespec64 nor the user +space timespec exactly. The get_timespec64() and put_timespec64() helper +functions can be used to ensure that the layout remains compatible with +user space and the padding is treated correctly. + +As it is cheap to convert seconds to nanoseconds, but the opposite +requires an expensive 64-bit division, a simple __u64 nanosecond value +can be simpler and more efficient. + +Timeout values and timestamps should ideally use CLOCK_MONOTONIC time, +as returned by ktime_get_ns() or ktime_get_ts64(). Unlike +CLOCK_REALTIME, this makes the timestamps immune from jumping backwards +or forwards due to leap second adjustments and clock_settime() calls. + +ktime_get_real_ns() can be used for CLOCK_REALTIME timestamps that +need to be persistent across a reboot or between multiple machines. + +32-bit compat mode +================== + +In order to support 32-bit user space running on a 64-bit machine, each +subsystem or driver that implements an ioctl callback handler must also +implement the corresponding compat_ioctl handler. + +As long as all the rules for data structures are followed, this is as +easy as setting the .compat_ioctl pointer to a helper function such as +compat_ptr_ioctl() or blkdev_compat_ptr_ioctl(). + +compat_ptr() +------------ + +On the s390 architecture, 31-bit user space has ambiguous representations +for data pointers, with the upper bit being ignored. When running such +a process in compat mode, the compat_ptr() helper must be used to +clear the upper bit of a compat_uptr_t and turn it into a valid 64-bit +pointer. On other architectures, this macro only performs a cast to a +``void __user *`` pointer. + +In an compat_ioctl() callback, the last argument is an unsigned long, +which can be interpreted as either a pointer or a scalar depending on +the command. If it is a scalar, then compat_ptr() must not be used, to +ensure that the 64-bit kernel behaves the same way as a 32-bit kernel +for arguments with the upper bit set. + +The compat_ptr_ioctl() helper can be used in place of a custom +compat_ioctl file operation for drivers that only take arguments that +are pointers to compatible data structures. + +Structure layout +---------------- + +Compatible data structures have the same layout on all architectures, +avoiding all problematic members: + +* ``long`` and ``unsigned long`` are the size of a register, so + they can be either 32-bit or 64-bit wide and cannot be used in portable + data structures. Fixed-length replacements are ``__s32``, ``__u32``, + ``__s64`` and ``__u64``. + +* Pointers have the same problem, in addition to requiring the + use of compat_ptr(). The best workaround is to use ``__u64`` + in place of pointers, which requires a cast to ``uintptr_t`` in user + space, and the use of u64_to_user_ptr() in the kernel to convert + it back into a user pointer. + +* On the x86-32 (i386) architecture, the alignment of 64-bit variables + is only 32-bit, but they are naturally aligned on most other + architectures including x86-64. This means a structure like:: + + struct foo { + __u32 a; + __u64 b; + __u32 c; + }; + + has four bytes of padding between a and b on x86-64, plus another four + bytes of padding at the end, but no padding on i386, and it needs a + compat_ioctl conversion handler to translate between the two formats. + + To avoid this problem, all structures should have their members + naturally aligned, or explicit reserved fields added in place of the + implicit padding. The ``pahole`` tool can be used for checking the + alignment. + +* On ARM OABI user space, structures are padded to multiples of 32-bit, + making some structs incompatible with modern EABI kernels if they + do not end on a 32-bit boundary. + +* On the m68k architecture, struct members are not guaranteed to have an + alignment greater than 16-bit, which is a problem when relying on + implicit padding. + +* Bitfields and enums generally work as one would expect them to, + but some properties of them are implementation-defined, so it is better + to avoid them completely in ioctl interfaces. + +* ``char`` members can be either signed or unsigned, depending on + the architecture, so the __u8 and __s8 types should be used for 8-bit + integer values, though char arrays are clearer for fixed-length strings. + +Information leaks +================= + +Uninitialized data must not be copied back to user space, as this can +cause an information leak, which can be used to defeat kernel address +space layout randomization (KASLR), helping in an attack. + +For this reason (and for compat support) it is best to avoid any +implicit padding in data structures.  Where there is implicit padding +in an existing structure, kernel drivers must be careful to fully +initialize an instance of the structure before copying it to user +space.  This is usually done by calling memset() before assigning to +individual members. + +Subsystem abstractions +====================== + +While some device drivers implement their own ioctl function, most +subsystems implement the same command for multiple drivers. Ideally the +subsystem has an .ioctl() handler that copies the arguments from and +to user space, passing them into subsystem specific callback functions +through normal kernel pointers. + +This helps in various ways: + +* Applications written for one driver are more likely to work for + another one in the same subsystem if there are no subtle differences + in the user space ABI. + +* The complexity of user space access and data structure layout is done + in one place, reducing the potential for implementation bugs. + +* It is more likely to be reviewed by experienced developers + that can spot problems in the interface when the ioctl is shared + between multiple drivers than when it is only used in a single driver. + +Alternatives to ioctl +===================== + +There are many cases in which ioctl is not the best solution for a +problem. Alternatives include: + +* System calls are a better choice for a system-wide feature that + is not tied to a physical device or constrained by the file system + permissions of a character device node + +* netlink is the preferred way of configuring any network related + objects through sockets. + +* debugfs is used for ad-hoc interfaces for debugging functionality + that does not need to be exposed as a stable interface to applications. + +* sysfs is a good way to expose the state of an in-kernel object + that is not tied to a file descriptor. + +* configfs can be used for more complex configuration than sysfs + +* A custom file system can provide extra flexibility with a simple + user interface but adds a lot of complexity to the implementation. -- cgit v1.2.3 From fcd6807271579c377a5fc43a4dc22fdd9883ba8c Mon Sep 17 00:00:00 2001 From: Pragat Pandya Date: Tue, 3 Mar 2020 10:33:00 +0530 Subject: Documentation: Add io-mapping.rst to driver-api manual Add io-mapping.rst under Documentation/driver-api and reference it from Sphinx TOC Tree present in Documentation/driver-api/index.rst Signed-off-by: Pragat Pandya Link: https://lore.kernel.org/r/20200303050301.5412-2-pragat.pandya@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/io-mapping.rst | 97 +++++++++++++++++++++++++++++++++ Documentation/io-mapping.txt | 97 --------------------------------- 3 files changed, 98 insertions(+), 97 deletions(-) create mode 100644 Documentation/driver-api/io-mapping.rst delete mode 100644 Documentation/io-mapping.txt (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 1d8c5599149b..99bdb393f475 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -79,6 +79,7 @@ available subsections can be seen below. ipmb isa isapnp + io-mapping generic-counter lightnvm-pblk memory-devices/index diff --git a/Documentation/driver-api/io-mapping.rst b/Documentation/driver-api/io-mapping.rst new file mode 100644 index 000000000000..a966239f04e4 --- /dev/null +++ b/Documentation/driver-api/io-mapping.rst @@ -0,0 +1,97 @@ +======================== +The io_mapping functions +======================== + +API +=== + +The io_mapping functions in linux/io-mapping.h provide an abstraction for +efficiently mapping small regions of an I/O device to the CPU. The initial +usage is to support the large graphics aperture on 32-bit processors where +ioremap_wc cannot be used to statically map the entire aperture to the CPU +as it would consume too much of the kernel address space. + +A mapping object is created during driver initialization using:: + + struct io_mapping *io_mapping_create_wc(unsigned long base, + unsigned long size) + +'base' is the bus address of the region to be made +mappable, while 'size' indicates how large a mapping region to +enable. Both are in bytes. + +This _wc variant provides a mapping which may only be used +with the io_mapping_map_atomic_wc or io_mapping_map_wc. + +With this mapping object, individual pages can be mapped either atomically +or not, depending on the necessary scheduling environment. Of course, atomic +maps are more efficient:: + + void *io_mapping_map_atomic_wc(struct io_mapping *mapping, + unsigned long offset) + +'offset' is the offset within the defined mapping region. +Accessing addresses beyond the region specified in the +creation function yields undefined results. Using an offset +which is not page aligned yields an undefined result. The +return value points to a single page in CPU address space. + +This _wc variant returns a write-combining map to the +page and may only be used with mappings created by +io_mapping_create_wc + +Note that the task may not sleep while holding this page +mapped. + +:: + + void io_mapping_unmap_atomic(void *vaddr) + +'vaddr' must be the value returned by the last +io_mapping_map_atomic_wc call. This unmaps the specified +page and allows the task to sleep once again. + +If you need to sleep while holding the lock, you can use the non-atomic +variant, although they may be significantly slower. + +:: + + void *io_mapping_map_wc(struct io_mapping *mapping, + unsigned long offset) + +This works like io_mapping_map_atomic_wc except it allows +the task to sleep while holding the page mapped. + + +:: + + void io_mapping_unmap(void *vaddr) + +This works like io_mapping_unmap_atomic, except it is used +for pages mapped with io_mapping_map_wc. + +At driver close time, the io_mapping object must be freed:: + + void io_mapping_free(struct io_mapping *mapping) + +Current Implementation +====================== + +The initial implementation of these functions uses existing mapping +mechanisms and so provides only an abstraction layer and no new +functionality. + +On 64-bit processors, io_mapping_create_wc calls ioremap_wc for the whole +range, creating a permanent kernel-visible mapping to the resource. The +map_atomic and map functions add the requested offset to the base of the +virtual address returned by ioremap_wc. + +On 32-bit processors with HIGHMEM defined, io_mapping_map_atomic_wc uses +kmap_atomic_pfn to map the specified page in an atomic fashion; +kmap_atomic_pfn isn't really supposed to be used with device pages, but it +provides an efficient mapping for this usage. + +On 32-bit processors without HIGHMEM defined, io_mapping_map_atomic_wc and +io_mapping_map_wc both use ioremap_wc, a terribly inefficient function which +performs an IPI to inform all processors about the new mapping. This results +in a significant performance penalty. diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.txt deleted file mode 100644 index a966239f04e4..000000000000 --- a/Documentation/io-mapping.txt +++ /dev/null @@ -1,97 +0,0 @@ -======================== -The io_mapping functions -======================== - -API -=== - -The io_mapping functions in linux/io-mapping.h provide an abstraction for -efficiently mapping small regions of an I/O device to the CPU. The initial -usage is to support the large graphics aperture on 32-bit processors where -ioremap_wc cannot be used to statically map the entire aperture to the CPU -as it would consume too much of the kernel address space. - -A mapping object is created during driver initialization using:: - - struct io_mapping *io_mapping_create_wc(unsigned long base, - unsigned long size) - -'base' is the bus address of the region to be made -mappable, while 'size' indicates how large a mapping region to -enable. Both are in bytes. - -This _wc variant provides a mapping which may only be used -with the io_mapping_map_atomic_wc or io_mapping_map_wc. - -With this mapping object, individual pages can be mapped either atomically -or not, depending on the necessary scheduling environment. Of course, atomic -maps are more efficient:: - - void *io_mapping_map_atomic_wc(struct io_mapping *mapping, - unsigned long offset) - -'offset' is the offset within the defined mapping region. -Accessing addresses beyond the region specified in the -creation function yields undefined results. Using an offset -which is not page aligned yields an undefined result. The -return value points to a single page in CPU address space. - -This _wc variant returns a write-combining map to the -page and may only be used with mappings created by -io_mapping_create_wc - -Note that the task may not sleep while holding this page -mapped. - -:: - - void io_mapping_unmap_atomic(void *vaddr) - -'vaddr' must be the value returned by the last -io_mapping_map_atomic_wc call. This unmaps the specified -page and allows the task to sleep once again. - -If you need to sleep while holding the lock, you can use the non-atomic -variant, although they may be significantly slower. - -:: - - void *io_mapping_map_wc(struct io_mapping *mapping, - unsigned long offset) - -This works like io_mapping_map_atomic_wc except it allows -the task to sleep while holding the page mapped. - - -:: - - void io_mapping_unmap(void *vaddr) - -This works like io_mapping_unmap_atomic, except it is used -for pages mapped with io_mapping_map_wc. - -At driver close time, the io_mapping object must be freed:: - - void io_mapping_free(struct io_mapping *mapping) - -Current Implementation -====================== - -The initial implementation of these functions uses existing mapping -mechanisms and so provides only an abstraction layer and no new -functionality. - -On 64-bit processors, io_mapping_create_wc calls ioremap_wc for the whole -range, creating a permanent kernel-visible mapping to the resource. The -map_atomic and map functions add the requested offset to the base of the -virtual address returned by ioremap_wc. - -On 32-bit processors with HIGHMEM defined, io_mapping_map_atomic_wc uses -kmap_atomic_pfn to map the specified page in an atomic fashion; -kmap_atomic_pfn isn't really supposed to be used with device pages, but it -provides an efficient mapping for this usage. - -On 32-bit processors without HIGHMEM defined, io_mapping_map_atomic_wc and -io_mapping_map_wc both use ioremap_wc, a terribly inefficient function which -performs an IPI to inform all processors about the new mapping. This results -in a significant performance penalty. -- cgit v1.2.3 From d1ce350015d86a67d245fad124e37d14b573cac2 Mon Sep 17 00:00:00 2001 From: Pragat Pandya Date: Tue, 3 Mar 2020 10:33:01 +0530 Subject: Documentation: Add io_ordering.rst to driver-api manual Add io_ordering.rst under Documentation/driver-api and reference it from the Sphinx TOC Tree present in Documentation/driver-api/index.rst Signed-off-by: Pragat Pandya Link: https://lore.kernel.org/r/20200303050301.5412-3-pragat.pandya@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/io_ordering.rst | 51 ++++++++++++++++++++++++++++++++ Documentation/io_ordering.txt | 51 -------------------------------- 3 files changed, 52 insertions(+), 51 deletions(-) create mode 100644 Documentation/driver-api/io_ordering.rst delete mode 100644 Documentation/io_ordering.txt (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 99bdb393f475..d4e78cb3ef4d 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -80,6 +80,7 @@ available subsections can be seen below. isa isapnp io-mapping + io_ordering generic-counter lightnvm-pblk memory-devices/index diff --git a/Documentation/driver-api/io_ordering.rst b/Documentation/driver-api/io_ordering.rst new file mode 100644 index 000000000000..2ab303ce9a0d --- /dev/null +++ b/Documentation/driver-api/io_ordering.rst @@ -0,0 +1,51 @@ +============================================== +Ordering I/O writes to memory-mapped addresses +============================================== + +On some platforms, so-called memory-mapped I/O is weakly ordered. On such +platforms, driver writers are responsible for ensuring that I/O writes to +memory-mapped addresses on their device arrive in the order intended. This is +typically done by reading a 'safe' device or bridge register, causing the I/O +chipset to flush pending writes to the device before any reads are posted. A +driver would usually use this technique immediately prior to the exit of a +critical section of code protected by spinlocks. This would ensure that +subsequent writes to I/O space arrived only after all prior writes (much like a +memory barrier op, mb(), only with respect to I/O). + +A more concrete example from a hypothetical device driver:: + + ... + CPU A: spin_lock_irqsave(&dev_lock, flags) + CPU A: val = readl(my_status); + CPU A: ... + CPU A: writel(newval, ring_ptr); + CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... + CPU B: spin_lock_irqsave(&dev_lock, flags) + CPU B: val = readl(my_status); + CPU B: ... + CPU B: writel(newval2, ring_ptr); + CPU B: spin_unlock_irqrestore(&dev_lock, flags) + ... + +In the case above, the device may receive newval2 before it receives newval, +which could cause problems. Fixing it is easy enough though:: + + ... + CPU A: spin_lock_irqsave(&dev_lock, flags) + CPU A: val = readl(my_status); + CPU A: ... + CPU A: writel(newval, ring_ptr); + CPU A: (void)readl(safe_register); /* maybe a config register? */ + CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... + CPU B: spin_lock_irqsave(&dev_lock, flags) + CPU B: val = readl(my_status); + CPU B: ... + CPU B: writel(newval2, ring_ptr); + CPU B: (void)readl(safe_register); /* maybe a config register? */ + CPU B: spin_unlock_irqrestore(&dev_lock, flags) + +Here, the reads from safe_register will cause the I/O chipset to flush any +pending writes before actually posting the read to the chipset, preventing +possible data corruption. diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.txt deleted file mode 100644 index 2ab303ce9a0d..000000000000 --- a/Documentation/io_ordering.txt +++ /dev/null @@ -1,51 +0,0 @@ -============================================== -Ordering I/O writes to memory-mapped addresses -============================================== - -On some platforms, so-called memory-mapped I/O is weakly ordered. On such -platforms, driver writers are responsible for ensuring that I/O writes to -memory-mapped addresses on their device arrive in the order intended. This is -typically done by reading a 'safe' device or bridge register, causing the I/O -chipset to flush pending writes to the device before any reads are posted. A -driver would usually use this technique immediately prior to the exit of a -critical section of code protected by spinlocks. This would ensure that -subsequent writes to I/O space arrived only after all prior writes (much like a -memory barrier op, mb(), only with respect to I/O). - -A more concrete example from a hypothetical device driver:: - - ... - CPU A: spin_lock_irqsave(&dev_lock, flags) - CPU A: val = readl(my_status); - CPU A: ... - CPU A: writel(newval, ring_ptr); - CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... - CPU B: spin_lock_irqsave(&dev_lock, flags) - CPU B: val = readl(my_status); - CPU B: ... - CPU B: writel(newval2, ring_ptr); - CPU B: spin_unlock_irqrestore(&dev_lock, flags) - ... - -In the case above, the device may receive newval2 before it receives newval, -which could cause problems. Fixing it is easy enough though:: - - ... - CPU A: spin_lock_irqsave(&dev_lock, flags) - CPU A: val = readl(my_status); - CPU A: ... - CPU A: writel(newval, ring_ptr); - CPU A: (void)readl(safe_register); /* maybe a config register? */ - CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... - CPU B: spin_lock_irqsave(&dev_lock, flags) - CPU B: val = readl(my_status); - CPU B: ... - CPU B: writel(newval2, ring_ptr); - CPU B: (void)readl(safe_register); /* maybe a config register? */ - CPU B: spin_unlock_irqrestore(&dev_lock, flags) - -Here, the reads from safe_register will cause the I/O chipset to flush any -pending writes before actually posting the read to the chipset, preventing -possible data corruption. -- cgit v1.2.3 From 99d1a38a739e1d8e3ae6b2f76a364b21f16d7bd9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 3 Mar 2020 16:50:34 +0100 Subject: docs: driver.rst: supress two ReSt warnings Get rid of those, by marking a literal block as such: Documentation/driver-api/gpio/driver.rst:425: WARNING: Unexpected indentation. Documentation/driver-api/gpio/driver.rst:423: WARNING: Inline emphasis start-string without end-string. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/8356b02547087979f57cb71fbefb5e5f636c78f4.1583250595.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/driver-api/driver-model/driver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst index baa6a85c8287..63887b813005 100644 --- a/Documentation/driver-api/driver-model/driver.rst +++ b/Documentation/driver-api/driver-model/driver.rst @@ -210,7 +210,7 @@ probed. While the typical use case for sync_state() is to have the kernel cleanly take over management of devices from the bootloader, the usage of sync_state() is not restricted to that. Use it whenever it makes sense to take an action after -all the consumers of a device have probed. +all the consumers of a device have probed:: int (*remove) (struct device *dev); -- cgit v1.2.3 From c44166fe5f38f0559eff1138cca094f3460e2345 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 20 Mar 2020 16:11:02 +0100 Subject: docs: prevent warnings due to autosectionlabel Changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") enabled a new feature at Sphinx: it will now generate index for each document title, plus to each chapter inside it. There's a drawback, though: one document cannot have two sections with the same name anymore. A followup patch will change the logic of autosectionlabel to avoid most creating references for every single section title, but still we need to be able to reference the chapters inside a document. There are a few places where there are two chapters with the same name. This patch renames one of the chapters, in order to avoid symbol conflict within the same document. PS.: as I don't speach Chinese, I had some help from a friend (Wen Liu) at the Chinese translation for "publishing patches" for this document: Documentation/translations/zh_CN/process/5.Posting.rst Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/2bffb91e4a63d41bf5fae1c23e1e8b3bba0b8806.1584716446.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/driver-api/80211/mac80211-advanced.rst | 8 ++++---- Documentation/driver-api/dmaengine/index.rst | 4 ++-- Documentation/filesystems/ecryptfs.rst | 11 +++++------ Documentation/kernel-hacking/hacking.rst | 4 ++-- Documentation/media/kapi/v4l2-controls.rst | 8 ++++---- Documentation/networking/snmp_counter.rst | 4 ++-- Documentation/powerpc/ultravisor.rst | 4 ++-- Documentation/security/siphash.rst | 8 ++++---- Documentation/target/tcmu-design.rst | 6 +++--- Documentation/translations/zh_CN/process/5.Posting.rst | 2 +- Documentation/x86/intel-iommu.rst | 3 ++- 11 files changed, 31 insertions(+), 31 deletions(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/80211/mac80211-advanced.rst b/Documentation/driver-api/80211/mac80211-advanced.rst index 9f1c5bb7ac35..24cb64b3b715 100644 --- a/Documentation/driver-api/80211/mac80211-advanced.rst +++ b/Documentation/driver-api/80211/mac80211-advanced.rst @@ -272,8 +272,8 @@ STA information lifetime rules .. kernel-doc:: net/mac80211/sta_info.c :doc: STA information lifetime rules -Aggregation -=========== +Aggregation Functions +===================== .. kernel-doc:: net/mac80211/sta_info.h :functions: sta_ampdu_mlme @@ -284,8 +284,8 @@ Aggregation .. kernel-doc:: net/mac80211/sta_info.h :functions: tid_ampdu_rx -Synchronisation -=============== +Synchronisation Functions +========================= TBD diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst index b9df904d0a79..bdc45d8b4cfb 100644 --- a/Documentation/driver-api/dmaengine/index.rst +++ b/Documentation/driver-api/dmaengine/index.rst @@ -5,8 +5,8 @@ DMAEngine documentation DMAEngine documentation provides documents for various aspects of DMAEngine framework. -DMAEngine documentation ------------------------ +DMAEngine development documentation +----------------------------------- This book helps with DMAengine internal APIs and guide for DMAEngine device driver writers. diff --git a/Documentation/filesystems/ecryptfs.rst b/Documentation/filesystems/ecryptfs.rst index 7236172300ef..1f2edef4c57a 100644 --- a/Documentation/filesystems/ecryptfs.rst +++ b/Documentation/filesystems/ecryptfs.rst @@ -30,13 +30,12 @@ Userspace requirements include: - Libgcrypt -Notes -===== +.. note:: -In the beta/experimental releases of eCryptfs, when you upgrade -eCryptfs, you should copy the files to an unencrypted location and -then copy the files back into the new eCryptfs mount to migrate the -files. + In the beta/experimental releases of eCryptfs, when you upgrade + eCryptfs, you should copy the files to an unencrypted location and + then copy the files back into the new eCryptfs mount to migrate the + files. Mount-wide Passphrase diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index d707a0a61cc9..eed2136d847f 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -601,7 +601,7 @@ Defined in ``include/linux/export.h`` This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol namespace. Symbol Namespaces are documented in -:ref:`Documentation/core-api/symbol-namespaces.rst ` +:doc:`../core-api/symbol-namespaces` :c:func:`EXPORT_SYMBOL_NS_GPL()` -------------------------------- @@ -610,7 +610,7 @@ Defined in ``include/linux/export.h`` This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol namespace. Symbol Namespaces are documented in -:ref:`Documentation/core-api/symbol-namespaces.rst ` +:doc:`../core-api/symbol-namespaces` Routines and Conventions ======================== diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index b20800cae3f2..5129019afb49 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -291,8 +291,8 @@ and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically suppo In practice the basic usage as described above is sufficient for most drivers. -Inheriting Controls -------------------- +Inheriting Sub-device Controls +------------------------------ When a sub-device is registered with a V4L2 driver by calling v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev @@ -757,8 +757,8 @@ attempting to find another control from the same handler will deadlock. It is recommended not to use this function from inside the control ops. -Inheriting Controls -------------------- +Preventing Controls inheritance +------------------------------- When one control handler is added to another using v4l2_ctrl_add_handler, then by default all controls from one are merged to the other. But a subdev might diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst index 38a4edc4522b..10e11099e74a 100644 --- a/Documentation/networking/snmp_counter.rst +++ b/Documentation/networking/snmp_counter.rst @@ -908,8 +908,8 @@ A TLP probe packet is sent. A packet loss is detected and recovered by TLP. -TCP Fast Open -============= +TCP Fast Open description +========================= TCP Fast Open is a technology which allows data transfer before the 3-way handshake complete. Please refer the `TCP Fast Open wiki`_ for a general description. diff --git a/Documentation/powerpc/ultravisor.rst b/Documentation/powerpc/ultravisor.rst index 363736d7fd36..df136c8f91fa 100644 --- a/Documentation/powerpc/ultravisor.rst +++ b/Documentation/powerpc/ultravisor.rst @@ -8,8 +8,8 @@ Protected Execution Facility .. contents:: :depth: 3 -Protected Execution Facility -############################ +Introduction +############ Protected Execution Facility (PEF) is an architectural change for POWER 9 that enables Secure Virtual Machines (SVMs). DD2.3 chips diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index 9965821ab333..4eba68cdf0a1 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -128,8 +128,8 @@ then when you can be absolutely certain that the outputs will never be transmitted out of the kernel. This is only remotely useful over `jhash` as a means of mitigating hashtable flooding denial of service attacks. -Generating a key -================ +Generating a HalfSipHash key +============================ Keys should always be generated from a cryptographically secure source of random numbers, either using get_random_bytes or get_random_once: @@ -139,8 +139,8 @@ get_random_bytes(&key, sizeof(key)); If you're not deriving your key from here, you're doing it wrong. -Using the functions -=================== +Using the HalfSipHash functions +=============================== There are two variants of the function, one that takes a list of integers, and one that takes a buffer:: diff --git a/Documentation/target/tcmu-design.rst b/Documentation/target/tcmu-design.rst index a7b426707bf6..e47047e32e27 100644 --- a/Documentation/target/tcmu-design.rst +++ b/Documentation/target/tcmu-design.rst @@ -5,7 +5,7 @@ TCM Userspace Design .. Contents: - 1) TCM Userspace Design + 1) Design a) Background b) Benefits c) Design constraints @@ -23,8 +23,8 @@ TCM Userspace Design 3) A final note -TCM Userspace Design -==================== +Design +====== TCM is another name for LIO, an in-kernel iSCSI target (server). Existing TCM targets run in the kernel. TCMU (TCM in Userspace) diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 41aba21ff050..9ff9945f918c 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -5,7 +5,7 @@ .. _cn_development_posting: -发送补丁 +发布补丁 ======== 迟早，当您的工作准备好提交给社区进行审查，并最终包含到主线内核中时。不出所料， diff --git a/Documentation/x86/intel-iommu.rst b/Documentation/x86/intel-iommu.rst index 9dae6b47e398..099f13d51d5f 100644 --- a/Documentation/x86/intel-iommu.rst +++ b/Documentation/x86/intel-iommu.rst @@ -95,9 +95,10 @@ and any RMRR's processed:: When DMAR is enabled for use, you will notice.. PCI-DMA: Using DMAR IOMMU +------------------------- Fault reporting ---------------- +^^^^^^^^^^^^^^^ :: -- cgit v1.2.3