[PATCH/doc] IPA protocol doc

[PATCH/doc] IPA protocol doc

[Yao Qi]

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

Re: [PATCH/doc] IPA protocol doc

[Eli Zaretskii]

> From: Yao Qi <yao@codesourcery.com>
> Date: Thu, 7 Jun 2012 21:33:46 +0800
> 
> This patch is to document the protocol that GDB/GDBserver is using
> with IPA, which will be used when writing a 3rd party agent.
> 

Thanks.

> 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?

In any case, please mention all the new nodes in the log entry, not
just their parent.

> +                                       This chapter is to define the
> +protocol of this kind of communication.

 "This chapter documents the protocol used for communications between
 GDBserver and the IPA."

(If you move this to the chapter I suggest above, use "section" rather
than "chapter" in this sentence.)

> +in-process agent, and then in-process agent replies data back to
> +represent the return result of the command, or some extra information.

 "...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 by primitive data types,
                                                 ^^
"of"

> +@menu
> +* Objects:IPA Protocol Objects:
> +* Commands:IPA Protocol Commands:
> +@end menu

Please format this @menu as we do with other menus in the Texinfo
source.

> +@node IPA Protocol Objects
> +@section Objects

A @cindex entry here would be useful.  You can use the node name, just
lower-case all the words.

Also, a section name such as "Objects" is too general; why not "IPA
Protocol Objects"?

> +The commands sent to and results received from agent may contain some
> +composed type of data, which is called @dfn{object}.

 "...may contain some complex data types called @dfn{objects}."

> +                                                      Usually, object

 "Usually, an object"

> +is the unit to transfer composite data types in commands.

This sentence sounds redundant: didn't you already said precisely that
in the previous one?

> +However, there are still some differences of two ends in two processes,
                                                                         ^
A colon ':' here

> +@enumerate

Please leave an empty line before @enumerate

> +@item word size. On some 64-bit machine, @value{GDBN} or GDBserver can be
                  ^^               ^^^^^^^
Two spaces, please, and "machines" in plural.  Also, please make all
the @item's in the enumeration a separate line, like this:

  @item
  Word size.  On some 64-bit machines, ...

> +compiled in 64-bit, while in-process agent is 32-bit.
   ^^^^^^^^^^^^^^^^^^
 "compiled as a 64-bit executable"

> +@item ABI.  Some machine may have multiple types of ABI, @value{GDBN} or
                    ^^^^^^^
 "machines"

This itemized list could use a sentence or two of introductory text,
explaining what you are about to describe.

> +@itemize @bullet
> +
> +@item agent expression object

Here, too, "@item" should be on a line by itself.  (Only in a @table
or a @multitable we put text on the same line as the @item.)

> +@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

I don't think having a @multitable interspersed with an @itemize (and
nested @itemize on top of that) is a good idea.  What does it gain us?

I'd prefer if you first enumerate all the objects in a single list
(and say a sentence or two about each one, e.g. what is it used for),
and then have a single @multitable with the attributes of all of them.

> +@node IPA Protocol Commands
> +@section Commands

Again, a @cindex entry would be good here.

> +@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.

Should we tell what is a "jumppad"?

> +@item qTfSTM
> +@pxref{qTfSTM}
> +@item qTsSTM
> +@pxref{qTsSTM}
> +@item qTSTMat
> +@pxref{qTSTMat}

You want @xref here, not @pxref (the latter is only appropriate in
parentheses in the middle of a sentence).

Thanks.

Re: [PATCH/doc] IPA protocol doc

[Yao Qi]

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

Re: [PATCH/doc] IPA protocol doc

[Eli Zaretskii]

> Date: Fri, 8 Jun 2012 14:03:54 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> This new patch address all the problems you pointed out.  Is it OK?

Yes, with two comments:

> gdb/doc:
> 	* gdb.texinfo (In-Process Agent): Add 'In-Process Agent
> 	Protocol'.
> 	(Tracepoint Packets): Add anchors.

Please mention here all the new nodes you added, like this:

	(In-Process Agent Protocol, IPA Protocol Objects)
	(IPA Protocol Commands): New nodes.

> +@multitable @columnfractions .30 .20 .50
> +@headitem Name @tab Size @tab Description
> +@item @emph{agent expression object} @tab @tab

Please add a short description of this table, something like this:

  The following table describes important attributes of each IPA
  object:

OK with these changes.

Thanks.