From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16519 invoked by alias); 12 Mar 2010 02:40:46 -0000 Received: (qmail 16464 invoked by uid 22791); 12 Mar 2010 02:40:44 -0000 X-SWARE-Spam-Status: No, hits=-2.4 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (38.113.113.100) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 12 Mar 2010 02:40:39 +0000 Received: (qmail 21436 invoked from network); 12 Mar 2010 02:40:38 -0000 Received: from unknown (HELO macbook-2.local) (stan@127.0.0.2) by mail.codesourcery.com with ESMTPA; 12 Mar 2010 02:40:38 -0000 Message-ID: <4B99A9A0.20500@codesourcery.com> Date: Fri, 12 Mar 2010 02:40:00 -0000 From: Stan Shebs User-Agent: Thunderbird 2.0.0.23 (Macintosh/20090812) MIME-Version: 1.0 To: gdb-patches@sourceware.org Subject: [PATCH] Document tracepoint restrictions Content-Type: multipart/mixed; boundary="------------050101030309090108040803" 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: 2010-03/txt/msg00430.txt.bz2 This is a multi-part message in MIME format. --------------050101030309090108040803 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Content-length: 586 While the savvy GDB hacker can use sekrit GDB internals knowledge to surmise what will and won't work with tracepoints, normal users can benefit from it being spelled out more explicitly. This patch adds a new section to the manual that explains some of the gotchas our new generation of tracepoint users has experienced already. Stan 2010-03-11 Stan Shebs Nathan Sidwell * gdb.texinfo (Tracepoint Actions): Clarify that while-stepping is doing instruction stepping. (Tracepoint Restrictions): New node. --------------050101030309090108040803 Content-Type: text/plain; x-mac-type="0"; x-mac-creator="0"; name="restrict-patch-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="restrict-patch-1" Content-length: 5038 Index: ChangeLog =================================================================== RCS file: /cvs/src/src/gdb/doc/ChangeLog,v retrieving revision 1.1021 diff -p -r1.1021 ChangeLog *** ChangeLog 10 Mar 2010 18:20:07 -0000 1.1021 --- ChangeLog 12 Mar 2010 02:33:51 -0000 *************** *** 1,3 **** --- 1,10 ---- + 2010-03-11 Stan Shebs + Nathan Sidwell + + * gdb.texinfo (Tracepoint Actions): Clarify that while-stepping is + doing instruction stepping. + (Tracepoint Restrictions): New node. + 2010-03-10 Tom Tromey * gdbint.texinfo (Symbol Handling): Update. Index: gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.679 diff -p -r1.679 gdb.texinfo *** gdb.texinfo 8 Mar 2010 19:20:38 -0000 1.679 --- gdb.texinfo 12 Mar 2010 02:33:52 -0000 *************** conditions and actions. *** 9352,9357 **** --- 9352,9358 ---- * Tracepoint Actions:: * Listing Tracepoints:: * Starting and Stopping Trace Experiments:: + * Tracepoint Restrictions:: @end menu @node Create and Delete Tracepoints *************** action were used. *** 9668,9677 **** @kindex while-stepping @r{(tracepoints)} @item while-stepping @var{n} ! Perform @var{n} single-step traces after the tracepoint, collecting ! new data at each step. The @code{while-stepping} command is ! followed by the list of what to collect while stepping (followed by ! its own @code{end} command): @smallexample > while-stepping 12 --- 9669,9678 ---- @kindex while-stepping @r{(tracepoints)} @item while-stepping @var{n} ! Perform @var{n} single-step instruction traces after the tracepoint, ! collecting new data at each instruction. The @code{while-stepping} ! command is followed by the list of what to collect while stepping ! (followed by its own @code{end} command): @smallexample > while-stepping 12 *************** which to specify that tracepoint. This *** 9835,9840 **** --- 9836,9900 ---- necessarily heuristic, and it may result in useless tracepoints being created; you may simply delete them if they are of no use. + @node Tracepoint Restrictions + @subsection Tracepoint Restrictions + + There are a number of restrictions on the use of tracepoints. + + @itemize @bullet + + @item + Tracepoint expressions are intended to gather objects (lvalues). Thus + the full flexibility of GDB's expression evaluator is not available. + You cannot call functions, cast objects to aggregate types, access + convenience variables or modify values (except by assignment to trace + state variables). Objective-C and Objective-C++ features are not + supported. + + @item + Collection of local variables, either individually or in bulk with + @code{$locals} or @code{$args}, during @code{while-stepping} may + behave erratically. The stepping action may enter a new scope (for + instance by stepping into a function), or the location of the variable + may change (for instance it is loaded into a register). The + tracepoint data recorded uses the location information for the + variables that is correct for the tracepoint location. When the + tracepoint is created, it is not possible, in general, to determine + where the steps of a @code{while-stepping} sequence will advance the + program -- particularly if a conditional branch is stepped. + + @item + Collection of an incompletely-initialized or partially-destroyed object + may result in something that @value{GDBN} cannot display, or displays + in a misleading way. + + @item + When @value{GDBN} displays a pointer to character it automatically + dereferences the pointer to also display characters of the string + being pointed to. However, collecting the pointer during tracing does + not automatically collect the string. You need to explicitly + dereference the pointer and provide size information if you want to + collect not only the pointer, but the memory pointed to. For example + @code{*ptr@@50} can be used to collect the 50 element array pointed to + by @code{ptr}. + + @item + It is not possible to collect a complete stack backtrace at a + tracepoint. Instead you may collect the registers and a few hundred + bytes from the stack pointer with something like @code{*$esp@@300} + (adjust to use the name of the actual stack pointer register on your + target architecture, and the amount of stack you wish to capture). + Then the @code{backtrace} command will show a partial backtrace when + using a trace frame. The number of stack frames that can be examined + depends on the sizes of the frames in the collected stack. + + @end itemize + + The above is not intended as an exhaustive list of restrictions. As + described above, tracepoint data gathering occurs on the target + without interaction from GDB. Thus the full capabilities of GDB are + not available during data gathering. + @node Analyze Collected Data @section Using the Collected Data --------------050101030309090108040803--