[tip:timers/core] timers: Adjust a kernel-doc comment

[tip-bot for Mauro Carvalho Chehab]

Commit-ID:  bf9c96bec76fbc4424b4c70be563af4107d8044f
Gitweb: https://git.kernel.org/tip/bf9c96bec76fbc4424b4c70be563af4107d8044f
Author: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
AuthorDate: Mon, 7 May 2018 06:35:48 -0300
Committer:  Thomas Gleixner <t...@linutronix.de>
CommitDate: Sun, 13 May 2018 15:55:43 +0200

timers: Adjust a kernel-doc comment

Those three warnings can easily solved by using :: to indicate a
code block:

./kernel/time/timer.c:1259: WARNING: Unexpected indentation.
./kernel/time/timer.c:1261: WARNING: Unexpected indentation.
./kernel/time/timer.c:1262: WARNING: Block quote ends without a blank 
line; unexpected unindent.

While here, align the lines at the block.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
Signed-off-by: Thomas Gleixner <t...@linutronix.de>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Stephen Boyd <sb...@kernel.org>
Cc: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mche...@infradead.org>
Cc: John Stultz <john.stu...@linaro.org>
Link: 
https://lkml.kernel.org/r/f02e6a0ce27f3b5e33415d92d07a40598904b3ee.1525684985.git.mchehab%2bsams...@kernel.org

---
 kernel/time/timer.c | 14 +++---
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/kernel/time/timer.c b/kernel/time/timer.c
index 4a4fd567fb26..cc2d23e6ff61 100644
--- a/kernel/time/timer.c
+++ b/kernel/time/timer.c
@@ -1251,18 +1251,18 @@ EXPORT_SYMBOL(try_to_del_timer_sync);
  *
  * Note: For !irqsafe timers, you must not hold locks that are held in
  *   interrupt context while calling this function. Even if the lock has
- *   nothing to do with the timer in question.  Here's why:
+ *   nothing to do with the timer in question.  Here's why::
  *
  *CPU0 CPU1
  * 
- *   
- *   call_timer_fn();
- * base->running_timer = mytimer;
- *  spin_lock_irq(somelock);
+ * 
+ *   call_timer_fn();
+ *   base->running_timer = mytimer;
+ *spin_lock_irq(somelock);
  * 
  *spin_lock(somelock);
- *  del_timer_sync(mytimer);
- *   while (base->running_timer == mytimer);
+ *del_timer_sync(mytimer);
+ *while (base->running_timer == mytimer);
  *
  * Now del_timer_sync() will never return and never release somelock.
  * The interrupt on the other CPU is waiting to grab somelock but
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 00/11] Fix some doc build warnings/errors and broken links

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:22:35 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:

> On Wed,  9 May 2018 10:18:43 -0300
> Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> 
> > Patches 1 to 5 on this series contain the patches that weren't yet
> > applied from the past patch series and touch only at Documentation.
> > There are two changes there:
> >   patch 2: fixed the description and added a c/c to cgroup maintainers;
> >   patch 4: rewritten according with Louis request, droping several hunks.  
> 
> Of these, I've applied 2, 4, and 6.  The networking and crypto folks like
> to apply their own documentation fixes; I assume they'll pick these up.

Hmm... I'm pretty sure I emailed about patch 4. Luis actually came with
a better solution: he partially removed the note, as it is outdated.
Better to revert it as otherwise it will rise conflicts at -next once
merged.

> 
> > Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
> > adding an auto-fix feature.  
> 
> Applied this one.
> 
> > Patches 7 and 8 fix things that would cause troubles for the
> > automatic autocorrection tool.  
> 
> #7 is applied.  #8 doesn't apply, though; I'm not sure which tree you made
> it against?  In any case, I've stopped here for now.

Andrea commented about #8. You already applied an identical patch :-)

> > Patch 9 touches a lot of random places (including MAINTAINERS)
> > that contain broken links and can be auto-fixed. It could be
> > broken into one patch per touched file, but I think that is
> > overkill.   
> 
> Let's keep this one (and the ones that follow) aside.  I'm happy to apply
> them, but I think they are best applied as an end-of-merge-window thing.  I
> envision lots of conflicts, and I already have a pile of those to explain
> to Linus this time around.

Yeah, this patch touches on a lot of stuff. Better to handle it by the
end of a merge window.

I suspect you'll need to re-generate it by running this command again:

./scripts/documentation-file-ref-check --fix

But you should check the results, as false positives may arise.

If you prefer, I rebased the tree with the pending patches, placing
patch 9 at the end. This way, you'll likely avoid conflicts with
patches 10 and 11.

https://git.linuxtv.org/mchehab/experimental.git/log/?h=broken-links-v4

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 18:52:20 +0200
Andrea Parri  escreveu:

