RE: [PATCH v3 8/8] Add documentation for new instruction record Python bindings.

["Metzger, Markus T" <markus.t.metzger@intel.com>]

> -----Original Message-----
> From: Wiederhake, Tim
> Sent: Monday, November 21, 2016 4:49 PM
> To: gdb-patches@sourceware.org
> Cc: palves@redhat.com; Metzger, Markus T <markus.t.metzger@intel.com>
> Subject: [PATCH v3 8/8] Add documentation for new instruction record Python
> bindings.
> 
> 2016-11-21  Tim Wiederhake  <tim.wiederhake@intel.com>
> 
> gdb/ChangeLog:
> 
> 	* NEWS: Add record Python bindings entry.
> 
> gdb/doc/ChangeLog:
> 
> 	* python.texi (Recordings In Python): New section.



> +@defvar Record.format
> +A string with the current recording format, e.g.@: @code{bt} or
> +@code{pts}.  Can be empty.

This should be "bts" instead of "pts".  IIRC the patches don't really allow
it to be empty.


> +@end defvar
> +
> +@defvar Record.begin
> +A format specific instruction object representing the first instruction

Should this be "method-specific" instead of "format-specific"?


> +The attributes and methods of instruction objects depend on the current
> +recording format.  Currently, only btrace instructions are supported.

Should this be "method" instead of "format"?


> +@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
> +
> +@defvar BtraceInstruction.error
> +An integer identifying the error code for gaps in the record.

Should this be "history" instead of "record"?


> +@defvar BtraceInstruction.decoded
> +A human readable string with the decoded instruction.  Contains the

Should this be "disassembled" instead of "decoded"?


> +@defvar BtraceFunctionCall.instructions
> +A list of instructions associated with this function call.

Should this be "a list of gdb.BtraceInstruction objects"?


> +The following example demonstrates the usage of these objects and
> +functions to create a function that will rewind a record to the last
> +time a function in a different file was executed.  This would typically
> +be used to track the execution of user provided callback functions in a
> +library which typically are not visible in a back trace.
> +
> +@smallexample
> +def bringback ():
> +    rec = gdb.current_recording ()
> +    if not rec:
> +        return
> +
> +    insn = rec.instruction_history
> +    if len (insn) == 0:
> +        return
> +
> +    try:
> +        position = insn.index (rec.replay_position)
> +    except:
> +        position = -1
> +    try:
> +        filename = insn[position].symbol.symtab.fullname ()
> +    except:
> +        filename = None
> +
> +    for i in reversed (insn[:position]):
> +	try:
> +            current = i.symbol.symtab.fullname ()
> +	except:
> +            current = None
> +
> +        if filename == current:
> +            continue
> +
> +        rec.goto (i)
> +        return
> +@end smallexample
> +
> +Another possible application is to write a function that counts the
> +number of code executions in a given line range.  This line range can
> +contain parts of functions or span across several functions and is not
> +limited to be contiguous.
> +
> +@smallexample
> +def countrange (filename, linerange):
> +    count = 0
> +
> +    def filter_only (file_name):
> +        for call in gdb.current_recording ().function_call_history:
> +            try:
> +                if file_name in call.symbol.symtab.fullname ():
> +                    yield call
> +            except:
> +                pass
> +
> +    for c in filter_only (filename):
> +        for i in c.instructions:
> +            try:
> +                if i.symbol.line in linerange:
> +                    count += 1
> +                    break;
> +            except:
> +                    pass
> +
> +    return count
> +@end smallexample
> +
>  @node Commands In Python
>  @subsubsection Commands In Python

The examples are really helpful.

The patch looks good to me but we need Eli to approve it.

Thanks,
Markus.
Intel Deutschland GmbH
Registered Address: Am Campeon 10-12, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de
Managing Directors: Christin Eisenschmid, Christian Lamprechter
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928