[patch v5 07/12] btrace, doc: document remote serial protocol

[markus dot t dot metzger at intel dot com]

From: Markus Metzger <markus.t.metzger@intel.com>

Document the extensions to the remote serial protocol for supporting branch tracing.

2012-12-07 Markus Metzger <markus.t.metzger@intel.com>

doc/
	* gdb.texinfo (Requirements): List qXfer:btrace:read requiring expat.
	(General Query Packets): Describe qbtrace, Qbtrace, and qXfer:btrace:read.


---
 gdb/doc/gdb.texinfo |  125 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 125 insertions(+), 0 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9ffdb77..6ce34e3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -34468,6 +34468,8 @@ or alternatively @pxref{Library List Format for SVR4 Targets})
 MS-Windows shared libraries (@pxref{Shared Libraries})
 @item
 Traceframe info (@pxref{Traceframe Info Format})
+@item
+Branch trace (@pxref{Branch Trace Format})
 @end itemize
 
 @item zlib
@@ -35329,6 +35331,7 @@ Show the current setting of the target wait timeout.
 * Memory Map Format::
 * Thread List Format::
 * Traceframe Info Format::
+* Branch Trace Format::
 @end menu
 
 @node Overview
@@ -36958,11 +36961,21 @@ These are the currently defined stub features and their properties:
 @tab @samp{-}
 @tab No
 
+@item @samp{qbtrace}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @item @samp{qXfer:auxv:read}
 @tab No
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:btrace:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @item @samp{qXfer:features:read}
 @tab No
 @tab @samp{-}
@@ -37023,6 +37036,11 @@ These are the currently defined stub features and their properties:
 @tab @samp{-}
 @tab Yes
 
+@item @samp{Qbtrace}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
 @item @samp{QNonStop}
 @tab No
 @tab @samp{-}
@@ -37118,6 +37136,10 @@ byte in its buffer for the NUL.  If this stub feature is not supported,
 The remote stub understands the @samp{qXfer:auxv:read} packet
 (@pxref{qXfer auxiliary vector read}).
 
+@item qXfer:btrace:read
+The remote stub understands the @samp{qXfer:btrace:read}
+packet (@pxref{qXfer btrace read}).
+
 @item qXfer:features:read
 The remote stub understands the @samp{qXfer:features:read} packet
 (@pxref{qXfer target description read}).
@@ -37252,6 +37274,12 @@ See @ref{Bytecode Descriptions} for details about the bytecode.
 The remote stub supports running a breakpoint's command list itself,
 rather than reporting the hit to @value{GDBN}.
 
+@item qbtrace
+The remote stub understands the @samp{qbtrace} packet.
+
+@item Qbtrace
+The remote stub understands the @samp{Qbtrace} packet.
+
 @end table
 
 @item qSymbol::
@@ -37370,6 +37398,18 @@ auxiliary vector}.  Note @var{annex} must be empty.
 This packet is not probed by default; the remote stub must request it,
 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
 
+@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer btrace read}
+
+Return a description of the current branch trace.
+@xref{Branch Trace Format}.  The annex part of the generic @samp{qXfer}
+packet contains the thread id (see @ref{thread-id syntax}) for which
+branch trace is to be read (@pxref{qXfer read}). The thread id must
+specify a single thread.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
 @item qXfer:features:read:@var{annex}:@var{offset},@var{length}
 @anchor{qXfer target description read}
 Access the @dfn{target description}.  @xref{Target Descriptions}.  The
@@ -37606,6 +37646,41 @@ The remote server created a new process.
 A badly formed request or an error was encountered.
 @end table
 
+@item qbtrace
+Return whether new branch trace data is available for the current thread.
+
+Reply:
+@table @samp
+@item yes
+New branch trace data is available.
+@item no
+No new branch trace data is available.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
+@item Qbtrace:on
+Enable branch tracing for the current thread.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been enabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
+@item Qbtrace:off
+Disable branch tracing for the current thread.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been disabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
 @end table
 
 @node Architecture-Specific Protocol Details
@@ -40022,6 +40097,56 @@ The formal DTD for the traceframe info format is given below:
                         length  CDATA   #REQUIRED>
 @end smallexample
 
+@node Branch Trace Format
+@section Branch Trace Format
+@cindex branch trace format
+
+In order to display the branch trace of an inferior thread,
+@value{GDBN} needs to obtain the list of branches. This list is
+represented as list of sequential code blocks that are connected via
+branches. The code in each block has been executed sequentially.
+
+This list is obtained using the @samp{qXfer:btrace:read}
+(@pxref{qXfer btrace read}) packet and is an XML document.
+
+@value{GDBN} must be linked with the Expat library to support XML
+traceframe info discovery.  @xref{Expat}.
+
+The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE btrace
+          PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
+                 "http://sourceware.org/gdb/gdb-btrace.dtd";>
+<btrace>
+   block...
+</btrace>
+@end smallexample
+
+@itemize
+
+@item
+A block of sequentially executed instructions starting at @var{begin}
+and ending at @var{end}:
+
+@smallexample
+<block begin="@var{begin}" end="@var{end}"/>
+@end smallexample
+
+@end itemize
+
+The formal DTD for the traceframe info format is given below:
+
+@smallexample
+<!ELEMENT btrace  (block)* >
+<!ATTLIST btrace  version CDATA   #FIXED "1.0">
+
+<!ELEMENT block        EMPTY>
+<!ATTLIST block        begin  CDATA   #REQUIRED
+                       end    CDATA   #REQUIRED>
+@end smallexample
+
 @include agentexpr.texi
 
 @node Target Descriptions
-- 
1.7.1