docs: Do not include from kernel/rcu/srcu.c

That file went away with commit bd8cc5a062f4 (srcu: Remove Classic SRCU)
during the 4.13 merge window, leading to errors like:

  Error: Cannot open file ./kernel/rcu/srcu.c

during the docs build.

Reported-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

scripts/kernel-doc: handle DECLARE_HASHTABLE

DECLARE_HASHTABLE needs similar handling to DECLARE_BITMAP
because otherwise kernel-doc assumes the member name is the
second, not first macro parameter.

Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: atomic_ops.txt is core-api/atomic_ops.rst

I was reading the memory barries documentation in order to make sure the
RISC-V barries were correct, and I found a broken link to the atomic
operations documentation.

Signed-off-by: Palmer Dabbelt <palmer@dabbelt.com>
Acked-by: 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: clean up some DocBook loose ends

There were a few bits and pieces left over from the now-disused DocBook
toolchain; git rid of them.

Reported-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Make the main documentation title less Geocities

This is probably the lamest patch ever, but then again "Welcome to The
Linux Kernel's documentation" is nearly equally lame. Really, we don't
need to "Welcome" people to the documentation, just tell them what the
site is about.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Docs: Use kernel-figure in vidioc-g-selection.rst

...otherwise the PDF build fails when it can't find constraints.pdf.

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

Docs: fix table problems in ras.rst

Two table problems caused the PDF build to fail:

 - Evidently multirow cells are not appreciated in table headers,
   so remove such from the "CS Rows" table.

 - The logging message structure table was incorrectly formatted,
   with two "+" instead of "|".  The HTML build is forgiving of such
   things, but PDF is not.

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

Docs: Fix breakage with Sphinx 1.5 and upper

Commit 85c21e5c3ee7 (docs-rst: better adjust margins and font size) added a
\usepackage{geometry} that conflicts with another inclusion deep within the
dependencies with newer versions of Sphinx, causing the the PDF build to fail
with a "conflicting parameters" error.

Detect the Sphinx version, using sphinxsetup for Sphinx versions 1.5 and
upper.

Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
[jc: Tweaked logic to exclude 1.5.x for x < 3 ]
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Docs: Include the Latex "ifthen" package

Otherwise we get PDF build failures when LaTeX refused to acknowledge the
existence of \ifthenelse

Fixes: 41cff161fe99d1c6a773becc2250a1dc3ac035ff
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc/kokr/howto: Only send regression fixes after -rc1

This commit applies commit 388f9b20f98d ("Documentation/process/howto:
Only send regression fixes after -rc1") to Korean translation.

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

docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters

Another place in lib/Kconfig.debug was already fixed in commit f8998c226587
("lib/Kconfig.debug: correct documentation paths").

Fixes: 9d85025b0418 ("docs-rst: create an user's manual book")
Signed-off-by: Steffen Maier <maier@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: Document suitability of IBM Verse for kernel development

IBM Verse is a web UI around Lotus Domino mail servers (much like
the Lotus Notes client talks to Domino servers).

For various reasons, it is not at all suitable for kernel development,
all of which have been raised (repeatedly) internally.

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>
Acked-by: Samuel Mendoza-Jonas <sam@mendozajonas.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Doc: fix a markup error in coding-style.rst

The "\n\t" sequence needs to be quoted or it will not render properly.

[jc: no signoff from the author, but it's trivial]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: driver-api: i2c: remove some outdated information

a) Linux can be an I2C slave meanwhile
b) all drivers except one use the driver model currently

Update the documentation.

Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: DMA API: fix a typo in a function name

Correct the typo, the wrongly typed function does not exist.

Fixes: 6c9c6d6301287e ("dma-debug: New interfaces to debug dma mapping errors")
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Docs: Insert missing space to separate link from text

Korean translation, there should be a space terminating the link.

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

doc/ko_KR/memory-barriers: Update control-dependencies example