> On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
> > On Thu, 10 May 2018 14:23:35 +0200
> > Andrea Parri  wrote:
> >   
> > > only
> > > remember that other people (including some developers running into the
> > > "disadventure" of opening an RST doc. from their preferred text editor
> > > and being brought to conclude:  "WTH!  I need to open a web browser, I
> > > guess...") _use_ such doc. and _do care_ about it, and that what might
> > > be an improvement for some people might look as "vandalizing" to others.  
> > 
> > If you have an example of a place where use of a web browser has been
> > made mandatory, please point it out.  Avoiding that was at the top of the
> > list of explicit requirements.  
> 
> That's all I need.
> 
> 
> >Surely an extra colon is not going to
> > force you to run screaming to the protective embrace of Firefox...?  
> 
> Let me put it in these terms: I believe that that extra colon (or the
> "diagram" keywork) is not going to improve/help my use of the doc. ;D

No, it won't improve, but, it won't make it harder for a human
to understand if a "diagram" or "::" is added at the description.

The thing is that we need something that works for the Kernel as
a hole, and not just on a few places.

On some subsystems, just a text is not good enough to describe
things. See, for example:
https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html

https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.html

https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.html
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html

Images, complex tables, etc are sometimes required to show some things.
Trying to explain just on text is harder to write, longer and worse
for readers. In the past, DocBook was used. ReST made very simple to
write documentation. From where I sit, I'm reviewing documentation
patches from a lot more people than the usage of a markup language.

As a bonus, we can now create cross-references for kernel-doc functions,
with is really great when reading documentation for complex hardware.

From where I sit at media, the subsystem documentation, if generated
in PDF, becomes a book with more than 1,100 pages, full of long tables,
images and graphs[1], covering uAPI, kAPI and driver-specific
documentation.

[1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf

As on all subsystems, developers write documentation directly
at .rst or as kernel-doc comments. But for reading it, even developers
prefer to read the docs via the html (or pdf) output, as it better
shows tables and images. It is also faster to follow the dozen
thousands of links inside it.

The point is: we shouldn't enforce everyone to use our own view
about how to navigate through documentation. People are free to
use whatever improves their workflow.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 13:42:58 -0300
Mauro Carvalho Chehab <mchehab+sams...@kernel.org> escreveu:

> Em Thu, 10 May 2018 09:38:46 -0600
> Jonathan Corbet <cor...@lwn.net> escreveu:
> 
> > On Thu, 10 May 2018 11:21:13 -0300
> > Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> > 
> > > The problem with a hint-based mechanism is that it will generate
> > > false hints. If added, we may end by needing to add extra tags to
> > > disable the hints mechanism where it gets wrong, or to periodically
> > > do code changes at kernel-doc comments in order to make the hints
> > > logic happy.
> > > 
> > > So, IMO, we should provide non-hints based mechanism, like forcing the
> > > string that prepends the colon to have a keyword that will make it to
> > > parse the block as literal, where expressions like:
> > > 
> > >   See the code-block foo:
> > >   See the following code example:
> > >   See the following flow diagram:
> > >   See the following artwork:
> > > 
> > > Is the best alternative to avoid "::", as on the enclosed patch.  
> > 
> > But this, too, is a hint-based mechanism.  Thanks for the patches, I'll
> > keep them around, but I would like an opportunity to try to do better
> > before applying them.  I fear that using magic words in this way will
> > lead to a constant stream of surprises, and I'd like to avoid that if
> > possible...
> 
> Yes, it is still hint-based. A careful selection of the "magic spell
> words/phrases" would minimize the risks of false positives, but it
> could still lead into some unwanted surprises.

Btw, running this:

$ git grep -A2 "\*\s.*following.*(code|example|artwork|flow|diagram).*:$"

currently doesn't have a single match. 

If we force a two word combination, and an ending with ":" should
be enough to not having too much false positives.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 09:38:46 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:

> On Thu, 10 May 2018 11:21:13 -0300
> Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> 
> > The problem with a hint-based mechanism is that it will generate
> > false hints. If added, we may end by needing to add extra tags to
> > disable the hints mechanism where it gets wrong, or to periodically
> > do code changes at kernel-doc comments in order to make the hints
> > logic happy.
> > 
> > So, IMO, we should provide non-hints based mechanism, like forcing the
> > string that prepends the colon to have a keyword that will make it to
> > parse the block as literal, where expressions like:
> > 
> > See the code-block foo:
> > See the following code example:
> > See the following flow diagram:
> > See the following artwork:
> > 
> > Is the best alternative to avoid "::", as on the enclosed patch.  
> 
> But this, too, is a hint-based mechanism.  Thanks for the patches, I'll
> keep them around, but I would like an opportunity to try to do better
> before applying them.  I fear that using magic words in this way will
> lead to a constant stream of surprises, and I'd like to avoid that if
> possible...

Yes, it is still hint-based. A careful selection of the "magic spell
words/phrases" would minimize the risks of false positives, but it
could still lead into some unwanted surprises.

IMO, "::" (or some other character combination that is not used
elsewhere) is still the safest option.


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Mauro Carvalho Chehab]

Comments that end with a comma and have certain keywords
should be presented as code-blocks

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0057d8eafcc1..8ce2d0f54369 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -803,7 +803,8 @@ sub output_highlight_rst {
#
if (! $in_literal) {
$block .= $line . "\n";
-   if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
+   if (($block =~ 
s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) ||
+   ($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
$in_literal = 1;
$litprefix = "";
$output .= highlight_block($block);
-- 
2.17.0


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH 2/2] wait: add a keyword to indicate a diagram code block on a kernel-doc

[Mauro Carvalho Chehab]

When handling code-blocks, usual parsing should be disabled.
Indicate it by using the keyword disagram.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 include/linux/wait.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/wait.h b/include/linux/wait.h
index d9f131ecf708..653814475ee9 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
*wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() as shown in this diagram:
  *
  *  CPU0 - wakerCPU1 - waiter
  *
-- 
2.17.0


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:

> On Thu, 10 May 2018 06:38:05 -0300
> Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> 
> > (Peter said):  
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.
> 
> FWIW, there's no problem with a sentence ending with a single colon.
> It's only an issue if you want to flag a special interpretation for the
> text that follows that sentence.  Just to be precise.
> 
> > Patches are welcome, although I don't see any easy way to solve it.  
> 
> I could envision some sort of heuristic that would recognize an indented
> block containing code.  Probably we could go simpler and force the
> "literal block" treatment for any indented block that lacks explicit
> enumeration markers.  So:
> 
>   this->would_be("a literal block");
> 
> but:
> 
>   - This would not be
> 
> Such a thing would likely be a bit fragile (people feel, rightly, that
> they can put anything into normal text) but it might just work well
> enough.  For best results, it should probably be done as part of Sphinx
> itself, rather than yet another ugly hack in the kerneldoc script.

I guess that it also won't work...

$ git grep -A2 "\*\s.*\s.*:$" -- $(git grep kernel-doc:: Documentation/|cut -d 
: -f 4-)

Present some matches that seem to be violating such hint.

drivers/edac/edac_device.h:/* The offset value can be:
drivers/edac/edac_device.h- *   -1 indicating no offset value
drivers/edac/edac_device.h- *   0 for zero-based block numbers

drivers/gpu/drm/drm_scdc_helper.c: *As per the spec:
drivers/gpu/drm/drm_scdc_helper.c- *TMDS clock rate for pixel clock 
< 340 MHz = 1x the character
drivers/gpu/drm/drm_scdc_helper.c- *rate = 1/10 pixel clock rate

I didn't actually check if those are part of a Kernel-doc markup, though,
but it shows that people sometimes don't add a "prepend" character to
a list.

In the specific case of errors, prepending with a "-" can be weird,
as it may lead ugly things like:

* - -1 indicating no offset value
* - 0 for zero-based block numbers

The problem with a hint-based mechanism is that it will generate
false hints. If added, we may end by needing to add extra tags to
disable the hints mechanism where it gets wrong, or to periodically
do code changes at kernel-doc comments in order to make the hints
logic happy.

So, IMO, we should provide non-hints based mechanism, like forcing the
string that prepends the colon to have a keyword that will make it to
parse the block as literal, where expressions like:

See the code-block foo:
See the following code example:
See the following flow diagram:
See the following artwork:

Is the best alternative to avoid "::", as on the enclosed patch.

> This particular problem may be solvable, and I'll look into it, but not
> right away.  The offline world is being rather insistently obnoxious
> these days...

Thanks,
Mauro

[PATCH] Mark a diagram at wait.h as such, using a code-block for it

Instead of explicitly using "::" to mark the diagram,
detect it based on code words inside the description.

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

diff --git a/include/linux/wait.h b/include/linux/wait.h
index d9f131ecf708..c360c5947374 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
*wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() like on this diagram:
  *
  *  CPU0 - wakerCPU1 - waiter
  *
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0057d8eafcc1..1c69072997f8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -803,7 +803,12 @@ sub output_highlight_rst {
#
if (! $in_literal) {
$block .= $line . "\n";
-   if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
+   if ($block =~ 
s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) {
+   $in_literal = 1;
+   $litprefix = "";
+   $output .= highlight_block($block);
+   $block = ""
+   } elsif (($line =~ /$sphinx_literal/) || ($line =~ 
/$sphinx_cblock/)) {
$in_literal = 1;
$litprefix = "";
$output .= highlight_block($block);


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:20:36 +0200
Peter Zijlstra <pet...@infradead.org> escreveu:

> On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:
> > Em Thu, 10 May 2018 01:38:38 -0700
> > Christoph Hellwig <h...@infradead.org> escreveu:
> >   
> > > >   * Use either while holding wait_queue_head::lock or when used for 
> > > > wakeups
> > > > - * with an extra smp_mb() like:
> > > > + * with an extra smp_mb() like::
> > > 
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.  
> 
> That is exactly my point; the whole rst stuff detracts from normal text.
> It makes both reading and writing harder than it needs to be.
> 
> > Patches are welcome, although I don't see any easy way to solve it.
> > 
> > In English, the common case is that a line with ends with a colon is
> > followed by a list. E. g.  
> 
> (google) Dictionary says:
> 
> "a punctuation mark (:) used to precede a list of items, a quotation, or
> an expansion or explanation."
> 
> An enumeration (list) is just one of many possible uses of the colon.

True, but the point is that whatever tool is used, it should be able
to uniquely unambiguously identify what it follows.

For example, it if is a list of items, it should keep parsing the
semantics markups inside it e. g. marking %FOO as a constant,
and bar() as a function, etc, following kernel-doc syntax. 

But, if it is a quote, a code example or an ascii artwork, it
should disable all such parsers, enclosing the result into a
literal block.

> > However, in this specific case, it is followed by an ascii artwork. 
> > The double colon is a notation that tells Sphinx to not parse the
> > lines at the next block, placing the contents of it inside a literal
> > block. It is used also when the next lines contain a code example,
> > in order to avoid parsing things like @, () and * inside the code 
> > block.
> > 
> > The kernel-doc tool might eventually have some parsing logic that
> > would replace something to a '::' before sending it to Sphinx.  
> 
> I think typically there will be an 'empty' line between the colon ending
> and the 'example/explanation'. This seems true for a number of comments
> I found in drm using the '::' nonsense.

Unfortunately, that's not true treewide. The presense/absense of a
blank line after a line ending with a colon doesn't indicate if the contents
below should be handled as a literal block or not[1].

[1] you can verify some use cases with:
$ git grep -A2 "\*.*\s.*:$" -- $(git grep kernel-doc:: 
Documentation/|cut -d : -f 4-)

> Simple regexes don't do multi-line patterns, but maybe the kerneldoc
> thing can parse it differently.

kernel-doc is a regex-based parser (and not an AI engine). It will do only
what it is programmed for, based on a clear regex-based semantics.

Independently on how easy/hard it would be to use a multi-line pattern
for this, what it is required is a clear non-hint based pattern that
will provide a match for a part of the tag that should be escaped
from normal parsing rules. The m/::$/ is a clear rule.

Do you have a proposal for some other rule? If so, I can see how
feasible is to add it there.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 01:38:38 -0700
Christoph Hellwig  escreveu:

> >   * Use either while holding wait_queue_head::lock or when used for wakeups
> > - * with an extra smp_mb() like:
> > + * with an extra smp_mb() like::  
> 
> Independent of any philosophical discussion not allowing a setence to
> end with a single ':' is completely idiotic.  Please fix the tooling
> instead to allow it, as it is very important for being able to just
> write understandable comments.

Patches are welcome, although I don't see any easy way to solve it.

In English, the common case is that a line with ends with a colon is
followed by a list. E. g.

foo:
  - bar1;
  - bar2.

However, in this specific case, it is followed by an ascii artwork. 
The double colon is a notation that tells Sphinx to not parse the
lines at the next block, placing the contents of it inside a literal
block. It is used also when the next lines contain a code example,
in order to avoid parsing things like @, () and * inside the code 
block.

The kernel-doc tool might eventually have some parsing logic that
would replace something to a '::' before sending it to Sphinx.
It could, for example, have a "hint" regex that would expect a
certain sequence of characters to be at the last line, like:

s/ascii\s+artwork.*:/ascii artwork.*::/
or
s/code\s+block.*:/code block.*::/

Then, change the kernel-doc comment to use it, like:

 * with an extra smp_mb() like shown at the following ascii artwork:

but IMHO, this is a lot worse than "::": it would be more intrusive
and more error-prune.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 04/11] docs: dell_rbu.txt: fix location of request_firmware

[Mauro Carvalho Chehab]

Em Wed,  9 May 2018 10:18:47 -0300
Mauro Carvalho Chehab <mchehab+sams...@kernel.org> escreveu:

> commit 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
> and other commits renamed the old firmware_class.c file and split it
> into separate files, but documentation was not changed accordingly,
> causing Sphinx errors.
> 
> Fixes for other files were already applied but dell_rbu.txt remains
> pointing to the old location.
> 
> Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
> Cc: Kees Cook <keesc...@chromium.org>
> Cc: Luis R. Rodriguez <mcg...@kernel.org>
> Cc: Greg Kroah-Hartman <gre...@linuxfoundation.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
> ---
>  Documentation/dell_rbu.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
> index 0fdb6aa2704c..befeff80e7ec 100644
> --- a/Documentation/dell_rbu.txt
> +++ b/Documentation/dell_rbu.txt
> @@ -121,8 +121,8 @@ read back the image downloaded.
>  
>  .. note::
>  
> -   This driver requires a patch for firmware_class.c which has the modified
> -   request_firmware_nowait function.
> +   This driver requires a patch for drivers/base/firmware_loader/main.c
> +   which has the modified request_firmware_nowait() function.

Please ignore this one. Luis send a patch updating it just removing this
comment, as it is outdated.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 08/11] docs: refcount-vs-atomic.rst: prefix url with https

[Mauro Carvalho Chehab]

Em Wed, 9 May 2018 15:43:19 +0200
Andrea Parri <andrea.pa...@amarulasolutions.com> escreveu:

> Hi Mauro,
> 
> On Wed, May 09, 2018 at 10:18:51AM -0300, Mauro Carvalho Chehab wrote:
> > There's a github URL there, but it is not prefixed by https.
> > Add a prefix, to avoid false-positives with:
> > ./scripts/documentation-file-ref-check
> > 
> > As a side effect, Sphinx should also generate a cross-ref.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> 
> There seems to be a "conflicting" patch ("applied" according to Jon):
> 
> 
> http://lkml.kernel.org/r/1525468309-5310-1-git-send-email-andrea.pa...@amarulasolutions.com
> 
> Let me stress here that the github repo. is out-of-date (and we have
> no plans to keep that in sync with mainline).

Good! One less patch pending :-)

Yeah, it seems that Jon pushed it from his repository today. I did a new
git remote update and I'm now seeing this one too.

> 
>   Andrea
> 
> 
> > ---
> >  Documentation/core-api/refcount-vs-atomic.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
> > b/Documentation/core-api/refcount-vs-atomic.rst
> > index 83351c258cdb..185d659e350a 100644
> > --- a/Documentation/core-api/refcount-vs-atomic.rst
> > +++ b/Documentation/core-api/refcount-vs-atomic.rst
> > @@ -17,7 +17,7 @@ in order to help maintainers validate their code against 
> > the change in
> >  these memory ordering guarantees.
> >  
> >  The terms used through this document try to follow the formal LKMM defined 
> > in
> > -github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> > +https://github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
> >  
> >  memory-barriers.txt and atomic_t.txt provide more background to the
> >  memory ordering in general and for atomic operations specifically.
> > -- 
> > 2.17.0
> >   



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Mauro Carvalho Chehab]

Em Wed, 9 May 2018 14:22:21 +0200
Boris Brezillon <boris.brezil...@bootlin.com> escreveu:

> On Wed, 9 May 2018 09:10:34 -0300
> Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> 
> > Hi Boris,
> > 
> > Em Mon, 7 May 2018 08:32:32 -0300
> > Mauro Carvalho Chehab <mchehab+sams...@kernel.org> escreveu:
> >   
> > > Hi Boris,
> > > 
> > > Em Mon, 7 May 2018 11:46:50 +0200
> > > Boris Brezillon <boris.brezil...@bootlin.com> escreveu:
> >   
> > > > Is there a simple
> > > > way we can get rid of the warning we have when not describing timings
> > > > but all of its fields?  
> > > 
> > > There's no direct way. It won't be hard to add a way to do it,
> > > like applying the enclosed patch with ends by declaring timings as:
> > > 
> > >   * @timings:  -- undescribed --
> > > 
> > > IMHO, this is uglier.
> > 
> > Didn't hear from you.  
> 
> I replied just a few minutes ago ;).

OK!

> > What do you prefer for me to do with regards to
> > this patch?   
> 
> Will queue the initial patch to nand/next (I can also queue it to the
> fixes branch if you prefer).

No need. it can follow the usual workflow.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 01/11] docs: can.rst: fix a footnote reference

[Mauro Carvalho Chehab]

As stated at:

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#footnotes

A footnote should contain either a number, a reference or
an auto number, e. g.:
[1], [#f1] or [#].

While using [*] accidentaly works for html, it fails for other
document outputs. In particular, it causes an error with LaTeX
output, causing all books after networking to not be built.

So, replace it by a valid syntax.

Acked-by: Oliver Hartkopp <socket...@hartkopp.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/networking/can.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
index d23c51abf8c6..2fd0b51a8c52 100644
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -164,7 +164,7 @@ The Linux network devices (by default) just can handle the
 transmission and reception of media dependent frames. Due to the
 arbitration on the CAN bus the transmission of a low prio CAN-ID
 may be delayed by the reception of a high prio CAN frame. To
-reflect the correct [*]_ traffic on the node the loopback of the sent
+reflect the correct [#f1]_ traffic on the node the loopback of the sent
 data has to be performed right after a successful transmission. If
 the CAN network interface is not capable of performing the loopback for
 some reason the SocketCAN core can do this task as a fallback solution.
@@ -175,7 +175,7 @@ networking behaviour for CAN applications. Due to some 
requests from
 the RT-SocketCAN group the loopback optionally may be disabled for each
 separate socket. See sockopts from the CAN RAW sockets in 
:ref:`socketcan-raw-sockets`.
 
-.. [*] you really like to have this when you're running analyser
+.. [#f1] you really like to have this when you're running analyser
tools like 'candump' or 'cansniffer' on the (same) node.
 
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 08/11] docs: refcount-vs-atomic.rst: prefix url with https

[Mauro Carvalho Chehab]

There's a github URL there, but it is not prefixed by https.
Add a prefix, to avoid false-positives with:
./scripts/documentation-file-ref-check

As a side effect, Sphinx should also generate a cross-ref.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/core-api/refcount-vs-atomic.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/core-api/refcount-vs-atomic.rst 
b/Documentation/core-api/refcount-vs-atomic.rst
index 83351c258cdb..185d659e350a 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the 
change in
 these memory ordering guarantees.
 
 The terms used through this document try to follow the formal LKMM defined in
-github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
+https://github.com/aparri/memory-model/blob/master/Documentation/explanation.txt
 
 memory-barriers.txt and atomic_t.txt provide more background to the
 memory ordering in general and for atomic operations specifically.
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 03/11] docs: crypto_engine.rst: Fix two parse warnings

[Mauro Carvalho Chehab]

./Documentation/crypto/crypto_engine.rst:13: WARNING: Unexpected indentation.
./Documentation/crypto/crypto_engine.rst:15: WARNING: Block quote ends without 
a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/crypto/crypto_engine.rst | 8 +---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/crypto/crypto_engine.rst 
b/Documentation/crypto/crypto_engine.rst
index 8272ac92a14f..1d56221dfe35 100644
--- a/Documentation/crypto/crypto_engine.rst
+++ b/Documentation/crypto/crypto_engine.rst
@@ -8,11 +8,13 @@ The crypto engine API (CE), is a crypto queue manager.
 
 Requirement
 ---
-You have to put at start of your tfm_ctx the struct crypto_engine_ctx
-struct your_tfm_ctx {
+You have to put at start of your tfm_ctx the struct crypto_engine_ctx::
+
+  struct your_tfm_ctx {
 struct crypto_engine_ctx enginectx;
 ...
-};
+  };
+
 Why: Since CE manage only crypto_async_request, it cannot know the underlying
 request_type and so have access only on the TFM.
 So using container_of for accessing __ctx is impossible.
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 07/11] docs: ranoops.rst: fix location of ramoops.txt

[Mauro Carvalho Chehab]

The location of the dt bindings file is wrong: it was probably
badly renamed by some script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/admin-guide/ramoops.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/ramoops.rst 
b/Documentation/admin-guide/ramoops.rst
index 4efd7ce77565..6dbcc5481000 100644
--- a/Documentation/admin-guide/ramoops.rst
+++ b/Documentation/admin-guide/ramoops.rst
@@ -61,7 +61,7 @@ Setting the ramoops parameters can be done in several 
different manners:
mem=128M ramoops.mem_address=0x800 ramoops.ecc=1
 
  B. Use Device Tree bindings, as described in
- 
``Documentation/device-tree/bindings/reserved-memory/admin-guide/ramoops.rst``.
+ ``Documentation/devicetree/bindings/reserved-memory/ramoops.txt``.
  For example::
 
reserved-memory {
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 04/11] docs: dell_rbu.txt: fix location of request_firmware

[Mauro Carvalho Chehab]

commit 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
and other commits renamed the old firmware_class.c file and split it
into separate files, but documentation was not changed accordingly,
causing Sphinx errors.

Fixes for other files were already applied but dell_rbu.txt remains
pointing to the old location.

Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
Cc: Kees Cook <keesc...@chromium.org>
Cc: Luis R. Rodriguez <mcg...@kernel.org>
Cc: Greg Kroah-Hartman <gre...@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/dell_rbu.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
index 0fdb6aa2704c..befeff80e7ec 100644
--- a/Documentation/dell_rbu.txt
+++ b/Documentation/dell_rbu.txt
@@ -121,8 +121,8 @@ read back the image downloaded.
 
 .. note::
 
-   This driver requires a patch for firmware_class.c which has the modified
-   request_firmware_nowait function.
+   This driver requires a patch for drivers/base/firmware_loader/main.c
+   which has the modified request_firmware_nowait() function.
 
Also after updating the BIOS image a user mode application needs to execute
code which sends the BIOS update request to the BIOS. So on the next reboot
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 05/11] docs: uio-howto.rst: use a code block to solve a warning

[Mauro Carvalho Chehab]

/devel/v4l/docs/Documentation/driver-api/uio-howto.rst:715: WARNING: Unexpected 
indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/driver-api/uio-howto.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/uio-howto.rst 
b/Documentation/driver-api/uio-howto.rst
index 92056c20e070..fb2eb73be4a3 100644
--- a/Documentation/driver-api/uio-howto.rst
+++ b/Documentation/driver-api/uio-howto.rst
@@ -711,7 +711,8 @@ The vmbus device regions are mapped into uio device 
resources:
 
 If a subchannel is created by a request to host, then the uio_hv_generic
 device driver will create a sysfs binary file for the per-channel ring buffer.
-For example:
+For example::
+

/sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring
 
 Further information
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 06/11] scripts/documentation-file-ref-check: rewrite it in perl with auto-fix mode

[Mauro Carvalho Chehab]

The original shell script works, but:
1) it is too slow;
2) it is hard to exclude rejex patterns

Convert it to perl.

Here, the new version is able to check the entire tree in
less than a second (after cached):

real0m0,284s
user0m0,668s
sys 0m0,778s

The old version takes more than a minute to complete (also
after cached):
real1m17,905s
user0m25,583s
sys 0m55,334s

It also produce less false-positives (if any).

The new script also contains an auto-fix mode.

Usually, file references get lost when they're moved to some other
place and/or renamed to .rst.

Add an experimental mode to auto-fix those.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 scripts/documentation-file-ref-check | 125 ---
 1 file changed, 113 insertions(+), 12 deletions(-)

diff --git a/scripts/documentation-file-ref-check 
b/scripts/documentation-file-ref-check
index bc1659900e89..2520bc14ffac 100755
--- a/scripts/documentation-file-ref-check
+++ b/scripts/documentation-file-ref-check
@@ -1,15 +1,116 @@
-#!/bin/sh
+#!/usr/bin/env perl
+# SPDX-License-Identifier: GPL-2.0
+#
 # Treewide grep for references to files under Documentation, and report
 # non-existing files in stderr.
 
-for f in $(git ls-files); do
-   for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do
-   # presume trailing . and , are not part of the name
-   ref=${ref%%[.,]}
-
-   # use ls to handle wildcards
-   if ! ls $ref >/dev/null 2>&1; then
-   echo "$f: $ref" >&2
-   fi
-   done
-done
+use warnings;
+use strict;
+use Getopt::Long qw(:config no_auto_abbrev);
+
+my $scriptname = $0;
+$scriptname =~ s,.*/([^/]+/),$1,;
+
+# Parse arguments
+my $help = 0;
+my $fix = 0;
+
+GetOptions(
+   'fix' => \$fix,
+   'h|help|usage' => \$help,
+);
+
+if ($help != 0) {
+print "$scriptname [--help] [--fix-rst]\n";
+exit -1;
+}
+
+# Step 1: find broken references
+print "Finding broken references. This may take a while...  " if ($fix);
+
+my %broken_ref;
+
+open IN, "git grep 'Documentation/'|"
+ or die "Failed to run git grep";
+while () {
+   next if (!m/^([^:]+):(.*)/);
+
+   my $f = $1;
+   my $ln = $2;
+
+   # Makefiles contain nasty expressions to parse docs
+   next if ($f =~ m/Makefile/);
+   # Skip this script
+   next if ($f eq $scriptname);
+
+   if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*+-]*),) {
+   my $prefix = $1;
+   my $ref = $2;
+   my $base = $2;
+
+   $ref =~ s/[\,\.]+$//;
+
+   my $fulref = "$prefix$ref";
+
+   $fulref =~ s/^(\<file|ref)://;
+   $fulref =~ s/^[\'\`]+//;
+   $fulref =~ s,^\$\(.*\)/,,;
+   $base =~ s,.*/,,;
+
+   # Remove URL false-positives
+   next if ($fulref =~ m/^http/);
+
+   # Check if exists, evaluating wildcards
+   next if (grep -e, glob("$ref $fulref"));
+
+   if ($fix) {
+   if (!($ref =~ m/(devicetree|scripts|Kconfig|Kbuild)/)) {
+   $broken_ref{$ref}++;
+   }
+   } else {
+   print STDERR "$f: $fulref\n";
+   }
+   }
+}
+
+exit 0 if (!$fix);
+
+# Step 2: Seek for file name alternatives
+print "Auto-fixing broken references. Please double-check the results\n";
+
+foreach my $ref (keys %broken_ref) {
+   my $new =$ref;
+
+   # get just the basename
+   $new =~ s,.*/,,;
+
+   # Seek for the same name on another place, as it may have been moved
+   my $f="";
+
+   $f = qx(find . -iname $new) if ($new);
+
+   # usual reason for breakage: file renamed to .rst
+   if (!$f) {
+   $new =~ s/\.txt$/.rst/;
+   $f=qx(find . -iname $new) if ($new);
+   }
+
+   my @find = split /\s+/, $f;
+
+   if (!$f) {
+   print STDERR "ERROR: Didn't find a replacement for $ref\n";
+   } elsif (scalar(@find) > 1) {
+   print STDERR "WARNING: Won't auto-replace, as found multiple 
files close to $ref:\n";
+   foreach my $j (@find) {
+   $j =~ s,^./,,;
+   print STDERR "$j\n";
+   }
+   } else {
+   $f = $find[0];
+   $f =~ s,^./,,;
+   print "INFO: Replacing $ref to $f\n";
+   foreach my $j (qx(git grep -l $ref)) {
+   qx(sed "s\@$ref\@$f\@g" -i $j);
+   }
+   }
+}
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 11/11] docs: fix broken references with multiple hints

[Mauro Carvalho Chehab]

The script:
./scripts/documentation-file-ref-check --fix-rst

Gives multiple hints for broken references on some files.
Manually use the one that applies for some files.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/ABI/obsolete/sysfs-gpio | 2 +-
 .../devicetree/bindings/display/bridge/tda998x.txt| 2 +-
 Documentation/trace/events.rst| 2 +-
 Documentation/trace/tracepoint-analysis.rst   | 2 +-
 Documentation/translations/zh_CN/SubmittingDrivers| 2 +-
 Documentation/translations/zh_CN/gpio.txt | 4 ++--
 MAINTAINERS   | 2 +-
 drivers/hid/usbhid/Kconfig| 2 +-
 drivers/input/Kconfig | 4 ++--
 drivers/input/joystick/Kconfig| 4 ++--
 drivers/input/joystick/iforce/Kconfig | 2 +-
 drivers/input/serio/Kconfig   | 4 ++--
 drivers/staging/fsl-mc/bus/dpio/dpio-driver.txt   | 2 +-
 drivers/video/fbdev/skeletonfb.c  | 8 
 include/linux/tracepoint.h| 2 +-
 security/device_cgroup.c  | 2 +-
 16 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/Documentation/ABI/obsolete/sysfs-gpio 
b/Documentation/ABI/obsolete/sysfs-gpio
index 32513dc2eec9..40d41ea1a3f5 100644
--- a/Documentation/ABI/obsolete/sysfs-gpio
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -11,7 +11,7 @@ Description:
   Kernel code may export it for complete or partial access.
 
   GPIOs are identified as they are inside the kernel, using integers in
-  the range 0..INT_MAX.  See Documentation/gpio/gpio.txt for more information.
+  the range 0..INT_MAX.  See Documentation/gpio for more information.
 
 /sys/class/gpio
/export ... asks the kernel to export a GPIO to userspace
diff --git a/Documentation/devicetree/bindings/display/bridge/tda998x.txt 
b/Documentation/devicetree/bindings/display/bridge/tda998x.txt
index 24cc2466185a..3484af33c879 100644
--- a/Documentation/devicetree/bindings/display/bridge/tda998x.txt
+++ b/Documentation/devicetree/bindings/display/bridge/tda998x.txt
@@ -27,7 +27,7 @@ Optional properties:
in question is used. The implementation allows one or two DAIs. If two
DAIs are defined, they must be of different type.
 
-[1] Documentation/sound/alsa/soc/DAI.txt
+[1] Documentation/sound/soc/dai.rst
 [2] include/dt-bindings/display/tda998x.h
 
 Example:
diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst
index 7b6b1236ec2e..c292117b83a9 100644
--- a/Documentation/trace/events.rst
+++ b/Documentation/trace/events.rst
@@ -8,7 +8,7 @@ Event Tracing
 1. Introduction
 ===
 
-Tracepoints (see Documentation/trace/tracepoints.txt) can be used
+Tracepoints (see Documentation/trace/tracepoints.rst) can be used
 without creating custom kernel modules to register probe functions
 using the event tracing infrastructure.
 
diff --git a/Documentation/trace/tracepoint-analysis.rst 
b/Documentation/trace/tracepoint-analysis.rst
index b0c9c21f129d..716326b9f152 100644
--- a/Documentation/trace/tracepoint-analysis.rst
+++ b/Documentation/trace/tracepoint-analysis.rst
@@ -6,7 +6,7 @@ Notes on Analysing Behaviour Using Events and Tracepoints
 1. Introduction
 ===
 
-Tracepoints (see Documentation/trace/tracepoints.txt) can be used without
+Tracepoints (see Documentation/trace/tracepoints.rst) can be used without
 creating custom kernel modules to register probe functions using the event
 tracing infrastructure.
 
diff --git a/Documentation/translations/zh_CN/SubmittingDrivers 
b/Documentation/translations/zh_CN/SubmittingDrivers
index 929385e4b194..15e73562f710 100644
--- a/Documentation/translations/zh_CN/SubmittingDrivers
+++ b/Documentation/translations/zh_CN/SubmittingDrivers
@@ -107,7 +107,7 @@ Linux 2.6:
程序测试的指导，请参阅
Documentation/power/drivers-testing.txt。有关驱动程序电
源管理问题相对全面的概述，请参阅
-   Documentation/power/admin-guide/devices.rst。
+   Documentation/driver-api/pm/devices.rst。
 
 管理：如果一个驱动程序的作者还在进行有效的维护，那么通常除了那
些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会
diff --git a/Documentation/translations/zh_CN/gpio.txt 
b/Documentation/translations/zh_CN/gpio.txt
index 4f8bf30a41dc..4cb1ba8b8fed 100644
--- a/Documentation/translations/zh_CN/gpio.txt
+++ b/Documentation/translations/zh_CN/gpio.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/gpio.txt
+Chinese translated version of Documentation/gpio
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -10,7 +10,7 @@ Maintainer: Grant Likely <grant.lik...@secretlab.ca>
Linus Walleij <linus.wal

[PATCH v2 10/11] arch/*: Kconfig: fix documentation for NMI watchdog

[Mauro Carvalho Chehab]

Changeset 9919cba7ff71 ("watchdog: Update documentation") updated
the documentation, removing the old nmi_watchdog.txt and adding
a file with a new content.

Update Kconfig files accordingly.

Fixes: 9919cba7ff71 ("watchdog: Update documentation")

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 arch/arm/Kconfig| 2 +-
 arch/parisc/Kconfig | 2 +-
 arch/sh/Kconfig | 2 +-
 arch/sparc/Kconfig  | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index a7f8e7f4b88f..7b4fa8356978 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -1305,7 +1305,7 @@ config SMP
  will run faster if you say N here.
 
  See also ,
-  and the SMP-HOWTO available at
+  and the SMP-HOWTO available 
at
  <http://tldp.org/HOWTO/SMP-HOWTO.html>.
 
  If you don't know what to do here, say N.
diff --git a/arch/parisc/Kconfig b/arch/parisc/Kconfig
index fc5a574c3482..b6823215cc9a 100644
--- a/arch/parisc/Kconfig
+++ b/arch/parisc/Kconfig
@@ -279,7 +279,7 @@ config SMP
  machines, but will use only one CPU of a multiprocessor machine.
  On a uniprocessor machine, the kernel will run faster if you say N.
 
- See also  and the SMP-HOWTO
+ See also  and the SMP-HOWTO
  available at <http://www.tldp.org/docs.html#howto>.
 
  If you don't know what to do here, say N.
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index 97fe29316476..bf628dd7c195 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -689,7 +689,7 @@ config SMP
  People using multiprocessor machines who say Y here should also say
  Y to "Enhanced Real Time Clock Support", below.
 
- See also  and the SMP-HOWTO
+ See also  and the SMP-HOWTO
  available at <http://www.tldp.org/docs.html#howto>.
 
  If you don't know what to do here, say N.
diff --git a/arch/sparc/Kconfig b/arch/sparc/Kconfig
index 8767e45f1b2b..66171c2e428b 100644
--- a/arch/sparc/Kconfig
+++ b/arch/sparc/Kconfig
@@ -189,7 +189,7 @@ config SMP
  Y to "Enhanced Real Time Clock Support", below. The "Advanced Power
  Management" code will be disabled if you say Y here.
 
- See also  and the SMP-HOWTO
+ See also  and the SMP-HOWTO
  available at <http://www.tldp.org/docs.html#howto>.
 
  If you don't know what to do here, say N.
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 02/11] docs: admin-guide: add cgroup-v2 documentation

[Mauro Carvalho Chehab]

The cgroup-v2.txt is already in ReST format. So, move it to the
admin-guide, where it belongs.

Cc: Tejun Heo <t...@kernel.org>
Cc: Li Zefan <lize...@huawei.com>
Cc: Johannes Weiner <han...@cmpxchg.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/00-INDEX | 2 --
 Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} | 0
 Documentation/admin-guide/index.rst| 1 +
 3 files changed, 1 insertion(+), 2 deletions(-)
 rename Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} (100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index a50d2380b6fb..2754fe83f0d4 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -80,8 +80,6 @@ cdrom/
- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
- cgroups v1 features, including cpusets and memory controller.
-cgroup-v2.txt
-   - cgroups v2 features, including cpusets and memory controller.
 cma/
- Continuous Memory Area (CMA) debugfs interface.
 conf.py
diff --git a/Documentation/cgroup-v2.txt 
b/Documentation/admin-guide/cgroup-v2.rst
similarity index 100%
rename from Documentation/cgroup-v2.txt
rename to Documentation/admin-guide/cgroup-v2.rst
diff --git a/Documentation/admin-guide/index.rst 
b/Documentation/admin-guide/index.rst
index 52eb3408f9a0..48d70af11652 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -48,6 +48,7 @@ configure specific aspects of kernel behavior to your liking.
:maxdepth: 1
 
initrd
+   cgroup-v2
serial-console
braille-console
parport
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 00/11] Fix some doc build warnings/errors and broken links

[Mauro Carvalho Chehab]

Hi Jon,

Patches 1 to 5 on this series contain the patches that weren't yet
applied from the past patch series and touch only at Documentation.
There are two changes there:
  patch 2: fixed the description and added a c/c to cgroup maintainers;
  patch 4: rewritten according with Louis request, droping several hunks.

Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
adding an auto-fix feature.

Before doing that, I made a shell script version, but there are
several false positives there that would require some regex
parsing to get rid. Also, performance was problematic: even
on an i7core with SSD M.2 disk, it was taking more than a minute
just to identify the errors. The perl version makes it in less
than a second and gives more reliable results.

It should be noticed that, as any other auto-fix tool, the
resuls of the fix should be validated.

The next 5 patches contain several fixes based on its results.

Patches 7 and 8 fix things that would cause troubles for the
automatic autocorrection tool.

Patch 9 touches a lot of random places (including MAINTAINERS)
that contain broken links and can be auto-fixed. It could be
broken into one patch per touched file, but I think that is
overkill. 

Patch 10 fixes the removal of nmi_watchdog.txt.

Patch 11 do some manual fixes on most of the places where
the automatic fix tool found multiple hints.

Ah, I noticed also several broken links on media. Those
were fixed on 3 separate patches, submitted to linux-media.
I intend to apply them via my own tree.

Regards,
Mauro


Mauro Carvalho Chehab (11):
  docs: can.rst: fix a footnote reference
  docs: admin-guide: add cgroup-v2 documentation
  docs: crypto_engine.rst: Fix two parse warnings
  docs: dell_rbu.txt: fix location of request_firmware
  docs: uio-howto.rst: use a code block to solve a warning
  scripts/documentation-file-ref-check: rewrite it in perl with auto-fix
mode
  docs: ranoops.rst: fix location of ramoops.txt
  docs: refcount-vs-atomic.rst: prefix url with https
  docs: Fix some broken references
  arch/*: Kconfig: fix documentation for NMI watchdog
  docs: fix broken references with multiple hints

 Documentation/00-INDEX|   2 -
 Documentation/ABI/obsolete/sysfs-gpio |   2 +-
 .../cgroup-v2.rst}|   0
 Documentation/admin-guide/index.rst   |   1 +
 .../admin-guide/kernel-parameters.txt |   4 +-
 Documentation/admin-guide/ramoops.rst |   2 +-
 Documentation/core-api/refcount-vs-atomic.rst |   2 +-
 Documentation/crypto/crypto_engine.rst|   8 +-
 Documentation/dell_rbu.txt|   4 +-
 .../bindings/display/bridge/tda998x.txt   |   2 +-
 .../bindings/input/rotary-encoder.txt |   2 +-
 Documentation/driver-api/gpio/consumer.rst|   2 +-
 Documentation/driver-api/uio-howto.rst|   3 +-
 Documentation/kprobes.txt |   4 +-
 Documentation/networking/can.rst  |   4 +-
 Documentation/trace/coresight.txt |   2 +-
 Documentation/trace/events.rst|   4 +-
 Documentation/trace/ftrace-uses.rst   |   2 +-
 Documentation/trace/histogram.txt |   2 +-
 Documentation/trace/intel_th.rst  |   2 +-
 Documentation/trace/tracepoint-analysis.rst   |   8 +-
 Documentation/translations/ja_JP/howto.rst|   4 +-
 .../translations/zh_CN/SubmittingDrivers  |   2 +-
 Documentation/translations/zh_CN/gpio.txt |   4 +-
 .../translations/zh_CN/magic-number.txt   |   4 +-
 .../zh_CN/video4linux/omap3isp.txt|   4 +-
 MAINTAINERS   |  22 +--
 arch/Kconfig  |   2 +-
 arch/arm/Kconfig  |   2 +-
 arch/arm/include/asm/cacheflush.h |   2 +-
 arch/arm64/include/asm/cacheflush.h   |   2 +-
 arch/microblaze/include/asm/cacheflush.h  |   2 +-
 arch/parisc/Kconfig   |   2 +-
 arch/sh/Kconfig   |   2 +-
 arch/sparc/Kconfig|   2 +-
 arch/um/Kconfig.um|   2 +-
 arch/unicore32/include/asm/cacheflush.h   |   2 +-
 arch/x86/entry/vsyscall/vsyscall_64.c |   2 +-
 arch/xtensa/include/asm/cacheflush.h  |   4 +-
 block/Kconfig |   2 +-
 certs/Kconfig |   2 +-
 crypto/asymmetric_keys/asymmetric_type.c  |   2 +-
 crypto/asymmetric_keys/signature.c|   2 +-
 drivers/char/Kconfig  |   2 +-
 drivers/clk/clk.c |   4 +-
 drivers/clk/ingenic/cgu.h |   2 +-
 drivers/gpu/vga/Kconfig   |   2 +-
 drivers/gpu/vga/vgaarb.c  |   2 +-
 drivers/hid/usbhid/Kconfig|   2 +-
 drivers/input/Kconfig |   4 +-
 drivers/input/joystick/Kconfig

[PATCH 3/3] media: v4l: fix broken video4linux docs locations

[Mauro Carvalho Chehab]

There are several places pointing to old documentation files:

  Documentation/video4linux/API.html
  Documentation/video4linux/bttv/
  Documentation/video4linux/cx2341x/fw-encoder-api.txt
  Documentation/video4linux/m5602.txt
  Documentation/video4linux/v4l2-framework.txt
  Documentation/video4linux/videobuf
  Documentation/video4linux/Zoran

Make them point to the new location where available, removing
otherwise.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 .../translations/zh_CN/video4linux/v4l2-framework.txt  |  6 +++---
 drivers/media/pci/bt8xx/Kconfig|  2 +-
 drivers/media/pci/cx18/cx18-streams.c  |  4 ++--
 drivers/media/pci/zoran/Kconfig|  2 +-
 drivers/media/radio/Kconfig| 10 +-
 drivers/media/radio/wl128x/Kconfig |  2 +-
 drivers/media/usb/gspca/m5602/Kconfig  |  2 --
 7 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt 
b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
index 698660b7f21f..054716a7ae77 100644
--- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/video4linux/v4l2-framework.txt
+Chinese translated version of Documentation/media/media_kapi.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Mauro Carvalho Chehab <mche...@infradead.org>
 Chinese maintainer: Fu Wei <tekkamanni...@gmail.com>
 -
-Documentation/video4linux/v4l2-framework.txt 的中文翻译
+Documentation/media/media_kapi.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
@@ -777,7 +777,7 @@ v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videob
 线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc
 分配的缓冲(videobuf-vmalloc)。
 
-请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf
+请参阅 Documentation/media/kapi/v4l2-videobuf.rst，以获得更多关于 videobuf
 层的使用信息。
 
 v4l2_fh 结构体
diff --git a/drivers/media/pci/bt8xx/Kconfig b/drivers/media/pci/bt8xx/Kconfig
index 4a93f6ded100..bc89e37608cd 100644
--- a/drivers/media/pci/bt8xx/Kconfig
+++ b/drivers/media/pci/bt8xx/Kconfig
@@ -16,7 +16,7 @@ config VIDEO_BT848
---help---
  Support for BT848 based frame grabber/overlay boards. This includes
  the Miro, Hauppauge and STB boards. Please read the material in
-  for more information.
+  for more information.
 
  To compile this driver as a module, choose M here: the
  module will be called bttv.
diff --git a/drivers/media/pci/cx18/cx18-streams.c 
b/drivers/media/pci/cx18/cx18-streams.c
index a594cfdeca20..b36f4ce25d22 100644
--- a/drivers/media/pci/cx18/cx18-streams.c
+++ b/drivers/media/pci/cx18/cx18-streams.c
@@ -853,7 +853,7 @@ int cx18_start_v4l2_encode_stream(struct cx18_stream *s)
 
/*
 * Audio related reset according to
-* Documentation/video4linux/cx2341x/fw-encoder-api.txt
+* Documentation/media/v4l-drivers/cx2341x.rst
 */
if (atomic_read(>ana_capturing) == 0)
cx18_vapi(cx, CX18_CPU_SET_MISC_PARAMETERS, 2,
@@ -861,7 +861,7 @@ int cx18_start_v4l2_encode_stream(struct cx18_stream *s)
 
/*
 * Number of lines for Field 1 & Field 2 according to
-* Documentation/video4linux/cx2341x/fw-encoder-api.txt
+* Documentation/media/v4l-drivers/cx2341x.rst
 * Field 1 is 312 for 625 line systems in BT.656
 * Field 2 is 313 for 625 line systems in BT.656
 */
diff --git a/drivers/media/pci/zoran/Kconfig b/drivers/media/pci/zoran/Kconfig
index 39ec35bd21a5..66c4c238ac0f 100644
--- a/drivers/media/pci/zoran/Kconfig
+++ b/drivers/media/pci/zoran/Kconfig
@@ -7,7 +7,7 @@ config VIDEO_ZORAN
  36057/36067 PCI controller chipset. This includes the Iomega
  Buz, Pinnacle DC10+ and the Linux Media Labs LML33. There is
  a driver homepage at <http://mjpeg.sf.net/driver-zoran/>. For
- more information, check .
+ more information, check 
.
 
  To compile this driver as a module, choose M here: the
  module will be called zr36067.
diff --git a/drivers/media/radio/Kconfig b/drivers/media/radio/Kconfig
index 8fa403c7149e..04ddd5057098 100644
--- a/drivers/media/radio/Kconfig
+++ b/drivers/media/radio/Kconfig
@@ -35,7 +35,7 @@ config RADIO_SI476X
  In order to control your radio card, you will need to use programs
  that are compatible

Re: [PATCH 18/18] w1: w1_io.c: fix a kernel-doc warning

[Mauro Carvalho Chehab]

Em Tue, 08 May 2018 14:03:39 +0300
Evgeniy Polyakov <z...@ioremap.net> escreveu:

> Hi
> 
> 07.05.2018, 12:36, "Mauro Carvalho Chehab" <mchehab+sams...@kernel.org>:
> > Add a blank line to avoid this Sphinx warning:
> > ./drivers/w1/w1_io.c:197: WARNING: Definition list ends without a 
> > blank line; unexpected unindent.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> 
> Looks good to me, thank you!
> What tree should this be forwarded to, or folks from linux doc will pick it 
> up?
> 
> Acked-by: Evgeniy Polyakov <z...@ioremap.net>

Jon prefers if this could go via the usual maintainer's tree.

So, could you send it via yours?

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 02/18] docs: fix location of request_firmware & friends

[Mauro Carvalho Chehab]

Em Tue, 8 May 2018 15:49:08 +
"Luis R. Rodriguez" <mcg...@kernel.org> escreveu:

> On Mon, May 07, 2018 at 06:35:38AM -0300, Mauro Carvalho Chehab wrote:
> > commit 5d6d1ddd2730 ("firmware: move firmware loader into its own 
> > directory")
> > and other commits renamed the old firmware_class.c file and split it
> > into separate files, but documentation was not changed accordingly,
> > causing Sphinx errors.
> > 
> > Change the location accordingly at the documentation files.
> > 
> > While here, add a missing entry at request_firmware.rst for
> > release_firmware() function.
> > 
> > Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own 
> > directory")
> > Cc: Kees Cook <keesc...@chromium.org>
> > Cc: Luis R. Rodriguez <mcg...@kernel.org>
> > Cc: Greg Kroah-Hartman <gre...@linuxfoundation.org>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
> > ---
> >  Documentation/dell_rbu.txt  |  4 ++--
> >  .../driver-api/firmware/fallback-mechanisms.rst |  2 +-
> >  .../driver-api/firmware/request_firmware.rst| 17 +++--
> >  Documentation/driver-api/infrastructure.rst |  2 +-
> >  Documentation/power/suspend-and-cpuhotplug.txt  |  2 +-
> >  5 files changed, 16 insertions(+), 11 deletions(-)
> > 
> > diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
> > index 0fdb6aa2704c..befeff80e7ec 100644
> > --- a/Documentation/dell_rbu.txt
> > +++ b/Documentation/dell_rbu.txt
> > @@ -121,8 +121,8 @@ read back the image downloaded.
> >  
> >  .. note::
> >  
> > -   This driver requires a patch for firmware_class.c which has the modified
> > -   request_firmware_nowait function.
> > +   This driver requires a patch for drivers/base/firmware_loader/main.c
> > +   which has the modified request_firmware_nowait() function.
> >  
> > Also after updating the BIOS image a user mode application needs to 
> > execute
> > code which sends the BIOS update request to the BIOS. So on the next 
> > reboot  
> 
> This part looks good and is needed.

Ok. I'll submit this as a separate patch.

> 
> > diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst 
> > b/Documentation/driver-api/firmware/fallback-mechanisms.rst
> > index f353783ae0be..7aed31b5a439 100644
> > --- a/Documentation/driver-api/firmware/fallback-mechanisms.rst
> > +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst
> > @@ -72,7 +72,7 @@ the firmware requested, and establishes it in the device 
> > hierarchy by
> >  associating the device used to make the request as the device's parent.
> >  The sysfs directory's file attributes are defined and controlled through
> >  the new device's class (firmware_class) and group (fw_dev_attr_groups).
> > -This is actually where the original firmware_class.c file name comes from,
> > +This is actually where drivers/base/firmware_loader/fallback.c comes from, 
> >  
> 
> Not this part.
> 
> What I meant to keep well documented here was not just only the old firmware
> file name for the code, but also the module name firmware_class, and its
> respective sysfs class name which is registered. From what I recall testing, 
> we
> could not rename the module now because of this. I believe it had to do with
> the modular case, given the sysfs class could still be registered.
> 
> The fact that I forget the exact *issue* which prevented the module rename 
> shows
> how important it is to document this.
> 
> Folks 10 years from now may wonder why the hell that name stuck, and the 
> point was
> to document that the *original* loader was the sysfs fallback mechanism.

Yeah, I was in doubt about this one too. Yet, IMHO, mentioning a filename
that got removed will also be problematic 10 years from now. Perhaps you 
could say something similar to:

Originally, the only firmware loading mechanism available was the
one that it is now used as fallback. The file containing it used
to be named after it, as firmware_class.c (nowadays, the fallback
mechanism is at drivers/base/firmware_loader/fallback.c).

This way, you keep providing the explanations while pointing to the new
location of the code.

Just my 2 cents.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Mauro Carvalho Chehab]

Hi Boris,

Em Mon, 7 May 2018 08:32:32 -0300
Mauro Carvalho Chehab <mchehab+sams...@kernel.org> escreveu:

> Hi Boris,
> 
> Em Mon, 7 May 2018 11:46:50 +0200
> Boris Brezillon <boris.brezil...@bootlin.com> escreveu:

> > Is there a simple
> > way we can get rid of the warning we have when not describing timings
> > but all of its fields?  
> 
> There's no direct way. It won't be hard to add a way to do it,
> like applying the enclosed patch with ends by declaring timings as:
> 
>   * @timings:  -- undescribed --
> 
> IMHO, this is uglier.

Didn't hear from you. What do you prefer for me to do with regards to
this patch? 

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 09/18] net: mac80211.h: fix a bad comment line

[Mauro Carvalho Chehab]

Em Mon, 07 May 2018 14:38:26 +0200
Johannes Berg <johan...@sipsolutions.net> escreveu:

> On Mon, 2018-05-07 at 15:37 +0300, Kalle Valo wrote:
> > Mauro Carvalho Chehab <mchehab+sams...@kernel.org> writes:
> >   
> > > Sphinx produces a lot of errors like this:
> > >   ./include/net/mac80211.h:2083: warning: bad line:  >
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> > 
> > Randy already submitted a similar patch:
> > 
> > https://patchwork.kernel.org/patch/10367275/
> > 
> > But it seems Johannes has not applied that yet.  
> 
> Yeah, I've been super busy preparing for the plugfest.
> 
> I'll make a pass over all the patches as soon as I can, hopefully today
> or tomorrow.

Thanks. I'll drop it from my patchset, assuming that you'll
be applying Randy's version or mine via your tree.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/18] docs: core-api: add cgroup-v2 documentation

[Mauro Carvalho Chehab]

Em Tue, 8 May 2018 09:51:14 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:

> On Mon,  7 May 2018 06:35:42 -0300
> Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> 
> > The cgroup-v2.txt is already in ReST format. So, move it to the
> > core-api guide, where it belongs.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> 
> Honestly, this seems to me like sysadmin material, so I think it should
> go into the admin guide instead.
> 
> Actually, looking at the patch, it seems you agree - it's just the
> changelog that's wrong :)

Yeah, wrong cut-and-paste. Sorry for that.

> I could fix that, but it should probably be posted with a CC to Tejun
> first.

I'll repost it c/c to cgroup maintainers with the right
description.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 15/18] iio: iio.h: use nested struct support on kernel-doc markup

[Mauro Carvalho Chehab]

Em Mon, 7 May 2018 18:08:03 +0100
Jonathan Cameron <ji...@kernel.org> escreveu:

> On Mon,  7 May 2018 06:35:51 -0300
> Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> 
> > Solve those Sphinx warnings:
> > 
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.sign' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.realbits' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.storagebits' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.shift' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.repeat' not described in 'iio_chan_spec'
> > ./include/linux/iio/iio.h:270: warning: Function parameter or member 
> > 'scan_type.endianness' not described in 'iio_chan_spec'
> > 
> > ./include/linux/iio/iio.h:191: WARNING: Unexpected indentation.
> > ./include/linux/iio/iio.h:192: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> >     ./include/linux/iio/iio.h:198: WARNING: Definition list ends without a 
> > blank line; unexpected unindent.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> Great thanks.  I couldn't figure out how to do this last time
> I looked at it.

Support for nested structs were only recently introduced :-)

> 
> Applied to the togreg branch of iio.git and pushed out as testing for
> the autobuilders to ignore it.

Thanks!
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()

[Mauro Carvalho Chehab]

Em Mon, 7 May 2018 07:23:22 -0700
"Paul E. McKenney" <paul...@linux.vnet.ibm.com> escreveu:

> On Mon, May 07, 2018 at 06:35:46AM -0300, Mauro Carvalho Chehab wrote:
> > The code example at rcupdate.h currently produce lots of warnings:
> > 
> > ./include/linux/rcupdate.h:572: WARNING: Unexpected indentation.
> > ./include/linux/rcupdate.h:576: WARNING: Unexpected indentation.
> > ./include/linux/rcupdate.h:580: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> > ./include/linux/rcupdate.h:582: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> > ./include/linux/rcupdate.h:582: WARNING: Inline literal start-string 
> > without end-string.
> > 
> > Change it to a code-block.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> 
> Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> 
> If you don't tell me otherwise, I will assume that you are pushing this.
> If you would rather that I take it, please let me know!

Hi Paul,

Feel free to merge it via your tree. It seems that Jon prefers to have
code changes merged via the usual maintainers.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Mauro Carvalho Chehab]

Em Tue, 08 May 2018 17:40:56 +0300
Jani Nikula <jani.nik...@linux.intel.com> escreveu:

> On Mon, 07 May 2018, Andrea Parri <andrea.pa...@amarulasolutions.com> wrote:
> > On Mon, May 07, 2018 at 06:35:41AM -0300, Mauro Carvalho Chehab wrote:  
> >> The cachetlb.txt is already in ReST format. So, move it to the
> >> core-api guide, where it belongs.
> >> 
> >> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
> >> ---
> >>  Documentation/00-INDEX| 2 --
> >>  Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
> >>  Documentation/core-api/index.rst  | 1 +
> >>  Documentation/memory-barriers.txt | 2 +-
> >>  Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
> >>  5 files changed, 3 insertions(+), 4 deletions(-)
> >>  rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)  
> >
> > I see a few "inline" references to the .txt file in -rc4 (see below):
> > I am not sure if you managed to update them too.  
> 
> Side note, there's scripts/documentation-file-ref-check to grep the
> kernel tree for things that look like file references to Documentation/*
> and complain if they don't exist.
> 
> I get about 350+ hits with that, patches welcome! ;)

This small script fixes a bunch of such errors:

scripts/documentation-file-ref-check 2>broken_refs
for i in $(cat broken_refs|cut -d: -f 2|grep -v 
devicetree|sort|uniq|grep \\.txt); do
rst=$(basename $i)
rst=${rst/.txt/.rst}
f=$(find . -name $rst)
f=${f#./}
if [ "$f" != "" ]; then
echo "Replacing $i to $f"
for j in $(git grep -l $i); do
sed "s@$i@$f@g" -i $j
done
fi
done

Thanks,
Mauro

[PATCH] docs: Fix some broken references

As we move stuff around, some doc references are broken. Fix some of
them via this script:

scripts/documentation-file-ref-check 2>broken_refs
for i in $(cat broken_refs|cut -d: -f 2|grep -v 
devicetree|sort|uniq|grep \\.txt); do
rst=$(basename $i)
rst=${rst/.txt/.rst}
f=$(find . -name $rst)
f=${f#./}
if [ "$f" != "" ]; then
echo "Replacing $i to $f"
for j in $(git grep -l $i); do
sed "s@$i@$f@g" -i $j
done
fi
done

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


diff --git a/Documentation/admin-guide/kernel-parameters.txt 
b/Documentation/admin-guide/kernel-parameters.txt
index 42f3e2884e7c..a7c4dfb573df 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4259,7 +4259,7 @@
[FTRACE] Set and start specified trace events in order
to facilitate early boot debugging. The event-list is a
comma separated list of trace events to enable. See
-   also Documentation/trace/events.txt
+   also Documentation/trace/events.rst
 
trace_options=[option-list]
[FTRACE] Enable or disable tracer options at boot.
@@ -4274,7 +4274,7 @@
 
  trace_options=stacktrace
 
-   See also Documentation/trace/ftrace.txt "trace options"
+   See also Documentation/trace/ftrace.rst "trace options"
section.
 
tp_printk[FTRACE]
diff --git a/Documentation/devicetree/bindings/input/rotary-encoder.txt 
b/Documentation/devicetree/bindings/input/rotary-encoder.txt
index f99fe5cdeaec..a644408b33b8 100644
--- a/Documentation/devicetree/bindings/input/rotary-encoder.txt
+++ b/Documentation/devicetree/bindings/input/rotary-encoder.txt
@@ -28,7 +28,7 @@ Deprecated properties:
   This property is deprecated. Instead, a 'steps-per-period ' value should
   be used, such as "rotary-encoder,steps-per-period = <2>".
 
-See Documentation/input/rotary-encoder.txt for more information.
+See Documentation/input/devices/rotary-encoder.rst for more information.
 
 Example:
 
diff --git a/Documentation/driver-api/gpio/consumer.rst 
b/Documentation/driver-api/gpio/consumer.rst
index c71a50d85b50..aa03f389d41d 100644
--- a/Documentation/driver-api/gpio/consumer.rst
+++ b/Documentation/driver-api/gpio/consumer.rst
@@ -57,7 +57,7 @@ device that displays digits), an additional index argument 
can be specified::

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Mauro Carvalho Chehab]

Em Tue, 8 May 2018 15:05:07 -0300
Mauro Carvalho Chehab <mchehab+sams...@kernel.org> escreveu:

> Em Tue, 08 May 2018 17:40:56 +0300
> Jani Nikula <jani.nik...@linux.intel.com> escreveu:
> 
> > On Mon, 07 May 2018, Andrea Parri <andrea.pa...@amarulasolutions.com> 
> > wrote:  
> > > On Mon, May 07, 2018 at 06:35:41AM -0300, Mauro Carvalho Chehab wrote:
> > >> The cachetlb.txt is already in ReST format. So, move it to the
> > >> core-api guide, where it belongs.
> > >> 
> > >> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
> > >> ---
> > >>  Documentation/00-INDEX| 2 --
> > >>  Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
> > >>  Documentation/core-api/index.rst  | 1 +
> > >>  Documentation/memory-barriers.txt | 2 +-
> > >>  Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
> > >>  5 files changed, 3 insertions(+), 4 deletions(-)
> > >>  rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)
> > >
> > > I see a few "inline" references to the .txt file in -rc4 (see below):
> > > I am not sure if you managed to update them too.
> > 
> > Side note, there's scripts/documentation-file-ref-check to grep the
> > kernel tree for things that look like file references to Documentation/*
> > and complain if they don't exist.
> > 
> > I get about 350+ hits with that, patches welcome! ;)  
> 
> This small script fixes a bunch of such errors:
> 
>   scripts/documentation-file-ref-check 2>broken_refs
>   for i in $(cat broken_refs|cut -d: -f 2|grep -v 
> devicetree|sort|uniq|grep \\.txt); do
>   rst=$(basename $i)
>   rst=${rst/.txt/.rst}
>   f=$(find . -name $rst)
>   f=${f#./}
>   if [ "$f" != "" ]; then
>   echo "Replacing $i to $f"
>   for j in $(git grep -l $i); do
>   sed "s@$i@$f@g" -i $j
>   done
>   fi
>   done

It follows an improvement to the above script that shows also what
it didn't find as a ReST file, and the ones that have common names
with multiple matches.

I guess we could integrate something like that at 
scripts/documentation-file-ref-check, in order to allow auto-correcting
renamed .txt files.

Regards,
Mauro


#!/bin/bash

scripts/documentation-file-ref-check 2>broken_refs
for i in $(cat broken_refs|cut -d: -f 2|grep -v devicetree|sort|uniq|grep 
\\.txt); do
rst=$(basename $i)
rst=${rst/.txt/.rst}
f=$(find . -name $rst)

if [ "$f" == "" ]; then
echo "ERROR: Didn't find a .rst replacement for $i"
elif [ "$(echo $f | grep ' ')" != "" ]; then
echo "ERROR: Found multiple possible replacements for $i:"
for j in $f; do
echo "$j"
done
else
echo "Replacing $i to $f"
f=${f#./}
for j in $(git grep -l $i); do
sed "s@$i@$f@g" -i $j
done
fi
done


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Mauro Carvalho Chehab]

Hi Boris,

Em Mon, 7 May 2018 11:46:50 +0200
Boris Brezillon <boris.brezil...@bootlin.com> escreveu:

> Hi Mauro,

> > diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
> > index 5dad59b31244..b986f94906df 100644
> > --- a/include/linux/mtd/rawnand.h
> > +++ b/include/linux/mtd/rawnand.h
> > @@ -740,8 +740,9 @@ enum nand_data_interface_type {
> >  
> >  /**
> >   * struct nand_data_interface - NAND interface timing
> > - * @type:  type of the timing
> > - * @timings:   The timing, type according to @type
> > + * @type:   type of the timing
> > + * @timings:The timing, type according to @type
> > + * @timings.sdr: Use it when @type is %NAND_SDR_IFACE.  
> 
> Hm, really feels weird to do that. I mean, either we describe
> timings.sdr or timings, but not both. I this case, I agree that
> describing timings.sdr would make more sense than generically
> describing any possible entries in the timings union.

This struct is funny, as the union has just one item. I assume
that the original intend is to be ready to have more timing
types (or you had it in the past). By the time you have a
second value there, describing the union would make more
sense.

> Is there a simple
> way we can get rid of the warning we have when not describing timings
> but all of its fields?

There's no direct way. It won't be hard to add a way to do it,
like applying the enclosed patch with ends by declaring timings as:

* @timings:  -- undescribed --

IMHO, this is uglier.

The way I see is that, if the embed struct/union is not interesting
enough to be described, the best would be to use an anonymous one like:

struct nand_data_interface {
enum nand_data_interface_type type;
union {
struct nand_sdr_timings sdr;
};
};

With the above, kernel-doc will expect a description just for @sdr.

Btw, if you want to see how nested struct/union is parsed, the
scripts/kernel_doc logic is at dump_struct() function.

When it finds an struct, it first handles private/public by simply
removing everything that it is not public from the struct, by a
very simple parser. Then, it converts nested struct/union into
un-nested ones. E. g. it converts:

struct {
union {
int foo1;
};
union {
int foo2;
} bar;
} foobar;

into this internal representation:

struct {
int foo1;
union;
int bar.foo2;
union bar;
};

Then it runs the normal un-nested struct parser.


Thanks,
Mauro

[PATCH] don't describe nested struct timings

IMHO, this is an ugly hack, but it allows having nested
structs (or fields) undescribed by purpose.

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

diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
index b986f94906df..b724c7edf532 100644
--- a/include/linux/mtd/rawnand.h
+++ b/include/linux/mtd/rawnand.h
@@ -741,7 +741,7 @@ enum nand_data_interface_type {
 /**
  * struct nand_data_interface - NAND interface timing
  * @type:   type of the timing
- * @timings:The timing, type according to @type
+ * @timings:-- undescribed --
  * @timings.sdr: Use it when @type is %NAND_SDR_IFACE.
  */
 struct nand_data_interface {
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0057d8eafcc1..196a2107c8c1 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -390,7 +390,7 @@ my $section = $section_default;
 my $section_context = "Context";
 my $section_return = "Return";
 
-my $undescribed = "-- undescribed --";
+my $undescribed = "-- undescribed --\n";
 
 reset_state();
 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 04/18] docs: admin-guide: add bcache documentation

[Mauro Carvalho Chehab]

The bcache.txt is already in ReST format. So, move it to the
admin guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/00-INDEX   | 2 --
 Documentation/{bcache.txt => admin-guide/bcache.rst} | 0
 Documentation/admin-guide/index.rst  | 1 +
 3 files changed, 1 insertion(+), 2 deletions(-)
 rename Documentation/{bcache.txt => admin-guide/bcache.rst} (100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 708dc4c166e4..53699c79ee54 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -64,8 +64,6 @@ auxdisplay/
- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
- directory with info on controlling backlights in flat panel displays
-bcache.txt
-   - Block-layer cache on fast SSDs to improve slow (raid) I/O performance.
 block/
- info on the Block I/O (BIO) layer.
 blockdev/
diff --git a/Documentation/bcache.txt b/Documentation/admin-guide/bcache.rst
similarity index 100%
rename from Documentation/bcache.txt
rename to Documentation/admin-guide/bcache.rst
diff --git a/Documentation/admin-guide/index.rst 
b/Documentation/admin-guide/index.rst
index cac906fb0ed0..52eb3408f9a0 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -60,6 +60,7 @@ configure specific aspects of kernel behavior to your liking.
mono
java
ras
+   bcache
pm/index
thunderbolt
LSM/index
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 06/18] docs: core-api: add cgroup-v2 documentation

[Mauro Carvalho Chehab]

The cgroup-v2.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/00-INDEX | 2 --
 Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} | 0
 Documentation/admin-guide/index.rst| 1 +
 3 files changed, 1 insertion(+), 2 deletions(-)
 rename Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} (100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 04074059bcdc..c6b81ef9827b 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -80,8 +80,6 @@ cdrom/
- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
- cgroups v1 features, including cpusets and memory controller.
-cgroup-v2.txt
-   - cgroups v2 features, including cpusets and memory controller.
 circular-buffers.txt
- how to make use of the existing circular buffer infrastructure
 clk.txt
diff --git a/Documentation/cgroup-v2.txt 
b/Documentation/admin-guide/cgroup-v2.rst
similarity index 100%
rename from Documentation/cgroup-v2.txt
rename to Documentation/admin-guide/cgroup-v2.rst
diff --git a/Documentation/admin-guide/index.rst 
b/Documentation/admin-guide/index.rst
index 52eb3408f9a0..48d70af11652 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -48,6 +48,7 @@ configure specific aspects of kernel behavior to your liking.
:maxdepth: 1
 
initrd
+   cgroup-v2
serial-console
braille-console
parport
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 08/18] docs: driver-api: add clk documentation

[Mauro Carvalho Chehab]

The clk.rst is already in ReST format. So, move it to the
driver-api guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/00-INDEX  | 2 --
 Documentation/admin-guide/kernel-parameters.txt | 2 +-
 Documentation/{clk.txt => driver-api/clk.rst}   | 0
 Documentation/driver-api/index.rst  | 1 +
 4 files changed, 2 insertions(+), 3 deletions(-)
 rename Documentation/{clk.txt => driver-api/clk.rst} (100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index a9dd1384d8e3..2754fe83f0d4 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -80,8 +80,6 @@ cdrom/
- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
- cgroups v1 features, including cpusets and memory controller.
-clk.txt
-   - info on the common clock framework
 cma/
- Continuous Memory Area (CMA) debugfs interface.
 conf.py
diff --git a/Documentation/admin-guide/kernel-parameters.txt 
b/Documentation/admin-guide/kernel-parameters.txt
index 865a24e4d516..42f3e2884e7c 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -518,7 +518,7 @@
those clocks in any way. This parameter is useful for
debug and development, but should not be needed on a
platform with proper driver support.  For more
-   information, see Documentation/clk.txt.
+   information, see Documentation/driver-api/clk.rst.
 
clock=  [BUGS=X86-32, HW] gettimeofday clocksource override.
[Deprecated]
diff --git a/Documentation/clk.txt b/Documentation/driver-api/clk.rst
similarity index 100%
rename from Documentation/clk.txt
rename to Documentation/driver-api/clk.rst
diff --git a/Documentation/driver-api/index.rst 
b/Documentation/driver-api/index.rst
index 3ac51c94f97b..5d04296f5ce0 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -17,6 +17,7 @@ available subsections can be seen below.
basics
infrastructure
pm/index
+   clk
device-io
device_connection
dma-buf
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 12/18] time: timer.c: adjust a kernel-doc comment

[Mauro Carvalho Chehab]

Those three warnings can easily solved by using :: to indicate a
code block:

./kernel/time/timer.c:1259: WARNING: Unexpected indentation.
./kernel/time/timer.c:1261: WARNING: Unexpected indentation.
./kernel/time/timer.c:1262: WARNING: Block quote ends without a blank 
line; unexpected unindent.

While here, align the lines at the block.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 kernel/time/timer.c | 14 +++---
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/kernel/time/timer.c b/kernel/time/timer.c
index 4a4fd567fb26..cc2d23e6ff61 100644
--- a/kernel/time/timer.c
+++ b/kernel/time/timer.c
@@ -1251,18 +1251,18 @@ EXPORT_SYMBOL(try_to_del_timer_sync);
  *
  * Note: For !irqsafe timers, you must not hold locks that are held in
  *   interrupt context while calling this function. Even if the lock has
- *   nothing to do with the timer in question.  Here's why:
+ *   nothing to do with the timer in question.  Here's why::
  *
  *CPU0 CPU1
  * 
- *   
- *   call_timer_fn();
- * base->running_timer = mytimer;
- *  spin_lock_irq(somelock);
+ * 
+ *   call_timer_fn();
+ *   base->running_timer = mytimer;
+ *spin_lock_irq(somelock);
  * 
  *spin_lock(somelock);
- *  del_timer_sync(mytimer);
- *   while (base->running_timer == mytimer);
+ *del_timer_sync(mytimer);
+ *while (base->running_timer == mytimer);
  *
  * Now del_timer_sync() will never return and never release somelock.
  * The interrupt on the other CPU is waiting to grab somelock but
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 03/18] docs: */index.rst: Add newer documents to their respective index.rst

[Mauro Carvalho Chehab]

A number of new docs were added, but they're currently not on
the index.rst from the session they're supposed to be, causing
Sphinx warnings.

Add them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/crypto/index.rst | 1 +
 Documentation/driver-api/index.rst | 1 +
 Documentation/process/index.rst| 1 +
 Documentation/security/index.rst   | 2 ++
 4 files changed, 5 insertions(+)

diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst
index 94c4786f2573..c4ff5d791233 100644
--- a/Documentation/crypto/index.rst
+++ b/Documentation/crypto/index.rst
@@ -20,5 +20,6 @@ for cryptographic use cases, as well as programming examples.
architecture
devel-algos
userspace-if
+   crypto_engine
api
api-samples
diff --git a/Documentation/driver-api/index.rst 
b/Documentation/driver-api/index.rst
index 6d8352c0f354..3ac51c94f97b 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -18,6 +18,7 @@ available subsections can be seen below.
infrastructure
pm/index
device-io
+   device_connection
dma-buf
device_link
message-based
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 1c9fe657ed01..37bd0628b6ee 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -52,6 +52,7 @@ lack of a better place.
adding-syscalls
magic-number
volatile-considered-harmful
+   clang-format
 
 .. only::  subproject and html
 
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 298a94a33f05..85492bfca530 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -9,5 +9,7 @@ Security Documentation
IMA-templates
keys/index
LSM
+   LSM-sctp
+   SELinux-sctp
self-protection
tpm/index
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 05/18] docs: core-api: add cachetlb documentation

[Mauro Carvalho Chehab]

The cachetlb.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/00-INDEX| 2 --
 Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
 Documentation/core-api/index.rst  | 1 +
 Documentation/memory-barriers.txt | 2 +-
 Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
 5 files changed, 3 insertions(+), 4 deletions(-)
 rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 53699c79ee54..04074059bcdc 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -76,8 +76,6 @@ bus-devices/
- directory with info on TI GPMC (General Purpose Memory Controller)
 bus-virt-phys-mapping.txt
- how to access I/O mapped memory from within device drivers.
-cachetlb.txt
-   - describes the cache/TLB flushing interfaces Linux uses.
 cdrom/
- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
diff --git a/Documentation/cachetlb.txt b/Documentation/core-api/cachetlb.rst
similarity index 100%
rename from Documentation/cachetlb.txt
rename to Documentation/core-api/cachetlb.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index c670a8031786..d4d71ee564ae 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -14,6 +14,7 @@ Core utilities
kernel-api
assoc_array
atomic_ops
+   cachetlb
refcount-vs-atomic
cpu_hotplug
idr
diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 6dafc8085acc..983249906fc6 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -2903,7 +2903,7 @@ is discarded from the CPU's cache and reloaded.  To deal 
with this, the
 appropriate part of the kernel must invalidate the overlapping bits of the
 cache on each CPU.
 
-See Documentation/cachetlb.txt for more information on cache management.
+See Documentation/core-api/cachetlb.rst for more information on cache 
management.
 
 
 CACHE COHERENCY VS MMIO
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt 
b/Documentation/translations/ko_KR/memory-barriers.txt
index 0a0930ab4156..081937577c1a 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -2846,7 +2846,7 @@ CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮
 문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는
 비트들을 무효화 시켜야 합니다.
 
-캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를
+캐시 관리에 대한 더 많은 정보를 위해선 Documentation/core-api/cachetlb.rst 를
 참고하세요.
 
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 02/18] docs: fix location of request_firmware & friends

[Mauro Carvalho Chehab]

commit 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
and other commits renamed the old firmware_class.c file and split it
into separate files, but documentation was not changed accordingly,
causing Sphinx errors.

Change the location accordingly at the documentation files.

While here, add a missing entry at request_firmware.rst for
release_firmware() function.

Fixes: 5d6d1ddd2730 ("firmware: move firmware loader into its own directory")
Cc: Kees Cook <keesc...@chromium.org>
Cc: Luis R. Rodriguez <mcg...@kernel.org>
Cc: Greg Kroah-Hartman <gre...@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/dell_rbu.txt  |  4 ++--
 .../driver-api/firmware/fallback-mechanisms.rst |  2 +-
 .../driver-api/firmware/request_firmware.rst| 17 +++--
 Documentation/driver-api/infrastructure.rst |  2 +-
 Documentation/power/suspend-and-cpuhotplug.txt  |  2 +-
 5 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
index 0fdb6aa2704c..befeff80e7ec 100644
--- a/Documentation/dell_rbu.txt
+++ b/Documentation/dell_rbu.txt
@@ -121,8 +121,8 @@ read back the image downloaded.
 
 .. note::
 
-   This driver requires a patch for firmware_class.c which has the modified
-   request_firmware_nowait function.
+   This driver requires a patch for drivers/base/firmware_loader/main.c
+   which has the modified request_firmware_nowait() function.
 
Also after updating the BIOS image a user mode application needs to execute
code which sends the BIOS update request to the BIOS. So on the next reboot
diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst 
b/Documentation/driver-api/firmware/fallback-mechanisms.rst
index f353783ae0be..7aed31b5a439 100644
--- a/Documentation/driver-api/firmware/fallback-mechanisms.rst
+++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst
@@ -72,7 +72,7 @@ the firmware requested, and establishes it in the device 
hierarchy by
 associating the device used to make the request as the device's parent.
 The sysfs directory's file attributes are defined and controlled through
 the new device's class (firmware_class) and group (fw_dev_attr_groups).
-This is actually where the original firmware_class.c file name comes from,
+This is actually where drivers/base/firmware_loader/fallback.c comes from,
 as originally the only firmware loading mechanism available was the
 mechanism we now use as a fallback mechanism.
 
diff --git a/Documentation/driver-api/firmware/request_firmware.rst 
b/Documentation/driver-api/firmware/request_firmware.rst
index cf4516dfbf96..8e34d29ea02d 100644
--- a/Documentation/driver-api/firmware/request_firmware.rst
+++ b/Documentation/driver-api/firmware/request_firmware.rst
@@ -17,19 +17,24 @@ an error is returned.
 
 request_firmware
 
-.. kernel-doc:: drivers/base/firmware_class.c
+.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware
 
 request_firmware_direct
 ---
-.. kernel-doc:: drivers/base/firmware_class.c
+.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_direct
 
 request_firmware_into_buf
 -
-.. kernel-doc:: drivers/base/firmware_class.c
+.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_into_buf
 
+release_firmware
+
+.. kernel-doc:: drivers/base/firmware_loader/main.c
+   :functions: release_firmware
+
 Asynchronous firmware requests
 ==
 
@@ -41,7 +46,7 @@ in atomic contexts.
 
 request_firmware_nowait
 ---
-.. kernel-doc:: drivers/base/firmware_class.c
+.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_nowait
 
 Special optimizations on reboot
@@ -54,8 +59,8 @@ this can be done with firmware_request_cache() insted of 
requesting for the
 firmare to be loaded.
 
 firmware_request_cache()

-.. kernel-doc:: drivers/base/firmware_class.c
+
+.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_cache
 
 request firmware API expected driver use
diff --git a/Documentation/driver-api/infrastructure.rst 
b/Documentation/driver-api/infrastructure.rst
index 6d9ff316b608..bee1b9a1702f 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -28,7 +28,7 @@ Device Drivers Base
 .. kernel-doc:: drivers/base/node.c
:internal:
 
-.. kernel-doc:: drivers/base/firmware_class.c
+.. kernel-doc:: drivers/base/firmware_loader/main.c
:export:
 
 .. kernel-doc:: drivers/base/transport_class.c
diff --git a/Documentation/power/suspend-and-cpuhotplug.txt 
b/Documentation/power/suspend-and-cpuhotplug.txt
index 31abd04b9572..6f55eb960a6d 100644
--- a/Document

[PATCH 14/18] fbdev: modedb.c: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Use code blocks to avoid those warnings and make it look nicer.

./drivers/video/fbdev/core/modedb.c:647: WARNING: Inline strong 
start-string without end-string.
./drivers/video/fbdev/core/modedb.c:647: WARNING: Inline strong 
start-string without end-string.
./drivers/video/fbdev/core/modedb.c:647: WARNING: Inline strong 
start-string without end-string.
./drivers/video/fbdev/core/modedb.c:647: WARNING: Inline strong 
start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 drivers/video/fbdev/core/modedb.c | 22 +++---
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/drivers/video/fbdev/core/modedb.c 
b/drivers/video/fbdev/core/modedb.c
index 2510fa728d77..7284324fbd77 100644
--- a/drivers/video/fbdev/core/modedb.c
+++ b/drivers/video/fbdev/core/modedb.c
@@ -642,23 +642,23 @@ static int fb_try_mode(struct fb_var_screeninfo *var, 
struct fb_info *info,
  * @default_mode fails, all modes in the video mode database will
  * be tried.
  *
- * Valid mode specifiers for @mode_option:
+ * Valid mode specifiers for @mode_option::
  *
- * x[M][R][-][@][i][m] or
- * [-][@]
+ *   x[M][R][-][@][i][m] or
+ *   [-][@]
  *
  * with , ,  and  decimal numbers and
  *  a string.
  *
- *  If 'M' is present after yres (and before refresh/bpp if present),
- *  the function will compute the timings using VESA(tm) Coordinated
- *  Video Timings (CVT).  If 'R' is present after 'M', will compute with
- *  reduced blanking (for flatpanels).  If 'i' is present, compute
- *  interlaced mode.  If 'm' is present, add margins equal to 1.8%
- *  of xres rounded down to 8 pixels, and 1.8% of yres. The char
- *  'i' and 'm' must be after 'M' and 'R'. Example:
+ * If 'M' is present after yres (and before refresh/bpp if present),
+ * the function will compute the timings using VESA(tm) Coordinated
+ * Video Timings (CVT).  If 'R' is present after 'M', will compute with
+ * reduced blanking (for flatpanels).  If 'i' is present, compute
+ * interlaced mode.  If 'm' is present, add margins equal to 1.8%
+ * of xres rounded down to 8 pixels, and 1.8% of yres. The char
+ * 'i' and 'm' must be after 'M' and 'R'. Example::
  *
- *  1024x768MR-8@60m - Reduced blank with margins at 60Hz.
+ *   1024x768MR-8@60m - Reduced blank with margins at 60Hz.
  *
  * NOTE: The passed struct @var is _not_ cleared!  This allows you
  * to supply values for e.g. the grayscale and accel_flags fields.
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 01/18] docs: can.rst: fix a footnote reference

[Mauro Carvalho Chehab]

As stated at:

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#footnotes

