[PATCH 1/6] docs: trace: fix a broken label

[PATCH 1/6] docs: trace: fix a broken label

[Mauro Carvalho Chehab]

Sphinx warnings about his:

	Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)

The problem is quite simple: Sphinx wants a blank line after
references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/trace/kprobetrace.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index b729b40a5ba5..3d162d432a3c 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
 For $comm, the default type is "string"; any other type is invalid.
 
 .. _user_mem_access:
+
 User Memory Access
 ------------------
 Kprobe events supports user-space memory access. For that purpose, you can use
-- 
2.21.0

[PATCH 2/6] docs: trace: add a missing blank line

[Mauro Carvalho Chehab]

Sphinx expects a blank line after a literal block markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/trace/kprobetrace.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index 3d162d432a3c..caa0a8ba081e 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -228,6 +228,7 @@ events, you need to enable it.
 
 Use the following command to start tracing in an interval.
 ::
+
     # echo 1 > tracing_on
     Open something...
     # echo 0 > tracing_on
-- 
2.21.0

[PATCH 3/6] lib: list_sort.c: add a blank line to avoid kernel-doc warnings

[Mauro Carvalho Chehab]

In order for a list to be recognized as such, blank lines
are required.

Solve those Sphinx warnings:

./lib/list_sort.c:162: WARNING: Unexpected indentation.
./lib/list_sort.c:163: WARNING: Block quote ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 lib/list_sort.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/list_sort.c b/lib/list_sort.c
index 712ed1f4eb64..52f0c258c895 100644
--- a/lib/list_sort.c
+++ b/lib/list_sort.c
@@ -157,9 +157,11 @@ static void merge_final(void *priv, cmp_func cmp, struct list_head *head,
  *
  * The number of pending lists of size 2^k is determined by the
  * state of bit k of "count" plus two extra pieces of information:
+ *
  * - The state of bit k-1 (when k == 0, consider bit -1 always set), and
  * - Whether the higher-order bits are zero or non-zero (i.e.
  *   is count >= 2^(k+1)).
+ *
  * There are six states we distinguish.  "x" represents some arbitrary
  * bits, and "y" represents some arbitrary non-zero bits:
  * 0:  00x: 0 pending of size 2^k;           x pending of sizes < 2^k
-- 
2.21.0

[PATCH 4/6] time: hrtimer: use a bullet for the returns bullet list

[Mauro Carvalho Chehab]

That gets rid of this warning:

	./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.

and displays nicely both at the source code and at the produced
documentation.

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

diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
index edb230aba3d1..49f78453892f 100644
--- a/kernel/time/hrtimer.c
+++ b/kernel/time/hrtimer.c
@@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
  * @timer:	hrtimer to stop
  *
  * Returns:
- *  0 when the timer was not active
- *  1 when the timer was active
- * -1 when the timer is currently executing the callback function and
+ *
+ *  •  0 when the timer was not active
+ *  •  1 when the timer was active
+ *  • -1 when the timer is currently executing the callback function and
  *    cannot be stopped
  */
 int hrtimer_try_to_cancel(struct hrtimer *timer)
-- 
2.21.0

[PATCH 5/6] docs: signal: fix a kernel-doc markup

[Mauro Carvalho Chehab]

The kernel-doc parser doesn't handle expressions with %foo*.
Instead, when an asterisk should be part of a constant, it
uses an alternative notation: `foo*`.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 kernel/signal.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/kernel/signal.c b/kernel/signal.c
index 91b789dd6e72..10a826855b59 100644
--- a/kernel/signal.c
+++ b/kernel/signal.c
@@ -349,7 +349,7 @@ void task_clear_jobctl_pending(struct task_struct *task, unsigned long mask)
  * @task has %JOBCTL_STOP_PENDING set and is participating in a group stop.
  * Group stop states are cleared and the group stop count is consumed if
  * %JOBCTL_STOP_CONSUME was set.  If the consumption completes the group
- * stop, the appropriate %SIGNAL_* flags are set.
+ * stop, the appropriate `SIGNAL_*` flags are set.
  *
  * CONTEXT:
  * Must be called with @task->sighand->siglock held.
-- 
2.21.0

[PATCH 6/6] drivers: base/node.c: fixes a kernel-doc markups

[Mauro Carvalho Chehab]

There was a typo at the name of the vars inside the kernel-doc
comment, causing those warnings:

	./drivers/base/node.c:690: warning: Function parameter or member 'mem_nid' not described in 'register_memory_node_under_compute_node'
	./drivers/base/node.c:690: warning: Function parameter or member 'cpu_nid' not described in 'register_memory_node_under_compute_node'
	./drivers/base/node.c:690: warning: Excess function parameter 'mem_node' description in 'register_memory_node_under_compute_node'
	./drivers/base/node.c:690: warning: Excess function parameter 'cpu_node' description in 'register_memory_node_under_compute_node'

There's also a description missing here:
	./drivers/base/node.c:78: warning: Function parameter or member 'hmem_attrs' not described in 'node_access_nodes'

Copy an existing description from another function call.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 drivers/base/node.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/base/node.c b/drivers/base/node.c
index 9be88fd05147..4ee32db9d61d 100644
--- a/drivers/base/node.c
+++ b/drivers/base/node.c
@@ -673,8 +673,8 @@ int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 /**
  * register_memory_node_under_compute_node - link memory node to its compute
  *					     node for a given access class.
- * @mem_node:	Memory node number
- * @cpu_node:	Cpu  node number
+ * @mem_nid:	Memory node number
+ * @cpu_nid:	Cpu  node number
  * @access:	Access class to register
  *
  * Description:
-- 
2.21.0

[PATCH v2 6/6] drivers: base/node.c: fixes a kernel-doc markups

[Mauro Carvalho Chehab]

There was a typo at the name of the vars inside the kernel-doc
comment, causing those warnings:

	./drivers/base/node.c:690: warning: Function parameter or member 'mem_nid' not described in 'register_memory_node_under_compute_node'
	./drivers/base/node.c:690: warning: Function parameter or member 'cpu_nid' not described in 'register_memory_node_under_compute_node'
	./drivers/base/node.c:690: warning: Excess function parameter 'mem_node' description in 'register_memory_node_under_compute_node'
	./drivers/base/node.c:690: warning: Excess function parameter 'cpu_node' description in 'register_memory_node_under_compute_node'

There's also a description missing here:
	./drivers/base/node.c:78: warning: Function parameter or member 'hmem_attrs' not described in 'node_access_nodes'

Copy an existing description from another function call.

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

v2: Add a missing hunk solving the warning reported as line #78.

 drivers/base/node.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/drivers/base/node.c b/drivers/base/node.c
index 9be88fd05147..beec80649b33 100644
--- a/drivers/base/node.c
+++ b/drivers/base/node.c
@@ -66,6 +66,7 @@ static DEVICE_ATTR(cpulist, S_IRUGO, node_read_cpulist, NULL);
  * @dev:	Device for this memory access class
  * @list_node:	List element in the node's access list
  * @access:	The access class rank
+ * @hmem_attrs: Heterogeneous memory performance attributes
  */
 struct node_access_nodes {
 	struct device		dev;
@@ -673,8 +674,8 @@ int register_cpu_under_node(unsigned int cpu, unsigned int nid)
 /**
  * register_memory_node_under_compute_node - link memory node to its compute
  *					     node for a given access class.
- * @mem_node:	Memory node number
- * @cpu_node:	Cpu  node number
+ * @mem_nid:	Memory node number
+ * @cpu_nid:	Cpu  node number
  * @access:	Access class to register
  *
  * Description:
-- 
2.21.0

Re: [PATCH 2/6] docs: trace: add a missing blank line

[Steven Rostedt]

On Tue, 18 Jun 2019 15:51:18 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Sphinx expects a blank line after a literal block markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

For the two tracing patches (1 and 2).

Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>

-- Steve

> ---
>  Documentation/trace/kprobetrace.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index 3d162d432a3c..caa0a8ba081e 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -228,6 +228,7 @@ events, you need to enable it.
>  
>  Use the following command to start tracing in an interval.
>  ::
> +
>      # echo 1 > tracing_on
>      Open something...
>      # echo 0 > tracing_on

Re: [PATCH 2/6] docs: trace: add a missing blank line

[Masami Hiramatsu]

On Tue, 18 Jun 2019 15:51:18 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Sphinx expects a blank line after a literal block markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Looks good to me, thanks!

Acked-by: Masami Hiramatsu <mhiramat@kernel.org>

> ---
>  Documentation/trace/kprobetrace.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index 3d162d432a3c..caa0a8ba081e 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -228,6 +228,7 @@ events, you need to enable it.
>  
>  Use the following command to start tracing in an interval.
>  ::
> +
>      # echo 1 > tracing_on
>      Open something...
>      # echo 0 > tracing_on
> -- 
> 2.21.0
> 


-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH 1/6] docs: trace: fix a broken label

[Masami Hiramatsu]

On Tue, 18 Jun 2019 15:51:17 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Sphinx warnings about his:
> 
> 	Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)
> 
> The problem is quite simple: Sphinx wants a blank line after
> references.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

This also looks good to me.

Acked-by: Masami Hiramatsu <mhiramat@kernel.org>

Thank you,

> ---
>  Documentation/trace/kprobetrace.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index b729b40a5ba5..3d162d432a3c 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
>  For $comm, the default type is "string"; any other type is invalid.
>  
>  .. _user_mem_access:
> +
>  User Memory Access
>  ------------------
>  Kprobe events supports user-space memory access. For that purpose, you can use
> -- 
> 2.21.0
> 


-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH 4/6] time: hrtimer: use a bullet for the returns bullet list

[Jonathan Corbet]

On Tue, 18 Jun 2019 15:51:20 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> That gets rid of this warning:
> 
> 	./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> and displays nicely both at the source code and at the produced
> documentation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  kernel/time/hrtimer.c | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> index edb230aba3d1..49f78453892f 100644
> --- a/kernel/time/hrtimer.c
> +++ b/kernel/time/hrtimer.c
> @@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
>   * @timer:	hrtimer to stop
>   *
>   * Returns:
> - *  0 when the timer was not active
> - *  1 when the timer was active
> - * -1 when the timer is currently executing the callback function and
> + *
> + *  •  0 when the timer was not active
> + *  •  1 when the timer was active
> + *  • -1 when the timer is currently executing the callback function and
>   *    cannot be stopped

So I have taken some grief for letting non-ASCII stuff into the docs
before; I can only imagine that those who object would be even more
unhappy to see it in a C source file.  I'm all for fixing the warning, but
I think we shouldn't start introducing exotic characters at this point...

Thanks,

jon


>   */
>  int hrtimer_try_to_cancel(struct hrtimer *timer)

Re: [PATCH 1/6] docs: trace: fix a broken label

[Jonathan Corbet]

On Tue, 18 Jun 2019 15:51:17 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Sphinx warnings about his:
> 
> 	Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)
> 
> The problem is quite simple: Sphinx wants a blank line after
> references.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  Documentation/trace/kprobetrace.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index b729b40a5ba5..3d162d432a3c 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
>  For $comm, the default type is "string"; any other type is invalid.
>  
>  .. _user_mem_access:

This one doesn't apply to docs-next; it should probably go through
whichever tree introduced the issue into linux-next.

Thanks,

jon

Re: [PATCH 2/6] docs: trace: add a missing blank line

[Jonathan Corbet]

On Tue, 18 Jun 2019 15:51:18 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Sphinx expects a blank line after a literal block markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  Documentation/trace/kprobetrace.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index 3d162d432a3c..caa0a8ba081e 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -228,6 +228,7 @@ events, you need to enable it.
>  
>  Use the following command to start tracing in an interval.
>  ::
> +

Applied, thanks.

jon

Re: [PATCH 3/6] lib: list_sort.c: add a blank line to avoid kernel-doc warnings

[Jonathan Corbet]

On Tue, 18 Jun 2019 15:51:19 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In order for a list to be recognized as such, blank lines
> are required.
> 
> Solve those Sphinx warnings:
> 
> ./lib/list_sort.c:162: WARNING: Unexpected indentation.
> ./lib/list_sort.c:163: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Applied, thanks.

jon

Re: [PATCH 4/6] time: hrtimer: use a bullet for the returns bullet list

[Mauro Carvalho Chehab]

Em Thu, 20 Jun 2019 14:02:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 18 Jun 2019 15:51:20 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > That gets rid of this warning:
> > 
> > 	./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.
> > 
> > and displays nicely both at the source code and at the produced
> > documentation.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >  kernel/time/hrtimer.c | 7 ++++---
> >  1 file changed, 4 insertions(+), 3 deletions(-)
> > 
> > diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> > index edb230aba3d1..49f78453892f 100644
> > --- a/kernel/time/hrtimer.c
> > +++ b/kernel/time/hrtimer.c
> > @@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
> >   * @timer:	hrtimer to stop
> >   *
> >   * Returns:
> > - *  0 when the timer was not active
> > - *  1 when the timer was active
> > - * -1 when the timer is currently executing the callback function and
> > + *
> > + *  •  0 when the timer was not active
> > + *  •  1 when the timer was active
> > + *  • -1 when the timer is currently executing the callback function and
> >   *    cannot be stopped  
> 
> So I have taken some grief for letting non-ASCII stuff into the docs
> before; I can only imagine that those who object would be even more
> unhappy to see it in a C source file.  I'm all for fixing the warning, but
> I think we shouldn't start introducing exotic characters at this point...

According to:
	http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists

The ASCII options are: "-", "+" or "*".

Both signs ('-' and '+') aren't too nice here, due to "-1".

So, what's left is '*'.

I remember someone once complained about having something like:

	* * -1 when the ...

But if you think we shouldn't use UTF-8 chars, be it.

Feel free to replace it at the patch, or if you prefer, I'll send a new
version tomorrow.

Thanks,
Mauro

Re: [PATCH 4/6] time: hrtimer: use a bullet for the returns bullet list

[Thomas Gleixner]

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

On Thu, 20 Jun 2019, Mauro Carvalho Chehab wrote:
> Em Thu, 20 Jun 2019 14:02:33 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> > On Tue, 18 Jun 2019 15:51:20 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > >   * Returns:
> > > - *  0 when the timer was not active
> > > - *  1 when the timer was active
> > > - * -1 when the timer is currently executing the callback function and
> > > + *
> > > + *  •  0 when the timer was not active
> > > + *  •  1 when the timer was active
> > > + *  • -1 when the timer is currently executing the callback function and
> > >   *    cannot be stopped  
> > 
> > So I have taken some grief for letting non-ASCII stuff into the docs
> > before; I can only imagine that those who object would be even more
> > unhappy to see it in a C source file.  I'm all for fixing the warning, but
> > I think we shouldn't start introducing exotic characters at this point...
> 
> According to:
> 	http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists
> 
> The ASCII options are: "-", "+" or "*".
> 
> Both signs ('-' and '+') aren't too nice here, due to "-1".
> 
> So, what's left is '*'.
> 
> I remember someone once complained about having something like:
> 
> 	* * -1 when the ...

I'm fine with that.
 
> But if you think we shouldn't use UTF-8 chars, be it.

I don't even know how to write them in the first place.
 
> Feel free to replace it at the patch, or if you prefer, I'll send a new
> version tomorrow.

Yes, please.

And while at it please fix the subject line. The usual prefix for hrtimer
is surprisingly 'hrtimer:' and not 'time: hrtimer:'. Also please start the
short sentence after the prefix with an uppercase character.

Thanks,

	tglx