X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=d0997b3525a9e2a4c9505950f9bf4647951412a7;hb=9d2897ad53ac9e70b9ed84193e912f2c158d5198;hp=39107ec90224abb4dbe6af2d3bc3f6c7018dd4d8;hpb=16af530a6fd6d33174ae322fb1739bcbcbeaf96d;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 39107ec902..d0997b3525 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1,6 +1,6 @@ \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 @@ -46,7 +46,7 @@ @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 @@ -120,7 +120,7 @@ This is the @value{EDITION} Edition, for @value{GDBN} @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 @@ -9331,6 +9331,7 @@ conditions and actions. * Enable and Disable Tracepoints:: * Tracepoint Passcounts:: * Tracepoint Conditions:: +* Trace State Variables:: * Tracepoint Actions:: * Listing Tracepoints:: * Starting and Stopping Trace Experiments:: @@ -9497,6 +9498,59 @@ search through. (@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 @@ -9572,6 +9626,15 @@ arguments separated by commas: the effect is the same. 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 @@ -9589,6 +9652,22 @@ its own @code{end} command): @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 @@ -9929,7 +10008,8 @@ use @code{output} instead. 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} @@ -12924,7 +13004,7 @@ that conflict with the regular expression language (e.g.@: @kindex info variables @item info variables -Print the names and data types of all variables that are declared +Print the names and data types of all variables that are defined outside of functions (i.e.@: excluding local variables). @item info variables @var{regexp} @@ -19328,6 +19408,19 @@ If no exception is raised, the return value is always an instance of @code{gdb.Value} (@pxref{Values From Inferior}). @end defun +@findex gdb.parse_and_eval +@defun parse_and_eval expression +Parse @var{expression} as an expression in the current language, +evaluate it, and return the result as a @code{gdb.Value}. +@var{expression} must be a string. + +This function can be useful when implementing a new command +(@pxref{Commands In Python}), as it provides a way to parse the +command's argument as an expression. It is also useful simply to +compute values, for example, it is the only way to get the value of a +convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}. +@end defun + @findex gdb.write @defun write string Print a string to @value{GDBN}'s paginated standard output stream. @@ -19608,6 +19701,12 @@ This is @code{True} if the field is artificial, usually meaning that it was provided by the compiler and not the user. This attribute is always provided, and is @code{False} if the field is not artificial. +@item is_base_class +This is @code{True} if the field represents a base class of a C@t{++} +structure. This attribute is always provided, and is @code{False} +if the field is not a base class of the type that is the argument of +@code{fields}, or if that type was not a C@t{++} class. + @item bitsize If the field is packed, or is a bitfield, then this will have a non-zero value, which is the size of the field in bits. Otherwise, @@ -19635,6 +19734,13 @@ variant of this type. That is, the result is neither @code{const} nor @code{volatile}. @end defmethod +@defmethod Type range +Return a Python @code{Tuple} object that contains two elements: the +low bound of the argument type and the high bound of that type. If +the type does not have a range, @value{GDBN} will raise a +@code{RuntimeError} exception. +@end defmethod + @defmethod Type reference Return a new @code{gdb.Type} object which represents a reference to this type. @@ -21929,6 +22035,13 @@ Quitting @value{GDBN} just prints the result class @samp{^exit}. <- ^exit @end smallexample +Please note that @samp{^exit} is printed immediately, but it might +take some time for @value{GDBN} to actually exit. During that time, @value{GDBN} +performs necessary cleanups, including killing programs being debugged +or disconnecting from debug hardware, so the frontend should wait till +@value{GDBN} exits and should only forcibly kill @value{GDBN} if it +fails to exit in reasonable time. + @subheading A Bad Command Here's what happens if you pass a non-existent command: @@ -29945,6 +30058,16 @@ The packet was understood and carried out. 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 @@ -30018,8 +30141,28 @@ There is no trace experiment running. 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