[PATCH 0/3] docs: ftrace: Fix minor issues in the doc

[PATCH 0/3] docs: ftrace: Fix minor issues in the doc

[Frank A. Cancio Bello]

I didn't want to be pushy with these minor fixes but occur to me
now that, even all seem to be clear in the latest version of the
RFC (v2) related to these fixes, a clean patchset could be expected
after the RFC. So here we go:

Clarifies the RAM footprint of buffer_size_kb without getting into
implementation details.

Fix typos and a small notation mistakes in the doc.

Changes in this patchset (since RFC v2)
  - Take out the notation mistake into its own commit because it
    is not a typo.

Changes in RFC v2:
  - Removes implementation description of the RAM footprint of
    buffer_size_kb, but still make the corresponded clarification.

  - Removes a patch that was just for illustration purposes because
    Steven already got the issue that I was referring to.

  - Adds a patch to fix other typos in the doc.

Frank A. Cancio Bello (3):
  docs: ftrace: Clarify the RAM impact of buffer_size_kb
  docs: ftrace: Fix typos
  docs: ftrace: Fix small notation mistake

 Documentation/trace/ftrace.rst             | 9 +++++----
 Documentation/trace/ring-buffer-design.txt | 2 +-
 2 files changed, 6 insertions(+), 5 deletions(-)

-- 
2.17.1

[PATCH 1/3] docs: ftrace: Clarify the RAM impact of buffer_size_kb

[Frank A. Cancio Bello]

The current text could mislead the user into believing that the number
of pages allocated by each CPU ring buffer is calculated by the round
up of the division: buffer_size_kb / PAGE_SIZE.

Clarifies that a few extra pages may be allocated to accommodate buffer
management meta-data.

Suggested-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Suggested-by: Joel Fernandes (Google) <joel@joelfernandes.org>
Signed-off-by: Frank A. Cancio Bello <frank@generalsoftwareinc.com>
---
 Documentation/trace/ftrace.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index d2b5657ed33e..5a037bedbf6a 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -185,7 +185,8 @@ of ftrace. Here is a list of some of the key files:
 	CPU buffer and not total size of all buffers. The
 	trace buffers are allocated in pages (blocks of memory
 	that the kernel uses for allocation, usually 4 KB in size).
