From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17469 invoked by alias); 27 Jan 2009 05:20:57 -0000 Received: (qmail 17455 invoked by uid 22791); 27 Jan 2009 05:20:54 -0000 X-SWARE-Spam-Status: No, hits=-0.9 required=5.0 tests=AWL,BAYES_50,J_CHICKENPOX_37 X-Spam-Check-By: sourceware.org Received: from smtp-outbound-2.vmware.com (HELO smtp-outbound-2.vmware.com) (65.115.85.73) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 27 Jan 2009 05:20:49 +0000 Received: from mailhost2.vmware.com (mailhost2.vmware.com [10.16.67.167]) by smtp-outbound-2.vmware.com (Postfix) with ESMTP id D7B5B8; Mon, 26 Jan 2009 21:20:47 -0800 (PST) Received: from [10.20.92.151] (promb-2s-dhcp151.eng.vmware.com [10.20.92.151]) by mailhost2.vmware.com (Postfix) with ESMTP id BB6528E5C6; Mon, 26 Jan 2009 21:20:47 -0800 (PST) Message-ID: <497E96D6.9010707@vmware.com> Date: Tue, 27 Jan 2009 05:20:00 -0000 From: Michael Snyder User-Agent: Thunderbird 1.5.0.12 (X11/20080411) MIME-Version: 1.0 To: Stan Shebs CC: "gdb@sourceware.org" Subject: Re: Proposed tracepoint enhancements, GDB manual patch References: <497E004D.1060001@codesourcery.com> In-Reply-To: <497E004D.1060001@codesourcery.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-IsSubscribed: yes Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org X-SW-Source: 2009-01/txt/msg00180.txt.bz2 Stan Shebs wrote: > As I mentioned a couple months ago, CodeSourcery is interested in > extending tracepoints, most notably to make them be more like > breakpoints with conditionals and such. We're also planning to add > "trace state variables", which are kind of like convenience variables > managed by the target's agent, and a file format for raw trace data > stored offline. Woo hoo! ;-) Things are still in the planning stage (I've been madly > hacking to get a basic stub running), so everything is still tweakable, > and feel free to comment on lamenesses or omissions. This first bit > takes the form of a patch to GDB's tracepoint chapter, so it should be > read with an eye to how user will learn how to use tracepoints. > > Stan > > > > ------------------------------------------------------------------------ > > Index: gdb.texinfo > =================================================================== > RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v > retrieving revision 1.535 > diff -p -r1.535 gdb.texinfo > *** gdb.texinfo 18 Nov 2008 21:31:27 -0000 1.535 > --- gdb.texinfo 20 Nov 2008 07:28:40 -0000 > *************** This chapter describes the tracepoint co > *** 8500,8509 **** > @section Commands to Set Tracepoints > > Before running such a @dfn{trace experiment}, an arbitrary number of > ! tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a > ! tracepoint has a number assigned to it by @value{GDBN}. Like with > ! breakpoints, tracepoint numbers are successive integers starting from > ! one. Many of the commands associated with tracepoints take the > tracepoint number as their argument, to identify which tracepoint to > work on. > > --- 8500,8509 ---- > @section Commands to Set Tracepoints > > Before running such a @dfn{trace experiment}, an arbitrary number of > ! tracepoints can be set. A tracepoint is actually a special type of > ! breakpoint (@pxref{Set Breaks}), so you can manipulate it using > ! standard breakpoint commands. For instance, each tracepoint has an > ! integer assigned to it by @value{GDBN}, and many commands take the > tracepoint number as their argument, to identify which tracepoint to > work on. > > *************** conditions and actions. > *** 8521,8526 **** > --- 8521,8528 ---- > * Create and Delete Tracepoints:: > * Enable and Disable Tracepoints:: > * Tracepoint Passcounts:: > + * Tracepoint Conditions:: > + * Trace State Variables:: > * Tracepoint Actions:: > * Listing Tracepoints:: > * Starting and Stopping Trace Experiments:: > *************** conditions and actions. > *** 8532,8547 **** > @table @code > @cindex set tracepoint > @kindex trace > ! @item trace > The @code{trace} command is very similar to the @code{break} command. > ! Its argument can be a source line, a function name, or an address in > ! the target program. @xref{Set Breaks}. The @code{trace} command > ! defines a tracepoint, which is a point in the target program where the > ! debugger will briefly stop, collect some data, and then allow the > ! program to continue. Setting a tracepoint or changing its commands > ! doesn't take effect until the next @code{tstart} command; thus, you > ! cannot change the tracepoint attributes once a trace experiment is > ! running. > > Here are some examples of using the @code{trace} command: > > --- 8534,8549 ---- > @table @code > @cindex set tracepoint > @kindex trace > ! @item trace @var{location} > The @code{trace} command is very similar to the @code{break} command. > ! Its argument @var{location} can be a source line, a function name, or > ! an address in the target program. @xref{Set Breaks}. The > ! @code{trace} command defines a tracepoint, which is a point in the > ! target program where the debugger will briefly stop, collect some > ! data, and then allow the program to continue. Setting a tracepoint or > ! changing its commands doesn't take effect until the next @code{tstart} > ! command; thus, you cannot change the tracepoint attributes once a > ! trace experiment is running. > > Here are some examples of using the @code{trace} command: > > *************** Here are some examples of using the @cod > *** 8560,8565 **** > --- 8562,8588 ---- > @noindent > You can abbreviate @code{trace} as @code{tr}. > > + @item trace @var{location} if @var{cond} > + Set a tracepoint with condition @var{cond}; evaluate the expression > + @var{cond} each time the tracepoint is reached, and collect data only > + if the value is nonzero---that is, if @var{cond} evaluates as true. > + @xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more > + information on tracepoint conditions. > + > + @cindex set fast tracepoint > + @kindex ftrace > + @item ftrace @var{location} [ if @var{cond} ] > + The @code{ftrace} command sets a ``fast'' tracepoint. For targets that > + support it, fast tracepoints will use a more efficient but possibly > + less general technique to trigger data collection, such as a jump > + instruction instead of a trap, or hardware support. It may not be > + possible to create a fast tracepoint at the desired location, in which > + case the command will exit with an explanatory message. (The regular > + @code{trace} command may also create fast tracepoints if possible.) > + > + @value{GDBN} handles arguments to @code{ftrace} exactly as for > + @code{trace}. > + > @vindex $tpnum > @cindex last tracepoint number > @cindex recent tracepoint number > *************** of the most recently set tracepoint. > *** 8569,8606 **** > > @kindex delete tracepoint > @cindex tracepoint deletion > ! @item delete tracepoint @r{[}@var{num}@r{]} > ! Permanently delete one or more tracepoints. With no argument, the > ! default is to delete all tracepoints. > > Examples: > > @smallexample > ! (@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints > > ! (@value{GDBP}) @b{delete trace} // remove all tracepoints > @end smallexample > > @noindent > ! You can abbreviate this command as @code{del tr}. > @end table > > @node Enable and Disable Tracepoints > @subsection Enable and Disable Tracepoints > > @table @code > ! @kindex disable tracepoint > ! @item disable tracepoint @r{[}@var{num}@r{]} > ! Disable tracepoint @var{num}, or all tracepoints if no argument > ! @var{num} is given. A disabled tracepoint will have no effect during > ! the next trace experiment, but it is not forgotten. You can re-enable > ! a disabled tracepoint using the @code{enable tracepoint} command. > ! > ! @kindex enable tracepoint > ! @item enable tracepoint @r{[}@var{num}@r{]} > ! Enable tracepoint @var{num}, or all tracepoints. The enabled > ! tracepoints will become effective the next time a trace experiment is > ! run. > @end table > > @node Tracepoint Passcounts > --- 8592,8628 ---- > > @kindex delete tracepoint > @cindex tracepoint deletion > ! @item delete @r{[}@var{num}@r{]} > ! Permanently delete one or more tracepoints. > > Examples: > > @smallexample > ! (@value{GDBP}) @b{delete 1 2 3} // remove three tracepoints > > ! (@value{GDBP}) @b{delete} // remove all breakpoints/tracepoints > @end smallexample > > @noindent > ! You can abbreviate this command as @code{del}. > @end table > > @node Enable and Disable Tracepoints > @subsection Enable and Disable Tracepoints > > @table @code > ! @kindex disable > ! @item disable @r{[}@var{num}@r{]} > ! Disable tracepoint @var{num}, or all tracepoints and breakpoints if no > ! argument @var{num} is given. A disabled tracepoint will have no > ! effect during the next trace experiment, but it is not forgotten. You > ! can re-enable a disabled tracepoint using the @code{enable} command. > ! > ! @kindex enable > ! @item enable @r{[}@var{num}@r{]} > ! Enable tracepoint @var{num}, or all tracepoints and breakpoints. The > ! enabled tracepoints will become effective the next time a trace > ! experiment is run. > @end table > > @node Tracepoint Passcounts > *************** Examples: > *** 8639,8644 **** > --- 8661,8752 ---- > @end smallexample > @end table > > + @node Tracepoint Conditions > + @subsection Tracepoint Conditions > + @cindex conditional breakpoints > + @cindex breakpoint conditions > + > + The simplest sort of tracepoint collects data every time your program > + reaches a specified place. You can also specify a @dfn{condition} for > + a tracepoint. A condition is just a Boolean expression in your > + programming language (@pxref{Expressions, ,Expressions}). A > + tracepoint with a condition evaluates the expression each time your > + program reaches it, and data collection happens only if the condition > + is @emph{true}. Tracepoint conditions can have side effects. > + > + Tracepoint conditions can be specified when a tracepoint is set, by > + using @samp{if} in the arguments to the @code{trace} command. > + @xref{Set Trace, ,Setting Tracepoints}. They can also be set or > + changed at any time with the @code{condition} command. > + > + @table @code > + @kindex condition > + @item condition @var{tpnum} @var{expression} > + Specify @var{expression} as the tracepoint condition for tracepoint > + @var{tpnum}. After you set a condition, tracepoint @var{tpnum} runs > + its actions only if the value of @var{expression} is true (nonzero, > + in C). When you use @code{condition}, @value{GDBN} checks > + @var{expression} immediately for syntactic correctness, and to > + determine whether symbols in it have referents in the context of your > + breakpoint. If @var{expression} uses symbols not referenced in the > + context of the breakpoint, @value{GDBN} prints an error message: > + > + @smallexample > + No symbol "foo" in current context. > + @end smallexample > + > + @noindent > + @value{GDBN} does not actually evaluate @var{expression} at the time > + the @code{condition} command (or a command that sets a tracepoint with > + a condition, like @code{trace if @dots{}}) is given, however. > + @xref{Expressions, ,Expressions}. Instead, @value{GDBN} encodes the > + expression into a form suitable for execution on the target, > + independently of @value{GDBN}. Global variables become raw memory > + locations, locals become stack accesses, and so forth. > + > + @item condition @var{tpnum} > + Remove the condition from tracepoint number @var{tpnum}. It becomes > + an ordinary unconditional tracepoint. > + @end table > + > + @node Trace State Variables > + @subsection Trace State Variables > + > + A @dfn{race state variable} is a special type of variable that is > + created and managed by target-side code. The syntax is the same as > + that for GDB's convenience variables (a string prefixed with ``$''), > + but they are stored on the target. They are created implicitly by > + being assigned to in conditional and action expressions, or > + explicitly, with a @code{tvariable} command. They are always signed > + integers, and always updated atomically. > + > + Trace state variables are remembered by @value{GDBN}, and downloaded > + to the target along with tracepoint information when the trace > + experiment starts. There are no intrinsic limits on the number of > + trace state variables, beyond memory limitations of the target. > + > + @table @code > + > + @item tvariable $@var{name} [ = @var{expression} ] > + The @code{tvariable} command creates a new trace state variable named > + @var{name}, and optionally sets it to the value of @var{expression}. > + @var{expression} is evaluated when this command is entered; a > + non-integer value will result in an error. A second @code{tvariable} > + command with the same name assigns a new value to the variable. > + > + @item tvariable delete $@var{name} > + This command deletes the trace state variable named @var{name}. > + > + @item info tvariables > + List all the trace state variables along with their values. > + > + @item $trace_timestamp > + This trace state variable is always defined, and its value is the > + current time at the moment it is accessed, expressed in > + system-specific units. > + > + @end table > + > @node Tracepoint Actions > @subsection Tracepoint Action Lists > > *************** recently defined (so that you can define > *** 8653,8659 **** > @code{actions} without bothering about its number). You specify the > actions themselves on the following lines, one action at a time, and > terminate the actions list with a line containing just @code{end}. So > ! far, the only defined actions are @code{collect} and > @code{while-stepping}. > > @cindex remove actions from a tracepoint > --- 8761,8767 ---- > @code{actions} without bothering about its number). You specify the > actions themselves on the following lines, one action at a time, and > terminate the actions list with a line containing just @code{end}. So > ! far, the only defined actions are @code{collect}, @code{do}, and > @code{while-stepping}. > > @cindex remove actions from a tracepoint > *************** and follow it immediately with @samp{end > *** 8663,8668 **** > --- 8771,8778 ---- > @smallexample > (@value{GDBP}) @b{collect @var{data}} // collect some data > > + (@value{GDBP}) @b{do @var{exp}} // evaluate an expression > + > (@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data > > (@value{GDBP}) @b{end} // signals the end of actions. > *************** Enter actions for tracepoint 1, one per > *** 8685,8690 **** > --- 8795,8801 ---- > > collect $regs > > while-stepping 12 > > collect $fp, $sp > + > do $stepcount = $stepcount + 1 > > end > end > @end smallexample > *************** arguments separated by commas: the effec > *** 8714,8724 **** > The command @code{info scope} (@pxref{Symbols, info scope}) is > particularly useful for figuring out what data to collect. > > @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 > --- 8825,8840 ---- > The command @code{info scope} (@pxref{Symbols, info scope}) is > particularly useful for figuring out what data to collect. > > + @item do @var{expr1}, @var{expr2}, @dots{} > + Evaluate @var{expr1}, @var{expr2}, etc, and discard the results. This > + is useful for setting the value of a trace state variable without > + filling up the trace buffer. > + > @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 do or collect while stepping (followed by > its own @code{end} command): > > @smallexample > *************** its own @code{end} command): > *** 8731,8736 **** > --- 8847,8858 ---- > @noindent > You may abbreviate @code{while-stepping} as @code{ws} or > @code{stepping}. > + > + @item set default-collect @var{expr1}, @var{expr2}, @dots{} > + This variable is a list of expressions to collect at each tracepoint > + hit, effectively an additional @code{collect} prepended to every > + tracepoint action list. > + > @end table > > @node Listing Tracepoints > *************** begins collecting data. This has the si > *** 8789,8794 **** > --- 8911,8923 ---- > the data collected in the trace buffer during the previous trace > experiment. > > + The trace experiment runs independently of any other @value{GDBN} > + interaction with your program. You may stop the program at a > + breakpoint, single-step, change program values, and so forth. Of > + course, confusion may ensue if you are manually altering program data > + while it is being collected, which could happen if the trace is > + running while you are in non-stop debugging mode. > + > @kindex tstop > @cindex stop a running trace experiment > @item tstop > *************** for examining the trace data. The basic > *** 8832,8851 **** > collects a trace @dfn{snapshot} every time it is hit and another > snapshot every time it single-steps. All these snapshots are > consecutively numbered from zero and go into a buffer, and you can > ! examine them later. The way you examine them is to @dfn{focus} on a > ! specific trace snapshot. When the remote stub is focused on a trace > ! snapshot, it will respond to all @value{GDBN} requests for memory and > ! registers by reading from the buffer which belongs to that snapshot, > ! rather than from @emph{real} memory or registers of the program being > ! debugged. This means that @strong{all} @value{GDBN} commands > ! (@code{print}, @code{info registers}, @code{backtrace}, etc.) will > ! behave as if we were currently debugging the program state as it was > ! when the tracepoint occurred. Any requests for data that are not in > ! the buffer will fail. > > @menu > * tfind:: How to select a trace snapshot > * tdump:: How to display all data for a snapshot > * save-tracepoints:: How to save tracepoints for a future run > @end menu > > --- 8961,8981 ---- > collects a trace @dfn{snapshot} every time it is hit and another > snapshot every time it single-steps. All these snapshots are > consecutively numbered from zero and go into a buffer, and you can > ! examine them later. The way you examine them is to @dfn{find} a > ! specific trace snapshot. When the target has found a trace snapshot, > ! it will respond to all @value{GDBN} requests for memory and registers > ! by reading from the buffer which belongs to that snapshot, rather than > ! from @emph{real} memory or registers of the program being debugged. > ! This means that @strong{all} @value{GDBN} commands (@code{print}, > ! @code{info registers}, @code{backtrace}, etc.) will behave as if we > ! were currently debugging the program state as it was when the > ! tracepoint occurred. Any requests for data that are not in the buffer > ! will fail. > > @menu > * tfind:: How to select a trace snapshot > * tdump:: How to display all data for a snapshot > + * Using a Trace File:: How to get trace snapshots from a file > * save-tracepoints:: How to save tracepoints for a future run > @end menu > > *************** gdb_long_test = 17 '\021' > *** 9025,9030 **** > --- 9155,9203 ---- > (@value{GDBP}) > @end smallexample > > + @node Using a Trace File > + @subsection Using a Trace File > + > + It may be that the trace experiment has finished running after GDB has > + disconnected from the target, and the results have been saved to a > + file. You can give a special @code{target} command to use this file as > + the source of trace snapshots. > + > + @table @code > + > + @item target tfile @var{filename} > + This target command causes @value{GDBN} to use the contents of > + @var{filename} as a source of trace snapshots that can be found with > + @var{tfind} and used as described above. Subsequent target commands, > + such as @code{target remote}, will terminate this mode and resume > + normal debugging. If the tracepoints recorded in the file are > + different from the ones currently defined by @value{GDBN}, the > + debugger will warn of the discrepancy and create new tracepoints from > + the file's data. > + > + @end table > + > + A file of trace data begins with the byte 0x7f (to indicate that it > + includes some binary data), followed by the chararacters > + 'TRACE\n'. Each tracepoint is then listed, with its properties > + recorded in ASCII, followed by runs of trace frames, which are > + recorded as raw binary. > + > + Each tracepoint record has the form > + > + ::::::\n > + > + where and are hex dumps of the agent expression > + bytecodes. > + > + Groups of trace frames are introduced with a 32-bit word, of which > + the first half is a tracepoint , and the second half of which > + is a count of frames following. Each trace frame consists of the raw > + data as collected; its contents may be parsed by interpreting the > + action expression for the frame's tracepoint. > + > + The end of the file is signified with a 32-bit word of all zeros. > + > @node save-tracepoints > @subsection @code{save-tracepoints @var{filename}} > @kindex save-tracepoints > *************** Files}). > *** 9041,9046 **** > --- 9214,9223 ---- > @cindex tracepoint variables > @cindex convenience variables for tracepoints > > + Several @value{GDBN} convenience variables are available to simplify > + the writing of analysis scripts. Note that these are not the same as > + trace state variables, which are managed by the target. > + > @table @code > @vindex $trace_frame > @item (int) $trace_frame