[PATCH v2 00/24] Documentation build fixes against next-20201013

[PATCH v2 00/24] Documentation build fixes against next-20201013

[Mauro Carvalho Chehab]

This series is based on the top of my previous series:

	https://lore.kernel.org/lkml/cover.1602589096.git.mchehab+huawei@kernel.org/

plus linux-next.

It contains the patches I sent before with documentation fixes
for Kernel 5.10, plus 3 new fixes for stuff that got merged today
at linux-next.

My plan is to do a late pull request by the end of the merge window
with the patches from this tree that weren't merged directly
via some other trees.

-

After both series applied, the only warnings with Sphinx 2.4.4
are those:

../include/kunit/test.h:282: warning: Function parameter or member '__suites' not described in 'kunit_test_suites_for_module'
../include/kunit/test.h:282: warning: Excess function parameter 'suites_list' description in 'kunit_test_suites_for_module'
../include/kunit/test.h:314: warning: Excess function parameter 'suites' description in 'kunit_test_suites'

.../Documentation/core-api/counters.rst:46: WARNING: undefined label: test counters module (if the link has no caption the label must precede a section header)
.../Documentation/core-api/counters.rst:49: WARNING: undefined label: selftest for counters (if the link has no caption the label must precede a section header)
.../Documentation/core-api/counters.rst:62: WARNING: undefined label: atomic_ops (if the link has no caption the label must precede a section header)

Those require some care from the authors in order to
properly address them.

Hopefully, this will all be sorted until the end of the merge window.


Mauro Carvalho Chehab (24):
  docs: hwmon: adm1266.rst: fix a broken reference
  tools: docs: memory-model: fix references for some files
  docs: SafeSetID: fix a warning
  docs: lockdep-design: fix some warning issues
  docs: admin-guide: net.rst: add a missing blank line
  blk-mq: docs: add kernel-doc description for a new struct member
  drm: amdgpu: kernel-doc: update some adev parameters
  drm: kernel-doc: document drm_dp_set_subconnector_property() params
  docs: kasan.rst: add two missing blank lines
  mm: pagemap.h: fix two kernel-doc markups
  drm/dp: fix kernel-doc warnings at drm_dp_helper.c
  drm/dp: fix a kernel-doc issue at drm_edid.c
  docs: i2c: index.rst: add slave-testunit-backend.rst
  docs: conf.py: disable automarkup for Sphinx 3.x
  docs: net: statistics.rst: remove a duplicated kernel-doc
  seqlock: fix two kernel-doc warnings
  docs: hwmon: mp2975.rst: address some html build warnings
  docs: userspace-api: add iommu.rst to the index file
  net: phy: remove kernel-doc duplication
  MAINTAINERS: fix broken doc refs due to yaml conversion
  crypto: sun8x-ce*: update entries to its documentation
  ice: docs fix a devlink info that broke a table
  RDMA: add a missing kernel-doc parameter markup
  counters: docs: add a missing include

 Documentation/admin-guide/LSM/SafeSetID.rst   |  2 +-
 .../admin-guide/hw-vuln/l1d_flush.rst         |  3 +-
 Documentation/admin-guide/sysctl/net.rst      |  1 +
 Documentation/conf.py                         |  3 +-
 Documentation/core-api/counters.rst           |  1 +
 Documentation/core-api/index.rst              |  1 +
 Documentation/dev-tools/kasan.rst             |  2 +
 .../bindings/clock/hi6220-clock.txt           |  2 +-
 Documentation/hwmon/adm1266.rst               |  2 +-
 Documentation/hwmon/index.rst                 |  1 +
 Documentation/hwmon/mp2975.rst                | 14 +++-
 Documentation/i2c/index.rst                   |  1 +
 Documentation/locking/lockdep-design.rst      | 69 +++++++++++--------
 Documentation/networking/devlink/ice.rst      |  1 +
 Documentation/networking/statistics.rst       |  3 +-
 Documentation/userspace-api/index.rst         |  1 +
 MAINTAINERS                                   |  9 ++-
 .../crypto/allwinner/sun8i-ce/sun8i-ce-hash.c |  2 +-
 .../crypto/allwinner/sun8i-ce/sun8i-ce-prng.c |  2 +-
 .../crypto/allwinner/sun8i-ce/sun8i-ce-trng.c |  2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c    |  2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c   |  6 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c  |  5 +-
 drivers/gpu/drm/drm_dp_helper.c               | 12 +++-
 drivers/gpu/drm/drm_edid.c                    |  2 +-
 drivers/infiniband/core/device.c              |  5 +-
 .../bindings/net/wireless/silabs,wfx.yaml     |  2 +-
 include/linux/blk-mq.h                        |  2 +
 include/linux/pagemap.h                       |  8 +--
 include/linux/phy.h                           | 40 ++---------
 include/linux/seqlock.h                       |  2 +-
 tools/memory-model/Documentation/README       |  2 +-
 tools/memory-model/Documentation/ordering.txt |  2 +-
 33 files changed, 113 insertions(+), 99 deletions(-)

-- 
2.26.2

[PATCH v2 01/24] docs: hwmon: adm1266.rst: fix a broken reference

[Mauro Carvalho Chehab]

The reference was missing the extension, causing the
check script to complain.

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

diff --git a/Documentation/hwmon/adm1266.rst b/Documentation/hwmon/adm1266.rst
index 9257f8a48650..2b877011cfdf 100644
--- a/Documentation/hwmon/adm1266.rst
+++ b/Documentation/hwmon/adm1266.rst
@@ -20,7 +20,7 @@ ADM1266 is a sequencer that features voltage readback from 17 channels via an
 integrated 12 bit SAR ADC, accessed using a PMBus interface.
 
 The driver is a client driver to the core PMBus driver. Please see
-Documentation/hwmon/pmbus for details on PMBus client drivers.
+Documentation/hwmon/pmbus.rst for details on PMBus client drivers.
 
 
 Sysfs entries
-- 
2.26.2

Re: [PATCH v2 01/24] docs: hwmon: adm1266.rst: fix a broken reference

[Guenter Roeck]

On Tue, Oct 13, 2020 at 02:14:28PM +0200, Mauro Carvalho Chehab wrote:
> The reference was missing the extension, causing the
> check script to complain.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Guenter Roeck <linux@roeck-us.net>

> ---
>  Documentation/hwmon/adm1266.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/hwmon/adm1266.rst b/Documentation/hwmon/adm1266.rst
> index 9257f8a48650..2b877011cfdf 100644
> --- a/Documentation/hwmon/adm1266.rst
> +++ b/Documentation/hwmon/adm1266.rst
> @@ -20,7 +20,7 @@ ADM1266 is a sequencer that features voltage readback from 17 channels via an
>  integrated 12 bit SAR ADC, accessed using a PMBus interface.
>  
>  The driver is a client driver to the core PMBus driver. Please see
> -Documentation/hwmon/pmbus for details on PMBus client drivers.
> +Documentation/hwmon/pmbus.rst for details on PMBus client drivers.
>  
>  
>  Sysfs entries
> -- 
> 2.26.2
> 

[PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Mauro Carvalho Chehab]

- The sysfs.txt file was converted to ReST and renamed;
- The control-dependencies.txt is not at
  Documentation/control-dependencies.txt. As it is at the
  same dir as the README file, which mentions it, just
  remove Documentation/.

With that, ./scripts/documentation-file-ref-check script
is now happy again for files under tools/.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/memory-model/Documentation/README       | 2 +-
 tools/memory-model/Documentation/ordering.txt | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
index 16177aaa9752..004969992bac 100644
--- a/tools/memory-model/Documentation/README
+++ b/tools/memory-model/Documentation/README
@@ -55,7 +55,7 @@ README
 Documentation/cheatsheet.txt
 	Quick-reference guide to the Linux-kernel memory model.
 
-Documentation/control-dependencies.txt
+control-dependencies.txt
 	A guide to preventing compiler optimizations from destroying
 	your control dependencies.
 
diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
index 3d020bed8585..629b19ae64a6 100644
--- a/tools/memory-model/Documentation/ordering.txt
+++ b/tools/memory-model/Documentation/ordering.txt
@@ -346,7 +346,7 @@ o	Accessing RCU-protected pointers via rcu_dereference()
 
 	If there is any significant processing of the pointer value
 	between the rcu_dereference() that returned it and a later
-	dereference(), please read Documentation/RCU/rcu_dereference.txt.
+	dereference(), please read Documentation/RCU/rcu_dereference.rst.
 
 It can also be quite helpful to review uses in the Linux kernel.
 
-- 
2.26.2

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Paul E. McKenney]

On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> - The sysfs.txt file was converted to ReST and renamed;
> - The control-dependencies.txt is not at
>   Documentation/control-dependencies.txt. As it is at the
>   same dir as the README file, which mentions it, just
>   remove Documentation/.
> 
> With that, ./scripts/documentation-file-ref-check script
> is now happy again for files under tools/.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Queued for review and testing, likely target v5.11.

							Thanx, Paul

> ---
>  tools/memory-model/Documentation/README       | 2 +-
>  tools/memory-model/Documentation/ordering.txt | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
> index 16177aaa9752..004969992bac 100644
> --- a/tools/memory-model/Documentation/README
> +++ b/tools/memory-model/Documentation/README
> @@ -55,7 +55,7 @@ README
>  Documentation/cheatsheet.txt
>  	Quick-reference guide to the Linux-kernel memory model.
>  
> -Documentation/control-dependencies.txt
> +control-dependencies.txt
>  	A guide to preventing compiler optimizations from destroying
>  	your control dependencies.
>  
> diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
> index 3d020bed8585..629b19ae64a6 100644
> --- a/tools/memory-model/Documentation/ordering.txt
> +++ b/tools/memory-model/Documentation/ordering.txt
> @@ -346,7 +346,7 @@ o	Accessing RCU-protected pointers via rcu_dereference()
>  
>  	If there is any significant processing of the pointer value
>  	between the rcu_dereference() that returned it and a later
> -	dereference(), please read Documentation/RCU/rcu_dereference.txt.
> +	dereference(), please read Documentation/RCU/rcu_dereference.rst.
>  
>  It can also be quite helpful to review uses in the Linux kernel.
>  
> -- 
> 2.26.2
> 

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Alan Stern]

On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > - The sysfs.txt file was converted to ReST and renamed;
> > - The control-dependencies.txt is not at
> >   Documentation/control-dependencies.txt. As it is at the
> >   same dir as the README file, which mentions it, just
> >   remove Documentation/.
> > 
> > With that, ./scripts/documentation-file-ref-check script
> > is now happy again for files under tools/.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> Queued for review and testing, likely target v5.11.

Instead of changing the path in the README reference, shouldn't 
tools/memory-model/control-dependencies.txt be moved to its proper 
position in .../Documentation?

Alan Stern

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Paul E. McKenney]

On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > > - The sysfs.txt file was converted to ReST and renamed;
> > > - The control-dependencies.txt is not at
> > >   Documentation/control-dependencies.txt. As it is at the
> > >   same dir as the README file, which mentions it, just
> > >   remove Documentation/.
> > > 
> > > With that, ./scripts/documentation-file-ref-check script
> > > is now happy again for files under tools/.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > 
> > Queued for review and testing, likely target v5.11.
> 
> Instead of changing the path in the README reference, shouldn't 
> tools/memory-model/control-dependencies.txt be moved to its proper 
> position in .../Documentation?

You are of course quite right.  My thought is to let Mauro go ahead,
given his short deadline.  We can then make this "git mv" change once
v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
added a reminder to my calendar.

							Thanx, Paul

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Mauro Carvalho Chehab]

Em Tue, 13 Oct 2020 18:58:40 -0700
"Paul E. McKenney" <paulmck@kernel.org> escreveu:

> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:  
> > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:  
> > > > - The sysfs.txt file was converted to ReST and renamed;
> > > > - The control-dependencies.txt is not at
> > > >   Documentation/control-dependencies.txt. As it is at the
> > > >   same dir as the README file, which mentions it, just
> > > >   remove Documentation/.
> > > > 
> > > > With that, ./scripts/documentation-file-ref-check script
> > > > is now happy again for files under tools/.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> > > 
> > > Queued for review and testing, likely target v5.11.  
> > 
> > Instead of changing the path in the README reference, shouldn't 
> > tools/memory-model/control-dependencies.txt be moved to its proper 
> > position in .../Documentation?  
> 
> You are of course quite right.  My thought is to let Mauro go ahead,
> given his short deadline.  We can then make this "git mv" change once
> v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
> added a reminder to my calendar.

Sounds like a plan to me.


If it helps on 5.11 plans, converting this file to ReST format is quite
trivial: it just needs to use "::" for C/asm code literal blocks, and 
to replace "(*) " by something that matches ReST syntax for lists,
like "(#) " or just "* ":

	https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists

See enclosed.

Thanks,
Mauro

[PATCH] convert control-dependencies.rst to ReST

- Mark literal blocks as such;
- Use a numbered list at the summary.

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

diff --git a/tools/memory-model/Documentation/control-dependencies.rst b/tools/memory-model/Documentation/control-dependencies.rst
index 366520cac937..52dc6a5bc173 100644
--- a/tools/memory-model/Documentation/control-dependencies.rst
+++ b/tools/memory-model/Documentation/control-dependencies.rst
@@ -7,7 +7,7 @@ the compiler's ignorance from breaking your code.
 
 A load-load control dependency requires a full read memory barrier, not
 simply a data dependency barrier to make it work correctly.  Consider the
-following bit of code:
+following bit of code::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -19,7 +19,7 @@ This will not have the desired effect because there is no actual data
 dependency, but rather a control dependency that the CPU may short-circuit
 by attempting to predict the outcome in advance, so that other CPUs see
 the load from b as having happened before the load from a.  In such a
-case what's actually required is:
+case what's actually required is::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -28,7 +28,7 @@ case what's actually required is:
 	}
 
 However, stores are not speculated.  This means that ordering -is- provided
-for load-store control dependencies, as in the following example:
+for load-store control dependencies, as in the following example::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -45,7 +45,7 @@ or, worse yet, convert the store into a check followed by a store.
 Worse yet, if the compiler is able to prove (say) that the value of
 variable "a" is always non-zero, it would be well within its rights
 to optimize the original example by eliminating the "if" statement
-as follows:
+as follows::
 
 	q = a;
 	b = 1;  /* BUG: Compiler and CPU can both reorder!!! */
@@ -53,7 +53,7 @@ as follows:
 So don't leave out either the READ_ONCE() or the WRITE_ONCE().
 
 It is tempting to try to enforce ordering on identical stores on both
-branches of the "if" statement as follows:
+branches of the "if" statement as follows::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -67,7 +67,7 @@ branches of the "if" statement as follows:
 	}
 
 Unfortunately, current compilers will transform this as follows at high
