From 93351d4196802b3ee01074d96df47b73716984ba Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 4 Oct 2020 09:44:28 +0200 Subject: scripts: kernel-doc: allow passing desired Sphinx C domain dialect When kernel-doc is called via kerneldoc.py, there's no need to auto-detect the Sphinx version, as the Sphinx module already knows it. So, add an optional parameter to allow changing the Sphinx dialect. As kernel-doc can also be manually called, keep the auto-detection logic if the parameter was not specified. On such case, emit a warning if sphinx-build can't be found at PATH. I ended using a suggestion from Joe for using a more readable regex, instead of using a complex one with a hidden group like: m/^(\d+)\.(\d+)(?:\.?(\d+)?)/ in order to get the optional argument. Thanks-to: Joe Perches Suggested-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/kerneldoc.py | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 4bcbd6ae01cd..1a1b12242a45 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -70,6 +70,11 @@ class KernelDocDirective(Directive): env = self.state.document.settings.env cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + # Pass the version string to kernel-doc, as it needs to use a different + # dialect, depending what the C domain supports for each specific + # Sphinx versions + cmd += ['-sphinx-version', sphinx.__version__] + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = [] -- cgit v1.3.1 From 71e552aebf260239463d348ecb75b972bee0804b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 24 Sep 2020 11:32:38 +0200 Subject: docs: cdomain.py: add support for a new Sphinx 3.1+ tag 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 --- Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) (limited to 'Documentation') 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): -- cgit v1.3.1 From 95f49490515e50f7ac23c453241503cd9fb4b434 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 25 Sep 2020 13:38:27 +0200 Subject: docs: cdomain.py: extend it to handle new Sphinx 3.x tags 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 --- Documentation/sphinx/cdomain.py | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) (limited to 'Documentation') 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)) -- cgit v1.3.1 From 91fc6d8afe06698326bdd4d3bcb362c17c52e288 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 28 Sep 2020 11:22:12 +0200 Subject: docs: kerneldoc.py: append the name of the parsed doc file 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 --- Documentation/sphinx/kerneldoc.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 1a1b12242a45..a3a5427130da 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -141,7 +141,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() -- cgit v1.3.1 From 2791f47d26d1e49a747a0a1aa2d694e6aab447ab Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 29 Sep 2020 11:32:18 +0200 Subject: docs: kerneldoc.py: add support for kerneldoc -nosymbol Currently, there's no way to exclude identifiers from a kernel-doc markup. Add support for it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/kernel-doc.rst | 8 ++++++++ Documentation/sphinx/kerneldoc.py | 7 +++++++ 2 files changed, 15 insertions(+) (limited to 'Documentation') 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 a3a5427130da..e9857ab904f1 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 @@ -104,6 +105,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)) -- cgit v1.3.1 From 06dc65b0fa6130aae73927399269bdea1b7658d8 Mon Sep 17 00:00:00 2001 From: "Nícolas F. R. A. Prado" Date: Tue, 13 Oct 2020 23:13:11 +0000 Subject: docs: automarkup.py: Use new C roles in Sphinx 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While Sphinx 2 used a single c:type role for struct, union, enum and typedef, Sphinx 3 uses a specific role for each one. To keep backward compatibility, detect the Sphinx version and use the correct roles for that version. Signed-off-by: Nícolas F. R. A. Prado Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/automarkup.py | 55 +++++++++++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index a1b0f554cd82..db13fb15cedc 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -23,7 +23,21 @@ from itertools import chain # bit tries to restrict matches to things that won't create trouble. # RE_function = re.compile(r'(([\w_][\w\d_]+)\(\))') -RE_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)') + +# +# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef +# +RE_generic_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)') + +# +# Sphinx 3 uses a different C role for each one of struct, union, enum and +# typedef +# +RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=re.ASCII) +RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=re.ASCII) +RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=re.ASCII) +RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII) + # # Detects a reference to a documentation page of the form Documentation/... with # an optional extension @@ -48,9 +62,22 @@ def markup_refs(docname, app, node): # # Associate each regex with the function that will markup its matches # - markup_func = {RE_type: markup_c_ref, - RE_function: markup_c_ref, - RE_doc: markup_doc_ref} + markup_func_sphinx2 = {RE_doc: markup_doc_ref, + RE_function: markup_c_ref, + RE_generic_type: markup_c_ref} + + markup_func_sphinx3 = {RE_doc: markup_doc_ref, + RE_function: markup_c_ref, + RE_struct: markup_c_ref, + RE_union: markup_c_ref, + RE_enum: markup_c_ref, + RE_typedef: markup_c_ref} + + if sphinx.version_info[0] >= 3: + markup_func = markup_func_sphinx3 + else: + markup_func = markup_func_sphinx2 + match_iterators = [regex.finditer(t) for regex in markup_func] # # Sort all references by the starting position in text @@ -79,8 +106,24 @@ def markup_refs(docname, app, node): # type_name) with an appropriate cross reference. # def markup_c_ref(docname, app, match): - class_str = {RE_function: 'c-func', RE_type: 'c-type'} - reftype_str = {RE_function: 'function', RE_type: 'type'} + class_str = {RE_function: 'c-func', + # Sphinx 2 only + RE_generic_type: 'c-type', + # Sphinx 3+ only + RE_struct: 'c-struct', + RE_union: 'c-union', + RE_enum: 'c-enum', + RE_typedef: 'c-type', + } + reftype_str = {RE_function: 'function', + # Sphinx 2 only + RE_generic_type: 'type', + # Sphinx 3+ only + RE_struct: 'struct', + RE_union: 'union', + RE_enum: 'enum', + RE_typedef: 'type', + } cdom = app.env.domains['c'] # -- cgit v1.3.1 From f66e47f98c1e827a85654a8cfa1ba539bb381a1b Mon Sep 17 00:00:00 2001 From: "Nícolas F. R. A. Prado" Date: Tue, 13 Oct 2020 23:13:17 +0000 Subject: docs: automarkup.py: Fix regexes to solve sphinx 3 warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit With the transition to Sphinx 3, new warnings were generated by automarkup, exposing bugs in the regexes. The warnings were caused by the expressions matching words in the translated versions of the documentation, since any unicode character was matched. Fix the regular expression by making the C regexes use ASCII and ensuring the expressions only match the beginning of words, in order to avoid warnings like this: WARNING: Unparseable C cross-reference: '调用debugfs_rename' That's probably due to the lack of using spaces between words on Chinese. Signed-off-by: Nícolas F. R. A. Prado Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/automarkup.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index db13fb15cedc..43dd9025fc77 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -22,12 +22,13 @@ from itertools import chain # :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last # bit tries to restrict matches to things that won't create trouble. # -RE_function = re.compile(r'(([\w_][\w\d_]+)\(\))') +RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII) # # Sphinx 2 uses the same :c:type role for struct, union, enum and typedef # -RE_generic_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)') +RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)', + flags=re.ASCII) # # Sphinx 3 uses a different C role for each one of struct, union, enum and @@ -42,7 +43,7 @@ RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII) # Detects a reference to a documentation page of the form Documentation/... with # an optional extension # -RE_doc = re.compile(r'Documentation(/[\w\-_/]+)(\.\w+)*') +RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*') # # Many places in the docs refer to common system calls. It is -- cgit v1.3.1 From 3050edfd7971da7fddc77ac7c4607697ec10a554 Mon Sep 17 00:00:00 2001 From: "Nícolas F. R. A. Prado" Date: Tue, 13 Oct 2020 23:13:23 +0000 Subject: docs: automarkup.py: Skip C reserved words when cross-referencing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit With the transition to Sphinx 3, new warnings were caused by automarkup, exposing bugs in the name matching. When automarkup parsed a text like "struct struct" in the documentation, it tried to cross-reference to a "struct" symbol, which is recognized as a C reserved word by Sphinx 3, generating a warning. Add some C reserved words (only the ones that were causing warnings) to a list and skip them while trying to cross-reference. Signed-off-by: Nícolas F. R. A. Prado Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/automarkup.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 43dd9025fc77..1cc3a2cf2a88 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -45,6 +45,12 @@ RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII) # RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*') +# +# Reserved C words that we should skip when cross-referencing +# +Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ] + + # # Many places in the docs refer to common system calls. It is # pointless to try to cross-reference them and, as has been known @@ -133,7 +139,8 @@ def markup_c_ref(docname, app, match): target = match.group(2) target_text = nodes.Text(match.group(0)) xref = None - if not (match.re == RE_function and target in Skipfuncs): + if not ((match.re == RE_function and target in Skipfuncs) + or (target in Skipnames)): lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) lit_text += target_text pxref = addnodes.pending_xref('', refdomain = 'c', -- cgit v1.3.1 From c51d9b046f907b7c96760700c6bdda6fbe38de60 Mon Sep 17 00:00:00 2001 From: "Nícolas F. R. A. Prado" Date: Tue, 13 Oct 2020 23:13:34 +0000 Subject: docs: automarkup.py: Add cross-reference for parametrized C macros MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sphinx 3 added support for declaring C macros with parameters using the :c:macro role. To support automarkup for both functions and parametrized macros using the same regex (words ending in ()), try to cross-reference to both, and only fall back to regular text if neither exist. Signed-off-by: Nícolas F. R. A. Prado Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/automarkup.py | 49 ++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 1cc3a2cf2a88..409dbc4100de 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -74,7 +74,7 @@ def markup_refs(docname, app, node): RE_generic_type: markup_c_ref} markup_func_sphinx3 = {RE_doc: markup_doc_ref, - RE_function: markup_c_ref, + RE_function: markup_func_ref_sphinx3, RE_struct: markup_c_ref, RE_union: markup_c_ref, RE_enum: markup_c_ref, @@ -109,12 +109,47 @@ def markup_refs(docname, app, node): return repl # -# Try to replace a C reference (function() or struct/union/enum/typedef -# type_name) with an appropriate cross reference. +# In sphinx3 we can cross-reference to C macro and function, each one with its +# own C role, but both match the same regex, so we try both. # +def markup_func_ref_sphinx3(docname, app, match): + class_str = ['c-func', 'c-macro'] + reftype_str = ['function', 'macro'] + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + if not (target in Skipfuncs or target in Skipnames): + for class_s, reftype_s in zip(class_str, reftype_str): + lit_text = nodes.literal(classes=['xref', 'c', class_s]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_s, + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_s, target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + + return target_text + def markup_c_ref(docname, app, match): - class_str = {RE_function: 'c-func', - # Sphinx 2 only + class_str = {# Sphinx 2 only + RE_function: 'c-func', RE_generic_type: 'c-type', # Sphinx 3+ only RE_struct: 'c-struct', @@ -122,8 +157,8 @@ def markup_c_ref(docname, app, match): RE_enum: 'c-enum', RE_typedef: 'c-type', } - reftype_str = {RE_function: 'function', - # Sphinx 2 only + reftype_str = {# Sphinx 2 only + RE_function: 'function', RE_generic_type: 'type', # Sphinx 3+ only RE_struct: 'struct', -- cgit v1.3.1 From 01fae02d8d67116f5b9bc36a8571356aa76f02f0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 24 Sep 2020 08:15:55 +0200 Subject: media: docs: make CEC documents compatible with Sphinx 3.1+ 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 --- .../userspace-api/media/cec/cec-func-close.rst | 10 +++------- .../userspace-api/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 +++++--------- .../userspace-api/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 ++++++++------- .../userspace-api/media/cec/cec-ioc-dqevent.rst | 15 +++++---------- .../userspace-api/media/cec/cec-ioc-g-mode.rst | 16 ++++++++-------- .../userspace-api/media/cec/cec-ioc-receive.rst | 18 ++++++++---------- 11 files changed, 63 insertions(+), 87 deletions(-) (limited to 'Documentation') 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 - .. c:function:: int close( int fd ) - :name: cec-close Arguments ========= ``fd`` - File descriptor returned by :c:func:`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() ` 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 - -.. 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() `. + 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() ` 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 - .. 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() ` 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() ` 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 - .. 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() ` function applications can wait for CEC +With the :c:func:`poll()` function applications can wait for CEC events. -On success :c: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 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() ` manual page. - +For more details see the :c:func:`poll()` manual page. Return Value ============ -On success, :c: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/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() `. + 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() `. + 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 + +``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)`` + +.. c:macro:: CEC_ADAP_S_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_S_LOG_ADDRS, struct cec_log_addrs *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`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 + +``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)`` -.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_S_PHYS_ADDR +.. 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() `. + 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() `. + 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() `. + 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 + +``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)`` -.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp ) - :name: CEC_TRANSMIT +.. c:macro:: CEC_TRANSMIT + +``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)`` Arguments ========= ``fd`` - File descriptor returned by :c:func:`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 ` 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 ============ -- cgit v1.3.1 From 407e84cd1e9a802df1955e281d8956439abc499b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 24 Sep 2020 14:04:26 +0200 Subject: media: docs: make V4L documents more compatible with Sphinx 3.1+ 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 --- Documentation/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 ++---- Documentation/userspace-api/media/v4l/dev-rds.rst | 12 +--- .../userspace-api/media/v4l/dev-sliced-vbi.rst | 31 +++------- Documentation/userspace-api/media/v4l/diff-v4l.rst | 39 ++---------- Documentation/userspace-api/media/v4l/dmabuf.rst | 8 +-- Documentation/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 ++++------ Documentation/userspace-api/media/v4l/mmap.rst | 26 ++++---- Documentation/userspace-api/media/v4l/open.rst | 15 ++--- Documentation/userspace-api/media/v4l/rw.rst | 18 +++--- .../userspace-api/media/v4l/streaming-par.rst | 5 +- Documentation/userspace-api/media/v4l/userp.rst | 11 ++-- .../userspace-api/media/v4l/vidioc-create-bufs.rst | 11 ++-- .../userspace-api/media/v4l/vidioc-cropcap.rst | 11 ++-- .../media/v4l/vidioc-dbg-g-chip-info.rst | 13 ++-- .../media/v4l/vidioc-dbg-g-register.rst | 18 +++--- .../userspace-api/media/v4l/vidioc-decoder-cmd.rst | 19 +++--- .../userspace-api/media/v4l/vidioc-dqevent.rst | 19 ++---- .../media/v4l/vidioc-dv-timings-cap.rst | 17 +++--- .../userspace-api/media/v4l/vidioc-encoder-cmd.rst | 25 ++++---- .../media/v4l/vidioc-enum-dv-timings.rst | 16 +++-- .../userspace-api/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 ++-- .../userspace-api/media/v4l/vidioc-enumaudio.rst | 10 ++-- .../media/v4l/vidioc-enumaudioout.rst | 10 ++-- .../userspace-api/media/v4l/vidioc-enuminput.rst | 14 ++--- .../userspace-api/media/v4l/vidioc-enumoutput.rst | 13 ++-- .../userspace-api/media/v4l/vidioc-enumstd.rst | 23 +++---- .../userspace-api/media/v4l/vidioc-expbuf.rst | 14 ++--- .../userspace-api/media/v4l/vidioc-g-audio.rst | 18 +++--- .../userspace-api/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 ++++---- .../userspace-api/media/v4l/vidioc-g-enc-index.rst | 13 ++-- .../userspace-api/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 +++---- .../userspace-api/media/v4l/vidioc-g-frequency.rst | 16 +++-- .../userspace-api/media/v4l/vidioc-g-input.rst | 15 +++-- .../userspace-api/media/v4l/vidioc-g-jpegcomp.rst | 17 +++--- .../userspace-api/media/v4l/vidioc-g-modulator.rst | 17 +++--- .../userspace-api/media/v4l/vidioc-g-output.rst | 15 +++-- .../userspace-api/media/v4l/vidioc-g-parm.rst | 30 ++++------ .../userspace-api/media/v4l/vidioc-g-priority.rst | 16 +++-- .../userspace-api/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 ++++---- .../userspace-api/media/v4l/vidioc-g-tuner.rst | 19 +++--- .../userspace-api/media/v4l/vidioc-log-status.rst | 10 ++-- .../userspace-api/media/v4l/vidioc-overlay.rst | 10 ++-- .../userspace-api/media/v4l/vidioc-prepare-buf.rst | 10 ++-- .../userspace-api/media/v4l/vidioc-qbuf.rst | 17 +++--- .../media/v4l/vidioc-query-dv-timings.rst | 15 +++-- .../userspace-api/media/v4l/vidioc-querybuf.rst | 10 ++-- .../userspace-api/media/v4l/vidioc-querycap.rst | 16 ++--- .../userspace-api/media/v4l/vidioc-queryctrl.rst | 22 +++---- .../userspace-api/media/v4l/vidioc-querystd.rst | 15 +++-- .../userspace-api/media/v4l/vidioc-reqbufs.rst | 10 ++-- .../media/v4l/vidioc-s-hw-freq-seek.rst | 11 ++-- .../userspace-api/media/v4l/vidioc-streamon.rst | 14 ++--- .../v4l/vidioc-subdev-enum-frame-interval.rst | 10 ++-- .../media/v4l/vidioc-subdev-enum-frame-size.rst | 11 ++-- .../media/v4l/vidioc-subdev-enum-mbus-code.rst | 10 ++-- .../media/v4l/vidioc-subdev-g-crop.rst | 16 +++-- .../media/v4l/vidioc-subdev-g-fmt.rst | 17 +++--- .../media/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(-) (limited to 'Documentation') diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 4f95496adc5b..8be62dcffbb2 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() ` 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() `, + 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 @@ -720,7 +716,6 @@ enum v4l2_memory - The buffer is used for :ref:`DMA shared buffer ` I/O. - Timecodes ========= @@ -729,7 +724,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 @@ -766,7 +760,6 @@ struct v4l2_timecode - The "user group" bits from the timecode. - .. _timecode-type: Timecode Types @@ -796,7 +789,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 ` 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