From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30197 invoked by alias); 7 Jun 2012 13:34:13 -0000 Received: (qmail 29367 invoked by uid 22791); 7 Jun 2012 13:34:12 -0000 X-SWARE-Spam-Status: No, hits=-2.5 required=5.0 tests=AWL,BAYES_00,FROM_12LTRDOM,KHOP_RCVD_UNTRUST,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; Thu, 07 Jun 2012 13:33:58 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1Sccqb-0007aR-8R from Yao_Qi@mentor.com for gdb-patches@sourceware.org; Thu, 07 Jun 2012 06:33:57 -0700 Received: from SVR-ORW-FEM-05.mgc.mentorg.com ([147.34.97.43]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Thu, 7 Jun 2012 06:33:26 -0700 Received: from localhost.localdomain (147.34.91.1) by svr-orw-fem-05.mgc.mentorg.com (147.34.97.43) with Microsoft SMTP Server id 14.1.289.1; Thu, 7 Jun 2012 06:33:55 -0700 From: Yao Qi To: Subject: [PATCH/doc] IPA protocol doc Date: Thu, 07 Jun 2012 13:34:00 -0000 Message-ID: <1339076026-31158-1-git-send-email-yao@codesourcery.com> MIME-Version: 1.0 Content-Type: text/plain 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/msg00214.txt.bz2 Hi, This patch is to document the protocol that GDB/GDBserver is using with IPA, which will be used when writing a 3rd party agent. gdb/doc: * gdb.texinfo (In-Process Agent Protocol): New appendix. --- gdb/doc/gdb.texinfo | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 157 insertions(+), 0 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 014cfd8..31a6439 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -178,6 +178,7 @@ software in general. We will miss him. the operating system * Trace File Format:: GDB trace file format * Index Section Format:: .gdb_index section format +* In-Process Agent Protocol:: In-Process Agent Protocol * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation @@ -37430,6 +37431,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 +37463,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 @@ -40225,6 +40229,159 @@ symbol. A string in the constant pool is zero-terminated. @end enumerate + +@node In-Process Agent Protocol +@appendix 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 chapter is to define the +protocol of this kind of communication. In general, @value{GDBN} or +GDBserver sends commands (@pxref{IPA Protocol Commands}) and data to +in-process agent, and then in-process agent replies data back to +represent the return result of the command, or some extra information. +The data sent to in-process agent is composed by primitive data types, +such as 4-byte or 8-byte type, and composite types, which are called +objects (@pxref{IPA Protocol Objects}). + +@menu +* Objects:IPA Protocol Objects: +* Commands:IPA Protocol Commands: +@end menu + +@node IPA Protocol Objects +@section Objects +The commands sent to and results received from agent may contain some +composed type of data, which is called @dfn{object}. Usually, object +is the unit to transfer composite data types in commands. + +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 machine, @value{GDBN} or GDBserver can be +compiled in 64-bit, while in-process agent is 32-bit. +@item ABI. Some machine 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 + +@itemize @bullet + +@item agent expression object +@anchor{agent expression object} +@multitable @columnfractions .10 .10 .80 +@headitem Name @tab Size @tab Description +@item length @tab 4 @tab length of bytes code +@item byte code @tab @var{length} @tab contents of byte code +@end multitable + +@item tracepoint action object +@anchor{tracepoint action object} + +@itemize @bullet +@item Tracepoint action for collecting memory +@multitable @columnfractions .10 .10 .80 +@headitem Type @tab Size @tab Description +@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. +@end multitable + +@item Tracepoint action for collecting registers +@multitable @columnfractions .10 .10 .80 +@headitem Type @tab Size @tab Description +@item 'R' @tab 1 @tab type of tracepoint action +@end multitable + +@item Tracepoint action for collecting static trace data +@multitable @columnfractions .10 .10 .80 +@headitem Type @tab Size @tab Description +@item 'L' @tab 1 @tab type of tracepoint action +@end multitable + +@item Tracepoint action for expression evaluation +@multitable @columnfractions .10 .10 .80 +@headitem Type @tab Size @tab Description +@item 'X' @tab 1 @tab type of tracepoint action +@item agent expression @tab length of @tab @ref{agent expression object} +@end multitable +@end itemize + +@item tracepoint object +@anchor{tracepoint object} +@multitable @columnfractions .15 .15 .70 +@headitem Name @tab Size @tab Description +@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 + +@end itemize + +@node IPA Protocol Commands +@section 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 jumppad. + +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 +@pxref{qTfSTM} +@item qTsSTM +@pxref{qTsSTM} +@item qTSTMat +@pxref{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 + @include gpl.texi @node GNU Free Documentation License -- 1.7.0.4