From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25796 invoked by alias); 23 Jan 2012 13:58:56 -0000 Received: (qmail 25787 invoked by uid 22791); 23 Jan 2012 13:58:54 -0000 X-SWARE-Spam-Status: No, hits=0.8 required=5.0 tests=AWL,BAYES_50,FROM_12LTRDOM X-Spam-Check-By: sourceware.org Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 23 Jan 2012 13:58:41 +0000 Received: from svr-orw-fem-01.mgc.mentorg.com ([147.34.98.93]) by relay1.mentorg.com with esmtp id 1RpKPw-0006Ih-N0 from Yao_Qi@mentor.com for gdb-patches@sourceware.org; Mon, 23 Jan 2012 05:58:40 -0800 Received: from SVR-ORW-FEM-05.mgc.mentorg.com ([147.34.97.43]) by svr-orw-fem-01.mgc.mentorg.com over TLS secured channel with Microsoft SMTPSVC(6.0.3790.4675); Mon, 23 Jan 2012 05:58:40 -0800 Received: from [127.0.0.1] (147.34.91.1) by svr-orw-fem-05.mgc.mentorg.com (147.34.97.43) with Microsoft SMTP Server id 14.1.289.1; Mon, 23 Jan 2012 05:58:38 -0800 Message-ID: <4F1D678B.2040705@codesourcery.com> Date: Mon, 23 Jan 2012 14:03:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:9.0) Gecko/20111220 Thunderbird/9.0 MIME-Version: 1.0 To: Subject: [patch 5/8] Doc for agent References: <4F1D55D7.7030506@codesourcery.com> In-Reply-To: <4F1D55D7.7030506@codesourcery.com> Content-Type: multipart/mixed; boundary="------------010708050502090908080509" X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-01/txt/msg00769.txt.bz2 --------------010708050502090908080509 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit Content-length: 245 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 (齐尧) --------------010708050502090908080509 Content-Type: text/x-patch; name="0005-agent-doc.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0005-agent-doc.patch" Content-length: 9114 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 --------------010708050502090908080509--