A footnote should contain either a number, a reference or
an auto number, e. g.:
[1], [#f1] or [#].

While using [*] accidentaly works for html, it fails for other
document outputs. In particular, it causes an error with LaTeX
output, causing all books after networking to not be built.

So, replace it by a valid syntax.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/networking/can.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
index d23c51abf8c6..2fd0b51a8c52 100644
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -164,7 +164,7 @@ The Linux network devices (by default) just can handle the
 transmission and reception of media dependent frames. Due to the
 arbitration on the CAN bus the transmission of a low prio CAN-ID
 may be delayed by the reception of a high prio CAN frame. To
-reflect the correct [*]_ traffic on the node the loopback of the sent
+reflect the correct [#f1]_ traffic on the node the loopback of the sent
 data has to be performed right after a successful transmission. If
 the CAN network interface is not capable of performing the loopback for
 some reason the SocketCAN core can do this task as a fallback solution.
@@ -175,7 +175,7 @@ networking behaviour for CAN applications. Due to some 
requests from
 the RT-SocketCAN group the loopback optionally may be disabled for each
 separate socket. See sockopts from the CAN RAW sockets in 
:ref:`socketcan-raw-sockets`.
 
-.. [*] you really like to have this when you're running analyser
+.. [#f1] you really like to have this when you're running analyser
tools like 'candump' or 'cansniffer' on the (same) node.
 
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 17/18] docs: uio-howto.rst: use a code block to solve a warning

[Mauro Carvalho Chehab]

/devel/v4l/docs/Documentation/driver-api/uio-howto.rst:715: WARNING: Unexpected 
indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/driver-api/uio-howto.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/uio-howto.rst 
b/Documentation/driver-api/uio-howto.rst
index 92056c20e070..fb2eb73be4a3 100644
--- a/Documentation/driver-api/uio-howto.rst
+++ b/Documentation/driver-api/uio-howto.rst
@@ -711,7 +711,8 @@ The vmbus device regions are mapped into uio device 
resources:
 
 If a subchannel is created by a request to host, then the uio_hv_generic
 device driver will create a sysfs binary file for the per-channel ring buffer.
-For example:
+For example::
+

/sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring
 
 Further information
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 07/18] docs: core-api: add circular-buffers documentation

[Mauro Carvalho Chehab]

The circular-buffers.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/00-INDEX  | 2 --
 .../{circular-buffers.txt => core-api/circular-buffers.rst} | 0
 Documentation/core-api/index.rst| 1 +
 Documentation/memory-barriers.txt   | 2 +-
 Documentation/translations/ko_KR/memory-barriers.txt| 2 +-
 5 files changed, 3 insertions(+), 4 deletions(-)
 rename Documentation/{circular-buffers.txt => core-api/circular-buffers.rst} 
(100%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index c6b81ef9827b..a9dd1384d8e3 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -80,8 +80,6 @@ cdrom/
- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
- cgroups v1 features, including cpusets and memory controller.
-circular-buffers.txt
-   - how to make use of the existing circular buffer infrastructure
 clk.txt
- info on the common clock framework
 cma/
diff --git a/Documentation/circular-buffers.txt 
b/Documentation/core-api/circular-buffers.rst
similarity index 100%
rename from Documentation/circular-buffers.txt
rename to Documentation/core-api/circular-buffers.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d4d71ee564ae..3864de589126 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -26,6 +26,7 @@ Core utilities
genalloc
errseq
printk-formats
+   circular-buffers
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 983249906fc6..33b8bc9573f8 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -3083,7 +3083,7 @@ CIRCULAR BUFFERS
 Memory barriers can be used to implement circular buffering without the need
 of a lock to serialise the producer with the consumer.  See:
 
-   Documentation/circular-buffers.txt
+   Documentation/core-api/circular-buffers.rst
 
 for details.
 
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt 
b/Documentation/translations/ko_KR/memory-barriers.txt
index 081937577c1a..2ec5fe0c9cf4 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -3023,7 +3023,7 @@ smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다.
 동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다.  더 자세한 내용을
 위해선 다음을 참고하세요:
 
-   Documentation/circular-buffers.txt
+   Documentation/core-api/circular-buffers.rst
 
 
 =
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups

[Mauro Carvalho Chehab]

Gets rid of those warnings and better document the parameters.

  ./include/linux/mtd/rawnand.h:752: warning: Function parameter or member 
'timings.sdr' not described in 'nand_data_interface'
  ./include/linux/mtd/rawnand.h:817: warning: Function parameter or member 
'buf' not described in 'nand_op_data_instr'
  ./include/linux/mtd/rawnand.h:817: warning: Function parameter or member 
'buf.in' not described in 'nand_op_data_instr'
  ./include/linux/mtd/rawnand.h:817: warning: Function parameter or member 
'buf.out' not described in 'nand_op_data_instr'
  ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
'ctx' not described in 'nand_op_instr'
  ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
'ctx.cmd' not described in 'nand_op_instr'
  ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
'ctx.addr' not described in 'nand_op_instr'
  ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
'ctx.data' not described in 'nand_op_instr'
  ./include/linux/mtd/rawnand.h:863: warning: Function parameter or member 
'ctx.waitrdy' not described in 'nand_op_instr'
  ./include/linux/mtd/rawnand.h:1010: warning: Function parameter or member 
'ctx' not described in 'nand_op_parser_pattern_elem'
  ./include/linux/mtd/rawnand.h:1010: warning: Function parameter or member 
'ctx.addr' not described in 'nand_op_parser_pattern_elem'
  ./include/linux/mtd/rawnand.h:1010: warning: Function parameter or member 
'ctx.data' not described in 'nand_op_parser_pattern_elem'
  ./include/linux/mtd/rawnand.h:1313: warning: Function parameter or member 
'manufacturer.desc' not described in 'nand_chip'
  ./include/linux/mtd/rawnand.h:1313: warning: Function parameter or member 
'manufacturer.priv' not described in 'nand_chip'

  ./include/linux/mtd/rawnand.h:848: WARNING: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 include/linux/mtd/rawnand.h | 26 ++
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
index 5dad59b31244..b986f94906df 100644
--- a/include/linux/mtd/rawnand.h
+++ b/include/linux/mtd/rawnand.h
@@ -740,8 +740,9 @@ enum nand_data_interface_type {
 
 /**
  * struct nand_data_interface - NAND interface timing
- * @type:  type of the timing
- * @timings:   The timing, type according to @type
+ * @type:   type of the timing
+ * @timings:The timing, type according to @type
+ * @timings.sdr: Use it when @type is %NAND_SDR_IFACE.
  */
 struct nand_data_interface {
enum nand_data_interface_type type;
@@ -798,8 +799,9 @@ struct nand_op_addr_instr {
 /**
  * struct nand_op_data_instr - Definition of a data instruction
  * @len: number of data bytes to move
- * @in: buffer to fill when reading from the NAND chip
- * @out: buffer to read from when writing to the NAND chip
+ * @buf: buffer to fill
+ * @buf.in: buffer to fill when reading from the NAND chip
+ * @buf.out: buffer to read from when writing to the NAND chip
  * @force_8bit: force 8-bit access
  *
  * Please note that "in" and "out" are inverted from the ONFI specification
@@ -842,9 +844,13 @@ enum nand_op_instr_type {
 /**
  * struct nand_op_instr - Instruction object
  * @type: the instruction type
- * @cmd/@addr/@data/@waitrdy: extra data associated to the instruction.
- *You'll have to use the appropriate element
- *depending on @type
+ * @ctx:  extra data associated to the instruction. You'll have to use the
+ *appropriate element depending on @type
+ * @ctx.cmd: use it if @type is %NAND_OP_CMD_INSTR
+ * @ctx.addr: use it if @type is %NAND_OP_ADDR_INSTR
+ * @ctx.data: use it if @type is %NAND_OP_DATA_IN_INSTR
+ *   or %NAND_OP_DATA_OUT_INSTR
+ * @ctx.waitrdy: use it if @type is %NAND_OP_WAITRDY_INSTR
  * @delay_ns: delay the controller should apply after the instruction has been
  *   issued on the bus. Most modern controllers have internal timings
  *   control logic, and in this case, the controller driver can ignore
@@ -997,7 +1003,9 @@ struct nand_op_parser_data_constraints {
  * struct nand_op_parser_pattern_elem - One element of a pattern
  * @type: the instructuction type
  * @optional: whether this element of the pattern is optional or mandatory
- * @addr/@data: address or data constraint (number of cycles or data length)
+ * @ctx: address or data constraint
+ * @ctx.addr: address constraint (number of cycles)
+ * @ctx.data: data constraint (data length)
  */
 struct nand_op_parser_pattern_elem {
enum nand_op_instr_type type;
@@ -1224,6 +1232,8 @@ int nand_op_parser_exec_op(struct nand_chip *chip,
  * devices.
  * @priv:  [OPTIONAL] pointer to private chip data
  * @manufacturer:  [INTERN] Contains manufacturer information
+ * @manufacturer.desc: [INTER

[PATCH 11/18] docs: crypto_engine.rst: Fix two parse warnings

[Mauro Carvalho Chehab]

./Documentation/crypto/crypto_engine.rst:13: WARNING: Unexpected indentation.
./Documentation/crypto/crypto_engine.rst:15: WARNING: Block quote ends without 
a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/crypto/crypto_engine.rst | 8 +---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/crypto/crypto_engine.rst 
b/Documentation/crypto/crypto_engine.rst
index 8272ac92a14f..1d56221dfe35 100644
--- a/Documentation/crypto/crypto_engine.rst
+++ b/Documentation/crypto/crypto_engine.rst
@@ -8,11 +8,13 @@ The crypto engine API (CE), is a crypto queue manager.
 
 Requirement
 ---
-You have to put at start of your tfm_ctx the struct crypto_engine_ctx
-struct your_tfm_ctx {
+You have to put at start of your tfm_ctx the struct crypto_engine_ctx::
+
+  struct your_tfm_ctx {
 struct crypto_engine_ctx enginectx;
 ...
-};
+  };
+
 Why: Since CE manage only crypto_async_request, it cannot know the underlying
 request_type and so have access only on the TFM.
 So using container_of for accessing __ctx is impossible.
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 18/18] w1: w1_io.c: fix a kernel-doc warning

[Mauro Carvalho Chehab]

Add a blank line to avoid this Sphinx warning:
./drivers/w1/w1_io.c:197: WARNING: Definition list ends without a blank 
line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 drivers/w1/w1_io.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/w1/w1_io.c b/drivers/w1/w1_io.c
index 075d120e7b88..0364d3329c52 100644
--- a/drivers/w1/w1_io.c
+++ b/drivers/w1/w1_io.c
@@ -194,6 +194,7 @@ static u8 w1_read_bit(struct w1_master *dev)
  *  bit 0 = id_bit
  *  bit 1 = comp_bit
  *  bit 2 = dir_taken
+ *
  * If both bits 0 & 1 are set, the search should be restarted.
  *
  * Return:bit fields - see above
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 09/18] net: mac80211.h: fix a bad comment line

[Mauro Carvalho Chehab]

Sphinx produces a lot of errors like this:
./include/net/mac80211.h:2083: warning: bad line:  >

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 include/net/mac80211.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index d2279b2d61aa..b2f3a0c018e7 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h
@@ -2080,7 +2080,7 @@ struct ieee80211_txq {
  * virtual interface might not be given air time for the transmission of
  * the frame, as it is not synced with the AP/P2P GO yet, and thus the
  * deauthentication frame might not be transmitted.
- >
+ *
  * @IEEE80211_HW_DOESNT_SUPPORT_QOS_NDP: The driver (or firmware) doesn't
  * support QoS NDP for AP probing - that's most likely a driver bug.
  *
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

The flow diagram should be inside a code-block to avoid those
warnings:
./include/linux/wait.h:110: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/wait.h:113: WARNING: Unexpected indentation.
./include/linux/wait.h:115: WARNING: Block quote ends without a blank 
line; unexpected unindent.

This is easily done by using "::" instead of just ":".

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 include/linux/wait.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/wait.h b/include/linux/wait.h
index d9f131ecf708..d907ed761a7f 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry 
*wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() like::
  *
  *  CPU0 - wakerCPU1 - waiter
  *
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 00/18] Fix some build warnings/errors with Sphinx

[Mauro Carvalho Chehab]

I decided to give a try with Sphinx last stable version
(1.17.4), and noticed several issues. The worse one was
with the networking book: a non-standard footnote there
with [*] instead of a number causes it to break PDF building.

So, I took some spare time to address some warnings all over
the tree, and moved a few text documents to a book. I with
I had more time to move the other ones and to solve other
warnings.

Mauro Carvalho Chehab (18):
  docs: can.rst: fix a footnote reference
  docs: fix location of request_firmware & friends
  docs: */index.rst: Add newer documents to their respective index.rst
  docs: admin-guide: add bcache documentation
  docs: core-api: add cachetlb documentation
  docs: core-api: add cgroup-v2 documentation
  docs: core-api: add circular-buffers documentation
  docs: driver-api: add clk documentation
  net: mac80211.h: fix a bad comment line
  rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()
  docs: crypto_engine.rst: Fix two parse warnings
  time: timer.c: adjust a kernel-doc comment
  wait: wait.h: Get rid of a kernel-doc/Sphinx warnings
  fbdev: modedb.c: fix a kernel-doc markup
  iio: iio.h: use nested struct support on kernel-doc markup
  mtd: rawnand.h: use nested union kernel-doc markups
  docs: uio-howto.rst: use a code block to solve a warning
  w1: w1_io.c: fix a kernel-doc warning

 Documentation/00-INDEX| 10 ---
 .../{bcache.txt => admin-guide/bcache.rst}|  0
 .../cgroup-v2.rst}|  0
 Documentation/admin-guide/index.rst   |  2 ++
 .../admin-guide/kernel-parameters.txt |  2 +-
 .../{cachetlb.txt => core-api/cachetlb.rst}   |  0
 .../circular-buffers.rst} |  0
 Documentation/core-api/index.rst  |  2 ++
 Documentation/crypto/crypto_engine.rst|  8 +++---
 Documentation/crypto/index.rst|  1 +
 Documentation/dell_rbu.txt|  4 +--
 Documentation/{clk.txt => driver-api/clk.rst} |  0
 .../firmware/fallback-mechanisms.rst  |  2 +-
 .../driver-api/firmware/request_firmware.rst  | 17 +++-
 Documentation/driver-api/index.rst|  2 ++
 Documentation/driver-api/infrastructure.rst   |  2 +-
 Documentation/driver-api/uio-howto.rst|  3 ++-
 Documentation/memory-barriers.txt |  4 +--
 Documentation/networking/can.rst  |  4 +--
 .../power/suspend-and-cpuhotplug.txt  |  2 +-
 Documentation/process/index.rst   |  1 +
 Documentation/security/index.rst  |  2 ++
 .../translations/ko_KR/memory-barriers.txt|  4 +--
 drivers/video/fbdev/core/modedb.c | 22 
 drivers/w1/w1_io.c|  1 +
 include/linux/iio/iio.h   | 24 -
 include/linux/mtd/rawnand.h   | 26 +--
 include/linux/rcupdate.h  |  5 ++--
 include/linux/wait.h  |  2 +-
 include/net/mac80211.h|  2 +-
 kernel/time/timer.c   | 14 +-
 31 files changed, 93 insertions(+), 75 deletions(-)
 rename Documentation/{bcache.txt => admin-guide/bcache.rst} (100%)
 rename Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} (100%)
 rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)
 rename Documentation/{circular-buffers.txt => core-api/circular-buffers.rst} 
(100%)
 rename Documentation/{clk.txt => driver-api/clk.rst} (100%)

-- 
2.17.0


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()

[Mauro Carvalho Chehab]

The code example at rcupdate.h currently produce lots of warnings:

./include/linux/rcupdate.h:572: WARNING: Unexpected indentation.
./include/linux/rcupdate.h:576: WARNING: Unexpected indentation.
./include/linux/rcupdate.h:580: WARNING: Block quote ends without a 
blank line; unexpected unindent.
./include/linux/rcupdate.h:582: WARNING: Block quote ends without a 
blank line; unexpected unindent.
./include/linux/rcupdate.h:582: WARNING: Inline literal start-string 
without end-string.

Change it to a code-block.

Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 include/linux/rcupdate.h | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
index 36360d07f25b..c890d10978fa 100644
--- a/include/linux/rcupdate.h
+++ b/include/linux/rcupdate.h
@@ -568,8 +568,8 @@ static inline void rcu_preempt_sleep_check(void) { }
  * This is simply an identity function, but it documents where a pointer
  * is handed off from RCU to some other synchronization mechanism, for
  * example, reference counting or locking.  In C11, it would map to
- * kill_dependency().  It could be used as follows:
- * ``
+ * kill_dependency().  It could be used as follows::
+ *
  * rcu_read_lock();
  * p = rcu_dereference(gp);
  * long_lived = is_long_lived(p);
@@ -580,7 +580,6 @@ static inline void rcu_preempt_sleep_check(void) { }
  * p = rcu_pointer_handoff(p);
  * }
  * rcu_read_unlock();
- *``
  */
 #define rcu_pointer_handoff(p) (p)
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAINTAINERS & files: Canonize the e-mails I use at files

[Mauro Carvalho Chehab]

Em Fri, 04 May 2018 13:58:39 +0300
Jani Nikula <jani.nik...@linux.intel.com> escreveu:

> On Fri, 04 May 2018, Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> > From now on, I'll start using my @kernel.org as my development e-mail.
> >
> > As such, let's remove the entries that point to the old
> > mche...@s-opensource.com at MAINTAINERS file.
> >
> > For the files written with a copyright with mchehab@s-opensource,
> > let's keep Samsung on their names, using mchehab+sams...@kernel.org,
> > in order to keep pointing to my employer, with sponsors the work.
> >
> > For the files written before I join Samsung (on July, 4 2013),
> > let's just use mche...@kernel.org.
> >
> > For bug reports, we can simply point to just kernel.org, as
> > this will reach my mchehab+samsung inbox anyway.  
> 
> I suppose this begs the question, why do we insist on adding our email
> addresses all over the place? On a quick grep, there are at least 40k+
> email addresses in the sources. Do we expect them all to be up-to-date
> too?

That's a good question.

The usual use case is that the e-mail allows people to contact developers
if needed. Such contact could simply due to something like handling SPDX
or other license-related issues or for troubleshooting.

There's also another reason (with IMHO, is more relevant): just the name
may not be enough to uniquely identify the author of some code. While
that might happen on occidental Countries, this is a way more relevant
for Asian Countries. For example, there are very few surnames on
some Countries there[1], and common names are usually... common. So, it
is not hard to find several people with exactly the same name working at
the same company. I've seen e-mails from those people that are things like
john.doe51@some.company, john.doe69@some.company, ...

[1] For example: https://en.wikipedia.org/wiki/List_of_Korean_surnames.

The e-mail is a way to uniquely identify a person. If we remove it,
then we may need to add another thing instead (like parents names,
security number or whatever), with would be weird, IMO. 

As we all use e-mails to uniquely identify contributors submissions,
IMHO, the best is to keep using e-mails. The side effect is that
we should keep those emails updated.

-

In the specific case of this patch, as I'm now just using @kernel.org
everywhere within the Kernel tree, I don't expect needing to change
it in long term.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] MAINTAINERS & files: Canonize the e-mails I use at files

[Mauro Carvalho Chehab]

>From now on, I'll start using my @kernel.org as my development e-mail.

As such, let's remove the entries that point to the old
mche...@s-opensource.com at MAINTAINERS file.

For the files written with a copyright with mchehab@s-opensource,
let's keep Samsung on their names, using mchehab+sams...@kernel.org,
in order to keep pointing to my employer, with sponsors the work.

For the files written before I join Samsung (on July, 4 2013),
let's just use mche...@kernel.org.

For bug reports, we can simply point to just kernel.org, as
this will reach my mchehab+samsung inbox anyway.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
Signed-off-by: Brian Warner <brian.war...@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
---
 Documentation/doc-guide/parse-headers.rst   |  4 ++--
 Documentation/media/uapi/rc/keytable.c.rst  |  2 +-
 Documentation/media/uapi/v4l/v4l2grab.c.rst |  2 +-
 Documentation/sphinx/parse-headers.pl   |  4 ++--
 .../zh_CN/video4linux/v4l2-framework.txt|  4 ++--
 MAINTAINERS | 17 -
 drivers/media/i2c/saa7115.c |  2 +-
 drivers/media/i2c/saa711x_regs.h|  2 +-
 drivers/media/i2c/tda7432.c |  2 +-
 drivers/media/i2c/tvp5150.c |  2 +-
 drivers/media/i2c/tvp5150_reg.h |  2 +-
 drivers/media/i2c/tvp7002.c |  2 +-
 drivers/media/i2c/tvp7002_reg.h |  2 +-
 drivers/media/media-devnode.c   |  2 +-
 drivers/media/pci/bt8xx/bttv-audio-hook.c   |  2 +-
 drivers/media/pci/bt8xx/bttv-audio-hook.h   |  2 +-
 drivers/media/pci/bt8xx/bttv-cards.c|  4 ++--
 drivers/media/pci/bt8xx/bttv-driver.c   |  2 +-
 drivers/media/pci/bt8xx/bttv-i2c.c  |  2 +-
 drivers/media/pci/cx23885/cx23885-input.c   |  2 +-
 drivers/media/pci/cx88/cx88-alsa.c  |  4 ++--
 drivers/media/pci/cx88/cx88-blackbird.c |  2 +-
 drivers/media/pci/cx88/cx88-core.c  |  2 +-
 drivers/media/pci/cx88/cx88-i2c.c   |  2 +-
 drivers/media/pci/cx88/cx88-video.c |  2 +-
 drivers/media/radio/radio-aimslab.c |  2 +-
 drivers/media/radio/radio-aztech.c  |  2 +-
 drivers/media/radio/radio-gemtek.c  |  2 +-
 drivers/media/radio/radio-maxiradio.c   |  2 +-
 drivers/media/radio/radio-rtrack2.c |  2 +-
 drivers/media/radio/radio-sf16fmi.c |  2 +-
 drivers/media/radio/radio-terratec.c|  2 +-
 drivers/media/radio/radio-trust.c   |  2 +-
 drivers/media/radio/radio-typhoon.c |  2 +-
 drivers/media/radio/radio-zoltrix.c |  2 +-
 drivers/media/rc/keymaps/rc-avermedia-m135a.c   |  2 +-
 drivers/media/rc/keymaps/rc-encore-enltv-fm53.c |  2 +-
 drivers/media/rc/keymaps/rc-encore-enltv2.c |  2 +-
 drivers/media/rc/keymaps/rc-kaiomy.c|  2 +-
 .../media/rc/keymaps/rc-kworld-plus-tv-analog.c |  2 +-
 drivers/media/rc/keymaps/rc-pixelview-new.c |  2 +-
 drivers/media/tuners/tea5761.c  |  4 ++--
 drivers/media/tuners/tea5767.c  |  4 ++--
 drivers/media/tuners/tuner-xc2028-types.h   |  2 +-
 drivers/media/tuners/tuner-xc2028.c |  4 ++--
 drivers/media/tuners/tuner-xc2028.h |  2 +-
 drivers/media/usb/em28xx/em28xx-camera.c|  2 +-
 drivers/media/usb/em28xx/em28xx-cards.c |  2 +-
 drivers/media/usb/em28xx/em28xx-core.c  |  4 ++--
 drivers/media/usb/em28xx/em28xx-dvb.c   |  4 ++--
 drivers/media/usb/em28xx/em28xx-i2c.c   |  2 +-
 drivers/media/usb/em28xx/em28xx-input.c |  2 +-
 drivers/media/usb/em28xx/em28xx-video.c |  4 ++--
 drivers/media/usb/em28xx/em28xx.h   |  2 +-
 drivers/media/usb/gspca/zc3xx-reg.h |  2 +-
 drivers/media/usb/tm6000/tm6000-cards.c |  2 +-
 drivers/media/usb/tm6000/tm6000-core.c  |  2 +-
 drivers/media/usb/tm6000/tm6000-i2c.c   |  2 +-
 drivers/media/usb/tm6000/tm6000-regs.h  |  2 +-
 drivers/media/usb/tm6000/tm6000-usb-isoc.h  |  2 +-
 drivers/media/usb/tm6000/tm6000-video.c |  2 +-
 drivers/media/usb/tm6000/tm6000.h   |  2 +-
 drivers/media/v4l2-core/v4l2-dev.c  |  4 ++--
 drivers/media/v4l2-core/v4l2-ioctl.c|  2 +-
 drivers/media/v4l2-core/videobuf-core.c |  6 +++---
 drivers/media/v4l2-core/videobuf-dma-contig.c   |  2 +-
 drivers/media/v4l2-core/videobuf-dma-sg.c   |  6 +++---
 drivers/media/v4l2-core/videobuf-vmalloc.c  |  4 ++--
 include/media/i2c/tvp7002.h |  2 +-
 include/media/videobuf-core.h   |  4 ++--
 include/media/videobuf-dma-sg.h |  4 ++--
 include/media/videobuf-vmalloc.h|  2 +-
 scripts/extract_xc3028.pl  

[PATCH] docs: kernel-doc: fix parsing of arrays

[Mauro Carvalho Chehab]

The logic with parses array has a bug that prevents it to
parse arrays like:
struct {
...
struct {
u64 msdu[IEEE80211_NUM_TIDS + 1];
...
...

Fix the parser to accept it.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..4356afda5afb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1062,7 +1062,7 @@ sub dump_struct($$) {
# Handle bitmaps
$arg =~ s/:\s*\d+\s*//g;
# Handle arrays
-   $arg =~ s/\[\S+\]//g;
+   $arg =~ s/\[.*\]//g;
# The type may have multiple words,
# and multiple IDs can be defined, like:
#   const struct foo, *bar, foobar
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: nested structs parsing

[Mauro Carvalho Chehab]

Em Thu, 29 Mar 2018 16:26:33 +0200
Johannes Berg  escreveu:

> Hi,
> 
> > The original patchset for nested structs was supporting it only 
> > when not inlined. This should be fixed on this patchset:
> > 
> > https://lkml.org/lkml/2018/2/19/387
> > 
> > Do you have those patches on your tree?  
> 
> No, looks like I don't have those yet. I'll wait for those then.
> 
> > With regards to duplicated warnings, that use to happen if the same header
> > is included several times (with is a common pratice at the net subsystem).  
> 
> Yeah, doesn't really matter anyway. I think I have to, in a sense,
> because I'm getting lots of functions separately from the headers.
> 
> > Could you please merge from docs-next and see if those problems
> > get solved?  
> 
> No, that doesn't seem to address it fully:
> 
> net/mac80211/sta_info.h:586: warning: Function parameter or member 
> 'tx_stats.packets' not described in 'sta_info'
> net/mac80211/sta_info.h:586: warning: Function parameter or member 
> 'tx_stats.bytes' not described in 'sta_info'
> net/mac80211/sta_info.h:586: warning: Function parameter or member 
> 'tx_stats.last_rate' not described in 'sta_info'
> net/mac80211/sta_info.h:586: warning: Function parameter or member 'msdu' not 
> described in 'sta_info'
> 
> You can reproduce this in
> 
>   git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211-next.git master
> 
> (merging with docs-next) and running
> 
>   make SPHINXDIRS=driver-api/80211 htmldocs

No need to run it for checking the errors... you can run just:

./scripts/kernel-doc -none net/mac80211/sta_info.h 

Applying the enclosed patch seems to work:


diff --git a/net/mac80211/sta_info.h b/net/mac80211/sta_info.h
index f64eb86ca64b..d81cb6155e8d 100644
--- a/net/mac80211/sta_info.h
+++ b/net/mac80211/sta_info.h
@@ -477,6 +477,10 @@ struct ieee80211_sta_rx_stats {
  * @tdls_chandef: a TDLS peer can have a wider chandef that is compatible to
  * the BSS one.
  * @tx_stats: TX statistics
+ * @tx_stats.packets: foo
+ * @tx_stats.last_rate: bar
+ * @tx_stats.bytes: foobar
+ * @tx_stats.msdu: foo
  * @rx_stats: RX statistics
  * @pcpu_rx_stats: per-CPU RX statistics, assigned only if the driver needs
  * this (by advertising the USES_RSS hw flag)


What's weird is that tx_stats.msdu field seems to be parsed wrong.
I'll take a look on it.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: nested structs parsing

[Mauro Carvalho Chehab]

Em Thu, 29 Mar 2018 11:47:07 +0200
Johannes Berg  escreveu:

> On Thu, 2018-03-29 at 11:46 +0200, Johannes Berg wrote:
> > Hi,
> > 
> > For a while I haven't looked at my documentation for 802.11, and now I
> > noticed I'm getting warnings due to the nested parsing.
> > 
> > However, something seems to be wrong? I have, for example, this (in
> > net/mac80211/sta_info.h)
> > 
> > struct sta_info {
> > ...
> > struct {
> > u64 packets[IEEE80211_NUM_ACS];
> > u64 bytes[IEEE80211_NUM_ACS];
> > struct ieee80211_tx_rate last_rate;
> > u64 msdu[IEEE80211_NUM_TIDS + 1];
> > } tx_stats;
> > };
> > 
> > but I'm getting the following warnings now, with only "@tx_stats" being
> > described in the documentation:
> > 
> > net/mac80211/sta_info.h:590: warning: Function parameter or member 
> > 'status_stats.last_ack' not described in 'sta_info'
> > net/mac80211/sta_info.h:590: warning: Function parameter or member 
> > 'status_stats.last_ack_signal' not described in 'sta_info'
> > net/mac80211/sta_info.h:590: warning: Function parameter or member 
> > 'status_stats.ack_signal_filled' not described in 'sta_info'
> > net/mac80211/sta_info.h:590: warning: Function parameter or member 'msdu' 
> > not described in 'sta_info'
> > 
> > I can understand the first three of those, but not the last one? Why is
> > the last one not qualified?
> > 
> > If I change it to this:
> > 
> > struct {
> > u64 packets[IEEE80211_NUM_ACS];
> > u64 bytes[IEEE80211_NUM_ACS];
> > /**
> >  * @last_rate: last TX rate
> >  */
> > struct ieee80211_tx_rate last_rate;
> > /**
> >  * @msdu: # of MSDUs per TID
> >  */
> > u64 msdu[IEEE80211_NUM_TIDS + 1];
> > } tx_stats;
> > 
> > I still get a warning on "tx_stats.last_rate", but not on "msdu", which
> > is sort of obvious from the warning text, but also rather unexpected.
> > 
> > Normally I'd say that the "msdu" warning is originally wrong
> > 
> > However, I'd also argue that if I'm using inline declarations, I
> > shouldn't have to write it like this:
> > 
> > struct {
> > u64 packets[IEEE80211_NUM_ACS];
> > u64 bytes[IEEE80211_NUM_ACS];
> > /**
> >  * @tx_stats.last_rate: last TX rate
> >  */
> > struct ieee80211_tx_rate last_rate;
> > ...
> > } tx_stats;  
> 
> Whoops, sent a fraction of a second too early - this actually causes a
> warning too (no idea why four times):
> 
> net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: 
>  * @tx_stats.last_rate: last TX rate
> net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: 
>  * @tx_stats.last_rate: last TX rate
> net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: 
>  * @tx_stats.last_rate: last TX rate
> net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: 
>  * @tx_stats.last_rate: last TX rate

The original patchset for nested structs was supporting it only 
when not inlined. This should be fixed on this patchset:

https://lkml.org/lkml/2018/2/19/387

Do you have those patches on your tree?

With regards to duplicated warnings, that use to happen if the same header
is included several times (with is a common pratice at the net subsystem).

I also submitted some patches to linux-next addressing it.

Could you please merge from docs-next and see if those problems
get solved?

It is located at:

git://git.lwn.net/linux.git docs-next

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 2/2] COPYING: use the new text with points to the license files

[Mauro Carvalho Chehab]

Now that we have a new COPYING file with points to the
Linux license files, replace it with the old content.

This patch does:
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename COPYING.new => COPYING (100%)

Reviewed-by: Greg Kroah-Hartman <gre...@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 COPYING | 358 ++--
 COPYING.new |  18 ---
 2 files changed, 10 insertions(+), 366 deletions(-)
 delete mode 100644 COPYING.new

diff --git a/COPYING b/COPYING
index ca442d313d86..da4cb28febe6 100644
--- a/COPYING
+++ b/COPYING
@@ -1,356 +1,18 @@
+The Linux Kernel is provided under:
 
-   NOTE! This copyright does *not* cover user programs that use kernel
- services by normal system calls - this is merely considered normal use
- of the kernel, and does *not* fall under the heading of "derived work".
- Also note that the GPL below is copyrighted by the Free Software
- Foundation, but the instance of code that it refers to (the Linux
- kernel) is copyrighted by me and others who actually wrote it.
+   SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
 
- Also note that the only valid version of the GPL as far as the kernel
- is concerned is _this_ particular version of the license (ie v2, not
- v2.2 or v3.x or whatever), unless explicitly otherwise stated.
+Being under the terms of the GNU General Public License version 2 only,
+according with:
 
-   Linus Torvalds
+   LICENSES/preferred/GPL-2.0
 
-
+With an explicit syscall exception, as stated at:
 
-   GNU GENERAL PUBLIC LICENSE
-  Version 2, June 1991
+   LICENSES/exceptions/Linux-syscall-note
 
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-   51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
+In addition, other licenses may also apply. Please see:
 
-   Preamble
+   Documentation/process/license-rules.rst
 
-  The licenses for most software are designed to take away your
-freedom to share and change it.  By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users.  This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
-  To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have.  You must make sure that they, too, receive or can get the
-source code.  And you must show them these terms so they know their
-rights.
-
-  We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
-  Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software.  If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
-  Finally, any free program is threatened constantly by software
-patents.  We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary.  To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-   GNU GENERAL PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. This License applies to any program or other work which contains
-a notice place

[PATCH v2 0/2] COPYING: create a new file with points to the Kernel license files

[Mauro Carvalho Chehab]

The contents of COPYING file is now duplicated at two other
files under LICENSE:
LICENSES/preferred/GPL-2.0
LICENSES/exceptions/Linux-syscall-note

Also, a new file was added, with describes how SPDX should work at
the Kernel source files:
Documentation/process/license-rules.rst

Instead fo having it copying the contents of two files, and not
even mentioning the third one, replace it by a file whose content
points to the other tree files, preserving the Kernel's license.

Adjust license-rules.rst accordingly.

No license changes.

NOTE


In order to make the diff easier to read, I broke it into two patches.
Feel free to merge both when merging if you want.


Mauro Carvalho Chehab (2):
  COPYING: create a new file with points to the Kernel license files
  COPYING: use the new text with points to the license files

 COPYING | 358 +---
 Documentation/process/license-rules.rst |  20 +-
 2 files changed, 21 insertions(+), 357 deletions(-)

-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 1/2] COPYING: create a new file with points to the Kernel license files

[Mauro Carvalho Chehab]

With the addition of SPDX patchset, the contents of COPYING file
is now duplicated at two other files under LICENSE:
LICENSES/preferred/GPL-2.0
LICENSES/exceptions/Linux-syscall-note

It is easy to check that the contents of the licence written on
those files are identical with COPYING using:

$ diff -upr COPYING LICENSES/preferred/GPL-2.0
$ diff -upr COPYING LICENSES/exceptions/Linux-syscall-note|less

Also, a new file was added, with describes how SPDX should work at
the Kernel source files:
Documentation/process/license-rules.rst

Instead fo having it copying the contents of two files, and not
even mentioning the third one, replace it by a file whose content
points to the other tree files, preserving the Kernel's license.

Adjust license-rules.rst accordingly.

Please notice that this file preserves the Kernel license as
is, without any changes.

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

Version 2:
   - Did some text changes at license-rules.rst, based on Matthew
 Wilcox review.

