From 0a0faf9fc652903d6467fc2bc8609891be730bdb Mon Sep 17 00:00:00 2001 From: Tim Wiederhake Date: Mon, 21 Nov 2016 16:39:57 +0100 Subject: [PATCH] Add documentation for new record Python bindings. Signed-off-by: Tim Wiederhake gdb/ChangeLog: * NEWS: Add record Python bindings entry. gdb/doc/ChangeLog: * python.texi (Recordings In Python): New section. Change-Id: Ibacb5930085bff36b0003fde30db9a8178cb280b --- gdb/NEWS | 4 + gdb/doc/python.texi | 245 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 249 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index 08f97c08213..f4128874c99 100644 --- a/gdb/NEWS +++ b/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. diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index fae45aa5d9f..d1cbadb8655 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -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 -- 2.30.2