Re: [PATCH 4/9] agent doc

[Yao Qi <yao at codesourcery dot com>]

On 02/23/2012 04:25 AM, Pedro Alves wrote:
>> > I am inclined to leave this explanation there, as it is still useful to
>> > generic term "agent".
> Hmm, it still seems incorrect in the exact same way.
> 
>> > -When GDB is debugging a remote target, the GDB @dfn{agent} code running
>> > +Although called @dfn{agent expression}, because they originally
>> > +referred to the in-process agent (@pxref{In-Process Agent}), these
> Still false.  Looks unchanged compared to the previous version?
> 
>> > +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,
> This is still confused on agent vs in-process agent.  The remote stub is
> an agent as well; it does things for gdb (e.g., GDBserver supports tracepoints).
> Note the several references to "agent" on this whole paragraph.  I suggest
> really just leave this paragraph as it was.
> 
>> > +@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.
> We lost the intro about tracepoints, so this mention of recording values
> for gdb to retrieve later is now awkward.

Pedro,
It gets my hand dirty to try to distinguish "agent" vs. "in-process
agent" in appendix "Agent Expression", so I removed all the changes in
doc/agentexpr.texi, to leave it as it was.

Same as previous version, a node "In-Process Agent" is added, to
describe what is it, and how to control it.  Mention that "in-process
agent can interpret and execute Agent Expressions" only to avoid the
confusion on "agent" vs. "in-process agent", hopefully.

If this version is still not what you want, or confusing to you, please
give me an outline of this part, I've ran out of my brainpower. :)

-- 
Yao (éå)

gdb/doc/
      * gdb.texinfo (In-Process Agent): New node.
      Document new commands.
---
 gdb/doc/gdb.texinfo |   58 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 58 insertions(+), 0 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 34bf77e..0eb3811 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.
+* In-Process Agent::            In-Process Agent
 
 * GDB Bugs::                    Reporting bugs in @value{GDBN}
 
@@ -32191,6 +32192,63 @@ 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 In-Process Agent
+@chapter In-Process Agent
+@cindex in-process 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.  The
+@dfn{In-Process 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 in-process agent will still stop or slow down the program.
+
+The in-process agent can interpret and execute 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.
+
+@anchor{Control Agent}
+You can control whether the in-process agent is used as an aid for
+debugging with the following commands:
+
+@table @code
+@kindex set agent on
+@item set agent on
+Causes the in-process agent to perform some operations on behalf of the
+debugger.  Just which operations requested by the user will be done
+by the in-process agent depends on the its capabilities.  For example,
+if you request to evaluate breakpoint conditions in the in-process agent,
+and the in-process agent has such capability as well, then breakpoint
+conditions will be evaluated in the in-process agent.
+
+@kindex set agent off
+@item set agent off
+Disables execution of debugging operations by the in-process agent.  All
+of the operations will be performed by @value{GDBN}.
+
+@kindex show agent
+@item show agent
+Display the current setting of execution of debugging operations by
+the in-process agent.
+@end table
+
 @node GDB Bugs
 @chapter Reporting Bugs in @value{GDBN}
 @cindex bugs in @value{GDBN}
-- 
1.7.0.4