From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 26900 invoked by alias); 8 Jun 2012 06:04:23 -0000 Received: (qmail 26880 invoked by uid 22791); 8 Jun 2012 06:04:21 -0000 X-SWARE-Spam-Status: No, hits=-4.3 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,KHOP_THREADED,RCVD_IN_HOSTKARMA_W,RCVD_IN_HOSTKARMA_WL X-Spam-Check-By: sourceware.org Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 08 Jun 2012 06:04:07 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1ScsIo-0001mD-8B from Yao_Qi@mentor.com ; Thu, 07 Jun 2012 23:04:06 -0700 Received: from SVR-ORW-FEM-02.mgc.mentorg.com ([147.34.96.206]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Thu, 7 Jun 2012 23:03:34 -0700 Received: from [127.0.0.1] (147.34.91.1) by svr-orw-fem-02.mgc.mentorg.com (147.34.96.168) with Microsoft SMTP Server id 14.1.289.1; Thu, 7 Jun 2012 23:04:03 -0700 Message-ID: <4FD195CA.7060607@codesourcery.com> Date: Fri, 08 Jun 2012 06:04:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:12.0) Gecko/20120430 Thunderbird/12.0.1 MIME-Version: 1.0 To: Eli Zaretskii CC: Subject: Re: [PATCH/doc] IPA protocol doc References: <1339076026-31158-1-git-send-email-yao@codesourcery.com> <83y5nzukr6.fsf@gnu.org> In-Reply-To: <83y5nzukr6.fsf@gnu.org> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit 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-06/txt/msg00221.txt.bz2 On 06/08/2012 12:53 AM, Eli Zaretskii wrote: >> > gdb/doc: >> > * gdb.texinfo (In-Process Agent Protocol): New appendix. > I wonder whether it would be better to make this a section of the > "In-Process Agent" chapter, rather than an appendix. Any reasons not > to do that? > I noticed that "Remote Protocol" exist in document as an appendix, so I made it an appendix as well. I agree with you, and move it to a section of "In-Process Agent". This new patch address all the problems you pointed out. Is it OK? -- Yao (齐尧) gdb/doc: * gdb.texinfo (In-Process Agent): Add 'In-Process Agent Protocol'. (Tracepoint Packets): Add anchors. --- gdb/doc/gdb.texinfo | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 153 insertions(+), 0 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 014cfd8..dd5f449 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -33447,6 +33447,156 @@ Display the current setting of execution of debugging operations by the in-process agent. @end table +@menu +* In-Process Agent Protocol:: +@end menu + +@node In-Process Agent Protocol +@section In-Process Agent Protocol +@cindex in-process agent protocol + +The in-process agent is able to communicate with both @value{GDBN} and +GDBserver (@pxref{In-Process Agent}). This section documents the protocol +used for communications between @value{GDBN} or GDBserver and the IPA. +In general, @value{GDBN} or GDBserver sends commands +(@pxref{IPA Protocol Commands}) and data to in-process agent, and then +in-process agent replies back with the return result of the command, or +some other information. The data sent to in-process agent is composed +of primitive data types, such as 4-byte or 8-byte type, and composite +types, which are called objects (@pxref{IPA Protocol Objects}). + +@menu +* IPA Protocol Objects:: +* IPA Protocol Commands:: +@end menu + +@node IPA Protocol Objects +@subsection IPA Protocol Objects +@cindex ipa protocol objects + +The commands sent to and results received from agent may contain some +complex data types called @dfn{objects}. + +The in-process agent is running on the same machine with @value{GDBN} +or GDBserver, so it doesn't have to handle as much differences between +two ends as remote protocol (@pxref{Remote Protocol}) tries to handle. +However, there are still some differences of two ends in two processes: + +@enumerate +@item +word size. On some 64-bit machines, @value{GDBN} or GDBserver can be +compiled as a 64-bit executable, while in-process agent is a 32-bit one. +@item +ABI. Some machines may have multiple types of ABI, @value{GDBN} or +GDBserver is compiled with one, and in-process agent is compiled with +the other one. +@end enumerate + +Here are the IPA Protocol Objects: + +@enumerate +@item +agent expression object. It represents an agent expression +(@pxref{Agent Expressions}). +@anchor{agent expression object} +@item +tracepoint action object. It represents a tracepoint action +(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers, +memory, static trace data and to evaluate expression. +@anchor{tracepoint action object} +@item +tracepoint object. It represents a tracepoint (@pxref{Tracepoints}). +@anchor{tracepoint object} + +@end enumerate + +@multitable @columnfractions .30 .20 .50 +@headitem Name @tab Size @tab Description +@item @emph{agent expression object} @tab @tab +@item length @tab 4 @tab length of bytes code +@item byte code @tab @var{length} @tab contents of byte code +@item @emph{tracepoint action for collecting memory} @tab @tab +@item 'M' @tab 1 @tab type of tracepoint action +@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the +address of the lowest byte to collect, otherwise @var{addr} is the offset +of @var{basereg} for memory collecting. +@item len @tab 8 @tab length of memory for collecting +@item basereg @tab 4 @tab the register number containing the starting +memory address for collecting. +@item @emph{tracepoint action for collecting registers} @tab @tab +@item 'R' @tab 1 @tab type of tracepoint action +@item @emph{tracepoint action for collecting static trace data} @tab @tab +@item 'L' @tab 1 @tab type of tracepoint action +@item @emph{tracepoint action for expression evaluation} @tab @tab +@item 'X' @tab 1 @tab type of tracepoint action +@item agent expression @tab length of @tab @ref{agent expression object} +@item @emph{tracepoint object} @tab @tab +@item number @tab 4 @tab number of tracepoint +@item address @tab 8 @tab address of tracepoint inserted on +@item type @tab 4 @tab type of tracepoint +@item enabled @tab 1 @tab enable or disable of tracepoint +@item step_count @tab 8 @tab step +@item pass_count @tab 8 @tab pass +@item numactions @tab 4 @tab number of tracepoint actions +@item hit count @tab 8 @tab hit count +@item trace frame usage @tab 8 @tab trace frame usage +@item compiled_cond @tab 8 @tab compiled condition +@item orig_size @tab 8 @tab orig size +@item condition @tab 4 if condition is NULL otherwise length of +@ref{agent expression object} +@tab zero if condition is NULL, otherwise is +@ref{agent expression object} +@item actions @tab variable +@tab numactions number of @ref{tracepoint action object} +@end multitable + +@node IPA Protocol Commands +@subsection IPA Protocol Commands +@cindex ipa protocol commands + +The spaces in each command are delimiters to ease reading this commands +specification. They don't exist in real commands. + +@table @samp + +@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head} +Installs a new fast tracepoint described by @var{tracepoint_object} +(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the +head of @dfn{jumppad}, which is used to jump to data collection routine +in IPA finally. + +Replies: +@table @samp +@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump} +@var{target_address} is address of tracepoint in the inferior. +@var{gdb_jump_pad_head} is updated head of jumppad. Both of +@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. +@var{fjump} contains a sequence of instructions jump to jumppad entry. +@var{fjump_size}, 4-byte long, is the size of @var{fjump}. +@item E @var{NN} +for an error + +@end table + +@item qTfSTM +@xref{qTfSTM}. +@item qTsSTM +@xref{qTsSTM}. +@item qTSTMat +@xref{qTSTMat}. +@item probe_marker_at:@var{address} +Asks in-process agent to probe the marker at @var{address}. + +Replies: +@table @samp +@item E @var{NN} +for an error +@end table +@item unprobe_marker_at:@var{address} +Asks in-process agent to unprobe the marker at @var{address}. +@end table + @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} @cindex bugs in @value{GDBN} @@ -37430,6 +37580,8 @@ trace state variables. @item qTfSTM @itemx qTsSTM +@anchor{qTfSTM} +@anchor{qTsSTM} These packets request data about static tracepoint markers that exist in the target program. @value{GDBN} sends @code{qTfSTM} to get the first piece of data, and multiple @code{qTsSTM} to get additional @@ -37460,6 +37612,7 @@ query), until the target responds with @samp{l} (lower-case ell, for @dfn{last}). @item qTSTMat:@var{address} +@anchor{qTSTMat} This packets requests data about static tracepoint markers in the target program at @var{address}. Replies to this packet follow the syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static -- 1.7.0.4