parse-headers.pl: add documentation for this script

Provide a man page for parse-headers.pl, describing
how to use it.

The documentation on ReST format was generated via pod2rst:
http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: doc-guide: split the kernel-documentation.rst contents

Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge remote-tracking branch 'sound/topic/restize-docs' into sound

Bring in the sphinxification of the sound documentation.

Merge tag 'v4.9-rc4' into sound

Bring in -rc4 patches so I can successfully merge the sound doc changes.

kernel-doc: add support for one line inline struct member doc comments

kernel-doc supports documenting struct members "inline" since
a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:

/**
 * struct foo - struct documentation
 */
struct foo {
/**
 * @bar: member documentation
 */
int bar;
};

Add support for one line inline comments:

/**
 * struct foo - struct documentation
 */
struct foo {
/** @bar: member documentation */
int bar;
};

Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.

Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs/completion.txt: drop dangling reference to completions-design.txt

Per the original author, the proposed document was never deemed
necessary, and the important bits got merged into completion.txt. Let's
just stop confusing readers by pointing at a nonexistent doc.

Signed-off-by: Brian Norris <briannorris@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: convert USB to new format

This is a conversion of the USB documentation to the Sphinx format.
No content was altered or reformatted.

Signed-off-by: Oliver <oneukum@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: circular-buffers: use READ_ONCE()

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the circular buffer documentation uses the latter
exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use
READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
circular buffer documentation.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Acked-by: David Howells <dhowells@redhat.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: atomic_ops: use {READ,WRITE}_ONCE()

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Will Deacon <will.deacon@arm.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Add more manuals to the PDF build

There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'mauro-pdf' into docs-next

Mauro says:

This series address a series of errors during PDF generation from
media documentation.

The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.

The next two patches fix PDF output issues with subdev-formats.rst.

The next 3 patches fix image includes and their output for PDF.

It is aligned with Linus request of not having binary-generated images
from their SVG source codes.

I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.

It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.

[jc: added a commit fixing up a "make cleandocs" warning]

docs: Avoid warning on cleandocs

Recent Makefile changes added an rm command without the requisite "-f",
leading to warnings if the files do not exist.  Make it be quiet again.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: auto-generate PDF image files

The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: convert gif files to png

Right now, media is using two different formats for bitmap
images: GIF and PNG. Let's use just one, to make it simpler when
building with Sphinx.

As PNG is usually better than GIF, let's use it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

convert some images from png to svg

SVG images are nicer, as they can easily be scaled. Also, they're
written in text, with makes easier to work.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

subdev-formats.rst: add missing columns to tabularcolumns

There are several missing columns on the size specification,
causing LaTeX to complain on interactive mode.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

subdev-formats.rst: don't use adjustbox on a longtable

adjustbox doesn't work on longtables. Also, this
causes an error on LaTeX in interactive mode.

So, use, instead, a tiny font.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+

PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.

The solution is to redefine the \DURole macro.

However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.

Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -C Documentation/output/./latex

Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

MAINTAINERS: The Chinese documentation moved

Update the F: line accordingly.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: Add HOWTO Korean translation into rst based build system

This commit adds Korean translation of HOWTO document into rst based
documentation build system.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: Move translations into a sub-directory

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs/driver-api: Apply changed source file names

Few files under dma-buf/ changed their names but the changes didn't
applied to a document that referencing them.  It is causing few
documentation build warnings.  This commit fixes the problems by
applying changed file names on the document.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ASoC: doc: ReSTize codec_to_codec.txt

Yet another simple conversion from a plain text file.
Renamed to codec-to-codec.rst to align with others.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

Merge branch 'topic/doc' of git://git./linux/kernel/git/broonie/sound into topic/restize-docs

ASoC: doc: ReSTize DPCM.txt

A simple conversion from a plain text file.
The file name was renamed to lower letters to align with others.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize jack.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize clocking.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize pops_clicks.txt

A simple conversion from a plain text file.
The file name was changed from "pops_clicks" to "pops-clicks" to align
with others.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize machine.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize platform.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize dapm.txt

A simple conversion from a plain text file.
The section numbers and the item numbers are dropped to align with the
ReST format.  Some lists are converted to description lists to be
clearer.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize DAI.txt

A simple conversion from a plain text file with slight reformatting /
corrections.

The file name was changed to lower letters to align with others.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize codec.txt

A simple conversion from a plain text file.
The section numbers are dropped to align with other documents.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ASoC: doc: ReSTize overview.txt

