The handling of dashes in particular results in confusing
documentation in a number of instances, since "--" becomes an
en-dash. This disables SmartyPants wholesale, losing smart quotes
along with smart dashes.

With Sphinx 1.6 we could fine-tune the conversion, using the new
smartquotes and smartquotes_action settings.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The UP.rst file calls for locks acquired within RCU callback functions
to use _irq variants (spin_lock_irqsave() or similar), which does work,
but can be overkill.  This commit therefore instead calls for _bh variants
(spin_lock_bh() or similar), while noting that _irq does work.
Signed-off-by: Paul E. McKenney <paulmck@linux.ibm.com>
Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The current ReStructuredText formatting results in "--", used to
indicate the end of the kernel command-line parameters, appearing as
an en-dash instead of two hyphens; this patch formats them as code,
"``--``", as done elsewhere in the documentation.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

fix the disjunction by replacing "of" with "or".
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Bring in (finally) automatic markup of function() so we need not load up
our docs with ugly c:func: annotations.

Changeset 163ede97 ("Documentation: platform: Delete x86-laptop-drivers.txt")
removed the x86-laptop-drivers.txt file, but forgot to update its
Kconfig.

Fixes: 163ede97 ("Documentation: platform: Delete x86-laptop-drivers.txt")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

We should really move the RCU directory there as well, but that can wait
for another day.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP
Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt
Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

RCU UP systems reST markup.
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

RCU linked list reST markup.
Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

RCU basic concepts reST markup.
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There's no need to use a .rst on Sphinx toc tables. As most of
the Documentation don't use, remove the remaing occurrences.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Build of htmldocs fails for out-of-tree builds:

$ make V=1 O=~/build/kernel/ htmldocs
make -C /home/rppt/build/kernel -f /home/rppt/git/linux-docs/Makefile htmldocs
make[1]: Entering directory '/home/rppt/build/kernel'
make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=scripts/basic
rm -f .tmp_quiet_recordmcount
make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=Documentation htmldocs
Can't open Documentation/conf.py at /home/rppt/git/linux-docs/scripts/sphinx-pre-install line 230.
/home/rppt/git/linux-docs/Documentation/Makefile:80: recipe for target 'htmldocs' failed
make[2]: *** [htmldocs] Error 2

The scripts/sphinx-pre-install is trying to open files in the current
directory which is $KBUILD_OUTPUT rather than in $srctree.

Fix it.
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Somehow, this file ended with Documentation/ twice.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Newer devices like Yubikey 5 and Nitrokey Pro 2 have added support for
NISTP's implementation of ECC cryptography, so update the guide
accordingly and add a note on when to use nistp256 and when to use
ed25519 for generating S keys.
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add documentation for Spectre vulnerability and the mitigation mechanisms:

- Explain the problem and risks
- Document the mitigation mechanisms
- Document the command line controls
- Document the sysfs files
Co-developed-by: Andi Kleen <ak@linux.intel.com>
Signed-off-by: Andi Kleen <ak@linux.intel.com>
Co-developed-by: Tim Chen <tim.c.chen@linux.intel.com>
Signed-off-by: Tim Chen <tim.c.chen@linux.intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The list of laptops supported by drivers in PDx86 subsystem is quite
big and growing. x86-laptop-drivers.txt contains details of very few
laptop models. Remove it because it does not  serve any purpose.
Signed-off-by: Puranjay Mohan <puranjay12@gmail.com>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Now that we can mark up function() automatically, there is no reason to use
:c:func: and every reason to avoid it.  Adjust the documentation to reflect
that fact.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

We now have better automarkup in sphinx itself and, besides, this markup
was incorrect and left :c:func: gunk in the processed docs.  Sort of
discouraging that nobody ever noticed...:)

As a first step toward the removal of impenetrable regex magic from
kernel-doc it's a tiny one, but you have to start somewhere.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Now that the build system automatically marks up function references, we
don't have to clutter the source files, so take it out.

[Some paragraphs could now benefit from refilling, but that was left out to
avoid obscuring the real changes.]
Acked-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

"git diff" says:

    \ No newline at end of file

after modifying the file.
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