 COPYING.new | 18 ++
 Documentation/process/license-rules.rst | 20 +++-
 2 files changed, 29 insertions(+), 9 deletions(-)
 create mode 100644 COPYING.new

diff --git a/COPYING.new b/COPYING.new
new file mode 100644
index ..da4cb28febe6
--- /dev/null
+++ b/COPYING.new
@@ -0,0 +1,18 @@
+The Linux Kernel is provided under:
+
+   SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
+
+Being under the terms of the GNU General Public License version 2 only,
+according with:
+
+   LICENSES/preferred/GPL-2.0
+
+With an explicit syscall exception, as stated at:
+
+   LICENSES/exceptions/Linux-syscall-note
+
+In addition, other licenses may also apply. Please see:
+
+   Documentation/process/license-rules.rst
+
+for more details.
diff --git a/Documentation/process/license-rules.rst 
b/Documentation/process/license-rules.rst
index 408f77dc6157..8ea26325fe3f 100644
--- a/Documentation/process/license-rules.rst
+++ b/Documentation/process/license-rules.rst
@@ -4,15 +4,17 @@ Linux kernel licensing rules
 
 
 The Linux Kernel is provided under the terms of the GNU General Public
-License version 2 only (GPL-2.0), as published by the Free Software
-Foundation, and provided in the COPYING file.  This documentation file is
-not meant to replace the COPYING file, but provides a description of how
-each source file should be annotated to make the licensing it is governed
-under clear and unambiguous.
-
-The license in the COPYING file applies to the kernel source as a whole,
-though individual source files can have a different license which is
-required to be compatible with the GPL-2.0::
+License version 2 only (GPL-2.0), as provided in LICENSES/preferred/GPL-2.0,
+with an explicit syscall exception described in
+LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.
+
+This documentation file provides a description of how each source file
+should be annotated to make its license clear and unambiguous.
+It doesn't replace the Kernel's license.
+
+The license described in the COPYING file applies to the kernel source
+as a whole, though individual source files can have a different license
+which is required to be compatible with the GPL-2.0::
 
 GPL-1.0+  :  GNU General Public License v1.0 or later
 GPL-2.0+  :  GNU General Public License v2.0 or later
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] COPYING: create a new file with points to the Kernel license files

[Mauro Carvalho Chehab]

Em Thu, 22 Mar 2018 05:13:55 -0700
Matthew Wilcox <wi...@infradead.org> escreveu:

> On Thu, Mar 22, 2018 at 06:54:13AM -0300, Mauro Carvalho Chehab wrote:
> > +++ b/Documentation/process/license-rules.rst
> > @@ -4,15 +4,17 @@ Linux kernel licensing rules
> >  
> >  
> >  The Linux Kernel is provided under the terms of the GNU General Public
> > -License version 2 only (GPL-2.0), as published by the Free Software
> > -Foundation, and provided in the COPYING file.  This documentation file is
> > -not meant to replace the COPYING file, but provides a description of how
> > -each source file should be annotated to make the licensing it is governed
> > -under clear and unambiguous.
> > -
> > -The license in the COPYING file applies to the kernel source as a whole,
> > -though individual source files can have a different license which is
> > -required to be compatible with the GPL-2.0::
> > +version 2 only (GPL-2.0), as written at LICENSES/preferred/GPL-2.0,  
> 
> ^^^ you dropped the word 'License' here
> 
> Also, I think this should read "as provided in", not "as written at".
> 
> > +with an explicit syscall exception described at  
> 
> s/at/in/
> 
> > +LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.  
> 
> This phrasing is awkward with "desribed" used twice in the same sentence ...
> 
> > +This documentation file is not meant to replace the Kernel's license,
> > +but provides a description of how each source file should be annotated
> > +to make the licensing it is governed under clear and unambiguous.  
> 
> I'd rather this said:
> 
> This documentation file provides a description of how each source file
> should be annotated to make its license clear and unambiguous.

Thanks for your review!

I'll be submitting it again as a v2, with the following text at the
license-rules.rst preamble:


Linux kernel licensing rules


The Linux Kernel is provided under the terms of the GNU General Public
License version 2 only (GPL-2.0), as provided in LICENSES/preferred/GPL-2.0,
with an explicit syscall exception described in
LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.

This documentation file provides a description of how each source file
should be annotated to make its license clear and unambiguous.
It doesn't replace the Kernel's license.

The license described in the COPYING file applies to the kernel source
as a whole, though individual source files can have a different license
which is required to be compatible with the GPL-2.0::



Regards,
Mauro


> 



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/2] COPYING: use the new text with points to the license files

[Mauro Carvalho Chehab]

Now that we have a new COPYING file with points to the
Linux license files, replace it with the old content.

This patch does:
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename COPYING.new => COPYING (100%)

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 COPYING | 358 ++--
 COPYING.new |  18 ---
 2 files changed, 10 insertions(+), 366 deletions(-)
 delete mode 100644 COPYING.new

diff --git a/COPYING b/COPYING
index ca442d313d86..da4cb28febe6 100644
--- a/COPYING
+++ b/COPYING
@@ -1,356 +1,18 @@
+The Linux Kernel is provided under:
 
-   NOTE! This copyright does *not* cover user programs that use kernel
- services by normal system calls - this is merely considered normal use
- of the kernel, and does *not* fall under the heading of "derived work".
- Also note that the GPL below is copyrighted by the Free Software
- Foundation, but the instance of code that it refers to (the Linux
- kernel) is copyrighted by me and others who actually wrote it.
+   SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
 
- Also note that the only valid version of the GPL as far as the kernel
- is concerned is _this_ particular version of the license (ie v2, not
- v2.2 or v3.x or whatever), unless explicitly otherwise stated.
+Being under the terms of the GNU General Public License version 2 only,
+according with:
 
-   Linus Torvalds
+   LICENSES/preferred/GPL-2.0
 
-
+With an explicit syscall exception, as stated at:
 
-   GNU GENERAL PUBLIC LICENSE
-  Version 2, June 1991
+   LICENSES/exceptions/Linux-syscall-note
 
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-   51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
+In addition, other licenses may also apply. Please see:
 
-   Preamble
+   Documentation/process/license-rules.rst
 
-  The licenses for most software are designed to take away your
-freedom to share and change it.  By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users.  This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
-  To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have.  You must make sure that they, too, receive or can get the
-source code.  And you must show them these terms so they know their
-rights.
-
-  We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
-  Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software.  If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
-  Finally, any free program is threatened constantly by software
-patents.  We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary.  To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-   GNU GENERAL PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the te

[PATCH 0/2] COPYING: create a new file with points to the Kernel license files

[Mauro Carvalho Chehab]

The contents of COPYING file is now duplicated at two other
files under LICENSE:
LICENSES/preferred/GPL-2.0
LICENSES/exceptions/Linux-syscall-note

Also, a new file was added, with describes how SPDX should work at
the Kernel source files:
Documentation/process/license-rules.rst

Instead fo having it copying the contents of two files, and not
even mentioning the third one, replace it by a file whose content
points to the other tree files, preserving the Kernel's license.

Adjust license-rules.rst accordingly.

No license changes.

NOTE



In order to make the diff easier to read, I broke it into two patches.
Feel free to merge both when merging if you want.

Mauro Carvalho Chehab (2):
  COPYING: create a new file with points to the Kernel license files
  COPYING: use the new text with points to the license files

 COPYING | 358 +---
 Documentation/process/license-rules.rst |  20 +-
 2 files changed, 21 insertions(+), 357 deletions(-)

-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/2] COPYING: create a new file with points to the Kernel license files

[Mauro Carvalho Chehab]

With the addition of SPDX patchset, the contents of COPYING file
is now duplicated at two other files under LICENSE:
LICENSES/preferred/GPL-2.0
LICENSES/exceptions/Linux-syscall-note

It is easy to check that the contents of the licence written on
those files are identical with COPYING using:

$ diff -upr COPYING LICENSES/preferred/GPL-2.0
$ diff -upr COPYING LICENSES/exceptions/Linux-syscall-note|less

Also, a new file was added, with describes how SPDX should work at
the Kernel source files:
Documentation/process/license-rules.rst

Instead fo having it copying the contents of two files, and not
even mentioning the third one, replace it by a file whose content
points to the other tree files, preserving the Kernel's license.

Adjust license-rules.rst accordingly.

Please notice that this file preserves the Kernel license as
is, without any changes.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 COPYING.new | 18 ++
 Documentation/process/license-rules.rst | 20 +++-
 2 files changed, 29 insertions(+), 9 deletions(-)
 create mode 100644 COPYING.new

diff --git a/COPYING.new b/COPYING.new
new file mode 100644
index ..da4cb28febe6
--- /dev/null
+++ b/COPYING.new
@@ -0,0 +1,18 @@
+The Linux Kernel is provided under:
+
+   SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
+
+Being under the terms of the GNU General Public License version 2 only,
+according with:
+
+   LICENSES/preferred/GPL-2.0
+
+With an explicit syscall exception, as stated at:
+
+   LICENSES/exceptions/Linux-syscall-note
+
+In addition, other licenses may also apply. Please see:
+
+   Documentation/process/license-rules.rst
+
+for more details.
diff --git a/Documentation/process/license-rules.rst 
b/Documentation/process/license-rules.rst
index 408f77dc6157..bba178e68a0c 100644
--- a/Documentation/process/license-rules.rst
+++ b/Documentation/process/license-rules.rst
@@ -4,15 +4,17 @@ Linux kernel licensing rules
 
 
 The Linux Kernel is provided under the terms of the GNU General Public
-License version 2 only (GPL-2.0), as published by the Free Software
-Foundation, and provided in the COPYING file.  This documentation file is
-not meant to replace the COPYING file, but provides a description of how
-each source file should be annotated to make the licensing it is governed
-under clear and unambiguous.
-
-The license in the COPYING file applies to the kernel source as a whole,
-though individual source files can have a different license which is
-required to be compatible with the GPL-2.0::
+version 2 only (GPL-2.0), as written at LICENSES/preferred/GPL-2.0,
+with an explicit syscall exception described at
+LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file.
+
+This documentation file is not meant to replace the Kernel's license,
+but provides a description of how each source file should be annotated
+to make the licensing it is governed under clear and unambiguous.
+
+The license described in the COPYING file applies to the kernel source
+as a whole, though individual source files can have a different license
+which is required to be compatible with the GPL-2.0::
 
 GPL-1.0+  :  GNU General Public License v1.0 or later
 GPL-2.0+  :  GNU General Public License v2.0 or later
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] w1: fix w1_ds2438 documentation

[Mauro Carvalho Chehab]

Em Fri,  2 Mar 2018 08:55:24 +0100
Mariusz Bialonczyk  escreveu:

> Signed-off-by: Mariusz Bialonczyk 
> ---
>  Documentation/w1/slaves/w1_ds2438 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/w1/slaves/w1_ds2438 
> b/Documentation/w1/slaves/w1_ds2438
> index b99f3674c5b4..e64f65a09387 100644
> --- a/Documentation/w1/slaves/w1_ds2438
> +++ b/Documentation/w1/slaves/w1_ds2438
> @@ -60,4 +60,4 @@ vad: general purpose A/D input (VAD)
>  vdd: battery input (VDD)
>  
>  After the voltage conversion the value is returned as decimal ASCII.
> -Note: The value is in mV, so to get a volts the value has to be divided by 
> 10.
> +Note: To get a volts the value has to be divided by 100.

Hmm... I've no idea why you sent this to linux-media and to me...

The proper maintainer seems to be Evgeniy:

 ./scripts/get_maintainer.pl -f Documentation/w1/slaves/w1_ds2438
Evgeniy Polyakov  (maintainer:W1 DALLAS'S 1-WIRE BUS)
Jonathan Corbet  (maintainer:DOCUMENTATION)
Greg Kroah-Hartman  (commit_signer:1/1=100%)
Mariusz Bialonczyk  
(commit_signer:1/1=100%,authored:1/1=100%,added_lines:63/63=100%)
linux-doc@vger.kernel.org (open list:DOCUMENTATION)
linux-ker...@vger.kernel.org (open list)



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 4/6] scripts: kernel-doc: support in-line comments on nested structs/unions

[Mauro Carvalho Chehab]

Em Fri, 16 Feb 2018 15:52:33 +0100
Markus Heiser <markus.hei...@darmarit.de> escreveu:

> > Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab 
> > <mche...@s-opensource.com>:
> > 
> > The parser at kernel-doc rejects names with dots in the middle.
> > Fix it, in order to support nested structs/unions.
> > 
> > Tested-by: Jani Nikula <jani.nik...@intel.com>
> > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> > ---
> > scripts/kernel-doc | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index fee8952037b1..06d7f3f2c094 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> > my $doc_content = $doc_com_body . '(.*)';
> > my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> > my $doc_inline_start = '^\s*/\*\*\s*$';
> > -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> > +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';  
> 
> Thanks!
> 
> FWIW: added similar patch to python variant of kernel-doc:
> 
> https://github.com/return42/linuxdoc/commit/5c5da9a
> 
> rendered example:
> 
>   
> https://return42.github.io/linuxdoc/linuxdoc-howto/all-in-a-tumble.html#struct-my-long-struct

On a quick look, on your example, bar2.barbar description looks different
than what we get from the perl version.

There, it generates it as:

``bar2.barbar``
  Description for **barbar** inside **foo.bar2**

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

[Mauro Carvalho Chehab]

Em Wed, 14 Feb 2018 20:20:21 +0200
Jani Nikula <jani.nik...@linux.intel.com> escreveu:

> On Wed, 14 Feb 2018, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> > There is a simple fix, though. Make inline comments to accept a dot:
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index fee8952037b1..06d7f3f2c094 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> >  my $doc_content = $doc_com_body . '(.*)';
> >  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> >  my $doc_inline_start = '^\s*/\*\*\s*$';
> > -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> > +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
> >  my $doc_inline_end = '^\s*\*/\s*$';
> >  my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
> >  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> >
> > That requires a small change at the inline parameters, though:
> >
> > diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c 
> > b/drivers/gpu/drm/i915/intel_dpio_phy.c
> > index 76473e9836c6..c8e9e44e5981 100644
> > --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> > +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> > @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
> >  */
> > struct {
> > /**
> > -* @port: which port maps to this channel.
> > +* @channel.port: which port maps to this channel.
> >  */
> > enum port port;
> > } channel[2];  
> 
> Perhaps it would be slightly more elegant to be able to leave out
> "channel." here and deduce that from the context... but the above
> matches what you'd write in the higher level struct comment, and
> produces the same output. It works and it's really simple. I like it.
> 
> Please submit this as a proper patch, with
> 
> Tested-by: Jani Nikula <jani.nik...@intel.com>

Submitted. I ended by submitting as a patch series, as, when I
did some tests with the examples, I found that kernel-doc have
issues parsing them.


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 6/6] drm: intel_dpio_phy: fix kernel-doc comments at nested struct

[Mauro Carvalho Chehab]

The in-lined comments for channel.port doesn't follow the syntax
described at kernel-doc document, causing the following warning:

$ ./scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter 
or member 'channel.port' not described in 'bxt_ddi_phy_info'

While the best would be for the Kernel to deduce that from the
context, supporting it is not trivial. So, let's just stick with
the existing syntax.

Reported-by: Jani Nikula <jani.nik...@intel.com>
Tested-by: Jani Nikula <jani.nik...@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/gpu/drm/i915/intel_dpio_phy.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c 
b/drivers/gpu/drm/i915/intel_dpio_phy.c
index 76473e9836c6..c8e9e44e5981 100644
--- a/drivers/gpu/drm/i915/intel_dpio_phy.c
+++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
@@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
 */
struct {
/**
-* @port: which port maps to this channel.
+* @channel.port: which port maps to this channel.
 */
enum port port;
} channel[2];
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 4/6] scripts: kernel-doc: support in-line comments on nested structs/unions

[Mauro Carvalho Chehab]

The parser at kernel-doc rejects names with dots in the middle.
Fix it, in order to support nested structs/unions.

Tested-by: Jani Nikula <jani.nik...@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..06d7f3f2c094 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
-my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 5/6] doc-guide: kernel-doc: add examples about nested union/structs

[Mauro Carvalho Chehab]

It helps to give some examples about how to use in-line
comments also when nested union/structs are present. So add it.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 13 +++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 1ddfe35c0e78..c6c329708d8a 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -286,8 +286,17 @@ on a line of their own, like all other kernel-doc 
comments::
  * Here, the member description may contain several paragraphs.
  */
 int baz;
-/** @foobar: Single line description. */
-int foobar;
+union {
+/** @foobar: Single line description. */
+int foobar;
+};
+/** @bar2: Description for struct @bar2 inside @foo */
+struct {
+/**
+ * @bar2.barbar: Description for @barbar inside @foo.bar2
+ */
+int barbar;
+} bar2;
   };
 
 Typedef documentation
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 3/6] doc-guide: kernel-doc: move in-line section to be after nested struct

[Mauro Carvalho Chehab]

We want to give some examples about how to do in-line comments
for nested structs. So, move it to be after nested structs/unions
chapter.

The section content was not changed on this patch.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 56 +-
 1 file changed, 28 insertions(+), 28 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 3c00ce0c84e5..1ddfe35c0e78 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -211,34 +211,6 @@ Example::
   int d;
   };
 
-In-line member documentation comments
-~
-
-The structure members may also be documented in-line within the definition.
-There are two styles, single-line comments where both the opening ``/**`` and
-closing ``*/`` are on the same line, and multi-line comments where they are 
each
-on a line of their own, like all other kernel-doc comments::
-
-  /**
-   * struct foo - Brief description.
-   * @foo: The Foo member.
-   */
-  struct foo {
-int foo;
-/**
- * @bar: The Bar member.
- */
-int bar;
-/**
- * @baz: The Baz member.
- *
- * Here, the member description may contain several paragraphs.
- */
-int baz;
-/** @foobar: Single line description. */
-int foobar;
-  };
-
 Nested structs/unions
 ~
 
@@ -290,6 +262,34 @@ It is possible to document nested structs and unions, 
like::
#) When the nested struct/union is anonymous, the member ``bar`` in it
   should be documented as ``@bar:``
 
+In-line member documentation comments
+~
+
+The structure members may also be documented in-line within the definition.
+There are two styles, single-line comments where both the opening ``/**`` and
+closing ``*/`` are on the same line, and multi-line comments where they are 
each
+on a line of their own, like all other kernel-doc comments::
+
+  /**
+   * struct foo - Brief description.
+   * @foo: The Foo member.
+   */
+  struct foo {
+int foo;
+/**
+ * @bar: The Bar member.
+ */
+int bar;
+/**
+ * @baz: The Baz member.
+ *
+ * Here, the member description may contain several paragraphs.
+ */
+int baz;
+/** @foobar: Single line description. */
+int foobar;
+  };
+
 Typedef documentation
 -
 
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/6] doc-guide: kernel-doc: fix example for inlined comments

[Mauro Carvalho Chehab]

Without ending with a ";", kernel-doc doesn't recognize it
as an struct, and it fails to parse the example.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 9fce378dccb2..3c00ce0c84e5 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -237,7 +237,7 @@ on a line of their own, like all other kernel-doc comments::
 int baz;
 /** @foobar: Single line description. */
 int foobar;
-  }
+  };
 
 Nested structs/unions
 ~
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/6] doc-guide: kernel-doc: fix example for nested_foobar struct

[Mauro Carvalho Chehab]

There's a missing */ at the end of Kernel docs example.
Even adding it, it will still produce 3 warnings:

example:33: warning: Function parameter or member 'bar' not described 
in 'nested_foobar'
example:33: warning: Function parameter or member 'bar.st1' not 
described in 'nested_foobar'
example:33: warning: Function parameter or member 'bar.st2' not 
described in 'nested_foobar'

So, make the example more complete and add the missing end
of comment there.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 4 
 1 file changed, 4 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
