From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 76327 invoked by alias); 27 Oct 2016 06:29:44 -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 76203 invoked by uid 89); 27 Oct 2016 06:29:43 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.3 required=5.0 tests=AWL,BAYES_00,KAM_LAZY_DOMAIN_SECURITY,RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=pts, indicating, decoded, Implementing 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; Thu, 27 Oct 2016 06:29:33 +0000 Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga102.jf.intel.com with ESMTP; 26 Oct 2016 23:29:22 -0700 X-ExtLoop1: 1 Received: from irvmail001.ir.intel.com ([163.33.26.43]) by orsmga003.jf.intel.com with ESMTP; 26 Oct 2016 23:29:21 -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 u9R6TKTK013793; Thu, 27 Oct 2016 07:29:20 +0100 Received: from ulvlx001.iul.intel.com (localhost [127.0.0.1]) by ulvlx001.iul.intel.com with ESMTP id u9R6TKd9003368; Thu, 27 Oct 2016 08:29:20 +0200 Received: (from twiederh@localhost) by ulvlx001.iul.intel.com with œ id u9R6TKmW003365; Thu, 27 Oct 2016 08:29:20 +0200 From: Tim Wiederhake To: gdb-patches@sourceware.org Cc: palves@redhat.com, markus.t.metzger@intel.com Subject: [PATCH 7/7] Add documentation for new instruction record Python bindings. Date: Thu, 27 Oct 2016 06:29:00 -0000 Message-Id: <1477549711-2603-8-git-send-email-tim.wiederhake@intel.com> In-Reply-To: <1477549711-2603-1-git-send-email-tim.wiederhake@intel.com> References: <1477549711-2603-1-git-send-email-tim.wiederhake@intel.com> X-IsSubscribed: yes X-SW-Source: 2016-10/txt/msg00737.txt.bz2 2016-10-26 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 | 239 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 243 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index 4a61438..6da2784 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 and GDBserver now require building with a C++ compiler. It is no longer possible to build GDB or GDBserver with a C diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index d6507e5..f396914 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,244 @@ 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 are available in the +@code{gdb} module: + +@defun gdb.start_recording ([method]) +Starts a recording using the given @var{method}. If no @var{method} is +given, the default method will be used. Returns a @code{gdb.Record} +object on success. Throws an exception on failure. The following +methods are currently supported: + +@itemize @bullet +@item +@code{"full"} +@item +@code{"btrace"}: Will use @code{"pt"} or @code{"bts"}, depending on +availability. +@item +@code{"btrace pt"} +@item +@code{"pt"}: Alias for @code{"btrace pt"} +@item +@code{"btrace bts"} +@item +@code{"bts"}: Alias for @code{"btrace bts"} +@end itemize +@end defun + +@defun gdb.current_recording () +Access a currently running recording. Returns a @code{gdb.Record} +object on success. Returns @code{None} if no recording is currently +active. +@end defun + +@defun gdb.stop_recording () +Stops the current recording. Throws 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}. +@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}. +@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