-optimization levels:
+optimization levels::
 
 	q = READ_ONCE(a);
 	barrier();
@@ -85,7 +85,7 @@ Now there is no conditional between the load from "a" and the store to
 The conditional is absolutely required, and must be present in the
 assembly code even after all compiler optimizations have been applied.
 Therefore, if you need ordering in this example, you need explicit
-memory barriers, for example, smp_store_release():
+memory barriers, for example, smp_store_release()::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -97,7 +97,7 @@ memory barriers, for example, smp_store_release():
 	}
 
 In contrast, without explicit memory barriers, two-legged-if control
-ordering is guaranteed only when the stores differ, for example:
+ordering is guaranteed only when the stores differ, for example::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -113,7 +113,7 @@ proving the value of "a".
 
 In addition, you need to be careful what you do with the local variable "q",
 otherwise the compiler might be able to guess the value and again remove
-the needed conditional.  For example:
+the needed conditional.  For example::
 
 	q = READ_ONCE(a);
 	if (q % MAX) {
@@ -126,7 +126,7 @@ the needed conditional.  For example:
 
 If MAX is defined to be 1, then the compiler knows that (q % MAX) is
 equal to zero, in which case the compiler is within its rights to
-transform the above code into the following:
+transform the above code into the following::
 
 	q = READ_ONCE(a);
 	WRITE_ONCE(b, 2);
@@ -137,7 +137,7 @@ between the load from variable "a" and the store to variable "b".  It is
 tempting to add a barrier(), but this does not help.  The conditional
 is gone, and the barrier won't bring it back.  Therefore, if you are
 relying on this ordering, you should make sure that MAX is greater than
-one, perhaps as follows:
+one, perhaps as follows::
 
 	q = READ_ONCE(a);
 	BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */
@@ -154,7 +154,7 @@ identical, as noted earlier, the compiler could pull this store outside
 of the 'if' statement.
 
 You must also be careful not to rely too much on boolean short-circuit
-evaluation.  Consider this example:
+evaluation.  Consider this example::
 
 	q = READ_ONCE(a);
 	if (q || 1 > 0)
@@ -162,7 +162,7 @@ evaluation.  Consider this example:
 
 Because the first condition cannot fault and the second condition is
 always true, the compiler can transform this example as following,
-defeating control dependency:
+defeating control dependency::
 
 	q = READ_ONCE(a);
 	WRITE_ONCE(b, 1);
@@ -174,7 +174,7 @@ the compiler to use the results.
 
 In addition, control dependencies apply only to the then-clause and
 else-clause of the if-statement in question.  In particular, it does
-not necessarily apply to code following the if-statement:
+not necessarily apply to code following the if-statement::
 
 	q = READ_ONCE(a);
 	if (q) {
@@ -189,7 +189,7 @@ compiler cannot reorder volatile accesses and also cannot reorder
 the writes to "b" with the condition.  Unfortunately for this line
 of reasoning, the compiler might compile the two writes to "b" as
 conditional-move instructions, as in this fanciful pseudo-assembly
-language:
+language::
 
 	ld r1,a
 	cmp r1,$0
@@ -213,14 +213,14 @@ for more information.
 
 In summary:
 
-  (*) Control dependencies can order prior loads against later stores.
+  (#) Control dependencies can order prior loads against later stores.
       However, they do -not- guarantee any other sort of ordering:
       Not prior loads against later loads, nor prior stores against
       later anything.  If you need these other forms of ordering,
       use smp_rmb(), smp_wmb(), or, in the case of prior stores and
       later loads, smp_mb().
 
-  (*) If both legs of the "if" statement begin with identical stores to
+  (#) If both legs of the "if" statement begin with identical stores to
       the same variable, then those stores must be ordered, either by
       preceding both of them with smp_mb() or by using smp_store_release()
       to carry out the stores.  Please note that it is -not- sufficient
@@ -229,28 +229,28 @@ In summary:
       destroy the control dependency while respecting the letter of the
       barrier() law.
 
-  (*) Control dependencies require at least one run-time conditional
+  (#) Control dependencies require at least one run-time conditional
       between the prior load and the subsequent store, and this
       conditional must involve the prior load.  If the compiler is able
       to optimize the conditional away, it will have also optimized
       away the ordering.  Careful use of READ_ONCE() and WRITE_ONCE()
       can help to preserve the needed conditional.
 
-  (*) Control dependencies require that the compiler avoid reordering the
+  (#) Control dependencies require that the compiler avoid reordering the
       dependency into nonexistence.  Careful use of READ_ONCE() or
       atomic{,64}_read() can help to preserve your control dependency.
       Please see the COMPILER BARRIER section for more information.
 
-  (*) Control dependencies apply only to the then-clause and else-clause
+  (#) Control dependencies apply only to the then-clause and else-clause
       of the if-statement containing the control dependency, including
       any functions that these two clauses call.  Control dependencies
       do -not- apply to code following the if-statement containing the
       control dependency.
 
-  (*) Control dependencies pair normally with other types of barriers.
+  (#) Control dependencies pair normally with other types of barriers.
 
-  (*) Control dependencies do -not- provide multicopy atomicity.  If you
+  (#) Control dependencies do -not- provide multicopy atomicity.  If you
       need all the CPUs to see a given store at the same time, use smp_mb().
 
-  (*) Compilers do not understand control dependencies.  It is therefore
+  (#) Compilers do not understand control dependencies.  It is therefore
       your job to ensure that they do not break your code.

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Akira Yokosawa]

On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Oct 2020 18:58:40 -0700
> "Paul E. McKenney" <paulmck@kernel.org> escreveu:
> 
>> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
>>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:  
>>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:  
>>>>> - The sysfs.txt file was converted to ReST and renamed;
>>>>> - The control-dependencies.txt is not at
>>>>>   Documentation/control-dependencies.txt. As it is at the
>>>>>   same dir as the README file, which mentions it, just
>>>>>   remove Documentation/.
>>>>>
>>>>> With that, ./scripts/documentation-file-ref-check script
>>>>> is now happy again for files under tools/.
>>>>>
>>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
>>>>
>>>> Queued for review and testing, likely target v5.11.  
>>>
>>> Instead of changing the path in the README reference, shouldn't 
>>> tools/memory-model/control-dependencies.txt be moved to its proper 
>>> position in .../Documentation?  
>>
>> You are of course quite right.  My thought is to let Mauro go ahead,
>> given his short deadline.  We can then make this "git mv" change once
>> v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
>> added a reminder to my calendar.
> 
> Sounds like a plan to me.
> 
> 
> If it helps on 5.11 plans, converting this file to ReST format is quite
> trivial: it just needs to use "::" for C/asm code literal blocks, and 
> to replace "(*) " by something that matches ReST syntax for lists,
> like "(#) " or just "* ":
> 
> 	https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
> 
> See enclosed.

I'm afraid conversion of LKMM documents to ReST is unlikely to happen
any time soon.
It should wait until such time comes when the auto markup tools become
clever enough and .rst files looks exactly the same as plain .txt files.

Am I asking too much? :-)

        Thanks, Akira

> 
> Thanks,
> Mauro
> 
> [PATCH] convert control-dependencies.rst to ReST
> 

[snip]

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Mauro Carvalho Chehab]

Em Wed, 14 Oct 2020 23:14:00 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:
> > Em Tue, 13 Oct 2020 18:58:40 -0700
> > "Paul E. McKenney" <paulmck@kernel.org> escreveu:
> >   
> >> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:  
> >>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:    
> >>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:    
> >>>>> - The sysfs.txt file was converted to ReST and renamed;
> >>>>> - The control-dependencies.txt is not at
> >>>>>   Documentation/control-dependencies.txt. As it is at the
> >>>>>   same dir as the README file, which mentions it, just
> >>>>>   remove Documentation/.
> >>>>>
> >>>>> With that, ./scripts/documentation-file-ref-check script
> >>>>> is now happy again for files under tools/.
> >>>>>
> >>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>    
> >>>>
> >>>> Queued for review and testing, likely target v5.11.    
> >>>
> >>> Instead of changing the path in the README reference, shouldn't 
> >>> tools/memory-model/control-dependencies.txt be moved to its proper 
> >>> position in .../Documentation?    
> >>
> >> You are of course quite right.  My thought is to let Mauro go ahead,
> >> given his short deadline.  We can then make this "git mv" change once
> >> v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
> >> added a reminder to my calendar.  
> > 
> > Sounds like a plan to me.
> > 
> > 
> > If it helps on 5.11 plans, converting this file to ReST format is quite
> > trivial: it just needs to use "::" for C/asm code literal blocks, and 
> > to replace "(*) " by something that matches ReST syntax for lists,
> > like "(#) " or just "* ":
> > 
> > 	https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
> > 
> > See enclosed.  
> 
> I'm afraid conversion of LKMM documents to ReST is unlikely to happen
> any time soon.
> It should wait until such time comes when the auto markup tools become
> clever enough and .rst files looks exactly the same as plain .txt files.
> 
> Am I asking too much? :-)
> 
>         Thanks, Akira

Yes :-)

	$ git log --author akiyks@gmail.com Documentation/sphinx
	$

The auto markup tools don't write themselves alone. Someone needs 
to write them and test if no regressions will happen with the existing
documents.

-

That's said, I suspect that one of the hardest things for something
like that to be possible is to be able to distinguish something
like:

	(some text)

From something like:

	/* some C code snippet or bash script, or other literal block */

So, at least "::" (or some other markup replacing it) is needed.

If you have some bright idea about how to implement it, feel free
to contribute with patches.

Thanks,
Mauro

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Paul E. McKenney]

On Tue, Oct 13, 2020 at 06:58:40PM -0700, Paul E. McKenney wrote:
> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > > > - The sysfs.txt file was converted to ReST and renamed;
> > > > - The control-dependencies.txt is not at
> > > >   Documentation/control-dependencies.txt. As it is at the
> > > >   same dir as the README file, which mentions it, just
> > > >   remove Documentation/.
> > > > 
> > > > With that, ./scripts/documentation-file-ref-check script
> > > > is now happy again for files under tools/.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > 
> > > Queued for review and testing, likely target v5.11.
> > 
> > Instead of changing the path in the README reference, shouldn't 
> > tools/memory-model/control-dependencies.txt be moved to its proper 
> > position in .../Documentation?
> 
> You are of course quite right.  My thought is to let Mauro go ahead,
> given his short deadline.  We can then make this "git mv" change once
> v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
> added a reminder to my calendar.

Except that I cannot find a commit where control-dependencies.txt is
in tools/memory-model.  And this file is not yet in mainline, but
only in -rcu and -next.  In both places, it is here:

	tools/memory-model/Documentation/control-dependencies.txt

Mauro, to what commit in what tree are you applying this patch?

							Thanx, Paul

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Mauro Carvalho Chehab]

Hi Paul,

Em Wed, 14 Oct 2020 11:57:20 -0700
"Paul E. McKenney" <paulmck@kernel.org> escreveu:

> On Tue, Oct 13, 2020 at 06:58:40PM -0700, Paul E. McKenney wrote:
> > On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:  
> > > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:  
> > > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:  
> > > > > - The sysfs.txt file was converted to ReST and renamed;
> > > > > - The control-dependencies.txt is not at
> > > > >   Documentation/control-dependencies.txt. As it is at the
> > > > >   same dir as the README file, which mentions it, just
> > > > >   remove Documentation/.
> > > > > 
> > > > > With that, ./scripts/documentation-file-ref-check script
> > > > > is now happy again for files under tools/.
> > > > > 
> > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> > > > 
> > > > Queued for review and testing, likely target v5.11.  
> > > 
> > > Instead of changing the path in the README reference, shouldn't 
> > > tools/memory-model/control-dependencies.txt be moved to its proper 
> > > position in .../Documentation?  
> > 
> > You are of course quite right.  My thought is to let Mauro go ahead,
> > given his short deadline. 

I guess there might be some misunderstanding here. My fault. The plan
is to have zero doc warnings for 5.10[1].

In order to get there, The patches for it were split on two series,
both for 5.10:

- The /80 series with patches that already applies on the top of master;
- This /24 patch series, which depends on trees that weren't merged
  upstream yet (back on Oct, 13). Those applies on the top of
  next-20201013.

I'm intending to submit later today (after next-20201015) a PR with 
patches from the /80 series.

The remaining ones should be sent as a late pull request by the end 
of the merge window, if the patch that caused the issue gets merged
for 5.10. That's the case of this patch.


[1] With Sphinx < 3. Sphinx 3 and above brings some additional
    warnings that depends on a fix at the toolset. The fixup patches
    for Sphinx were proposed yesterday by the Sphinx maintainer
    of the C domain parser. More details can be seen here:

	https://github.com/sphinx-doc/sphinx/pull/8313


> >  We can then make this "git mv" change once
> > v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
> > added a reminder to my calendar.  
> 
> Except that I cannot find a commit where control-dependencies.txt is
> in tools/memory-model.  And this file is not yet in mainline, but
> only in -rcu and -next.  In both places, it is here:
> 
> 	tools/memory-model/Documentation/control-dependencies.txt
> 
> Mauro, to what commit in what tree are you applying this patch?

This is against next-20201013. The specific commit adding
README and control-dependencies.txt is this one:

commit d34a972f67252457158122e5ba7a0ce5ece62067
Author:     Paul E. McKenney <paulmck@kernel.org>
AuthorDate: Tue Aug 11 11:27:33 2020 -0700
Commit:     Paul E. McKenney <paulmck@kernel.org>
CommitDate: Sun Oct 4 17:21:31 2020 -0700

    tools/memory-model: Document categories of ordering primitives
    
    The Linux kernel has a number of categories of ordering primitives, which
    are recorded in the LKMM implementation and hinted at by cheatsheet.txt.
    But there is no overview of these categories, and such an overview
    is needed in order to understand multithreaded LKMM litmus tests.
    This commit therefore adds an ordering.txt as well as extracting a
    control-dependencies.txt from memory-barriers.txt.  It also updates the
    README file.
    
    [ paulmck: Apply Akira Yokosawa file-placement feedback. ]
    [ paulmck:  Apply Alan Stern feedback. ]
    Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

Btw, after re-checking the patch, I would drop this hunk:

diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
index 16177aaa9752..004969992bac 100644
--- a/tools/memory-model/Documentation/README
+++ b/tools/memory-model/Documentation/README
@@ -55,7 +55,7 @@ README
 Documentation/cheatsheet.txt
 	Quick-reference guide to the Linux-kernel memory model.
 
-Documentation/control-dependencies.txt
+control-dependencies.txt
 	A guide to preventing compiler optimizations from destroying
 	your control dependencies.

The ./scripts/documentation-file-ref-check doesn't complain about
broken references for Documentation/ files outside the main
docs dir. So, this hunk is not really needed to fix warnings with
5.10. Besides that, there are other references to those files:

	$ git grep Documentation tools/memory-model/Documentation/README
	tools/memory-model/Documentation/README:tools/memory-model/Documentation directory.  It has been said that at
	tools/memory-model/Documentation/README:Documentation/cheatsheet.txt
	tools/memory-model/Documentation/README:Documentation/control-dependencies.txt
	tools/memory-model/Documentation/README:Documentation/explanation.txt
	tools/memory-model/Documentation/README:Documentation/litmus-tests.txt
	tools/memory-model/Documentation/README:Documentation/ordering.txt
	tools/memory-model/Documentation/README:Documentation/recipes.txt
	tools/memory-model/Documentation/README:Documentation/references.txt
	tools/memory-model/Documentation/README:Documentation/simple.txt

That also refer to the files inside tools/memory-model/Documentation/.
So, they should ether all be replaced to just the file name without
the directory (IMHO, that makes more sense) or kept as-is.

In any case, for 5.10, all we need is to fix this reference:

	Documentation/RCU/rcu_dereference.txt -> Documentation/RCU/rcu_dereference.rst

Also, the patch description is wrong. I suspect that, when this patch
was originally written, there were more hunks being touched, but
fixes for everything else were already merged. So, the only thing that
is left is the above change.

It follows a new version. feel free to either pick (or merge) this one at 
the same tree as tools/memory-model/Documentation/ordering.txt if you
think that this works best for you.

Otherwise, I'll keep this on my -next tree together with this series,
aiming to submit by the end of the merge window, if ordering.txt gets
merged for 5.10.

Thanks,
Mauro

[PATCH v2.1 02/24] tools/memory-model: fix a broken doc reference

Documentation/RCU/rcu_dereference.txt -> Documentation/RCU/rcu_dereference.rst

Fixes: d34a972f6725 ("tools/memory-model: Document categories of ordering primitives")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
index 3d020bed8585..629b19ae64a6 100644
--- a/tools/memory-model/Documentation/ordering.txt
+++ b/tools/memory-model/Documentation/ordering.txt
@@ -346,7 +346,7 @@ o	Accessing RCU-protected pointers via rcu_dereference()
 
 	If there is any significant processing of the pointer value
 	between the rcu_dereference() that returned it and a later
-	dereference(), please read Documentation/RCU/rcu_dereference.txt.
+	dereference(), please read Documentation/RCU/rcu_dereference.rst.
 
 It can also be quite helpful to review uses in the Linux kernel.
 

Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

[Peter Zijlstra]

On Thu, Oct 15, 2020 at 07:15:18AM +0200, Mauro Carvalho Chehab wrote:
> I guess there might be some misunderstanding here. My fault. The plan
> is to have zero doc warnings for 5.10[1].

I'd be glad to help and convert all the documentation under my
maintainership to .txt files for you.

[PATCH v2 03/24] docs: SafeSetID: fix a warning

[Mauro Carvalho Chehab]

As reported by Sphinx 2.4.4:

	docs/Documentation/admin-guide/LSM/SafeSetID.rst:110: WARNING: Title underline too short.

	Note on GID policies and setgroups()
	==================

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

diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst
index 17996c9070e2..0ec34863c674 100644
--- a/Documentation/admin-guide/LSM/SafeSetID.rst
+++ b/Documentation/admin-guide/LSM/SafeSetID.rst
@@ -107,7 +107,7 @@ for a UID/GID will prevent that UID/GID from obtaining auxiliary setid
 privileges, such as allowing a user to set up user namespace UID/GID mappings.
 
 Note on GID policies and setgroups()
-==================
+====================================
 In v5.9 we are adding support for limiting CAP_SETGID privileges as was done
 previously for CAP_SETUID. However, for compatibility with common sandboxing
 related code conventions in userspace, we currently allow arbitrary
-- 
2.26.2

[PATCH v2 04/24] docs: lockdep-design: fix some warning issues

[Mauro Carvalho Chehab]

There are several warnings caused by a recent change
224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")

Those are reported by htmldocs build:

    Documentation/locking/lockdep-design.rst:429: WARNING: Definition list ends without a blank line; unexpected unindent.
    Documentation/locking/lockdep-design.rst:452: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/locking/lockdep-design.rst:453: WARNING: Unexpected indentation.
    Documentation/locking/lockdep-design.rst:453: WARNING: Blank line required after table.
    Documentation/locking/lockdep-design.rst:454: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/locking/lockdep-design.rst:455: WARNING: Unexpected indentation.
    Documentation/locking/lockdep-design.rst:455: WARNING: Blank line required after table.
    Documentation/locking/lockdep-design.rst:456: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/locking/lockdep-design.rst:457: WARNING: Unexpected indentation.
    Documentation/locking/lockdep-design.rst:457: WARNING: Blank line required after table.

Besides the reported issues, there are some missing blank
lines that ended producing wrong html output, and some
literals are not properly identified.

Also, the symbols used at the irq enabled/disable table
are not displayed as expected, as they're not literals.
Also, on another table they're using a different notation.

Fixes: 224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/locking/lockdep-design.rst | 69 ++++++++++++++----------
 1 file changed, 40 insertions(+), 29 deletions(-)

diff --git a/Documentation/locking/lockdep-design.rst b/Documentation/locking/lockdep-design.rst
index cec03bd1294a..7ac0c5092c21 100644
--- a/Documentation/locking/lockdep-design.rst
+++ b/Documentation/locking/lockdep-design.rst
@@ -42,6 +42,7 @@ The validator tracks lock-class usage history and divides the usage into
 (4 usages * n STATEs + 1) categories:
 
 where the 4 usages can be:
+
 - 'ever held in STATE context'
 - 'ever held as readlock in STATE context'
 - 'ever held with STATE enabled'
@@ -49,10 +50,12 @@ where the 4 usages can be:
 
 where the n STATEs are coded in kernel/locking/lockdep_states.h and as of
 now they include:
+
 - hardirq
 - softirq
 
 where the last 1 category is:
+
 - 'ever used'                                       [ == !unused        ]
 
 When locking rules are violated, these usage bits are presented in the
@@ -71,12 +74,12 @@ of the lock and readlock (if exists), for each of the n STATEs listed
 above respectively, and the character displayed at each bit position
 indicates:
 
-   ===  ===================================================
-   '.'  acquired while irqs disabled and not in irq context
-   '-'  acquired in irq context
-   '+'  acquired with irqs enabled
-   '?'  acquired in irq context with irqs enabled.
-   ===  ===================================================
+   =====  ===================================================
+   ``.``  acquired while irqs disabled and not in irq context
+   ``-``  acquired in irq context
+   ``+``  acquired with irqs enabled
+   ``?``  acquired in irq context with irqs enabled.
+   =====  ===================================================
 
 The bits are illustrated with an example::
 
@@ -96,14 +99,14 @@ exact case is for the lock as of the reporting time.
   +--------------+-------------+--------------+
   |              | irq enabled | irq disabled |
   +--------------+-------------+--------------+
-  | ever in irq  |      ?      |       -      |
+  | ever in irq  |    ``?``    |     ``-``    |
   +--------------+-------------+--------------+
-  | never in irq |      +      |       .      |
+  | never in irq |    ``+``    |     ``.``    |
   +--------------+-------------+--------------+
 
-The character '-' suggests irq is disabled because if otherwise the
-charactor '?' would have been shown instead. Similar deduction can be
-applied for '+' too.
+The character ``-`` suggests irq is disabled because if otherwise the
+charactor ``?`` would have been shown instead. Similar deduction can be
+applied for ``+`` too.
 
 Unused locks (e.g., mutexes) cannot be part of the cause of an error.
 
@@ -216,7 +219,7 @@ looks like this::
        BD_MUTEX_PARTITION
   };
 
-mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+  mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
 
 In this case the locking is done on a bdev object that is known to be a
 partition.
@@ -334,7 +337,7 @@ Troubleshooting:
 ----------------
 
 The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes.
-Exceeding this number will trigger the following lockdep warning:
+Exceeding this number will trigger the following lockdep warning::
 
 	(DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS))
 
@@ -420,7 +423,8 @@ the critical section of another reader of the same lock instance.
 
 The difference between recursive readers and non-recursive readers is because:
 recursive readers get blocked only by a write lock *holder*, while non-recursive
-readers could get blocked by a write lock *waiter*. Considering the follow example:
+readers could get blocked by a write lock *waiter*. Considering the follow
+example::
 
 	TASK A:			TASK B:
 
@@ -448,20 +452,22 @@ There are simply four block conditions:
 
 Block condition matrix, Y means the row blocks the column, and N means otherwise.
 
-	    | E | r | R |
 	+---+---+---+---+
-	  E | Y | Y | Y |
+	|   | E | r | R |
 	+---+---+---+---+
-	  r | Y | Y | N |
+	| E | Y | Y | Y |
+	+---+---+---+---+
+	| r | Y | Y | N |
+	+---+---+---+---+
+	| R | Y | Y | N |
 	+---+---+---+---+
-	  R | Y | Y | N |
 
 	(W: writers, r: non-recursive readers, R: recursive readers)
 
 
 acquired recursively. Unlike non-recursive read locks, recursive read locks
 only get blocked by current write lock *holders* other than write lock
-*waiters*, for example:
+*waiters*, for example::
 
 	TASK A:			TASK B:
 
@@ -491,7 +497,7 @@ Recursive locks don't block each other, while non-recursive locks do (this is
 even true for two non-recursive read locks). A non-recursive lock can block the
 corresponding recursive lock, and vice versa.
 