These are all obvious typos.
Signed-off-by: James Morse <james.morse@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

"If the MBA is specified in MB then user can enter the max b/w in MB"
is a tautology. How can the user know if the schemata takes a percentage
or a MB/s value?

This is referring to whether the software controller is interpreting
the schemata's value. Make this clear.
Signed-off-by: James Morse <james.morse@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

"L2 cache does not support code and data prioritization". This isn't
true, elsewhere the document says it can be enabled with the cdpl2
mount option.

While we're here, these sample strings have lower-case code/data,
which isn't how the kernel exports them.
Signed-off-by: James Morse <james.morse@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Since commit 4d05bf71 ("x86/resctrl: Introduce AMD QOS feature")
resctrl has supported non-contiguous cache bit masks. The interface
for this is currently try-it-and-see.

Update the documentation to say Intel CPUs have this requirement,
instead of X86.

Cc: Babu Moger <Babu.Moger@amd.com>
Signed-off-by: James Morse <james.morse@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The asterisks prepended to the quoted text currently get translated to
bullet points, which gets increasingly confusing the smaller your
screen is (when viewing the sphinx output, that is).

Convert the whole quote to a literal block.
Signed-off-by: Valentin Schneider <valentin.schneider@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Since strlcpy is deprecated, the documentation shouldn't suggest using
it. This patch fixes the examples to use strscpy instead. It also uses
sizeof instead of underlying constants as far as possible, to simplify
future changes to the corresponding data structures.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Acked-by: Kees Cook <keescook@chromium.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

In order for a list to be recognized as such, blank lines
are required.

Solve those Sphinx warnings:

./lib/list_sort.c:162: WARNING: Unexpected indentation.
./lib/list_sort.c:163: WARNING: Block quote ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Sphinx expects a blank line after a literal block markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The new font is available since recently.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Every merge window seems to involve at least one episode where subsystem
maintainers don't manage their trees as Linus would like.  Document the
expectations so that at least he has something to point people to.
Acked-by: David Rientjes <rientjes@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Since commit 5b18b5a7 ("block: delete part_round_stats and switch to
less precise counting") io_ticks is approximated by adding one at each
start and end of requests if jiffies has changed.

This works perfectly for requests shorter than a jiffy. If requests runs
more than 2 jiffies some I/O time will not be accounted unless there are
other reuqests.
Signed-off-by: Konstantin Khlebnikov <khlebnikov@yandex-team.ru>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

powerpc architecture (both 64-bit and 32-bit) supports stack protector
mechanism since some time now [see commit 06ec27ae ("powerpc/64:
add stack protector support")].

Update stackprotector arch support documentation to reflect the same.

Cc: Michael Ellerman <mpe@ellerman.id.au>
Signed-off-by: Bhupesh Sharma <bhsharma@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Update the documentation to reflect the new naming scheme with
latest changes.
Reported-by: Leo Yan <leo.yan@linaro.org>
Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>
Signed-off-by: Suzuki K Poulose <suzuki.poulose@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There's a paragraph that explains how to create fixed width text block,
but it doesn't explains how to create fixed width text inline, although
this feature is really used through the documentation. Fix that adding a
quick note about it.
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

When there's no Documentation/output directory, the script will
complain about those missing references:

	Documentation/doc-guide/sphinx.rst: Documentation/output
	Documentation/doc-guide/sphinx.rst: Documentation/output
	Documentation/process/howto.rst: Documentation/output
	Documentation/translations/it_IT/doc-guide/sphinx.rst: Documentation/output
	Documentation/translations/it_IT/doc-guide/sphinx.rst: Documentation/output
	Documentation/translations/it_IT/process/howto.rst: Documentation/output
	Documentation/translations/ja_JP/howto.rst: Documentation/output
	Documentation/translations/ko_KR/howto.rst: Documentation/output

Those are false positives, so add an ignore rule for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Sphinx need to know when a paragraph ends. So, do some adjustments
at the file for it to be properly parsed.

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.

that's said, I believe that this file should be moved to the
GPU/DRM documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

In order to prepare to add them to the Kernel API book,
convert the files to ReST format.

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>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>