RE: [PATCH 3/3] doc, record: document record changes

["Metzger, Markus T" <markus dot t dot metzger at intel dot com>]

> -----Original Message-----
> From: Eli Zaretskii [mailto:eliz@gnu.org]
> Sent: Friday, March 01, 2013 3:26 PM


> > > > +"record function-call-history" prints the names of the functions
> > > > +from instructions stored in the execution log.
> > >
> > > "prints the names of the functions called by instructions in the
> > > execution log"
> >
> > I'm not sure whether "called" is the right term. The algorithm walks over
> > all instructions and collects the functions from which these instructions
> > originated.
> >
> > Example:
> >
> > 1  void foo (void)
> > 2 {
> > 3    ...
> > 4    bar ();
> > 5    ...
> > 6  }
> >
> > When we record the execution of foo, there will be instructions for the
> > first ..., then instructions for bar, and then instructions for the second ....
> >
> > The "record function-call-history" will print:
> >   foo.c:1-4	foo (void)
> >   bar.c:8-12	bar (void)
> >   foo.c:5-6	foo (void
> 
> This indicates that "record function-execution-history" might be a
> better name.  But in any case, weren't 'bar' and 'foo' called in this
> example?

Yes, they were called.

What I have problems with is that foo was called once but we print
two lines for foo, one for instructions before the call to bar and one
for instructions after the return from bar.

Wouldn't "called" suggest that there be only one line for foo in the
above example?

 
> Your original text, "prints the names of the functions from
> instructions", is confusing, since instructions don't store function
> names, they store addresses and numbers.

I'm not exactly happy with my formulation, either.


> > > > +@kindex show record full memory-query
> > > > +@item show record full memory-query
> > >
> > > I think it is good enough to have only one "@kindex set record" and
> > > one "@kindex show record" entry (which you already have at the
> > > beginning of this description), without the entries that advertise the
> > > rest of the command arguments.  These varieties are all described
> > > together, so the multitude of index entries does not have any useful
> > > effect, it just bloats the index.
> >
> > I just renamed the text for existing indices. Do you still want me to
> > merge them?
> 
> Can you give one example of such renaming?  I'm not sure I understand
> what you did.

There had been a target "record" that I renamed to "record-full".
Then I added a new target "record-btrace" that provides similar, yet
different functionality.

There's a prefix-command "record" whose sub-commands operate on
target record.

Those sub-commands that are applicable to both targets, I left unchanged.
Those sub-commands that are specific to target "record-full", I put
under a new prefix-command "record full".

Same for "set record" and "show record".

In the documentation, there had been a @kindex show record memory-query.
I changed it to @kindex show record full memory-query.


> > > > +@item record function-call-history
> > > > +Print function names for instructions stored in the recorded execution
> > > > +log.  Prints one line for each sequence of instructions that is
> > > > +correlated to the same function.
> > >
> > > Isn't the last sentence equivalent to saying
> > >
> > >   Prints one line for each function call in the execution log.
> > >
> > > ?  If it is equivalent, I think my suggested wording is more clear and
> > > less technical.
> >
> > See above.
> 
> Given the example (which I think it would be good to have in the
> manual), I suggest this wording instead:
> 
>   Prints one line for each sequence of instructions that all belong to
>   the same function.

That's good. Thanks!

Regards,
Markus.
Intel GmbH
Dornacher Strasse 1
85622 Feldkirchen/Muenchen, Deutschland
Sitz der Gesellschaft: Feldkirchen bei Muenchen
Geschaeftsfuehrer: Christian Lamprechter, Hannes Schwaderer, Douglas Lusk
Registergericht: Muenchen HRB 47456
Ust.-IdNr./VAT Registration No.: DE129385895
Citibank Frankfurt a.M. (BLZ 502 109 00) 600119052