This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH 4/9] agent doc
On 02/22/2012 01:26 AM, Pedro Alves wrote:
> On 02/20/2012 02:40 AM, Yao Qi wrote:
>
>> -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
>
> That's incorrect. Agent expressions existed long before the in-process
> agent was invented. See the confusion about calling the new IPA thing
> just "agent"?
>
I didn't realize "agent" was introduced back in 1999, long before IPA
was created.
> From agentexpr.texi:
>
> When GDB is debugging a remote 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.
> (...) The interpreter is
> small, and strict limits on the memory and time required to evaluate an
> expression are easy to determine, making it suitable for use by the
> debugging agent in real-time applications.
>
> So nothing mentioned here about in-process or not. This applies all the
> same to the agent expression mechinary in GDBserver (tracepoints, etc.).
> That's an agent as well. "agent" is a very loose term for roughly something
> that runs on the remote target on GDB's behalf. Can we just drop that
> explanation? If we name things clearly then that's unnecessary.
>
I am inclined to leave this explanation there, as it is still useful to
generic term "agent".
> So I'd suggest also:
>
> On 02/20/2012 02:40 AM, Yao Qi wrote:
>> +reduce the number of operations performed by debugger. @dfn{Agent},
>
> the in-process agent
>
s/agent/in-process agent/ in my patch.
--
Yao (éå)
gdb/doc/
2012-02-22 Yao Qi <yao@codesourcery.com>
* agentexpr.texi (Agent Expressions): Update some parts for agent expression
can not only be used in in-process agent, but also in remote stubs.
Move some contents to ...
* gdb.texinfo (In-Process Agent): ... to here. New node.
Document new commands.
---
gdb/doc/agentexpr.texi | 37 ++++++++++-------------------
gdb/doc/gdb.texinfo | 58 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 71 insertions(+), 24 deletions(-)
diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
index d0f6f15..65e4423 100644
--- a/gdb/doc/agentexpr.texi
+++ b/gdb/doc/agentexpr.texi
@@ -13,32 +13,21 @@
@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
+Although called @dfn{agent expression}, because they originally
+referred to the in-process agent (@pxref{In-Process Agent}), these
+expressions can be used in conjunction with many unrelated @value{GDBN}
+features, such as expressions used in tracepoints for data collection,
+expressions used in breakpoint condition evaluation, etc. Note that 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, 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..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 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. 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