Re: [PATCH v6 9/9] Add documentation for new record Python bindings.

[Yao Qi <qiyaoltc at gmail dot com>]

Tim Wiederhake <tim.wiederhake@intel.com> writes:

Hi Tim,
I read them again this morning, and have a design question in general,
why are they specific to btrace?

> +The attributes and methods of instruction objects depend on the current
> +recording method.  Currently, only btrace instructions are supported.
> +
> +A @code{gdb.BtraceInstruction} object has the following attributes:
> +
> +@defvar BtraceInstruction.number
> +An integer identifying this instruction.  @var{number} corresponds to
> +the numbers seen in @code{record instruction-history}
> +(@pxref{Process Record and Replay}).
> +@end defvar
> +

Why is it btrace specific?  Instructions in history of any record
methods can have a number or id, isn't?

> +@defvar BtraceInstruction.error
> +An integer identifying the error code for gaps in the history.
> +@code{None} for regular instructions.
> +@end defvar

> +
> +@defvar BtraceInstruction.sal
> +A @code{gdb.Symtab_and_line} object representing the associated symtab
> +and line of this instruction.  May be @code{None} if the instruction
> +is a gap.
> +@end defvar
> +
> +@defvar BtraceInstruction.pc
> +An integer representing this instruction's address.  May be @code{None}
> +if the instruction is a gap or the debug symbols could not be read.
> +@end defvar

Again, is it btrace specific?  Any instruction will have an address,
regardless of debug symbol.

Secondly, we have BtraceInstruction.pc, do we still need
BtraceInstruction.sal?  The sal can be got from other python api,
although these api may not exist.

Can add a base class like RecordInstruction, which have some basic
attributes for all record methods, and BtraceInstruction extends it to
add more btrace specific attributes.

> +
> +@defvar BtraceInstruction.data
> +A buffer with the raw instruction data.  May be @code{None} if the
> +instruction is a gap.
> +@end defvar
> +
> +@defvar BtraceInstruction.decoded
> +A human readable string with the disassembled instruction.  Contains the
> +error message for gaps.
> +@end defvar
> +
> +@defvar BtraceInstruction.size
> +The size of the instruction in bytes.  Will be @code{None} if the
> +instruction is a gap.
> +@end defvar
> +
> +@defvar BtraceInstruction.is_speculative
> +A boolean indicating whether the instruction was executed
> +speculatively.  Will be @code{None} for gaps.
> +@end defvar

Why are these four attributes about Btrace or even record?  To me, they
are about instruction decode or disassembly.

> +
> +The attributes and methods of function call objects depend on the
> +current recording format.  Currently, only btrace function calls are
> +supported.
> +
> +A @code{gdb.BtraceFunctionCall} object has the following attributes:
> +
> +@defvar BtraceFunctionCall.number
> +An integer identifying this function call.  @var{number} corresponds to
> +the numbers seen in @code{record function-call-history}
> +(@pxref{Process Record and Replay}).
> +@end defvar
> +
> +@defvar BtraceFunctionCall.symbol
> +A @code{gdb.Symbol} object representing the associated symbol.  May be
> +@code{None} if the function call is a gap or the debug symbols could
> +not be read.
> +@end defvar
> +
> +@defvar BtraceFunctionCall.level
> +An integer representing the function call's stack level.  May be
> +@code{None} if the function call is a gap.
> +@end defvar
> +
> +@defvar BtraceFunctionCall.instructions
> +A list of @code{gdb.BtraceInstruction} objects associated with this function
> +call.
> +@end defvar
> +
> +@defvar BtraceFunctionCall.up
> +A @code{gdb.BtraceFunctionCall} object representing the caller's
> +function segment.  If the call has not been recorded, this will be the
> +function segment to which control returns.  If neither the call nor the
> +return have been recorded, this will be @code{None}.
> +@end defvar
> +
> +@defvar BtraceFunctionCall.prev_sibling
> +A @code{gdb.BtraceFunctionCall} object representing the previous
> +segment of this function call.  May be @code{None}.
> +@end defvar
> +
> +@defvar BtraceFunctionCall.next_sibling
> +A @code{gdb.BtraceFunctionCall} object representing the next segment of
> +this function call.  May be @code{None}.
> +@end defvar
> +

Sorry, I don't understand BtraceFunctionCall, can you give an example?
BtraceFunctionCall.symbol and .level indicates it represents a function
call rather than a function.  In the following example,

f2 () { f1 (); }
f3 () { f1 (); }

main () { f2 (); f3 (); }

Here are my understandings,

 - There are two BtraceFunctionCall objects bf1 and bf2 for f1, the first
   one, bf1, is about the call in f2 and the second one, bf2, is about the
   call in f3.
 - bf2.up is about the call in f2, and bf3.up is about the call in f3.
 - bf2.next_sibling == bf3 and bf3.prev_sibling == b2

Are they correct?

-- 
Yao (齐尧)