\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
@c Free Software Foundation, Inc.
@c
@c %**start of header
@copying
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2009 Free Software Foundation, Inc.
+Copyright (C) 1988-2010 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
* Enable and Disable Tracepoints::
* Tracepoint Passcounts::
* Tracepoint Conditions::
+* Trace State Variables::
* Tracepoint Actions::
* Listing Tracepoints::
* Starting and Stopping Trace Experiments::
(@value{GDBP}) @kbd{trace normal_operation if errcode > 0}
@end smallexample
+@node Trace State Variables
+@subsection Trace State Variables
+@cindex trace state variables
+
+A @dfn{trace 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 must be created explicitly,
+using a @code{tvariable} command. They are always 64-bit signed
+integers.
+
+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.
+
+@cindex convenience variables, and trace state variables
+Although trace state variables are managed by the target, you can use
+them in print commands and expressions as if they were convenience
+variables; @value{GDBN} will get the current value from the target
+while the trace experiment is running. Trace state variables share
+the same namespace as other ``$'' variables, which means that you
+cannot have trace state variables with names like @code{$23} or
+@code{$pc}, nor can you have a trace state variable and a convenience
+variable with the same name.
+
+@table @code
+
+@item tvariable $@var{name} [ = @var{expression} ]
+@kindex tvariable
+The @code{tvariable} command creates a new trace state variable named
+@code{$@var{name}}, and optionally gives it an initial value of
+@var{expression}. @var{expression} is evaluated when this command is
+entered; the result will be converted to an integer if possible,
+otherwise @value{GDBN} will report an error. A subsequent
+@code{tvariable} command specifying the same name does not create a
+variable, but instead assigns the supplied initial value to the
+existing variable of that name, overwriting any previous initial
+value. The default initial value is 0.
+
+@item info tvariables
+@kindex info tvariables
+List all the trace state variables along with their initial values.
+Their current values may also be displayed, if the trace experiment is
+currently running.
+
+@item delete tvariable @r{[} $@var{name} @dots{} @r{]}
+@kindex delete tvariable
+Delete the given trace state variables, or all of them if no arguments
+are specified.
+
+@end table
+
@node Tracepoint Actions
@subsection Tracepoint Action Lists
The command @code{info scope} (@pxref{Symbols, info scope}) is
particularly useful for figuring out what data to collect.
+@kindex teval @r{(tracepoints)}
+@item teval @var{expr1}, @var{expr2}, @dots{}
+Evaluate the given expressions when the tracepoint is hit. This
+command accepts a comma-separated list of expressions. The results
+are discarded, so this is mainly useful for assigning values to trace
+state variables (@pxref{Trace State Variables}) without adding those
+values to the trace buffer, as would be the case if the @code{collect}
+action were used.
+
@kindex while-stepping @r{(tracepoints)}
@item while-stepping @var{n}
Perform @var{n} single-step traces after the tracepoint, collecting
@noindent
You may abbreviate @code{while-stepping} as @code{ws} or
@code{stepping}.
+
+@item set default-collect @var{expr1}, @var{expr2}, @dots{}
+@kindex set default-collect
+@cindex default collection action
+This variable is a list of expressions to collect at each tracepoint
+hit. It is effectively an additional @code{collect} action prepended
+to every tracepoint action list. The expressions are parsed
+individually for each tracepoint, so for instance a variable named
+@code{xyz} may be interpreted as a global for one tracepoint, and a
+local for another, as appropriate to the tracepoint's location.
+
+@item show default-collect
+@kindex show default-collect
+Show the list of expressions that are collected by default at each
+tracepoint hit.
+
@end table
@node Listing Tracepoints
Here's a simple example of using these convenience variables for
stepping through all the trace snapshots and printing some of their
-data.
+data. Note that these are not the same as trace state variables,
+which are managed by the target.
@smallexample
(@value{GDBP}) @b{tfind start}
The packet was not recognized.
@end table
+@item QTDV:@var{n}:@var{value}
+@cindex define trace state variable, remote request
+@cindex @samp{QTDV} packet
+Create a new trace state variable, number @var{n}, with an initial
+value of @var{value}, which is a 64-bit signed integer. Both @var{n}
+and @var{value} are encoded as hexadecimal values. @value{GDBN} has
+the option of not using this packet for initial values of zero; the
+target should simply create the trace state variables as they are
+mentioned in expressions.
+
@item QTFrame:@var{n}
Select the @var{n}'th tracepoint frame from the buffer, and use the
register and memory contents recorded there to answer subsequent
There is a trace experiment running.
@end table
+@item qTV:@var{var}
+@cindex trace state variable value, remote request
+@cindex @samp{qTV} packet
+Ask the stub for the value of the trace state variable number @var{var}.
+
+Replies:
+@table @samp
+@item V@var{value}
+The value of the variable is @var{value}. This will be the current
+value of the variable if the user is examining a running target, or a
+saved value if the variable was collected in the trace frame that the
+user is looking at. Note that multiple requests may result in
+different reply values, such as when requesting values while the
+program is running.
+
+@item U
+The value of the variable is unknown. This would occur, for example,
+if the user is examining a trace frame in which the requested variable
+was not collected.
@end table
+@end table
@node Host I/O Packets
@section Host I/O Packets
projects / deliverable / binutils-gdb.git / blobdiff