docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

Commit f061c9f7d058 ("Documentation: Document each netlink family")
added recipes for YAML -> RST conversion.
Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by
deleting generated .rst files") made sure those converted .rst files
are cleaned by "make cleandocs".

However, they took care of htmldocs build only.

If one of other targets such as latexdocs or epubdocs is built
without building htmldocs, missing .rst files can cause additional
WARNINGs from sphinx-build as follow:

./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs'
./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link'
./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc'
./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs'

Add dependency to $(YNL_INDEX) for other targets and allow any targets
to be built cleanly right after "make cleandocs".

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: stable@vger.kernel.org # v6.7
Cc: Thorsten Blum <thorsten.blum@toblux.com>
Cc: Breno Leitao <leitao@debian.org>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: "David S. Miller" <davem@davemloft.net>
Reviwed-by: Breno Leitao <leitao@debian.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <e876e3c8-109d-4bc8-9916-05a4bc4ee9ac@gmail.com>

docs: Makefile: Fix make cleandocs by deleting generated .rst files

The script tools/net/ynl/ynl-gen-rst.py (YNL_TOOL) generates several .rst
files (YNL_INDEX, YNL_RST_FILES) in Documentation/networking/netlink_spec
(YNL_RST_DIR) which are not deleted by make cleandocs.

Fix make cleandocs by deleting the generated .rst files.

Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>
Reviewed-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240208145001.61769-1-thorsten.blum@toblux.com

doc/netlink: Regenerate netlink .rst files if ynl-gen-rst changes

Add ynl-gen-rst.py to the dependencies for the netlink .rst files in the
doc Makefile so that the docs get regenerated if the ynl-gen-rst.py
script is modified. Use $(Q) to honour V=1 in the rules that run
ynl-gen-rst.py

Reviewed-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Breno Leitao <leitao@debian.org>
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20231215093720.18774-10-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Documentation: Document each netlink family

This is a simple script that parses the Netlink YAML spec files
(Documentation/netlink/specs/), and generates RST files to be rendered
in the Network -> Netlink Specification documentation page.

Create a python script that is invoked during 'make htmldocs', reads the
YAML specs input file and generate the correspondent RST file.

Create a new Documentation/networking/netlink_spec index page, and
reference each Netlink RST file that was processed above in this main
index.rst file.

In case of any exception during the parsing, dump the error and skip
the file.

Do not regenerate the RST files if the input files (YAML) were not
changed in-between invocations.

Suggested-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Breno Leitao <leitao@debian.org>

----
Changelog:

V3:
* Do not regenerate the RST files if the input files were not
changed. In order to do it, a few things changed:
- Rely on Makefile more to find what changed, and trigger
individual file processing
- The script parses file by file now (instead of batches)
- Create a new option to generate the index file

V2:
* Moved the logic from a sphinx extension to a external script
* Adjust some formatting as suggested by Donald Hunter and Jakub
* Auto generating all the rsts instead of having stubs
* Handling error gracefully
Reviewed-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>

docs: Integrate rustdoc generation into htmldocs

Change target `make htmldocs` to combine RST Sphinx and the generation of
Rust documentation, when support is available and .config exists.

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230718151534.4067460-3-carlos.bilbao@amd.com

kbuild: do not print extra logs for V=2

Some scripts increase the verbose level when V=1, but others when
not V=0.

I think the former is correct because V=2 is not a log level but
a switch to print the reason for rebuilding.

Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
Reviewed-by: Nicolas Schier <nicolas@fjasle.eu>

doc: add texinfodocs and infodocs targets

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or anchors, for example).

Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
Link: https://lore.kernel.org/r/20221116190210.28407-2-maxim.cournoyer@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Makefile: Add -no-shell-escape option to LATEXOPTS

It turns out that LaTeX enables \write18, which allows (some) shell
commands to be executed from the document source, by default. This the
often-seen warning during a pdfdocs build:

restricted \write18 enabled

That is a potential security problem and is entirely unnecessary; nothing
in the kernel PDF docs build needs that capability. So disable \write18
explicitly.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/519bd2d9-1bee-03e1-eeb4-d9883c18be0c@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: address some text issues with css/theme support

Fix:
- overriden ->overridden
- some whitespace issues introduced at the css/theme
Makefile help.

Reported-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/b0b166025019f7cc4f122bd789c79ba28cc2d29d.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Makefile: use the right path for DOCS_CSS

