docs: Include simplified link titles in main index

Include simplified link titles in the main page's documentation index to
enhance website's readability and UX. Update the text that directs users to
various documents without changing the actual titles chosen by the authors.

Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240109155643.3489369-3-carlos.bilbao@amd.com

Documentation: Move RAS section to admin-guide

This is where this stuff should be.

Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
Link: https://lore.kernel.org/r/87a5pes8jy.fsf@meer.lwn.net

Documentation: RAS: Add index and address translation section

There are a lot of RAS topic to document, and there are a lot of details
for each topic.

Prep for this by adding an index for the RAS directory. This will
provide a top-level document and table of contents. It also provides the
option to build the RAS directory individually using "make SPHINXDIRS=".

Start a section on address translation. This will be expanded with
details for future translation methods and how they're used in the
kernel.

Move the error decoding topic to its own section. Links to other error
decoding kernel docs will be added.

Signed-off-by: Yazen Ghannam <yazen.ghannam@amd.com>
Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
Link: https://lore.kernel.org/r/20240123041401.79812-4-yazen.ghannam@amd.com

Documentation: Begin a RAS section

Add some initial RAS documentation. The expectation is for this to
collect, among others, all the user-visible features for interaction
with the RAS features of the kernel.

Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
Link: https://lore.kernel.org/r/20231128142049.GTZWX3QQTSaQk/+u53@fat_crate.local

docs: create a top-level arch/ directory

As the first step in bringing some order to our architecture-specific
documentation, create a top-level arch/ directory and move arch.rst as its
index.rst file.

There is no change in the rendered docs at this point.

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

Documentation: front page: use recommended heading adornments

Convert the Documentation front page to use the heading adornments
that are documented in doc-guide/sphinx.rst for document title and
chapters. I.e., convert most section headings to chapters.

This leaves "Indices and tables" as a chapter entry at the same level
as the other chapters.

The only visual difference from before to after is that the "Indices
and tables" heading is smaller and has more vertical whitespace
preceding it (although that may depend on the web browser being used).

Fixes: 0c7b4366f1ab ("docs: Rewrite the front page")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/20230215005726.27320-1-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: add a man-pages link to the front page

Readers looking for user-oriented information may benefit from it.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: David Vernet <void@manifault.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220927160559.97154-8-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: move asm-annotations.rst into core-api

This one file should not really be in the top-level documentation
directory. core-api/ may not be a perfect fit but seems to be best, so
move it there. Adjust a couple of internal document references to make
them location-independent, and point checkpatch.pl at the new location.

Cc: Jiri Slaby <jirislaby@kernel.org>
Cc: Joe Perches <joe@perches.com>
Reviewed-by: David Vernet <void@manifault.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220927160559.97154-6-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: remove some index.rst cruft

There is some useless boilerplate text that was added by sphinx when this
file was first created; take it out.

Reviewed-by: David Vernet <void@manifault.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220927160559.97154-5-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Rewrite the front page

The front page is the entry point to the documentation, especially for
people who read it online. It's a big mess of everything we could think to
toss into it. Rewrite the page with an eye toward simplicity and making it
easy for readers to get going toward what they really want to find.

This is only a beginning, but it makes our docs more approachable than
before.

Acked-by: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: David Vernet <void@manifault.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220927160559.97154-3-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: add Rust documentation

Most of the documentation for Rust is written within the source code
itself, as it is idiomatic for Rust projects. This applies to both
the shared infrastructure at `rust/` as well as any other Rust module
(e.g. drivers) written across the kernel.

However, these documents contain general information that does not
fit particularly well in the source code, like the Quick Start guide.

It also contains a few other small changes elsewhere in the
documentation folder.