b/Documentation/doc-guide/kernel-doc.rst
index 2fb7f2bfc245..9fce378dccb2 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -250,10 +250,14 @@ It is possible to document nested structs and unions, 
like::
* @memb2: second member of anonymous union/anonymous struct
* @memb3: third member of anonymous union/anonymous struct
* @memb4: fourth member of anonymous union/anonymous struct
+   * @bar: non-anonymous union
+   * @bar.st1: struct st1 inside @bar
+   * @bar.st2: struct st2 inside @bar
* @bar.st1.memb1: first member of struct st1 on union bar
* @bar.st1.memb2: second member of struct st1 on union bar
* @bar.st2.memb1: first member of struct st2 on union bar
* @bar.st2.memb2: second member of struct st2 on union bar
+   */
   struct nested_foobar {
 /* Anonymous union/struct*/
 union {
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 0/6] Add support for in-line nested struct comments

[Mauro Carvalho Chehab]

This series fix two bugs at kernel-doc.rst examples and add support
for in-line nested struct comments.

It also converts one documentation at intel_dpio_phy to use it,
in order to give a practical example about how to use it.

Mauro Carvalho Chehab (6):
  doc-guide: kernel-doc: fix example for nested_foobar struct
  doc-guide: kernel-doc: fix example for inlined comments
  doc-guide: kernel-doc: move in-line section to be after nested struct
  scripts: kernel-doc: support in-line comments on nested structs/unions
  doc-guide: kernel-doc: add examples about nested union/structs
  drm: intel_dpio_phy: fix kernel-doc comments at nested struct

 Documentation/doc-guide/kernel-doc.rst | 69 --
 drivers/gpu/drm/i915/intel_dpio_phy.c  |  2 +-
 scripts/kernel-doc |  2 +-
 3 files changed, 43 insertions(+), 30 deletions(-)

-- 
2.14.3


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

[Mauro Carvalho Chehab]

Em Wed, 14 Feb 2018 18:07:03 +0200
Jani Nikula <jani.nik...@linux.intel.com> escreveu:

> On Mon, 18 Dec 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> > It is possible to use nested structs like:
> >
> > struct {
> > struct {
> > void *arg1;
> > } st1, st2, *st3, st4;
> > };
> >
> > Handling it requires to split each parameter. Change the logic
> > to allow such definitions.
> >
> > In order to test the new nested logic, the following file
> > was used to test  
> 
> Hi Mauro, resurrecting an old thread...
> 
> So this was a great improvement to documenting nested structs. However,
> it looks like it only supports describing the nested structs at the top
> level comment, and fails for inline documentation comments.

True. I didn't consider inline comments when I wrote the patch.
We don't use inline doc tags at media. IMO, a single description block
on the top works better, but yeah, it would be very good if it would
support nested structs to also have inlined comments.

Yet, on a quick hack:

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..e2d5cadd8d0b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1009,6 +1009,8 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
 
+print "members: $members\n";
+
# ignore members marked private:
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
$members =~ s/\/\*\s*private:.*//gosi;

produce:

$ scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
members:  bool dual_channel; enum dpio_phy rcomp_phy; int reset_delay; 
u32 pwron_mask; struct { enum port port; }  channel[2]; 
drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter 
or member 'channel.port' not described in 'bxt_ddi_phy_info'

So, dump_struct() already receives the struct sanitizes without any comments
inside.

There is a simple fix, though. Make inline comments to accept a dot:

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..06d7f3f2c094 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
-my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';

That requires a small change at the inline parameters, though:

diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c 
b/drivers/gpu/drm/i915/intel_dpio_phy.c
index 76473e9836c6..c8e9e44e5981 100644
--- a/drivers/gpu/drm/i915/intel_dpio_phy.c
+++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
@@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
 */
struct {
/**
-* @port: which port maps to this channel.
+* @channel.port: which port maps to this channel.
 */
enum port port;
} channel[2];

The alternative would be a way more complex: to teach the code with
starts at:

If ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {

About how to handle with inlined structs/enums at inlined comments.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] media: cxusb, dib0700: ignore XC2028_I2C_FLUSH

[Mauro Carvalho Chehab]

The XC2028_I2C_FLUSH only needs to be implemented on a few
devices. Others can safely ignore it.

That prevents filling the dmesg with lots of messages like:

dib0700: stk7700ph_xc3028_callback: unknown command 2, arg 0

Reported-by: Enrico Mioso <mrkiko...@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mche...@osg.samsung.com>
---
 drivers/media/usb/dvb-usb/cxusb.c   | 2 ++
 drivers/media/usb/dvb-usb/dib0700_devices.c | 1 +
 2 files changed, 3 insertions(+)

diff --git a/drivers/media/usb/dvb-usb/cxusb.c 
b/drivers/media/usb/dvb-usb/cxusb.c
index 37dea0adc695..cfe86b4864b3 100644
--- a/drivers/media/usb/dvb-usb/cxusb.c
+++ b/drivers/media/usb/dvb-usb/cxusb.c
@@ -677,6 +677,8 @@ static int dvico_bluebird_xc2028_callback(void *ptr, int 
component,
case XC2028_RESET_CLK:
deb_info("%s: XC2028_RESET_CLK %d\n", __func__, arg);
break;
+   case XC2028_I2C_FLUSH:
+   break;
default:
deb_info("%s: unknown command %d, arg %d\n", __func__,
 command, arg);
diff --git a/drivers/media/usb/dvb-usb/dib0700_devices.c 
b/drivers/media/usb/dvb-usb/dib0700_devices.c
index 366b05529915..a9968fb1e8e4 100644
--- a/drivers/media/usb/dvb-usb/dib0700_devices.c
+++ b/drivers/media/usb/dvb-usb/dib0700_devices.c
@@ -430,6 +430,7 @@ static int stk7700ph_xc3028_callback(void *ptr, int 
component,
state->dib7000p_ops.set_gpio(adap->fe_adap[0].fe, 8, 0, 1);
break;
case XC2028_RESET_CLK:
+   case XC2028_I2C_FLUSH:
break;
default:
err("%s: unknown command %d, arg %d\n", __func__,
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: Fix misconversion of #if

[Mauro Carvalho Chehab]

Em Tue, 16 Jan 2018 19:40:55 -0800
Matthew Wilcox <wi...@infradead.org> escreveu:

> From: Matthew Wilcox <mawil...@microsoft.com>
> 
> At some stage of the conversion pipeline, something thought that the
> DocBook entity  should be rendered as NUM instead of #.
> 
> Signed-off-by: Matthew Wilcox <mawil...@microsoft.com>
Reviewed-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> ---
>  Documentation/kernel-hacking/hacking.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/kernel-hacking/hacking.rst 
> b/Documentation/kernel-hacking/hacking.rst
> index daf3883b2694..5c4d30e81b7f 100644
> --- a/Documentation/kernel-hacking/hacking.rst
> +++ b/Documentation/kernel-hacking/hacking.rst
> @@ -690,8 +690,8 @@ not provide the necessary runtime environment and the 
> include files are
>  not tested for it. It is still possible, but not recommended. If you
>  really want to do this, forget about exceptions at least.
>  
> -NUMif
> --
> +#if
> +---
>  
>  It is generally considered cleaner to use macros in header files (or at
>  the top of .c files) to abstract away functions rather than using \`#if'



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 02/11] media: videobuf2: Add new uAPI for DVB streaming I/O

[Mauro Carvalho Chehab]

Em Mon, 8 Jan 2018 15:26:50 +0100
Hans Verkuil  escreveu:

> A quick follow-up:
> 
> On 01/08/2018 02:54 PM, Hans Verkuil wrote:
> >> +/*
> >> + * Videobuf operations
> >> + */
> >> +int dvb_vb2_init(struct dvb_vb2_ctx *ctx, const char *name, int 
> >> nonblocking)
> >> +{
> >> +  struct vb2_queue *q = >vb_q;
> >> +  int ret;
> >> +
> >> +  memset(ctx, 0, sizeof(struct dvb_vb2_ctx));
> >> +  q->type = DVB_BUF_TYPE_CAPTURE;  
> > 
> > We don't support DVB_BUF_TYPE_OUTPUT? Shouldn't this information come from 
> > the
> > driver?
> >   
> >> +  /**capture type*/  
> > 
> > Why /** ?
> >   
> >> +  q->is_output = 0;  
> > 
> > Can be dropped unless we support DVB_BUF_TYPE_OUTPUT.
> >   
> >> +  /**only mmap is supported currently*/  
> > 
> > /** ?
> >   
> >> +  q->io_modes = VB2_MMAP;
> >> +  q->drv_priv = ctx;
> >> +  q->buf_struct_size = sizeof(struct dvb_buffer);
> >> +  q->min_buffers_needed = 1;
> >> +  q->ops = _vb2_qops;
> >> +  q->mem_ops = _vmalloc_memops;
> >> +  q->buf_ops = _vb2_buf_ops;
> >> +  q->num_buffers = 0;  
> > 
> > Not needed, is zeroed in the memset above.
> > 
> > I'm also missing q->timestamp_flags: should be set to 
> > V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC.  
> 
> Ignore this, see my comments later on.
> 
> >   
> >> +  ret = vb2_core_queue_init(q);
> >> +  if (ret) {
> >> +  ctx->state = DVB_VB2_STATE_NONE;
> >> +  dprintk(1, "[%s] errno=%d\n", ctx->name, ret);
> >> +  return ret;
> >> +  }
> >> +
> >> +  mutex_init(>mutex);
> >> +  spin_lock_init(>slock);
> >> +  INIT_LIST_HEAD(>dvb_q);
> >> +
> >> +  strncpy(ctx->name, name, DVB_VB2_NAME_MAX);  
> > 
> > I believe strlcpy is recommended.
> >   
> >> +  ctx->nonblocking = nonblocking;
> >> +  ctx->state = DVB_VB2_STATE_INIT;
> >> +
> >> +  dprintk(3, "[%s]\n", ctx->name);
> >> +
> >> +  return 0;
> >> +}  
> 
> 
> 
> >> diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
> >> index c10f1324b4ca..e212aa18ad78 100644
> >> --- a/include/uapi/linux/dvb/dmx.h
> >> +++ b/include/uapi/linux/dvb/dmx.h
> >> @@ -211,6 +211,64 @@ struct dmx_stc {
> >>__u64 stc;
> >>  };
> >>  
> >> +/**
> >> + * struct dmx_buffer - dmx buffer info
> >> + *
> >> + * @index:id number of the buffer
> >> + * @bytesused:number of bytes occupied by data in the buffer 
> >> (payload);
> >> + * @offset:   for buffers with memory == DMX_MEMORY_MMAP;
> >> + *offset from the start of the device memory for this 
> >> plane,
> >> + *(or a "cookie" that should be passed to mmap() as 
> >> offset)  
> > 
> > Since we only support MMAP this is always a 'cookie' in practice. So I 
> > think this
> > should just be:
> > 
> > A "cookie" that should be passed to mmap() as offset.
> >   
> >> + * @length:   size in bytes of the buffer
> >> + *
> >> + * Contains data exchanged by application and driver using one of the 
> >> streaming
> >> + * I/O methods.
> >> + */
> >> +struct dmx_buffer {
> >> +  __u32   index;
> >> +  __u32   bytesused;
> >> +  __u32   offset;  
> > 
> > I suggest making this a __u64: that way we can handle pointers as well in
> > the future if we need them (as we do for the USERPTR case for V4L2).
> > 
> > Should this also be wrapped in a union? Useful when adding dmabuf support 
> > in the
> > future.
> > 
> > Do you think there is any use-case for multiplanar formats in the future?
> > With perhaps meta data in a separate plane? Having to add support for this 
> > later
> > has proven to be very painful, so we need to be as certain as possible that
> > this isn't going to happen. Otherwise it's better to prepare for this right 
> > now.
> >   
> >> +  __u32   length;
> >> +  __u32   reserved[4];  
> > 
> > I do believe you need a memory field as well. It's only MMAP today, but in
> > the future DMABUF will most likely be supported as well and you need to be
> > able to tell what memory mode is being used.
> >   
> >> +};  
> 
> There is no 'flags' field here. But without that you cannot check the buffer
> states, esp. the ERROR state. Or can that never happen?

On DVB, there is a protocol stack there that allows checking errors,
either MPEG-TS (current standards) or IP/MMT - for the new, yet to be
implemented ATSC version 3 standard.

Even if we add an error state, userspace will just ignore, as it will
need to verify the packet CRC checks.

> Would a timestamp field be useful, if only for debugging?

I don't see how a timestamp will help here for debugging. Probably,
adding event trace points would work better, but we have those
already at vb2-core.

Anyway, as this is kAPI only, we can add it later as needed.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 02/11] media: videobuf2: Add new uAPI for DVB streaming I/O

[Mauro Carvalho Chehab]

Em Mon, 8 Jan 2018 14:54:51 +0100
Hans Verkuil <hverk...@xs4all.nl> escreveu:

> Hi Mauro,
> 
> Thanks for this patch series, nice to see this moving forward.
> 
> Some comments below (note the wrong queue_setup code in particular since that
> relates to my comment about the '[PATCH v3] media: videobuf2-core: don't go 
> out
> of the buffer range' patch).
> 
> On 12/21/2017 05:18 PM, Mauro Carvalho Chehab wrote:
> > From: Satendra Singh Thakur <satendr...@samsung.com>
> > 
> > Adds a new uAPI for DVB to use streaming I/O which is implemented
> > based on videobuf2, using those new ioctls:
> > 
> > - DMX_REQBUFS:  Request kernel to allocate buffers which count and size
> > are dedicated by user.
> > - DMX_QUERYBUF: Get the buffer information like a memory offset which
> > will mmap() and be shared with user-space.
> > - DMX_EXPBUF:   Just for testing whether buffer-exporting success or not.
> > - DMX_QBUF: Pass the buffer to kernel-space.
> > - DMX_DQBUF:Get back the buffer which may contain TS data.
> > 
> > Originally developed by: Junghak Sung <jh1009.s...@samsung.com>, as
> > seen at:
> > https://patchwork.linuxtv.org/patch/31613/
> > https://patchwork.kernel.org/patch/7334301/
> > 
> > The original patch was written before merging VB2-core functionalities
> > upstream. When such series was added, several adjustments were made,
> > fixing some issues with V4L2, causing the original patch to be
> > non-trivially rebased.
> > 
> > After rebased, a few bugs in the patch were fixed. The patch was
> > also enhanced it and polling functionality got added.
> > 
> > The main changes over the original patch are:
> > 
> > dvb_vb2_fill_buffer():
> > - Set the size of the outgoing buffer after while loop using
> >   vb2_set_plane_payload;
> > 
> > - Added NULL check for source buffer as per normal convention
> >   of demux driver, this is called twice, first time with valid
> >   buffer second time with NULL pointer, if its not handled,  
> 
> its -> it's
> 
> >   it will result in  crash
> > 
> > - Restricted spinlock for only list_* operations
> > 
> > dvb_vb2_init():
> > - Restricted q->io_modes to only VB2_MMAP as its the only
> >   supported mode
> > 
> > dvb_vb2_release():
> > - Replaced the && in if condiion with &, because otherwise  
> 
> condition
> 
> >   it was always getting satisfied.
> > 
> > dvb_vb2_stream_off():
> > - Added list_del code for enqueud buffers upon stream off  
> 
> enqueued
> 
> > 
> > dvb_vb2_poll():
> > - Added this new function in order to support polling
> > 
> > dvb_demux_poll() and dvb_dvr_poll()
> > - dvb_vb2_poll() is now called from these functions
> > 
> > - Ported this patch and latest videobuf2 to lower kernel versions and
> >   tested auto scan.

Too late to change it, as the patch was already merged, as per
Michel's suggestion.

> > [mche...@s-opensource.com: checkpatch fixes]
> > Co-developed-by: Junghak Sung <jh1009.s...@samsung.com>
> > Signed-off-by: Junghak Sung <jh1009.s...@samsung.com>
> > Signed-off-by: Geunyoung Kim <nenggun@samsung.com>
> > Acked-by: Seung-Woo Kim <sw0312@samsung.com>
> > Acked-by: Inki Dae <inki@samsung.com>
> > Signed-off-by: Satendra Singh Thakur <satendr...@samsung.com>
> > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> > ---
> >  drivers/media/dvb-core/Makefile  |   2 +-
> >  drivers/media/dvb-core/dmxdev.c  | 196 +++---
> >  drivers/media/dvb-core/dmxdev.h  |   4 +
> >  drivers/media/dvb-core/dvb_vb2.c | 423 
> > +++
> >  drivers/media/dvb-core/dvb_vb2.h |  72 +++
> >  include/uapi/linux/dvb/dmx.h |  66 +-
> >  6 files changed, 733 insertions(+), 30 deletions(-)
> >  create mode 100644 drivers/media/dvb-core/dvb_vb2.c
> >  create mode 100644 drivers/media/dvb-core/dvb_vb2.h
> > 
> > diff --git a/drivers/media/dvb-core/Makefile 
> > b/drivers/media/dvb-core/Makefile
> > index 47e2e391bfb8..bbc65dfa0a8e 100644
> > --- a/drivers/media/dvb-core/Makefile
> > +++ b/drivers/media/dvb-core/Makefile
> > @@ -7,6 +7,6 @@ dvb-net-$(CONFIG_DVB_NET) := dvb_net.o
> >  
> >  dvb-core-objs := dvbdev.o dmxdev.o dvb_demux.o \
> >  dvb_ca_en50221.o dvb_frontend.o 

Re: [PATCH v3 1/1] runchecks: Generalize make C={1,2} to support multiple checkers

[Mauro Carvalho Chehab]

Em Fri, 05 Jan 2018 20:41:41 +0100
Knut Omang <knut.om...@oracle.com> escreveu:

> On Fri, 2018-01-05 at 16:08 -0200, Mauro Carvalho Chehab wrote:
> > Em Thu, 04 Jan 2018 21:15:31 +0100
> > Knut Omang <knut.om...@oracle.com> escreveu:
> >   
> > > > I'm surprised the commit message and the provided documentation say
> > > > nothing about using CHECK=foo on the command line. That already supports
> > > > arbitrary checkers. 
> > > 
> > > The problem, highlighted by Jim Davis in
> > > 
> > > https://lkml.org/lkml/2017/11/20/638
> > > 
> > > is that the current solution isn't flexible enough - that discussion 
> > > is what lead me to this reimplementation of what I originally intended 
> > > to be a checkpatch only solution.
> > >   
> > > > How does this relate to that? Is this supposed to be
> > > > a complete replacement? Or what?
> > > 
> > > It has evolved into a complete replacement of the intention of CHECK.
> > >   
> > > > 'make help' also references $CHECK, and this patch doesn't update the
> > > > help text.
> > > 
> > > I realize now that this needs to be handled in some way due to the way I 
> > > split the 
> > > arguments with '--' - the intention was to keep it for bw compatibility.
> > > 
> > > It would be good to know if people rely on using CHECK with C={1,2} for 
> > > anything beside the checkers supported by runchecks today  
> > 
> > I do. Here, I use:
> > 
> > $ make ARCH=i386  CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 
> > W=1
> > CHECK='compile_checks' M=drivers/media
> > 
> > Where "compile_checks" is actually a small script that calls both
> > smatch and sparse:
> > 
> > #!/bin/bash
> > /devel/smatch/smatch -p=kernel $@  
> 
> I suppose you here refer to this:
> https://blogs.oracle.com/linuxkernel/smatch-static-analysis-tool-overview,-by-dan-carpenter
> 
> Good idea! I'll have a look at how that plays with this.

Yes.

> 
> > /devel/sparse/sparse $@
> > 
> > So, I'm not sure why we need something else.   
> 
> The core functionality is the selective suppression logic and output 
> unification
> which makes checking with automated build tools more flexible and 
> applicable right away (not when every warning from every checker is fixed...)

If the idea is to use it only/mostly with automated build tools, then
the better would be to call it only when explicitly requested, e. g.
something like C=3, in order to avoid breaking the usecase where one
would run its own script.

On my case, I use C=1 CHECK=compile_checks as part as my usual patch
handling. For every patch I apply on media, I call make again, to be
sure that no warning/building errors were added, not only with gcc
but also with smatch and sparse. 

> 
> > That said, I didn't look
> > on its code, but looking on its diffstat:
> > 
> >  Makefile   |  23 +-
> >  scripts/Makefile.build |   4 +-
> >  scripts/runchecks  | 734 ++-
> >  scripts/runchecks.cfg  |  63 ++-
> >  scripts/runchecks_help.txt |  43 ++-
> > 
> > Using a 734 lines python program just to do an exec on an external checker
> > seems too much!  
> 
> Sure, if that was the case I would be the first to agree :-)
> 
> Thanks,
> Knut
> 
> > Thanks,
> > Mauro  



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 1/1] runchecks: Generalize make C={1,2} to support multiple checkers

[Mauro Carvalho Chehab]

Em Thu, 04 Jan 2018 21:15:31 +0100
Knut Omang  escreveu:

> > I'm surprised the commit message and the provided documentation say
> > nothing about using CHECK=foo on the command line. That already supports
> > arbitrary checkers.   
> 
> The problem, highlighted by Jim Davis in
> 
> https://lkml.org/lkml/2017/11/20/638
> 
> is that the current solution isn't flexible enough - that discussion 
> is what lead me to this reimplementation of what I originally intended 
> to be a checkpatch only solution.
> 
> > How does this relate to that? Is this supposed to be
> > a complete replacement? Or what?  
> 
> It has evolved into a complete replacement of the intention of CHECK.
> 
> > 'make help' also references $CHECK, and this patch doesn't update the
> > help text.  
> 
> I realize now that this needs to be handled in some way due to the way I 
> split the 
> arguments with '--' - the intention was to keep it for bw compatibility.
> 
> It would be good to know if people rely on using CHECK with C={1,2} for 
> anything beside the checkers supported by runchecks today

I do. Here, I use:

$ make ARCH=i386  CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 
CHECK='compile_checks' M=drivers/media

Where "compile_checks" is actually a small script that calls both
smatch and sparse:

#!/bin/bash
/devel/smatch/smatch -p=kernel $@
/devel/sparse/sparse $@

So, I'm not sure why we need something else. That said, I didn't look
on its code, but looking on its diffstat:

 Makefile   |  23 +-
 scripts/Makefile.build |   4 +-
 scripts/runchecks  | 734 ++-
 scripts/runchecks.cfg  |  63 ++-
 scripts/runchecks_help.txt |  43 ++-

Using a 734 lines python program just to do an exec on an external checker
seems too much!

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: scripts/kernel-doc: no warning or error on lots of missing function parameters

[Mauro Carvalho Chehab]

Em Sat, 30 Dec 2017 10:38:03 -0800
Randy Dunlap <rdun...@infradead.org> escreveu:

> >>>> Using linux-next-20171222, with its ("new") scripts/kernel-doc, I see
> >>>>
> >>>>> grep -c  not.described doc005.out
> >>>> 86
> >>>>
> >>>> but if I use scripts/kernel-doc from linux-4.15-rc5 (in 
> >>>> linux-next-20171222), I see
> >>>>
> >>>>> grep -c No.description.found doc006.out
> >>>> 305

> > $ git checkout next-20171221  
> 
> Please try it with linux-next-20171222 instead of 1221.
> It has many more patches to scripts/kernel-doc.

OK, now I was able to reproduce the issue. The problem is that the
logic with inhibits warning outputs is incomplete: it doesn't take
into account "-export" and "-internal" command line arguments.
Sorry for the mess.

Please check if the enclosed patches fix the issue.

Regards,
Mauro


[PATCH] scripts: kernel_doc: better handle show warnings logic

The logic with inhibits warnings for definitions that is not
output is incomplete: it doesn't cover the cases where
OUTPUT_INTERNAL and OUTPUT_EXPORTED are used.

As the most common case is OUTPUT_ALL, place it first,
in order to optimize a litte bit the check logic.

Fixes: 2defb2729217 ("scripts: kernel-doc: apply filtering rules to warnings")
Reported-by: Randy Dunlap <rdun...@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 1e2b35ce1c9d..fee8952037b1 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1140,6 +1140,44 @@ sub dump_struct($$) {
 }
 }
 
+
+sub show_warnings($$) {
+   my $functype = shift;
+   my $name = shift;
+
+   return 1 if ($output_selection == OUTPUT_ALL);
+
+   if ($output_selection == OUTPUT_EXPORTED) {
+   if (defined($function_table{$name})) {
+   return 1;
+   } else {
+   return 0;
+   }
+   }
+if ($output_selection == OUTPUT_INTERNAL) {
+   if (!($functype eq "function" && 
defined($function_table{$name}))) {
+   return 1;
+   } else {
+   return 0;
+   }
+   }
+   if ($output_selection == OUTPUT_INCLUDE) {
+   if (defined($function_table{$name})) {
+   return 1;
+   } else {
+   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()");
+}
+
 sub dump_enum($$) {
 my $x = shift;
 my $file = shift;
@@ -1160,11 +1198,7 @@ sub dump_enum($$) {
push @parameterlist, $arg;
if (!$parameterdescs{$arg}) {
$parameterdescs{$arg} = $undescribed;
-   if (($output_selection == OUTPUT_ALL) ||
-   ($output_selection == OUTPUT_INCLUDE &&
-defined($function_table{$declaration_name})) ||
-   ($output_selection == OUTPUT_EXCLUDE &&
-!defined($function_table{$declaration_name}))) {
+   if (show_warnings("enum", $declaration_name)) {
print STDERR "${file}:$.: warning: Enum value '$arg' 
not described in enum '$declaration_name'\n";
}
}
@@ -1173,11 +1207,7 @@ sub dump_enum($$) {
 
while (my ($k, $v) = each %parameterdescs) {
if (!exists($_members{$k})) {
-   if (($output_selection == OUTPUT_ALL) ||
-   ($output_selection == OUTPUT_INCLUDE &&
-defined($function_table{$declaration_name})) ||
-   ($output_selection == OUTPUT_EXCLUDE &&
-!defined($function_table{$declaration_name}))) {
+   if (show_warnings("enum", $declaration_name)) {
 print STDERR "${file}:$.: warning: Excess enum value '$k' 
description in '$declaration_name'\n";
}
}
@@ -1385,11 +1415,7 @@ sub push_parameter() {
if (!defined $parameterdescs{$param} && $param !~ /^#/) {
$parameterdescs{$param} = $undescribed;
 
-   if (($output_selection == OUTPUT_ALL) ||
-   ($output_selection == OUTPUT_INCLUDE &&
-defined($function_table{$declaration_name})) ||
-   ($output_selection == OUTPUT_EXCLUDE &&
-!defined($function_table{$de

Re: scripts/kernel-doc: no warning or error on lots of missing function parameters

[Mauro Carvalho Chehab]

Em Fri, 29 Dec 2017 20:12:15 -0800
Randy Dunlap <rdun...@infradead.org> escreveu:

> On 12/29/2017 06:28 PM, Mauro Carvalho Chehab wrote:
> > Em Fri, 29 Dec 2017 18:17:08 -0800
> > Randy Dunlap <rdun...@infradead.org> escreveu:
> >   
> >> In linux-next-20171222, this message:
> >>
> >>print STDERR "${file}:$.: warning:" .
> >>" No description found for parameter '$param'\n";
> >>
> >> has roughly/approximately been replaced with:
> >>
> >>print STDERR
> >>"${file}:$.: warning: Function parameter or member '$param' not 
> >> described in '$declaration_name'\n";
> >>
> >>
> >> Using linux-next-20171222, with its ("new") scripts/kernel-doc, I see
> >>  
> >>> grep -c  not.described doc005.out  
> >> 86
> >>
> >> but if I use scripts/kernel-doc from linux-4.15-rc5 (in 
> >> linux-next-20171222), I see
> >>  
> >>> grep -c No.description.found doc006.out  
> >> 305
> >>
> >>
> >> This is not good.  
> > 
> > Actually, if you look at the messages produced before linux-next, you'll
> > notice that the *same* error is reported multiple times.
> > 
> > The problem is that some headers are included multiple times:
> > 
> > $ git grep include/net/cfg80211.h Documentation/|wc -l
> > 111
> > 
> > If you look inside Documentation/driver-api/80211/cfg80211.rst,
> > you'll see:
> > 
> > .. kernel-doc:: include/net/cfg80211.h
> >:functions: ieee80211_channel_flags
> > 
> > .. kernel-doc:: include/net/cfg80211.h
> >:functions: ieee80211_channel
> > 
> > ...
> > 
> > With the old incarnation of kernel-doc, every time it parses an
> > script, it generate warnings for all symbols, *including* the
> > ones that aren't part of the kernel-doc output. The one at
> > linux-next has an extra logic that, when "functions" is used,
> > it will only output warnings for the symbol mentioned there,
> > with prevents it to repeat the same error report every time.
> > 
> > I suspect that, if you do:
> > 
> > grep No.description.found doc006.out|sort|uniq|wc -l  
> 
> That (copy-and-pasted to prevent typos) gives me 304 (i.e., one less).
> 
> > you'll see that the number of errors on 4.15-rc5 is actually
> > smaller than on linux-next, as it now reports missing symbols
> > on nested structs and unions.  
> 
> There are definitely missing parameter descriptions that are not being
> reported in linux-next.  Here's one such example (still working in
> linux-next-20171222, just with differing versions of scripts/kernel-doc).
> 
> kernel-doc from 4.15-rc5:
> 
> ../net/core/dev.c:6400: warning: No description found for parameter 'extack'
> ../net/core/dev.c:6423: warning: No description found for parameter 'extack'
> 
> kernel-doc from linux-next-20171222:
> 
> {those reports are missing but the descriptions are also missing}

Hmm... here, it showed it:

$ git checkout next-20171221
$ make SPHINXDIRS=networking htmldocs
  SPHINX  htmldocs --> 
file:///devel/v4l/linux-next/Documentation/output/networking
  PARSE   include/uapi/linux/dvb/audio.h
  PARSE   include/uapi/linux/dvb/ca.h
  PARSE   include/uapi/linux/dvb/dmx.h
  PARSE   include/uapi/linux/dvb/frontend.h
  PARSE   include/uapi/linux/dvb/net.h
  PARSE   include/uapi/linux/dvb/video.h
  PARSE   include/uapi/linux/videodev2.h
  PARSE   include/uapi/linux/media.h
  PARSE   include/uapi/linux/cec.h
  PARSE   include/uapi/linux/lirc.h
Running Sphinx v1.4.9
making output directory...
load additional sphinx-config: 
/devel/v4l/linux-next/Documentation/networking/conf.py
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
./net/core/dev.c:1695: warning: Excess function parameter 'dev' description in 
'call_netdevice_notifiers_info'
./net/core/dev.c:6398: warning: No description found for parameter 'extack'
./net/core/dev.c:6421: warning: No description found for parameter 'extack'
./include/linux/phylink.h:56: warning: No description found for parameter 
'__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising'
./include/linux/phylink.h:56: warning: No description found for parameter 
'__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising'
./include/linux/phylink.h:56: warning: Excess struct member 'advertising' 
description in 'phylink_link_state'
./include/linux/phylink.h:56: warning: Excess struct member 'lp_advertising' 
description in 'phylink

Re: scripts/kernel-doc: no warning or error on lots of missing function parameters

[Mauro Carvalho Chehab]

Em Fri, 29 Dec 2017 18:17:08 -0800
Randy Dunlap  escreveu:

> In linux-next-20171222, this message:
> 
>   print STDERR "${file}:$.: warning:" .
>   " No description found for parameter '$param'\n";
> 
> has roughly/approximately been replaced with:
> 
>   print STDERR
>   "${file}:$.: warning: Function parameter or member '$param' not 
> described in '$declaration_name'\n";
> 
> 
> Using linux-next-20171222, with its ("new") scripts/kernel-doc, I see
> 
> > grep -c  not.described doc005.out
> 86
> 
> but if I use scripts/kernel-doc from linux-4.15-rc5 (in linux-next-20171222), 
> I see
> 
> > grep -c No.description.found doc006.out
> 305
> 
> 
> This is not good.

Actually, if you look at the messages produced before linux-next, you'll
notice that the *same* error is reported multiple times.

The problem is that some headers are included multiple times:

$ git grep include/net/cfg80211.h Documentation/|wc -l
111

If you look inside Documentation/driver-api/80211/cfg80211.rst,
you'll see:

.. kernel-doc:: include/net/cfg80211.h
   :functions: ieee80211_channel_flags

.. kernel-doc:: include/net/cfg80211.h
   :functions: ieee80211_channel

...

With the old incarnation of kernel-doc, every time it parses an
script, it generate warnings for all symbols, *including* the
ones that aren't part of the kernel-doc output. The one at
linux-next has an extra logic that, when "functions" is used,
it will only output warnings for the symbol mentioned there,
with prevents it to repeat the same error report every time.

I suspect that, if you do:

grep No.description.found doc006.out|sort|uniq|wc -l

you'll see that the number of errors on 4.15-rc5 is actually
smaller than on linux-next, as it now reports missing symbols
on nested structs and unions.

Regards,

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/11] media: dvb_vb2: fix a warning about streamoff logic

[Mauro Carvalho Chehab]

Em Thu, 21 Dec 2017 14:18:04 -0200
Mauro Carvalho Chehab <mche...@s-opensource.com> escreveu:

> The streamoff logic is causing those warnings:
> 
>  WARNING: CPU: 3 PID: 3382 at drivers/media/v4l2-core/videobuf2-core.c:1652 
> __vb2_queue_cancel+0x177/0x250 [videobuf2_core]
>  Modules linked in: bnep fuse xt_CHECKSUM iptable_mangle tun ebtable_filter 
> ebtables ip6table_filter ip6_tables xt_physdev br_netfilter bluetooth bridge 
> rfkill ecdh_generic stp llc nf_log_ipv4 nf_log_common xt_LOG xt_conntrack 
> ipt_MASQUERADE nf_nat_masquerade_ipv4 iptable_nat nf_conntrack_ipv4 
> nf_defrag_ipv4 nf_nat_ipv4 nf_nat nf_conntrack libcrc32c sunrpc vfat fat 
> snd_hda_codec_hdmi rc_dib0700_nec i915 rc_pinnacle_pctv_hd em28xx_rc a8293 
> ts2020 m88ds3103 i2c_mux em28xx_dvb dib8000 dvb_usb_dib0700 dib0070 dib7000m 
> dib0090 dvb_usb dvb_core uvcvideo snd_usb_audio videobuf2_v4l2 dib3000mc 
> videobuf2_vmalloc videobuf2_memops dibx000_common videobuf2_core rc_core 
> snd_usbmidi_lib snd_rawmidi em28xx tveeprom v4l2_common videodev media 
> intel_rapl x86_pkg_temp_thermal intel_powerclamp coretemp snd_hda_intel
>  kvm_intel snd_hda_codec kvm snd_hwdep snd_hda_core snd_seq irqbypass 
> crct10dif_pclmul crc32_pclmul i2c_algo_bit ghash_clmulni_intel snd_seq_device 
> drm_kms_helper snd_pcm intel_cstate intel_uncore snd_timer tpm_tis drm 
> mei_wdt iTCO_wdt iTCO_vendor_support tpm_tis_core snd intel_rapl_perf mei_me 
> mei tpm i2c_i801 soundcore lpc_ich video binfmt_misc hid_logitech_hidpp 
> hid_logitech_dj e1000e crc32c_intel ptp pps_core analog gameport joydev
>  CPU: 3 PID: 3382 Comm: lt-dvbv5-zap Not tainted 4.14.0+ #3
>  Hardware name:  /D53427RKE, BIOS 
> RKPPT10H.86A.0048.2017.0506.1545 05/06/2017
>  task: 94b93bbe1e40 task.stack: b7a98320c000
>  RIP: 0010:__vb2_queue_cancel+0x177/0x250 [videobuf2_core]
>  RSP: 0018:b7a98320fd40 EFLAGS: 00010202
>  RAX: 0001 RBX: 94b92ff72428 RCX: 
>  RDX: 0001 RSI: 0001 RDI: 94b92ff72428
>  RBP: b7a98320fd68 R08: 94b92ff725d8 R09: b7a98320fcc8
>  R10: 94b978003d98 R11: 94b92ff72428 R12: 94b92ff72428
>  R13: 0282 R14: 94b92059ae20 R15: dead0100
>  FS:  () GS:94b99e38() knlGS:
>  CS:  0010 DS:  ES:  CR0: 80050033
>  CR2: 555953007d70 CR3: 00012be09004 CR4: 001606e0
>  Call Trace:
>   vb2_core_streamoff+0x28/0x90 [videobuf2_core]
>   dvb_vb2_stream_off+0xd1/0x150 [dvb_core]
>   dvb_dvr_release+0x114/0x120 [dvb_core]
>   __fput+0xdf/0x1e0
>   fput+0xe/0x10
>   task_work_run+0x94/0xc0
>   do_exit+0x2dc/0xba0
>   do_group_exit+0x47/0xb0
>   SyS_exit_group+0x14/0x20
>   entry_SYSCALL_64_fastpath+0x1a/0xa5
>  RIP: 0033:0x7f775e931ed8
>  RSP: 002b:7fff07019d68 EFLAGS: 0246 ORIG_RAX: 00e7
>  RAX: ffda RBX: 01d02690 RCX: 7f775e931ed8
>  RDX: 0001 RSI: 003c RDI: 0001
>  RBP: 7fff0701a500 R08: 00e7 R09: ff70
>  R10: 7f775e854dd8 R11: 0246 R12: 
>  R13: 035fa000 R14: 000a R15: 000a
>  Code: 00 00 04 74 1c 44 89 e8 49 83 c5 01 41 39 84 24 88 01 00 00 77 8a 5b 
> 41 5c 41 5d 41 5e 41 5f 5d c3 48 89 df e8 bb fd ff ff eb da <0f> ff 41 8b b4 
> 24 88 01 00 00 85 f6 74 34 bb 01 00 00 00 eb 10
> 
> There are actually two issues here:
> 
> 1) list_del() should be called when changing the buffer state;
> 
> 2) The logic with marks the buffers as done is at the wrong place.
> 
> Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>

I ended by sending a wrong version. The one I sent causes a list
corruption, as it deletes a queued value without marking the buffer
as done:

[  627.233534] list_del corruption, a0aa01182e20->next is 
LIST_POISON1 (dead0100)


Regards,
Mauro



[PATCH] media: dvb_vb2: fix a warning about streamoff logic

The streamoff logic is causing those warnings:

 WARNING: CPU: 3 PID: 3382 at drivers/media/v4l2-core/videobuf2-core.c:1652 
__vb2_queue_cancel+0x177/0x250 [videobuf2_core]
 Modules linked in: bnep fuse xt_CHECKSUM iptable_mangle tun ebtable_filter 
ebtables ip6table_filter ip6_tables xt_physdev br_netfilter bluetooth bridge 
rfkill ecdh_generic stp llc nf_log_ipv4 nf_log_common xt_LOG xt_conntrack 
ipt_MASQUERADE nf_nat_masquerade_ipv4 iptable_nat nf_conntrack_ipv4 
nf_defrag_ipv4 nf_nat_ipv4 nf_nat nf_conntrack libcrc32c sunrpc vfat fat 
snd_hda_codec_hdmi rc_dib0700_nec i915 rc_pinnacle_pctv_hd em28xx_rc a8293 
ts2020 m88ds3103 i2c_mux em28xx_dvb dib8000 dvb_usb_dib0700 dib0070 dib7000m 
dib0090 dvb_usb dvb_core uvcvideo snd_usb_audio videobu

Re: [PATCH v4 00/18] kernel-doc: add supported to document nested structs

[Mauro Carvalho Chehab]

Em Thu, 21 Dec 2017 14:08:43 -0700
Jonathan Corbet <cor...@lwn.net> escreveu:

> On Mon, 18 Dec 2017 10:30:01 -0200
> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> 
> > This is a rebased version of my patch series that add support for
> > nested structs on kernel-doc. With this version, it won't produce anymore
> > hundreds of identical warnings, as patch 17 removes the warning
> > duplication.
> > 
> > Excluding warnings about duplicated Note: section at hash.h, before
> > this series, it reports 166 kernel-doc warnings. After this patch series,
> > it reports 123 kernel-doc warnings, being 51 from DVB. I have already a 
> > patch
> > series that will cleanup those new DVB warnings due to nested structs.
> > 
> > So, the net result is that the number of warnings is reduced with
> > this version.  
> 
> This seems like a great set of improvements overall, and I love getting
> rid of all that old kernel-doc code. 

> I will note that it makes a full
> htmldocs build take 20-30 seconds longer, which is not entirely
> welcome, but so be it. Someday, I guess, $SOMEBODY should see if there's
> some low-hanging optimization fruit there.

Yeah. Well, I used a recursive algorithm, with can be painfull if there
are mang things to parse.

Anyway, I didn't notice it, because there was a major performance regression
that happened recently that it is affecting all my sphinx builds: trying to
compile stuff in parallel with SPHINXOPTS=-j5 is crashing with:

# Loaded extensions:
#   kfigure (1.0.0) from /devel/v4l/patchwork/Documentation/sphinx/kfigure.py
#   kernel_include (1.0) from 
/devel/v4l/patchwork/Documentation/sphinx/kernel_include.py
#   rstFlatTable (1.0) from 
/devel/v4l/patchwork/Documentation/sphinx/rstFlatTable.py
#   cdomain (1.0) from /devel/v4l/patchwork/Documentation/sphinx/cdomain.py
#   kerneldoc (1.0) from /devel/v4l/patchwork/Documentation/sphinx/kerneldoc.py
#   alabaster (0.7.10) from 
/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/alabaster/__init__.pyc
#   sphinx.ext.imgmath (1.4.9) from 
/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/ext/imgmath.pyc
Traceback (most recent call last):
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/cmdline.py", 
line 244, in main
app.build(opts.force_all, filenames)
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/application.py", 
line 297, in build
self.builder.build_update()
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py",
 line 251, in build_update
'out of date' % len(to_build))
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py",
 line 265, in build
self.doctreedir, self.app))
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/environment.py", 
line 567, in update
self._read_parallel(docnames, app, nproc=app.parallel)
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/environment.py", 
line 625, in _read_parallel
tasks.join()
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/util/parallel.py",
 line 92, in join
self._join_one()
  File 
"/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/util/parallel.py",
 line 97, in _join_one
exc, result = pipe.recv()
EOFError

I had to change my build scripts to remove parallel build, with increased
*a lot* the building time. So, right now, I just go out to take a coffee
or two when building documentation, as, without -j (even without this
patch series), is really slow.

If someone wants to look into it, the breakage happened by the time
I upgraded to Fedora 27 and Kernel 4.14 was released. Yet, I'm using
pip for Sphinx.

So, I dunno what's the culprit. I didn't have time yet to investigate.

> Applied, thanks.

Thank you!

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 09/11] media: dvb-core: get rid of mmap reserved field

[Mauro Carvalho Chehab]

The "reserved" field was a way, used at V4L2 API, to add new
data to existing structs without breaking userspace. However,
there are now clever ways of doing that, without needing to add
an uneeded overhead. So, get rid of them.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/media/uapi/dvb/dmx-expbuf.rst   | 2 --
 Documentation/media/uapi/dvb/dmx-qbuf.rst | 2 --
 Documentation/media/uapi/dvb/dmx-querybuf.rst | 2 --
 Documentation/media/uapi/dvb/dmx-reqbufs.rst  | 2 --
 drivers/media/dvb-core/dvb_vb2.c  | 1 -
 include/uapi/linux/dvb/dmx.h  | 3 ---
 6 files changed, 12 deletions(-)

diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst 
b/Documentation/media/uapi/dvb/dmx-expbuf.rst
index 51df34c6fb59..2d96cfe891df 100644
--- a/Documentation/media/uapi/dvb/dmx-expbuf.rst
+++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst
@@ -36,8 +36,6 @@ This ioctl is an extension to the memory mapping I/O method.
 It can be used to export a buffer as a DMABUF file at any time after
 buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl.
 
-The ``reserved`` array must be zeroed before calling it.
-
 To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`.
 Applications must set the ``index`` field. Valid index numbers
 range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS`
diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst 
b/Documentation/media/uapi/dvb/dmx-qbuf.rst
index b20b8153d48d..b48c4931658e 100644
--- a/Documentation/media/uapi/dvb/dmx-qbuf.rst
+++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst
@@ -45,8 +45,6 @@ numbers range from zero to the number of buffers allocated 
with
 one. The contents of the struct :c:type:`dmx_buffer` returned
 by a :ref:`DMX_QUERYBUF` ioctl will do as well.
 
-The and ``reserved`` field must be set to 0.
-
 When ``DMX_QBUF`` is called with a pointer to this structure, it locks the
 memory pages of the buffer in physical memory, so they cannot be swapped
 out to disk. Buffers remain locked until dequeued, until the
diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst 
b/Documentation/media/uapi/dvb/dmx-querybuf.rst
index 46a50f191b10..89481e24bb86 100644
--- a/Documentation/media/uapi/dvb/dmx-querybuf.rst
+++ b/Documentation/media/uapi/dvb/dmx-querybuf.rst
@@ -36,8 +36,6 @@ This ioctl is part of the mmap streaming I/O method. It can
 be used to query the status of a buffer at any time after buffers have
 been allocated with the :ref:`DMX_REQBUFS` ioctl.
 
-The ``reserved`` array must be zeroed before calling it.
-
 Applications set the ``index`` field. Valid index numbers range from zero
 to the number of buffers allocated with :ref:`DMX_REQBUFS`
 (struct :c:type:`dvb_requestbuffers` ``count``) minus one.
diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst 
b/Documentation/media/uapi/dvb/dmx-reqbufs.rst
index 0749623d9d83..14b80d60bf35 100644
--- a/Documentation/media/uapi/dvb/dmx-reqbufs.rst
+++ b/Documentation/media/uapi/dvb/dmx-reqbufs.rst
@@ -42,8 +42,6 @@ allocated by applications through a device driver, and this 
ioctl only
 configures the driver into DMABUF I/O mode without performing any direct
 allocation.
 
-The ``reserved`` array must be zeroed before calling it.
-
 To allocate device buffers applications initialize all fields of the
 struct :c:type:`dmx_requestbuffers` structure. They set the  ``count`` field
 to the desired number of buffers,  and ``size`` to the size of each
diff --git a/drivers/media/dvb-core/dvb_vb2.c b/drivers/media/dvb-core/dvb_vb2.c
index 277d33b83089..7b1663f64e84 100644
--- a/drivers/media/dvb-core/dvb_vb2.c
+++ b/drivers/media/dvb-core/dvb_vb2.c
@@ -140,7 +140,6 @@ static void _fill_dmx_buffer(struct vb2_buffer *vb, void 
*pb)
b->length = vb->planes[0].length;
b->bytesused = vb->planes[0].bytesused;
b->offset = vb->planes[0].m.offset;
-   memset(b->reserved, 0, sizeof(b->reserved));
dprintk(3, "[%s]\n", ctx->name);
 }
 
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
index e212aa18ad78..5f3c5a918f00 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -229,7 +229,6 @@ struct dmx_buffer {
__u32   bytesused;
__u32   offset;
__u32   length;
-   __u32   reserved[4];
 };
 
 /**
@@ -244,7 +243,6 @@ struct dmx_buffer {
 struct dmx_requestbuffers {
__u32   count;
__u32   size;
-   __u32   reserved[2];
 };
 
 /**
@@ -266,7 +264,6 @@ struct dmx_exportbuffer {
__u32   index;
__u32   flags;
__s32   fd;
-   __u32   reserved[5];
 };
 
 #define DMX_START_IO('o', 41)
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
th

[PATCH 07/11] media: dvb uAPI docs: document demux mmap/munmap syscalls

[Mauro Carvalho Chehab]

With the new dmx mmap interface, those two syscalls are now
handled by the subsystem. Document them.

This patch is based on the V4L2 text for those ioctls.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/media/uapi/dvb/dmx-mmap.rst   | 116 
 Documentation/media/uapi/dvb/dmx-munmap.rst |  54 +
 Documentation/media/uapi/dvb/dmx_fcalls.rst |   2 +
 3 files changed, 172 insertions(+)
 create mode 100644 Documentation/media/uapi/dvb/dmx-mmap.rst
 create mode 100644 Documentation/media/uapi/dvb/dmx-munmap.rst

diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst 
b/Documentation/media/uapi/dvb/dmx-mmap.rst
new file mode 100644
index ..15d107348b9f
--- /dev/null
+++ b/Documentation/media/uapi/dvb/dmx-mmap.rst
@@ -0,0 +1,116 @@
+.. _dmx-mmap:
+
+*
+Digital TV mmap()
+*
+
+Name
+
+
+dmx-mmap - Map device memory into application address space
+
+.. warning:: this API is still experimental
+
+Synopsis
+
+
+.. code-block:: c
+
+#include 
+#include 
+
+
+.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, 
int fd, off_t offset )
+:name: dmx-mmap
+
+Arguments
+=
+
+``start``
+Map the buffer to this address in the application's address space.
+When the ``MAP_FIXED`` flag is specified, ``start`` must be a
+multiple of the pagesize and mmap will fail when the specified
+address cannot be used. Use of this option is discouraged;
+applications should just specify a ``NULL`` pointer here.
+
+``length``
+Length of the memory area to map. This must be a multiple of the
+DVB packet length (188, on most drivers).
+
+``prot``
+The ``prot`` argument describes the desired memory protection.
+Regardless of the device type and the direction of data exchange it
+should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
+and write access to image buffers. Drivers should support at least
+this combination of flags.
+
+``flags``
+The ``flags`` parameter specifies the type of the mapped object,
+mapping options and whether modifications made to the mapped copy of
+the page are private to the process or are to be shared with other
+references.
+
+``MAP_FIXED`` requests that the driver selects no other address than
+the one specified. If the specified address cannot be used,
+:ref:`mmap() ` will fail. If ``MAP_FIXED`` is specified,
+``start`` must be a multiple of the pagesize. Use of this option is
+discouraged.
+
+One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
+``MAP_SHARED`` allows applications to share the mapped memory with
+other (e. g. child-) processes.
+
+.. note::
+
+   The Linux Digital TV applications should not set the
+   ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
+   flags.
+
+``fd``
+File descriptor returned by :ref:`open() `.
+
+``offset``
+Offset of the buffer in device memory, as returned by
+:ref:`DMX_QUERYBUF` ioctl.
+
+
+Description
+===
+
+The :ref:`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.
+
+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() ` function is used.
+
+
+Return Value
+
+
+On success :ref:`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:
+
+EBADF
+``fd`` is not a valid file descriptor.
+
+EACCES
+``fd`` is not open for reading and writing.
+
+EINVAL
+The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
+they are too large, or not aligned on a ``PAGESIZE`` boundary.)
+
+The ``flags`` or ``prot`` value is not supported.
+
+No buffers have been allocated with the
+:ref:`DMX_REQBUFS` ioctl.
+
+ENOMEM
+Not enough physical or virtual memory was available to complete the
+request.
diff --git a/Documentation/media/uapi/dvb/dmx-munmap.rst 
b/Documentation/media/uapi/dvb/dmx-munmap.rst
new file mode 100644
index ..d77218732bb6
--- /dev/null
+++ b/Documentation/media/uapi/dvb/dmx-munmap.rst
@@ -0,0 +1,54 @@
+.. _dmx-munmap:
+
+
+DVB munmap()
+
+
+Name
+
+
+dmx-munmap - Unmap device memory
+
+.. warning:: This API is still experimental.
+
+
+Synopsis
+
+
+.. code-block:: c
+
+#include 
+#include 
+
+
+.. c:function:: int munmap( void *start, size_t length )
+:name: dmx-munmap
+
+Arguments
+=
+
+``start``
+Address of the mapped 

[PATCH 02/11] media: videobuf2: Add new uAPI for DVB streaming I/O

[Mauro Carvalho Chehab]

From: Satendra Singh Thakur <satendr...@samsung.com>

Adds a new uAPI for DVB to use streaming I/O which is implemented
based on videobuf2, using those new ioctls:

- DMX_REQBUFS:  Request kernel to allocate buffers which count and size
are dedicated by user.
- DMX_QUERYBUF: Get the buffer information like a memory offset which
will mmap() and be shared with user-space.
- DMX_EXPBUF:   Just for testing whether buffer-exporting success or not.
- DMX_QBUF: Pass the buffer to kernel-space.
- DMX_DQBUF:Get back the buffer which may contain TS data.

Originally developed by: Junghak Sung <jh1009.s...@samsung.com>, as
seen at:
https://patchwork.linuxtv.org/patch/31613/
https://patchwork.kernel.org/patch/7334301/

The original patch was written before merging VB2-core functionalities
upstream. When such series was added, several adjustments were made,
fixing some issues with V4L2, causing the original patch to be
non-trivially rebased.

After rebased, a few bugs in the patch were fixed. The patch was
also enhanced it and polling functionality got added.

The main changes over the original patch are:

dvb_vb2_fill_buffer():
- Set the size of the outgoing buffer after while loop using
  vb2_set_plane_payload;

- Added NULL check for source buffer as per normal convention
  of demux driver, this is called twice, first time with valid
  buffer second time with NULL pointer, if its not handled,
  it will result in  crash

- Restricted spinlock for only list_* operations

dvb_vb2_init():
- Restricted q->io_modes to only VB2_MMAP as its the only
  supported mode

dvb_vb2_release():
- Replaced the && in if condiion with &, because otherwise
  it was always getting satisfied.

dvb_vb2_stream_off():
- Added list_del code for enqueud buffers upon stream off

dvb_vb2_poll():
- Added this new function in order to support polling

dvb_demux_poll() and dvb_dvr_poll()
- dvb_vb2_poll() is now called from these functions

- Ported this patch and latest videobuf2 to lower kernel versions and
  tested auto scan.

[mche...@s-opensource.com: checkpatch fixes]
Co-developed-by: Junghak Sung <jh1009.s...@samsung.com>
Signed-off-by: Junghak Sung <jh1009.s...@samsung.com>
Signed-off-by: Geunyoung Kim <nenggun@samsung.com>
Acked-by: Seung-Woo Kim <sw0312@samsung.com>
Acked-by: Inki Dae <inki@samsung.com>
Signed-off-by: Satendra Singh Thakur <satendr...@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/dvb-core/Makefile  |   2 +-
 drivers/media/dvb-core/dmxdev.c  | 196 +++---
 drivers/media/dvb-core/dmxdev.h  |   4 +
 drivers/media/dvb-core/dvb_vb2.c | 423 +++
 drivers/media/dvb-core/dvb_vb2.h |  72 +++
 include/uapi/linux/dvb/dmx.h |  66 +-
 6 files changed, 733 insertions(+), 30 deletions(-)
 create mode 100644 drivers/media/dvb-core/dvb_vb2.c
 create mode 100644 drivers/media/dvb-core/dvb_vb2.h

diff --git a/drivers/media/dvb-core/Makefile b/drivers/media/dvb-core/Makefile
index 47e2e391bfb8..bbc65dfa0a8e 100644
--- a/drivers/media/dvb-core/Makefile
+++ b/drivers/media/dvb-core/Makefile
@@ -7,6 +7,6 @@ dvb-net-$(CONFIG_DVB_NET) := dvb_net.o
 
 dvb-core-objs := dvbdev.o dmxdev.o dvb_demux.o \
 dvb_ca_en50221.o dvb_frontend.o\
-$(dvb-net-y) dvb_ringbuffer.o dvb_math.o
+$(dvb-net-y) dvb_ringbuffer.o dvb_vb2.o dvb_math.o
 
 obj-$(CONFIG_DVB_CORE) += dvb-core.o
diff --git a/drivers/media/dvb-core/dmxdev.c b/drivers/media/dvb-core/dmxdev.c
index 18e4230865be..4cbb9003a1ed 100644
--- a/drivers/media/dvb-core/dmxdev.c
+++ b/drivers/media/dvb-core/dmxdev.c
@@ -28,6 +28,7 @@
 #include 
 #include 
 #include "dmxdev.h"
+#include "dvb_vb2.h"
 
 static int debug;
 
@@ -138,14 +139,8 @@ static int dvb_dvr_open(struct inode *inode, struct file 
*file)
return -ENODEV;
}
 
-   if ((file->f_flags & O_ACCMODE) == O_RDWR) {
-   if (!(dmxdev->capabilities & DMXDEV_CAP_DUPLEX)) {
-   mutex_unlock(>mutex);
-   return -EOPNOTSUPP;
-   }
-   }
-
-   if ((file->f_flags & O_ACCMODE) == O_RDONLY) {
+   if (((file->f_flags & O_ACCMODE) == O_RDONLY) ||
+   ((file->f_flags & O_ACCMODE) == O_RDWR)) {
void *mem;
 
if (!dvbdev->readers) {
@@ -158,6 +153,8 @@ static int dvb_dvr_open(struct inode *inode, struct file 
*file)
return -ENOMEM;
}
dvb_ringbuffer_init(>dvr_buffer, mem, DVR_BUFFER_SIZE);
+   dvb_vb2_init(>dvr_vb2_ctx, "dvr",
+ 

[PATCH 06/11] media: move videobuf2 to drivers/media/common

[Mauro Carvalho Chehab]

Now that VB2 is used by both V4L2 and DVB core, move it to
the common part of the subsystem.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/common/Kconfig   |  1 +
 drivers/media/common/Makefile  |  2 +-
 drivers/media/common/videobuf/Kconfig  | 31 +
 drivers/media/common/videobuf/Makefile |  7 +
 .../videobuf}/videobuf2-core.c |  0
 .../videobuf}/videobuf2-dma-contig.c   |  0
 .../videobuf}/videobuf2-dma-sg.c   |  0
 .../{v4l2-core => common/videobuf}/videobuf2-dvb.c |  0
 .../videobuf}/videobuf2-memops.c   |  0
 .../videobuf}/videobuf2-v4l2.c |  0
 .../videobuf}/videobuf2-vmalloc.c  |  0
 drivers/media/v4l2-core/Kconfig| 32 --
 drivers/media/v4l2-core/Makefile   |  7 -
 13 files changed, 40 insertions(+), 40 deletions(-)
 create mode 100644 drivers/media/common/videobuf/Kconfig
 create mode 100644 drivers/media/common/videobuf/Makefile
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-core.c (100%)
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-dma-contig.c 
(100%)
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-dma-sg.c (100%)
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-dvb.c (100%)
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-memops.c (100%)
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-v4l2.c (100%)
 rename drivers/media/{v4l2-core => common/videobuf}/videobuf2-vmalloc.c (100%)

