[PATCH 4/9] agent doc

[Yao Qi <yao@codesourcery.com>]

Documentation bits.  Leave original contents of node "Agent Expressions" there, with
some minor updates.  A new node "Agent" is added.

gdb/doc/
2012-01-21  Yao Qi  <yao@codesourcery.com>

	* agentexpr.texi (Agent Expressions): Update some parts for agent expression
	can not only be used in agent, but also in remote stubs.
	Move some contents to ...
	* gdb.texinfo (Agent): ... to here.  New node.
---
 gdb/doc/agentexpr.texi |   35 +++++++++--------------------
 gdb/doc/gdb.texinfo    |   56 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 24 deletions(-)

diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
index d0f6f15..7075281 100644
--- a/gdb/doc/agentexpr.texi
+++ b/gdb/doc/agentexpr.texi
@@ -13,32 +13,19 @@
 
 @node Agent Expressions
 @appendix The GDB Agent Expression Mechanism
-
-In some applications, it is not feasible for the debugger to interrupt
-the program's execution long enough for the developer to learn anything
-helpful about its behavior.  If the program's correctness depends on its
-real-time behavior, delays introduced by a debugger might cause the
-program to fail, even when the code itself is correct.  It is useful to
-be able to observe the program's behavior without interrupting it.
-
-Using GDB's @code{trace} and @code{collect} commands, the user can
-specify locations in the program, and arbitrary expressions to evaluate
-when those locations are reached.  Later, using the @code{tfind}
-command, she can examine the values those expressions had when the
-program hit the trace points.  The expressions may also denote objects
-in memory --- structures or arrays, for example --- whose values GDB
-should record; while visiting a particular tracepoint, the user may
-inspect those objects as if they were in memory at that moment.
-However, because GDB records these values without interacting with the
-user, it can do so quickly and unobtrusively, hopefully not disturbing
-the program's behavior.
-
-When GDB is debugging a remote target, the GDB @dfn{agent} code running
+Agent expression will be used in many cases, such as the expressions used in tracepoints
+for data collection, and expressions used in breakpoint condition evaluation.  The
+expressions may also denote registers and objects in memory---structures or arrays, for
+example---whose values @value{GDBN} should record.  Originally, agent expressions are used
+in @dfn{agent} (@pxref{Agent}), so they are called @dfn{Agent Expression}.  Gradually,
+they are used more widely, such as in remote stub.
+
+When @value{GDBN} is debugging, the @value{GDBN} agent code running
 on the target computes the values of the expressions itself.  To avoid
-having a full symbolic expression evaluator on the agent, GDB translates
-expressions in the source language into a simpler bytecode language, and
-then sends the bytecode to the agent; the agent then executes the
-bytecode, and records the values for GDB to retrieve later.
+having a full symbolic expression evaluator on the agent or remote stub,
+@value{GDBN} translates expressions in the source language into a simpler bytecode
+language, and then sends the bytecode to the agent; the agent then executes the
+bytecode, and records the values for @value{GDBN} to retrieve later.
 
 The bytecode language is simple; there are forty-odd opcodes, the bulk
 of which are the usual vocabulary of C operands (addition, subtraction,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 34bf77e..a833f34 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -154,6 +154,7 @@ software in general.  We will miss him.
 * GDB/MI::                      @value{GDBN}'s Machine Interface.
 * Annotations::                 @value{GDBN}'s annotation interface.
 * JIT Interface::               Using the JIT debugging interface.
+* Agent::                       Debugging Agent
 
 * GDB Bugs::                    Reporting bugs in @value{GDBN}
 
@@ -32191,6 +32192,61 @@ frame and to write out the values of the registers in the previous
 frame.  Both have a callback (@code{target_read}) to read bytes off the
 target's address space.
 
+@node Agent
+@chapter Debugging Agent
+@cindex debugging agent
+The traditional debugging model is conceptually low-speed, but works fine,
+because most bugs can be reproduced in debugging-mode execution.  However,
+as multi-core or many-core processors are becoming mainstream, and
+multi-threaded programs become more and more popular, there should be more
+and more bugs that only manifest themselves at normal-mode execution, for
+example, thread races, because debugger's interference with the program's
+timing may conceal the bugs.  On the other hand, in some applications,
+it is not feasible for the debugger to interrupt the program's execution
+long enough for the developer to learn anything helpful about its behavior.
+If the program's correctness depends on its real-time behavior, delays
+introduced by a debugger might cause the program to fail, even when the
+code itself is correct.  It is useful to be able to observe the program's
+behavior without interrupting it.
+
+Therefore, traditional debugging model is too intrusive to reproduce
+some bugs.  In order to reduce the interference with the program, we can
+reduce the number of operations performed by debugger.  @dfn{Agent},
+a shared library, is running within the same process with inferior, and is
+able to perform some debugging operations itself.  As a result, debugger
+is only involved when necessary, and performance of debugging can be
+improved accordingly.  Note that interference with program can be
+reduced but can't be removed completely, because the agent will still stop
+or slow down the program.
+
+The agent can interpret and execute @dfn{Agent Expressions}
+(@pxref{Agent Expressions}) during performing debugging operations.  The
+agent expressions can be used for different purposes, such as collecting
+data in tracepoints, and condition evaluation in breakpoints.
+
+@menu
+* Control Agent::               Turn agent on and off
+@end menu
+@node Control Agent
+@section Turn Agent On And Off
+
+You can control whether the agent is used as an aid for debugging
+with the following commands:
+
+@table @code
+@item set agent on
+Causes the agent to perform some operations on behalf of the
+debugger.  Just which operations requested by the user will be done
+by the agent depends on the agent's capabilities.  For example, if
+you request to evaluate breakpoint conditions in the agent, and the
+agent has such capability as well, then breakpoint conditions will be
+evaluated in the agent.
+
+@item set agent off
+Disables execution of debugging operations by the agent.  All of the
+operations will be performed by @value{GDBN}.
+@end table
+
 @node GDB Bugs
 @chapter Reporting Bugs in @value{GDBN}
 @cindex bugs in @value{GDBN}
-- 
1.7.0.4