From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 90455 invoked by alias); 4 Nov 2016 07:55:35 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 90381 invoked by uid 89); 4 Nov 2016 07:55:35 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.1 required=5.0 tests=AWL,BAYES_00,KAM_LAZY_DOMAIN_SECURITY,RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=scripting, contiguous, yield, UD:line X-HELO: mga09.intel.com Received: from mga09.intel.com (HELO mga09.intel.com) (134.134.136.24) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 04 Nov 2016 07:55:26 +0000 Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga102.jf.intel.com with ESMTP; 04 Nov 2016 00:55:13 -0700 X-ExtLoop1: 1 Received: from irvmail001.ir.intel.com ([163.33.26.43]) by fmsmga001.fm.intel.com with ESMTP; 04 Nov 2016 00:55:12 -0700 Received: from ulvlx001.iul.intel.com (ulvlx001.iul.intel.com [172.28.207.17]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id uA47tBU6011393; Fri, 4 Nov 2016 07:55:11 GMT Received: from ulvlx001.iul.intel.com (localhost [127.0.0.1]) by ulvlx001.iul.intel.com with ESMTP id uA47tBL4014856; Fri, 4 Nov 2016 08:55:11 +0100 Received: (from twiederh@localhost) by ulvlx001.iul.intel.com with œ id uA47tAXH014853; Fri, 4 Nov 2016 08:55:11 +0100 From: Tim Wiederhake To: gdb-patches@sourceware.org Cc: palves@redhat.com, markus.t.metzger@intel.com Subject: [PATCH v2 8/8] Add documentation for new instruction record Python bindings. Date: Fri, 04 Nov 2016 07:55:00 -0000 Message-Id: <1478246074-14526-9-git-send-email-tim.wiederhake@intel.com> In-Reply-To: <1478246074-14526-1-git-send-email-tim.wiederhake@intel.com> References: <1478246074-14526-1-git-send-email-tim.wiederhake@intel.com> X-IsSubscribed: yes X-SW-Source: 2016-11/txt/msg00090.txt.bz2 2016-11-04 Tim Wiederhake gdb/ChangeLog: * NEWS: Add record Python bindings entry. gdb/doc/ChangeLog: * python.texi: Add record Python bindings entry. --- gdb/NEWS | 4 + gdb/doc/python.texi | 237 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 241 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index a6b1282..31bdd83 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. + * Building GDB and GDBserver now requires a C++11 compiler. For example, GCC 4.8 or later. diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index d6507e5..26c7fdc 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,242 @@ 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.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} or +@code{pts}. Can be empty. +@end defvar + +@defvar Record.begin +A format specific instruction object representing the first instruction +in this recording. +@end defvar + +@defvar Record.end +A format 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 format. 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 record. +@code{None} for regular instructions. +@end defvar + +@defvar BtraceInstruction.symbol +A @code{gdb.Symtab_and_line} object representing the associated line +and symbol 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 decoded 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{Node} 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 instructions 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].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 -- 2.7.4