A simple conversion from a plain text file.
Created a new subdirectory, Documentation/sound/soc, for this and
other ASoC documents.

Since the index page contains the TOC, so "Documentation" section got
removed from overview.

Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize img,spdif-in.txt

Yet another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize serial-u16550.txt

Yet another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize hdspm.txt

A simple conversion from a plain text file.  Quite a few reformatting
in the end due to the style of the original document.

Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize README.maya44

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Bt87x.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize MIXART.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Audiophile-USB.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize VIA82xx-mixer.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize emu10k1-jack.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Audigy-mixer.txt

Another simple conversion from a plain text file.
Put to cards subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize SB-Live-mixer document

Another simple conversion from a plain text file.
Put to cards subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize CMIPCI document

A simple conversion from a plain text file.
Put to cards subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Joystick document

A conversion from a simple text file.
A new subdirectory, cards, was created to contain the card-specific
information like this one.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Jack-Controls.txt

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize timestamping document

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize compress-offload document

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize ControlNames.txt

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize seq_oss document

Converted from an ancient plain HTML document. It's much readable now!
Put to designs subdirectory with a slight rename.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize OSS-Emulation document

A simple conversion from a text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Channel-Mapping-API document

A simple conversion from a text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize powersave document

A simple conversion from a text file.
Put into designs subdirectory, although it's mostly relevant with
HD-audio.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize Procfile document

A simple conversion from a text file.

A new subidrectory, Documentation/sound/designs, was created to put
this document.  The other API design and implementation docuemnts
will be put to that directory in later commits.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize ALSA-Configuration document

A simple conversion from the text file.

Since this is the only document specific to the configurations, it's
put to the root sound subdirectory.

A section describing the obsoleted configure stuff of old alsa-driver
tarball got removed.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize HD-Audio-DP-MST-audio.txt

A simple conversion from a plain text file.
Put to hd-audio subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize HD-Audio-Controls document

A conversion from a simple text file.
Put to hd-audio subdirectory with a rename.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize HD-Audio-Models document

A simple reformat with the description list of ReST, and the content
was kept as is, but renamed as Documentation/sound/hd-audio/models.rst.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize HD-Audio document

The original HD-Audio.txt was already in asciidoc format, so it's a
simple conversion in the end.

A new subdirectory, Documentation/sound/hd-audio, is created and the
document is moved there with another file name to match better with
the recent Documentation tree structure.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize writing-an-alsa-driver document

Another simple conversion from DocBook to ReST.
This required a few manual fixups and reformats, but the most of
contents are kept as is.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: ReSTize alsa-driver-api document

A simple conversion of alsa-driver-api document from DocBook to ReST.

It's moved to the new Documentation/sound/kernel-api subdirectory that
will contain other ALSA kernel API documents.

The GPL legal note was removed, as it's superfluous (and doesn't fit
with ReST kernel docs pretty well).

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: doc: Remove alsa-parameters.txt

This is a really obsoleted information, effectively just listing the
module names.  Let's get rid of it for avoiding confusions.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

USB: fix typo in documentation

A typo sneaked in the latest change on the USB documentation. Fixing it
and also a trailing whitespace since it is also in the "USB Host-Side API
Model" chapter.

Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com>

coding-style: fix mismatch of jump label name

Commit 865a1caa4b6b ("CodingStyle: Clarify and complete chapter 7")
renamed the label "out_buffer" to "out_free_buffer", but missed to
change this line.

Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: make cleandocs misses a fair number of files

Removes intermediate 'Documentation/DocBook/.*.xml.cmd' files

Changes since v1:
- Reduce the patch to DocBook cleandocs

References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.com
Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'tpm' into docs-next

tpm: move documentation under Documentation/security

In order too make Documentation root directory cleaner move the tpm
directory under Documentation/security.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

tpm: transition tpm_vtpm_proxy documentation to the Sphinx

Transitioned the tpm_vtpm_proxy documentation to the Sphinx
infrastructure and removed parts from the documentation that are easier
to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c
to be compatible with this approach and wrote associated documentation
comments.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Doc: update kselftest.txt with details on how to run tests after install

Update kselftest.txt with details on how to run tests after install.

Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Fix a PDF build error in bug-bisect.rst

It seems we can't have literal blocks in footnotes, which almost actually
makes some sense.  So just use basic ``monospace`` instead.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'sphinx-fixes-for-docs-next' of git://people.freedesktop.org/~jani/drm into test

A set of PDF and other docs related fixes from Jani.

