Commit Graph

25466 Commits

Author SHA1 Message Date
Jani Nikula
bdf107d87e DocBook: use DOCBOOKS="" to ignore DocBooks instead of IGNORE_DOCBOOKS=1
Instead of a separate ignore flag, use the obvious DOCBOOKS="" to ignore
all DocBook files. This is also in line with the Sphinx build being
ignored if a non-empty DOCBOOKS make variable is specified on the make
command line.

This replaces the IGNORE_DOCBOOKS introduced in

commit 547218864a
Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Date:   Sat Jul 9 13:12:45 2016 -0300

    doc-rst: add an option to ignore DocBooks when generating docs

and aligns with

commit 6387872c86
Author: Jani Nikula <jani.nikula@intel.com>
Date:   Fri Jul 1 15:24:44 2016 +0300

    Documentation/sphinx: skip build if user requested specific DOCBOOKS

Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-04 16:51:33 -06:00
seokhoon.yoon
09c3bcce7c Documenation: update cgroup's document path
cgroup's document path is changed to "cgroup-v1". update it.

Signed-off-by: seokhoon.yoon <iamyooon@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-03 15:43:58 -06:00
Jani Nikula
d9a77fe243 Documentation/sphinx: do not warn about missing tools in 'make help'
Simply move the dochelp rule outside of the HAVE_SPHINX check,
overriding the .DEFAULT rule for HAVE_SPHINX=0.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Christian Kujau <lists@nerdbynature.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-03 15:41:31 -06:00
Jonathan Corbet
29310a5075 Revert "doc/sphinx: Enable keep_warnings"
This reverts commit 47d6d752b9.

Commit f42ddca7be (doc-rst: kernel-doc directive, fix state machine
reporter) from Marcus Heiser provides a better fix, so this configuration
change is no longer needed.
2016-07-20 16:56:21 -06:00
Markus Heiser
f42ddca7be doc-rst: kernel-doc directive, fix state machine reporter
Add a reporter replacement that assigns the correct source name and line
number to a system message, as recorded in a ViewList.