Reviewed-by: Kees Cook <keescook@chromium.org>
Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com>
Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com>
Co-developed-by: Finn Behrens <me@kloenk.de>
Signed-off-by: Finn Behrens <me@kloenk.de>
Co-developed-by: Adam Bratschi-Kaye <ark.email@gmail.com>
Signed-off-by: Adam Bratschi-Kaye <ark.email@gmail.com>
Co-developed-by: Wedson Almeida Filho <wedsonaf@google.com>
Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com>
Co-developed-by: Michael Ellerman <mpe@ellerman.id.au>
Signed-off-by: Michael Ellerman <mpe@ellerman.id.au>
Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com>
Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com>
Co-developed-by: Wu XiangCheng <bobwxc@email.cn>
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Co-developed-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Gary Guo <gary@garyguo.net>
Co-developed-by: Boris-Chengbiao Zhou <bobo1239@web.de>
Signed-off-by: Boris-Chengbiao Zhou <bobo1239@web.de>
Co-developed-by: Yuki Okushi <jtitor@2k36.org>
Signed-off-by: Yuki Okushi <jtitor@2k36.org>
Co-developed-by: Wei Liu <wei.liu@kernel.org>
Signed-off-by: Wei Liu <wei.liu@kernel.org>
Co-developed-by: Daniel Xu <dxu@dxuuu.xyz>
Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
Co-developed-by: Julian Merkle <me@jvmerkle.de>
Signed-off-by: Julian Merkle <me@jvmerkle.de>
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

docs: rename Documentation/vm to Documentation/mm

so it will be consistent with code mm directory and with
Documentation/admin-guide/mm and won't be confused with virtual machines.

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Suggested-by: Matthew Wilcox <willy@infradead.org>
Tested-by: Ira Weiny <ira.weiny@intel.com>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Wu XiangCheng <bobwxc@email.cn>

docs: Move the HTE documentation to driver-api/

The hardware timestamp engine documentation is driver API material, and
really belongs in the driver-API book; move it there.

Cc: Thierry Reding <treding@nvidia.com>
Acked-by: Dipen Patel <dipenp@nvidia.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

hte: Add Tegra194 HTE kernel provider

Tegra194 device has multiple HTE instances also known as GTE (Generic
Hardware Timestamping Engine) which can timestamp subset of SoC lines
and signals. This provider driver focuses on IRQ and GPIO lines and
exposes timestamping ability on those lines to the consumers through
HTE subsystem.

Also, with this patch, added:
- documentation about this provider and its capabilities at
Documentation/hte.
- Compilation support in Makefile and Kconfig

Signed-off-by: Dipen Patel <dipenp@nvidia.com>
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: Thierry Reding <treding@nvidia.com>

Documentation: move tty to driver-api

Based on discussion starting as 87mthw2o93.fsf@meer.lwn.net, let's move
the tty documentation to driver-api. It's more appropriate there.

Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220411110143.10019-2-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

Documentation: move watch_queue to core-api

Move watch_queue documentation to the core-api index and
subdirectory.

Fixes: c73be61cede5 ("pipe: Add general notification queue support")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: David Howells <dhowells@redhat.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Drop Documentation/ide/

Drop all Documentation/ide/ since IDE support was deleted by
Christoph Hellwig <hch@lst.de>, Jun 16 2021.

Fixes: b7fb14d3ac63 ("ide: remove the legacy ide driver")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jens Axboe <axboe@kernel.dk>
Acked-by: Damien Le Moal <damien.lemoal@opensource.wdc.com>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Add PECI documentation

Add a brief overview of PECI and PECI wire interface.
The documentation also contains kernel-doc for PECI subsystem internals
and PECI CPU Driver API.

Reviewed-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Acked-by: Joel Stanley <joel@jms.id.au>
Signed-off-by: Iwona Winiarska <iwona.winiarska@intel.com>
Link: https://lore.kernel.org/r/20220208153639.255278-14-iwona.winiarska@intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

docs: Hook the RTLA documents into the kernel docs build

The RTLA documents were added to Documentation/ but never hooked into the
rest of the docs build, leading to a bunch of warnings like:

Documentation/tools/rtla/rtla-osnoise.rst: WARNING: document isn't included in any toctree

Add some basic glue to wire these documents into the build so that they are
available with the rest of the rendered docs. No attempt has been made to
turn the RTLA docs into proper RST files rather than warmed-over man pages;
that is an exercise for the future.

Fixes: d40d48e1f1f2 ("rtla: Add Documentation")
Acked-by: Daniel Bristot de Oliveira <bristot@kernel.org>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Link: https://lore.kernel.org/r/877dau555q.fsf@meer.lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: add TTY chapter

We now have all the kernel-doc comments in the code ready. So add a
couple of documents dragging those into generated docs from
Documentation/. There is only some sugar text around included
kernel-docs here.

It's a complete chapter, to be extended later as desired. This is a
solid cornerstone for the time being, I believe.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-24-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

docs: Group arch-specific documentation under "CPU Architectures"

