* [PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Since Sphinx 3.0, the C domain code was rewritten, but only
after version 3.1 it got support for setting namespaces on
C domains, with is something that it is required, in order to
document system calls, like ioctl() and others.
As part of changing the documentation subsystem to properly
build with Sphinx 3.1+, add support for such new tag:
.. c:namespace::"
Such tag optionally replaces the optional "name" tag for functions,
setting a single namespace domain for all C references found
at the file.
With that, it should be possible to convert existing
documentation to be compatible with both Sphinx 1.x/2.x and
3.1+.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++-
1 file changed, 54 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index cbac8e608dc4..35805c44a4fc 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -40,14 +40,56 @@ from sphinx import addnodes
from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
from sphinx.domains.c import CObject as Base_CObject
from sphinx.domains.c import CDomain as Base_CDomain
+from itertools import chain
+import re
-__version__ = '1.0'
+__version__ = '1.1'
# Get Sphinx version
major, minor, patch = sphinx.version_info[:3]
+# Namespace to be prepended to the full name
+namespace = None
+
+#
+# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
+# - Store the namespace if ".. c:namespace::" tag is found
+
+RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
+
+def markup_namespace(match):
+ global namespace
+
+ namespace = match.group(1)
+
+ return ""
+
+def c_markups(app, docname, source):
+ result = ""
+ markup_func = {
+ RE_namespace: markup_namespace,
+ }
+
+ lines = iter(source[0].splitlines(True))
+ for n in lines:
+ match_iterators = [regex.finditer(n) for regex in markup_func]
+ matches = sorted(chain(*match_iterators), key=lambda m: m.start())
+ for m in matches:
+ n = n[:m.start()] + markup_func[m.re](m) + n[m.end():]
+
+ result = result + n
+
+ source[0] = result
+
+#
+# Now implements support for the cdomain namespacing logic
+#
+
def setup(app):
+ # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
+ app.connect('source-read', c_markups)
+
if (major == 1 and minor < 8):
app.override_domain(CDomain)
else:
@@ -75,6 +117,8 @@ class CObject(Base_CObject):
function-like macro, the name of the macro is returned. Otherwise
``False`` is returned. """
+ global namespace
+
if not self.objtype == 'function':
return False
@@ -107,11 +151,16 @@ class CObject(Base_CObject):
param += nodes.emphasis(argname, argname)
paramlist += param
+ if namespace:
+ fullname = namespace + "." + fullname
+
return fullname
def handle_signature(self, sig, signode):
"""Transform a C signature into RST nodes."""
+ global namespace
+
fullname = self.handle_func_like_macro(sig, signode)
if not fullname:
fullname = super(CObject, self).handle_signature(sig, signode)
@@ -122,6 +171,10 @@ class CObject(Base_CObject):
else:
# FIXME: handle :name: value of other declaration types?
pass
+ else:
+ if namespace:
+ fullname = namespace + "." + fullname
+
return fullname
def add_target_and_index(self, name, sig, signode):
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
` (50 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
While most of the C domain parsing is done via kernel-doc,
some RST files use C domain tags directly.
While several of them can be removed for Sphinx < 3.0, due
to automarkup.py, and several others that could be
converted into kernel-doc markups, changes like that are
time-consuming, and may not fit all cases.
As we already have the cdomain.py for handing backward
compatibility with Sphinx versions below 3.0, let's
make it more complete, in order to cover any usage of the
newer tags outside kernel-doc.
This way, it should be feasible to use the new tags inside
the Kernel tree, without losing backward compatibility.
This should allow fixing the remaining warnings with
the Kernel tags.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/cdomain.py | 40 ++++++++++++++++++++++++++++++++-
1 file changed, 39 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 35805c44a4fc..014a5229e57a 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -54,7 +54,7 @@ namespace = None
#
# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
# - Store the namespace if ".. c:namespace::" tag is found
-
+#
RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
def markup_namespace(match):
@@ -64,10 +64,48 @@ def markup_namespace(match):
return ""
+#
+# Handle c:macro for function-style declaration
+#
+RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$')
+def markup_macro(match):
+ return ".. c:function:: " + match.group(1) + ' ' + match.group(2)
+
+#
+# Handle newer c domain tags that are evaluated as .. c:type: for
+# backward-compatibility with Sphinx < 3.0
+#
+RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$')
+
+def markup_ctype(match):
+ return ".. c:type:: " + match.group(2)
+
+#
+# Handle newer c domain tags that are evaluated as :c:type: for
+# backward-compatibility with Sphinx < 3.0
+#
+RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`')
+def markup_ctype_refs(match):
+ return ":c:type:`" + match.group(2) + '`'
+
+#
+# Simply convert :c:expr: and :c:texpr: into a literal block.
+#
+RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`')
+def markup_c_expr(match):
+ return '\ ``' + match.group(2) + '``\ '
+
+#
+# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones
+#
def c_markups(app, docname, source):
result = ""
markup_func = {
RE_namespace: markup_namespace,
+ RE_expr: markup_c_expr,
+ RE_macro: markup_macro,
+ RE_ctype: markup_ctype,
+ RE_ctype_refs: markup_ctype_refs,
}
lines = iter(source[0].splitlines(True))
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
` (49 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
The class types changed after the C domain rewrite on
Sphinx 3.x. Due to that, the automarkup extension is just
generating additional noise when trying to convert structs
and other markups into cross references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0a102d57437d..3875401486de 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,7 @@ needs_sphinx = '1.3'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
- 'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
+ 'kfigure', 'sphinx.ext.ifconfig',
'maintainers_include', 'sphinx.ext.autosectionlabel' ]
#
@@ -52,6 +52,7 @@ if major >= 3:
''')
else:
extensions.append('cdomain')
+ extensions.append('automarkup')
# Ensure that autosectionlabel will produce unique names
autosectionlabel_prefix_document = True
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with Sphinx 3.x
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (2 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-10-01 21:41 ` Jonathan Corbet
2020-09-30 13:24 ` [PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on " Mauro Carvalho Chehab
` (48 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:
.. c:type:: typedef-like declaration
.. c:type:: name
Using it for other types (including functions) don't work anymore.
So, there are newer tags for macro, enum, struct, union, and others,
which doesn't exist on older versions.
Add a check for the Sphinx version and change the produced tags
accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 65 insertions(+), 6 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 724528f4b7d6..3efc06d6f82d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -271,6 +271,8 @@ if ($#ARGV == -1) {
}
my $kernelversion;
+my $sphinx_major;
+
my $dohighlight = "";
my $verbose = 0;
@@ -465,6 +467,43 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
# continue execution near EOF;
+# The C domain dialect changed on Sphinx 3. So, we need to check the
+# version in order to produce the right tags.
+sub findprog($)
+{
+ foreach(split(/:/, $ENV{PATH})) {
+ return "$_/$_[0]" if(-x "$_/$_[0]");
+ }
+}
+
+sub get_sphinx_version()
+{
+ my $ver;
+ my $major = 1;
+
+ my $cmd = "sphinx-build";
+ if (!findprog($cmd)) {
+ my $cmd = "sphinx-build3";
+ return $major if (!findprog($cmd));
+ }
+
+ open IN, "$cmd --version 2>&1 |";
+ while (<IN>) {
+ if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
+ $major=$1;
+ last;
+ }
+ # Sphinx 1.2.x uses a different format
+ if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
+ $major=$1;
+ last;
+ }
+ }
+ close IN;
+
+ return $major;
+}
+
# get kernel version from env
sub get_kernel_version() {
my $version = 'unknown kernel version';
@@ -848,7 +887,11 @@ sub output_function_rst(%) {
my $start = "";
if ($args{'typedef'}) {
- print ".. c:type:: ". $args{'function'} . "\n\n";
+ if ($sphinx_major < 3) {
+ print ".. c:type:: ". $args{'function'} . "\n\n";
+ } else {
+ print ".. c:function:: ". $args{'function'} . "\n\n";
+ }
print_lineno($declaration_start_line);
print " **Typedef**: ";
$lineprefix = "";
@@ -938,9 +981,14 @@ sub output_enum_rst(%) {
my ($parameter);
my $oldprefix = $lineprefix;
my $count;
- my $name = "enum " . $args{'enum'};
- print "\n\n.. c:type:: " . $name . "\n\n";
+ if ($sphinx_major < 3) {
+ my $name = "enum " . $args{'enum'};
+ print "\n\n.. c:type:: " . $name . "\n\n";
+ } else {
+ my $name = $args{'enum'};
+ print "\n\n.. c:enum:: " . $name . "\n\n";
+ }
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
@@ -966,8 +1014,13 @@ sub output_typedef_rst(%) {
my %args = %{$_[0]};
my ($parameter);
my $oldprefix = $lineprefix;
- my $name = "typedef " . $args{'typedef'};
+ my $name;
+ if ($sphinx_major < 3) {
+ $name = "typedef " . $args{'typedef'};
+ } else {
+ $name = $args{'typedef'};
+ }
print "\n\n.. c:type:: " . $name . "\n\n";
print_lineno($declaration_start_line);
$lineprefix = " ";
@@ -982,9 +1035,14 @@ sub output_struct_rst(%) {
my %args = %{$_[0]};
my ($parameter);
my $oldprefix = $lineprefix;
- my $name = $args{'type'} . " " . $args{'struct'};
- print "\n\n.. c:type:: " . $name . "\n\n";
+ if ($sphinx_major < 3) {
+ my $name = $args{'type'} . " " . $args{'struct'};
+ print "\n\n.. c:type:: " . $name . "\n\n";
+ } else {
+ my $name = $args{'struct'};
+ print "\n\n.. c:struct:: " . $name . "\n\n";
+ }
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
@@ -2235,6 +2293,7 @@ sub process_file($) {
}
+$sphinx_major = get_sphinx_version();
$kernelversion = get_kernel_version();
# generate a sequence of code that will splice in highlighting information
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with Sphinx 3.x
2020-09-30 13:24 ` [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
@ 2020-10-01 21:41 ` Jonathan Corbet
2020-10-01 23:02 ` Jonathan Corbet
2020-10-02 6:22 ` Mauro Carvalho Chehab
0 siblings, 2 replies; 103+ messages in thread
From: Jonathan Corbet @ 2020-10-01 21:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: Linux Doc Mailing List, linux-kernel
On Wed, 30 Sep 2020 15:24:27 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:
>
> .. c:type:: typedef-like declaration
> .. c:type:: name
>
> Using it for other types (including functions) don't work anymore.
>
> So, there are newer tags for macro, enum, struct, union, and others,
> which doesn't exist on older versions.
>
> Add a check for the Sphinx version and change the produced tags
> accordingly.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++----
> 1 file changed, 65 insertions(+), 6 deletions(-)
So this seems generally good, but I do wonder if we shouldn't just pass
the sphinx version into kernel-doc as a parameter? We're already doing a
version check in the makefile, we should be able to capture the result and
pass it in, maybe?
jon
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with Sphinx 3.x
2020-10-01 21:41 ` Jonathan Corbet
@ 2020-10-01 23:02 ` Jonathan Corbet
2020-10-02 6:22 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 103+ messages in thread
From: Jonathan Corbet @ 2020-10-01 23:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: Linux Doc Mailing List, linux-kernel
On Thu, 1 Oct 2020 15:41:00 -0600
Jonathan Corbet <corbet@lwn.net> wrote:
> On Wed, 30 Sep 2020 15:24:27 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:
> >
> > .. c:type:: typedef-like declaration
> > .. c:type:: name
> >
> > Using it for other types (including functions) don't work anymore.
> >
> > So, there are newer tags for macro, enum, struct, union, and others,
> > which doesn't exist on older versions.
> >
> > Add a check for the Sphinx version and change the produced tags
> > accordingly.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> > scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++----
> > 1 file changed, 65 insertions(+), 6 deletions(-)
>
> So this seems generally good, but I do wonder if we shouldn't just pass
> the sphinx version into kernel-doc as a parameter? We're already doing a
> version check in the makefile, we should be able to capture the result and
> pass it in, maybe?
Actually, I'm being slow...we invoke kernel-doc *from within Sphinx*, so
it shouldn't be all that hard to stick the version number onto the command
line. If we did it that way, it would also be easier to manually test
kernel-doc for various Sphinx versions... ?
jon
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with Sphinx 3.x
2020-10-01 21:41 ` Jonathan Corbet
2020-10-01 23:02 ` Jonathan Corbet
@ 2020-10-02 6:22 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-02 6:22 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linux Doc Mailing List, linux-kernel
Em Thu, 1 Oct 2020 15:41:00 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Wed, 30 Sep 2020 15:24:27 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:
> >
> > .. c:type:: typedef-like declaration
> > .. c:type:: name
> >
> > Using it for other types (including functions) don't work anymore.
> >
> > So, there are newer tags for macro, enum, struct, union, and others,
> > which doesn't exist on older versions.
> >
> > Add a check for the Sphinx version and change the produced tags
> > accordingly.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> > scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++----
> > 1 file changed, 65 insertions(+), 6 deletions(-)
>
> So this seems generally good, but I do wonder if we shouldn't just pass
> the sphinx version into kernel-doc as a parameter? We're already doing a
> version check in the makefile, we should be able to capture the result and
> pass it in, maybe?
My plan is to work later on a patch adding support for it ;)
Yet, there's something to consider: troubleshooting.
I mean, if a warning is produced during "make htmldocs", as part
of troubleshooting, people do:
./scripts/kernel-doc <some file>
It sounds more natural that, by default, it will output the same
output as the one generated via "make htmldocs".
So, the version detection code there sounds the right way for
doing it.
Yet, as you pointed, as kerneldoc.py knows the Sphinx version,
it should be easy for it to pass an argument and avoid version
detection, by calling kernel-doc as:
./scripts/kernel-doc --sphinx3 <somefile>
or
./scripts/kernel-doc --sphinx-version 3 <somefile>
(not sure yet about how to name such arguments ;-) )
That might give some performance gain.
Btw, with regards to performance, I have a few other ideas that
might help how to improve kernel-doc (yet to be verified).
At least for now, I opted to keep it more straight without
adding more complexity. My plan is to work on those
things after the merge window.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (3 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 06/52] scripts: kernel-doc: fix troubles with line counts Mauro Carvalho Chehab
` (47 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Unfortunately, Sphinx 3.x parser for c functions is too pedantic:
https://github.com/sphinx-doc/sphinx/issues/8241
While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.
So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 34 ++++++++++++++++++++++++----------
1 file changed, 24 insertions(+), 10 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3efc06d6f82d..e1140869b889 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -886,19 +886,29 @@ sub output_function_rst(%) {
my $oldprefix = $lineprefix;
my $start = "";
- if ($args{'typedef'}) {
- if ($sphinx_major < 3) {
+ if ($sphinx_major < 3) {
+ if ($args{'typedef'}) {
print ".. c:type:: ". $args{'function'} . "\n\n";
+ print_lineno($declaration_start_line);
+ print " **Typedef**: ";
+ $lineprefix = "";
+ output_highlight_rst($args{'purpose'});
+ $start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ". $args{'function'} . "\n\n";
+ print ".. c:function:: ";
}
- print_lineno($declaration_start_line);
- print " **Typedef**: ";
- $lineprefix = "";
- output_highlight_rst($args{'purpose'});
- $start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ";
+ print ".. c:macro:: ". $args{'function'} . "\n\n";
+
+ if ($args{'typedef'}) {
+ print_lineno($declaration_start_line);
+ print " **Typedef**: ";
+ $lineprefix = "";
+ output_highlight_rst($args{'purpose'});
+ $start = "\n\n**Syntax**\n\n ``";
+ } else {
+ print "``";
+ }
}
if ($args{'functiontype'} ne "") {
$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
@@ -925,7 +935,11 @@ sub output_function_rst(%) {
if ($args{'typedef'}) {
print ");``\n\n";
} else {
- print ")\n\n";
+ if ($sphinx_major < 3) {
+ print ")\n\n";
+ } else {
+ print ")``\n";
+ }
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 06/52] scripts: kernel-doc: fix troubles with line counts
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (4 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on " Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 07/52] scripts: kernel-doc: reimplement -nofunction argument Mauro Carvalho Chehab
` (46 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
There's currently a bug with the way kernel-doc script
counts line numbers that can be seen with:
$ ./scripts/kernel-doc -rst -enable-lineno include/linux/math64.h >all && ./scripts/kernel-doc -rst -internal -enable-lineno include/linux/math64.h >int && diff -U0 int all
--- int 2020-09-28 12:58:08.927486808 +0200
+++ all 2020-09-28 12:58:08.905486845 +0200
@@ -1 +1 @@
-#define LINENO 27
+#define LINENO 26
@@ -3 +3 @@
-#define LINENO 16
+#define LINENO 15
@@ -9 +9 @@
-#define LINENO 17
+#define LINENO 16
...
This is happening with perl version 5.30.3, but I'm not
so sure if this is a perl bug, or if this is due to something
else.
In any case, fixing it is easy. Basically, when "-internal"
parameter is used, the process_export_file() function opens the
handle "IN". This makes the line number to be incremented, as the
handler for the main open is also "IN".
Fix the problem by using a different handler for the
main open().
While here, add a missing close for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e1140869b889..07b1073b0bc0 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2261,7 +2261,7 @@ sub process_file($) {
$file = map_filename($orig_file);
- if (!open(IN,"<$file")) {
+ if (!open(IN_FILE,"<$file")) {
print STDERR "Error: Cannot open file $file\n";
++$errors;
return;
@@ -2270,9 +2270,9 @@ sub process_file($) {
$. = 1;
$section_counter = 0;
- while (<IN>) {
+ while (<IN_FILE>) {
while (s/\\\s*$//) {
- $_ .= <IN>;
+ $_ .= <IN_FILE>;
}
# Replace tabs by spaces
while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
@@ -2304,6 +2304,7 @@ sub process_file($) {
print STDERR "${file}:1: warning: no structured comments found\n";
}
}
+ close IN_FILE;
}
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 07/52] scripts: kernel-doc: reimplement -nofunction argument
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (5 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 06/52] scripts: kernel-doc: fix troubles with line counts Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 08/52] scripts: kernel-doc: fix typedef identification Mauro Carvalho Chehab
` (45 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Right now, the build system doesn't use -nofunction, as
it is pretty much useless, because it doesn't consider
the other output modes (extern, internal), working only
with all.
Also, it is limited to exclude functions.
Re-implement it in order to allow excluding any symbols from
the document output, no matter what mode is used.
The parameter was also renamed to "-nosymbol", as it express
better its meaning.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 44 +++++++++++++++++++++-----------------------
1 file changed, 21 insertions(+), 23 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 07b1073b0bc0..6588a0d27fe4 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -66,9 +66,8 @@ Output selection (mutually exclusive):
-function NAME Only output documentation for the given function(s)
or DOC: section title(s). All other functions and DOC:
sections are ignored. May be specified multiple times.
- -nofunction NAME Do NOT output documentation for the given function(s);
- only output documentation for the other functions and
- DOC: sections. May be specified multiple times.
+ -nosymbol NAME Exclude the specified symbols from the output
+ documentation. May be specified multiple times.
Output selection modifiers:
-no-doc-sections Do not output DOC: sections.
@@ -288,9 +287,8 @@ my $modulename = "Kernel API";
use constant {
OUTPUT_ALL => 0, # output all symbols and doc sections
OUTPUT_INCLUDE => 1, # output only specified symbols
- OUTPUT_EXCLUDE => 2, # output everything except specified symbols
- OUTPUT_EXPORTED => 3, # output exported symbols
- OUTPUT_INTERNAL => 4, # output non-exported symbols
+ OUTPUT_EXPORTED => 2, # output exported symbols
+ OUTPUT_INTERNAL => 3, # output non-exported symbols
};
my $output_selection = OUTPUT_ALL;
my $show_not_found = 0; # No longer used
@@ -315,6 +313,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
# could cause "use of undefined value" or other bugs.
my ($function, %function_table, %parametertypes, $declaration_purpose);
+my %nosymbol_table = ();
my $declaration_start_line;
my ($type, $declaration_name, $return_type);
my ($newsection, $newcontents, $prototype, $brcount, %source_map);
@@ -434,10 +433,9 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
$output_selection = OUTPUT_INCLUDE;
$function = shift @ARGV;
$function_table{$function} = 1;
- } elsif ($cmd eq "nofunction") { # output all except specific functions
- $output_selection = OUTPUT_EXCLUDE;
- $function = shift @ARGV;
- $function_table{$function} = 1;
+ } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
+ my $symbol = shift @ARGV;
+ $nosymbol_table{$symbol} = 1;
} elsif ($cmd eq "export") { # only exported symbols
$output_selection = OUTPUT_EXPORTED;
%function_table = ();
@@ -570,11 +568,11 @@ sub dump_doc_section {
return;
}
+ return if (defined($nosymbol_table{$name}));
+
if (($output_selection == OUTPUT_ALL) ||
- ($output_selection == OUTPUT_INCLUDE &&
- defined($function_table{$name})) ||
- ($output_selection == OUTPUT_EXCLUDE &&
- !defined($function_table{$name})))
+ (($output_selection == OUTPUT_INCLUDE) &&
+ defined($function_table{$name})))
{
dump_section($file, $name, $contents);
output_blockhead({'sectionlist' => \@sectionlist,
@@ -800,6 +798,8 @@ sub output_blockhead_rst(%) {
my ($parameter, $section);
foreach $section (@{$args{'sectionlist'}}) {
+ next if (defined($nosymbol_table{$section}));
+
if ($output_selection != OUTPUT_INCLUDE) {
print "**$section**\n\n";
}
@@ -1115,12 +1115,14 @@ sub output_declaration {
my $name = shift;
my $functype = shift;
my $func = "output_${functype}_$output_mode";
+
+ return if (defined($nosymbol_table{$name}));
+
if (($output_selection == OUTPUT_ALL) ||
(($output_selection == OUTPUT_INCLUDE ||
$output_selection == OUTPUT_EXPORTED) &&
defined($function_table{$name})) ||
- (($output_selection == OUTPUT_EXCLUDE ||
- $output_selection == OUTPUT_INTERNAL) &&
+ ($output_selection == OUTPUT_INTERNAL &&
!($functype eq "function" && defined($function_table{$name}))))
{
&$func(@_);
@@ -1301,6 +1303,8 @@ sub show_warnings($$) {
my $functype = shift;
my $name = shift;
+ return 0 if (defined($nosymbol_table{$name}));
+
return 1 if ($output_selection == OUTPUT_ALL);
if ($output_selection == OUTPUT_EXPORTED) {
@@ -1324,13 +1328,6 @@ sub show_warnings($$) {
return 0;
}
}
- if ($output_selection == OUTPUT_EXCLUDE) {
- if (!defined($function_table{$name})) {
- return 1;
- } else {
- return 0;
- }
- }
die("Please add the new output type at show_warnings()");
}
@@ -1945,6 +1942,7 @@ sub process_export_file($) {
while (<IN>) {
if (/$export_symbol/) {
+ next if (defined($nosymbol_table{$2}));
$function_table{$2} = 1;
}
}
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 08/52] scripts: kernel-doc: fix typedef identification
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (6 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 07/52] scripts: kernel-doc: reimplement -nofunction argument Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 09/52] scripts: kernel-doc: don't mangle with parameter list Mauro Carvalho Chehab
` (44 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Some typedef expressions are output as normal functions.
As we need to be clearer about the type with Sphinx 3.x,
detect such cases.
While here, fix a wrongly-indented block.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 62 ++++++++++++++++++++++++++++++----------------
1 file changed, 40 insertions(+), 22 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6588a0d27fe4..a0344c78c641 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1741,30 +1741,48 @@ sub dump_function($$) {
return;
}
- my $prms = join " ", @parameterlist;
- check_sections($file, $declaration_name, "function", $sectcheck, $prms);
+ my $prms = join " ", @parameterlist;
+ check_sections($file, $declaration_name, "function", $sectcheck, $prms);
- # This check emits a lot of warnings at the moment, because many
- # functions don't have a 'Return' doc section. So until the number
- # of warnings goes sufficiently down, the check is only performed in
- # verbose mode.
- # TODO: always perform the check.
- if ($verbose && !$noret) {
- check_return_section($file, $declaration_name, $return_type);
- }
+ # This check emits a lot of warnings at the moment, because many
+ # functions don't have a 'Return' doc section. So until the number
+ # of warnings goes sufficiently down, the check is only performed in
+ # verbose mode.
+ # TODO: always perform the check.
+ if ($verbose && !$noret) {
+ check_return_section($file, $declaration_name, $return_type);
+ }
- output_declaration($declaration_name,
- 'function',
- {'function' => $declaration_name,
- 'module' => $modulename,
- 'functiontype' => $return_type,
- 'parameterlist' => \@parameterlist,
- 'parameterdescs' => \%parameterdescs,
- 'parametertypes' => \%parametertypes,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose
- });
+ # The function parser can be called with a typedef parameter.
+ # Handle it.
+ if ($return_type =~ /typedef/) {
+ output_declaration($declaration_name,
+ 'function',
+ {'function' => $declaration_name,
+ 'typedef' => 1,
+ 'module' => $modulename,
+ 'functiontype' => $return_type,
+ 'parameterlist' => \@parameterlist,
+ 'parameterdescs' => \%parameterdescs,
+ 'parametertypes' => \%parametertypes,
+ 'sectionlist' => \@sectionlist,
+ 'sections' => \%sections,
+ 'purpose' => $declaration_purpose
+ });
+ } else {
+ output_declaration($declaration_name,
+ 'function',
+ {'function' => $declaration_name,
+ 'module' => $modulename,
+ 'functiontype' => $return_type,
+ 'parameterlist' => \@parameterlist,
+ 'parameterdescs' => \%parameterdescs,
+ 'parametertypes' => \%parametertypes,
+ 'sectionlist' => \@sectionlist,
+ 'sections' => \%sections,
+ 'purpose' => $declaration_purpose
+ });
+ }
}
sub reset_state {
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 09/52] scripts: kernel-doc: don't mangle with parameter list
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (7 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 08/52] scripts: kernel-doc: fix typedef identification Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 10/52] docs: kerneldoc.py: append the name of the parsed doc file Mauro Carvalho Chehab
` (43 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
While kernel-doc needs to parse parameters in order to
identify its name, it shouldn't be touching the type,
as parsing it is very difficult, and errors happen.
One current error is when parsing this parameter:
const u32 (*tab)[256]
Found at ./lib/crc32.c, on this function:
u32 __pure crc32_be_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial);
The current logic mangles it, producing this output:
const u32 ( *tab
That's something that it is not recognizeable.
So, instead, let's push the argument as-is, and use it
when printing the function prototype and when describing
each argument.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 26 ++++++++++++++------------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a0344c78c641..f549837d874d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -655,10 +655,10 @@ sub output_function_man(%) {
$type = $args{'parametertypes'}{$parameter};
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
# pointer-to-function
- print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
+ print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
} else {
$type =~ s/([^\*])$/$1 /;
- print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
+ print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
}
$count++;
$parenth = "";
@@ -929,7 +929,7 @@ sub output_function_rst(%) {
# pointer-to-function
print $1 . $parameter . ") (" . $2 . ")";
} else {
- print $type . " " . $parameter;
+ print $type;
}
}
if ($args{'typedef'}) {
@@ -954,7 +954,7 @@ sub output_function_rst(%) {
$type = $args{'parametertypes'}{$parameter};
if ($type ne "") {
- print "``$type $parameter``\n";
+ print "``$type``\n";
} else {
print "``$parameter``\n";
}
@@ -1472,7 +1472,7 @@ sub create_parameterlist($$$$) {
# Treat preprocessor directive as a typeless variable just to fill
# corresponding data structures "correctly". Catch it later in
# output_* subs.
- push_parameter($arg, "", $file);
+ push_parameter($arg, "", "", $file);
} elsif ($arg =~ m/\(.+\)\s*\(/) {
# pointer-to-function
$arg =~ tr/#/,/;
@@ -1481,7 +1481,7 @@ sub create_parameterlist($$$$) {
$type = $arg;
$type =~ s/([^\(]+\(\*?)\s*$param/$1/;
save_struct_actual($param);
- push_parameter($param, $type, $file, $declaration_name);
+ push_parameter($param, $type, $arg, $file, $declaration_name);
} elsif ($arg) {
$arg =~ s/\s*:\s*/:/g;
$arg =~ s/\s*\[/\[/g;
@@ -1506,26 +1506,28 @@ sub create_parameterlist($$$$) {
foreach $param (@args) {
if ($param =~ m/^(\*+)\s*(.*)/) {
save_struct_actual($2);
- push_parameter($2, "$type $1", $file, $declaration_name);
+
+ push_parameter($2, "$type $1", $arg, $file, $declaration_name);
}
elsif ($param =~ m/(.*?):(\d+)/) {
if ($type ne "") { # skip unnamed bit-fields
save_struct_actual($1);
- push_parameter($1, "$type:$2", $file, $declaration_name)
+ push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
}
}
else {
save_struct_actual($param);
- push_parameter($param, $type, $file, $declaration_name);
+ push_parameter($param, $type, $arg, $file, $declaration_name);
}
}
}
}
}
-sub push_parameter($$$$) {
+sub push_parameter($$$$$) {
my $param = shift;
my $type = shift;
+ my $org_arg = shift;
my $file = shift;
my $declaration_name = shift;
@@ -1589,8 +1591,8 @@ sub push_parameter($$$$) {
# "[blah" in a parameter string;
###$param =~ s/\s*//g;
push @parameterlist, $param;
- $type =~ s/\s\s+/ /g;
- $parametertypes{$param} = $type;
+ $org_arg =~ s/\s\s+/ /g;
+ $parametertypes{$param} = $org_arg;
}
sub check_sections($$$$$) {
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 10/52] docs: kerneldoc.py: append the name of the parsed doc file
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (8 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 09/52] scripts: kernel-doc: don't mangle with parameter list Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 11/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol Mauro Carvalho Chehab
` (42 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Changbin Du, linux-kernel
Finding where an error like this was generated:
../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Can take some time, as there's no glue about what kernel-doc
tag generated it. It is a way better to display it as:
.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Declaration is 'div_s64_rem'.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/kerneldoc.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 4bcbd6ae01cd..6686955d1def 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -136,7 +136,8 @@ class KernelDocDirective(Directive):
lineoffset = int(match.group(1)) - 1
# we must eat our comments since the upset the markup
else:
- result.append(line, filename, lineoffset)
+ doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno)
+ result.append(line, doc + ": " + filename, lineoffset)
lineoffset += 1
node = nodes.section()
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 11/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (9 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 10/52] docs: kerneldoc.py: append the name of the parsed doc file Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 12/52] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
` (41 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Nícolas F. R. A. Prado, Changbin Du,
linux-kernel
Currently, there's no way to exclude identifiers from
a kernel-doc markup. Add support for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/doc-guide/kernel-doc.rst | 8 ++++++++
Documentation/sphinx/kerneldoc.py | 7 +++++++
2 files changed, 15 insertions(+)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 4fd86c21397b..52a87ab4c99f 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -490,6 +490,14 @@ identifiers: *[ function/type ...]*
.. kernel-doc:: lib/idr.c
:identifiers:
+no-identifiers: *[ function/type ...]*
+ Exclude documentation for each *function* and *type* in *source*.
+
+ Example::
+
+ .. kernel-doc:: lib/bitmap.c
+ :no-identifiers: bitmap_parselist
+
functions: *[ function/type ...]*
This is an alias of the 'identifiers' directive and deprecated.
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 6686955d1def..233f610539f0 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -62,6 +62,7 @@ class KernelDocDirective(Directive):
'export': directives.unchanged,
'internal': directives.unchanged,
'identifiers': directives.unchanged,
+ 'no-identifiers': directives.unchanged,
'functions': directives.unchanged,
}
has_content = False
@@ -99,6 +100,12 @@ class KernelDocDirective(Directive):
else:
cmd += ['-no-doc-sections']
+ if 'no-identifiers' in self.options:
+ no_identifiers = self.options.get('no-identifiers').split()
+ if no_identifiers:
+ for i in no_identifiers:
+ cmd += ['-nosymbol', i]
+
for pattern in export_file_patterns:
for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
env.note_dependency(os.path.abspath(f))
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 12/52] media: docs: make CEC documents compatible with Sphinx 3.1+
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (10 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 11/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 13/52] media: docs: make V4L documents more " Mauro Carvalho Chehab
` (40 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Hans Verkuil, Mauro Carvalho Chehab,
linux-kernel, linux-media
Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../media/cec/cec-func-close.rst | 10 +++-------
.../media/cec/cec-func-ioctl.rst | 11 ++++------
.../userspace-api/media/cec/cec-func-open.rst | 10 +++-------
.../userspace-api/media/cec/cec-func-poll.rst | 14 +++++--------
.../media/cec/cec-ioc-adap-g-caps.rst | 10 +++++-----
.../media/cec/cec-ioc-adap-g-conn-info.rst | 11 +++++-----
.../media/cec/cec-ioc-adap-g-log-addrs.rst | 20 ++++++++-----------
.../media/cec/cec-ioc-adap-g-phys-addr.rst | 15 +++++++-------
.../media/cec/cec-ioc-dqevent.rst | 15 +++++---------
.../media/cec/cec-ioc-g-mode.rst | 16 +++++++--------
.../media/cec/cec-ioc-receive.rst | 18 ++++++++---------
11 files changed, 63 insertions(+), 87 deletions(-)
diff --git a/Documentation/userspace-api/media/cec/cec-func-close.rst b/Documentation/userspace-api/media/cec/cec-func-close.rst
index 33c563f414a8..409e70a5f80f 100644
--- a/Documentation/userspace-api/media/cec/cec-func-close.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-close.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _cec-func-close:
@@ -11,7 +12,6 @@ Name
cec-close - Close a cec device
-
Synopsis
========
@@ -19,16 +19,13 @@ Synopsis
#include <unistd.h>
-
.. c:function:: int close( int fd )
- :name: cec-close
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
-
+ File descriptor returned by :c:func:`open()`.
Description
===========
@@ -36,11 +33,10 @@ Description
Closes the cec device. Resources associated with the file descriptor are
freed. The device configuration remain unchanged.
-
Return Value
============
-:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:
``EBADF``
diff --git a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
index 3b88230fad80..7c93f86de6cc 100644
--- a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _cec-func-ioctl:
@@ -18,15 +19,13 @@ Synopsis
#include <sys/ioctl.h>
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
- :name: cec-ioctl
+``int ioctl(int fd, int request, void *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``request``
CEC ioctl request code as defined in the cec.h header file, for
@@ -35,11 +34,10 @@ Arguments
``argp``
Pointer to a request-specific structure.
-
Description
===========
-The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The
+The :c:func:`ioctl()` function manipulates cec device parameters. The
argument ``fd`` must be an open file descriptor.
The ioctl ``request`` code specifies the cec function to be called. It
@@ -51,7 +49,6 @@ their parameters are located in the cec.h header file. All cec ioctl
requests, their respective function and parameters are specified in
:ref:`cec-user-func`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst
index 887bfd2a755e..d86563a34b9e 100644
--- a/Documentation/userspace-api/media/cec/cec-func-open.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-open.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _cec-func-open:
@@ -18,10 +19,7 @@ Synopsis
#include <fcntl.h>
-
.. c:function:: int open( const char *device_name, int flags )
- :name: cec-open
-
Arguments
=========
@@ -42,11 +40,10 @@ Arguments
Other flags have no effect.
-
Description
===========
-To open a cec device applications call :c:func:`open() <cec-open>` with the
+To open a cec device applications call :c:func:`open()` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.
@@ -54,11 +51,10 @@ When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.
-
Return Value
============
-:c:func:`open() <cec-open>` returns the new file descriptor on success. On error,
+:c:func:`open()` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
include:
diff --git a/Documentation/userspace-api/media/cec/cec-func-poll.rst b/Documentation/userspace-api/media/cec/cec-func-poll.rst
index 2d87136e9a3f..980bbfc0bcce 100644
--- a/Documentation/userspace-api/media/cec/cec-func-poll.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _cec-func-poll:
@@ -11,7 +12,6 @@ Name
cec-poll - Wait for some event on a file descriptor
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <sys/poll.h>
-
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
- :name: cec-poll
Arguments
=========
@@ -35,14 +33,13 @@ Arguments
``timeout``
Timeout to wait for events
-
Description
===========
-With the :c:func:`poll() <cec-poll>` function applications can wait for CEC
+With the :c:func:`poll()` function applications can wait for CEC
events.
-On success :c:func:`poll() <cec-poll>` returns the number of file descriptors
+On success :c:func:`poll()` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
@@ -53,13 +50,12 @@ then the ``POLLPRI`` flag is set. When the function times out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
-For more details see the :c:func:`poll() <cec-poll>` manual page.
-
+For more details see the :c:func:`poll()` manual page.
Return Value
============
-On success, :c:func:`poll() <cec-poll>` returns the number structures which have
+On success, :c:func:`poll()` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
index 7f25365ce0fb..c7309a2fcbce 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _CEC_ADAP_G_CAPS:
@@ -14,18 +15,18 @@ CEC_ADAP_G_CAPS - Query device capabilities
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp )
- :name: CEC_ADAP_G_CAPS
+.. c:macro:: CEC_ADAP_G_CAPS
+
+``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
-
Description
===========
@@ -62,7 +63,6 @@ returns the information to the application. The ioctl never fails.
- CEC Framework API version, formatted with the ``KERNEL_VERSION()``
macro.
-
.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
.. _cec-capabilities:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
index 6818ddf1495c..13116b0b5c17 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
@@ -2,6 +2,8 @@
..
.. Copyright 2019 Google LLC
..
+.. c:namespace:: CEC
+
.. _CEC_ADAP_G_CONNECTOR_INFO:
*******************************
@@ -16,18 +18,18 @@ CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp )
- :name: CEC_ADAP_G_CONNECTOR_INFO
+.. c:macro:: CEC_ADAP_G_CONNECTOR_INFO
+
+``int ioctl(int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
-
Description
===========
@@ -57,7 +59,6 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set.
* - }
-
-
.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
.. _connector-type:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
index 1ca893270ae9..c760c07b6b3f 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _CEC_ADAP_LOG_ADDRS:
.. _CEC_ADAP_G_LOG_ADDRS:
@@ -13,21 +14,22 @@ Name
CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
-
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
- :name: CEC_ADAP_G_LOG_ADDRS
+.. c:macro:: CEC_ADAP_G_LOG_ADDRS
-.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
- :name: CEC_ADAP_S_LOG_ADDRS
+``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)``
+
+.. c:macro:: CEC_ADAP_S_LOG_ADDRS
+
+``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`cec_log_addrs`.
@@ -148,7 +150,6 @@ logical address types are already defined will return with error ``EBUSY``.
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
-
.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
.. _cec-log-addrs-flags:
@@ -185,7 +186,6 @@ logical address types are already defined will return with error ``EBUSY``.
All other messages are ignored.
-
.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
.. _cec-versions:
@@ -211,7 +211,6 @@ logical address types are already defined will return with error ``EBUSY``.
- 6
- CEC version according to the HDMI 2.0 standard.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-prim-dev-types:
@@ -257,7 +256,6 @@ logical address types are already defined will return with error ``EBUSY``.
- 7
- Use for a video processor device.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-log-addr-types:
@@ -306,7 +304,6 @@ logical address types are already defined will return with error ``EBUSY``.
Control).
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-all-dev-types-flags:
@@ -348,7 +345,6 @@ logical address types are already defined will return with error ``EBUSY``.
- This supports the CEC Switch or Video Processing type.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
index a10443be1b26..fb22f6894f26 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _CEC_ADAP_PHYS_ADDR:
.. _CEC_ADAP_G_PHYS_ADDR:
@@ -13,21 +14,22 @@ Name
CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
-
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
- :name: CEC_ADAP_G_PHYS_ADDR
+.. c:macro:: CEC_ADAP_G_PHYS_ADDR
-.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
- :name: CEC_ADAP_S_PHYS_ADDR
+``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)``
+
+.. c:macro:: CEC_ADAP_S_PHYS_ADDR
+
+``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to the CEC address.
@@ -71,7 +73,6 @@ For example, the EDID for each HDMI input of the TV will have a
different physical address of the form a.0.0.0 that the sources will
read out and use as their physical address.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
index 3bc81fc5a73f..736fda5ad73d 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _CEC_DQEVENT:
@@ -11,22 +12,21 @@ Name
CEC_DQEVENT - Dequeue a CEC event
-
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp )
- :name: CEC_DQEVENT
+.. c:macro:: CEC_DQEVENT
+
+``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
-
Description
===========
@@ -72,7 +72,6 @@ it is guaranteed that the state did change in between the two events.
the HDMI driver is still configuring the device or because the HDMI
device was unbound.
-
.. c:type:: cec_event_lost_msgs
.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
@@ -94,7 +93,6 @@ it is guaranteed that the state did change in between the two events.
replied to within a second according to the CEC specification,
this is more than enough.
-
.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
.. c:type:: cec_event
@@ -130,7 +128,6 @@ it is guaranteed that the state did change in between the two events.
* - }
-
-
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-events:
@@ -204,7 +201,6 @@ it is guaranteed that the state did change in between the two events.
if the 5V is high, then an initial event will be generated for that
filehandle.
-
.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
.. _cec-event-flags:
@@ -230,7 +226,6 @@ it is guaranteed that the state did change in between the two events.
This is an indication that the application cannot keep up.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
index 2093e373c93c..d3387b1fa7c5 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _CEC_MODE:
.. _CEC_G_MODE:
@@ -13,17 +14,19 @@ CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp )
- :name: CEC_G_MODE
+.. c:macro:: CEC_G_MODE
-.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp )
- :name: CEC_S_MODE
+``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``
+
+.. c:macro:: CEC_S_MODE
+
+``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to CEC mode.
@@ -101,7 +104,6 @@ Available initiator modes are:
then an attempt to become one will return the ``EBUSY`` error code
error.
-
Available follower modes are:
.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
@@ -193,7 +195,6 @@ Available follower modes are:
the process has the ``CAP_NET_ADMIN`` capability. If that is not
set, then the ``EPERM`` error code is returned.
-
Core message processing details:
.. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
@@ -272,7 +273,6 @@ Core message processing details:
and then just pass the message on to the follower(s).
-
Return Value
============
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
index 9d629d46973c..b2fc051e99f4 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
.. _CEC_TRANSMIT:
.. _CEC_RECEIVE:
@@ -12,21 +13,22 @@ Name
CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
-
Synopsis
========
-.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp )
- :name: CEC_RECEIVE
+.. c:macro:: CEC_RECEIVE
-.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp )
- :name: CEC_TRANSMIT
+``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)``
+
+.. c:macro:: CEC_TRANSMIT
+
+``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <cec-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct cec_msg.
@@ -194,7 +196,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
supports this, otherwise it is always 0. This counter is only
valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
-
.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
.. _cec-msg-flags:
@@ -228,7 +229,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
capability. If that is not set, then the ``EPERM`` error code is
returned.
-
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-tx-status:
@@ -298,7 +298,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
- The transmit timed out. This should not normally happen and this
indicates a driver problem.
-
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-rx-status:
@@ -335,7 +334,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
reply was interrupted.
-
Return Value
============
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 13/52] media: docs: make V4L documents more compatible with Sphinx 3.1+
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (11 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 12/52] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 14/52] media: docs: make DVB " Mauro Carvalho Chehab
` (39 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Niklas Söderlund, Alexandre Courbot,
Boris Brezillon, Dafna Hirschfeld, Ezequiel Garcia, Hans Verkuil,
Helen Koike, Jacopo Mondi, Jernej Skrabec, Jian-Jia Su,
Laurent Pinchart, Mauro Carvalho Chehab, Michael Tretter,
Paul Kocialkowski, Randy Dunlap, Ricardo Ribalda, Sakari Ailus,
Sergey Senozhatsky, Tomasz Figa, linux-kernel, linux-media
Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../userspace-api/media/v4l/buffer.rst | 14 +---
.../userspace-api/media/v4l/dev-capture.rst | 7 +-
.../userspace-api/media/v4l/dev-output.rst | 7 +-
.../userspace-api/media/v4l/dev-raw-vbi.rst | 19 ++---
.../userspace-api/media/v4l/dev-rds.rst | 12 +---
.../media/v4l/dev-sliced-vbi.rst | 31 ++------
.../userspace-api/media/v4l/diff-v4l.rst | 39 ++---------
.../userspace-api/media/v4l/dmabuf.rst | 8 +--
.../userspace-api/media/v4l/format.rst | 7 +-
.../userspace-api/media/v4l/func-close.rst | 8 +--
.../userspace-api/media/v4l/func-ioctl.rst | 10 +--
.../userspace-api/media/v4l/func-mmap.rst | 18 ++---
.../userspace-api/media/v4l/func-munmap.rst | 14 ++--
.../userspace-api/media/v4l/func-open.rst | 14 ++--
.../userspace-api/media/v4l/func-poll.rst | 40 +++++------
.../userspace-api/media/v4l/func-read.rst | 39 +++++------
.../userspace-api/media/v4l/func-select.rst | 42 +++++------
.../userspace-api/media/v4l/func-write.rst | 13 ++--
.../userspace-api/media/v4l/hist-v4l2.rst | 70 ++-----------------
Documentation/userspace-api/media/v4l/io.rst | 6 +-
.../media/v4l/libv4l-introduction.rst | 30 ++++----
.../userspace-api/media/v4l/mmap.rst | 26 +++----
.../userspace-api/media/v4l/open.rst | 15 ++--
Documentation/userspace-api/media/v4l/rw.rst | 18 ++---
.../userspace-api/media/v4l/streaming-par.rst | 5 +-
.../userspace-api/media/v4l/userp.rst | 11 +--
.../media/v4l/vidioc-create-bufs.rst | 11 ++-
.../media/v4l/vidioc-cropcap.rst | 11 ++-
.../media/v4l/vidioc-dbg-g-chip-info.rst | 13 ++--
.../media/v4l/vidioc-dbg-g-register.rst | 18 ++---
.../media/v4l/vidioc-decoder-cmd.rst | 19 +++--
.../media/v4l/vidioc-dqevent.rst | 19 ++---
.../media/v4l/vidioc-dv-timings-cap.rst | 17 ++---
.../media/v4l/vidioc-encoder-cmd.rst | 25 +++----
.../media/v4l/vidioc-enum-dv-timings.rst | 16 ++---
.../media/v4l/vidioc-enum-fmt.rst | 12 ++--
.../media/v4l/vidioc-enum-frameintervals.rst | 15 ++--
.../media/v4l/vidioc-enum-framesizes.rst | 16 ++---
.../media/v4l/vidioc-enum-freq-bands.rst | 12 ++--
.../media/v4l/vidioc-enumaudio.rst | 10 ++-
.../media/v4l/vidioc-enumaudioout.rst | 10 ++-
.../media/v4l/vidioc-enuminput.rst | 14 ++--
.../media/v4l/vidioc-enumoutput.rst | 13 ++--
.../media/v4l/vidioc-enumstd.rst | 23 ++----
.../userspace-api/media/v4l/vidioc-expbuf.rst | 14 ++--
.../media/v4l/vidioc-g-audio.rst | 18 ++---
.../media/v4l/vidioc-g-audioout.rst | 16 ++---
.../userspace-api/media/v4l/vidioc-g-crop.rst | 16 ++---
.../userspace-api/media/v4l/vidioc-g-ctrl.rst | 16 ++---
.../media/v4l/vidioc-g-dv-timings.rst | 26 +++----
.../userspace-api/media/v4l/vidioc-g-edid.rst | 25 ++++---
.../media/v4l/vidioc-g-enc-index.rst | 13 ++--
.../media/v4l/vidioc-g-ext-ctrls.rst | 21 +++---
.../userspace-api/media/v4l/vidioc-g-fbuf.rst | 18 ++---
.../userspace-api/media/v4l/vidioc-g-fmt.rst | 22 +++---
.../media/v4l/vidioc-g-frequency.rst | 16 ++---
.../media/v4l/vidioc-g-input.rst | 15 ++--
.../media/v4l/vidioc-g-jpegcomp.rst | 17 ++---
.../media/v4l/vidioc-g-modulator.rst | 17 ++---
.../media/v4l/vidioc-g-output.rst | 15 ++--
.../userspace-api/media/v4l/vidioc-g-parm.rst | 30 ++++----
.../media/v4l/vidioc-g-priority.rst | 16 ++---
.../media/v4l/vidioc-g-selection.rst | 15 ++--
.../media/v4l/vidioc-g-sliced-vbi-cap.rst | 12 ++--
.../userspace-api/media/v4l/vidioc-g-std.rst | 24 ++++---
.../media/v4l/vidioc-g-tuner.rst | 19 ++---
.../media/v4l/vidioc-log-status.rst | 10 ++-
.../media/v4l/vidioc-overlay.rst | 10 ++-
.../media/v4l/vidioc-prepare-buf.rst | 10 ++-
.../userspace-api/media/v4l/vidioc-qbuf.rst | 17 +++--
.../media/v4l/vidioc-query-dv-timings.rst | 15 ++--
.../media/v4l/vidioc-querybuf.rst | 10 ++-
.../media/v4l/vidioc-querycap.rst | 16 ++---
.../media/v4l/vidioc-queryctrl.rst | 22 +++---
.../media/v4l/vidioc-querystd.rst | 15 ++--
.../media/v4l/vidioc-reqbufs.rst | 10 ++-
.../media/v4l/vidioc-s-hw-freq-seek.rst | 11 ++-
.../media/v4l/vidioc-streamon.rst | 14 ++--
.../v4l/vidioc-subdev-enum-frame-interval.rst | 10 ++-
.../v4l/vidioc-subdev-enum-frame-size.rst | 11 ++-
.../v4l/vidioc-subdev-enum-mbus-code.rst | 10 ++-
.../media/v4l/vidioc-subdev-g-crop.rst | 16 ++---
.../media/v4l/vidioc-subdev-g-fmt.rst | 17 ++---
.../v4l/vidioc-subdev-g-frame-interval.rst | 16 ++---
.../media/v4l/vidioc-subdev-g-selection.rst | 17 ++---
.../media/v4l/vidioc-subdev-querycap.rst | 9 ++-
.../media/v4l/vidioc-subscribe-event.rst | 17 ++---
87 files changed, 559 insertions(+), 922 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst
index da7366e0e317..7dbdfbb4a0a9 100644
--- a/Documentation/userspace-api/media/v4l/buffer.rst
+++ b/Documentation/userspace-api/media/v4l/buffer.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _buffer:
@@ -33,7 +34,6 @@ mem-to-mem devices is an exception to the rule: the timestamp source
flags are copied from the OUTPUT video buffer to the CAPTURE video
buffer.
-
Interactions between formats, controls and buffers
==================================================
@@ -152,7 +152,6 @@ based on the queried sizes (for instance by allocating a set of buffers large
enough for all the desired formats and controls, or by allocating separate set
of appropriately sized buffers for each use case).
-
.. c:type:: v4l2_buffer
struct v4l2_buffer
@@ -257,7 +256,7 @@ struct v4l2_buffer
``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
start of the device memory. The value is returned by the driver
and apart of serving as parameter to the
- :ref:`mmap() <func-mmap>` function not useful for applications.
+ :c:func:`mmap()` function not useful for applications.
See :ref:`mmap` for details
* - unsigned long
- ``userptr``
@@ -310,7 +309,6 @@ struct v4l2_buffer
given, then ``EINVAL`` will be returned.
-
.. c:type:: v4l2_plane
struct v4l2_plane
@@ -350,7 +348,7 @@ struct v4l2_plane
- ``mem_offset``
- When the memory type in the containing struct
:c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this
- is the value that should be passed to :ref:`mmap() <func-mmap>`,
+ is the value that should be passed to :c:func:`mmap()`,
similar to the ``offset`` field in struct
:c:type:`v4l2_buffer`.
* - unsigned long
@@ -384,7 +382,6 @@ struct v4l2_plane
applications.
-
.. c:type:: v4l2_buf_type
enum v4l2_buf_type
@@ -448,7 +445,6 @@ enum v4l2_buf_type
- Buffer for metadata output, see :ref:`metadata`.
-
.. _buffer-flags:
Buffer Flags
@@ -706,7 +702,6 @@ enum v4l2_memory
- The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
-
Timecodes
=========
@@ -715,7 +710,6 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a
(struct :c:type:`timeval` timestamps are stored in the struct
:c:type:`v4l2_buffer` ``timestamp`` field.)
-
.. c:type:: v4l2_timecode
struct v4l2_timecode
@@ -752,7 +746,6 @@ struct v4l2_timecode
- The "user group" bits from the timecode.
-
.. _timecode-type:
Timecode Types
@@ -782,7 +775,6 @@ Timecode Types
-
-
.. _timecode-flags:
Timecode Flags
diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst
index 5ea1ffe71fa6..fe58fd450e2f 100644
--- a/Documentation/userspace-api/media/v4l/dev-capture.rst
+++ b/Documentation/userspace-api/media/v4l/dev-capture.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _capture:
@@ -19,7 +20,6 @@ device.
.. note:: The same device file names are used for video output devices.
-
Querying Capabilities
=====================
@@ -34,7 +34,6 @@ functions they may also support the :ref:`video overlay <overlay>`
streaming I/O methods must be supported. Tuners and audio inputs are
optional.
-
Supplemental Functions
======================
@@ -45,7 +44,6 @@ Video capture devices shall support :ref:`audio input <audio>`,
:ref:`video input <video>` ioctls must be supported by all video
capture devices.
-
Image Format Negotiation
========================
@@ -55,7 +53,7 @@ capture, the latter how images are stored in memory, i. e. in RGB or YUV
format, the number of bits per pixel or width and height. Together they
also define how images are scaled in the process.
-As usual these parameters are *not* reset at :ref:`open() <func-open>`
+As usual these parameters are *not* reset at :c:func:`open()`
time to permit Unix tool chains, programming a device and then reading
from it as if it was a plain file. Well written V4L2 applications ensure
they really get what they want, including cropping and scaling.
@@ -95,7 +93,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC
requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
-
Reading Images
==============
diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst
index 2315faf61aaf..eadcb4aa813b 100644
--- a/Documentation/userspace-api/media/v4l/dev-output.rst
+++ b/Documentation/userspace-api/media/v4l/dev-output.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _output:
@@ -18,7 +19,6 @@ device.
.. note:: The same device file names are used also for video capture devices.
-
Querying Capabilities
=====================
@@ -32,7 +32,6 @@ functions they may also support the :ref:`raw VBI output <raw-vbi>`
streaming I/O methods must be supported. Modulators and audio outputs
are optional.
-
Supplemental Functions
======================
@@ -43,7 +42,6 @@ Video output devices shall support :ref:`audio output <audio>`,
:ref:`video output <video>` ioctls must be supported by all video
output devices.
-
Image Format Negotiation
========================
@@ -53,7 +51,7 @@ the latter how images are stored in memory, i. e. in RGB or YUV format,
the number of bits per pixel or width and height. Together they also
define how images are scaled in the process.
-As usual these parameters are *not* reset at :ref:`open() <func-open>`
+As usual these parameters are *not* reset at :c:func:`open()`
time to permit Unix tool chains, programming a device and then writing
to it as if it was a plain file. Well written V4L2 applications ensure
they really get what they want, including cropping and scaling.
@@ -92,7 +90,6 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC
requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
-
Writing Images
==============
diff --git a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst
index bb52f85a619c..3f43a01ba938 100644
--- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst
+++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _raw-vbi:
@@ -32,7 +33,6 @@ applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
device function.
-
Querying Capabilities
=====================
@@ -44,7 +44,6 @@ in the ``capabilities`` field of struct
read/write, streaming or asynchronous I/O methods must be supported. VBI
devices may or may not have a tuner or modulator.
-
Supplemental Functions
======================
@@ -53,7 +52,6 @@ VBI devices shall support :ref:`video input or output <video>`,
ioctls as needed. The :ref:`video standard <standard>` ioctls provide
information vital to program a VBI device, therefore must be supported.
-
Raw VBI Format Negotiation
==========================
@@ -62,7 +60,7 @@ frequency. To properly interpret the data V4L2 specifies an ioctl to
query the sampling parameters. Moreover, to allow for some flexibility
applications can also suggest different parameters.
-As usual these parameters are *not* reset at :ref:`open() <func-open>`
+As usual these parameters are *not* reset at :c:func:`open()`
time to permit Unix tool chains, programming a device and then reading
from it as if it was a plain file. Well written V4L2 applications should
always ensure they really get what they want, requesting reasonable
@@ -91,8 +89,8 @@ happen for instance when the video and VBI areas to capture would
overlap, or when the driver supports multiple opens and another process
already requested VBI capturing or output. Anyway, applications must
expect other resource allocation points which may return ``EBUSY``, at the
-:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>`
-, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls.
+:ref:`VIDIOC_STREAMON` ioctl and the first :c:func:`read()`
+, :c:func:`write()` and :c:func:`select()` calls.
VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests
@@ -182,7 +180,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
- This array is reserved for future extensions. Drivers and
applications must set it to zero.
-
.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}|
.. _vbifmt-flags:
@@ -218,7 +215,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
non-zero.
-
.. _vbi-hsync:
.. kernel-figure:: vbi_hsync.svg
@@ -227,7 +223,6 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
**Figure 4.1. Line synchronization**
-
.. _vbi-525:
.. kernel-figure:: vbi_525.svg
@@ -251,7 +246,6 @@ negotiation, or after switching the video standard which may invalidate
the negotiated VBI parameters, should be refused by the driver. A format
change during active I/O is not permitted.
-
Reading and writing VBI images
==============================
@@ -261,7 +255,6 @@ consisting of two fields of VBI images immediately following in memory.
The total size of a frame computes as follows:
-
.. code-block:: c
(count[0] + count[1]) * samples_per_line * sample size in bytes
@@ -276,8 +269,8 @@ The latter bears the possibility of synchronizing video and VBI data by
using buffer timestamps.
Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the
-first :ref:`read() <func-read>`, :ref:`write() <func-write>` and
-:ref:`select() <func-select>` call can be resource allocation
+first :c:func:`read()`, :c:func:`write()` and
+:c:func:`select()` call can be resource allocation
points returning an ``EBUSY`` error code if the required hardware resources
are temporarily unavailable, for example the device is already in use by
another process.
diff --git a/Documentation/userspace-api/media/v4l/dev-rds.rst b/Documentation/userspace-api/media/v4l/dev-rds.rst
index 463726ba46d7..207216d5e6a5 100644
--- a/Documentation/userspace-api/media/v4l/dev-rds.rst
+++ b/Documentation/userspace-api/media/v4l/dev-rds.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _rds:
@@ -28,7 +29,6 @@ The RDS interface does not support this format. Should support for MMBS
the linux-media mailing list:
`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
-
Querying Capabilities
=====================
@@ -68,31 +68,27 @@ like program identification codes and radio text, the flag
:ref:`Writing RDS data <writing-rds-data>` and
:ref:`FM Transmitter Control Reference <fm-tx-controls>`.
-
.. _reading-rds-data:
Reading RDS data
================
RDS data can be read from the radio device with the
-:ref:`read() <func-read>` function. The data is packed in groups of
+:c:func:`read()` function. The data is packed in groups of
three bytes.
-
.. _writing-rds-data:
Writing RDS data
================
RDS data can be written to the radio device with the
-:ref:`write() <func-write>` function. The data is packed in groups of
+:c:func:`write()` function. The data is packed in groups of
three bytes, as follows:
-
RDS datastructures
==================
-
.. c:type:: v4l2_rds_data
.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}|
@@ -113,7 +109,6 @@ RDS datastructures
- Block description
-
.. _v4l2-rds-block:
.. tabularcolumns:: |p{2.9cm}|p{14.6cm}|
@@ -136,7 +131,6 @@ RDS datastructures
reception of this block.
-
.. _v4l2-rds-block-codes:
.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}|
diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
index 807751f305fb..f0df144c9f63 100644
--- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
+++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _sliced:
@@ -27,7 +28,6 @@ however the default function here is video capturing or output.
Different file descriptors must be used to pass raw and sliced VBI data
simultaneously, if this is supported by the driver.
-
Querying Capabilities
=====================
@@ -39,7 +39,6 @@ respectively, in the ``capabilities`` field of struct
read/write, streaming or asynchronous :ref:`I/O methods <io>` must be
supported. Sliced VBI devices may have a tuner or modulator.
-
Supplemental Functions
======================
@@ -49,7 +48,6 @@ capabilities, and they may support :ref:`control` ioctls.
The :ref:`video standard <standard>` ioctls provide information vital
to program a sliced VBI device, therefore must be supported.
-
.. _sliced-vbi-format-negotitation:
Sliced VBI Format Negotiation
@@ -96,9 +94,8 @@ at this point, it may return an ``EBUSY`` error code if the required
resources are temporarily unavailable. Other resource allocation points
which may return ``EBUSY`` can be the
:ref:`VIDIOC_STREAMON` ioctl and the first
-:ref:`read() <func-read>`, :ref:`write() <func-write>` and
-:ref:`select() <func-select>` call.
-
+:c:func:`read()`, :c:func:`write()` and
+:c:func:`select()` call.
.. c:type:: v4l2_sliced_vbi_format
@@ -191,7 +188,7 @@ struct v4l2_sliced_vbi_format
* - __u32
- ``io_size``
- :cspan:`2` Maximum number of bytes passed by one
- :ref:`read() <func-read>` or :ref:`write() <func-write>` call,
+ :c:func:`read()` or :c:func:`write()` call,
and the buffer size in bytes for the
:ref:`VIDIOC_QBUF` and
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
@@ -274,7 +271,6 @@ Sliced VBI services
\normalsize
-
Drivers may return an ``EINVAL`` error code when applications attempt to
read or write data without prior format negotiation, after switching the
video standard (which may invalidate the negotiated VBI parameters) and
@@ -284,13 +280,12 @@ return an ``EBUSY`` error code when applications attempt to change the
format while i/o is in progress (between a
:ref:`VIDIOC_STREAMON` and
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
-:ref:`read() <func-read>` or :ref:`write() <func-write>` call).
-
+:c:func:`read()` or :c:func:`write()` call).
Reading and writing sliced VBI data
===================================
-A single :ref:`read() <func-read>` or :ref:`write() <func-write>`
+A single :c:func:`read()` or :c:func:`write()`
call must pass all data belonging to one video frame. That is an array
of struct :c:type:`v4l2_sliced_vbi_data` structures with one or
more elements and a total size not exceeding ``io_size`` bytes. Likewise
@@ -298,7 +293,6 @@ in streaming I/O mode one buffer of ``io_size`` bytes must contain data
of one video frame. The ``id`` of unused
struct :c:type:`v4l2_sliced_vbi_data` elements must be zero.
-
.. c:type:: v4l2_sliced_vbi_data
struct v4l2_sliced_vbi_data
@@ -344,9 +338,8 @@ struct v4l2_sliced_vbi_data
bytes at the end of this array are undefined, drivers and
applications shall ignore them.
-
Packets are always passed in ascending line number order, without
-duplicate line numbers. The :ref:`write() <func-write>` function and
+duplicate line numbers. The :c:func:`write()` function and
the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
error code when applications violate this rule. They must also return an
EINVAL error code when applications pass an incorrect field or line
@@ -370,7 +363,6 @@ streaming (:ref:`memory mapping <mmap>` and/or
:ref:`user pointer <userp>`) I/O. The latter bears the possibility of
synchronizing video and VBI data by using buffer timestamps.
-
Sliced VBI Data in MPEG Streams
===============================
@@ -405,7 +397,6 @@ data insertion is not supported by the device.
The following subsections specify the format of the embedded sliced VBI
data.
-
MPEG Stream Embedded, Sliced VBI Data Format: NONE
--------------------------------------------------
@@ -417,7 +408,6 @@ nor driver shall insert "empty" embedded sliced VBI data packets in the
MPEG stream when this format is set. No MPEG stream data structures are
specified for this format.
-
MPEG Stream Embedded, Sliced VBI Data Format: IVTV
--------------------------------------------------
@@ -460,7 +450,6 @@ the end with unspecified fill bytes to align the end of the payload to a
with 18 lines/field with 43 bytes of data/line and a 4 byte magic
number).
-
.. c:type:: v4l2_mpeg_vbi_fmt_ivtv
struct v4l2_mpeg_vbi_fmt_ivtv
@@ -523,7 +512,6 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
valid and that 36 lines of sliced VBI data are present.
-
.. c:type:: v4l2_mpeg_vbi_itv0
.. c:type:: v4l2_mpeg_vbi_ITV0
@@ -548,7 +536,6 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0
value:
-
::
linemask[0] b0: line 6 first field
@@ -574,7 +561,6 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0
applications.
-
.. _v4l2-mpeg-vbi-itv0-1:
struct v4l2_mpeg_vbi_ITV0
@@ -596,7 +582,6 @@ struct v4l2_mpeg_vbi_ITV0
lines 6 through 23 of the second field.
-
.. c:type:: v4l2_mpeg_vbi_itv0_line
struct v4l2_mpeg_vbi_itv0_line
@@ -619,7 +604,6 @@ struct v4l2_mpeg_vbi_itv0_line
- The sliced VBI data for the line.
-
.. _ITV0-Line-Identifier-Constants:
Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
@@ -653,7 +637,6 @@ Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
description of the line payload.
-
.. [#f1]
According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
field and lines 5-22 of the second field may carry Teletext data.
diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst
index 3f7bac44377c..caa05fbbd396 100644
--- a/Documentation/userspace-api/media/v4l/diff-v4l.rst
+++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _diff-v4l:
@@ -13,7 +14,6 @@ the much improved V4L2 API replaces the V4L API. The support for the old
V4L calls were removed from Kernel, but the library :ref:`libv4l`
supports the conversion of a V4L API system call into a V4L2 one.
-
Opening and Closing Devices
===========================
@@ -32,7 +32,6 @@ recommend that V4L2 drivers by default register devices with the same
numbers, but the system administrator can assign arbitrary minor numbers
using driver module options. The major device number remains 81.
-
.. _v4l-dev:
.. flat-table:: V4L Device Types, Names and Numbers
@@ -53,14 +52,12 @@ using driver module options. The major device number remains 81.
- ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
- 224-255
-
V4L prohibits (or used to prohibit) multiple opens of a device file.
V4L2 drivers *may* support multiple opens, see :ref:`open` for details
and consequences.
V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
-
Querying Capabilities
=====================
@@ -151,7 +148,6 @@ introduction.
- ``-``
- See above.
-
The ``audios`` field was replaced by ``capabilities`` flag
``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
outputs. To determine their number applications can enumerate audio
@@ -164,7 +160,6 @@ were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
dimensions returns the closest size possible, taking into account the
current video standard, cropping and scaling limitations.
-
Video Sources
=============
@@ -180,7 +175,6 @@ The ``channel`` field counting inputs was renamed to ``index``, the
video input types were renamed as follows:
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -192,7 +186,6 @@ video input types were renamed as follows:
* - ``VIDEO_TYPE_CAMERA``
- ``V4L2_INPUT_TYPE_CAMERA``
-
Unlike the ``tuners`` field expressing the number of tuners of this
input, V4L2 assumes each video input is connected to at most one tuner.
However a tuner can have more than one input, i. e. RF connectors, and a
@@ -216,7 +209,6 @@ addition together with the ``norm`` field and has been removed in the
meantime. V4L2 has a similar, albeit more comprehensive approach to
video standards, see :ref:`standard` for more information.
-
Tuning
======
@@ -260,7 +252,6 @@ frequency where renamed to
to a struct :c:type:`v4l2_frequency` instead of an
unsigned long integer.
-
.. _v4l-image-properties:
Image Properties
@@ -274,7 +265,6 @@ replaced by V4L2 controls accessible with the
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -292,7 +282,6 @@ replaced by V4L2 controls accessible with the
* - ``whiteness``
- ``V4L2_CID_WHITENESS``
-
The V4L picture controls are assumed to range from 0 to 65535 with no
particular reset value. The V4L2 API permits arbitrary limits and
defaults which can be queried with the
@@ -306,7 +295,6 @@ of the image depth and others need not know. The ``palette`` field moved
into the struct :c:type:`v4l2_pix_format`:
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -346,11 +334,9 @@ into the struct :c:type:`v4l2_pix_format`:
* - ``VIDEO_PALETTE_YUV410P``
- :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
-
V4L2 image formats are defined in :ref:`pixfmt`. The image format can
be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
Audio
=====
@@ -384,7 +370,6 @@ The following fields where replaced by V4L2 controls accessible with the
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -400,7 +385,6 @@ The following fields where replaced by V4L2 controls accessible with the
* - ``balance``
- ``V4L2_CID_AUDIO_BALANCE``
-
To determine which of these controls are supported by a driver V4L
provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
@@ -416,7 +400,6 @@ V4L2 API permits arbitrary limits and defaults which can be queried with
the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
information about controls see :ref:`control`.
-
Frame Buffer Overlay
====================
@@ -463,7 +446,6 @@ size is determined by ``w.width`` and ``w.height``.
The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
:ref:`VIDIOC_OVERLAY`.
-
Cropping
========
@@ -490,21 +472,19 @@ struct :c:type:`v4l2_window`. These structures are used to
select a capture or overlay format with the
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
Reading Images, Memory Mapping
==============================
-
Capturing using the read method
-------------------------------
There is no essential difference between reading images from a V4L or
-V4L2 device using the :ref:`read() <func-read>` function, however V4L2
+V4L2 device using the :c:func:`read()` function, however V4L2
drivers are not required to support this I/O method. Applications can
determine if the function is available with the
:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
exchanging data with applications must support the
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+:c:func:`select()` and :c:func:`poll()`
functions.
To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
@@ -517,7 +497,6 @@ negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
For more information about the V4L2 read interface see :ref:`rw`.
-
Capturing using memory mapping
------------------------------
@@ -528,7 +507,6 @@ read method. V4L2 supports memory mapping as well, with a few
differences.
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -550,7 +528,7 @@ differences.
``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
the offset of each buffer from the start of the virtual file, and
the overall amount of memory used, which can be used as arguments
- for the :ref:`mmap() <func-mmap>` function.
+ for the :c:func:`mmap()` function.
- Buffers are individually mapped. The offset and size of each
buffer can be determined with the
:ref:`VIDIOC_QUERYBUF` ioctl.
@@ -568,7 +546,7 @@ differences.
the incoming queue. Filled buffers are dequeued from the outgoing
queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
until filled buffers become available this function,
- :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
+ :c:func:`select()` or :c:func:`poll()` can
be used. The :ref:`VIDIOC_STREAMON` ioctl
must be called once after enqueuing one or more buffers to start
capturing. Its counterpart
@@ -577,11 +555,9 @@ differences.
signal status, if known, with the
:ref:`VIDIOC_ENUMINPUT` ioctl.
-
For a more in-depth discussion of memory mapping and examples, see
:ref:`mmap`.
-
Reading Raw VBI Data
====================
@@ -592,7 +568,6 @@ the V4L VBI interface. Reading from the device yields a raw VBI image
with the following parameters:
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -616,7 +591,6 @@ with the following parameters:
* - flags
- 0
-
Undocumented in the V4L specification, in Linux 2.3 the
``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
``vbi_format`` were added to determine the VBI image
@@ -630,11 +604,10 @@ remaining fields are probably equivalent to struct
Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
semantics differ from those specified for V4L2 in two ways. The
-parameters are reset on :ref:`open() <func-open>` and
+parameters are reset on :c:func:`open()` and
``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
are invalid.
-
Miscellaneous
=============
diff --git a/Documentation/userspace-api/media/v4l/dmabuf.rst b/Documentation/userspace-api/media/v4l/dmabuf.rst
index f43d400dafaa..50fba11c2477 100644
--- a/Documentation/userspace-api/media/v4l/dmabuf.rst
+++ b/Documentation/userspace-api/media/v4l/dmabuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _dmabuf:
@@ -36,7 +37,6 @@ are passed in struct :c:type:`v4l2_buffer` (or in struct
driver must be switched into DMABUF I/O mode by calling the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
-
Example: Initiating streaming I/O with DMABUF file descriptors
==============================================================
@@ -135,10 +135,10 @@ buffers it must wait until an empty buffer can be dequeued and reused.
Two methods exist to suspend execution of the application until one or
more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
-``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
+``O_NONBLOCK`` flag was given to the :c:func:`open()` function,
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
error code when no buffer is available. The
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+:c:func:`select()` and :c:func:`poll()`
functions are always available.
To start and stop capturing or displaying applications call the
@@ -158,5 +158,5 @@ Drivers implementing DMABUF importing I/O must support the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
<VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
-and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+and the :c:func:`select()` and :c:func:`poll()`
functions.
diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst
index eaa6445f6160..35bbb2fea46e 100644
--- a/Documentation/userspace-api/media/v4l/format.rst
+++ b/Documentation/userspace-api/media/v4l/format.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _format:
@@ -6,7 +7,6 @@
Data Formats
************
-
Data Format Negotiation
=======================
@@ -53,8 +53,8 @@ image size.
When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
effects are implied by the next step, the selection of an I/O method
with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
-with the first :ref:`read() <func-read>` or
-:ref:`write() <func-write>` call.
+with the first :c:func:`read()` or
+:c:func:`write()` call.
Generally only one logical stream can be assigned to a file descriptor,
the exception being drivers permitting simultaneous video capturing and
@@ -67,7 +67,6 @@ All drivers exchanging data with applications must support the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
-
Image Format Enumeration
========================
diff --git a/Documentation/userspace-api/media/v4l/func-close.rst b/Documentation/userspace-api/media/v4l/func-close.rst
index c03ff3e62738..dba3263fd1b9 100644
--- a/Documentation/userspace-api/media/v4l/func-close.rst
+++ b/Documentation/userspace-api/media/v4l/func-close.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-close:
@@ -11,7 +12,6 @@ Name
v4l2-close - Close a V4L2 device
-
Synopsis
========
@@ -19,16 +19,13 @@ Synopsis
#include <unistd.h>
-
.. c:function:: int close( int fd )
- :name: v4l2-close
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
+ File descriptor returned by :c:func:`open()`.
Description
===========
@@ -38,7 +35,6 @@ associated with the file descriptor are freed. However data format
parameters, current input or output, control values or other properties
remain unchanged.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/func-ioctl.rst b/Documentation/userspace-api/media/v4l/func-ioctl.rst
index 8bde6b4f1cb5..f3b005094334 100644
--- a/Documentation/userspace-api/media/v4l/func-ioctl.rst
+++ b/Documentation/userspace-api/media/v4l/func-ioctl.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-ioctl:
@@ -11,7 +12,6 @@ Name
v4l2-ioctl - Program a V4L2 device
-
Synopsis
========
@@ -19,15 +19,13 @@ Synopsis
#include <sys/ioctl.h>
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
- :name: v4l2-ioctl
+``int ioctl(int fd, int request, void *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``request``
V4L2 ioctl request code as defined in the ``videodev2.h`` header
@@ -36,7 +34,6 @@ Arguments
``argp``
Pointer to a function parameter, usually a structure.
-
Description
===========
@@ -50,7 +47,6 @@ include the version in the kernel sources on the system they compile on.
All V4L2 ioctl requests, their respective function and parameters are
specified in :ref:`user-func`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/func-mmap.rst b/Documentation/userspace-api/media/v4l/func-mmap.rst
index b3a9cd862a7f..e3e5e64ebe7e 100644
--- a/Documentation/userspace-api/media/v4l/func-mmap.rst
+++ b/Documentation/userspace-api/media/v4l/func-mmap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-mmap:
@@ -11,7 +12,6 @@ Name
v4l2-mmap - Map device memory into application address space
-
Synopsis
========
@@ -20,9 +20,7 @@ Synopsis
#include <unistd.h>
#include <sys/mman.h>
-
.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
- :name: v4l2-mmap
Arguments
=========
@@ -54,7 +52,7 @@ Arguments
#. The Linux ``videobuf`` kernel module, which is used by some
drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the
driver does not support the desired protection, the
- :ref:`mmap() <func-mmap>` function fails.
+ :c:func:`mmap()` function fails.
#. Device memory accesses (e. g. the memory on a graphics card
with video capturing hardware) may incur a performance penalty
@@ -70,7 +68,7 @@ Arguments
``MAP_FIXED`` requests that the driver selects no other address than
the one specified. If the specified address cannot be used,
- :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified,
+ :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified,
``start`` must be a multiple of the pagesize. Use of this option is
discouraged.
@@ -87,7 +85,7 @@ Arguments
flags.
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``offset``
Offset of the buffer in device memory. This must be the same value
@@ -97,11 +95,10 @@ Arguments
in the struct :c:type:`v4l2_plane` ``m`` union
``mem_offset`` field for the multi-planar API.
-
Description
===========
-The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at
+The :c:func:`mmap()` function asks to map ``length`` bytes starting at
``offset`` in the memory of the device specified by ``fd`` into the
application address space, preferably at address ``start``. This latter
address is a hint only, and is usually specified as 0.
@@ -111,13 +108,12 @@ Suitable length and offset parameters are queried with the
allocated with the :ref:`VIDIOC_REQBUFS` ioctl
before they can be queried.
-To unmap buffers the :ref:`munmap() <func-munmap>` function is used.
-
+To unmap buffers the :c:func:`munmap()` function is used.
Return Value
============
-On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On
+On success :c:func:`mmap()` returns a pointer to the mapped buffer. On
error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
appropriately. Possible error codes are:
diff --git a/Documentation/userspace-api/media/v4l/func-munmap.rst b/Documentation/userspace-api/media/v4l/func-munmap.rst
index e8a27e43373a..077d58333904 100644
--- a/Documentation/userspace-api/media/v4l/func-munmap.rst
+++ b/Documentation/userspace-api/media/v4l/func-munmap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-munmap:
@@ -11,7 +12,6 @@ Name
v4l2-munmap - Unmap device memory
-
Synopsis
========
@@ -20,37 +20,33 @@ Synopsis
#include <unistd.h>
#include <sys/mman.h>
-
.. c:function:: int munmap( void *start, size_t length )
- :name: v4l2-munmap
Arguments
=========
``start``
Address of the mapped buffer as returned by the
- :ref:`mmap() <func-mmap>` function.
+ :c:func:`mmap()` function.
``length``
Length of the mapped buffer. This must be the same value as given to
- :ref:`mmap() <func-mmap>` and returned by the driver in the struct
+ :c:func:`mmap()` and returned by the driver in the struct
:c:type:`v4l2_buffer` ``length`` field for the
single-planar API and in the struct
:c:type:`v4l2_plane` ``length`` field for the
multi-planar API.
-
Description
===========
-Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped
+Unmaps a previously with the :c:func:`mmap()` function mapped
buffer and frees it, if possible.
-
Return Value
============
-On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the
+On success :c:func:`munmap()` returns 0, on failure -1 and the
``errno`` variable is set appropriately:
EINVAL
diff --git a/Documentation/userspace-api/media/v4l/func-open.rst b/Documentation/userspace-api/media/v4l/func-open.rst
index f3890d284918..ba23ff1e45dd 100644
--- a/Documentation/userspace-api/media/v4l/func-open.rst
+++ b/Documentation/userspace-api/media/v4l/func-open.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-open:
@@ -11,7 +12,6 @@ Name
v4l2-open - Open a V4L2 device
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <fcntl.h>
-
.. c:function:: int open( const char *device_name, int flags )
- :name: v4l2-open
Arguments
=========
@@ -34,7 +32,7 @@ Arguments
technicality, input devices still support only reading and output
devices only writing.
- When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>`
+ When the ``O_NONBLOCK`` flag is given, the :c:func:`read()`
function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will
return the ``EAGAIN`` error code when no data is available or no
buffer is in the driver outgoing queue, otherwise these functions
@@ -43,22 +41,20 @@ Arguments
Other flags have no effect.
-
Description
===========
-To open a V4L2 device applications call :ref:`open() <func-open>` with the
+To open a V4L2 device applications call :c:func:`open()` with the
desired device name. This function has no side effects; all data format
parameters, current input or output, control values or other properties
-remain unchanged. At the first :ref:`open() <func-open>` call after loading the
+remain unchanged. At the first :c:func:`open()` call after loading the
driver they will be reset to default values, drivers are never in an
undefined state.
-
Return Value
============
-On success :ref:`open() <func-open>` returns the new file descriptor. On error
+On success :c:func:`open()` returns the new file descriptor. On error
-1 is returned, and the ``errno`` variable is set appropriately.
Possible error codes are:
diff --git a/Documentation/userspace-api/media/v4l/func-poll.rst b/Documentation/userspace-api/media/v4l/func-poll.rst
index 95cf9c6fedcd..cbf4a0a10ae2 100644
--- a/Documentation/userspace-api/media/v4l/func-poll.rst
+++ b/Documentation/userspace-api/media/v4l/func-poll.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-poll:
@@ -11,7 +12,6 @@ Name
v4l2-poll - Wait for some event on a file descriptor
-
Synopsis
========
@@ -19,19 +19,16 @@ Synopsis
#include <sys/poll.h>
-
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
- :name: v4l2-poll
Arguments
=========
-
Description
===========
-With the :ref:`poll() <func-poll>` function applications can suspend execution
+With the :c:func:`poll()` function applications can suspend execution
until the driver has captured data or is ready to accept data for
output.
@@ -44,57 +41,56 @@ display. When buffers are already in the outgoing queue of the driver
(capture) or the incoming queue isn't full (display) the function
returns immediately.
-On success :ref:`poll() <func-poll>` returns the number of file descriptors
+On success :c:func:`poll()` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
-``revents`` field of the respective :c:func:`struct pollfd` structure
+``revents`` field of the respective ``struct pollfd`` structure
is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
flags in the ``revents`` field, output devices the ``POLLOUT`` and
``POLLWRNORM`` flags. When the function timed out it returns a value of
zero, on failure it returns -1 and the ``errno`` variable is set
appropriately. When the application did not call
-:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :ref:`poll() <func-poll>`
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()`
function succeeds, but sets the ``POLLERR`` flag in the ``revents``
field. When the application has called
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but
hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the
-:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in
+:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in
the ``revents`` field. For output devices this same situation will cause
-:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and
+:c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and
``POLLWRNORM`` flags in the ``revents`` field.
If an event occurred (see :ref:`VIDIOC_DQEVENT`)
then ``POLLPRI`` will be set in the ``revents`` field and
-:ref:`poll() <func-poll>` will return.
+:c:func:`poll()` will return.
-When use of the :ref:`read() <func-read>` function has been negotiated and the
-driver does not capture yet, the :ref:`poll() <func-poll>` function starts
+When use of the :c:func:`read()` function has been negotiated and the
+driver does not capture yet, the :c:func:`poll()` function starts
capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
it waits until data has been captured and can be read. When the driver
captures continuously (as opposed to, for example, still images) the
function may return immediately.
-When use of the :ref:`write() <func-write>` function has been negotiated and the
-driver does not stream yet, the :ref:`poll() <func-poll>` function starts
+When use of the :c:func:`write()` function has been negotiated and the
+driver does not stream yet, the :c:func:`poll()` function starts
streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
it waits until the driver is ready for a non-blocking
-:ref:`write() <func-write>` call.
+:c:func:`write()` call.
If the caller is only interested in events (just ``POLLPRI`` is set in
-the ``events`` field), then :ref:`poll() <func-poll>` will *not* start
+the ``events`` field), then :c:func:`poll()` will *not* start
streaming if the driver does not stream yet. This makes it possible to
just poll for events and not for buffers.
-All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
-function or streaming I/O must also support the :ref:`poll() <func-poll>`
+All drivers implementing the :c:func:`read()` or :c:func:`write()`
+function or streaming I/O must also support the :c:func:`poll()`
function.
-For more details see the :ref:`poll() <func-poll>` manual page.
-
+For more details see the :c:func:`poll()` manual page.
Return Value
============
-On success, :ref:`poll() <func-poll>` returns the number structures which have
+On success, :c:func:`poll()` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:
diff --git a/Documentation/userspace-api/media/v4l/func-read.rst b/Documentation/userspace-api/media/v4l/func-read.rst
index 56b255c595e1..e6f6ac4bed77 100644
--- a/Documentation/userspace-api/media/v4l/func-read.rst
+++ b/Documentation/userspace-api/media/v4l/func-read.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-read:
@@ -11,7 +12,6 @@ Name
v4l2-read - Read from a V4L2 device
-
Synopsis
========
@@ -19,15 +19,13 @@ Synopsis
#include <unistd.h>
-
.. c:function:: ssize_t read( int fd, void *buf, size_t count )
- :name: v4l2-read
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``buf``
Buffer to be filled
@@ -38,48 +36,48 @@ Arguments
Description
===========
-:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file
+:c:func:`read()` attempts to read up to ``count`` bytes from file
descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
data in the buffer is discussed in the respective device interface
-section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero
+section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
the result is unspecified. Regardless of the ``count`` value each
-:ref:`read() <func-read>` call will provide at most one frame (two fields)
+:c:func:`read()` call will provide at most one frame (two fields)
worth of data.
-By default :ref:`read() <func-read>` blocks until data becomes available. When
-the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>`
+By default :c:func:`read()` blocks until data becomes available. When
+the ``O_NONBLOCK`` flag was given to the :c:func:`open()`
function it returns immediately with an ``EAGAIN`` error code when no data
-is available. The :ref:`select() <func-select>` or
-:ref:`poll() <func-poll>` functions can always be used to suspend
+is available. The :c:func:`select()` or
+:c:func:`poll()` functions can always be used to suspend
execution until data becomes available. All drivers supporting the
-:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and
-:ref:`poll() <func-poll>`.
+:c:func:`read()` function must also support :c:func:`select()` and
+:c:func:`poll()`.
Drivers can implement read functionality in different ways, using a
single or multiple buffers and discarding the oldest or newest frames
once the internal buffers are filled.
-:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled.
+:c:func:`read()` never returns a "snapshot" of a buffer being filled.
Using a single buffer the driver will stop capturing when the
application starts reading the buffer until the read is finished. Thus
only the period of the vertical blanking interval is available for
reading, or the capture rate must fall below the nominal frame rate of
the video standard.
-The behavior of :ref:`read() <func-read>` when called during the active picture
+The behavior of :c:func:`read()` when called during the active picture
period or the vertical blanking separating the top and bottom field
depends on the discarding policy. A driver discarding the oldest frames
keeps capturing into an internal buffer, continuously overwriting the
previously, not read frame, and returns the frame being received at the
-time of the :ref:`read() <func-read>` call as soon as it is complete.
+time of the :c:func:`read()` call as soon as it is complete.
A driver discarding the newest frames stops capturing until the next
-:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>`
+:c:func:`read()` call. The frame being received at :c:func:`read()`
time is discarded, returning the following frame instead. Again this
implies a reduction of the capture rate to one half or less of the
nominal frame rate. An example of this model is the video read mode of
-the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>`
+the bttv driver, initiating a DMA to user memory when :c:func:`read()`
is called and returning when the DMA finished.
In the multiple buffer model drivers maintain a ring of internal
@@ -94,14 +92,13 @@ the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
however. The discarding policy is not reported and cannot be changed.
For minimum requirements see :ref:`devices`.
-
Return Value
============
On success, the number of bytes read is returned. It is not an error if
this number is smaller than the number of bytes requested, or the amount
of data required for one frame. This may happen for example because
-:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is
+:c:func:`read()` was interrupted by a signal. On error, -1 is
returned, and the ``errno`` variable is set appropriately. In this case
the next read will start at the beginning of a new frame. Possible error
codes are:
@@ -129,5 +126,5 @@ EIO
communicate with a remote device (USB camera etc.).
EINVAL
- The :ref:`read() <func-read>` function is not supported by this driver, not
+ The :c:func:`read()` function is not supported by this driver, not
on this device, or generally not on this type of device.
diff --git a/Documentation/userspace-api/media/v4l/func-select.rst b/Documentation/userspace-api/media/v4l/func-select.rst
index 6715d5efcc27..ba1879c728f0 100644
--- a/Documentation/userspace-api/media/v4l/func-select.rst
+++ b/Documentation/userspace-api/media/v4l/func-select.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-select:
@@ -11,7 +12,6 @@ Name
v4l2-select - Synchronous I/O multiplexing
-
Synopsis
========
@@ -21,9 +21,7 @@ Synopsis
#include <sys/types.h>
#include <unistd.h>
-
.. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
- :name: v4l2-select
Arguments
=========
@@ -43,11 +41,10 @@ Arguments
``timeout``
Maximum time to wait.
-
Description
===========
-With the :ref:`select() <func-select>` function applications can suspend
+With the :c:func:`select()` function applications can suspend
execution until the driver has captured data or is ready to accept data
for output.
@@ -56,40 +53,39 @@ buffer has been filled or displayed and can be dequeued with the
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
the outgoing queue of the driver the function returns immediately.
-On success :ref:`select() <func-select>` returns the total number of bits set in
-:c:func:`struct fd_set`. When the function timed out it returns
+On success :c:func:`select()` returns the total number of bits set in
+``fd_set``. When the function timed out it returns
a value of zero. On failure it returns -1 and the ``errno`` variable is
set appropriately. When the application did not call
:ref:`VIDIOC_QBUF` or
-:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>`
+:ref:`VIDIOC_STREAMON` yet the :c:func:`select()`
function succeeds, setting the bit of the file descriptor in ``readfds``
or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
calls will fail. [#f1]_
-When use of the :ref:`read() <func-read>` function has been negotiated and the
-driver does not capture yet, the :ref:`select() <func-select>` function starts
-capturing. When that fails, :ref:`select() <func-select>` returns successful and
-a subsequent :ref:`read() <func-read>` call, which also attempts to start
+When use of the :c:func:`read()` function has been negotiated and the
+driver does not capture yet, the :c:func:`select()` function starts
+capturing. When that fails, :c:func:`select()` returns successful and
+a subsequent :c:func:`read()` call, which also attempts to start
capturing, will return an appropriate error code. When the driver
captures continuously (as opposed to, for example, still images) and
-data is already available the :ref:`select() <func-select>` function returns
+data is already available the :c:func:`select()` function returns
immediately.
-When use of the :ref:`write() <func-write>` function has been negotiated the
-:ref:`select() <func-select>` function just waits until the driver is ready for a
-non-blocking :ref:`write() <func-write>` call.
+When use of the :c:func:`write()` function has been negotiated the
+:c:func:`select()` function just waits until the driver is ready for a
+non-blocking :c:func:`write()` call.
-All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
-function or streaming I/O must also support the :ref:`select() <func-select>`
+All drivers implementing the :c:func:`read()` or :c:func:`write()`
+function or streaming I/O must also support the :c:func:`select()`
function.
-For more details see the :ref:`select() <func-select>` manual page.
-
+For more details see the :c:func:`select()` manual page.
Return Value
============
-On success, :ref:`select() <func-select>` returns the number of descriptors
+On success, :c:func:`select()` returns the number of descriptors
contained in the three returned descriptor sets, which will be zero if
the timeout expired. On error -1 is returned, and the ``errno`` variable
is set appropriately; the sets and ``timeout`` are undefined. Possible
@@ -115,6 +111,6 @@ EINVAL
``FD_SETSIZE``.
.. [#f1]
- The Linux kernel implements :ref:`select() <func-select>` like the
- :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot
+ The Linux kernel implements :c:func:`select()` like the
+ :c:func:`poll()` function, but :c:func:`select()` cannot
return a ``POLLERR``.
diff --git a/Documentation/userspace-api/media/v4l/func-write.rst b/Documentation/userspace-api/media/v4l/func-write.rst
index 37683611df04..49f5a0f4275f 100644
--- a/Documentation/userspace-api/media/v4l/func-write.rst
+++ b/Documentation/userspace-api/media/v4l/func-write.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _func-write:
@@ -11,7 +12,6 @@ Name
v4l2-write - Write to a V4L2 device
-
Synopsis
========
@@ -19,15 +19,13 @@ Synopsis
#include <unistd.h>
-
.. c:function:: ssize_t write( int fd, void *buf, size_t count )
- :name: v4l2-write
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``buf``
Buffer with data to be written
@@ -38,10 +36,10 @@ Arguments
Description
===========
-:ref:`write() <func-write>` writes up to ``count`` bytes to the device
+:c:func:`write()` writes up to ``count`` bytes to the device
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``. When the hardware outputs are not active yet, this function
-enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0
+enables them. When ``count`` is zero, :c:func:`write()` returns 0
without any other effect.
When the application does not provide more data in time, the previous
@@ -49,7 +47,6 @@ video frame, raw VBI image, sliced VPS or WSS data is displayed again.
Sliced Teletext or Closed Caption data is not repeated, the driver
inserts a blank line instead.
-
Return Value
============
@@ -80,5 +77,5 @@ EIO
I/O error. This indicates some hardware problem.
EINVAL
- The :ref:`write() <func-write>` function is not supported by this driver,
+ The :c:func:`write()` function is not supported by this driver,
not on this device, or generally not on this type of device.
diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst
index 1a4fd941f163..28a2750d5c8c 100644
--- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst
+++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _hist-v4l2:
@@ -14,18 +15,17 @@ not just an extension but a replacement for the V4L API. However it took
another four years and two stable kernel releases until the new API was
finally accepted for inclusion into the kernel in its present form.
-
Early Versions
==============
1998-08-20: First version.
-1998-08-27: The :ref:`select() <func-select>` function was introduced.
+1998-08-27: The :c:func:`select()` function was introduced.
1998-09-10: New video standard interface.
1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise
-meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the
+meaningless ``O_TRUNC`` :c:func:`open()` flag, and the
aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set
this flag if they intend to access controls only, as opposed to capture
applications which need exclusive access. The ``VIDEO_STD_XXX``
@@ -65,7 +65,6 @@ output devices were added.
1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
-
V4L2 Version 0.16 1999-01-31
============================
@@ -73,7 +72,6 @@ V4L2 Version 0.16 1999-01-31
are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
digital zoom (cropping) controls.
-
V4L2 Version 0.18 1999-03-16
============================
@@ -81,7 +79,6 @@ Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver
writers, this changes how you implement your ioctl handler. See the
Driver Writer's Guide. Added some more control id codes.
-
V4L2 Version 0.19 1999-06-05
============================
@@ -107,7 +104,6 @@ malfunction of this ioctl.
1999-06-05: Changed the value of V4L2_CID_WHITENESS.
-
V4L2 Version 0.20 (1999-09-10)
==============================
@@ -128,14 +124,12 @@ common Linux driver API conventions.
VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
-
.. code-block:: c
err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
becomes
-
.. code-block:: c
int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
@@ -202,7 +196,6 @@ common Linux driver API conventions.
field counts captured frames, it is ignored by output devices. When a
capture driver drops a frame, the sequence number of that frame is skipped.
-
V4L2 Version 0.20 incremental changes
=====================================
@@ -290,13 +283,11 @@ A number of changes were made to the raw VBI interface.
were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the
latter was missing in the ``videodev.h`` file.
-
V4L2 Version 0.20 2002-07-25
============================
Added sliced VBI interface proposal.
-
V4L2 in Linux 2.5.46, 2002-10
=============================
@@ -307,7 +298,7 @@ This unnamed version was finally merged into Linux 2.5.46.
1. As specified in :ref:`related`, drivers must make related device
functions available under all minor device numbers.
-2. The :ref:`open() <func-open>` function requires access mode
+2. The :c:func:`open()` function requires access mode
``O_RDWR`` regardless of the device type. All V4L2 drivers
exchanging data with applications must support the ``O_NONBLOCK``
flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the
@@ -435,7 +426,6 @@ This unnamed version was finally merged into Linux 2.5.46.
the buffer type names changed as follows.
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -597,7 +587,6 @@ This unnamed version was finally merged into Linux 2.5.46.
V4L2 documentation was inaccurate, this has been corrected in
:ref:`pixfmt`.
-
V4L2 2003-06-19
===============
@@ -648,7 +637,6 @@ V4L2 2003-06-19
Kernel 2.6.39. Drivers and applications assuming a constant parameter
need an update.
-
V4L2 2003-11-05
===============
@@ -657,7 +645,6 @@ V4L2 2003-11-05
refer to bytes in memory, in ascending address order.
-
.. flat-table::
:header-rows: 1
:stub-columns: 0
@@ -678,7 +665,6 @@ V4L2 2003-11-05
- R, G, B, X
- B, G, R, X
-
The ``V4L2_PIX_FMT_BGR24`` example was always correct.
In :ref:`v4l-image-properties` the mapping of the V4L
@@ -689,7 +675,6 @@ V4L2 2003-11-05
RGB pixel formats differently. These issues have yet to be addressed,
for details see :ref:`pixfmt-rgb`.
-
V4L2 in Linux 2.6.6, 2004-05-09
===============================
@@ -698,7 +683,6 @@ V4L2 in Linux 2.6.6, 2004-05-09
ioctl, while the read-only version was renamed to
``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39.
-
V4L2 in Linux 2.6.8
===================
@@ -709,7 +693,6 @@ V4L2 in Linux 2.6.8
the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no
longer read-only.
-
V4L2 spec erratum 2004-08-01
============================
@@ -727,7 +710,6 @@ V4L2 spec erratum 2004-08-01
also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO``
error code was not documented.
-
V4L2 in Linux 2.6.14
====================
@@ -735,7 +717,6 @@ V4L2 in Linux 2.6.14
:ref:`sliced` and replaces the interface first proposed in V4L2
specification 0.8.
-
V4L2 in Linux 2.6.15
====================
@@ -755,7 +736,6 @@ V4L2 in Linux 2.6.15
``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
in Linux 2.6.25.)
-
V4L2 spec erratum 2005-11-27
============================
@@ -765,7 +745,6 @@ cropping is supported. In the video standard selection example in
:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used
the wrong argument type.
-
V4L2 spec erratum 2006-01-10
============================
@@ -778,14 +757,12 @@ V4L2 spec erratum 2006-01-10
write-only as stated on its reference page. The ioctl changed in 2003
as noted above.
-
V4L2 spec erratum 2006-02-03
============================
1. In struct v4l2_captureparm and struct v4l2_outputparm the ``timeperframe``
field gives the time in seconds, not microseconds.
-
V4L2 spec erratum 2006-02-04
============================
@@ -808,7 +785,6 @@ V4L2 in Linux 2.6.17
``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See
the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details.
-
V4L2 spec erratum 2006-09-23 (Draft 0.15)
=========================================
@@ -837,7 +813,6 @@ V4L2 spec erratum 2006-09-23 (Draft 0.15)
extended from 224-239 to 224-255. Accordingly device file names
``/dev/vbi0`` to ``/dev/vbi31`` are possible now.
-
V4L2 in Linux 2.6.18
====================
@@ -852,7 +827,6 @@ V4L2 in Linux 2.6.18
``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER``
(:ref:`control-flags`). See :ref:`extended-controls` for details.
-
V4L2 in Linux 2.6.19
====================
@@ -874,14 +848,12 @@ V4L2 in Linux 2.6.19
3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was
added.
-
V4L2 spec erratum 2006-10-12 (Draft 0.17)
=========================================
1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not
4:2:2 format.
-
V4L2 in Linux 2.6.21
====================
@@ -889,7 +861,6 @@ V4L2 in Linux 2.6.21
General Public License version two or later, and under a 3-clause
BSD-style license.
-
V4L2 in Linux 2.6.22
====================
@@ -914,7 +885,6 @@ V4L2 in Linux 2.6.22
This may **break compatibility** with existing applications. Drivers
supporting the "host order RGB32" format are not known.
-
V4L2 in Linux 2.6.24
====================
@@ -922,7 +892,6 @@ V4L2 in Linux 2.6.24
``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
``V4L2_PIX_FMT_YUV32`` were added.
-
V4L2 in Linux 2.6.25
====================
@@ -949,7 +918,6 @@ V4L2 in Linux 2.6.25
interface in Linux 2.6.18, where finally removed from the
``videodev2.h`` header file.
-
V4L2 in Linux 2.6.26
====================
@@ -959,7 +927,6 @@ V4L2 in Linux 2.6.26
2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
``V4L2_CID_COLOR_KILLER``.
-
V4L2 in Linux 2.6.27
====================
@@ -971,7 +938,6 @@ V4L2 in Linux 2.6.27
``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``,
``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added.
-
V4L2 in Linux 2.6.28
====================
@@ -983,7 +949,6 @@ V4L2 in Linux 2.6.28
3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and
``V4L2_PIX_FMT_SGRBG10DPCM8`` were added.
-
V4L2 in Linux 2.6.29
====================
@@ -999,7 +964,6 @@ V4L2 in Linux 2.6.29
``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
``V4L2_CID_PRIVACY``.
-
V4L2 in Linux 2.6.30
====================
@@ -1007,7 +971,6 @@ V4L2 in Linux 2.6.30
2. New control ``V4L2_CID_COLORFX`` was added.
-
V4L2 in Linux 2.6.32
====================
@@ -1034,21 +997,18 @@ V4L2 in Linux 2.6.32
9. Added Remote Controller chapter, describing the default Remote
Controller mapping for media devices.
-
V4L2 in Linux 2.6.33
====================
1. Added support for Digital Video timings in order to support HDTV
receivers and transmitters.
-
V4L2 in Linux 2.6.34
====================
1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE``
controls to the :ref:`Camera controls class <camera-controls>`.
-
V4L2 in Linux 2.6.37
====================
@@ -1057,7 +1017,6 @@ V4L2 in Linux 2.6.37
applications found that used it. It was originally scheduled for
removal in 2.6.35.
-
V4L2 in Linux 2.6.39
====================
@@ -1067,7 +1026,6 @@ V4L2 in Linux 2.6.39
drivers and applications. See :ref:`multi-planar API <planar-apis>`
for details.
-
V4L2 in Linux 3.1
=================
@@ -1078,7 +1036,6 @@ V4L2 in Linux 3.1
Added V4L2_CTRL_TYPE_BITMASK.
-
V4L2 in Linux 3.2
=================
@@ -1089,7 +1046,6 @@ V4L2 in Linux 3.2
Does not affect the compatibility of current drivers and
applications. See :ref:`selection API <selection-api>` for details.
-
V4L2 in Linux 3.3
=================
@@ -1099,7 +1055,6 @@ V4L2 in Linux 3.3
2. Added the device_caps field to struct v4l2_capabilities and added
the new V4L2_CAP_DEVICE_CAPS capability.
-
V4L2 in Linux 3.4
=================
@@ -1110,7 +1065,6 @@ V4L2 in Linux 3.4
:ref:`VIDIOC_QUERY_DV_TIMINGS` and
:ref:`VIDIOC_DV_TIMINGS_CAP`.
-
V4L2 in Linux 3.5
=================
@@ -1137,7 +1091,6 @@ V4L2 in Linux 3.5
``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``,
``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``.
-
V4L2 in Linux 3.6
=================
@@ -1150,7 +1103,6 @@ V4L2 in Linux 3.6
3. Added support for frequency band enumerations:
:ref:`VIDIOC_ENUM_FREQ_BANDS`.
-
V4L2 in Linux 3.9
=================
@@ -1160,7 +1112,6 @@ V4L2 in Linux 3.9
2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See
:ref:`ctrl-changes-flags`.
-
V4L2 in Linux 3.10
==================
@@ -1172,32 +1123,27 @@ V4L2 in Linux 3.10
2. Added new debugging ioctl
:ref:`VIDIOC_DBG_G_CHIP_INFO`.
-
V4L2 in Linux 3.11
==================
1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl.
-
V4L2 in Linux 3.14
==================
1. In struct v4l2_rect, the type of ``width`` and
``height`` fields changed from _s32 to _u32.
-
V4L2 in Linux 3.15
==================
1. Added Software Defined Radio (SDR) Interface.
-
V4L2 in Linux 3.16
==================
1. Added event V4L2_EVENT_SOURCE_CHANGE.
-
V4L2 in Linux 3.17
==================
@@ -1207,14 +1153,12 @@ V4L2 in Linux 3.17
2. Added compound control types and
:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
-
V4L2 in Linux 3.18
==================
1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera
controls.
-
V4L2 in Linux 3.19
==================
@@ -1232,13 +1176,11 @@ V4L2 in Linux 4.4
3. Added transmitter support for Software Defined Radio (SDR) Interface.
-
.. _other:
Relation of V4L2 to other Linux multimedia APIs
===============================================
-
.. _xvideo:
X Video Extension
@@ -1284,7 +1226,6 @@ YUV to RGB conversion and scaling for faster video playback, and added
an interface to MPEG-2 decoding hardware. This API is useful to display
images captured with V4L2 devices.
-
Digital Video
-------------
@@ -1294,13 +1235,11 @@ homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux
DVB API has no connection to the V4L2 API except that drivers for hybrid
hardware may support both.
-
Audio Interfaces
----------------
[to do - OSS/ALSA]
-
.. _experimental:
Experimental API Elements
@@ -1314,7 +1253,6 @@ change in the future.
- :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
-
.. _obsolete:
Obsolete API Elements
diff --git a/Documentation/userspace-api/media/v4l/io.rst b/Documentation/userspace-api/media/v4l/io.rst
index 9dc36b41dbf6..ce0cece6f35f 100644
--- a/Documentation/userspace-api/media/v4l/io.rst
+++ b/Documentation/userspace-api/media/v4l/io.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _io:
@@ -9,8 +10,8 @@ The V4L2 API defines several different methods to read from or write to
a device. All drivers exchanging data with applications must support at
least one of them.
-The classic I/O method using the :ref:`read() <func-read>` and
-:ref:`write() <func-write>` function is automatically selected after opening a
+The classic I/O method using the :c:func:`read()` and
+:c:func:`write()` function is automatically selected after opening a
V4L2 device. When the driver does not support this method attempts to
read or write will fail at any time.
@@ -38,7 +39,6 @@ closing and reopening the device.
The following sections describe the various I/O methods in more detail.
-
.. toctree::
:maxdepth: 1
diff --git a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst
index e03280b35570..05690f2358ce 100644
--- a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst
+++ b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _libv4l-introduction:
@@ -17,7 +18,6 @@ An example of using libv4l is provided by
libv4l consists of 3 different libraries:
-
libv4lconvert
=============
@@ -65,7 +65,6 @@ libv4lconvert/processing. These controls are stored application wide
libv4lconvert/processing offers the actual video processing
functionality.
-
libv4l1
=======
@@ -78,7 +77,6 @@ just pass calls through.
Since those functions are emulations of the old V4L1 API, it shouldn't
be used for new applications.
-
libv4l2
=======
@@ -105,7 +103,6 @@ available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
keeps enumerating the hardware supported formats, plus the emulated
formats offered by libv4l at the end.
-
.. _libv4l-ops:
Libv4l device control functions
@@ -115,17 +112,17 @@ The common file operation methods are provided by libv4l.
Those functions operate just like the gcc function ``dup()`` and
V4L2 functions
-:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`,
-:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`read() <v4l2-read>`,
-:c:func:`mmap() <v4l2-mmap>` and :c:func:`munmap() <v4l2-munmap>`:
+:c:func:`open()`, :c:func:`close()`,
+:c:func:`ioctl()`, :c:func:`read()`,
+:c:func:`mmap()` and :c:func:`munmap()`:
.. c:function:: int v4l2_open(const char *file, int oflag, ...)
- operates like the :c:func:`open() <v4l2-open>` function.
+ operates like the :c:func:`open()` function.
.. c:function:: int v4l2_close(int fd)
- operates like the :c:func:`close() <v4l2-close>` function.
+ operates like the :c:func:`close()` function.
.. c:function:: int v4l2_dup(int fd)
@@ -133,19 +130,19 @@ V4L2 functions
.. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...)
- operates like the :c:func:`ioctl() <v4l2-ioctl>` function.
+ operates like the :c:func:`ioctl()` function.
.. c:function:: int v4l2_read (int fd, void* buffer, size_t n)
- operates like the :c:func:`read() <v4l2-read>` function.
+ operates like the :c:func:`read()` function.
.. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset);
- operates like the :c:func:`munmap() <v4l2-munmap>` function.
+ operates like the :c:func:`munmap()` function.
.. c:function:: int v4l2_munmap(void *_start, size_t length);
- operates like the :c:func:`munmap() <v4l2-munmap>` function.
+ operates like the :c:func:`munmap()` function.
Those functions provide additional control:
@@ -168,14 +165,13 @@ Those functions provide additional control:
of the given v4l control id. when the cid does not exist, could not be
accessed for some reason, or some error occurred 0 is returned.
-
v4l1compat.so wrapper library
=============================
This library intercepts calls to
-:c:func:`open() <v4l2-open>`, :c:func:`close() <v4l2-close>`,
-:c:func:`ioctl() <v4l2-ioctl>`, :c:func:`mmap() <v4l2-mmap>` and
-:c:func:`munmap() <v4l2-munmap>`
+:c:func:`open()`, :c:func:`close()`,
+:c:func:`ioctl()`, :c:func:`mmap()` and
+:c:func:`munmap()`
operations and redirects them to the libv4l counterparts, by using
``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2
API.
diff --git a/Documentation/userspace-api/media/v4l/mmap.rst b/Documentation/userspace-api/media/v4l/mmap.rst
index 1cce31c6de79..16b1e13b029f 100644
--- a/Documentation/userspace-api/media/v4l/mmap.rst
+++ b/Documentation/userspace-api/media/v4l/mmap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _mmap:
@@ -35,22 +36,22 @@ This ioctl can also be used to change the number of buffers or to free
the allocated memory, provided none of the buffers are still mapped.
Before applications can access the buffers they must map them into their
-address space with the :ref:`mmap() <func-mmap>` function. The
+address space with the :c:func:`mmap()` function. The
location of the buffers in device memory can be determined with the
:ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar
API case, the ``m.offset`` and ``length`` returned in a struct
:c:type:`v4l2_buffer` are passed as sixth and second
-parameter to the :ref:`mmap() <func-mmap>` function. When using the
+parameter to the :c:func:`mmap()` function. When using the
multi-planar API, struct :c:type:`v4l2_buffer` contains an
array of struct :c:type:`v4l2_plane` structures, each
containing its own ``m.offset`` and ``length``. When using the
multi-planar API, every plane of every buffer has to be mapped
-separately, so the number of calls to :ref:`mmap() <func-mmap>` should
+separately, so the number of calls to :c:func:`mmap()` should
be equal to number of buffers times number of planes in each buffer. The
offset and length values must not be modified. Remember, the buffers are
allocated in physical memory, as opposed to virtual memory, which can be
swapped out to disk. Applications should free the buffers as soon as
-possible with the :ref:`munmap() <func-munmap>` function.
+possible with the :c:func:`munmap()` function.
Example: Mapping buffers in the single-planar API
=================================================
@@ -122,7 +123,6 @@ Example: Mapping buffers in the single-planar API
for (i = 0; i < reqbuf.count; i++)
munmap(buffers[i].start, buffers[i].length);
-
Example: Mapping buffers in the multi-planar API
================================================
@@ -238,10 +238,10 @@ be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two
methods exist to suspend execution of the application until one or more
buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK``
-flag was given to the :ref:`open() <func-open>` function,
+flag was given to the :c:func:`open()` function,
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
-error code when no buffer is available. The :ref:`select() <func-select>`
-or :ref:`poll() <func-poll>` functions are always available.
+error code when no buffer is available. The :c:func:`select()`
+or :c:func:`poll()` functions are always available.
To start and stop capturing or output applications call the
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
@@ -259,15 +259,15 @@ Drivers implementing memory mapping I/O must support the
<VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
<VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
-<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select()
-<func-select>` and :ref:`poll() <func-poll>` function. [#f3]_
+<func-mmap>`, :c:func:`munmap()`, :ref:`select()
+<func-select>` and :c:func:`poll()` function. [#f3]_
[capture example]
.. [#f1]
One could use one file descriptor and set the buffer type field
accordingly when calling :ref:`VIDIOC_QBUF` etc.,
- but it makes the :ref:`select() <func-select>` function ambiguous. We also
+ but it makes the :c:func:`select()` function ambiguous. We also
like the clean approach of one file descriptor per logical stream.
Video overlay for example is also a logical stream, although the CPU
is not needed for continuous operation.
@@ -280,6 +280,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
scatter-gather lists and the like.
.. [#f3]
- At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
- the same, and :ref:`select() <func-select>` is too important to be optional.
+ At the driver level :c:func:`select()` and :c:func:`poll()` are
+ the same, and :c:func:`select()` is too important to be optional.
The rest should be evident.
diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
index 4e8fd216a1b0..18bfb9b8137d 100644
--- a/Documentation/userspace-api/media/v4l/open.rst
+++ b/Documentation/userspace-api/media/v4l/open.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _open:
@@ -140,7 +141,6 @@ means applications cannot *reliably* scan for loaded or installed
drivers. The user must enter a device name, or the application can try
the conventional device names.
-
.. _related:
Related Devices
@@ -157,7 +157,7 @@ support all functions. However, in practice this never worked: this
support it and if they did it was certainly never tested. In addition,
switching a device node between different functions only works when
using the streaming I/O API, not with the
-:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
+:c:func:`read()`/\ :c:func:`write()` API.
Today each V4L2 device node supports just one function.
@@ -178,7 +178,6 @@ the Media Controller. If you want to work on this please write to the
linux-media mailing list:
`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
-
Multiple Opens
==============
@@ -192,8 +191,8 @@ device should not change the state of the device. [#f2]_
Once an application has allocated the memory buffers needed for
streaming data (by calling the :ref:`VIDIOC_REQBUFS`
or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
-implicitly by calling the :ref:`read() <func-read>` or
-:ref:`write() <func-write>` functions) that application (filehandle)
+implicitly by calling the :c:func:`read()` or
+:c:func:`write()` functions) that application (filehandle)
becomes the owner of the device. It is no longer allowed to make changes
that would affect the buffer sizes (e.g. by calling the
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
@@ -206,7 +205,6 @@ requested type of data, and to change related properties, to this file
descriptor. Applications can request additional access privileges using
the priority mechanism described in :ref:`app-pri`.
-
Shared Data Streams
===================
@@ -215,12 +213,11 @@ the same data stream on a device by copying buffers, time multiplexing
or similar means. This is better handled by a proxy application in user
space.
-
Functions
=========
To open and close V4L2 devices applications use the
-:ref:`open() <func-open>` and :ref:`close() <func-close>` function,
+:c:func:`open()` and :c:func:`close()` function,
respectively. Devices are programmed using the
:ref:`ioctl() <func-ioctl>` function as explained in the following
sections.
@@ -228,7 +225,7 @@ sections.
.. [#f1]
There are still some old and obscure drivers that have not been
updated to allow for multiple opens. This implies that for such
- drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code
+ drivers :c:func:`open()` can return an ``EBUSY`` error code
when the device is already in use.
.. [#f2]
diff --git a/Documentation/userspace-api/media/v4l/rw.rst b/Documentation/userspace-api/media/v4l/rw.rst
index 43609a27c3ec..64b85fb2a328 100644
--- a/Documentation/userspace-api/media/v4l/rw.rst
+++ b/Documentation/userspace-api/media/v4l/rw.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _rw:
@@ -6,8 +7,8 @@
Read/Write
**********
-Input and output devices support the :ref:`read() <func-read>` and
-:ref:`write() <func-write>` function, respectively, when the
+Input and output devices support the :c:func:`read()` and
+:c:func:`write()` function, respectively, when the
``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl is set.
@@ -22,18 +23,17 @@ However this is also the simplest I/O method, requiring little or no
setup to exchange data. It permits command line stunts like this (the
vidctrl tool is fictitious):
-
.. code-block:: none
$ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
$ dd if=/dev/video of=myimage.422 bs=202752 count=1
-To read from the device applications use the :ref:`read() <func-read>`
-function, to write the :ref:`write() <func-write>` function. Drivers
+To read from the device applications use the :c:func:`read()`
+function, to write the :c:func:`write()` function. Drivers
must implement one I/O method if they exchange data with applications,
but it need not be this. [#f1]_ When reading or writing is supported, the
-driver must also support the :ref:`select() <func-select>` and
-:ref:`poll() <func-poll>` function. [#f2]_
+driver must also support the :c:func:`select()` and
+:c:func:`poll()` function. [#f2]_
.. [#f1]
It would be desirable if applications could depend on drivers
@@ -43,5 +43,5 @@ driver must also support the :ref:`select() <func-select>` and
capturing still images.
.. [#f2]
- At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
- the same, and :ref:`select() <func-select>` is too important to be optional.
+ At the driver level :c:func:`select()` and :c:func:`poll()` are
+ the same, and :c:func:`select()` is too important to be optional.
diff --git a/Documentation/userspace-api/media/v4l/streaming-par.rst b/Documentation/userspace-api/media/v4l/streaming-par.rst
index cc2e8fcecc7e..806cbfdad0f1 100644
--- a/Documentation/userspace-api/media/v4l/streaming-par.rst
+++ b/Documentation/userspace-api/media/v4l/streaming-par.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _streaming-par:
@@ -14,13 +15,13 @@ The current video standard determines a nominal number of frames per
second. If less than this number of frames is to be captured or output,
applications can request frame skipping or duplicating on the driver
side. This is especially useful when using the
-:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are
+:c:func:`read()` or :c:func:`write()`, which are
not augmented by timestamps or sequence counters, and to avoid
unnecessary data copying.
Finally these ioctls can be used to determine the number of buffers used
internally by a driver in read/write mode. For implications see the
-section discussing the :ref:`read() <func-read>` function.
+section discussing the :c:func:`read()` function.
To get and set the streaming parameters applications call the
:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
diff --git a/Documentation/userspace-api/media/v4l/userp.rst b/Documentation/userspace-api/media/v4l/userp.rst
index 5b7321907dab..db224f9b611e 100644
--- a/Documentation/userspace-api/media/v4l/userp.rst
+++ b/Documentation/userspace-api/media/v4l/userp.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _userp:
@@ -78,10 +79,10 @@ buffers it must wait until an empty buffer can be dequeued and reused.
Two methods exist to suspend execution of the application until one or
more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
-``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
+``O_NONBLOCK`` flag was given to the :c:func:`open()` function,
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
error code when no buffer is available. The :ref:`select()
-<func-select>` or :ref:`poll() <func-poll>` function are always
+<func-select>` or :c:func:`poll()` function are always
available.
To start and stop capturing or output applications call the
@@ -101,7 +102,7 @@ Drivers implementing user pointer I/O must support the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [#f2]_
+:c:func:`select()` and :c:func:`poll()` function. [#f2]_
.. [#f1]
We expect that frequently used buffers are typically not swapped out.
@@ -116,6 +117,6 @@ and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
because an application may share them with other processes.
.. [#f2]
- At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
- the same, and :ref:`select() <func-select>` is too important to be optional.
+ At the driver level :c:func:`select()` and :c:func:`poll()` are
+ the same, and :c:func:`select()` is too important to be optional.
The rest should be evident.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
index d999028f47df..b06e5b528e11 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_CREATE_BUFS:
@@ -11,24 +12,22 @@ Name
VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp )
- :name: VIDIOC_CREATE_BUFS
+.. c:macro:: VIDIOC_CREATE_BUFS
+``int ioctl(int fd, VIDIOC_CREATE_BUFS, struct v4l2_create_buffers *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_create_buffers`.
-
Description
===========
@@ -71,7 +70,6 @@ the actual number allocated and the starting index in the ``count`` and
the ``index`` fields respectively. On return ``count`` can be smaller
than the number requested.
-
.. c:type:: v4l2_create_buffers
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -119,7 +117,6 @@ than the number requested.
- A place holder for future extensions. Drivers and applications
must set the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst
index aa02c312824e..00c31410d4e4 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_CROPCAP:
@@ -11,24 +12,22 @@ Name
VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp )
- :name: VIDIOC_CROPCAP
+.. c:macro:: VIDIOC_CROPCAP
+``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_cropcap`.
-
Description
===========
@@ -95,7 +94,6 @@ overlay devices.
Starting with kernel 4.13 both variations are allowed.
-
.. _v4l2-rect-crop:
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -120,7 +118,6 @@ overlay devices.
- ``height``
- Height of the rectangle, in pixels.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst
index a2541329b30a..bde6e952b267 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_DBG_G_CHIP_INFO:
@@ -11,24 +12,22 @@ Name
VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp )
- :name: VIDIOC_DBG_G_CHIP_INFO
+.. c:macro:: VIDIOC_DBG_G_CHIP_INFO
+``int ioctl(int fd, VIDIOC_DBG_G_CHIP_INFO, struct v4l2_dbg_chip_info *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_dbg_chip_info`.
-
Description
===========
@@ -76,7 +75,6 @@ is available from the LinuxTV v4l-dvb repository; see
`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
instructions.
-
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
.. _name-v4l2-dbg-match:
@@ -103,7 +101,6 @@ instructions.
-
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_dbg_chip_info
@@ -130,7 +127,6 @@ instructions.
- Reserved fields, both application and driver must set these to 0.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _name-chip-match-types:
@@ -148,7 +144,6 @@ instructions.
- 4
- Match the nth sub-device.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst
index 350a04eb0e86..e1a6abe705bd 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_DBG_G_REGISTER:
@@ -11,27 +12,26 @@ Name
VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp )
- :name: VIDIOC_DBG_G_REGISTER
+.. c:macro:: VIDIOC_DBG_G_REGISTER
-.. c:function:: int ioctl( int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp )
- :name: VIDIOC_DBG_S_REGISTER
+``int ioctl(int fd, VIDIOC_DBG_G_REGISTER, struct v4l2_dbg_register *argp)``
+.. c:macro:: VIDIOC_DBG_S_REGISTER
+
+``int ioctl(int fd, VIDIOC_DBG_S_REGISTER, const struct v4l2_dbg_register *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_dbg_register`.
-
Description
===========
@@ -85,7 +85,6 @@ It is available from the LinuxTV v4l-dvb repository; see
`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
instructions.
-
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
.. c:type:: v4l2_dbg_match
@@ -112,7 +111,6 @@ instructions.
-
-
.. c:type:: v4l2_dbg_register
.. flat-table:: struct v4l2_dbg_register
@@ -133,7 +131,6 @@ instructions.
- The value read from, or to be written into the register.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _chip-match-types:
@@ -151,7 +148,6 @@ instructions.
- 4
- Match the nth sub-device.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst
index 0ef757f061e3..fd71ceece037 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_DECODER_CMD:
@@ -11,28 +12,26 @@ Name
VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp )
- :name: VIDIOC_DECODER_CMD
+.. c:macro:: VIDIOC_DECODER_CMD
+``int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp )
- :name: VIDIOC_TRY_DECODER_CMD
+.. c:macro:: VIDIOC_TRY_DECODER_CMD
+``int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
pointer to struct :c:type:`v4l2_decoder_cmd`.
-
Description
===========
@@ -47,11 +46,11 @@ this structure.
The ``cmd`` field must contain the command code. Some commands use the
``flags`` field for additional information.
-A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`
+A :c:func:`write()` or :ref:`VIDIOC_STREAMON`
call sends an implicit START command to the decoder if it has not been
started yet. Applies to both queues of mem2mem decoders.
-A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
call of a streaming file descriptor sends an implicit immediate STOP
command to the decoder, and all buffered data is discarded. Applies to both
queues of mem2mem decoders.
@@ -60,7 +59,6 @@ In principle, these ioctls are optional, not all drivers may support them. They
introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders
(as further documented in :ref:`decoder`).
-
.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}|
.. c:type:: v4l2_decoder_cmd
@@ -131,7 +129,6 @@ introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decod
-
-
.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}|
.. _decoder-cmds:
diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
index f0dfc8cf9b14..634af717c8ba 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_DQEVENT:
@@ -11,24 +12,22 @@ Name
VIDIOC_DQEVENT - Dequeue event
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp )
- :name: VIDIOC_DQEVENT
+.. c:macro:: VIDIOC_DQEVENT
+``int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_event`.
-
Description
===========
@@ -38,7 +37,6 @@ structure are filled by the driver. The file handle will also receive
exceptions which the application may get by e.g. using the select system
call.
-
.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}|
.. c:type:: v4l2_event
@@ -100,7 +98,6 @@ call.
zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. cssclass:: longtable
@@ -191,7 +188,6 @@ call.
- Base event number for driver-private events.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_event_vsync
@@ -206,7 +202,6 @@ call.
- The upcoming field. See enum :c:type:`v4l2_field`.
-
.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}|
.. c:type:: v4l2_event_ctrl
@@ -257,7 +252,6 @@ call.
:ref:`v4l2_queryctrl <v4l2-queryctrl>`.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_event_frame_sync
@@ -272,7 +266,6 @@ call.
- The sequence number of the frame being received.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_event_src_change
@@ -288,7 +281,6 @@ call.
:ref:`src-changes-flags`.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_event_motion_det
@@ -318,7 +310,6 @@ call.
automatically assigned to the default region 0.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _ctrl-changes-flags:
@@ -344,7 +335,6 @@ call.
step or the default value of the control changed.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _src-changes-flags:
@@ -375,7 +365,6 @@ call.
loss of signal and so restarting streaming I/O is required in order for
the hardware to synchronize to the video signal.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst
index 82bb732893be..27bd6a83e42c 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_DV_TIMINGS_CAP:
@@ -11,27 +12,26 @@ Name
VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp )
- :name: VIDIOC_DV_TIMINGS_CAP
+.. c:macro:: VIDIOC_DV_TIMINGS_CAP
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp )
- :name: VIDIOC_SUBDEV_DV_TIMINGS_CAP
+``int ioctl(int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)``
+.. c:macro:: VIDIOC_SUBDEV_DV_TIMINGS_CAP
+
+``int ioctl(int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_dv_timings_cap`.
-
Description
===========
@@ -55,7 +55,6 @@ the desired pad number in the struct
zero the ``reserved`` array. Attempts to query capabilities on a pad
that doesn't support them will return an ``EINVAL`` error code.
-
.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}|
.. c:type:: v4l2_bt_timings_cap
@@ -97,7 +96,6 @@ that doesn't support them will return an ``EINVAL`` error code.
Drivers must set the array to zero.
-
.. tabularcolumns:: |p{1.0cm}|p{4.0cm}|p{3.5cm}|p{9.2cm}|
.. c:type:: v4l2_dv_timings_cap
@@ -153,7 +151,6 @@ that doesn't support them will return an ``EINVAL`` error code.
- Can support non-standard timings, i.e. timings not belonging to
the standards set in the ``standards`` field.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
index 44aad55d9459..5673606711b4 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENCODER_CMD:
@@ -11,22 +12,22 @@ Name
VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp )
- :name: VIDIOC_ENCODER_CMD
+.. c:macro:: VIDIOC_ENCODER_CMD
-.. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp )
- :name: VIDIOC_TRY_ENCODER_CMD
+``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
+.. c:macro:: VIDIOC_TRY_ENCODER_CMD
+
+``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_encoder_cmd`.
@@ -47,16 +48,16 @@ this structure.
The ``cmd`` field must contain the command code. Some commands use the
``flags`` field for additional information.
-After a STOP command, :ref:`read() <func-read>` calls will read
+After a STOP command, :c:func:`read()` calls will read
the remaining data buffered by the driver. When the buffer is empty,
-:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
+:c:func:`read()` will return zero and the next :c:func:`read()`
call will restart the encoder.
-A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
call sends an implicit START command to the encoder if it has not been
started yet. Applies to both queues of mem2mem encoders.
-A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
call of a streaming file descriptor sends an implicit immediate STOP to
the encoder, and all buffered data is discarded. Applies to both queues of
mem2mem encoders.
@@ -65,7 +66,6 @@ These ioctls are optional, not all drivers may support them. They were
introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
encoders (as further documented in :ref:`encoder`).
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_encoder_cmd
@@ -89,7 +89,6 @@ encoders (as further documented in :ref:`encoder`).
the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _encoder-cmds:
@@ -134,7 +133,6 @@ encoders (as further documented in :ref:`encoder`).
the encoder is already running, this command does nothing. No
flags are defined for this command.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _encoder-flags:
@@ -151,7 +149,6 @@ encoders (as further documented in :ref:`encoder`).
Does not apply to :ref:`encoder`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst
index bb74096cfbd8..20730cd4f6ef 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUM_DV_TIMINGS:
@@ -11,27 +12,26 @@ Name
VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp )
- :name: VIDIOC_ENUM_DV_TIMINGS
+.. c:macro:: VIDIOC_ENUM_DV_TIMINGS
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp )
- :name: VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+``int ioctl(int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)``
+.. c:macro:: VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+
+``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_enum_dv_timings`.
-
Description
===========
@@ -65,7 +65,6 @@ pad number in the struct
Attempts to enumerate timings on a pad that doesn't support them will
return an ``EINVAL`` error code.
-
.. c:type:: v4l2_enum_dv_timings
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -91,7 +90,6 @@ return an ``EINVAL`` error code.
- ``timings``
- The timings.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
index b8347a96a554..2b3fa9c23146 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUM_FMT:
@@ -11,24 +12,22 @@ Name
VIDIOC_ENUM_FMT - Enumerate image formats
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp )
- :name: VIDIOC_ENUM_FMT
+.. c:macro:: VIDIOC_ENUM_FMT
+``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_fmtdesc`.
-
Description
===========
@@ -72,7 +71,6 @@ the ``mbus_code`` field is handled differently:
formats shall not depend on the active configuration of the video device
or device pipeline.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_fmtdesc
@@ -137,7 +135,6 @@ the ``mbus_code`` field is handled differently:
zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _fmtdesc-flags:
@@ -227,7 +224,6 @@ the ``mbus_code`` field is handled differently:
device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst
index 68469756e6c7..1f0949726045 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUM_FRAMEINTERVALS:
@@ -11,25 +12,23 @@ Name
VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp )
- :name: VIDIOC_ENUM_FRAMEINTERVALS
+.. c:macro:: VIDIOC_ENUM_FRAMEINTERVALS
+``int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_frmivalenum`
that contains a pixel format and size and receives a frame interval.
-
Description
===========
@@ -91,7 +90,6 @@ other ioctl calls while it runs the frame interval enumeration.
frame_rate = 1 / frame_interval
-
Structs
=======
@@ -99,7 +97,6 @@ In the structs below, *IN* denotes a value that has to be filled in by
the application, *OUT* denotes values that the driver fills in. The
application should zero out all members except for the *IN* fields.
-
.. c:type:: v4l2_frmival_stepwise
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -120,7 +117,6 @@ application should zero out all members except for the *IN* fields.
- Frame interval step size [s].
-
.. c:type:: v4l2_frmivalenum
.. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}|
@@ -163,11 +159,9 @@ application should zero out all members except for the *IN* fields.
applications.
-
Enums
=====
-
.. c:type:: v4l2_frmivaltypes
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
@@ -187,7 +181,6 @@ Enums
- 3
- Step-wise defined frame interval.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst
index dc4e0e216e7e..c9a36bcf699f 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUM_FRAMESIZES:
@@ -11,26 +12,24 @@ Name
VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp )
- :name: VIDIOC_ENUM_FRAMESIZES
+.. c:macro:: VIDIOC_ENUM_FRAMESIZES
+``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_frmsizeenum`
that contains an index and pixel format and receives a frame width
and height.
-
Description
===========
@@ -81,7 +80,6 @@ without any interaction from the application itself. This means that the
enumeration data is consistent if the application does not perform any
other ioctl calls while it runs the frame size enumeration.
-
Structs
=======
@@ -89,7 +87,6 @@ In the structs below, *IN* denotes a value that has to be filled in by
the application, *OUT* denotes values that the driver fills in. The
application should zero out all members except for the *IN* fields.
-
.. c:type:: v4l2_frmsize_discrete
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -107,7 +104,6 @@ application should zero out all members except for the *IN* fields.
- Height of the frame [pixel].
-
.. c:type:: v4l2_frmsize_stepwise
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -137,7 +133,6 @@ application should zero out all members except for the *IN* fields.
- Frame height step size [pixel].
-
.. c:type:: v4l2_frmsizeenum
.. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}|
@@ -173,11 +168,9 @@ application should zero out all members except for the *IN* fields.
applications.
-
Enums
=====
-
.. c:type:: v4l2_frmsizetypes
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
@@ -197,7 +190,6 @@ Enums
- 3
- Step-wise defined frame size.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst
index 2dabf542b20f..a0764fca8d18 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUM_FREQ_BANDS:
@@ -11,24 +12,22 @@ Name
VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp )
- :name: VIDIOC_ENUM_FREQ_BANDS
+.. c:macro:: VIDIOC_ENUM_FREQ_BANDS
+``int ioctl(int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_frequency_band`.
-
Description
===========
@@ -41,7 +40,6 @@ fields, and zero out the ``reserved`` array of a struct
This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
of the corresponding tuner/modulator is set.
-
.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
.. c:type:: v4l2_frequency_band
@@ -110,7 +108,6 @@ of the corresponding tuner/modulator is set.
Applications and drivers must set the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _band-modulation:
@@ -130,7 +127,6 @@ of the corresponding tuner/modulator is set.
- 0x08
- Amplitude Modulation, commonly used for analog radio.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst
index 6cf06ac0bb70..7873e5434d3e 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUMAUDIO:
@@ -11,24 +12,22 @@ Name
VIDIOC_ENUMAUDIO - Enumerate audio inputs
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp )
- :name: VIDIOC_ENUMAUDIO
+.. c:macro:: VIDIOC_ENUMAUDIO
+``int ioctl(int fd, VIDIOC_ENUMAUDIO, struct v4l2_audio *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_audio`.
-
Description
===========
@@ -43,7 +42,6 @@ zero, incrementing by one until the driver returns ``EINVAL``.
See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct
:c:type:`v4l2_audio`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst
index b4a42ea397db..d4c3ba320834 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUMAUDOUT:
@@ -11,24 +12,22 @@ Name
VIDIOC_ENUMAUDOUT - Enumerate audio outputs
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp )
- :name: VIDIOC_ENUMAUDOUT
+.. c:macro:: VIDIOC_ENUMAUDOUT
+``int ioctl(int fd, VIDIOC_ENUMAUDOUT, struct v4l2_audioout *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_audioout`.
-
Description
===========
@@ -48,7 +47,6 @@ zero, incrementing by one until the driver returns ``EINVAL``.
See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct
:c:type:`v4l2_audioout`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst
index 714688f81e23..0f62e681a827 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUMINPUT:
@@ -11,24 +12,22 @@ Name
VIDIOC_ENUMINPUT - Enumerate video inputs
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp )
- :name: VIDIOC_ENUMINPUT
+.. c:macro:: VIDIOC_ENUMINPUT
+``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_input`.
-
Description
===========
@@ -39,7 +38,6 @@ fill the rest of the structure or return an ``EINVAL`` error code when the
index is out of bounds. To enumerate all inputs applications shall begin
at index zero, incrementing by one until the driver returns ``EINVAL``.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_input
@@ -103,7 +101,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _input-type:
@@ -126,7 +123,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
- This input is a touch device for capturing raw touch data.
-
.. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}|
.. _input-status:
@@ -198,7 +194,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
- VTR time constant. [?]
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _input-capabilities:
@@ -222,7 +217,6 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
:ref:`v4l2-selections-common`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst
index 272a0b2b475c..91fcf99094d2 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUMOUTPUT:
@@ -11,24 +12,22 @@ Name
VIDIOC_ENUMOUTPUT - Enumerate video outputs
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp )
- :name: VIDIOC_ENUMOUTPUT
+.. c:macro:: VIDIOC_ENUMOUTPUT
+``int ioctl(int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_output`.
-
Description
===========
@@ -40,7 +39,6 @@ when the index is out of bounds. To enumerate all outputs applications
shall begin at index zero, incrementing by one until the driver returns
``EINVAL``.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_output
@@ -98,7 +96,6 @@ shall begin at index zero, incrementing by one until the driver returns
zero.
-
.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}|
.. _output-type:
@@ -121,7 +118,6 @@ shall begin at index zero, incrementing by one until the driver returns
- The video output will be copied to a :ref:`video overlay <overlay>`.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _output-capabilities:
@@ -145,7 +141,6 @@ shall begin at index zero, incrementing by one until the driver returns
``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
:ref:`v4l2-selections-common`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst
index 85bc6d0231f1..b5704e8cf909 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_ENUMSTD:
@@ -11,27 +12,26 @@ Name
VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp )
- :name: VIDIOC_ENUMSTD
+.. c:macro:: VIDIOC_ENUMSTD
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp )
- :name: VIDIOC_SUBDEV_ENUMSTD
+``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)``
+.. c:macro:: VIDIOC_SUBDEV_ENUMSTD
+
+``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_standard`.
-
Description
===========
@@ -45,7 +45,6 @@ zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
enumerate a different set of standards after switching the video input
or output. [#f1]_
-
.. c:type:: v4l2_standard
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -85,7 +84,6 @@ or output. [#f1]_
zero.
-
.. c:type:: v4l2_fract
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -102,7 +100,6 @@ or output. [#f1]_
- ``denominator``
-
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. _v4l2-std-id:
@@ -120,7 +117,6 @@ or output. [#f1]_
standards.
-
.. code-block:: c
#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
@@ -142,7 +138,6 @@ rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
PAL video recorders can play back NTSC tapes in this mode for display on
a 50/60 Hz agnostic PAL TV.
-
.. code-block:: c
#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
@@ -152,7 +147,6 @@ a 50/60 Hz agnostic PAL TV.
``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
-
.. code-block:: c
#define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
@@ -175,7 +169,6 @@ terrestrial digital TV standards. Presently the V4L2 API does not
support digital TV. See also the Linux DVB API at
`https://linuxtv.org <https://linuxtv.org>`__.
-
.. code-block:: c
#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |
@@ -228,7 +221,6 @@ support digital TV. See also the Linux DVB API at
#define V4L2_STD_ALL (V4L2_STD_525_60 |
V4L2_STD_625_50)
-
.. raw:: latex
\begingroup
@@ -303,7 +295,6 @@ support digital TV. See also the Linux DVB API at
\endgroup
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst
index a2c475a83a58..212377c90442 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_EXPBUF:
@@ -11,24 +12,22 @@ Name
VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp )
- :name: VIDIOC_EXPBUF
+.. c:macro:: VIDIOC_EXPBUF
+``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_exportbuffer`.
-
Description
===========
@@ -63,11 +62,9 @@ for details about importing DMABUF files into V4L2 nodes. It is
recommended to close a DMABUF file when it is no longer used to allow
the associated memory to be reclaimed.
-
Examples
========
-
.. code-block:: c
int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
@@ -87,7 +84,6 @@ Examples
return 0;
}
-
.. code-block:: c
int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
@@ -114,7 +110,6 @@ Examples
return 0;
}
-
.. c:type:: v4l2_exportbuffer
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -155,7 +150,6 @@ Examples
- Reserved field for future use. Drivers and applications must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst
index 38667864355a..4c93bd55bd97 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_AUDIO:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp )
- :name: VIDIOC_G_AUDIO
+.. c:macro:: VIDIOC_G_AUDIO
-.. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp )
- :name: VIDIOC_S_AUDIO
+``int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)``
+.. c:macro:: VIDIOC_S_AUDIO
+
+``int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_audio`.
-
Description
===========
@@ -49,7 +49,6 @@ ioctl. Drivers may switch to a different audio mode if the request
cannot be satisfied. However, this is a write-only ioctl, it does not
return the actual new audio mode.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_audio
@@ -80,7 +79,6 @@ return the actual new audio mode.
the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _audio-capability:
@@ -101,7 +99,6 @@ return the actual new audio mode.
- Automatic Volume Level mode is supported.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _audio-mode:
@@ -115,7 +112,6 @@ return the actual new audio mode.
- 0x00001
- AVL mode is on.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst
index 5bf56723c7ba..194f22493517 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_AUDOUT:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp )
- :name: VIDIOC_G_AUDOUT
+.. c:macro:: VIDIOC_G_AUDOUT
-.. c:function:: int ioctl( int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp )
- :name: VIDIOC_S_AUDOUT
+``int ioctl(int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp)``
+.. c:macro:: VIDIOC_S_AUDOUT
+
+``int ioctl(int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_audioout`.
-
Description
===========
@@ -56,7 +56,6 @@ as ``VIDIOC_G_AUDOUT`` does.
Connectors on a TV card to loop back the received audio signal
to a sound card are not audio outputs in this sense.
-
.. c:type:: v4l2_audioout
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -87,7 +86,6 @@ as ``VIDIOC_G_AUDOUT`` does.
- Reserved for future extensions. Drivers and applications must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst
index 735a6bf5e025..0ac1509e41cc 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_CROP:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_CROP, struct v4l2_crop *argp )
- :name: VIDIOC_G_CROP
+.. c:macro:: VIDIOC_G_CROP
-.. c:function:: int ioctl( int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp )
- :name: VIDIOC_S_CROP
+``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)``
+.. c:macro:: VIDIOC_S_CROP
+
+``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_crop`.
-
Description
===========
@@ -69,7 +69,6 @@ been negotiated.
When cropping is not supported then no parameters are changed and
:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
-
.. c:type:: v4l2_crop
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -100,7 +99,6 @@ When cropping is not supported then no parameters are changed and
Starting with kernel 4.13 both variations are allowed.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst
index d863c849be95..4f1bed53fad5 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_CTRL:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp )
- :name: VIDIOC_G_CTRL
+.. c:macro:: VIDIOC_G_CTRL
-.. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp )
- :name: VIDIOC_S_CTRL
+``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``
+.. c:macro:: VIDIOC_S_CTRL
+
+``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_control`.
-
Description
===========
@@ -55,7 +55,6 @@ These ioctls work only with user controls. For other control classes the
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
-
.. c:type:: v4l2_control
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -72,7 +71,6 @@ These ioctls work only with user controls. For other control classes the
- ``value``
- New value or current value.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst
index e5a58db574d4..760a33d43b7d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_DV_TIMINGS:
@@ -11,33 +12,34 @@ Name
VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp )
- :name: VIDIOC_G_DV_TIMINGS
+.. c:macro:: VIDIOC_G_DV_TIMINGS
-.. c:function:: int ioctl( int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp )
- :name: VIDIOC_S_DV_TIMINGS
+``int ioctl(int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp )
- :name: VIDIOC_SUBDEV_G_DV_TIMINGS
+.. c:macro:: VIDIOC_S_DV_TIMINGS
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp )
- :name: VIDIOC_SUBDEV_S_DV_TIMINGS
+``int ioctl(int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp)``
+.. c:macro:: VIDIOC_SUBDEV_G_DV_TIMINGS
+
+``int ioctl(int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp)``
+
+.. c:macro:: VIDIOC_SUBDEV_S_DV_TIMINGS
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_dv_timings`.
-
Description
===========
@@ -60,7 +62,6 @@ the current input or output does not support DV timings (e.g. if
:ref:`VIDIOC_ENUMINPUT` does not set the
``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
-
Return Value
============
@@ -170,7 +171,6 @@ EPERM
- Reserved for future extensions. Drivers and applications must set
the array to zero.
-
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
.. c:type:: v4l2_dv_timings
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst
index 6a9ed2915cb9..39d523a449a7 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_EDID:
@@ -11,34 +12,34 @@ Name
VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_EDID, struct v4l2_edid *argp )
- :name: VIDIOC_G_EDID
+.. c:macro:: VIDIOC_G_EDID
-.. c:function:: int ioctl( int fd, VIDIOC_S_EDID, struct v4l2_edid *argp )
- :name: VIDIOC_S_EDID
+``int ioctl(int fd, VIDIOC_G_EDID, struct v4l2_edid *argp)``
+.. c:macro:: VIDIOC_S_EDID
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp )
- :name: VIDIOC_SUBDEV_G_EDID
+``int ioctl(int fd, VIDIOC_S_EDID, struct v4l2_edid *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp )
- :name: VIDIOC_SUBDEV_S_EDID
+.. c:macro:: VIDIOC_SUBDEV_G_EDID
+``int ioctl(int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp)``
+
+.. c:macro:: VIDIOC_SUBDEV_S_EDID
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_edid`.
-
Description
===========
@@ -97,7 +98,6 @@ this will drive the hotplug pin low and/or block the source from reading
the EDID data in some way. In any case, the end result is the same: the
EDID is no longer available.
-
.. c:type:: v4l2_edid
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -132,7 +132,6 @@ EDID is no longer available.
- Pointer to memory that contains the EDID. The minimum size is
``blocks`` * 128.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst
index 99cddf3b9888..7698e65ccccf 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_ENC_INDEX:
@@ -11,24 +12,22 @@ Name
VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp )
- :name: VIDIOC_G_ENC_INDEX
+.. c:macro:: VIDIOC_G_ENC_INDEX
+``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_enc_idx`.
-
Description
===========
@@ -55,7 +54,6 @@ will be zero.
Currently this ioctl is only defined for MPEG-2 program streams and
video elementary streams.
-
.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}|
.. c:type:: v4l2_enc_idx
@@ -83,7 +81,6 @@ video elementary streams.
their ``offset``.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_enc_idx_entry
@@ -116,7 +113,6 @@ video elementary streams.
- Reserved for future extensions. Drivers must set the array to
zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _enc-idx-flags:
@@ -140,7 +136,6 @@ video elementary streams.
- *AND* the flags field with this mask to obtain the picture coding
type.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
index 0991af626591..f2173e310d67 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_EXT_CTRLS:
@@ -11,32 +12,30 @@ Name
VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp )
- :name: VIDIOC_G_EXT_CTRLS
+.. c:macro:: VIDIOC_G_EXT_CTRLS
+``int ioctl(int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp )
- :name: VIDIOC_S_EXT_CTRLS
+.. c:macro:: VIDIOC_S_EXT_CTRLS
+``int ioctl(int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp )
- :name: VIDIOC_TRY_EXT_CTRLS
+.. c:macro:: VIDIOC_TRY_EXT_CTRLS
+``int ioctl(int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_ext_controls`.
-
Description
===========
@@ -119,7 +118,6 @@ correct. This prevents the situation where only some of the controls
were set/get. Only low-level errors (e. g. a failed i2c command) can
still cause this situation.
-
.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}|
.. c:type:: v4l2_ext_control
@@ -195,7 +193,6 @@ still cause this situation.
* - }
-
-
.. tabularcolumns:: |p{4.0cm}|p{2.2cm}|p{2.1cm}|p{8.2cm}|
.. c:type:: v4l2_ext_controls
@@ -309,7 +306,6 @@ still cause this situation.
Ignored if ``count`` equals zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _ctrl-class:
@@ -363,7 +359,6 @@ still cause this situation.
- The class containing RF tuner controls. These controls are
described in :ref:`rf-tuner-controls`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst
index 7e1a0b812754..dc1f16343b22 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_FBUF:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
- :name: VIDIOC_G_FBUF
+.. c:macro:: VIDIOC_G_FBUF
-.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp )
- :name: VIDIOC_S_FBUF
+``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)``
+.. c:macro:: VIDIOC_S_FBUF
+
+``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_framebuffer`.
-
Description
===========
@@ -75,7 +75,6 @@ jeopardize the system security, its stability or even damage the
hardware, therefore only the superuser can set the parameters for a
destructive video overlay.
-
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
.. c:type:: v4l2_framebuffer
@@ -208,7 +207,6 @@ destructive video overlay.
- ``priv``
- Reserved. Drivers and applications must set this field to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _framebuffer-cap:
@@ -257,7 +255,6 @@ destructive video overlay.
chroma-key colors are replaced by framebuffer pixels, which is
exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _framebuffer-flags:
@@ -332,7 +329,6 @@ destructive video overlay.
other, so same ``chromakey`` field of struct
:c:type:`v4l2_window` is being used.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst
index 7d113451bfbc..7e9f8475ea63 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_FMT:
@@ -11,29 +12,30 @@ Name
VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_FMT, struct v4l2_format *argp )
- :name: VIDIOC_G_FMT
+.. c:macro:: VIDIOC_G_FMT
-.. c:function:: int ioctl( int fd, VIDIOC_S_FMT, struct v4l2_format *argp )
- :name: VIDIOC_S_FMT
+``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp )
- :name: VIDIOC_TRY_FMT
+.. c:macro:: VIDIOC_S_FMT
+
+``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)``
+
+.. c:macro:: VIDIOC_TRY_FMT
+
+``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_format`.
-
Description
===========
@@ -85,7 +87,6 @@ recommended drivers are not required to implement this ioctl.
The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
-
.. c:type:: v4l2_format
.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}|
@@ -135,7 +136,6 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical
* - }
-
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst
index da0d5dee72ff..5445a4a442e4 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_FREQUENCY:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp )
- :name: VIDIOC_G_FREQUENCY
+.. c:macro:: VIDIOC_G_FREQUENCY
-.. c:function:: int ioctl( int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp )
- :name: VIDIOC_S_FREQUENCY
+``int ioctl(int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp)``
+.. c:macro:: VIDIOC_S_FREQUENCY
+
+``int ioctl(int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_frequency`.
-
Description
===========
@@ -51,7 +51,6 @@ structure. When the requested frequency is not possible the driver
assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
write-only ioctl, it does not return the actual new frequency.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_frequency
@@ -89,7 +88,6 @@ write-only ioctl, it does not return the actual new frequency.
- Reserved for future extensions. Drivers and applications must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst
index f4637bc464f6..eee9ce51c797 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-input.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-input.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_INPUT:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_INPUT, int *argp )
- :name: VIDIOC_G_INPUT
+.. c:macro:: VIDIOC_G_INPUT
-.. c:function:: int ioctl( int fd, VIDIOC_S_INPUT, int *argp )
- :name: VIDIOC_S_INPUT
+``int ioctl(int fd, VIDIOC_G_INPUT, int *argp)``
+.. c:macro:: VIDIOC_S_INPUT
+
+``int ioctl(int fd, VIDIOC_S_INPUT, int *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer an integer with input index.
-
Description
===========
@@ -52,7 +52,6 @@ other parameters.
Information about video inputs is available using the
:ref:`VIDIOC_ENUMINPUT` ioctl.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst
index 8721adc5ad70..93ed111dfcb9 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_JPEGCOMP:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp )
- :name: VIDIOC_G_JPEGCOMP
+.. c:macro:: VIDIOC_G_JPEGCOMP
-.. c:function:: int ioctl( int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp )
- :name: VIDIOC_S_JPEGCOMP
+``int ioctl(int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp)``
+.. c:macro:: VIDIOC_S_JPEGCOMP
+
+``int ioctl(int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_jpegcompression`.
-
Description
===========
@@ -54,7 +54,6 @@ stored in the JPEG-encoded fields. These define how the JPEG field is
encoded. If you omit them, applications assume you've used standard
encoding. You usually do want to add them.
-
.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}|
.. c:type:: v4l2_jpegcompression
@@ -92,7 +91,6 @@ encoding. You usually do want to add them.
control is exposed by a driver applications should use it instead
and ignore this field.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _jpeg-markers:
@@ -118,7 +116,6 @@ encoding. You usually do want to add them.
- (1<<7)
- App segment, driver will always use APP0
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst
index baf499d0df74..2ac2473e341b 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_MODULATOR:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp )
- :name: VIDIOC_G_MODULATOR
+.. c:macro:: VIDIOC_G_MODULATOR
-.. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp )
- :name: VIDIOC_S_MODULATOR
+``int ioctl(int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp)``
+.. c:macro:: VIDIOC_S_MODULATOR
+
+``int ioctl(int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_modulator`.
-
Description
===========
@@ -60,7 +60,6 @@ context.
To change the radio frequency the
:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
-
.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
.. c:type:: v4l2_modulator
@@ -121,7 +120,6 @@ To change the radio frequency the
Drivers and applications must set the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _modulator-txsubchans:
@@ -182,7 +180,6 @@ To change the radio frequency the
- 0x0010
- Enable the RDS encoder for a radio FM transmitter.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst
index 0afc55c67840..3138c4cc8fe3 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_OUTPUT:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_OUTPUT, int *argp )
- :name: VIDIOC_G_OUTPUT
+.. c:macro:: VIDIOC_G_OUTPUT
-.. c:function:: int ioctl( int fd, VIDIOC_S_OUTPUT, int *argp )
- :name: VIDIOC_S_OUTPUT
+``int ioctl(int fd, VIDIOC_G_OUTPUT, int *argp)``
+.. c:macro:: VIDIOC_S_OUTPUT
+
+``int ioctl(int fd, VIDIOC_S_OUTPUT, int *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer with output index.
-
Description
===========
@@ -53,7 +53,6 @@ negotiating any other parameters.
Information about video outputs is available using the
:ref:`VIDIOC_ENUMOUTPUT` ioctl.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
index 94f3af279bba..724f7fa7bae1 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_PARM:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp )
- :name: VIDIOC_G_PARM
+.. c:macro:: VIDIOC_G_PARM
-.. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp )
- :name: VIDIOC_S_PARM
+``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)``
+.. c:macro:: VIDIOC_S_PARM
+
+``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_streamparm`.
-
Description
===========
@@ -48,7 +48,7 @@ format, on the other hand, may change the frame interval.
Further these ioctls can be used to determine the number of buffers used
internally by a driver in read/write mode. For implications see the
-section discussing the :ref:`read() <func-read>` function.
+section discussing the :c:func:`read()` function.
To get and set the streaming parameters applications call the
:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
@@ -56,7 +56,6 @@ To get and set the streaming parameters applications call the
pointer to a struct :c:type:`v4l2_streamparm` which contains a
union holding separate parameters for input and output devices.
-
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
.. c:type:: v4l2_streamparm
@@ -89,7 +88,6 @@ union holding separate parameters for input and output devices.
-
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_captureparm
@@ -138,7 +136,7 @@ union holding separate parameters for input and output devices.
* - __u32
- ``readbuffers``
- Applications set this field to the desired number of buffers used
- internally by the driver in :ref:`read() <func-read>` mode.
+ internally by the driver in :c:func:`read()` mode.
Drivers return the actual number of buffers. When an application
requests zero buffers, drivers should just return the current
setting rather than the minimum or an error code. For details see
@@ -149,7 +147,6 @@ union holding separate parameters for input and output devices.
the array to zero.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_outputparm
@@ -172,7 +169,7 @@ union holding separate parameters for input and output devices.
* - :cspan:`2`
The field is intended to repeat frames on the driver side in
- :ref:`write() <func-write>` mode (in streaming mode timestamps
+ :c:func:`write()` mode (in streaming mode timestamps
can be used to throttle the output), saving I/O bandwidth.
For stateful encoders (see :ref:`encoder`) this represents the
@@ -199,7 +196,7 @@ union holding separate parameters for input and output devices.
* - __u32
- ``writebuffers``
- Applications set this field to the desired number of buffers used
- internally by the driver in :ref:`write() <func-write>` mode. Drivers
+ internally by the driver in :c:func:`write()` mode. Drivers
return the actual number of buffers. When an application requests
zero buffers, drivers should just return the current setting
rather than the minimum or an error code. For details see
@@ -210,7 +207,6 @@ union holding separate parameters for input and output devices.
the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _parm-caps:
@@ -226,7 +222,6 @@ union holding separate parameters for input and output devices.
field.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _parm-flags:
@@ -265,8 +260,7 @@ union holding separate parameters for input and output devices.
- Moving objects in the image might have excessive motion blur.
- - Capture might only work through the :ref:`read() <func-read>` call.
-
+ - Capture might only work through the :c:func:`read()` call.
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst
index da3166ac6d08..d72a0c716fca 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_PRIORITY:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp )
- :name: VIDIOC_G_PRIORITY
+.. c:macro:: VIDIOC_G_PRIORITY
-.. c:function:: int ioctl( int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp )
- :name: VIDIOC_S_PRIORITY
+``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)``
+.. c:macro:: VIDIOC_S_PRIORITY
+
+``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an enum :c:type:`v4l2_priority` type.
-
Description
===========
@@ -43,7 +43,6 @@ To request an access priority applications store the desired priority in
an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
with a pointer to this variable.
-
.. c:type:: v4l2_priority
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
@@ -78,7 +77,6 @@ with a pointer to this variable.
it blocks any other fd from changing device properties. Usually
applications which must not be interrupted, like video recording.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst
index cda7a69ea130..9a9e589cce77 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_SELECTION:
@@ -11,23 +12,22 @@ Name
VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp )
- :name: VIDIOC_G_SELECTION
+.. c:macro:: VIDIOC_G_SELECTION
+``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp )
- :name: VIDIOC_S_SELECTION
+.. c:macro:: VIDIOC_S_SELECTION
+``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_selection`.
@@ -115,7 +115,6 @@ constraints.
Selection targets and flags are documented in
:ref:`v4l2-selections-common`.
-
.. _sel-const-adjust:
.. kernel-figure:: constraints.svg
@@ -128,7 +127,6 @@ Selection targets and flags are documented in
-
.. c:type:: v4l2_selection
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -168,7 +166,6 @@ Selection targets and flags are documented in
Starting with kernel 4.13 both variations are allowed.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst
index a3a7fb00350f..752f7f5fae73 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_SLICED_VBI_CAP:
@@ -11,24 +12,22 @@ Name
VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp )
- :name: VIDIOC_G_SLICED_VBI_CAP
+.. c:macro:: VIDIOC_G_SLICED_VBI_CAP
+``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_sliced_vbi_cap`.
-
Description
===========
@@ -44,7 +43,6 @@ the sliced VBI API is unsupported or ``type`` is invalid.
The ``type`` field was added, and the ioctl changed from read-only
to write-read, in Linux 2.6.19.
-
.. c:type:: v4l2_sliced_vbi_cap
.. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}|
@@ -120,7 +118,6 @@ the sliced VBI API is unsupported or ``type`` is invalid.
See also :ref:`vbi-525` and :ref:`vbi-625`.
-
.. raw:: latex
\scriptsize
@@ -183,7 +180,6 @@ the sliced VBI API is unsupported or ``type`` is invalid.
\normalsize
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst
index 8a659a873528..da91fe07d9e0 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-std.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-std.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_STD:
@@ -11,33 +12,34 @@ Name
VIDIOC_G_STD - VIDIOC_S_STD - VIDIOC_SUBDEV_G_STD - VIDIOC_SUBDEV_S_STD - Query or select the video standard of the current input
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_STD, v4l2_std_id *argp )
- :name: VIDIOC_G_STD
+.. c:macro:: VIDIOC_G_STD
-.. c:function:: int ioctl( int fd, VIDIOC_S_STD, const v4l2_std_id *argp )
- :name: VIDIOC_S_STD
+``int ioctl(int fd, VIDIOC_G_STD, v4l2_std_id *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp )
- :name: VIDIOC_SUBDEV_G_STD
+.. c:macro:: VIDIOC_S_STD
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp )
- :name: VIDIOC_SUBDEV_S_STD
+``int ioctl(int fd, VIDIOC_S_STD, const v4l2_std_id *argp)``
+.. c:macro:: VIDIOC_SUBDEV_G_STD
+
+``int ioctl(int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp)``
+
+.. c:macro:: VIDIOC_SUBDEV_S_STD
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to :c:type:`v4l2_std_id`.
-
Description
===========
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst
index e3ba5b18a357..116e66c01556 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_G_TUNER:
@@ -11,27 +12,26 @@ Name
VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp )
- :name: VIDIOC_G_TUNER
+.. c:macro:: VIDIOC_G_TUNER
-.. c:function:: int ioctl( int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp )
- :name: VIDIOC_S_TUNER
+``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)``
+.. c:macro:: VIDIOC_S_TUNER
+
+``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_tuner`.
-
Description
===========
@@ -59,7 +59,6 @@ to zero. The term 'tuner' means SDR receiver in this context.
To change the radio frequency the
:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
-
.. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}|
.. c:type:: v4l2_tuner
@@ -183,7 +182,6 @@ To change the radio frequency the
Drivers and applications must set the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. c:type:: v4l2_tuner_type
@@ -207,7 +205,6 @@ To change the radio frequency the
- 5
- Tuner controls the RF part of a Software Digital Radio (SDR)
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _tuner-capability:
@@ -299,7 +296,6 @@ To change the radio frequency the
instead of 62.5 kHz.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _tuner-rxsubchans:
@@ -338,7 +334,6 @@ To change the radio frequency the
- The tuner receives an RDS channel.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _tuner-audmode:
diff --git a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst
index 74b06dc68109..c218747be762 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-log-status.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-log-status.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_LOG_STATUS:
@@ -11,20 +12,18 @@ Name
VIDIOC_LOG_STATUS - Log driver status information
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_LOG_STATUS)
- :name: VIDIOC_LOG_STATUS
+.. c:macro:: VIDIOC_LOG_STATUS
+``int ioctl(int fd, VIDIOC_LOG_STATUS)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
+ File descriptor returned by :c:func:`open()`.
Description
===========
@@ -40,7 +39,6 @@ Mismatches may give an indication where the problem is.
This ioctl is optional and not all drivers support it. It was introduced
in Linux 2.6.15.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst
index 8553fc7a6d8b..f2efaaba24c0 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-overlay.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-overlay.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_OVERLAY:
@@ -11,24 +12,22 @@ Name
VIDIOC_OVERLAY - Start or stop video overlay
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_OVERLAY, const int *argp )
- :name: VIDIOC_OVERLAY
+.. c:macro:: VIDIOC_OVERLAY
+``int ioctl(int fd, VIDIOC_OVERLAY, const int *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
-
Description
===========
@@ -41,7 +40,6 @@ Drivers do not support :ref:`VIDIOC_STREAMON` or
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with
``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst
index df003e5a65ac..45bb1eab2c2d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_PREPARE_BUF:
@@ -11,24 +12,22 @@ Name
VIDIOC_PREPARE_BUF - Prepare a buffer for I/O
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp )
- :name: VIDIOC_PREPARE_BUF
+.. c:macro:: VIDIOC_PREPARE_BUF
+``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_buffer`.
-
Description
===========
@@ -41,7 +40,6 @@ in advance saves time during the actual I/O.
The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst
index cd920d0b6adf..fbf8c5962d8a 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_QBUF:
@@ -11,27 +12,26 @@ Name
VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp )
- :name: VIDIOC_QBUF
+.. c:macro:: VIDIOC_QBUF
-.. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp )
- :name: VIDIOC_DQBUF
+``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)``
+.. c:macro:: VIDIOC_DQBUF
+
+``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_buffer`.
-
Description
===========
@@ -142,13 +142,12 @@ API is used the ``m.fd`` fields of the passed array of struct
By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
queue. When the ``O_NONBLOCK`` flag was given to the
-:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
+:c:func:`open()` function, ``VIDIOC_DQBUF`` returns
immediately with an ``EAGAIN`` error code when no buffer is available.
The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst
index 6942e7e76897..5afdc4b4dc2d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_QUERY_DV_TIMINGS:
@@ -11,27 +12,26 @@ Name
VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp )
- :name: VIDIOC_QUERY_DV_TIMINGS
+.. c:macro:: VIDIOC_QUERY_DV_TIMINGS
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp )
- :name: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
+``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
+.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
+
+``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_dv_timings`.
-
Description
===========
@@ -65,7 +65,6 @@ and returns ``ERANGE``. In that case the application can call
found timings with the hardware's capabilities in order to give more
precise feedback to the user.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst
index 1d7ecf2697af..6c615e893866 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-querybuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_QUERYBUF:
@@ -11,24 +12,22 @@ Name
VIDIOC_QUERYBUF - Query the status of a buffer
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp )
- :name: VIDIOC_QUERYBUF
+.. c:macro:: VIDIOC_QUERYBUF
+``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_buffer`.
-
Description
===========
@@ -67,7 +66,6 @@ flags, they are meaningless in this context.
The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst
index 80b7b79561f5..b512b1fbf9a3 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_QUERYCAP:
@@ -11,24 +12,22 @@ Name
VIDIOC_QUERYCAP - Query device capabilities
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp )
- :name: VIDIOC_QUERYCAP
+.. c:macro:: VIDIOC_QUERYCAP
+``int ioctl(int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_capability`.
-
Description
===========
@@ -39,7 +38,6 @@ pointer to a struct :c:type:`v4l2_capability` which is
filled by the driver. When the driver is not compatible with this
specification the ioctl returns an ``EINVAL`` error code.
-
.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}|
.. c:type:: v4l2_capability
@@ -132,7 +130,6 @@ specification the ioctl returns an ``EINVAL`` error code.
zero.
-
.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}|
.. _device-capabilities:
@@ -243,8 +240,8 @@ specification the ioctl returns an ``EINVAL`` error code.
- The device supports the :ref:`metadata` capture interface.
* - ``V4L2_CAP_READWRITE``
- 0x01000000
- - The device supports the :ref:`read() <rw>` and/or
- :ref:`write() <rw>` I/O methods.
+ - The device supports the :c:func:`read()` and/or
+ :c:func:`write()` I/O methods.
* - ``V4L2_CAP_ASYNCIO``
- 0x02000000
- The device supports the :ref:`asynchronous <async>` I/O methods.
@@ -269,7 +266,6 @@ specification the ioctl returns an ``EINVAL`` error code.
only appear in the ``capabilities`` field and never in the
``device_caps`` field.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
index 559ad849f7b9..9b8716f90f12 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_QUERYCTRL:
@@ -11,31 +12,29 @@ Name
VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
-
Synopsis
========
-.. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp )
- :name: VIDIOC_QUERYCTRL
+``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``
-.. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp )
- :name: VIDIOC_QUERY_EXT_CTRL
+.. c:macro:: VIDIOC_QUERY_EXT_CTRL
-.. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp )
- :name: VIDIOC_QUERYMENU
+``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``
+.. c:macro:: VIDIOC_QUERYMENU
+
+``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
or :c:type:`v4l2_querymenu` (depending on the ioctl).
-
Description
===========
@@ -95,7 +94,6 @@ inclusive.
See also the examples in :ref:`control`.
-
.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
.. _v4l2-queryctrl:
@@ -174,7 +172,6 @@ See also the examples in :ref:`control`.
zero.
-
.. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
.. _v4l2-query-ext-ctrl:
@@ -275,7 +272,6 @@ See also the examples in :ref:`control`.
the array to zero.
-
.. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}|
.. _v4l2-querymenu:
@@ -311,7 +307,6 @@ See also the examples in :ref:`control`.
zero.
-
.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
.. c:type:: v4l2_ctrl_type
@@ -582,7 +577,6 @@ See also the examples in :ref:`control`.
streaming is in progress since most drivers do not support changing
the format in that case.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst
index b043ec48cf9d..4a88287d8f61 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-querystd.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-querystd.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_QUERYSTD:
@@ -11,27 +12,26 @@ Name
VIDIOC_QUERYSTD - VIDIOC_SUBDEV_QUERYSTD - Sense the video standard received by the current input
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp )
- :name: VIDIOC_QUERYSTD
+.. c:macro:: VIDIOC_QUERYSTD
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp )
- :name: VIDIOC_SUBDEV_QUERYSTD
+``int ioctl(int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp)``
+.. c:macro:: VIDIOC_SUBDEV_QUERYSTD
+
+``int ioctl(int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to :c:type:`v4l2_std_id`.
-
Description
===========
@@ -58,7 +58,6 @@ or output.
standard is valid they will have to stop streaming, set the new
standard, allocate new buffers and start streaming again.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
index afc35cd7b614..c1c88e00b106 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_REQBUFS:
@@ -11,19 +12,18 @@ Name
VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp )
- :name: VIDIOC_REQBUFS
+.. c:macro:: VIDIOC_REQBUFS
+``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_requestbuffers`.
@@ -69,7 +69,6 @@ fds are closed. A ``count`` value of zero frees or orphans all buffers, after
aborting or finishing any DMA in progress, an implicit
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
-
.. c:type:: v4l2_requestbuffers
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -158,7 +157,6 @@ aborting or finishing any DMA in progress, an implicit
:ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and
:ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst
index fb09ea31cad7..1948f31c2dbc 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_S_HW_FREQ_SEEK:
@@ -11,24 +12,22 @@ Name
VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp )
- :name: VIDIOC_S_HW_FREQ_SEEK
+.. c:macro:: VIDIOC_S_HW_FREQ_SEEK
+``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_hw_freq_seek`.
-
Description
===========
@@ -59,7 +58,6 @@ set.
If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
error code is returned and no seek takes place.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_hw_freq_seek
@@ -116,7 +114,6 @@ error code is returned and no seek takes place.
- Reserved for future extensions. Applications must set the array to
zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst
index d9623aa7c425..0bc86f06947b 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-streamon.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-streamon.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_STREAMON:
@@ -11,22 +12,22 @@ Name
VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp )
- :name: VIDIOC_STREAMON
+.. c:macro:: VIDIOC_STREAMON
-.. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp )
- :name: VIDIOC_STREAMOFF
+``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
+.. c:macro:: VIDIOC_STREAMOFF
+
+``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
@@ -84,7 +85,6 @@ state as mentioned above.
no notion of starting or stopping "now". Buffer timestamps can be used
to synchronize with other events.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst
index 932e8416f11c..17acf3fd8396 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
@@ -11,24 +12,22 @@ Name
VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp )
- :name: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`.
-
Description
===========
@@ -97,7 +96,6 @@ multiple pads of the same sub-device is not defined.
- Reserved for future extensions. Applications and drivers must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst
index 3c480573df59..8016fba7023f 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
@@ -11,24 +12,22 @@ Name
VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp )
- :name: VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`.
-
Description
===========
@@ -62,7 +61,6 @@ current values of V4L2 controls. See
:ref:`VIDIOC_SUBDEV_G_FMT` for more
information about try formats.
-
.. c:type:: v4l2_subdev_frame_size_enum
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -103,7 +101,6 @@ information about try formats.
- Reserved for future extensions. Applications and drivers must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst
index 3b6a8044c391..1fd950e34a0b 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_ENUM_MBUS_CODE:
@@ -11,24 +12,22 @@ Name
VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp )
- :name: VIDIOC_SUBDEV_ENUM_MBUS_CODE
+.. c:macro:: VIDIOC_SUBDEV_ENUM_MBUS_CODE
+``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_mbus_code_enum`.
-
Description
===========
@@ -47,7 +46,6 @@ other pads of the sub-device, as well as on the current active links.
See :ref:`VIDIOC_SUBDEV_G_FMT` for more
information about the try formats.
-
.. c:type:: v4l2_subdev_mbus_code_enum
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
index 45c988b13ba6..2d78b4f5928d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_G_CROP:
@@ -11,27 +12,26 @@ Name
VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp )
- :name: VIDIOC_SUBDEV_G_CROP
+.. c:macro:: VIDIOC_SUBDEV_G_CROP
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp )
- :name: VIDIOC_SUBDEV_S_CROP
+``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)``
+.. c:macro:: VIDIOC_SUBDEV_S_CROP
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_crop`.
-
Description
===========
@@ -76,7 +76,6 @@ rectangle doesn't match the device capabilities. They must instead
modify the rectangle to match what the hardware can provide. The
modified format should be as close as possible to the original request.
-
.. c:type:: v4l2_subdev_crop
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -101,7 +100,6 @@ modified format should be as close as possible to the original request.
- Reserved for future extensions. Applications and drivers must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst
index 76ce46f53c76..90b9bbfb61dd 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_G_FMT:
@@ -11,27 +12,26 @@ Name
VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp )
- :name: VIDIOC_SUBDEV_G_FMT
+.. c:macro:: VIDIOC_SUBDEV_G_FMT
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp )
- :name: VIDIOC_SUBDEV_S_FMT
+``int ioctl(int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp)``
+.. c:macro:: VIDIOC_SUBDEV_S_FMT
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_format`.
-
Description
===========
@@ -81,7 +81,6 @@ doesn't match the device capabilities. They must instead modify the
format to match what the hardware can provide. The modified format
should be as close as possible to the original request.
-
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_subdev_format
@@ -108,7 +107,6 @@ should be as close as possible to the original request.
the array to zero.
-
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _v4l2-subdev-format-whence:
@@ -125,7 +123,6 @@ should be as close as possible to the original request.
- 1
- Active formats, applied to the hardware.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst
index 7e0b177e70aa..3a50f8b2843d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_G_FRAME_INTERVAL:
@@ -11,27 +12,26 @@ Name
VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp )
- :name: VIDIOC_SUBDEV_G_FRAME_INTERVAL
+.. c:macro:: VIDIOC_SUBDEV_G_FRAME_INTERVAL
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp )
- :name: VIDIOC_SUBDEV_S_FRAME_INTERVAL
+``int ioctl(int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)``
+.. c:macro:: VIDIOC_SUBDEV_S_FRAME_INTERVAL
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_frame_interval`.
-
Description
===========
@@ -74,7 +74,6 @@ Sub-devices that support the frame interval ioctls should implement them
on a single pad only. Their behaviour when supported on multiple pads of
the same sub-device is not defined.
-
.. c:type:: v4l2_subdev_frame_interval
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -95,7 +94,6 @@ the same sub-device is not defined.
- Reserved for future extensions. Applications and drivers must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst
index 948903a34d6f..f35b9562df21 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_G_SELECTION:
@@ -11,27 +12,26 @@ Name
VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp )
- :name: VIDIOC_SUBDEV_G_SELECTION
+.. c:macro:: VIDIOC_SUBDEV_G_SELECTION
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp )
- :name: VIDIOC_SUBDEV_S_SELECTION
+``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)``
+.. c:macro:: VIDIOC_SUBDEV_S_SELECTION
+
+``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_selection`.
-
Description
===========
@@ -58,7 +58,6 @@ There are two types of selection targets: actual and bounds. The actual
targets are the targets which configure the hardware. The BOUNDS target
will return a rectangle that contain all possible actual rectangles.
-
Discovering supported features
------------------------------
@@ -69,7 +68,6 @@ return ``EINVAL``.
Selection targets and flags are documented in
:ref:`v4l2-selections-common`.
-
.. c:type:: v4l2_subdev_selection
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -100,7 +98,6 @@ Selection targets and flags are documented in
- Reserved for future extensions. Applications and drivers must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst
index e806385ba176..949d9775b03d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_QUERYCAP:
@@ -11,24 +12,22 @@ Name
VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp )
- :name: VIDIOC_SUBDEV_QUERYCAP
+.. c:macro:: VIDIOC_SUBDEV_QUERYCAP
+``int ioctl(int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_capability`.
-
Description
===========
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
index 67827671bbaa..d1ad35164033 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
.. _VIDIOC_SUBSCRIBE_EVENT:
.. _VIDIOC_UNSUBSCRIBE_EVENT:
@@ -12,34 +13,32 @@ Name
VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
-
Synopsis
========
-.. c:function:: int ioctl( int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp )
- :name: VIDIOC_SUBSCRIBE_EVENT
+.. c:macro:: VIDIOC_SUBSCRIBE_EVENT
-.. c:function:: int ioctl( int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp )
- :name: VIDIOC_UNSUBSCRIBE_EVENT
+``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
+.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
+
+``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_event_subscription`.
-
Description
===========
Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
using the :ref:`VIDIOC_DQEVENT` ioctl.
-
.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}|
.. c:type:: v4l2_event_subscription
@@ -72,7 +71,6 @@ using the :ref:`VIDIOC_DQEVENT` ioctl.
the array to zero.
-
.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}|
.. _event-flags:
@@ -107,7 +105,6 @@ using the :ref:`VIDIOC_DQEVENT` ioctl.
Think carefully when you set this flag so you won't get into
situations like that.
-
Return Value
============
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 14/52] media: docs: make DVB documents more compatible with Sphinx 3.1+
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (12 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 13/52] media: docs: make V4L documents more " Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 15/52] media: docs: make MC " Mauro Carvalho Chehab
` (38 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Arnd Bergmann, Hans Verkuil,
Mauro Carvalho Chehab, Randy Dunlap, linux-kernel, linux-media
Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../dvb/audio-bilingual-channel-select.rst | 7 +++----
.../media/dvb/audio-channel-select.rst | 8 +++-----
.../media/dvb/audio-clear-buffer.rst | 8 ++++----
.../userspace-api/media/dvb/audio-continue.rst | 7 +++----
.../userspace-api/media/dvb/audio-fclose.rst | 7 +------
.../userspace-api/media/dvb/audio-fopen.rst | 7 +------
.../userspace-api/media/dvb/audio-fwrite.rst | 7 +------
.../media/dvb/audio-get-capabilities.rst | 8 +++-----
.../media/dvb/audio-get-status.rst | 8 +++-----
.../userspace-api/media/dvb/audio-pause.rst | 9 ++++-----
.../userspace-api/media/dvb/audio-play.rst | 7 +++----
.../media/dvb/audio-select-source.rst | 8 +++-----
.../media/dvb/audio-set-av-sync.rst | 8 +++-----
.../media/dvb/audio-set-bypass-mode.rst | 9 ++++-----
.../userspace-api/media/dvb/audio-set-id.rst | 9 ++++-----
.../userspace-api/media/dvb/audio-set-mixer.rst | 9 ++++-----
.../userspace-api/media/dvb/audio-set-mute.rst | 8 +++-----
.../media/dvb/audio-set-streamtype.rst | 10 +++-------
.../userspace-api/media/dvb/audio-stop.rst | 9 ++++-----
.../userspace-api/media/dvb/ca-fclose.rst | 7 ++-----
.../userspace-api/media/dvb/ca-fopen.rst | 7 +------
.../userspace-api/media/dvb/ca-get-cap.rst | 8 ++++----
.../media/dvb/ca-get-descr-info.rst | 9 +++++----
.../userspace-api/media/dvb/ca-get-msg.rst | 10 ++++------
.../media/dvb/ca-get-slot-info.rst | 9 ++++-----
.../userspace-api/media/dvb/ca-reset.rst | 9 ++++-----
.../userspace-api/media/dvb/ca-send-msg.rst | 9 ++++-----
.../userspace-api/media/dvb/ca-set-descr.rst | 8 ++++----
.../userspace-api/media/dvb/dmx-add-pid.rst | 10 ++++------
.../userspace-api/media/dvb/dmx-expbuf.rst | 11 ++++-------
.../userspace-api/media/dvb/dmx-fclose.rst | 9 +++------
.../userspace-api/media/dvb/dmx-fopen.rst | 5 +----
.../userspace-api/media/dvb/dmx-fread.rst | 7 ++-----
.../userspace-api/media/dvb/dmx-fwrite.rst | 6 ++----
.../media/dvb/dmx-get-pes-pids.rst | 12 +++++-------
.../userspace-api/media/dvb/dmx-get-stc.rst | 12 +++++-------
.../userspace-api/media/dvb/dmx-mmap.rst | 15 ++++++---------
.../userspace-api/media/dvb/dmx-munmap.rst | 14 +++++---------
.../userspace-api/media/dvb/dmx-qbuf.rst | 17 ++++++++---------
.../userspace-api/media/dvb/dmx-querybuf.rst | 9 ++++-----
.../userspace-api/media/dvb/dmx-remove-pid.rst | 10 ++++------
.../userspace-api/media/dvb/dmx-reqbufs.rst | 9 ++++-----
.../media/dvb/dmx-set-buffer-size.rst | 10 ++++------
.../userspace-api/media/dvb/dmx-set-filter.rst | 12 +++++-------
.../media/dvb/dmx-set-pes-filter.rst | 13 ++++---------
.../userspace-api/media/dvb/dmx-start.rst | 11 ++++-------
.../userspace-api/media/dvb/dmx-stop.rst | 9 ++++-----
.../media/dvb/fe-diseqc-recv-slave-reply.rst | 9 ++++-----
.../media/dvb/fe-diseqc-reset-overload.rst | 9 ++++-----
.../media/dvb/fe-diseqc-send-burst.rst | 10 ++++------
.../media/dvb/fe-diseqc-send-master-cmd.rst | 9 ++++-----
.../dvb/fe-dishnetwork-send-legacy-cmd.rst | 10 ++++------
.../media/dvb/fe-enable-high-lnb-voltage.rst | 10 ++++------
.../userspace-api/media/dvb/fe-get-event.rst | 12 ++++--------
.../userspace-api/media/dvb/fe-get-frontend.rst | 12 ++++--------
.../userspace-api/media/dvb/fe-get-info.rst | 11 ++++-------
.../userspace-api/media/dvb/fe-get-property.rst | 15 +++++++--------
.../userspace-api/media/dvb/fe-read-ber.rst | 9 ++++-----
.../media/dvb/fe-read-signal-strength.rst | 9 ++++-----
.../userspace-api/media/dvb/fe-read-snr.rst | 9 ++++-----
.../userspace-api/media/dvb/fe-read-status.rst | 11 ++++-------
.../media/dvb/fe-read-uncorrected-blocks.rst | 9 ++++-----
.../media/dvb/fe-set-frontend-tune-mode.rst | 10 ++++------
.../userspace-api/media/dvb/fe-set-frontend.rst | 11 ++++-------
.../userspace-api/media/dvb/fe-set-tone.rst | 10 ++++------
.../userspace-api/media/dvb/fe-set-voltage.rst | 10 ++++------
.../media/dvb/frontend_f_close.rst | 8 ++------
.../userspace-api/media/dvb/frontend_f_open.rst | 10 ++--------
.../userspace-api/media/dvb/net-add-if.rst | 9 ++++-----
.../userspace-api/media/dvb/net-get-if.rst | 10 ++++------
.../userspace-api/media/dvb/net-remove-if.rst | 10 ++++------
.../media/dvb/video-clear-buffer.rst | 8 +++-----
.../userspace-api/media/dvb/video-command.rst | 10 ++++------
.../userspace-api/media/dvb/video-continue.rst | 8 +++-----
.../media/dvb/video-fast-forward.rst | 10 +++-------
.../userspace-api/media/dvb/video-fclose.rst | 6 +-----
.../userspace-api/media/dvb/video-fopen.rst | 6 +-----
.../userspace-api/media/dvb/video-freeze.rst | 8 +++-----
.../userspace-api/media/dvb/video-fwrite.rst | 6 +-----
.../media/dvb/video-get-capabilities.rst | 8 +++-----
.../userspace-api/media/dvb/video-get-event.rst | 8 +++-----
.../media/dvb/video-get-frame-count.rst | 8 +++-----
.../userspace-api/media/dvb/video-get-pts.rst | 8 +++-----
.../userspace-api/media/dvb/video-get-size.rst | 8 +++-----
.../media/dvb/video-get-status.rst | 7 +++----
.../userspace-api/media/dvb/video-play.rst | 8 +++-----
.../media/dvb/video-select-source.rst | 7 +++----
.../userspace-api/media/dvb/video-set-blank.rst | 8 +++-----
.../media/dvb/video-set-display-format.rst | 8 +++-----
.../media/dvb/video-set-format.rst | 9 +++------
.../media/dvb/video-set-streamtype.rst | 8 +++-----
.../media/dvb/video-slowmotion.rst | 10 +++-------
.../media/dvb/video-stillpicture.rst | 8 +++-----
.../userspace-api/media/dvb/video-stop.rst | 8 +++-----
.../media/dvb/video-try-command.rst | 8 +++-----
95 files changed, 329 insertions(+), 534 deletions(-)
diff --git a/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst b/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst
index ba4f48b30d29..33b5363317f1 100644
--- a/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst
+++ b/Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_BILINGUAL_CHANNEL_SELECT:
@@ -16,9 +17,9 @@ AUDIO_BILINGUAL_CHANNEL_SELECT
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct *audio_channel_select)
- :name: AUDIO_BILINGUAL_CHANNEL_SELECT
+.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT
+``int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct audio_channel_select *select)``
Arguments
---------
@@ -39,7 +40,6 @@ Arguments
- Select the output format of the audio (mono left/right, stereo).
-
Description
-----------
@@ -50,7 +50,6 @@ for MPEG decoders controlled through V4L2.
This ioctl call asks the Audio Device to select the requested channel
for bilingual streams if possible.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-channel-select.rst b/Documentation/userspace-api/media/dvb/audio-channel-select.rst
index ba83b639d955..74093df92a68 100644
--- a/Documentation/userspace-api/media/dvb/audio-channel-select.rst
+++ b/Documentation/userspace-api/media/dvb/audio-channel-select.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_CHANNEL_SELECT:
@@ -16,9 +17,9 @@ AUDIO_CHANNEL_SELECT
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct *audio_channel_select)
- :name: AUDIO_CHANNEL_SELECT
+.. c:macro:: AUDIO_CHANNEL_SELECT
+``int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct audio_channel_select *select)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -40,7 +40,6 @@ Arguments
- Select the output format of the audio (mono left/right, stereo).
-
Description
-----------
@@ -50,7 +49,6 @@ V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
This ioctl call asks the Audio Device to select the requested channel if
possible.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst b/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst
index 7035a40c0e3a..a0ebb0278260 100644
--- a/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst
+++ b/Documentation/userspace-api/media/dvb/audio-clear-buffer.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_CLEAR_BUFFER:
@@ -16,8 +17,9 @@ AUDIO_CLEAR_BUFFER
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_CLEAR_BUFFER)
- :name: AUDIO_CLEAR_BUFFER
+.. c:macro:: AUDIO_CLEAR_BUFFER
+
+``int ioctl(int fd, AUDIO_CLEAR_BUFFER)``
Arguments
---------
@@ -26,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -39,7 +40,6 @@ Description
This ioctl call asks the Audio Device to clear all software and hardware
buffers of the audio decoder device.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-continue.rst b/Documentation/userspace-api/media/dvb/audio-continue.rst
index c8d514a4eeb0..a2e9850f37f2 100644
--- a/Documentation/userspace-api/media/dvb/audio-continue.rst
+++ b/Documentation/userspace-api/media/dvb/audio-continue.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_CONTINUE:
@@ -16,9 +17,9 @@ AUDIO_CONTINUE
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_CONTINUE)
- :name: AUDIO_CONTINUE
+.. c:macro:: AUDIO_CONTINUE
+``int ioctl(int fd, AUDIO_CONTINUE)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -40,7 +40,6 @@ Description
This ioctl restarts the decoding and playing process previously paused
with AUDIO_PAUSE command.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-fclose.rst b/Documentation/userspace-api/media/dvb/audio-fclose.rst
index c968177b1e3f..77857d578e83 100644
--- a/Documentation/userspace-api/media/dvb/audio-fclose.rst
+++ b/Documentation/userspace-api/media/dvb/audio-fclose.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _audio_fclose:
@@ -17,8 +18,6 @@ Synopsis
--------
.. c:function:: int close(int fd)
- :name: dvb-audio-close
-
Arguments
---------
@@ -27,20 +26,17 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
-
Description
-----------
This system call closes a previously opened audio device.
-
Return Value
------------
@@ -48,7 +44,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EBADF``
diff --git a/Documentation/userspace-api/media/dvb/audio-fopen.rst b/Documentation/userspace-api/media/dvb/audio-fopen.rst
index d34001e038dc..774daaab3bad 100644
--- a/Documentation/userspace-api/media/dvb/audio-fopen.rst
+++ b/Documentation/userspace-api/media/dvb/audio-fopen.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _audio_fopen:
@@ -17,8 +18,6 @@ Synopsis
--------
.. c:function:: int open(const char *deviceName, int flags)
- :name: dvb-audio-open
-
Arguments
---------
@@ -27,7 +26,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- const char \*deviceName
@@ -60,7 +58,6 @@ Arguments
-
- (blocking mode is the default)
-
Description
-----------
@@ -78,7 +75,6 @@ fail, and an error code will be returned. If the Audio Device is opened
in O_RDONLY mode, the only ioctl call that can be used is
AUDIO_GET_STATUS. All other call will return with an error code.
-
Return Value
------------
@@ -88,7 +84,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``ENODEV``
diff --git a/Documentation/userspace-api/media/dvb/audio-fwrite.rst b/Documentation/userspace-api/media/dvb/audio-fwrite.rst
index d17ec719e231..7b096ac2b6c4 100644
--- a/Documentation/userspace-api/media/dvb/audio-fwrite.rst
+++ b/Documentation/userspace-api/media/dvb/audio-fwrite.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _audio_fwrite:
@@ -17,8 +18,6 @@ Synopsis
--------
.. c:function:: size_t write(int fd, const void *buf, size_t count)
- :name: dvb-audio-write
-
Arguments
---------
@@ -27,7 +26,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +44,6 @@ Arguments
- Size of buf.
-
Description
-----------
@@ -56,7 +53,6 @@ PES format. If O_NONBLOCK is not specified the function will block
until buffer space is available. The amount of data to be transferred is
implied by count.
-
Return Value
------------
@@ -64,7 +60,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EPERM``
diff --git a/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst b/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst
index 33907e40e48c..6d9eb71dad17 100644
--- a/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst
+++ b/Documentation/userspace-api/media/dvb/audio-get-capabilities.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_GET_CAPABILITIES:
@@ -16,9 +17,9 @@ AUDIO_GET_CAPABILITIES
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap)
- :name: AUDIO_GET_CAPABILITIES
+.. c:macro:: AUDIO_GET_CAPABILITIES
+``int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -40,14 +40,12 @@ Arguments
- Returns a bit array of supported sound formats.
-
Description
-----------
This ioctl call asks the Audio Device to tell us about the decoding
capabilities of the audio hardware.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-get-status.rst b/Documentation/userspace-api/media/dvb/audio-get-status.rst
index 4213d076c6ed..7ae8db2e65e9 100644
--- a/Documentation/userspace-api/media/dvb/audio-get-status.rst
+++ b/Documentation/userspace-api/media/dvb/audio-get-status.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_GET_STATUS:
@@ -16,9 +17,9 @@ AUDIO_GET_STATUS
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status)
- :name: AUDIO_GET_STATUS
+.. c:macro:: AUDIO_GET_STATUS
+``int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -40,14 +40,12 @@ Arguments
- Returns the current state of Audio Device.
-
Description
-----------
This ioctl call asks the Audio Device to return the current state of the
Audio Device.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-pause.rst b/Documentation/userspace-api/media/dvb/audio-pause.rst
index 2de74f1662cf..d37d1ddce4df 100644
--- a/Documentation/userspace-api/media/dvb/audio-pause.rst
+++ b/Documentation/userspace-api/media/dvb/audio-pause.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_PAUSE:
@@ -16,8 +17,9 @@ AUDIO_PAUSE
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_PAUSE)
- :name: AUDIO_PAUSE
+.. c:macro:: AUDIO_PAUSE
+
+``int ioctl(int fd, AUDIO_PAUSE)``
Arguments
---------
@@ -26,14 +28,12 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
-
Description
-----------
@@ -41,7 +41,6 @@ This ioctl call suspends the audio stream being played. Decoding and
playing are paused. It is then possible to restart again decoding and
playing process of the audio stream using AUDIO_CONTINUE command.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-play.rst b/Documentation/userspace-api/media/dvb/audio-play.rst
index d4e4eacb8686..e591930b6ca7 100644
--- a/Documentation/userspace-api/media/dvb/audio-play.rst
+++ b/Documentation/userspace-api/media/dvb/audio-play.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_PLAY:
@@ -16,9 +17,9 @@ AUDIO_PLAY
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_PLAY)
- :name: AUDIO_PLAY
+.. c:macro:: AUDIO_PLAY
+``int ioctl(int fd, AUDIO_PLAY)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -40,7 +40,6 @@ Description
This ioctl call asks the Audio Device to start playing an audio stream
from the selected source.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-select-source.rst b/Documentation/userspace-api/media/dvb/audio-select-source.rst
index fb09f914cb8f..6a0c0f365eb1 100644
--- a/Documentation/userspace-api/media/dvb/audio-select-source.rst
+++ b/Documentation/userspace-api/media/dvb/audio-select-source.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SELECT_SOURCE:
@@ -16,9 +17,9 @@ AUDIO_SELECT_SOURCE
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source)
- :name: AUDIO_SELECT_SOURCE
+.. c:macro:: AUDIO_SELECT_SOURCE
+``int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -40,7 +40,6 @@ Arguments
- Indicates the source that shall be used for the Audio stream.
-
Description
-----------
@@ -49,7 +48,6 @@ the input data. The possible sources are demux or memory. If
AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
through the write command.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst b/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst
index 5bcb9b1ed19d..85a8016bf025 100644
--- a/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst
+++ b/Documentation/userspace-api/media/dvb/audio-set-av-sync.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SET_AV_SYNC:
@@ -16,9 +17,9 @@ AUDIO_SET_AV_SYNC
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state)
- :name: AUDIO_SET_AV_SYNC
+.. c:macro:: AUDIO_SET_AV_SYNC
+``int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -44,14 +44,12 @@ Arguments
FALSE: AV-sync OFF
-
Description
-----------
This ioctl call asks the Audio Device to turn ON or OFF A/V
synchronization.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst b/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst
index f24a18bbb567..ecac02f1b2fc 100644
--- a/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst
+++ b/Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SET_BYPASS_MODE:
@@ -16,8 +17,9 @@ AUDIO_SET_BYPASS_MODE
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode)
- :name: AUDIO_SET_BYPASS_MODE
+.. c:macro:: AUDIO_SET_BYPASS_MODE
+
+``int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode)``
Arguments
---------
@@ -26,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -44,7 +45,6 @@ Arguments
FALSE: Bypass is enabled
-
Description
-----------
@@ -54,7 +54,6 @@ that can’t be handled by the Digital TV system shall be decoded. Dolby
DigitalTM streams are automatically forwarded by the Digital TV subsystem if
the hardware can handle it.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-set-id.rst b/Documentation/userspace-api/media/dvb/audio-set-id.rst
index 0227e1071d0c..39ad846d412d 100644
--- a/Documentation/userspace-api/media/dvb/audio-set-id.rst
+++ b/Documentation/userspace-api/media/dvb/audio-set-id.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SET_ID:
@@ -16,8 +17,9 @@ AUDIO_SET_ID
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_SET_ID, int id)
- :name: AUDIO_SET_ID
+.. c:macro:: AUDIO_SET_ID
+
+``int ioctl(int fd, AUDIO_SET_ID, int id)``
Arguments
---------
@@ -26,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -39,7 +40,6 @@ Arguments
- audio sub-stream id
-
Description
-----------
@@ -51,7 +51,6 @@ other stream types. If the stream type is set the id just specifies the
substream id of the audio stream and only the first 5 bits are
recognized.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-set-mixer.rst b/Documentation/userspace-api/media/dvb/audio-set-mixer.rst
index 58f18cf8240d..45dbdf4801e0 100644
--- a/Documentation/userspace-api/media/dvb/audio-set-mixer.rst
+++ b/Documentation/userspace-api/media/dvb/audio-set-mixer.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SET_MIXER:
@@ -16,8 +17,9 @@ AUDIO_SET_MIXER
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix)
- :name: AUDIO_SET_MIXER
+.. c:macro:: AUDIO_SET_MIXER
+
+``int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix)``
Arguments
---------
@@ -26,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -39,13 +40,11 @@ Arguments
- mixer settings.
-
Description
-----------
This ioctl lets you adjust the mixer settings of the audio decoder.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-set-mute.rst b/Documentation/userspace-api/media/dvb/audio-set-mute.rst
index 7ea7d8663e6b..987751f92967 100644
--- a/Documentation/userspace-api/media/dvb/audio-set-mute.rst
+++ b/Documentation/userspace-api/media/dvb/audio-set-mute.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SET_MUTE:
@@ -16,9 +17,9 @@ AUDIO_SET_MUTE
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_SET_MUTE, boolean state)
- :name: AUDIO_SET_MUTE
+.. c:macro:: AUDIO_SET_MUTE
+``int ioctl(int fd, AUDIO_SET_MUTE, boolean state)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -44,7 +44,6 @@ Arguments
FALSE: Audio Un-mute
-
Description
-----------
@@ -55,7 +54,6 @@ V4L2 :ref:`VIDIOC_DECODER_CMD` with the
This ioctl call asks the audio device to mute the stream that is
currently being played.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst b/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst
index d9f4924afdbe..77d73c74882f 100644
--- a/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst
+++ b/Documentation/userspace-api/media/dvb/audio-set-streamtype.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_SET_STREAMTYPE:
@@ -16,9 +17,9 @@ AUDIO_SET_STREAMTYPE
Synopsis
--------
-.. c:function:: int ioctl(fd, AUDIO_SET_STREAMTYPE, int type)
- :name: AUDIO_SET_STREAMTYPE
+.. c:macro:: AUDIO_SET_STREAMTYPE
+``int ioctl(fd, AUDIO_SET_STREAMTYPE, int type)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
-
- int fd
@@ -40,7 +40,6 @@ Arguments
- stream type
-
Description
-----------
@@ -48,7 +47,6 @@ This ioctl tells the driver which kind of audio stream to expect. This
is useful if the stream offers several audio sub-streams like LPCM and
AC3.
-
Return Value
------------
@@ -57,12 +55,10 @@ appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
-
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EINVAL``
diff --git a/Documentation/userspace-api/media/dvb/audio-stop.rst b/Documentation/userspace-api/media/dvb/audio-stop.rst
index 3a2bc328626d..d77f786fd797 100644
--- a/Documentation/userspace-api/media/dvb/audio-stop.rst
+++ b/Documentation/userspace-api/media/dvb/audio-stop.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.audio
.. _AUDIO_STOP:
@@ -16,8 +17,9 @@ AUDIO_STOP
Synopsis
--------
-.. c:function:: int ioctl(int fd, AUDIO_STOP)
- :name: AUDIO_STOP
+.. c:macro:: AUDIO_STOP
+
+``int ioctl(int fd, AUDIO_STOP)``
Arguments
---------
@@ -26,21 +28,18 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
-
Description
-----------
This ioctl call asks the Audio Device to stop playing the current
stream.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/ca-fclose.rst b/Documentation/userspace-api/media/dvb/ca-fclose.rst
index 00379ee7e9ed..27f217a350e7 100644
--- a/Documentation/userspace-api/media/dvb/ca-fclose.rst
+++ b/Documentation/userspace-api/media/dvb/ca-fclose.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _ca_fclose:
@@ -11,26 +12,22 @@ Name
Digital TV CA close()
-
Synopsis
--------
.. c:function:: int close(int fd)
- :name: dvb-ca-close
-
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
Description
-----------
This system call closes a previously opened CA device.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/ca-fopen.rst b/Documentation/userspace-api/media/dvb/ca-fopen.rst
index 9ca4bd1d8d5f..7f99908fff2c 100644
--- a/Documentation/userspace-api/media/dvb/ca-fopen.rst
+++ b/Documentation/userspace-api/media/dvb/ca-fopen.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _ca_fopen:
@@ -11,13 +12,10 @@ Name
Digital TV CA open()
-
Synopsis
--------
.. c:function:: int open(const char *name, int flags)
- :name: dvb-ca-open
-
Arguments
---------
@@ -45,7 +43,6 @@ Arguments
- open in non-blocking mode
(blocking mode is the default)
-
Description
-----------
@@ -63,11 +60,9 @@ Only one user can open the CA Device in ``O_RDWR`` mode. All other
attempts to open the device in this mode will fail, and an error code
will be returned.
-
Return Value
------------
-
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
diff --git a/Documentation/userspace-api/media/dvb/ca-get-cap.rst b/Documentation/userspace-api/media/dvb/ca-get-cap.rst
index 93742a5d941d..9b29513eeda8 100644
--- a/Documentation/userspace-api/media/dvb/ca-get-cap.rst
+++ b/Documentation/userspace-api/media/dvb/ca-get-cap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_GET_CAP:
@@ -11,19 +12,18 @@ Name
CA_GET_CAP
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)
- :name: CA_GET_CAP
+.. c:macro:: CA_GET_CAP
+``int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``caps``
Pointer to struct :c:type:`ca_caps`.
diff --git a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst
index be7dec053685..0cfdcdab33a8 100644
--- a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst
+++ b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_GET_DESCR_INFO:
@@ -11,18 +12,18 @@ Name
CA_GET_DESCR_INFO
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)
- :name: CA_GET_DESCR_INFO
+.. c:macro:: CA_GET_DESCR_INFO
+
+``int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``desc``
Pointer to struct :c:type:`ca_descr_info`.
diff --git a/Documentation/userspace-api/media/dvb/ca-get-msg.rst b/Documentation/userspace-api/media/dvb/ca-get-msg.rst
index e8802b4c5fa1..7c9a8d197343 100644
--- a/Documentation/userspace-api/media/dvb/ca-get-msg.rst
+++ b/Documentation/userspace-api/media/dvb/ca-get-msg.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_GET_MSG:
@@ -11,19 +12,18 @@ Name
CA_GET_MSG
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)
- :name: CA_GET_MSG
+.. c:macro:: CA_GET_MSG
+``int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``msg``
Pointer to struct :c:type:`ca_msg`.
@@ -38,11 +38,9 @@ Receives a message via a CI CA module.
Please notice that, on most drivers, this is done by reading from
the /dev/adapter?/ca? device node.
-
Return Value
------------
-
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
diff --git a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst
index d283df335914..582444af7003 100644
--- a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst
+++ b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_GET_SLOT_INFO:
@@ -11,19 +12,18 @@ Name
CA_GET_SLOT_INFO
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)
- :name: CA_GET_SLOT_INFO
+.. c:macro:: CA_GET_SLOT_INFO
+``int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``info``
Pointer to struct :c:type:`ca_slot_info`.
@@ -34,7 +34,6 @@ Description
Returns information about a CA slot identified by
:c:type:`ca_slot_info`.slot_num.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/ca-reset.rst b/Documentation/userspace-api/media/dvb/ca-reset.rst
index fc49ef2ffcdb..b01ca48f0b50 100644
--- a/Documentation/userspace-api/media/dvb/ca-reset.rst
+++ b/Documentation/userspace-api/media/dvb/ca-reset.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_RESET:
@@ -11,19 +12,18 @@ Name
CA_RESET
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_RESET)
- :name: CA_RESET
+.. c:macro:: CA_RESET
+``int ioctl(fd, CA_RESET)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
Description
-----------
@@ -31,7 +31,6 @@ Description
Puts the Conditional Access hardware on its initial state. It should
be called before start using the CA hardware.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/ca-send-msg.rst b/Documentation/userspace-api/media/dvb/ca-send-msg.rst
index cf423fe881b8..7dd2ab4ef675 100644
--- a/Documentation/userspace-api/media/dvb/ca-send-msg.rst
+++ b/Documentation/userspace-api/media/dvb/ca-send-msg.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_SEND_MSG:
@@ -11,24 +12,22 @@ Name
CA_SEND_MSG
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)
- :name: CA_SEND_MSG
+.. c:macro:: CA_SEND_MSG
+``int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``msg``
Pointer to struct :c:type:`ca_msg`.
-
Description
-----------
diff --git a/Documentation/userspace-api/media/dvb/ca-set-descr.rst b/Documentation/userspace-api/media/dvb/ca-set-descr.rst
index a5c628a4d3cd..a740af34c872 100644
--- a/Documentation/userspace-api/media/dvb/ca-set-descr.rst
+++ b/Documentation/userspace-api/media/dvb/ca-set-descr.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.ca
.. _CA_SET_DESCR:
@@ -11,19 +12,18 @@ Name
CA_SET_DESCR
-
Synopsis
--------
-.. c:function:: int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)
- :name: CA_SET_DESCR
+.. c:macro:: CA_SET_DESCR
+``int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)``
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``msg``
Pointer to struct :c:type:`ca_descr`.
diff --git a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst
index 3f08ecd88b0c..ea0c7dd91e05 100644
--- a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_ADD_PID:
@@ -11,24 +12,22 @@ Name
DMX_ADD_PID
-
Synopsis
--------
-.. c:function:: int ioctl(fd, DMX_ADD_PID, __u16 *pid)
- :name: DMX_ADD_PID
+.. c:macro:: DMX_ADD_PID
+``int ioctl(fd, DMX_ADD_PID, __u16 *pid)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``pid``
PID number to be filtered.
-
Description
-----------
@@ -36,7 +35,6 @@ This ioctl call allows to add multiple PIDs to a transport stream filter
previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to
:c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst
index cde2b78a35fa..5cdc2035e3b7 100644
--- a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_EXPBUF:
@@ -13,24 +14,22 @@ DMX_EXPBUF - Export a buffer as a DMABUF file descriptor.
.. warning:: this API is still experimental
-
Synopsis
========
-.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp )
- :name: DMX_EXPBUF
+.. c:macro:: DMX_EXPBUF
+``int ioctl(int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <dmx_fopen>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dmx_exportbuffer`.
-
Description
===========
@@ -54,11 +53,9 @@ driver, on success. This is a DMABUF file descriptor. The application may
pass it to other DMABUF-aware devices. It is recommended to close a DMABUF
file when it is no longer used to allow the associated memory to be reclaimed.
-
Examples
========
-
.. code-block:: c
int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd)
diff --git a/Documentation/userspace-api/media/dvb/dmx-fclose.rst b/Documentation/userspace-api/media/dvb/dmx-fclose.rst
index af036792f13d..719ac1d4f686 100644
--- a/Documentation/userspace-api/media/dvb/dmx-fclose.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-fclose.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _dmx_fclose:
@@ -11,27 +12,23 @@ Name
Digital TV demux close()
-
Synopsis
--------
.. c:function:: int close(int fd)
- :name: dvb-dmx-close
-
Arguments
---------
``fd``
File descriptor returned by a previous call to
- :c:func:`open() <dvb-dmx-open>`.
+ :c:func:`open()`.
Description
-----------
This system call deactivates and deallocates a filter that was
-previously allocated via the :c:func:`open() <dvb-dmx-open>` call.
-
+previously allocated via the :c:func:`open()` call.
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/dmx-fopen.rst b/Documentation/userspace-api/media/dvb/dmx-fopen.rst
index 7117c9bc4325..8f0a2b831d4a 100644
--- a/Documentation/userspace-api/media/dvb/dmx-fopen.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-fopen.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _dmx_fopen:
@@ -11,12 +12,10 @@ Name
Digital TV demux open()
-
Synopsis
--------
.. c:function:: int open(const char *deviceName, int flags)
- :name: dvb-dmx-open
Arguments
---------
@@ -47,7 +46,6 @@ Arguments
- open in non-blocking mode
(blocking mode is the default)
-
Description
-----------
@@ -68,7 +66,6 @@ affect the semantics of the ``open()`` call itself. A device opened
in blocking mode can later be put into non-blocking mode (and vice versa)
using the ``F_SETFL`` command of the fcntl system call.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/dmx-fread.rst b/Documentation/userspace-api/media/dvb/dmx-fread.rst
index c708a240abae..78e9daef595a 100644
--- a/Documentation/userspace-api/media/dvb/dmx-fread.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-fread.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _dmx_fread:
@@ -11,18 +12,16 @@ Name
Digital TV demux read()
-
Synopsis
--------
.. c:function:: size_t read(int fd, void *buf, size_t count)
- :name: dvb-dmx-read
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``buf``
Buffer to be filled
@@ -44,7 +43,6 @@ to be transferred is implied by count.
:c:type:`DMX_CHECK_CRC <dmx_sct_filter_params>` flag set,
data that fails on CRC check will be silently ignored.
-
Return Value
------------
@@ -75,6 +73,5 @@ appropriately.
- The driver failed to write to the callers buffer due to an
invalid \*buf pointer.
-
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst
index bef565a35c59..e11ee0ba84a5 100644
--- a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _dmx_fwrite:
@@ -11,18 +12,16 @@ Name
Digital TV demux write()
-
Synopsis
--------
.. c:function:: ssize_t write(int fd, const void *buf, size_t count)
- :name: dvb-dmx-write
Arguments
---------
``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
+ File descriptor returned by a previous call to :c:func:`open()`.
``buf``
Buffer with data to be written
@@ -40,7 +39,6 @@ digitally recorded Transport Stream. Matching filters have to be defined
in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``.
The amount of data to be transferred is implied by count.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst
index e92d94d93b18..4f5f0505c0d5 100644
--- a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_GET_PES_PIDS:
@@ -11,23 +12,22 @@ Name
DMX_GET_PES_PIDS
-
Synopsis
--------
-.. c:function:: int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])
- :name: DMX_GET_PES_PIDS
+.. c:macro:: DMX_GET_PES_PIDS
+
+``int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``pids``
Array used to store 5 Program IDs.
-
Description
-----------
@@ -45,13 +45,11 @@ pids[DMX_PES_SUBTITLE] 3 first subtitle PID
pids[DMX_PES_PCR] 4 first Program Clock Reference PID
======================= ======== =======================================
-
.. note::
A value equal to 0xffff means that the PID was not filled by the
Kernel.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst
index 3762efcf1355..6ada74f6eb18 100644
--- a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_GET_STC:
@@ -11,23 +12,22 @@ Name
DMX_GET_STC
-
Synopsis
--------
-.. c:function:: int ioctl( int fd, DMX_GET_STC, struct dmx_stc *stc)
- :name: DMX_GET_STC
+.. c:macro:: DMX_GET_STC
+
+``int ioctl(int fd, DMX_GET_STC, struct dmx_stc *stc)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``stc``
Pointer to :c:type:`dmx_stc` where the stc data is to be stored.
-
Description
-----------
@@ -39,7 +39,6 @@ The result is returned in form of a ratio with a 64 bit numerator
and a 32 bit denominator, so the real 90kHz STC value is
``stc->stc / stc->base``.
-
Return Value
------------
@@ -61,6 +60,5 @@ appropriately.
- Invalid stc number.
-
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/userspace-api/media/dvb/dmx-mmap.rst b/Documentation/userspace-api/media/dvb/dmx-mmap.rst
index efa9b04be700..8826c6226fb0 100644
--- a/Documentation/userspace-api/media/dvb/dmx-mmap.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-mmap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _dmx-mmap:
@@ -21,9 +22,7 @@ Synopsis
#include <unistd.h>
#include <sys/mman.h>
-
.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
- :name: dmx-mmap
Arguments
=========
@@ -54,7 +53,7 @@ Arguments
``MAP_FIXED`` requests that the driver selects no other address than
the one specified. If the specified address cannot be used,
- :ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified,
+ :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified,
``start`` must be a multiple of the pagesize. Use of this option is
discouraged.
@@ -69,17 +68,16 @@ Arguments
flags.
``fd``
- File descriptor returned by :ref:`open() <dmx_fopen>`.
+ File descriptor returned by :c:func:`open()`.
``offset``
Offset of the buffer in device memory, as returned by
:ref:`DMX_QUERYBUF` ioctl.
-
Description
===========
-The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at
+The :c:func:`mmap()` function asks to map ``length`` bytes starting at
``offset`` in the memory of the device specified by ``fd`` into the
application address space, preferably at address ``start``. This latter
address is a hint only, and is usually specified as 0.
@@ -88,13 +86,12 @@ Suitable length and offset parameters are queried with the
:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the
:ref:`DMX_REQBUFS` ioctl before they can be queried.
-To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used.
-
+To unmap buffers the :c:func:`munmap()` function is used.
Return Value
============
-On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On
+On success :c:func:`mmap()` returns a pointer to the mapped buffer. On
error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
appropriately. Possible error codes are:
diff --git a/Documentation/userspace-api/media/dvb/dmx-munmap.rst b/Documentation/userspace-api/media/dvb/dmx-munmap.rst
index 308a9593919c..66bbc11e5c40 100644
--- a/Documentation/userspace-api/media/dvb/dmx-munmap.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-munmap.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _dmx-munmap:
@@ -13,7 +14,6 @@ dmx-munmap - Unmap device memory
.. warning:: This API is still experimental.
-
Synopsis
========
@@ -22,33 +22,29 @@ Synopsis
#include <unistd.h>
#include <sys/mman.h>
-
.. c:function:: int munmap( void *start, size_t length )
- :name: dmx-munmap
Arguments
=========
``start``
Address of the mapped buffer as returned by the
- :ref:`mmap() <dmx-mmap>` function.
+ :c:func:`mmap()` function.
``length``
Length of the mapped buffer. This must be the same value as given to
- :ref:`mmap() <dmx-mmap>`.
-
+ :c:func:`mmap()`.
Description
===========
-Unmaps a previously with the :ref:`mmap() <dmx-mmap>` function mapped
+Unmaps a previously with the :c:func:`mmap()` function mapped
buffer and frees it, if possible.
-
Return Value
============
-On success :ref:`munmap() <dmx-munmap>` returns 0, on failure -1 and the
+On success :c:func:`munmap()` returns 0, on failure -1 and the
``errno`` variable is set appropriately:
EINVAL
diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst
index fcb1c55dd49a..17e70143c1b0 100644
--- a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_QBUF:
@@ -13,27 +14,26 @@ DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver
.. warning:: this API is still experimental
-
Synopsis
========
-.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp )
- :name: DMX_QBUF
+.. c:macro:: DMX_QBUF
-.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp )
- :name: DMX_DQBUF
+``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)``
+.. c:macro:: DMX_DQBUF
+
+``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <dmx_fopen>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dmx_buffer`.
-
Description
===========
@@ -60,13 +60,12 @@ the driver fills the remaining fields or returns an error code.
By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
queue. When the ``O_NONBLOCK`` flag was given to the
-:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns
+:c:func:`open()` function, ``DMX_DQBUF`` returns
immediately with an ``EAGAIN`` error code when no buffer is available.
The struct :c:type:`dmx_buffer` structure is specified in
:ref:`buffer`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst
index df13e2b053c9..08ee9853d6b4 100644
--- a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_QUERYBUF:
@@ -13,24 +14,22 @@ DMX_QUERYBUF - Query the status of a buffer
.. warning:: this API is still experimental
-
Synopsis
========
-.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp )
- :name: DMX_QUERYBUF
+.. c:macro:: DMX_QUERYBUF
+``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <dmx_fopen>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dvb_buffer`.
-
Description
===========
diff --git a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst
index ce408d0d7c77..f75b33e5e49a 100644
--- a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_REMOVE_PID:
@@ -11,24 +12,22 @@ Name
DMX_REMOVE_PID
-
Synopsis
--------
-.. c:function:: int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)
- :name: DMX_REMOVE_PID
+.. c:macro:: DMX_REMOVE_PID
+``int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``pid``
PID of the PES filter to be removed.
-
Description
-----------
@@ -37,7 +36,6 @@ transport stream filter, e. g. a filter previously set up with output
equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`, created via either
:ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst
index 433aed632f92..d2bb1909ec98 100644
--- a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_REQBUFS:
@@ -13,19 +14,18 @@ DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O
.. warning:: this API is still experimental
-
Synopsis
========
-.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp )
- :name: DMX_REQBUFS
+.. c:macro:: DMX_REQBUFS
+``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <dmx_fopen>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dmx_requestbuffers`.
@@ -64,7 +64,6 @@ buffers, however this cannot succeed when any buffers are still mapped.
A ``count`` value of zero frees all buffers, after aborting or finishing
any DMA in progress.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst
index e803cbab220b..13ce4092c2d2 100644
--- a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_SET_BUFFER_SIZE:
@@ -11,19 +12,18 @@ Name
DMX_SET_BUFFER_SIZE
-
Synopsis
--------
-.. c:function:: int ioctl( int fd, DMX_SET_BUFFER_SIZE, unsigned long size)
- :name: DMX_SET_BUFFER_SIZE
+.. c:macro:: DMX_SET_BUFFER_SIZE
+``int ioctl(int fd, DMX_SET_BUFFER_SIZE, unsigned long size)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``size``
Unsigned long size
@@ -36,11 +36,9 @@ filtered data. The default size is two maximum sized sections, i.e. if
this function is not called a buffer size of ``2 * 4096`` bytes will be
used.
-
Return Value
------------
-
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
diff --git a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst
index 4cd3db512b4e..f43455b7adae 100644
--- a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_SET_FILTER:
@@ -11,24 +12,23 @@ Name
DMX_SET_FILTER
-
Synopsis
--------
-.. c:function:: int ioctl( int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)
- :name: DMX_SET_FILTER
+.. c:macro:: DMX_SET_FILTER
+
+``int ioctl(int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``params``
Pointer to structure containing filter parameters.
-
Description
-----------
@@ -43,11 +43,9 @@ operation should be started immediately (without waiting for a
:ref:`DMX_START` ioctl call). If a filter was previously set-up, this
filter will be canceled, and the receive buffer will be flushed.
-
Return Value
------------
-
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
diff --git a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst
index 8e54fd2636ed..5bb682e4a88f 100644
--- a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_SET_PES_FILTER:
@@ -11,25 +12,22 @@ Name
DMX_SET_PES_FILTER
-
Synopsis
--------
-.. c:function:: int ioctl( int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)
- :name: DMX_SET_PES_FILTER
+.. c:macro:: DMX_SET_PES_FILTER
+``int ioctl(int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)``
Arguments
---------
-
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
``params``
Pointer to structure containing filter parameters.
-
Description
-----------
@@ -38,7 +36,6 @@ provided. By a PES filter is meant a filter that is based just on the
packet identifier (PID), i.e. no PES header or payload filtering
capability is supported.
-
Return Value
------------
@@ -54,7 +51,6 @@ appropriately.
:stub-columns: 0
:widths: 1 16
-
- .. row 1
- ``EBUSY``
@@ -64,6 +60,5 @@ appropriately.
Make sure that these filters are stopped before starting this
filter.
-
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/userspace-api/media/dvb/dmx-start.rst b/Documentation/userspace-api/media/dvb/dmx-start.rst
index 6f1413e13936..aedccf952a14 100644
--- a/Documentation/userspace-api/media/dvb/dmx-start.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-start.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_START:
@@ -11,19 +12,18 @@ Name
DMX_START
-
Synopsis
--------
-.. c:function:: int ioctl( int fd, DMX_START)
- :name: DMX_START
+.. c:macro:: DMX_START
+``int ioctl(int fd, DMX_START)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
Description
-----------
@@ -31,7 +31,6 @@ Description
This ioctl call is used to start the actual filtering operation defined
via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`.
-
Return Value
------------
@@ -46,7 +45,6 @@ appropriately.
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EINVAL``
@@ -63,6 +61,5 @@ appropriately.
Make sure that these filters are stopped before starting this
filter.
-
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/userspace-api/media/dvb/dmx-stop.rst b/Documentation/userspace-api/media/dvb/dmx-stop.rst
index cbc3956fd71d..8661e6772104 100644
--- a/Documentation/userspace-api/media/dvb/dmx-stop.rst
+++ b/Documentation/userspace-api/media/dvb/dmx-stop.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.dmx
.. _DMX_STOP:
@@ -11,19 +12,18 @@ Name
DMX_STOP
-
Synopsis
--------
-.. c:function:: int ioctl( int fd, DMX_STOP)
- :name: DMX_STOP
+.. c:macro:: DMX_STOP
+``int ioctl(int fd, DMX_STOP)``
Arguments
---------
``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
+ File descriptor returned by :c:func:`open()`.
Description
-----------
@@ -32,7 +32,6 @@ This ioctl call is used to stop the actual filtering operation defined
via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and
started via the :ref:`DMX_START` command.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst
index 115cced97e66..d9be817f0390 100644
--- a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst
+++ b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_DISEQC_RECV_SLAVE_REPLY:
@@ -11,24 +12,22 @@ Name
FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp )
- :name: FE_DISEQC_RECV_SLAVE_REPLY
+.. c:macro:: FE_DISEQC_RECV_SLAVE_REPLY
+``int ioctl(int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
pointer to struct :c:type:`dvb_diseqc_slave_reply`.
-
Description
===========
diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst
index 5ffc34a6496e..d36f7d1157c6 100644
--- a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst
+++ b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_DISEQC_RESET_OVERLOAD:
@@ -11,19 +12,18 @@ Name
FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_DISEQC_RESET_OVERLOAD, NULL )
- :name: FE_DISEQC_RESET_OVERLOAD
+.. c:macro:: FE_DISEQC_RESET_OVERLOAD
+``int ioctl(int fd, FE_DISEQC_RESET_OVERLOAD, NULL)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
Description
===========
@@ -33,7 +33,6 @@ this ioctl call restores the power to the bus. The call requires
read/write access to the device. This call has no effect if the device
is manually powered off. Not all Digital TV adapters support this ioctl.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst
index fd59afe814f3..8fb73ee29951 100644
--- a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst
+++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_DISEQC_SEND_BURST:
@@ -11,24 +12,22 @@ Name
FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone )
- :name: FE_DISEQC_SEND_BURST
+.. c:macro:: FE_DISEQC_SEND_BURST
+``int ioctl(int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``tone``
An integer enumered value described at :c:type:`fe_sec_mini_cmd`.
-
Description
===========
@@ -39,7 +38,6 @@ read/write permissions.
It provides support for what's specified at
`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst
index faa2a8364e10..c97029def2ee 100644
--- a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst
+++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_DISEQC_SEND_MASTER_CMD:
@@ -11,25 +12,23 @@ Name
FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp )
- :name: FE_DISEQC_SEND_MASTER_CMD
+.. c:macro:: FE_DISEQC_SEND_MASTER_CMD
+``int ioctl(int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
pointer to struct
:c:type:`dvb_diseqc_master_cmd`
-
Description
===========
diff --git a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst
index 60d69bb6da71..d1dba74c55a9 100644
--- a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst
+++ b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_DISHNETWORK_SEND_LEGACY_CMD:
@@ -11,24 +12,22 @@ Name
FE_DISHNETWORK_SEND_LEGACY_CMD
-
Synopsis
========
-.. c:function:: int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)
- :name: FE_DISHNETWORK_SEND_LEGACY_CMD
+.. c:macro:: FE_DISHNETWORK_SEND_LEGACY_CMD
+``int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``cmd``
Sends the specified raw cmd to the dish via DISEqC.
-
Description
===========
@@ -42,7 +41,6 @@ frontend, for Dish Network legacy switches.
As support for this ioctl were added in 2004, this means that such
dishes were already legacy in 2004.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst
index df0cc91384d9..40d7320f82f7 100644
--- a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst
+++ b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_ENABLE_HIGH_LNB_VOLTAGE:
@@ -11,19 +12,18 @@ Name
FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high )
- :name: FE_ENABLE_HIGH_LNB_VOLTAGE
+.. c:macro:: FE_ENABLE_HIGH_LNB_VOLTAGE
+``int ioctl(int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``high``
Valid flags:
@@ -33,7 +33,6 @@ Arguments
- >0 - enables slightly higher voltages instead of 13/18V, in order
to compensate for long antenna cables.
-
Description
===========
@@ -41,7 +40,6 @@ Select output DC level between normal LNBf voltages or higher LNBf
voltages between 0 (normal) or a value grater than 0 for higher
voltages.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-get-event.rst b/Documentation/userspace-api/media/dvb/fe-get-event.rst
index 723bb3a4a630..f63029eca90e 100644
--- a/Documentation/userspace-api/media/dvb/fe-get-event.rst
+++ b/Documentation/userspace-api/media/dvb/fe-get-event.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_GET_EVENT:
@@ -13,24 +14,22 @@ FE_GET_EVENT
.. attention:: This ioctl is deprecated.
-
Synopsis
========
-.. c:function:: int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)
- :name: FE_GET_EVENT
+.. c:macro:: FE_GET_EVENT
+``int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``ev``
Points to the location where the event, if any, is to be stored.
-
Description
===========
@@ -40,7 +39,6 @@ or non-blocking mode. In the latter case, the call fails immediately
with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until
an event becomes available.
-
Return Value
============
@@ -49,12 +47,10 @@ On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
-
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EWOULDBLOCK``
diff --git a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst
index 2bfc1f1a3dc5..40700533e7e7 100644
--- a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst
+++ b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_GET_FRONTEND:
@@ -13,32 +14,28 @@ FE_GET_FRONTEND
.. attention:: This ioctl is deprecated.
-
Synopsis
========
-.. c:function:: int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)
- :name: FE_GET_FRONTEND
+.. c:macro:: FE_GET_FRONTEND
+``int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
-
+ File descriptor returned by :c:func:`open()`.
``p``
Points to parameters for tuning operation.
-
Description
===========
This ioctl call queries the currently effective frontend parameters. For
this command, read-only access to the device is sufficient.
-
Return Value
============
@@ -51,7 +48,6 @@ appropriately.
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EINVAL``
diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst
index eba115c03471..2e5f0209846f 100644
--- a/Documentation/userspace-api/media/dvb/fe-get-info.rst
+++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_GET_INFO:
@@ -12,24 +13,22 @@ Name
FE_GET_INFO - Query Digital TV frontend capabilities and returns information
about the - front-end. This call only requires read-only access to the device.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_GET_INFO, struct dvb_frontend_info *argp )
- :name: FE_GET_INFO
+.. c:macro:: FE_GET_INFO
+``int ioctl(int fd, FE_GET_INFO, struct dvb_frontend_info *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
pointer to struct :c:type:`dvb_frontend_info`
-
Description
===========
@@ -40,7 +39,6 @@ takes a pointer to dvb_frontend_info which is filled by the driver.
When the driver is not compatible with this specification the ioctl
returns an error.
-
frontend capabilities
=====================
@@ -49,7 +47,6 @@ supported only on some specific frontend types.
The frontend capabilities are described at :c:type:`fe_caps`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-get-property.rst b/Documentation/userspace-api/media/dvb/fe-get-property.rst
index 10e1db172d8a..29363dc4a0c3 100644
--- a/Documentation/userspace-api/media/dvb/fe-get-property.rst
+++ b/Documentation/userspace-api/media/dvb/fe-get-property.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_GET_PROPERTY:
@@ -11,27 +12,26 @@ Name
FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_GET_PROPERTY, struct dtv_properties *argp )
- :name: FE_GET_PROPERTY
+.. c:macro:: FE_GET_PROPERTY
-.. c:function:: int ioctl( int fd, FE_SET_PROPERTY, struct dtv_properties *argp )
- :name: FE_SET_PROPERTY
+``int ioctl(int fd, FE_GET_PROPERTY, struct dtv_properties *argp)``
+.. c:macro:: FE_SET_PROPERTY
+
+``int ioctl(int fd, FE_SET_PROPERTY, struct dtv_properties *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dtv_properties`.
-
Description
===========
@@ -63,7 +63,6 @@ depends on the delivery system and on the device:
- This call only requires read-only access to the device.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-read-ber.rst b/Documentation/userspace-api/media/dvb/fe-read-ber.rst
index 2200eb1d06f9..f33f1dd20501 100644
--- a/Documentation/userspace-api/media/dvb/fe-read-ber.rst
+++ b/Documentation/userspace-api/media/dvb/fe-read-ber.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_READ_BER:
@@ -16,20 +17,19 @@ FE_READ_BER
Synopsis
========
-.. c:function:: int ioctl(int fd, FE_READ_BER, uint32_t *ber)
- :name: FE_READ_BER
+.. c:macro:: FE_READ_BER
+``int ioctl(int fd, FE_READ_BER, uint32_t *ber)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``ber``
The bit error rate is stored into \*ber.
-
Description
===========
@@ -37,7 +37,6 @@ This ioctl call returns the bit error rate for the signal currently
received/demodulated by the front-end. For this command, read-only
access to the device is sufficient.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst
index 4832efad2a2e..2b7d06145cb1 100644
--- a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst
+++ b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_READ_SIGNAL_STRENGTH:
@@ -16,20 +17,19 @@ FE_READ_SIGNAL_STRENGTH
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)
- :name: FE_READ_SIGNAL_STRENGTH
+.. c:macro:: FE_READ_SIGNAL_STRENGTH
+``int ioctl(int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``strength``
The signal strength value is stored into \*strength.
-
Description
===========
@@ -37,7 +37,6 @@ This ioctl call returns the signal strength value for the signal
currently received by the front-end. For this command, read-only access
to the device is sufficient.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-read-snr.rst b/Documentation/userspace-api/media/dvb/fe-read-snr.rst
index 141e4fc661c2..e44e559ab7e8 100644
--- a/Documentation/userspace-api/media/dvb/fe-read-snr.rst
+++ b/Documentation/userspace-api/media/dvb/fe-read-snr.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_READ_SNR:
@@ -16,20 +17,19 @@ FE_READ_SNR
Synopsis
========
-.. c:function:: int ioctl(int fd, FE_READ_SNR, int16_t *snr)
- :name: FE_READ_SNR
+.. c:macro:: FE_READ_SNR
+``int ioctl(int fd, FE_READ_SNR, int16_t *snr)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``snr``
The signal-to-noise ratio is stored into \*snr.
-
Description
===========
@@ -37,7 +37,6 @@ This ioctl call returns the signal-to-noise ratio for the signal
currently received by the front-end. For this command, read-only access
to the device is sufficient.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-read-status.rst b/Documentation/userspace-api/media/dvb/fe-read-status.rst
index ba61feb5e535..75c6ee60ac9c 100644
--- a/Documentation/userspace-api/media/dvb/fe-read-status.rst
+++ b/Documentation/userspace-api/media/dvb/fe-read-status.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_READ_STATUS:
@@ -11,25 +12,23 @@ Name
FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_READ_STATUS, unsigned int *status )
- :name: FE_READ_STATUS
+.. c:macro:: FE_READ_STATUS
+``int ioctl(int fd, FE_READ_STATUS, unsigned int *status)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``status``
pointer to a bitmask integer filled with the values defined by enum
:c:type:`fe_status`.
-
Description
===========
@@ -44,7 +43,6 @@ written.
varies according with the architecture. This needs to be fixed in the
future.
-
int fe_status
=============
@@ -52,7 +50,6 @@ The fe_status parameter is used to indicate the current state and/or
state changes of the frontend hardware. It is produced using the enum
:c:type:`fe_status` values on a bitmask
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst
index bf9746f8a671..653cd99a66f5 100644
--- a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst
+++ b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_READ_UNCORRECTED_BLOCKS:
@@ -16,20 +17,19 @@ FE_READ_UNCORRECTED_BLOCKS
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)
- :name: FE_READ_UNCORRECTED_BLOCKS
+.. c:macro:: FE_READ_UNCORRECTED_BLOCKS
+``int ioctl(int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``ublocks``
The total number of uncorrected blocks seen by the driver so far.
-
Description
===========
@@ -39,7 +39,6 @@ increment in block count during a specific time interval should be
calculated. For this command, read-only access to the device is
sufficient.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst
index f0e178e3a180..56923c1a66b0 100644
--- a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst
+++ b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_SET_FRONTEND_TUNE_MODE:
@@ -11,19 +12,18 @@ Name
FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags )
- :name: FE_SET_FRONTEND_TUNE_MODE
+.. c:macro:: FE_SET_FRONTEND_TUNE_MODE
+``int ioctl(int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``flags``
Valid flags:
@@ -37,14 +37,12 @@ Arguments
is closed, this flag will be automatically turned off when the
device is reopened read-write.
-
Description
===========
Allow setting tuner mode flags to the frontend, between 0 (normal) or
``FE_TUNE_MODE_ONESHOT`` mode
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst
index 2b169778e0d6..d1b857632059 100644
--- a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst
+++ b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_SET_FRONTEND:
@@ -13,24 +14,22 @@ Name
FE_SET_FRONTEND
-
Synopsis
========
-.. c:function:: int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p)
- :name: FE_SET_FRONTEND
+.. c:macro:: FE_SET_FRONTEND
+``int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
+ File descriptor returned by :c:func:`open()`.
``p``
Points to parameters for tuning operation.
-
Description
===========
@@ -44,7 +43,6 @@ operation is initiated before the previous one was completed, the
previous operation will be aborted in favor of the new one. This command
requires read/write access to the device.
-
Return Value
============
@@ -66,6 +64,5 @@ appropriately.
- Maximum supported symbol rate reached.
-
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/userspace-api/media/dvb/fe-set-tone.rst b/Documentation/userspace-api/media/dvb/fe-set-tone.rst
index 944d54488e71..9f44bf946183 100644
--- a/Documentation/userspace-api/media/dvb/fe-set-tone.rst
+++ b/Documentation/userspace-api/media/dvb/fe-set-tone.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_SET_TONE:
@@ -11,24 +12,22 @@ Name
FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode tone )
- :name: FE_SET_TONE
+.. c:macro:: FE_SET_TONE
+``int ioctl(int fd, FE_SET_TONE, enum fe_sec_tone_mode tone)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``tone``
an integer enumered value described at :c:type:`fe_sec_tone_mode`
-
Description
===========
@@ -45,7 +44,6 @@ this is done using the DiSEqC ioctls.
capability of selecting the band. So, it is recommended that applications
would change to SEC_TONE_OFF when the device is not used.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst
index 73740be0e7dc..c66771830be1 100644
--- a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst
+++ b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _FE_SET_VOLTAGE:
@@ -11,24 +12,22 @@ Name
FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage )
- :name: FE_SET_VOLTAGE
+.. c:macro:: FE_SET_VOLTAGE
+``int ioctl(int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``voltage``
an integer enumered value described at :c:type:`fe_sec_voltage`
-
Description
===========
@@ -49,7 +48,6 @@ power up the LNBf.
the voltage to SEC_VOLTAGE_OFF while the device is not is used is
recommended.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/frontend_f_close.rst b/Documentation/userspace-api/media/dvb/frontend_f_close.rst
index 96e15b4ee76d..52c323a85014 100644
--- a/Documentation/userspace-api/media/dvb/frontend_f_close.rst
+++ b/Documentation/userspace-api/media/dvb/frontend_f_close.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _frontend_f_close:
@@ -11,7 +12,6 @@ Name
fe-close - Close a frontend device
-
Synopsis
========
@@ -19,16 +19,13 @@ Synopsis
#include <unistd.h>
-
.. c:function:: int close( int fd )
- :name: dvb-fe-close
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <dvb-fe-open>`.
-
+ File descriptor returned by :c:func:`open()`.
Description
===========
@@ -37,7 +34,6 @@ This system call closes a previously opened front-end device. After
closing a front-end device, its corresponding hardware might be powered
down automatically.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/frontend_f_open.rst b/Documentation/userspace-api/media/dvb/frontend_f_open.rst
index 49a01dd58d03..bb37eded0870 100644
--- a/Documentation/userspace-api/media/dvb/frontend_f_open.rst
+++ b/Documentation/userspace-api/media/dvb/frontend_f_open.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.fe
.. _frontend_f_open:
@@ -11,7 +12,6 @@ Name
fe-open - Open a frontend device
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <fcntl.h>
-
.. c:function:: int open( const char *device_name, int flags )
- :name: dvb-fe-open
Arguments
=========
@@ -44,7 +42,6 @@ Arguments
Other flags have no effect.
-
Description
===========
@@ -70,16 +67,14 @@ the specified mode. This implies that the corresponding hardware is
powered up, and that other front-ends may have been powered down to make
that possible.
-
Return Value
============
-On success :ref:`open() <frontend_f_open>` returns the new file descriptor.
+On success :c:func:`open()` returns the new file descriptor.
On error, -1 is returned, and the ``errno`` variable is set appropriately.
Possible error codes are:
-
On success 0 is returned, and :c:type:`ca_slot_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
@@ -105,6 +100,5 @@ appropriately.
- The limit on the total number of files open on the system has been
reached.
-
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/userspace-api/media/dvb/net-add-if.rst b/Documentation/userspace-api/media/dvb/net-add-if.rst
index 0859830b645e..022b4c626249 100644
--- a/Documentation/userspace-api/media/dvb/net-add-if.rst
+++ b/Documentation/userspace-api/media/dvb/net-add-if.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.net
.. _NET_ADD_IF:
@@ -11,24 +12,22 @@ Name
NET_ADD_IF - Creates a new network interface for a given Packet ID.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, NET_ADD_IF, struct dvb_net_if *net_if )
- :name: NET_ADD_IF
+.. c:macro:: NET_ADD_IF
+``int ioctl(int fd, NET_ADD_IF, struct dvb_net_if *net_if)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``net_if``
pointer to struct :c:type:`dvb_net_if`
-
Description
===========
diff --git a/Documentation/userspace-api/media/dvb/net-get-if.rst b/Documentation/userspace-api/media/dvb/net-get-if.rst
index d8c9f939d62c..e99696c9db74 100644
--- a/Documentation/userspace-api/media/dvb/net-get-if.rst
+++ b/Documentation/userspace-api/media/dvb/net-get-if.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.net
.. _NET_GET_IF:
@@ -11,24 +12,22 @@ Name
NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, NET_GET_IF, struct dvb_net_if *net_if )
- :name: NET_GET_IF
+.. c:macro:: NET_GET_IF
+``int ioctl(int fd, NET_GET_IF, struct dvb_net_if *net_if)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``net_if``
pointer to struct :c:type:`dvb_net_if`
-
Description
===========
@@ -39,7 +38,6 @@ encapsulation type used on such interface. If the interface was not
created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill
the ``errno`` with ``EINVAL`` error code.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/net-remove-if.rst b/Documentation/userspace-api/media/dvb/net-remove-if.rst
index ecbcacbaf9f7..ac88691c0423 100644
--- a/Documentation/userspace-api/media/dvb/net-remove-if.rst
+++ b/Documentation/userspace-api/media/dvb/net-remove-if.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.net
.. _NET_REMOVE_IF:
@@ -11,31 +12,28 @@ Name
NET_REMOVE_IF - Removes a network interface.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, NET_REMOVE_IF, int ifnum )
- :name: NET_REMOVE_IF
+.. c:macro:: NET_REMOVE_IF
+``int ioctl(int fd, NET_REMOVE_IF, int ifnum)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
+ File descriptor returned by :c:func:`open()`.
``net_if``
number of the interface to be removed
-
Description
===========
The NET_REMOVE_IF ioctl deletes an interface previously created via
:ref:`NET_ADD_IF <net>`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/dvb/video-clear-buffer.rst b/Documentation/userspace-api/media/dvb/video-clear-buffer.rst
index fa1f2f49bdac..a7730559bbb2 100644
--- a/Documentation/userspace-api/media/dvb/video-clear-buffer.rst
+++ b/Documentation/userspace-api/media/dvb/video-clear-buffer.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_CLEAR_BUFFER:
@@ -16,9 +17,9 @@ VIDEO_CLEAR_BUFFER
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_CLEAR_BUFFER)
- :name: VIDEO_CLEAR_BUFFER
+.. c:macro:: VIDEO_CLEAR_BUFFER
+``int ioctl(fd, VIDEO_CLEAR_BUFFER)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -40,14 +40,12 @@ Arguments
- Equals VIDEO_CLEAR_BUFFER for this command.
-
Description
-----------
This ioctl call clears all video buffers in the driver and in the
decoder hardware.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-command.rst b/Documentation/userspace-api/media/dvb/video-command.rst
index ef0da85d5f92..cae9445eb3af 100644
--- a/Documentation/userspace-api/media/dvb/video-command.rst
+++ b/Documentation/userspace-api/media/dvb/video-command.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_COMMAND:
@@ -16,9 +17,9 @@ VIDEO_COMMAND
Synopsis
--------
-.. c:function:: int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd)
- :name: VIDEO_COMMAND
+.. c:macro:: VIDEO_COMMAND
+``int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Commands the decoder.
-
Description
-----------
@@ -59,7 +58,7 @@ subset of the ``v4l2_decoder_cmd`` struct, so refer to the
:ref:`VIDIOC_DECODER_CMD` documentation for
more information.
-.. c:type:: struct video_command
+.. c:type:: video_command
.. code-block:: c
@@ -89,7 +88,6 @@ more information.
};
};
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-continue.rst b/Documentation/userspace-api/media/dvb/video-continue.rst
index 9a767b50b23b..bc34bf3989e4 100644
--- a/Documentation/userspace-api/media/dvb/video-continue.rst
+++ b/Documentation/userspace-api/media/dvb/video-continue.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_CONTINUE:
@@ -16,9 +17,9 @@ VIDEO_CONTINUE
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_CONTINUE)
- :name: VIDEO_CONTINUE
+.. c:macro:: VIDEO_CONTINUE
+``int ioctl(fd, VIDEO_CONTINUE)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -40,7 +40,6 @@ Arguments
- Equals VIDEO_CONTINUE for this command.
-
Description
-----------
@@ -50,7 +49,6 @@ V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
This ioctl call restarts decoding and playing processes of the video
stream which was played before a call to VIDEO_FREEZE was made.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-fast-forward.rst b/Documentation/userspace-api/media/dvb/video-fast-forward.rst
index c43a13c7ae75..e71fa8d6965b 100644
--- a/Documentation/userspace-api/media/dvb/video-fast-forward.rst
+++ b/Documentation/userspace-api/media/dvb/video-fast-forward.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_FAST_FORWARD:
@@ -16,9 +17,9 @@ VIDEO_FAST_FORWARD
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames)
- :name: VIDEO_FAST_FORWARD
+.. c:macro:: VIDEO_FAST_FORWARD
+``int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- The number of frames to skip.
-
Description
-----------
@@ -54,7 +53,6 @@ This ioctl call asks the Video Device to skip decoding of N number of
I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
selected.
-
Return Value
------------
@@ -63,12 +61,10 @@ appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
-
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EPERM``
diff --git a/Documentation/userspace-api/media/dvb/video-fclose.rst b/Documentation/userspace-api/media/dvb/video-fclose.rst
index 27ccb2d6f961..01d24d548439 100644
--- a/Documentation/userspace-api/media/dvb/video-fclose.rst
+++ b/Documentation/userspace-api/media/dvb/video-fclose.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _video_fclose:
@@ -18,7 +19,6 @@ Synopsis
.. c:function:: int close(int fd)
-
Arguments
---------
@@ -26,20 +26,17 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
-
Description
-----------
This system call closes a previously opened video device.
-
Return Value
------------
@@ -47,7 +44,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EBADF``
diff --git a/Documentation/userspace-api/media/dvb/video-fopen.rst b/Documentation/userspace-api/media/dvb/video-fopen.rst
index aa1dc6020fa7..1371b083e4e8 100644
--- a/Documentation/userspace-api/media/dvb/video-fopen.rst
+++ b/Documentation/userspace-api/media/dvb/video-fopen.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _video_fopen:
@@ -18,7 +19,6 @@ Synopsis
.. c:function:: int open(const char *deviceName, int flags)
-
Arguments
---------
@@ -26,7 +26,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- const char \*deviceName
@@ -59,7 +58,6 @@ Arguments
-
- (blocking mode is the default)
-
Description
-----------
@@ -79,7 +77,6 @@ returned. If the Video Device is opened in O_RDONLY mode, the only
ioctl call that can be used is VIDEO_GET_STATUS. All other call will
return an error code.
-
Return Value
------------
@@ -89,7 +86,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``ENODEV``
diff --git a/Documentation/userspace-api/media/dvb/video-freeze.rst b/Documentation/userspace-api/media/dvb/video-freeze.rst
index 93e0ae8e79d8..4321f257cb70 100644
--- a/Documentation/userspace-api/media/dvb/video-freeze.rst
+++ b/Documentation/userspace-api/media/dvb/video-freeze.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_FREEZE:
@@ -16,9 +17,9 @@ VIDEO_FREEZE
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_FREEZE)
- :name: VIDEO_FREEZE
+.. c:macro:: VIDEO_FREEZE
+``int ioctl(fd, VIDEO_FREEZE)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -40,7 +40,6 @@ Arguments
- Equals VIDEO_FREEZE for this command.
-
Description
-----------
@@ -54,7 +53,6 @@ If VIDEO_SOURCE_MEMORY is selected in the ioctl call
VIDEO_SELECT_SOURCE, the Digital TV subsystem will not decode any more data
until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-fwrite.rst b/Documentation/userspace-api/media/dvb/video-fwrite.rst
index 5ccdf78f11e1..a07fd7d7a40e 100644
--- a/Documentation/userspace-api/media/dvb/video-fwrite.rst
+++ b/Documentation/userspace-api/media/dvb/video-fwrite.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _video_fwrite:
@@ -18,7 +19,6 @@ Synopsis
.. c:function:: size_t write(int fd, const void *buf, size_t count)
-
Arguments
---------
@@ -26,7 +26,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -45,7 +44,6 @@ Arguments
- Size of buf.
-
Description
-----------
@@ -55,7 +53,6 @@ PES format, unless the capability allows other formats. If O_NONBLOCK
is not specified the function will block until buffer space is
available. The amount of data to be transferred is implied by count.
-
Return Value
------------
@@ -63,7 +60,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EPERM``
diff --git a/Documentation/userspace-api/media/dvb/video-get-capabilities.rst b/Documentation/userspace-api/media/dvb/video-get-capabilities.rst
index 619f78a66b6c..01e09f56656c 100644
--- a/Documentation/userspace-api/media/dvb/video-get-capabilities.rst
+++ b/Documentation/userspace-api/media/dvb/video-get-capabilities.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_GET_CAPABILITIES:
@@ -16,9 +17,9 @@ VIDEO_GET_CAPABILITIES
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap)
- :name: VIDEO_GET_CAPABILITIES
+.. c:macro:: VIDEO_GET_CAPABILITIES
+``int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Pointer to a location where to store the capability information.
-
Description
-----------
@@ -54,7 +53,6 @@ This ioctl call asks the video device about its decoding capabilities.
On success it returns and integer which has bits set according to the
defines in section ??.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-get-event.rst b/Documentation/userspace-api/media/dvb/video-get-event.rst
index 29566a245fcd..90382bc36cfe 100644
--- a/Documentation/userspace-api/media/dvb/video-get-event.rst
+++ b/Documentation/userspace-api/media/dvb/video-get-event.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_GET_EVENT:
@@ -16,9 +17,9 @@ VIDEO_GET_EVENT
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev)
- :name: VIDEO_GET_EVENT
+.. c:macro:: VIDEO_GET_EVENT
+``int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Points to the location where the event, if any, is to be stored.
-
Description
-----------
@@ -93,7 +92,6 @@ appropriately. The generic error codes are described at the
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EWOULDBLOCK``
diff --git a/Documentation/userspace-api/media/dvb/video-get-frame-count.rst b/Documentation/userspace-api/media/dvb/video-get-frame-count.rst
index 5f65f8dba184..b48ac8c58a41 100644
--- a/Documentation/userspace-api/media/dvb/video-get-frame-count.rst
+++ b/Documentation/userspace-api/media/dvb/video-get-frame-count.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_GET_FRAME_COUNT:
@@ -16,9 +17,9 @@ VIDEO_GET_FRAME_COUNT
Synopsis
--------
-.. c:function:: int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts)
- :name: VIDEO_GET_FRAME_COUNT
+.. c:macro:: VIDEO_GET_FRAME_COUNT
+``int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -47,7 +47,6 @@ Arguments
- Returns the number of frames displayed since the decoder was
started.
-
Description
-----------
@@ -58,7 +57,6 @@ control.
This ioctl call asks the Video Device to return the number of displayed
frames since the decoder was started.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-get-pts.rst b/Documentation/userspace-api/media/dvb/video-get-pts.rst
index 28655a1a9249..fedaff41be0b 100644
--- a/Documentation/userspace-api/media/dvb/video-get-pts.rst
+++ b/Documentation/userspace-api/media/dvb/video-get-pts.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_GET_PTS:
@@ -16,9 +17,9 @@ VIDEO_GET_PTS
Synopsis
--------
-.. c:function:: int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts)
- :name: VIDEO_GET_PTS
+.. c:macro:: VIDEO_GET_PTS
+``int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -51,7 +51,6 @@ Arguments
but may also be a value close to it like the PTS of the last
decoded frame or the last PTS extracted by the PES parser.
-
Description
-----------
@@ -62,7 +61,6 @@ control.
This ioctl call asks the Video Device to return the current PTS
timestamp.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-get-size.rst b/Documentation/userspace-api/media/dvb/video-get-size.rst
index a199afbfc1b1..de34331c5bd1 100644
--- a/Documentation/userspace-api/media/dvb/video-get-size.rst
+++ b/Documentation/userspace-api/media/dvb/video-get-size.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_GET_SIZE:
@@ -16,9 +17,9 @@ VIDEO_GET_SIZE
Synopsis
--------
-.. c:function:: int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size)
- :name: VIDEO_GET_SIZE
+.. c:macro:: VIDEO_GET_SIZE
+``int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Returns the size and aspect ratio.
-
Description
-----------
@@ -62,7 +61,6 @@ This ioctl returns the size and aspect ratio.
video_format_t aspect_ratio;
} video_size_t;
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-get-status.rst b/Documentation/userspace-api/media/dvb/video-get-status.rst
index 3f29dac18a21..9b86fbf411d4 100644
--- a/Documentation/userspace-api/media/dvb/video-get-status.rst
+++ b/Documentation/userspace-api/media/dvb/video-get-status.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_GET_STATUS:
@@ -16,9 +17,9 @@ VIDEO_GET_STATUS
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status)
- :name: VIDEO_GET_STATUS
+.. c:macro:: VIDEO_GET_STATUS
+``int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Returns the current status of the Video Device.
-
Description
-----------
diff --git a/Documentation/userspace-api/media/dvb/video-play.rst b/Documentation/userspace-api/media/dvb/video-play.rst
index 71db54d840cb..35ac8b98fdbf 100644
--- a/Documentation/userspace-api/media/dvb/video-play.rst
+++ b/Documentation/userspace-api/media/dvb/video-play.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_PLAY:
@@ -16,9 +17,9 @@ VIDEO_PLAY
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_PLAY)
- :name: VIDEO_PLAY
+.. c:macro:: VIDEO_PLAY
+``int ioctl(fd, VIDEO_PLAY)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -40,7 +40,6 @@ Arguments
- Equals VIDEO_PLAY for this command.
-
Description
-----------
@@ -50,7 +49,6 @@ V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
This ioctl call asks the Video Device to start playing a video stream
from the selected source.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-select-source.rst b/Documentation/userspace-api/media/dvb/video-select-source.rst
index 2e4ee53fa155..929a20985d53 100644
--- a/Documentation/userspace-api/media/dvb/video-select-source.rst
+++ b/Documentation/userspace-api/media/dvb/video-select-source.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_SELECT_SOURCE:
@@ -16,9 +17,9 @@ VIDEO_SELECT_SOURCE
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)
- :name: VIDEO_SELECT_SOURCE
+.. c:macro:: VIDEO_SELECT_SOURCE
+``int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Indicates which source shall be used for the Video stream.
-
Description
-----------
diff --git a/Documentation/userspace-api/media/dvb/video-set-blank.rst b/Documentation/userspace-api/media/dvb/video-set-blank.rst
index 5454fe7905bd..70249a6ba125 100644
--- a/Documentation/userspace-api/media/dvb/video-set-blank.rst
+++ b/Documentation/userspace-api/media/dvb/video-set-blank.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_SET_BLANK:
@@ -16,9 +17,9 @@ VIDEO_SET_BLANK
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_SET_BLANK, boolean mode)
- :name: VIDEO_SET_BLANK
+.. c:macro:: VIDEO_SET_BLANK
+``int ioctl(fd, VIDEO_SET_BLANK, boolean mode)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -51,13 +51,11 @@ Arguments
-
- FALSE: Show last decoded frame.
-
Description
-----------
This ioctl call asks the Video Device to blank out the picture.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-set-display-format.rst b/Documentation/userspace-api/media/dvb/video-set-display-format.rst
index ada6113e2f2d..1de4f40ae732 100644
--- a/Documentation/userspace-api/media/dvb/video-set-display-format.rst
+++ b/Documentation/userspace-api/media/dvb/video-set-display-format.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_SET_DISPLAY_FORMAT:
@@ -16,9 +17,9 @@ VIDEO_SET_DISPLAY_FORMAT
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT)
- :name: VIDEO_SET_DISPLAY_FORMAT
+.. c:macro:: VIDEO_SET_DISPLAY_FORMAT
+``int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,14 +46,12 @@ Arguments
- Selects the video format to be used.
-
Description
-----------
This ioctl call asks the Video Device to select the video format to be
applied by the MPEG chip on the video.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-set-format.rst b/Documentation/userspace-api/media/dvb/video-set-format.rst
index 758a5d1642ab..bb64e37ae081 100644
--- a/Documentation/userspace-api/media/dvb/video-set-format.rst
+++ b/Documentation/userspace-api/media/dvb/video-set-format.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_SET_FORMAT:
@@ -16,9 +17,9 @@ VIDEO_SET_FORMAT
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format)
- :name: VIDEO_SET_FORMAT
+.. c:macro:: VIDEO_SET_FORMAT
+``int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- video format of TV as defined in section ??.
-
Description
-----------
@@ -72,12 +71,10 @@ appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
-
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EINVAL``
diff --git a/Documentation/userspace-api/media/dvb/video-set-streamtype.rst b/Documentation/userspace-api/media/dvb/video-set-streamtype.rst
index f3a99858b1db..1f31c048bdbc 100644
--- a/Documentation/userspace-api/media/dvb/video-set-streamtype.rst
+++ b/Documentation/userspace-api/media/dvb/video-set-streamtype.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_SET_STREAMTYPE:
@@ -16,9 +17,9 @@ VIDEO_SET_STREAMTYPE
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_SET_STREAMTYPE, int type)
- :name: VIDEO_SET_STREAMTYPE
+.. c:macro:: VIDEO_SET_STREAMTYPE
+``int ioctl(fd, VIDEO_SET_STREAMTYPE, int type)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- stream type
-
Description
-----------
@@ -54,7 +53,6 @@ This ioctl tells the driver which kind of stream to expect being written
to it. If this call is not used the default of video PES is used. Some
drivers might not support this call and always expect PES.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-slowmotion.rst b/Documentation/userspace-api/media/dvb/video-slowmotion.rst
index 2ccb84d6a68b..1478fcc30cb8 100644
--- a/Documentation/userspace-api/media/dvb/video-slowmotion.rst
+++ b/Documentation/userspace-api/media/dvb/video-slowmotion.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_SLOWMOTION:
@@ -16,9 +17,9 @@ VIDEO_SLOWMOTION
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_SLOWMOTION, int nFrames)
- :name: VIDEO_SLOWMOTION
+.. c:macro:: VIDEO_SLOWMOTION
+``int ioctl(fd, VIDEO_SLOWMOTION, int nFrames)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- The number of times to repeat each frame.
-
Description
-----------
@@ -54,7 +53,6 @@ This ioctl call asks the video device to repeat decoding frames N number
of times. This call can only be used if VIDEO_SOURCE_MEMORY is
selected.
-
Return Value
------------
@@ -63,12 +61,10 @@ appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
-
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``EPERM``
diff --git a/Documentation/userspace-api/media/dvb/video-stillpicture.rst b/Documentation/userspace-api/media/dvb/video-stillpicture.rst
index a04f9f3ed162..d25384222a20 100644
--- a/Documentation/userspace-api/media/dvb/video-stillpicture.rst
+++ b/Documentation/userspace-api/media/dvb/video-stillpicture.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_STILLPICTURE:
@@ -16,9 +17,9 @@ VIDEO_STILLPICTURE
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp)
- :name: VIDEO_STILLPICTURE
+.. c:macro:: VIDEO_STILLPICTURE
+``int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Pointer to a location where an I-frame and size is stored.
-
Description
-----------
@@ -54,7 +53,6 @@ This ioctl call asks the Video Device to display a still picture
(I-frame). The input data shall contain an I-frame. If the pointer is
NULL, then the current displayed still picture is blanked.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-stop.rst b/Documentation/userspace-api/media/dvb/video-stop.rst
index 9318655dce23..96f61c5b48a2 100644
--- a/Documentation/userspace-api/media/dvb/video-stop.rst
+++ b/Documentation/userspace-api/media/dvb/video-stop.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_STOP:
@@ -16,9 +17,9 @@ VIDEO_STOP
Synopsis
--------
-.. c:function:: int ioctl(fd, VIDEO_STOP, boolean mode)
- :name: VIDEO_STOP
+.. c:macro:: VIDEO_STOP
+``int ioctl(fd, VIDEO_STOP, boolean mode)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -56,7 +56,6 @@ Arguments
-
- FALSE: Show last decoded frame.
-
Description
-----------
@@ -67,7 +66,6 @@ This ioctl call asks the Video Device to stop playing the current
stream. Depending on the input parameter, the screen can be blanked out
or displaying the last decoded frame.
-
Return Value
------------
diff --git a/Documentation/userspace-api/media/dvb/video-try-command.rst b/Documentation/userspace-api/media/dvb/video-try-command.rst
index 430c36035329..79bf3dfb8a32 100644
--- a/Documentation/userspace-api/media/dvb/video-try-command.rst
+++ b/Documentation/userspace-api/media/dvb/video-try-command.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: DTV.video
.. _VIDEO_TRY_COMMAND:
@@ -16,9 +17,9 @@ VIDEO_TRY_COMMAND
Synopsis
--------
-.. c:function:: int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd)
- :name: VIDEO_TRY_COMMAND
+.. c:macro:: VIDEO_TRY_COMMAND
+``int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd)``
Arguments
---------
@@ -27,7 +28,6 @@ Arguments
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- int fd
@@ -46,7 +46,6 @@ Arguments
- Try a decoder command.
-
Description
-----------
@@ -59,7 +58,6 @@ subset of the ``v4l2_decoder_cmd`` struct, so refer to the
:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
for more information.
-
Return Value
------------
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 15/52] media: docs: make MC documents more compatible with Sphinx 3.1+
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (13 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 14/52] media: docs: make DVB " Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 16/52] media: docs: make RC " Mauro Carvalho Chehab
` (37 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Alexandre Courbot, Hans Verkuil,
Mauro Carvalho Chehab, linux-kernel, linux-media
Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../media/mediactl/media-func-close.rst | 10 +++-------
.../media/mediactl/media-func-ioctl.rst | 10 +++-------
.../media/mediactl/media-func-open.rst | 10 +++-------
.../media/mediactl/media-ioc-device-info.rst | 13 ++++---------
.../media/mediactl/media-ioc-enum-entities.rst | 11 ++++-------
.../media/mediactl/media-ioc-enum-links.rst | 13 ++++---------
.../media/mediactl/media-ioc-g-topology.rst | 14 ++++----------
.../media/mediactl/media-ioc-request-alloc.rst | 11 +++++------
.../media/mediactl/media-ioc-setup-link.rst | 10 ++++------
.../media/mediactl/media-request-ioc-queue.rst | 7 +++----
.../media/mediactl/media-request-ioc-reinit.rst | 8 ++++----
.../userspace-api/media/mediactl/request-api.rst | 5 +++--
.../media/mediactl/request-func-close.rst | 8 ++------
.../media/mediactl/request-func-ioctl.rst | 8 ++------
.../media/mediactl/request-func-poll.rst | 12 ++++--------
15 files changed, 52 insertions(+), 98 deletions(-)
diff --git a/Documentation/userspace-api/media/mediactl/media-func-close.rst b/Documentation/userspace-api/media/mediactl/media-func-close.rst
index ec571b34ce69..8ac2443e76c1 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-close.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-close.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media-func-close:
@@ -11,7 +12,6 @@ Name
media-close - Close a media device
-
Synopsis
========
@@ -19,16 +19,13 @@ Synopsis
#include <unistd.h>
-
.. c:function:: int close( int fd )
- :name: mc-close
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <mc-open>`.
-
+ File descriptor returned by :c:func:`open()`.
Description
===========
@@ -36,11 +33,10 @@ Description
Closes the media device. Resources associated with the file descriptor
are freed. The device configuration remain unchanged.
-
Return Value
============
-:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:
EBADF
diff --git a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
index 35ed549bec0e..9e9a838f4795 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media-func-ioctl:
@@ -11,7 +12,6 @@ Name
media-ioctl - Control a media device
-
Synopsis
========
@@ -19,15 +19,13 @@ Synopsis
#include <sys/ioctl.h>
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
- :name: mc-ioctl
+``int ioctl(int fd, int request, void *argp)``
Arguments
=========
``fd``
- File descriptor returned by :c:func:`open() <mc-open>`.
+ File descriptor returned by :c:func:`open()`.
``request``
Media ioctl request code as defined in the media.h header file, for
@@ -36,7 +34,6 @@ Arguments
``argp``
Pointer to a request-specific structure.
-
Description
===========
@@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All media ioctl
requests, their respective function and parameters are specified in
:ref:`media-user-func`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/media-func-open.rst b/Documentation/userspace-api/media/mediactl/media-func-open.rst
index 2c2595157ea3..24487cb0a308 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-open.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-open.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media-func-open:
@@ -11,7 +12,6 @@ Name
media-open - Open a media device
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <fcntl.h>
-
.. c:function:: int open( const char *device_name, int flags )
- :name: mc-open
Arguments
=========
@@ -33,11 +31,10 @@ Arguments
Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
Other flags have no effect.
-
Description
===========
-To open a media device applications call :ref:`open() <media-func-open>` with the
+To open a media device applications call :c:func:`open()` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.
@@ -45,11 +42,10 @@ When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.
-
Return Value
============
-:ref:`open() <func-open>` returns the new file descriptor on success. On error,
+:c:func:`open()` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
are:
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
index cde1ddfc0bfb..0c4c5d2cfcb2 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_ioc_device_info:
@@ -11,24 +12,22 @@ Name
MEDIA_IOC_DEVICE_INFO - Query device information
-
Synopsis
========
-.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp )
- :name: MEDIA_IOC_DEVICE_INFO
+.. c:macro:: MEDIA_IOC_DEVICE_INFO
+``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_device_info`.
-
Description
===========
@@ -38,7 +37,6 @@ a struct :c:type:`media_device_info`. The driver
fills the structure and returns the information to the application. The
ioctl never fails.
-
.. c:type:: media_device_info
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -48,7 +46,6 @@ ioctl never fails.
:stub-columns: 0
:widths: 1 1 2
-
* - char
- ``driver``\ [16]
- Name of the driver implementing the media API as a NUL-terminated
@@ -94,7 +91,6 @@ ioctl never fails.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
-
The ``serial`` and ``bus_info`` fields can be used to distinguish
between multiple instances of otherwise identical hardware. The serial
number takes precedence when provided and can be assumed to be unique.
@@ -102,7 +98,6 @@ If the serial number is an empty string, the ``bus_info`` field can be
used instead. The ``bus_info`` field is guaranteed to be unique, but can
vary across reboots or device unplug/replug.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
index 93e35f198f47..92dd8ecd538c 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_ioc_enum_entities:
@@ -11,24 +12,22 @@ Name
MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
-
Synopsis
========
-.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp )
- :name: MEDIA_IOC_ENUM_ENTITIES
+.. c:macro:: MEDIA_IOC_ENUM_ENTITIES
+``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_entity_desc`.
-
Description
===========
@@ -49,7 +48,6 @@ Entity IDs can be non-contiguous. Applications must *not* try to
enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
id's until they get an error.
-
.. c:type:: media_entity_desc
.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}|
@@ -136,7 +134,6 @@ id's until they get an error.
* - }
-
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
index f3e94c7b5dc3..3bc98a6a2ec5 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_ioc_enum_links:
@@ -11,24 +12,22 @@ Name
MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
-
Synopsis
========
-.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
- :name: MEDIA_IOC_ENUM_LINKS
+.. c:macro:: MEDIA_IOC_ENUM_LINKS
+``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_links_enum`.
-
Description
===========
@@ -53,7 +52,6 @@ outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
Only forward links that originate at one of the entity's source pads are
returned during the enumeration process.
-
.. c:type:: media_links_enum
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -82,7 +80,6 @@ returned during the enumeration process.
- Reserved for future extensions. Drivers and applications must set
the array to zero.
-
.. c:type:: media_pad_desc
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -110,7 +107,6 @@ returned during the enumeration process.
the array to zero.
-
.. c:type:: media_link_desc
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -137,7 +133,6 @@ returned during the enumeration process.
- Reserved for future extensions. Drivers and applications must set
the array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
index 9b7d2296b7fd..8f8b3b586edd 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_ioc_g_topology:
@@ -11,24 +12,22 @@ Name
MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
-
Synopsis
========
-.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
- :name: MEDIA_IOC_G_TOPOLOGY
+.. c:macro:: MEDIA_IOC_G_TOPOLOGY
+``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_v2_topology`.
-
Description
===========
@@ -120,7 +119,6 @@ desired arrays with the media graph elements.
converted to a 64-bits integer. It can be zero. if zero, the ioctl
won't store the links. It will just update ``num_links``
-
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_entity
@@ -158,7 +156,6 @@ desired arrays with the media graph elements.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
-
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_interface
@@ -192,7 +189,6 @@ desired arrays with the media graph elements.
- Used only for device node interfaces. See
:c:type:`media_v2_intf_devnode` for details.
-
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_intf_devnode
@@ -245,7 +241,6 @@ desired arrays with the media graph elements.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
-
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_link
@@ -282,7 +277,6 @@ desired arrays with the media graph elements.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
index ea05ff0c5382..9195b4b8bf20 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_ioc_request_alloc:
@@ -11,24 +12,22 @@ Name
MEDIA_IOC_REQUEST_ALLOC - Allocate a request
-
Synopsis
========
-.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )
- :name: MEDIA_IOC_REQUEST_ALLOC
+.. c:macro:: MEDIA_IOC_REQUEST_ALLOC
+``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
-
Description
===========
@@ -51,7 +50,7 @@ Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
for the request to complete.
The request will remain allocated until all the file descriptors associated
-with it are closed by :ref:`close() <request-func-close>` and the driver no
+with it are closed by :c:func:`close()` and the driver no
longer uses the request internally. See also
:ref:`here <media-request-life-time>` for more information.
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
index e2aa51015783..23208300cb61 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_ioc_setup_link:
@@ -11,24 +12,22 @@ Name
MEDIA_IOC_SETUP_LINK - Modify the properties of a link
-
Synopsis
========
-.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp )
- :name: MEDIA_IOC_SETUP_LINK
+.. c:macro:: MEDIA_IOC_SETUP_LINK
+``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)``
Arguments
=========
``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
+ File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_link_desc`.
-
Description
===========
@@ -53,7 +52,6 @@ non-dynamic link will return an ``EBUSY`` error code.
If the specified link can't be found the driver returns with an ``EINVAL``
error code.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
index ca1b33196242..04b33db2bb45 100644
--- a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
+++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_request_ioc_queue:
@@ -11,13 +12,12 @@ Name
MEDIA_REQUEST_IOC_QUEUE - Queue a request
-
Synopsis
========
-.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
- :name: MEDIA_REQUEST_IOC_QUEUE
+.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
+``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
Arguments
=========
@@ -25,7 +25,6 @@ Arguments
``request_fd``
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
-
Description
===========
diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
index cfd503bdef70..57567b87b985 100644
--- a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
+++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media_request_ioc_reinit:
@@ -11,13 +12,12 @@ Name
MEDIA_REQUEST_IOC_REINIT - Re-initialize a request
-
Synopsis
========
-.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT )
- :name: MEDIA_REQUEST_IOC_REINIT
+.. c:macro:: MEDIA_REQUEST_IOC_REINIT
+``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)``
Arguments
=========
@@ -33,7 +33,7 @@ this request ioctl can be used to re-initialize a previously allocated
request.
Re-initializing a request will clear any existing data from the request.
-This avoids having to :ref:`close() <request-func-close>` a completed
+This avoids having to :c:func:`close()` a completed
request and allocate a new request. Instead the completed request can just
be re-initialized and it is ready to be used again.
diff --git a/Documentation/userspace-api/media/mediactl/request-api.rst b/Documentation/userspace-api/media/mediactl/request-api.rst
index c0fa4dbb2b28..6c4cbd9f08a5 100644
--- a/Documentation/userspace-api/media/mediactl/request-api.rst
+++ b/Documentation/userspace-api/media/mediactl/request-api.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _media-request-api:
@@ -93,7 +94,7 @@ regardless of whether a request is in use or not.
Setting the same control through a request and also directly can lead to
undefined behavior!
-User-space can :ref:`poll() <request-func-poll>` a request file descriptor in
+User-space can :c:func:`poll()` a request file descriptor in
order to wait until the request completes. A request is considered complete
once all its associated buffers are available for dequeuing and all the
associated controls have been updated with the values at the time of completion.
@@ -115,7 +116,7 @@ Recycling and Destruction
-------------------------
Finally, a completed request can either be discarded or be reused. Calling
-:ref:`close() <request-func-close>` on a request file descriptor will make
+:c:func:`close()` on a request file descriptor will make
that file descriptor unusable and the request will be freed once it is no
longer in use by the kernel. That is, if the request is queued and then the
file descriptor is closed, then it won't be freed until the driver completed
diff --git a/Documentation/userspace-api/media/mediactl/request-func-close.rst b/Documentation/userspace-api/media/mediactl/request-func-close.rst
index 04e00bb9defd..f4b8eb385ad7 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-close.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-close.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC.request
.. _request-func-close:
@@ -11,7 +12,6 @@ Name
request-close - Close a request file descriptor
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <unistd.h>
-
.. c:function:: int close( int fd )
- :name: req-close
Arguments
=========
@@ -29,7 +27,6 @@ Arguments
``fd``
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
-
Description
===========
@@ -38,11 +35,10 @@ are freed once all file descriptors associated with the request are closed
and the driver has completed the request.
See :ref:`here <media-request-life-time>` for more information.
-
Return Value
============
-:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is
+:c:func:`close()` returns 0 on success. On error, -1 is
returned, and ``errno`` is set appropriately. Possible error codes are:
EBADF
diff --git a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
index 1e1c5edb860c..4fb3d2ef32d1 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _request-func-ioctl:
@@ -11,7 +12,6 @@ Name
request-ioctl - Control a request file descriptor
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <sys/ioctl.h>
-
-.. c:function:: int ioctl( int fd, int cmd, void *argp )
- :name: req-ioctl
+``int ioctl(int fd, int cmd, void *argp)``
Arguments
=========
@@ -36,7 +34,6 @@ Arguments
``argp``
Pointer to a request-specific structure.
-
Description
===========
@@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All request ioctl
commands, their respective function and parameters are specified in
:ref:`media-user-func`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/mediactl/request-func-poll.rst b/Documentation/userspace-api/media/mediactl/request-func-poll.rst
index 92947213d3d5..ce0043dbe7da 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-poll.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-poll.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
.. _request-func-poll:
@@ -11,7 +12,6 @@ Name
request-poll - Wait for some event on a file descriptor
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <sys/poll.h>
-
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
- :name: request-poll
Arguments
=========
@@ -35,14 +33,13 @@ Arguments
``timeout``
Timeout to wait for events
-
Description
===========
-With the :c:func:`poll() <request-func-poll>` function applications can wait
+With the :c:func:`poll()` function applications can wait
for a request to complete.
-On success :c:func:`poll() <request-func-poll>` returns the number of file
+On success :c:func:`poll()` returns the number of file
descriptors that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
@@ -53,11 +50,10 @@ set appropriately.
Attempting to poll for a request that is not yet queued will
set the ``POLLERR`` flag in ``revents``.
-
Return Value
============
-On success, :c:func:`poll() <request-func-poll>` returns the number of
+On success, :c:func:`poll()` returns the number of
structures which have non-zero ``revents`` fields, or zero if the call
timed out. On error -1 is returned, and the ``errno`` variable is set
appropriately:
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 16/52] media: docs: make RC documents more compatible with Sphinx 3.1+
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (14 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 15/52] media: docs: make MC " Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 17/52] media: cec-core.rst: don't use c:type for structs Mauro Carvalho Chehab
` (36 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Sean Young,
linux-kernel, linux-media
Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../userspace-api/media/rc/lirc-get-features.rst | 9 ++++-----
.../userspace-api/media/rc/lirc-get-rec-mode.rst | 12 +++++++-----
.../media/rc/lirc-get-rec-resolution.rst | 8 ++++----
.../userspace-api/media/rc/lirc-get-send-mode.rst | 14 +++++++-------
.../userspace-api/media/rc/lirc-get-timeout.rst | 13 +++++++------
Documentation/userspace-api/media/rc/lirc-read.rst | 10 +++-------
.../media/rc/lirc-set-measure-carrier-mode.rst | 8 ++++----
.../media/rc/lirc-set-rec-carrier-range.rst | 6 ++++--
.../media/rc/lirc-set-rec-carrier.rst | 8 ++++----
.../media/rc/lirc-set-rec-timeout-reports.rst | 8 ++++----
.../media/rc/lirc-set-rec-timeout.rst | 13 +++++++------
.../media/rc/lirc-set-send-carrier.rst | 8 ++++----
.../media/rc/lirc-set-send-duty-cycle.rst | 8 ++++----
.../media/rc/lirc-set-transmitter-mask.rst | 8 ++++----
.../media/rc/lirc-set-wideband-receiver.rst | 8 ++++----
.../userspace-api/media/rc/lirc-write.rst | 7 ++-----
16 files changed, 73 insertions(+), 75 deletions(-)
diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst
index 6846ae99848c..66a243dbd437 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-features.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_get_features:
@@ -14,8 +15,9 @@ LIRC_GET_FEATURES - Get the underlying hardware device's features
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features)
- :name: LIRC_GET_FEATURES
+.. c:macro:: LIRC_GET_FEATURES
+
+``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)``
Arguments
=========
@@ -26,11 +28,9 @@ Arguments
``features``
Bitmask with the LIRC features.
-
Description
===========
-
Get the underlying hardware device's features. If a driver does not
announce support of certain features, calling of the corresponding ioctls
is undefined.
@@ -184,7 +184,6 @@ LIRC features
Unused. Kept just to avoid breaking uAPI.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
index e8f397a87331..188478ed1233 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_get_rec_mode:
.. _lirc_set_rec_mode:
@@ -15,11 +16,13 @@ LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode.
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode)
- :name: LIRC_GET_REC_MODE
+.. c:macro:: LIRC_GET_REC_MODE
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode)
- :name: LIRC_SET_REC_MODE
+``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_REC_MODE
+
+``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)``
Arguments
=========
@@ -47,7 +50,6 @@ Return Value
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``ENODEV``
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
index 3f08aa7c24a9..e29445c5ce16 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_get_rec_resolution:
@@ -14,8 +15,9 @@ LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microsecond
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)
- :name: LIRC_GET_REC_RESOLUTION
+.. c:macro:: LIRC_GET_REC_RESOLUTION
+
+``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)``
Arguments
=========
@@ -26,7 +28,6 @@ Arguments
``microseconds``
Resolution, in microseconds.
-
Description
===========
@@ -38,7 +39,6 @@ This ioctl returns the integer value with such resolution, with can be
used by userspace applications like lircd to automatically adjust the
tolerance value.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
index f93b30c92193..77472fb5608a 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_get_send_mode:
.. _lirc_set_send_mode:
@@ -15,11 +16,13 @@ LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode.
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode )
- :name: LIRC_GET_SEND_MODE
+.. c:macro:: LIRC_GET_SEND_MODE
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode )
- :name: LIRC_SET_SEND_MODE
+``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_SEND_MODE
+
+``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)``
Arguments
=========
@@ -30,7 +33,6 @@ Arguments
``mode``
The mode used for transmitting.
-
Description
===========
@@ -44,14 +46,12 @@ modes the driver supports.
Return Value
============
-
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- .. row 1
- ``ENODEV``
diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
index ec191a383d75..f5f3e06d6206 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_get_min_timeout:
.. _lirc_get_max_timeout:
@@ -16,11 +17,13 @@ range for IR receive.
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)
- :name: LIRC_GET_MIN_TIMEOUT
+.. c:macro:: LIRC_GET_MIN_TIMEOUT
-.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)
- :name: LIRC_GET_MAX_TIMEOUT
+``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_GET_MAX_TIMEOUT
+
+``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)``
Arguments
=========
@@ -31,7 +34,6 @@ Arguments
``timeout``
Timeout, in microseconds.
-
Description
===========
@@ -47,7 +49,6 @@ that can be set.
both ioctls will return the same value even though the timeout
cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst
index b94a349bd99e..d589560214f4 100644
--- a/Documentation/userspace-api/media/rc/lirc-read.rst
+++ b/Documentation/userspace-api/media/rc/lirc-read.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc-read:
@@ -11,7 +12,6 @@ Name
lirc-read - Read from a LIRC device
-
Synopsis
========
@@ -19,10 +19,7 @@ Synopsis
#include <unistd.h>
-
.. c:function:: ssize_t read( int fd, void *buf, size_t count )
- :name: lirc-read
-
Arguments
=========
@@ -39,9 +36,9 @@ Arguments
Description
===========
-:ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file
+:c:func:`read()` attempts to read up to ``count`` bytes from file
descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero,
-:ref:`read() <lirc-read>` returns zero and has no other results. If ``count``
+:c:func:`read()` returns zero and has no other results. If ``count``
is greater than ``SSIZE_MAX``, the result is unspecified.
The exact format of the data depends on what :ref:`lirc_modes` a driver
@@ -59,7 +56,6 @@ by hardware decoders. The :c:type:`rc_proto` member is set to the
used for transmission, and ``scancode`` to the decoded scancode,
and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
index 820d6bf28c1c..9bf9811a905a 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_measure_carrier_mode:
@@ -14,8 +15,9 @@ LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable )
- :name: LIRC_SET_MEASURE_CARRIER_MODE
+.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE
+
+``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)``
Arguments
=========
@@ -27,7 +29,6 @@ Arguments
enable = 1 means enable measure mode, enable = 0 means disable measure
mode.
-
Description
===========
@@ -37,7 +38,6 @@ Enable or disable measure mode. If enabled, from the next key
press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By
default this should be turned off.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
index e33e6a320b7a..530bc223930a 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_rec_carrier_range:
@@ -15,8 +16,9 @@ IR receive.
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency )
- :name: LIRC_SET_REC_CARRIER_RANGE
+.. c:macro:: LIRC_SET_REC_CARRIER_RANGE
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)``
Arguments
=========
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
index a6784d5e59c8..28c928f1cc14 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_rec_carrier:
@@ -11,12 +12,12 @@ Name
LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency )
- :name: LIRC_SET_REC_CARRIER
+.. c:macro:: LIRC_SET_REC_CARRIER
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)``
Arguments
=========
@@ -37,7 +38,6 @@ Set receive carrier used to modulate IR PWM pulses and spaces.
If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl
sets the upper bound frequency that will be recognized by the device.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
index 55be65df7d5a..83e7155c5796 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_rec_timeout_reports:
@@ -14,8 +15,9 @@ LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable )
- :name: LIRC_SET_REC_TIMEOUT_REPORTS
+.. c:macro:: LIRC_SET_REC_TIMEOUT_REPORTS
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable)``
Arguments
=========
@@ -27,7 +29,6 @@ Arguments
enable = 1 means enable timeout report, enable = 0 means disable timeout
reports.
-
Description
===========
@@ -40,7 +41,6 @@ should be turned off.
This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
index e91a0daecde6..8f3f9adf54ab 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_rec_timeout:
.. _lirc_get_rec_timeout:
@@ -15,11 +16,13 @@ LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR ina
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout )
- :name: LIRC_GET_REC_TIMEOUT
+.. c:macro:: LIRC_GET_REC_TIMEOUT
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout )
- :name: LIRC_SET_REC_TIMEOUT
+``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_SET_REC_TIMEOUT
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)``
Arguments
=========
@@ -30,7 +33,6 @@ Arguments
``timeout``
Timeout, in microseconds.
-
Description
===========
@@ -45,7 +47,6 @@ given value should be set.
The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
index e199aac7d8e0..e3810ba58746 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_send_carrier:
@@ -11,12 +12,12 @@ Name
LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX.
-
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency )
- :name: LIRC_SET_SEND_CARRIER
+.. c:macro:: LIRC_SET_SEND_CARRIER
+
+``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)``
Arguments
=========
@@ -32,7 +33,6 @@ Description
Set send carrier used to modulate IR PWM pulses and spaces.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
index a9074f4fb058..52a072529af9 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_send_duty_cycle:
@@ -15,8 +16,9 @@ IR transmit.
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)
- :name: LIRC_SET_SEND_DUTY_CYCLE
+.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE
+
+``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)``
Arguments
=========
@@ -28,7 +30,6 @@ Arguments
Duty cicle, describing the pulse width in percent (from 1 to 99) of
the total cycle. Values 0 and 100 are reserved.
-
Description
===========
@@ -38,7 +39,6 @@ Currently, no special meaning is defined for 0 or 100, but this
could be used to switch off carrier generation in the future, so
these values should be reserved.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
index 1f5527427281..68f4cc2e3ae3 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_transmitter_mask:
@@ -14,8 +15,9 @@ LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask )
- :name: LIRC_SET_TRANSMITTER_MASK
+.. c:macro:: LIRC_SET_TRANSMITTER_MASK
+
+``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)``
Arguments
=========
@@ -26,7 +28,6 @@ Arguments
``mask``
Mask with channels to enable tx. Channel 0 is the least significant bit.
-
Description
===========
@@ -42,7 +43,6 @@ When an invalid bit mask is given, i.e. a bit is set, even though the device
does not have so many transitters, then this ioctl returns the number of
available transitters and does nothing otherwise.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
index 2c43b620b3f3..be5321c4a91f 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc_set_wideband_receiver:
@@ -14,8 +15,9 @@ LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver.
Synopsis
========
-.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable )
- :name: LIRC_SET_WIDEBAND_RECEIVER
+.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER
+
+``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)``
Arguments
=========
@@ -27,7 +29,6 @@ Arguments
enable = 1 means enable wideband receiver, enable = 0 means disable
wideband receiver.
-
Description
===========
@@ -47,7 +48,6 @@ reduced range of reception.
carrier reports. Trying to disable wide band receiver while carrier
reports are active will do nothing.
-
Return Value
============
diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst
index 421de2cfa4ca..c1c3230d4fd6 100644
--- a/Documentation/userspace-api/media/rc/lirc-write.rst
+++ b/Documentation/userspace-api/media/rc/lirc-write.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
.. _lirc-write:
@@ -11,7 +12,6 @@ Name
lirc-write - Write to a LIRC device
-
Synopsis
========
@@ -19,9 +19,7 @@ Synopsis
#include <unistd.h>
-
.. c:function:: ssize_t write( int fd, void *buf, size_t count )
- :name: lirc-write
Arguments
=========
@@ -38,7 +36,7 @@ Arguments
Description
===========
-:ref:`write() <lirc-write>` writes up to ``count`` bytes to the device
+:c:func:`write()` writes up to ``count`` bytes to the device
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``.
@@ -64,7 +62,6 @@ for the protocol or the scancode is not valid for the specified protocol,
``EINVAL`` is returned. The write function blocks until the scancode
is transmitted by the hardware.
-
Return Value
============
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 17/52] media: cec-core.rst: don't use c:type for structs
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (15 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 16/52] media: docs: make RC " Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments Mauro Carvalho Chehab
` (35 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Hans Verkuil, Mauro Carvalho Chehab,
linux-kernel, linux-media
The new C domain code on Sphinx 3 doesn't allow anymore
to use c:type:: for structs.
Now that cdomain.py has backward support, let's use
c:struct:: instead.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/media/cec-core.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst
index 03016eeaf8f4..bc42982ac21e 100644
--- a/Documentation/driver-api/media/cec-core.rst
+++ b/Documentation/driver-api/media/cec-core.rst
@@ -98,7 +98,7 @@ Implementing the Low-Level CEC Adapter
The following low-level adapter operations have to be implemented in
your driver:
-.. c:type:: struct cec_adap_ops
+.. c:struct:: cec_adap_ops
.. code-block:: none
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (16 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 17/52] media: cec-core.rst: don't use c:type for structs Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:46 ` Vincenzo Frascino
2020-09-30 13:24 ` [PATCH v4 19/52] memblock: get rid of a :c:type leftover Mauro Carvalho Chehab
` (34 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Peter Zijlstra (Intel),
Chunyan Zhang, Oleg Nesterov, Thomas Gleixner, Vincenzo Frascino,
linux-kernel
There are several functions at math64.h that are also
defined at div64.c. As both are included at kernel-api.rst,
Sphinx 3.x complains about symbol duplication:
./lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'div_s64_rem'.
./lib/math/div64.c:104: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'div64_u64_rem'.
./lib/math/div64.c:144: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'div64_u64'.
./lib/math/div64.c:172: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'div64_s64'.
In order to avoid Sphinx warnings about duplication, change the kernel-doc
markups to just comments at math64.h.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/linux/math64.h | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/include/linux/math64.h b/include/linux/math64.h
index 3381d9e33c4e..66deb1fdc2ef 100644
--- a/include/linux/math64.h
+++ b/include/linux/math64.h
@@ -28,7 +28,7 @@ static inline u64 div_u64_rem(u64 dividend, u32 divisor, u32 *remainder)
return dividend / divisor;
}
-/**
+/*
* div_s64_rem - signed 64bit divide with 32bit divisor with remainder
* @dividend: signed 64bit dividend
* @divisor: signed 32bit divisor
@@ -42,7 +42,7 @@ static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
return dividend / divisor;
}
-/**
+/*
* div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
* @dividend: unsigned 64bit dividend
* @divisor: unsigned 64bit divisor
@@ -56,7 +56,7 @@ static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
return dividend / divisor;
}
-/**
+/*
* div64_u64 - unsigned 64bit divide with 64bit divisor
* @dividend: unsigned 64bit dividend
* @divisor: unsigned 64bit divisor
@@ -68,7 +68,7 @@ static inline u64 div64_u64(u64 dividend, u64 divisor)
return dividend / divisor;
}
-/**
+/*
* div64_s64 - signed 64bit divide with 64bit divisor
* @dividend: signed 64bit dividend
* @divisor: signed 64bit divisor
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments
2020-09-30 13:24 ` [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments Mauro Carvalho Chehab
@ 2020-09-30 13:46 ` Vincenzo Frascino
0 siblings, 0 replies; 103+ messages in thread
From: Vincenzo Frascino @ 2020-09-30 13:46 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
Cc: Peter Zijlstra (Intel),
Chunyan Zhang, Oleg Nesterov, Thomas Gleixner, linux-kernel
On 9/30/20 2:24 PM, Mauro Carvalho Chehab wrote:
> There are several functions at math64.h that are also
> defined at div64.c. As both are included at kernel-api.rst,
> Sphinx 3.x complains about symbol duplication:
>
> ./lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
> Declaration is 'div_s64_rem'.
> ./lib/math/div64.c:104: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
> Declaration is 'div64_u64_rem'.
> ./lib/math/div64.c:144: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
> Declaration is 'div64_u64'.
> ./lib/math/div64.c:172: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
> Declaration is 'div64_s64'.
>
> In order to avoid Sphinx warnings about duplication, change the kernel-doc
> markups to just comments at math64.h.
>
Reviewed-by: Vincenzo Frascino <vincenzo.frascino@arm.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> include/linux/math64.h | 8 ++++----
> 1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/include/linux/math64.h b/include/linux/math64.h
> index 3381d9e33c4e..66deb1fdc2ef 100644
> --- a/include/linux/math64.h
> +++ b/include/linux/math64.h
> @@ -28,7 +28,7 @@ static inline u64 div_u64_rem(u64 dividend, u32 divisor, u32 *remainder)
> return dividend / divisor;
> }
>
> -/**
> +/*
> * div_s64_rem - signed 64bit divide with 32bit divisor with remainder
> * @dividend: signed 64bit dividend
> * @divisor: signed 32bit divisor
> @@ -42,7 +42,7 @@ static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
> return dividend / divisor;
> }
>
> -/**
> +/*
> * div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
> * @dividend: unsigned 64bit dividend
> * @divisor: unsigned 64bit divisor
> @@ -56,7 +56,7 @@ static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
> return dividend / divisor;
> }
>
> -/**
> +/*
> * div64_u64 - unsigned 64bit divide with 64bit divisor
> * @dividend: unsigned 64bit dividend
> * @divisor: unsigned 64bit divisor
> @@ -68,7 +68,7 @@ static inline u64 div64_u64(u64 dividend, u64 divisor)
> return dividend / divisor;
> }
>
> -/**
> +/*
> * div64_s64 - signed 64bit divide with 64bit divisor
> * @dividend: signed 64bit dividend
> * @divisor: signed 64bit divisor
>
--
Regards,
Vincenzo
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 19/52] memblock: get rid of a :c:type leftover
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (17 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 14:23 ` Mike Rapoport
2020-09-30 13:24 ` Mauro Carvalho Chehab
` (33 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Andrew Morton, Mike Rapoport,
linux-kernel, linux-mm
chanseset b3a7bb1851c8 ("docs: get rid of :c:type explicit declarations for structs")
removed several :c:type: markups, except by one.
Now, Sphinx 3.x complains about it:
.../Documentation/core-api/boot-time-mm:26: ../mm/memblock.c:51: WARNING: Unparseable C cross-reference: 'struct\nmemblock_type'
Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
struct
memblock_type
------^
As, on Sphinx 3.x, the right markup is c:struct:`foo`.
So, let's remove it, relying on automarkup.py to convert it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
mm/memblock.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/mm/memblock.c b/mm/memblock.c
index 165f40a8a254..326c6b3fec1d 100644
--- a/mm/memblock.c
+++ b/mm/memblock.c
@@ -50,8 +50,8 @@
*
* Each region is represented by :c:type:`struct memblock_region` that
* defines the region extents, its attributes and NUMA node id on NUMA
- * systems. Every memory type is described by the :c:type:`struct
- * memblock_type` which contains an array of memory regions along with
+ * systems. Every memory type is described by the struct memblock_type
+ * which contains an array of memory regions along with
* the allocator metadata. The "memory" and "reserved" types are nicely
* wrapped with :c:type:`struct memblock`. This structure is statically
* initialized at build time. The region arrays are initially sized to
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 19/52] memblock: get rid of a :c:type leftover
2020-09-30 13:24 ` [PATCH v4 19/52] memblock: get rid of a :c:type leftover Mauro Carvalho Chehab
@ 2020-09-30 14:23 ` Mike Rapoport
2020-09-30 15:13 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 103+ messages in thread
From: Mike Rapoport @ 2020-09-30 14:23 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Andrew Morton,
linux-kernel, linux-mm
Hello Mauro,
On Wed, Sep 30, 2020 at 03:24:42PM +0200, Mauro Carvalho Chehab wrote:
> chanseset b3a7bb1851c8 ("docs: get rid of :c:type explicit declarations for structs")
> removed several :c:type: markups, except by one.
>
> Now, Sphinx 3.x complains about it:
>
> .../Documentation/core-api/boot-time-mm:26: ../mm/memblock.c:51: WARNING: Unparseable C cross-reference: 'struct\nmemblock_type'
> Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
> struct
> memblock_type
> ------^
Maybe this warning is caused by '\n' between struct and memblock_type?
There are two more occurences of :c:type: around and they do not seem to
cause warnings.
> As, on Sphinx 3.x, the right markup is c:struct:`foo`.
>
> So, let's remove it, relying on automarkup.py to convert it.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> mm/memblock.c | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/mm/memblock.c b/mm/memblock.c
> index 165f40a8a254..326c6b3fec1d 100644
> --- a/mm/memblock.c
> +++ b/mm/memblock.c
> @@ -50,8 +50,8 @@
> *
> * Each region is represented by :c:type:`struct memblock_region` that
Can you please also convert this one?
> * defines the region extents, its attributes and NUMA node id on NUMA
> - * systems. Every memory type is described by the :c:type:`struct
> - * memblock_type` which contains an array of memory regions along with
> + * systems. Every memory type is described by the struct memblock_type
> + * which contains an array of memory regions along with
> * the allocator metadata. The "memory" and "reserved" types are nicely
> * wrapped with :c:type:`struct memblock`. This structure is statically
And this?
> * initialized at build time. The region arrays are initially sized to
> --
> 2.26.2
>
--
Sincerely yours,
Mike.
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 19/52] memblock: get rid of a :c:type leftover
2020-09-30 14:23 ` Mike Rapoport
@ 2020-09-30 15:13 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 15:13 UTC (permalink / raw)
To: Mike Rapoport
Cc: Linux Doc Mailing List, Jonathan Corbet, Andrew Morton,
linux-kernel, linux-mm
Em Wed, 30 Sep 2020 17:23:23 +0300
Mike Rapoport <rppt@kernel.org> escreveu:
> Hello Mauro,
>
> On Wed, Sep 30, 2020 at 03:24:42PM +0200, Mauro Carvalho Chehab wrote:
> > chanseset b3a7bb1851c8 ("docs: get rid of :c:type explicit declarations for structs")
> > removed several :c:type: markups, except by one.
> >
> > Now, Sphinx 3.x complains about it:
> >
> > .../Documentation/core-api/boot-time-mm:26: ../mm/memblock.c:51: WARNING: Unparseable C cross-reference: 'struct\nmemblock_type'
> > Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
> > struct
> > memblock_type
> > ------^
>
> Maybe this warning is caused by '\n' between struct and memblock_type?
> There are two more occurences of :c:type: around and they do not seem to
> cause warnings.
Yeah, maybe. Yet, according with:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#c-roles
c:type: should only be used together with ".. c:type", and this
doesn't work anymore for declaring structs, as the only valid
ways of using it after Sphinx 3.0 are:
.. c:type:: typedef-like declaration
.. c:type:: name
So, the old syntax generated by kernel doc:
.. c:type:: struct foo
Doesn't work anymore. Kernel-doc now uses, instead:
.. c:struct:: foo
(if version >= 3.0)
So, the right tag would be: :c:struct`foo`, if Sphinx > 3
or c:type:`foo` for older versions.
Better to rely on having the automarkup solving this for
us.
-
>
> > As, on Sphinx 3.x, the right markup is c:struct:`foo`.
> >
> > So, let's remove it, relying on automarkup.py to convert it.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> > mm/memblock.c | 4 ++--
> > 1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/mm/memblock.c b/mm/memblock.c
> > index 165f40a8a254..326c6b3fec1d 100644
> > --- a/mm/memblock.c
> > +++ b/mm/memblock.c
> > @@ -50,8 +50,8 @@
> > *
> > * Each region is represented by :c:type:`struct memblock_region` that
>
> Can you please also convert this one?
>
> > * defines the region extents, its attributes and NUMA node id on NUMA
> > - * systems. Every memory type is described by the :c:type:`struct
> > - * memblock_type` which contains an array of memory regions along with
> > + * systems. Every memory type is described by the struct memblock_type
> > + * which contains an array of memory regions along with
> > * the allocator metadata. The "memory" and "reserved" types are nicely
> > * wrapped with :c:type:`struct memblock`. This structure is statically
>
> And this?
Good point.
I'll change those too for the next version.
>
> > * initialized at build time. The region arrays are initially sized to
> > --
> > 2.26.2
> >
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Daniel Vetter, David Airlie,
Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann, dri-devel,
linux-kernel
As warned by Sphinx:
./Documentation/gpu/drm-kms-helpers:305: ./include/drm/drm_dsc.h:587: WARNING: Unparseable C cross-reference: 'struct'
Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
struct
------^
The markup for one struct is wrong, as struct is used twice.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/drm/drm_dsc.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
index 887954cbfc60..732f32740c86 100644
--- a/include/drm/drm_dsc.h
+++ b/include/drm/drm_dsc.h
@@ -588,7 +588,7 @@ struct drm_dsc_picture_parameter_set {
* This structure represents the DSC PPS infoframe required to send the Picture
* Parameter Set metadata required before enabling VESA Display Stream
* Compression. This is based on the DP Secondary Data Packet structure and
- * comprises of SDP Header as defined &struct struct dp_sdp_header in drm_dp_helper.h
+ * comprises of SDP Header as defined &struct dp_sdp_header in drm_dp_helper.h
* and PPS payload defined in &struct drm_dsc_picture_parameter_set.
*
* @pps_header: Header for PPS as per DP SDP header format of type
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Thomas Zimmermann, Mauro Carvalho Chehab, linux-kernel,
David Airlie, dri-devel
As warned by Sphinx:
./Documentation/gpu/drm-kms-helpers:305: ./include/drm/drm_dsc.h:587: WARNING: Unparseable C cross-reference: 'struct'
Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
struct
------^
The markup for one struct is wrong, as struct is used twice.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
include/drm/drm_dsc.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
index 887954cbfc60..732f32740c86 100644
--- a/include/drm/drm_dsc.h
+++ b/include/drm/drm_dsc.h
@@ -588,7 +588,7 @@ struct drm_dsc_picture_parameter_set {
* This structure represents the DSC PPS infoframe required to send the Picture
* Parameter Set metadata required before enabling VESA Display Stream
* Compression. This is based on the DP Secondary Data Packet structure and
- * comprises of SDP Header as defined &struct struct dp_sdp_header in drm_dp_helper.h
+ * comprises of SDP Header as defined &struct dp_sdp_header in drm_dp_helper.h
* and PPS payload defined in &struct drm_dsc_picture_parameter_set.
*
* @pps_header: Header for PPS as per DP SDP header format of type
--
2.26.2
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 14:42 ` Daniel Vetter
-1 siblings, 0 replies; 103+ messages in thread
From: Daniel Vetter @ 2020-09-30 14:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Daniel Vetter,
David Airlie, Maarten Lankhorst, Maxime Ripard,
Thomas Zimmermann, dri-devel, linux-kernel
On Wed, Sep 30, 2020 at 03:24:43PM +0200, Mauro Carvalho Chehab wrote:
> As warned by Sphinx:
>
> ./Documentation/gpu/drm-kms-helpers:305: ./include/drm/drm_dsc.h:587: WARNING: Unparseable C cross-reference: 'struct'
> Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
> struct
> ------^
>
> The markup for one struct is wrong, as struct is used twice.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Applied to drm-misc-fixes, thanks for your patch.
-Daniel
> ---
> include/drm/drm_dsc.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
> index 887954cbfc60..732f32740c86 100644
> --- a/include/drm/drm_dsc.h
> +++ b/include/drm/drm_dsc.h
> @@ -588,7 +588,7 @@ struct drm_dsc_picture_parameter_set {
> * This structure represents the DSC PPS infoframe required to send the Picture
> * Parameter Set metadata required before enabling VESA Display Stream
> * Compression. This is based on the DP Secondary Data Packet structure and
> - * comprises of SDP Header as defined &struct struct dp_sdp_header in drm_dp_helper.h
> + * comprises of SDP Header as defined &struct dp_sdp_header in drm_dp_helper.h
> * and PPS payload defined in &struct drm_dsc_picture_parameter_set.
> *
> * @pps_header: Header for PPS as per DP SDP header format of type
> --
> 2.26.2
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup
@ 2020-09-30 14:42 ` Daniel Vetter
0 siblings, 0 replies; 103+ messages in thread
From: Daniel Vetter @ 2020-09-30 14:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Thomas Zimmermann, Jonathan Corbet, David Airlie,
Linux Doc Mailing List, linux-kernel, dri-devel
On Wed, Sep 30, 2020 at 03:24:43PM +0200, Mauro Carvalho Chehab wrote:
> As warned by Sphinx:
>
> ./Documentation/gpu/drm-kms-helpers:305: ./include/drm/drm_dsc.h:587: WARNING: Unparseable C cross-reference: 'struct'
> Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
> struct
> ------^
>
> The markup for one struct is wrong, as struct is used twice.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Applied to drm-misc-fixes, thanks for your patch.
-Daniel
> ---
> include/drm/drm_dsc.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
> index 887954cbfc60..732f32740c86 100644
> --- a/include/drm/drm_dsc.h
> +++ b/include/drm/drm_dsc.h
> @@ -588,7 +588,7 @@ struct drm_dsc_picture_parameter_set {
> * This structure represents the DSC PPS infoframe required to send the Picture
> * Parameter Set metadata required before enabling VESA Display Stream
> * Compression. This is based on the DP Secondary Data Packet structure and
> - * comprises of SDP Header as defined &struct struct dp_sdp_header in drm_dp_helper.h
> + * comprises of SDP Header as defined &struct dp_sdp_header in drm_dp_helper.h
> * and PPS payload defined in &struct drm_dsc_picture_parameter_set.
> *
> * @pps_header: Header for PPS as per DP SDP header format of type
> --
> 2.26.2
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 21/52] docs: remove some replace macros like |struct foo|
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (19 preceding siblings ...)
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` Mauro Carvalho Chehab
` (31 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Rafael J. Wysocki, Daniel Lezcano,
Greg Kroah-Hartman, Saravana Kannan, Viresh Kumar, linux-kernel,
linux-pm
There are three files with replace macros for structs,
mapping them into Sphinx 2.x C domain references.
Well, this is broken on Sphinx 3.x. Also, for Sphinx 2.x,
the automarkup macro should be able to take care of them.
So, let's just drop those.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/admin-guide/pm/cpufreq.rst | 11 ++--
Documentation/driver-api/device_link.rst | 10 ++--
Documentation/driver-api/pm/cpuidle.rst | 65 +++++++++++-------------
3 files changed, 38 insertions(+), 48 deletions(-)
diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst
index 368e612145d2..6adb7988e0eb 100644
--- a/Documentation/admin-guide/pm/cpufreq.rst
+++ b/Documentation/admin-guide/pm/cpufreq.rst
@@ -1,7 +1,6 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
-.. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>`
.. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>`
=======================
@@ -92,16 +91,16 @@ control the P-state of multiple CPUs at the same time and writing to it affects
all of those CPUs simultaneously.
Sets of CPUs sharing hardware P-state control interfaces are represented by
-``CPUFreq`` as |struct cpufreq_policy| objects. For consistency,
-|struct cpufreq_policy| is also used when there is only one CPU in the given
+``CPUFreq`` as struct cpufreq_policy objects. For consistency,
+struct cpufreq_policy is also used when there is only one CPU in the given
set.
-The ``CPUFreq`` core maintains a pointer to a |struct cpufreq_policy| object for
+The ``CPUFreq`` core maintains a pointer to a struct cpufreq_policy object for
every CPU in the system, including CPUs that are currently offline. If multiple
CPUs share the same hardware P-state control interface, all of the pointers
-corresponding to them point to the same |struct cpufreq_policy| object.
+corresponding to them point to the same struct cpufreq_policy object.
-``CPUFreq`` uses |struct cpufreq_policy| as its basic data type and the design
+``CPUFreq`` uses struct cpufreq_policy as its basic data type and the design
of its user space interface is based on the policy concept.
diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
index bc2d89af88ce..76950d061632 100644
--- a/Documentation/driver-api/device_link.rst
+++ b/Documentation/driver-api/device_link.rst
@@ -1,7 +1,3 @@
-.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
-.. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>`
-
-
.. _device_link:
============
@@ -166,7 +162,7 @@ Examples
is the same as if the MMU was the parent of the master device.
The fact that both devices share the same power domain would normally
- suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|,
+ suggest usage of a struct dev_pm_domain or struct generic_pm_domain,
however these are not independent devices that happen to share a power
switch, but rather the MMU device serves the busmaster device and is
useless without it. A device link creates a synthetic hierarchical
@@ -202,7 +198,7 @@ Examples
Alternatives
============
-* A |struct dev_pm_domain| can be used to override the bus,
+* A struct dev_pm_domain can be used to override the bus,
class or device type callbacks. It is intended for devices sharing
a single on/off switch, however it does not guarantee a specific
suspend/resume ordering, this needs to be implemented separately.
@@ -211,7 +207,7 @@ Alternatives
suspended. Furthermore it cannot be used to enforce a specific shutdown
ordering or a driver presence dependency.
-* A |struct generic_pm_domain| is a lot more heavyweight than a
+* A struct generic_pm_domain is a lot more heavyweight than a
device link and does not allow for shutdown ordering or driver presence
dependencies. It also cannot be used on ACPI systems.
diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst
index 3588bf078566..d477208604b8 100644
--- a/Documentation/driver-api/pm/cpuidle.rst
+++ b/Documentation/driver-api/pm/cpuidle.rst
@@ -1,11 +1,6 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
-.. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>`
-.. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>`
-.. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>`
-.. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>`
-
========================
CPU Idle Time Management
========================
@@ -54,7 +49,7 @@ platform that the Linux kernel can run on. For this reason, data structures
operated on by them cannot depend on any hardware architecture or platform
design details as well.
-The governor itself is represented by a |struct cpuidle_governor| object
+The governor itself is represented by a struct cpuidle_governor object
containing four callback pointers, :c:member:`enable`, :c:member:`disable`,
:c:member:`select`, :c:member:`reflect`, a :c:member:`rating` field described
below, and a name (string) used for identifying it.
@@ -83,11 +78,11 @@ callbacks:
int (*enable) (struct cpuidle_driver *drv, struct cpuidle_device *dev);
The role of this callback is to prepare the governor for handling the
- (logical) CPU represented by the |struct cpuidle_device| object pointed
- to by the ``dev`` argument. The |struct cpuidle_driver| object pointed
+ (logical) CPU represented by the struct cpuidle_device object pointed
+ to by the ``dev`` argument. The struct cpuidle_driver object pointed
to by the ``drv`` argument represents the ``CPUIdle`` driver to be used
with that CPU (among other things, it should contain the list of
- |struct cpuidle_state| objects representing idle states that the
+ struct cpuidle_state objects representing idle states that the
processor holding the given CPU can be asked to enter).
It may fail, in which case it is expected to return a negative error
@@ -102,7 +97,7 @@ callbacks:
void (*disable) (struct cpuidle_driver *drv, struct cpuidle_device *dev);
Called to make the governor stop handling the (logical) CPU represented
- by the |struct cpuidle_device| object pointed to by the ``dev``
+ by the struct cpuidle_device object pointed to by the ``dev``
argument.
It is expected to reverse any changes made by the ``->enable()``
@@ -116,12 +111,12 @@ callbacks:
bool *stop_tick);
Called to select an idle state for the processor holding the (logical)
- CPU represented by the |struct cpuidle_device| object pointed to by the
+ CPU represented by the struct cpuidle_device object pointed to by the
``dev`` argument.
The list of idle states to take into consideration is represented by the
- :c:member:`states` array of |struct cpuidle_state| objects held by the
- |struct cpuidle_driver| object pointed to by the ``drv`` argument (which
+ :c:member:`states` array of struct cpuidle_state objects held by the
+ struct cpuidle_driver object pointed to by the ``drv`` argument (which
represents the ``CPUIdle`` driver to be used with the CPU at hand). The
value returned by this callback is interpreted as an index into that
array (unless it is a negative error code).
@@ -136,7 +131,7 @@ callbacks:
asking the processor to enter the idle state).
This callback is mandatory (i.e. the :c:member:`select` callback pointer
- in |struct cpuidle_governor| must not be ``NULL`` for the registration
+ in struct cpuidle_governor must not be ``NULL`` for the registration
of the governor to succeed).
:c:member:`reflect`
@@ -167,21 +162,21 @@ CPU idle time management (``CPUIdle``) drivers provide an interface between the
other parts of ``CPUIdle`` and the hardware.
First of all, a ``CPUIdle`` driver has to populate the :c:member:`states` array
-of |struct cpuidle_state| objects included in the |struct cpuidle_driver| object
+of struct cpuidle_state objects included in the struct cpuidle_driver object
representing it. Going forward this array will represent the list of available
idle states that the processor hardware can be asked to enter shared by all of
the logical CPUs handled by the given driver.
The entries in the :c:member:`states` array are expected to be sorted by the
-value of the :c:member:`target_residency` field in |struct cpuidle_state| in
+value of the :c:member:`target_residency` field in struct cpuidle_state in
the ascending order (that is, index 0 should correspond to the idle state with
the minimum value of :c:member:`target_residency`). [Since the
:c:member:`target_residency` value is expected to reflect the "depth" of the
-idle state represented by the |struct cpuidle_state| object holding it, this
+idle state represented by the struct cpuidle_state object holding it, this
sorting order should be the same as the ascending sorting order by the idle
state "depth".]
-Three fields in |struct cpuidle_state| are used by the existing ``CPUIdle``
+Three fields in struct cpuidle_state are used by the existing ``CPUIdle``
governors for computations related to idle state selection:
:c:member:`target_residency`
@@ -203,7 +198,7 @@ governors for computations related to idle state selection:
any idle state at all. [There are other flags used by the ``CPUIdle``
core in special situations.]
-The :c:member:`enter` callback pointer in |struct cpuidle_state|, which must not
+The :c:member:`enter` callback pointer in struct cpuidle_state, which must not
be ``NULL``, points to the routine to execute in order to ask the processor to
enter this particular idle state:
@@ -212,14 +207,14 @@ enter this particular idle state:
void (*enter) (struct cpuidle_device *dev, struct cpuidle_driver *drv,
int index);
-The first two arguments of it point to the |struct cpuidle_device| object
+The first two arguments of it point to the struct cpuidle_device object
representing the logical CPU running this callback and the
-|struct cpuidle_driver| object representing the driver itself, respectively,
-and the last one is an index of the |struct cpuidle_state| entry in the driver's
+struct cpuidle_driver object representing the driver itself, respectively,
+and the last one is an index of the struct cpuidle_state entry in the driver's
:c:member:`states` array representing the idle state to ask the processor to
enter.
-The analogous ``->enter_s2idle()`` callback in |struct cpuidle_state| is used
+The analogous ``->enter_s2idle()`` callback in struct cpuidle_state is used
only for implementing the suspend-to-idle system-wide power management feature.
The difference between in and ``->enter()`` is that it must not re-enable
interrupts at any point (even temporarily) or attempt to change the states of
@@ -227,48 +222,48 @@ clock event devices, which the ``->enter()`` callback may do sometimes.
Once the :c:member:`states` array has been populated, the number of valid
entries in it has to be stored in the :c:member:`state_count` field of the
-|struct cpuidle_driver| object representing the driver. Moreover, if any
+struct cpuidle_driver object representing the driver. Moreover, if any
entries in the :c:member:`states` array represent "coupled" idle states (that
is, idle states that can only be asked for if multiple related logical CPUs are
-idle), the :c:member:`safe_state_index` field in |struct cpuidle_driver| needs
+idle), the :c:member:`safe_state_index` field in struct cpuidle_driver needs
to be the index of an idle state that is not "coupled" (that is, one that can be
asked for if only one logical CPU is idle).
In addition to that, if the given ``CPUIdle`` driver is only going to handle a
subset of logical CPUs in the system, the :c:member:`cpumask` field in its
-|struct cpuidle_driver| object must point to the set (mask) of CPUs that will be
+struct cpuidle_driver object must point to the set (mask) of CPUs that will be
handled by it.
A ``CPUIdle`` driver can only be used after it has been registered. If there
are no "coupled" idle state entries in the driver's :c:member:`states` array,
-that can be accomplished by passing the driver's |struct cpuidle_driver| object
+that can be accomplished by passing the driver's struct cpuidle_driver object
to :c:func:`cpuidle_register_driver()`. Otherwise, :c:func:`cpuidle_register()`
should be used for this purpose.
-However, it also is necessary to register |struct cpuidle_device| objects for
+However, it also is necessary to register struct cpuidle_device objects for
all of the logical CPUs to be handled by the given ``CPUIdle`` driver with the
help of :c:func:`cpuidle_register_device()` after the driver has been registered
and :c:func:`cpuidle_register_driver()`, unlike :c:func:`cpuidle_register()`,
does not do that automatically. For this reason, the drivers that use
:c:func:`cpuidle_register_driver()` to register themselves must also take care
-of registering the |struct cpuidle_device| objects as needed, so it is generally
+of registering the struct cpuidle_device objects as needed, so it is generally
recommended to use :c:func:`cpuidle_register()` for ``CPUIdle`` driver
registration in all cases.
-The registration of a |struct cpuidle_device| object causes the ``CPUIdle``
+The registration of a struct cpuidle_device object causes the ``CPUIdle``
``sysfs`` interface to be created and the governor's ``->enable()`` callback to
be invoked for the logical CPU represented by it, so it must take place after
registering the driver that will handle the CPU in question.
-``CPUIdle`` drivers and |struct cpuidle_device| objects can be unregistered
+``CPUIdle`` drivers and struct cpuidle_device objects can be unregistered
when they are not necessary any more which allows some resources associated with
them to be released. Due to dependencies between them, all of the
-|struct cpuidle_device| objects representing CPUs handled by the given
+struct cpuidle_device objects representing CPUs handled by the given
``CPUIdle`` driver must be unregistered, with the help of
:c:func:`cpuidle_unregister_device()`, before calling
:c:func:`cpuidle_unregister_driver()` to unregister the driver. Alternatively,
:c:func:`cpuidle_unregister()` can be called to unregister a ``CPUIdle`` driver
-along with all of the |struct cpuidle_device| objects representing CPUs handled
+along with all of the struct cpuidle_device objects representing CPUs handled
by it.
``CPUIdle`` drivers can respond to runtime system configuration changes that
@@ -277,8 +272,8 @@ happen, for example, when the system's power source is switched from AC to
battery or the other way around). Upon a notification of such a change,
a ``CPUIdle`` driver is expected to call :c:func:`cpuidle_pause_and_lock()` to
turn ``CPUIdle`` off temporarily and then :c:func:`cpuidle_disable_device()` for
-all of the |struct cpuidle_device| objects representing CPUs affected by that
+all of the struct cpuidle_device objects representing CPUs affected by that
change. Next, it can update its :c:member:`states` array in accordance with
the new configuration of the system, call :c:func:`cpuidle_enable_device()` for
-all of the relevant |struct cpuidle_device| objects and invoke
+all of the relevant struct cpuidle_device objects and invoke
:c:func:`cpuidle_resume_and_unlock()` to allow ``CPUIdle`` to be used again.
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Alexander A. Klimov, André Almeida,
Theodore Y. Ts'o, Alexandru Ardelean, Andrew Morton,
Anshuman Khandual, Eric Biggers, Greg Kroah-Hartman, Jaegeuk Kim,
Jaroslav Kysela, Jens Axboe, Jonathan Cameron,
Mauro Carvalho Chehab, Mike Rapoport, Moritz Fischer,
Puranjay Mohan, Randy Dunlap, Satya Tangirala, Takashi Iwai,
Tom Rix, alsa-devel, linux-fpga, linux-fscrypt, linux-kernel,
linux-media, linux-mm
The :c:type:`foo` only works properly with structs before
Sphinx 3.x.
On Sphinx 3.x, structs should now be declared using the
.. c:struct, and referenced via :c:struct tag.
As we now have the automarkup.py macro, that automatically
convert:
struct foo
into cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/block/blk-mq.rst | 8 +++----
Documentation/block/inline-encryption.rst | 8 +++----
Documentation/driver-api/fpga/fpga-bridge.rst | 4 ++--
Documentation/driver-api/fpga/fpga-mgr.rst | 4 ++--
Documentation/driver-api/fpga/fpga-region.rst | 2 +-
Documentation/driver-api/iio/buffers.rst | 2 +-
Documentation/driver-api/iio/core.rst | 6 ++---
Documentation/driver-api/iio/hw-consumer.rst | 2 +-
.../driver-api/iio/triggered-buffers.rst | 2 +-
Documentation/driver-api/iio/triggers.rst | 4 ++--
.../driver-api/media/dtv-frontend.rst | 4 ++--
Documentation/driver-api/media/mc-core.rst | 24 +++++++++----------
.../driver-api/media/v4l2-controls.rst | 2 +-
Documentation/driver-api/media/v4l2-dev.rst | 8 +++----
.../driver-api/media/v4l2-device.rst | 6 ++---
Documentation/driver-api/media/v4l2-event.rst | 10 ++++----
Documentation/driver-api/media/v4l2-fh.rst | 16 ++++++-------
.../driver-api/media/v4l2-subdev.rst | 2 +-
Documentation/driver-api/regulator.rst | 4 ++--
Documentation/driver-api/usb/URB.rst | 2 +-
Documentation/driver-api/usb/gadget.rst | 10 ++++----
Documentation/driver-api/usb/hotplug.rst | 2 +-
Documentation/filesystems/fscrypt.rst | 14 +++++------
Documentation/filesystems/fsverity.rst | 2 +-
Documentation/sound/designs/tracepoints.rst | 22 ++++++++---------
| 2 +-
Documentation/vm/ksm.rst | 2 +-
Documentation/vm/memory-model.rst | 6 ++---
mm/ksm.c | 2 +-
mm/memblock.c | 4 ++--
30 files changed, 93 insertions(+), 93 deletions(-)
diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
index 88c56afcb070..86a632af02b0 100644
--- a/Documentation/block/blk-mq.rst
+++ b/Documentation/block/blk-mq.rst
@@ -63,10 +63,10 @@ Software staging queues
~~~~~~~~~~~~~~~~~~~~~~~
The block IO subsystem adds requests in the software staging queues
-(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent
+(represented by struct blk_mq_ctx) in case that they weren't sent
directly to the driver. A request is one or more BIOs. They arrived at the
-block layer through the data structure struct :c:type:`bio`. The block layer
-will then build a new structure from it, the struct :c:type:`request` that will
+block layer through the data structure struct bio. The block layer
+will then build a new structure from it, the struct request that will
be used to communicate with the device driver. Each queue has its own lock and
the number of queues is defined by a per-CPU or per-node basis.
@@ -102,7 +102,7 @@ hardware queue will be drained in sequence according to their mapping.
Hardware dispatch queues
~~~~~~~~~~~~~~~~~~~~~~~~
-The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct
+The hardware queue (represented by struct blk_mq_hw_ctx) is a struct
used by device drivers to map the device submission queues (or device DMA ring
buffer), and are the last step of the block layer submission code before the
low level device driver taking ownership of the request. To run this queue, the
diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst
index 354817b80887..e75151e467d3 100644
--- a/Documentation/block/inline-encryption.rst
+++ b/Documentation/block/inline-encryption.rst
@@ -52,7 +52,7 @@ Constraints and notes
Design
======
-We add a :c:type:`struct bio_crypt_ctx` to :c:type:`struct bio` that can
+We add a struct bio_crypt_ctx to struct bio that can
represent an encryption context, because we need to be able to pass this
encryption context from the upper layers (like the fs layer) to the
device driver to act upon.
@@ -85,7 +85,7 @@ blk-mq changes, other block layer changes and blk-crypto-fallback
=================================================================
We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to
-:c:type:`struct request`. These will be referred to as the ``crypto fields``
+struct request. These will be referred to as the ``crypto fields``
for the request. This ``keyslot`` is the keyslot into which the
``bi_crypt_context`` has been programmed in the KSM of the ``request_queue``
that this request is being sent to.
@@ -118,7 +118,7 @@ of the algorithm being used adheres to spec and functions correctly).
If a ``request queue``'s inline encryption hardware claimed to support the
encryption context specified with a bio, then it will not be handled by the
``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a
-:c:type:`struct request` needs to be allocated for that bio. At that point,
+struct request needs to be allocated for that bio. At that point,
blk-mq tries to program the encryption context into the ``request_queue``'s
keyslot_manager, and obtain a keyslot, which it stores in its newly added
``keyslot`` field. This keyslot is released when the request is completed.
@@ -188,7 +188,7 @@ keyslots supported by the hardware.
The device driver also needs to tell the KSM how to actually manipulate the
IE hardware in the device to do things like programming the crypto key into
the IE hardware into a particular keyslot. All this is achieved through the
-:c:type:`struct blk_ksm_ll_ops` field in the KSM that the device driver
+struct blk_ksm_ll_ops field in the KSM that the device driver
must fill up after initing the ``blk_keyslot_manager``.
The KSM also handles runtime power management for the device when applicable
diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst
index ccd677ba7d76..198aadafd3e7 100644
--- a/Documentation/driver-api/fpga/fpga-bridge.rst
+++ b/Documentation/driver-api/fpga/fpga-bridge.rst
@@ -4,8 +4,8 @@ FPGA Bridge
API to implement a new FPGA bridge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* struct :c:type:`fpga_bridge` — The FPGA Bridge structure
-* struct :c:type:`fpga_bridge_ops` — Low level Bridge driver ops
+* struct fpga_bridge — The FPGA Bridge structure
+* struct fpga_bridge_ops — Low level Bridge driver ops
* devm_fpga_bridge_create() — Allocate and init a bridge struct
* fpga_bridge_register() — Register a bridge
* fpga_bridge_unregister() — Unregister a bridge
diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
index af5382af1379..22f7885b32c9 100644
--- a/Documentation/driver-api/fpga/fpga-mgr.rst
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -102,8 +102,8 @@ API for implementing a new FPGA Manager driver
----------------------------------------------
* ``fpga_mgr_states`` — Values for :c:member:`fpga_manager->state`.
-* struct :c:type:`fpga_manager` — the FPGA manager struct
-* struct :c:type:`fpga_manager_ops` — Low level FPGA manager driver ops
+* struct fpga_manager — the FPGA manager struct
+* struct fpga_manager_ops — Low level FPGA manager driver ops
* devm_fpga_mgr_create() — Allocate and init a manager struct
* fpga_mgr_register() — Register an FPGA manager
* fpga_mgr_unregister() — Unregister an FPGA manager
diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
index 31118a8ba218..3e52be7e2968 100644
--- a/Documentation/driver-api/fpga/fpga-region.rst
+++ b/Documentation/driver-api/fpga/fpga-region.rst
@@ -45,7 +45,7 @@ An example of usage can be seen in the probe function of [#f2]_.
API to add a new FPGA region
----------------------------
-* struct :c:type:`fpga_region` — The FPGA region struct
+* struct fpga_region — The FPGA region struct
* devm_fpga_region_create() — Allocate and init a region struct
* fpga_region_register() — Register an FPGA region
* fpga_region_unregister() — Unregister an FPGA region
diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index dd64c9c5fb1e..3ddebddc02ca 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -2,7 +2,7 @@
Buffers
=======
-* struct :c:type:`iio_buffer` — general buffer structure
+* struct iio_buffer — general buffer structure
* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
is selected
* :c:func:`iio_buffer_get` — Grab a reference to the buffer
diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-api/iio/core.rst
index 51b21e002396..715cf29482a1 100644
--- a/Documentation/driver-api/iio/core.rst
+++ b/Documentation/driver-api/iio/core.rst
@@ -10,7 +10,7 @@ applications manipulating sensors. The implementation can be found under
Industrial I/O Devices
----------------------
-* struct :c:type:`iio_dev` - industrial I/O device
+* struct iio_dev - industrial I/O device
* iio_device_alloc() - allocate an :c:type:`iio_dev` from a driver
* iio_device_free() - free an :c:type:`iio_dev` from a driver
* iio_device_register() - register a device with the IIO subsystem
@@ -66,7 +66,7 @@ Common attributes are:
IIO device channels
===================
-struct :c:type:`iio_chan_spec` - specification of a single channel
+struct iio_chan_spec - specification of a single channel
An IIO device channel is a representation of a data channel. An IIO device can
have one or multiple channels. For example:
@@ -77,7 +77,7 @@ have one or multiple channels. For example:
* an accelerometer can have up to 3 channels representing acceleration on X, Y
and Z axes.
-An IIO channel is described by the struct :c:type:`iio_chan_spec`.
+An IIO channel is described by the struct iio_chan_spec.
A thermometer driver for the temperature sensor in the example above would
have to describe its channel as follows::
diff --git a/Documentation/driver-api/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst
index 819fb9edc005..76133a3796f2 100644
--- a/Documentation/driver-api/iio/hw-consumer.rst
+++ b/Documentation/driver-api/iio/hw-consumer.rst
@@ -8,7 +8,7 @@ software buffer for data. The implementation can be found under
:file:`drivers/iio/buffer/hw-consumer.c`
-* struct :c:type:`iio_hw_consumer` — Hardware consumer structure
+* struct iio_hw_consumer — Hardware consumer structure
* :c:func:`iio_hw_consumer_alloc` — Allocate IIO hardware consumer
* :c:func:`iio_hw_consumer_free` — Free IIO hardware consumer
* :c:func:`iio_hw_consumer_enable` — Enable IIO hardware consumer
diff --git a/Documentation/driver-api/iio/triggered-buffers.rst b/Documentation/driver-api/iio/triggered-buffers.rst
index 0db12660cc90..417555dbbdf4 100644
--- a/Documentation/driver-api/iio/triggered-buffers.rst
+++ b/Documentation/driver-api/iio/triggered-buffers.rst
@@ -10,7 +10,7 @@ IIO triggered buffer setup
* :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc
* :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by
:c:func:`iio_triggered_buffer_setup`
-* struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks
+* struct iio_buffer_setup_ops — buffer setup related callbacks
A typical triggered buffer setup looks like this::
diff --git a/Documentation/driver-api/iio/triggers.rst b/Documentation/driver-api/iio/triggers.rst
index dfd7ba3eabde..288625e40672 100644
--- a/Documentation/driver-api/iio/triggers.rst
+++ b/Documentation/driver-api/iio/triggers.rst
@@ -2,7 +2,7 @@
Triggers
========
-* struct :c:type:`iio_trigger` — industrial I/O trigger device
+* struct iio_trigger — industrial I/O trigger device
* :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc
* :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register
iio_trigger_unregister
@@ -63,7 +63,7 @@ Let's see a simple example of how to setup a trigger to be used by a driver::
IIO trigger ops
===============
-* struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger.
+* struct iio_trigger_ops — operations structure for an iio_trigger.
Notice that a trigger has a set of operations attached:
diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst
index b362109bb131..91f77fe58e83 100644
--- a/Documentation/driver-api/media/dtv-frontend.rst
+++ b/Documentation/driver-api/media/dtv-frontend.rst
@@ -125,7 +125,7 @@ responsible for tuning the device. It supports multiple algorithms to
detect a channel, as defined at enum :c:func:`dvbfe_algo`.
The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
-doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to
+doesn't fill its field at struct dvb_frontend_ops, it will default to
``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning,
e. g. it will try first to use the specified center frequency ``f``,
then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|,
@@ -140,7 +140,7 @@ define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.
a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to
define its own hardware-assisted algorithm. Very few hardware need to
use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other
- function callbacks at struct :c:type:`dvb_frontend_ops`.
+ function callbacks at struct dvb_frontend_ops.
Attaching frontend driver to the bridge driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst
index 05bba0b61748..57b5bbba944e 100644
--- a/Documentation/driver-api/media/mc-core.rst
+++ b/Documentation/driver-api/media/mc-core.rst
@@ -36,7 +36,7 @@ pad to a sink pad.
Media device
^^^^^^^^^^^^
-A media device is represented by a struct :c:type:`media_device`
+A media device is represented by a struct media_device
instance, defined in ``include/media/media-device.h``.
Allocation of the structure is handled by the media device driver, usually by
embedding the :c:type:`media_device` instance in a larger driver-specific
@@ -49,7 +49,7 @@ and unregistered by calling :c:func:`media_device_unregister()`.
Entities
^^^^^^^^
-Entities are represented by a struct :c:type:`media_entity`
+Entities are represented by a struct media_entity
instance, defined in ``include/media/media-entity.h``. The structure is usually
embedded into a higher-level structure, such as
:c:type:`v4l2_subdev` or :c:type:`video_device`
@@ -67,10 +67,10 @@ Interfaces
^^^^^^^^^^
Interfaces are represented by a
-struct :c:type:`media_interface` instance, defined in
+struct media_interface instance, defined in
``include/media/media-entity.h``. Currently, only one type of interface is
defined: a device node. Such interfaces are represented by a
-struct :c:type:`media_intf_devnode`.
+struct media_intf_devnode.
Drivers initialize and create device node interfaces by calling
:c:func:`media_devnode_create()`
@@ -79,7 +79,7 @@ and remove them by calling:
Pads
^^^^
-Pads are represented by a struct :c:type:`media_pad` instance,
+Pads are represented by a struct media_pad instance,
defined in ``include/media/media-entity.h``. Each entity stores its pads in
a pads array managed by the entity driver. Drivers usually embed the array in
a driver-specific structure.
@@ -87,8 +87,8 @@ a driver-specific structure.
Pads are identified by their entity and their 0-based index in the pads
array.
-Both information are stored in the struct :c:type:`media_pad`,
-making the struct :c:type:`media_pad` pointer the canonical way
+Both information are stored in the struct media_pad,
+making the struct media_pad pointer the canonical way
to store and pass link references.
Pads have flags that describe the pad capabilities and state.
@@ -104,7 +104,7 @@ Pads have flags that describe the pad capabilities and state.
Links
^^^^^
-Links are represented by a struct :c:type:`media_link` instance,
+Links are represented by a struct media_link instance,
defined in ``include/media/media-entity.h``. There are two types of links:
**1. pad to pad links**:
@@ -187,7 +187,7 @@ Use count and power handling
Due to the wide differences between drivers regarding power management
needs, the media controller does not implement power management. However,
-the struct :c:type:`media_entity` includes a ``use_count``
+the struct media_entity includes a ``use_count``
field that media drivers
can use to track the number of users of every entity for power management
needs.
@@ -213,11 +213,11 @@ prevent link states from being modified during streaming by calling
The function will mark all entities connected to the given entity through
enabled links, either directly or indirectly, as streaming.
-The struct :c:type:`media_pipeline` instance pointed to by
+The struct media_pipeline instance pointed to by
the pipe argument will be stored in every entity in the pipeline.
-Drivers should embed the struct :c:type:`media_pipeline`
+Drivers should embed the struct media_pipeline
in higher-level pipeline structures and can then access the
-pipeline through the struct :c:type:`media_entity`
+pipeline through the struct media_entity
pipe field.
Calls to :c:func:`media_pipeline_start()` can be nested.
diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst
index 5129019afb49..77f42ea3bac7 100644
--- a/Documentation/driver-api/media/v4l2-controls.rst
+++ b/Documentation/driver-api/media/v4l2-controls.rst
@@ -27,7 +27,7 @@ V4L2 specification with respect to controls in a central place. And to make
life as easy as possible for the driver developer.
Note that the control framework relies on the presence of a struct
-:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for
+:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for
sub-device drivers.
diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst
index 63c064837c00..666330af31ed 100644
--- a/Documentation/driver-api/media/v4l2-dev.rst
+++ b/Documentation/driver-api/media/v4l2-dev.rst
@@ -67,7 +67,7 @@ You should also set these fields of :c:type:`video_device`:
file operation is called this lock will be taken by the core and released
afterwards. See the next section for more details.
-- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
+- :c:type:`video_device`->queue: a pointer to the struct vb2_queue
associated with this device node.
If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
@@ -81,7 +81,7 @@ You should also set these fields of :c:type:`video_device`:
- :c:type:`video_device`->prio: keeps track of the priorities. Used to
implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
- If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state`
+ If left to ``NULL``, then it will use the struct v4l2_prio_state
in :c:type:`v4l2_device`. If you want to have a separate priority state per
(group of) device node(s), then you can point it to your own struct
:c:type:`v4l2_prio_state`.
@@ -95,7 +95,7 @@ You should also set these fields of :c:type:`video_device`:
but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
(cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
devices at the same time it is setup without a parent device. But when the
- struct :c:type:`video_device` is initialized you **do** know which parent
+ struct video_device is initialized you **do** know which parent
PCI device to use and so you set ``dev_device`` to the correct PCI device.
If you use :c:type:`v4l2_ioctl_ops`, then you should set
@@ -138,7 +138,7 @@ ioctls and locking
------------------
The V4L core provides optional locking services. The main service is the
-lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
+lock field in struct video_device, which is a pointer to a mutex.
If you set this pointer, then that will be used by unlocked_ioctl to
serialize all ioctls.
diff --git a/Documentation/driver-api/media/v4l2-device.rst b/Documentation/driver-api/media/v4l2-device.rst
index 5e25bf182c18..7bd9c45f551b 100644
--- a/Documentation/driver-api/media/v4l2-device.rst
+++ b/Documentation/driver-api/media/v4l2-device.rst
@@ -3,7 +3,7 @@
V4L2 device instance
--------------------
-Each device instance is represented by a struct :c:type:`v4l2_device`.
+Each device instance is represented by a struct v4l2_device.
Very simple devices can just allocate this struct, but most of the time you
would embed this struct inside a larger struct.
@@ -18,9 +18,9 @@ dev->driver_data field is ``NULL``, it will be linked to
Drivers that want integration with the media device framework need to set
dev->driver_data manually to point to the driver-specific device structure
-that embed the struct :c:type:`v4l2_device` instance. This is achieved by a
+that embed the struct v4l2_device instance. This is achieved by a
``dev_set_drvdata()`` call before registering the V4L2 device instance.
-They must also set the struct :c:type:`v4l2_device` mdev field to point to a
+They must also set the struct v4l2_device mdev field to point to a
properly initialized and registered :c:type:`media_device` instance.
If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
diff --git a/Documentation/driver-api/media/v4l2-event.rst b/Documentation/driver-api/media/v4l2-event.rst
index a4b7ae2b94d8..5b8254eba7da 100644
--- a/Documentation/driver-api/media/v4l2-event.rst
+++ b/Documentation/driver-api/media/v4l2-event.rst
@@ -44,18 +44,18 @@ such objects.
So to summarize:
-- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events,
+- struct v4l2_fh has two lists: one of the ``subscribed`` events,
and one of the ``available`` events.
-- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised
+- struct v4l2_subscribed_event has a ringbuffer of raised
(pending) events of that particular type.
-- If struct :c:type:`v4l2_subscribed_event` is associated with a specific
+- If struct v4l2_subscribed_event is associated with a specific
object, then that object will have an internal list of
- struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an
+ struct v4l2_subscribed_event so it knows who subscribed an
event to that object.
-Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has
+Furthermore, the internal struct v4l2_subscribed_event has
``merge()`` and ``replace()`` callbacks which drivers can set. These
callbacks are called when a new event is raised and there is no more room.
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index 4c62b19af744..3eeaa8da0c9e 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -3,11 +3,11 @@
V4L2 File handlers
------------------
-struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
+struct v4l2_fh provides a way to easily keep file handle specific
data that is used by the V4L2 framework.
.. attention::
- New drivers must use struct :c:type:`v4l2_fh`
+ New drivers must use struct v4l2_fh
since it is also used to implement priority handling
(:ref:`VIDIOC_G_PRIORITY`).
@@ -16,11 +16,11 @@ whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
This bit is set whenever :c:func:`v4l2_fh_init` is called.
-struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
+struct v4l2_fh is allocated as a part of the driver's own file handle
structure and ``file->private_data`` is set to it in the driver's ``open()``
function by the driver.
-In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
+In many cases the struct v4l2_fh will be embedded in a larger
structure. In that case you should call:
#) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()``
@@ -102,18 +102,18 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
memory can be freed.
-If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
+If struct v4l2_fh is not embedded, then you can use these helper functions:
:c:func:`v4l2_fh_open <v4l2_fh_open>`
(struct file \*filp)
-- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
- the struct :c:type:`video_device` associated with the file struct.
+- This allocates a struct v4l2_fh, initializes it and adds it to
+ the struct video_device associated with the file struct.
:c:func:`v4l2_fh_release <v4l2_fh_release>`
(struct file \*filp)
-- This deletes it from the struct :c:type:`video_device` associated with the
+- This deletes it from the struct video_device associated with the
file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
These two functions can be plugged into the v4l2_file_operation's ``open()``
diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 6248ea99e979..bb5b1a7cdfd9 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -110,7 +110,7 @@ pads:
err = media_entity_pads_init(&sd->entity, npads, pads);
The pads array must have been previously initialized. There is no need to
-manually set the struct :c:type:`media_entity` function and name fields, but the
+manually set the struct media_entity function and name fields, but the
revision field must be initialized if needed.
A reference to the entity will be automatically acquired/released when the
diff --git a/Documentation/driver-api/regulator.rst b/Documentation/driver-api/regulator.rst
index 520da0a5251d..b43c78eb24d8 100644
--- a/Documentation/driver-api/regulator.rst
+++ b/Documentation/driver-api/regulator.rst
@@ -116,7 +116,7 @@ core, providing operations structures to the core. A notifier interface
allows error conditions to be reported to the core.
Registration should be triggered by explicit setup done by the platform,
-supplying a struct :c:type:`regulator_init_data` for the regulator
+supplying a struct regulator_init_data for the regulator
containing constraint and supply information.
Machine interface
@@ -144,7 +144,7 @@ a given system, for example supporting higher supply voltages than the
consumers are rated for.
This is done at driver registration time` by providing a
-struct :c:type:`regulation_constraints`.
+struct regulation_constraints.
The constraints may also specify an initial configuration for the
regulator in the constraints, which is particularly useful for use with
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst
index 1e4abc896a0d..a182c0f5e38a 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -47,7 +47,7 @@ called USB Request Block, or URB for short.
The URB structure
=================
-Some of the fields in struct :c:type:`urb` are::
+Some of the fields in struct urb are::
struct urb
{
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index 3e8a3809c0b8..09396edd6131 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -176,9 +176,9 @@ Kernel Mode Gadget API
Gadget drivers declare themselves through a struct
:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
-for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
-involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
-the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
+for a struct usb_gadget. The response to a set_configuration usually
+involves enabling one or more of the struct usb_ep objects exposed by
+the gadget, and submitting one or more struct usb_request buffers to
transfer data. Understand those four data types, and their operations,
and you will understand how this API works.
@@ -339,8 +339,8 @@ multi-configuration devices (also more than one function, but not
necessarily sharing a given configuration). There is however an optional
framework which makes it easier to reuse and combine functions.
-Devices using this framework provide a struct :c:type:`usb_composite_driver`,
-which in turn provides one or more struct :c:type:`usb_configuration`
+Devices using this framework provide a struct usb_composite_driver,
+which in turn provides one or more struct usb_configuration
instances. Each such configuration includes at least one struct
:c:type:`usb_function`, which packages a user visible role such as "network
link" or "mass storage device". Management functions may also exist,
diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst
index 79663e653ca1..c1e13107c50e 100644
--- a/Documentation/driver-api/usb/hotplug.rst
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -122,7 +122,7 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this::
Most USB device drivers should pass these tables to the USB subsystem as
well as to the module management subsystem. Not all, though: some driver
frameworks connect using interfaces layered over USB, and so they won't
-need such a struct :c:type:`usb_driver`.
+need such a struct usb_driver.
Drivers that connect directly to the USB subsystem should be declared
something like this::
diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 423c5a0daf45..4f858b38a412 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -437,7 +437,7 @@ FS_IOC_SET_ENCRYPTION_POLICY
The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
empty directory or verifies that a directory or regular file already
has the specified encryption policy. It takes in a pointer to a
-:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
+struct fscrypt_policy_v1 or a :c:type:`struct
fscrypt_policy_v2`, defined as follows::
#define FSCRYPT_POLICY_V1 0
@@ -508,7 +508,7 @@ This structure must be initialized as follows:
replaced with ``master_key_identifier``, which is longer and cannot
be arbitrarily chosen. Instead, the key must first be added using
`FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
- the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
+ the kernel returned in the struct fscrypt_add_key_arg must
be used as the ``master_key_identifier`` in the :c:type:`struct
fscrypt_policy_v2`.
@@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX
The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
policy, if any, for a directory or regular file. No additional
permissions are required beyond the ability to open the file. It
-takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
+takes in a pointer to a struct fscrypt_get_policy_ex_arg,
defined as follows::
struct fscrypt_get_policy_ex_arg {
@@ -680,7 +680,7 @@ the filesystem, making all files on the filesystem which were
encrypted using that key appear "unlocked", i.e. in plaintext form.
It can be executed on any file or directory on the target filesystem,
but using the filesystem's root directory is recommended. It takes in
-a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
+a pointer to a struct fscrypt_add_key_arg, defined as
follows::
struct fscrypt_add_key_arg {
@@ -710,7 +710,7 @@ follows::
__u8 raw[];
};
-:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
+struct fscrypt_add_key_arg must be zeroed, then initialized
as follows:
- If the key is being added for use by v1 encryption policies, then
@@ -860,7 +860,7 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
encryption key from the filesystem, and possibly removes the key
itself. It can be executed on any file or directory on the target
filesystem, but using the filesystem's root directory is recommended.
-It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
+It takes in a pointer to a struct fscrypt_remove_key_arg,
defined as follows::
struct fscrypt_remove_key_arg {
@@ -1149,7 +1149,7 @@ Encryption context
------------------
An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is
+fscrypt_context_v1` or a struct fscrypt_context_v2. It is
up to individual filesystems to decide where to store it, but normally
it would be stored in a hidden extended attribute. It should *not* be
exposed by the xattr-related system calls such as getxattr() and
diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst
index 6c8944f6f0f7..895e9711ed88 100644
--- a/Documentation/filesystems/fsverity.rst
+++ b/Documentation/filesystems/fsverity.rst
@@ -84,7 +84,7 @@ FS_IOC_ENABLE_VERITY
--------------------
The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes
-in a pointer to a :c:type:`struct fsverity_enable_arg`, defined as
+in a pointer to a struct fsverity_enable_arg, defined as
follows::
struct fsverity_enable_arg {
diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst
index 78bc5572f829..b0a7e3010187 100644
--- a/Documentation/sound/designs/tracepoints.rst
+++ b/Documentation/sound/designs/tracepoints.rst
@@ -34,20 +34,20 @@ substream. In this procedure, PCM hardware parameters are decided by
interaction between applications and ALSA PCM core. Once decided, runtime of
the PCM substream keeps the parameters.
-The parameters are described in :c:type:`struct snd_pcm_hw_params`. This
+The parameters are described in struct snd_pcm_hw_params. This
structure includes several types of parameters. Applications set preferable
value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE
or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available
set of parameters. The latter is used for an actual decision of the parameters.
-The :c:type:`struct snd_pcm_hw_params` structure has below members:
+The struct snd_pcm_hw_params structure has below members:
``flags``
Configurable. ALSA PCM core and some drivers handle this flag to select
convenient parameters or change their behaviour.
``masks``
Configurable. This type of parameter is described in
- :c:type:`struct snd_mask` and represent mask values. As of PCM protocol
+ struct snd_mask and represent mask values. As of PCM protocol
v2.0.13, three types are defined.
- SNDRV_PCM_HW_PARAM_ACCESS
@@ -55,7 +55,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
- SNDRV_PCM_HW_PARAM_SUBFORMAT
``intervals``
Configurable. This type of parameter is described in
- :c:type:`struct snd_interval` and represent values with a range. As of
+ struct snd_interval and represent values with a range. As of
PCM protocol v2.0.13, twelve types are defined.
- SNDRV_PCM_HW_PARAM_SAMPLE_BITS
@@ -78,7 +78,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
are going to be changed.
``cmask``
Read-only. After returning from ioctl(2), buffer in user space for
- :c:type:`struct snd_pcm_hw_params` includes result of each operation.
+ struct snd_pcm_hw_params includes result of each operation.
This mask represents which mask/interval parameter is actually changed.
``info``
Read-only. This represents hardware/driver capabilities as bit flags
@@ -110,10 +110,10 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
value to this parameter but some drivers intentionally set zero with
a care of hardware design or data transmission protocol.
-ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when
+ALSA PCM core handles buffer of struct snd_pcm_hw_params when
applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
Parameters in the buffer are changed according to
-:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The
+struct snd_pcm_hardware and rules of constraints in the runtime. The
structure describes capabilities of handled hardware. The rules describes
dependencies on which a parameter is decided according to several parameters.
A rule has a callback function, and drivers can register arbitrary functions
@@ -121,17 +121,17 @@ to compute the target parameter. ALSA PCM core registers some rules to the
runtime as a default.
Each driver can join in the interaction as long as it prepared for two stuffs
-in a callback of :c:type:`struct snd_pcm_ops.open`.
+in a callback of struct snd_pcm_ops.open.
1. In the callback, drivers are expected to change a member of
- :c:type:`struct snd_pcm_hardware` type in the runtime, according to
+ struct snd_pcm_hardware type in the runtime, according to
capacities of corresponding hardware.
2. In the same callback, drivers are also expected to register additional rules
of constraints into the runtime when several parameters have dependencies
due to hardware design.
The driver can refers to result of the interaction in a callback of
-:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the
+struct snd_pcm_ops.hw_params, however it should not change the
content.
Tracepoints in this category are designed to trace changes of the
@@ -163,7 +163,7 @@ fields are different according to type of the parameter. For parameters of mask
type, the fields represent hexadecimal dump of content of the parameter. For
parameters of interval type, the fields represent values of each member of
``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in
-:c:type:`struct snd_interval` in this order.
+struct snd_interval in this order.
Tracepoints in drivers
======================
--git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index 00a69aceff44..1910079f984f 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -110,7 +110,7 @@ while (<IN>) {
) {
my $s = $1;
- $structs{$s} = "struct :c:type:`$s`\\ ";
+ $structs{$s} = "struct $s\\ ";
next;
}
}
diff --git a/Documentation/vm/ksm.rst b/Documentation/vm/ksm.rst
index d1b7270ad55c..9e37add068e6 100644
--- a/Documentation/vm/ksm.rst
+++ b/Documentation/vm/ksm.rst
@@ -26,7 +26,7 @@ tree.
If a KSM page is shared between less than ``max_page_sharing`` VMAs,
the node of the stable tree that represents such KSM page points to a
-list of :c:type:`struct rmap_item` and the ``page->mapping`` of the
+list of struct rmap_item and the ``page->mapping`` of the
KSM page points to the stable tree node.
When the sharing passes this threshold, KSM adds a second dimension to
diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst
index 769449734573..9daadf9faba1 100644
--- a/Documentation/vm/memory-model.rst
+++ b/Documentation/vm/memory-model.rst
@@ -24,7 +24,7 @@ whether it is possible to manually override that default.
although it is still in use by several architectures.
All the memory models track the status of physical page frames using
-:c:type:`struct page` arranged in one or more arrays.
+struct page arranged in one or more arrays.
Regardless of the selected memory model, there exists one-to-one
mapping between the physical page frame number (PFN) and the
@@ -111,7 +111,7 @@ maps for non-volatile memory devices and deferred initialization of
the memory map for larger systems.
The SPARSEMEM model presents the physical memory as a collection of
-sections. A section is represented with :c:type:`struct mem_section`
+sections. A section is represented with struct mem_section
that contains `section_mem_map` that is, logically, a pointer to an
array of struct pages. However, it is stored with some other magic
that aids the sections management. The section size and maximal number
@@ -172,7 +172,7 @@ management.
The virtually mapped memory map allows storing `struct page` objects
for persistent memory devices in pre-allocated storage on those
-devices. This storage is represented with :c:type:`struct vmem_altmap`
+devices. This storage is represented with struct vmem_altmap
that is eventually passed to vmemmap_populate() through a long chain
of function calls. The vmemmap_populate() implementation may use the
`vmem_altmap` along with :c:func:`vmemmap_alloc_block_buf` helper to
diff --git a/mm/ksm.c b/mm/ksm.c
index 9afccc36dbd2..0960750bb316 100644
--- a/mm/ksm.c
+++ b/mm/ksm.c
@@ -81,7 +81,7 @@
* different KSM page copy of that content
*
* Internally, the regular nodes, "dups" and "chains" are represented
- * using the same :c:type:`struct stable_node` structure.
+ * using the same struct stable_node structure.
*
* In addition to the stable tree, KSM uses a second data structure called the
* unstable tree: this tree holds pointers to pages which have been found to
diff --git a/mm/memblock.c b/mm/memblock.c
index 326c6b3fec1d..b68ee86788af 100644
--- a/mm/memblock.c
+++ b/mm/memblock.c
@@ -48,12 +48,12 @@
* boot regardless of the possible restrictions and memory hot(un)plug;
* the ``physmem`` type is only available on some architectures.
*
- * Each region is represented by :c:type:`struct memblock_region` that
+ * Each region is represented by struct memblock_region that
* defines the region extents, its attributes and NUMA node id on NUMA
* systems. Every memory type is described by the struct memblock_type
* which contains an array of memory regions along with
* the allocator metadata. The "memory" and "reserved" types are nicely
- * wrapped with :c:type:`struct memblock`. This structure is statically
+ * wrapped with struct memblock. This structure is statically
* initialized at build time. The region arrays are initially sized to
* %INIT_MEMBLOCK_REGIONS for "memory" and %INIT_MEMBLOCK_RESERVED_REGIONS
* for "reserved". The region array for "physmem" is initially sized to
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: alsa-devel, Tom Rix, linux-fpga, André Almeida, linux-mm,
Mauro Carvalho Chehab, Satya Tangirala, Eric Biggers,
Alexandru Ardelean, linux-media, Anshuman Khandual,
linux-fscrypt, Moritz Fischer, Jonathan Cameron, Jaegeuk Kim,
Mauro Carvalho Chehab, Jens Axboe, Theodore Y. Ts'o,
Puranjay Mohan, Greg Kroah-Hartman, Randy Dunlap, Takashi Iwai,
linux-kernel, Alexander A. Klimov, Andrew Morton, Mike Rapoport
The :c:type:`foo` only works properly with structs before
Sphinx 3.x.
On Sphinx 3.x, structs should now be declared using the
.. c:struct, and referenced via :c:struct tag.
As we now have the automarkup.py macro, that automatically
convert:
struct foo
into cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/block/blk-mq.rst | 8 +++----
Documentation/block/inline-encryption.rst | 8 +++----
Documentation/driver-api/fpga/fpga-bridge.rst | 4 ++--
Documentation/driver-api/fpga/fpga-mgr.rst | 4 ++--
Documentation/driver-api/fpga/fpga-region.rst | 2 +-
Documentation/driver-api/iio/buffers.rst | 2 +-
Documentation/driver-api/iio/core.rst | 6 ++---
Documentation/driver-api/iio/hw-consumer.rst | 2 +-
.../driver-api/iio/triggered-buffers.rst | 2 +-
Documentation/driver-api/iio/triggers.rst | 4 ++--
.../driver-api/media/dtv-frontend.rst | 4 ++--
Documentation/driver-api/media/mc-core.rst | 24 +++++++++----------
.../driver-api/media/v4l2-controls.rst | 2 +-
Documentation/driver-api/media/v4l2-dev.rst | 8 +++----
.../driver-api/media/v4l2-device.rst | 6 ++---
Documentation/driver-api/media/v4l2-event.rst | 10 ++++----
Documentation/driver-api/media/v4l2-fh.rst | 16 ++++++-------
.../driver-api/media/v4l2-subdev.rst | 2 +-
Documentation/driver-api/regulator.rst | 4 ++--
Documentation/driver-api/usb/URB.rst | 2 +-
Documentation/driver-api/usb/gadget.rst | 10 ++++----
Documentation/driver-api/usb/hotplug.rst | 2 +-
Documentation/filesystems/fscrypt.rst | 14 +++++------
Documentation/filesystems/fsverity.rst | 2 +-
Documentation/sound/designs/tracepoints.rst | 22 ++++++++---------
| 2 +-
Documentation/vm/ksm.rst | 2 +-
Documentation/vm/memory-model.rst | 6 ++---
mm/ksm.c | 2 +-
mm/memblock.c | 4 ++--
30 files changed, 93 insertions(+), 93 deletions(-)
diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
index 88c56afcb070..86a632af02b0 100644
--- a/Documentation/block/blk-mq.rst
+++ b/Documentation/block/blk-mq.rst
@@ -63,10 +63,10 @@ Software staging queues
~~~~~~~~~~~~~~~~~~~~~~~
The block IO subsystem adds requests in the software staging queues
-(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent
+(represented by struct blk_mq_ctx) in case that they weren't sent
directly to the driver. A request is one or more BIOs. They arrived at the
-block layer through the data structure struct :c:type:`bio`. The block layer
-will then build a new structure from it, the struct :c:type:`request` that will
+block layer through the data structure struct bio. The block layer
+will then build a new structure from it, the struct request that will
be used to communicate with the device driver. Each queue has its own lock and
the number of queues is defined by a per-CPU or per-node basis.
@@ -102,7 +102,7 @@ hardware queue will be drained in sequence according to their mapping.
Hardware dispatch queues
~~~~~~~~~~~~~~~~~~~~~~~~
-The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct
+The hardware queue (represented by struct blk_mq_hw_ctx) is a struct
used by device drivers to map the device submission queues (or device DMA ring
buffer), and are the last step of the block layer submission code before the
low level device driver taking ownership of the request. To run this queue, the
diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst
index 354817b80887..e75151e467d3 100644
--- a/Documentation/block/inline-encryption.rst
+++ b/Documentation/block/inline-encryption.rst
@@ -52,7 +52,7 @@ Constraints and notes
Design
======
-We add a :c:type:`struct bio_crypt_ctx` to :c:type:`struct bio` that can
+We add a struct bio_crypt_ctx to struct bio that can
represent an encryption context, because we need to be able to pass this
encryption context from the upper layers (like the fs layer) to the
device driver to act upon.
@@ -85,7 +85,7 @@ blk-mq changes, other block layer changes and blk-crypto-fallback
=================================================================
We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to
-:c:type:`struct request`. These will be referred to as the ``crypto fields``
+struct request. These will be referred to as the ``crypto fields``
for the request. This ``keyslot`` is the keyslot into which the
``bi_crypt_context`` has been programmed in the KSM of the ``request_queue``
that this request is being sent to.
@@ -118,7 +118,7 @@ of the algorithm being used adheres to spec and functions correctly).
If a ``request queue``'s inline encryption hardware claimed to support the
encryption context specified with a bio, then it will not be handled by the
``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a
-:c:type:`struct request` needs to be allocated for that bio. At that point,
+struct request needs to be allocated for that bio. At that point,
blk-mq tries to program the encryption context into the ``request_queue``'s
keyslot_manager, and obtain a keyslot, which it stores in its newly added
``keyslot`` field. This keyslot is released when the request is completed.
@@ -188,7 +188,7 @@ keyslots supported by the hardware.
The device driver also needs to tell the KSM how to actually manipulate the
IE hardware in the device to do things like programming the crypto key into
the IE hardware into a particular keyslot. All this is achieved through the
-:c:type:`struct blk_ksm_ll_ops` field in the KSM that the device driver
+struct blk_ksm_ll_ops field in the KSM that the device driver
must fill up after initing the ``blk_keyslot_manager``.
The KSM also handles runtime power management for the device when applicable
diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst
index ccd677ba7d76..198aadafd3e7 100644
--- a/Documentation/driver-api/fpga/fpga-bridge.rst
+++ b/Documentation/driver-api/fpga/fpga-bridge.rst
@@ -4,8 +4,8 @@ FPGA Bridge
API to implement a new FPGA bridge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* struct :c:type:`fpga_bridge` — The FPGA Bridge structure
-* struct :c:type:`fpga_bridge_ops` — Low level Bridge driver ops
+* struct fpga_bridge — The FPGA Bridge structure
+* struct fpga_bridge_ops — Low level Bridge driver ops
* devm_fpga_bridge_create() — Allocate and init a bridge struct
* fpga_bridge_register() — Register a bridge
* fpga_bridge_unregister() — Unregister a bridge
diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
index af5382af1379..22f7885b32c9 100644
--- a/Documentation/driver-api/fpga/fpga-mgr.rst
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -102,8 +102,8 @@ API for implementing a new FPGA Manager driver
----------------------------------------------
* ``fpga_mgr_states`` — Values for :c:member:`fpga_manager->state`.
-* struct :c:type:`fpga_manager` — the FPGA manager struct
-* struct :c:type:`fpga_manager_ops` — Low level FPGA manager driver ops
+* struct fpga_manager — the FPGA manager struct
+* struct fpga_manager_ops — Low level FPGA manager driver ops
* devm_fpga_mgr_create() — Allocate and init a manager struct
* fpga_mgr_register() — Register an FPGA manager
* fpga_mgr_unregister() — Unregister an FPGA manager
diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
index 31118a8ba218..3e52be7e2968 100644
--- a/Documentation/driver-api/fpga/fpga-region.rst
+++ b/Documentation/driver-api/fpga/fpga-region.rst
@@ -45,7 +45,7 @@ An example of usage can be seen in the probe function of [#f2]_.
API to add a new FPGA region
----------------------------
-* struct :c:type:`fpga_region` — The FPGA region struct
+* struct fpga_region — The FPGA region struct
* devm_fpga_region_create() — Allocate and init a region struct
* fpga_region_register() — Register an FPGA region
* fpga_region_unregister() — Unregister an FPGA region
diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index dd64c9c5fb1e..3ddebddc02ca 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -2,7 +2,7 @@
Buffers
=======
-* struct :c:type:`iio_buffer` — general buffer structure
+* struct iio_buffer — general buffer structure
* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
is selected
* :c:func:`iio_buffer_get` — Grab a reference to the buffer
diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-api/iio/core.rst
index 51b21e002396..715cf29482a1 100644
--- a/Documentation/driver-api/iio/core.rst
+++ b/Documentation/driver-api/iio/core.rst
@@ -10,7 +10,7 @@ applications manipulating sensors. The implementation can be found under
Industrial I/O Devices
----------------------
-* struct :c:type:`iio_dev` - industrial I/O device
+* struct iio_dev - industrial I/O device
* iio_device_alloc() - allocate an :c:type:`iio_dev` from a driver
* iio_device_free() - free an :c:type:`iio_dev` from a driver
* iio_device_register() - register a device with the IIO subsystem
@@ -66,7 +66,7 @@ Common attributes are:
IIO device channels
===================
-struct :c:type:`iio_chan_spec` - specification of a single channel
+struct iio_chan_spec - specification of a single channel
An IIO device channel is a representation of a data channel. An IIO device can
have one or multiple channels. For example:
@@ -77,7 +77,7 @@ have one or multiple channels. For example:
* an accelerometer can have up to 3 channels representing acceleration on X, Y
and Z axes.
-An IIO channel is described by the struct :c:type:`iio_chan_spec`.
+An IIO channel is described by the struct iio_chan_spec.
A thermometer driver for the temperature sensor in the example above would
have to describe its channel as follows::
diff --git a/Documentation/driver-api/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst
index 819fb9edc005..76133a3796f2 100644
--- a/Documentation/driver-api/iio/hw-consumer.rst
+++ b/Documentation/driver-api/iio/hw-consumer.rst
@@ -8,7 +8,7 @@ software buffer for data. The implementation can be found under
:file:`drivers/iio/buffer/hw-consumer.c`
-* struct :c:type:`iio_hw_consumer` — Hardware consumer structure
+* struct iio_hw_consumer — Hardware consumer structure
* :c:func:`iio_hw_consumer_alloc` — Allocate IIO hardware consumer
* :c:func:`iio_hw_consumer_free` — Free IIO hardware consumer
* :c:func:`iio_hw_consumer_enable` — Enable IIO hardware consumer
diff --git a/Documentation/driver-api/iio/triggered-buffers.rst b/Documentation/driver-api/iio/triggered-buffers.rst
index 0db12660cc90..417555dbbdf4 100644
--- a/Documentation/driver-api/iio/triggered-buffers.rst
+++ b/Documentation/driver-api/iio/triggered-buffers.rst
@@ -10,7 +10,7 @@ IIO triggered buffer setup
* :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc
* :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by
:c:func:`iio_triggered_buffer_setup`
-* struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks
+* struct iio_buffer_setup_ops — buffer setup related callbacks
A typical triggered buffer setup looks like this::
diff --git a/Documentation/driver-api/iio/triggers.rst b/Documentation/driver-api/iio/triggers.rst
index dfd7ba3eabde..288625e40672 100644
--- a/Documentation/driver-api/iio/triggers.rst
+++ b/Documentation/driver-api/iio/triggers.rst
@@ -2,7 +2,7 @@
Triggers
========
-* struct :c:type:`iio_trigger` — industrial I/O trigger device
+* struct iio_trigger — industrial I/O trigger device
* :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc
* :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register
iio_trigger_unregister
@@ -63,7 +63,7 @@ Let's see a simple example of how to setup a trigger to be used by a driver::
IIO trigger ops
===============
-* struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger.
+* struct iio_trigger_ops — operations structure for an iio_trigger.
Notice that a trigger has a set of operations attached:
diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst
index b362109bb131..91f77fe58e83 100644
--- a/Documentation/driver-api/media/dtv-frontend.rst
+++ b/Documentation/driver-api/media/dtv-frontend.rst
@@ -125,7 +125,7 @@ responsible for tuning the device. It supports multiple algorithms to
detect a channel, as defined at enum :c:func:`dvbfe_algo`.
The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
-doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to
+doesn't fill its field at struct dvb_frontend_ops, it will default to
``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning,
e. g. it will try first to use the specified center frequency ``f``,
then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|,
@@ -140,7 +140,7 @@ define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.
a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to
define its own hardware-assisted algorithm. Very few hardware need to
use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other
- function callbacks at struct :c:type:`dvb_frontend_ops`.
+ function callbacks at struct dvb_frontend_ops.
Attaching frontend driver to the bridge driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst
index 05bba0b61748..57b5bbba944e 100644
--- a/Documentation/driver-api/media/mc-core.rst
+++ b/Documentation/driver-api/media/mc-core.rst
@@ -36,7 +36,7 @@ pad to a sink pad.
Media device
^^^^^^^^^^^^
-A media device is represented by a struct :c:type:`media_device`
+A media device is represented by a struct media_device
instance, defined in ``include/media/media-device.h``.
Allocation of the structure is handled by the media device driver, usually by
embedding the :c:type:`media_device` instance in a larger driver-specific
@@ -49,7 +49,7 @@ and unregistered by calling :c:func:`media_device_unregister()`.
Entities
^^^^^^^^
-Entities are represented by a struct :c:type:`media_entity`
+Entities are represented by a struct media_entity
instance, defined in ``include/media/media-entity.h``. The structure is usually
embedded into a higher-level structure, such as
:c:type:`v4l2_subdev` or :c:type:`video_device`
@@ -67,10 +67,10 @@ Interfaces
^^^^^^^^^^
Interfaces are represented by a
-struct :c:type:`media_interface` instance, defined in
+struct media_interface instance, defined in
``include/media/media-entity.h``. Currently, only one type of interface is
defined: a device node. Such interfaces are represented by a
-struct :c:type:`media_intf_devnode`.
+struct media_intf_devnode.
Drivers initialize and create device node interfaces by calling
:c:func:`media_devnode_create()`
@@ -79,7 +79,7 @@ and remove them by calling:
Pads
^^^^
-Pads are represented by a struct :c:type:`media_pad` instance,
+Pads are represented by a struct media_pad instance,
defined in ``include/media/media-entity.h``. Each entity stores its pads in
a pads array managed by the entity driver. Drivers usually embed the array in
a driver-specific structure.
@@ -87,8 +87,8 @@ a driver-specific structure.
Pads are identified by their entity and their 0-based index in the pads
array.
-Both information are stored in the struct :c:type:`media_pad`,
-making the struct :c:type:`media_pad` pointer the canonical way
+Both information are stored in the struct media_pad,
+making the struct media_pad pointer the canonical way
to store and pass link references.
Pads have flags that describe the pad capabilities and state.
@@ -104,7 +104,7 @@ Pads have flags that describe the pad capabilities and state.
Links
^^^^^
-Links are represented by a struct :c:type:`media_link` instance,
+Links are represented by a struct media_link instance,
defined in ``include/media/media-entity.h``. There are two types of links:
**1. pad to pad links**:
@@ -187,7 +187,7 @@ Use count and power handling
Due to the wide differences between drivers regarding power management
needs, the media controller does not implement power management. However,
-the struct :c:type:`media_entity` includes a ``use_count``
+the struct media_entity includes a ``use_count``
field that media drivers
can use to track the number of users of every entity for power management
needs.
@@ -213,11 +213,11 @@ prevent link states from being modified during streaming by calling
The function will mark all entities connected to the given entity through
enabled links, either directly or indirectly, as streaming.
-The struct :c:type:`media_pipeline` instance pointed to by
+The struct media_pipeline instance pointed to by
the pipe argument will be stored in every entity in the pipeline.
-Drivers should embed the struct :c:type:`media_pipeline`
+Drivers should embed the struct media_pipeline
in higher-level pipeline structures and can then access the
-pipeline through the struct :c:type:`media_entity`
+pipeline through the struct media_entity
pipe field.
Calls to :c:func:`media_pipeline_start()` can be nested.
diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst
index 5129019afb49..77f42ea3bac7 100644
--- a/Documentation/driver-api/media/v4l2-controls.rst
+++ b/Documentation/driver-api/media/v4l2-controls.rst
@@ -27,7 +27,7 @@ V4L2 specification with respect to controls in a central place. And to make
life as easy as possible for the driver developer.
Note that the control framework relies on the presence of a struct
-:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for
+:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for
sub-device drivers.
diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst
index 63c064837c00..666330af31ed 100644
--- a/Documentation/driver-api/media/v4l2-dev.rst
+++ b/Documentation/driver-api/media/v4l2-dev.rst
@@ -67,7 +67,7 @@ You should also set these fields of :c:type:`video_device`:
file operation is called this lock will be taken by the core and released
afterwards. See the next section for more details.
-- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
+- :c:type:`video_device`->queue: a pointer to the struct vb2_queue
associated with this device node.
If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
@@ -81,7 +81,7 @@ You should also set these fields of :c:type:`video_device`:
- :c:type:`video_device`->prio: keeps track of the priorities. Used to
implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
- If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state`
+ If left to ``NULL``, then it will use the struct v4l2_prio_state
in :c:type:`v4l2_device`. If you want to have a separate priority state per
(group of) device node(s), then you can point it to your own struct
:c:type:`v4l2_prio_state`.
@@ -95,7 +95,7 @@ You should also set these fields of :c:type:`video_device`:
but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
(cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
devices at the same time it is setup without a parent device. But when the
- struct :c:type:`video_device` is initialized you **do** know which parent
+ struct video_device is initialized you **do** know which parent
PCI device to use and so you set ``dev_device`` to the correct PCI device.
If you use :c:type:`v4l2_ioctl_ops`, then you should set
@@ -138,7 +138,7 @@ ioctls and locking
------------------
The V4L core provides optional locking services. The main service is the
-lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
+lock field in struct video_device, which is a pointer to a mutex.
If you set this pointer, then that will be used by unlocked_ioctl to
serialize all ioctls.
diff --git a/Documentation/driver-api/media/v4l2-device.rst b/Documentation/driver-api/media/v4l2-device.rst
index 5e25bf182c18..7bd9c45f551b 100644
--- a/Documentation/driver-api/media/v4l2-device.rst
+++ b/Documentation/driver-api/media/v4l2-device.rst
@@ -3,7 +3,7 @@
V4L2 device instance
--------------------
-Each device instance is represented by a struct :c:type:`v4l2_device`.
+Each device instance is represented by a struct v4l2_device.
Very simple devices can just allocate this struct, but most of the time you
would embed this struct inside a larger struct.
@@ -18,9 +18,9 @@ dev->driver_data field is ``NULL``, it will be linked to
Drivers that want integration with the media device framework need to set
dev->driver_data manually to point to the driver-specific device structure
-that embed the struct :c:type:`v4l2_device` instance. This is achieved by a
+that embed the struct v4l2_device instance. This is achieved by a
``dev_set_drvdata()`` call before registering the V4L2 device instance.
-They must also set the struct :c:type:`v4l2_device` mdev field to point to a
+They must also set the struct v4l2_device mdev field to point to a
properly initialized and registered :c:type:`media_device` instance.
If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
diff --git a/Documentation/driver-api/media/v4l2-event.rst b/Documentation/driver-api/media/v4l2-event.rst
index a4b7ae2b94d8..5b8254eba7da 100644
--- a/Documentation/driver-api/media/v4l2-event.rst
+++ b/Documentation/driver-api/media/v4l2-event.rst
@@ -44,18 +44,18 @@ such objects.
So to summarize:
-- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events,
+- struct v4l2_fh has two lists: one of the ``subscribed`` events,
and one of the ``available`` events.
-- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised
+- struct v4l2_subscribed_event has a ringbuffer of raised
(pending) events of that particular type.
-- If struct :c:type:`v4l2_subscribed_event` is associated with a specific
+- If struct v4l2_subscribed_event is associated with a specific
object, then that object will have an internal list of
- struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an
+ struct v4l2_subscribed_event so it knows who subscribed an
event to that object.
-Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has
+Furthermore, the internal struct v4l2_subscribed_event has
``merge()`` and ``replace()`` callbacks which drivers can set. These
callbacks are called when a new event is raised and there is no more room.
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index 4c62b19af744..3eeaa8da0c9e 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -3,11 +3,11 @@
V4L2 File handlers
------------------
-struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
+struct v4l2_fh provides a way to easily keep file handle specific
data that is used by the V4L2 framework.
.. attention::
- New drivers must use struct :c:type:`v4l2_fh`
+ New drivers must use struct v4l2_fh
since it is also used to implement priority handling
(:ref:`VIDIOC_G_PRIORITY`).
@@ -16,11 +16,11 @@ whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
This bit is set whenever :c:func:`v4l2_fh_init` is called.
-struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
+struct v4l2_fh is allocated as a part of the driver's own file handle
structure and ``file->private_data`` is set to it in the driver's ``open()``
function by the driver.
-In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
+In many cases the struct v4l2_fh will be embedded in a larger
structure. In that case you should call:
#) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()``
@@ -102,18 +102,18 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
memory can be freed.
-If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
+If struct v4l2_fh is not embedded, then you can use these helper functions:
:c:func:`v4l2_fh_open <v4l2_fh_open>`
(struct file \*filp)
-- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
- the struct :c:type:`video_device` associated with the file struct.
+- This allocates a struct v4l2_fh, initializes it and adds it to
+ the struct video_device associated with the file struct.
:c:func:`v4l2_fh_release <v4l2_fh_release>`
(struct file \*filp)
-- This deletes it from the struct :c:type:`video_device` associated with the
+- This deletes it from the struct video_device associated with the
file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
These two functions can be plugged into the v4l2_file_operation's ``open()``
diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 6248ea99e979..bb5b1a7cdfd9 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -110,7 +110,7 @@ pads:
err = media_entity_pads_init(&sd->entity, npads, pads);
The pads array must have been previously initialized. There is no need to
-manually set the struct :c:type:`media_entity` function and name fields, but the
+manually set the struct media_entity function and name fields, but the
revision field must be initialized if needed.
A reference to the entity will be automatically acquired/released when the
diff --git a/Documentation/driver-api/regulator.rst b/Documentation/driver-api/regulator.rst
index 520da0a5251d..b43c78eb24d8 100644
--- a/Documentation/driver-api/regulator.rst
+++ b/Documentation/driver-api/regulator.rst
@@ -116,7 +116,7 @@ core, providing operations structures to the core. A notifier interface
allows error conditions to be reported to the core.
Registration should be triggered by explicit setup done by the platform,
-supplying a struct :c:type:`regulator_init_data` for the regulator
+supplying a struct regulator_init_data for the regulator
containing constraint and supply information.
Machine interface
@@ -144,7 +144,7 @@ a given system, for example supporting higher supply voltages than the
consumers are rated for.
This is done at driver registration time` by providing a
-struct :c:type:`regulation_constraints`.
+struct regulation_constraints.
The constraints may also specify an initial configuration for the
regulator in the constraints, which is particularly useful for use with
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst
index 1e4abc896a0d..a182c0f5e38a 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -47,7 +47,7 @@ called USB Request Block, or URB for short.
The URB structure
=================
-Some of the fields in struct :c:type:`urb` are::
+Some of the fields in struct urb are::
struct urb
{
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index 3e8a3809c0b8..09396edd6131 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -176,9 +176,9 @@ Kernel Mode Gadget API
Gadget drivers declare themselves through a struct
:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
-for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
-involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
-the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
+for a struct usb_gadget. The response to a set_configuration usually
+involves enabling one or more of the struct usb_ep objects exposed by
+the gadget, and submitting one or more struct usb_request buffers to
transfer data. Understand those four data types, and their operations,
and you will understand how this API works.
@@ -339,8 +339,8 @@ multi-configuration devices (also more than one function, but not
necessarily sharing a given configuration). There is however an optional
framework which makes it easier to reuse and combine functions.
-Devices using this framework provide a struct :c:type:`usb_composite_driver`,
-which in turn provides one or more struct :c:type:`usb_configuration`
+Devices using this framework provide a struct usb_composite_driver,
+which in turn provides one or more struct usb_configuration
instances. Each such configuration includes at least one struct
:c:type:`usb_function`, which packages a user visible role such as "network
link" or "mass storage device". Management functions may also exist,
diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst
index 79663e653ca1..c1e13107c50e 100644
--- a/Documentation/driver-api/usb/hotplug.rst
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -122,7 +122,7 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this::
Most USB device drivers should pass these tables to the USB subsystem as
well as to the module management subsystem. Not all, though: some driver
frameworks connect using interfaces layered over USB, and so they won't
-need such a struct :c:type:`usb_driver`.
+need such a struct usb_driver.
Drivers that connect directly to the USB subsystem should be declared
something like this::
diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 423c5a0daf45..4f858b38a412 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -437,7 +437,7 @@ FS_IOC_SET_ENCRYPTION_POLICY
The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
empty directory or verifies that a directory or regular file already
has the specified encryption policy. It takes in a pointer to a
-:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
+struct fscrypt_policy_v1 or a :c:type:`struct
fscrypt_policy_v2`, defined as follows::
#define FSCRYPT_POLICY_V1 0
@@ -508,7 +508,7 @@ This structure must be initialized as follows:
replaced with ``master_key_identifier``, which is longer and cannot
be arbitrarily chosen. Instead, the key must first be added using
`FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
- the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
+ the kernel returned in the struct fscrypt_add_key_arg must
be used as the ``master_key_identifier`` in the :c:type:`struct
fscrypt_policy_v2`.
@@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX
The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
policy, if any, for a directory or regular file. No additional
permissions are required beyond the ability to open the file. It
-takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
+takes in a pointer to a struct fscrypt_get_policy_ex_arg,
defined as follows::
struct fscrypt_get_policy_ex_arg {
@@ -680,7 +680,7 @@ the filesystem, making all files on the filesystem which were
encrypted using that key appear "unlocked", i.e. in plaintext form.
It can be executed on any file or directory on the target filesystem,
but using the filesystem's root directory is recommended. It takes in
-a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
+a pointer to a struct fscrypt_add_key_arg, defined as
follows::
struct fscrypt_add_key_arg {
@@ -710,7 +710,7 @@ follows::
__u8 raw[];
};
-:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
+struct fscrypt_add_key_arg must be zeroed, then initialized
as follows:
- If the key is being added for use by v1 encryption policies, then
@@ -860,7 +860,7 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
encryption key from the filesystem, and possibly removes the key
itself. It can be executed on any file or directory on the target
filesystem, but using the filesystem's root directory is recommended.
-It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
+It takes in a pointer to a struct fscrypt_remove_key_arg,
defined as follows::
struct fscrypt_remove_key_arg {
@@ -1149,7 +1149,7 @@ Encryption context
------------------
An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is
+fscrypt_context_v1` or a struct fscrypt_context_v2. It is
up to individual filesystems to decide where to store it, but normally
it would be stored in a hidden extended attribute. It should *not* be
exposed by the xattr-related system calls such as getxattr() and
diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst
index 6c8944f6f0f7..895e9711ed88 100644
--- a/Documentation/filesystems/fsverity.rst
+++ b/Documentation/filesystems/fsverity.rst
@@ -84,7 +84,7 @@ FS_IOC_ENABLE_VERITY
--------------------
The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes
-in a pointer to a :c:type:`struct fsverity_enable_arg`, defined as
+in a pointer to a struct fsverity_enable_arg, defined as
follows::
struct fsverity_enable_arg {
diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst
index 78bc5572f829..b0a7e3010187 100644
--- a/Documentation/sound/designs/tracepoints.rst
+++ b/Documentation/sound/designs/tracepoints.rst
@@ -34,20 +34,20 @@ substream. In this procedure, PCM hardware parameters are decided by
interaction between applications and ALSA PCM core. Once decided, runtime of
the PCM substream keeps the parameters.
-The parameters are described in :c:type:`struct snd_pcm_hw_params`. This
+The parameters are described in struct snd_pcm_hw_params. This
structure includes several types of parameters. Applications set preferable
value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE
or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available
set of parameters. The latter is used for an actual decision of the parameters.
-The :c:type:`struct snd_pcm_hw_params` structure has below members:
+The struct snd_pcm_hw_params structure has below members:
``flags``
Configurable. ALSA PCM core and some drivers handle this flag to select
convenient parameters or change their behaviour.
``masks``
Configurable. This type of parameter is described in
- :c:type:`struct snd_mask` and represent mask values. As of PCM protocol
+ struct snd_mask and represent mask values. As of PCM protocol
v2.0.13, three types are defined.
- SNDRV_PCM_HW_PARAM_ACCESS
@@ -55,7 +55,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
- SNDRV_PCM_HW_PARAM_SUBFORMAT
``intervals``
Configurable. This type of parameter is described in
- :c:type:`struct snd_interval` and represent values with a range. As of
+ struct snd_interval and represent values with a range. As of
PCM protocol v2.0.13, twelve types are defined.
- SNDRV_PCM_HW_PARAM_SAMPLE_BITS
@@ -78,7 +78,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
are going to be changed.
``cmask``
Read-only. After returning from ioctl(2), buffer in user space for
- :c:type:`struct snd_pcm_hw_params` includes result of each operation.
+ struct snd_pcm_hw_params includes result of each operation.
This mask represents which mask/interval parameter is actually changed.
``info``
Read-only. This represents hardware/driver capabilities as bit flags
@@ -110,10 +110,10 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
value to this parameter but some drivers intentionally set zero with
a care of hardware design or data transmission protocol.
-ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when
+ALSA PCM core handles buffer of struct snd_pcm_hw_params when
applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
Parameters in the buffer are changed according to
-:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The
+struct snd_pcm_hardware and rules of constraints in the runtime. The
structure describes capabilities of handled hardware. The rules describes
dependencies on which a parameter is decided according to several parameters.
A rule has a callback function, and drivers can register arbitrary functions
@@ -121,17 +121,17 @@ to compute the target parameter. ALSA PCM core registers some rules to the
runtime as a default.
Each driver can join in the interaction as long as it prepared for two stuffs
-in a callback of :c:type:`struct snd_pcm_ops.open`.
+in a callback of struct snd_pcm_ops.open.
1. In the callback, drivers are expected to change a member of
- :c:type:`struct snd_pcm_hardware` type in the runtime, according to
+ struct snd_pcm_hardware type in the runtime, according to
capacities of corresponding hardware.
2. In the same callback, drivers are also expected to register additional rules
of constraints into the runtime when several parameters have dependencies
due to hardware design.
The driver can refers to result of the interaction in a callback of
-:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the
+struct snd_pcm_ops.hw_params, however it should not change the
content.
Tracepoints in this category are designed to trace changes of the
@@ -163,7 +163,7 @@ fields are different according to type of the parameter. For parameters of mask
type, the fields represent hexadecimal dump of content of the parameter. For
parameters of interval type, the fields represent values of each member of
``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in
-:c:type:`struct snd_interval` in this order.
+struct snd_interval in this order.
Tracepoints in drivers
======================
--git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index 00a69aceff44..1910079f984f 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -110,7 +110,7 @@ while (<IN>) {
) {
my $s = $1;
- $structs{$s} = "struct :c:type:`$s`\\ ";
+ $structs{$s} = "struct $s\\ ";
next;
}
}
diff --git a/Documentation/vm/ksm.rst b/Documentation/vm/ksm.rst
index d1b7270ad55c..9e37add068e6 100644
--- a/Documentation/vm/ksm.rst
+++ b/Documentation/vm/ksm.rst
@@ -26,7 +26,7 @@ tree.
If a KSM page is shared between less than ``max_page_sharing`` VMAs,
the node of the stable tree that represents such KSM page points to a
-list of :c:type:`struct rmap_item` and the ``page->mapping`` of the
+list of struct rmap_item and the ``page->mapping`` of the
KSM page points to the stable tree node.
When the sharing passes this threshold, KSM adds a second dimension to
diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst
index 769449734573..9daadf9faba1 100644
--- a/Documentation/vm/memory-model.rst
+++ b/Documentation/vm/memory-model.rst
@@ -24,7 +24,7 @@ whether it is possible to manually override that default.
although it is still in use by several architectures.
All the memory models track the status of physical page frames using
-:c:type:`struct page` arranged in one or more arrays.
+struct page arranged in one or more arrays.
Regardless of the selected memory model, there exists one-to-one
mapping between the physical page frame number (PFN) and the
@@ -111,7 +111,7 @@ maps for non-volatile memory devices and deferred initialization of
the memory map for larger systems.
The SPARSEMEM model presents the physical memory as a collection of
-sections. A section is represented with :c:type:`struct mem_section`
+sections. A section is represented with struct mem_section
that contains `section_mem_map` that is, logically, a pointer to an
array of struct pages. However, it is stored with some other magic
that aids the sections management. The section size and maximal number
@@ -172,7 +172,7 @@ management.
The virtually mapped memory map allows storing `struct page` objects
for persistent memory devices in pre-allocated storage on those
-devices. This storage is represented with :c:type:`struct vmem_altmap`
+devices. This storage is represented with struct vmem_altmap
that is eventually passed to vmemmap_populate() through a long chain
of function calls. The vmemmap_populate() implementation may use the
`vmem_altmap` along with :c:func:`vmemmap_alloc_block_buf` helper to
diff --git a/mm/ksm.c b/mm/ksm.c
index 9afccc36dbd2..0960750bb316 100644
--- a/mm/ksm.c
+++ b/mm/ksm.c
@@ -81,7 +81,7 @@
* different KSM page copy of that content
*
* Internally, the regular nodes, "dups" and "chains" are represented
- * using the same :c:type:`struct stable_node` structure.
+ * using the same struct stable_node structure.
*
* In addition to the stable tree, KSM uses a second data structure called the
* unstable tree: this tree holds pointers to pages which have been found to
diff --git a/mm/memblock.c b/mm/memblock.c
index 326c6b3fec1d..b68ee86788af 100644
--- a/mm/memblock.c
+++ b/mm/memblock.c
@@ -48,12 +48,12 @@
* boot regardless of the possible restrictions and memory hot(un)plug;
* the ``physmem`` type is only available on some architectures.
*
- * Each region is represented by :c:type:`struct memblock_region` that
+ * Each region is represented by struct memblock_region that
* defines the region extents, its attributes and NUMA node id on NUMA
* systems. Every memory type is described by the struct memblock_type
* which contains an array of memory regions along with
* the allocator metadata. The "memory" and "reserved" types are nicely
- * wrapped with :c:type:`struct memblock`. This structure is statically
+ * wrapped with struct memblock. This structure is statically
* initialized at build time. The region arrays are initially sized to
* %INIT_MEMBLOCK_REGIONS for "memory" and %INIT_MEMBLOCK_RESERVED_REGIONS
* for "reserved". The region array for "physmem" is initially sized to
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 14:26 ` Mike Rapoport
-1 siblings, 0 replies; 103+ messages in thread
From: Mike Rapoport @ 2020-09-30 14:26 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Alexander A. Klimov,
André Almeida, Theodore Y. Ts'o, Alexandru Ardelean,
Andrew Morton, Anshuman Khandual, Eric Biggers,
Greg Kroah-Hartman, Jaegeuk Kim, Jaroslav Kysela, Jens Axboe,
Jonathan Cameron, Mauro Carvalho Chehab, Moritz Fischer,
Puranjay Mohan, Randy Dunlap, Satya Tangirala, Takashi Iwai,
Tom Rix, alsa-devel, linux-fpga, linux-fscrypt, linux-kernel,
linux-media, linux-mm
On Wed, Sep 30, 2020 at 03:24:45PM +0200, Mauro Carvalho Chehab wrote:
> The :c:type:`foo` only works properly with structs before
> Sphinx 3.x.
>
> On Sphinx 3.x, structs should now be declared using the
> .. c:struct, and referenced via :c:struct tag.
>
> As we now have the automarkup.py macro, that automatically
> convert:
> struct foo
>
> into cross-references, let's get rid of that, solving
> several warnings when building docs with Sphinx 3.x.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
...
> Documentation/vm/ksm.rst | 2 +-
> Documentation/vm/memory-model.rst | 6 ++---
> mm/ksm.c | 2 +-
> mm/memblock.c | 4 ++--
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
> 30 files changed, 93 insertions(+), 93 deletions(-)
>
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
@ 2020-09-30 14:26 ` Mike Rapoport
0 siblings, 0 replies; 103+ messages in thread
From: Mike Rapoport @ 2020-09-30 14:26 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: alsa-devel, Linux Doc Mailing List, Tom Rix, linux-fpga,
André Almeida, linux-mm, Jonathan Corbet, Satya Tangirala,
Eric Biggers, Alexandru Ardelean, linux-media, Anshuman Khandual,
linux-fscrypt, Moritz Fischer, Jonathan Cameron, Jaegeuk Kim,
Mauro Carvalho Chehab, Jens Axboe, Theodore Y. Ts'o,
Puranjay Mohan, Greg Kroah-Hartman, Randy Dunlap, Takashi Iwai,
linux-kernel, Alexander A. Klimov, Andrew Morton
On Wed, Sep 30, 2020 at 03:24:45PM +0200, Mauro Carvalho Chehab wrote:
> The :c:type:`foo` only works properly with structs before
> Sphinx 3.x.
>
> On Sphinx 3.x, structs should now be declared using the
> .. c:struct, and referenced via :c:struct tag.
>
> As we now have the automarkup.py macro, that automatically
> convert:
> struct foo
>
> into cross-references, let's get rid of that, solving
> several warnings when building docs with Sphinx 3.x.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
...
> Documentation/vm/ksm.rst | 2 +-
> Documentation/vm/memory-model.rst | 6 ++---
> mm/ksm.c | 2 +-
> mm/memblock.c | 4 ++--
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
> 30 files changed, 93 insertions(+), 93 deletions(-)
>
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 15:01 ` Takashi Iwai
-1 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 15:01 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Alexander A. Klimov,
André Almeida, Theodore Y. Ts'o, Alexandru Ardelean,
Andrew Morton, Anshuman Khandual, Eric Biggers,
Greg Kroah-Hartman, Jaegeuk Kim, Jaroslav Kysela, Jens Axboe,
Jonathan Cameron, Mauro Carvalho Chehab, Mike Rapoport,
Moritz Fischer, Puranjay Mohan, Randy Dunlap, Satya Tangirala,
Takashi Iwai, Tom Rix, alsa-devel, linux-fpga, linux-fscrypt,
linux-kernel, linux-media, linux-mm
On Wed, 30 Sep 2020 15:24:45 +0200,
Mauro Carvalho Chehab wrote:
>
> The :c:type:`foo` only works properly with structs before
> Sphinx 3.x.
>
> On Sphinx 3.x, structs should now be declared using the
> .. c:struct, and referenced via :c:struct tag.
>
> As we now have the automarkup.py macro, that automatically
> convert:
> struct foo
>
> into cross-references, let's get rid of that, solving
> several warnings when building docs with Sphinx 3.x.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
For the sound part:
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
@ 2020-09-30 15:01 ` Takashi Iwai
0 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 15:01 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: alsa-devel, Linux Doc Mailing List, Tom Rix, linux-fpga,
André Almeida, linux-mm, Jonathan Corbet, Satya Tangirala,
Eric Biggers, Alexandru Ardelean, linux-media, Anshuman Khandual,
linux-fscrypt, Moritz Fischer, Jonathan Cameron, Jaegeuk Kim,
Mauro Carvalho Chehab, Jens Axboe, Theodore Y. Ts'o,
Puranjay Mohan, Greg Kroah-Hartman, Randy Dunlap, Takashi Iwai,
linux-kernel, Alexander A. Klimov, Andrew Morton, Mike Rapoport
On Wed, 30 Sep 2020 15:24:45 +0200,
Mauro Carvalho Chehab wrote:
>
> The :c:type:`foo` only works properly with structs before
> Sphinx 3.x.
>
> On Sphinx 3.x, structs should now be declared using the
> .. c:struct, and referenced via :c:struct tag.
>
> As we now have the automarkup.py macro, that automatically
> convert:
> struct foo
>
> into cross-references, let's get rid of that, solving
> several warnings when building docs with Sphinx 3.x.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
For the sound part:
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 16:50 ` André Almeida
-1 siblings, 0 replies; 103+ messages in thread
From: André Almeida @ 2020-09-30 16:50 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
Cc: Alexander A. Klimov, Theodore Y. Ts'o, Alexandru Ardelean,
Andrew Morton, Anshuman Khandual, Eric Biggers,
Greg Kroah-Hartman, Jaegeuk Kim, Jaroslav Kysela, Jens Axboe,
Jonathan Cameron, Mauro Carvalho Chehab, Mike Rapoport,
Moritz Fischer, Puranjay Mohan, Randy Dunlap, Satya Tangirala,
Takashi Iwai, Tom Rix, alsa-devel, linux-fpga, linux-fscrypt,
linux-kernel, linux-media, linux-mm
On 9/30/20 10:24 AM, Mauro Carvalho Chehab wrote:
> The :c:type:`foo` only works properly with structs before
> Sphinx 3.x.
>
> On Sphinx 3.x, structs should now be declared using the
> .. c:struct, and referenced via :c:struct tag.
>
> As we now have the automarkup.py macro, that automatically
> convert:
> struct foo
>
> into cross-references, let's get rid of that, solving
> several warnings when building docs with Sphinx 3.x.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> Documentation/block/blk-mq.rst | 8 +++----
Regarding blk-mq.rst:
Reviewed-by: André Almeida <andrealmeid@collabora.com>
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
@ 2020-09-30 16:50 ` André Almeida
0 siblings, 0 replies; 103+ messages in thread
From: André Almeida @ 2020-09-30 16:50 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
Cc: alsa-devel, Tom Rix, linux-fpga, linux-mm, Satya Tangirala,
Eric Biggers, Alexandru Ardelean, linux-media, Anshuman Khandual,
linux-fscrypt, Moritz Fischer, Jonathan Cameron, Jaegeuk Kim,
Mauro Carvalho Chehab, Jens Axboe, Theodore Y. Ts'o,
Puranjay Mohan, Greg Kroah-Hartman, Randy Dunlap, Takashi Iwai,
linux-kernel, Alexander A. Klimov, Andrew Morton, Mike Rapoport
On 9/30/20 10:24 AM, Mauro Carvalho Chehab wrote:
> The :c:type:`foo` only works properly with structs before
> Sphinx 3.x.
>
> On Sphinx 3.x, structs should now be declared using the
> .. c:struct, and referenced via :c:struct tag.
>
> As we now have the automarkup.py macro, that automatically
> convert:
> struct foo
>
> into cross-references, let's get rid of that, solving
> several warnings when building docs with Sphinx 3.x.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> Documentation/block/blk-mq.rst | 8 +++----
Regarding blk-mq.rst:
Reviewed-by: André Almeida <andrealmeid@collabora.com>
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (21 preceding siblings ...)
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 16:35 ` Steven Rostedt
2020-10-01 6:06 ` Kamalesh Babulal
2020-09-30 13:24 ` [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst Mauro Carvalho Chehab
` (29 subsequent siblings)
52 siblings, 2 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Steven Rostedt (VMware),
Kamalesh Babulal, Miroslav Benes, Petr Mladek,
Sebastian Andrzej Siewior, linux-kernel
There are some c-domain tags that are wrong. While this won't
cause problems with Sphinx < 3.0, this cause troubles with
newer versions, as the C parser won't recognize the contents
of the tag, and will drop it from the output.
Let's just place them at literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/trace/ftrace-uses.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst
index 2a05e770618a..a4955f7e3d19 100644
--- a/Documentation/trace/ftrace-uses.rst
+++ b/Documentation/trace/ftrace-uses.rst
@@ -55,17 +55,17 @@ an ftrace_ops with ftrace:
Both .flags and .private are optional. Only .func is required.
-To enable tracing call:
+To enable tracing call::
-.. c:function:: register_ftrace_function(&ops);
+ register_ftrace_function(&ops);
-To disable tracing call:
+To disable tracing call::
-.. c:function:: unregister_ftrace_function(&ops);
+ unregister_ftrace_function(&ops);
-The above is defined by including the header:
+The above is defined by including the header::
-.. c:function:: #include <linux/ftrace.h>
+ #include <linux/ftrace.h>
The registered callback will start being called some time after the
register_ftrace_function() is called and before it returns. The exact time
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
2020-09-30 13:24 ` [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags Mauro Carvalho Chehab
@ 2020-09-30 16:35 ` Steven Rostedt
2020-10-01 6:06 ` Kamalesh Babulal
1 sibling, 0 replies; 103+ messages in thread
From: Steven Rostedt @ 2020-09-30 16:35 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Kamalesh Babulal,
Miroslav Benes, Petr Mladek, Sebastian Andrzej Siewior,
linux-kernel
On Wed, 30 Sep 2020 15:24:46 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> There are some c-domain tags that are wrong. While this won't
> cause problems with Sphinx < 3.0, this cause troubles with
> newer versions, as the C parser won't recognize the contents
> of the tag, and will drop it from the output.
>
> Let's just place them at literal blocks.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
-- Steve
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
2020-09-30 13:24 ` [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags Mauro Carvalho Chehab
2020-09-30 16:35 ` Steven Rostedt
@ 2020-10-01 6:06 ` Kamalesh Babulal
2020-10-01 6:41 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 103+ messages in thread
From: Kamalesh Babulal @ 2020-10-01 6:06 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
Cc: Steven Rostedt (VMware),
Miroslav Benes, Petr Mladek, Sebastian Andrzej Siewior,
linux-kernel
On 30/09/20 6:54 pm, Mauro Carvalho Chehab wrote:
> There are some c-domain tags that are wrong. While this won't
> cause problems with Sphinx < 3.0, this cause troubles with
> newer versions, as the C parser won't recognize the contents
> of the tag, and will drop it from the output.
>
> Let's just place them at literal blocks.
>
tired with Sphinx v3.2.1, invalid C declaration warnings are not
seen with the patch.
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
--
Kamalesh
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
2020-10-01 6:06 ` Kamalesh Babulal
@ 2020-10-01 6:41 ` Mauro Carvalho Chehab
2020-10-01 8:27 ` Kamalesh Babulal
0 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-01 6:41 UTC (permalink / raw)
To: Kamalesh Babulal
Cc: Linux Doc Mailing List, Jonathan Corbet, Steven Rostedt (VMware),
Miroslav Benes, Petr Mladek, Sebastian Andrzej Siewior,
linux-kernel
Em Thu, 1 Oct 2020 11:36:53 +0530
Kamalesh Babulal <kamalesh@linux.vnet.ibm.com> escreveu:
> On 30/09/20 6:54 pm, Mauro Carvalho Chehab wrote:
> > There are some c-domain tags that are wrong. While this won't
> > cause problems with Sphinx < 3.0, this cause troubles with
> > newer versions, as the C parser won't recognize the contents
> > of the tag, and will drop it from the output.
> >
> > Let's just place them at literal blocks.
> >
>
> tired with Sphinx v3.2.1, invalid C declaration warnings are not
> seen with the patch.
Well, it would be possible to use :c:expr: with Sphinx 3.2.1,
in order for it to check for invalid C declarations.
Btw, this is one of the improvements over the last versions: the
rewritten C parser there is a lot more pedantic with regards to the
C syntax.
-
That's said, the backward-compatibility code I added at
Documentation/sphinx/cdomain.py will convert this into a
literal markup though, as there's no equivalent tag before
Sphinx 3.x.
As there are still one upstream issue on Sphinx 3.x that requires a fix[1],
and we don't know yet the issues with :c:expr[2], at least for now, I would
avoid adding :c:expr: markups.
[1] Right now, the C domain is not able to have two names
for different types. So, it is not possible to have
a struct "foo" and a function "foo".
Due to that, while I was able to fix all warnings with
Sphinx 2.x build, Sphinx 3.x will still have bogus
warnings.
[2] One of the limitations of :c:expr: is with regards to function
prototypes. You can't use it like: :c:expr:`int foo(void);`,
as it will complain with the function return type.
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Reviewed-by: Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
Thanks!
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
2020-10-01 6:41 ` Mauro Carvalho Chehab
@ 2020-10-01 8:27 ` Kamalesh Babulal
0 siblings, 0 replies; 103+ messages in thread
From: Kamalesh Babulal @ 2020-10-01 8:27 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Steven Rostedt (VMware),
Miroslav Benes, Petr Mladek, Sebastian Andrzej Siewior,
linux-kernel
On 01/10/20 12:11 pm, Mauro Carvalho Chehab wrote:
> Em Thu, 1 Oct 2020 11:36:53 +0530
> Kamalesh Babulal <kamalesh@linux.vnet.ibm.com> escreveu:
>
>> On 30/09/20 6:54 pm, Mauro Carvalho Chehab wrote:
>>> There are some c-domain tags that are wrong. While this won't
>>> cause problems with Sphinx < 3.0, this cause troubles with
>>> newer versions, as the C parser won't recognize the contents
>>> of the tag, and will drop it from the output.
>>>
>>> Let's just place them at literal blocks.
>>>
>>
>> tired with Sphinx v3.2.1, invalid C declaration warnings are not
>> seen with the patch.
>
> Well, it would be possible to use :c:expr: with Sphinx 3.2.1,
> in order for it to check for invalid C declarations.
>
> Btw, this is one of the improvements over the last versions: the
> rewritten C parser there is a lot more pedantic with regards to the
> C syntax.
>
> -
>
> That's said, the backward-compatibility code I added at
> Documentation/sphinx/cdomain.py will convert this into a
> literal markup though, as there's no equivalent tag before
> Sphinx 3.x.
>
> As there are still one upstream issue on Sphinx 3.x that requires a fix[1],
> and we don't know yet the issues with :c:expr[2], at least for now, I would
> avoid adding :c:expr: markups.
>
> [1] Right now, the C domain is not able to have two names
> for different types. So, it is not possible to have
> a struct "foo" and a function "foo".
>
> Due to that, while I was able to fix all warnings with
> Sphinx 2.x build, Sphinx 3.x will still have bogus
> warnings.
>
> [2] One of the limitations of :c:expr: is with regards to function
> prototypes. You can't use it like: :c:expr:`int foo(void);`,
> as it will complain with the function return type.
>
Thank you for explaining in detail on the :c:expr: tag. I intended to
say this patch fixes the warnings seen while using the c-domain tags
and are fixed by converting them into literals.
--
Kamalesh
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (22 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-10-01 12:04 ` Federico Vaga
2020-09-30 13:24 ` [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions Mauro Carvalho Chehab
` (28 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Federico Vaga, linux-kernel
The C domain functions there collide with the English ones,
due to namespace collision, generating lots of warnings with
Sphinx 3.x:
./include/linux/mutex.h:121: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
Declaration is 'mutex_init'.
./include/linux/mutex.h:152: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
Declaration is 'mutex_is_locked'.
./include/linux/mutex.h:226: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
Declaration is 'mutex_trylock_recursive'.
./kernel/locking/mutex.c:281: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
Declaration is 'mutex_lock'.
...
Add a namespace tag there, in order to prevent that.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/translations/it_IT/kernel-hacking/locking.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 4615df5723fb..bf1acd6204ef 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -1,5 +1,7 @@
.. include:: ../disclaimer-ita.rst
+.. c:namespace:: it_IT
+
:Original: :ref:`Documentation/kernel-hacking/locking.rst <kernel_hacking_lock>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst
2020-09-30 13:24 ` [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst Mauro Carvalho Chehab
@ 2020-10-01 12:04 ` Federico Vaga
0 siblings, 0 replies; 103+ messages in thread
From: Federico Vaga @ 2020-10-01 12:04 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, linux-kernel
On 2020-09-30 15:24, Mauro Carvalho Chehab wrote:
> The C domain functions there collide with the English ones,
> due to namespace collision, generating lots of warnings with
> Sphinx 3.x:
>
> ./include/linux/mutex.h:121: WARNING: Duplicate C declaration, also
> defined in 'translations/it_IT/kernel-hacking/locking'.
> Declaration is 'mutex_init'.
> ./include/linux/mutex.h:152: WARNING: Duplicate C declaration, also
> defined in 'translations/it_IT/kernel-hacking/locking'.
> Declaration is 'mutex_is_locked'.
> ./include/linux/mutex.h:226: WARNING: Duplicate C declaration, also
> defined in 'translations/it_IT/kernel-hacking/locking'.
> Declaration is 'mutex_trylock_recursive'.
> ./kernel/locking/mutex.c:281: WARNING: Duplicate C declaration, also
> defined in 'translations/it_IT/kernel-hacking/locking'.
> Declaration is 'mutex_lock'.
> ...
>
> Add a namespace tag there, in order to prevent that.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
> ---
> Documentation/translations/it_IT/kernel-hacking/locking.rst | 2 ++
> 1 file changed, 2 insertions(+)
>
> diff --git
> a/Documentation/translations/it_IT/kernel-hacking/locking.rst
> b/Documentation/translations/it_IT/kernel-hacking/locking.rst
> index 4615df5723fb..bf1acd6204ef 100644
> --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
> +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
> @@ -1,5 +1,7 @@
> .. include:: ../disclaimer-ita.rst
>
> +.. c:namespace:: it_IT
> +
> :Original: :ref:`Documentation/kernel-hacking/locking.rst
> <kernel_hacking_lock>`
> :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
--
Federico Vaga
http://www.federicovaga.it/
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (23 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 21:23 ` David Miller
2020-09-30 13:24 ` [PATCH v4 26/52] docs: genericirq.rst: don't document chip.c functions twice Mauro Carvalho Chehab
` (27 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, David S. Miller, Alexander Aring,
Jakub Kicinski, Stefan Schmidt, linux-kernel, linux-wpan, netdev
There are some warnings produced with Sphinx 3.x:
Documentation/networking/ieee802154.rst:29: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 7]
int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
-------^
Documentation/networking/ieee802154.rst:134: WARNING: Invalid C declaration: Expected end of definition. [error at 81]
void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi):
---------------------------------------------------------------------------------^
Documentation/networking/ieee802154.rst:139: WARNING: Invalid C declaration: Expected end of definition. [error at 95]
void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling):
-----------------------------------------------------------------------------------------------^
Documentation/networking/ieee802154.rst:158: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
int start(struct ieee802154_hw *hw):
-----------------------------------^
Documentation/networking/ieee802154.rst:162: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
void stop(struct ieee802154_hw *hw):
-----------------------------------^
Documentation/networking/ieee802154.rst:166: WARNING: Invalid C declaration: Expected end of definition. [error at 61]
int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb):
-------------------------------------------------------------^
Documentation/networking/ieee802154.rst:171: WARNING: Invalid C declaration: Expected end of definition. [error at 43]
int ed(struct ieee802154_hw *hw, u8 *level):
-------------------------------------------^
Documentation/networking/ieee802154.rst:176: WARNING: Invalid C declaration: Expected end of definition. [error at 62]
int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel):
--------------------------------------------------------------^
Caused by some bad c:function: prototypes. Fix them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/networking/ieee802154.rst | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/Documentation/networking/ieee802154.rst b/Documentation/networking/ieee802154.rst
index 6f4bf8447a21..f27856d77c8b 100644
--- a/Documentation/networking/ieee802154.rst
+++ b/Documentation/networking/ieee802154.rst
@@ -26,7 +26,9 @@ The stack is composed of three main parts:
Socket API
==========
-.. c:function:: int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
+::
+
+ int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
The address family, socket addresses etc. are defined in the
include/net/af_ieee802154.h header or in the special header
@@ -131,12 +133,12 @@ Register PHY in the system.
Freeing registered PHY.
-.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi):
+.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi)
Telling 802.15.4 module there is a new received frame in the skb with
the RF Link Quality Indicator (LQI) from the hardware device.
-.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling):
+.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling)
Telling 802.15.4 module the frame in the skb is or going to be
transmitted through the hardware device
@@ -155,25 +157,25 @@ operations structure at least::
...
};
-.. c:function:: int start(struct ieee802154_hw *hw):
+.. c:function:: int start(struct ieee802154_hw *hw)
Handler that 802.15.4 module calls for the hardware device initialization.
-.. c:function:: void stop(struct ieee802154_hw *hw):
+.. c:function:: void stop(struct ieee802154_hw *hw)
Handler that 802.15.4 module calls for the hardware device cleanup.
-.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb):
+.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb)
Handler that 802.15.4 module calls for each frame in the skb going to be
transmitted through the hardware device.
-.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level):
+.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level)
Handler that 802.15.4 module calls for Energy Detection from the hardware
device.
-.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel):
+.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel)
Set radio for listening on specific channel of the hardware device.
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions
2020-09-30 13:24 ` [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions Mauro Carvalho Chehab
@ 2020-09-30 21:23 ` David Miller
0 siblings, 0 replies; 103+ messages in thread
From: David Miller @ 2020-09-30 21:23 UTC (permalink / raw)
To: mchehab+huawei
Cc: linux-doc, corbet, alex.aring, kuba, stefan, linux-kernel,
linux-wpan, netdev
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Wed, 30 Sep 2020 15:24:48 +0200
> There are some warnings produced with Sphinx 3.x:
>
> Documentation/networking/ieee802154.rst:29: WARNING: Error in declarator or parameters
> Invalid C declaration: Expecting "(" in parameters. [error at 7]
> int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
> -------^
> Documentation/networking/ieee802154.rst:134: WARNING: Invalid C declaration: Expected end of definition. [error at 81]
> void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi):
> ---------------------------------------------------------------------------------^
> Documentation/networking/ieee802154.rst:139: WARNING: Invalid C declaration: Expected end of definition. [error at 95]
> void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling):
> -----------------------------------------------------------------------------------------------^
> Documentation/networking/ieee802154.rst:158: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
> int start(struct ieee802154_hw *hw):
> -----------------------------------^
> Documentation/networking/ieee802154.rst:162: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
> void stop(struct ieee802154_hw *hw):
> -----------------------------------^
> Documentation/networking/ieee802154.rst:166: WARNING: Invalid C declaration: Expected end of definition. [error at 61]
> int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb):
> -------------------------------------------------------------^
> Documentation/networking/ieee802154.rst:171: WARNING: Invalid C declaration: Expected end of definition. [error at 43]
> int ed(struct ieee802154_hw *hw, u8 *level):
> -------------------------------------------^
> Documentation/networking/ieee802154.rst:176: WARNING: Invalid C declaration: Expected end of definition. [error at 62]
> int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel):
> --------------------------------------------------------------^
>
> Caused by some bad c:function: prototypes. Fix them.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: David S. Miller <davem@davemloft.net>
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 26/52] docs: genericirq.rst: don't document chip.c functions twice
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (24 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 27/52] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag Mauro Carvalho Chehab
` (26 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Thomas Gleixner, linux-kernel
Currently, kernel/irq/chip.c is included twice, one for
export functions, and then for internal ones. However, as
the :export: and :internal: tags are missing, they ended
being included twice.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/core-api/genericirq.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
index 8f06d885c310..f959c9b53f61 100644
--- a/Documentation/core-api/genericirq.rst
+++ b/Documentation/core-api/genericirq.rst
@@ -419,6 +419,7 @@ functions which are exported.
.. kernel-doc:: kernel/irq/manage.c
.. kernel-doc:: kernel/irq/chip.c
+ :export:
Internal Functions Provided
===========================
@@ -431,6 +432,7 @@ functions.
.. kernel-doc:: kernel/irq/handle.c
.. kernel-doc:: kernel/irq/chip.c
+ :internal:
Credits
=======
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 27/52] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (25 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 26/52] docs: genericirq.rst: don't document chip.c functions twice Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` Mauro Carvalho Chehab
` (25 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Christophe Leroy, Daniel Axtens,
Marco Elver, Michael Ellerman, linux-kernel
This is already included at genericirq.rst. Adding it twice
causes C namespace duplication:
.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:100: WARNING: Duplicate C declaration, also defined in 'genericirq'.
Declaration is 'synchronize_hardirq'.
.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:128: WARNING: Duplicate C declaration, also defined in 'genericirq'.
Declaration is 'synchronize_irq'.
.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:443: WARNING: Duplicate C declaration, also defined in 'genericirq'.
Declaration is 'irq_set_affinity_notifier'.
...
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/core-api/kernel-api.rst | 6 ------
1 file changed, 6 deletions(-)
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 4ac53a1363f6..741aa37dc181 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -231,12 +231,6 @@ Refer to the file kernel/module.c for more information.
Hardware Interfaces
===================
-Interrupt Handling
-------------------
-
-.. kernel-doc:: kernel/irq/manage.c
- :export:
-
DMA Channels
------------
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 28/52] docs: remove sound API duplication
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Jonathan Neuschäfer, rd.dunlab,
Harald Seiler, Heikki Krogerus, Jaroslav Kysela, Jason Gunthorpe,
Kuninori Morimoto, Leonard Crestez, Mark Brown, Michael Walle,
Pragat Pandya, Randy Dunlap, Takashi Iwai, alsa-devel,
linux-kernel
The sound API is documented on two different parts:
under Documentation/driver-api/sound.rst and under
Documentation/sound/kernel-api/alsa-driver-api.rst.
The alsa-driver-api.rst seems more complete, and APIs
are split per type. There's just one missing kernel-doc
markup there.
Add it and drop the duplicated one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/index.rst | 1 -
Documentation/driver-api/sound.rst | 54 -------------------
.../sound/kernel-api/alsa-driver-api.rst | 1 +
3 files changed, 1 insertion(+), 55 deletions(-)
delete mode 100644 Documentation/driver-api/sound.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 6e7c702e0268..987d6e74ea6a 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -27,7 +27,6 @@ available subsections can be seen below.
component
message-based
infiniband
- sound
frame-buffer
regulator
iio/index
diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst
deleted file mode 100644
index afef6eabc073..000000000000
--- a/Documentation/driver-api/sound.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-Sound Devices
-=============
-
-.. kernel-doc:: include/sound/core.h
- :internal:
-
-.. kernel-doc:: sound/sound_core.c
- :export:
-
-.. kernel-doc:: include/sound/pcm.h
- :internal:
-
-.. kernel-doc:: sound/core/pcm.c
- :export:
-
-.. kernel-doc:: sound/core/device.c
- :export:
-
-.. kernel-doc:: sound/core/info.c
- :export:
-
-.. kernel-doc:: sound/core/rawmidi.c
- :export:
-
-.. kernel-doc:: sound/core/sound.c
- :export:
-
-.. kernel-doc:: sound/core/memory.c
- :export:
-
-.. kernel-doc:: sound/core/pcm_memory.c
- :export:
-
-.. kernel-doc:: sound/core/init.c
- :export:
-
-.. kernel-doc:: sound/core/isadma.c
- :export:
-
-.. kernel-doc:: sound/core/control.c
- :export:
-
-.. kernel-doc:: sound/core/pcm_lib.c
- :export:
-
-.. kernel-doc:: sound/core/hwdep.c
- :export:
-
-.. kernel-doc:: sound/core/pcm_native.c
- :export:
-
-.. kernel-doc:: sound/core/memalloc.c
- :export:
-
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst
index c8cc651eccf7..d24c64df7069 100644
--- a/Documentation/sound/kernel-api/alsa-driver-api.rst
+++ b/Documentation/sound/kernel-api/alsa-driver-api.rst
@@ -132,3 +132,4 @@ ISA DMA Helpers
Other Helper Macros
-------------------
.. kernel-doc:: include/sound/core.h
+.. kernel-doc:: sound/sound_core.c
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 28/52] docs: remove sound API duplication
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: alsa-devel, Heikki Krogerus, Kuninori Morimoto,
Mauro Carvalho Chehab, linux-kernel, rd.dunlab, Randy Dunlap,
Pragat Pandya, Jonathan Neuschäfer, Jason Gunthorpe,
Michael Walle, Mark Brown, Takashi Iwai, Harald Seiler,
Leonard Crestez
The sound API is documented on two different parts:
under Documentation/driver-api/sound.rst and under
Documentation/sound/kernel-api/alsa-driver-api.rst.
The alsa-driver-api.rst seems more complete, and APIs
are split per type. There's just one missing kernel-doc
markup there.
Add it and drop the duplicated one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/index.rst | 1 -
Documentation/driver-api/sound.rst | 54 -------------------
.../sound/kernel-api/alsa-driver-api.rst | 1 +
3 files changed, 1 insertion(+), 55 deletions(-)
delete mode 100644 Documentation/driver-api/sound.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 6e7c702e0268..987d6e74ea6a 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -27,7 +27,6 @@ available subsections can be seen below.
component
message-based
infiniband
- sound
frame-buffer
regulator
iio/index
diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst
deleted file mode 100644
index afef6eabc073..000000000000
--- a/Documentation/driver-api/sound.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-Sound Devices
-=============
-
-.. kernel-doc:: include/sound/core.h
- :internal:
-
-.. kernel-doc:: sound/sound_core.c
- :export:
-
-.. kernel-doc:: include/sound/pcm.h
- :internal:
-
-.. kernel-doc:: sound/core/pcm.c
- :export:
-
-.. kernel-doc:: sound/core/device.c
- :export:
-
-.. kernel-doc:: sound/core/info.c
- :export:
-
-.. kernel-doc:: sound/core/rawmidi.c
- :export:
-
-.. kernel-doc:: sound/core/sound.c
- :export:
-
-.. kernel-doc:: sound/core/memory.c
- :export:
-
-.. kernel-doc:: sound/core/pcm_memory.c
- :export:
-
-.. kernel-doc:: sound/core/init.c
- :export:
-
-.. kernel-doc:: sound/core/isadma.c
- :export:
-
-.. kernel-doc:: sound/core/control.c
- :export:
-
-.. kernel-doc:: sound/core/pcm_lib.c
- :export:
-
-.. kernel-doc:: sound/core/hwdep.c
- :export:
-
-.. kernel-doc:: sound/core/pcm_native.c
- :export:
-
-.. kernel-doc:: sound/core/memalloc.c
- :export:
-
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst
index c8cc651eccf7..d24c64df7069 100644
--- a/Documentation/sound/kernel-api/alsa-driver-api.rst
+++ b/Documentation/sound/kernel-api/alsa-driver-api.rst
@@ -132,3 +132,4 @@ ISA DMA Helpers
Other Helper Macros
-------------------
.. kernel-doc:: include/sound/core.h
+.. kernel-doc:: sound/sound_core.c
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 28/52] docs: remove sound API duplication
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 14:57 ` Takashi Iwai
-1 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 14:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet,
Jonathan Neuschäfer, rd.dunlab, Harald Seiler,
Heikki Krogerus, Jaroslav Kysela, Jason Gunthorpe,
Kuninori Morimoto, Leonard Crestez, Mark Brown, Michael Walle,
Pragat Pandya, Randy Dunlap, Takashi Iwai, alsa-devel,
linux-kernel
On Wed, 30 Sep 2020 15:24:51 +0200,
Mauro Carvalho Chehab wrote:
>
> The sound API is documented on two different parts:
> under Documentation/driver-api/sound.rst and under
> Documentation/sound/kernel-api/alsa-driver-api.rst.
>
> The alsa-driver-api.rst seems more complete, and APIs
> are split per type. There's just one missing kernel-doc
> markup there.
>
> Add it and drop the duplicated one.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 28/52] docs: remove sound API duplication
@ 2020-09-30 14:57 ` Takashi Iwai
0 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 14:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: alsa-devel, Heikki Krogerus, Kuninori Morimoto, Jonathan Corbet,
linux-kernel, rd.dunlab, Linux Doc Mailing List, Pragat Pandya,
Jonathan Neuschäfer, Jason Gunthorpe, Michael Walle,
Mark Brown, Randy Dunlap, Takashi Iwai, Harald Seiler,
Leonard Crestez
On Wed, 30 Sep 2020 15:24:51 +0200,
Mauro Carvalho Chehab wrote:
>
> The sound API is documented on two different parts:
> under Documentation/driver-api/sound.rst and under
> Documentation/sound/kernel-api/alsa-driver-api.rst.
>
> The alsa-driver-api.rst seems more complete, and APIs
> are split per type. There's just one missing kernel-doc
> markup there.
>
> Add it and drop the duplicated one.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 29/52] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (27 preceding siblings ...)
2020-09-30 13:24 ` Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup Mauro Carvalho Chehab
` (23 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Lai Jiangshan, Tejun Heo, linux-kernel
As there's already a rst file with workqueue markups, containing
part of them, move the other definitions, in order to avoid
warnings with Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/core-api/workqueue.rst | 2 ++
Documentation/driver-api/basics.rst | 9 ---------
2 files changed, 2 insertions(+), 9 deletions(-)
diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index 00a5ba51e63f..541d31de8926 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -396,3 +396,5 @@ Kernel Inline Documentations Reference
======================================
.. kernel-doc:: include/linux/workqueue.h
+
+.. kernel-doc:: kernel/workqueue.c
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 1ba88c7b3984..54f8d5ca7475 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -55,15 +55,6 @@ High-resolution timers
.. kernel-doc:: kernel/time/hrtimer.c
:export:
-Workqueues and Kevents
-----------------------
-
-.. kernel-doc:: include/linux/workqueue.h
- :internal:
-
-.. kernel-doc:: kernel/workqueue.c
- :export:
-
Internal Functions
------------------
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (28 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 29/52] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include Mauro Carvalho Chehab
` (22 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
This is already included at scsi.rst. So, remove the duplication,
in order to avoid Sphinx warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/target.rst | 12 ------------
1 file changed, 12 deletions(-)
diff --git a/Documentation/driver-api/target.rst b/Documentation/driver-api/target.rst
index 620ec6173a93..c70ca25171c0 100644
--- a/Documentation/driver-api/target.rst
+++ b/Documentation/driver-api/target.rst
@@ -41,18 +41,6 @@ iSCSI boot information
.. kernel-doc:: drivers/scsi/iscsi_boot_sysfs.c
:export:
-
-iSCSI transport class
-=====================
-
-The file drivers/scsi/scsi_transport_iscsi.c defines transport
-attributes for the iSCSI class, which sends SCSI packets over TCP/IP
-connections.
-
-.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
- :export:
-
-
iSCSI TCP interfaces
====================
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (29 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 21:03 ` Saravana Kannan
2020-09-30 13:24 ` [PATCH v4 32/52] docs: basics.rst: get rid of rcu kernel-doc macros Mauro Carvalho Chehab
` (21 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Greg Kroah-Hartman, Saravana Kannan, linux-kernel
The infrastructure.rst file already includes the external
symbols from drivers/base/core.c.
Duplicating 3 functions there causes namespace collisions:
Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
Declaration is 'device_link_state'.
Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
Declaration is 'device_link_add'.
Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
Declaration is 'device_link_del'.
Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
Declaration is 'device_link_remove'.
So, drop the reference, adding just a mention to the functions
associated with device_link.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/device_link.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
index 76950d061632..ee913ae16371 100644
--- a/Documentation/driver-api/device_link.rst
+++ b/Documentation/driver-api/device_link.rst
@@ -317,5 +317,4 @@ State machine
API
===
-.. kernel-doc:: drivers/base/core.c
- :functions: device_link_add device_link_del device_link_remove
+See device_link_add(), device_link_del() and device_link_remove().
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include
2020-09-30 13:24 ` [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include Mauro Carvalho Chehab
@ 2020-09-30 21:03 ` Saravana Kannan
0 siblings, 0 replies; 103+ messages in thread
From: Saravana Kannan @ 2020-09-30 21:03 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Greg Kroah-Hartman, LKML
On Wed, Sep 30, 2020 at 6:25 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> The infrastructure.rst file already includes the external
> symbols from drivers/base/core.c.
>
> Duplicating 3 functions there causes namespace collisions:
>
> Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
> Declaration is 'device_link_state'.
> Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
> Declaration is 'device_link_add'.
> Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
> Declaration is 'device_link_del'.
> Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
> Declaration is 'device_link_remove'.
>
> So, drop the reference, adding just a mention to the functions
> associated with device_link.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> Documentation/driver-api/device_link.rst | 3 +--
> 1 file changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
> index 76950d061632..ee913ae16371 100644
> --- a/Documentation/driver-api/device_link.rst
> +++ b/Documentation/driver-api/device_link.rst
> @@ -317,5 +317,4 @@ State machine
> API
> ===
>
> -.. kernel-doc:: drivers/base/core.c
> - :functions: device_link_add device_link_del device_link_remove
> +See device_link_add(), device_link_del() and device_link_remove().
I just "copy paste" rst formatting because I've never bothered to
understand it. If these changes fix warnings, I'm okay with them. They
seem pretty harmless.
-Saravana
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 32/52] docs: basics.rst: get rid of rcu kernel-doc macros
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (30 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc Mauro Carvalho Chehab
` (20 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Those are already defined at kernel-api.rst, as part of the
synchronization primitives chapter.
This solves several Sphinx 3 warnings, like:
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'rcu_idle_enter'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'rcu_idle_exit'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'rcu_is_watching'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'call_rcu'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'synchronize_rcu'.
...
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/basics.rst | 6 ------
1 file changed, 6 deletions(-)
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 54f8d5ca7475..63bbe3ed5e76 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -103,12 +103,6 @@ Kernel utility functions
.. kernel-doc:: kernel/panic.c
:export:
-.. kernel-doc:: kernel/rcu/tree.c
- :export:
-
-.. kernel-doc:: kernel/rcu/update.c
- :export:
-
.. kernel-doc:: include/linux/overflow.h
:internal:
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (31 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 32/52] docs: basics.rst: get rid of rcu kernel-doc macros Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 21:23 ` David Miller
2020-09-30 13:24 ` [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags Mauro Carvalho Chehab
` (19 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, David S. Miller, Jakub Kicinski,
linux-kernel, netdev
include/linux/ethtool.h is included twice with kernel-doc,
both to document ethtool_pause_stats(). The first one is
at statistics.rst, and the second one at ethtool-netlink.rst.
Replace one of the references to use the name of the
function. The automarkup.py extension should create the
cross-references.
Solves this warning:
../Documentation/networking/ethtool-netlink.rst: WARNING: Duplicate C declaration, also defined in 'networking/statistics'.
Declaration is 'ethtool_pause_stats'.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/networking/statistics.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst
index 8e15bc98830b..234abedc29b2 100644
--- a/Documentation/networking/statistics.rst
+++ b/Documentation/networking/statistics.rst
@@ -175,5 +175,4 @@ The following structures are internal to the kernel, their members are
translated to netlink attributes when dumped. Drivers must not overwrite
the statistics they don't report with 0.
-.. kernel-doc:: include/linux/ethtool.h
- :identifiers: ethtool_pause_stats
+- ethtool_pause_stats()
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc
2020-09-30 13:24 ` [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc Mauro Carvalho Chehab
@ 2020-09-30 21:23 ` David Miller
0 siblings, 0 replies; 103+ messages in thread
From: David Miller @ 2020-09-30 21:23 UTC (permalink / raw)
To: mchehab+huawei; +Cc: linux-doc, corbet, kuba, linux-kernel, netdev
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Wed, 30 Sep 2020 15:24:56 +0200
> include/linux/ethtool.h is included twice with kernel-doc,
> both to document ethtool_pause_stats(). The first one is
> at statistics.rst, and the second one at ethtool-netlink.rst.
>
> Replace one of the references to use the name of the
> function. The automarkup.py extension should create the
> cross-references.
>
> Solves this warning:
>
> ../Documentation/networking/ethtool-netlink.rst: WARNING: Duplicate C declaration, also defined in 'networking/statistics'.
> Declaration is 'ethtool_pause_stats'.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: David S. Miller <davem@davemloft.net>
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (32 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 23:23 ` Kees Cook
2020-09-30 13:24 ` [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags Mauro Carvalho Chehab
` (18 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Anton Vorontsov, Colin Cross, Kees Cook,
Tony Luck, linux-kernel
There is currently a problem with kernel-doc tags from blk.c:
.../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:175: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
Declaration is 'register_pstore_device'.
.../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:432: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
Declaration is 'register_pstore_blk'.
.../Documentation/admin-guide/pstore-blk:242: ./include/linux/pstore_blk.h:43: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
Declaration is 'pstore_device_info'.
Basically, the internal parts is shown with :export:, instead
of :internal:. Yet, there are some other exported docs that
aren't at the document, because they lack :identifiers:.
So, instead, let's just use :export: at the kAPI part of
the documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/admin-guide/pstore-blk.rst | 10 ++--------
1 file changed, 2 insertions(+), 8 deletions(-)
diff --git a/Documentation/admin-guide/pstore-blk.rst b/Documentation/admin-guide/pstore-blk.rst
index 296d5027787a..6898aba9fb5c 100644
--- a/Documentation/admin-guide/pstore-blk.rst
+++ b/Documentation/admin-guide/pstore-blk.rst
@@ -154,17 +154,11 @@ Configurations for driver
Only a block device driver cares about these configurations. A block device
driver uses ``register_pstore_blk`` to register to pstore/blk.
-.. kernel-doc:: fs/pstore/blk.c
- :identifiers: register_pstore_blk
-
A non-block device driver uses ``register_pstore_device`` with
``struct pstore_device_info`` to register to pstore/blk.
.. kernel-doc:: fs/pstore/blk.c
- :identifiers: register_pstore_device
-
-.. kernel-doc:: include/linux/pstore_blk.h
- :identifiers: pstore_device_info
+ :export:
Compression and header
----------------------
@@ -237,7 +231,7 @@ For developer reference, here are all the important structures and APIs:
:internal:
.. kernel-doc:: fs/pstore/blk.c
- :export:
+ :internal:
.. kernel-doc:: include/linux/pstore_blk.h
:internal:
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags
2020-09-30 13:24 ` [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags Mauro Carvalho Chehab
@ 2020-09-30 23:23 ` Kees Cook
0 siblings, 0 replies; 103+ messages in thread
From: Kees Cook @ 2020-09-30 23:23 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Anton Vorontsov,
Colin Cross, Tony Luck, linux-kernel
On Wed, Sep 30, 2020 at 03:24:57PM +0200, Mauro Carvalho Chehab wrote:
> There is currently a problem with kernel-doc tags from blk.c:
>
> .../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:175: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
> Declaration is 'register_pstore_device'.
> .../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:432: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
> Declaration is 'register_pstore_blk'.
> .../Documentation/admin-guide/pstore-blk:242: ./include/linux/pstore_blk.h:43: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
> Declaration is 'pstore_device_info'.
>
> Basically, the internal parts is shown with :export:, instead
> of :internal:. Yet, there are some other exported docs that
> aren't at the document, because they lack :identifiers:.
>
> So, instead, let's just use :export: at the kAPI part of
> the documentation.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
That should work; thanks!
Acked-by: Kees Cook <keescook@chromium.org>
--
Kees Cook
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (33 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 16:21 ` Eric Biggers
2020-09-30 13:24 ` [PATCH v4 36/52] docs: devices.rst: get rid of :c:type macros Mauro Carvalho Chehab
` (17 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Theodore Y. Ts'o, Eric Biggers,
Jaegeuk Kim, linux-fscrypt, linux-kernel
The :c:type: tag has problems with Sphinx 3.x, as structs
there should be declared with c:struct.
So, remove them, relying at automarkup.py extension to
convert them into cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/filesystems/fscrypt.rst | 51 ++++++++++++---------------
1 file changed, 23 insertions(+), 28 deletions(-)
diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 4f858b38a412..46a9d1bd2ab5 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -437,8 +437,7 @@ FS_IOC_SET_ENCRYPTION_POLICY
The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
empty directory or verifies that a directory or regular file already
has the specified encryption policy. It takes in a pointer to a
-struct fscrypt_policy_v1 or a :c:type:`struct
-fscrypt_policy_v2`, defined as follows::
+struct fscrypt_policy_v1 or a struct fscrypt_policy_v2, defined as follows::
#define FSCRYPT_POLICY_V1 0
#define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
@@ -464,11 +463,10 @@ fscrypt_policy_v2`, defined as follows::
This structure must be initialized as follows:
-- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
- :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
- is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original
- policy version as "v1", though its version code is really 0.) For
- new encrypted directories, use v2 policies.
+- ``version`` must be FSCRYPT_POLICY_V1 (0) if struct fscrypt_policy_v1
+ is used or FSCRYPT_POLICY_V2 (2) if struct fscrypt_policy_v2 is used.
+ (Note: we refer to the original policy version as "v1", though its
+ version code is really 0.) For new encrypted directories, use v2 policies.
- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
be set to constants from ``<linux/fscrypt.h>`` which identify the
@@ -509,8 +507,7 @@ This structure must be initialized as follows:
be arbitrarily chosen. Instead, the key must first be added using
`FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
the kernel returned in the struct fscrypt_add_key_arg must
- be used as the ``master_key_identifier`` in the :c:type:`struct
- fscrypt_policy_v2`.
+ be used as the ``master_key_identifier`` in struct fscrypt_policy_v2.
If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
verifies that the file is an empty directory. If so, the specified
@@ -637,9 +634,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
encryption policy, if any, for a directory or regular file. However,
unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
-version. It takes in a pointer directly to a :c:type:`struct
-fscrypt_policy_v1` rather than a :c:type:`struct
-fscrypt_get_policy_ex_arg`.
+version. It takes in a pointer directly to struct fscrypt_policy_v1
+rather than struct fscrypt_get_policy_ex_arg.
The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
@@ -717,10 +713,9 @@ as follows:
``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
``key_spec.u.descriptor`` must contain the descriptor of the key
being added, corresponding to the value in the
- ``master_key_descriptor`` field of :c:type:`struct
- fscrypt_policy_v1`. To add this type of key, the calling process
- must have the CAP_SYS_ADMIN capability in the initial user
- namespace.
+ ``master_key_descriptor`` field of struct fscrypt_policy_v1.
+ To add this type of key, the calling process must have the
+ CAP_SYS_ADMIN capability in the initial user namespace.
Alternatively, if the key is being added for use by v2 encryption
policies, then ``key_spec.type`` must contain
@@ -737,8 +732,8 @@ as follows:
- ``key_id`` is 0 if the raw key is given directly in the ``raw``
field. Otherwise ``key_id`` is the ID of a Linux keyring key of
- type "fscrypt-provisioning" whose payload is a :c:type:`struct
- fscrypt_provisioning_key_payload` whose ``raw`` field contains the
+ type "fscrypt-provisioning" whose payload is
+ struct fscrypt_provisioning_key_payload whose ``raw`` field contains the
raw key and whose ``type`` field matches ``key_spec.type``. Since
``raw`` is variable-length, the total size of this key's payload
must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the
@@ -956,8 +951,8 @@ FS_IOC_GET_ENCRYPTION_KEY_STATUS
The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
master encryption key. It can be executed on any file or directory on
the target filesystem, but using the filesystem's root directory is
-recommended. It takes in a pointer to a :c:type:`struct
-fscrypt_get_key_status_arg`, defined as follows::
+recommended. It takes in a pointer to struct fscrypt_get_key_status_arg,
+defined as follows::
struct fscrypt_get_key_status_arg {
/* input */
@@ -1148,12 +1143,12 @@ Implementation details
Encryption context
------------------
-An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context_v1` or a struct fscrypt_context_v2. It is
-up to individual filesystems to decide where to store it, but normally
-it would be stored in a hidden extended attribute. It should *not* be
-exposed by the xattr-related system calls such as getxattr() and
-setxattr() because of the special semantics of the encryption xattr.
+An encryption policy is represented on-disk by struct fscrypt_context_v1
+or struct fscrypt_context_v2. It is up to individual filesystems to decide
+where to store it, but normally it would be stored in a hidden extended
+attribute. It should *not* be exposed by the xattr-related system calls
+such as getxattr() and setxattr() because of the special semantics of the
+encryption xattr.
(In particular, there would be much confusion if an encryption policy
were to be added to or removed from anything other than an empty
directory.) These structs are defined as follows::
@@ -1249,8 +1244,8 @@ a strong "hash" of the ciphertext filename, along with the optional
filesystem-specific hash(es) needed for directory lookups. This
allows the filesystem to still, with a high degree of confidence, map
the filename given in ->lookup() back to a particular directory entry
-that was previously listed by readdir(). See :c:type:`struct
-fscrypt_nokey_name` in the source for more details.
+that was previously listed by readdir(). See struct fscrypt_nokey_name
+in the source for more details.
Note that the precise way that filenames are presented to userspace
without the key is subject to change in the future. It is only meant
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-09-30 13:24 ` [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags Mauro Carvalho Chehab
@ 2020-09-30 16:21 ` Eric Biggers
2020-09-30 16:53 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 103+ messages in thread
From: Eric Biggers @ 2020-09-30 16:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Theodore Y. Ts'o,
Jaegeuk Kim, linux-fscrypt, linux-kernel
On Wed, Sep 30, 2020 at 03:24:58PM +0200, Mauro Carvalho Chehab wrote:
> The :c:type: tag has problems with Sphinx 3.x, as structs
> there should be declared with c:struct.
>
> So, remove them, relying at automarkup.py extension to
> convert them into cross-references.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
What does this patch series apply to? Cover letter says next-20200922, but it
doesn't apply.
It's very difficult to review patches without any way to apply them.
- Eric
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-09-30 16:21 ` Eric Biggers
@ 2020-09-30 16:53 ` Mauro Carvalho Chehab
2020-09-30 17:06 ` Eric Biggers
0 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 16:53 UTC (permalink / raw)
To: Eric Biggers
Cc: Linux Doc Mailing List, Jonathan Corbet, Theodore Y. Ts'o,
Jaegeuk Kim, linux-fscrypt, linux-kernel
Hi Eric,
Em Wed, 30 Sep 2020 09:21:44 -0700
Eric Biggers <ebiggers@kernel.org> escreveu:
> On Wed, Sep 30, 2020 at 03:24:58PM +0200, Mauro Carvalho Chehab wrote:
> > The :c:type: tag has problems with Sphinx 3.x, as structs
> > there should be declared with c:struct.
> >
> > So, remove them, relying at automarkup.py extension to
> > convert them into cross-references.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> What does this patch series apply to? Cover letter says next-20200922, but it
> doesn't apply.
>
> It's very difficult to review patches without any way to apply them.
I double checked: it is against next-20200922. The reason of
not being today's next is that I didn't want any new warnings
to be introduced before I finish this patch series.
Anyway, I'm planning to do a rebase tomorrow on the top of the
latest -next.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-09-30 16:53 ` Mauro Carvalho Chehab
@ 2020-09-30 17:06 ` Eric Biggers
2020-10-05 12:06 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 103+ messages in thread
From: Eric Biggers @ 2020-09-30 17:06 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Theodore Y. Ts'o,
Jaegeuk Kim, linux-fscrypt, linux-kernel
On Wed, Sep 30, 2020 at 06:53:33PM +0200, Mauro Carvalho Chehab wrote:
> Hi Eric,
>
> Em Wed, 30 Sep 2020 09:21:44 -0700
> Eric Biggers <ebiggers@kernel.org> escreveu:
>
> > On Wed, Sep 30, 2020 at 03:24:58PM +0200, Mauro Carvalho Chehab wrote:
> > > The :c:type: tag has problems with Sphinx 3.x, as structs
> > > there should be declared with c:struct.
> > >
> > > So, remove them, relying at automarkup.py extension to
> > > convert them into cross-references.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >
> > What does this patch series apply to? Cover letter says next-20200922, but it
> > doesn't apply.
> >
> > It's very difficult to review patches without any way to apply them.
>
> I double checked: it is against next-20200922. The reason of
> not being today's next is that I didn't want any new warnings
> to be introduced before I finish this patch series.
>
> Anyway, I'm planning to do a rebase tomorrow on the top of the
> latest -next.
>
Doesn't work. Here's what I did:
e@sol ~/linux $ git checkout -f next-20200922
Updating files: 100% (9850/9850), done.
HEAD is now at e64997027d5f Add linux-next specific files for 20200922
e@sol ~/linux $ b4 am 689d790237b64fc7d81fcf97ac303cc1dbdd33d4.1601467849.git.mchehab+huawei@kernel.org
Looking up https://lore.kernel.org/linux-fscrypt/689d790237b64fc7d81fcf97ac303cc1dbdd33d4.1601467849.git.mchehab%2Bhuawei%40kernel.org
Grabbing thread from lore.kernel.org/linux-fscrypt
Analyzing 7 messages in the thread
---
Thread incomplete, attempting to backfill
Grabbing thread from lore.kernel.org/linux-doc
Loaded 59 messages from https://lore.kernel.org/linux-doc/
Grabbing thread from lore.kernel.org/alsa-devel
Grabbing thread from lore.kernel.org/linux-fpga
Grabbing thread from lore.kernel.org/lkml
Loaded 2 messages from https://lore.kernel.org/lkml/
Successfully backfilled missing patches
---
Writing ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.mbx
[PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag
[PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags
[PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x
[PATCH v4 04/52] scripts: kernel-doc: make it more compatible with Sphinx 3.x
[PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x
[PATCH v4 06/52] scripts: kernel-doc: fix troubles with line counts
[PATCH v4 07/52] scripts: kernel-doc: reimplement -nofunction argument
[PATCH v4 08/52] scripts: kernel-doc: fix typedef identification
[PATCH v4 09/52] scripts: kernel-doc: don't mangle with parameter list
[PATCH v4 10/52] docs: kerneldoc.py: append the name of the parsed doc file
[PATCH v4 11/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol
[PATCH v4 12/52] media: docs: make CEC documents compatible with Sphinx 3.1+
[PATCH v4 13/52] media: docs: make V4L documents more compatible with Sphinx 3.1+
[PATCH v4 14/52] media: docs: make DVB documents more compatible with Sphinx 3.1+
[PATCH v4 15/52] media: docs: make MC documents more compatible with Sphinx 3.1+
[PATCH v4 16/52] media: docs: make RC documents more compatible with Sphinx 3.1+
[PATCH v4 17/52] media: cec-core.rst: don't use c:type for structs
[PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments
+ Reviewed-by: Vincenzo Frascino <vincenzo.frascino@arm.com>
[PATCH v4 19/52] memblock: get rid of a :c:type leftover
[PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup
[PATCH v4 21/52] docs: remove some replace macros like |struct foo|
[PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs
+ Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
+ Reviewed-by: André Almeida <andrealmeid@collabora.com>
[PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
+ Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
[PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst
[PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions
[PATCH v4 26/52] docs: genericirq.rst: don't document chip.c functions twice
[PATCH v4 27/52] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag
[PATCH v4 28/52] docs: remove sound API duplication
+ Reviewed-by: Takashi Iwai <tiwai@suse.de>
[PATCH v4 29/52] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst
[PATCH v4 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup
[PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include
[PATCH v4 32/52] docs: basics.rst: get rid of rcu kernel-doc macros
[PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc
[PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags
[PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
[PATCH v4 36/52] docs: devices.rst: get rid of :c:type macros
[PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
+ Reviewed-by: Takashi Iwai <tiwai@suse.de>
[PATCH v4 38/52] docs: block: typec_bus.rst: get rid of :c:type
+ Reviewed-by: André Almeida <andrealmeid@collabora.com>
[PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
+ Reviewed-by: Takashi Iwai <tiwai@suse.de>
[PATCH v4 40/52] docs: fpga: replace :c:member: macros
[PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages
[PATCH v4 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag
[PATCH v4 43/52] docs: infrastructure.rst: don't include firmware kernel-doc
[PATCH v4 44/52] docs: gpu: i915.rst: Fix several C duplication warnings
[PATCH v4 45/52] docs: devices.rst: fix a C reference markup
[PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup
[PATCH v4 47/52] docs: mei.rst: fix a C expression markup
[PATCH v4 48/52] docs: basics.rst: avoid duplicated C function declaration
[PATCH v4 49/52] workqueue: fix a kernel-doc warning
+ Acked-by: Tejun Heo <tj@kernel.org>
[PATCH v4 50/52] scripts: kernel-doc: try to use c:function if possible
[PATCH v4 51/52] docs: conf.py: fix c:function support with Sphinx 3.x
[PATCH v4 52/52] docs: conf.py: change the Sphinx 3.x+ text
---
Total patches: 52
---
Cover: ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.cover
Link: https://lore.kernel.org/r/cover.1601467849.git.mchehab+huawei@kernel.org
Base: not found
git am ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.mbx
e@sol ~/linux $ git am ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.mbx
Applying: docs: cdomain.py: add support for a new Sphinx 3.1+ tag
Applying: docs: cdomain.py: extend it to handle new Sphinx 3.x tags
Applying: docs: conf.py: disable automarkup for Sphinx 3.x
Applying: scripts: kernel-doc: make it more compatible with Sphinx 3.x
Applying: scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x
Applying: scripts: kernel-doc: fix troubles with line counts
Applying: scripts: kernel-doc: reimplement -nofunction argument
Applying: scripts: kernel-doc: fix typedef identification
Applying: scripts: kernel-doc: don't mangle with parameter list
Applying: docs: kerneldoc.py: append the name of the parsed doc file
Applying: docs: kerneldoc.py: add support for kerneldoc -nosymbol
Applying: media: docs: make CEC documents compatible with Sphinx 3.1+
Applying: media: docs: make V4L documents more compatible with Sphinx 3.1+
error: patch failed: Documentation/userspace-api/media/v4l/hist-v4l2.rst:202
error: Documentation/userspace-api/media/v4l/hist-v4l2.rst: patch does not apply
error: patch failed: Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst:227
error: Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst: patch does not apply
Patch failed at 0013 media: docs: make V4L documents more compatible with Sphinx 3.1+
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-09-30 17:06 ` Eric Biggers
@ 2020-10-05 12:06 ` Mauro Carvalho Chehab
2020-10-05 19:08 ` Eric Biggers
0 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-05 12:06 UTC (permalink / raw)
To: Eric Biggers
Cc: Linux Doc Mailing List, Jonathan Corbet, Theodore Y. Ts'o,
Jaegeuk Kim, linux-fscrypt, linux-kernel
Hi Eric,
Em Wed, 30 Sep 2020 10:06:37 -0700
Eric Biggers <ebiggers@kernel.org> escreveu:
> > I double checked: it is against next-20200922. The reason of
> > not being today's next is that I didn't want any new warnings
> > to be introduced before I finish this patch series.
> >
> > Anyway, I'm planning to do a rebase tomorrow on the top of the
> > latest -next.
> >
>
> Doesn't work. Here's what I did:
...
> Cover: ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.cover
> Link: https://lore.kernel.org/r/cover.1601467849.git.mchehab+huawei@kernel.org
> Base: not found
> git am ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.mbx
>
> e@sol ~/linux $ git am ./v4_20200930_mchehab_huawei_fix_html_build_with_sphinx_3_1_and_above.mbx
> Applying: docs: cdomain.py: add support for a new Sphinx 3.1+ tag
> Applying: docs: cdomain.py: extend it to handle new Sphinx 3.x tags
> Applying: docs: conf.py: disable automarkup for Sphinx 3.x
> Applying: scripts: kernel-doc: make it more compatible with Sphinx 3.x
> Applying: scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x
> Applying: scripts: kernel-doc: fix troubles with line counts
> Applying: scripts: kernel-doc: reimplement -nofunction argument
> Applying: scripts: kernel-doc: fix typedef identification
> Applying: scripts: kernel-doc: don't mangle with parameter list
> Applying: docs: kerneldoc.py: append the name of the parsed doc file
> Applying: docs: kerneldoc.py: add support for kerneldoc -nosymbol
> Applying: media: docs: make CEC documents compatible with Sphinx 3.1+
> Applying: media: docs: make V4L documents more compatible with Sphinx 3.1+
> error: patch failed: Documentation/userspace-api/media/v4l/hist-v4l2.rst:202
> error: Documentation/userspace-api/media/v4l/hist-v4l2.rst: patch does not apply
> error: patch failed: Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst:227
> error: Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst: patch does not apply
> Patch failed at 0013 media: docs: make V4L documents more compatible with Sphinx 3.1+
> hint: Use 'git am --show-current-patch=diff' to see the failed patch
> When you have resolved this problem, run "git am --continue".
> If you prefer to skip this patch, run "git am --skip" instead.
> To restore the original branch and stop patching, run "git am --abort".
Well, the media patches were indeed based at the media upstream tree.
As I maintain the media tree, and the changes for it are huge, I opted
to merge from media before applying this series. Btw, the series
is also after the other fix patches for the warnings with Sphinx 2.x
that I sent previously. It might eventually conflict with the Sphinx 3.x
patch series.
At the current version, there are 101 patches against next-20201002, being
about half of them fixing all doc warnings on Sphinx 2.x, and the other
ones fixing almost all Sphinx 3.x warnings.
The latest version at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=sphinx3-fixes-v4
In the specific case of fscript.rst, there are only two patches on my
series affecting it, both as part of this /52 series:
$ git log next-20200922..devel/sphinx3-fixes-v4 Documentation/filesystems/fscrypt.rst
commit ee4af6dd20dd6d2ac7f5d970abac960a36679e13
Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Tue Sep 29 09:13:18 2020 +0200
docs: fs: fscrypt.rst: get rid of :c:type: tags
The :c:type: tag has problems with Sphinx 3.x, as structs
there should be declared with c:struct.
So, remove them, relying at automarkup.py extension to
convert them into cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
commit 0945e3961d006e210e374b6d3224d9108c1dfa25
Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Fri Sep 25 12:01:25 2020 +0200
docs: get rid of :c:type explicit declarations for structs
The :c:type:`foo` only works properly with structs before
Sphinx 3.x.
On Sphinx 3.x, structs should now be declared using the
.. c:struct, and referenced via :c:struct tag.
As we now have the automarkup.py macro, that automatically
convert:
struct foo
into cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Anyway, I'm waiting for the today's next, in order to do another
rebase, fixing any new warning that might be added, and to post the
patches that weren't merged yet via other trees.
The end goal is to have zero warnings with Sphinx 2.x, and the minimal
number of warnings with 3.x (right now, there's just 6 warnings
with 3.x - fixing those require fixes at Sphinx C domain parser).
Thanks,
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-10-05 12:06 ` Mauro Carvalho Chehab
@ 2020-10-05 19:08 ` Eric Biggers
2020-10-06 8:23 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 103+ messages in thread
From: Eric Biggers @ 2020-10-05 19:08 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Theodore Y. Ts'o,
Jaegeuk Kim, linux-fscrypt, linux-kernel
On Mon, Oct 05, 2020 at 02:06:22PM +0200, Mauro Carvalho Chehab wrote:
> The latest version at:
>
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=sphinx3-fixes-v4
Doesn't work either.
$ git remote add mchehab https://git.linuxtv.org/mchehab/experimental.git
$ git fetch mchehab
warning: alternate disabled by http.followRedirects: https://git.linuxtv.org/git/linux.git/
warning: alternate disabled by http.followRedirects: https://git.linuxtv.org/git/media_tree.git/
warning: alternate disabled by http.followRedirects: https://git.linuxtv.org/git/linux.git/
error: Unable to find 4d9f4b7b8bf7af2d8deb4435833a7e165b9bdd21 under https://git.linuxtv.org/mchehab/experimental.git
Fetching objects: 286, done.
Cannot obtain needed object 4d9f4b7b8bf7af2d8deb4435833a7e165b9bdd21
while processing commit 0a0cde580853340e1a585a1959eaaf055b7cff9a.
error: fetch failed.
> In the specific case of fscript.rst, there are only two patches on my
> series affecting it, both as part of this /52 series:
But those two patches don't apply because they also change other files.
I need to apply patches to do a proper review. Reviewers shouldn't have to
waste time trying to figure out how to apply your patches.
- Eric
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags
2020-10-05 19:08 ` Eric Biggers
@ 2020-10-06 8:23 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-06 8:23 UTC (permalink / raw)
To: Eric Biggers
Cc: Linux Doc Mailing List, Jonathan Corbet, Theodore Y. Ts'o,
Jaegeuk Kim, linux-fscrypt, linux-kernel
Em Mon, 5 Oct 2020 12:08:23 -0700
Eric Biggers <ebiggers@kernel.org> escreveu:
> On Mon, Oct 05, 2020 at 02:06:22PM +0200, Mauro Carvalho Chehab wrote:
> > The latest version at:
> >
> > https://git.linuxtv.org/mchehab/experimental.git/log/?h=sphinx3-fixes-v4
>
> Doesn't work either.
>
> $ git remote add mchehab https://git.linuxtv.org/mchehab/experimental.git
> $ git fetch mchehab
> warning: alternate disabled by http.followRedirects: https://git.linuxtv.org/git/linux.git/
> warning: alternate disabled by http.followRedirects: https://git.linuxtv.org/git/media_tree.git/
> warning: alternate disabled by http.followRedirects: https://git.linuxtv.org/git/linux.git/
> error: Unable to find 4d9f4b7b8bf7af2d8deb4435833a7e165b9bdd21 under https://git.linuxtv.org/mchehab/experimental.git
> Fetching objects: 286, done.
> Cannot obtain needed object 4d9f4b7b8bf7af2d8deb4435833a7e165b9bdd21
> while processing commit 0a0cde580853340e1a585a1959eaaf055b7cff9a.
> error: fetch failed.
Well, support for https was broken at linuxtv.org. Not many media
developers use https instead of git.
The main issue is that we heavily use alternates there, in order
to minimize disk space usage. After some server upgrade, https
stopped working properly.
I just fixed it, by adding some new rewrite rules that will call
git http-backend in order to solve alternates.
Thanks for reporting it.
> > In the specific case of fscript.rst, there are only two patches on my
> > series affecting it, both as part of this /52 series:
>
> But those two patches don't apply because they also change other files.
>
> I need to apply patches to do a proper review. Reviewers shouldn't have to
> waste time trying to figure out how to apply your patches.
Yeah, agreed. Sorry for that.
Not sure what would be the best way to minimize the issues, though.
I mean, I might place those documentation patches on my linux-next
branch, making them visible at tomorrow's linux-next, but that
doesn't sound a good idea, as this will be a source of conflicts,
since several patches from my tree are based on patches applied
via someone's else's tree.
Hopefully, after getting this series merged upstream, the
docs build for html will finally went into a clean state. Any new
warnings that might sleep though maintainer's reviews could
easily be fixed without depending on a 100+ patch series.
-
Btw, there was no new linux-next tag yesterday. The last one is
still next-20201002.
I'll wait for a while a today's linux-next. After rebasing on the
top of that, I'll submit a v5 of this series.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 36/52] docs: devices.rst: get rid of :c:type macros
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (34 preceding siblings ...)
2020-09-30 13:24 ` [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags Mauro Carvalho Chehab
@ 2020-09-30 13:24 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` Mauro Carvalho Chehab
` (16 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Rafael J. Wysocki, Alan Stern,
Bjorn Helgaas, Wolfram Sang, linux-kernel
There's no need to use macros to use :c:type on this file,
as automarkup.py should do this automatically.
Also, this breaks compatibility with Sphinx 3.x, as there,
structs should be declared using .. c:struct.
So, get rid of them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/pm/devices.rst | 24 ++++++++----------------
1 file changed, 8 insertions(+), 16 deletions(-)
diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 946ad0b94e31..4bda8a21f5d1 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -1,14 +1,6 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
-.. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>`
-.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
-.. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>`
-.. |struct device_type| replace:: :c:type:`struct device_type <device_type>`
-.. |struct class| replace:: :c:type:`struct class <class>`
-.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>`
-.. |struct device| replace:: :c:type:`struct device <device>`
-
.. _driverapi_pm_devices:
==============================
@@ -107,7 +99,7 @@ Device Power Management Operations
Device power management operations, at the subsystem level as well as at the
device driver level, are implemented by defining and populating objects of type
-|struct dev_pm_ops| defined in :file:`include/linux/pm.h`. The roles of the
+struct dev_pm_ops defined in :file:`include/linux/pm.h`. The roles of the
methods included in it will be explained in what follows. For now, it should be
sufficient to remember that the last three methods are specific to runtime power
management while the remaining ones are used during system-wide power
@@ -115,7 +107,7 @@ transitions.
There also is a deprecated "old" or "legacy" interface for power management
operations available at least for some subsystems. This approach does not use
-|struct dev_pm_ops| objects and it is suitable only for implementing system
+struct dev_pm_ops objects and it is suitable only for implementing system
sleep power management methods in a limited way. Therefore it is not described
in this document, so please refer directly to the source code for more
information about it.
@@ -125,9 +117,9 @@ Subsystem-Level Methods
-----------------------
The core methods to suspend and resume devices reside in
-|struct dev_pm_ops| pointed to by the :c:member:`ops` member of
-|struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|,
-|struct device_type| and |struct class|. They are mostly of interest to the
+struct dev_pm_ops pointed to by the :c:member:`ops` member of
+struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type,
+struct device_type and struct class. They are mostly of interest to the
people writing infrastructure for platforms and buses, like PCI or USB, or
device type and device class drivers. They also are relevant to the writers of
device drivers whose subsystems (PM domains, device types, device classes and
@@ -156,7 +148,7 @@ The :c:member:`power.can_wakeup` flag just records whether the device (and its
driver) can physically support wakeup events. The
:c:func:`device_set_wakeup_capable()` routine affects this flag. The
:c:member:`power.wakeup` field is a pointer to an object of type
-|struct wakeup_source| used for controlling whether or not the device should use
+struct wakeup_source used for controlling whether or not the device should use
its system wakeup mechanism and for notifying the PM core of system wakeup
events signaled by the device. This object is only present for wakeup-capable
devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created
@@ -713,8 +705,8 @@ nested inside another power domain. The nested domain is referred to as the
sub-domain of the parent domain.
Support for power domains is provided through the :c:member:`pm_domain` field of
-|struct device|. This field is a pointer to an object of type
-|struct dev_pm_domain|, defined in :file:`include/linux/pm.h`, providing a set
+struct device. This field is a pointer to an object of type
+struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set
of power management callbacks analogous to the subsystem-level and device driver
callbacks that are executed for the given device during all power transitions,
instead of the respective subsystem-level callbacks. Specifically, if a
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Arnd Bergmann, Jaroslav Kysela,
Julia Lawall, Takashi Iwai, alsa-devel, linux-kernel
the :c:type shouldn't be used with structs with Sphinx 3,
as the C domain there uses .. c:struct for structs.
As we have the automarkup extension, let's just get rid of
all :c:type as a hole, as those will be automagically
marked as such.
This solves a bunch of warnings with Sphinx 3, like those:
.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
Invalid C declaration: Expected end of definition. [error at 8]
calling snd_card_free
--------^
.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
Invalid C declaration: Expected end of definition. [error at 20]
snd_rawmidi_transmit*
--------------------^
.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
Invalid C declaration: Expected end of definition. [error at 9]
copy_from/to_user
---------^
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../kernel-api/writing-an-alsa-driver.rst | 105 ++++++++----------
1 file changed, 47 insertions(+), 58 deletions(-)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index aa9d5ab183d2..85d6e9c643ef 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -194,7 +194,7 @@ The minimum flow for PCI soundcards is as follows:
- create ``remove`` callback.
-- create a :c:type:`struct pci_driver <pci_driver>` structure
+- create a struct pci_driver structure
containing the three pointers above.
- create an ``init`` function just calling the
@@ -487,7 +487,7 @@ The destructor, remove callback, simply releases the card instance. Then
the ALSA middle layer will release all the attached components
automatically.
-It would be typically just :c:func:`calling snd_card_free()`:
+It would be typically just calling :c:func:`snd_card_free()`:
::
@@ -560,16 +560,15 @@ return the card instance. The extra_size argument is used to allocate
card->private_data for the chip-specific data. Note that these data are
allocated by :c:func:`snd_card_new()`.
-The first argument, the pointer of struct :c:type:`struct device
-<device>`, specifies the parent device. For PCI devices, typically
-``&pci->`` is passed there.
+The first argument, the pointer of struct device, specifies the parent
+device. For PCI devices, typically ``&pci->`` is passed there.
Components
----------
After the card is created, you can attach the components (devices) to
the card instance. In an ALSA driver, a component is represented as a
-:c:type:`struct snd_device <snd_device>` object. A component
+struct snd_device object. A component
can be a PCM instance, a control interface, a raw MIDI interface, etc.
Each such instance has one component entry.
@@ -628,7 +627,7 @@ argument of :c:func:`snd_card_new()`, i.e.
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
sizeof(struct mychip), &card);
-:c:type:`struct mychip <mychip>` is the type of the chip record.
+struct mychip is the type of the chip record.
In return, the allocated record can be accessed as
@@ -890,7 +889,7 @@ functions. These resources must be released in the destructor
function (see below).
Now assume that the PCI device has an I/O port with 8 bytes and an
-interrupt. Then :c:type:`struct mychip <mychip>` will have the
+interrupt. Then struct mychip will have the
following fields:
::
@@ -1094,7 +1093,7 @@ PCI Entries
-----------
So far, so good. Let's finish the missing PCI stuff. At first, we need a
-:c:type:`struct pci_device_id <pci_device_id>` table for
+struct pci_device_id table for
this chipset. It's a table of PCI vendor/device ID number, and some
masks.
@@ -1110,19 +1109,17 @@ For example,
};
MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
-The first and second fields of the :c:type:`struct pci_device_id
-<pci_device_id>` structure are the vendor and device IDs. If you
-have no reason to filter the matching devices, you can leave the
-remaining fields as above. The last field of the :c:type:`struct
-pci_device_id <pci_device_id>` struct contains private data
-for this entry. You can specify any value here, for example, to define
-specific operations for supported device IDs. Such an example is found
-in the intel8x0 driver.
+The first and second fields of the struct pci_device_id are the vendor
+and device IDs. If you have no reason to filter the matching devices, you can
+leave the remaining fields as above. The last field of the
+struct pci_device_id contains private data for this entry. You can specify
+any value here, for example, to define specific operations for supported
+device IDs. Such an example is found in the intel8x0 driver.
The last entry of this list is the terminator. You must specify this
all-zero entry.
-Then, prepare the :c:type:`struct pci_driver <pci_driver>`
+Then, prepare the struct pci_driver
record:
::
@@ -1439,8 +1436,8 @@ corresponding argument.
If a chip supports multiple playbacks or captures, you can specify more
numbers, but they must be handled properly in open/close, etc.
callbacks. When you need to know which substream you are referring to,
-then it can be obtained from :c:type:`struct snd_pcm_substream
-<snd_pcm_substream>` data passed to each callback as follows:
+then it can be obtained from struct snd_pcm_substream data passed to each
+callback as follows:
::
@@ -1639,10 +1636,9 @@ In the sections below, important records are explained.
Hardware Description
~~~~~~~~~~~~~~~~~~~~
-The hardware descriptor (:c:type:`struct snd_pcm_hardware
-<snd_pcm_hardware>`) contains the definitions of the fundamental
-hardware configuration. Above all, you'll need to define this in the
-`PCM open callback`_. Note that the runtime instance holds the copy of
+The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
+the fundamental hardware configuration. Above all, you'll need to define this
+in the `PCM open callback`_. Note that the runtime instance holds the copy of
the descriptor, not the pointer to the existing descriptor. That is,
in the open callback, you can modify the copied descriptor
(``runtime->hw``) as you need. For example, if the maximum number of
@@ -1800,14 +1796,13 @@ Running Status
~~~~~~~~~~~~~~
The running status can be referred via ``runtime->status``. This is
-the pointer to the :c:type:`struct snd_pcm_mmap_status
-<snd_pcm_mmap_status>` record. For example, you can get the current
+the pointer to the struct snd_pcm_mmap_status record.
+For example, you can get the current
DMA hardware pointer via ``runtime->status->hw_ptr``.
The DMA application pointer can be referred via ``runtime->control``,
-which points to the :c:type:`struct snd_pcm_mmap_control
-<snd_pcm_mmap_control>` record. However, accessing directly to
-this value is not recommended.
+which points to the struct snd_pcm_mmap_control record.
+However, accessing directly to this value is not recommended.
Private Data
~~~~~~~~~~~~
@@ -1843,8 +1838,8 @@ error number such as ``-EINVAL``. To choose an appropriate error
number, it is advised to check what value other parts of the kernel
return when the same kind of request fails.
-The callback function takes at least the argument with :c:type:`struct
-snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
+The callback function takes at least the argument with
+struct snd_pcm_substream pointer. To retrieve the chip
record from the given substream instance, you can use the following
macro.
@@ -2313,10 +2308,10 @@ non-atomic contexts. For example, the function
:c:func:`snd_pcm_period_elapsed()` is called typically from the
interrupt handler. But, if you set up the driver to use a threaded
interrupt handler, this call can be in non-atomic context, too. In such
-a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
-<snd_pcm>` object after creating it. When this flag is set, mutex
-and rwsem are used internally in the PCM core instead of spin and
-rwlocks, so that you can call all PCM functions safely in a non-atomic
+a case, you can set ``nonatomic`` filed of struct snd_pcm object
+after creating it. When this flag is set, mutex and rwsem are used internally
+in the PCM core instead of spin and rwlocks, so that you can call all PCM
+functions safely in a non-atomic
context.
Constraints
@@ -2357,8 +2352,7 @@ There are many different constraints. Look at ``sound/pcm.h`` for a
complete list. You can even define your own constraint rules. For
example, let's suppose my_chip can manage a substream of 1 channel if
and only if the format is ``S16_LE``, otherwise it supports any format
-specified in the :c:type:`struct snd_pcm_hardware
-<snd_pcm_hardware>` structure (or in any other
+specified in struct snd_pcm_hardware> (or in any other
constraint_list). You can build a rule like this:
::
@@ -2467,7 +2461,7 @@ Definition of Controls
To create a new control, you need to define the following three
callbacks: ``info``, ``get`` and ``put``. Then, define a
-:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
+struct snd_kcontrol_new record, such as:
::
@@ -2602,8 +2596,8 @@ info callback
~~~~~~~~~~~~~
The ``info`` callback is used to get detailed information on this
-control. This must store the values of the given :c:type:`struct
-snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
+control. This must store the values of the given
+struct snd_ctl_elem_info object. For example,
for a boolean control with a single element:
::
@@ -2774,13 +2768,11 @@ In the simplest way, you can do like this:
if (err < 0)
return err;
-where ``my_control`` is the :c:type:`struct snd_kcontrol_new
-<snd_kcontrol_new>` object defined above, and chip is the object
-pointer to be passed to kcontrol->private_data which can be referred
-to in callbacks.
+where ``my_control`` is the struct snd_kcontrol_new object defined above,
+and chip is the object pointer to be passed to kcontrol->private_data which
+can be referred to in callbacks.
-:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
-snd_kcontrol <snd_kcontrol>` instance, and
+:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
:c:func:`snd_ctl_add()` assigns the given control component to the
card.
@@ -2797,10 +2789,9 @@ can call :c:func:`snd_ctl_notify()`. For example,
This function takes the card pointer, the event-mask, and the control id
pointer for the notification. The event-mask specifies the types of
notification, for example, in the above example, the change of control
-values is notified. The id pointer is the pointer of :c:type:`struct
-snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
-find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
-interrupts.
+values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
+to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
+for hardware volume interrupts.
Metadata
--------
@@ -2915,9 +2906,8 @@ with an ``ac97_bus_ops_t`` record with callback functions.
The bus record is shared among all belonging ac97 instances.
-And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
-snd_ac97_template <snd_ac97_template>` record together with
-the bus pointer created above.
+And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
+record together with the bus pointer created above.
::
@@ -3118,11 +3108,10 @@ devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
Usually, the port address corresponds to the command port and port + 1
corresponds to the data port. If not, you may change the ``cport``
-field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
-However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
+field of struct snd_mpu401 manually afterward.
+However, struct snd_mpu401 pointer is
not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
-need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
-<snd_mpu401>` explicitly,
+need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
::
@@ -3772,7 +3761,7 @@ For creating the SG-buffer handler, call
:c:func:`snd_pcm_set_managed_buffer_all()` with
``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
pre-allocator. You need to pass ``&pci->dev``, where pci is
-the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
+the struct pci_dev pointer of the chip as
well.
::
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: alsa-devel, Arnd Bergmann, Mauro Carvalho Chehab, linux-kernel,
Takashi Iwai, Julia Lawall
the :c:type shouldn't be used with structs with Sphinx 3,
as the C domain there uses .. c:struct for structs.
As we have the automarkup extension, let's just get rid of
all :c:type as a hole, as those will be automagically
marked as such.
This solves a bunch of warnings with Sphinx 3, like those:
.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
Invalid C declaration: Expected end of definition. [error at 8]
calling snd_card_free
--------^
.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
Invalid C declaration: Expected end of definition. [error at 20]
snd_rawmidi_transmit*
--------------------^
.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
Invalid C declaration: Expected end of definition. [error at 9]
copy_from/to_user
---------^
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../kernel-api/writing-an-alsa-driver.rst | 105 ++++++++----------
1 file changed, 47 insertions(+), 58 deletions(-)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index aa9d5ab183d2..85d6e9c643ef 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -194,7 +194,7 @@ The minimum flow for PCI soundcards is as follows:
- create ``remove`` callback.
-- create a :c:type:`struct pci_driver <pci_driver>` structure
+- create a struct pci_driver structure
containing the three pointers above.
- create an ``init`` function just calling the
@@ -487,7 +487,7 @@ The destructor, remove callback, simply releases the card instance. Then
the ALSA middle layer will release all the attached components
automatically.
-It would be typically just :c:func:`calling snd_card_free()`:
+It would be typically just calling :c:func:`snd_card_free()`:
::
@@ -560,16 +560,15 @@ return the card instance. The extra_size argument is used to allocate
card->private_data for the chip-specific data. Note that these data are
allocated by :c:func:`snd_card_new()`.
-The first argument, the pointer of struct :c:type:`struct device
-<device>`, specifies the parent device. For PCI devices, typically
-``&pci->`` is passed there.
+The first argument, the pointer of struct device, specifies the parent
+device. For PCI devices, typically ``&pci->`` is passed there.
Components
----------
After the card is created, you can attach the components (devices) to
the card instance. In an ALSA driver, a component is represented as a
-:c:type:`struct snd_device <snd_device>` object. A component
+struct snd_device object. A component
can be a PCM instance, a control interface, a raw MIDI interface, etc.
Each such instance has one component entry.
@@ -628,7 +627,7 @@ argument of :c:func:`snd_card_new()`, i.e.
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
sizeof(struct mychip), &card);
-:c:type:`struct mychip <mychip>` is the type of the chip record.
+struct mychip is the type of the chip record.
In return, the allocated record can be accessed as
@@ -890,7 +889,7 @@ functions. These resources must be released in the destructor
function (see below).
Now assume that the PCI device has an I/O port with 8 bytes and an
-interrupt. Then :c:type:`struct mychip <mychip>` will have the
+interrupt. Then struct mychip will have the
following fields:
::
@@ -1094,7 +1093,7 @@ PCI Entries
-----------
So far, so good. Let's finish the missing PCI stuff. At first, we need a
-:c:type:`struct pci_device_id <pci_device_id>` table for
+struct pci_device_id table for
this chipset. It's a table of PCI vendor/device ID number, and some
masks.
@@ -1110,19 +1109,17 @@ For example,
};
MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
-The first and second fields of the :c:type:`struct pci_device_id
-<pci_device_id>` structure are the vendor and device IDs. If you
-have no reason to filter the matching devices, you can leave the
-remaining fields as above. The last field of the :c:type:`struct
-pci_device_id <pci_device_id>` struct contains private data
-for this entry. You can specify any value here, for example, to define
-specific operations for supported device IDs. Such an example is found
-in the intel8x0 driver.
+The first and second fields of the struct pci_device_id are the vendor
+and device IDs. If you have no reason to filter the matching devices, you can
+leave the remaining fields as above. The last field of the
+struct pci_device_id contains private data for this entry. You can specify
+any value here, for example, to define specific operations for supported
+device IDs. Such an example is found in the intel8x0 driver.
The last entry of this list is the terminator. You must specify this
all-zero entry.
-Then, prepare the :c:type:`struct pci_driver <pci_driver>`
+Then, prepare the struct pci_driver
record:
::
@@ -1439,8 +1436,8 @@ corresponding argument.
If a chip supports multiple playbacks or captures, you can specify more
numbers, but they must be handled properly in open/close, etc.
callbacks. When you need to know which substream you are referring to,
-then it can be obtained from :c:type:`struct snd_pcm_substream
-<snd_pcm_substream>` data passed to each callback as follows:
+then it can be obtained from struct snd_pcm_substream data passed to each
+callback as follows:
::
@@ -1639,10 +1636,9 @@ In the sections below, important records are explained.
Hardware Description
~~~~~~~~~~~~~~~~~~~~
-The hardware descriptor (:c:type:`struct snd_pcm_hardware
-<snd_pcm_hardware>`) contains the definitions of the fundamental
-hardware configuration. Above all, you'll need to define this in the
-`PCM open callback`_. Note that the runtime instance holds the copy of
+The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
+the fundamental hardware configuration. Above all, you'll need to define this
+in the `PCM open callback`_. Note that the runtime instance holds the copy of
the descriptor, not the pointer to the existing descriptor. That is,
in the open callback, you can modify the copied descriptor
(``runtime->hw``) as you need. For example, if the maximum number of
@@ -1800,14 +1796,13 @@ Running Status
~~~~~~~~~~~~~~
The running status can be referred via ``runtime->status``. This is
-the pointer to the :c:type:`struct snd_pcm_mmap_status
-<snd_pcm_mmap_status>` record. For example, you can get the current
+the pointer to the struct snd_pcm_mmap_status record.
+For example, you can get the current
DMA hardware pointer via ``runtime->status->hw_ptr``.
The DMA application pointer can be referred via ``runtime->control``,
-which points to the :c:type:`struct snd_pcm_mmap_control
-<snd_pcm_mmap_control>` record. However, accessing directly to
-this value is not recommended.
+which points to the struct snd_pcm_mmap_control record.
+However, accessing directly to this value is not recommended.
Private Data
~~~~~~~~~~~~
@@ -1843,8 +1838,8 @@ error number such as ``-EINVAL``. To choose an appropriate error
number, it is advised to check what value other parts of the kernel
return when the same kind of request fails.
-The callback function takes at least the argument with :c:type:`struct
-snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
+The callback function takes at least the argument with
+struct snd_pcm_substream pointer. To retrieve the chip
record from the given substream instance, you can use the following
macro.
@@ -2313,10 +2308,10 @@ non-atomic contexts. For example, the function
:c:func:`snd_pcm_period_elapsed()` is called typically from the
interrupt handler. But, if you set up the driver to use a threaded
interrupt handler, this call can be in non-atomic context, too. In such
-a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
-<snd_pcm>` object after creating it. When this flag is set, mutex
-and rwsem are used internally in the PCM core instead of spin and
-rwlocks, so that you can call all PCM functions safely in a non-atomic
+a case, you can set ``nonatomic`` filed of struct snd_pcm object
+after creating it. When this flag is set, mutex and rwsem are used internally
+in the PCM core instead of spin and rwlocks, so that you can call all PCM
+functions safely in a non-atomic
context.
Constraints
@@ -2357,8 +2352,7 @@ There are many different constraints. Look at ``sound/pcm.h`` for a
complete list. You can even define your own constraint rules. For
example, let's suppose my_chip can manage a substream of 1 channel if
and only if the format is ``S16_LE``, otherwise it supports any format
-specified in the :c:type:`struct snd_pcm_hardware
-<snd_pcm_hardware>` structure (or in any other
+specified in struct snd_pcm_hardware> (or in any other
constraint_list). You can build a rule like this:
::
@@ -2467,7 +2461,7 @@ Definition of Controls
To create a new control, you need to define the following three
callbacks: ``info``, ``get`` and ``put``. Then, define a
-:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
+struct snd_kcontrol_new record, such as:
::
@@ -2602,8 +2596,8 @@ info callback
~~~~~~~~~~~~~
The ``info`` callback is used to get detailed information on this
-control. This must store the values of the given :c:type:`struct
-snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
+control. This must store the values of the given
+struct snd_ctl_elem_info object. For example,
for a boolean control with a single element:
::
@@ -2774,13 +2768,11 @@ In the simplest way, you can do like this:
if (err < 0)
return err;
-where ``my_control`` is the :c:type:`struct snd_kcontrol_new
-<snd_kcontrol_new>` object defined above, and chip is the object
-pointer to be passed to kcontrol->private_data which can be referred
-to in callbacks.
+where ``my_control`` is the struct snd_kcontrol_new object defined above,
+and chip is the object pointer to be passed to kcontrol->private_data which
+can be referred to in callbacks.
-:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
-snd_kcontrol <snd_kcontrol>` instance, and
+:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
:c:func:`snd_ctl_add()` assigns the given control component to the
card.
@@ -2797,10 +2789,9 @@ can call :c:func:`snd_ctl_notify()`. For example,
This function takes the card pointer, the event-mask, and the control id
pointer for the notification. The event-mask specifies the types of
notification, for example, in the above example, the change of control
-values is notified. The id pointer is the pointer of :c:type:`struct
-snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
-find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
-interrupts.
+values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
+to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
+for hardware volume interrupts.
Metadata
--------
@@ -2915,9 +2906,8 @@ with an ``ac97_bus_ops_t`` record with callback functions.
The bus record is shared among all belonging ac97 instances.
-And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
-snd_ac97_template <snd_ac97_template>` record together with
-the bus pointer created above.
+And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
+record together with the bus pointer created above.
::
@@ -3118,11 +3108,10 @@ devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
Usually, the port address corresponds to the command port and port + 1
corresponds to the data port. If not, you may change the ``cport``
-field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
-However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
+field of struct snd_mpu401 manually afterward.
+However, struct snd_mpu401 pointer is
not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
-need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
-<snd_mpu401>` explicitly,
+need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
::
@@ -3772,7 +3761,7 @@ For creating the SG-buffer handler, call
:c:func:`snd_pcm_set_managed_buffer_all()` with
``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
pre-allocator. You need to pass ``&pci->dev``, where pci is
-the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
+the struct pci_dev pointer of the chip as
well.
::
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
2020-09-30 13:25 ` Mauro Carvalho Chehab
@ 2020-09-30 14:59 ` Takashi Iwai
-1 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 14:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Arnd Bergmann,
Jaroslav Kysela, Julia Lawall, Takashi Iwai, alsa-devel,
linux-kernel
On Wed, 30 Sep 2020 15:25:00 +0200,
Mauro Carvalho Chehab wrote:
>
> the :c:type shouldn't be used with structs with Sphinx 3,
> as the C domain there uses .. c:struct for structs.
>
> As we have the automarkup extension, let's just get rid of
> all :c:type as a hole, as those will be automagically
whole?
> marked as such.
>
> This solves a bunch of warnings with Sphinx 3, like those:
>
> .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
> Invalid C declaration: Expected end of definition. [error at 8]
> calling snd_card_free
> --------^
> .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
> Invalid C declaration: Expected end of definition. [error at 20]
> snd_rawmidi_transmit*
> --------------------^
> .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
> Invalid C declaration: Expected end of definition. [error at 9]
> copy_from/to_user
> ---------^
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
@ 2020-09-30 14:59 ` Takashi Iwai
0 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 14:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: alsa-devel, Arnd Bergmann, Jonathan Corbet, linux-kernel,
Linux Doc Mailing List, Takashi Iwai, Julia Lawall
On Wed, 30 Sep 2020 15:25:00 +0200,
Mauro Carvalho Chehab wrote:
>
> the :c:type shouldn't be used with structs with Sphinx 3,
> as the C domain there uses .. c:struct for structs.
>
> As we have the automarkup extension, let's just get rid of
> all :c:type as a hole, as those will be automagically
whole?
> marked as such.
>
> This solves a bunch of warnings with Sphinx 3, like those:
>
> .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
> Invalid C declaration: Expected end of definition. [error at 8]
> calling snd_card_free
> --------^
> .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
> Invalid C declaration: Expected end of definition. [error at 20]
> snd_rawmidi_transmit*
> --------------------^
> .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
> Invalid C declaration: Expected end of definition. [error at 9]
> copy_from/to_user
> ---------^
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 38/52] docs: block: typec_bus.rst: get rid of :c:type
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (36 preceding siblings ...)
2020-09-30 13:25 ` Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 16:48 ` André Almeida
2020-09-30 13:25 ` Mauro Carvalho Chehab
` (14 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, André Almeida, Jens Axboe,
Randy Dunlap, linux-kernel
The :c:type macros are not used properly there, as reported
by Sphinx 3:
./Documentation/block/blk-mq.rst:112: WARNING: Unparseable C cross-reference: 'hctx->dispatch'
Invalid C declaration: Expected end of definition. [error at 4]
hctx->dispatch
----^
Also, they won't be generating any cross references.
So, replace them by a literal markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/block/blk-mq.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
index 86a632af02b0..a980d23af48c 100644
--- a/Documentation/block/blk-mq.rst
+++ b/Documentation/block/blk-mq.rst
@@ -110,9 +110,9 @@ block layer removes requests from the associated software queues and tries to
dispatch to the hardware.
If it's not possible to send the requests directly to hardware, they will be
-added to a linked list (:c:type:`hctx->dispatch`) of requests. Then,
+added to a linked list (``hctx->dispatch``) of requests. Then,
next time the block layer runs a queue, it will send the requests laying at the
-:c:type:`dispatch` list first, to ensure a fairness dispatch with those
+``dispatch`` list first, to ensure a fairness dispatch with those
requests that were ready to be sent first. The number of hardware queues
depends on the number of hardware contexts supported by the hardware and its
device driver, but it will not be more than the number of cores of the system.
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 38/52] docs: block: typec_bus.rst: get rid of :c:type
2020-09-30 13:25 ` [PATCH v4 38/52] docs: block: typec_bus.rst: " Mauro Carvalho Chehab
@ 2020-09-30 16:48 ` André Almeida
0 siblings, 0 replies; 103+ messages in thread
From: André Almeida @ 2020-09-30 16:48 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
Cc: Jens Axboe, Randy Dunlap, linux-kernel
On 9/30/20 10:25 AM, Mauro Carvalho Chehab wrote:
> The :c:type macros are not used properly there, as reported
> by Sphinx 3:
>
> ./Documentation/block/blk-mq.rst:112: WARNING: Unparseable C cross-reference: 'hctx->dispatch'
> Invalid C declaration: Expected end of definition. [error at 4]
> hctx->dispatch
> ----^
>
> Also, they won't be generating any cross references.
>
> So, replace them by a literal markup.
Your commit message says "docs: block: typec_bus.rst: ...", but the name
of this file is "blk-mq.rst".
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
After solving the issue above:
Reviewed-by: André Almeida <andrealmeid@collabora.com>
> ---
> Documentation/block/blk-mq.rst | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
> index 86a632af02b0..a980d23af48c 100644
> --- a/Documentation/block/blk-mq.rst
> +++ b/Documentation/block/blk-mq.rst
> @@ -110,9 +110,9 @@ block layer removes requests from the associated software queues and tries to
> dispatch to the hardware.
>
> If it's not possible to send the requests directly to hardware, they will be
> -added to a linked list (:c:type:`hctx->dispatch`) of requests. Then,
> +added to a linked list (``hctx->dispatch``) of requests. Then,
> next time the block layer runs a queue, it will send the requests laying at the
> -:c:type:`dispatch` list first, to ensure a fairness dispatch with those
> +``dispatch`` list first, to ensure a fairness dispatch with those
> requests that were ready to be sent first. The number of hardware queues
> depends on the number of hardware contexts supported by the hardware and its
> device driver, but it will not be more than the number of cores of the system.
>
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Arnd Bergmann, Jaroslav Kysela,
Julia Lawall, Takashi Iwai, alsa-devel, linux-kernel
Some such markups are invalid, as reported by Sphinx:
./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
Invalid C declaration: Expected end of definition. [error at 20]
snd_rawmidi_transmit*
--------------------^
./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
Invalid C declaration: Expected end of definition. [error at 9]
copy_from/to_user
---------^
The first case seems to be better replaced by a literal.
For the second one, let's generate cross-references, by
spliting it in two.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 85d6e9c643ef..73bbd59afc33 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -3315,8 +3315,7 @@ data and removes them from the buffer at once:
}
If you know beforehand how many bytes you can accept, you can use a
-buffer size greater than one with the
-:c:func:`snd_rawmidi_transmit\*()` functions.
+buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
The ``trigger`` callback must not sleep. If the hardware FIFO is full
before the substream buffer has been emptied, you have to continue
@@ -3916,7 +3915,7 @@ the maximum size of the proc file access.
The read/write callbacks of raw mode are more direct than the text mode.
You need to use a low-level I/O functions such as
-:c:func:`copy_from/to_user()` to transfer the data.
+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
::
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: alsa-devel, Arnd Bergmann, Mauro Carvalho Chehab, linux-kernel,
Takashi Iwai, Julia Lawall
Some such markups are invalid, as reported by Sphinx:
./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
Invalid C declaration: Expected end of definition. [error at 20]
snd_rawmidi_transmit*
--------------------^
./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
Invalid C declaration: Expected end of definition. [error at 9]
copy_from/to_user
---------^
The first case seems to be better replaced by a literal.
For the second one, let's generate cross-references, by
spliting it in two.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 85d6e9c643ef..73bbd59afc33 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -3315,8 +3315,7 @@ data and removes them from the buffer at once:
}
If you know beforehand how many bytes you can accept, you can use a
-buffer size greater than one with the
-:c:func:`snd_rawmidi_transmit\*()` functions.
+buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
The ``trigger`` callback must not sleep. If the hardware FIFO is full
before the substream buffer has been emptied, you have to continue
@@ -3916,7 +3915,7 @@ the maximum size of the proc file access.
The read/write callbacks of raw mode are more direct than the text mode.
You need to use a low-level I/O functions such as
-:c:func:`copy_from/to_user()` to transfer the data.
+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
::
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread
* Re: [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
2020-09-30 13:25 ` Mauro Carvalho Chehab
@ 2020-09-30 14:58 ` Takashi Iwai
-1 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 14:58 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Arnd Bergmann,
Jaroslav Kysela, Julia Lawall, Takashi Iwai, alsa-devel,
linux-kernel
On Wed, 30 Sep 2020 15:25:02 +0200,
Mauro Carvalho Chehab wrote:
>
> Some such markups are invalid, as reported by Sphinx:
>
> ./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
> Invalid C declaration: Expected end of definition. [error at 20]
> snd_rawmidi_transmit*
> --------------------^
> ./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
> Invalid C declaration: Expected end of definition. [error at 9]
> copy_from/to_user
> ---------^
>
> The first case seems to be better replaced by a literal.
>
> For the second one, let's generate cross-references, by
> spliting it in two.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* Re: [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
@ 2020-09-30 14:58 ` Takashi Iwai
0 siblings, 0 replies; 103+ messages in thread
From: Takashi Iwai @ 2020-09-30 14:58 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: alsa-devel, Arnd Bergmann, Jonathan Corbet, linux-kernel,
Linux Doc Mailing List, Takashi Iwai, Julia Lawall
On Wed, 30 Sep 2020 15:25:02 +0200,
Mauro Carvalho Chehab wrote:
>
> Some such markups are invalid, as reported by Sphinx:
>
> ./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
> Invalid C declaration: Expected end of definition. [error at 20]
> snd_rawmidi_transmit*
> --------------------^
> ./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
> Invalid C declaration: Expected end of definition. [error at 9]
> copy_from/to_user
> ---------^
>
> The first case seems to be better replaced by a literal.
>
> For the second one, let's generate cross-references, by
> spliting it in two.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 40/52] docs: fpga: replace :c:member: macros
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (38 preceding siblings ...)
2020-09-30 13:25 ` Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 23:46 ` Moritz Fischer
2020-09-30 13:25 ` [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages Mauro Carvalho Chehab
` (12 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Moritz Fischer, Tom Rix, linux-fpga, linux-kernel
Those macros are not doing the right thing with Sphinx 3,
causing parse errors:
./Documentation/driver-api/fpga/fpga-mgr.rst:104: WARNING: Unparseable C cross-reference: 'fpga_manager->state'
Invalid C declaration: Expected end of definition. [error at 12]
fpga_manager->state
------------^
./Documentation/driver-api/fpga/fpga-programming.rst:18: WARNING: Unparseable C cross-reference: 'fpga_region->info'
Invalid C declaration: Expected end of definition. [error at 11]
fpga_region->info
-----------^
./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->bridge_list'
Invalid C declaration: Expected end of definition. [error at 11]
fpga_region->bridge_list
-----------^
./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->get_bridges'
Invalid C declaration: Expected end of definition. [error at 11]
fpga_region->get_bridges
-----------^
Replace them by :c:expr:, with does what's desired.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/fpga/fpga-mgr.rst | 2 +-
Documentation/driver-api/fpga/fpga-programming.rst | 2 +-
Documentation/driver-api/fpga/fpga-region.rst | 4 ++--
3 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
index 22f7885b32c9..917ee22db429 100644
--- a/Documentation/driver-api/fpga/fpga-mgr.rst
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -101,7 +101,7 @@ in state.
API for implementing a new FPGA Manager driver
----------------------------------------------
-* ``fpga_mgr_states`` — Values for :c:member:`fpga_manager->state`.
+* ``fpga_mgr_states`` — Values for :c:expr:`fpga_manager->state`.
* struct fpga_manager — the FPGA manager struct
* struct fpga_manager_ops — Low level FPGA manager driver ops
* devm_fpga_mgr_create() — Allocate and init a manager struct
diff --git a/Documentation/driver-api/fpga/fpga-programming.rst b/Documentation/driver-api/fpga/fpga-programming.rst
index f487ad64dfb9..002392dab04f 100644
--- a/Documentation/driver-api/fpga/fpga-programming.rst
+++ b/Documentation/driver-api/fpga/fpga-programming.rst
@@ -15,7 +15,7 @@ the FPGA manager and bridges. It will:
* lock the mutex of the region's FPGA manager
* build a list of FPGA bridges if a method has been specified to do so
* disable the bridges
- * program the FPGA using info passed in :c:member:`fpga_region->info`.
+ * program the FPGA using info passed in :c:expr:`fpga_region->info`.
* re-enable the bridges
* release the locks
diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
index 3e52be7e2968..363a8171ab0a 100644
--- a/Documentation/driver-api/fpga/fpga-region.rst
+++ b/Documentation/driver-api/fpga/fpga-region.rst
@@ -61,9 +61,9 @@ during the region's probe function.
The FPGA region will need to specify which bridges to control while programming
the FPGA. The region driver can build a list of bridges during probe time
-(:c:member:`fpga_region->bridge_list`) or it can have a function that creates
+(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
the list of bridges to program just before programming
-(:c:member:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
+(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
following APIs to handle building or tearing down that list.
* fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 40/52] docs: fpga: replace :c:member: macros
2020-09-30 13:25 ` [PATCH v4 40/52] docs: fpga: replace :c:member: macros Mauro Carvalho Chehab
@ 2020-09-30 23:46 ` Moritz Fischer
0 siblings, 0 replies; 103+ messages in thread
From: Moritz Fischer @ 2020-09-30 23:46 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Moritz Fischer, Tom Rix,
linux-fpga, linux-kernel
On Wed, Sep 30, 2020 at 03:25:03PM +0200, Mauro Carvalho Chehab wrote:
> Those macros are not doing the right thing with Sphinx 3,
> causing parse errors:
>
> ./Documentation/driver-api/fpga/fpga-mgr.rst:104: WARNING: Unparseable C cross-reference: 'fpga_manager->state'
> Invalid C declaration: Expected end of definition. [error at 12]
> fpga_manager->state
> ------------^
> ./Documentation/driver-api/fpga/fpga-programming.rst:18: WARNING: Unparseable C cross-reference: 'fpga_region->info'
> Invalid C declaration: Expected end of definition. [error at 11]
> fpga_region->info
> -----------^
> ./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->bridge_list'
> Invalid C declaration: Expected end of definition. [error at 11]
> fpga_region->bridge_list
> -----------^
> ./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->get_bridges'
> Invalid C declaration: Expected end of definition. [error at 11]
> fpga_region->get_bridges
> -----------^
>
> Replace them by :c:expr:, with does what's desired.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Moritz Fischer <mdf@kernel.org>
> ---
> Documentation/driver-api/fpga/fpga-mgr.rst | 2 +-
> Documentation/driver-api/fpga/fpga-programming.rst | 2 +-
> Documentation/driver-api/fpga/fpga-region.rst | 4 ++--
> 3 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
> index 22f7885b32c9..917ee22db429 100644
> --- a/Documentation/driver-api/fpga/fpga-mgr.rst
> +++ b/Documentation/driver-api/fpga/fpga-mgr.rst
> @@ -101,7 +101,7 @@ in state.
> API for implementing a new FPGA Manager driver
> ----------------------------------------------
>
> -* ``fpga_mgr_states`` — Values for :c:member:`fpga_manager->state`.
> +* ``fpga_mgr_states`` — Values for :c:expr:`fpga_manager->state`.
> * struct fpga_manager — the FPGA manager struct
> * struct fpga_manager_ops — Low level FPGA manager driver ops
> * devm_fpga_mgr_create() — Allocate and init a manager struct
> diff --git a/Documentation/driver-api/fpga/fpga-programming.rst b/Documentation/driver-api/fpga/fpga-programming.rst
> index f487ad64dfb9..002392dab04f 100644
> --- a/Documentation/driver-api/fpga/fpga-programming.rst
> +++ b/Documentation/driver-api/fpga/fpga-programming.rst
> @@ -15,7 +15,7 @@ the FPGA manager and bridges. It will:
> * lock the mutex of the region's FPGA manager
> * build a list of FPGA bridges if a method has been specified to do so
> * disable the bridges
> - * program the FPGA using info passed in :c:member:`fpga_region->info`.
> + * program the FPGA using info passed in :c:expr:`fpga_region->info`.
> * re-enable the bridges
> * release the locks
>
> diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
> index 3e52be7e2968..363a8171ab0a 100644
> --- a/Documentation/driver-api/fpga/fpga-region.rst
> +++ b/Documentation/driver-api/fpga/fpga-region.rst
> @@ -61,9 +61,9 @@ during the region's probe function.
>
> The FPGA region will need to specify which bridges to control while programming
> the FPGA. The region driver can build a list of bridges during probe time
> -(:c:member:`fpga_region->bridge_list`) or it can have a function that creates
> +(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
> the list of bridges to program just before programming
> -(:c:member:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
> +(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
> following APIs to handle building or tearing down that list.
>
> * fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
> --
> 2.26.2
>
Thanks!
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (39 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 40/52] docs: fpga: replace :c:member: macros Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-10-01 11:29 ` Daniel Thompson
2020-09-30 13:25 ` [PATCH v4 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag Mauro Carvalho Chehab
` (11 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Daniel Thompson, Douglas Anderson,
Jason Wessel, kgdb-bugreport, linux-kernel
Which Sphinx 3, :c:type: can't be used anymore for structs,
as this should be used only for typedefs.
Rely on automarkup.py for struct references.
This file has an special case, though: it uses the tag also
to point to an array. Let's use, instead, :c:expr: for such
purpose, as it should do the right thing.
This should fix this warning:
./Documentation/dev-tools/kgdb.rst:875: WARNING: Unparseable C cross-reference: 'kdb_poll_funcs[]'
Invalid C declaration: Expected end of definition. [error at 14]
kdb_poll_funcs[]
--------------^
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/dev-tools/kgdb.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
index c908ef4d3f04..77b688e6a254 100644
--- a/Documentation/dev-tools/kgdb.rst
+++ b/Documentation/dev-tools/kgdb.rst
@@ -726,7 +726,7 @@ The kernel debugger is organized into a number of components:
- contains an arch-specific trap catcher which invokes
kgdb_handle_exception() to start kgdb about doing its work
- - translation to and from gdb specific packet format to :c:type:`pt_regs`
+ - translation to and from gdb specific packet format to struct pt_regs
- Registration and unregistration of architecture specific trap
hooks
@@ -846,7 +846,7 @@ invokes a callback in the serial core which in turn uses the callback in
the UART driver.
When using kgdboc with a UART, the UART driver must implement two
-callbacks in the :c:type:`struct uart_ops <uart_ops>`.
+callbacks in the struct uart_ops.
Example from ``drivers/8250.c``::
@@ -875,7 +875,7 @@ kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
The core polled keyboard driver for PS/2 type keyboards is in
``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
when kgdboc populates the callback in the array called
-:c:type:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
+:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
function which polls hardware for single character input.
kgdboc and kms
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages
2020-09-30 13:25 ` [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages Mauro Carvalho Chehab
@ 2020-10-01 11:29 ` Daniel Thompson
0 siblings, 0 replies; 103+ messages in thread
From: Daniel Thompson @ 2020-10-01 11:29 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Douglas Anderson,
Jason Wessel, kgdb-bugreport, linux-kernel
On Wed, Sep 30, 2020 at 03:25:04PM +0200, Mauro Carvalho Chehab wrote:
> Which Sphinx 3, :c:type: can't be used anymore for structs,
> as this should be used only for typedefs.
>
> Rely on automarkup.py for struct references.
>
> This file has an special case, though: it uses the tag also
> to point to an array. Let's use, instead, :c:expr: for such
> purpose, as it should do the right thing.
>
> This should fix this warning:
>
> ./Documentation/dev-tools/kgdb.rst:875: WARNING: Unparseable C cross-reference: 'kdb_poll_funcs[]'
> Invalid C declaration: Expected end of definition. [error at 14]
> kdb_poll_funcs[]
> --------------^
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Daniel Thompson <daniel.thompson@linaro.org>
Daniel.
> ---
> Documentation/dev-tools/kgdb.rst | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
> index c908ef4d3f04..77b688e6a254 100644
> --- a/Documentation/dev-tools/kgdb.rst
> +++ b/Documentation/dev-tools/kgdb.rst
> @@ -726,7 +726,7 @@ The kernel debugger is organized into a number of components:
> - contains an arch-specific trap catcher which invokes
> kgdb_handle_exception() to start kgdb about doing its work
>
> - - translation to and from gdb specific packet format to :c:type:`pt_regs`
> + - translation to and from gdb specific packet format to struct pt_regs
>
> - Registration and unregistration of architecture specific trap
> hooks
> @@ -846,7 +846,7 @@ invokes a callback in the serial core which in turn uses the callback in
> the UART driver.
>
> When using kgdboc with a UART, the UART driver must implement two
> -callbacks in the :c:type:`struct uart_ops <uart_ops>`.
> +callbacks in the struct uart_ops.
> Example from ``drivers/8250.c``::
>
>
> @@ -875,7 +875,7 @@ kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
> The core polled keyboard driver for PS/2 type keyboards is in
> ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
> when kgdboc populates the callback in the array called
> -:c:type:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
> +:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
> function which polls hardware for single character input.
>
> kgdboc and kms
> --
> 2.26.2
>
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (40 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 43/52] docs: infrastructure.rst: don't include firmware kernel-doc Mauro Carvalho Chehab
` (10 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Martin K. Petersen, Jens Axboe,
Jiri Slaby, linux-kernel
The usage of :c:type: to reference to a struct member is wrong,
as pointed by Sphinx 3:
./Documentation/driver-api/libata.rst:511: WARNING: Unparseable C cross-reference: 'qc->complete_fn'
Invalid C declaration: Expected end of definition. [error at 2]
qc->complete_fn
--^
Instead, let's use :c:expr: for such purpose.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/libata.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst
index e2f87b82b074..d477e296bda5 100644
--- a/Documentation/driver-api/libata.rst
+++ b/Documentation/driver-api/libata.rst
@@ -508,7 +508,7 @@ also complete commands.
2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
-3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the
+3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
callback is not zero. Completion is short circuited and
:c:func:`ata_qc_complete` returns.
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 43/52] docs: infrastructure.rst: don't include firmware kernel-doc
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (41 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` Mauro Carvalho Chehab
` (9 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Those are already documented at:
Documentation/driver-api/firmware/request_firmware.rst
Including it twice is causing lots of warnings:
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'request_firmware'.
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'firmware_request_nowarn'.
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'request_firmware_direct'.
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'firmware_request_platform'.
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'firmware_request_cache'.
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'request_firmware_into_buf'.
./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
Declaration is 'request_firmware_nowait'.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/infrastructure.rst | 3 ---
1 file changed, 3 deletions(-)
diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index 06d98c4526df..e38d79be4e16 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -28,9 +28,6 @@ Device Drivers Base
.. kernel-doc:: drivers/base/node.c
:internal:
-.. kernel-doc:: drivers/base/firmware_loader/main.c
- :export:
-
.. kernel-doc:: drivers/base/transport_class.c
:export:
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 44/52] docs: gpu: i915.rst: Fix several C duplication warnings
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
` (50 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Daniel Vetter, David Airlie, Jani Nikula,
Joonas Lahtinen, Maarten Lankhorst, Maxime Ripard, Rodrigo Vivi,
Thomas Zimmermann, dri-devel, intel-gfx, linux-kernel
As reported by Sphinx:
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_wait_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_poll_wait'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_enable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_disable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_enable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_disable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_destroy_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_release'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'read_properties_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_register'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_unregister'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_add_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_remove_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_fini'.
With Sphinx 3, C declarations can't be duplicated anymore,
so let's exclude those from the other internals found on
i915_perf.c file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
1 file changed, 25 insertions(+), 4 deletions(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 33cc6ddf8f64..cff1f154b473 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_poll_wait
-All i915 Perf Internals
------------------------
+Other i915 Perf Internals
+-------------------------
-This section simply includes all currently documented i915 perf internals, in
-no particular order, but may include some more minor utilities or platform
+This section simply includes all other currently documented i915 perf internals,
+in no particular order, but may include some more minor utilities or platform
specific details than found in the more high-level sections.
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:internal:
+ :no-identifiers:
+ i915_perf_init
+ i915_perf_fini
+ i915_perf_register
+ i915_perf_unregister
+ i915_perf_open_ioctl
+ i915_perf_release
+ i915_perf_add_config_ioctl
+ i915_perf_remove_config_ioctl
+ read_properties_unlocked
+ i915_perf_open_ioctl_locked
+ i915_perf_destroy_locked
+ i915_perf_read i915_perf_ioctl
+ i915_perf_enable_locked
+ i915_perf_disable_locked
+ i915_perf_poll i915_perf_poll_locked
+ i915_oa_stream_init i915_oa_read
+ i915_oa_stream_enable
+ i915_oa_stream_disable
+ i915_oa_wait_unlocked
+ i915_oa_poll_wait
Style
=====
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [Intel-gfx] [PATCH v4 44/52] docs: gpu: i915.rst: Fix several C duplication warnings
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Thomas Zimmermann, Mauro Carvalho Chehab, dri-devel,
linux-kernel, David Airlie, Maxime Ripard, intel-gfx
As reported by Sphinx:
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_wait_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_poll_wait'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_enable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_disable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_enable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_disable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_destroy_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_release'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'read_properties_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_register'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_unregister'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_add_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_remove_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_fini'.
With Sphinx 3, C declarations can't be duplicated anymore,
so let's exclude those from the other internals found on
i915_perf.c file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
1 file changed, 25 insertions(+), 4 deletions(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 33cc6ddf8f64..cff1f154b473 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_poll_wait
-All i915 Perf Internals
------------------------
+Other i915 Perf Internals
+-------------------------
-This section simply includes all currently documented i915 perf internals, in
-no particular order, but may include some more minor utilities or platform
+This section simply includes all other currently documented i915 perf internals,
+in no particular order, but may include some more minor utilities or platform
specific details than found in the more high-level sections.
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:internal:
+ :no-identifiers:
+ i915_perf_init
+ i915_perf_fini
+ i915_perf_register
+ i915_perf_unregister
+ i915_perf_open_ioctl
+ i915_perf_release
+ i915_perf_add_config_ioctl
+ i915_perf_remove_config_ioctl
+ read_properties_unlocked
+ i915_perf_open_ioctl_locked
+ i915_perf_destroy_locked
+ i915_perf_read i915_perf_ioctl
+ i915_perf_enable_locked
+ i915_perf_disable_locked
+ i915_perf_poll i915_perf_poll_locked
+ i915_oa_stream_init i915_oa_read
+ i915_oa_stream_enable
+ i915_oa_stream_disable
+ i915_oa_wait_unlocked
+ i915_oa_poll_wait
Style
=====
--
2.26.2
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 44/52] docs: gpu: i915.rst: Fix several C duplication warnings
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Thomas Zimmermann, Mauro Carvalho Chehab, dri-devel,
linux-kernel, David Airlie, Rodrigo Vivi, intel-gfx
As reported by Sphinx:
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_wait_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_poll_wait'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_enable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_disable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_enable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_disable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_destroy_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_release'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'read_properties_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_register'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_unregister'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_add_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_remove_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_fini'.
With Sphinx 3, C declarations can't be duplicated anymore,
so let's exclude those from the other internals found on
i915_perf.c file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
1 file changed, 25 insertions(+), 4 deletions(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 33cc6ddf8f64..cff1f154b473 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_poll_wait
-All i915 Perf Internals
------------------------
+Other i915 Perf Internals
+-------------------------
-This section simply includes all currently documented i915 perf internals, in
-no particular order, but may include some more minor utilities or platform
+This section simply includes all other currently documented i915 perf internals,
+in no particular order, but may include some more minor utilities or platform
specific details than found in the more high-level sections.
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:internal:
+ :no-identifiers:
+ i915_perf_init
+ i915_perf_fini
+ i915_perf_register
+ i915_perf_unregister
+ i915_perf_open_ioctl
+ i915_perf_release
+ i915_perf_add_config_ioctl
+ i915_perf_remove_config_ioctl
+ read_properties_unlocked
+ i915_perf_open_ioctl_locked
+ i915_perf_destroy_locked
+ i915_perf_read i915_perf_ioctl
+ i915_perf_enable_locked
+ i915_perf_disable_locked
+ i915_perf_poll i915_perf_poll_locked
+ i915_oa_stream_init i915_oa_read
+ i915_oa_stream_enable
+ i915_oa_stream_disable
+ i915_oa_wait_unlocked
+ i915_oa_poll_wait
Style
=====
--
2.26.2
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 103+ messages in thread
* [PATCH v4 45/52] docs: devices.rst: fix a C reference markup
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (43 preceding siblings ...)
2020-09-30 13:25 ` Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup Mauro Carvalho Chehab
` (7 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Rafael J. Wysocki, Alan Stern,
Bjorn Helgaas, Jeff Kirsher, linux-kernel
The C domain parser of Sphinx3 expects just function names
for :c:func: markups:
./Documentation/driver-api/pm/devices.rst:413: WARNING: Unparseable C cross-reference: 'device_may_wakeup(dev)'
Invalid C declaration: Expected end of definition. [error at 17]
device_may_wakeup(dev)
-----------------^
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/pm/devices.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 4bda8a21f5d1..6b3bfd29fd84 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -410,7 +410,7 @@ On many platforms they will gate off one or more clock sources; sometimes they
will also switch off power supplies or reduce voltages. [Drivers supporting
runtime PM may already have performed some or all of these steps.]
-If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be
+If :c:func:`device_may_wakeup()` returns ``true``, the device should be
prepared for generating hardware wakeup signals to trigger a system wakeup event
when the system is in the sleep state. For example, :c:func:`enable_irq_wake()`
might identify GPIO signals hooked up to a switch or other external hardware,
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (44 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 45/52] docs: devices.rst: fix a C reference markup Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-10-01 12:05 ` Federico Vaga
2020-09-30 13:25 ` [PATCH v4 47/52] docs: mei.rst: fix a C expression markup Mauro Carvalho Chehab
` (6 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Federico Vaga, Lukas Bulwahn, linux-kernel
There's a missing "`", causing this warning:
./Documentation/translations/it_IT/kernel-hacking/hacking.rst:404: WARNING: Unparseable C cross-reference: 'cpu_to_be32p(), che prende un puntatore\nad un tipo, e ritorna il valore convertito. L\'altra variante per\nla famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s'
Invalid C declaration: Expected end of definition. [error at 14]
cpu_to_be32p(), che prende un puntatore
ad un tipo, e ritorna il valore convertito. L'altra variante per
la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s
--------------^
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/translations/it_IT/kernel-hacking/hacking.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
index 6aab27a8d323..3d30b69f1ec1 100644
--- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
@@ -402,7 +402,7 @@ il valore convertito. Tutte le varianti supportano anche il processo inverso:
:c:func:`be32_to_cpu()`, eccetera.
Queste funzioni hanno principalmente due varianti: la variante per
-puntatori, come :c:func:`cpu_to_be32p(), che prende un puntatore
+puntatori, come :c:func:`cpu_to_be32p()`, che prende un puntatore
ad un tipo, e ritorna il valore convertito. L'altra variante per
la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s()`,
che convertono il valore puntato da un puntatore, e ritornano void.
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup
2020-09-30 13:25 ` [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup Mauro Carvalho Chehab
@ 2020-10-01 12:05 ` Federico Vaga
0 siblings, 0 replies; 103+ messages in thread
From: Federico Vaga @ 2020-10-01 12:05 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Lukas Bulwahn, linux-kernel
On 2020-09-30 15:25, Mauro Carvalho Chehab wrote:
> There's a missing "`", causing this warning:
> ./Documentation/translations/it_IT/kernel-hacking/hacking.rst:404:
> WARNING: Unparseable C cross-reference: 'cpu_to_be32p(), che prende un
> puntatore\nad un tipo, e ritorna il valore convertito. L\'altra
> variante per\nla famiglia di conversioni "in-situ", come
> :c:func:`cpu_to_be32s'
> Invalid C declaration: Expected end of definition. [error at 14]
> cpu_to_be32p(), che prende un puntatore
> ad un tipo, e ritorna il valore convertito. L'altra variante per
> la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s
> --------------^
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
> ---
> Documentation/translations/it_IT/kernel-hacking/hacking.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git
> a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
> b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
> index 6aab27a8d323..3d30b69f1ec1 100644
> --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
> +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
> @@ -402,7 +402,7 @@ il valore convertito. Tutte le varianti supportano
> anche il processo inverso:
> :c:func:`be32_to_cpu()`, eccetera.
>
> Queste funzioni hanno principalmente due varianti: la variante per
> -puntatori, come :c:func:`cpu_to_be32p(), che prende un puntatore
> +puntatori, come :c:func:`cpu_to_be32p()`, che prende un puntatore
> ad un tipo, e ritorna il valore convertito. L'altra variante per
> la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s()`,
> che convertono il valore puntato da un puntatore, e ritornano void.
--
Federico Vaga
http://www.federicovaga.it/
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 47/52] docs: mei.rst: fix a C expression markup
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (45 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 20:30 ` Winkler, Tomas
2020-09-30 13:25 ` [PATCH v4 48/52] docs: basics.rst: avoid duplicated C function declaration Mauro Carvalho Chehab
` (5 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Tomas Winkler, linux-kernel
Sphinx 3.x doesn't allow expressions using :c:func markup:
./Documentation/driver-api/mei/mei.rst:41: WARNING: Unparseable C cross-reference: 'close(int fd)'
Invalid C declaration: Expected end of definition. [error at 5]
close(int fd)
-----^
So, convert it into a :c:expr.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/mei/mei.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/driver-api/mei/mei.rst b/Documentation/driver-api/mei/mei.rst
index cea0b69ec216..4f2ced4ccdc6 100644
--- a/Documentation/driver-api/mei/mei.rst
+++ b/Documentation/driver-api/mei/mei.rst
@@ -38,7 +38,7 @@ Because some of the Intel ME features can change the system
configuration, the driver by default allows only a privileged
user to access it.
-The session is terminated calling :c:func:`close(int fd)`.
+The session is terminated calling :c:expr:`close(fd)`.
A code snippet for an application communicating with Intel AMTHI client:
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* RE: [PATCH v4 47/52] docs: mei.rst: fix a C expression markup
2020-09-30 13:25 ` [PATCH v4 47/52] docs: mei.rst: fix a C expression markup Mauro Carvalho Chehab
@ 2020-09-30 20:30 ` Winkler, Tomas
0 siblings, 0 replies; 103+ messages in thread
From: Winkler, Tomas @ 2020-09-30 20:30 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
Cc: linux-kernel
> Sphinx 3.x doesn't allow expressions using :c:func markup:
>
> ./Documentation/driver-api/mei/mei.rst:41: WARNING: Unparseable
> C cross-reference: 'close(int fd)'
> Invalid C declaration: Expected end of definition. [error at 5]
> close(int fd)
> -----^
>
> So, convert it into a :c:expr.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Tomas Winkler <tomas.winkler@intel.com>
> ---
> Documentation/driver-api/mei/mei.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/mei/mei.rst b/Documentation/driver-
> api/mei/mei.rst
> index cea0b69ec216..4f2ced4ccdc6 100644
> --- a/Documentation/driver-api/mei/mei.rst
> +++ b/Documentation/driver-api/mei/mei.rst
> @@ -38,7 +38,7 @@ Because some of the Intel ME features can change the
> system
> configuration, the driver by default allows only a privileged
> user to access it.
>
> -The session is terminated calling :c:func:`close(int fd)`.
> +The session is terminated calling :c:expr:`close(fd)`.
>
> A code snippet for an application communicating with Intel AMTHI client:
>
> --
> 2.26.2
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 48/52] docs: basics.rst: avoid duplicated C function declaration
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (46 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 47/52] docs: mei.rst: fix a C expression markup Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 49/52] workqueue: fix a kernel-doc warning Mauro Carvalho Chehab
` (4 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
pci_device_id is already documented at pci.rst:
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'PCI/pci'.
Declaration is 'pci_device_id'.
The kstrtol and kstrtoul are already at kernel-api:
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'kstrtoul'.
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'kstrtol'.
And the printk is already defined at printk-basics:
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/printk-basics'.
Declaration is 'printk'.
So, exclude those identifiers from basirs.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/basics.rst | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 63bbe3ed5e76..3e2dae954898 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -12,6 +12,8 @@ Driver device table
.. kernel-doc:: include/linux/mod_devicetable.h
:internal:
+ :no-identifiers: pci_device_id
+
Delaying, scheduling, and timer routines
----------------------------------------
@@ -96,9 +98,11 @@ Kernel utility functions
.. kernel-doc:: include/linux/kernel.h
:internal:
+ :no-identifiers: kstrtol kstrtoul
.. kernel-doc:: kernel/printk/printk.c
:export:
+ :no-identifiers: printk
.. kernel-doc:: kernel/panic.c
:export:
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 49/52] workqueue: fix a kernel-doc warning
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (47 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 48/52] docs: basics.rst: avoid duplicated C function declaration Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 15:57 ` Tejun Heo
2020-09-30 13:25 ` [PATCH v4 50/52] scripts: kernel-doc: try to use c:function if possible Mauro Carvalho Chehab
` (3 subsequent siblings)
52 siblings, 1 reply; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Lai Jiangshan, Tejun Heo, linux-kernel
As warned by Sphinx:
./Documentation/core-api/workqueue:400: ./kernel/workqueue.c:1218: WARNING: Unexpected indentation.
the return code table is currently not recognized, as it lacks
markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
kernel/workqueue.c | 3 +++
1 file changed, 3 insertions(+)
diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index c41c3c17b86a..e07d37396dfe 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -1212,11 +1212,14 @@ static void pwq_dec_nr_in_flight(struct pool_workqueue *pwq, int color)
* stable state - idle, on timer or on worklist.
*
* Return:
+ *
+ * ======== ================================================================
* 1 if @work was pending and we successfully stole PENDING
* 0 if @work was idle and we claimed PENDING
* -EAGAIN if PENDING couldn't be grabbed at the moment, safe to busy-retry
* -ENOENT if someone else is canceling @work, this state may persist
* for arbitrarily long
+ * ======== ================================================================
*
* Note:
* On >= 0 return, the caller owns @work's PENDING bit. To avoid getting
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 49/52] workqueue: fix a kernel-doc warning
2020-09-30 13:25 ` [PATCH v4 49/52] workqueue: fix a kernel-doc warning Mauro Carvalho Chehab
@ 2020-09-30 15:57 ` Tejun Heo
0 siblings, 0 replies; 103+ messages in thread
From: Tejun Heo @ 2020-09-30 15:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Jonathan Corbet, Lai Jiangshan, linux-kernel
On Wed, Sep 30, 2020 at 03:25:12PM +0200, Mauro Carvalho Chehab wrote:
> As warned by Sphinx:
>
> ./Documentation/core-api/workqueue:400: ./kernel/workqueue.c:1218: WARNING: Unexpected indentation.
>
> the return code table is currently not recognized, as it lacks
> markups.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Tejun Heo <tj@kernel.org>
Please route however you see fit.
Thanks.
--
tejun
^ permalink raw reply [flat|nested] 103+ messages in thread
* [PATCH v4 50/52] scripts: kernel-doc: try to use c:function if possible
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (48 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 49/52] workqueue: fix a kernel-doc warning Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 51/52] docs: conf.py: fix c:function support with Sphinx 3.x Mauro Carvalho Chehab
` (2 subsequent siblings)
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
There are a few namespace clashes by using c:macro everywhere:
basically, when using it, we can't have something like:
.. c:struct:: pwm_capture
.. c:macro:: pwm_capture
So, we need to use, instead:
.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)
for the function declaration.
The kernel-doc change was proposed by Jakob Lykke Andersen here:
https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65
Although I did a different implementation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 22 +++++++++++++---------
1 file changed, 13 insertions(+), 9 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f549837d874d..a05356c56fb8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -885,6 +885,7 @@ sub output_function_rst(%) {
my ($parameter, $section);
my $oldprefix = $lineprefix;
my $start = "";
+ my $is_macro = 0;
if ($sphinx_major < 3) {
if ($args{'typedef'}) {
@@ -898,7 +899,12 @@ sub output_function_rst(%) {
print ".. c:function:: ";
}
} else {
- print ".. c:macro:: ". $args{'function'} . "\n\n";
+ if ($args{'typedef'} || $args{'functiontype'} eq "") {
+ $is_macro = 1;
+ print ".. c:macro:: ". $args{'function'} . "\n\n";
+ } else {
+ print ".. c:function:: ";
+ }
if ($args{'typedef'}) {
print_lineno($declaration_start_line);
@@ -907,7 +913,7 @@ sub output_function_rst(%) {
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
} else {
- print "``";
+ print "``" if ($is_macro);
}
}
if ($args{'functiontype'} ne "") {
@@ -932,14 +938,12 @@ sub output_function_rst(%) {
print $type;
}
}
- if ($args{'typedef'}) {
- print ");``\n\n";
+ if ($is_macro) {
+ print ")``\n\n";
} else {
- if ($sphinx_major < 3) {
- print ")\n\n";
- } else {
- print ")``\n";
- }
+ print ")\n\n";
+ }
+ if (!$args{'typedef'}) {
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 51/52] docs: conf.py: fix c:function support with Sphinx 3.x
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (49 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 50/52] scripts: kernel-doc: try to use c:function if possible Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 52/52] docs: conf.py: change the Sphinx 3.x+ text Mauro Carvalho Chehab
2020-10-01 21:48 ` [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Jonathan Corbet
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
Sphinx C parser for the C domain is now more pedantic when
trying to identify the function types. That prevents scope
macros to be used as type defines.
Yet, since 3.0.2, it is possible to provide it a list of
such macros. Add them, in order to solve several Sphinx 3.x
warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 65 +++++++++++++++++++++++++++++++++++++++++--
1 file changed, 62 insertions(+), 3 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 3875401486de..b402bd8f6f71 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -47,9 +47,68 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
#
if major >= 3:
sys.stderr.write('''WARNING: The kernel documentation build process
- does not work correctly with Sphinx v3.0 and above. Expect errors
- in the generated output.
- ''')
+ does not work correctly with Sphinx v3.0 and above. Expect errors
+ in the generated output.
+ ''')
+ if minor > 0 or patch >= 2:
+ # Sphinx c function parser is more pedantic with regards to type
+ # checking. Due to that, having macros at c:function cause problems.
+ # Those needed to be scaped by using c_id_attributes[] array
+ c_id_attributes = [
+ # GCC Compiler types not parsed by Sphinx:
+ "__restrict__",
+
+ # include/linux/compiler_types.h:
+ "__iomem",
+ "__kernel",
+ "noinstr",
+ "notrace",
+ "__percpu",
+ "__rcu",
+ "__user",
+
+ # include/linux/compiler_attributes.h:
+ "__alias",
+ "__aligned",
+ "__aligned_largest",
+ "__always_inline",
+ "__assume_aligned",
+ "__cold",
+ "__attribute_const__",
+ "__copy",
+ "__pure",
+ "__designated_init",
+ "__visible",
+ "__printf",
+ "__scanf",
+ "__gnu_inline",
+ "__malloc",
+ "__mode",
+ "__no_caller_saved_registers",
+ "__noclone",
+ "__nonstring",
+ "__noreturn",
+ "__packed",
+ "__pure",
+ "__section",
+ "__always_unused",
+ "__maybe_unused",
+ "__used",
+ "__weak",
+ "noinline",
+
+ # include/linux/memblock.h:
+ "__init_memblock",
+ "__meminit",
+
+ # include/linux/init.h:
+ "__init",
+ "__ref",
+
+ # include/linux/linkage.h:
+ "asmlinkage",
+ ]
+
else:
extensions.append('cdomain')
extensions.append('automarkup')
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* [PATCH v4 52/52] docs: conf.py: change the Sphinx 3.x+ text
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (50 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 51/52] docs: conf.py: fix c:function support with Sphinx 3.x Mauro Carvalho Chehab
@ 2020-09-30 13:25 ` Mauro Carvalho Chehab
2020-10-01 21:48 ` [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Jonathan Corbet
52 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-30 13:25 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel
After the build fix patches, it is believed that the output
with Sphinx 3.x won't be a problem. Still, the C domain
support was re-written, and this can have caused hidden
issues.
So, let's keep the warning, changing it to a lighter
warning text.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index b402bd8f6f71..4f5d15abd047 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -47,8 +47,8 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
#
if major >= 3:
sys.stderr.write('''WARNING: The kernel documentation build process
- does not work correctly with Sphinx v3.0 and above. Expect errors
- in the generated output.
+ support for Sphinx v3.0 and above is brand new. Be prepared for
+ possible issues in the generated output.
''')
if minor > 0 or patch >= 2:
# Sphinx c function parser is more pedantic with regards to type
--
2.26.2
^ permalink raw reply related [flat|nested] 103+ messages in thread* Re: [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
` (51 preceding siblings ...)
2020-09-30 13:25 ` [PATCH v4 52/52] docs: conf.py: change the Sphinx 3.x+ text Mauro Carvalho Chehab
@ 2020-10-01 21:48 ` Jonathan Corbet
2020-10-02 6:52 ` Mauro Carvalho Chehab
52 siblings, 1 reply; 103+ messages in thread
From: Jonathan Corbet @ 2020-10-01 21:48 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, linux-kernel, David S. Miller,
Rafael J. Wysocki, Alexander Aring, Andrew Morton,
Anton Vorontsov, Colin Cross, Daniel Lezcano, Daniel Thompson,
Daniel Vetter, David Airlie, Jakub Kicinski, Jaroslav Kysela,
Jason Wessel, Kees Cook, Maarten Lankhorst,
Mauro Carvalho Chehab, Maxime Ripard, Mike Rapoport,
Moritz Fischer, Sean Young, Stefan Schmidt, Takashi Iwai,
Tejun Heo, Thomas Zimmermann, Tony Luck, Viresh Kumar
On Wed, 30 Sep 2020 15:24:23 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> This series add proper support for Sphinx 3.1 and above for building the html docs.
>
> This series comes after the one I wrote fixing the warnings.
>
> With this series applied on the top of next-20200922, there are just 12
> warnings:
> - 2 of them happens also on Sphinx 2.4.4
> (both seem easy to fix: I'll send later fixes for those);
> - 10 happens only on Sphinx 3.2.1.
>
> The new warnings are all due to duplicated C domain cross-reference symbols.
>
> Basically, the C domain on Sphinx doesn't allow to have an struct and
> a function with the same name. I opened an issue on Sphinx.:
>
> https://github.com/sphinx-doc/sphinx/issues/8241
>
> Hopefully, some newer version may have it fixed.
>
> There is still one thing that requires a fix: the automarkup.py. The
> way cross-references are stored with Sphinx 3 are different.
> I didn't try yet to address it, but I suspect that it shouldn't be
> hard to address it.
Modulo my comment on part 4, I think this is what we want. It's kind of
unfortunate that it's all necessary, but that's the way things are these
days, I guess.
This part is a bit intimidating, though:
> 288 files changed, 1709 insertions(+), 2183 deletions(-)
Should we maybe position this as an end-of-merge-window blast, once other
stuff has hopefully mostly settled? I can certainly warn Linus that it's
coming when I send the main docs pull.
I wonder how soon we could pull our minimum version forward to 3.1 and
drop a bunch of stuff? I fear it may not be for a while, alas...
Thanks for doing all this work,
jon
^ permalink raw reply [flat|nested] 103+ messages in thread* Re: [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above
2020-10-01 21:48 ` [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Jonathan Corbet
@ 2020-10-02 6:52 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 103+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-02 6:52 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, linux-kernel, David S. Miller,
Rafael J. Wysocki, Alexander Aring, Andrew Morton,
Anton Vorontsov, Colin Cross, Daniel Lezcano, Daniel Thompson,
Daniel Vetter, David Airlie, Jakub Kicinski, Jaroslav Kysela,
Jason Wessel, Kees Cook, Maarten Lankhorst,
Mauro Carvalho Chehab, Maxime Ripard, Mike Rapoport,
Moritz Fischer, Sean Young, Stefan Schmidt, Takashi Iwai,
Tejun Heo, Thomas Zimmermann, Tony Luck, Viresh Kumar
Em Thu, 1 Oct 2020 15:48:54 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Wed, 30 Sep 2020 15:24:23 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > This series add proper support for Sphinx 3.1 and above for building the html docs.
> >
> > This series comes after the one I wrote fixing the warnings.
> >
> > With this series applied on the top of next-20200922, there are just 12
> > warnings:
> > - 2 of them happens also on Sphinx 2.4.4
> > (both seem easy to fix: I'll send later fixes for those);
> > - 10 happens only on Sphinx 3.2.1.
> >
> > The new warnings are all due to duplicated C domain cross-reference symbols.
> >
> > Basically, the C domain on Sphinx doesn't allow to have an struct and
> > a function with the same name. I opened an issue on Sphinx.:
> >
> > https://github.com/sphinx-doc/sphinx/issues/8241
> >
> > Hopefully, some newer version may have it fixed.
> >
> > There is still one thing that requires a fix: the automarkup.py. The
> > way cross-references are stored with Sphinx 3 are different.
> > I didn't try yet to address it, but I suspect that it shouldn't be
> > hard to address it.
>
> Modulo my comment on part 4, I think this is what we want. It's kind of
> unfortunate that it's all necessary, but that's the way things are these
> days, I guess.
Yes, it is unfortunate. Yet, my feeling is that this approach provides
us a good way to transition to the new C domain parser, which has some
advantages over the older code.
> This part is a bit intimidating, though:
>
> > 288 files changed, 1709 insertions(+), 2183 deletions(-)
Yes. Yet, the media userspace API is responsible for most of it:
224 files changed, 1076 insertions(+), 1716 deletions(-)
As most of the uAPI documentation doesn't rely on kernel-doc
(mostly due to historic reasons).
To be fair, most of the other changes outside the building system
are due to already-existing issues at the documentation. There are
several kernel-doc tags creating duplicated C references.
While Sphinx < 3 C domain parser were able to detect them, such
warnings are disabled by default.
> Should we maybe position this as an end-of-merge-window blast, once other
> stuff has hopefully mostly settled? I can certainly warn Linus that it's
> coming when I send the main docs pull.
Yeah, adding this series, together with the remaining patches fixing
all warnings with Sphinx < 3 at the end of the merge window seems
the right thing to do, IMO.
> I wonder how soon we could pull our minimum version forward to 3.1 and
> drop a bunch of stuff? I fear it may not be for a while, alas...
I guess it may take some time. In any case, for the next minimal
version, I would set for the upcoming one that will fix those
issue reported here:
https://github.com/sphinx-doc/sphinx/issues/7819
https://github.com/sphinx-doc/sphinx/issues/8241
One such example is this warning:
.../Documentation/driver-api/miscellaneous:48: ../drivers/pwm/core.c:669: WARNING: Duplicate C declaration, also defined in 'driver-api/miscellaneous'.
Declaration is 'int pwm_capture (struct pwm_device *pwm, struct pwm_capture *result, unsigned long timeout)'.
(See: we have a function pwm_capture and a struct with the
same name. Both have kernel-doc tags at drivers/pwm/core.c)
Without fixing it, there's no way to produce a zero-warning
docs building[1] with Sphinx versions above 2.4.x.
[1] Well, it could be possible to rename such kAPI symbols to
make Sphinx happy, but IMO, the C domain there should be able
to fully support the C language.
> Thanks for doing all this work,
Anytime.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 103+ messages in thread