From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2749 invoked by alias); 13 Feb 2017 12:38:18 -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 2650 invoked by uid 89); 13 Feb 2017 12:38:17 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=2.0 required=5.0 tests=AWL,BAYES_60,KAM_LAZY_DOMAIN_SECURITY,RP_MATCHES_RCVD autolearn=no version=3.3.2 spammy=rdseed, rdrand, timwiederhakeintelcom, tim.wiederhake@intel.com X-HELO: mga04.intel.com Received: from mga04.intel.com (HELO mga04.intel.com) (192.55.52.120) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 13 Feb 2017 12:38:14 +0000 Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 13 Feb 2017 04:38:12 -0800 X-ExtLoop1: 1 Received: from irvmail001.ir.intel.com ([163.33.26.43]) by fmsmga002.fm.intel.com with ESMTP; 13 Feb 2017 04:38:10 -0800 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 v1DCcABs010250; Mon, 13 Feb 2017 12:38:10 GMT Received: from ulvlx001.iul.intel.com (localhost [127.0.0.1]) by ulvlx001.iul.intel.com with ESMTP id v1DCcAfN011635; Mon, 13 Feb 2017 13:38:10 +0100 Received: (from twiederh@localhost) by ulvlx001.iul.intel.com with œ id v1DCc9Pk011631; Mon, 13 Feb 2017 13:38:09 +0100 From: Tim Wiederhake To: gdb-patches@sourceware.org Cc: markus.t.metzger@intel.com, palves@redhat.com, xdje42@gmail.com Subject: [PATCH v6 9/9] Add documentation for new record Python bindings. Date: Mon, 13 Feb 2017 12:38:00 -0000 Message-Id: <1486989450-11313-10-git-send-email-tim.wiederhake@intel.com> In-Reply-To: <1486989450-11313-1-git-send-email-tim.wiederhake@intel.com> References: <1486989450-11313-1-git-send-email-tim.wiederhake@intel.com> X-IsSubscribed: yes X-SW-Source: 2017-02/txt/msg00329.txt.bz2 2017-02-13 Tim Wiederhake gdb/ChangeLog: * NEWS: Add record Python bindings entry. gdb/doc/ChangeLog: * python.texi (Recordings In Python): New section. --- gdb/NEWS | 4 + gdb/doc/python.texi | 245 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 249 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index 08f97c0..f412887 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 fae45aa..d1cbadb 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.7.4