This commit applies upstream change, commit b26cfc48e3e0 ("doc: Update
control-dependencies section of memory-barriers.txt"), to Korean
translation.

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

Merge remote-tracking branch 'mauro-exp/docbook3' into death-to-docbook

Mauro says:

This patch series convert the remaining DocBooks to ReST.

The first version was originally
send as 3 patch series:

   [PATCH 00/36] Convert DocBook documents to ReST
   [PATCH 0/5] Convert more books to ReST
   [PATCH 00/13] Get rid of DocBook

The lsm book was added as if it were a text file under
Documentation. The plan is to merge it with another file
under Documentation/security, after both this series and
a security Documentation patch series gets merged.

It also adjusts some Sphinx-pedantic errors/warnings on
some kernel-doc markups.

I also added some patches here to add PDF output for all
existing ReST books.

Documentation, kbuild: fix typo "minimun" -> "minimum"

Signed-off-by: Tobias Klauser <tklauser@distanz.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Fix some formatting issues in request-key.rst

The white space in the big enumerated list was inconsistent, leading to
some strange formatting artifacts.

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

doc: ReSTify keys-trusted-encrypted.txt

Adjusts for ReST markup and moves under keys security devel index.

Cc: David Howells <dhowells@redhat.com>
Cc: Mimi Zohar <zohar@linux.vnet.ibm.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify keys-request-key.txt

Adjusts for ReST markup and moves under keys security devel index.

Cc: David Howells <dhowells@redhat.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify keys-ecryptfs.txt

Adjusts for ReST markup and moves under keys security devel index.

Cc: David Howells <dhowells@redhat.com>
Cc: Tyler Hicks <tyhicks@canonical.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify keys.txt

This creates a new section in the security development index for kernel
keys, and adjusts for ReST markup.

Cc: David Howells <dhowells@redhat.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify Smack.txt

Adjusts for ReST markup and moves under LSM admin guide.

Acked-by: Casey Schaufler <casey@schaufler-ca.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify LoadPin.txt

Adjusts for ReST markup and moves under LSM admin guide.

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify Yama.txt

Adjusts for ReST markup and moves under LSM admin guide.

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify tomoyo.txt

Adjusts for ReST markup and moves under LSM admin guide.

Cc: Tetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify apparmor.txt

Adjusts for ReST markup and moves under LSM admin guide.

Acked-by: John Johansen <john.johansen@canonical.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify SELinux.txt

Adjusts for ReST markup and moves under LSM admin guide.

Cc: Paul Moore <paul@paul-moore.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify and split LSM.txt

The existing LSM.txt file covered both usage and development, so split
this into two files, one under admin-guide and one under kernel
development.

Cc: James Morris <james.l.morris@oracle.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: security: minor cleanups to build kernel-doc

These fixes were needed to parse lsm_hooks.h kernel-doc. More work is
needed, but this is the first step.

Acked-by: James Morris <james.l.morris@oracle.com>
Acked-by: Casey Schaufler <casey@schaufler-ca.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify self-protection.txt

This updates the credentials API documentation to ReST markup and moves
it under the security subsection of kernel API documentation.

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify credentials.txt

This updates the credentials API documentation to ReST markup and moves
it under the security subsection of kernel API documentation.

Cc: David Howells <dhowells@redhat.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify IMA-templates.txt

Adjust IMA-templates.txt for ReST markup and add to the index for
security/, under the Kernel API Documentation.

Cc: Mimi Zohar <zohar@linux.vnet.ibm.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify no_new_privs.txt

This updates no_new_privs documentation to ReST markup and adds it to
the user-space API documentation.

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ReSTify seccomp_filter.txt

This updates seccomp_filter.txt for ReST markup, and moves it under the
user-space API index, since it describes how application author can use
seccomp.

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: fix inline emphasis in unshare.rst

The asterisk of the pointer is interpreted as a start tag for inline
emphasis. Asterisks which are not Sphinx markup need to be quoted in
rst-files. This fixes the Sphinx warning:

Documentation/userspace-api/unshare.rst:108: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

core-api: remove an unexpected unident

As complained by Sphinx:
Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent.

This was already addressed, but not really fixed in 2ba90ccca7.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge tag 'v4.12-rc1' into docs-next

Linux 4.12-rc1

kernel-doc: describe the ``literal`` syntax

changeset b97f193abf83 ("scripts/kernel-doc: fix parser
for apostrophes") added support for ``literal`` inside
kernel-doc, in order to allow using the "%" symbol inside
a literal block, as this is used at printk() description.

Document it.

Fixes: b97f193abf83 ("scripts/kernel-doc: fix parser for apostrophes")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: get rid of Documentation/sphinx/tmplcvt script

As everything was converted to ReST, we don't need this
script anymore.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

usb: fix the comment with regards to DocBook

The USB gadget documentation is not at DocBook anymore.
The main file was converted to ReST, and stored at
Documentation/driver-api/usb/gadget.rst, but there are
still several plain text files related to gadget under
Documentation/usb.

So, be generic and just mention documentation
without specifying where it is.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

fs: fix the location of the kernel-api book

The kernel-api book is now part of the core-api. Update its
location.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

lib: update location of kgdb documentation

The documentation was moved from DocBook directory.
Update its location.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

fs: update location of filesystems documentation

The filesystem documentation was moved from DocBook to
Documentation/filesystems/. Update it at the sources.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

irq: update genericirq book location

This book got converted from DocBook. Update its references to
point to the current location.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

ia64, scsi: update references for the device-io book

The book is now at Documentation/driver-api/device-io.rst.
Update such references.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

ata: update references for libata documentation

The libata documentation is now using ReST. Update references
to it to point to the new place.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

MAINTAINERS: update old references for DocBook directory

As everything was converted, update the references to
point to the new places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs: update old references for DocBook from the documentation

DocBook is mentioned several times at the documentation. Update
the obsolete references from it at the DocBook.

Acked-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs: remove DocBook from the building system

Now that we don't have any DocBook anymore, remove it from
the building system.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert lsm from DocBook to ReST

This file is outdated. Still, as it is the only one left at
DocBook dir, convert it, and store it, with a .txt extension,
under Documentation/lsm.txt.

This way, we can get rid of DocBook from the building system,
without needing to wait for someone to take care of it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert sh book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings

./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found
./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation.
./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent.
./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation.
./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

mtdnand.rst: group the "::" with previous line

Group the :: with the previous paragraph, in order to make it
visually better when reading as a text file.

While here, replace:
ored (with means "Covered or adorned with ore or metal")
by:
OR-ed

To reflect its true meaning.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert mtdnand book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

The tables were manually adjusted to fit into 80 columns.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert librs book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert rapidio book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert w1 book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

scsi: fix some kernel-doc markups

Sphinx is very pedantic with regards to ident/spacing.
Fix some kernel-doc markups in order to solve those
errors/warnings:

./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string.
./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string.
./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string.
./drivers/scsi/scsi_scan.c:1056: ERROR: Unexpected indentation.
./drivers/scsi/scsi_scan.c:1057: WARNING: Block quote ends without a blank line; unexpected unindent.
./drivers/scsi/scsi_transport_fc.c:2918: ERROR: Unexpected indentation.
./drivers/scsi/scsi_transport_fc.c:2921: WARNING: Block quote ends without a blank line; unexpected unindent.
./drivers/scsi/scsi_transport_fc.c:2922: WARNING: Enumerated list ends without a blank line; unexpected unindent.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert scsi DocBook to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert z8530book DocBook to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Some manual adjustments were required due to some
conversion error on some literals.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

net: fix some identation issues at kernel-doc markups

Sphinx is very pedantic with regards to identation and
escape sequences:

  ./include/net/sock.h:1967: ERROR: Unexpected indentation.
  ./include/net/sock.h:1969: ERROR: Unexpected indentation.
  ./include/net/sock.h:1970: WARNING: Block quote ends without a blank line; unexpected unindent.
  ./include/net/sock.h:1971: WARNING: Block quote ends without a blank line; unexpected unindent.
  ./include/net/sock.h:2268: WARNING: Inline emphasis start-string without end-string.
  ./net/core/sock.c:2686: ERROR: Unexpected indentation.
  ./net/core/sock.c:2687: WARNING: Block quote ends without a blank line; unexpected unindent.
  ./net/core/datagram.c:182: WARNING: Inline emphasis start-string without end-string.
  ./include/linux/netdevice.h:1444: ERROR: Unexpected indentation.
  ./drivers/net/phy/phy.c:381: ERROR: Unexpected indentation.
  ./drivers/net/phy/phy.c:382: WARNING: Block quote ends without a blank line; unexpected unindent.

- Fix spacing where needed;
- Properly escape constants;
- Use a literal block for a race description.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

net: skbuff.h: properly escape a macro name on kernel-doc

The "%" escape code of kernel-doc only handle letters. It
doesn't handle special chars. So, use the ``literal``
notation. That fixes this warning:

./include/linux/skbuff.h:2695: WARNING: Inline literal start-string without end-string.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert networking book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert s390-drivers DocBook to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Acked-by: Cornelia Huck <cornelia.huck@de.ibm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

libata: fix identation on a kernel-doc markup

Sphinx got confused with the markup identation:
./drivers/ata/libata-scsi.c:3402: ERROR: Unexpected indentation.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

libata.rst: add c function and struct cross-references

Instead of just using text for functions and structs, use
the C domain tags, in order to allow cross-referencing with
the kernel-doc markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert libata book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

fs: jbd2: escape a string with special chars on a kernel-doc

kernel-doc will try to interpret a foo() string, except if
properly escaped.

Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

fs: eventfd: fix identation on kernel-doc

Sphinx require explicit tags in order to use a list of possible
values, otherwise it produces this error:

./fs/eventfd.c:219: WARNING: Option list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

fs: add a blank lines on some kernel-doc comments

Sphinx gets confused when it finds identation without a
good reason for it and without a preceding blank line:

./fs/mpage.c:347: ERROR: Unexpected indentation.
./fs/namei.c:4303: ERROR: Unexpected indentation.
./fs/fs-writeback.c:2060: ERROR: Unexpected indentation.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: don't ignore internal functions for jbd2 docs

Those functions are currently ignored, causing references at
the documentation to be lost. Don't ignore it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

fs: jbd2: make jbd2_journal_start() kernel-doc parseable

kernel-doc script expects that a function documentation to
be just before the function, otherwise it will be ignored.

So, move the kernel-doc markup to the right place.

Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: filesystems: use c domain references where needed

Instead of just mention the function names, use cross-references
to the kernel-doc tags where pertinent.

While not all function documentation is included here, I
double-checked that all functions mentioned there still
exists.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert filesystems book to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: add userspace API book to pdf output

The userspace API book was added without the bits required to
generate PDF output. Add them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: add sound book to pdf output

The sound subsystem book was added without the bits required to
generate PDF output. Add them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: add dev-tools book to pdf output

The dev-tools API book was added without the bits required to
generate PDF output at the main conf.py. Add them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: add crypto API book to pdf output

The crypto API book was added without the bits required to
generate PDF output. Add them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: conf.py: remove kernel-documentation from LaTeX

There's no kernel-documentation.rst file at Documentation/
anymore. So, remove it from the list of LaTeX-generated
documents.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: conf.py: sort LaTeX documents in alphabetical order

As we add more documents, it makes more sense to sort the
entries there in alphabetical order, as it makes easier to
check if something is not there.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

conf.py: define a color for important markup on PDF output

As kdbg.rst uses the ".. important::" annotation, let's define a
color for PDF output.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

kgdb.rst: Adjust ReST markups

The automatic conversion didn't work too well for this file.
It added weird html blocks inside it, and did some weird
things for literals. Manually fix it, in order to present
a nice display at html/pdf outputs.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert kgdb DocBook to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

locking.rst: Update some ReST markups

Correct a few minor issues with ReST notation used on
this file (produced by an automatic tool).

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

locking.rst: add captions to two tables

Those tables have a "caption" at the end, but ReST
actually expects it on a different way.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

locking.rst: reformat locking table

Use a different markup for this table, in order to make it
smaller when seeing in text mode.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

mutex, futex: adjust kernel-doc markups to generate ReST

There are a few issues on some kernel-doc markups that was
causing troubles with kernel-doc output on ReST format:

./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string.
./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent.

Fix them.

No functional changes.

Acked-by: Darren Hart (VMware) <dvhart@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert kernel-locking to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

- Manually adjust tables with got broken by conversion

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

kernel-hacking: update document

This document is fairly updated. Yet, some stuff moved to
other kernel headers. So, update to point to the right
places.

While here, adjust some minor ReST markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: convert kernel-hacking to ReST

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

- Manually adjusted to use ..note and ..warning
- Minor fixes for it to be parsed without errors
- Use **bold** for emphasis.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Linux 4.12-rc1

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

Pull some more input subsystem updates from Dmitry Torokhov:
 "An updated xpad driver with a few more recognized device IDs, and a
  new psxpad-spi driver, allowing connecting Playstation 1 and 2 joypads
  via SPI bus"

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input:
  Input: cros_ec_keyb - remove extraneous 'const'
  Input: add support for PlayStation 1/2 joypads connected via SPI
  Input: xpad - add USB IDs for Mad Catz Brawlstick and Razer Sabertooth
  Input: xpad - sync supported devices with xboxdrv
  Input: xpad - sort supported devices by USB ID

Merge tag 'upstream-4.12-rc1' of git://git.infradead.org/linux-ubifs

Pull UBI/UBIFS updates from Richard Weinberger:

 - new config option CONFIG_UBIFS_FS_SECURITY

 - minor improvements

 - random fixes

* tag 'upstream-4.12-rc1' of git://git.infradead.org/linux-ubifs:
  ubi: Add debugfs file for tracking PEB state
  ubifs: Fix a typo in comment of ioctl2ubifs & ubifs2ioctl
  ubifs: Remove unnecessary assignment
  ubifs: Fix cut and paste error on sb type comparisons
  ubi: fastmap: Fix slab corruption
  ubifs: Add CONFIG_UBIFS_FS_SECURITY to disable/enable security labels
  ubi: Make mtd parameter readable
  ubi: Fix section mismatch

Merge branch 'for-linus-4.12-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rw/uml

Pull UML fixes from Richard Weinberger:
 "No new stuff, just fixes"

* 'for-linus-4.12-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rw/uml:
  um: Add missing NR_CPUS include
  um: Fix to call read_initrd after init_bootmem
  um: Include kbuild.h instead of duplicating its macros
  um: Fix PTRACE_POKEUSER on x86_64
  um: Set number of CPUs
  um: Fix _print_addr()

Merge branch 'akpm' (patches from Andrew)

Merge misc fixes from Andrew Morton:
 "15 fixes"

* emailed patches from Andrew Morton <akpm@linux-foundation.org>:
  mm, docs: update memory.stat description with workingset* entries
  mm: vmscan: scan until it finds eligible pages
  mm, thp: copying user pages must schedule on collapse
  dax: fix PMD data corruption when fault races with write
  dax: fix data corruption when fault races with write
  ext4: return to starting transaction in ext4_dax_huge_fault()
  mm: fix data corruption due to stale mmap reads
  dax: prevent invalidation of mapped DAX entries
  Tigran has moved
  mm, vmalloc: fix vmalloc users tracking properly
  mm/khugepaged: add missed tracepoint for collapse_huge_page_swapin
  gcov: support GCC 7.1
  mm, vmstat: Remove spurious WARN() during zoneinfo print
  time: delete current_fs_time()
  hwpoison, memcg: forcibly uncharge LRU pages

mm, docs: update memory.stat description with workingset* entries

Commit 4b4cea91691d ("mm: vmscan: fix IO/refault regression in cache
workingset transition") introduced three new entries in memory stat
file:

 - workingset_refault
 - workingset_activate
 - workingset_nodereclaim

This commit adds a corresponding description to the cgroup v2 docs.

Link: http://lkml.kernel.org/r/1494530293-31236-1-git-send-email-guro@fb.com
Signed-off-by: Roman Gushchin <guro@fb.com>
Cc: Johannes Weiner <hannes@cmpxchg.org>
Cc: Michal Hocko <mhocko@kernel.org>
Cc: Vladimir Davydov <vdavydov.dev@gmail.com>
Cc: Tejun Heo <tj@kernel.org>
Cc: Li Zefan <lizefan@huawei.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

mm: vmscan: scan until it finds eligible pages

Although there are a ton of free swap and anonymous LRU page in elgible
zones, OOM happened.

  balloon invoked oom-killer: gfp_mask=0x17080c0(GFP_KERNEL_ACCOUNT|__GFP_ZERO|__GFP_NOTRACK), nodemask=(null),  order=0, oom_score_adj=0
  CPU: 7 PID: 1138 Comm: balloon Not tainted 4.11.0-rc6-mm1-zram-00289-ge228d67e9677-dirty #17
  Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS Ubuntu-1.8.2-1ubuntu1 04/01/2014
  Call Trace:
   oom_kill_process+0x21d/0x3f0
   out_of_memory+0xd8/0x390
   __alloc_pages_slowpath+0xbc1/0xc50
   __alloc_pages_nodemask+0x1a5/0x1c0
   pte_alloc_one+0x20/0x50
   __pte_alloc+0x1e/0x110
   __handle_mm_fault+0x919/0x960
   handle_mm_fault+0x77/0x120
   __do_page_fault+0x27a/0x550
   trace_do_page_fault+0x43/0x150
   do_async_page_fault+0x2c/0x90
   async_page_fault+0x28/0x30
  Mem-Info:
  active_anon:424716 inactive_anon:65314 isolated_anon:0
   active_file:52 inactive_file:46 isolated_file:0
   unevictable:0 dirty:27 writeback:0 unstable:0
   slab_reclaimable:3967 slab_unreclaimable:4125
   mapped:133 shmem:43 pagetables:1674 bounce:0
   free:4637 free_pcp:225 free_cma:0
  Node 0 active_anon:1698864kB inactive_anon:261256kB active_file:208kB inactive_file:184kB unevictable:0kB isolated(anon):0kB isolated(file):0kB mapped:532kB dirty:108kB writeback:0kB shmem:172kB writeback_tmp:0kB unstable:0kB all_unreclaimable? no
  DMA free:7316kB min:32kB low:44kB high:56kB active_anon:8064kB inactive_anon:0kB active_file:0kB inactive_file:0kB unevictable:0kB writepending:0kB present:15992kB managed:15908kB mlocked:0kB slab_reclaimable:464kB slab_unreclaimable:40kB kernel_stack:0kB pagetables:24kB bounce:0kB free_pcp:0kB local_pcp:0kB free_cma:0kB
  lowmem_reserve[]: 0 992 992 1952
  DMA32 free:9088kB min:2048kB low:3064kB high:4080kB active_anon:952176kB inactive_anon:0kB active_file:36kB inactive_file:0kB unevictable:0kB writepending:88kB present:1032192kB managed:1019388kB mlocked:0kB slab_reclaimable:13532kB slab_unreclaimable:16460kB kernel_stack:3552kB pagetables:6672kB bounce:0kB free_pcp:56kB local_pcp:24kB free_cma:0kB
  lowmem_reserve[]: 0 0 0 959
  Movable free:3644kB min:1980kB low:2960kB high:3940kB active_anon:738560kB inactive_anon:261340kB active_file:188kB inactive_file:640kB unevictable:0kB writepending:20kB present:1048444kB managed:1010816kB mlocked:0kB slab_reclaimable:0kB slab_unreclaimable:0kB kernel_stack:0kB pagetables:0kB bounce:0kB free_pcp:832kB local_pcp:60kB free_cma:0kB
  lowmem_reserve[]: 0 0 0 0
  DMA: 1*4kB (E) 0*8kB 18*16kB (E) 10*32kB (E) 10*64kB (E) 9*128kB (ME) 8*256kB (E) 2*512kB (E) 2*1024kB (E) 0*2048kB 0*4096kB = 7524kB
  DMA32: 417*4kB (UMEH) 181*8kB (UMEH) 68*16kB (UMEH) 48*32kB (UMEH) 14*64kB (MH) 3*128kB (M) 1*256kB (H) 1*512kB (M) 2*1024kB (M) 0*2048kB 0*4096kB = 9836kB
  Movable: 1*4kB (M) 1*8kB (M) 1*16kB (M) 1*32kB (M) 0*64kB 1*128kB (M) 2*256kB (M) 4*512kB (M) 1*1024kB (M) 0*2048kB 0*4096kB = 3772kB
  378 total pagecache pages
  17 pages in swap cache
  Swap cache stats: add 17325, delete 17302, find 0/27
  Free swap  = 978940kB
  Total swap = 1048572kB
  524157 pages RAM
  0 pages HighMem/MovableOnly
  12629 pages reserved
  0 pages cma reserved
  0 pages hwpoisoned
  [ pid ]   uid  tgid total_vm      rss nr_ptes nr_pmds swapents oom_score_adj name
  [  433]     0   433     4904        5      14       3       82             0 upstart-udev-br
  [  438]     0   438    12371        5      27       3      191         -1000 systemd-udevd

With investigation, skipping page of isolate_lru_pages makes reclaim
void because it returns zero nr_taken easily so LRU shrinking is
effectively nothing and just increases priority aggressively.  Finally,
OOM happens.

The problem is that get_scan_count determines nr_to_scan with eligible
zones so although priority drops to zero, it couldn't reclaim any pages
if the LRU contains mostly ineligible pages.

get_scan_count:

        size = lruvec_lru_size(lruvec, lru, sc->reclaim_idx);
size = size >> sc->priority;

Assumes sc->priority is 0 and LRU list is as follows.

N-N-N-N-H-H-H-H-H-H-H-H-H-H-H-H-H-H-H-H

(Ie, small eligible pages are in the head of LRU but others are
 almost ineligible pages)

In that case, size becomes 4 so VM want to scan 4 pages but 4 pages from
tail of the LRU are not eligible pages.  If get_scan_count counts
skipped pages, it doesn't reclaim any pages remained after scanning 4
pages so it ends up OOM happening.

This patch makes isolate_lru_pages try to scan pages until it encounters
eligible zones's pages.

[akpm@linux-foundation.org: clean up mind-bending `for' statement.  Tweak comment text]
Fixes: 3db65812d688 ("Revert "mm, vmscan: account for skipped pages as a partial scan"")
Link: http://lkml.kernel.org/r/1494457232-27401-1-git-send-email-minchan@kernel.org
Signed-off-by: Minchan Kim <minchan@kernel.org>
Acked-by: Michal Hocko <mhocko@suse.com>
Acked-by: Johannes Weiner <hannes@cmpxchg.org>
Cc: Mel Gorman <mgorman@techsingularity.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>