diff --git a/drivers/media/common/Kconfig b/drivers/media/common/Kconfig
index 326df0ad75c0..cdfc905967dc 100644
--- a/drivers/media/common/Kconfig
+++ b/drivers/media/common/Kconfig
@@ -16,6 +16,7 @@ config CYPRESS_FIRMWARE
tristate "Cypress firmware helper routines"
depends on USB
 
+source "drivers/media/common/videobuf/Kconfig"
 source "drivers/media/common/b2c2/Kconfig"
 source "drivers/media/common/saa7146/Kconfig"
 source "drivers/media/common/siano/Kconfig"
diff --git a/drivers/media/common/Makefile b/drivers/media/common/Makefile
index 2d1b0a025084..f24b5ed39982 100644
--- a/drivers/media/common/Makefile
+++ b/drivers/media/common/Makefile
@@ -1,4 +1,4 @@
-obj-y += b2c2/ saa7146/ siano/ v4l2-tpg/
+obj-y += b2c2/ saa7146/ siano/ v4l2-tpg/ videobuf/
 obj-$(CONFIG_VIDEO_CX2341X) += cx2341x.o
 obj-$(CONFIG_VIDEO_TVEEPROM) += tveeprom.o
 obj-$(CONFIG_CYPRESS_FIRMWARE) += cypress_firmware.o
diff --git a/drivers/media/common/videobuf/Kconfig 
b/drivers/media/common/videobuf/Kconfig
new file mode 100644
index ..5df05250de94
--- /dev/null
+++ b/drivers/media/common/videobuf/Kconfig
@@ -0,0 +1,31 @@
+# Used by drivers that need Videobuf2 modules
+config VIDEOBUF2_CORE
+   select DMA_SHARED_BUFFER
+   tristate
+
+config VIDEOBUF2_MEMOPS
+   tristate
+   select FRAME_VECTOR
+
+config VIDEOBUF2_DMA_CONTIG
+   tristate
+   depends on HAS_DMA
+   select VIDEOBUF2_CORE
+   select VIDEOBUF2_MEMOPS
+   select DMA_SHARED_BUFFER
+
+config VIDEOBUF2_VMALLOC
+   tristate
+   select VIDEOBUF2_CORE
+   select VIDEOBUF2_MEMOPS
+   select DMA_SHARED_BUFFER
+
+config VIDEOBUF2_DMA_SG
+   tristate
+   depends on HAS_DMA
+   select VIDEOBUF2_CORE
+   select VIDEOBUF2_MEMOPS
+
+config VIDEOBUF2_DVB
+   tristate
+   select VIDEOBUF2_CORE
diff --git a/drivers/media/common/videobuf/Makefile 
b/drivers/media/common/videobuf/Makefile
new file mode 100644
index ..19de5ccda20b
--- /dev/null
+++ b/drivers/media/common/videobuf/Makefile
@@ -0,0 +1,7 @@
+
+obj-$(CONFIG_VIDEOBUF2_CORE) += videobuf2-core.o videobuf2-v4l2.o
+obj-$(CONFIG_VIDEOBUF2_MEMOPS) += videobuf2-memops.o
+obj-$(CONFIG_VIDEOBUF2_VMALLOC) += videobuf2-vmalloc.o
+obj-$(CONFIG_VIDEOBUF2_DMA_CONTIG) += videobuf2-dma-contig.o
+obj-$(CONFIG_VIDEOBUF2_DMA_SG) += videobuf2-dma-sg.o
+obj-$(CONFIG_VIDEOBUF2_DVB) += videobuf2-dvb.o
diff --git a/drivers/media/v4l2-core/videobuf2-core.c 
b/drivers/media/common/videobuf/videobuf2-core.c
similarity index 100%
rename from drivers/media/v4l2-core/videobuf2-core.c
rename to drivers/media/common/videobuf/videobuf2-core.c
diff --git a/drivers/media/v4l2-core/videobuf2-dma-contig.c 
b/drivers/media/common/videobuf/videobuf2-dma-contig.c
similarity index 100%
rename from drivers/media/v4l2-core/videobuf2-dma-contig.c
rename to drivers/media/common/videobuf/videobuf2-dma-contig.c
diff --git a/drivers/media/v4l2-core/videobuf2-dma-sg.c 
b/drivers/media/common/videobuf/videobuf2-dma-sg.c
similarity index 100%
rename from drivers/media/v4l2-core/videobuf2-dma-sg.c
rename to drivers/media/common/videobuf/videobuf2-dma-sg.c
diff --git a/drivers/media/v4l2-core/videobuf2-dvb.c 
b/drivers/media/comm

[PATCH 10/11] fs: compat_ioctl: add new DVB demux ioctls

[Mauro Carvalho Chehab]

Use trivial handling for the new DVB demux ioctls, as none
of them passes a pointer inside their structures.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 fs/compat_ioctl.c | 5 +
 1 file changed, 5 insertions(+)

diff --git a/fs/compat_ioctl.c b/fs/compat_ioctl.c
index bd5d91e119ca..cc71c3676ce2 100644
--- a/fs/compat_ioctl.c
+++ b/fs/compat_ioctl.c
@@ -1333,6 +1333,11 @@ COMPATIBLE_IOCTL(DMX_SET_PES_FILTER)
 COMPATIBLE_IOCTL(DMX_SET_BUFFER_SIZE)
 COMPATIBLE_IOCTL(DMX_GET_PES_PIDS)
 COMPATIBLE_IOCTL(DMX_GET_STC)
