Commit 255442c9 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

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
  ...
parents d76e0a05 ae17a87d

Documentation/00-INDEX

+0 −4
Original line number Diff line number Diff line
@@ -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/

Documentation/admin-guide/kernel-parameters.txt

+3 −0
Original line number Diff line number Diff line
@@ -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

Documentation/admin-guide/mono.rst

+3 −3
Original line number Diff line number Diff line
@@ -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

Documentation/conf.py

+0 −1
Original line number Diff line number Diff line
@@ -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

Documentation/errseq.rst→Documentation/core-api/errseq.rst

+15 −5
Original line number Diff line number Diff line 
=====================

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

    +-----------------+----+----------------+

+--------------------------------------+----+------------------------+

| 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

CRA Git | Maintained and supported by SUSTech CRA and CCSE