Re: [patch 5/8] Doc for agent

[Yao Qi <yao at codesourcery dot com>]

On 01/24/2012 01:54 PM, Eli Zaretskii wrote:
>> > I remove this paragraph because it fits to the concept of tracepoint
>> > ("observer the program's behavior without interrupting it"), and the
>> > agent work can do more than that.
> What can it do in addition?  I don't think your new text said anything
> about that.
> 
>> > I don't mind putting it back at the
>> > the beginning of chapter "Debugging Agent" as another problem statement.
> I think it should be the only statement of the problem.  If the agent
> has additional benefits, their description should be added to the
> above text.

The agent has only one benefit so far, that is, reducing interference
with program during debugging.  However, I gave two problems at the
beginning, one is that program is wrong, but interference prevent
reproducing it, for example, races in threads.  The other is that
program is right, but interference changes its behavior and program
fails finally.  These two problems can be treated as a single problem,
from some point of view.  My previous reply might be misleading.

Here is a new doc patch.

-- 
Yao (éå)

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

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

diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
index d0f6f15..0cb0f1b 100644
--- a/gdb/doc/agentexpr.texi
+++ b/gdb/doc/agentexpr.texi
@@ -11,34 +11,55 @@
 @c
 @c See the file gdb.texinfo for copying conditions.
 
+@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
+the bug.  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.
+
+@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 the agent with @value{GDBN}, expressions in agent 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.
+
+When @value{GDBN} is debugging a target, the @value{GDBN} @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
+having a full symbolic expression evaluator on the agent, @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 GDB to retrieve later.
+bytecode, and records the values for @value{GDBN} 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 +77,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 +86,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 +221,7 @@ recorded.
 
 
 @node Bytecode Descriptions
-@section Bytecode Descriptions
+@subsection Bytecode Descriptions
 
 Each bytecode description has the following form:
 
@@ -503,7 +523,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 +573,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 +730,60 @@ opcode 0x30 reserved, to remain compatible with the customer who added
 it.
 
 @end table
+
+@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 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, @value{GDBN} needs a way to ask the target about itself.  We haven't worked
+out the details yet, but in general, @value{GDBN} 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