ko_KR/HOWTO: Mark subsection in suggested format

`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format.  This commit marks
them in the format.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Add whitespace between URL and text

Because few sentences has no whitespace between URL and text, few
document viewers fail to properly parse the URL from it.  This commit
adds whitespace between them to fix the problem.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Clean up bare :: lines

This commit applies commit 1b49ecf2f3be ("docs: Clean up bare :: lines")
to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Adjust external link references

This commit appplies commit f1eebe92c265 ("Documentation/HOWTO: adjust
external link references") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Improve some markups to make it visually better

This commit applies commit 34fed7e7e0e5 ("Documentation/HOWTO: improve
some markups to make it visually better") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Update information about generating documentation

This commit applies commit 43fb67a5258c ("Documentation/HOWTO: update
information about generating documentation") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Add cross-references to other documents

This commit applies commit 609d99a3b72e ("Documentation/HOWTO: add
cross-references to other documents") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Convert to ReST notation

This commit applies commit 022e04d6f555 ("Documentation/HOWTO: convert
to ReST notation") to Korean translation and fix a trivial ReST build
failure problem.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Update obsolete link to bugzilla faq

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Fix subtitles style

This commit fixes subtitles style.  It aligns them with their header,
adjust blank lines between them properly.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Fix a typo: s/Linux Torvalds/Linus Torvalds

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/process/howto: Mark subsection in suggested format

`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format.  This commit marks
them in the format.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

admin-guide: merge oops-tracing with bug-hunting

Now that oops-tracing.rst has only information about
stack dumps found on OOPS, and bug-hunting.rst has only
information about how to identify the source code line
associated with a stack dump, let's merge them and
improve the information inside it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

admin-guide: move tainted kernels info to a separate file

The tainted kernels info is not directly related to
the oops tracing. So, let's move it to a separate file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: admin-guide: move bug bisect to a separate file

Better organize the admin guide documentation by moving the
bug bisect to a separate file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

bug-hunting.rst: update info about bug hunting

The document shows a really old procedure for bug hunting that
nobody uses anymore. Remove such section, and update the
remaining documentation to reflect the procedures used
currently.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Linux 4.9-rc4

Merge branch 'i2c/for-current' of git://git./linux/kernel/git/wsa/linux

Pull i2c fix from Wolfram Sang:
 "A bugfix for the I2C core fixing a (rare) race condition"

* 'i2c/for-current' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux:
  i2c: core: fix NULL pointer dereference under race condition

Merge branches 'sched-urgent-for-linus' and 'core-urgent-for-linus' of git://git./linux/kernel/git/tip/tip

Pull stack vmap fixups from Thomas Gleixner:
 "Two small patches related to sched_show_task():

   - make sure to hold a reference on the task stack while accessing it

   - remove the thread_saved_pc printout

  .. and add a sanity check into release_task_stack() to catch problems
  with task stack references"

* 'sched-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
  sched/core: Remove pointless printout in sched_show_task()
  sched/core: Fix oops in sched_show_task()

* 'core-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
  fork: Add task stack refcounting sanity check and prevent premature task stack freeing

Merge tag 'md/4.9-rc3' of git://git./linux/kernel/git/shli/md

Pull MD fixes from Shaohua Li:
 "There are several bug fixes queued:

   - fix raid5-cache recovery bugs

   - fix discard IO error handling for raid1/10

   - fix array sync writes bogus position to superblock

   - fix IO error handling for raid array with external metadata"

* tag 'md/4.9-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/shli/md:
  md: be careful not lot leak internal curr_resync value into metadata. -- (all)
  raid1: handle read error also in readonly mode
  raid5-cache: correct condition for empty metadata write
  md: report 'write_pending' state when array in sync
  md/raid5: write an empty meta-block when creating log super-block
  md/raid5: initialize next_checkpoint field before use
  RAID10: ignore discard error
  RAID1: ignore discard error

Merge tag 'scsi-fixes' of git://git./linux/kernel/git/jejb/scsi

Pull SCSI fixes from James Bottomley:
 "Two more important data integrity fixes related to RAID device drivers
  which wrongly throw away the SYNCHRONIZE CACHE command in the non-RAID
  path and a memory leak in the scsi_debug driver"

* tag 'scsi-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi:
  scsi: arcmsr: Send SYNCHRONIZE_CACHE command to firmware
  scsi: scsi_debug: Fix memory leak if LBP enabled and module is unloaded
  scsi: megaraid_sas: Fix data integrity failure for JBOD (passthrough) devices