-A deadlock case with recursive locks involved is as follow:
+A deadlock case with recursive locks involved is as follow::
 
 	TASK A:			TASK B:
 
@@ -510,7 +516,7 @@ because there are 3 types for lockers, there are, in theory, 9 types of lock
 dependencies, but we can show that 4 types of lock dependencies are enough for
 deadlock detection.
 
-For each lock dependency:
+For each lock dependency::
 
 	L1 -> L2
 
@@ -525,20 +531,25 @@ same types).
 With the above combination for simplification, there are 4 types of dependency edges
 in the lockdep graph:
 
-1) -(ER)->: exclusive writer to recursive reader dependency, "X -(ER)-> Y" means
+1) -(ER)->:
+	    exclusive writer to recursive reader dependency, "X -(ER)-> Y" means
 	    X -> Y and X is a writer and Y is a recursive reader.
 
-2) -(EN)->: exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means
+2) -(EN)->:
+	    exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means
 	    X -> Y and X is a writer and Y is either a writer or non-recursive reader.
 
-3) -(SR)->: shared reader to recursive reader dependency, "X -(SR)-> Y" means
+3) -(SR)->:
+	    shared reader to recursive reader dependency, "X -(SR)-> Y" means
 	    X -> Y and X is a reader (recursive or not) and Y is a recursive reader.
 
-4) -(SN)->: shared reader to non-recursive locker dependency, "X -(SN)-> Y" means
+4) -(SN)->:
+	    shared reader to non-recursive locker dependency, "X -(SN)-> Y" means
 	    X -> Y and X is a reader (recursive or not) and Y is either a writer or
 	    non-recursive reader.
 
-Note that given two locks, they may have multiple dependencies between them, for example:
+Note that given two locks, they may have multiple dependencies between them,
+for example::
 
 	TASK A:
 
@@ -592,11 +603,11 @@ circles that won't cause deadlocks.
 
 Proof for sufficiency (Lemma 1):
 
-Let's say we have a strong circle:
+Let's say we have a strong circle::
 
 	L1 -> L2 ... -> Ln -> L1
 
-, which means we have dependencies:
+, which means we have dependencies::
 
 	L1 -> L2
 	L2 -> L3
@@ -633,7 +644,7 @@ a lock held by P2, and P2 is waiting for a lock held by P3, ... and Pn is waitin
 for a lock held by P1. Let's name the lock Px is waiting as Lx, so since P1 is waiting
 for L1 and holding Ln, so we will have Ln -> L1 in the dependency graph. Similarly,
 we have L1 -> L2, L2 -> L3, ..., Ln-1 -> Ln in the dependency graph, which means we
-have a circle:
+have a circle::
 
 	Ln -> L1 -> L2 -> ... -> Ln
 
-- 
2.26.2

Re: [PATCH v2 04/24] docs: lockdep-design: fix some warning issues

[Peter Zijlstra]

On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> +   =====  ===================================================
> +   ``.``  acquired while irqs disabled and not in irq context
> +   ``-``  acquired in irq context
> +   ``+``  acquired with irqs enabled
> +   ``?``  acquired in irq context with irqs enabled.
> +   =====  ===================================================
>  
>  The bits are illustrated with an example::
>  
> @@ -96,14 +99,14 @@ exact case is for the lock as of the reporting time.
>    +--------------+-------------+--------------+
>    |              | irq enabled | irq disabled |
>    +--------------+-------------+--------------+
> -  | ever in irq  |      ?      |       -      |
> +  | ever in irq  |    ``?``    |     ``-``    |
>    +--------------+-------------+--------------+
> -  | never in irq |      +      |       .      |
> +  | never in irq |    ``+``    |     ``.``    |
>    +--------------+-------------+--------------+
>  
> -The character '-' suggests irq is disabled because if otherwise the
> -charactor '?' would have been shown instead. Similar deduction can be
> -applied for '+' too.
> +The character ``-`` suggests irq is disabled because if otherwise the
> +charactor ``?`` would have been shown instead. Similar deduction can be
> +applied for ``+`` too.
>  

NAK!

Re: [PATCH v2 04/24] docs: lockdep-design: fix some warning issues

[Matthew Wilcox]

On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > +   =====  ===================================================
> > +   ``.``  acquired while irqs disabled and not in irq context
> > +   ``-``  acquired in irq context
> > +   ``+``  acquired with irqs enabled
> > +   ``?``  acquired in irq context with irqs enabled.
> > +   =====  ===================================================
>
> NAK!

You're seriously suggesting that:

-   ===  ===================================================
-   '.'  acquired while irqs disabled and not in irq context
-   '-'  acquired in irq context
-   '+'  acquired with irqs enabled
-   '?'  acquired in irq context with irqs enabled.
-   ===  ===================================================
+   =====  ===================================================
+   ``.``  acquired while irqs disabled and not in irq context
+   ``-``  acquired in irq context
+   ``+``  acquired with irqs enabled
+   ``?``  acquired in irq context with irqs enabled.
+   =====  ===================================================

this change makes the lockdep docs less readable?

It's not the markup that makes the lockdep documentation hard to
understand.