When make is used with O=<dir>, the location of the css file
won't be get right:

$ make DOCS_THEME=nature DOCS_CSS=my_css.css O=DOCS SPHINXDIRS=x86 -j9 htmldocs
make[1]: Entering directory '/work/lnx/next/next-2021-1210/DOCS'
...
cp: cannot stat 'my_css.css': No such file or directory

Fix it in a way that both relative and absolute paths will be
handled.

Reported-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/cea4ff1237ae9a99bc6509ab1bf9c70acd97e265.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: allow to pass extra DOCS_CSS themes via make

Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

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

docs: allow selecting a Sphinx theme

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME environment var.

There's a catch, though: as the current theme override logic is
dependent of the RTD theme, we need to move the code which
adds the CSS overrides to be inside the RTD theme logic.

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

docs: Makefile: Use CONFIG_SHELL not SHELL

Fix think-o about which variable to find the Kbuild-configured shell.
This has accidentally worked due to most shells setting $SHELL by
default.

Fixes: 51e46c7a4007 ("docs, parallelism: Rearrange how jobserver reservations are made")
Cc: stable@vger.kernel.org
Signed-off-by: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20210617225808.3907377-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

kbuild: remove PYTHON variable

Python retired in 2020, and some distributions do not provide the
'python' command any more.

As in commit 51839e29cb59 ("scripts: switch explicitly to Python 3"),
we need to use more specific 'python3' to invoke scripts even if they
are written in a way compatible with both Python 2 and 3.

This commit removes the variable 'PYTHON', and switches the existing
users to 'PYTHON3'.

BTW, PEP 394 (https://www.python.org/dev/peps/pep-0394/) is a helpful
material.

Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>

docs: Kconfig/Makefile: add a check for broken ABI files

The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.

Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.

With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:

Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/57a38de85cb4b548857207cf1fc1bf1ee08613c9.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

docs: Makefile: honor V=0 for docs building

Reduce the number of displayed mesages when building the
docs with V=0.

Suggested-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/478c114a2399b68a18de94ee5f98649304f3903b.1603796153.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Makefile: place final pdf docs on a separate dir

The Sphinx build system for PDF is too complex and generate
lots of ancillary files, including one PDF file for each
image.

So, at the end, the main latex dir has 156 pdf files, instead
of the 71 ones that would match each generated book. That's
confusing and it makes harder to identify when something didn't
work.

So, instead, let's move the final PDF output(s) to a separate
dir. This way, the latex/ dir will have the temporary and the
final *.tex files, while the final pdf files that built ok
will be under the pdf/ directory.

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

media: docs: move uAPI book to userspace-api/media

Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee3862 ("docs: Create a user-space API guide").

As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.

Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.

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

kbuild: remove trailing slash from devicetree/binding/ for descending

obj-* needs a trailing slash for a directory, but subdir-* does not
because it already implies a directory.

Also, change subdir-y to subdir- to ensure this is effective only
for cleaning targets.

This makes the cleaning log consistent. (no trailing slash)

Before:

$ make clean
CLEAN Documentation/devicetree/bindings/

After:

$ make clean
CLEAN Documentation/devicetree/bindings

Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>

Documentation: sort _SPHINXDIRS for 'make help'

Sort the _SPHINXDIRS so that the 'make help' output is easier to read &
search and in a predictable order instead of some unknown pseudo-random
order.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs, parallelism: Rearrange how jobserver reservations are made

Rasmus correctly observed that the existing jobserver reservation only
worked if no other build targets were specified. The correct approach
is to hold the jobserver slots until sphinx has finished. To fix this,
the following changes are made:

- refactor (and rename) scripts/jobserver-exec to set an environment
variable for the maximally reserved jobserver slots and exec a
child, to release the slots on exit.

- create Documentation/scripts/parallel-wrapper.sh which examines both
$PARALLELISM and the detected "-jauto" logic from Documentation/Makefile
to decide sphinx's final -j argument.

- chain these together in Documentation/Makefile

Suggested-by: Rasmus Villemoes <linux@rasmusvillemoes.dk>
Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk
Signed-off-by: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

kbuild: Wrap long "make help" text lines

Some "make help" text lines extend beyond 80 characters.
Wrap them before an opening parenthesis, or before 80 characters.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>

docs: Fix "make help" suggestion for SPHINXDIR

Commit 9fc3a18a942f ("docs: remove extra conf.py files") broke the setting
of _SPHINXDIRS in Documentation/Makefile. Let's just have it look for an
index.rst file instead.

Fixes: 9fc3a18a942f ("docs: remove extra conf.py files")
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Use make invocation's -j argument for parallelism

While sphinx 1.7 and later supports "-jauto" for parallelism, this
effectively ignores the "-j" flag used in the "make" invocation, which
may cause confusion for build systems. Instead, extract the available
parallelism from "make"'s job server (since it is not exposed in any
special variables) and use that for the "sphinx-build" run. Now things
work correctly for builds where -j is specified at the top-level:

