From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 11329 invoked by alias); 17 Feb 2012 02:56:51 -0000 Received: (qmail 11257 invoked by uid 22791); 17 Feb 2012 02:56:47 -0000 X-SWARE-Spam-Status: No, hits=-0.3 required=5.0 tests=AWL,BAYES_20,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; Fri, 17 Feb 2012 02:56:32 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1RyDzr-0004Oj-Sg from Yao_Qi@mentor.com for gdb-patches@sourceware.org; Thu, 16 Feb 2012 18:56:31 -0800 Received: from SVR-ORW-FEM-03.mgc.mentorg.com ([147.34.97.39]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Thu, 16 Feb 2012 18:55:46 -0800 Received: from localhost.localdomain (147.34.91.1) by svr-orw-fem-03.mgc.mentorg.com (147.34.97.39) with Microsoft SMTP Server id 14.1.289.1; Thu, 16 Feb 2012 18:56:30 -0800 From: Yao Qi To: Subject: [PATCH 4/9] agent doc Date: Fri, 17 Feb 2012 02:57:00 -0000 Message-ID: <1329447300-18841-5-git-send-email-yao@codesourcery.com> In-Reply-To: <1329447300-18841-1-git-send-email-yao@codesourcery.com> References: <1329447300-18841-1-git-send-email-yao@codesourcery.com> MIME-Version: 1.0 Content-Type: text/plain 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-02/txt/msg00348.txt.bz2 Documentation bits. Leave original contents of node "Agent Expressions" there, with some minor updates. A new node "Agent" is added. gdb/doc/ 2012-01-21 Yao Qi * agentexpr.texi (Agent Expressions): Update some parts for agent expression can not only be used in agent, but also in remote stubs. Move some contents to ... * gdb.texinfo (Agent): ... to here. New node. --- gdb/doc/agentexpr.texi | 35 +++++++++-------------------- gdb/doc/gdb.texinfo | 56 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 24 deletions(-) diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi index d0f6f15..7075281 100644 --- a/gdb/doc/agentexpr.texi +++ b/gdb/doc/agentexpr.texi @@ -13,32 +13,19 @@ @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 +Agent expression 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. Originally, agent expressions are used +in @dfn{agent} (@pxref{Agent}), so they are called @dfn{Agent Expression}. Gradually, +they are used more widely, such as in remote stub. + +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..a833f34 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. +* Agent:: Debugging Agent * GDB Bugs:: Reporting bugs in @value{GDBN} @@ -32191,6 +32192,61 @@ 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 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 +some bugs. 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. + +The agent can interpret and execute @dfn{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. + +@menu +* Control Agent:: Turn agent on and off +@end menu +@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 GDB Bugs @chapter Reporting Bugs in @value{GDBN} @cindex bugs in @value{GDBN} -- 1.7.0.4