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