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

Metzger, Markus T
2016-11-29T15:48:52Z

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