From: Tim Wiederhake <tim.wiederhake@intel.com>
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 [thread overview]
Message-ID: <1486989450-11313-10-git-send-email-tim.wiederhake@intel.com> (raw)
In-Reply-To: <1486989450-11313-1-git-send-email-tim.wiederhake@intel.com>
2017-02-13 Tim Wiederhake <tim.wiederhake@intel.com>
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
next prev parent reply other threads:[~2017-02-13 12:38 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-02-13 12:38 [PATCH v6 0/9] Python bindings for btrace recordings Tim Wiederhake
2017-02-13 12:38 ` [PATCH v6 2/9] btrace: Export btrace_decode_error function Tim Wiederhake
2017-02-13 12:38 ` [PATCH v6 1/9] btrace: Count gaps as one instruction explicitly Tim Wiederhake
2017-02-13 12:38 ` [PATCH v6 5/9] Add method to query current recording method to target_ops Tim Wiederhake
2017-02-13 12:38 ` Tim Wiederhake [this message]
2017-02-13 14:48 ` [PATCH v6 9/9] Add documentation for new record Python bindings Eli Zaretskii
2017-03-03 11:10 ` Yao Qi
2017-03-06 8:56 ` Wiederhake, Tim
2017-03-07 11:53 ` Yao Qi
2017-03-07 17:23 ` Wiederhake, Tim
2017-03-17 16:50 ` Yao Qi
2017-02-13 12:38 ` [PATCH v6 3/9] btrace: Use binary search to find instruction Tim Wiederhake
2017-02-13 12:38 ` [PATCH v6 6/9] python: Create Python bindings for record history Tim Wiederhake
2017-02-13 12:38 ` [PATCH v6 4/9] Add record_start and record_stop functions Tim Wiederhake
[not found] ` <1486989450-11313-8-git-send-email-tim.wiederhake@intel.com>
2017-02-13 17:03 ` [PATCH v6 7/9] python: Implement btrace Python bindings for record history Doug Evans
2017-02-13 17:12 ` Doug Evans
[not found] ` <1486989450-11313-9-git-send-email-tim.wiederhake@intel.com>
2017-02-13 17:17 ` [PATCH v6 8/9] python: Add tests for record Python bindings Doug Evans
2017-02-13 17:18 ` [PATCH v6 0/9] Python bindings for btrace recordings Doug Evans
2017-02-14 10:20 ` Wiederhake, Tim
2017-02-14 16:22 ` Doug Evans
2017-02-15 7:35 ` Wiederhake, Tim
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1486989450-11313-10-git-send-email-tim.wiederhake@intel.com \
--to=tim.wiederhake@intel.com \
--cc=gdb-patches@sourceware.org \
--cc=markus.t.metzger@intel.com \
--cc=palves@redhat.com \
--cc=xdje42@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).