X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=d0997b3525a9e2a4c9505950f9bf4647951412a7;hb=9d2897ad53ac9e70b9ed84193e912f2c158d5198;hp=18bad647ce18e6715f9413e30321ae5cb292ad93;hpb=29153c240adea2794a6ec1c8c4da1dbe3654a045;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 18bad647ce..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 @@ -5214,8 +5214,8 @@ breakpoint, the breakpoint applies to @emph{all} threads of your program. You can use the @code{thread} qualifier on conditional breakpoints as -well; in this case, place @samp{thread @var{threadno}} before the -breakpoint condition, like this: +well; in this case, place @samp{thread @var{threadno}} before or +after the breakpoint condition, like this: @smallexample (@value{GDBP}) break frik.c:13 thread 28 if bartab > lim @@ -5356,7 +5356,7 @@ the first line of a function, @code{reverse-next} will take you back to the caller of that function, @emph{before} the function was called, just as the normal @code{next} command would take you from the last line of a function back to its return to its caller -@footnote{Unles the code is too heavily optimized.}. +@footnote{Unless the code is too heavily optimized.}. @kindex reverse-nexti @kindex rni @r{(@code{reverse-nexti})} @@ -6539,8 +6539,14 @@ in symbolic form by specifying the @code{/r}. The default memory range is the function surrounding the program counter of the selected frame. A single argument to this command is a program counter value; @value{GDBN} dumps the function -surrounding this value. Two arguments specify a range of addresses -(first inclusive, second exclusive) to dump. +surrounding this value. When two arguments are given, they should +be separated by a comma, possibly surrounded by whitespace. The +arguments specify a range of addresses (first inclusive, second exclusive) +to dump. In that case, the name of the function is also printed (since +there could be several functions in the given range). + +The argument(s) can be any expression yielding a numeric value, such as +@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}. If the range of memory being disassembled contains current program counter, the instruction at that location is shown with a @code{=>} marker. @@ -6550,7 +6556,7 @@ The following example shows the disassembly of a range of addresses of HP PA-RISC 2.0 code: @smallexample -(@value{GDBP}) disas 0x32c4 0x32e4 +(@value{GDBP}) disas 0x32c4, 0x32e4 Dump of assembler code from 0x32c4 to 0x32e4: 0x32c4 : addil 0,dp 0x32c8 : ldw 0x22c(sr0,r1),r26 @@ -6570,21 +6576,21 @@ program is stopped just after function prologue: (@value{GDBP}) disas /m main Dump of assembler code for function main: 5 @{ - 0x08048330 : push %ebp - 0x08048331 : mov %esp,%ebp - 0x08048333 : sub $0x8,%esp - 0x08048336 : and $0xfffffff0,%esp - 0x08048339 : sub $0x10,%esp + 0x08048330 <+0>: push %ebp + 0x08048331 <+1>: mov %esp,%ebp + 0x08048333 <+3>: sub $0x8,%esp + 0x08048336 <+6>: and $0xfffffff0,%esp + 0x08048339 <+9>: sub $0x10,%esp 6 printf ("Hello.\n"); -=> 0x0804833c : movl $0x8048440,(%esp) - 0x08048343 : call 0x8048284 +=> 0x0804833c <+12>: movl $0x8048440,(%esp) + 0x08048343 <+19>: call 0x8048284 7 return 0; 8 @} - 0x08048348 : mov $0x0,%eax - 0x0804834d : leave - 0x0804834e : ret + 0x08048348 <+24>: mov $0x0,%eax + 0x0804834d <+29>: leave + 0x0804834e <+30>: ret End of assembler dump. @end smallexample @@ -9325,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:: @@ -9491,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 @@ -9566,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 @@ -9583,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 @@ -9923,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} @@ -12918,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} @@ -14082,13 +14168,14 @@ name @value{GDBN} is currently using. @table @code @kindex set debug-file-directory -@item set debug-file-directory @var{directory} -Set the directory which @value{GDBN} searches for separate debugging -information files to @var{directory}. +@item set debug-file-directory @var{directories} +Set the directories which @value{GDBN} searches for separate debugging +information files to @var{directory}. Multiple directory components can be set +concatenating them by a directory separator. @kindex show debug-file-directory @item show debug-file-directory -Show the directory @value{GDBN} searches for separate debugging +Show the directories @value{GDBN} searches for separate debugging information files. @end table @@ -15232,6 +15319,34 @@ extended-remote}. This should be set to a filename valid on the target system. If it is not set, the target will use a default filename (e.g.@: the last program run). +@item set remote interrupt-sequence +@cindex interrupt remote programs +@cindex select Ctrl-C, BREAK or BREAK-g +Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or +@samp{BREAK-g} as the +sequence to the remote target in order to interrupt the execution. +@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which +is high level of serial line for some certain time. +Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g. +It is @code{BREAK} signal followed by character @code{g}. + +@item show interrupt-sequence +Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g} +is sent by @value{GDBN} to interrupt the remote program. +@code{BREAK-g} is BREAK signal followed by @code{g} and +also known as Magic SysRq g. + +@item set remote interrupt-on-connect +@cindex send interrupt-sequence on start +Specify whether interrupt-sequence is sent to remote target when +@value{GDBN} connects to it. This is mostly needed when you debug +Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g} +which is known as Magic SysRq g in order to connect @value{GDBN}. + +@item show interrupt-on-connect +Show whether interrupt-sequence is sent +to remote target when @value{GDBN} connects to it. + @kindex set tcp @kindex show tcp @item set tcp auto-retry on @@ -19293,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. @@ -19352,8 +19480,8 @@ readable, @value{GDBN} will evaluate it as a Python script. If this file does not exist, and if the parameter @code{debug-file-directory} is set (@pxref{Separate Debug Files}), -then @value{GDBN} will use the file named -@file{@var{debug-file-directory}/@var{real-name}}, where +then @value{GDBN} will use for its each separated directory component +@code{component} the file named @file{@code{component}/@var{real-name}}, where @var{real-name} is the object file's real name, as described above. Finally, if this file does not exist, then @value{GDBN} will look for @@ -19443,6 +19571,13 @@ The type of this @code{gdb.Value}. The value of this attribute is a The following methods are provided: @table @code +@defmethod Value cast type +Return a new instance of @code{gdb.Value} that is the result of +casting this instance to the type described by @var{type}, which must +be a @code{gdb.Type} object. If the cast cannot be performed for some +reason, this method throws an exception. +@end defmethod + @defmethod Value dereference For pointer data types, this method returns a new @code{gdb.Value} object whose contents is the object pointed to by the pointer. For example, if @@ -19566,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, @@ -19593,11 +19734,23 @@ 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. @end defmethod +@defmethod Type pointer +Return a new @code{gdb.Type} object which represents a pointer to this +type. +@end defmethod + @defmethod Type strip_typedefs Return a new @code{gdb.Type} that represents the real type, after removing all layers of typedefs. @@ -21882,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: @@ -23383,7 +23543,7 @@ For a stack with frame levels 0 through 11: @subsubheading Synopsis @smallexample - -stack-list-arguments @var{show-values} + -stack-list-arguments @var{print-values} [ @var{low-frame} @var{high-frame} ] @end smallexample @@ -23396,9 +23556,11 @@ larger than the actual number of frames. On the other hand, @var{high-frame} may be larger than the actual number of frames, in which case only existing frames will be returned. -The @var{show-values} argument must have a value of 0 or 1. A value of -0 means that only the names of the arguments are listed, a value of 1 -means that both names and values of the arguments are printed. +If @var{print-values} is 0 or @code{--no-values}, print only the names of +the variables; if it is 1 or @code{--all-values}, print also their +values; and if it is 2 or @code{--simple-values}, print the name, +type and value for simple data types, and the name and type for arrays, +structures and unions. Use of this command to obtain arguments in a single frame is deprecated in favor of the @samp{-stack-list-variables} command. @@ -23581,7 +23743,7 @@ Display the local variable names for the selected frame. If @var{print-values} is 0 or @code{--no-values}, print only the names of the variables; if it is 1 or @code{--all-values}, print also their values; and if it is 2 or @code{--simple-values}, print the name, -type and value for simple data types and the name and type for arrays, +type and value for simple data types, and the name and type for arrays, structures and unions. In this last case, a frontend can immediately display the value of simple data types and create variable objects for other data types when the user wishes to explore their values in @@ -23623,7 +23785,7 @@ Display the names of local variables and function arguments for the selected fra @var{print-values} is 0 or @code{--no-values}, print only the names of the variables; if it is 1 or @code{--all-values}, print also their values; and if it is 2 or @code{--simple-values}, print the name, -type and value for simple data types and the name and type for arrays, +type and value for simple data types, and the name and type for arrays, structures and unions. @subsubheading Example @@ -29896,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 @@ -29969,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 @@ -30075,9 +30267,9 @@ or -1 if an error occurs. @var{pathname} is a string. @cindex interrupts (remote protocol) When a program on the remote target is running, @value{GDBN} may -attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK}, -control of which is specified via @value{GDBN}'s @samp{remotebreak} -setting (@pxref{set remotebreak}). +attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or +a @code{BREAK} followed by @code{g}, +control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}. The precise meaning of @code{BREAK} is defined by the transport mechanism and may, in fact, be undefined. @value{GDBN} does not @@ -30094,6 +30286,10 @@ and does @emph{not} represent an interrupt. E.g., an @samp{X} packet (@pxref{X packet}), used for binary downloads, may include an unescaped @code{0x03} as part of its packet. +@code{BREAK} followed by @code{g} is also known as Magic SysRq g. +When Linux kernel receives this sequence from serial port, +it stops execution and connects to gdb. + Stubs are not required to recognize these interrupt mechanisms and the precise meaning associated with receipt of the interrupt is implementation defined. If the target supports debugging of multiple