To declutter the top-level table of contents (the side bar), this
patch reduces the architecture-specfic documentation to one top-level
item, "CPU Architectures".

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Link: https://lore.kernel.org/r/20210312152804.2110703-1-j.neuschaefer@gmx.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Include ext4 documentation via filesystems/

The documentation for other filesystems is already included via
filesystems/index.rst. Include ext4 in the same way and remove it
from the top-level table of contents.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Link: https://lore.kernel.org/r/20210101215215.1047826-1-j.neuschaefer@gmx.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: archis: add a per-architecture features list

Add a feature list matrix for each architecture to their
respective Kernel books.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9c39d4dd93e05c0008205527d2c3450912f029ed.1606748711.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: index.rst: Add watch_queue

Fix the following sphinx warning:

Documentation/watch_queue.rst:
WARNING: document isn't included in any toctree

By adding watch_queue.rst to the index.

Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-13-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: move remaining stuff under Documentation/*.txt to Documentation/staging

There are several files that I was unable to find a proper place
for them, and 3 ones that are still in plain old text format.

Let's place those stuff behind the carpet, as we'd like to keep the
root directory clean.

We can later discuss and move those into better places.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/11bd0d75e65a874f7c276a0aeab0fe13f3376f5f.1592203650.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: dt: add an index.rst file for devicetree

There are some device tree documentation under
Documentation/devicetree. Add a top index file for it and
add the already-existing ReST file on it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>

media: docs: get rid of Documentation/media/

Now that everything got moved, we can get rid of the
old media directory.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

docs: Add documentation for MHI bus

MHI (Modem Host Interface) is a communication protocol used by the
host processors to control and communicate with modems over a high
speed peripheral bus or shared memory. The MHI protocol has been
designed and developed by Qualcomm Innovation Center, Inc., for use
in their modems. This commit adds the documentation for the bus and
the implementation in Linux kernel.

This is based on the patch submitted by Sujeev Dias:
https://lkml.org/lkml/2018/7/9/987

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Sujeev Dias <sdias@codeaurora.org>
Signed-off-by: Siddartha Mohanadoss <smohanad@codeaurora.org>
[mani: converted to .rst and splitted the patch]
Signed-off-by: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
Reviewed-by: Jeffrey Hugo <jhugo@codeaurora.org>
Link: https://lore.kernel.org/r/20200220095854.4804-2-manivannan.sadhasivam@linaro.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

scsi: docs: Add an empty index file for SCSI documents

In preparation for adding the SCSI documents to the documentation
body, add an empty index for it.

The next patches should be adding contents to it, as files get
converted to ReST format.

Link: https://lore.kernel.org/r/4d8c1b7ebe5898ac4a8265ca5e5a9552da3b426f.1583136624.git.mchehab+huawei@kernel.org
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>

docs: Move Intel Many Integrated Core documentation (mic) under misc-devices

It doesn't need to be a top-level chapter.

This patch also updates MAINTAINERS and makes sure the F: lines are
properly sorted.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Link: https://lore.kernel.org/r/20200308211519.8414-1-j.neuschaefer@gmx.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: cpu-freq: convert index.txt to ReST

most of the stuff there can be re-used with ReST format,
but we need to add an empty TOC and remove the existing
entries, as the following conversion patches will be re-adding
them, as they're converted.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

linkage: Introduce new macros for assembler symbols

Introduce new C macros for annotations of functions and data in
assembly. There is a long-standing mess in macros like ENTRY, END,
ENDPROC and similar. They are used in different manners and sometimes
incorrectly.

So introduce macros with clear use to annotate assembly as follows:

a) Support macros for the ones below
SYM_T_FUNC -- type used by assembler to mark functions
SYM_T_OBJECT -- type used by assembler to mark data
SYM_T_NONE -- type used by assembler to mark entries of unknown type

They are defined as STT_FUNC, STT_OBJECT, and STT_NOTYPE
respectively. According to the gas manual, this is the most portable
way. I am not sure about other assemblers, so this can be switched
back to %function and %object if this turns into a problem.
Architectures can also override them by something like ", @function"
if they need.

SYM_A_ALIGN, SYM_A_NONE -- align the symbol?
SYM_L_GLOBAL, SYM_L_WEAK, SYM_L_LOCAL -- linkage of symbols

b) Mostly internal annotations, used by the ones below
SYM_ENTRY -- use only if you have to (for non-paired symbols)
SYM_START -- use only if you have to (for paired symbols)
SYM_END -- use only if you have to (for paired symbols)

c) Annotations for code
SYM_INNER_LABEL_ALIGN -- only for labels in the middle of code
SYM_INNER_LABEL -- only for labels in the middle of code

SYM_FUNC_START_LOCAL_ALIAS -- use where there are two local names for
one function
SYM_FUNC_START_ALIAS -- use where there are two global names for one
function
SYM_FUNC_END_ALIAS -- the end of LOCAL_ALIASed or ALIASed function

SYM_FUNC_START -- use for global functions
SYM_FUNC_START_NOALIGN -- use for global functions, w/o alignment
SYM_FUNC_START_LOCAL -- use for local functions
SYM_FUNC_START_LOCAL_NOALIGN -- use for local functions, w/o
alignment
SYM_FUNC_START_WEAK -- use for weak functions
SYM_FUNC_START_WEAK_NOALIGN -- use for weak functions, w/o alignment
SYM_FUNC_END -- the end of SYM_FUNC_START_LOCAL, SYM_FUNC_START,
SYM_FUNC_START_WEAK, ...

For functions with special (non-C) calling conventions:
SYM_CODE_START -- use for non-C (special) functions
SYM_CODE_START_NOALIGN -- use for non-C (special) functions, w/o
alignment
SYM_CODE_START_LOCAL -- use for local non-C (special) functions
SYM_CODE_START_LOCAL_NOALIGN -- use for local non-C (special)
functions, w/o alignment
SYM_CODE_END -- the end of SYM_CODE_START_LOCAL or SYM_CODE_START

d) For data
SYM_DATA_START -- global data symbol
SYM_DATA_START_LOCAL -- local data symbol
SYM_DATA_END -- the end of the SYM_DATA_START symbol
SYM_DATA_END_LABEL -- the labeled end of SYM_DATA_START symbol
SYM_DATA -- start+end wrapper around simple global data
SYM_DATA_LOCAL -- start+end wrapper around simple local data

==========

The macros allow to pair starts and ends of functions and mark functions
correctly in the output ELF objects.

All users of the old macros in x86 are converted to use these in further
patches.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Signed-off-by: Borislav Petkov <bp@suse.de>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Andrey Ryabinin <aryabinin@virtuozzo.com>
Cc: Boris Ostrovsky <boris.ostrovsky@oracle.com>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: Ingo Molnar <mingo@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Josh Poimboeuf <jpoimboe@redhat.com>
Cc: Juergen Gross <jgross@suse.com>
Cc: Len Brown <len.brown@intel.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: linux-arch@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: linux-pm@vger.kernel.org
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Pavel Machek <pavel@ucw.cz>
Cc: Peter Zijlstra <a.p.zijlstra@chello.nl>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Will Deacon <will@kernel.org>
Cc: x86-ml <x86@kernel.org>
Cc: xen-devel@lists.xenproject.org
Link: https://lkml.kernel.org/r/20191011115108.12392-2-jslaby@suse.cz

docs: Move the user-space ioctl() docs to userspace-api

This is strictly user-space material at this point, so put it with the
other user-space API documentation.

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

Documentation: virt: Fix broken reference to virt tree's index

Fix broken reference to virt/index.rst.

Fixes: 2f5947dfcaec ("Documentation: move Documentation/virtual to Documentation/virt")
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: Add doc for the Ingenic TCU hardware

Add documentation about the Timer/Counter Unit (TCU) present in the
Ingenic JZ47xx SoCs.

The Timer/Counter Unit (TCU) in Ingenic JZ47xx SoCs is a multi-function
hardware block. It features up to to eight channels, that can be used as
counters, timers, or PWM.

- JZ4725B, JZ4750, JZ4755 only have six TCU channels. The other SoCs all
have eight channels.

- JZ4725B introduced a separate channel, called Operating System Timer
(OST). It is a 32-bit programmable timer. On JZ4770 and above, it is
64-bit.

- Each one of the TCU channels has its own clock, which can be reparented
to three different clocks (pclk, ext, rtc), gated, and reclocked, through
their TCSR register.
* The watchdog and OST hardware blocks also feature a TCSR register with
the same format in their register space.
* The TCU registers used to gate/ungate can also gate/ungate the watchdog
and OST clocks.

- Each TCU channel works in one of two modes:
* mode TCU1: channels cannot work in sleep mode, but are easier to
operate.
* mode TCU2: channels can work in sleep mode, but the operation is a bit
more complicated than with TCU1 channels.

- The mode of each TCU channel depends on the SoC used:
* On the oldest SoCs (up to JZ4740), all of the eight channels operate in
TCU1 mode.
* On JZ4725B, channel 5 operates as TCU2, the others operate as TCU1.
* On newest SoCs (JZ4750 and above), channels 1-2 operate as TCU2, the
others operate as TCU1.

- Each channel can generate an interrupt. Some channels share an interrupt
line, some don't, and this changes between SoC versions:
* on older SoCs (JZ4740 and below), channel 0 and channel 1 have their
own interrupt line; channels 2-7 share the last interrupt line.
* On JZ4725B, channel 0 has its own interrupt; channels 1-5 share one
interrupt line; the OST uses the last interrupt line.
* on newer SoCs (JZ4750 and above), channel 5 has its own interrupt;
channels 0-4 and (if eight channels) 6-7 all share one interrupt line;
the OST uses the last interrupt line.

Signed-off-by: Paul Cercueil <paul@crapouillou.net>
Tested-by: Mathieu Malaterre <malat@debian.org>
Tested-by: Artur Rojek <contact@artur-rojek.eu>
Signed-off-by: Paul Burton <paul.burton@mips.com>
Cc: Ralf Baechle <ralf@linux-mips.org>
Cc: James Hogan <jhogan@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Daniel Lezcano <daniel.lezcano@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Michael Turquette <mturquette@baylibre.com>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: Jason Cooper <jason@lakedaemon.net>
Cc: Marc Zyngier <marc.zyngier@arm.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: devicetree@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-mips@vger.kernel.org
Cc: linux-clk@vger.kernel.org
Cc: od@zcrc.me

docs: w1: convert to ReST and add to the kAPI group of docs

The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

spi: docs: convert to ReST and add it to the kABI bookset

While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: nios2: add it to the main Documentation body

Rename and add the nios2 documentation to the documentation
body.

The nios2 document is already on an ReST compatible format.
All it needs is that the title of the document to be promoted
one level.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: mips: add to the documentation body as ReST

Manually convert the AU1xxx_IDE.README file to ReST and add
to a MIPS book as part of the main documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Paul Burton <paul.burton@mips.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: isdn: convert to ReST and add to kAPI bookset

The ISDN documentation is a mix of admin guide, uAPI and kAPI.

Ideally, it should be split. Yet, not sure if it would worth
the troble. Anyway, we have the same kind of mix on several
drivers specific documentation. So, just like the others, keep
the directory at the root Documentation/ tree, just adding a
pointer to it at the kAPI section, as the documentation was
written with the Kernel developers in mind.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: openrisc: convert to ReST and add to documentation body

Manually convert the two openRisc documents to ReST, adding them
to the Linux documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Stafford Horne <shorne@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: parisc: convert to ReST and add to documentation body

Manually convert the two PA-RISC documents to ReST, adding them
to the Linux documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: i2c: convert to ReST and add to driver-api bookset

Convert each file at I2C subsystem, renaming them to .rst and
adding to the driver-api book.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: virtual: add it to the documentation body

As files are getting converted to ReST, add them to the
documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: power: add it to to the main documentation index

The power docs are orphaned at the documentation body.

While it could likely be moved to be inside some guide, I'm opting to just
adding it to the main index.rst, removing the :orphan: and adding the SPDX
header.

The reason is similar to what it was done for other driver-specific
subsystems: the docs there contain a mix of Kernelspace, uAPI and
admin-guide. So, better to keep them on its own directory,
while the docs there are not properly classified.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: powerpc: convert docs to ReST and rename to *.rst

Convert docs to ReST and add them to the arch-specific
book.

The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.

The changes were mostly to mark literal blocks and add a few
missing section title identifiers.

One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl

docs: locking: add it to the main index

The locking directory is part of the Kernel API bookset. Add
it to the index file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: add some directories to the main documentation index

The contents of those directories were orphaned at the documentation
body.

While those directories could likely be moved to be inside some guide,
I'm opting to just adding their indexes to the main one, removing the
:orphan: and adding the SPDX header.

For the drivers, the rationale is that the documentation contains
a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on
separate directories, as we've be doing with similar subsystem-specific
docs that were not split yet.

For the others, well... I'm too lazy to do the move. Also, it
seems to make sense to keep at least some of those at the main
dir (like kbuild, for example). In any case, a latter patch
could do the move.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>

docs: phy: place documentation under driver-api

This subsystem-specific documentation belongs to the
driver-api.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: driver-api: add remaining converted dirs to it

There are a number of driver-specific descriptions that contain a
mix of userspace and kernelspace documentation. Just like we did
with other similar subsystems, add them at the driver-api
groupset, but don't move the directories.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: add some documentation dirs to the driver-api book

Those are subsystem docs, with a mix of kABI and user-faced
docs. While they're not split, keep the dirs where they are,
adding just a pointer to the main index.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: add arch doc directories to the index

Now that several arch documents were converted to ReST,
add their indexes to Documentation/index.rst and remove the
:orphan: from them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: ioctl: add it to the uAPI guide

While 100% of its contents is userspace, let's keep the dir
at the same place, as this is a well-known location.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: leds: add it to the driver-api book

The contents of leds driver docs is messy: it has lots of
admin-guide stuff and kernel internal ones, just like other
driver subsystems.

I'm opting to keep the dir at the same place and just add
a link to it. This makes clearer that this require changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

docs: arm: convert docs to ReST and rename to *.rst

Converts ARM the text files to ReST, preparing them to be an
architecture book.

The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by Corentin Labbe <clabbe.montjoie@gmail.com> # For sun4i-ss

docs: infiniband: add it to the driver-api bookset

While this contains some uAPI stuff, it was intended to be read by a
kernel doc. So, let's not move it to a different dir, but, instead, just
add it to the driver-api bookset.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>

docs: usb: rename files to .rst and add them to drivers-api

While there are a mix of things here, most of the stuff
were written from Kernel developer's PoV. So, add them to
the driver-api book.

A follow up for this patch would be to move documents from
there that are specific to sysadmins, adding them to the
admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Johan Hovold <johan@kernel.org>
Acked-by: Felipe Balbi <felipe.balbi@linux.intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

Documentation: Remove duplicate x86 index entry

x86 got added twice to the index via the RST conversion and the MDS
documentation changes. Remove one instance.

Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: add Linux PCI to Sphinx TOC tree

Add index.rst for PCI subsystem. More docs will be added later.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>

Documentation: add Linux x86 docs to Sphinx TOC tree

Add a index.rst for x86 support. More docs will be added later.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: add Linux ACPI to Sphinx TOC tree

Add below index.rst files for ACPI subsystem. More docs will be added later.
o admin-guide/acpi/index.rst
o driver-api/acpi/index.rst
o firmware-guide/index.rst

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

docs: hwmon: Add an index file and rename docs to *.rst

Now that all files were converted to ReST format, rename them
and add an index.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Guenter Roeck <linux@roeck-us.net>

x86/speculation/mds: Add mds_clear_cpu_buffers()

The Microarchitectural Data Sampling (MDS) vulernabilities are mitigated by
clearing the affected CPU buffers. The mechanism for clearing the buffers
uses the unused and obsolete VERW instruction in combination with a
microcode update which triggers a CPU buffer clear when VERW is executed.

Provide a inline function with the assembly magic. The argument of the VERW
instruction must be a memory operand as documented:

"MD_CLEAR enumerates that the memory-operand variant of VERW (for
example, VERW m16) has been extended to also overwrite buffers affected
by MDS. This buffer overwriting functionality is not guaranteed for the
register operand variant of VERW."

Documentation also recommends to use a writable data segment selector:

"The buffer overwriting occurs regardless of the result of the VERW
permission check, as well as when the selector is null or causes a
descriptor load segment violation. However, for lowest latency we
recommend using a selector that indicates a valid writable data
segment."

Add x86 specific documentation about MDS and the internal workings of the
mitigation.

Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Borislav Petkov <bp@suse.de>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Frederic Weisbecker <frederic@kernel.org>
Reviewed-by: Jon Masters <jcm@redhat.com>
Tested-by: Jon Masters <jcm@redhat.com>

Documentation: add ibmvmc to toctree(index) and fix warnings

Fix Sphinx warnings in ibmvmc.rst, add an index.rst file in
Documentation/misc-devices/, and insert that index file into the
top-level index file.

Documentation/misc-devices/ibmvmc.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent.
Documentation/misc-devices/ibmvmc.rst:: WARNING: document isn't included in any toctree

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Steven Royer <seroyer@linux.ibm.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: tidy up TOCs and refs to license-rules.rst

The documentation and TOCs are organized in a manner of a tree. Adding a TOC to
the root, which refers to a file which is located in a subfolder forms a
grid. Those TOCs are a bit confusing and thats why we get additional error
messages while building partial documentation::

$ make SPHINXDIRS=process htmldocs
...
checking consistency... Documentation/process/license-rules.rst: \
WARNING: document isn't included in any toctree

To fix it, the *root-license-TOC* is replaced by a reference and the
'license-roles.txt' is added to the Documentation/process/index.rst TOC.

BTW: there was an old licences remark in Documentation/process/howto.rst which
is also updated, mentioning SPDX and pointing to the license-rules.rst

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

docs: fix up the obviously obsolete bits in the new ext4 documentation

Signed-off-by: Theodore Ts'o <tytso@mit.edu>

docs: create filesystem internal section

Create a new top-level section for documentation of filesystem usage,
on-disk format information, and anything else.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>

docs: Add bpf/index to top level index

Recently bpf docs were converted to RST format. The new files were not
added to the top level toctree. This causes build system to emit a
warning of type

WARNING: document isn't included in any toctree

Add bpf/index.rst to Documentation/index.rst

Signed-off-by: Tobin C. Harding <me@tobin.cc>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>

doc: add some chapter labels

The idea is to make it easier to create references (doc-guide does the same).
This will be used, for example but not only, in translations to point to
the main document.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: move away translations from top-level index

In translations/ we have now a dedicated index.rst where we add/remove
references to translations. Translations are in English alphabetical
order.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs/vm: add index.rst and link MM documentation to top level index

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: add Linux tracing to Sphinx TOC tree

This just add a index.rst for trace subsystem. More docs will
be added later.

Cc: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Changbin Du <changbin.du@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: Add license-rules.rst to describe how to properly identify file licenses

Add a file to the Documentation directory to describe how file licenses
should be described in all kernel files, using the SPDX identifier, as well
as where all licenses should be in the kernel source tree for people to
refer to (LICENSES/).

Thanks to Kate and Greg for review and editing and Jonas for the
suggestions concerning the meta tags in the licenses files.

Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Jonas Oberg <jonas@fsfe.org>
Reviewed-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: add maintainer book

There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.

Quoting Greg Kroah-Hartman on LKML:

Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.

Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.

(quote references: kernel summit, Europe 2017)

Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.

Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.

Signed-off-by: Tobin C. Harding <me@tobin.cc>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
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-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>

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

docs-rst: add input docs at main index and use kernel-figure

The input subsystem documentation got converted into ReST.

Add it to the main documentation index and use kernel-figure
for the two svg images there.

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

Documentation: Add HOWTO Japanese translation into rst based build system

This commit adds Japanese translation of HOWTO document into rst based
documentation build system with updates.

Signed-off-by: Tsugikazu Shibata <tshibata@ab.jp.nec.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Create a user-space API guide

This is meant to be the place for documentation relevant to application
developers. It's empty for the moment, but at least we have a place now!

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

docs/zh_CN: Add coding-style into docs build system

Tested by the command:

make htmldocs

During the compiling process, zh_CN/coding-style.rst has no errors and
warnings generated, the generated html document has been checked.

Signed-off-by: Andy Deng <theandy.deng@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

crypto: doc - convert crypto API documentation to Sphinx

With the conversion of the kernel crypto API DocBook to Sphinx, the
monolithic document is broken up into individual documents. The
documentation is unchanged with the exception of a slight reordering to
keep the individual document parts self-contained.

Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Move the 802.11 guide into the driver-api manual

Put this documentation with the other driver docs and try to keep the top
level reasonably clean.

Cc: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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

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

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

Documentation: Add HOWTO Korean translation into rst based build system

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

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

ALSA: doc: ReSTize alsa-driver-api document

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

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

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

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

tpm: move documentation under Documentation/security

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

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

tpm: transition tpm_vtpm_proxy documentation to the Sphinx

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

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

Documentation/00-index: update for new core-api folder

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Tweak the top-level Sphinx page

This will be the initial landing point for readers, so give them a bit of
introductory material. Also split the TOC into area-specific chunks to
make the whole thing a bit more approachable.

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

doc-rst: make dev-tools folder buildable stand-alone

Add minimal conf.py and moved dev-tools/tools.rst to dev-tools/index.rst
makes the dev-tools folder buildable stand-alone. To build only this
folder run::

make SPHINXDIRS=dev-tools htmldocs
make SPHINXDIRS=dev-tools pdfdocs

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

docs-rst: create an user's manual book

Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.

As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.

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

docs: rename development-process/ to process/

As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.

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

docs-rst: sphinxify 802.11 documentation

This is just a very basic conversion, I've split up the original
multi-book template, and also split up the multi-part mac80211
part in the original book; neither of those were handled by the
automatic pandoc conversion.

Fix errors that showed up, resulting in a much nicer rendering,
at least for the interface combinations documentation.

Signed-off-by: Johannes Berg <johannes.berg@intel.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>

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>

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>

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>

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>

[media] doc-rst: better name the media books

The titles at the media books were misleading, and some books
were not numbered.

Rename the kAPI book to better reflect its contents, be more
consistent on the initial rst file for each book and better
name them.

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

doc-rst: add v4l-drivers to index file

Adds documentation for V4L drivers.

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

[media] add DVB documentation to Sphinx

Now that all DVB files got converted, add it to Sphinx
build.

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

[media] doc-rst: Convert media API to rst

Move the contents of the media section at
DocBooks/DocBook/device-drivers.tmpl to a new ReST book.

For now, the contents is kept as-is. Next patches will fix
the warnings and add cross-references that were removed due to
the conversion.

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

doc_rst: rename the media Sphinx suff to Documentation/media

The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.

No functional changes.

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

doc-rst: linux_tv DocBook to reST migration (docs-next)

This is the restructuredText (reST) migration of the ``media``
DocBook-XML set from the linux_tv project.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Documentation: add meta-documentation for Sphinx and kernel-doc

Describe Sphinx, reStructuredText, the kernel-doc extension, the
kernel-doc structured documentation comments, etc.

The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim
<twaugh@redhat.com>.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/sphinx: drop modindex, we don't have python modules

The modindex is for python modules.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/gpu: add new gpu.rst converted from DocBook gpu.tmpl

This is the first step towards converting the DocBook gpu.tmpl to Sphinx
and reStructuredText, the new kernel documentation tool and markup.

Use Jon's "cheesy conversion script" in Documentation/sphinx/tmplcvt to
do the rough conversion. Do the manual edits in follow-up patches. Add a
new Documentation/gpu directories for the graphics related
documentation. (Hooray, now we can have directories based on topics
rather than tools under Documentation.)

We also won't remove the DocBook gpu.tmpl yet so it's easier to build
both and compare the results for parity.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/bc7b4f9ac037632e0c8469c079d21fad5eaa39a0.1466506505.git.jani.nikula@intel.com

Documentation/sphinx: add basic working Sphinx configuration and build

Add basic configuration and makefile to build documentation from any
.rst files under Documentation using Sphinx. For starters, there's just
the placeholder index.rst.

At the top level Makefile, hook Sphinx documentation targets alongside
(but independent of) the DocBook toolchain, having both be run on the
various 'make *docs' targets.

All Sphinx processing is placed into Documentation/Makefile.sphinx. Both
that and the Documentation/DocBook/Makefile are now expected to handle
all the documentation targets, explicitly ignoring them if they're not
relevant for that particular toolchain. The changes to the existing
DocBook Makefile are kept minimal.

There is graceful handling of missing Sphinx and rst2pdf (which is
needed for pdf output) by checking for the tool and python module,
respectively, with informative messages to the user.

If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but
otherwise gracefully fall back to the Sphinx default theme, with an
informative message to the user, and slightly less pretty HTML output.

Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available),
epubdocs and xmldocs targets. The output documents are written into per
output type subdirectories under Documentation/output.

Finally, you can pass options to sphinx-build using the SPHINXBUILD make
variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose
output from Sphinx.

This is based on the original work by Jonathan Corbet, but he probably
wouldn't recognize this as his own anymore.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>