Re: [PATCH v2 04/24] docs: lockdep-design: fix some warning issues

[Peter Zijlstra]

On Tue, Oct 13, 2020 at 02:11:16PM +0100, Matthew Wilcox wrote:
> On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> > On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > > +   =====  ===================================================
> > > +   ``.``  acquired while irqs disabled and not in irq context
> > > +   ``-``  acquired in irq context
> > > +   ``+``  acquired with irqs enabled
> > > +   ``?``  acquired in irq context with irqs enabled.
> > > +   =====  ===================================================
> >
> > NAK!
> 
> You're seriously suggesting that:
> 
> -   ===  ===================================================
> -   '.'  acquired while irqs disabled and not in irq context
> -   '-'  acquired in irq context
> -   '+'  acquired with irqs enabled
> -   '?'  acquired in irq context with irqs enabled.
> -   ===  ===================================================
> +   =====  ===================================================
> +   ``.``  acquired while irqs disabled and not in irq context
> +   ``-``  acquired in irq context
> +   ``+``  acquired with irqs enabled
> +   ``?``  acquired in irq context with irqs enabled.
> +   =====  ===================================================
> 
> this change makes the lockdep docs less readable?

Definitely makes it harder to read for me. My C trained eyes go WTF at
seeing it, which breaks the flow. ',' is a regular single character
constant, '','' a syntax error.

> It's not the markup that makes the lockdep documentation hard to
> understand.

I'm not sure what you're alluding to, the subject just isn't easy to
begin with.

Over all I'm tempted to just convert the whole thing to .txt and avoid
all the RST shit entirely.

Re: [PATCH v2 04/24] docs: lockdep-design: fix some warning issues

[Matthew Wilcox]

On Tue, Oct 13, 2020 at 04:09:41PM +0200, Peter Zijlstra wrote:
> On Tue, Oct 13, 2020 at 02:11:16PM +0100, Matthew Wilcox wrote:
> > On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> > > On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > > > +   =====  ===================================================
> > > > +   ``.``  acquired while irqs disabled and not in irq context
> > > > +   ``-``  acquired in irq context
> > > > +   ``+``  acquired with irqs enabled
> > > > +   ``?``  acquired in irq context with irqs enabled.
> > > > +   =====  ===================================================
> > >
> > > NAK!
> > 
> > You're seriously suggesting that:
> > 
> > -   ===  ===================================================
> > -   '.'  acquired while irqs disabled and not in irq context
> > -   '-'  acquired in irq context
> > -   '+'  acquired with irqs enabled
> > -   '?'  acquired in irq context with irqs enabled.
> > -   ===  ===================================================
> > +   =====  ===================================================
> > +   ``.``  acquired while irqs disabled and not in irq context
> > +   ``-``  acquired in irq context
> > +   ``+``  acquired with irqs enabled
> > +   ``?``  acquired in irq context with irqs enabled.
> > +   =====  ===================================================
> > 
> > this change makes the lockdep docs less readable?
> 
> Definitely makes it harder to read for me. My C trained eyes go WTF at
> seeing it, which breaks the flow. ',' is a regular single character
> constant, '','' a syntax error.

OK, that's fair.  'a' is definitely a character constant.  Perhaps
the automarkup script can take care of this for us?  We'd have to
be careful not to catch anything we shouldn't've [1], but I'm sure
there's a regex for it.  Something like "\<'.'\>", perhaps?

[1] I'm quite proud of that one.

> > It's not the markup that makes the lockdep documentation hard to
> > understand.
> 
> I'm not sure what you're alluding to, the subject just isn't easy to
> begin with.

Absolutely.  The problem is (similar to most Linux documentation)
the document doesn't know who its audience is.  It mixes internal
implementation details of lockdep with what people need to know who
are just trying to understand what a lockdep splat means.  I don't
have time to restructure it right now though.

Re: [PATCH v2 04/24] docs: lockdep-design: fix some warning issues

[Mauro Carvalho Chehab]

Em Tue, 13 Oct 2020 16:02:50 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> On Tue, Oct 13, 2020 at 04:09:41PM +0200, Peter Zijlstra wrote:
> > On Tue, Oct 13, 2020 at 02:11:16PM +0100, Matthew Wilcox wrote:
> > > On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> > > > On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > > > > +   =====  ===================================================
> > > > > +   ``.``  acquired while irqs disabled and not in irq context
> > > > > +   ``-``  acquired in irq context
> > > > > +   ``+``  acquired with irqs enabled
> > > > > +   ``?``  acquired in irq context with irqs enabled.
> > > > > +   =====  ===================================================
> > > >
> > > > NAK!
> > > 
> > > You're seriously suggesting that:
> > > 
> > > -   ===  ===================================================
> > > -   '.'  acquired while irqs disabled and not in irq context
> > > -   '-'  acquired in irq context
> > > -   '+'  acquired with irqs enabled
> > > -   '?'  acquired in irq context with irqs enabled.
> > > -   ===  ===================================================
> > > +   =====  ===================================================
> > > +   ``.``  acquired while irqs disabled and not in irq context
> > > +   ``-``  acquired in irq context
> > > +   ``+``  acquired with irqs enabled
> > > +   ``?``  acquired in irq context with irqs enabled.
> > > +   =====  ===================================================
> > > 
> > > this change makes the lockdep docs less readable?
> > 
> > Definitely makes it harder to read for me. My C trained eyes go WTF at
> > seeing it, which breaks the flow. ',' is a regular single character
> > constant, '','' a syntax error.
> 
> OK, that's fair.  'a' is definitely a character constant.  Perhaps
> the automarkup script can take care of this for us?  We'd have to
> be careful not to catch anything we shouldn't've [1], but I'm sure
> there's a regex for it.  Something like "\<'.'\>", perhaps?

I guess that this regex could work:

	/\b\'\S\'\b/ 

would get this very specific case, or maybe even:
	/\b\'\S+\'\b/

in order to get things like 'foo'.

Adding support for something like this at 
Documentation/sphinx/automarkup.py should be trivial. However,
checking if this won't be doing anything wrong with the other existing
files can be painful.

Yet, there are 3 issues related to '.' character usage.

See, the first table is:

   ===  ===================================================
   '.'  acquired while irqs disabled and not in irq context
   '-'  acquired in irq context
   '+'  acquired with irqs enabled
   '?'  acquired in irq context with irqs enabled.
   ===  ===================================================

There, it uses '.' in order to indicate the dot character and so on.

The second table uses a different notation:

   +--------------+-------------+--------------+
   |              | irq enabled | irq disabled |
   +--------------+-------------+--------------+
   | ever in irq  |      ?      |       -      |
   +--------------+-------------+--------------+
   | never in irq |      +      |       .      |
   +--------------+-------------+--------------+

which uses just a question mark without aphostrophes, instead of
'?' (and the same for the other symbols).

The text describing them returns back to the notation used at the
first table:

	"The character '-' suggests irq is disabled because if otherwise the
	 charactor '?' would have been shown instead. Similar deduction can be
	 applied for '+' too."

-

The above has actually 3 separate problems:

1) This problem has nothing to do with Sphinx notation. The notation
   is not coherent: It should use either ., ``.`` or '.' everywhere.  

2) This is Sphinx-specific: a single minus or a single plus character
indicates a list. On both cases, this is actually replaced by an UTF-8
bullet character: '•'.

