Due to a limitation at the DocBook language, the references
were using lowercase and slashes, instead of the name of the
ioctls. On ReST, make them identical. This will hopefully
help to cleanup the code a little bit.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There are several constants there that should be, instead,
cross-references. Fix them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There are two examples in the code, but the captions of them
were lost during the ReST conversion. Manually add them again.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The Video4Linux documentation is big. We want to numerate the
items, as it makes easier to reference an item while discussing
the document on meetings.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Instead of using const, transform it into a reference.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

What should be a reference to VIDIOC_S_PRIORITY was incorrectly
defined as a constant at the DocBook. Fix it on the rst version.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Make easier to navigate at the media document by adding the
links to each of the parts of the document.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This is not due to the format change, but there are some
wrong references on this file. Fix them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The conversion of the authors and revision history lists
didn't end too well.

Manually fix them.

The revision history still needs some care in the future.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Fix some issues from the conversion and improve the documentation
a little bit, by adding two relevent keywords (SDR and DTMB).
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The RST version was produced in 2016. So, update it where
it was still pointing to the wrong year.

While here, added the missing (copyright) symbols.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This is the restructuredText (reST) migration of the ``media``
DocBook-XML set from the linux_tv project.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

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

This patch fix a spelling typo in intel_powerclamp.txt
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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.pySigned-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
[jc: fixed typos and misspellings in the docs]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NMichal Nazarewicz <mina86@mina86.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NTiezhu Yang <kernelpatch@126.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NEric Wheeler <bcache@linux.ewheeler.net>
Cc: Marc MERLIN <marc@merlins.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NMarc MERLIN <marc@merlins.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

The modindex is for python modules.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NJani Nikula <jani.nikula@intel.com>

Using the default str.split doesn't return empty strings like the
current version does.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Leftover cruft. No functional changes.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a DT binding documentation of Video Processor Unit for the
MT8173 SoC from Mediatek.
Signed-off-by: NAndrew-CT Chen <andrew-ct.chen@mediatek.com>
Signed-off-by: NTiffany Lin <tiffany.lin@mediatek.com>
Acked-by: NRob Herring <robh@kernel.org>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

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: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Signed-off-by: NNiklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NAndy Deng <theandy.deng@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NBrian Norris <computersforpeace@gmail.com>
Acked-by: NSteven Rostedt <rostedt@goodmis.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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 f4a66c20 ("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: NMike Danese <mikedanese@google.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NJavier Martinez Canillas <javier@osg.samsung.com>
Reviewed-by: NGustavo Padovan <gustavo.padovan@collabora.co.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Use generic reserved memory bindings and mark old, custom properties
as obsoleted.
Signed-off-by: NMarek Szyprowski <m.szyprowski@samsung.com>
Reviewed-by: NJavier Martinez Canillas <javier@osg.samsung.com>
Acked-by: NRob Herring <robh@kernel.org>
Acked-by: NKrzysztof Kozlowski <k.kozlowski@samsung.com>
Signed-off-by: NSylwester Nawrocki <s.nawrocki@samsung.com>

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: NDaniel Vetter <daniel.vetter@intel.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NDaniel Vetter <daniel.vetter@intel.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NMarius Vlad <marius.c.vlad@intel.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Add "struct" in the label of the reference.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Function references should include the parens (), struct references
should not include "struct".
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NJonathan Corbet <corbet@lwn.net>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>