make -j16 htmldocs

If -j is not specified, continue to fallback to "-jauto" if available.

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

docs: Kbuild/Makefile: allow check for missing docs at build time

While this doesn't make sense for production Kernels, in order to
avoid regressions when documents are touched, let's add a
check target at the make file.

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

docs: Completely fix the remote build tree case

My previous fix miserably failed to catch all of the invocations of
"./scripts/sphinx-pre-install", so we got build errors. Try again with
more caffeine.

Reported-by: kbuild test robot <lkp@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: look for sphinx-pre-install in the source tree

Recent makefile changes included an invocation of
./scripts/sphinx-pre-install. Unfortunately, that fails when a separate
build directory is in use with:

/bin/bash: ./scripts/sphinx-pre-install: No such file or directory

Use $(srctree) to fully specify the location of this script.

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

docs: by default, build docs a lot faster with Sphinx >= 1.7

Since Sphinx version 1.7, it is possible to use "-jauto" in
order to speedup documentation builds. On older versions,
while -j was already supported, one would need to set the
number of threads manually.

So, if SPHINXOPTS is not provided, add -jauto, in order to
speed up the build. That makes it *a lot* times faster than
without -j.

If one really wants to slow things down, it can just use:

make SPHINXOPTS=-j1 htmldocs

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
[ jc: fixed perl magic to determine sphinx version ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

scripts/sphinx-pre-install: always check if version is compatible with build

Call the script every time a make docs target is selected, on
a simplified check mode.

With this change, the script will set two vars:

$min_version - obtained from `needs_sphinx` var inside
conf.py (currently, '1.3')

$rec_version - obtained from sphinx/requirements.txt.

With those changes, a target like "make htmldocs" will do:

1) If no sphinx-build/sphinx-build3 is found, it will run
the script on normal mode as before, checking for all
system dependencies and providing install hints for the
needed programs and will abort the build;

2) If no sphinx-build/sphinx-build3 is found, but there is
a sphinx_${VER}/bin/activate file, and if
${VER} >= $min_version (string comparation), it will
run in full mode, and will recommend to activate the
virtualenv. If there are multiple virtualenvs, it
will string sort the versions, recommending the
highest version and will abort the build;

3) If Sphinx is detected but has a version lower than
$min_version, it will run in full mode - with will
recommend creating a virtual env using sphinx/requirements.txt,
and will abort the build.

4) If Sphinx is detected and version is lower than
$rec_version, it will run in full mode and will
recommend creating a virtual env using sphinx/requirements.txt.

In this case, it **won't** abort the build.

5) If Sphinx is detected and version is equal or righer than
$rec_version it will return just after detecting the
version ("quick mode"), not checking if are there any
missing dependencies.

Just like before, if one wants to install Sphinx from the
distro, it has to call the script manually and use `--no-virtualenv`
argument to get the hints for his OS:

You should run:

sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme

While here, add a small help for the three optional arguments
for the script.

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

docs: Makefile: use latexmk if available

In the past, Sphinx was generating a LaTex Makefile that would
run xelatex 3 times. Running it multiple times is needed in order
to make the indexes right.

However, newer versions of it runs it just once, as it expects
the machine to use the "latexmk" build, with automatically
detects the need for rebuilds.

So, add a logic at the Makefile in order to detect if latexmk
is installed. If so, it will call it.

As an additional bonus, the output of latexmk is a little bit
better, making easier to identify build problems.

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

kbuild: Add support for DT binding schema checks

This adds the build infrastructure for checking DT binding schema
documents and validating dts files using the binding schema.

Check DT binding schema documents:
make dt_binding_check

Build dts files and check using DT binding schema:
make dtbs_check