3) This is a minor issue:

   using '.' will produce an html table that will display, using
   a normal font, as '.', while ``.`` would use a monospaced 
   font and won't display the apostrophes. IMO, at the html output, 
   it would be better to just a dot without apostrophes, as the
   text of the dmesg output doesn't have apostrophes either:

     "When locking rules are violated, these usage bits are presented in the
      locking error messages, inside curlies, with a total of 2 * n STATEs bits.
      A contrived example::

        modprobe/2287 is trying to acquire lock:
         (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24

        but task is already holding lock:
         (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24"

   Yet, we could live without addressing this one.

> [1] I'm quite proud of that one.
> 
> > > It's not the markup that makes the lockdep documentation hard to
> > > understand.
> > 
> > I'm not sure what you're alluding to, the subject just isn't easy to
> > begin with.
> 
> Absolutely.  The problem is (similar to most Linux documentation)
> the document doesn't know who its audience is.  It mixes internal
> implementation details of lockdep with what people need to know who
> are just trying to understand what a lockdep splat means.  I don't
> have time to restructure it right now though.

Yeah, that is one of the the main issues with this. This specific 
section of the file describes something that a sysadmin or a Kernel
newbie may see on his system. He'll likely seek the web for some
documentation about that, in order to try to understand it.

If someone is willing to do that, it will get this:

	https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#state

Where it presents a plain wrong table that it would look like this:

   +--------------+-------------+--------------+
   |              | irq enabled | irq disabled |
   +--------------+-------------+--------------+
   | ever in irq  |      ?      |       •      |
   +--------------+-------------+--------------+
   | never in irq |      •      |       .      |
   +--------------+-------------+--------------+

If you prefer, I can send a new version of this patch using this at
the second table:

   +--------------+-------------+--------------+
   |              | irq enabled | irq disabled |
   +--------------+-------------+--------------+
   | ever in irq  |     '?'     |      '-'     |
   +--------------+-------------+--------------+
   | never in irq |     '+'     |      '.'     |
   +--------------+-------------+--------------+

and keep using '.' at the other parts of the document.

This should solve the Sphinx issue, although the Sphinx output
won't be using a monospaced font.

Thanks,
Mauro

[PATCH v2 05/24] docs: admin-guide: net.rst: add a missing blank line

[Mauro Carvalho Chehab]

There's a missing blank line after a literal block, which
causes this warning:

	Documentation/admin-guide/sysctl/net.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.

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

diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst
index 57fd6ce68fe0..f2ab8a5b6a4b 100644
--- a/Documentation/admin-guide/sysctl/net.rst
+++ b/Documentation/admin-guide/sysctl/net.rst
@@ -300,6 +300,7 @@ Note:
       0:    0     1     2     3     4     5     6     7
   RSS hash key:
   84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89
+
 netdev_tstamp_prequeue
 ----------------------
 
-- 
2.26.2

[PATCH v2 06/24] blk-mq: docs: add kernel-doc description for a new struct member

[Mauro Carvalho Chehab]

As reported by kernel-doc:
	./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'

There is now a new member for struct blk_mq_tag_set. Add a
description for it, based on the commit that introduced it.

Fixes: f1b49fdc1c64 ("blk-mq: Record active_queues_shared_sbitmap per tag_set for when using shared sbitmap")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/blk-mq.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/linux/blk-mq.h b/include/linux/blk-mq.h
index b23eeca4d677..794b2a33a2c3 100644
--- a/include/linux/blk-mq.h
+++ b/include/linux/blk-mq.h
@@ -235,6 +235,8 @@ enum hctx_type {
  * @flags:	   Zero or more BLK_MQ_F_* flags.
  * @driver_data:   Pointer to data owned by the block driver that created this
  *		   tag set.
+ * @active_queues_shared_sbitmap:
+ * 		   number of active request queues per tag set.
  * @__bitmap_tags: A shared tags sbitmap, used over all hctx's
  * @__breserved_tags:
  *		   A shared reserved tags sbitmap, used over all hctx's
-- 
2.26.2

Re: [PATCH v2 06/24] blk-mq: docs: add kernel-doc description for a new struct member

[John Garry]

On 13/10/2020 13:14, Mauro Carvalho Chehab wrote:
> As reported by kernel-doc:
> 	./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'
> 
> There is now a new member for struct blk_mq_tag_set. Add a
> description for it, based on the commit that introduced it.
> 
> Fixes: f1b49fdc1c64 ("blk-mq: Record active_queues_shared_sbitmap per tag_set for when using shared sbitmap")
> Signed-off-by: Mauro Carvalho Chehab<mchehab+huawei@kernel.org>

Reviewed-by: John Garry <john.garry@huawei.com>

Re: [PATCH v2 06/24] blk-mq: docs: add kernel-doc description for a new struct member

[Jens Axboe]

On 10/13/20 6:14 AM, Mauro Carvalho Chehab wrote:
> As reported by kernel-doc:
> 	./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'
> 
> There is now a new member for struct blk_mq_tag_set. Add a
> description for it, based on the commit that introduced it.

Reviewed-by: Jens Axboe <axboe@kernel.dk>

-- 
Jens Axboe

[PATCH v2 07/24] drm: amdgpu: kernel-doc: update some adev parameters

[Mauro Carvalho Chehab]

Running "make htmldocs: produce lots of warnings on those files:
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'

They're related to the repacement of some parameters by adev,
and due to a few renamed parameters.

Update the kernel-doc documentation accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c   | 2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c  | 6 +++---
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 5 ++---
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
index f8f298b34805..fb375752feb1 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
@@ -817,7 +817,7 @@ static void amdgpu_block_invalid_wreg(struct amdgpu_device *adev,
 /**
  * amdgpu_device_asic_init - Wrapper for atom asic_init
  *
- * @dev: drm_device pointer
+ * @adev: drm_device pointer
  *
  * Does any asic specific work and then calls atom asic init.
  */
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
index f203e4a6a3f2..5f3a04cd0fba 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
@@ -81,8 +81,8 @@ static const struct ttm_resource_manager_func amdgpu_gtt_mgr_func;
 /**
  * amdgpu_gtt_mgr_init - init GTT manager and DRM MM
  *
- * @man: TTM memory type manager
- * @p_size: maximum size of GTT
+ * @adev: amdgpu device structure
+ * @gtt_size: maximum size of GTT
  *
  * Allocate and initialize the GTT manager.
  */
@@ -123,7 +123,7 @@ int amdgpu_gtt_mgr_init(struct amdgpu_device *adev, uint64_t gtt_size)
 /**
  * amdgpu_gtt_mgr_fini - free and destroy GTT manager
  *
- * @man: TTM memory type manager
+ * @adev: amdgpu device structure
  *
  * Destroy and free the GTT manager, returns -EBUSY if ranges are still
  * allocated inside it.
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
index 01c1171afbe0..a0e787ddbbd7 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
@@ -168,8 +168,7 @@ static const struct ttm_resource_manager_func amdgpu_vram_mgr_func;
 /**
  * amdgpu_vram_mgr_init - init VRAM manager and DRM MM
  *
- * @man: TTM memory type manager
- * @p_size: maximum size of VRAM
+ * @adev: amdgpu device structure
  *
  * Allocate and initialize the VRAM manager.
  */
@@ -199,7 +198,7 @@ int amdgpu_vram_mgr_init(struct amdgpu_device *adev)
 /**
  * amdgpu_vram_mgr_fini - free and destroy VRAM manager
  *
- * @man: TTM memory type manager
+ * @adev: amdgpu device structure
  *
  * Destroy and free the VRAM manager, returns -EBUSY if ranges are still
  * allocated inside it.
-- 
2.26.2

Re: [PATCH v2 07/24] drm: amdgpu: kernel-doc: update some adev parameters

[Christian König]

Am 13.10.20 um 14:14 schrieb Mauro Carvalho Chehab:
> Running "make htmldocs: produce lots of warnings on those files:
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
> 	./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
>
> They're related to the repacement of some parameters by adev,
> and due to a few renamed parameters.
>
> Update the kernel-doc documentation accordingly.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   drivers/gpu/drm/amd/amdgpu/amdgpu_device.c   | 2 +-
>   drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c  | 6 +++---
>   drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 5 ++---
>   3 files changed, 6 insertions(+), 7 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> index f8f298b34805..fb375752feb1 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> @@ -817,7 +817,7 @@ static void amdgpu_block_invalid_wreg(struct amdgpu_device *adev,
>   /**
>    * amdgpu_device_asic_init - Wrapper for atom asic_init
>    *
> - * @dev: drm_device pointer
> + * @adev: drm_device pointer

This should probably read amdgpu device pointer, but apart from that 
looks good to me.

Christian.

>    *
>    * Does any asic specific work and then calls atom asic init.
>    */
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
> index f203e4a6a3f2..5f3a04cd0fba 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
> @@ -81,8 +81,8 @@ static const struct ttm_resource_manager_func amdgpu_gtt_mgr_func;
>   /**
>    * amdgpu_gtt_mgr_init - init GTT manager and DRM MM
>    *
> - * @man: TTM memory type manager
> - * @p_size: maximum size of GTT
> + * @adev: amdgpu device structure
> + * @gtt_size: maximum size of GTT
>    *
>    * Allocate and initialize the GTT manager.
>    */
> @@ -123,7 +123,7 @@ int amdgpu_gtt_mgr_init(struct amdgpu_device *adev, uint64_t gtt_size)
>   /**
>    * amdgpu_gtt_mgr_fini - free and destroy GTT manager
>    *
> - * @man: TTM memory type manager
> + * @adev: amdgpu device structure
>    *
>    * Destroy and free the GTT manager, returns -EBUSY if ranges are still
>    * allocated inside it.
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> index 01c1171afbe0..a0e787ddbbd7 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> @@ -168,8 +168,7 @@ static const struct ttm_resource_manager_func amdgpu_vram_mgr_func;
>   /**
>    * amdgpu_vram_mgr_init - init VRAM manager and DRM MM
>    *
> - * @man: TTM memory type manager
> - * @p_size: maximum size of VRAM
> + * @adev: amdgpu device structure
>    *
>    * Allocate and initialize the VRAM manager.
>    */
> @@ -199,7 +198,7 @@ int amdgpu_vram_mgr_init(struct amdgpu_device *adev)
>   /**
>    * amdgpu_vram_mgr_fini - free and destroy VRAM manager
>    *
> - * @man: TTM memory type manager
> + * @adev: amdgpu device structure
>    *
>    * Destroy and free the VRAM manager, returns -EBUSY if ranges are still
>    * allocated inside it.

[PATCH v2 08/24] drm: kernel-doc: document drm_dp_set_subconnector_property() params

[Mauro Carvalho Chehab]

Changeset e5b92773287c ("drm: report dp downstream port type as a subconnector property")
added a new function to the kAPI, but didn't add any documentation
for the parameters for drm_dp_set_subconnector_property().

Fixes: e5b92773287c ("drm: report dp downstream port type as a subconnector property")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_dp_helper.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index 90807a6b415c..b1c71af88579 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -1028,7 +1028,8 @@ EXPORT_SYMBOL(drm_dp_downstream_debug);
 
 /**
  * drm_dp_subconnector_type() - get DP branch device type
- *
+ * @dpcd: DisplayPort configuration data
+ * @port_cap: port capabilities
  */
 enum drm_mode_subconnector
 drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
@@ -1079,6 +1080,10 @@ EXPORT_SYMBOL(drm_dp_subconnector_type);
 
 /**
  * drm_mode_set_dp_subconnector_property - set subconnector for DP connector
+ * @connector: connector to set property on
+ * @status: connector status
+ * @dpcd: DisplayPort configuration data
+ * @port_cap: port capabilities
  *
  * Called by a driver on every detect event.
  */
-- 
2.26.2

[PATCH v2 09/24] docs: kasan.rst: add two missing blank lines

[Mauro Carvalho Chehab]

literal blocks should start and end with a blank line,
as otherwise the parser complains and may do the wrong
thing, as warned by Sphinx:

	Documentation/dev-tools/kasan.rst:298: WARNING: Literal block ends without a blank line; unexpected unindent.
	Documentation/dev-tools/kasan.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.

Reviewed-by: Andrey Konovalov <andreyknvl@google.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/dev-tools/kasan.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
index c09c9ca2ff1c..2b68addaadcd 100644
--- a/Documentation/dev-tools/kasan.rst
+++ b/Documentation/dev-tools/kasan.rst
@@ -295,11 +295,13 @@ print the number of the test and the status of the test:
 pass::
 
         ok 28 - kmalloc_double_kzfree
+
 or, if kmalloc failed::
 
         # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163
         Expected ptr is not null, but is
         not ok 4 - kmalloc_large_oob_right
+
 or, if a KASAN report was expected, but not found::
 
         # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629
-- 
2.26.2

[PATCH v2 10/24] mm: pagemap.h: fix two kernel-doc markups

[Mauro Carvalho Chehab]

Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
index parameter, but forgot to update the kernel-doc markups
accordingly.

Fixes: 6c8adf8446a3 ("mm: add find_lock_head")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/pagemap.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
index 7dd3523093db..932a260a29f2 100644
--- a/include/linux/pagemap.h
+++ b/include/linux/pagemap.h
@@ -342,9 +342,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
 /**
  * find_lock_page - locate, pin and lock a pagecache page
  * @mapping: the address_space to search
- * @offset: the page index
+ * @index: the page index
  *
- * Looks up the page cache entry at @mapping & @offset.  If there is a
+ * Looks up the page cache entry at @mapping & @index.  If there is a
  * page cache page, it is returned locked and with an increased
  * refcount.
  *
@@ -361,9 +361,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
 /**
  * find_lock_head - Locate, pin and lock a pagecache page.
  * @mapping: The address_space to search.
- * @offset: The page index.
+ * @index: The page index.
  *
- * Looks up the page cache entry at @mapping & @offset.  If there is a
+ * Looks up the page cache entry at @mapping & @index.  If there is a
  * page cache page, its head page is returned locked and with an increased
  * refcount.
  *
-- 
2.26.2

Re: [PATCH v2 10/24] mm: pagemap.h: fix two kernel-doc markups

[Matthew Wilcox]

On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> index parameter, but forgot to update the kernel-doc markups
> accordingly.

The patch is correct (thank you!), but the description here references
a git commit id that's only found in the -next tree and is unstable.

Andrew, can you fold this into the offending commit?

> Fixes: 6c8adf8446a3 ("mm: add find_lock_head")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  include/linux/pagemap.h | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
> index 7dd3523093db..932a260a29f2 100644
> --- a/include/linux/pagemap.h
> +++ b/include/linux/pagemap.h
> @@ -342,9 +342,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
>  /**
>   * find_lock_page - locate, pin and lock a pagecache page
>   * @mapping: the address_space to search
> - * @offset: the page index
> + * @index: the page index
>   *
> - * Looks up the page cache entry at @mapping & @offset.  If there is a
> + * Looks up the page cache entry at @mapping & @index.  If there is a
>   * page cache page, it is returned locked and with an increased
>   * refcount.
>   *
> @@ -361,9 +361,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
>  /**
>   * find_lock_head - Locate, pin and lock a pagecache page.
>   * @mapping: The address_space to search.
> - * @offset: The page index.
> + * @index: The page index.
>   *
> - * Looks up the page cache entry at @mapping & @offset.  If there is a
> + * Looks up the page cache entry at @mapping & @index.  If there is a
>   * page cache page, its head page is returned locked and with an increased
>   * refcount.
>   *
> -- 
> 2.26.2
> 

Re: [PATCH v2 10/24] mm: pagemap.h: fix two kernel-doc markups

[Mauro Carvalho Chehab]

Hi Matthew,

Em Tue, 13 Oct 2020 13:26:54 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> > Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> > index parameter, but forgot to update the kernel-doc markups
> > accordingly.  
> 
> The patch is correct (thank you!), but the description here references
> a git commit id that's only found in the -next tree and is unstable.
> 
> Andrew, can you fold this into the offending commit?

Patch already reached upstream. So, it gained a stable reference.

So, I'm changing its description to:

  Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
  Date:   Thu Sep 10 08:38:07 2020 +0200

    locking/refcount: move kernel-doc markups to the proper place
    
    Changeset a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
    added a set of functions starting with __ that have a new
    parameter, adding a series of new warnings:
    
            $ ./scripts/kernel-doc -none include/linux/refcount.h
            include/linux/refcount.h:169: warning: Function parameter or member 'oldp' not described in '__refcount_add_not_zero'
            include/linux/refcount.h:208: warning: Function parameter or member 'oldp' not described in '__refcount_add'
            include/linux/refcount.h:239: warning: Function parameter or member 'oldp' not described in '__refcount_inc_not_zero'
            include/linux/refcount.h:261: warning: Function parameter or member 'oldp' not described in '__refcount_inc'
            include/linux/refcount.h:291: warning: Function parameter or member 'oldp' not described in '__refcount_sub_and_test'
            include/linux/refcount.h:327: warning: Function parameter or member 'oldp' not described in '__refcount_dec_and_test'
            include/linux/refcount.h:347: warning: Function parameter or member 'oldp' not described in '__refcount_dec'
    
    The issue is that the kernel-doc markups are now misplaced,
    as they should be added just before the functions.
    
    So, move the kernel-doc markups to the proper places,
    in order to drop the warnings.
    
    It should be noticed that git show produces a crappy output,
    for this patch without "--patience" flag.
    
    Fixes: a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
    Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

If ok for you, I should be sending it upstream on a next pull request
for the documentation warning fix series.

Regards,
Mauro

> 
> > Fixes: 6c8adf8446a3 ("mm: add find_lock_head")
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  include/linux/pagemap.h | 8 ++++----
> >  1 file changed, 4 insertions(+), 4 deletions(-)
> > 
> > diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
> > index 7dd3523093db..932a260a29f2 100644
> > --- a/include/linux/pagemap.h
> > +++ b/include/linux/pagemap.h
> > @@ -342,9 +342,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
> >  /**
> >   * find_lock_page - locate, pin and lock a pagecache page
> >   * @mapping: the address_space to search
> > - * @offset: the page index
> > + * @index: the page index
> >   *
> > - * Looks up the page cache entry at @mapping & @offset.  If there is a
> > + * Looks up the page cache entry at @mapping & @index.  If there is a
> >   * page cache page, it is returned locked and with an increased
> >   * refcount.
> >   *
> > @@ -361,9 +361,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
> >  /**
> >   * find_lock_head - Locate, pin and lock a pagecache page.
> >   * @mapping: The address_space to search.
> > - * @offset: The page index.
> > + * @index: The page index.
> >   *
> > - * Looks up the page cache entry at @mapping & @offset.  If there is a
> > + * Looks up the page cache entry at @mapping & @index.  If there is a
> >   * page cache page, its head page is returned locked and with an increased
> >   * refcount.
> >   *
> > -- 
> > 2.26.2
> >   



Thanks,
Mauro

Re: [PATCH v2 10/24] mm: pagemap.h: fix two kernel-doc markups

[Matthew Wilcox]

On Wed, Oct 21, 2020 at 11:55:57AM +0200, Mauro Carvalho Chehab wrote:
> Hi Matthew,
> 
> Em Tue, 13 Oct 2020 13:26:54 +0100
> Matthew Wilcox <willy@infradead.org> escreveu:
> 
> > On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> > > Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> > > index parameter, but forgot to update the kernel-doc markups
> > > accordingly.  
> > 
> > The patch is correct (thank you!), but the description here references
> > a git commit id that's only found in the -next tree and is unstable.
> > 
> > Andrew, can you fold this into the offending commit?
> 
> Patch already reached upstream. So, it gained a stable reference.
> 
> So, I'm changing its description to:
> 
>   Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>   Date:   Thu Sep 10 08:38:07 2020 +0200
> 
>     locking/refcount: move kernel-doc markups to the proper place

This is the wrong changelog?

Re: [PATCH v2 10/24] mm: pagemap.h: fix two kernel-doc markups

[Mauro Carvalho Chehab]

Em Wed, 21 Oct 2020 12:28:19 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> On Wed, Oct 21, 2020 at 11:55:57AM +0200, Mauro Carvalho Chehab wrote:
> > Hi Matthew,
> > 
> > Em Tue, 13 Oct 2020 13:26:54 +0100
> > Matthew Wilcox <willy@infradead.org> escreveu:
> >   
> > > On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:  
> > > > Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> > > > index parameter, but forgot to update the kernel-doc markups
> > > > accordingly.    
> > > 
> > > The patch is correct (thank you!), but the description here references
> > > a git commit id that's only found in the -next tree and is unstable.
> > > 
> > > Andrew, can you fold this into the offending commit?  
> > 
> > Patch already reached upstream. So, it gained a stable reference.
> > 
> > So, I'm changing its description to:
> > 
> >   Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >   Date:   Thu Sep 10 08:38:07 2020 +0200
> > 
> >     locking/refcount: move kernel-doc markups to the proper place  
> 
> This is the wrong changelog?

Sorry! Yeah, that was the wrong one. I'm enclosing the right one
with the complete patch.

Thanks,
Mauro

[PATCH] mm: pagemap.h: fix two kernel-doc markups

Changeset a8cf7f272b5a ("mm: add find_lock_head") renamed the
index parameter, but forgot to update the kernel-doc markups
accordingly.

Fixes: a8cf7f272b5a ("mm: add find_lock_head")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
index c77b7c31b2e4..e1e19c1f9ec9 100644
--- a/include/linux/pagemap.h
+++ b/include/linux/pagemap.h
@@ -344,9 +344,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
 /**
  * find_lock_page - locate, pin and lock a pagecache page
  * @mapping: the address_space to search
- * @offset: the page index
+ * @index: the page index
  *
- * Looks up the page cache entry at @mapping & @offset.  If there is a
+ * Looks up the page cache entry at @mapping & @index.  If there is a
  * page cache page, it is returned locked and with an increased
  * refcount.
  *
@@ -363,9 +363,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
 /**
  * find_lock_head - Locate, pin and lock a pagecache page.
  * @mapping: The address_space to search.
- * @offset: The page index.
+ * @index: The page index.
  *
- * Looks up the page cache entry at @mapping & @offset.  If there is a
+ * Looks up the page cache entry at @mapping & @index.  If there is a
  * page cache page, its head page is returned locked and with an increased
  * refcount.
  *

Re: [PATCH v2 10/24] mm: pagemap.h: fix two kernel-doc markups

[Matthew Wilcox]

On Wed, Oct 21, 2020 at 01:59:03PM +0200, Mauro Carvalho Chehab wrote:
> [PATCH] mm: pagemap.h: fix two kernel-doc markups
> 
> Changeset a8cf7f272b5a ("mm: add find_lock_head") renamed the
> index parameter, but forgot to update the kernel-doc markups
> accordingly.
> 
> Fixes: a8cf7f272b5a ("mm: add find_lock_head")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org>

[PATCH v2 11/24] drm/dp: fix kernel-doc warnings at drm_dp_helper.c

[Mauro Carvalho Chehab]

As warned by kernel-doc:

	./drivers/gpu/drm/drm_dp_helper.c:385: warning: Function parameter or member 'type' not described in 'drm_dp_downstream_is_type'
	./drivers/gpu/drm/drm_dp_helper.c:886: warning: Function parameter or member 'dev' not described in 'drm_dp_downstream_mode'

Some function parameters weren't documented.

Fixes: 38784f6f8805 ("drm/dp: Add helpers to identify downstream facing port types")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_dp_helper.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index b1c71af88579..deeed73f4ed6 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -374,6 +374,10 @@ static bool is_edid_digital_input_dp(const struct edid *edid)
  * drm_dp_downstream_is_type() - is the downstream facing port of certain type?
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
+ * @type: port type to be checked. Can be:
+ * 	  %DP_DS_PORT_TYPE_DP, %DP_DS_PORT_TYPE_VGA, %DP_DS_PORT_TYPE_DVI,
+ * 	  %DP_DS_PORT_TYPE_HDMI, %DP_DS_PORT_TYPE_NON_EDID,
+ *	  %DP_DS_PORT_TYPE_DP_DUALMODE or %DP_DS_PORT_TYPE_WIRELESS.
  *
  * Caveat: Only works with DPCD 1.1+ port caps.
  *
@@ -870,6 +874,7 @@ EXPORT_SYMBOL(drm_dp_downstream_444_to_420_conversion);
 
 /**
  * drm_dp_downstream_mode() - return a mode for downstream facing port
+ * @dev: DRM device
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
  *
-- 
2.26.2

Re: [PATCH v2 11/24] drm/dp: fix kernel-doc warnings at drm_dp_helper.c

[Lyude Paul]

Reviewed-by: Lyude Paul <lyude@redhat.com>

On Tue, 2020-10-13 at 14:14 +0200, Mauro Carvalho Chehab wrote:
> As warned by kernel-doc:
> 
> 	./drivers/gpu/drm/drm_dp_helper.c:385: warning: Function parameter or
> member 'type' not described in 'drm_dp_downstream_is_type'
> 	./drivers/gpu/drm/drm_dp_helper.c:886: warning: Function parameter or
> member 'dev' not described in 'drm_dp_downstream_mode'
> 
> Some function parameters weren't documented.
> 
> Fixes: 38784f6f8805 ("drm/dp: Add helpers to identify downstream facing port
> types")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/gpu/drm/drm_dp_helper.c | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
> index b1c71af88579..deeed73f4ed6 100644
> --- a/drivers/gpu/drm/drm_dp_helper.c
> +++ b/drivers/gpu/drm/drm_dp_helper.c
> @@ -374,6 +374,10 @@ static bool is_edid_digital_input_dp(const struct edid
> *edid)
>   * drm_dp_downstream_is_type() - is the downstream facing port of certain
> type?
>   * @dpcd: DisplayPort configuration data
>   * @port_cap: port capabilities
> + * @type: port type to be checked. Can be:
> + * 	  %DP_DS_PORT_TYPE_DP, %DP_DS_PORT_TYPE_VGA, %DP_DS_PORT_TYPE_DVI,
> + * 	  %DP_DS_PORT_TYPE_HDMI, %DP_DS_PORT_TYPE_NON_EDID,
> + *	  %DP_DS_PORT_TYPE_DP_DUALMODE or %DP_DS_PORT_TYPE_WIRELESS.
>   *
>   * Caveat: Only works with DPCD 1.1+ port caps.
>   *
> @@ -870,6 +874,7 @@ EXPORT_SYMBOL(drm_dp_downstream_444_to_420_conversion);
>  
>  /**
>   * drm_dp_downstream_mode() - return a mode for downstream facing port
> + * @dev: DRM device
>   * @dpcd: DisplayPort configuration data
>   * @port_cap: port capabilities
>   *
-- 
Sincerely,
      Lyude Paul (she/her)
      Software Engineer at Red Hat

Note: I deal with a lot of emails and have a lot of bugs on my plate. If you've
asked me a question, are waiting for a review/merge on a patch, etc. and I
haven't responded in a while, please feel free to send me another email to check
on my status. I don't bite!

[PATCH v2 12/24] drm/dp: fix a kernel-doc issue at drm_edid.c

[Mauro Carvalho Chehab]

The name of the argument is different, causing those warnings:

	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or member 'video_code' not described in 'drm_display_mode_from_cea_vic'
	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter 'vic' description in 'drm_display_mode_from_cea_vic'

Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_edid.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
index a82f37d44258..631125b46e04 100644
--- a/drivers/gpu/drm/drm_edid.c
+++ b/drivers/gpu/drm/drm_edid.c
@@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector *connector, u8 svd)
 /**
  * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
  * @dev: DRM device
- * @vic: CEA VIC of the mode
+ * @video_code: CEA VIC of the mode
  *
  * Creates a new mode matching the specified CEA VIC.
  *
-- 
2.26.2

Re: [PATCH v2 12/24] drm/dp: fix a kernel-doc issue at drm_edid.c

[Lyude Paul]

Reviewed-by: Lyude Paul <lyude@redhat.com>

Thanks for the fixes! I will go ahead and push 11 and 12 to drm-misc-next.

On Tue, 2020-10-13 at 14:14 +0200, Mauro Carvalho Chehab wrote:
> The name of the argument is different, causing those warnings:
> 
> 	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or member
> 'video_code' not described in 'drm_display_mode_from_cea_vic'
> 	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter
> 'vic' description in 'drm_display_mode_from_cea_vic'
> 
> Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/gpu/drm/drm_edid.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
> index a82f37d44258..631125b46e04 100644
> --- a/drivers/gpu/drm/drm_edid.c
> +++ b/drivers/gpu/drm/drm_edid.c
> @@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector *connector, u8
> svd)
>  /**
>   * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
>   * @dev: DRM device
> - * @vic: CEA VIC of the mode
> + * @video_code: CEA VIC of the mode
>   *
>   * Creates a new mode matching the specified CEA VIC.
>   *
-- 
Sincerely,
      Lyude Paul (she/her)
      Software Engineer at Red Hat

Note: I deal with a lot of emails and have a lot of bugs on my plate. If you've
asked me a question, are waiting for a review/merge on a patch, etc. and I
haven't responded in a while, please feel free to send me another email to check
on my status. I don't bite!

Re: [PATCH v2 12/24] drm/dp: fix a kernel-doc issue at drm_edid.c

[Lyude Paul]

wait, I think there's some confusion here. these patches have already been
pushed


On Tue, 2020-10-13 at 14:14 +0200, Mauro Carvalho Chehab wrote:
> The name of the argument is different, causing those warnings:
> 
> 	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or member
> 'video_code' not described in 'drm_display_mode_from_cea_vic'
> 	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter
> 'vic' description in 'drm_display_mode_from_cea_vic'
> 
> Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/gpu/drm/drm_edid.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
> index a82f37d44258..631125b46e04 100644
> --- a/drivers/gpu/drm/drm_edid.c
> +++ b/drivers/gpu/drm/drm_edid.c
> @@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector *connector, u8
> svd)
>  /**
>   * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
>   * @dev: DRM device
> - * @vic: CEA VIC of the mode
> + * @video_code: CEA VIC of the mode
>   *
>   * Creates a new mode matching the specified CEA VIC.
>   *
-- 
Sincerely,
      Lyude Paul (she/her)
      Software Engineer at Red Hat

Note: I deal with a lot of emails and have a lot of bugs on my plate. If you've
asked me a question, are waiting for a review/merge on a patch, etc. and I
haven't responded in a while, please feel free to send me another email to check
on my status. I don't bite!

Re: [PATCH v2 12/24] drm/dp: fix a kernel-doc issue at drm_edid.c

[Mauro Carvalho Chehab]

Hi Lyude,

Em Tue, 13 Oct 2020 15:49:11 -0400
Lyude Paul <lyude@redhat.com> escreveu:

> wait, I think there's some confusion here. these patches have already been
> pushed

As the patch adding the warning was merged upstream at the 5.10 merge
window, the fixup one should also be added there, instead of waiting
until 5.11 ;-)

So, if OK for you, I'll send this upstream via my tree by the end of
the merge window, as our goal is that 5.10 won't have doc warnings.

Regards,
Mauro
> 
> 
> On Tue, 2020-10-13 at 14:14 +0200, Mauro Carvalho Chehab wrote:
> > The name of the argument is different, causing those warnings:
> > 
> > 	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or member
> > 'video_code' not described in 'drm_display_mode_from_cea_vic'
> > 	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter
> > 'vic' description in 'drm_display_mode_from_cea_vic'
> > 
> > Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  drivers/gpu/drm/drm_edid.c | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
> > index a82f37d44258..631125b46e04 100644
> > --- a/drivers/gpu/drm/drm_edid.c
> > +++ b/drivers/gpu/drm/drm_edid.c
> > @@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector *connector, u8
> > svd)
> >  /**
> >   * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
> >   * @dev: DRM device
> > - * @vic: CEA VIC of the mode
> > + * @video_code: CEA VIC of the mode
> >   *
> >   * Creates a new mode matching the specified CEA VIC.
> >   *  



Thanks,
Mauro

Re: [PATCH v2 12/24] drm/dp: fix a kernel-doc issue at drm_edid.c

[Lyude Paul]

Ah, good point. It looks like you've already added the drm-misc-next and drm
maintainers to here so as long as they're aware that should be fine

On Wed, 2020-10-21 at 12:11 +0200, Mauro Carvalho Chehab wrote:
> Hi Lyude,
> 
> Em Tue, 13 Oct 2020 15:49:11 -0400
> Lyude Paul <lyude@redhat.com> escreveu:
> 
> > wait, I think there's some confusion here. these patches have already been
> > pushed
> 
> As the patch adding the warning was merged upstream at the 5.10 merge
> window, the fixup one should also be added there, instead of waiting
> until 5.11 ;-)
> 
> So, if OK for you, I'll send this upstream via my tree by the end of
> the merge window, as our goal is that 5.10 won't have doc warnings.
> 
> Regards,
> Mauro
> > 
> > On Tue, 2020-10-13 at 14:14 +0200, Mauro Carvalho Chehab wrote:
> > > The name of the argument is different, causing those warnings:
> > > 
> > > 	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or
> > > member
> > > 'video_code' not described in 'drm_display_mode_from_cea_vic'
> > > 	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter
> > > 'vic' description in 'drm_display_mode_from_cea_vic'
> > > 
> > > Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > ---
> > >  drivers/gpu/drm/drm_edid.c | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > > 
> > > diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
> > > index a82f37d44258..631125b46e04 100644
> > > --- a/drivers/gpu/drm/drm_edid.c
> > > +++ b/drivers/gpu/drm/drm_edid.c
> > > @@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector
> > > *connector, u8
> > > svd)
> > >  /**
> > >   * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
> > >   * @dev: DRM device
> > > - * @vic: CEA VIC of the mode
> > > + * @video_code: CEA VIC of the mode
> > >   *
> > >   * Creates a new mode matching the specified CEA VIC.
> > >   *  
> 
> 
> Thanks,
> Mauro
> 
-- 
Cheers,
	Lyude Paul (she/her)
	Software Engineer at Red Hat

[PATCH v2 13/24] docs: i2c: index.rst: add slave-testunit-backend.rst

[Mauro Carvalho Chehab]

As warned by Sphinx:

	.../Documentation/i2c/slave-testunit-backend.rst: WARNING: document isn't included in any toctree

This document is not included anywhere.

Fixes: a8335c64c5f0 ("i2c: add slave testunit driver")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/hw-vuln/l1d_flush.rst | 3 +--
 Documentation/i2c/index.rst                     | 1 +
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/hw-vuln/l1d_flush.rst b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
index adc4ecc72361..f794e2b1096c 100644
--- a/Documentation/admin-guide/hw-vuln/l1d_flush.rst
+++ b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
@@ -22,8 +22,7 @@ mechanism
 Usage Guidelines
 ----------------
 
-Please see document: :ref:`Documentation/userspace-api/spec_ctrl.rst` for
-details.
+Please see document: :doc:`/userspace-api/spec_ctrl` for details.
 
 **NOTE**: The feature is disabled by default, applications need to
 specifically opt into the feature to enable it.
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index 8b76217e370a..c8bf6f7d5286 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -38,6 +38,7 @@ Debugging
 
    gpio-fault-injection
    i2c-stub
+   slave-testunit-backend
 
 Slave I2C
 =========
-- 
2.26.2

Re: [PATCH v2 13/24] docs: i2c: index.rst: add slave-testunit-backend.rst

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 344 bytes --]


> Fixes: a8335c64c5f0 ("i2c: add slave testunit driver")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

As discussed with v1, I already fixed it (correctly). Patch is in
linux-next:

https://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux.git/commit/?h=i2c/for-next&id=40daf09a30a0c86a038bcce606604333f32e03f8

Thanks!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 14/24] docs: conf.py: disable automarkup for Sphinx 3.x

[Mauro Carvalho Chehab]

The class types changed after the C domain rewrite on
Sphinx 3.x. Due to that, the automarkup extension is just
generating additional noise when trying to convert structs
and other markups into cross references.

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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 376dd0ddf39c..4f5d15abd047 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,7 @@ needs_sphinx = '1.3'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
-              'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
+              'kfigure', 'sphinx.ext.ifconfig',
               'maintainers_include', 'sphinx.ext.autosectionlabel' ]
 
 #
@@ -111,6 +111,7 @@ if major >= 3:
 
 else:
     extensions.append('cdomain')
+    extensions.append('automarkup')
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
-- 
2.26.2

[PATCH v2 15/24] docs: net: statistics.rst: remove a duplicated kernel-doc

[Mauro Carvalho Chehab]

include/linux/ethtool.h is included twice with kernel-doc,
both to document ethtool_pause_stats(). The first one is
at statistics.rst, and the second one at ethtool-netlink.rst.

Replace one of the references to use the name of the
function. The automarkup.py extension should create the
cross-references.

Solves this warning:

	../Documentation/networking/ethtool-netlink.rst: WARNING: Duplicate C declaration, also defined in 'networking/statistics'.
	Declaration is 'ethtool_pause_stats'.

Acked-by: David S. Miller <davem@davemloft.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/networking/statistics.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst
index 8e15bc98830b..234abedc29b2 100644
--- a/Documentation/networking/statistics.rst
+++ b/Documentation/networking/statistics.rst
@@ -175,5 +175,4 @@ The following structures are internal to the kernel, their members are
 translated to netlink attributes when dumped. Drivers must not overwrite
 the statistics they don't report with 0.
 
-.. kernel-doc:: include/linux/ethtool.h
-    :identifiers: ethtool_pause_stats
+- ethtool_pause_stats()
-- 
2.26.2

[PATCH v2 16/24] seqlock: fix two kernel-doc warnings

[Mauro Carvalho Chehab]

Right now, seqloc.h produces two kernel-doc warnings:

	./include/linux/seqlock.h:181: error: Cannot parse typedef!
	WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno ./include/linux/seqlock.h' failed with return code 1

Those are due to two things:

1. the kernel-doc markup syntax doesn't recognize "typedef"
   expression at the markup. Both functions and typedefs
   use the same notation:

	/**
	 * foo - some bar description
	 */
  or
	/**
	 * foo() - some bar description
	 */

2. kernel-doc markups require a function or typedef prototype,
   in order to get the type of each argument. This is also
   common for other code documentation markkup languages, like
   doxygen.

On other words, a valid notation for describing those macros
would be:

	 /**
	  * seqcount_LOCKNAME_t() - sequence counter with LOCKNAME associated
	  * @seqcount:  The real sequence counter
	  * @lock:      Pointer to the associated lock
	  *
	  * <some description>
	  */
	#if 0 /* kernel-doc needs a function or typedef prototype */
	void seqcount_LOCKNAME_t(seqcount_##lockname##_t *seqcount, locktype *lock) {}
	#endif

Alternatively, the description of those arguments should be added
as a DOC: block.

Yet, from changeset a28e884b966e ("seqlock: Fix multiple kernel-doc warnings"),
it sounds that, on this file, it is preferred to just convert the
kernel-doc markups into simple comments.

Fixes: a8772dccb2ec ("seqlock: Fold seqcount_LOCKNAME_t definition")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/seqlock.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/seqlock.h b/include/linux/seqlock.h
index ac5b07f558b0..cbfc78b92b65 100644
--- a/include/linux/seqlock.h
+++ b/include/linux/seqlock.h
@@ -154,7 +154,7 @@ static inline void seqcount_lockdep_reader_access(const seqcount_t *s)
 #define __SEQ_LOCK(expr)
 #endif
 
-/**
+/*
  * typedef seqcount_LOCKNAME_t - sequence counter with LOCKNAME associated
  * @seqcount:	The real sequence counter
  * @lock:	Pointer to the associated lock
-- 
2.26.2

[PATCH v2 17/24] docs: hwmon: mp2975.rst: address some html build warnings

[Mauro Carvalho Chehab]

    .../Documentation/hwmon/mp2975.rst:25: WARNING: Unexpected indentation.
    .../Documentation/hwmon/mp2975.rst:27: WARNING: Block quote ends without a blank line; unexpected unindent.
    .../Documentation/hwmon/mp2975.rst:69: WARNING: Unexpected indentation.
    .../Documentation/hwmon/mp2975.rst:70: WARNING: Block quote ends without a blank line; unexpected unindent.
    .../Documentation/hwmon/mp2975.rst:72: WARNING: Bullet list ends without a blank line; unexpected unindent.
    .../Documentation/hwmon/mp2975.rst: WARNING: document isn't included in any toctree

List blocks should have blank lines before and after them,
in order to be properly parsed.

Fixes: 4beb7a028e9f ("hwmon: (pmbus) Add support for MPS Multi-phase mp2975 controller")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/hwmon/index.rst  |  1 +
 Documentation/hwmon/mp2975.rst | 14 +++++++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index e6b91ab12978..b797db738225 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -132,6 +132,7 @@ Hardware Monitoring Kernel Drivers
    mcp3021
    menf21bmc
    mlxreg-fan
+   mp2975
    nct6683
    nct6775
    nct7802
diff --git a/Documentation/hwmon/mp2975.rst b/Documentation/hwmon/mp2975.rst
index 5b0609c62f48..81d816b71490 100644
--- a/Documentation/hwmon/mp2975.rst
+++ b/Documentation/hwmon/mp2975.rst
@@ -20,6 +20,7 @@ This driver implements support for Monolithic Power Systems, Inc. (MPS)
 vendor dual-loop, digital, multi-phase controller MP2975.
 
 This device:
+
 - Supports up to two power rail.
 - Provides 8 pulse-width modulations (PWMs), and can be configured up
   to 8-phase operation for rail 1 and up to 4-phase operation for rail
@@ -32,10 +33,12 @@ This device:
   10-mV DAC, IMVP9 mode with 5-mV DAC.
 
 Device supports:
+
 - SVID interface.
 - AVSBus interface.
 
 Device complaint with:
+
 - PMBus rev 1.3 interface.
 
 Device supports direct format for reading output current, output voltage,
@@ -45,11 +48,14 @@ Device supports VID and direct formats for reading output voltage.
 The below VID modes are supported: VR12, VR13, IMVP9.
 
 The driver provides the next attributes for the current:
+
 - for current in: input, maximum alarm;
 - for current out input, maximum alarm and highest values;
 - for phase current: input and label.
-attributes.
+  attributes.
+
 The driver exports the following attributes via the 'sysfs' files, where
+
 - 'n' is number of telemetry pages (from 1 to 2);
 - 'k' is number of configured phases (from 1 to 8);
 - indexes 1, 1*n for "iin";
@@ -65,11 +71,14 @@ The driver exports the following attributes via the 'sysfs' files, where
 **curr[1-{2n+k}]_label**
 
 The driver provides the next attributes for the voltage:
+
 - for voltage in: input, high critical threshold, high critical alarm, all only
   from page 0;
 - for voltage out: input, low and high critical thresholds, low and high
   critical alarms, from pages 0 and 1;
+
 The driver exports the following attributes via the 'sysfs' files, where
+
 - 'n' is number of telemetry pages (from 1 to 2);
 - indexes 1 for "iin";
 - indexes n+1, n+2 for "vout";
@@ -87,9 +96,12 @@ The driver exports the following attributes via the 'sysfs' files, where
 **in[2-{n+1}1_lcrit_alarm**
 
 The driver provides the next attributes for the power:
+
 - for power in alarm and input.
 - for power out: highest and input.
+
 The driver exports the following attributes via the 'sysfs' files, where
+
 - 'n' is number of telemetry pages (from 1 to 2);
 - indexes 1 for "pin";
 - indexes n+1, n+2 for "pout";
-- 
2.26.2

Re: [PATCH v2 17/24] docs: hwmon: mp2975.rst: address some html build warnings

[Guenter Roeck]

On Tue, Oct 13, 2020 at 02:14:44PM +0200, Mauro Carvalho Chehab wrote:
>     .../Documentation/hwmon/mp2975.rst:25: WARNING: Unexpected indentation.
>     .../Documentation/hwmon/mp2975.rst:27: WARNING: Block quote ends without a blank line; unexpected unindent.
>     .../Documentation/hwmon/mp2975.rst:69: WARNING: Unexpected indentation.
>     .../Documentation/hwmon/mp2975.rst:70: WARNING: Block quote ends without a blank line; unexpected unindent.
>     .../Documentation/hwmon/mp2975.rst:72: WARNING: Bullet list ends without a blank line; unexpected unindent.
>     .../Documentation/hwmon/mp2975.rst: WARNING: document isn't included in any toctree
> 
> List blocks should have blank lines before and after them,
> in order to be properly parsed.
> 
> Fixes: 4beb7a028e9f ("hwmon: (pmbus) Add support for MPS Multi-phase mp2975 controller")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Guenter Roeck <linux@roeck-us.net>

> ---
>  Documentation/hwmon/index.rst  |  1 +
>  Documentation/hwmon/mp2975.rst | 14 +++++++++++++-
>  2 files changed, 14 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
> index e6b91ab12978..b797db738225 100644
> --- a/Documentation/hwmon/index.rst
> +++ b/Documentation/hwmon/index.rst
> @@ -132,6 +132,7 @@ Hardware Monitoring Kernel Drivers
>     mcp3021
>     menf21bmc
>     mlxreg-fan
> +   mp2975
>     nct6683
>     nct6775
>     nct7802
> diff --git a/Documentation/hwmon/mp2975.rst b/Documentation/hwmon/mp2975.rst
> index 5b0609c62f48..81d816b71490 100644
> --- a/Documentation/hwmon/mp2975.rst
> +++ b/Documentation/hwmon/mp2975.rst
> @@ -20,6 +20,7 @@ This driver implements support for Monolithic Power Systems, Inc. (MPS)
>  vendor dual-loop, digital, multi-phase controller MP2975.
>  
>  This device:
> +
>  - Supports up to two power rail.
>  - Provides 8 pulse-width modulations (PWMs), and can be configured up
>    to 8-phase operation for rail 1 and up to 4-phase operation for rail
> @@ -32,10 +33,12 @@ This device:
>    10-mV DAC, IMVP9 mode with 5-mV DAC.
>  
>  Device supports:
> +
>  - SVID interface.
>  - AVSBus interface.
>  
>  Device complaint with:
> +
>  - PMBus rev 1.3 interface.
>  
>  Device supports direct format for reading output current, output voltage,
> @@ -45,11 +48,14 @@ Device supports VID and direct formats for reading output voltage.
>  The below VID modes are supported: VR12, VR13, IMVP9.
>  
>  The driver provides the next attributes for the current:
> +
>  - for current in: input, maximum alarm;
>  - for current out input, maximum alarm and highest values;
>  - for phase current: input and label.
> -attributes.
> +  attributes.
> +
>  The driver exports the following attributes via the 'sysfs' files, where
> +
>  - 'n' is number of telemetry pages (from 1 to 2);
>  - 'k' is number of configured phases (from 1 to 8);
>  - indexes 1, 1*n for "iin";
> @@ -65,11 +71,14 @@ The driver exports the following attributes via the 'sysfs' files, where
>  **curr[1-{2n+k}]_label**
>  
>  The driver provides the next attributes for the voltage:
> +
>  - for voltage in: input, high critical threshold, high critical alarm, all only
>    from page 0;
>  - for voltage out: input, low and high critical thresholds, low and high
>    critical alarms, from pages 0 and 1;
> +
>  The driver exports the following attributes via the 'sysfs' files, where
> +
>  - 'n' is number of telemetry pages (from 1 to 2);
>  - indexes 1 for "iin";
>  - indexes n+1, n+2 for "vout";
> @@ -87,9 +96,12 @@ The driver exports the following attributes via the 'sysfs' files, where
>  **in[2-{n+1}1_lcrit_alarm**
>  
>  The driver provides the next attributes for the power:
> +
>  - for power in alarm and input.
>  - for power out: highest and input.
> +
>  The driver exports the following attributes via the 'sysfs' files, where
> +
>  - 'n' is number of telemetry pages (from 1 to 2);
>  - indexes 1 for "pin";
>  - indexes n+1, n+2 for "pout";
> -- 
> 2.26.2
> 

[PATCH v2 18/24] docs: userspace-api: add iommu.rst to the index file

[Mauro Carvalho Chehab]

There's a new uAPI doc for IOMMU. Add it to the index file.
Should address this warning:

	.../Documentation/userspace-api/iommu.rst: WARNING: document isn't included in any toctree

Fixes: d0023e3ee28d ("docs: IOMMU user API")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/userspace-api/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 69fc5167e648..acd2cc2a538d 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -22,6 +22,7 @@ place where this information is gathered.
    spec_ctrl
    accelerators/ocxl
    ioctl/index
+   iommu
    media/index
 
 .. only::  subproject and html
-- 
2.26.2

[PATCH v2 19/24] net: phy: remove kernel-doc duplication

[Mauro Carvalho Chehab]

Sphinx 3 now checks for duplicated function declarations:

	.../Documentation/networking/kapi:143: ../include/linux/phy.h:163: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
	Declaration is 'unsigned int phy_supported_speeds (struct phy_device *phy, unsigned int *speeds, unsigned int size)'.
	.../Documentation/networking/kapi:143: ../include/linux/phy.h:1034: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
	Declaration is 'int phy_read_mmd (struct phy_device *phydev, int devad, u32 regnum)'.
	.../Documentation/networking/kapi:143: ../include/linux/phy.h:1076: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
	Declaration is 'int __phy_read_mmd (struct phy_device *phydev, int devad, u32 regnum)'.
	.../Documentation/networking/kapi:143: ../include/linux/phy.h:1088: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
	Declaration is 'int phy_write_mmd (struct phy_device *phydev, int devad, u32 regnum, u16 val)'.
	.../Documentation/networking/kapi:143: ../include/linux/phy.h:1100: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
	Declaration is 'int __phy_write_mmd (struct phy_device *phydev, int devad, u32 regnum, u16 val)'.

It turns that both the C and the H files have the same
kernel-doc markup for the same functions. Let's drop the
at the header file, keeping the one closer to the code.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/phy.h | 40 +++++-----------------------------------
 1 file changed, 5 insertions(+), 35 deletions(-)

diff --git a/include/linux/phy.h b/include/linux/phy.h
index eb3cb1a98b45..56563e5e0dc7 100644
--- a/include/linux/phy.h
+++ b/include/linux/phy.h
@@ -147,16 +147,8 @@ typedef enum {
 	PHY_INTERFACE_MODE_MAX,
 } phy_interface_t;
 
-/**
+/*
  * phy_supported_speeds - return all speeds currently supported by a PHY device
- * @phy: The PHY device to return supported speeds of.
- * @speeds: buffer to store supported speeds in.
- * @size: size of speeds buffer.
- *
- * Description: Returns the number of supported speeds, and fills
- * the speeds buffer with the supported speeds. If speeds buffer is
- * too small to contain all currently supported speeds, will return as
- * many speeds as can fit.
  */
 unsigned int phy_supported_speeds(struct phy_device *phy,
 				      unsigned int *speeds,
@@ -1022,14 +1014,9 @@ static inline int __phy_modify_changed(struct phy_device *phydev, u32 regnum,
 					regnum, mask, set);
 }
 
-/**
+/*
  * phy_read_mmd - Convenience function for reading a register
  * from an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to read from
- * @regnum: The register on the MMD to read
- *
- * Same rules as for phy_read();
  */
 int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
 
@@ -1064,38 +1051,21 @@ int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
 	__ret; \
 })
 
-/**
+/*
  * __phy_read_mmd - Convenience function for reading a register
  * from an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to read from
- * @regnum: The register on the MMD to read
- *
- * Same rules as for __phy_read();
  */
 int __phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
 
-/**
+/*
  * phy_write_mmd - Convenience function for writing a register
  * on an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to write to
- * @regnum: The register on the MMD to read
- * @val: value to write to @regnum
- *
- * Same rules as for phy_write();
  */
 int phy_write_mmd(struct phy_device *phydev, int devad, u32 regnum, u16 val);
 
-/**
+/*
  * __phy_write_mmd - Convenience function for writing a register
  * on an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to write to
- * @regnum: The register on the MMD to read
- * @val: value to write to @regnum
- *
- * Same rules as for __phy_write();
  */
 int __phy_write_mmd(struct phy_device *phydev, int devad, u32 regnum, u16 val);
 
-- 
2.26.2

[PATCH v2 20/24] MAINTAINERS: fix broken doc refs due to yaml conversion

[Mauro Carvalho Chehab]

Several *.txt files got converted to yaml. Update their
references at MAINTAINERS file accordingly.

Acked-by: Stephen Boyd <sboyd@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/devicetree/bindings/clock/hi6220-clock.txt | 2 +-
 MAINTAINERS                                              | 9 ++++-----
 .../devicetree/bindings/net/wireless/silabs,wfx.yaml     | 2 +-
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/clock/hi6220-clock.txt b/Documentation/devicetree/bindings/clock/hi6220-clock.txt
index ef3deb7b86ea..17ac4a3dd26a 100644
--- a/Documentation/devicetree/bindings/clock/hi6220-clock.txt
+++ b/Documentation/devicetree/bindings/clock/hi6220-clock.txt
@@ -4,7 +4,7 @@ Clock control registers reside in different Hi6220 system controllers,
 please refer the following document to know more about the binding rules
 for these system controllers:
 
-Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt
+Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml
 
 Required Properties:
 
diff --git a/MAINTAINERS b/MAINTAINERS
index f1eeef654caa..891b735233d3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -978,7 +978,7 @@ M:	Michael Hennerich <Michael.Hennerich@analog.com>
 L:	linux-iio@vger.kernel.org
 S:	Supported
 W:	http://ez.analog.com/community/linux-device-drivers
-F:	Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.txt
+F:	Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml
 F:	drivers/iio/adc/ad7768-1.c
 
 ANALOG DEVICES INC AD7780 DRIVER
@@ -3867,7 +3867,7 @@ M:	Roger Quadros <rogerq@ti.com>
 L:	linux-usb@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/peter.chen/usb.git
-F:	Documentation/devicetree/bindings/usb/cdns-usb3.txt
+F:	Documentation/devicetree/bindings/usb/cdns,usb3.yaml
 F:	drivers/usb/cdns3/
 
 CADET FM/AM RADIO RECEIVER DRIVER
@@ -7919,7 +7919,7 @@ HISILICON LPC BUS DRIVER
 M:	john.garry@huawei.com
 S:	Maintained
 W:	http://www.hisilicon.com
-F:	Documentation/devicetree/bindings/arm/hisilicon/hisilicon-low-pin-count.txt
+F:	Documentation/devicetree/bindings/arm/hisilicon/low-pin-count.yaml
 F:	drivers/bus/hisi_lpc.c
 
 HISILICON NETWORK SUBSYSTEM 3 DRIVER (HNS3)
@@ -14910,7 +14910,6 @@ RENESAS ETHERNET DRIVERS
 R:	Sergei Shtylyov <sergei.shtylyov@gmail.com>
 L:	netdev@vger.kernel.org
 L:	linux-renesas-soc@vger.kernel.org
-F:	Documentation/devicetree/bindings/net/renesas,*.txt
 F:	Documentation/devicetree/bindings/net/renesas,*.yaml
 F:	drivers/net/ethernet/renesas/
 F:	include/linux/sh_eth.h
@@ -18114,7 +18113,7 @@ M:	Yu Chen <chenyu56@huawei.com>
 M:	Binghui Wang <wangbinghui@hisilicon.com>
 L:	linux-usb@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/bindings/phy/phy-hi3660-usb3.txt
+F:	Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml
 F:	drivers/phy/hisilicon/phy-hi3660-usb3.c
 
 USB ISP116X DRIVER
diff --git a/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml b/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml
index 43b5630c0407..510edd12ed19 100644
--- a/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml
+++ b/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml
@@ -24,7 +24,7 @@ description:
     In addition, it is recommended to declare a mmc-pwrseq on SDIO host above
     WFx. Without it, you may encounter issues with warm boot. The mmc-pwrseq
     should be compatible with mmc-pwrseq-simple. Please consult
-    Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt for more
+    Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml for more
     information.
 
   For SPI':'
-- 
2.26.2

[PATCH v2 21/24] crypto: sun8x-ce*: update entries to its documentation

[Mauro Carvalho Chehab]

The README file was converted to ReST format. Update the
references for it accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/crypto/allwinner/sun8i-ce/sun8i-ce-hash.c | 2 +-
 drivers/crypto/allwinner/sun8i-ce/sun8i-ce-prng.c | 2 +-
 drivers/crypto/allwinner/sun8i-ce/sun8i-ce-trng.c | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-hash.c b/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-hash.c
index fa2f1b4fad7b..a94bf28f858a 100644
--- a/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-hash.c
+++ b/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-hash.c
@@ -7,7 +7,7 @@
  *
  * This file add support for MD5 and SHA1/SHA224/SHA256/SHA384/SHA512.
  *
- * You could find the datasheet in Documentation/arm/sunxi/README
+ * You could find the datasheet in Documentation/arm/sunxi.rst
  */
 #include <linux/dma-mapping.h>
 #include <linux/pm_runtime.h>
diff --git a/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-prng.c b/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-prng.c
index 78503006949c..cfde9ee4356b 100644
--- a/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-prng.c
+++ b/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-prng.c
@@ -7,7 +7,7 @@
  *
  * This file handle the PRNG
  *
- * You could find a link for the datasheet in Documentation/arm/sunxi/README
+ * You could find a link for the datasheet in Documentation/arm/sunxi.rst
  */
 #include "sun8i-ce.h"
 #include <linux/dma-mapping.h>
diff --git a/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-trng.c b/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-trng.c
index 654328160d19..5b7af4498bd5 100644
--- a/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-trng.c
+++ b/drivers/crypto/allwinner/sun8i-ce/sun8i-ce-trng.c
@@ -7,7 +7,7 @@
  *
  * This file handle the TRNG
  *
- * You could find a link for the datasheet in Documentation/arm/sunxi/README
+ * You could find a link for the datasheet in Documentation/arm/sunxi.rst
  */
 #include "sun8i-ce.h"
 #include <linux/dma-mapping.h>
-- 
2.26.2

[PATCH v2 22/24] ice: docs fix a devlink info that broke a table

[Mauro Carvalho Chehab]

Changeset 410d06879c01 ("ice: add the DDP Track ID to devlink info")
added description for a new devlink field, but forgot to add
one of its columns, causing it to break:

	.../Documentation/networking/devlink/ice.rst:15: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 11 does not contain the same number of items as row 1 (3 vs 4).

	.. list-table:: devlink info versions implemented
	    :widths: 5 5 5 90
...
	    * - ``fw.app.bundle_id``
	      - 0xc0000001
	      - Unique identifier for the DDP package loaded in the device. Also
	        referred to as the DDP Track ID. Can be used to uniquely identify
	        the specific DDP package.

Add the type field to the ``fw.app.bundle_id`` row.

Fixes: 410d06879c01 ("ice: add the DDP Track ID to devlink info")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/networking/devlink/ice.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst
index b165181d5d4d..a432dc419fa4 100644
--- a/Documentation/networking/devlink/ice.rst
+++ b/Documentation/networking/devlink/ice.rst
@@ -70,6 +70,7 @@ The ``ice`` driver reports the following versions
         that both the name (as reported by ``fw.app.name``) and version are
         required to uniquely identify the package.
     * - ``fw.app.bundle_id``
+      - running
       - 0xc0000001
       - Unique identifier for the DDP package loaded in the device. Also
         referred to as the DDP Track ID. Can be used to uniquely identify
-- 
2.26.2

Re: [PATCH v2 22/24] ice: docs fix a devlink info that broke a table

[Jacob Keller]

On 10/13/2020 5:14 AM, Mauro Carvalho Chehab wrote:
> Changeset 410d06879c01 ("ice: add the DDP Track ID to devlink info")
> added description for a new devlink field, but forgot to add
> one of its columns, causing it to break:
> 
> 	.../Documentation/networking/devlink/ice.rst:15: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 11 does not contain the same number of items as row 1 (3 vs 4).
> 
> 	.. list-table:: devlink info versions implemented
> 	    :widths: 5 5 5 90
> ...
> 	    * - ``fw.app.bundle_id``
> 	      - 0xc0000001
> 	      - Unique identifier for the DDP package loaded in the device. Also
> 	        referred to as the DDP Track ID. Can be used to uniquely identify
> 	        the specific DDP package.
> 
> Add the type field to the ``fw.app.bundle_id`` row.
> 
> Fixes: 410d06879c01 ("ice: add the DDP Track ID to devlink info")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Yep, looks correct. Thanks for the fix!

Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>

> ---
>  Documentation/networking/devlink/ice.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst
> index b165181d5d4d..a432dc419fa4 100644
> --- a/Documentation/networking/devlink/ice.rst
> +++ b/Documentation/networking/devlink/ice.rst
> @@ -70,6 +70,7 @@ The ``ice`` driver reports the following versions
>          that both the name (as reported by ``fw.app.name``) and version are
>          required to uniquely identify the package.
>      * - ``fw.app.bundle_id``
> +      - running
>        - 0xc0000001
>        - Unique identifier for the DDP package loaded in the device. Also
>          referred to as the DDP Track ID. Can be used to uniquely identify
> 

[PATCH v2 23/24] RDMA: add a missing kernel-doc parameter markup

[Mauro Carvalho Chehab]

Changeset 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
added a new parameter to ib_register_device().

Document it.

Fixes: 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/infiniband/core/device.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/infiniband/core/device.c b/drivers/infiniband/core/device.c
index feaec8d2f0ca..a3b1fc84cdca 100644
--- a/drivers/infiniband/core/device.c
+++ b/drivers/infiniband/core/device.c
@@ -1318,7 +1318,10 @@ static void prevent_dealloc_device(struct ib_device *ib_dev)
  * ib_register_device - Register an IB device with IB core
  * @device: Device to register
  * @name: unique string device name. This may include a '%' which will
- * cause a unique index to be added to the passed device name.
+ * 	  cause a unique index to be added to the passed device name.
+ * @dma_device: pointer to a DMA-capable device. If %NULL, then the IB
+ *	        device will be used. In this case the caller should fully
+ *		setup the ibdev for DMA. This usually means using dma_virt_ops.
  *
  * Low-level drivers use ib_register_device() to register their
  * devices with the IB core.  All registered clients will receive a
-- 
2.26.2

Re: [PATCH v2 23/24] RDMA: add a missing kernel-doc parameter markup

[Jason Gunthorpe]

On Tue, Oct 13, 2020 at 02:14:50PM +0200, Mauro Carvalho Chehab wrote:
> Changeset 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
> added a new parameter to ib_register_device().
> 
> Document it.
> 
> Fixes: 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/infiniband/core/device.c | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)

This is in linux-next, not Linus's tree.

I've fixed it up in the rdma tree

Thanks,
Jason

[PATCH v2 24/24] counters: docs: add a missing include

[Mauro Carvalho Chehab]

Changeset 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")

Is causing two new warnings:

	.../Documentation/core-api/counters.rst:8: WARNING: Undefined substitution referenced: "copy".
	.../Documentation/core-api/counters.rst:9: WARNING: Undefined substitution referenced: "copy".

Because it forgot to include isonum.txt, which defines |copy|
macro.

While here, also add it to core-api index file, in order to
solve this warning:

	.../Documentation/core-api/counters.rst: WARNING: document isn't included in any toctree

Fixes: 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/core-api/counters.rst | 1 +
 Documentation/core-api/index.rst    | 1 +
 2 files changed, 2 insertions(+)

diff --git a/Documentation/core-api/counters.rst b/Documentation/core-api/counters.rst
index 642d907f4d3a..2821aebf3f45 100644
--- a/Documentation/core-api/counters.rst
+++ b/Documentation/core-api/counters.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
 
 ======================
 Simple atomic counters
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 69171b1799f2..cf9cd44c1191 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -43,6 +43,7 @@ Library functionality that is used throughout the kernel.
    this_cpu_ops
    timekeeping
    errseq
+   counters
 
 Concurrency primitives
 ======================
-- 
2.26.2

Re: [PATCH v2 24/24] counters: docs: add a missing include

[Shuah Khan]

On 10/13/20 6:14 AM, Mauro Carvalho Chehab wrote:
> Changeset 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
> 
> Is causing two new warnings:
> 
> 	.../Documentation/core-api/counters.rst:8: WARNING: Undefined substitution referenced: "copy".
> 	.../Documentation/core-api/counters.rst:9: WARNING: Undefined substitution referenced: "copy".
> 
> Because it forgot to include isonum.txt, which defines |copy|
> macro.
> 
> While here, also add it to core-api index file, in order to
> solve this warning:
> 
> 	.../Documentation/core-api/counters.rst: WARNING: document isn't included in any toctree
> 
> Fixes: 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   Documentation/core-api/counters.rst | 1 +
>   Documentation/core-api/index.rst    | 1 +
>   2 files changed, 2 insertions(+)
> 
> diff --git a/Documentation/core-api/counters.rst b/Documentation/core-api/counters.rst
> index 642d907f4d3a..2821aebf3f45 100644
> --- a/Documentation/core-api/counters.rst
> +++ b/Documentation/core-api/counters.rst
> @@ -1,4 +1,5 @@
>   .. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
>   
>   ======================
>   Simple atomic counters
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index 69171b1799f2..cf9cd44c1191 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -43,6 +43,7 @@ Library functionality that is used throughout the kernel.
>      this_cpu_ops
>      timekeeping
>      errseq
> +   counters
>   
>   Concurrency primitives
>   ======================
> 

Thank you for the patch. I will add this to my patch series.

thanks,
-- Shuah