From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14663 invoked by alias); 17 Dec 2012 16:02:48 -0000 Received: (qmail 14479 invoked by uid 22791); 17 Dec 2012 16:02:43 -0000 X-SWARE-Spam-Status: No, hits=-7.8 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,KHOP_THREADED,RCVD_IN_DNSWL_HI,RCVD_IN_HOSTKARMA_W,TW_QB,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mga11.intel.com (HELO mga11.intel.com) (192.55.52.93) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 17 Dec 2012 16:02:27 +0000 Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga102.fm.intel.com with ESMTP; 17 Dec 2012 08:02:05 -0800 X-ExtLoop1: 1 Received: from swsutil001.isw.intel.com ([10.237.237.11]) by fmsmga002.fm.intel.com with ESMTP; 17 Dec 2012 08:01:57 -0800 Received: from ulslx001.iul.intel.com (ulslx001.iul.intel.com [172.28.207.63]) by swsutil001.isw.intel.com (8.13.6/8.13.6/MailSET/Hub) with ESMTP id qBHG1t7c019698; Mon, 17 Dec 2012 16:01:56 GMT Received: from ulslx001.iul.intel.com (localhost [127.0.0.1]) by ulslx001.iul.intel.com with ESMTP id qBHG1tbo026525; Mon, 17 Dec 2012 17:01:55 +0100 Received: (from mmetzger@localhost) by ulslx001.iul.intel.com with id qBHG1tJf026521; Mon, 17 Dec 2012 17:01:55 +0100 From: markus.t.metzger@intel.com To: jan.kratochvil@redhat.com, palves@redhat.com, tromey@redhat.com, kettenis@gnu.org Cc: gdb-patches@sourceware.org, markus.t.metzger@gmail.com, Markus Metzger Subject: [patch v6 07/12] btrace, doc: document remote serial protocol Date: Mon, 17 Dec 2012 16:03:00 -0000 Message-Id: <1355760101-26237-8-git-send-email-markus.t.metzger@intel.com> In-Reply-To: <1355760101-26237-1-git-send-email-markus.t.metzger@intel.com> References: <1355760101-26237-1-git-send-email-markus.t.metzger@intel.com> X-IsSubscribed: yes 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 X-SW-Source: 2012-12/txt/msg00569.txt.bz2 From: Markus Metzger Document the extensions to the remote serial protocol for supporting branch tracing. This patch has been reviewed and approved by Eli Zaretskii. 2012-12-17 Markus Metzger 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 5abcd93..66cff6f 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -34561,6 +34561,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 @@ -35422,6 +35424,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 @@ -37051,11 +37054,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{-} @@ -37116,6 +37129,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{-} @@ -37211,6 +37229,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}). @@ -37345,6 +37367,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:: @@ -37463,6 +37491,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 (@pxref{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 @@ -37699,6 +37739,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 @@ -40115,6 +40190,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 + + + + block... + +@end smallexample + +@itemize + +@item +A block of sequentially executed instructions starting at @var{begin} +and ending at @var{end}: + +@smallexample + +@end smallexample + +@end itemize + +The formal DTD for the branch trace format is given below: + +@smallexample + + + + + +@end smallexample + @include agentexpr.texi @node Target Descriptions -- 1.7.6.5