[1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-20 16:51:12 -06:00
Jonathan Corbet
8ed292fe86 docs: deprecate kernel-doc-nano-HOWTO.txt
Now that the new Sphinx world order is taking over, the information in
kernel-doc-nano-HOWTO.txt is outmoded.  I hate to remove it altogether,
since it's one of those files that people expect to find.  But we can add a
warning and fix all the other pointers to it.

Reminded-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-20 16:45:37 -06:00
Daniel Vetter
47d6d752b9 doc/sphinx: Enable keep_warnings
Unfortunately warnings generated after parsing in sphinx can end up
with entirely bogus files and line numbers as sources. Strangely for
outright errors this is not a problem. Trying to convert warnings to
errors also doesn't fix it.

The only way to get useful output out of sphinx to be able to root
cause the error seems to be enabling keep_warnings, which inserts
a System Message into the actual output. Not pretty at all, but I
don't really want to fix up core rst/sphinx code, and this gets the job
done meanwhile.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-19 16:22:20 -06:00
Jerome Marchand
e6507a00fd Documentation: add watermark_scale_factor to the list of vm systcl file
Commit 795ae7a0de ("mm: scale kswapd watermarks in proportion to
memory") properly added the description of the new knob to
Documentation/sysctl/vm.txt, but forgot to add it to the list of files
in /proc/sys/vm. Let's fix that.

Signed-off-by: Jerome Marchand <jmarchan@redhat.com>
Acked-by: Johannes Weiner <hannes@cmpxchg.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-18 08:27:01 -06:00
Jonathan Corbet
fd7db68b93 docs: Get rid of some kernel-documentation warnings
Sphinx wants to interpret all literal blocks as being in the chosen
language and complains when an attempt to parse a block fails.
kernel-documentation.rst has a few blocks that are not in C; make that
explicit to shut down the associated warnings.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-17 19:24:02 -06:00
Mauro Carvalho Chehab
547218864a doc-rst: add an option to ignore DocBooks when generating docs
Sometimes, we want to do a partial build, instead of building
everything. However, right now, if one wants to build just
Sphinx books, it will build also the DocBooks.

Add an option to allow to ignore all DocBooks when building
documentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-09 23:15:05 -06:00
Masanari Iida
fb054c5a95 workqueue: Fix a typo in workqueue.txt
This patch fixes a spelling typo in workqueue.txt

Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Acked-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-06 02:37:38 -06:00
Masanari Iida
a039ba34a3 Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
This patch fix some spelling typo found in ocfs2-online-filecheck.txt

Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-01 16:17:15 -06:00
Jani Nikula
6387872c86 Documentation/sphinx: skip build if user requested specific DOCBOOKS
If the user requested specific DocBooks to be built using 'make
DOCBOOKS=foo.xml htmldocs', assume no Sphinx build is desired. This
check is transitional, and can be removed once we drop the DocBook
build.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Fixes: 22cba31bae ("Documentation/sphinx: add basic working Sphinx configuration and build")
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-01 16:16:07 -06:00
Jani Nikula
a569bf69f0 Documentation: add cleanmediadocs to the documentation targets
This was broken when updating the documentation targets for the Sphinx
build, and moving from %docs target pattern to explicitly listed
targets.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Fixes: 22cba31bae ("Documentation/sphinx: add basic working Sphinx configuration and build")
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-01 16:15:31 -06:00
Jonathan Corbet
19abdb15f3 Add .pyc files to .gitignore
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-30 13:07:33 -06:00
Masanari Iida
05d0066a57 Doc: PM: Fix a typo in intel_powerclamp.txt
This patch fix a spelling typo in intel_powerclamp.txt

Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-30 13:05:40 -06:00
Markus Heiser
0249a76448 doc-rst: flat-table directive - initial implementation
Implements the reST flat-table directive.

The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:

* column-span: with the role ``cspan`` a cell can be extended through
  additional columns

* row-span: with the role ``rspan`` a cell can be extended through
  additional rows

* auto span rightmost cell of a table row over the missing cells on the right
  side of that table-row.  With Option ``:fill-cells:`` this behavior can
  changed from *auto span* to *auto fill*, which automaticly inserts (empty)

list tables

  The *list tables* formats are double stage lists. Compared to the
  ASCII-art they migth be less comfortable for readers of the
  text-files. Their advantage is, that they are easy to create/modify
  and that the diff of a modification is much more meaningfull, because
  it is limited to the modified content.

The initial implementation was taken from the sphkerneldoc project [1]

[1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-30 12:58:33 -06:00
Jani Nikula
17defc282f 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>
2016-06-24 06:55:28 -06:00
Michal Nazarewicz
072baa0371 Documentation: tiny typo fix in usb/gadget_multi.txt
Signed-off-by: Michal Nazarewicz <mina86@mina86.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 08:09:10 -06:00
Tiezhu Yang
a37376f326 Documentation: fix wrong value in md.txt
In the current Documentation/md.txt, the lower limit value of
stripe_cache_size is 16 and the default value is 128, but when
I update kernel to the latest mainline version and RAID5 array
is created by mdadm, then execute the following commands, it
shows an error and a difference respectively.

1) set stripe_cache_size to 16
[root@localhost ~]# echo 16 > /sys/block/md0/md/stripe_cache_size
bash: echo: write error: Invalid argument
2) read the default value of stripe_cache_size
[root@localhost ~]# cat /sys/block/md0/md/stripe_cache_size
256

I read drivers/md/raid5.c and find the following related code:
1) in function 'raid5_set_cache_size':
if (size <= 16 || size > 32768)
	return -EINVAL;
2) #define NR_STRIPES		256

So the lower limit value of stripe_cache_size should be 17 and
the default value should be 256.

Signed-off-by: Tiezhu Yang <kernelpatch@126.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 08:08:36 -06:00
Eric Wheeler
c0b8c9a344 bcache: documentation formatting, edited for clarity, stripe alignment notes
Signed-off-by: Eric Wheeler <bcache@linux.ewheeler.net>
Cc: Marc MERLIN <marc@merlins.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 07:58:38 -06:00
Marc MERLIN
c9b2ffc022 bcache: documentation updates and corrections
Bcache documentation updates:
- Added new HOWTO/COOKBOOK section
- fixed a few typos
- /sys/block/bcache0/cache_mode is /sys/block/bcache0/bcache/cache_mode

