Add cross references for the documents mentioned at HOWTO and
are under the Documentation/ directory, using the ReST notation.

It should be noticed that HOWTO also mentions the /README file.
We opted to not touch it, for now, as making it build on
Sphinx would require it to be moved to a Documentation/foo
directory.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This one required lots of manual work, for it to be properly
displayed.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Do a few changes to make the output look better:

- use bullets on trivial patches list;
- use monotonic font for tools name;
- use :manpage:`foo` for man pages;
- don't put all references to maintainer*html at the same line.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- Change the sections to use ReST markup;
- Add cross-references where needed;
- convert aspas to verbatim text;
- use code block tags;
- make Sphinx happy.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- Change the document title markup to make it on a higher level;
- Add blank lines as needed, to improve the output;
- use italics for the country-code at kernel.org ftp URL.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add markups for it to be properly parsed by Sphinx.

As people browsing this document may not notice that the source
file title is "stable_api_nonsense", I opted to use bold to
the rationale for this document. I also found it better to
add a note when it says that the nonsense applies only to the
kABI/kAPI, and not to uAPI.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a name for the document and convert the sections to
ReST markups.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- Convert document name to ReST;
- Convert footnotes;
- Convert sections to ReST format;
- Don't use _foo_, as Sphinx doesn't support underline. Instead,
  use bold;
- While here, remove whitespaces at the end of lines.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There are two places there where there are notes that should
be highlighted. So, use the ReST note markup for such texts.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Sphinx doesn't accept underline markups by purpose.
While there are ways to support underline via CSS, this won't
be portable with non-html outputs.

As we want CodingStyle to do emphasis, replace _foo_ by **foo**,
using bold emphasis.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

On Sphinx/ReST notation, ``foo`` means that foo will be will be
marked as inline literal, effectively making it to be presented
as a monospaced font.

As we want this document to be parsed by Sphinx, instead of using
"foo", use ``foo`` for the names that are literal, because it is an
usual typographic convention to use monospaced fonts for functions
and language commands on documents, and we're following such
convention on the other ReST books.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- Fix all chapter identation;
- add c blocks where needed;
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

As discussed at linux-doc ML, the best is to keep all documents
backward compatible with Sphinx version 1.2, as it is the latest
version found on some distros like Debian.

All books currently support it.

Please notice that, while it mentions the eventual need of
XeLaTex and texlive to build pdf files, this is not a minimal
requirement, as one could just be interested on building html
documents. Also, identifying the minimal requirements for
texlive packages is not trivial, as each distribution seems to
use different criteria on grouping LaTex functionalities.

While here, update the current kernel version to 4.x.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- Fix chapter identation inconsistencies;
- Convert table to ReST format;
- use the right tag for bullets;
- Fix bold emphasis;
- mark blocks with :: tags;
- use verbatim font for files;
- make Sphinx happy
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This document is old: it is from Kernel v2.6.12 days.
Update it to the current status, and add a reference for the
linux-next tree.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- use the correct markup to identify each section;

- Add some blank lines for Sphinx to properly interpret
  the markups;

- Remove a blank space on some paragraphs;

- Fix the verbatim and bold markups;

- Cleanup the remaining errors to make Sphinx happy.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This document is almost compliant with ReST notation, but some
small adjustments are needed to make it parse properly by
Sphinx (mostly, add blank lines where needed).
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that the files at Documentation/development-process/
were converted to ReST, make create a book at Sphinx.

As we'll have other books related to the development process,
we'll add it as a sub-book.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that the documents were converted, rename them to .rst, as
this is needed by the Sphinx build logic.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This document is on good shape for ReST: all it was needed was
to fix the section markups, add a toctree, convert the tables
and add a few code/quote blocks.

While not strictly required, I opted to use lowercase for
the titles, just like the other books that were converted
to Sphinx.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

As we're about to use those two markups, add them to the
theme style overrride.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Multi-cpu support is useful to improve the performance of kdump in
some cases. So add the description of enable multi-cpu support in
dump-capture kernel.
Signed-off-by: NZhou Wenjian <zhouwj-fnst@cn.fujitsu.com>
Acked-by: NBaoquan He <bhe@redhat.com>
Acked-by: NXunlei Pang <xpang@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

