X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=d0997b3525a9e2a4c9505950f9bf4647951412a7;hb=9d2897ad53ac9e70b9ed84193e912f2c158d5198;hp=52149f01bfb05d698ed2a9c03fb1efd5001a7998;hpb=4f412fd0b647fcc2aea5f3ad18c0f7833e6a408b;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 52149f01bf..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 @@ -517,6 +517,9 @@ Tensilica, Inc.@: contributed support for Xtensa processors. Others who have worked on the Xtensa port of @value{GDBN} in the past include Steve Tjiang, John Newlin, and Scott Foehner. +Michael Eager and staff of Xilinx, Inc., contributed support for the +Xilinx MicroBlaze architecture. + @node Sample Session @chapter A Sample @value{GDBN} Session @@ -1791,9 +1794,9 @@ kill a child process. * Attach:: Debugging an already-running process * Kill Process:: Killing the child process -* Inferiors:: Debugging multiple inferiors +* Inferiors and Programs:: Debugging multiple inferiors and programs * Threads:: Debugging programs with multiple threads -* Processes:: Debugging programs with multiple processes +* Forks:: Debugging forks * Checkpoint/Restart:: Setting a @emph{bookmark} to return to later @end menu @@ -2346,30 +2349,30 @@ next type @code{run}, @value{GDBN} notices that the file has changed, and reads the symbol table again (while trying to preserve your current breakpoint settings). -@node Inferiors -@section Debugging Multiple Inferiors +@node Inferiors and Programs +@section Debugging Multiple Inferiors and Programs -Some @value{GDBN} targets are able to run multiple processes created -from a single executable. This can happen, for instance, with an -embedded system reporting back several processes via the remote -protocol. +@value{GDBN} lets you run and debug multiple programs in a single +session. In addition, @value{GDBN} on some systems may let you run +several programs simultaneously (otherwise you have to exit from one +before starting another). In the most general case, you can have +multiple threads of execution in each of multiple processes, launched +from multiple executables. @cindex inferior @value{GDBN} represents the state of each program execution with an object called an @dfn{inferior}. An inferior typically corresponds to a process, but is more general and applies also to targets that do not have processes. Inferiors may be created before a process runs, and -may (in future) be retained after a process exits. Each run of an -executable creates a new inferior, as does each attachment to an -existing process. Inferiors have unique identifiers that are -different from process ids, and may optionally be named as well. -Usually each inferior will also have its own distinct address space, -although some embedded targets may have several inferiors running in -different parts of a single space. - -Each inferior may in turn have multiple threads running in it. +may be retained after a process exits. Inferiors have unique +identifiers that are different from process ids. Usually each +inferior will also have its own distinct address space, although some +embedded targets may have several inferiors running in different parts +of a single address space. Each inferior may in turn have multiple +threads running in it. -To find out what inferiors exist at any moment, use @code{info inferiors}: +To find out what inferiors exist at any moment, use @w{@code{info +inferiors}}: @table @code @kindex info inferiors @@ -2384,6 +2387,10 @@ the inferior number assigned by @value{GDBN} @item the target system's inferior identifier + +@item +the name of the executable the inferior is running. + @end enumerate @noindent @@ -2396,9 +2403,9 @@ For example, @smallexample (@value{GDBP}) info inferiors - Num Description -* 1 process 2307 - 2 process 3401 + Num Description Executable + 2 process 2307 hello +* 1 process 3401 goodbye @end smallexample To switch focus between inferiors, use the @code{inferior} command: @@ -2411,9 +2418,57 @@ Make inferior number @var{infno} the current inferior. The argument in the first field of the @samp{info inferiors} display. @end table -To quit debugging one of the inferiors, you can either detach from it -by using the @w{@code{detach inferior}} command (allowing it to run -independently), or kill it using the @w{@code{kill inferior}} command: + +You can get multiple executables into a debugging session via the +@code{add-inferior} and @w{@code{clone-inferior}} commands. On some +systems @value{GDBN} can add inferiors to the debug session +automatically by following calls to @code{fork} and @code{exec}. To +remove inferiors from the debugging session use the +@w{@code{remove-inferior}} command. + +@table @code +@kindex add-inferior +@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] +Adds @var{n} inferiors to be run using @var{executable} as the +executable. @var{n} defaults to 1. If no executable is specified, +the inferiors begins empty, with no program. You can still assign or +change the program assigned to the inferior at any time by using the +@code{file} command with the executable name as its argument. + +@kindex clone-inferior +@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] +Adds @var{n} inferiors ready to execute the same program as inferior +@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the +number of the current inferior. This is a convenient command when you +want to run another instance of the inferior you are debugging. + +@smallexample +(@value{GDBP}) info inferiors + Num Description Executable +* 1 process 29964 helloworld +(@value{GDBP}) clone-inferior +Added inferior 2. +1 inferiors added. +(@value{GDBP}) info inferiors + Num Description Executable + 2 helloworld +* 1 process 29964 helloworld +@end smallexample + +You can now simply switch focus to inferior 2 and run it. + +@kindex remove-inferior +@item remove-inferior @var{infno} +Removes the inferior @var{infno}. It is not possible to remove an +inferior that is running with this command. For those, use the +@code{kill} or @code{detach} command first. + +@end table + +To quit debugging one of the running inferiors that is not the current +inferior, you can either detach from it by using the @w{@code{detach +inferior}} command (allowing it to run independently), or kill it +using the @w{@code{kill inferior}} command: @table @code @kindex detach inferior @var{infno} @@ -2427,6 +2482,12 @@ Kill the inferior identified by @value{GDBN} inferior number @var{infno}, and remove it from the inferior list. @end table +After the successful completion of a command such as @code{detach}, +@code{detach inferior}, @code{kill} or @code{kill inferior}, or after +a normal process exit, the inferior is still valid and listed with +@code{info inferiors}, ready to be restarted. + + To be notified when inferiors are started or exit under @value{GDBN}'s control use @w{@code{set print inferior-events}}: @@ -2447,6 +2508,67 @@ Show whether messages will be printed when @value{GDBN} detects that inferiors have started, exited or have been detached. @end table +Many commands will work the same with multiple programs as with a +single program: e.g., @code{print myglobal} will simply display the +value of @code{myglobal} in the current inferior. + + +Occasionaly, when debugging @value{GDBN} itself, it may be useful to +get more info about the relationship of inferiors, programs, address +spaces in a debug session. You can do that with the @w{@code{maint +info program-spaces}} command. + +@table @code +@kindex maint info program-spaces +@item maint info program-spaces +Print a list of all program spaces currently being managed by +@value{GDBN}. + +@value{GDBN} displays for each program space (in this order): + +@enumerate +@item +the program space number assigned by @value{GDBN} + +@item +the name of the executable loaded into the program space, with e.g., +the @code{file} command. + +@end enumerate + +@noindent +An asterisk @samp{*} preceding the @value{GDBN} program space number +indicates the current program space. + +In addition, below each program space line, @value{GDBN} prints extra +information that isn't suitable to display in tabular form. For +example, the list of inferiors bound to the program space. + +@smallexample +(@value{GDBP}) maint info program-spaces + Id Executable + 2 goodbye + Bound inferiors: ID 1 (process 21561) +* 1 hello +@end smallexample + +Here we can see that no inferior is running the program @code{hello}, +while @code{process 21561} is running the program @code{goodbye}. On +some targets, it is possible that multiple inferiors are bound to the +same program space. The most common example is that of debugging both +the parent and child processes of a @code{vfork} call. For example, + +@smallexample +(@value{GDBP}) maint info program-spaces + Id Executable +* 1 vfork-test + Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) +@end smallexample + +Here, both inferior 2 and inferior 1 are running in the same program +space as a result of inferior 1 having executed a @code{vfork} call. +@end table + @node Threads @section Debugging Programs with Multiple Threads @@ -2726,8 +2848,8 @@ only on some platforms. Display current libthread_db search path. @end table -@node Processes -@section Debugging Programs with Multiple Processes +@node Forks +@section Debugging Forks @cindex fork, debugging programs which call @cindex multiple processes @@ -2818,13 +2940,14 @@ If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN} will retain control of all forked processes (including nested forks). You can list the forked processes under the control of @value{GDBN} by using the @w{@code{info inferiors}} command, and switch from one fork -to another by using the @code{inferior} command (@pxref{Inferiors, -,Debugging Multiple Inferiors}). +to another by using the @code{inferior} command (@pxref{Inferiors and +Programs, ,Debugging Multiple Inferiors and Programs}). To quit debugging one of the forked processes, you can either detach from it by using the @w{@code{detach inferior}} command (allowing it to run independently), or kill it using the @w{@code{kill inferior}} -command. @xref{Inferiors, ,Debugging Multiple Inferiors}. +command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors +and Programs}. If you ask to debug a child process and a @code{vfork} is followed by an @code{exec}, @value{GDBN} executes the new target up to the first @@ -2836,9 +2959,68 @@ On some systems, when a child process is spawned by @code{vfork}, you cannot debug the child or parent until an @code{exec} call completes. If you issue a @code{run} command to @value{GDBN} after an @code{exec} -call executes, the new target restarts. To restart the parent process, -use the @code{file} command with the parent executable name as its -argument. +call executes, the new target restarts. To restart the parent +process, use the @code{file} command with the parent executable name +as its argument. By default, after an @code{exec} call executes, +@value{GDBN} discards the symbols of the previous executable image. +You can change this behaviour with the @w{@code{set follow-exec-mode}} +command. + +@table @code +@kindex set follow-exec-mode +@item set follow-exec-mode @var{mode} + +Set debugger response to a program call of @code{exec}. An +@code{exec} call replaces the program image of a process. + +@code{follow-exec-mode} can be: + +@table @code +@item new +@value{GDBN} creates a new inferior and rebinds the process to this +new inferior. The program the process was running before the +@code{exec} call can be restarted afterwards by restarting the +original inferior. + +For example: + +@smallexample +(@value{GDBP}) info inferiors +(gdb) info inferior + Id Description Executable +* 1 prog1 +(@value{GDBP}) run +process 12020 is executing new program: prog2 +Program exited normally. +(@value{GDBP}) info inferiors + Id Description Executable +* 2 prog2 + 1 prog1 +@end smallexample + +@item same +@value{GDBN} keeps the process bound to the same inferior. The new +executable image replaces the previous executable loaded in the +inferior. Restarting the inferior after the @code{exec} call, with +e.g., the @code{run} command, restarts the executable the process was +running after the @code{exec} call. This is the default mode. + +For example: + +@smallexample +(@value{GDBP}) info inferiors + Id Description Executable +* 1 prog1 +(@value{GDBP}) run +process 12020 is executing new program: prog2 +Program exited normally. +(@value{GDBP}) info inferiors + Id Description Executable +* 1 prog2 +@end smallexample + +@end table +@end table You can use the @code{catch} command to make @value{GDBN} stop whenever a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set @@ -5032,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 @@ -5174,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})} @@ -5334,9 +5516,25 @@ oldest record to make room for each new one, without asking. @item show record stop-at-limit Show the current setting of @code{stop-at-limit}. -@kindex info record insn-number -@item info record insn-number -Show the current number of recorded instructions. +@kindex info record +@item info record +Show various statistics about the state of process record and its +in-memory execution log buffer, including: + +@itemize @bullet +@item +Whether in record mode or replay mode. +@item +Lowest recorded instruction number (counting from when the current execution log started recording instructions). +@item +Highest recorded instruction number. +@item +Current instruction about to be replayed (if in replay mode). +@item +Number of instructions contained in the execution log. +@item +Maximum number of instructions that may be contained in the execution log. +@end itemize @kindex record delete @kindex rec del @@ -6341,48 +6539,58 @@ 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. @end table 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 -0x32cc : ldil 0x3000,r31 -0x32d0 : ble 0x3f8(sr4,r31) -0x32d4 : ldo 0(r31),rp -0x32d8 : addil -0x800,dp -0x32dc : ldo 0x588(r1),r26 -0x32e0 : ldil 0x3000,r31 + 0x32c4 : addil 0,dp + 0x32c8 : ldw 0x22c(sr0,r1),r26 + 0x32cc : ldil 0x3000,r31 + 0x32d0 : ble 0x3f8(sr4,r31) + 0x32d4 : ldo 0(r31),rp + 0x32d8 : addil -0x800,dp + 0x32dc : ldo 0x588(r1),r26 + 0x32e0 : ldil 0x3000,r31 End of assembler dump. @end smallexample -Here is an example showing mixed source+assembly for Intel x86: +Here is an example showing mixed source+assembly for Intel x86, when the +program is stopped just after function prologue: @smallexample (@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 @@ -7062,6 +7270,18 @@ with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, the repeat count @var{n} is used again; the other arguments default as for successive uses of @code{x}. +When examining machine instructions, the instruction at current program +counter is shown with a @code{=>} marker. For example: + +@smallexample +(@value{GDBP}) x/5i $pc-6 + 0x804837f : mov %esp,%ebp + 0x8048381 : push %ecx + 0x8048382 : sub $0x4,%esp +=> 0x8048385 : movl $0x8048460,(%esp) + 0x804838c : call 0x80482d4 +@end smallexample + @cindex @code{$_}, @code{$__}, and value history The addresses and contents printed by the @code{x} command are not saved in the value history because there is often too much of them and they @@ -9111,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:: @@ -9277,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 @@ -9352,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 @@ -9369,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 @@ -9709,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} @@ -12704,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} @@ -13868,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 @@ -14900,6 +15201,13 @@ Disable or enable general debugging messages. Disable or enable specific debugging messages associated with the remote protocol (@pxref{Remote Protocol}). +@item monitor set libthread-db-search-path [PATH] +@cindex gdbserver, search path for @code{libthread_db} +When this command is issued, @var{path} is a colon-separated list of +directories to search for @code{libthread_db} (@pxref{Threads,,set +libthread-db-search-path}). If you omit @var{path}, +@samp{libthread-db-search-path} will be reset to an empty list. + @item monitor exit Tell gdbserver to exit immediately. This command should be followed by @code{disconnect} to close the debugging session. @code{gdbserver} will @@ -15011,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 @@ -15900,10 +16236,20 @@ counts of various errors encountered so far. @cindex Cygwin-specific commands @value{GDBN} supports native debugging of MS Windows programs, including -DLLs with and without symbolic debugging information. There are various -additional Cygwin-specific commands, described in this section. -Working with DLLs that have no debugging symbols is described in -@ref{Non-debug DLL Symbols}. +DLLs with and without symbolic debugging information. + +@cindex Ctrl-BREAK, MS-Windows +@cindex interrupt debuggee on MS-Windows +MS-Windows programs that call @code{SetConsoleMode} to switch off the +special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted +by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows +supports @kbd{C-@key{BREAK}} as an alternative interrupt key +sequence, which can be used to interrupt the debuggee even if it +ignores @kbd{C-c}. + +There are various additional Cygwin-specific commands, described in +this section. Working with DLLs that have no debugging symbols is +described in @ref{Non-debug DLL Symbols}. @table @code @kindex info w32 @@ -16560,6 +16906,7 @@ acceptable commands. * ARM:: ARM RDI * M32R/D:: Renesas M32R/D * M68K:: Motorola M68K +* MicroBlaze:: Xilinx MicroBlaze * MIPS Embedded:: MIPS Embedded * OpenRISC 1000:: OpenRisc 1000 * PA:: HP PA Embedded @@ -16811,6 +17158,44 @@ dBUG ROM monitor for Motorola ColdFire. @end table +@node MicroBlaze +@subsection MicroBlaze +@cindex Xilinx MicroBlaze +@cindex XMD, Xilinx Microprocessor Debugger + +The MicroBlaze is a soft-core processor supported on various Xilinx +FPGAs, such as Spartan or Virtex series. Boards with these processors +usually have JTAG ports which connect to a host system running the Xilinx +Embedded Development Kit (EDK) or Software Development Kit (SDK). +This host system is used to download the configuration bitstream to +the target FPGA. The Xilinx Microprocessor Debugger (XMD) program +communicates with the target board using the JTAG interface and +presents a @code{gdbserver} interface to the board. By default +@code{xmd} uses port @code{1234}. (While it is possible to change +this default port, it requires the use of undocumented @code{xmd} +commands. Contact Xilinx support if you need to do this.) + +Use these GDB commands to connect to the MicroBlaze target processor. + +@table @code +@item target remote :1234 +Use this command to connect to the target if you are running @value{GDBN} +on the same system as @code{xmd}. + +@item target remote @var{xmd-host}:1234 +Use this command to connect to the target if it is connected to @code{xmd} +running on a different system named @var{xmd-host}. + +@item load +Use this command to download a program to the MicroBlaze target. + +@item set debug microblaze @var{n} +Enable MicroBlaze-specific debugging messages if non-zero. + +@item show debug microblaze @var{n} +Show MicroBlaze-specific debugging level. +@end table + @node MIPS Embedded @subsection MIPS Embedded @@ -19023,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. @@ -19082,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 @@ -19173,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 @@ -19296,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, @@ -19323,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. @@ -21612,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: @@ -23113,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 @@ -23126,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. @@ -23311,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 @@ -23353,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 @@ -28210,16 +28642,14 @@ Step. Step with signal @var{sig}. The signal @var{sig} should be two hex digits. @item t Stop. -@item T @var{sig} -Stop with signal @var{sig}. The signal @var{sig} should be two hex digits. @end table The optional argument @var{addr} normally associated with the @samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is not supported in @samp{vCont}. -The @samp{t} and @samp{T} actions are only relevant in non-stop mode -(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. +The @samp{t} action is only relevant in non-stop mode +(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. A stop reply should be generated for any affected thread not already stopped. When a thread is stopped by means of a @samp{t} action, the corresponding stop reply should indicate that the thread has stopped with @@ -29136,12 +29566,12 @@ These are the currently defined stub features and their properties: @item @samp{ReverseContinue} @tab No -@tab @samp{+} +@tab @samp{-} @tab No @item @samp{ReverseStep} @tab No -@tab @samp{+} +@tab @samp{-} @tab No @end multitable @@ -29628,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 @@ -29701,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 @@ -29807,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 @@ -29826,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