Merge branch 'for-linus' of git://git./linux/kernel/git/dtor/input

Pull input subsystem updates from Dmitry Torokhov.

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input:
  Input: psmouse - cleanup Focaltech code
  Input: i8042 - add XMG C504 to keyboard reset table

Merge tag 'firewire-fixes' of git://git./linux/kernel/git/ieee1394/linux1394

Pull FireWire (IEEE 1394) fixes from Stefan Richter:

 - add missing input validation to the firewire-net driver. Invalid
   IP-over-1394 encapsulation headers could trigger buffer overflows
   (CVE 2016-8633).

 - IP-over-1394 link fragmentation headers were read and written
   incorrectly, breaking fragmented RX/TX with other OS's stacks.

* tag 'firewire-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/ieee1394/linux1394:
  firewire: net: fix fragmented datagram_size off-by-one
  firewire: net: guard against rx buffer overflows

Merge tag 'media/v4.9-3' of git://git./linux/kernel/git/mchehab/linux-media

Pull media fixes from Mauro Carvalho Chehab:
 "A series of fixup patches meant to fix the usage of DMA on stack, plus
  one warning fixup"

* tag 'media/v4.9-3' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (32 commits)
  [media] radio-bcm2048: don't ignore errors
  [media] pctv452e: fix semicolon.cocci warnings
  [media] flexcop-usb: don't use stack for DMA
  [media] stk-webcam: don't use stack for DMA
  [media] s2255drv: don't use stack for DMA
  [media] cpia2_usb: don't use stack for DMA
  [media] digitv: handle error code on RC query
  [media] dw2102: return error if su3000_power_ctrl() fails
  [media] nova-t-usb2: handle error code on RC query
  [media] technisat-usb2: use DMA buffers for I2C transfers
  [media] pctv452e: don't call BUG_ON() on non-fatal error
  [media] pctv452e: don't do DMA on stack
  [media] nova-t-usb2: don't do DMA on stack
  [media] gp8psk: don't go past the buffer size
  [media] gp8psk: don't do DMA on stack
  [media] dtv5100: don't do DMA on stack
  [media] dtt200u: handle USB control message errors
  [media] dtt200u: don't do DMA on stack
  [media] dtt200u-fe: handle errors on USB control messages
  [media] dtt200u-fe: don't do DMA on stack
  ...

Merge tag 'pci-v4.9-fixes-2' of git://git./linux/kernel/git/helgaas/pci

Pull PCI fixes from Bjorn Helgaas:

 - fix for a Qualcomm driver issue that causes a use-before-set crash

 - fix for DesignWare iATU unroll support that causes external aborts
   when enabling the host bridge

* tag 'pci-v4.9-fixes-2' of git://git.kernel.org/pub/scm/linux/kernel/git/helgaas/pci:
  PCI: designware: Check for iATU unroll support after initializing host
  PCI: qcom: Fix pp->dev usage before assignment

Merge tag 'for-linus-20161104' of git://git.infradead.org/linux-mtd

Pull MTD fixes from Brian Norris:

 - MAINTAINERS updates to reflect some new maintainers/submaintainers.

   We have some great volunteers who've been developing and reviewing
   already. We're going to try a group maintainership model, so
   eventually you'll probably see pull requests from people besides me.

 - NAND fixes from Boris:
    "Three simple fixes:

      - fix a non-critical bug in the gpmi driver
      - fix a bug in the 'automatic NAND timings selection' feature
        introduced in 4.9-rc1
      - fix a false positive uninitialized-var warning"

* tag 'for-linus-20161104' of git://git.infradead.org/linux-mtd:
  mtd: mtk: avoid warning in mtk_ecc_encode
  mtd: nand: Fix data interface configuration logic
  mtd: nand: gpmi: disable the clocks on errors
  MAINTAINERS: add more people to the MTD maintainer team
  MAINTAINERS: add a maintainer for the SPI NOR subsystem

Merge tag 'mmc-v4.9-rc2' of git://git./linux/kernel/git/ulfh/mmc

Pull MMC fixes from Ulf Hansson:
 "MMC host:

   - sdhci-msm: Fix error path in probe
   - dw_mmc-pltfm: Avoid NULL pointer dereference"

* tag 'mmc-v4.9-rc2' of git://git.kernel.org/pub/scm/linux/kernel/git/ulfh/mmc:
  mmc: sdhci-msm: Fix error return code in sdhci_msm_probe()
  mmc: dw_mmc-pltfm: fix the potential NULL pointer dereference