[patch 5/8] Doc for agent

Yao Qi
2012-01-23T13:58:56Z

[-- Attachment #1: Type: text/plain, Size: 251 bytes --]

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 (é½å°§)

[-- Attachment #2: 0005-agent-doc.patch --]
[-- Type: text/x-patch, Size: 9114 bytes --]

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