Documentation/HOWTO: add cross-references to other documents

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/kernel-docs.txt: convert it to ReST markup

This one required lots of manual work, for it to be properly
displayed.

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

Documentation/SubmittingPatches: enrich the Sphinx output

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

Documentation/SubmittingPatches: convert it to ReST markup

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

Documentation/SubmittingDrivers: convert it to ReST markup

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

Documentation/stable_kernel_rules.txt: convert it to ReST markup

- 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/stable_api_nonsense.txt: convert it to ReST markup

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

Documentation/SecurityBugs: convert it to ReST markup

Add a name for the document and convert the sections to
ReST markups.

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

Documentation/ManagementStyle: convert it to ReST markup

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

Documentation/CodingStyle: use the .. note:: markup where needed

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

Documentation/CodingStyle: replace underline markups

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

Documentation/CodingStyle: use the proper tag for verbatim font

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

Documentation/CodingStyle: Convert to ReST markup

- Fix all chapter identation;
- add c blocks where needed;

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

Documentation/Changes: add minimal requirements for documentation build

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

Documentation/Changes: convert it to ReST markup

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

Documentation/applying-patches.txt: Update the information there

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

Documentation/applying-patches.txt: convert it to ReST markup

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

Documentation/HOWTO: convert to ReST notation

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

docs-rst: create a book for the development process

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

doc: development-process: rename files to rst

Now that the documents were converted, rename them to .rst, as
this is needed by the Sphinx build logic.

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

doc: development-process: convert it to ReST markup

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: add CSS styles for :kbd: and :menuselection:

As we're about to use those two markups, add them to the
theme style overrride.

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

Documentation: kdump: Add description of enable multi-cpus support

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: Zhou Wenjian <zhouwj-fnst@cn.fujitsu.com>
Acked-by: Baoquan He <bhe@redhat.com>
Acked-by: Xunlei Pang <xpang@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: kdump: Remind user of nr_cpus

nr_cpus can help to save memory. So we should remind user of it.

Signed-off-by: Zhou Wenjian <zhouwj-fnst@cn.fujitsu.com>
Acked-by: Baoquan He <bhe@redhat.com>
Acked-by: Xunlei Pang <xpang@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: DMA-API-HOWTO: Fix a typo

Fix a type in example variable name.

Signed-off-by: Andrey Smirnov <andrew.smirnov@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'driver-api' into doc/4.9

This short series convers device-drivers.tmpl into the RST format, splits
it up, and sets up the result under Documentation/driver-api/.  For added
fun, I've taken one top-level file (hsi.txt) and folded it into the
document as a way of showing the direction I'm thinking I would like things
to go.  There is plenty more of this sort of work that could be done, to
say the least - this is just a beginning!

The formatted results can be seen at:

    http://static.lwn.net/kerneldoc/driver-api/index.html

As part of the long-term task to turn Documentation/ into less of a horror
movie, I'd like to collect documentation of the driver-specific API here.
Arguably gpu/ and the media API stuff should eventually move here, though
we can discuss the color of that particular shed some other day.
Meanwhile, I'd appreciate comments on the general idea.

docs/driver-model: fix typo

No need to be be, just be should be sufficient.

Signed-off-by: Laurent Navet <laurent.navet@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

DMA-API-HOWTO: <asm/generic/scatterlist.h> is no more

So don't mention it.

Signed-off-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst:c-domain: function-like macros arguments

Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.

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

doc-rst:c-domain: fix sphinx version incompatibility

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/e6a5a3a92e938fcd75866b4227db9e0524d58f7c

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

Documentation/filesystems: Fixed typo

Fixed a -> an typo.

Signed-off-by: Robert Foss <robert.foss@collabora.com>
Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Don't format internal MPT docs

This is the driver API document, so the internal stuff is just noise here.

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

docs: split up serial-interfaces.rst

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: Sebastian Reichel <sre@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Pull the HSI documentation together

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: Sebastian Reichel <sre@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Special-case function-pointer parameters in kernel-doc

Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.

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

docs: make kernel-doc handle varargs properly

As far as I can tell, the handling of "..." arguments has never worked
right, so any documentation provided was ignored in favor of "variable
arguments."  This makes kernel-doc handle "@...:" as documented.  It does
*not* fix spots in kerneldoc comments that don't follow that convention,
but they are no more broken than before.

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

x86: fix memory ranges in mm documentation

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: Lorenzo Stoakes <lstoakes@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

documentation/scsi: Remove nodisconnect parameter

