Add documentation for new record Python bindings.
Signed-off-by: Tim Wiederhake <tim.wiederhake@intel.com> gdb/ChangeLog: * NEWS: Add record Python bindings entry. gdb/doc/ChangeLog: * python.texi (Recordings In Python): New section. Change-Id: Ibacb5930085bff36b0003fde30db9a8178cb280b
This commit is contained in:
Tim Wiederhake
parent
714aa61c16
commit
0a0faf9fc6
4
gdb/NEWS
4
gdb/NEWS
|
|
@ -3,6 +3,10 @@
|
|||
|
||||
*** Changes since GDB 7.12
|
||||
|
||||
* Python Scripting
|
||||
|
||||
** New functions to start, stop and access a running btrace recording.
|
||||
|
||||
* GDB now supports recording and replaying rdrand and rdseed Intel 64
|
||||
instructions.
|
||||
|
||||
|
|
|
|||
|
|
@ -151,6 +151,7 @@ optional arguments while skipping others. Example:
|
|||
* Inferiors In Python:: Python representation of inferiors (processes)
|
||||
* Events In Python:: Listening for events from @value{GDBN}.
|
||||
* Threads In Python:: Accessing inferior threads from Python.
|
||||
* Recordings In Python:: Accessing recordings from Python.
|
||||
* Commands In Python:: Implementing new commands in Python.
|
||||
* Parameters In Python:: Adding new @value{GDBN} parameters.
|
||||
* Functions In Python:: Writing new convenience functions.
|
||||
|
|
@ -3062,6 +3063,250 @@ Return a Boolean indicating whether the thread is running.
|
|||
Return a Boolean indicating whether the thread is exited.
|
||||
@end defun
|
||||
|
||||
@node Recordings In Python
|
||||
@subsubsection Recordings In Python
|
||||
@cindex recordings in python
|
||||
|
||||
The following recordings-related functions
|
||||
(@pxref{Process Record and Replay}) are available in the @code{gdb}
|
||||
module:
|
||||
|
||||
@defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
|
||||
Start a recording using the given @var{method} and @var{format}. If
|
||||
no @var{format} is given, the default format for the recording method
|
||||
is used. If no @var{method} is given, the default method will be used.
|
||||
Returns a @code{gdb.Record} object on success. Throw an exception on
|
||||
failure.
|
||||
|
||||
The following strings can be passed as @var{method}:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@code{"full"}
|
||||
@item
|
||||
@code{"btrace"}: Possible values for @var{format}: @code{"pt"},
|
||||
@code{"bts"} or leave out for default format.
|
||||
@end itemize
|
||||
@end defun
|
||||
|
||||
@defun gdb.current_recording ()
|
||||
Access a currently running recording. Return a @code{gdb.Record}
|
||||
object on success. Return @code{None} if no recording is currently
|
||||
active.
|
||||
@end defun
|
||||
|
||||
@defun gdb.stop_recording ()
|
||||
Stop the current recording. Throw an exception if no recording is
|
||||
currently active. All record objects become invalid after this call.
|
||||
@end defun
|
||||
|
||||
A @code{gdb.Record} object has the following attributes:
|
||||
|
||||
@defvar Record.ptid
|
||||
ID of the thread associated with this object as a tuple of three integers. The
|
||||
first is the Process ID (PID); the second is the Lightweight Process ID (LWPID),
|
||||
and the third is the Thread ID (TID). Either the LWPID or TID may be 0, which
|
||||
indicates that the operating system does not use that identifier.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.method
|
||||
A string with the current recording method, e.g.@: @code{full} or
|
||||
@code{btrace}.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.format
|
||||
A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
|
||||
@code{None}.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.begin
|
||||
A method specific instruction object representing the first instruction
|
||||
in this recording.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.end
|
||||
A method specific instruction object representing the current
|
||||
instruction, that is not actually part of the recording.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.replay_position
|
||||
The instruction representing the current replay position. If there is
|
||||
no replay active, this will be @code{None}.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.instruction_history
|
||||
A list with all recorded instructions.
|
||||
@end defvar
|
||||
|
||||
@defvar Record.function_call_history
|
||||
A list with all recorded function call segments.
|
||||
@end defvar
|
||||
|
||||
A @code{gdb.Record} object has the following methods:
|
||||
|
||||
@defun Record.goto (instruction)
|
||||
Move the replay position to the given @var{instruction}.
|
||||
@end defun
|
||||
|
||||
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
|
||||
|
||||
@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
|
||||
|
||||
@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
|
||||
|
||||
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
|
||||
|
||||
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].sal.symtab.fullname ()
|
||||
except:
|
||||
filename = None
|
||||
|
||||
for i in reversed (insn[:position]):
|
||||
try:
|
||||
current = i.sal.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.sal.line in linerange:
|
||||
count += 1
|
||||
break;
|
||||
except:
|
||||
pass
|
||||
|
||||
return count
|
||||
@end smallexample
|
||||
|
||||
@node Commands In Python
|
||||
@subsubsection Commands In Python
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue