[patch 5/8] Doc for agent

[Yao Qi <yao at codesourcery dot com>]

In this patch, we create a new chapter for agent, and put "Agent
Expression" under this chapter.  One section "Control Agent" is added to
document command in patch 3/8, and the rest of them is from original
"Agent Expression".

-- 
Yao (éå)

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

	* agentexpr.texi: Re-structure doc for agent.
	* gdb.texinfo: Move chapeter `Agent Expression' to `Agent'.
---
 gdb/doc/agentexpr.texi |  159 ++++++++++++++++++++++++++++--------------------
 gdb/doc/gdb.texinfo    |    2 +-
 2 files changed, 94 insertions(+), 67 deletions(-)

diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
index d0f6f15..e06ab20 100644
--- a/gdb/doc/agentexpr.texi
+++ b/gdb/doc/agentexpr.texi
@@ -11,34 +11,43 @@
 @c
 @c See the file gdb.texinfo for copying conditions.
 
+@node Agent
+@chapter Debugging Agent
+The traditional debugging model is conceptually low-speed, but works fine,
+because most of bugs can be reproduced in low-speed execution.  However,
+as multi-core or many-core processor is becoming mainstream, and
+multi-threaded program becomes more and more popular, there should be more
+and more bugs that only manifest themselves at full speed, for example, thread
+races.  Therefore, traditional debugging model is too intrusive to reproduce
+the bug.  In order to overcome the interference, we should reduce the number of
+operations debugger performed.  @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.
+
+
+@menu
+* Agent Expressions::	The GDB Agent Expression Mechanism
+* Control Agent::       Turn agent on and off
+* Varying Target Capabilities:: How to discover what the target can do
+@end menu
+
 @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
+@section The GDB Agent Expression Mechanism
+
+When using agent with @value{GDBN}, expression in agent will be used in many cases,
+such as the expressions used in tracepoint 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.
+
+When GDB is debugging a target, the GDB @dfn{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.
+bytecode, and records the values for GDB to retrieve later.  We call these bytecode
+@dfn{Agent Expression}.
 
 The bytecode language is simple; there are forty-odd opcodes, the bulk
 of which are the usual vocabulary of C operands (addition, subtraction,
@@ -56,7 +65,6 @@ debugging agent in real-time applications.
 * General Bytecode Design::     Overview of the interpreter.
 * Bytecode Descriptions::       What each one does.
 * Using Agent Expressions::     How agent expressions fit into the big picture.
-* Varying Target Capabilities:: How to discover what the target can do.
 * Rationale::                   Why we did it this way.
 @end menu
 
@@ -66,7 +74,7 @@ debugging agent in real-time applications.
 
 
 @node General Bytecode Design
-@section General Bytecode Design
+@subsection General Bytecode Design
 
 The agent represents bytecode expressions as an array of bytes.  Each
 instruction is one byte long (thus the term @dfn{bytecode}).  Some
@@ -201,7 +209,7 @@ recorded.
 
 
 @node Bytecode Descriptions
-@section Bytecode Descriptions
+@subsection Bytecode Descriptions
 
 Each bytecode description has the following form:
 
@@ -503,7 +511,7 @@ address, and the top of the stack is the lvalue's size, in bytes.
 
 
 @node Using Agent Expressions
-@section Using Agent Expressions
+@subsection Using Agent Expressions
 
 Agent expressions can be used in several different ways by @value{GDBN},
 and the debugger can generate different bytecode sequences as appropriate.
@@ -553,46 +561,8 @@ reports an error.
 
 @end itemize
 
-
-@node Varying Target Capabilities
-@section Varying Target Capabilities
-
-Some targets don't support floating-point, and some would rather not
-have to deal with @code{long long} operations.  Also, different targets
-will have different stack sizes, and different bytecode buffer lengths.
-
-Thus, GDB needs a way to ask the target about itself.  We haven't worked
-out the details yet, but in general, GDB should be able to send the
-target a packet asking it to describe itself.  The reply should be a
-packet whose length is explicit, so we can add new information to the
-packet in future revisions of the agent, without confusing old versions
-of GDB, and it should contain a version number.  It should contain at
-least the following information:
-
-@itemize @bullet
-
-@item
-whether floating point is supported
-
-@item
-whether @code{long long} is supported
-
-@item
-maximum acceptable size of bytecode stack
-
-@item
-maximum acceptable length of bytecode expressions
-
-@item
-which registers are actually available for collection
-
-@item
-whether the target supports disabled tracepoints
-
-@end itemize
-
 @node Rationale
-@section Rationale
+@subsection Rationale
 
 Some of the design decisions apparent above are arguable.
 
@@ -748,3 +718,60 @@ opcode 0x30 reserved, to remain compatible with the customer who added
 it.
 
 @end table
+
+@node Control Agent
+@section Turn agent on and off
+
+As a helper of debugging, agent should be turned on and off by user, which
+can be done with the following commands:
+
+@table @code
+@item set agent on
+Causes agent may execute some debugging operations, which is determined by
+actual debugging request from users and by the capability of agent.  For
+example, if user request to evaluate breakpoint conditions in agent, and
+agent has such capability as well, then breakpoint conditions will be
+evaluated in agent.
+
+@item set agent off
+Causes agent not execute any debugging operations.  All of them should be
+performed in @value{GDBN}.
+
+@end table
+
+@node Varying Target Capabilities
+@section Varying Target Capabilities
+
+Some targets don't support floating-point, and some would rather not
+have to deal with @code{long long} operations.  Also, different targets
+will have different stack sizes, and different bytecode buffer lengths.
+
+Thus, GDB needs a way to ask the target about itself.  We haven't worked
+out the details yet, but in general, GDB should be able to send the
+target a packet asking it to describe itself.  The reply should be a
+packet whose length is explicit, so we can add new information to the
+packet in future revisions of the agent, without confusing old versions
+of GDB, and it should contain a version number.  It should contain at
+least the following information:
+
+@itemize @bullet
+
+@item
+whether floating point is supported
+
+@item
+whether @code{long long} is supported
+
+@item
+maximum acceptable size of bytecode stack
+
+@item
+maximum acceptable length of bytecode expressions
+
+@item
+which registers are actually available for collection
+
+@item
+whether the target supports disabled tracepoints
+
+@end itemize
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c4763d4..810dc3c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -170,7 +170,7 @@ software in general.  We will miss him.
 * Installing GDB::              Installing GDB
 * Maintenance Commands::        Maintenance Commands
 * Remote Protocol::             GDB Remote Serial Protocol
-* Agent Expressions::           The GDB Agent Expression Mechanism
+* Agent::                       Debugging Agent
 * Target Descriptions::         How targets can describe themselves to
                                 @value{GDBN}
 * Operating System Information:: Getting additional information from
-- 
1.7.0.4