The driver that used the 'nodisconnect' parameter was removed in
commit 565bae6a4a8f ("[SCSI] 53c7xx: kill driver"). Related documentation
was cleaned up in commit f37a7238d379 ("[SCSI] 53c7xx: fix removal
fallout"), except for the remaining two mentions that are removed here.

Signed-off-by: Finn Thain <fthain@telegraphics.com.au>
Reviewed-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: ioctl: Add some clarifications to botching-up-ioctls

- 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: Laura Abbott <labbott@redhat.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: define PDF's of the media folder

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

  make SPHINXDIRS=media pdfdocs

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

doc-rst: generic way to build PDF of sub-folders

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: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinx-extensions: add metadata parallel-safe

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-metadata

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: kernel-doc: fix typedef output in RST format

When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);

The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.

So, a declaration like:

.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)

Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.

So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:

./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc

So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc

   **Typedef**: timings check callback

**Syntax**

  ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``

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

docs-rst: improve typedef parser

Improve the parser to handle typedefs like:

typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);

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

docs: kernel-parameter: Improve the description of nr_cpus and maxcpus

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: Baoquan He <bhe@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: kernel-doc: better output struct members

Right now, for a struct, kernel-doc produces the following output:

.. c:type:: struct v4l2_prio_state

   stores the priority states

**Definition**

::

  struct v4l2_prio_state {
    atomic_t prios[4];
  };

**Members**

``atomic_t prios[4]``
  array with elements to store the array priorities

Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
item[atomic_t prios\[4\]] array with elements to store the array priorities

Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.

Also, for function members, like:

        int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);

It puts the name of the member at the end, like:

        int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read

With is very confusing.

The best is to highlight what really matters: the member name.
is a secondary information.

So, change kernel-doc, for it to produce the output on a different way:

**Members**

``prios[4]``

  array with elements to store the array priorities

Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.

So, both LaTeX/PDF and HTML outputs will look good.

It should be noticed, however, that the way Sphinx LaTeX output handles
things like:

Foo
   bar

is different than the HTML output. On HTML, it will produce something
like:

**Foo**
   bar

While, on LaTeX, it puts both foo and bar at the same line, like:

**Foo** bar

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

docs-rst: add package adjustbox

We need adjustbox to allow adjusting the size of tables that
are bigger than the line width. There are quite a few of them
at the media books.

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

docs-rst: Fix an warning when in interactive mode

When XeLaTeX is in interactive mode, it complains that
py@noticelength already exists. Rename it and declare it
only once to avoid such messages.

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

docs-rst: Use better colors for note/warning/attention boxes

Instead of painting the box with gray, let's use a colored
box. IMHO, that makes easier to warn users about some issue
pointed by the Sphinx. It also matches to what we do already
with the HTML output.

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

docs-rst: conf.py: adjust the size of .. note:: tag

While the current implementation works well when using as a
paragraph, it doesn't work properly if inside a table. As we
have quite a few such cases, fix the logic to take the column
size into account.

PS.: I took the logic there from the latest version of Sphinx.sty

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

docs-rst: add support for LaTeX output

Sphinx supports LaTeX output. Sometimes, it is interesting to
call it directly, instead of also generating a PDF. As it comes
for free, add a target for it.

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

doc-rst: migrate ioctl CEC_DQEVENT to c-domain

This is only one example, demonstrating the benefits of the patch
series.  The CEC_DQEVENT ioctl is migrated to the sphinx c-domain and
referred by ":name: CEC_DQEVENT".

With this change the indirection using ":ref:`CEC_DQEVENT` is no longer
needed, we can refer the ioctl directly with ":c:func:`CEC_DQEVENT`". As
addition in the index, there is a entry "CEC_DQEVENT (C function)".

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

doc-rst: Revert "kernel-doc: fix handling of address_space tags"

This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e.

From the origin comit log::

  The RST cpp:function handler is very pedantic: it doesn't allow any
  macros like __user on it

Since the kernel-doc parser does NOT make use of the cpp:domain, there
is no need to change the kernel-doc parser eleminating the address_space
tags.

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

doc-rst: moved *duplicate* warnings to nitpicky mode

Moved the *duplicate C object description* warnings for function
declarations in the nitpicky mode. In nitpick mode, you can suppress
those warnings (e.g. ioctl) with::

  nitpicky = True
  nitpick_ignore = [
      ("c:func", "ioctl"),
  ]

See Sphinx documentation for the config values for ``nitpick`` and
``nitpick_ignore`` [1].

With this change all the ".. cpp:function:: int ioctl(..)" descriptions
(found in the media book) can be migrated to ".. c:function:: int
ioctl(..)", without getting any warnings. E.g.::

  .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )

  .. c:function:: int ioctl( int fd, int request, struct cec_event *argp )