+COMPATIBLE_IOCTL(DMX_REQBUFS)
+COMPATIBLE_IOCTL(DMX_QUERYBUF)
+COMPATIBLE_IOCTL(DMX_EXPBUF)
+COMPATIBLE_IOCTL(DMX_QBUF)
+COMPATIBLE_IOCTL(DMX_DQBUF)
 COMPATIBLE_IOCTL(FE_GET_INFO)
 COMPATIBLE_IOCTL(FE_DISEQC_RESET_OVERLOAD)
 COMPATIBLE_IOCTL(FE_DISEQC_SEND_MASTER_CMD)
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 05/11] media: dvb_vb2: fix a warning about streamoff logic

[Mauro Carvalho Chehab]

The streamoff logic is causing those warnings:

 WARNING: CPU: 3 PID: 3382 at drivers/media/v4l2-core/videobuf2-core.c:1652 
__vb2_queue_cancel+0x177/0x250 [videobuf2_core]
 Modules linked in: bnep fuse xt_CHECKSUM iptable_mangle tun ebtable_filter 
ebtables ip6table_filter ip6_tables xt_physdev br_netfilter bluetooth bridge 
rfkill ecdh_generic stp llc nf_log_ipv4 nf_log_common xt_LOG xt_conntrack 
ipt_MASQUERADE nf_nat_masquerade_ipv4 iptable_nat nf_conntrack_ipv4 
nf_defrag_ipv4 nf_nat_ipv4 nf_nat nf_conntrack libcrc32c sunrpc vfat fat 
snd_hda_codec_hdmi rc_dib0700_nec i915 rc_pinnacle_pctv_hd em28xx_rc a8293 
ts2020 m88ds3103 i2c_mux em28xx_dvb dib8000 dvb_usb_dib0700 dib0070 dib7000m 
dib0090 dvb_usb dvb_core uvcvideo snd_usb_audio videobuf2_v4l2 dib3000mc 
videobuf2_vmalloc videobuf2_memops dibx000_common videobuf2_core rc_core 
snd_usbmidi_lib snd_rawmidi em28xx tveeprom v4l2_common videodev media 
intel_rapl x86_pkg_temp_thermal intel_powerclamp coretemp snd_hda_intel
 kvm_intel snd_hda_codec kvm snd_hwdep snd_hda_core snd_seq irqbypass 
crct10dif_pclmul crc32_pclmul i2c_algo_bit ghash_clmulni_intel snd_seq_device 
drm_kms_helper snd_pcm intel_cstate intel_uncore snd_timer tpm_tis drm mei_wdt 
iTCO_wdt iTCO_vendor_support tpm_tis_core snd intel_rapl_perf mei_me mei tpm 
i2c_i801 soundcore lpc_ich video binfmt_misc hid_logitech_hidpp hid_logitech_dj 
e1000e crc32c_intel ptp pps_core analog gameport joydev
 CPU: 3 PID: 3382 Comm: lt-dvbv5-zap Not tainted 4.14.0+ #3
 Hardware name:  /D53427RKE, BIOS 
RKPPT10H.86A.0048.2017.0506.1545 05/06/2017
 task: 94b93bbe1e40 task.stack: b7a98320c000
 RIP: 0010:__vb2_queue_cancel+0x177/0x250 [videobuf2_core]
 RSP: 0018:b7a98320fd40 EFLAGS: 00010202
 RAX: 0001 RBX: 94b92ff72428 RCX: 
 RDX: 0001 RSI: 0001 RDI: 94b92ff72428
 RBP: b7a98320fd68 R08: 94b92ff725d8 R09: b7a98320fcc8
 R10: 94b978003d98 R11: 94b92ff72428 R12: 94b92ff72428
 R13: 0282 R14: 94b92059ae20 R15: dead0100
 FS:  () GS:94b99e38() knlGS:
 CS:  0010 DS:  ES:  CR0: 80050033
 CR2: 555953007d70 CR3: 00012be09004 CR4: 001606e0
 Call Trace:
  vb2_core_streamoff+0x28/0x90 [videobuf2_core]
  dvb_vb2_stream_off+0xd1/0x150 [dvb_core]
  dvb_dvr_release+0x114/0x120 [dvb_core]
  __fput+0xdf/0x1e0
  fput+0xe/0x10
  task_work_run+0x94/0xc0
  do_exit+0x2dc/0xba0
  do_group_exit+0x47/0xb0
  SyS_exit_group+0x14/0x20
  entry_SYSCALL_64_fastpath+0x1a/0xa5
 RIP: 0033:0x7f775e931ed8
 RSP: 002b:7fff07019d68 EFLAGS: 0246 ORIG_RAX: 00e7
 RAX: ffda RBX: 01d02690 RCX: 7f775e931ed8
 RDX: 0001 RSI: 003c RDI: 0001
 RBP: 7fff0701a500 R08: 00e7 R09: ff70
 R10: 7f775e854dd8 R11: 0246 R12: 
 R13: 035fa000 R14: 000a R15: 000a
 Code: 00 00 04 74 1c 44 89 e8 49 83 c5 01 41 39 84 24 88 01 00 00 77 8a 5b 41 
5c 41 5d 41 5e 41 5f 5d c3 48 89 df e8 bb fd ff ff eb da <0f> ff 41 8b b4 24 88 
01 00 00 85 f6 74 34 bb 01 00 00 00 eb 10

There are actually two issues here:

1) list_del() should be called when changing the buffer state;

2) The logic with marks the buffers as done is at the wrong place.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/dvb-core/dvb_vb2.c | 33 -
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/drivers/media/dvb-core/dvb_vb2.c b/drivers/media/dvb-core/dvb_vb2.c
index 34193a4acc47..277d33b83089 100644
--- a/drivers/media/dvb-core/dvb_vb2.c
+++ b/drivers/media/dvb-core/dvb_vb2.c
@@ -89,8 +89,19 @@ static int _start_streaming(struct vb2_queue *vq, unsigned 
int count)
 static void _stop_streaming(struct vb2_queue *vq)
 {
struct dvb_vb2_ctx *ctx = vb2_get_drv_priv(vq);
+   struct dvb_buffer *buf;
+   unsigned long flags = 0;
 
dprintk(3, "[%s]\n", ctx->name);
+
+   spin_lock_irqsave(>slock, flags);
+   while (!list_empty(>dvb_q)) {
+   buf = list_entry(ctx->dvb_q.next,
+struct dvb_buffer, list);
+   vb2_buffer_done(>vb, VB2_BUF_STATE_ERROR);
+   list_del(>list);
+   }
+   spin_unlock_irqrestore(>slock, flags);
 }
 
 static void _dmxdev_lock(struct vb2_queue *vq)
@@ -224,21 +235,8 @@ int dvb_vb2_stream_off(struct dvb_vb2_ctx *ctx)
 {
struct vb2_queue *q = (struct vb2_queue *)>vb_q;
int ret;
-   unsigned long flags = 0;
 
ctx->state &= ~DVB_VB2_STATE_STREAMON;
-   spin_lock_irqsave(>slock, flags);
-   while (!list_empty(>dvb_q)) {
-   struct dvb_buffer   *buf;
-
-   buf = list_entry(ctx->dvb_q.next,
-  

[PATCH 04/11] media: vb2-core: add a new warning about pending buffers

[Mauro Carvalho Chehab]

There's a logic at the VB2 core that produces a WARN_ON if
there are still buffers waiting to be filled. However, it doesn't
indicate what buffers are still opened, with makes harder to
identify issues inside caller drivers.

So, add a new pr_warn() pointing to such buffers. That, together
with debug instrumentation inside the drivers can make easier to
identify where the problem is.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/v4l2-core/videobuf2-core.c | 5 -
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/media/v4l2-core/videobuf2-core.c 
b/drivers/media/v4l2-core/videobuf2-core.c
index 319ab8bf220f..064d3c6f1e74 100644
--- a/drivers/media/v4l2-core/videobuf2-core.c
+++ b/drivers/media/v4l2-core/videobuf2-core.c
@@ -1653,8 +1653,11 @@ static void __vb2_queue_cancel(struct vb2_queue *q)
 */
if (WARN_ON(atomic_read(>owned_by_drv_count))) {
for (i = 0; i < q->num_buffers; ++i)
-   if (q->bufs[i]->state == VB2_BUF_STATE_ACTIVE)
+   if (q->bufs[i]->state == VB2_BUF_STATE_ACTIVE) {
+   pr_warn("driver bug: stop_streaming operation 
is leaving buf %p in active state\n",
+   q->bufs[i]);
vb2_buffer_done(q->bufs[i], 
VB2_BUF_STATE_ERROR);
+   }
/* Must be zero now */
WARN_ON(atomic_read(>owned_by_drv_count));
}
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 03/11] media: vb2-core: add pr_fmt() macro

[Mauro Carvalho Chehab]

Simplify the pr_foo() macros by adding a pr_fmt() macro.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/v4l2-core/videobuf2-core.c | 30 --
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/drivers/media/v4l2-core/videobuf2-core.c 
b/drivers/media/v4l2-core/videobuf2-core.c
index 21017b478a34..319ab8bf220f 100644
--- a/drivers/media/v4l2-core/videobuf2-core.c
+++ b/drivers/media/v4l2-core/videobuf2-core.c
@@ -14,6 +14,8 @@
  * the Free Software Foundation.
  */
 
+#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
+
 #include 
 #include 
 #include 
@@ -32,10 +34,10 @@
 static int debug;
 module_param(debug, int, 0644);
 
-#define dprintk(level, fmt, arg...)  \
-   do {  \
-   if (debug >= level)   \
-   pr_info("vb2-core: %s: " fmt, __func__, ## arg); \
+#define dprintk(level, fmt, arg...)\
+   do {\
+   if (debug >= level) \
+   pr_info("%s: " fmt, __func__, ## arg);  \
} while (0)
 
 #ifdef CONFIG_VIDEO_ADV_DEBUG
@@ -460,12 +462,12 @@ static int __vb2_queue_free(struct vb2_queue *q, unsigned 
int buffers)
  q->cnt_wait_prepare != q->cnt_wait_finish;
 
if (unbalanced || debug) {
-   pr_info("vb2: counters for queue %p:%s\n", q,
+   pr_info("counters for queue %p:%s\n", q,
unbalanced ? " UNBALANCED!" : "");
-   pr_info("vb2: setup: %u start_streaming: %u 
stop_streaming: %u\n",
+   pr_info(" setup: %u start_streaming: %u 
stop_streaming: %u\n",
q->cnt_queue_setup, q->cnt_start_streaming,
q->cnt_stop_streaming);
-   pr_info("vb2: wait_prepare: %u wait_finish: %u\n",
+   pr_info(" wait_prepare: %u wait_finish: %u\n",
q->cnt_wait_prepare, q->cnt_wait_finish);
}
q->cnt_queue_setup = 0;
@@ -486,23 +488,23 @@ static int __vb2_queue_free(struct vb2_queue *q, unsigned 
int buffers)
  vb->cnt_buf_init != vb->cnt_buf_cleanup;
 
if (unbalanced || debug) {
-   pr_info("vb2:   counters for queue %p, buffer %d:%s\n",
+   pr_info("   counters for queue %p, buffer %d:%s\n",
q, buffer, unbalanced ? " UNBALANCED!" : "");
-   pr_info("vb2: buf_init: %u buf_cleanup: %u 
buf_prepare: %u buf_finish: %u\n",
+   pr_info(" buf_init: %u buf_cleanup: %u buf_prepare: 
%u buf_finish: %u\n",
vb->cnt_buf_init, vb->cnt_buf_cleanup,
vb->cnt_buf_prepare, vb->cnt_buf_finish);
-   pr_info("vb2: buf_queue: %u buf_done: %u\n",
+   pr_info(" buf_queue: %u buf_done: %u\n",
vb->cnt_buf_queue, vb->cnt_buf_done);
-   pr_info("vb2: alloc: %u put: %u prepare: %u finish: 
%u mmap: %u\n",
+   pr_info(" alloc: %u put: %u prepare: %u finish: %u 
mmap: %u\n",
vb->cnt_mem_alloc, vb->cnt_mem_put,
vb->cnt_mem_prepare, vb->cnt_mem_finish,
vb->cnt_mem_mmap);
-   pr_info("vb2: get_userptr: %u put_userptr: %u\n",
+   pr_info(" get_userptr: %u put_userptr: %u\n",
vb->cnt_mem_get_userptr, 
vb->cnt_mem_put_userptr);
-   pr_info("vb2: attach_dmabuf: %u detach_dmabuf: %u 
map_dmabuf: %u unmap_dmabuf: %u\n",
+   pr_info(" attach_dmabuf: %u detach_dmabuf: %u 
map_dmabuf: %u unmap_dmabuf: %u\n",
vb->cnt_mem_attach_dmabuf, 
vb->cnt_mem_detach_dmabuf,
vb->cnt_mem_map_dmabuf, 
vb->cnt_mem_unmap_dmabuf);
-   pr_info("vb2: get_dmabuf: %u num_users: %u vaddr: 
%u cookie: %u\n",
+   pr_info(" get_dmabuf: %u num_users: %u vaddr: %u 
cookie: %u\n",
vb->cnt_mem_get_dmabuf,
vb->cnt_mem_num_users,
vb->cnt_mem_vaddr,
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 08/11] media: dvb uAPI docs: document mmap-related ioctls

[Mauro Carvalho Chehab]

5 new ioctls were added to the DVB demux API, in order to
handle memory maped I/O. Add documentation for them.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 Documentation/media/uapi/dvb/dmx-expbuf.rst   | 90 +++
 Documentation/media/uapi/dvb/dmx-qbuf.rst | 85 +
 Documentation/media/uapi/dvb/dmx-querybuf.rst | 65 +++
 Documentation/media/uapi/dvb/dmx-reqbufs.rst  | 76 ++
 Documentation/media/uapi/dvb/dmx_fcalls.rst   |  4 ++
 5 files changed, 320 insertions(+)
 create mode 100644 Documentation/media/uapi/dvb/dmx-expbuf.rst
 create mode 100644 Documentation/media/uapi/dvb/dmx-qbuf.rst
 create mode 100644 Documentation/media/uapi/dvb/dmx-querybuf.rst
 create mode 100644 Documentation/media/uapi/dvb/dmx-reqbufs.rst

diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst 
b/Documentation/media/uapi/dvb/dmx-expbuf.rst
new file mode 100644
index ..51df34c6fb59
--- /dev/null
+++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst
@@ -0,0 +1,90 @@
+.. _DMX_EXPBUF:
+
+
+ioctl DMX_EXPBUF
+
+
+Name
+
+
+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
+
+
+Arguments
+=
+
+``fd``
+File descriptor returned by :ref:`open() `.
+
+``argp``
+Pointer to struct :c:type:`dmx_exportbuffer`.
+
+
+Description
+===
+
+This ioctl is an extension to the memory mapping I/O method.
+It can be used to export a buffer as a DMABUF file at any time after
+buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl.
+
+The ``reserved`` array must be zeroed before calling it.
+
+To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`.
+Applications must set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS`
+(struct :c:type:`dmx_requestbuffers` ``count``) minus one.
+Additional flags may be posted in the ``flags`` field. Refer to a manual
+for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
+and O_RDWR are supported.
+All other fields must be set to zero. In the
+case of multi-planar API, every plane is exported separately using
+multiple :ref:`DMX_EXPBUF` calls.
+
+After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a
+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)
+{
+   struct dmx_exportbuffer expbuf;
+
+   memset(, 0, sizeof(expbuf));
+   expbuf.type = bt;
+   expbuf.index = index;
+   if (ioctl(v4lfd, DMX_EXPBUF, ) == -1) {
+   perror("DMX_EXPBUF");
+   return -1;
+   }
+
+   *dmafd = expbuf.fd;
+
+   return 0;
+}
+
+Return Value
+
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes ` chapter.
+
+EINVAL
+A queue is not in MMAP mode or DMABUF exporting is not supported or
+``flags`` or ``index`` fields are invalid.
diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst 
b/Documentation/media/uapi/dvb/dmx-qbuf.rst
new file mode 100644
index ..b20b8153d48d
--- /dev/null
+++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst
@@ -0,0 +1,85 @@
+.. _DMX_QBUF:
+
+*
+ioctl DMX_QBUF, DMX_DQBUF
+*
+
+Name
+
+
+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:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp )
+:name: DMX_DQBUF
+
+
+Arguments
+=
+
+``fd``
+File descriptor returned by :ref:`open() `.
+
+``argp``
+Pointer to struct :c:type:`dmx_buffer`.
+
+
+Description
+===
+
+Applications call the ``DMX_QBUF`` ioctl to enqueue an empty
+(capturing) or filled (output) buffer in the driver's incoming queue.
+The semantics depend on the selected I/O method.
+
+To enqueue a buffer applications set the ``index`` field. Valid index
+numbers range from zero to the number of buffers allocated with
+:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus
+one. The contents of the struct :c:type:`dmx_buffer` returned
+by a :ref:`DMX_QUERYBUF` ioctl will do as well.
+
+The and ``reserved`` field must be set to 0.
+
+When ``DMX_QBUF`` is called with a pointer to this structure, it locks t

[PATCH 11/11] media: dvb_vb2: add SPDX headers

[Mauro Carvalho Chehab]

This code is released under GPL. Add the corresponding SPDX
headers.

Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/dvb-core/dvb_vb2.c | 1 +
 drivers/media/dvb-core/dvb_vb2.h | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/drivers/media/dvb-core/dvb_vb2.c b/drivers/media/dvb-core/dvb_vb2.c
index 7b1663f64e84..10d8f627af3a 100644
--- a/drivers/media/dvb-core/dvb_vb2.c
+++ b/drivers/media/dvb-core/dvb_vb2.c
@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: GPL
 /*
  * dvb-vb2.c - dvb-vb2
  *
diff --git a/drivers/media/dvb-core/dvb_vb2.h b/drivers/media/dvb-core/dvb_vb2.h
index d68653926d91..a5164effee16 100644
--- a/drivers/media/dvb-core/dvb_vb2.h
+++ b/drivers/media/dvb-core/dvb_vb2.h
@@ -1,4 +1,6 @@
 /*
+ * SPDX-License-Identifier: GPL
+ *
  * dvb-vb2.h - DVB driver helper framework for streaming I/O
  *
  * Copyright (C) 2015 Samsung Electronics
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 01/11] media: vb2-core: Fix a bug about unnecessary calls to queue cancel and free

[Mauro Carvalho Chehab]

From: Satendra Singh Thakur <satendr...@samsung.com>

When the func vb2_core_reqbufs is called first time after
vb2_core_queue_init(), the condition q->memory != memory always gets
satisfied, since q->memory was set to 0 at vb2_core_queue_init().

After the condition is true, unnecessary calls to __vb2_queue_cancel()
and  __vb2_queue_free() are done. in such case, *count is non-zero,
q->num_buffers is zero and q->memory is 0, which is not equal to
memory field *count=N, q->num_buffers=0, q->memory != memory.

[mche...@s-opensource.com: fix checkpatch issues]
Signed-off-by: Satendra Singh Thakur <satendr...@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
---
 drivers/media/v4l2-core/videobuf2-core.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/drivers/media/v4l2-core/videobuf2-core.c 
b/drivers/media/v4l2-core/videobuf2-core.c
index cb115ba6a1d2..21017b478a34 100644
--- a/drivers/media/v4l2-core/videobuf2-core.c
+++ b/drivers/media/v4l2-core/videobuf2-core.c
@@ -662,7 +662,8 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory 
memory,
return -EBUSY;
}
 
-   if (*count == 0 || q->num_buffers != 0 || q->memory != memory) {
+   if (*count == 0 || q->num_buffers != 0 ||
+   (q->memory && q->memory != memory)) {
/*
 * We already have buffers allocated, so first check if they
 * are not in use and can be freed.
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/8] media: v4l2-ioctl.h: convert debug into an enum of bits

[Mauro Carvalho Chehab]

Em Wed, 20 Dec 2017 12:47:23 +0200
Laurent Pinchart <laurent.pinch...@ideasonboard.com> escreveu:

> Hi Mauro,
> 
> On Tuesday, 19 December 2017 17:34:46 EET Mauro Carvalho Chehab wrote:
> > Em Tue, 19 Dec 2017 16:05:46 +0200 Laurent Pinchart escreveu:  
> > > On Tuesday, 19 December 2017 16:02:02 EET Laurent Pinchart wrote:  
> > >> On Tuesday, 19 December 2017 13:39:27 EET Sakari Ailus wrote:  
> > >>> On Mon, Dec 18, 2017 at 05:53:56PM -0200, Mauro Carvalho Chehab wrote:  
> > >>>> The V4L2_DEV_DEBUG_IOCTL macros actually define a bitmask,
> > >>>> but without using Kernel's modern standards. Also,
> > >>>> documentation looks akward.
> > >>>> 
> > >>>> So, convert them into an enum with valid bits, adding
> > >>>> the correspoinding kernel-doc documentation for it.  
> > >>> 
> > >>> The pattern of using bits for flags is a well established one and I
> > >>> wouldn't deviate from that by requiring the use of the BIT() macro.
> > >>> There are no benefits that I can see from here but the approach brings
> > >>> additional risks: misuse of the flags and mimicing the same risky
> > >>> pattern.
> > >>> 
> > >>> I'd also like to echo Laurent's concern that code is being changed in
> > >>> odd ways and not for itself, but due to deficiencies in documentation
> > >>> tools.
> > >>> 
> > >>> I believe the tooling has to be improved to address this properly.
> > >>> That only needs to done once, compared to changing all flag
> > >>> definitions to enums.  
> > >> 
> > >> That's my main concern too. We really must not sacrifice code
> > >> readability or writing ease in order to work around limitations of the
> > >> documentation system. For this reason I'm strongly opposed to patches 2
> > >> and 5 in this series.  
> > > 
> > > And I forgot to mention patch 8/8. Let's drop those three and improve the
> > > documentation system instead.  
> > 
> > Are you volunteering yourself to write the kernel-doc patches? :-)  
> 
> I thought you were the expert in this field, given the number of 
> documentation 
> patches that you have merged in the kernel ? :-)

c/c linux-doc, as this kind of discussion should be happening there.

Let me recap your proposal here, for the others from linux-doc to
understand this reply:

Em Mon, 18 Dec 2017 17:32:11 +0200
Laurent Pinchart <laurent.pinch...@ideasonboard.com> escreveu:

> Hi Mauro,
> 
> On Monday, 18 December 2017 17:13:26 EET Mauro Carvalho Chehab wrote:
> > Em Fri, 13 Oct 2017 15:38:11 +0300 Laurent Pinchart escreveu:  
> > > On Thursday, 28 September 2017 00:46:51 EEST Mauro Carvalho Chehab wrote: 
> > >  
> > >> Currently, there's no way to document #define foo 
> > >> with kernel-doc. So, convert it to an enum, and document.  
> > > 
> > > The documentation seems fine to me (except for one comment below).
> > > However, converting macros to an enum just to work around a defect of the
> > > documentation system doesn't seem like a good idea to me. I'd rather find
> > > a way to document macros.  
> > 
> > I agree that this limitation should be fixed.
> > 
> > Yet, in this specific case where we have an "array" of defines, all
> > associated to the same field (even being a bitmask), and assuming that
> > we would add a way for kernel-doc to parse this kind of defines
> > (not sure how easy/doable would be), then, in order to respect the
> > way kernel-doc markup is, the documentation for those macros would be:
> > 
> > 
> > /**
> >  * define: Just log the ioctl name + error code
> >  */
> > #define V4L2_DEV_DEBUG_IOCTL0x01
> > /**
> >  * define: Log the ioctl name arguments + error code
> >  */
> > #define V4L2_DEV_DEBUG_IOCTL_ARG0x02
> > /**
> >  * define: Log the file operations open, release, mmap and get_unmapped_area
> > */
> > #define V4L2_DEV_DEBUG_FOP  0x04
> > /**
> >  * define: Log the read and write file operations and the VIDIOC_(D)QBUF
> > ioctls */
> > #define V4L2_DEV_DEBUG_STREAMING0x08
> > 
> > IMHO, this is a way easier to read/understand by humans, and a way more
> > coincise:
> > 
> > /**
> >  * enum v4l2_debug_flags - Device debug flags to be used with the video
> >  *  device debug attribute
> >  *
> >  * @V4L2_DEV_D

Re: [PATCH 2/8] media: v4l2-ioctl.h: convert debug into an enum of bits

[Mauro Carvalho Chehab]

Em Tue, 19 Dec 2017 19:17:12 +0200
Laurent Pinchart <laurent.pinch...@ideasonboard.com> escreveu:

> Hi Mauro,
> 
> On Tuesday, 19 December 2017 17:37:58 EET Mauro Carvalho Chehab wrote:
> > Em Tue, 19 Dec 2017 16:12:35 +0200 Sakari Ailus escreveu:  
> > > On Tue, Dec 19, 2017 at 04:02:02PM +0200, Laurent Pinchart wrote:  
> > >> And furthermore using enum types in the uAPI is a bad idea as the enum
> > >> size is architecture-dependent. That's why we use integer types in
> > >> structures used as ioctl arguments.  
> > > 
> > > I guess we have an argeement on that, enums are a no-go for uAPI, for
> > > reasons not related to the topic at hand.  
> > 
> > Huh? We're not talking about uAPI. This is kAPI. Using enums there is OK.  
> 
> Sure, there's no disagreement about that. 

> The point was that, as both uAPI and  kAPI should be documented,

No disagreement here...

> and we can't use enums for uAPI, 

Err... we actually do use enums on uAPI... videodev2.h is full of it.
What we can't do is to use enums on ioctls. So, all such enums are
replaced by u32 at the ioctl calls.

Ok, this is not elegant (and it happened for historic reasons - we're
now avoiding it at all costs), but that's the way it is.

The fact is - for uAPI - we have enums and defines, and both are
documented.

> we need a way to document non-enum types,

We have already a way to document all uAPI data structures, including
enums and defines.

> which we could then use to document the kAPI the same way.

Let's not mix subjects. This patch series is all about kAPI.

Specifically, we're talking about this change:

-/* Just log the ioctl name + error code */
-#define V4L2_DEV_DEBUG_IOCTL   0x01
-/* Log the ioctl name arguments + error code */
-#define V4L2_DEV_DEBUG_IOCTL_ARG   0x02
-/* Log the file operations open, release, mmap and get_unmapped_area */
-#define V4L2_DEV_DEBUG_FOP 0x04
-/* Log the read and write file operations and the VIDIOC_(D)QBUF ioctls */
-#define V4L2_DEV_DEBUG_STREAMING   0x08
+/**
+ * enum v4l2_debug_bits - Device debug bits to be used with the video
+ * device debug attribute
+ *
+ * @V4L2_DEBUG_IOCTL:  Just log the ioctl name + error code.
+ * @V4L2_DEBUG_IOCTL_ARG:  Log the ioctl name arguments + error code.
+ * @V4L2_DEBUG_FOP:Log the file operations and open, release,
+ * mmap and get_unmapped_area syscalls.
+ * @V4L2_DEBUG_STREAMING:  Log the read and write syscalls and
+ * :c:ref:`VIDIOC_[Q|DQ]BUF ` ioctls.
+ * @V4L2_DEBUG_POLL:   Log poll syscalls.
+ */
+enum v4l2_debug_bits {
+   V4L2_DEBUG_IOCTL= 0,
+   V4L2_DEBUG_IOCTL_ARG= 1,
+   V4L2_DEBUG_FOP  = 2,
+   V4L2_DEBUG_STREAMING= 3,
+   V4L2_DEBUG_POLL = 4,
+};

I agree with the principle of having a way to document #defines and
static data that belongs to kAPI and drivers. So, from my side, if
someone pops up and propose a way to document #defines to linux-doc,
manages to get such proposal accepted and submit patches implementing it, 
I'm fine.

There are things like:

include/media/cec.h:#define CEC_NUM_CORE_EVENTS 2
include/media/cec.h:#define CEC_MAX_MSG_RX_QUEUE_SZ (18 * 3)
include/media/cec.h:#define CEC_MAX_MSG_TX_QUEUE_SZ (18 * 1)
include/media/rc-core.h:#define IR_DEFAULT_TIMEOUT  MS_TO_NS(125)
include/media/rc-core.h:#define IR_MAX_DURATION 5   /* 500 
ms */
include/media/v4l2-clk.h:#define V4L2_CLK_NAME_SIZE 64
...

that currently can't be documented, and do belong to "#define" namespace,
as those are true macros that create an alias for a magic number.

Those should *never* be converted to enums. The fact that they can't right
now be documented shouldn't be used as an excuse to conver to enums: they're
just magic numbers that can be used on a countless number of random places
that may or may not be related.

However, I do believe that, grouping namespace for values with the
same meaning do belong to enums. After all, those values are bound
together for life, as they're meant to be used at the same places.
A define is a very poor and lazy way to define, and sometimes induce
to mistakes, as, from time to time, I see values on defines that belongs
to an specific field being used on some other one.

>From documentation PoV, they also play nicer when grouped together,
as a common comment that applies to all such values are grouped
together.

In the specific case of this patch, all those V4L2_DEV_DEBUG_* bits
(or V4L2_DEV_DEBUG_* values - before this patchset) are meant to be
used only when enabling or disabling V4L2 core debug messages.

Grouping them into the same "enum" namespace makes all sense.
They should have grouped together since the beginning. That