nr_cpus can help to save memory. So we should remind user of it.
Signed-off-by: NZhou Wenjian <zhouwj-fnst@cn.fujitsu.com>
Acked-by: NBaoquan He <bhe@redhat.com>
Acked-by: NXunlei Pang <xpang@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix a type in example variable name.
Signed-off-by: NAndrey Smirnov <andrew.smirnov@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

No need to be be, just be should be sufficient.
Signed-off-by: NLaurent Navet <laurent.navet@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

So don't mention it.
Signed-off-by: NChristoph Hellwig <hch@lst.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The self.indexnode's tuple has changed in sphinx version 1.4, from a
former 4 element tuple to a 5 element tuple.

https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7cSigned-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fixed a -> an typo.
Signed-off-by: NRobert Foss <robert.foss@collabora.com>
Acked-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This is the driver API document, so the internal stuff is just noise here.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

It never made sense to keep these documents together; move each into its
own file.

Drop the section numbering on hsi.txt on its way to its own file.
Suggested-by: NSebastian Reichel <sre@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The HSI subsystem documentation was split across hsi.txt and the
device-drivers docbook.  Now that the latter has been converted to Sphinx,
pull in the HSI document so that it's all in one place.
Acked-by: NSebastian Reichel <sre@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This is a trivial fix to correct upper bound addresses to always be
inclusive. Previously, the majority of ranges specified were inclusive with a
small minority specifying an exclusive upper bound. This patch fixes this
inconsistency.
Signed-off-by: NLorenzo Stoakes <lstoakes@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The driver that used the 'nodisconnect' parameter was removed in
commit 565bae6a ("[SCSI] 53c7xx: kill driver"). Related documentation
was cleaned up in commit f37a7238 ("[SCSI] 53c7xx: fix removal
fallout"), except for the remaining two mentions that are removed here.
Signed-off-by: NFinn Thain <fthain@telegraphics.com.au>
Reviewed-by: NGeert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- The guide currently says to pad the structure to a multiple of
  64-bits. This is not necessary in cases where the structure contains
  no 64-bit types. Clarify this concept to avoid unnecessary padding.
- When using __u64 to hold user pointers, blindly trying to do a cast to
  a void __user * may generate a warning on 32-bit systems about a cast
  from an integer to a pointer of different size. There is a macro to
  deal with this which hides an ugly double cast. Add a reference to
  this macro.
Signed-off-by: NLaura Abbott <labbott@redhat.com>
Acked-by: NArnd Bergmann <arnd@arndb.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

To build only the PDF of the media folder run::

  make SPHINXDIRS=media pdfdocs
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This extends the method to build only sub-folders to the targets
"latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
required, where the latex_documents of the sub-folder are
defined. E.g. to build only gpu's PDF add the following to the
Documentation/gpu/conf.py::

  +latex_documents = [
  +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
  +     "The kernel development community", "manual"),
  +]

and run:

  make SPHINXDIRS=gpu pdfdocs
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The setup() function of a Sphinx-extension can return a dictionary. This
is treated by Sphinx as metadata of the extension [1].

With metadata "parallel_read_safe = True" a extension is marked as
save for "parallel reading of source". This is needed if you want
build in parallel with N processes. E.g.:

  make SPHINXOPTS=-j4 htmldocs

will no longer log warnings like:

  WARNING: the foobar extension does not declare if it is safe for
  parallel reading, assuming it isn't - please ask the extension author
  to check and make it explicit.

Add metadata to extensions:

* kernel-doc
* flat-table
* kernel-include

[1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadataSigned-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Tested-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

From the old description people still can't get what's the exact
difference between nr_cpus and maxcpus. Especially in kdump kernel
nr_cpus is always suggested if it's implemented in the ARCH. The
reason is nr_cpus is used to limit the max number of possible cpu
in system, the sum of already plugged cpus and hot plug cpus can't
exceed its value. However maxcpus is used to limit how many cpus
are allowed to be brought up during bootup.
Signed-off-by: NBaoquan He <bhe@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>