The main effect, is that we get those *CPP-types* back into Sphinx's C-
namespace and we need no longer to distinguish between c/cpp references,
when we refer a function like the ioctl.

[1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky

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

doc-rst:c-domain: ref-name of a function declaration

Add option 'name' to the "c:function:" directive.  With option 'name'
the ref-name of a function can be modified. E.g.::

    .. c:function:: int ioctl( int fd, int request )
       :name: VIDIOC_LOG_STATUS

The func-name (e.g. ioctl) remains in the output but the ref-name
changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for
this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
can now referenced by::

    :c:func:`VIDIOC_LOG_STATUS`

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

doc-rst: add boilerplate to customize c-domain

Add a sphinx-extension to customize the sphinx c-domain.  No functional
changes right yet, just the boilerplate code.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: split up the driver book

We don't need to keep it as a single large file anymore; split it up so
that it is easier to manage and the individual sections can be read
directly as plain files.

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

Docs: sphinxify device-drivers.tmpl

Perform a basic sphinx conversion of the device-drivers docbook and move it
to its own directory.

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

Merge branch 'dev-tools' into doc/4.9

Coalesce development-tool documents into a single directory and sphinxify
them.

docs: Sphinxify gdb-kernel-debugging.txt and move to dev-tools

Acked-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kmemcheck.txt and move to dev-tools

Cc: Vegard Nossum <vegardno@ifi.uio.no>
Cc: Pekka Enberg <penberg@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kmemleak.txt and move it to dev-tools

Acked-by: Catalin Marinas <catalin.marinas@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify ubsan.txt and move it to dev-tools

Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kasan.txt and move to dev-tools

No textual changes beyond formatting.

Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Acked-by: Alexander Potapenko <glider@google.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinixfy gcov.txt and move to dev-tools

No textual changes beyond formatting.

Cc: Peter Oberparleiter <oberpar@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kcov.txt and move to dev-tools

Another document added to the dev-tools collection.

Cc: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify sparse.txt and move to dev-tools

Fold the sparse document into the development tools set; no changes to the
text itself beyond formatting.

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

docs: sphinxify coccinelle.txt and add it to dev-tools

No textual changes have been made, but the formatting has obviously been
tweaked.

Cc: Michal Marek <mmarek@suse.com>
Cc: Gilles Muller <Gilles.Muller@lip6.fr>
Acked-by: Nicolas Palix <nicolas.palix@imag.fr>
Acked-by: Julia Lawall <julia.lawall@lip6.fr>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: create a new dev-tools directory

This directory will be a collecting point for documentation oriented around
development tools.  As a step toward ordering Documentation/ it's a small
one, but we have to start somewhere...

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

Merge branch 'xelatex' into doc/4.9

Mauro says:

This patch series fix Sphinx to allow it to build the media
documentation as a PDF file.

The first patch is actually a bug fix: one of the previous patch
broke compilation for PDF as a hole, as it added an extra
parenthesis to a function call.

The second patch just removes a left over code for rst2pdf.

The other patches change from "pdflatex" to "xelatex" and address
several issues that prevent building the media books.

I think this patch series belong to docs-next. Feel free to merge
them there, if you agree. There's one extra patch that touches
Documentation/conf.py, re-adding the media book to the PDF build,
but IMHO this one would be better to be merged via the media tree,
after the fixes inside the media documentation to fix the build.

docs-rst: enable the Sphinx math extension

This extension will be used by the media books.

The name of the math image extension changed on Sphinx 1.4.x,
according with:
http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmath

Let's autodetect, to keep building with versions < 1.4.

Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: Don't go to interactive mode on errors

When building for LaTeX, it stops and enters into interactive
mode on errors. Don't do that, as there are some non-fatal errors
on media books when using Sphinx 1.4.x that we don't know how fix
yet.

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

docs-rst: parse-heraders.pl: escape LaTeX characters

Let's escape the LaTeX characters, to avoid troubles when
outputing them.

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

docs-rst: better adjust margins and font size

As we have big tables, reduce the left/right margins and decrease
the point size to 8pt. Visually, it is still good enough, and
now less tables are too big to be displayed.

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

docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output

pdflatex doesn't accept using some UTF-8 chars, like
"equal or less than" or "equal or greater than" chars. However,
the media documents use them. So, we need to use XeLaTeX for
conversion, and a font that accepts such characters.

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

docs-rst: improve output for .. notes:: on LaTeX

The output for those notes are bad in pdf, as they're not
in a box with a different color. Also, it causes the output
to not build if the note is inside a table.

Change its implementation to avoid the above troubles.

The logic there came from:
https://stackoverflow.com/questions/606746/how-to-customize-an-existing-latex-environment-without-interfering-with-other-en

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

docs-rst: allow generating some LaTeX pages in landscape

Portrait is too small for some tables used at the media docs.
So, allow documents to tell Sphinx to generate some pages
in landscape by using:

.. raw:: latex

    \begin{landscape}

<some stuff>

.. raw:: latex

    \end{landscape}

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

docs-rst: remove a rst2pdf left over code

The usage of rst2pdf was replaced by pdflatex on a previous
patch. Remove the left-over code at conf.py.

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

docs-rst: fix a breakage when building PDF documents

changeset 606b9ac81a63 ("doc-rst: generic way to build only sphinx
sub-folders") accidentally broke PDF generation by adding an extra
")". Remove it.

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

mm, kasan: Update kasan docs to indicate arm64 support

KASAN has been supported on arm64 since 39d114ddc682 ("arm64: add KASAN
support"). Update the docs to indicate this.

Signed-off-by: Laura Abbott <labbott@redhat.com>
Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: add index to sub-folders

Add a index if only a sub-folder is build e.g.::

  make SPHINXDIRS=media cleandocs htmldocs

BTW: removed dead search link in the top-index file

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

kconfig-language: improve menuconfig usage description

Improper menuconfig usage leads to empty menu entries.
zconfdump() is able to reveal some real-life examples:
- menuconfig VFIO_NOIOMMU
- menuconfig RESET_CONTROLLER
- menuconfig SND_ARM

To avoid future occurrences of those, improve the menuconfig syntax
description.

Signed-off-by: Eugeniu Rosca <rosca.eugeniu@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Update the maximum depth of C-state from 6 to 9

Hi Jon,

This patch is an old one, we have corrected some minor issues on the newer one.
Please only review the newest version from my last mail with this subject
"[PATCH] ACPI: Update the maximum depth of C-state from 6 to 9".
And I also attached it to this mail.

Thanks,
Baole

On 7/11/2016 6:37 AM, Jonathan Corbet wrote:
> On Mon, 4 Jul 2016 09:55:10 +0800
> "baolex.ni" <baolex.ni@intel.com> wrote:
>
>> Currently, CPUIDLE_STATE_MAX has been defined as 10 in the cpuidle head file,
>> and max_cstate = CPUIDLE_STATE_MAX – 1, so 9 is the right maximum depth of C-state.
>> This change is reflected in one place of the kernel-param file,
>> but not in the other place where I suggest changing.
>>
>> Signed-off-by: Chuansheng Liu <chuansheng.liu@intel.com>
>> Signed-off-by: Baole Ni <baolex.ni@intel.com>
>
> So why are there two signoffs on a single-line patch?  Which one of you
> is the actual author?
>
> Thanks,
>
> jon
>

From cf5f8aa6885874f6490b11507d3c0c86fa0a11f4 Mon Sep 17 00:00:00 2001
From: Chuansheng Liu <chuansheng.liu@intel.com>
Date: Mon, 4 Jul 2016 08:52:51 +0800
Subject: [PATCH] Update the maximum depth of C-state from 6 to 9
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Currently, CPUIDLE_STATE_MAX has been defined as 10 in the cpuidle head file,
and max_cstate = CPUIDLE_STATE_MAX – 1, so 9 is the right maximum depth of C-state.
This change is reflected in one place of the kernel-param file,
but not in the other place where I suggest changing.

Signed-off-by: Chuansheng Liu <chuansheng.liu@intel.com>
Signed-off-by: Baole Ni <baolex.ni@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: sunxi: Update Allwinner SoC documentation

Now, the A83T and A64 SoC user manuals are available.
Update the documentation to add the links.

An updated version of A83T datasheet is also included now.

Signed-off-by: Icenowy Zheng <icenowy@aosc.xyz>
Acked-by: Chen-Yu Tsai <wens@csie.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: rs485: Do not define manually the ioctl

It is not a very good practice to define the IOCTL manually instead of
using the header file.

Fix it on the documentation example.

Signed-off-by: Ricardo Ribalda Delgado <ricardo.ribalda@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: kprobes: Document jprobes stack copying limitations

Some architectures (i.e.: sparc64 and arm64) make reasonable partial stack
duplication for jprobes problematic. Document this.

Signed-off-by: David A. Long <dave.long@linaro.org>
Acked-by: Catalin Marinas <catalin.marinas@arm.com>
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

CodingStyle: Remove "Don't use C99-style comments"

Because Linus may still be reading source code on greenbar paper
instead of color terminals with code syntax highlighting and
appropriate font decorations.

Link: http://lkml.kernel.org/r/CA+55aFyQYJerovMsSoSKS7PessZBr4vNp-3QUUwhqk4A4_jcbg@mail.gmail.com
Signed-off-by: Joe Perches <joe@perches.com>

CodingStyle: Clarify and complete chapter 7

Chapter 7 (Centralized exiting of functions) of the coding style
documentation is unclear at times, and lacks some information (such
as the possibility to indent labels with a single space.) Clarify and
complete it.

Signed-off-by: Jean Delvare <jdelvare@suse.de>
Cc: Markus Elfring <elfring@users.sourceforge.net>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

README: Delete obsolete i386 info + update arch/i386/ paths

Support for i386 was removed in v3.8, delete the paragraph that says
processor types above 386 won't work on that architecture. It's obsolete
information and potentially confusing. Also change a couple of
"arch/i386/" paths to one that exists now, using "arch/x86/" instead.

Signed-off-by: Øyvind A. Holm <sunny@sunbase.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: clk: update file names containing referenced structures

Commit 'b09d6d991' removes include/linux/clk-private.h and
re-arranges the clock related structures contained in it in
different files. The documentation has not been updated
accordingly, thus it wasn't anymore consistent.

Place the structures referenced by Documentation/clk.txt in the
correct files and update their contents to the latest status.

Signed-off-by: Andi Shyti <andi.shyti@samsung.com>
[geert: Fix path to clk.c, whitespace, more clk_core, ...]
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: add docutils config file

To stop the sphinx-build on severe errors and exit with an exit code (to
stop make) the halt_level must be set. The halt_level can't be set from
sphinx, it is a docutils configuration [1]. For this a docutils.conf was
added.

[1] http://docutils.sourceforge.net/docs/user/config.html

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

doc-rst: add stand-alone conf.py to gpu folder

With the gpu/conf.py, the gpu folder can be build and distributed
stand-alone. To compile only the html of 'gpu' folder use::

  make SPHINXDIRS="gpu" htmldocs

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

doc-rst: add media/conf_nitpick.py

The media/conf_nitpick.py is a *build-theme* wich uses the nit-picking
mode of sphinx. To compile only the html of 'media' with the nit-picking
build use::

  make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs

With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.

The origin media/conf_nitpick.py comes from Mauro's experimental
docs-next branch::

  https://git.linuxtv.org/mchehab/experimental.git mchehab/docs-next

BTW fixed python indentation in media/conf_nitpick.py.  Python
indentation is 4 spaces [1] and Python 3 disallows mixing the use of
tabs and spaces for indentation [2].

[1] https://www.python.org/dev/peps/pep-0008/#indentation
[2] https://www.python.org/dev/peps/pep-0008/#tabs-or-spaces

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

doc-rst: add stand-alone conf.py to media folder

With the media/conf.py, and media/index.rst the media folder can be
build and distributed stand-alone.

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

doc-rst: generic way to build only sphinx sub-folders

Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.

* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF

Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::

  make SPHINXDIRS="media gpu" htmldocs

To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::

  make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs

With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.

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

Documentation: exclude media documentation from pdf generation

Although pdflatex is more robust than rst2pdf, building media
documentation pdf still fails. Exclude media documentation from pdf
generation for now.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: switch to pdflatex for pdf generation

Looks like rst2pdf is not robust enough, especially for large documents.

Use recursive make on the Sphinx generated makefile to convert latex to
pdf. The ugly detail is that pdf is generated into
Documentation/output/latex.

Unfortunately, the pdflatex build generates huge amounts of build log
noise, and also fails in the end. We'll fix that next.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/sphinx: build the media intermediate rst files for all outputs

This is a stopgap measure to allow building outputs other than html.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Linux 4.8-rc1

Merge branch 'for-linus' of git://git.kernel.dk/linux-block

Pull more block fixes from Jens Axboe:
 "As mentioned in the pull the other day, a few more fixes for this
  round, all related to the bio op changes in this series.

  Two fixes, and then a cleanup, renaming bio->bi_rw to bio->bi_opf.  I
  wanted to do that change right after or right before -rc1, so that
  risk of conflict was reduced.  I just rebased the series on top of
  current master, and no new ->bi_rw usage has snuck in"

* 'for-linus' of git://git.kernel.dk/linux-block:
  block: rename bio bi_rw to bi_opf
  target: iblock_execute_sync_cache() should use bio_set_op_attrs()
  mm: make __swap_writepage() use bio_set_op_attrs()
  block/mm: make bdev_ops->rw_page() take a bool for read/write