gdb/doc/ 2012-01-26 Yao Qi * 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