Signed-off-by: Marc MERLIN <marc@merlins.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 07:57:03 -06:00
Jani Nikula
ebc88ef05c Documentation: add top level 'make help' output for Sphinx
While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-23 15:11:51 +03:00
Jani Nikula
0cea220cf7 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>
2016-06-23 15:11:35 +03:00
Jani Nikula
03d35d9ec4 Documentation/sphinx: add support for specifying extra export files
Let the user specify file patterns where to look for the EXPORT_SYMBOLs
in addition to the file with kernel-doc comments. This is directly based
on the -export-file FILE option added to kernel-doc in "kernel-doc: add
support for specifying extra files for EXPORT_SYMBOLs", but we extend
that with globbing patterns in the Sphinx extension.

The file patterns are added as options to the :export: and :internal:
arguments of the kernel-doc directive. For example, to extract the
documentation of exported functions from include/net/mac80211.h:

.. kernel-doc:: include/net/mac80211.h
   :export: net/mac80211/*.c

Without the file pattern, no exported functions would be found, as the
EXPORT_SYMBOLs are placed in the various source files under
net/mac80211.

The matched files are also added as dependencies on the document in
Sphinx, as they may affect the output. This is one of the reasons to do
the globbing in the Sphinx extension instead of in scripts/kernel-doc.

The file pattern remains optional, and is not needed if the kernel-doc
comments and EXPORT_SYMBOLs are placed in the source file passed in as
the main argument to the kernel-doc directive. This is the most common
case across the kernel source tree.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10 16:46:55 +03:00
Jani Nikula
057de5c4dd Documentation/sphinx: use a more sensible string split in kernel-doc extension
Using the default str.split doesn't return empty strings like the
current version does.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10 11:29:21 +03:00
Jani Nikula
06173fe33a Documentation/sphinx: remove unnecessary temporary variable
Leftover cruft. No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10 11:29:20 +03:00
Kees Cook
c9de4a82c8 docs: self-protection: rename "leak" to "exposure"
The meaning of "leak" can be both "untracked resource allocation" and
"memory content disclosure". This document's use was entirely of the
latter meaning, so avoid the confusion by using the Common Weakness
Enumeration name for this: Information Exposure (CWE-200). Additionally
adds a section on structure randomization.

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-09 13:23:27 -06:00
Jonathan Corbet
6d5244c72e Merge branch 'sphinx-for-docs-next' into doc/4.8
Jani Nikula says:

Jon, this is v2 of [1] and [2], with a considerable amount of polish and
fixes added. We started dogfooding this within drm-intel, and Daniel has
reviewed the lot and contributed a number of fixes, most notably
accurate file and line number references from Sphinx build
errors/warnings to the kernel-doc comments in source code.

We believe this is now in good shape for merging for v4.8. It's all in
my sphinx-for-docs-next branch that you've already looked at; pull
details below.

When this lands in docs-next and we can backmerge to drm, we'll plunge
ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We
think it's best to contribute that via the drm tree, as it'll involve
splitting up the documentation and likely numerous updates to kernel-doc
comments.

I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and
rst, obviously converting it to rst while at it.
2016-06-09 13:17:11 -06:00
Daniel Vetter
d90368f2fa doc/sphinx: Track line-number of starting blocks
Design is pretty simple: kernel-doc inserts breadcrumbs with line
numbers, and sphinx picks them up. At first I went with a sphinx
comment, but inserting those at random places seriously upsets the
parser, and must be filtered. Hence why this version now uses "#define
LINEO " since one of these ever escape into output it's pretty clear
there is a bug.

It seems to work well, and at least the 2-3 errors where sphinx
complained about something that was not correct in kernel-doc text the
line numbers matched up perfectly.

v2: Instead of noodling around in the parser state machine, create
a ViewList and parse it ourselves. This seems to be the recommended
way, per Jani's suggestion.

v3:
- Split out ViewList pach. Splitting the kernel-doc changes from the
  sphinx ones isn't possible, since emitting the LINENO lines wreaks
  havoc with the rst formatting. We must filter them.

- Improve the regex per Jani's suggestions, and compile it just once
  for speed.

- Now that LINENO lines are eaten, also add them to function parameter
  descriptions. Much less content and offset than for in-line struct
  member descriptions, but still nice to know which exact continuation
  line upsets sphinx.

- Simplify/clarify the line +/-1 business a bit.

v4: Split out the scripts/kernel-doc changes and make line-numbers
opt-in, as suggested by Jani.

Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-04 11:35:59 +03:00
Niklas Söderlund
f3e6a55c36 Documentation: dmaengine: fix typo for device_resume
Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-03 14:00:21 -06:00
Andy Deng
49e48419ad Documentation/zh_CN: update Chinese version CodingStyle
Chinese version CodingStyle is a little outdate, it should be updated.

This patch sync with the latest CodingStyle of all changes,
new chapters (chapter 19 and chapter 20) have been translated.

Signed-off-by: Andy Deng <theandy.deng@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-03 13:35:06 -06:00
Brian Norris
d81749ea8b doc: clarify that trace_events= takes a comma-separated list
It took me browsing through the source code to determine that I was,
indeed, using the wrong delimiter in my command lines. So I might as
well document it for the next person.

Signed-off-by: Brian Norris <computersforpeace@gmail.com>
Acked-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-03 13:32:58 -06:00
Mike Danese
3610a2add3 mpssd: fix buffer overflow warning
The compilation emits a warning in function ‘snprintf’,
    inlined from ‘set_cmdline’ at
    ../Documentation/mic/mpssd/mpssd.c:1541:9:
/usr/include/x86_64-linux-gnu/bits/stdio2.h:64:10:
    warning: call to __builtin___snprintf_chk will always overflow
    destination buffer

This was introduced in commit f4a66c2044 ("misc: mic: Update MIC host
daemon with COSM changes") and is fixed by reverting the changes to the
size argument of these snprintf statements.

Cc: Ashutosh Dixit <ashutosh.dixit@intel.com>
Signed-off-by: Mike Danese <mikedanese@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-03 13:31:37 -06:00
Javier Martinez Canillas
fac8434dab Documentation: Fix some grammar mistakes in sync_file.txt
There are two sentences in the Sync File documentation where the
english is a little off. This patch is an attempt to fix these.

Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Reviewed-by: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-03 13:24:16 -06:00
Daniel Vetter
16e161c8c6 doc/sphinx: Stop touching state_machine internals
Instead of just forcefully inserting our kernel-doc input and letting
the state machine stumble over it the recommended way is to create
ViewList, parse that and then return the list of parsed nodes.

Suggested by Jani.

Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-03 11:31:37 +03:00
Daniel Vetter
9cc1a44c03 doc/sphinx: Pass right filename as source
With this error output becomes almost readable. The line numbers are
still totally bonghits, but that's a lot harder to pull out of
kerneldoc. We'd essentially have to insert some special markers in the
kernel-doc output, split the output along these markers and then
insert each block separately using

     state_machine.insert_input(block, source, first_line)

Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-01 12:28:31 +03:00
Jani Nikula
ba35018593 Documentation/sphinx: fix kernel-doc extension on python3
Reconcile differences between python2 and python3 on dealing with
stdout, stderr from Popen. This fixes "name 'unicode' is not defined"
errors on python3. We'll need to try to keep the extension working on
both python-sphinx and python3-sphinx so we don't need two copies.

Reported-and-tested-by: Marius Vlad <marius.c.vlad@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-01 11:06:58 +03:00
Jani Nikula
30ca7aaf27 Documentation/sphinx: nicer referencing of struct in docbook->rst conversion
Add "struct" in the label of the reference.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:54 +03:00
Jani Nikula
2e83ecb834 sphinx: update docbook->rst conversion script match C domain spec
Function references should include the parens (), struct references
should not include "struct".

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:53 +03:00
Jonathan Corbet
89a66d7610 sphinx: cheesy script to convert .tmpl files
This script uses pandoc to convert existing DocBook template files to RST
templates.  A couple of sed scripts are need to massage things both before
and after the conversion, but the result is then usable with no hand
editing.

[Jani: Change usage to tmplcvt <in> <out>. Fix escaping for docproc
directives. Add support the new kernel-doc extension.]

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:53 +03:00
Jani Nikula
c13ce448c8 Documentation/sphinx: set version and release properly
Read the version and release from the top level Makefile (for use when
Sphinx is invoked directly, by e.g. Read the Docs), but override them
via Sphinx command line arguments in a normal documentation build.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:53 +03:00
Jani Nikula
24dcdeb28b Documentation/sphinx: configure the kernel-doc extension
Tell Sphinx where to find the extension, and pass on the kernel src tree
and kernel-doc paths to the extension.

With this, any .rst files under Documentation may contain the kernel-doc
rst directive to include kernel-doc documentation from any source file.

While building, it may be handy to pass kernel-doc extension
configuration on the command line. For example, 'make SPHINXOPTS="-D
kerneldoc_verbosity=0" htmldocs' silences all stderr output from
kernel-doc when the kernel-doc exit code is 0. (The stderr will be
logged unconditionally when the exit code is non-zero.)

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:52 +03:00
Jani Nikula
c56de1db54 Documentation/sphinx: add Sphinx kernel-doc directive extension
Add an extension to handle kernel-doc directives, to call kernel-doc
according to the arguments and parameters given to the reStructuredText
directive.

The syntax for the kernel-doc directive is:

.. kernel-doc:: FILENAME
   :export:
   :internal:
   :functions: FUNCTION [FUNCTION ...]
   :doc: SECTION TITLE

Of the directive options export, internal, functions, and doc, currently
only one option may be given at a time.

The FILENAME is relative from the kernel source tree root.

The extension notifies Sphinx about the document dependency on FILENAME,
causing the document to be rebuilt when the file has been changed.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:52 +03:00
Jani Nikula
81cd318102 Documentation: add .gitignore
The Sphinx output directory is generated.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:51 +03:00
Jani Nikula
22cba31bae 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>
2016-05-30 13:38:51 +03:00
Linus Torvalds
4029632c34 Merge branch 'upstream' of git://git.linux-mips.org/pub/scm/ralf/upstream-linus
Pull more MIPS updates from Ralf Baechle:
 "This is the secondnd batch of MIPS patches for 4.7. Summary:

  CPS:
   - Copy EVA configuration when starting secondary VPs.

  EIC:
   - Clear Status IPL.

  Lasat:
   - Fix a few off by one bugs.

  lib:
   - Mark intrinsics notrace.  Not only are the intrinsics
     uninteresting, it would cause infinite recursion.

  MAINTAINERS:
   - Add file patterns for MIPS BRCM device tree bindings.
   - Add file patterns for mips device tree bindings.

  MT7628:
   - Fix MT7628 pinmux typos.
   - wled_an pinmux gpio.
   - EPHY LEDs pinmux support.

  Pistachio:
   - Enable KASLR

  VDSO:
   - Build microMIPS VDSO for microMIPS kernels.
   - Fix aliasing warning by building with `-fno-strict-aliasing' for
     debugging but also tracing them might result in recursion.

  Misc:
   - Add missing FROZEN hotplug notifier transitions.
   - Fix clk binding example for varioius PIC32 devices.
   - Fix cpu interrupt controller node-names in the DT files.
   - Fix XPA CPU feature separation.
   - Fix write_gc0_* macros when writing zero.
   - Add inline asm encoding helpers.
   - Add missing VZ accessor microMIPS encodings.
   - Fix little endian microMIPS MSA encodings.
   - Add 64-bit HTW fields and fix its configuration.
   - Fix sigreturn via VDSO on microMIPS kernel.
   - Lots of typo fixes.
   - Add definitions of SegCtl registers and use them"

* 'upstream' of git://git.linux-mips.org/pub/scm/ralf/upstream-linus: (49 commits)
  MIPS: Add missing FROZEN hotplug notifier transitions
  MIPS: Build microMIPS VDSO for microMIPS kernels
  MIPS: Fix sigreturn via VDSO on microMIPS kernel
  MIPS: devicetree: fix cpu interrupt controller node-names
  MIPS: VDSO: Build with `-fno-strict-aliasing'
  MIPS: Pistachio: Enable KASLR
  MIPS: lib: Mark intrinsics notrace
  MIPS: Fix 64-bit HTW configuration
  MIPS: Add 64-bit HTW fields
  MAINTAINERS: Add file patterns for mips device tree bindings
  MAINTAINERS: Add file patterns for mips brcm device tree bindings
  MIPS: Simplify DSP instruction encoding macros
  MIPS: Add missing tlbinvf/XPA microMIPS encodings
  MIPS: Fix little endian microMIPS MSA encodings
  MIPS: Add missing VZ accessor microMIPS encodings
  MIPS: Add inline asm encoding helpers
  MIPS: Spelling fix lets -> let's
  MIPS: VR41xx: Fix typo
  MIPS: oprofile: Fix typo
  MIPS: math-emu: Fix typo
  ...
2016-05-28 16:41:39 -07:00
Linus Torvalds
0723ab4a97 sound updates #2 for 4.7-rc1
This is the second update round for 4.7-rc1.  Most of changes are
 about the pending ASoC updates and fixes, including a few new
 drivers.  Below are some highlights:
 
 ASoC:
 - New drivers for MAX98371 and TAS5720
 - SPI support for TLV320AIC32x4, along with the module split
 - TDM support for STI Uniperf IPs
 - Remaining topology API fixes / updates
 
 HDA:
 - A couple of Dell quirks and new Realtek codec support
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v2
 
 iQIcBAABCAAGBQJXSLGwAAoJEGwxgFQ9KSmkKz4P/2xpAXcwjT/g/WgeNVsZLnxd
 vs1KlMPSWXLHY7ESZB+oDYtw5pAQWta2gKnG3T0QpkEtyqcyvEAUch55SfPbkDWz
 bRwboK91NF9Cfrso+QnUG1HdpaeDsNydiAR5u2sdemQG+rh8TmWXNmFsuqPptjbm
 LP6Spf8Ia2TYAvagZOB+2UTl7Jq8jMXiYP3aGWMHm7P/kREMQkSWcQ9U8F8UK92G
 5D0qKGvChsd23ybGUL1nBM7wBvErFoKd4Xa1zMudQt8EkTjistdgm24v3PO+lKDv
 JYiEugOZctzqtQVUlQMXcIqrlsafXwJN7ttKGst9gj32bM+a7EW0TGG0KyhxXI5w
 fRgGU7AJwncs9hBzEPBfc6Jms85THN2HpusU61ZYpyFAhLnHAOL7iIZnNKY8Pyyg
 tOPY2lTwHD9ic9EiC33/IypT50n0lBOi7X+YE7lGWdm2jXNvxtFv1jUw99kx25fj
 UaFNQaDYXXDKO1POCFrHpIq+jJ71Jmk7mXktI75wfuLyX3PSPyFg8OBbYVbTWkbL
 xdSqBs6LCESZ1iV9mauxwPSex44BpaMB3E0TA+7iN3+0Uwdfxe0OoLnX6dGiLSZJ
 QenFu/EDdCsA8rlrDy7AS1e5ulpYsTY1KGSZbfNzMdNsmD2XC3FdZHEF5PAC4wZQ
 EnNaik6InJgHlMF/6MXo
 =uNKQ
 -----END PGP SIGNATURE-----

Merge tag 'sound-4.7-rc1-2' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound

Pull more sound updates from Takashi Iwai:
 "This is the second update round for 4.7-rc1.  Most of changes are
  about the pending ASoC updates and fixes, including a few new drivers.
  Below are some highlights:

  ASoC:
   - New drivers for MAX98371 and TAS5720
   - SPI support for TLV320AIC32x4, along with the module split
   - TDM support for STI Uniperf IPs
   - Remaining topology API fixes / updates

  HDA:
   - A couple of Dell quirks and new Realtek codec support"

* tag 'sound-4.7-rc1-2' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound: (63 commits)
  ALSA: hda - Fix headset mic detection problem for one Dell machine
  spi: spi-ep93xx: Fix the PTR_ERR() argument
  ALSA: hda/realtek - Add support for ALC295/ALC3254
  ASoC: kirkwood: fix build failure
  ALSA: hda - Fix headphone noise on Dell XPS 13 9360
  ASoC: ak4642: Enable cache usage to fix crashes on resume
  ASoC: twl6040: Disconnect AUX output pads on digital mute
  ASoC: tlv320aic32x4: Properly implement the positive and negative pins into the mixers
  rcar: src: skip disabled-SRC nodes
  ASoC: max98371 Remove duplicate entry in max98371_reg
  ASoC: twl6040: Select LPPLL during standby
  ASoC: rsnd: don't use prohibited number to PDMACHCRn.SRS
  ASoC: simple-card: Add pm callbacks to platform driver
  ASoC: pxa: Fix module autoload for platform drivers
  ASoC: topology: Fix memory leak in widget creation
  ASoC: Add max98371 codec driver
  ASoC: rsnd: count .probe/.remove for rsnd_mod_call()
  ASoC: topology: Check size mismatch of ABI objects before parsing
  ASoC: topology: Check failure to create a widget
  ASoC: add support for TAS5720 digital amplifier
  ...
2016-05-28 12:23:12 -07:00
Linus Torvalds
9ba55cf7cf Merge branch 'for-next' of git://git.kernel.org/pub/scm/linux/kernel/git/nab/target-pending
Pull SCSI target updates from Nicholas Bellinger:
 "Here are the outstanding target pending updates for v4.7-rc1.

  The highlights this round include:

   - Allow external PR/ALUA metadata path be defined at runtime via top
     level configfs attribute (Lee)
   - Fix target session shutdown bug for ib_srpt multi-channel (hch)
   - Make TFO close_session() and shutdown_session() optional (hch)
   - Drop se_sess->sess_kref + convert tcm_qla2xxx to internal kref
     (hch)
   - Add tcm_qla2xxx endpoint attribute for basic FC jammer (Laurence)
   - Refactor iscsi-target RX/TX PDU encode/decode into common code
     (Varun)
   - Extend iscsit_transport with xmit_pdu, release_cmd, get_rx_pdu,
     validate_parameters, and get_r2t_ttt for generic ISO offload
     (Varun)
   - Initial merge of cxgb iscsi-segment offload target driver (Varun)

  The bulk of the changes are Chelsio's new driver, along with a number
  of iscsi-target common code improvements made by Varun + Co along the
  way"

* 'for-next' of git://git.kernel.org/pub/scm/linux/kernel/git/nab/target-pending: (29 commits)
  iscsi-target: Fix early sk_data_ready LOGIN_FLAGS_READY race
  cxgbit: Use type ISCSI_CXGBIT + cxgbit tpg_np attribute
  iscsi-target: Convert transport drivers to signal rdma_shutdown
  iscsi-target: Make iscsi_tpg_np driver show/store use generic code
  tcm_qla2xxx Add SCSI command jammer/discard capability
  iscsi-target: graceful disconnect on invalid mapping to iovec
  target: need_to_release is always false, remove redundant check and kfree
  target: remove sess_kref and ->shutdown_session
  iscsi-target: remove usage of ->shutdown_session
  tcm_qla2xxx: introduce a private sess_kref
  target: make close_session optional
  target: make ->shutdown_session optional
  target: remove acl_stop
  target: consolidate and fix session shutdown
  cxgbit: add files for cxgbit.ko
  iscsi-target: export symbols
  iscsi-target: call complete on conn_logout_comp
  iscsi-target: clear tx_thread_active
  iscsi-target: add new offload transport type
  iscsi-target: use conn_transport->transport_type in text rsp
  ...
2016-05-28 12:04:17 -07:00
Linus Torvalds
1cbe06c3cf Round two of 4.7 merge window patches
- Dynamic counter infrastructure in the IB drivers
   This is a sysfs based code to allow free form access to the hardware
   counters RDMA devices might support so drivers don't need to code
   this up repeatedly themselves
 - SendOnlyFullMember multicast support
 - IB router support
 - A couple misc fixes
 - The big item on the list: hfi1 driver updates, plus moving the hfi1
   driver out of staging
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJXRyupAAoJELgmozMOVy/deHAQAJp87yn8hntHXh81Kjrvezch
 McJ0v7FTsfsLVe/Y+YAbaAREjanhnUDzZ36WUqS9rHadOl+Ia0fD+M53aTk9hDKS
 R9/oWQDsUb8k7imdhNrSS72Q2kbwr++8RqBoEEFcl4fuDCVsrRhUaf+perJTEnoK
 I9APDQCNU3FCTPFRllK5al6gi5UGEW9vO9JQZb+VnTVW9+LjlYobzcZfttAw8oRN
 rtQLP3xGb7ZwV0ngH0dt2TthN2ih97TavnISojTdJ5I+WHFxLV0YbHSK/E2JLdoi
 hVknhrflPIKr+mRVv97yCCz92kGAdTKG3sT9vNUVUQ0Y8kEdrW/LrnrmxsBEYzkl
 GcQeqg7//ffOlQ0dGZZjlkPg/8yMPo9CBsfPDcOvXeenK0lkao9qg2yrIz+CBC/9
 YlpUKfL0JLRal9O6y3Mh++ZQ9R1kvQN8/CgHLUlRQdWLfxf7VPA4rIcaWT7iGfvg
 z6jIJKjsK+hqKhY9oKh3YfNmXh65IQ5OF3+tBzHKwNiGXNSsMYAVYP3vc/HYTJvz
 4EpsenndKb5l0AOvDch8rMmw7YZPf2NOdi90TW6Bq1VgTIDRxh0WzR2QTnWBVRSf
 XAcC3DLXTHqC/UUpHrdXgfvU/0nQXaVUvPWIAM/t3hy91GLscByDw4973+tISs/B
 7AHSptbVQaBUpTjWHfKf
 =5+cf
 -----END PGP SIGNATURE-----

Merge tag 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dledford/rdma

Pull more rdma updates from Doug Ledford:
 "This is the second group of code for the 4.7 merge window.  It looks
  large, but only in one sense.  I'll get to that in a minute.  The list
  of changes here breaks down as follows:

   - Dynamic counter infrastructure in the IB drivers

     This is a sysfs based code to allow free form access to the
     hardware counters RDMA devices might support so drivers don't need
     to code this up repeatedly themselves

   - SendOnlyFullMember multicast support

   - IB router support

   - A couple misc fixes

   - The big item on the list: hfi1 driver updates, plus moving the hfi1
     driver out of staging

  There was a group of 15 patches in the hfi1 list that I thought I had
  in the first pull request but they weren't.  So that added to the
  length of the hfi1 section here.

  As far as these go, everything but the hfi1 is pretty straight
  forward.

  The hfi1 is, if you recall, the driver that Al had complaints about
  how it used the write/writev interfaces in an overloaded fashion.  The
  write portion of their interface behaved like the write handler in the
  IB stack proper and did bi-directional communications.  The writev
  interface, on the other hand, only accepts SDMA request structures.
  The completions for those structures are sent back via an entirely
  different event mechanism.

  With the security patch, we put security checks on the write
  interface, however, we also knew they would be going away soon.  Now,
  we've converted the write handler in the hfi1 driver to use ioctls
  from the IB reserved magic area for its bidirectional communications.
  With that change, Intel has addressed all of the items originally on
  their TODO when they went into staging (as well as many items added to
  the list later).

  As such, I moved them out, and since they were the last item in the
  staging/rdma directory, and I don't have immediate plans to use the
  staging area again, I removed the staging/rdma area.

  Because of the move out of staging, as well as a series of 5 patches
  in the hfi1 driver that removed code people thought should be done in
  a different way and was optional to begin with (a snoop debug
  interface, an eeprom driver for an eeprom connected directory to their
  hfi1 chip and not via an i2c bus, and a few other things like that),
  the line count, especially the removal count, is high"

* tag 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dledford/rdma: (56 commits)
  staging/rdma: Remove the entire rdma subdirectory of staging
  IB/core: Make device counter infrastructure dynamic
  IB/hfi1: Fix pio map initialization
  IB/hfi1: Correct 8051 link parameter settings
  IB/hfi1: Update pkey table properly after link down or FM start
  IB/rdamvt: Fix rdmavt s_ack_queue sizing
  IB/rdmavt: Max atomic value should be a u8
  IB/hfi1: Fix hard lockup due to not using save/restore spin lock
  IB/hfi1: Add tracing support for send with invalidate opcode
  IB/hfi1, qib: Add ieth to the packet header definitions
  IB/hfi1: Move driver out of staging
  IB/hfi1: Do not free hfi1 cdev parent structure early
  IB/hfi1: Add trace message in user IOCTL handling
  IB/hfi1: Remove write(), use ioctl() for user cmds
  IB/hfi1: Add ioctl() interface for user commands
  IB/hfi1: Remove unused user command
  IB/hfi1: Remove snoop/diag interface
  IB/hfi1: Remove EPROM functionality from data device
  IB/hfi1: Remove UI char device
  IB/hfi1: Remove multiple device cdev
  ...
2016-05-28 11:04:16 -07:00