Optionally, DT_SCHEMA_FILES can be passed in with a schema file(s) to
use for validation. This makes it easier to find and fix errors
generated by a specific schema.

Currently, the validation targets are separate from a normal build to
avoid a hard dependency on the external DT schema project and because
there are lots of warnings generated.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mark Rutland <mark.rutland@arm.com>
Acked-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Cc: Michal Marek <michal.lkml@markovi.net>
Cc: linux-doc@vger.kernel.org
Cc: devicetree@vger.kernel.org
Cc: linux-kbuild@vger.kernel.org
Signed-off-by: Rob Herring <robh@kernel.org>

Documentation: add script and build target to check for broken file references

Add a simple script and build target to do a treewide grep for
references to files under Documentation, and report the non-existing
file in stderr. It tries to take into account punctuation not part of
the filename, and wildcards, but there are bound to be false positives
too. Mostly seems accurate though.

We've moved files around enough to make having this worthwhile.

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

doc: enhance dochelp include default output location for doc build

Enhance documentation help message to specify the default location for
the generated documents.

Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: Makefile: if sphinx is not found, run a check script

Right now, if the building system doesn't find Sphinx, it
bails out, without providing any instructions about what
should be done.

Instead, run a script, providing some guidance about the
steps needed for Sphinx build to work.

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

docs: Makefile: remove no-ops targets

After removal of DocBook, those targets are bogus.

Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: remove DocBook from the building system

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

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

samples: move blackfin gptimers-example from Documentation

Move blackfin gptimers-example to samples and remove it from Documentation
Makefile. Update samples Kconfig and Makefile to build gptimers-example.

blackfin is the last CONFIG_BUILD_DOCSRC target in Documentation/Makefile.
Hence this patch also includes changes to remove CONFIG_BUILD_DOCSRC from
Makefile and lib/Kconfig.debug and updates VIDEO_PCI_SKELETON dependency
on BUILD_DOCSRC.

Documentation/Makefile is not deleted to avoid braking make htmldocs and
make distclean.

Acked-by: Michal Marek <mmarek@suse.com>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Kees Cook <keescook@chromium.org>
Reported-by: Valentin Rothberg <valentinrothberg@gmail.com>
Reported-by: Paul Gortmaker <paul.gortmaker@windriver.com>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

tools: move pcmcia crc32hash tool from Documentation

Move pcmcia crc32hash tool from Documentation to tools/pcmcia and
remove it from Documentation Makefile. Update location information
for this tool. Create a new Makefile to build pcmcia. It can be built
from top level directory or from pcmcia directory:

Run make -C tools/pcmcia or cd tools/pcmcia; make

Acked-by: Dominik Brodowski <linux@dominikbrodowski.net>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

tools: move laptops dslm tool from Documentation

Move laptops dslm tool to tools/laptop/dslm and remove it from
Documentation Makefile. Update location information for this
tool. Create a new Makefile to build dslm. It can be built
from top level directory or from laptops directory:

Run make -C tools/laptop/dslm or cd tools/laptop/dslm; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

tools: move accounting tool from Documentation

Move accounting tool to tools and remove it from Documentation
Makefile. Update location information for this tool. Create a
new Makefile to build accounting. It can be built from top level
directory or from accounting directory:

Run make -C tools/accounting or cd tools/accounting; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

samples: move auxdisplay example code from Documentation

Move auxdisplay examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build auxdisplay. It can be built
from top level directory or from auxdisplay directory:

Run make -C samples/auxdisplay or cd samples/auxdisplay; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

samples: move watchdog example code from Documentation

Move watchdog examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build watchdog. It can be built
from top level directory or from watchdog directory:

Run make -C samples/watchdog or cd samples/watchdog; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

samples: move timers example code from Documentation

Move timers examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build timers. It can be built
from top level directory or from timers directory:

Run make -C samples/timers or cd samples/timers; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Clemens Ladisch <clemens@ladisch.de>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

samples: move misc-devices/mei example code from Documentation

Move misc-devices/mei examples to samples/mei and remove it from
Documentation Makefile. Delete misc-devices/Makefile.

Create a new Makefile to build samples/mei. It can be built from top
level directory or from mei directory:

Run make -C samples/mei or cd samples/mei; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Tomas Winkler <tomas.winkler@intel.com>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

samples: move mic/mpssd example code from Documentation