-	If the last page allocated has room for more bytes
+	A few extra pages may be allocated to accommodate buffer management
+	meta-data. If the last page allocated has room for more bytes
 	than requested, the rest of the page will be used,
 	making the actual allocation bigger than requested or shown.
 	( Note, the size may not be a multiple of the page size
-- 
2.17.1

[PATCH 2/3] docs: ftrace: Fix typos

[Frank A. Cancio Bello]

Fix minor typos in the doc.

Signed-off-by: Frank A. Cancio Bello <frank@generalsoftwareinc.com>
---
 Documentation/trace/ftrace.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 5a037bedbf6a..6c9f40d5a2f9 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -236,7 +236,7 @@ of ftrace. Here is a list of some of the key files:
 	This interface also allows for commands to be used. See the
 	"Filter commands" section for more details.
 
-	As a speed up, since processing strings can't be quite expensive
+	As a speed up, since processing strings can be quite expensive
 	and requires a check of all functions registered to tracing, instead
 	an index can be written into this file. A number (starting with "1")
 	written will instead select the same corresponding at the line position
@@ -383,7 +383,7 @@ of ftrace. Here is a list of some of the key files:
 
 	By default, 128 comms are saved (see "saved_cmdlines" above). To
 	increase or decrease the amount of comms that are cached, echo
-	in a the number of comms to cache, into this file.
+	in the number of comms to cache, into this file.
 
   saved_tgids:
 
@@ -3325,7 +3325,7 @@ directories after it is created.
 
 As you can see, the new directory looks similar to the tracing directory
 itself. In fact, it is very similar, except that the buffer and
-events are agnostic from the main director, or from any other
+events are agnostic from the main directory, or from any other
 instances that are created.
 
 The files in the new directory work just like the files with the
-- 
2.17.1

Re: [PATCH 2/3] docs: ftrace: Fix typos

[Randy Dunlap]

On 12/24/19 9:57 AM, Frank A. Cancio Bello wrote:
> Fix minor typos in the doc.
> 
> Signed-off-by: Frank A. Cancio Bello <frank@generalsoftwareinc.com>
> ---
>  Documentation/trace/ftrace.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
> index 5a037bedbf6a..6c9f40d5a2f9 100644
> --- a/Documentation/trace/ftrace.rst
> +++ b/Documentation/trace/ftrace.rst
> @@ -236,7 +236,7 @@ of ftrace. Here is a list of some of the key files:
>  	This interface also allows for commands to be used. See the
>  	"Filter commands" section for more details.
>  
> -	As a speed up, since processing strings can't be quite expensive
> +	As a speed up, since processing strings can be quite expensive
>  	and requires a check of all functions registered to tracing, instead
>  	an index can be written into this file. A number (starting with "1")
>  	written will instead select the same corresponding at the line position
> @@ -383,7 +383,7 @@ of ftrace. Here is a list of some of the key files:
>  
>  	By default, 128 comms are saved (see "saved_cmdlines" above). To
>  	increase or decrease the amount of comms that are cached, echo
> -	in a the number of comms to cache, into this file.
> +	in the number of comms to cache, into this file.

That repeats the inwardness of the echo (in + into).  How about:

+	the number of comms to cache into this file.

>  
>    saved_tgids:
>  
> @@ -3325,7 +3325,7 @@ directories after it is created.
>  
>  As you can see, the new directory looks similar to the tracing directory
>  itself. In fact, it is very similar, except that the buffer and
> -events are agnostic from the main director, or from any other
> +events are agnostic from the main directory, or from any other
>  instances that are created.
>  
>  The files in the new directory work just like the files with the
> 


-- 
~Randy

Re: [PATCH 2/3] docs: ftrace: Fix typos

[Frank A. Cancio Bello]

On Tue, Dec 24, 2019 at 03:11:34PM -0800, Randy Dunlap wrote:
> On 12/24/19 9:57 AM, Frank A. Cancio Bello wrote:
> > Fix minor typos in the doc.
> > 
> > Signed-off-by: Frank A. Cancio Bello <frank@generalsoftwareinc.com>
> > ---
> >  Documentation/trace/ftrace.rst | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
> > index 5a037bedbf6a..6c9f40d5a2f9 100644
> > --- a/Documentation/trace/ftrace.rst
> > +++ b/Documentation/trace/ftrace.rst
> > @@ -236,7 +236,7 @@ of ftrace. Here is a list of some of the key files:
> >  	This interface also allows for commands to be used. See the
> >  	"Filter commands" section for more details.
> >  
> > -	As a speed up, since processing strings can't be quite expensive
> > +	As a speed up, since processing strings can be quite expensive
> >  	and requires a check of all functions registered to tracing, instead
> >  	an index can be written into this file. A number (starting with "1")
> >  	written will instead select the same corresponding at the line position
> > @@ -383,7 +383,7 @@ of ftrace. Here is a list of some of the key files:
> >  
> >  	By default, 128 comms are saved (see "saved_cmdlines" above). To
> >  	increase or decrease the amount of comms that are cached, echo
> > -	in a the number of comms to cache, into this file.
> > +	in the number of comms to cache, into this file.
> 
> That repeats the inwardness of the echo (in + into).  How about:
> 
> +	the number of comms to cache into this file.
>

Thank you. I re-sent the patchset with this improvement.

frank a.

> >  
> >    saved_tgids:
> >  
> > @@ -3325,7 +3325,7 @@ directories after it is created.
> >  
> >  As you can see, the new directory looks similar to the tracing directory
> >  itself. In fact, it is very similar, except that the buffer and
> > -events are agnostic from the main director, or from any other
> > +events are agnostic from the main directory, or from any other
> >  instances that are created.
> >  
> >  The files in the new directory work just like the files with the
> > 
> 
> 
> -- 
> ~Randy
> 

[PATCH 3/3] docs: ftrace: Fix small notation mistake

[Frank A. Cancio Bello]

The use of iff ("if and only if") notation is not accurate in this case.

Suggested-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Signed-off-by: Frank A. Cancio Bello <frank@generalsoftwareinc.com>
---
 Documentation/trace/ring-buffer-design.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.txt
index ff747b6fa39b..2d53c6f25b91 100644
--- a/Documentation/trace/ring-buffer-design.txt
+++ b/Documentation/trace/ring-buffer-design.txt
@@ -37,7 +37,7 @@ commit_page - a pointer to the page with the last finished non-nested write.
 
 cmpxchg - hardware-assisted atomic transaction that performs the following:
 
-   A = B iff previous A == C
+   A = B if previous A == C
 
    R = cmpxchg(A, C, B) is saying that we replace A with B if and only if
       current A is equal to C, and we put the old (current) A into R
-- 
2.17.1

[PATCH 0/3] docs: ftrace: Fix minor issues in the doc

[Frank A. Cancio Bello]

I didn't want to be pushy with these minor fixes but occur to me
now that, even all seem to be clear in the latest version of the
RFC (v2) related to these fixes, a clean patchset could be expected
after such RFC. So here we go:

Clarifies the RAM footprint of buffer_size_kb without getting into
implementation details.

Fix typos and a small notation mistakes in the doc.

Changes since PATCH v1:
  - Improves the redaction as per Randy suggestion.

Changes since RFC v2:
  - Take out the notation mistake into its own commit because it
    is not a typo.

Changes since RFC v1:
  - Removes implementation description of the RAM footprint of
    buffer_size_kb, but still make the corresponded clarification.

  - Removes a patch that was just for illustration purposes because
    Steven already got the issue that I was referring to.

  - Adds a patch to fix other typos in the doc.

Frank A. Cancio Bello (3):
  docs: ftrace: Clarify the RAM impact of buffer_size_kb
  docs: ftrace: Fix typos
  docs: ftrace: Fix small notation mistake

 Documentation/trace/ftrace.rst             | 9 +++++----
 Documentation/trace/ring-buffer-design.txt | 2 +-
 2 files changed, 6 insertions(+), 5 deletions(-)

-- 
2.17.1