[PATCH/doc] IPA protocol doc

[Yao Qi <yao at codesourcery dot com>]

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