Move mic/mpssd examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build mic/mpssd. It can be built
from top level directory or from mic/mpssd directory:

Run make -C samples/mic/mpssd or cd samples/mic/mpssd; make

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

selftests: Move networking/timestamping from Documentation

Remove networking from Documentation Makefile to move the test to
selftests. Update networking/timestamping Makefile to work under
selftests. These tests will not be run as part of selftests suite
and will not be included in install targets. They can be built and
run separately for now.

This is part of the effort to move runnable code from Documentation.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

selftests: move ia64 tests from Documentation/ia64

Remove ia64 from Makefile to move the test to selftests.

Update ia64 Makefile to work under selftests. ia64 will not be run as part
of selftests suite and will not be included in install targets. They can be
built separately for now.

The original Makefile built this test on all archirectures and this update
doesn't change that.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

selftests: move vDSO tests from Documentation/vDSO

Remove vDSO from Makefile to move the to selftests. Update vDSO Makefile
to work under selftests. vDSO will not be run as part of selftests suite
and will not be included in install targets. They can be built separately
for now.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

selftests: move ptp tests from Documentation/ptp

Remove ptp from Makefile to move the test to selftests. Update ptp Makefile
to work under selftests. ptp will not be run as part of selftests suite and
will not be included in install targets. They can be built separately for
now.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

selftests: move prctl tests from Documentation/prctl

Move prctl tests from Documentation/prctl to selftests/prctl.

Remove prctl from Makefile to move the test. Update prctl Makefile to work
under selftests. prctl will not be run as part of selftests suite and will
not be included in install targets. They can be built separately for now.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

selftests: move dnotify_test from Documentation/filesystems

Move dnotify_test.c, Makefile, and .gitignore from Documentation/filesystems
to selftests/filesystems.

Remove filesystems build target from Documentation/Makefile and update
selftests/filesystems/Makefile to work under selftests. dnotify_test will
not be run as part of selftests suite and will not be included in install
targets. It can be built separately for now.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>

[media] samples: v4l: from Documentation to samples directory

With the new autoksyms support, we can run into a situation where
the v4l pci skeleton module is the only one using some exported
symbols that get dropped because they are never referenced by
the kernel otherwise, causing a build problem:

ERROR: "vb2_dma_contig_memops" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!
ERROR: "vb2_dma_contig_init_ctx_attrs" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!
ERROR: "v4l2_match_dv_timings" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!
ERROR: "v4l2_find_dv_timings_cap" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!
ERROR: "v4l2_valid_dv_timings" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!
ERROR: "v4l2_enum_dv_timings_cap" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!
ERROR: "vb2_dma_contig_cleanup_ctx" [Documentation/video4linux/v4l2-pci-skeleton.ko] undefined!

Specifically, we do look in the samples directory for users of
symbols, but not the Documentation directory.

This solves the build problem by moving the connector sample into
the same directory as the other samples.

Fixes: 23121ca2b56b ("kbuild: create/adjust generated/autoksyms.h")

Signed-off-by: Arnd Bergmann <arnd@arndb.de>

samples: v4l: from Documentation to samples directory

A small bug with the new autoksyms support showed that there are
two kernel modules in the Documentation directory that qualify
as samples, while all other samples are in the samples/ directory.

This patch was originally meant as a workaround for that bug, but
it has now been solved in a different way. However, I still think
it makes sense as a cleanup to consolidate all sample code in
one place.

Signed-off-by: Arnd Bergmann <arnd@arndb.de>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Acked-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

samples: connector: from Documentation to samples directory

A small bug with the new autoksyms support showed that there are
two kernel modules in the Documentation directory that qualify
as samples, while all other samples are in the samples/ directory.

This patch was originally meant as a workaround for that bug, but
it has now been solved in a different way. However, I still think
it makes sense as a cleanup to consolidate all sample code in
one place.

Signed-off-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

spi: Move spi code from Documentation to tools

Jon Corbet requested this code moved with the last changeset,
https://lkml.org/lkml/2015/3/1/144,
but the patch was not applied because it missed the Makefile.
Moved spidev_test, spidev_fdx and their Makefile infrastructure.

Signed-off-by: Joshua Clayton <stillcompiling@gmail.com>
Signed-off-by: Mark Brown <broonie@kernel.org>

Documentation: Remove ZBOOT MMC/SDHI utility and docs

