[RFC v2 0/2] docs: ftrace: Clarify the RAM impact of buffer_size_kb

[RFC v2 0/2] docs: ftrace: Clarify the RAM impact of buffer_size_kb

[Frank A. Cancio Bello]

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

Changes in 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 (2):
  docs: ftrace: Clarify the RAM impact of buffer_size_kb
  docs: ftrace: Fix typos

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

-- 
2.17.1

[RFC v2 1/2] 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..2b21068ebf8e 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

[RFC v2 2/2] 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 +++---
 Documentation/trace/ring-buffer-design.txt | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 2b21068ebf8e..9e7b45485ea1 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
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

Re: [RFC v2 2/2] docs: ftrace: Fix typos

[Steven Rostedt]

On Sun, 24 Nov 2019 23:38:41 -0500
"Frank A. Cancio Bello" <frank@generalsoftwareinc.com> wrote:

> --- 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

This wasn't a typo. "iff" means "if and only if" which is a standard
notation. That is, this is shorthand for:

  A = B if previous A == C
  previous A == C if A = B

-- Steve


>  
>     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
> -- 

Re: [RFC v2 2/2] docs: ftrace: Fix typos

[Steven Rostedt]

On Mon, 25 Nov 2019 12:37:09 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> On Sun, 24 Nov 2019 23:38:41 -0500
> "Frank A. Cancio Bello" <frank@generalsoftwareinc.com> wrote:
> 
> > --- 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  
> 
> This wasn't a typo. "iff" means "if and only if" which is a standard
> notation. That is, this is shorthand for:
> 
>   A = B if previous A == C
>   previous A == C if A = B

Although thinking about this more, this may not be correct. If
previous A == B, then A = B, thus the "iff" notation is not actually
accurate.

This wouldn't then be a typo fix, but a real fix to the logic ;-)

-- Steve

> 
> 
> >  
> >     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
> > --   

Re: [RFC v2 2/2] docs: ftrace: Fix typos

[Frank A. Cancio Bello]

On Mon, Nov 25, 2019 at 04:46:25PM -0500, Steven Rostedt wrote:
> On Mon, 25 Nov 2019 12:37:09 -0500
> Steven Rostedt <rostedt@goodmis.org> wrote:
> 
> > On Sun, 24 Nov 2019 23:38:41 -0500
> > "Frank A. Cancio Bello" <frank@generalsoftwareinc.com> wrote:
> > 
> > > --- 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  
> > 
> > This wasn't a typo. "iff" means "if and only if" which is a standard
> > notation. That is, this is shorthand for:
> > 
> >   A = B if previous A == C
> >   previous A == C if A = B
> 
> Although thinking about this more, this may not be correct. If
> previous A == B, then A = B, thus the "iff" notation is not actually
> accurate.
> 
> This wouldn't then be a typo fix, but a real fix to the logic ;-)
> 

What are the odds ;)

I knew about the concept https://en.wikipedia.org/wiki/If_and_only_if
from school math but didn't remember the notation. For me was
suspicious so, I  looked in "the cmpxchg doc" and nothing referring
to "iff" was there, then I decided to classified it as a typo.

Now thinking more deeply, I agreed with you that was not a typo but
a "logic mistake", even not for the same reason ;)

Being not 100% sure of what I'm about to say, I will say it
anyway because you have been kind enough to write the second email.

"if and only if (shortened as iff) is a biconditional logical
connective between statements" and A = B can't be considered a
logical statement in the context of that definition (math/logic),
even it could be in C.

Thank you Steven one more time for such a quick reply!
frank a.