summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2018-01-31 19:25:25 -0800
committerLinus Torvalds <torvalds@linux-foundation.org>2018-01-31 19:25:25 -0800
commit255442c93843f52b6891b21d0b485bf2c97f93c3 (patch)
tree8fd1daa752dbfa4721f64421ab7d4e695605d9f7
parentd76e0a050e0f5e7c00e6d334f758178bbc16eb98 (diff)
parentae17a87dd7c79fa742ef5dcf06d1095eec4e1925 (diff)
Merge tag 'docs-4.16' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "Documentation updates for 4.16. New stuff includes refcount_t documentation, errseq documentation, kernel-doc support for nested structure definitions, the removal of lots of crufty kernel-doc support for unused formats, SPDX tag documentation, the beginnings of a manual for subsystem maintainers, and lots of fixes and updates. As usual, some of the changesets reach outside of Documentation/ to effect kerneldoc comment fixes. It also adds the new LICENSES directory, of which Thomas promises I do not need to be the maintainer" * tag 'docs-4.16' of git://git.lwn.net/linux: (65 commits) linux-next: docs-rst: Fix typos in kfigure.py linux-next: DOC: HWPOISON: Fix path to debugfs in hwpoison.txt Documentation: Fix misconversion of #if docs: add index entry for networking/msg_zerocopy Documentation: security/credentials.rst: explain need to sort group_list LICENSES: Add MPL-1.1 license LICENSES: Add the GPL 1.0 license LICENSES: Add Linux syscall note exception LICENSES: Add the MIT license LICENSES: Add the BSD-3-clause "Clear" license LICENSES: Add the BSD 3-clause "New" or "Revised" License LICENSES: Add the BSD 2-clause "Simplified" license LICENSES: Add the LGPL-2.1 license LICENSES: Add the LGPL 2.0 license LICENSES: Add the GPL 2.0 license Documentation: Add license-rules.rst to describe how to properly identify file licenses scripts: kernel_doc: better handle show warnings logic fs/*/Kconfig: drop links to 404-compliant http://acl.bestbits.at doc: md: Fix a file name to md-fault.c in fault-injection.txt errseq: Add to documentation tree ...
-rw-r--r--Documentation/00-INDEX4
-rw-r--r--Documentation/admin-guide/kernel-parameters.txt3
-rw-r--r--Documentation/admin-guide/mono.rst6
-rw-r--r--Documentation/conf.py1
-rw-r--r--Documentation/core-api/errseq.rst (renamed from Documentation/errseq.rst)20
-rw-r--r--Documentation/core-api/index.rst3
-rw-r--r--Documentation/core-api/kernel-api.rst15
-rw-r--r--Documentation/core-api/printk-formats.rst (renamed from Documentation/printk-formats.txt)227
-rw-r--r--Documentation/core-api/refcount-vs-atomic.rst150
-rw-r--r--Documentation/doc-guide/kernel-doc.rst360
-rw-r--r--Documentation/driver-api/basics.rst21
-rw-r--r--Documentation/driver-api/usb/usb3-debug-port.rst52
-rw-r--r--Documentation/driver-api/usb/writing_usb_driver.rst2
-rw-r--r--Documentation/fault-injection/fault-injection.txt2
-rw-r--r--Documentation/filesystems/ext2.txt2
-rw-r--r--Documentation/filesystems/ext4.txt7
-rw-r--r--Documentation/filesystems/vfat.txt2
-rw-r--r--Documentation/i2c/dev-interface17
-rw-r--r--Documentation/index.rst13
-rw-r--r--Documentation/kbuild/kconfig-language.txt21
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt322
-rw-r--r--Documentation/kernel-hacking/hacking.rst6
-rw-r--r--Documentation/maintainer/conf.py10
-rw-r--r--Documentation/maintainer/configure-git.rst34
-rw-r--r--Documentation/maintainer/index.rst14
-rw-r--r--Documentation/maintainer/pull-requests.rst178
-rw-r--r--Documentation/process/kernel-enforcement-statement.rst3
-rw-r--r--Documentation/process/license-rules.rst370
-rw-r--r--Documentation/process/submit-checklist.rst4
-rw-r--r--Documentation/security/credentials.rst7
-rw-r--r--Documentation/security/self-protection.rst15
-rw-r--r--Documentation/sphinx/kfigure.py6
-rw-r--r--Documentation/sysctl/kernel.txt17
-rw-r--r--Documentation/trace/ftrace-uses.rst60
-rw-r--r--Documentation/usb/chipidea.txt12
-rw-r--r--Documentation/vm/hwpoison.txt2
-rw-r--r--Documentation/w1/w1.generic2
-rw-r--r--LICENSES/exceptions/Linux-syscall-note25
-rw-r--r--LICENSES/other/GPL-1.0260
-rw-r--r--LICENSES/other/MPL-1.1478
-rw-r--r--LICENSES/preferred/BSD-2-Clause32
-rw-r--r--LICENSES/preferred/BSD-3-Clause36
-rw-r--r--LICENSES/preferred/BSD-3-Clause-Clear41
-rw-r--r--LICENSES/preferred/GPL-2.0353
-rw-r--r--LICENSES/preferred/LGPL-2.0487
-rw-r--r--LICENSES/preferred/LGPL-2.1503
-rw-r--r--LICENSES/preferred/MIT30
-rw-r--r--drivers/w1/w1_netlink.h6
-rw-r--r--fs/9p/Kconfig3
-rw-r--r--fs/Kconfig6
-rw-r--r--fs/btrfs/Kconfig3
-rw-r--r--fs/ceph/Kconfig3
-rw-r--r--fs/cifs/Kconfig15
-rw-r--r--fs/ext2/Kconfig6
-rw-r--r--fs/ext4/Kconfig3
-rw-r--r--fs/f2fs/Kconfig6
-rw-r--r--fs/hfsplus/Kconfig3
-rw-r--r--fs/jffs2/Kconfig6
-rw-r--r--fs/jfs/Kconfig3
-rw-r--r--fs/reiserfs/Kconfig6
-rw-r--r--fs/xfs/Kconfig3
-rw-r--r--include/linux/errseq.h2
-rw-r--r--include/linux/refcount.h2
-rw-r--r--lib/errseq.c37
-rw-r--r--lib/uuid.c34
-rw-r--r--lib/vsprintf.c5
-rwxr-xr-xscripts/kernel-doc1506
67 files changed, 3887 insertions, 2006 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7f3a0728ccf2 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -228,8 +228,6 @@ isdn/
- directory with info on the Linux ISDN support, and supported cards.
kbuild/
- directory with info about the kernel build process.
-kernel-doc-nano-HOWTO.txt
- - outdated info about kernel-doc documentation.
kdump/
- directory with mini HowTo on getting the crash dump code to work.
doc-guide/
@@ -346,8 +344,6 @@ prctl/
- directory with info on the priveledge control subsystem
preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
- - how to get printk format specifiers right
process/
- how to work with the mainline kernel development process.
pps/
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index b98048b56ada..dc63e5bddf78 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -2538,6 +2538,9 @@
This is useful when you use a panic=... timeout and
need the box quickly up again.
+ These settings can be accessed at runtime via
+ the nmi_watchdog and hardlockup_panic sysctls.
+
netpoll.carrier_timeout=
[NET] Specifies amount of time (in seconds) that
netpoll should wait for a carrier. By default netpoll
diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst
index cdddc099af64..59e6d59f0ed9 100644
--- a/Documentation/admin-guide/mono.rst
+++ b/Documentation/admin-guide/mono.rst
@@ -9,14 +9,14 @@ This will allow you to execute Mono-based .NET binaries just like any
other program after you have done the following:
1) You MUST FIRST install the Mono CLR support, either by downloading
- a binary package, a source tarball or by installing from CVS. Binary
+ a binary package, a source tarball or by installing from Git. Binary
packages for several distributions can be found at:
- http://go-mono.com/download.html
+ http://www.mono-project.com/download/
Instructions for compiling Mono can be found at:
- http://www.go-mono.com/compiling.html
+ http://www.mono-project.com/docs/compiling-mono/linux/
Once the Mono CLR support has been installed, just check that
``/usr/bin/mono`` (which could be located elsewhere, for example
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 63857d33778c..62ac5a9f3a9f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -88,7 +88,6 @@ finally:
if makefile_version and makefile_patchlevel:
version = release = makefile_version + '.' + makefile_patchlevel
else:
- sys.stderr.write('Warning: Could not extract kernel version\n')
version = release = "unknown version"
# The language for content autogenerated by Sphinx. Refer to documentation
diff --git a/Documentation/errseq.rst b/Documentation/core-api/errseq.rst
index 4c29bd5afbc5..ff332e272405 100644
--- a/Documentation/errseq.rst
+++ b/Documentation/core-api/errseq.rst
@@ -1,5 +1,7 @@
+=====================
The errseq_t datatype
=====================
+
An errseq_t is a way of recording errors in one place, and allowing any
number of "subscribers" to tell whether it has changed since a previous
point where it was sampled.
@@ -21,12 +23,13 @@ a flag to tell whether the value has been sampled since a new value was
recorded. That allows us to avoid bumping the counter if no one has
sampled it since the last time an error was recorded.
-Thus we end up with a value that looks something like this::
+Thus we end up with a value that looks something like this:
- bit: 31..13 12 11..0
- +-----------------+----+----------------+
- | counter | SF | errno |
- +-----------------+----+----------------+
++--------------------------------------+----+------------------------+
+| 31..13 | 12 | 11..0 |
++--------------------------------------+----+------------------------+
+| counter | SF | errno |
++--------------------------------------+----+------------------------+
The general idea is for "watchers" to sample an errseq_t value and keep
it as a running cursor. That value can later be used to tell whether
@@ -42,6 +45,7 @@ has ever been an error set since it was first initialized.
API usage
=========
+
Let me tell you a story about a worker drone. Now, he's a good worker
overall, but the company is a little...management heavy. He has to
report to 77 supervisors today, and tomorrow the "big boss" is coming in
@@ -125,6 +129,7 @@ not usable by anyone else.
Serializing errseq_t cursor updates
===================================
+
Note that the errseq_t API does not protect the errseq_t cursor during a
check_and_advance_operation. Only the canonical error code is handled
atomically. In a situation where more than one task might be using the
@@ -147,3 +152,8 @@ errseq_check_and_advance after taking the lock. e.g.::
That avoids the spinlock in the common case where nothing has changed
since the last time it was checked.
+
+Functions
+=========
+
+.. kernel-doc:: lib/errseq.c
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d5bbe035316d..1b1fd01990b5 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -14,6 +14,7 @@ Core utilities
kernel-api
assoc_array
atomic_ops
+ refcount-vs-atomic
cpu_hotplug
local_ops
workqueue
@@ -21,6 +22,8 @@ Core utilities
flexible-arrays
librs
genalloc
+ errseq
+ printk-formats
Interfaces for kernel debugging
===============================
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 2d9da6c40a4d..e7fadf02c511 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -139,6 +139,21 @@ Division Functions
.. kernel-doc:: lib/gcd.c
:export:
+Sorting
+-------
+
+.. kernel-doc:: lib/sort.c
+ :export:
+
+.. kernel-doc:: lib/list_sort.c
+ :export:
+
+UUID/GUID
+---------
+
+.. kernel-doc:: lib/uuid.c
+ :export:
+
Memory Management in Linux
==========================
diff --git a/Documentation/printk-formats.txt b/Documentation/core-api/printk-formats.rst
index aa0a776c817a..258b46435320 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
:Author: Randy Dunlap <rdunlap@infradead.org>
:Author: Andrew Murray <amurray@mpc-data.co.uk>
+
Integer types
=============
@@ -25,39 +26,45 @@ Integer types
s64 %lld or %llx
u64 %llu or %llx
-If <type> is dependent on a config option for its size (e.g., ``sector_t``,
-``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
-use a format specifier of its largest possible type and explicitly cast to it.
+
+If <type> is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
+format specifier of its largest possible type and explicitly cast to it.
Example::
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: sizeof() returns type size_t.
-The kernel's printf does not support ``%n``. For obvious reasons, floating
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
-Pointer Types
+Pointer types
=============
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The kernel also supports extended specifiers for printing
+pointers of different types.
+
+Plain Pointers
+--------------
::
%p abcdef12 or 00000000abcdef12
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+
Symbols/Function Pointers
-=========================
+-------------------------
::
@@ -69,6 +76,7 @@ Symbols/Function Pointers
%ps versatile_init
%pB prev_fn_of_versatile_init+0x88/0x88
+
The ``F`` and ``f`` specifiers are for printing function pointers,
for example, f->func, &gettimeofday. They have the same result as
``S`` and ``s`` specifiers. But they do an extra conversion on
@@ -77,14 +85,14 @@ are actually function descriptors.
The ``S`` and ``s`` specifiers can be used for printing symbols
from direct addresses, for example, __builtin_return_address(0),
-(void *)regs->ip. They result in the symbol name with (``S``) or
-without (``s``) offsets. If KALLSYMS are disabled then the symbol
+(void *)regs->ip. They result in the symbol name with (S) or
+without (s) offsets. If KALLSYMS are disabled then the symbol
address is printed instead.
The ``B`` specifier results in the symbol name with offsets and should be
used when printing stack backtraces. The specifier takes into
consideration the effect of compiler optimisations which may occur
-when tail-call``s are used and marked with the noreturn GCC attribute.
+when tail-calls are used and marked with the noreturn GCC attribute.
Examples::
@@ -97,33 +105,32 @@ Examples::
printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack);
Kernel Pointers
-===============
+---------------
::
%pK 01234567 or 0123456789abcdef
For printing kernel pointers which should be hidden from unprivileged
-users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see
+users. The behaviour of %pK depends on the kptr_restrict sysctl - see
Documentation/sysctl/kernel.txt for more details.
Unmodified Addresses
-====================
+--------------------
::
%px 01234567 or 0123456789abcdef
-For printing pointers when you _really_ want to print the address. Please
+For printing pointers when you *really* want to print the address. Please
consider whether or not you are leaking sensitive information about the
-Kernel layout in memory before printing pointers with %px. %px is
-functionally equivalent to %lx. %px is preferred to %lx because it is more
-uniquely grep'able. If, in the future, we need to modify the way the Kernel
-handles printing pointers it will be nice to be able to find the call
-sites.
+kernel memory layout before printing pointers with %px. %px is functionally
+equivalent to %lx (or %lu). %px is preferred because it is more uniquely
+grep'able. If in the future we need to modify the way the kernel handles
+printing pointers we will be better equipped to find the call sites.
Struct Resources
-================
+----------------
::
@@ -133,32 +140,37 @@ Struct Resources
[mem 0x0000000060000000-0x000000006fffffff pref]
For printing struct resources. The ``R`` and ``r`` specifiers result in a
-printed resource with (``R``) or without (``r``) a decoded flags member.
+printed resource with (R) or without (r) a decoded flags member.
+
Passed by reference.
-Physical addresses types ``phys_addr_t``
-========================================
+Physical address types phys_addr_t
+----------------------------------
::
%pa[p] 0x01234567 or 0x0123456789abcdef
-For printing a ``phys_addr_t`` type (and its derivatives, such as
-``resource_size_t``) which can vary based on build options, regardless of
-the width of the CPU data path. Passed by reference.
+For printing a phys_addr_t type (and its derivatives, such as
+resource_size_t) which can vary based on build options, regardless of the
+width of the CPU data path.
+
+Passed by reference.
-DMA addresses types ``dma_addr_t``
-==================================
+DMA address types dma_addr_t
+----------------------------
::
%pad 0x01234567 or 0x0123456789abcdef
-For printing a ``dma_addr_t`` type which can vary based on build options,
-regardless of the width of the CPU data path. Passed by reference.
+For printing a dma_addr_t type which can vary based on build options,
+regardless of the width of the CPU data path.
+
+Passed by reference.
Raw buffer as an escaped string
-===============================
+-------------------------------
::
@@ -168,8 +180,8 @@ For printing raw buffer as an escaped string. For the following buffer::
1b 62 20 5c 43 07 22 90 0d 5d
-few examples show how the conversion would be done (the result string
-without surrounding quotes)::
+A few examples show how the conversion would be done (excluding surrounding
+quotes)::
%*pE "\eb \C\a"\220\r]"
%*pEhp "\x1bb \C\x07"\x90\x0d]"
@@ -179,23 +191,23 @@ The conversion rules are applied according to an optional combination
of flags (see :c:func:`string_escape_mem` kernel documentation for the
details):
- - ``a`` - ESCAPE_ANY
- - ``c`` - ESCAPE_SPECIAL
- - ``h`` - ESCAPE_HEX
- - ``n`` - ESCAPE_NULL
- - ``o`` - ESCAPE_OCTAL
- - ``p`` - ESCAPE_NP
- - ``s`` - ESCAPE_SPACE
+ - a - ESCAPE_ANY
+ - c - ESCAPE_SPECIAL
+ - h - ESCAPE_HEX
+ - n - ESCAPE_NULL
+ - o - ESCAPE_OCTAL
+ - p - ESCAPE_NP
+ - s - ESCAPE_SPACE
By default ESCAPE_ANY_NP is used.
ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
printing SSIDs.
-If field width is omitted the 1 byte only will be escaped.
+If field width is omitted then 1 byte only will be escaped.
Raw buffer as a hex string
-==========================
+--------------------------
::
@@ -204,12 +216,12 @@ Raw buffer as a hex string
%*phD 00-01-02- ... -3f
%*phN 000102 ... 3f
-For printing a small buffers (up to 64 bytes long) as a hex string with
-certain separator. For the larger buffers consider to use
+For printing small buffers (up to 64 bytes long) as a hex string with a
+certain separator. For larger buffers consider using
:c:func:`print_hex_dump`.
MAC/FDDI addresses
-==================
+------------------
::
@@ -220,11 +232,11 @@ MAC/FDDI addresses
%pmR 050403020100
For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
-specifiers result in a printed address with (``M``) or without (``m``) byte
-separators. The default byte separator is the colon (``:``).
+specifiers result in a printed address with (M) or without (m) byte
+separators. The default byte separator is the colon (:).
Where FDDI addresses are concerned the ``F`` specifier can be used after
-the ``M`` specifier to use dash (``-``) separators instead of the default
+the ``M`` specifier to use dash (-) separators instead of the default
separator.
For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
@@ -234,7 +246,7 @@ of Bluetooth addresses which are in the little endian order.
Passed by reference.
IPv4 addresses
-==============
+--------------
::
@@ -243,8 +255,8 @@ IPv4 addresses
%p[Ii]4[hnbl]
For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
-specifiers result in a printed address with (``i4``) or without (``I4``)
-leading zeros.
+specifiers result in a printed address with (i4) or without (I4) leading
+zeros.
The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
host, network, big or little endian order addresses respectively. Where
@@ -253,7 +265,7 @@ no specifier is provided the default network/big endian order is used.
Passed by reference.
IPv6 addresses
-==============
+--------------
::
@@ -262,7 +274,7 @@ IPv6 addresses
%pI6c 1:2:3:4:5:6:7:8
For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
-specifiers result in a printed address with (``I6``) or without (``i6``)
+specifiers result in a printed address with (I6) or without (i6)
colon-separators. Leading zeros are always used.
The additional ``c`` specifier can be used with the ``I`` specifier to
@@ -272,7 +284,7 @@ http://tools.ietf.org/html/rfc5952
Passed by reference.
IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
-=========================================================
+---------------------------------------------------------
::
@@ -282,8 +294,8 @@ IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
%pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345
%p[Ii]S[pfschnbl]
-For printing an IP address without the need to distinguish whether it``s
-of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``,
+For printing an IP address without the need to distinguish whether it's of
+type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
specified through ``IS`` or ``iS``, can be passed to this format specifier.
The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
@@ -309,7 +321,7 @@ Further examples::
%pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789
UUID/GUID addresses
-===================
+-------------------