Remove ZBOOT MMC/SDHI Documentation for sh7372 together
wit the vrl4 utility. Without sh7372 and Mackerel support
these files are no longer useful.

Signed-off-by: Magnus Damm <damm+renesas@opensource.se>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Simon Horman <horms+renesas@verge.net.au>

Documentation: add makefiles for more targets

Add a bunch of previously unbuilt source files to the Documentation build
machinery.

Signed-off-by: Peter Foley <pefoley2@pefoley.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

Documentation: use subdir-y to avoid unnecessary built-in.o files

Change the Documentation makefiles from obj-m to subdir-y
to avoid generating unnecessary built-in.o files since nothing
in Documentation/ is ever linked in to vmlinux.

Signed-off-by: Peter Foley <pefoley2@pefoley.com>
Acked-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

mei: move doc files Documentation/misc-devices/mei

1. move mei.txt, TODO, and the example code under Documentation/misc-devices/mei
2. update the TODO file

Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

mm: move hugepage test examples to tools/testing/selftests/vm

hugepage-mmap.c, hugepage-shm.c and map_hugetlb.c in Documentation/vm are
simple pass/fail tests, It's better to promote them to
tools/testing/selftests.

Thanks suggestion of Andrew Morton about this. They all need firstly
setting up proper nr_hugepages and hugepage-mmap need to mount hugetlbfs.
So I add a shell script run_vmtests to do such work which will call the
three test programs and check the return value of them.

Changes to original code including below:
a. add run_vmtests script
b. return error when read_bytes mismatch with writed bytes.
c. coding style fixes: do not use assignment in if condition

[akpm@linux-foundation.org: build the targets before trying to execute them]
[akpm@linux-foundation.org: Documentation/vm/ no longer has a Makefile. Fixes "make clean"]
Signed-off-by: Dave Young <dyoung@redhat.com>
Cc: Wu Fengguang <fengguang.wu@intel.com>
Cc: Christoph Lameter <cl@linux.com>
Cc: Pekka Enberg <penberg@cs.helsinki.fi>
Cc: Frederic Weisbecker <fweisbec@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

[media] Remove the old V4L1 v4lgrab.c file

This example file uses the old V4L1 API. It also doesn't use libv4l.
So, it is completely obsolete. A good example already exists at
v4l-utils (v4l2grab.c):
http://git.linuxtv.org/v4l-utils.git

Reviewed-by: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Documentation/fs/: split txt and source files

Make dnotify_test.c source file and add it to Makefile so that
bitrot can be prevented.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Documentation/laptop/: split txt and source files

Documentation/laptops/laptop-mode.txt:
Expose example and tool source files in the Documentation/ directory in
their own files instead of being buried (almost hidden) in readme/txt files.
This should help to prevent bitrot.

This will make them more visible/usable to users who may need
to use them, to developers who may need to test with them, and
to anyone who would fix/update them if they were more visible.

Also, if any of these possibly should not be in the kernel tree at
all, it will be clearer that they are here and we can discuss if
they should be removed.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Documentation/timers/: split txt and source files

Documentation/timers/hpet.txt:
Expose example and tool source files in the Documentation/timers/ directory in
their own files instead of being buried (almost hidden) in readme/txt files.
This should help to prevent bitrot.

This will make them more visible/usable to users who may need
to use them, to developers who may need to test with them, and
to anyone who would fix/update them if they were more visible.

Also, if any of these possibly should not be in the kernel tree at
all, it will be clearer that they are here and we can discuss if
they should be removed.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

docsrc: build Documentation/ sources

Currently source files in the Documentation/ sub-dir can easily bit-rot
since they are not generally buildable, either because they are hidden in
text files or because there are no Makefile rules for them. This needs to
be fixed so that the source files remain usable and good examples of code
instead of bad examples.

Add the ability to build source files that are in the Documentation/ dir.
Add to Kconfig as "BUILD_DOCSRC" config symbol.

Use "CONFIG_BUILD_DOCSRC=1 make ..." to build objects from the
Documentation/ sources. Or enable BUILD_DOCSRC in the *config system.
However, this symbol depends on HEADERS_CHECK since the header files need
to be installed (for userspace builds).

Built (using cross-tools) for x86-64, i386, alpha, ia64, sparc32,
sparc64, powerpc, sh, m68k, & mips.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Reviewed-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>