Re: [PATCH] perf tools: Document --children option in more detail

[Namhyung Kim <namhyung@kernel.org>]

Hi David,

Thanks for fixing my English :)

On Sun, Apr 19, 2015 at 11:11:14AM -0600, David Ahern wrote:
> On 4/18/15 11:33 AM, Namhyung Kim wrote:
> >+It might confusing that the sum of the all children overhead exceeds
> >+100%.  But with this enabled, users can find which function has most
> >+overhead even if samples are spread over the children.
> 
> Can you add more detail on why the sum can exceed 100%?

OK.  How about this?

"It might confusing that the sum of the all children overhead exceeds
100% since each of them is already an accumulation of (self) overhead
of its children."

> 
> >+
> >+Let me see you an example; there’re three functions like below.
> 
> That sentence needs some work and should stay in 3rd person. Maybe something
> like this:
> 
> "Consider the following example:"

OK.

> 
> >+
> >+-----------------------
> >+void foo(void) {
> >+    /* something */
> >+}
> >+
> >+bar(void) {
> >+    /* do something */
> >+    foo();
> >+}
> >+
> >+int main(void) {
> >+    bar()
> >+    return 0;
> >+}
> >+-----------------------
> >+
> >+In this case 'foo' is a child of 'bar', and 'bar' is an immediate
> >+child of 'main' so 'foo' also is a child of 'main'.  In other words,
> >+'main' is a parent of 'foo' and 'bar'. and 'bar' is a parent of 'foo'.
> >+
> >+Suppose all samples are recorded in the 'foo' and 'bar' only.  When
> >+you record with callchain you'll see something like below in the usual
> >+(self-overhead-only) output of the perf report:
> >+
> >+----------------------------------
> >+Overhead  Symbol
> >+........  .....................
> >+  60.00%  foo
> >+          |
> >+          --- foo
> >+              bar
> >+              main
> >+              __libc_start_main
> >+
> >+  40.00%  bar
> >+          |
> >+          --- bar
> >+              main
> >+              __libc_start_main
> >+----------------------------------
> >+
> >+When --children option is enabled, the (self) overhead of children (in
> >+this case foo and bar) will be added to its parent to calculate the
> >+children overhead.  In this case we'll see somethink like below:
> 
> Man pages should avoid contractions, should be in 3rd person and
> s/somethink/something/.
> 
> "When --children option is enabled, the (self) overhead of children (in this
> case foo and bar) are added to the parent to calculate the children
> overhead. In this case the report could display as:"

OK.

> 
> >+
> >+-------------------------------------------
> >+Children      Self  Symbol
> >+........  ........  ....................
> >+ 100.00%     0.00%  __libc_start_main
> >+          |
> >+          --- __libc_start_main
> >+
> >+ 100.00%     0.00%  main
> >+          |
> >+          --- main
> >+              __libc_start_main
> >+
> >+ 100.00%    40.00%  bar
> >+          |
> >+          --- bar
> >+              main
> >+              __libc_start_main
> >+
> >+  60.00%    60.00%  foo
> >+          |
> >+          --- foo
> >+              bar
> >+              main
> >+              __libc_start_main
> >+-------------------------------------------
> >+
> >+Please note that since v3.16 the children overhead will be shown by
> >+default and the output will be sorted by the values, users can disable
> >+it by specifing --no-children option on the command line, or by adding
> >++report.children = false+ or +top.children = false+ config option.
> 
> Maintain tense. Something like:
> 
> "Since v3.16 the children overhead is shown by default and the output is
> sorted by the values. Children overhead is disabled by specifying
> --no-children option on the command line or by adding 'report.children =
> false' or 'top.children = false' in the perfconfig file.

OK

> 
> Overall nicely done. Thanks for taking the time to write this up.

And thank you so much for reviewing this! :)
Namhyung