@cindex repeating command sequences
@kindex C-o @r{(operate-and-get-next)}
The @kbd{C-o} binding is useful for repeating a complex sequence of
-commands. This command accepts the current line, like @kbd{RET}, and
+commands. This command accepts the current line, like @key{RET}, and
then fetches the next line relative to the current line from the history
for editing.
Similar, but print only the outermost @var{n} frames.
@item backtrace full
-Print the values of the local variables also.
@itemx bt full
+@itemx bt full @var{n}
+@itemx bt full -@var{n}
+Print the values of the local variables also. @var{n} specifies the
+number of frames to print, like described above.
@end table
@kindex where
The search path is used to find both program source files and @value{GDBN}
script files (read using the @samp{-command} option and @samp{source} command).
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a list of source path substitution rules. A @dfn{substitution
+rule} specifies how to rewrite source directories stored in the program's
+debug information in case the sources were moved to a different
+directory between compilation and debugging. A rule is made of
+two strings, the first specifying what needs to be rewritten in
+the path, and the second specifying how it should be rewritten.
+In @ref{set substitute-path}, we name these two parts @var{from} and
+@var{to} respectively. @value{GDBN} does a simple string replacement
+of @var{from} with @var{to} at the start of the directory part of the
+source file name, and uses that result instead of the original file
+name to look up the sources.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}. The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
+substitution rule, use the @code{set substitute-path} command
+(@pxref{set substitute-path}).
+
+To avoid unexpected substitution results, a rule is applied only if the
+@var{from} part of the directory name ends at a directory separator.
+For instance, a rule substituting @file{/usr/source} into
+@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
+not to @file{/usr/sourceware/foo-2.0}. And because the substitution
+is applied only at the begining of the directory name, this rule will
+not be applied to @file{/root/usr/source/baz.c} either.
+
+In many cases, you can achieve the same result using the @code{directory}
+command. However, @code{set substitute-path} can be more efficient in
+the case where the sources are organized in a complex tree with multiple
+subdirectories. With the @code{directory} command, you need to add each
+subdirectory of your project. If you moved the entire tree while
+preserving its internal organization, then @code{set substitute-path}
+allows you to direct the debugger to all the sources with one single
+command.
+
+@code{set substitute-path} is also more than just a shortcut command.
+The source path is only used if the file at the original location no
+longer exists. On the other hand, @code{set substitute-path} modifies
+the debugger behavior to look at the rewritten location instead. So, if
+for any reason a source file that is not relevant to your executable is
+located at the original location, a substitution rule is the only
+method available to point GDB at the new location.
+
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
@item show directories
@kindex show directories
Print the source path: show which directories it contains.
+
+@anchor{set substitute-path}
+@item set substitute-path @var{from} @var{to}
+@kindex set substitute-path
+Define a source path substitution rule, and add it at the end of the
+current list of existing substitution rules. If a rule with the same
+@var{from} was already defined, then the old rule is also deleted.
+
+For example, if the file @file{/foo/bar/baz.c} was moved to
+@file{/mnt/cross/baz.c}, then the command
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+@end smallexample
+
+@noindent
+will tell @value{GDBN} to replace @samp{/usr/src} with
+@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
+@file{baz.c} even though it was moved.
+
+In the case when more than one substitution rule have been defined,
+the rules are evaluated one by one in the order where they have been
+defined. The first one matching, if any, is selected to perform
+the substitution.
+
+For instance, if we had entered the following commands:
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src/include /mnt/include
+(@value{GDBP}) set substitute-path /usr/src /mnt/src
+@end smallexample
+
+@noindent
+@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
+@file{/mnt/include/defs.h} by using the first rule. However, it would
+use the second rule to rewrite @file{/usr/src/lib/foo.c} into
+@file{/mnt/src/lib/foo.c}.
+
+
+@item unset substitute-path [path]
+@kindex unset substitute-path
+If a path is specified, search the current list of substitution rules
+for a rule that would rewrite that path. Delete that rule if found.
+A warning is emitted by the debugger if no rule could be found.
+
+If no path is specified, then all substitution rules are deleted.
+
+@item show substitute-path [path]
+@kindex show substitute-path
+If a path is specified, then print the source path substitution rule
+which would rewrite that path, if any.
+
+If no path is specified, then print all existing source path substitution
+rules.
+
@end table
If your source path is cluttered with directories that are no longer of
Depending on the configuration and operating system facilities,
@value{GDBN} may be able to show you this information. For remote
targets, this functionality may further depend on the remote stub's
-support of the @samp{qPart:auxv:read} packet, see @ref{Remote
+support of the @samp{qXfer:auxv:read} packet, see @ref{Remote
configuration, auxiliary vector}.
@table @code
@cindex memory region attributes
@dfn{Memory region attributes} allow you to describe special handling
-required by regions of your target's memory. @value{GDBN} uses attributes
-to determine whether to allow certain types of memory accesses; whether to
-use specific width accesses; and whether to cache target memory.
+required by regions of your target's memory. @value{GDBN} uses
+attributes to determine whether to allow certain types of memory
+accesses; whether to use specific width accesses; and whether to cache
+target memory. By default the description of memory regions is
+fetched from the target (if the current target supports this), but the
+user can override the fetched regions.
Defined memory regions can be individually enabled and disabled. When a
memory region is disabled, @value{GDBN} uses the default attributes when
case: it is treated as the the target's maximum memory address.
(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
+@item mem auto
+Discard any user changes to the memory regions and use target-supplied
+regions, if available, or no regions if the target does not support.
+
@kindex delete mem
@item delete mem @var{nums}@dots{}
Remove memory regions @var{nums}@dots{} from the list of regions
* Target Commands:: Commands for managing targets
* Byte Order:: Choosing target byte order
* Remote:: Remote debugging
-* KOD:: Kernel Object Display
@end menu
Many remote targets require you to download the executable's code once
you've successfully established a connection. You may wish to control
-various aspects of this process, such as the size of the data chunks
-used by @value{GDBN} to download program parts to the remote target.
+various aspects of this process.
@table @code
-@kindex set download-write-size
-@item set download-write-size @var{size}
-Set the write size used when downloading a program. Only used when
-downloading a program onto a remote target. Specify zero or a
-negative value to disable blocked writes. The actual size of each
-transfer is also limited by the size of the target packet and the
-memory cache.
-
-@kindex show download-write-size
-@item show download-write-size
-@kindex show download-write-size
-Show the current value of the write size.
@item set hash
@kindex set hash@r{, for remote monitors}
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
+Depending on the remote side capabilities, @value{GDBN} may be able to
+load programs into flash memory.
+
@code{load} does not repeat if you press @key{RET} again after using it.
@end table
@end table
-@node KOD
-@section Kernel Object Display
-@cindex kernel object display
-@cindex KOD
-
-Some targets support kernel object display. Using this facility,
-@value{GDBN} communicates specially with the underlying operating system
-and can display information about operating system-level objects such as
-mutexes and other synchronization objects. Exactly which objects can be
-displayed is determined on a per-OS basis.
-
-@kindex set os
-Use the @code{set os} command to set the operating system. This tells
-@value{GDBN} which kernel object display module to initialize:
-
-@smallexample
-(@value{GDBP}) set os cisco
-@end smallexample
-
-@kindex show os
-The associated command @code{show os} displays the operating system
-set with the @code{set os} command; if no operating system has been
-set, @code{show os} will display an empty string @samp{""}.
-
-If @code{set os} succeeds, @value{GDBN} will display some information
-about the operating system, and will create a new @code{info} command
-which can be used to query the target. The @code{info} command is named
-after the operating system:
-
-@kindex info cisco
-@smallexample
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object Description
-any Any and all objects
-@end smallexample
-
-Further subcommands can be used to query about particular objects known
-by the kernel.
-
-There is currently no way to determine whether a given operating
-system is supported other than to try setting it with @kbd{set os
-@var{name}}, where @var{name} is the name of the operating system you
-want to try.
-
-
@node Remote Debugging
@chapter Debugging remote programs
@cindex interrupting remote programs
@cindex remote programs, interrupting
Whenever @value{GDBN} is waiting for the remote program, if you type the
-interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+interrupt character (often @kbd{C-c}), @value{GDBN} attempts to stop the
program. This may or may not succeed, depending in part on the hardware
and the serial drivers the remote system uses. If you type the
interrupt character once again, @value{GDBN} displays this prompt:
@cindex BREAK signal instead of Ctrl-C
@anchor{set remotebreak}
If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
-when you press the @key{Ctrl-C} key to interrupt the program running
+when you type @kbd{C-c} to interrupt the program running
on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
character instead. The default is off, since most remote systems
expect to see @samp{Ctrl-C} as the interrupt signal.
@item set remote read-aux-vector-packet
@cindex auxiliary vector of remote target
@cindex @code{auxv}, and remote targets
-Set the use of the remote protocol's @samp{qPart:auxv:read} (target
-auxiliary vector read) request. This request is used to fetch the
+Set the use of the remote protocol's @samp{qXfer:auxv:read} (target
+auxiliary vector) request. This request is used to fetch the
remote target's @dfn{auxiliary vector}, see @ref{OS Information,
Auxiliary Vector}. The default setting depends on the remote stub's
support of this request (@value{GDBN} queries the stub when this
-request is first required). @xref{General Query Packets, qPart}, for
+request is first required). @xref{General Query Packets, qXfer}, for
more information about this request.
@item show remote read-aux-vector-packet
-Show the current setting of use of the @samp{qPart:auxv:read} request.
+Show the current setting of use of the @samp{qXfer:auxv:read} request.
@item set remote symbol-lookup-packet
@cindex remote symbol lookup request
Use the @sc{reset} button on the development board
@itemize @bullet
@item
-to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
+to interrupt your program (don't use @kbd{C-c} on the DOS host---it has
no way to pass an interrupt signal to the development board); and
@item
Connect the controlling terminal to the STDBUG command monitor. When
you are done interacting with STDBUG, typing either of two character
sequences gets you back to the @value{GDBN} command prompt:
-@kbd{@key{RET}~.} (Return, followed by tilde and period) or
-@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
+@kbd{@key{RET} ~ .} (Return, followed by tilde and period) or
+@kbd{@key{RET} ~ C-d} (Return, followed by tilde and control-D).
@end table
@node Z8000
@end table
+@cindex command tracing
+If you need to debug user-defined commands or sourced files you may find it
+useful to enable @dfn{command tracing}. In this mode each command will be
+printed as it is executed, prefixed with one or more @samp{+} symbols, the
+quantity denoting the call depth of each command.
+
+@table @code
+@kindex set trace-commands
+@cindex command scripts, debugging
+@item set trace-commands on
+Enable command tracing.
+@item set trace-commands off
+Disable command tracing.
+@item show trace-commands
+Display the current state of command tracing.
+@end table
+
@node Debugging Output
@section Optional messages about internal happenings
@cindex optional debugging messages
@table @code
@kindex source
@cindex execute commands from a file
-@item source @var{filename}
+@item source [@code{-v}] @var{filename}
Execute the command file @var{filename}.
@end table
@value{GDBN} searches for @var{filename} in the current directory and then
on the search path (specified with the @samp{directory} command).
+If @code{-v}, for verbose mode, is given then @value{GDBN} displays
+each command as it is executed. The option must be given before
+@var{filename}, and is interpreted as part of the filename anywhere else.
+
Commands that would ask for confirmation if used interactively proceed
without asking when used in a command file. Many @value{GDBN} commands that
normally print messages to say what they are doing omit the messages
for scrolling. This means they are available for readline when the
active window is the command window. When the command window
does not have the focus, it is necessary to use other readline
-key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}.
+key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} and @kbd{C-f}.
@node TUI Single Key Mode
@section TUI Single Key Mode
it is possible to type most @value{GDBN} commands without interaction
with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
@emph{SingleKey} mode is restored. The only way to permanently leave
-this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}.
+this mode is by typing @kbd{q} or @kbd{C-x s}.
@node TUI Commands
@item refresh
@kindex refresh
-Refresh the screen. This is similar to using @key{C-L} key.
+Refresh the screen. This is similar to typing @kbd{C-L}.
@item tui reg float
@kindex tui reg
@value{GDBN} @code{down} command.
@end table
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break})
+In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
tells @value{GDBN} to set a breakpoint on the source line point is on.
If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
* GDB/MI Simple Examples::
* GDB/MI Command Description Format::
* GDB/MI Breakpoint Commands::
+* GDB/MI Program Context::
+* GDB/MI Thread Commands::
+* GDB/MI Program Execution::
+* GDB/MI Stack Manipulation::
+* GDB/MI Variable Objects::
* GDB/MI Data Manipulation::
-* GDB/MI Program Control::
+* GDB/MI Tracepoint Commands::
+* GDB/MI Symbol Query::
* GDB/MI File Commands::
@ignore
* GDB/MI Kod Commands::
* GDB/MI Memory Overlay Commands::
* GDB/MI Signal Handling Commands::
@end ignore
-* GDB/MI Stack Manipulation::
-* GDB/MI Symbol Query::
* GDB/MI Target Manipulation::
-* GDB/MI Thread Commands::
-* GDB/MI Tracepoint Commands::
-* GDB/MI Variable Objects::
* GDB/MI Miscellaneous Commands::
@end menu
The output from @sc{gdb/mi} consists of zero or more out-of-band records
followed, optionally, by a single result record. This result record
is for the most recent command. The sequence of output records is
-terminated by @samp{(@value{GDBP})}.
+terminated by @samp{(gdb)}.
If an input command was prefixed with a @code{@var{token}} then the
corresponding output for that command will also be prefixed by that same
@table @code
@item @var{output} @expansion{}
-@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
+@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
@item @var{result-record} @expansion{}
@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
@cindex compatibility, @sc{gdb/mi} and CLI
@cindex @sc{gdb/mi}, compatibility with CLI
-For the developers convenience CLI commands can be entered directly.
-However, CLI commands that use sequences of commands such @code{source},
-@code{commands} will not work and commands that result in queries such
-as pending breakpoints and quitting once execution has started will
-default to yes.
+For the developers convenience CLI commands can be entered directly,
+but there may be some unexpected behaviour. For example, commands
+that query the user will behave as if the user replied yes, breakpoint
+command lists are not executed and some CLI commands, such as
+@code{if}, @code{when} and @code{define}, prompt for further input with
+@samp{>}, which is not valid MI output.
This feature may be removed at some stage in the future and it is
-recommended that front ends use the @code{-interpreter exec} command.
-@xref{GDB/MI Miscellaneous Commands}.
+recommended that front ends use the @code{-interpreter-exec} command
+(@pxref{-interpreter-exec}).
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Development and Front Ends
<- ^exit
@end smallexample
-@subsubheading A Bad Command
+@subheading A Bad Command
Here's what happens if you pass a non-existent command:
@smallexample
-> -rubbish
<- ^error,msg="Undefined MI command: rubbish"
-<- (@value{GDBP})
+<- (gdb)
@end smallexample
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-insert main
^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"@}
-(@value{GDBP})
+(gdb)
-break-after 1 3
~
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0",ignore="3"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@ignore
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-condition 1 1
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",cond="1",times="0",ignore="3"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-delete} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-delete 1
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-disable} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-disable 2
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-enable} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-enable 2
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-info} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-insert main
^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="4",times="0"@}
-(@value{GDBP})
+(gdb)
-break-insert -t foo
^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="11",times="0"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",
fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
-(@value{GDBP})
+(gdb)
-break-insert -r foo.*
~int foo(int, int);
^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
"fullname="/home/foo/recursive2.c",line="11",times="0"@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-list} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
line="13",times="0"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
Here's an example of the result when there are no breakpoints:
@smallexample
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-watch} Command
Setting a watchpoint on a variable in the @code{main} function:
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch x
^done,wpt=@{number="2",exp="x"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
frame=@{func="main",args=[],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="5"@}
-(@value{GDBP})
+(gdb)
@end smallexample
Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
for the watchpoint going out of scope.
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch C
^done,wpt=@{number="5",exp="C"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
+(gdb)
@end smallexample
Listing breakpoints and watchpoints, at different points in the program
deleted.
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch C
^done,wpt=@{number="2",exp="C"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@},
bkpt=@{number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="0"@}]@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
bkpt=@{number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="-5"@}]@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
times="1"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Data Manipulation
-@section @sc{gdb/mi} Data Manipulation
-
-@cindex data manipulation, in @sc{gdb/mi}
-@cindex @sc{gdb/mi}, data manipulation
-This section describes the @sc{gdb/mi} commands that manipulate data:
-examine memory and registers, evaluate expressions, etc.
+@node GDB/MI Program Context
+@section @sc{gdb/mi} Program Context
-@c REMOVED FROM THE INTERFACE.
-@c @subheading -data-assign
-@c Change the value of a program variable. Plenty of side effects.
-@c @subsubheading GDB command
-@c set variable
-@c @subsubheading Example
-@c N.A.
+@subheading The @code{-exec-arguments} Command
+@findex -exec-arguments
-@subheading The @code{-data-disassemble} Command
-@findex -data-disassemble
@subsubheading Synopsis
@smallexample
- -data-disassemble
- [ -s @var{start-addr} -e @var{end-addr} ]
- | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
- -- @var{mode}
+ -exec-arguments @var{args}
@end smallexample
-@noindent
-Where:
-
-@table @samp
-@item @var{start-addr}
-is the beginning address (or @code{$pc})
-@item @var{end-addr}
-is the end address
-@item @var{filename}
-is the name of the file to disassemble
-@item @var{linenum}
-is the line number to disassemble around
-@item @var{lines}
-is the the number of disassembly lines to be produced. If it is -1,
-the whole function will be disassembled, in case no @var{end-addr} is
-specified. If @var{end-addr} is specified as a non-zero value, and
-@var{lines} is lower than the number of disassembly lines between
-@var{start-addr} and @var{end-addr}, only @var{lines} lines are
-displayed; if @var{lines} is higher than the number of lines between
-@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
-are displayed.
-@item @var{mode}
-is either 0 (meaning only disassembly) or 1 (meaning mixed source and
-disassembly).
-@end table
-
-@subsubheading Result
-
-The output for each instruction is composed of four fields:
-
-@itemize @bullet
-@item Address
-@item Func-name
-@item Offset
-@item Instruction
-@end itemize
-
-Note that whatever included in the instruction field, is not manipulated
-directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
+Set the inferior program arguments, to be used in the next
+@samp{-exec-run}.
@subsubheading @value{GDBN} Command
-There's no direct mapping from this command to the CLI.
+The corresponding @value{GDBN} command is @samp{set args}.
@subsubheading Example
-Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
+@c FIXME!
+Don't have one around.
-@smallexample
-(@value{GDBP})
--data-disassemble -s $pc -e "$pc + 20" -- 0
-^done,
-asm_insns=[
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
-@{address="0x000107c4",func-name="main",offset="8",
-inst="sethi %hi(0x11800), %o2"@},
-@{address="0x000107c8",func-name="main",offset="12",
-inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
-@{address="0x000107cc",func-name="main",offset="16",
-inst="sethi %hi(0x11800), %o2"@},
-@{address="0x000107d0",func-name="main",offset="20",
-inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
-(@value{GDBP})
-@end smallexample
-Disassemble the whole @code{main} function. Line 32 is part of
-@code{main}.
+@subheading The @code{-exec-show-arguments} Command
+@findex -exec-show-arguments
+
+@subsubheading Synopsis
@smallexample
--data-disassemble -f basics.c -l 32 -- 0
-^done,asm_insns=[
-@{address="0x000107bc",func-name="main",offset="0",
-inst="save %sp, -112, %sp"@},
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
-@{address="0x000107c4",func-name="main",offset="8",
-inst="sethi %hi(0x11800), %o2"@},
-[@dots{}]
-@{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
-@{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
-(@value{GDBP})
+ -exec-show-arguments
@end smallexample
-Disassemble 3 instructions from the start of @code{main}:
+Print the arguments of the program.
-@smallexample
-(@value{GDBP})
--data-disassemble -f basics.c -l 32 -n 3 -- 0
-^done,asm_insns=[
-@{address="0x000107bc",func-name="main",offset="0",
-inst="save %sp, -112, %sp"@},
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
-@{address="0x000107c4",func-name="main",offset="8",
-inst="sethi %hi(0x11800), %o2"@}]
-(@value{GDBP})
-@end smallexample
+@subsubheading @value{GDBN} Command
-Disassemble 3 instructions from the start of @code{main} in mixed mode:
+The corresponding @value{GDBN} command is @samp{show args}.
-@smallexample
-(@value{GDBP})
--data-disassemble -f basics.c -l 32 -n 3 -- 1
-^done,asm_insns=[
-src_and_asm_line=@{line="31",
-file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
- testsuite/gdb.mi/basics.c",line_asm_insn=[
-@{address="0x000107bc",func-name="main",offset="0",
-inst="save %sp, -112, %sp"@}]@},
-src_and_asm_line=@{line="32",
-file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
- testsuite/gdb.mi/basics.c",line_asm_insn=[
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
-@{address="0x000107c4",func-name="main",offset="8",
-inst="sethi %hi(0x11800), %o2"@}]@}]
-(@value{GDBP})
-@end smallexample
+@subsubheading Example
+N.A.
-@subheading The @code{-data-evaluate-expression} Command
-@findex -data-evaluate-expression
+@subheading The @code{-environment-cd} Command
+@findex -environment-cd
@subsubheading Synopsis
@smallexample
- -data-evaluate-expression @var{expr}
+ -environment-cd @var{pathdir}
@end smallexample
-Evaluate @var{expr} as an expression. The expression could contain an
-inferior function call. The function call will execute synchronously.
-If the expression contains spaces, it must be enclosed in double quotes.
+Set @value{GDBN}'s working directory.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
-@samp{call}. In @code{gdbtk} only, there's a corresponding
-@samp{gdb_eval} command.
+The corresponding @value{GDBN} command is @samp{cd}.
@subsubheading Example
-In the following example, the numbers that precede the commands are the
-@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
-Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
-output.
-
@smallexample
-211-data-evaluate-expression A
-211^done,value="1"
-(@value{GDBP})
-311-data-evaluate-expression &A
-311^done,value="0xefffeb7c"
-(@value{GDBP})
-411-data-evaluate-expression A+3
-411^done,value="4"
-(@value{GDBP})
-511-data-evaluate-expression "A + 3"
-511^done,value="4"
-(@value{GDBP})
+(gdb)
+-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done
+(gdb)
@end smallexample
-@subheading The @code{-data-list-changed-registers} Command
-@findex -data-list-changed-registers
+@subheading The @code{-environment-directory} Command
+@findex -environment-directory
@subsubheading Synopsis
@smallexample
- -data-list-changed-registers
+ -environment-directory [ -r ] [ @var{pathdir} ]+
@end smallexample
-Display a list of the registers that have changed.
+Add directories @var{pathdir} to beginning of search path for source files.
+If the @samp{-r} option is used, the search path is reset to the default
+search path. If directories @var{pathdir} are supplied in addition to the
+@samp{-r} option, the search path is first reset and then addition
+occurs as normal.
+Multiple directories may be specified, separated by blanks. Specifying
+multiple directories in a single command
+results in the directories added to the beginning of the
+search path in the same order they were presented in the command.
+If blanks are needed as
+part of a directory name, double-quotes should be used around
+the name. In the command output, the path will show up separated
+by the system directory-separator character. The directory-seperator
+character must not be used
+in any directory name.
+If no directories are specified, the current search path is displayed.
@subsubheading @value{GDBN} Command
-@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
-has the corresponding command @samp{gdb_changed_register_list}.
+The corresponding @value{GDBN} command is @samp{dir}.
@subsubheading Example
-On a PPC MBX board:
-
@smallexample
-(@value{GDBP})
--exec-continue
-^running
-
-(@value{GDBP})
-*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
-args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@}
-(@value{GDBP})
--data-list-changed-registers
-^done,changed-registers=["0","1","2","4","5","6","7","8","9",
-"10","11","13","14","15","16","17","18","19","20","21","22","23",
-"24","25","26","27","28","30","31","64","65","66","67","69"]
-(@value{GDBP})
+(gdb)
+-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+(gdb)
+-environment-directory ""
+^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+(gdb)
+-environment-directory -r /home/jjohnstn/src/gdb /usr/src
+^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
+(gdb)
+-environment-directory -r
+^done,source-path="$cdir:$cwd"
+(gdb)
@end smallexample
-@subheading The @code{-data-list-register-names} Command
-@findex -data-list-register-names
+@subheading The @code{-environment-path} Command
+@findex -environment-path
@subsubheading Synopsis
@smallexample
- -data-list-register-names [ ( @var{regno} )+ ]
+ -environment-path [ -r ] [ @var{pathdir} ]+
@end smallexample
-Show a list of register names for the current target. If no arguments
-are given, it shows a list of the names of all the registers. If
-integer numbers are given as arguments, it will print a list of the
-names of the registers corresponding to the arguments. To ensure
-consistency between a register name and its number, the output list may
-include empty register names.
+Add directories @var{pathdir} to beginning of search path for object files.
+If the @samp{-r} option is used, the search path is reset to the original
+search path that existed at gdb start-up. If directories @var{pathdir} are
+supplied in addition to the
+@samp{-r} option, the search path is first reset and then addition
+occurs as normal.
+Multiple directories may be specified, separated by blanks. Specifying
+multiple directories in a single command
+results in the directories added to the beginning of the
+search path in the same order they were presented in the command.
+If blanks are needed as
+part of a directory name, double-quotes should be used around
+the name. In the command output, the path will show up separated
+by the system directory-separator character. The directory-seperator
+character must not be used
+in any directory name.
+If no directories are specified, the current path is displayed.
+
@subsubheading @value{GDBN} Command
-@value{GDBN} does not have a command which corresponds to
-@samp{-data-list-register-names}. In @code{gdbtk} there is a
-corresponding command @samp{gdb_regnames}.
+The corresponding @value{GDBN} command is @samp{path}.
@subsubheading Example
-For the PPC MBX board:
@smallexample
-(@value{GDBP})
--data-list-register-names
-^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
-"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
-"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
-"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
-"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
-"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
-"", "pc","ps","cr","lr","ctr","xer"]
-(@value{GDBP})
--data-list-register-names 1 2 3
-^done,register-names=["r1","r2","r3"]
-(@value{GDBP})
+(gdb)
+-environment-path
+^done,path="/usr/bin"
+(gdb)
+-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
+^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
+(gdb)
+-environment-path -r /usr/local/bin
+^done,path="/usr/local/bin:/usr/bin"
+(gdb)
@end smallexample
-@subheading The @code{-data-list-register-values} Command
-@findex -data-list-register-values
+
+@subheading The @code{-environment-pwd} Command
+@findex -environment-pwd
@subsubheading Synopsis
@smallexample
- -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ -environment-pwd
@end smallexample
-Display the registers' contents. @var{fmt} is the format according to
-which the registers' contents are to be returned, followed by an optional
-list of numbers specifying the registers to display. A missing list of
-numbers indicates that the contents of all the registers must be returned.
-
-Allowed formats for @var{fmt} are:
-
-@table @code
-@item x
-Hexadecimal
-@item o
-Octal
-@item t
-Binary
-@item d
-Decimal
-@item r
-Raw
-@item N
-Natural
-@end table
+Show the current working directory.
-@subsubheading @value{GDBN} Command
+@subsubheading @value{GDBN} command
-The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
-all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
+The corresponding @value{GDBN} command is @samp{pwd}.
@subsubheading Example
-For a PPC MBX board (note: line breaks are for readability only, they
-don't appear in the actual output):
-
@smallexample
-(@value{GDBP})
--data-list-register-values r 64 65
-^done,register-values=[@{number="64",value="0xfe00a300"@},
-@{number="65",value="0x00029002"@}]
-(@value{GDBP})
--data-list-register-values x
-^done,register-values=[@{number="0",value="0xfe0043c8"@},
-@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
-@{number="3",value="0x0"@},@{number="4",value="0xa"@},
-@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
-@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
-@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
-@{number="11",value="0x1"@},@{number="12",value="0x0"@},
-@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
-@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
-@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
-@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
-@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
-@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
-@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
-@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
-@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
-@{number="31",value="0x0"@},@{number="32",value="0x0"@},
-@{number="33",value="0x0"@},@{number="34",value="0x0"@},
-@{number="35",value="0x0"@},@{number="36",value="0x0"@},
-@{number="37",value="0x0"@},@{number="38",value="0x0"@},
-@{number="39",value="0x0"@},@{number="40",value="0x0"@},
-@{number="41",value="0x0"@},@{number="42",value="0x0"@},
-@{number="43",value="0x0"@},@{number="44",value="0x0"@},
-@{number="45",value="0x0"@},@{number="46",value="0x0"@},
-@{number="47",value="0x0"@},@{number="48",value="0x0"@},
-@{number="49",value="0x0"@},@{number="50",value="0x0"@},
-@{number="51",value="0x0"@},@{number="52",value="0x0"@},
-@{number="53",value="0x0"@},@{number="54",value="0x0"@},
-@{number="55",value="0x0"@},@{number="56",value="0x0"@},
-@{number="57",value="0x0"@},@{number="58",value="0x0"@},
-@{number="59",value="0x0"@},@{number="60",value="0x0"@},
-@{number="61",value="0x0"@},@{number="62",value="0x0"@},
-@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
-@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
-@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
-@{number="69",value="0x20002b03"@}]
-(@value{GDBP})
+(gdb)
+-environment-pwd
+^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
+(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Thread Commands
+@section @sc{gdb/mi} Thread Commands
+
-@subheading The @code{-data-read-memory} Command
-@findex -data-read-memory
+@subheading The @code{-thread-info} Command
+@findex -thread-info
@subsubheading Synopsis
@smallexample
- -data-read-memory [ -o @var{byte-offset} ]
- @var{address} @var{word-format} @var{word-size}
- @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
+ -thread-info
@end smallexample
-@noindent
-where:
+@subsubheading @value{GDBN} command
-@table @samp
-@item @var{address}
-An expression specifying the address of the first memory word to be
-read. Complex expressions containing embedded white space should be
-quoted using the C convention.
+No equivalent.
-@item @var{word-format}
-The format to be used to print the memory words. The notation is the
-same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
-,Output formats}).
+@subsubheading Example
+N.A.
-@item @var{word-size}
-The size of each memory word in bytes.
-@item @var{nr-rows}
-The number of rows in the output table.
+@subheading The @code{-thread-list-all-threads} Command
+@findex -thread-list-all-threads
-@item @var{nr-cols}
-The number of columns in the output table.
+@subsubheading Synopsis
-@item @var{aschar}
-If present, indicates that each row should include an @sc{ascii} dump. The
-value of @var{aschar} is used as a padding character when a byte is not a
-member of the printable @sc{ascii} character set (printable @sc{ascii}
-characters are those whose code is between 32 and 126, inclusively).
+@smallexample
+ -thread-list-all-threads
+@end smallexample
-@item @var{byte-offset}
-An offset to add to the @var{address} before fetching memory.
-@end table
+@subsubheading @value{GDBN} Command
-This command displays memory contents as a table of @var{nr-rows} by
-@var{nr-cols} words, each word being @var{word-size} bytes. In total,
-@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
-(returned as @samp{total-bytes}). Should less than the requested number
-of bytes be returned by the target, the missing words are identified
-using @samp{N/A}. The number of bytes read from the target is returned
-in @samp{nr-bytes} and the starting address used to read memory in
-@samp{addr}.
+The equivalent @value{GDBN} command is @samp{info threads}.
-The address of the next/previous row or page is available in
-@samp{next-row} and @samp{prev-row}, @samp{next-page} and
-@samp{prev-page}.
-
-@subsubheading @value{GDBN} Command
+@subsubheading Example
+N.A.
-The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
-@samp{gdb_get_mem} memory read command.
-@subsubheading Example
+@subheading The @code{-thread-list-ids} Command
+@findex -thread-list-ids
-Read six bytes of memory starting at @code{bytes+6} but then offset by
-@code{-6} bytes. Format as three rows of two columns. One byte per
-word. Display each word in hex.
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
-9-data-read-memory -o -6 -- bytes+6 x 1 3 2
-9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
-next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
-prev-page="0x0000138a",memory=[
-@{addr="0x00001390",data=["0x00","0x01"]@},
-@{addr="0x00001392",data=["0x02","0x03"]@},
-@{addr="0x00001394",data=["0x04","0x05"]@}]
-(@value{GDBP})
+ -thread-list-ids
@end smallexample
-Read two bytes of memory starting at address @code{shorts + 64} and
-display as a single word formatted in decimal.
+Produces a list of the currently known @value{GDBN} thread ids. At the
+end of the list it also prints the total number of such threads.
+
+@subsubheading @value{GDBN} Command
+
+Part of @samp{info threads} supplies the same information.
+
+@subsubheading Example
+
+No threads present, besides the main process:
@smallexample
-(@value{GDBP})
-5-data-read-memory shorts+64 d 2 1 1
-5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
-next-row="0x00001512",prev-row="0x0000150e",
-next-page="0x00001512",prev-page="0x0000150e",memory=[
-@{addr="0x00001510",data=["128"]@}]
-(@value{GDBP})
+(gdb)
+-thread-list-ids
+^done,thread-ids=@{@},number-of-threads="0"
+(gdb)
@end smallexample
-Read thirty two bytes of memory starting at @code{bytes+16} and format
-as eight rows of four columns. Include a string encoding with @samp{x}
-used as the non-printable character.
+
+Several threads:
@smallexample
-(@value{GDBP})
-4-data-read-memory bytes+16 x 1 8 4 x
-4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
-next-row="0x000013c0",prev-row="0x0000139c",
-next-page="0x000013c0",prev-page="0x00001380",memory=[
-@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
-@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
-@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
-@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
-@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
-@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
-@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
-@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
-(@value{GDBP})
+(gdb)
+-thread-list-ids
+^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
+number-of-threads="3"
+(gdb)
@end smallexample
-@subheading The @code{-display-delete} Command
-@findex -display-delete
+
+@subheading The @code{-thread-select} Command
+@findex -thread-select
@subsubheading Synopsis
@smallexample
- -display-delete @var{number}
+ -thread-select @var{threadnum}
@end smallexample
-Delete the display @var{number}.
+Make @var{threadnum} the current thread. It prints the number of the new
+current thread, and the topmost frame for that thread.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{delete display}.
+The corresponding @value{GDBN} command is @samp{thread}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-exec-next
+^running
+(gdb)
+*stopped,reason="end-stepping-range",thread-id="2",line="187",
+file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
+(gdb)
+-thread-list-ids
+^done,
+thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
+number-of-threads="3"
+(gdb)
+-thread-select 3
+^done,new-thread-id="3",
+frame=@{level="0",func="vprintf",
+args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
+@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
+(gdb)
+@end smallexample
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Program Execution
+@section @sc{gdb/mi} Program Execution
+
+These are the asynchronous commands which generate the out-of-band
+record @samp{*stopped}. Currently GDB only really executes
+asynchronously with remote targets and this interaction is mimicked in
+other cases.
-@subheading The @code{-display-disable} Command
-@findex -display-disable
+@subheading The @code{-exec-continue} Command
+@findex -exec-continue
@subsubheading Synopsis
@smallexample
- -display-disable @var{number}
+ -exec-continue
@end smallexample
-Disable display @var{number}.
+Resumes the execution of the inferior program until a breakpoint is
+encountered, or until the inferior exits.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{disable display}.
+The corresponding @value{GDBN} corresponding is @samp{continue}.
@subsubheading Example
-N.A.
+
+@smallexample
+-exec-continue
+^running
+(gdb)
+@@Hello world
+*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
+file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
+(gdb)
+@end smallexample
-@subheading The @code{-display-enable} Command
-@findex -display-enable
+@subheading The @code{-exec-finish} Command
+@findex -exec-finish
@subsubheading Synopsis
@smallexample
- -display-enable @var{number}
+ -exec-finish
@end smallexample
-Enable display @var{number}.
+Resumes the execution of the inferior program until the current
+function is exited. Displays the results returned by the function.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{enable display}.
+The corresponding @value{GDBN} command is @samp{finish}.
@subsubheading Example
-N.A.
-
-@subheading The @code{-display-insert} Command
-@findex -display-insert
-
-@subsubheading Synopsis
+Function returning @code{void}.
@smallexample
- -display-insert @var{expression}
+-exec-finish
+^running
+(gdb)
+@@hello from foo
+*stopped,reason="function-finished",frame=@{func="main",args=[],
+file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
+(gdb)
@end smallexample
-Display @var{expression} every time the program stops.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{display}.
+Function returning other than @code{void}. The name of the internal
+@value{GDBN} variable storing the result is printed, together with the
+value itself.
-@subsubheading Example
-N.A.
+@smallexample
+-exec-finish
+^running
+(gdb)
+*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
+args=[@{name="a",value="1"],@{name="b",value="9"@}@},
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+gdb-result-var="$1",return-value="0"
+(gdb)
+@end smallexample
-@subheading The @code{-display-list} Command
-@findex -display-list
+@subheading The @code{-exec-interrupt} Command
+@findex -exec-interrupt
@subsubheading Synopsis
@smallexample
- -display-list
+ -exec-interrupt
@end smallexample
-List the displays. Do not show the current values.
+Interrupts the background execution of the target. Note how the token
+associated with the stop message is the one for the execution command
+that has been interrupted. The token for the interrupt itself only
+appears in the @samp{^done} output. If the user is trying to
+interrupt a non-running program, an error message will be printed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info display}.
+The corresponding @value{GDBN} command is @samp{interrupt}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+111-exec-continue
+111^running
-@subheading The @code{-environment-cd} Command
-@findex -environment-cd
+(gdb)
+222-exec-interrupt
+222^done
+(gdb)
+111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
+frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="13"@}
+(gdb)
+
+(gdb)
+-exec-interrupt
+^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-exec-next} Command
+@findex -exec-next
@subsubheading Synopsis
@smallexample
- -environment-cd @var{pathdir}
+ -exec-next
@end smallexample
-Set @value{GDBN}'s working directory.
+Resumes execution of the inferior program, stopping when the beginning
+of the next source line is reached.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{cd}.
+The corresponding @value{GDBN} command is @samp{next}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
-^done
-(@value{GDBP})
+-exec-next
+^running
+(gdb)
+*stopped,reason="end-stepping-range",line="8",file="hello.c"
+(gdb)
@end smallexample
-@subheading The @code{-environment-directory} Command
-@findex -environment-directory
+@subheading The @code{-exec-next-instruction} Command
+@findex -exec-next-instruction
@subsubheading Synopsis
@smallexample
- -environment-directory [ -r ] [ @var{pathdir} ]+
+ -exec-next-instruction
@end smallexample
-Add directories @var{pathdir} to beginning of search path for source files.
-If the @samp{-r} option is used, the search path is reset to the default
-search path. If directories @var{pathdir} are supplied in addition to the
-@samp{-r} option, the search path is first reset and then addition
-occurs as normal.
-Multiple directories may be specified, separated by blanks. Specifying
-multiple directories in a single command
-results in the directories added to the beginning of the
-search path in the same order they were presented in the command.
-If blanks are needed as
-part of a directory name, double-quotes should be used around
-the name. In the command output, the path will show up separated
-by the system directory-separator character. The directory-seperator
-character must not be used
-in any directory name.
-If no directories are specified, the current search path is displayed.
+Executes one machine instruction. If the instruction is a function
+call, continues until the function returns. If the program stops at an
+instruction in the middle of a source line, the address will be
+printed as well.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{dir}.
+The corresponding @value{GDBN} command is @samp{nexti}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
-^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
-(@value{GDBP})
--environment-directory ""
-^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
-(@value{GDBP})
--environment-directory -r /home/jjohnstn/src/gdb /usr/src
-^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
-(@value{GDBP})
--environment-directory -r
-^done,source-path="$cdir:$cwd"
-(@value{GDBP})
+(gdb)
+-exec-next-instruction
+^running
+
+(gdb)
+*stopped,reason="end-stepping-range",
+addr="0x000100d4",line="5",file="hello.c"
+(gdb)
@end smallexample
-@subheading The @code{-environment-path} Command
-@findex -environment-path
+@subheading The @code{-exec-return} Command
+@findex -exec-return
@subsubheading Synopsis
@smallexample
- -environment-path [ -r ] [ @var{pathdir} ]+
+ -exec-return
@end smallexample
-Add directories @var{pathdir} to beginning of search path for object files.
-If the @samp{-r} option is used, the search path is reset to the original
-search path that existed at gdb start-up. If directories @var{pathdir} are
-supplied in addition to the
-@samp{-r} option, the search path is first reset and then addition
-occurs as normal.
-Multiple directories may be specified, separated by blanks. Specifying
-multiple directories in a single command
-results in the directories added to the beginning of the
-search path in the same order they were presented in the command.
-If blanks are needed as
-part of a directory name, double-quotes should be used around
-the name. In the command output, the path will show up separated
-by the system directory-separator character. The directory-seperator
-character must not be used
-in any directory name.
-If no directories are specified, the current path is displayed.
-
+Makes current function return immediately. Doesn't execute the inferior.
+Displays the new current frame.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{path}.
+The corresponding @value{GDBN} command is @samp{return}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-path
-^done,path="/usr/bin"
-(@value{GDBP})
--environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
-^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
-(@value{GDBP})
--environment-path -r /usr/local/bin
-^done,path="/usr/local/bin:/usr/bin"
-(@value{GDBP})
+(gdb)
+200-break-insert callee4
+200^done,bkpt=@{number="1",addr="0x00010734",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+(gdb)
+000-exec-run
+000^running
+(gdb)
+000*stopped,reason="breakpoint-hit",bkptno="1",
+frame=@{func="callee4",args=[],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+(gdb)
+205-break-delete
+205^done
+(gdb)
+111-exec-return
+111^done,frame=@{level="0",func="callee3",
+args=[@{name="strarg",
+value="0x11940 \"A string argument.\""@}],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+(gdb)
@end smallexample
-@subheading The @code{-environment-pwd} Command
-@findex -environment-pwd
+@subheading The @code{-exec-run} Command
+@findex -exec-run
@subsubheading Synopsis
@smallexample
- -environment-pwd
+ -exec-run
@end smallexample
-Show the current working directory.
+Starts execution of the inferior from the beginning. The inferior
+executes until either a breakpoint is encountered or the program
+exits. In the latter case the output will include an exit code, if
+the program has exited exceptionally.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{pwd}.
+The corresponding @value{GDBN} command is @samp{run}.
-@subsubheading Example
+@subsubheading Examples
@smallexample
-(@value{GDBP})
--environment-pwd
-^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
-(@value{GDBP})
+(gdb)
+-break-insert main
+^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+*stopped,reason="breakpoint-hit",bkptno="1",
+frame=@{func="main",args=[],file="recursive2.c",
+fullname="/home/foo/bar/recursive2.c",line="4"@}
+(gdb)
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Program Control
-@section @sc{gdb/mi} Program control
-
-These are the asynchronous commands which generate the out-of-band
-record @samp{*stopped}. Currently GDB only really executes
-asynchronously with remote targets and this interaction is mimicked in
-other cases.
+@noindent
+Program exited normally:
-@subheading The @code{-exec-abort} Command
-@findex -exec-abort
+@smallexample
+(gdb)
+-exec-run
+^running
+(gdb)
+x = 55
+*stopped,reason="exited-normally"
+(gdb)
+@end smallexample
-@subsubheading Synopsis
+@noindent
+Program exited exceptionally:
@smallexample
- -exec-abort
+(gdb)
+-exec-run
+^running
+(gdb)
+x = 55
+*stopped,reason="exited",exit-code="01"
+(gdb)
@end smallexample
-Kill the inferior running program.
+Another way the program can terminate is if it receives a signal such as
+@code{SIGINT}. In this case, @sc{gdb/mi} displays this:
-@subsubheading @value{GDBN} Command
+@smallexample
+(gdb)
+*stopped,reason="exited-signalled",signal-name="SIGINT",
+signal-meaning="Interrupt"
+@end smallexample
-The corresponding @value{GDBN} command is @samp{kill}.
-@subsubheading Example
-N.A.
+@c @subheading -exec-signal
-@subheading The @code{-exec-arguments} Command
-@findex -exec-arguments
+@subheading The @code{-exec-step} Command
+@findex -exec-step
@subsubheading Synopsis
@smallexample
- -exec-arguments @var{args}
+ -exec-step
@end smallexample
-Set the inferior program arguments, to be used in the next
-@samp{-exec-run}.
+Resumes execution of the inferior program, stopping when the beginning
+of the next source line is reached, if the next source line is not a
+function call. If it is, stop at the first instruction of the called
+function.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{set args}.
+The corresponding @value{GDBN} command is @samp{step}.
@subsubheading Example
-@c FIXME!
-Don't have one around.
+Stepping into a function:
+
+@smallexample
+-exec-step
+^running
+(gdb)
+*stopped,reason="end-stepping-range",
+frame=@{func="foo",args=[@{name="a",value="10"@},
+@{name="b",value="0"@}],file="recursive2.c",
+fullname="/home/foo/bar/recursive2.c",line="11"@}
+(gdb)
+@end smallexample
+Regular stepping:
+
+@smallexample
+-exec-step
+^running
+(gdb)
+*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
+(gdb)
+@end smallexample
-@subheading The @code{-exec-continue} Command
-@findex -exec-continue
+
+@subheading The @code{-exec-step-instruction} Command
+@findex -exec-step-instruction
@subsubheading Synopsis
@smallexample
- -exec-continue
+ -exec-step-instruction
@end smallexample
-Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits.
+Resumes the inferior which executes one machine instruction. The
+output, once @value{GDBN} has stopped, will vary depending on whether
+we have stopped in the middle of a source line or not. In the former
+case, the address at which the program stopped will be printed as
+well.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} corresponding is @samp{continue}.
+The corresponding @value{GDBN} command is @samp{stepi}.
@subsubheading Example
@smallexample
--exec-continue
+(gdb)
+-exec-step-instruction
^running
-(@value{GDBP})
-@@Hello world
-*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
-(@value{GDBP})
+
+(gdb)
+*stopped,reason="end-stepping-range",
+frame=@{func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="10"@}
+(gdb)
+-exec-step-instruction
+^running
+
+(gdb)
+*stopped,reason="end-stepping-range",
+frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="10"@}
+(gdb)
@end smallexample
-@subheading The @code{-exec-finish} Command
-@findex -exec-finish
+@subheading The @code{-exec-until} Command
+@findex -exec-until
@subsubheading Synopsis
@smallexample
- -exec-finish
+ -exec-until [ @var{location} ]
@end smallexample
-Resumes the execution of the inferior program until the current
-function is exited. Displays the results returned by the function.
+Executes the inferior until the @var{location} specified in the
+argument is reached. If there is no argument, the inferior executes
+until a source line greater than the current one is reached. The
+reason for stopping in this case will be @samp{location-reached}.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{finish}.
+The corresponding @value{GDBN} command is @samp{until}.
@subsubheading Example
-Function returning @code{void}.
-
@smallexample
--exec-finish
+(gdb)
+-exec-until recursive2.c:6
^running
-(@value{GDBP})
-@@hello from foo
-*stopped,reason="function-finished",frame=@{func="main",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
-(@value{GDBP})
+(gdb)
+x = 55
+*stopped,reason="location-reached",frame=@{func="main",args=[],
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
+(gdb)
@end smallexample
-Function returning other than @code{void}. The name of the internal
-@value{GDBN} variable storing the result is printed, together with the
-value itself.
+@ignore
+@subheading -file-clear
+Is this going away????
+@end ignore
-@smallexample
--exec-finish
-^running
-(@value{GDBP})
-*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
-args=[@{name="a",value="1"],@{name="b",value="9"@}@},
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-gdb-result-var="$1",return-value="0"
-(@value{GDBP})
-@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Stack Manipulation
+@section @sc{gdb/mi} Stack Manipulation Commands
-@subheading The @code{-exec-interrupt} Command
-@findex -exec-interrupt
+@subheading The @code{-stack-info-frame} Command
+@findex -stack-info-frame
@subsubheading Synopsis
@smallexample
- -exec-interrupt
+ -stack-info-frame
@end smallexample
-Interrupts the background execution of the target. Note how the token
-associated with the stop message is the one for the execution command
-that has been interrupted. The token for the interrupt itself only
-appears in the @samp{^done} output. If the user is trying to
-interrupt a non-running program, an error message will be printed.
+Get info on the selected frame.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{interrupt}.
+The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
+(without arguments).
@subsubheading Example
@smallexample
-(@value{GDBP})
-111-exec-continue
-111^running
-
-(@value{GDBP})
-222-exec-interrupt
-222^done
-(@value{GDBP})
-111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
-frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="13"@}
-(@value{GDBP})
-
-(@value{GDBP})
--exec-interrupt
-^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
-(@value{GDBP})
+(gdb)
+-stack-info-frame
+^done,frame=@{level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
+(gdb)
@end smallexample
-
-@subheading The @code{-exec-next} Command
-@findex -exec-next
+@subheading The @code{-stack-info-depth} Command
+@findex -stack-info-depth
@subsubheading Synopsis
@smallexample
- -exec-next
+ -stack-info-depth [ @var{max-depth} ]
@end smallexample
-Resumes execution of the inferior program, stopping when the beginning
-of the next source line is reached.
+Return the depth of the stack. If the integer argument @var{max-depth}
+is specified, do not count beyond @var{max-depth} frames.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{next}.
+There's no equivalent @value{GDBN} command.
@subsubheading Example
+For a stack with frame levels 0 through 11:
+
@smallexample
--exec-next
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",line="8",file="hello.c"
-(@value{GDBP})
+(gdb)
+-stack-info-depth
+^done,depth="12"
+(gdb)
+-stack-info-depth 4
+^done,depth="4"
+(gdb)
+-stack-info-depth 12
+^done,depth="12"
+(gdb)
+-stack-info-depth 11
+^done,depth="11"
+(gdb)
+-stack-info-depth 13
+^done,depth="12"
+(gdb)
@end smallexample
-
-@subheading The @code{-exec-next-instruction} Command
-@findex -exec-next-instruction
+@subheading The @code{-stack-list-arguments} Command
+@findex -stack-list-arguments
@subsubheading Synopsis
@smallexample
- -exec-next-instruction
+ -stack-list-arguments @var{show-values}
+ [ @var{low-frame} @var{high-frame} ]
@end smallexample
-Executes one machine instruction. If the instruction is a function
-call, continues until the function returns. If the program stops at an
-instruction in the middle of a source line, the address will be
-printed as well.
+Display a list of the arguments for the frames between @var{low-frame}
+and @var{high-frame} (inclusive). If @var{low-frame} and
+@var{high-frame} are not provided, list the arguments for the whole
+call stack. If the two arguments are equal, show the single frame
+at the corresponding level. It is an error if @var{low-frame} is
+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.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{nexti}.
+@value{GDBN} does not have an equivalent command. @code{gdbtk} has a
+@samp{gdb_get_args} command which partially overlaps with the
+functionality of @samp{-stack-list-arguments}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--exec-next-instruction
-^running
-
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-addr="0x000100d4",line="5",file="hello.c"
-(@value{GDBP})
+(gdb)
+-stack-list-frames
+^done,
+stack=[
+frame=@{level="0",addr="0x00010734",func="callee4",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+frame=@{level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
+frame=@{level="2",addr="0x0001078c",func="callee2",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
+frame=@{level="3",addr="0x000107b4",func="callee1",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
+frame=@{level="4",addr="0x000107e0",func="main",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
+(gdb)
+-stack-list-arguments 0
+^done,
+stack-args=[
+frame=@{level="0",args=[]@},
+frame=@{level="1",args=[name="strarg"]@},
+frame=@{level="2",args=[name="intarg",name="strarg"]@},
+frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
+frame=@{level="4",args=[]@}]
+(gdb)
+-stack-list-arguments 1
+^done,
+stack-args=[
+frame=@{level="0",args=[]@},
+frame=@{level="1",
+ args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
+frame=@{level="2",args=[
+@{name="intarg",value="2"@},
+@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
+@{frame=@{level="3",args=[
+@{name="intarg",value="2"@},
+@{name="strarg",value="0x11940 \"A string argument.\""@},
+@{name="fltarg",value="3.5"@}]@},
+frame=@{level="4",args=[]@}]
+(gdb)
+-stack-list-arguments 0 2 2
+^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
+(gdb)
+-stack-list-arguments 1 2 2
+^done,stack-args=[frame=@{level="2",
+args=[@{name="intarg",value="2"@},
+@{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
+(gdb)
@end smallexample
+@c @subheading -stack-list-exception-handlers
+
-@subheading The @code{-exec-return} Command
-@findex -exec-return
+@subheading The @code{-stack-list-frames} Command
+@findex -stack-list-frames
@subsubheading Synopsis
@smallexample
- -exec-return
+ -stack-list-frames [ @var{low-frame} @var{high-frame} ]
@end smallexample
-Makes current function return immediately. Doesn't execute the inferior.
-Displays the new current frame.
+List the frames currently on the stack. For each frame it displays the
+following info:
+
+@table @samp
+@item @var{level}
+The frame number, 0 being the topmost frame, i.e. the innermost function.
+@item @var{addr}
+The @code{$pc} value for that frame.
+@item @var{func}
+Function name.
+@item @var{file}
+File name of the source file where the function lives.
+@item @var{line}
+Line number corresponding to the @code{$pc}.
+@end table
+
+If invoked without arguments, this command prints a backtrace for the
+whole stack. If given two integer arguments, it shows the frames whose
+levels are between the two arguments (inclusive). If the two arguments
+are equal, it shows the single frame at the corresponding level. It is
+an error if @var{low-frame} is 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.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{return}.
+The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
@subsubheading Example
+Full stack backtrace:
+
@smallexample
-(@value{GDBP})
-200-break-insert callee4
-200^done,bkpt=@{number="1",addr="0x00010734",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
-(@value{GDBP})
-000-exec-run
-000^running
-(@value{GDBP})
-000*stopped,reason="breakpoint-hit",bkptno="1",
-frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
-(@value{GDBP})
-205-break-delete
-205^done
-(@value{GDBP})
-111-exec-return
-111^done,frame=@{level="0",func="callee3",
-args=[@{name="strarg",
-value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
+(gdb)
+-stack-list-frames
+^done,stack=
+[frame=@{level="0",addr="0x0001076c",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
+frame=@{level="1",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="2",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="6",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="7",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="8",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="9",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="10",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="11",addr="0x00010738",func="main",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
+(gdb)
@end smallexample
+Show frames between @var{low_frame} and @var{high_frame}:
-@subheading The @code{-exec-run} Command
-@findex -exec-run
+@smallexample
+(gdb)
+-stack-list-frames 3 5
+^done,stack=
+[frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+(gdb)
+@end smallexample
+
+Show a single frame:
+
+@smallexample
+(gdb)
+-stack-list-frames 3 3
+^done,stack=
+[frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-stack-list-locals} Command
+@findex -stack-list-locals
@subsubheading Synopsis
@smallexample
- -exec-run
+ -stack-list-locals @var{print-values}
@end smallexample
-Starts execution of the inferior from the beginning. The inferior
-executes until either a breakpoint is encountered or the program
-exits. In the latter case the output will include an exit code, if
-the program has exited exceptionally.
+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,
+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 the user wishes to explore their values in
+more detail.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{run}.
+@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
-@subsubheading Examples
+@subsubheading Example
@smallexample
-(@value{GDBP})
--break-insert main
-^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
-(@value{GDBP})
--exec-run
-^running
-(@value{GDBP})
-*stopped,reason="breakpoint-hit",bkptno="1",
-frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="4"@}
-(@value{GDBP})
+(gdb)
+-stack-list-locals 0
+^done,locals=[name="A",name="B",name="C"]
+(gdb)
+-stack-list-locals --all-values
+^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
+ @{name="C",value="@{1, 2, 3@}"@}]
+-stack-list-locals --simple-values
+^done,locals=[@{name="A",type="int",value="1"@},
+ @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
+(gdb)
@end smallexample
-@noindent
-Program exited normally:
+
+@subheading The @code{-stack-select-frame} Command
+@findex -stack-select-frame
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--exec-run
-^running
-(@value{GDBP})
-x = 55
-*stopped,reason="exited-normally"
-(@value{GDBP})
+ -stack-select-frame @var{framenum}
@end smallexample
-@noindent
-Program exited exceptionally:
+Change the selected frame. Select a different frame @var{framenum} on
+the stack.
-@smallexample
-(@value{GDBP})
--exec-run
-^running
-(@value{GDBP})
-x = 55
-*stopped,reason="exited",exit-code="01"
-(@value{GDBP})
-@end smallexample
+@subsubheading @value{GDBN} Command
-Another way the program can terminate is if it receives a signal such as
-@code{SIGINT}. In this case, @sc{gdb/mi} displays this:
+The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
+@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
+
+@subsubheading Example
@smallexample
-(@value{GDBP})
-*stopped,reason="exited-signalled",signal-name="SIGINT",
-signal-meaning="Interrupt"
+(gdb)
+-stack-select-frame 2
+^done
+(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Variable Objects
+@section @sc{gdb/mi} Variable Objects
-@subheading The @code{-exec-show-arguments} Command
-@findex -exec-show-arguments
-@subsubheading Synopsis
+@subheading Motivation for Variable Objects in @sc{gdb/mi}
-@smallexample
- -exec-show-arguments
-@end smallexample
+For the implementation of a variable debugger window (locals, watched
+expressions, etc.), we are proposing the adaptation of the existing code
+used by @code{Insight}.
-Print the arguments of the program.
+The two main reasons for that are:
-@subsubheading @value{GDBN} Command
+@enumerate 1
+@item
+It has been proven in practice (it is already on its second generation).
-The corresponding @value{GDBN} command is @samp{show args}.
+@item
+It will shorten development time (needless to say how important it is
+now).
+@end enumerate
-@subsubheading Example
-N.A.
+The original interface was designed to be used by Tcl code, so it was
+slightly changed so it could be used through @sc{gdb/mi}. This section
+describes the @sc{gdb/mi} operations that will be available and gives some
+hints about their use.
-@c @subheading -exec-signal
+@emph{Note}: In addition to the set of operations described here, we
+expect the @sc{gui} implementation of a variable window to require, at
+least, the following operations:
-@subheading The @code{-exec-step} Command
-@findex -exec-step
+@itemize @bullet
+@item @code{-gdb-show} @code{output-radix}
+@item @code{-stack-list-arguments}
+@item @code{-stack-list-locals}
+@item @code{-stack-select-frame}
+@end itemize
+
+@subheading Introduction to Variable Objects in @sc{gdb/mi}
+
+@cindex variable objects in @sc{gdb/mi}
+The basic idea behind variable objects is the creation of a named object
+to represent a variable, an expression, a memory location or even a CPU
+register. For each object created, a set of operations is available for
+examining or changing its properties.
+
+Furthermore, complex data types, such as C structures, are represented
+in a tree format. For instance, the @code{struct} type variable is the
+root and the children will represent the struct members. If a child
+is itself of a complex type, it will also have children of its own.
+Appropriate language differences are handled for C, C@t{++} and Java.
+
+When returning the actual values of the objects, this facility allows
+for the individual selection of the display format used in the result
+creation. It can be chosen among: binary, decimal, hexadecimal, octal
+and natural. Natural refers to a default format automatically
+chosen based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
+
+The following is the complete set of @sc{gdb/mi} operations defined to
+access this functionality:
+
+@multitable @columnfractions .4 .6
+@item @strong{Operation}
+@tab @strong{Description}
+
+@item @code{-var-create}
+@tab create a variable object
+@item @code{-var-delete}
+@tab delete the variable object and its children
+@item @code{-var-set-format}
+@tab set the display format of this variable
+@item @code{-var-show-format}
+@tab show the display format of this variable
+@item @code{-var-info-num-children}
+@tab tells how many children this object has
+@item @code{-var-list-children}
+@tab return a list of the object's children
+@item @code{-var-info-type}
+@tab show the type of this variable object
+@item @code{-var-info-expression}
+@tab print what this variable object represents
+@item @code{-var-show-attributes}
+@tab is this variable editable? does it exist here?
+@item @code{-var-evaluate-expression}
+@tab get the value of this variable
+@item @code{-var-assign}
+@tab set the value of this variable
+@item @code{-var-update}
+@tab update the variable and its children
+@end multitable
+
+In the next subsection we describe each operation in detail and suggest
+how it can be used.
+
+@subheading Description And Use of Operations on Variable Objects
+
+@subheading The @code{-var-create} Command
+@findex -var-create
@subsubheading Synopsis
@smallexample
- -exec-step
+ -var-create @{@var{name} | "-"@}
+ @{@var{frame-addr} | "*"@} @var{expression}
@end smallexample
-Resumes execution of the inferior program, stopping when the beginning
-of the next source line is reached, if the next source line is not a
-function call. If it is, stop at the first instruction of the called
-function.
+This operation creates a variable object, which allows the monitoring of
+a variable, the result of an expression, a memory cell or a CPU
+register.
-@subsubheading @value{GDBN} Command
+The @var{name} parameter is the string by which the object can be
+referenced. It must be unique. If @samp{-} is specified, the varobj
+system will generate a string ``varNNNNNN'' automatically. It will be
+unique provided that one does not specify @var{name} on that format.
+The command fails if a duplicate name is found.
-The corresponding @value{GDBN} command is @samp{step}.
+The frame under which the expression should be evaluated can be
+specified by @var{frame-addr}. A @samp{*} indicates that the current
+frame should be used.
-@subsubheading Example
+@var{expression} is any expression valid on the current language set (must not
+begin with a @samp{*}), or one of the following:
-Stepping into a function:
+@itemize @bullet
+@item
+@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
-@smallexample
--exec-step
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[@{name="a",value="10"@},
-@{name="b",value="0"@}],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="11"@}
-(@value{GDBP})
-@end smallexample
+@item
+@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
-Regular stepping:
+@item
+@samp{$@var{regname}} --- a CPU register name
+@end itemize
+
+@subsubheading Result
+
+This operation returns the name, number of children and the type of the
+object created. Type is returned as a string as the ones generated by
+the @value{GDBN} CLI:
@smallexample
--exec-step
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
-(@value{GDBP})
+ name="@var{name}",numchild="N",type="@var{type}"
@end smallexample
-@subheading The @code{-exec-step-instruction} Command
-@findex -exec-step-instruction
+@subheading The @code{-var-delete} Command
+@findex -var-delete
@subsubheading Synopsis
@smallexample
- -exec-step-instruction
+ -var-delete @var{name}
@end smallexample
-Resumes the inferior which executes one machine instruction. The
-output, once @value{GDBN} has stopped, will vary depending on whether
-we have stopped in the middle of a source line or not. In the former
-case, the address at which the program stopped will be printed as
-well.
+Deletes a previously created variable object and all of its children.
-@subsubheading @value{GDBN} Command
+Returns an error if the object @var{name} is not found.
-The corresponding @value{GDBN} command is @samp{stepi}.
-@subsubheading Example
+@subheading The @code{-var-set-format} Command
+@findex -var-set-format
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--exec-step-instruction
-^running
+ -var-set-format @var{name} @var{format-spec}
+@end smallexample
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
-(@value{GDBP})
--exec-step-instruction
-^running
+Sets the output format for the value of the object @var{name} to be
+@var{format-spec}.
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
-(@value{GDBP})
+The syntax for the @var{format-spec} is as follows:
+
+@smallexample
+ @var{format-spec} @expansion{}
+ @{binary | decimal | hexadecimal | octal | natural@}
@end smallexample
-@subheading The @code{-exec-until} Command
-@findex -exec-until
+@subheading The @code{-var-show-format} Command
+@findex -var-show-format
@subsubheading Synopsis
@smallexample
- -exec-until [ @var{location} ]
+ -var-show-format @var{name}
@end smallexample
-Executes the inferior until the @var{location} specified in the
-argument is reached. If there is no argument, the inferior executes
-until a source line greater than the current one is reached. The
-reason for stopping in this case will be @samp{location-reached}.
+Returns the format used to display the value of the object @var{name}.
-@subsubheading @value{GDBN} Command
+@smallexample
+ @var{format} @expansion{}
+ @var{format-spec}
+@end smallexample
-The corresponding @value{GDBN} command is @samp{until}.
-@subsubheading Example
+@subheading The @code{-var-info-num-children} Command
+@findex -var-info-num-children
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--exec-until recursive2.c:6
-^running
-(@value{GDBP})
-x = 55
-*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
-(@value{GDBP})
+ -var-info-num-children @var{name}
@end smallexample
-@ignore
-@subheading -file-clear
-Is this going away????
-@end ignore
+Returns the number of children of a variable object @var{name}:
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI File Commands
-@section @sc{gdb/mi} File Commands
+@smallexample
+ numchild=@var{n}
+@end smallexample
-This section describes the GDB/MI commands to specify executable file names
-and to read in and obtain symbol table information.
-@subheading The @code{-file-exec-and-symbols} Command
-@findex -file-exec-and-symbols
+@subheading The @code{-var-list-children} Command
+@findex -var-list-children
@subsubheading Synopsis
@smallexample
- -file-exec-and-symbols @var{file}
+ -var-list-children [@var{print-values}] @var{name}
@end smallexample
+@anchor{-var-list-children}
-Specify the executable file to be debugged. This file is the one from
-which the symbol table is also read. If no file is specified, the
-command clears the executable and symbol information. If breakpoints
-are set when using this command with no arguments, @value{GDBN} will produce
-error messages. Otherwise, no output is produced, except a completion
-notification.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{file}.
+Return a list of the children of the specified variable object and
+create variable objects for them, if they do not already exist. With
+a single argument or if @var{print-values} has a value for of 0 or
+@code{--no-values}, print only the names of the variables; if
+@var{print-values} is 1 or @code{--all-values}, also print their
+values; and if it is 2 or @code{--simple-values} print the name and
+value for simple data types and just the name for arrays, structures
+and unions.
@subsubheading Example
@smallexample
-(@value{GDBP})
--file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+(gdb)
+ -var-list-children n
+ ^done,numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
+(gdb)
+ -var-list-children --all-values n
+ ^done,numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
@end smallexample
-@subheading The @code{-file-exec-file} Command
-@findex -file-exec-file
+@subheading The @code{-var-info-type} Command
+@findex -var-info-type
@subsubheading Synopsis
@smallexample
- -file-exec-file @var{file}
+ -var-info-type @var{name}
@end smallexample
-Specify the executable file to be debugged. Unlike
-@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
-from this file. If used without argument, @value{GDBN} clears the information
-about the executable file. No output is produced, except a completion
-notification.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{exec-file}.
-
-@subsubheading Example
+Returns the type of the specified variable @var{name}. The type is
+returned as a string in the same format as it is output by the
+@value{GDBN} CLI:
@smallexample
-(@value{GDBP})
--file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+ type=@var{typename}
@end smallexample
-@subheading The @code{-file-list-exec-sections} Command
-@findex -file-list-exec-sections
+@subheading The @code{-var-info-expression} Command
+@findex -var-info-expression
@subsubheading Synopsis
@smallexample
- -file-list-exec-sections
+ -var-info-expression @var{name}
@end smallexample
-List the sections of the current executable file.
-
-@subsubheading @value{GDBN} Command
-
-The @value{GDBN} command @samp{info file} shows, among the rest, the same
-information as this command. @code{gdbtk} has a corresponding command
-@samp{gdb_load_info}.
+Returns what is represented by the variable object @var{name}:
-@subsubheading Example
-N.A.
+@smallexample
+ lang=@var{lang-spec},exp=@var{expression}
+@end smallexample
+@noindent
+where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
-@subheading The @code{-file-list-exec-source-file} Command
-@findex -file-list-exec-source-file
+@subheading The @code{-var-show-attributes} Command
+@findex -var-show-attributes
@subsubheading Synopsis
@smallexample
- -file-list-exec-source-file
+ -var-show-attributes @var{name}
@end smallexample
-List the line number, the current source file, and the absolute path
-to the current source file for the current executable.
-
-@subsubheading @value{GDBN} Command
-
-The @value{GDBN} equivalent is @samp{info source}
-
-@subsubheading Example
+List attributes of the specified variable object @var{name}:
@smallexample
-(@value{GDBP})
-123-file-list-exec-source-file
-123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
-(@value{GDBP})
+ status=@var{attr} [ ( ,@var{attr} )* ]
@end smallexample
+@noindent
+where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-@subheading The @code{-file-list-exec-source-files} Command
-@findex -file-list-exec-source-files
+@subheading The @code{-var-evaluate-expression} Command
+@findex -var-evaluate-expression
@subsubheading Synopsis
@smallexample
- -file-list-exec-source-files
+ -var-evaluate-expression @var{name}
@end smallexample
-List the source files for the current executable.
-
-It will always output the filename, but only when GDB can find the absolute
-file name of a source file, will it output the fullname.
-
-@subsubheading @value{GDBN} Command
-
-The @value{GDBN} equivalent is @samp{info sources}.
-@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
+Evaluates the expression that is represented by the specified variable
+object and returns its value as a string in the current format specified
+for the object:
-@subsubheading Example
@smallexample
-(@value{GDBP})
--file-list-exec-source-files
-^done,files=[
-@{file=foo.c,fullname=/home/foo.c@},
-@{file=/home/bar.c,fullname=/home/bar.c@},
-@{file=gdb_could_not_find_fullpath.c@}]
-(@value{GDBP})
+ value=@var{value}
@end smallexample
-@subheading The @code{-file-list-shared-libraries} Command
-@findex -file-list-shared-libraries
+Note that one must invoke @code{-var-list-children} for a variable
+before the value of a child variable can be evaluated.
+
+@subheading The @code{-var-assign} Command
+@findex -var-assign
@subsubheading Synopsis
@smallexample
- -file-list-shared-libraries
+ -var-assign @var{name} @var{expression}
@end smallexample
-List the shared libraries in the program.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info shared}.
+Assigns the value of @var{expression} to the variable object specified
+by @var{name}. The object must be @samp{editable}. If the variable's
+value is altered by the assign, the variable will show up in any
+subsequent @code{-var-update} list.
@subsubheading Example
-N.A.
-
-
-@subheading The @code{-file-list-symbol-files} Command
-@findex -file-list-symbol-files
-
-@subsubheading Synopsis
@smallexample
- -file-list-symbol-files
+(gdb)
+-var-assign var1 3
+^done,value="3"
+(gdb)
+-var-update *
+^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
+(gdb)
@end smallexample
-List symbol files.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info file} (part of it).
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-file-symbol-file} Command
-@findex -file-symbol-file
+@subheading The @code{-var-update} Command
+@findex -var-update
@subsubheading Synopsis
@smallexample
- -file-symbol-file @var{file}
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
@end smallexample
-Read symbol table info from the specified @var{file} argument. When
-used without arguments, clears @value{GDBN}'s symbol table info. No output is
-produced, except for a completion notification.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{symbol-file}.
+Update the value of the variable object @var{name} by evaluating its
+expression after fetching all the new values from memory or registers.
+A @samp{*} causes all existing variable objects to be updated. The
+option @var{print-values} determines whether names both and values, or
+just names are printed in the manner described for
+@code{-var-list-children} (@pxref{-var-list-children}).
@subsubheading Example
@smallexample
-(@value{GDBP})
--file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+(gdb)
+-var-assign var1 3
+^done,value="3"
+(gdb)
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(gdb)
@end smallexample
-@ignore
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Kod Commands
-@section @sc{gdb/mi} Kod Commands
-
-The Kod commands are not implemented.
-
-@c @subheading -kod-info
-
-@c @subheading -kod-list
-
-@c @subheading -kod-list-object-types
-
-@c @subheading -kod-show
-
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Memory Overlay Commands
-@section @sc{gdb/mi} Memory Overlay Commands
-
-The memory overlay commands are not implemented.
+@node GDB/MI Data Manipulation
+@section @sc{gdb/mi} Data Manipulation
-@c @subheading -overlay-auto
+@cindex data manipulation, in @sc{gdb/mi}
+@cindex @sc{gdb/mi}, data manipulation
+This section describes the @sc{gdb/mi} commands that manipulate data:
+examine memory and registers, evaluate expressions, etc.
-@c @subheading -overlay-list-mapping-state
+@c REMOVED FROM THE INTERFACE.
+@c @subheading -data-assign
+@c Change the value of a program variable. Plenty of side effects.
+@c @subsubheading GDB command
+@c set variable
+@c @subsubheading Example
+@c N.A.
-@c @subheading -overlay-list-overlays
+@subheading The @code{-data-disassemble} Command
+@findex -data-disassemble
-@c @subheading -overlay-map
+@subsubheading Synopsis
-@c @subheading -overlay-off
+@smallexample
+ -data-disassemble
+ [ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
+ -- @var{mode}
+@end smallexample
-@c @subheading -overlay-on
-
-@c @subheading -overlay-unmap
-
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Signal Handling Commands
-@section @sc{gdb/mi} Signal Handling Commands
-
-Signal handling commands are not implemented.
-
-@c @subheading -signal-handle
-
-@c @subheading -signal-list-handle-actions
-
-@c @subheading -signal-list-signal-types
-@end ignore
-
-
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Stack Manipulation
-@section @sc{gdb/mi} Stack Manipulation Commands
-
-
-@subheading The @code{-stack-info-frame} Command
-@findex -stack-info-frame
-
-@subsubheading Synopsis
-
-@smallexample
- -stack-info-frame
-@end smallexample
-
-Get info on the selected frame.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
-(without arguments).
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--stack-info-frame
-^done,frame=@{level="1",addr="0x0001076c",func="callee3",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
-(@value{GDBP})
-@end smallexample
-
-@subheading The @code{-stack-info-depth} Command
-@findex -stack-info-depth
-
-@subsubheading Synopsis
-
-@smallexample
- -stack-info-depth [ @var{max-depth} ]
-@end smallexample
-
-Return the depth of the stack. If the integer argument @var{max-depth}
-is specified, do not count beyond @var{max-depth} frames.
-
-@subsubheading @value{GDBN} Command
-
-There's no equivalent @value{GDBN} command.
-
-@subsubheading Example
-
-For a stack with frame levels 0 through 11:
-
-@smallexample
-(@value{GDBP})
--stack-info-depth
-^done,depth="12"
-(@value{GDBP})
--stack-info-depth 4
-^done,depth="4"
-(@value{GDBP})
--stack-info-depth 12
-^done,depth="12"
-(@value{GDBP})
--stack-info-depth 11
-^done,depth="11"
-(@value{GDBP})
--stack-info-depth 13
-^done,depth="12"
-(@value{GDBP})
-@end smallexample
-
-@subheading The @code{-stack-list-arguments} Command
-@findex -stack-list-arguments
-
-@subsubheading Synopsis
-
-@smallexample
- -stack-list-arguments @var{show-values}
- [ @var{low-frame} @var{high-frame} ]
-@end smallexample
-
-Display a list of the arguments for the frames between @var{low-frame}
-and @var{high-frame} (inclusive). If @var{low-frame} and
-@var{high-frame} are not provided, list the arguments for the whole call
-stack.
-
-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.
-
-@subsubheading @value{GDBN} Command
-
-@value{GDBN} does not have an equivalent command. @code{gdbtk} has a
-@samp{gdb_get_args} command which partially overlaps with the
-functionality of @samp{-stack-list-arguments}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--stack-list-frames
-^done,
-stack=[
-frame=@{level="0",addr="0x00010734",func="callee4",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
-frame=@{level="1",addr="0x0001076c",func="callee3",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
-frame=@{level="2",addr="0x0001078c",func="callee2",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
-frame=@{level="3",addr="0x000107b4",func="callee1",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
-frame=@{level="4",addr="0x000107e0",func="main",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
-(@value{GDBP})
--stack-list-arguments 0
-^done,
-stack-args=[
-frame=@{level="0",args=[]@},
-frame=@{level="1",args=[name="strarg"]@},
-frame=@{level="2",args=[name="intarg",name="strarg"]@},
-frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
-frame=@{level="4",args=[]@}]
-(@value{GDBP})
--stack-list-arguments 1
-^done,
-stack-args=[
-frame=@{level="0",args=[]@},
-frame=@{level="1",
- args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
-frame=@{level="2",args=[
-@{name="intarg",value="2"@},
-@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
-@{frame=@{level="3",args=[
-@{name="intarg",value="2"@},
-@{name="strarg",value="0x11940 \"A string argument.\""@},
-@{name="fltarg",value="3.5"@}]@},
-frame=@{level="4",args=[]@}]
-(@value{GDBP})
--stack-list-arguments 0 2 2
-^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
-(@value{GDBP})
--stack-list-arguments 1 2 2
-^done,stack-args=[frame=@{level="2",
-args=[@{name="intarg",value="2"@},
-@{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
-(@value{GDBP})
-@end smallexample
-
-@c @subheading -stack-list-exception-handlers
-
-
-@subheading The @code{-stack-list-frames} Command
-@findex -stack-list-frames
-
-@subsubheading Synopsis
-
-@smallexample
- -stack-list-frames [ @var{low-frame} @var{high-frame} ]
-@end smallexample
-
-List the frames currently on the stack. For each frame it displays the
-following info:
+@noindent
+Where:
@table @samp
-@item @var{level}
-The frame number, 0 being the topmost frame, i.e. the innermost function.
-@item @var{addr}
-The @code{$pc} value for that frame.
-@item @var{func}
-Function name.
-@item @var{file}
-File name of the source file where the function lives.
-@item @var{line}
-Line number corresponding to the @code{$pc}.
+@item @var{start-addr}
+is the beginning address (or @code{$pc})
+@item @var{end-addr}
+is the end address
+@item @var{filename}
+is the name of the file to disassemble
+@item @var{linenum}
+is the line number to disassemble around
+@item @var{lines}
+is the the number of disassembly lines to be produced. If it is -1,
+the whole function will be disassembled, in case no @var{end-addr} is
+specified. If @var{end-addr} is specified as a non-zero value, and
+@var{lines} is lower than the number of disassembly lines between
+@var{start-addr} and @var{end-addr}, only @var{lines} lines are
+displayed; if @var{lines} is higher than the number of lines between
+@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
+are displayed.
+@item @var{mode}
+is either 0 (meaning only disassembly) or 1 (meaning mixed source and
+disassembly).
@end table
-If invoked without arguments, this command prints a backtrace for the
-whole stack. If given two integer arguments, it shows the frames whose
-levels are between the two arguments (inclusive). If the two arguments
-are equal, it shows the single frame at the corresponding level.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
-
-@subsubheading Example
-
-Full stack backtrace:
-
-@smallexample
-(@value{GDBP})
--stack-list-frames
-^done,stack=
-[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
-frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
-(@value{GDBP})
-@end smallexample
-
-Show frames between @var{low_frame} and @var{high_frame}:
-
-@smallexample
-(@value{GDBP})
--stack-list-frames 3 5
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
-(@value{GDBP})
-@end smallexample
-
-Show a single frame:
-
-@smallexample
-(@value{GDBP})
--stack-list-frames 3 3
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
-(@value{GDBP})
-@end smallexample
-
-
-@subheading The @code{-stack-list-locals} Command
-@findex -stack-list-locals
+@subsubheading Result
-@subsubheading Synopsis
+The output for each instruction is composed of four fields:
-@smallexample
- -stack-list-locals @var{print-values}
-@end smallexample
+@itemize @bullet
+@item Address
+@item Func-name
+@item Offset
+@item Instruction
+@end itemize
-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,
-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 the user wishes to explore their values in
-more detail.
+Note that whatever included in the instruction field, is not manipulated
+directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
@subsubheading @value{GDBN} Command
-@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
+There's no direct mapping from this command to the CLI.
@subsubheading Example
-@smallexample
-(@value{GDBP})
--stack-list-locals 0
-^done,locals=[name="A",name="B",name="C"]
-(@value{GDBP})
--stack-list-locals --all-values
-^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
- @{name="C",value="@{1, 2, 3@}"@}]
--stack-list-locals --simple-values
-^done,locals=[@{name="A",type="int",value="1"@},
- @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
-(@value{GDBP})
-@end smallexample
-
-
-@subheading The @code{-stack-select-frame} Command
-@findex -stack-select-frame
-
-@subsubheading Synopsis
+Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
@smallexample
- -stack-select-frame @var{framenum}
+(gdb)
+-data-disassemble -s $pc -e "$pc + 20" -- 0
+^done,
+asm_insns=[
+@{address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+@{address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@},
+@{address="0x000107c8",func-name="main",offset="12",
+inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
+@{address="0x000107cc",func-name="main",offset="16",
+inst="sethi %hi(0x11800), %o2"@},
+@{address="0x000107d0",func-name="main",offset="20",
+inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
+(gdb)
@end smallexample
-Change the selected frame. Select a different frame @var{framenum} on
-the stack.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
-@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
-
-@subsubheading Example
+Disassemble the whole @code{main} function. Line 32 is part of
+@code{main}.
@smallexample
-(@value{GDBP})
--stack-select-frame 2
-^done
-(@value{GDBP})
+-data-disassemble -f basics.c -l 32 -- 0
+^done,asm_insns=[
+@{address="0x000107bc",func-name="main",offset="0",
+inst="save %sp, -112, %sp"@},
+@{address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+@{address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@},
+[@dots{}]
+@{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
+@{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
+(gdb)
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Symbol Query
-@section @sc{gdb/mi} Symbol Query Commands
-
-
-@subheading The @code{-symbol-info-address} Command
-@findex -symbol-info-address
-
-@subsubheading Synopsis
+Disassemble 3 instructions from the start of @code{main}:
@smallexample
- -symbol-info-address @var{symbol}
+(gdb)
+-data-disassemble -f basics.c -l 32 -n 3 -- 0
+^done,asm_insns=[
+@{address="0x000107bc",func-name="main",offset="0",
+inst="save %sp, -112, %sp"@},
+@{address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+@{address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@}]
+(gdb)
@end smallexample
-Describe where @var{symbol} is stored.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info address}.
+Disassemble 3 instructions from the start of @code{main} in mixed mode:
-@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-data-disassemble -f basics.c -l 32 -n 3 -- 1
+^done,asm_insns=[
+src_and_asm_line=@{line="31",
+file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
+ testsuite/gdb.mi/basics.c",line_asm_insn=[
+@{address="0x000107bc",func-name="main",offset="0",
+inst="save %sp, -112, %sp"@}]@},
+src_and_asm_line=@{line="32",
+file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
+ testsuite/gdb.mi/basics.c",line_asm_insn=[
+@{address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+@{address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@}]@}]
+(gdb)
+@end smallexample
-@subheading The @code{-symbol-info-file} Command
-@findex -symbol-info-file
+@subheading The @code{-data-evaluate-expression} Command
+@findex -data-evaluate-expression
@subsubheading Synopsis
@smallexample
- -symbol-info-file
+ -data-evaluate-expression @var{expr}
@end smallexample
-Show the file for the symbol.
+Evaluate @var{expr} as an expression. The expression could contain an
+inferior function call. The function call will execute synchronously.
+If the expression contains spaces, it must be enclosed in double quotes.
@subsubheading @value{GDBN} Command
-There's no equivalent @value{GDBN} command. @code{gdbtk} has
-@samp{gdb_find_file}.
+The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
+@samp{call}. In @code{gdbtk} only, there's a corresponding
+@samp{gdb_eval} command.
@subsubheading Example
-N.A.
-
-@subheading The @code{-symbol-info-function} Command
-@findex -symbol-info-function
-
-@subsubheading Synopsis
+In the following example, the numbers that precede the commands are the
+@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
+Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
+output.
@smallexample
- -symbol-info-function
+211-data-evaluate-expression A
+211^done,value="1"
+(gdb)
+311-data-evaluate-expression &A
+311^done,value="0xefffeb7c"
+(gdb)
+411-data-evaluate-expression A+3
+411^done,value="4"
+(gdb)
+511-data-evaluate-expression "A + 3"
+511^done,value="4"
+(gdb)
@end smallexample
-Show which function the symbol lives in.
-
-@subsubheading @value{GDBN} Command
-
-@samp{gdb_get_function} in @code{gdbtk}.
-
-@subsubheading Example
-N.A.
-
-@subheading The @code{-symbol-info-line} Command
-@findex -symbol-info-line
+@subheading The @code{-data-list-changed-registers} Command
+@findex -data-list-changed-registers
@subsubheading Synopsis
@smallexample
- -symbol-info-line
+ -data-list-changed-registers
@end smallexample
-Show the core addresses of the code for a source line.
+Display a list of the registers that have changed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info line}.
-@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
+@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
+has the corresponding command @samp{gdb_changed_register_list}.
@subsubheading Example
-N.A.
-
-@subheading The @code{-symbol-info-symbol} Command
-@findex -symbol-info-symbol
-
-@subsubheading Synopsis
+On a PPC MBX board:
@smallexample
- -symbol-info-symbol @var{addr}
-@end smallexample
-
-Describe what symbol is at location @var{addr}.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info symbol}.
+(gdb)
+-exec-continue
+^running
-@subsubheading Example
-N.A.
+(gdb)
+*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
+args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@}
+(gdb)
+-data-list-changed-registers
+^done,changed-registers=["0","1","2","4","5","6","7","8","9",
+"10","11","13","14","15","16","17","18","19","20","21","22","23",
+"24","25","26","27","28","30","31","64","65","66","67","69"]
+(gdb)
+@end smallexample
-@subheading The @code{-symbol-list-functions} Command
-@findex -symbol-list-functions
+@subheading The @code{-data-list-register-names} Command
+@findex -data-list-register-names
@subsubheading Synopsis
@smallexample
- -symbol-list-functions
+ -data-list-register-names [ ( @var{regno} )+ ]
@end smallexample
-List the functions in the executable.
+Show a list of register names for the current target. If no arguments
+are given, it shows a list of the names of all the registers. If
+integer numbers are given as arguments, it will print a list of the
+names of the registers corresponding to the arguments. To ensure
+consistency between a register name and its number, the output list may
+include empty register names.
@subsubheading @value{GDBN} Command
-@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
-@samp{gdb_search} in @code{gdbtk}.
+@value{GDBN} does not have a command which corresponds to
+@samp{-data-list-register-names}. In @code{gdbtk} there is a
+corresponding command @samp{gdb_regnames}.
@subsubheading Example
-N.A.
+For the PPC MBX board:
+@smallexample
+(gdb)
+-data-list-register-names
+^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
+"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
+"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
+"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
+"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
+"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
+"", "pc","ps","cr","lr","ctr","xer"]
+(gdb)
+-data-list-register-names 1 2 3
+^done,register-names=["r1","r2","r3"]
+(gdb)
+@end smallexample
-@subheading The @code{-symbol-list-lines} Command
-@findex -symbol-list-lines
+@subheading The @code{-data-list-register-values} Command
+@findex -data-list-register-values
@subsubheading Synopsis
@smallexample
- -symbol-list-lines @var{filename}
+ -data-list-register-values @var{fmt} [ ( @var{regno} )*]
@end smallexample
-Print the list of lines that contain code and their associated program
-addresses for the given source filename. The entries are sorted in
-ascending PC order.
+Display the registers' contents. @var{fmt} is the format according to
+which the registers' contents are to be returned, followed by an optional
+list of numbers specifying the registers to display. A missing list of
+numbers indicates that the contents of all the registers must be returned.
+
+Allowed formats for @var{fmt} are:
+
+@table @code
+@item x
+Hexadecimal
+@item o
+Octal
+@item t
+Binary
+@item d
+Decimal
+@item r
+Raw
+@item N
+Natural
+@end table
@subsubheading @value{GDBN} Command
-There is no corresponding @value{GDBN} command.
+The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
+all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
@subsubheading Example
+
+For a PPC MBX board (note: line breaks are for readability only, they
+don't appear in the actual output):
+
@smallexample
-(@value{GDBP})
--symbol-list-lines basics.c
-^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
-(@value{GDBP})
+(gdb)
+-data-list-register-values r 64 65
+^done,register-values=[@{number="64",value="0xfe00a300"@},
+@{number="65",value="0x00029002"@}]
+(gdb)
+-data-list-register-values x
+^done,register-values=[@{number="0",value="0xfe0043c8"@},
+@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
+@{number="3",value="0x0"@},@{number="4",value="0xa"@},
+@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
+@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
+@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
+@{number="11",value="0x1"@},@{number="12",value="0x0"@},
+@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
+@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
+@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
+@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
+@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
+@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
+@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
+@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
+@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
+@{number="31",value="0x0"@},@{number="32",value="0x0"@},
+@{number="33",value="0x0"@},@{number="34",value="0x0"@},
+@{number="35",value="0x0"@},@{number="36",value="0x0"@},
+@{number="37",value="0x0"@},@{number="38",value="0x0"@},
+@{number="39",value="0x0"@},@{number="40",value="0x0"@},
+@{number="41",value="0x0"@},@{number="42",value="0x0"@},
+@{number="43",value="0x0"@},@{number="44",value="0x0"@},
+@{number="45",value="0x0"@},@{number="46",value="0x0"@},
+@{number="47",value="0x0"@},@{number="48",value="0x0"@},
+@{number="49",value="0x0"@},@{number="50",value="0x0"@},
+@{number="51",value="0x0"@},@{number="52",value="0x0"@},
+@{number="53",value="0x0"@},@{number="54",value="0x0"@},
+@{number="55",value="0x0"@},@{number="56",value="0x0"@},
+@{number="57",value="0x0"@},@{number="58",value="0x0"@},
+@{number="59",value="0x0"@},@{number="60",value="0x0"@},
+@{number="61",value="0x0"@},@{number="62",value="0x0"@},
+@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
+@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
+@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
+@{number="69",value="0x20002b03"@}]
+(gdb)
@end smallexample
-@subheading The @code{-symbol-list-types} Command
-@findex -symbol-list-types
+@subheading The @code{-data-read-memory} Command
+@findex -data-read-memory
@subsubheading Synopsis
@smallexample
- -symbol-list-types
+ -data-read-memory [ -o @var{byte-offset} ]
+ @var{address} @var{word-format} @var{word-size}
+ @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
@end smallexample
-List all the type names.
+@noindent
+where:
-@subsubheading @value{GDBN} Command
+@table @samp
+@item @var{address}
+An expression specifying the address of the first memory word to be
+read. Complex expressions containing embedded white space should be
+quoted using the C convention.
-The corresponding commands are @samp{info types} in @value{GDBN},
-@samp{gdb_search} in @code{gdbtk}.
+@item @var{word-format}
+The format to be used to print the memory words. The notation is the
+same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
+,Output formats}).
-@subsubheading Example
-N.A.
+@item @var{word-size}
+The size of each memory word in bytes.
+@item @var{nr-rows}
+The number of rows in the output table.
-@subheading The @code{-symbol-list-variables} Command
-@findex -symbol-list-variables
+@item @var{nr-cols}
+The number of columns in the output table.
-@subsubheading Synopsis
+@item @var{aschar}
+If present, indicates that each row should include an @sc{ascii} dump. The
+value of @var{aschar} is used as a padding character when a byte is not a
+member of the printable @sc{ascii} character set (printable @sc{ascii}
+characters are those whose code is between 32 and 126, inclusively).
-@smallexample
- -symbol-list-variables
-@end smallexample
+@item @var{byte-offset}
+An offset to add to the @var{address} before fetching memory.
+@end table
+
+This command displays memory contents as a table of @var{nr-rows} by
+@var{nr-cols} words, each word being @var{word-size} bytes. In total,
+@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
+(returned as @samp{total-bytes}). Should less than the requested number
+of bytes be returned by the target, the missing words are identified
+using @samp{N/A}. The number of bytes read from the target is returned
+in @samp{nr-bytes} and the starting address used to read memory in
+@samp{addr}.
-List all the global and static variable names.
+The address of the next/previous row or page is available in
+@samp{next-row} and @samp{prev-row}, @samp{next-page} and
+@samp{prev-page}.
@subsubheading @value{GDBN} Command
-@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
+The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
+@samp{gdb_get_mem} memory read command.
@subsubheading Example
-N.A.
+Read six bytes of memory starting at @code{bytes+6} but then offset by
+@code{-6} bytes. Format as three rows of two columns. One byte per
+word. Display each word in hex.
-@subheading The @code{-symbol-locate} Command
-@findex -symbol-locate
+@smallexample
+(gdb)
+9-data-read-memory -o -6 -- bytes+6 x 1 3 2
+9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
+next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
+prev-page="0x0000138a",memory=[
+@{addr="0x00001390",data=["0x00","0x01"]@},
+@{addr="0x00001392",data=["0x02","0x03"]@},
+@{addr="0x00001394",data=["0x04","0x05"]@}]
+(gdb)
+@end smallexample
-@subsubheading Synopsis
+Read two bytes of memory starting at address @code{shorts + 64} and
+display as a single word formatted in decimal.
@smallexample
- -symbol-locate
+(gdb)
+5-data-read-memory shorts+64 d 2 1 1
+5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
+next-row="0x00001512",prev-row="0x0000150e",
+next-page="0x00001512",prev-page="0x0000150e",memory=[
+@{addr="0x00001510",data=["128"]@}]
+(gdb)
@end smallexample
-@subsubheading @value{GDBN} Command
+Read thirty two bytes of memory starting at @code{bytes+16} and format
+as eight rows of four columns. Include a string encoding with @samp{x}
+used as the non-printable character.
-@samp{gdb_loc} in @code{gdbtk}.
+@smallexample
+(gdb)
+4-data-read-memory bytes+16 x 1 8 4 x
+4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
+next-row="0x000013c0",prev-row="0x0000139c",
+next-page="0x000013c0",prev-page="0x00001380",memory=[
+@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
+@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
+@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
+@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
+@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
+@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
+@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
+@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
+(gdb)
+@end smallexample
-@subsubheading Example
-N.A.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Tracepoint Commands
+@section @sc{gdb/mi} Tracepoint Commands
+The tracepoint commands are not yet implemented.
-@subheading The @code{-symbol-type} Command
-@findex -symbol-type
+@c @subheading -trace-actions
-@subsubheading Synopsis
+@c @subheading -trace-delete
-@smallexample
- -symbol-type @var{variable}
-@end smallexample
+@c @subheading -trace-disable
-Show type of @var{variable}.
+@c @subheading -trace-dump
-@subsubheading @value{GDBN} Command
+@c @subheading -trace-enable
-The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
-@samp{gdb_obj_variable}.
+@c @subheading -trace-exists
-@subsubheading Example
-N.A.
+@c @subheading -trace-find
+@c @subheading -trace-frame-number
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Target Manipulation
-@section @sc{gdb/mi} Target Manipulation Commands
+@c @subheading -trace-info
+@c @subheading -trace-insert
-@subheading The @code{-target-attach} Command
-@findex -target-attach
+@c @subheading -trace-list
-@subsubheading Synopsis
+@c @subheading -trace-pass-count
-@smallexample
- -target-attach @var{pid} | @var{file}
-@end smallexample
+@c @subheading -trace-save
-Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
+@c @subheading -trace-start
-@subsubheading @value{GDBN} command
+@c @subheading -trace-stop
-The corresponding @value{GDBN} command is @samp{attach}.
-@subsubheading Example
-N.A.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Symbol Query
+@section @sc{gdb/mi} Symbol Query Commands
-@subheading The @code{-target-compare-sections} Command
-@findex -target-compare-sections
+@subheading The @code{-symbol-info-address} Command
+@findex -symbol-info-address
@subsubheading Synopsis
@smallexample
- -target-compare-sections [ @var{section} ]
+ -symbol-info-address @var{symbol}
@end smallexample
-Compare data of section @var{section} on target to the exec file.
-Without the argument, all sections are compared.
+Describe where @var{symbol} is stored.
@subsubheading @value{GDBN} Command
-The @value{GDBN} equivalent is @samp{compare-sections}.
+The corresponding @value{GDBN} command is @samp{info address}.
@subsubheading Example
N.A.
-@subheading The @code{-target-detach} Command
-@findex -target-detach
+@subheading The @code{-symbol-info-file} Command
+@findex -symbol-info-file
@subsubheading Synopsis
@smallexample
- -target-detach
-@end smallexample
-
-Detach from the remote target which normally resumes its execution.
-There's no output.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{detach}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--target-detach
-^done
-(@value{GDBP})
+ -symbol-info-file
@end smallexample
+Show the file for the symbol.
-@subheading The @code{-target-disconnect} Command
-@findex -target-disconnect
-
-@subsubheading Synopsis
-
-@example
- -target-disconnect
-@end example
-
-Disconnect from the remote target. There's no output and the target is
-generally not resumed.
-
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{disconnect}.
+There's no equivalent @value{GDBN} command. @code{gdbtk} has
+@samp{gdb_find_file}.
@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--target-disconnect
-^done
-(@value{GDBP})
-@end smallexample
+N.A.
-@subheading The @code{-target-download} Command
-@findex -target-download
+@subheading The @code{-symbol-info-function} Command
+@findex -symbol-info-function
@subsubheading Synopsis
@smallexample
- -target-download
+ -symbol-info-function
@end smallexample
-Loads the executable onto the remote target.
-It prints out an update message every half second, which includes the fields:
-
-@table @samp
-@item section
-The name of the section.
-@item section-sent
-The size of what has been sent so far for that section.
-@item section-size
-The size of the section.
-@item total-sent
-The total size of what was sent so far (the current and the previous sections).
-@item total-size
-The size of the overall executable to download.
-@end table
-
-@noindent
-Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
-@sc{gdb/mi} Output Syntax}).
-
-In addition, it prints the name and size of the sections, as they are
-downloaded. These messages include the following fields:
-
-@table @samp
-@item section
-The name of the section.
-@item section-size
-The size of the section.
-@item total-size
-The size of the overall executable to download.
-@end table
-
-@noindent
-At the end, a summary is printed.
+Show which function the symbol lives in.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{load}.
-
-@subsubheading Example
-
-Note: each status message appears on a single line. Here the messages
-have been broken down so that they can fit onto a page.
+@samp{gdb_get_function} in @code{gdbtk}.
-@smallexample
-(@value{GDBP})
--target-download
-+download,@{section=".text",section-size="6668",total-size="9880"@}
-+download,@{section=".text",section-sent="512",section-size="6668",
-total-sent="512",total-size="9880"@}
-+download,@{section=".text",section-sent="1024",section-size="6668",
-total-sent="1024",total-size="9880"@}
-+download,@{section=".text",section-sent="1536",section-size="6668",
-total-sent="1536",total-size="9880"@}
-+download,@{section=".text",section-sent="2048",section-size="6668",
-total-sent="2048",total-size="9880"@}
-+download,@{section=".text",section-sent="2560",section-size="6668",
-total-sent="2560",total-size="9880"@}
-+download,@{section=".text",section-sent="3072",section-size="6668",
-total-sent="3072",total-size="9880"@}
-+download,@{section=".text",section-sent="3584",section-size="6668",
-total-sent="3584",total-size="9880"@}
-+download,@{section=".text",section-sent="4096",section-size="6668",
-total-sent="4096",total-size="9880"@}
-+download,@{section=".text",section-sent="4608",section-size="6668",
-total-sent="4608",total-size="9880"@}
-+download,@{section=".text",section-sent="5120",section-size="6668",
-total-sent="5120",total-size="9880"@}
-+download,@{section=".text",section-sent="5632",section-size="6668",
-total-sent="5632",total-size="9880"@}
-+download,@{section=".text",section-sent="6144",section-size="6668",
-total-sent="6144",total-size="9880"@}
-+download,@{section=".text",section-sent="6656",section-size="6668",
-total-sent="6656",total-size="9880"@}
-+download,@{section=".init",section-size="28",total-size="9880"@}
-+download,@{section=".fini",section-size="28",total-size="9880"@}
-+download,@{section=".data",section-size="3156",total-size="9880"@}
-+download,@{section=".data",section-sent="512",section-size="3156",
-total-sent="7236",total-size="9880"@}
-+download,@{section=".data",section-sent="1024",section-size="3156",
-total-sent="7748",total-size="9880"@}
-+download,@{section=".data",section-sent="1536",section-size="3156",
-total-sent="8260",total-size="9880"@}
-+download,@{section=".data",section-sent="2048",section-size="3156",
-total-sent="8772",total-size="9880"@}
-+download,@{section=".data",section-sent="2560",section-size="3156",
-total-sent="9284",total-size="9880"@}
-+download,@{section=".data",section-sent="3072",section-size="3156",
-total-sent="9796",total-size="9880"@}
-^done,address="0x10004",load-size="9880",transfer-rate="6586",
-write-rate="429"
-(@value{GDBP})
-@end smallexample
+@subsubheading Example
+N.A.
-@subheading The @code{-target-exec-status} Command
-@findex -target-exec-status
+@subheading The @code{-symbol-info-line} Command
+@findex -symbol-info-line
@subsubheading Synopsis
@smallexample
- -target-exec-status
+ -symbol-info-line
@end smallexample
-Provide information on the state of the target (whether it is running or
-not, for instance).
+Show the core addresses of the code for a source line.
@subsubheading @value{GDBN} Command
-There's no equivalent @value{GDBN} command.
+The corresponding @value{GDBN} command is @samp{info line}.
+@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
@subsubheading Example
N.A.
-@subheading The @code{-target-list-available-targets} Command
-@findex -target-list-available-targets
+@subheading The @code{-symbol-info-symbol} Command
+@findex -symbol-info-symbol
@subsubheading Synopsis
@smallexample
- -target-list-available-targets
+ -symbol-info-symbol @var{addr}
@end smallexample
-List the possible targets to connect to.
+Describe what symbol is at location @var{addr}.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{help target}.
+The corresponding @value{GDBN} command is @samp{info symbol}.
@subsubheading Example
N.A.
-@subheading The @code{-target-list-current-targets} Command
-@findex -target-list-current-targets
+@subheading The @code{-symbol-list-functions} Command
+@findex -symbol-list-functions
@subsubheading Synopsis
@smallexample
- -target-list-current-targets
+ -symbol-list-functions
@end smallexample
-Describe the current target.
+List the functions in the executable.
@subsubheading @value{GDBN} Command
-The corresponding information is printed by @samp{info file} (among
-other things).
+@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
+@samp{gdb_search} in @code{gdbtk}.
@subsubheading Example
N.A.
-@subheading The @code{-target-list-parameters} Command
-@findex -target-list-parameters
+@subheading The @code{-symbol-list-lines} Command
+@findex -symbol-list-lines
@subsubheading Synopsis
@smallexample
- -target-list-parameters
+ -symbol-list-lines @var{filename}
@end smallexample
-@c ????
+Print the list of lines that contain code and their associated program
+addresses for the given source filename. The entries are sorted in
+ascending PC order.
@subsubheading @value{GDBN} Command
-No equivalent.
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Example
+@smallexample
+(gdb)
+-symbol-list-lines basics.c
+^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-symbol-list-types} Command
+@findex -symbol-list-types
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-list-types
+@end smallexample
+
+List all the type names.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding commands are @samp{info types} in @value{GDBN},
+@samp{gdb_search} in @code{gdbtk}.
@subsubheading Example
N.A.
-@subheading The @code{-target-select} Command
-@findex -target-select
+@subheading The @code{-symbol-list-variables} Command
+@findex -symbol-list-variables
@subsubheading Synopsis
@smallexample
- -target-select @var{type} @var{parameters @dots{}}
+ -symbol-list-variables
@end smallexample
-Connect @value{GDBN} to the remote target. This command takes two args:
+List all the global and static variable names.
-@table @samp
-@item @var{type}
-The type of target, for instance @samp{async}, @samp{remote}, etc.
-@item @var{parameters}
-Device names, host names and the like. @xref{Target Commands, ,
-Commands for managing targets}, for more details.
-@end table
+@subsubheading @value{GDBN} Command
-The output is a connection notification, followed by the address at
-which the target program is, in the following form:
+@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-locate} Command
+@findex -symbol-locate
+
+@subsubheading Synopsis
@smallexample
-^connected,addr="@var{address}",func="@var{function name}",
- args=[@var{arg list}]
+ -symbol-locate
@end smallexample
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{target}.
+@samp{gdb_loc} in @code{gdbtk}.
@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-type} Command
+@findex -symbol-type
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--target-select async /dev/ttya
-^connected,addr="0xfe00a300",func="??",args=[]
-(@value{GDBP})
+ -symbol-type @var{variable}
@end smallexample
+Show type of @var{variable}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
+@samp{gdb_obj_variable}.
+
+@subsubheading Example
+N.A.
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Thread Commands
-@section @sc{gdb/mi} Thread Commands
+@node GDB/MI File Commands
+@section @sc{gdb/mi} File Commands
+This section describes the GDB/MI commands to specify executable file names
+and to read in and obtain symbol table information.
-@subheading The @code{-thread-info} Command
-@findex -thread-info
+@subheading The @code{-file-exec-and-symbols} Command
+@findex -file-exec-and-symbols
@subsubheading Synopsis
@smallexample
- -thread-info
+ -file-exec-and-symbols @var{file}
@end smallexample
-@subsubheading @value{GDBN} command
+Specify the executable file to be debugged. This file is the one from
+which the symbol table is also read. If no file is specified, the
+command clears the executable and symbol information. If breakpoints
+are set when using this command with no arguments, @value{GDBN} will produce
+error messages. Otherwise, no output is produced, except a completion
+notification.
-No equivalent.
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{file}.
@subsubheading Example
-N.A.
+
+@smallexample
+(gdb)
+-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
+@end smallexample
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
+@subheading The @code{-file-exec-file} Command
+@findex -file-exec-file
@subsubheading Synopsis
@smallexample
- -thread-list-all-threads
+ -file-exec-file @var{file}
@end smallexample
+Specify the executable file to be debugged. Unlike
+@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
+from this file. If used without argument, @value{GDBN} clears the information
+about the executable file. No output is produced, except a completion
+notification.
+
@subsubheading @value{GDBN} Command
-The equivalent @value{GDBN} command is @samp{info threads}.
+The corresponding @value{GDBN} command is @samp{exec-file}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
+@end smallexample
-@subheading The @code{-thread-list-ids} Command
-@findex -thread-list-ids
+
+@subheading The @code{-file-list-exec-sections} Command
+@findex -file-list-exec-sections
@subsubheading Synopsis
@smallexample
- -thread-list-ids
+ -file-list-exec-sections
@end smallexample
-Produces a list of the currently known @value{GDBN} thread ids. At the
-end of the list it also prints the total number of such threads.
+List the sections of the current executable file.
@subsubheading @value{GDBN} Command
-Part of @samp{info threads} supplies the same information.
+The @value{GDBN} command @samp{info file} shows, among the rest, the same
+information as this command. @code{gdbtk} has a corresponding command
+@samp{gdb_load_info}.
@subsubheading Example
+N.A.
-No threads present, besides the main process:
+
+@subheading The @code{-file-list-exec-source-file} Command
+@findex -file-list-exec-source-file
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--thread-list-ids
-^done,thread-ids=@{@},number-of-threads="0"
-(@value{GDBP})
+ -file-list-exec-source-file
@end smallexample
+List the line number, the current source file, and the absolute path
+to the current source file for the current executable.
-Several threads:
+@subsubheading @value{GDBN} Command
+
+The @value{GDBN} equivalent is @samp{info source}
+
+@subsubheading Example
@smallexample
-(@value{GDBP})
--thread-list-ids
-^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
-number-of-threads="3"
-(@value{GDBP})
+(gdb)
+123-file-list-exec-source-file
+123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
+(gdb)
@end smallexample
-@subheading The @code{-thread-select} Command
-@findex -thread-select
+@subheading The @code{-file-list-exec-source-files} Command
+@findex -file-list-exec-source-files
@subsubheading Synopsis
@smallexample
- -thread-select @var{threadnum}
+ -file-list-exec-source-files
@end smallexample
-Make @var{threadnum} the current thread. It prints the number of the new
-current thread, and the topmost frame for that thread.
+List the source files for the current executable.
+
+It will always output the filename, but only when GDB can find the absolute
+file name of a source file, will it output the fullname.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{thread}.
+The @value{GDBN} equivalent is @samp{info sources}.
+@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
@subsubheading Example
-
@smallexample
-(@value{GDBP})
--exec-next
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",thread-id="2",line="187",
-file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
-(@value{GDBP})
--thread-list-ids
-^done,
-thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
-number-of-threads="3"
-(@value{GDBP})
--thread-select 3
-^done,new-thread-id="3",
-frame=@{level="0",func="vprintf",
-args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
-@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
-(@value{GDBP})
+(gdb)
+-file-list-exec-source-files
+^done,files=[
+@{file=foo.c,fullname=/home/foo.c@},
+@{file=/home/bar.c,fullname=/home/bar.c@},
+@{file=gdb_could_not_find_fullpath.c@}]
+(gdb)
+@end smallexample
+
+@subheading The @code{-file-list-shared-libraries} Command
+@findex -file-list-shared-libraries
+
+@subsubheading Synopsis
+
+@smallexample
+ -file-list-shared-libraries
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Tracepoint Commands
-@section @sc{gdb/mi} Tracepoint Commands
+List the shared libraries in the program.
-The tracepoint commands are not yet implemented.
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-actions
+The corresponding @value{GDBN} command is @samp{info shared}.
-@c @subheading -trace-delete
+@subsubheading Example
+N.A.
-@c @subheading -trace-disable
-@c @subheading -trace-dump
+@subheading The @code{-file-list-symbol-files} Command
+@findex -file-list-symbol-files
-@c @subheading -trace-enable
+@subsubheading Synopsis
-@c @subheading -trace-exists
+@smallexample
+ -file-list-symbol-files
+@end smallexample
-@c @subheading -trace-find
+List symbol files.
-@c @subheading -trace-frame-number
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-info
+The corresponding @value{GDBN} command is @samp{info file} (part of it).
-@c @subheading -trace-insert
+@subsubheading Example
+N.A.
-@c @subheading -trace-list
-@c @subheading -trace-pass-count
+@subheading The @code{-file-symbol-file} Command
+@findex -file-symbol-file
-@c @subheading -trace-save
+@subsubheading Synopsis
-@c @subheading -trace-start
+@smallexample
+ -file-symbol-file @var{file}
+@end smallexample
-@c @subheading -trace-stop
+Read symbol table info from the specified @var{file} argument. When
+used without arguments, clears @value{GDBN}'s symbol table info. No output is
+produced, except for a completion notification.
+@subsubheading @value{GDBN} Command
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Variable Objects
-@section @sc{gdb/mi} Variable Objects
+The corresponding @value{GDBN} command is @samp{symbol-file}.
+@subsubheading Example
-@subheading Motivation for Variable Objects in @sc{gdb/mi}
+@smallexample
+(gdb)
+-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
+@end smallexample
-For the implementation of a variable debugger window (locals, watched
-expressions, etc.), we are proposing the adaptation of the existing code
-used by @code{Insight}.
+@ignore
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Memory Overlay Commands
+@section @sc{gdb/mi} Memory Overlay Commands
-The two main reasons for that are:
+The memory overlay commands are not implemented.
-@enumerate 1
-@item
-It has been proven in practice (it is already on its second generation).
+@c @subheading -overlay-auto
-@item
-It will shorten development time (needless to say how important it is
-now).
-@end enumerate
+@c @subheading -overlay-list-mapping-state
-The original interface was designed to be used by Tcl code, so it was
-slightly changed so it could be used through @sc{gdb/mi}. This section
-describes the @sc{gdb/mi} operations that will be available and gives some
-hints about their use.
+@c @subheading -overlay-list-overlays
-@emph{Note}: In addition to the set of operations described here, we
-expect the @sc{gui} implementation of a variable window to require, at
-least, the following operations:
+@c @subheading -overlay-map
-@itemize @bullet
-@item @code{-gdb-show} @code{output-radix}
-@item @code{-stack-list-arguments}
-@item @code{-stack-list-locals}
-@item @code{-stack-select-frame}
-@end itemize
+@c @subheading -overlay-off
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@c @subheading -overlay-on
-@cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation of a named object
-to represent a variable, an expression, a memory location or even a CPU
-register. For each object created, a set of operations is available for
-examining or changing its properties.
+@c @subheading -overlay-unmap
-Furthermore, complex data types, such as C structures, are represented
-in a tree format. For instance, the @code{struct} type variable is the
-root and the children will represent the struct members. If a child
-is itself of a complex type, it will also have children of its own.
-Appropriate language differences are handled for C, C@t{++} and Java.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Signal Handling Commands
+@section @sc{gdb/mi} Signal Handling Commands
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation. It can be chosen among: binary, decimal, hexadecimal, octal
-and natural. Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
+Signal handling commands are not implemented.
-The following is the complete set of @sc{gdb/mi} operations defined to
-access this functionality:
+@c @subheading -signal-handle
-@multitable @columnfractions .4 .6
-@item @strong{Operation}
-@tab @strong{Description}
+@c @subheading -signal-list-handle-actions
-@item @code{-var-create}
-@tab create a variable object
-@item @code{-var-delete}
-@tab delete the variable object and its children
-@item @code{-var-set-format}
-@tab set the display format of this variable
-@item @code{-var-show-format}
-@tab show the display format of this variable
-@item @code{-var-info-num-children}
-@tab tells how many children this object has
-@item @code{-var-list-children}
-@tab return a list of the object's children
-@item @code{-var-info-type}
-@tab show the type of this variable object
-@item @code{-var-info-expression}
-@tab print what this variable object represents
-@item @code{-var-show-attributes}
-@tab is this variable editable? does it exist here?
-@item @code{-var-evaluate-expression}
-@tab get the value of this variable
-@item @code{-var-assign}
-@tab set the value of this variable
-@item @code{-var-update}
-@tab update the variable and its children
-@end multitable
+@c @subheading -signal-list-signal-types
+@end ignore
-In the next subsection we describe each operation in detail and suggest
-how it can be used.
-@subheading Description And Use of Operations on Variable Objects
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Target Manipulation
+@section @sc{gdb/mi} Target Manipulation Commands
-@subheading The @code{-var-create} Command
-@findex -var-create
+
+@subheading The @code{-target-attach} Command
+@findex -target-attach
@subsubheading Synopsis
@smallexample
- -var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*"@} @var{expression}
+ -target-attach @var{pid} | @var{file}
@end smallexample
-This operation creates a variable object, which allows the monitoring of
-a variable, the result of an expression, a memory cell or a CPU
-register.
-
-The @var{name} parameter is the string by which the object can be
-referenced. It must be unique. If @samp{-} is specified, the varobj
-system will generate a string ``varNNNNNN'' automatically. It will be
-unique provided that one does not specify @var{name} on that format.
-The command fails if a duplicate name is found.
-
-The frame under which the expression should be evaluated can be
-specified by @var{frame-addr}. A @samp{*} indicates that the current
-frame should be used.
+Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
-@var{expression} is any expression valid on the current language set (must not
-begin with a @samp{*}), or one of the following:
+@subsubheading @value{GDBN} command
-@itemize @bullet
-@item
-@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
+The corresponding @value{GDBN} command is @samp{attach}.
-@item
-@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
+@subsubheading Example
+N.A.
-@item
-@samp{$@var{regname}} --- a CPU register name
-@end itemize
-@subsubheading Result
+@subheading The @code{-target-compare-sections} Command
+@findex -target-compare-sections
-This operation returns the name, number of children and the type of the
-object created. Type is returned as a string as the ones generated by
-the @value{GDBN} CLI:
+@subsubheading Synopsis
@smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ -target-compare-sections [ @var{section} ]
@end smallexample
+Compare data of section @var{section} on target to the exec file.
+Without the argument, all sections are compared.
-@subheading The @code{-var-delete} Command
-@findex -var-delete
-
-@subsubheading Synopsis
-
-@smallexample
- -var-delete @var{name}
-@end smallexample
+@subsubheading @value{GDBN} Command
-Deletes a previously created variable object and all of its children.
+The @value{GDBN} equivalent is @samp{compare-sections}.
-Returns an error if the object @var{name} is not found.
+@subsubheading Example
+N.A.
-@subheading The @code{-var-set-format} Command
-@findex -var-set-format
+@subheading The @code{-target-detach} Command
+@findex -target-detach
@subsubheading Synopsis
@smallexample
- -var-set-format @var{name} @var{format-spec}
+ -target-detach
@end smallexample
-Sets the output format for the value of the object @var{name} to be
-@var{format-spec}.
+Detach from the remote target which normally resumes its execution.
+There's no output.
-The syntax for the @var{format-spec} is as follows:
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{detach}.
+
+@subsubheading Example
@smallexample
- @var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural@}
+(gdb)
+-target-detach
+^done
+(gdb)
@end smallexample
-@subheading The @code{-var-show-format} Command
-@findex -var-show-format
+@subheading The @code{-target-disconnect} Command
+@findex -target-disconnect
@subsubheading Synopsis
-@smallexample
- -var-show-format @var{name}
-@end smallexample
+@example
+ -target-disconnect
+@end example
+
+Disconnect from the remote target. There's no output and the target is
+generally not resumed.
+
+@subsubheading @value{GDBN} command
-Returns the format used to display the value of the object @var{name}.
+The corresponding @value{GDBN} command is @samp{disconnect}.
+
+@subsubheading Example
@smallexample
- @var{format} @expansion{}
- @var{format-spec}
+(gdb)
+-target-disconnect
+^done
+(gdb)
@end smallexample
-@subheading The @code{-var-info-num-children} Command
-@findex -var-info-num-children
+@subheading The @code{-target-download} Command
+@findex -target-download
@subsubheading Synopsis
@smallexample
- -var-info-num-children @var{name}
+ -target-download
@end smallexample
-Returns the number of children of a variable object @var{name}:
+Loads the executable onto the remote target.
+It prints out an update message every half second, which includes the fields:
-@smallexample
- numchild=@var{n}
-@end smallexample
+@table @samp
+@item section
+The name of the section.
+@item section-sent
+The size of what has been sent so far for that section.
+@item section-size
+The size of the section.
+@item total-sent
+The total size of what was sent so far (the current and the previous sections).
+@item total-size
+The size of the overall executable to download.
+@end table
+@noindent
+Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
+@sc{gdb/mi} Output Syntax}).
-@subheading The @code{-var-list-children} Command
-@findex -var-list-children
+In addition, it prints the name and size of the sections, as they are
+downloaded. These messages include the following fields:
-@subsubheading Synopsis
+@table @samp
+@item section
+The name of the section.
+@item section-size
+The size of the section.
+@item total-size
+The size of the overall executable to download.
+@end table
-@smallexample
- -var-list-children [@var{print-values}] @var{name}
-@end smallexample
-@anchor{-var-list-children}
+@noindent
+At the end, a summary is printed.
-Return a list of the children of the specified variable object and
-create variable objects for them, if they do not already exist. With
-a single argument or if @var{print-values} has a value for of 0 or
-@code{--no-values}, print only the names of the variables; if
-@var{print-values} is 1 or @code{--all-values}, also print their
-values; and if it is 2 or @code{--simple-values} print the name and
-value for simple data types and just the name for arrays, structures
-and unions.
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{load}.
@subsubheading Example
+Note: each status message appears on a single line. Here the messages
+have been broken down so that they can fit onto a page.
+
@smallexample
-(@value{GDBP})
- -var-list-children n
- ^done,numchild=@var{n},children=[@{name=@var{name},
- numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
-(@value{GDBP})
- -var-list-children --all-values n
- ^done,numchild=@var{n},children=[@{name=@var{name},
- numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
+(gdb)
+-target-download
++download,@{section=".text",section-size="6668",total-size="9880"@}
++download,@{section=".text",section-sent="512",section-size="6668",
+total-sent="512",total-size="9880"@}
++download,@{section=".text",section-sent="1024",section-size="6668",
+total-sent="1024",total-size="9880"@}
++download,@{section=".text",section-sent="1536",section-size="6668",
+total-sent="1536",total-size="9880"@}
++download,@{section=".text",section-sent="2048",section-size="6668",
+total-sent="2048",total-size="9880"@}
++download,@{section=".text",section-sent="2560",section-size="6668",
+total-sent="2560",total-size="9880"@}
++download,@{section=".text",section-sent="3072",section-size="6668",
+total-sent="3072",total-size="9880"@}
++download,@{section=".text",section-sent="3584",section-size="6668",
+total-sent="3584",total-size="9880"@}
++download,@{section=".text",section-sent="4096",section-size="6668",
+total-sent="4096",total-size="9880"@}
++download,@{section=".text",section-sent="4608",section-size="6668",
+total-sent="4608",total-size="9880"@}
++download,@{section=".text",section-sent="5120",section-size="6668",
+total-sent="5120",total-size="9880"@}
++download,@{section=".text",section-sent="5632",section-size="6668",
+total-sent="5632",total-size="9880"@}
++download,@{section=".text",section-sent="6144",section-size="6668",
+total-sent="6144",total-size="9880"@}
++download,@{section=".text",section-sent="6656",section-size="6668",
+total-sent="6656",total-size="9880"@}
++download,@{section=".init",section-size="28",total-size="9880"@}
++download,@{section=".fini",section-size="28",total-size="9880"@}
++download,@{section=".data",section-size="3156",total-size="9880"@}
++download,@{section=".data",section-sent="512",section-size="3156",
+total-sent="7236",total-size="9880"@}
++download,@{section=".data",section-sent="1024",section-size="3156",
+total-sent="7748",total-size="9880"@}
++download,@{section=".data",section-sent="1536",section-size="3156",
+total-sent="8260",total-size="9880"@}
++download,@{section=".data",section-sent="2048",section-size="3156",
+total-sent="8772",total-size="9880"@}
++download,@{section=".data",section-sent="2560",section-size="3156",
+total-sent="9284",total-size="9880"@}
++download,@{section=".data",section-sent="3072",section-size="3156",
+total-sent="9796",total-size="9880"@}
+^done,address="0x10004",load-size="9880",transfer-rate="6586",
+write-rate="429"
+(gdb)
@end smallexample
-@subheading The @code{-var-info-type} Command
-@findex -var-info-type
+@subheading The @code{-target-exec-status} Command
+@findex -target-exec-status
@subsubheading Synopsis
@smallexample
- -var-info-type @var{name}
+ -target-exec-status
@end smallexample
-Returns the type of the specified variable @var{name}. The type is
-returned as a string in the same format as it is output by the
-@value{GDBN} CLI:
+Provide information on the state of the target (whether it is running or
+not, for instance).
-@smallexample
- type=@var{typename}
-@end smallexample
+@subsubheading @value{GDBN} Command
+There's no equivalent @value{GDBN} command.
-@subheading The @code{-var-info-expression} Command
-@findex -var-info-expression
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-target-list-available-targets} Command
+@findex -target-list-available-targets
@subsubheading Synopsis
@smallexample
- -var-info-expression @var{name}
+ -target-list-available-targets
@end smallexample
-Returns what is represented by the variable object @var{name}:
+List the possible targets to connect to.
-@smallexample
- lang=@var{lang-spec},exp=@var{expression}
-@end smallexample
+@subsubheading @value{GDBN} Command
-@noindent
-where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
+The corresponding @value{GDBN} command is @samp{help target}.
-@subheading The @code{-var-show-attributes} Command
-@findex -var-show-attributes
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-target-list-current-targets} Command
+@findex -target-list-current-targets
@subsubheading Synopsis
@smallexample
- -var-show-attributes @var{name}
+ -target-list-current-targets
@end smallexample
-List attributes of the specified variable object @var{name}:
+Describe the current target.
-@smallexample
- status=@var{attr} [ ( ,@var{attr} )* ]
-@end smallexample
+@subsubheading @value{GDBN} Command
-@noindent
-where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
+The corresponding information is printed by @samp{info file} (among
+other things).
-@subheading The @code{-var-evaluate-expression} Command
-@findex -var-evaluate-expression
+@subsubheading Example
+N.A.
-@subsubheading Synopsis
-@smallexample
- -var-evaluate-expression @var{name}
-@end smallexample
+@subheading The @code{-target-list-parameters} Command
+@findex -target-list-parameters
-Evaluates the expression that is represented by the specified variable
-object and returns its value as a string in the current format specified
-for the object:
+@subsubheading Synopsis
@smallexample
- value=@var{value}
+ -target-list-parameters
@end smallexample
-Note that one must invoke @code{-var-list-children} for a variable
-before the value of a child variable can be evaluated.
+@c ????
-@subheading The @code{-var-assign} Command
-@findex -var-assign
+@subsubheading @value{GDBN} Command
-@subsubheading Synopsis
+No equivalent.
-@smallexample
- -var-assign @var{name} @var{expression}
-@end smallexample
+@subsubheading Example
+N.A.
-Assigns the value of @var{expression} to the variable object specified
-by @var{name}. The object must be @samp{editable}. If the variable's
-value is altered by the assign, the variable will show up in any
-subsequent @code{-var-update} list.
-@subsubheading Example
+@subheading The @code{-target-select} Command
+@findex -target-select
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--var-assign var1 3
-^done,value="3"
-(@value{GDBP})
--var-update *
-^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
-(@value{GDBP})
+ -target-select @var{type} @var{parameters @dots{}}
@end smallexample
-@subheading The @code{-var-update} Command
-@findex -var-update
+Connect @value{GDBN} to the remote target. This command takes two args:
-@subsubheading Synopsis
+@table @samp
+@item @var{type}
+The type of target, for instance @samp{async}, @samp{remote}, etc.
+@item @var{parameters}
+Device names, host names and the like. @xref{Target Commands, ,
+Commands for managing targets}, for more details.
+@end table
+
+The output is a connection notification, followed by the address at
+which the target program is, in the following form:
@smallexample
- -var-update [@var{print-values}] @{@var{name} | "*"@}
+^connected,addr="@var{address}",func="@var{function name}",
+ args=[@var{arg list}]
@end smallexample
-Update the value of the variable object @var{name} by evaluating its
-expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated. The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{target}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--var-assign var1 3
-^done,value="3"
-(@value{GDBP})
--var-update --all-values var1
-^done,changelist=[@{name="var1",value="3",in_scope="true",
-type_changed="false"@}]
-(@value{GDBP})
+(gdb)
+-target-select async /dev/ttya
+^connected,addr="0xfe00a300",func="??",args=[]
+(gdb)
@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-gdb-exit
^exit
@end smallexample
+
+@subheading The @code{-exec-abort} Command
+@findex -exec-abort
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-abort
+@end smallexample
+
+Kill the inferior running program.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{kill}.
+
+@subsubheading Example
+N.A.
+
+
@subheading The @code{-gdb-set} Command
@findex -gdb-set
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-gdb-set $foo=3
^done
-(@value{GDBP})
+(gdb)
@end smallexample
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-gdb-show annotate
^done,value="0"
-(@value{GDBP})
+(gdb)
@end smallexample
@c @subheading -gdb-source
@c This example modifies the actual output from GDB to avoid overfull
@c box in TeX.
@smallexample
-(@value{GDBP})
+(gdb)
-gdb-version
~GNU gdb 5.2.1
~Copyright 2000 Free Software Foundation, Inc.
~This GDB was configured as
"--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
^done
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-interpreter-exec} Command
@smallexample
-interpreter-exec @var{interpreter} @var{command}
@end smallexample
+@anchor{-interpreter-exec}
Execute the specified @var{command} in the given @var{interpreter}.
@subheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-interpreter-exec console "break main"
&"During symbol reading, couldn't parse type; debugger out of date?.\n"
&"During symbol reading, bad structure-type format.\n"
~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
^done
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-inferior-tty-set} Command
@subheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-inferior-tty-set /dev/pts/1
^done
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-inferior-tty-show} Command
@subheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-inferior-tty-set /dev/pts/1
^done
-(@value{GDBP})
+(gdb)
-inferior-tty-show
^done,inferior_tty_terminal="/dev/pts/1"
-(@value{GDBP})
+(gdb)
@end smallexample
@node Annotations
@node Installing GDB
@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
@cindex installation
-@cindex configuring @value{GDBN}, and source tree subdirectories
+@menu
+* Requirements:: Requirements for building @value{GDBN}
+* Running Configure:: Invoking the @value{GDBN} @code{configure} script
+* Separate Objdir:: Compiling @value{GDBN} in another directory
+* Config Names:: Specifying names for hosts and targets
+* Configure Options:: Summary of options for configure
+@end menu
+
+@node Requirements
+@section Requirements for building @value{GDBN}
+@cindex building @value{GDBN}, requirements for
+
+Building @value{GDBN} requires various tools and packages to be available.
+Other packages will be used only if they are found.
+
+@heading Tools/packages necessary for building @value{GDBN}
+@table @asis
+@item ISO C90 compiler
+@value{GDBN} is written in ISO C90. It should be buildable with any
+working C90 compiler, e.g.@: GCC.
+
+@end table
+
+@heading Tools/packages optional for building @value{GDBN}
+@table @asis
+@item Expat
+@value{GDBN} can use the Expat XML parsing library. This library may be
+included with your operating system distribution; if it is not, you
+can get the latest version from @url{http://expat.sourceforge.net}.
+The @code{configure} script will search for this library in several
+standard locations; if it is installed in an unusual path, you can
+use the @option{--with-libexpat-prefix} option to specify its location.
+
+Expat is used currently only used to implement some remote-specific
+features.
+
+@end table
+
+@node Running Configure
+@section Invoking the @value{GDBN} @code{configure} script
+@cindex configuring @value{GDBN}
@value{GDBN} comes with a @code{configure} script that automates the process
of preparing @value{GDBN} for installation; you can then use @code{make} to
build the @code{gdb} program.
that @value{GDBN} uses the shell to start your program---some systems refuse to
let @value{GDBN} debug child processes whose programs are not readable.
-@menu
-* Separate Objdir:: Compiling @value{GDBN} in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
-@end menu
-
@node Separate Objdir
@section Compiling @value{GDBN} in another directory
* Interrupts::
* Examples::
* File-I/O remote protocol extension::
+* Memory map format::
@end menu
@node Overview
exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
exceptions).
-Fields within the packet should be separated using @samp{,} @samp{;} or
@cindex remote protocol, field separator
+Fields within the packet should be separated using @samp{,} @samp{;} or
@samp{:}. Except where otherwise noted all numbers are represented in
@sc{hex} with leading zeros suppressed.
@samp{:} could not appear as the third character in a packet (as it
would potentially conflict with the @var{sequence-id}).
+@cindex remote protocol, binary data
+@anchor{Binary Data}
+Binary data in most packets is encoded either as two hexadecimal
+digits per byte of binary data. This allowed the traditional remote
+protocol to work over connections which were only seven-bit clean.
+Some packets designed more recently assume an eight-bit clean
+connection, and use a more efficient encoding to send and receive
+binary data.
+
+The binary data representation uses @code{7d} (@sc{ascii} @samp{@}})
+as an escape character. Any escaped byte is transmitted as the escape
+character followed by the original character XORed with @code{0x20}.
+For example, the byte @code{0x7d} would be transmitted as the two
+bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}),
+@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii}
+@samp{@}}) must always be escaped. Responses sent by the stub
+must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it
+is not interpreted as the start of a run-length encoded sequence
+(described next).
+
Response @var{data} can be run-length encoded to save space. A @samp{*}
means that the next character is an @sc{ascii} encoding giving a repeat count
which stands for that many repetitions of the character preceding the
Reply:
@table @samp
@item @var{XX@dots{}}
-Memory contents; each byte is transmitted as a two-digit hexidecimal
+Memory contents; each byte is transmitted as a two-digit hexadecimal
number. The reply may contain fewer bytes than requested if the
server was able to read only part of the region of memory.
@item E @var{NN}
@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
-hexidecimal number.
+hexadecimal number.
Reply:
@table @samp
@anchor{write register packet}
@cindex @samp{P} packet
Write register @var{n@dots{}} with value @var{r@dots{}}. The register
-number @var{n} is in hexidecimal, and @var{r@dots{}} contains two hex
+number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
digits for each byte in the register (target byte order).
Reply:
The @samp{vCont} packet is not supported.
@end table
+@item vFlashErase:@var{addr},@var{length}
+@cindex @samp{vFlashErase} packet
+Direct the stub to erase @var{length} bytes of flash starting at
+@var{addr}. The region may enclose any number of flash blocks, but
+its start and end must fall on block boundaries, as indicated by the
+flash block size appearing in the memory map (@pxref{Memory map
+format}). @value{GDBN} groups flash memory programming operations
+together, and sends a @samp{vFlashDone} request after each group; the
+stub is allowed to delay erase operation until the @samp{vFlashDone}
+packet is received.
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashWrite:@var{addr}:@var{XX@dots{}}
+@cindex @samp{vFlashWrite} packet
+Direct the stub to write data to flash address @var{addr}. The data
+is passed in binary form using the same encoding as for the @samp{X}
+packet (@pxref{Binary Data}). The memory ranges specified by
+@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
+not overlap, and must appear in order of increasing addresses
+(although @samp{vFlashErase} packets for higher addresses may already
+have been received; the ordering is guaranteed only between
+@samp{vFlashWrite} packets). If a packet writes to an address that was
+neither erased by a preceding @samp{vFlashErase} packet nor by some other
+target-specific method, the results are unpredictable.
+
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E.memtype
+for vFlashWrite addressing non-flash memory
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashDone
+@cindex @samp{vFlashDone} packet
+Indicate to the stub that flash programming operation is finished.
+The stub is permitted to delay or batch the effects of a group of
+@samp{vFlashErase} and @samp{vFlashWrite} packets until a
+@samp{vFlashDone} packet is received. The contents of the affected
+regions of flash memory are unpredictable until the @samp{vFlashDone}
+request is completed.
+
@item X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@cindex @samp{X} packet
Write data to memory, where the data is transmitted in binary.
@var{addr} is address, @var{length} is number of bytes,
-@samp{@var{XX}@dots{}} is binary data. The bytes @code{0x23}
-(@sc{ascii} @samp{#}), @code{0x24} (@sc{ascii} @samp{$}), and
-@code{0x7d} (@sc{ascii} @samp{@}}) are escaped using @code{0x7d}
-(@sc{ascii} @samp{@}}), and then XORed with @code{0x20}. For example,
-the byte @code{0x7d} would be transmitted as the two bytes @code{0x7d
-0x5d}.
+@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
Reply:
@table @samp
@table @samp
@item S @var{AA}
-The program received signal number @var{AA} (a two-digit hexidecimal
-number).
+The program received signal number @var{AA} (a two-digit hexadecimal
+number). This is equivalent to a @samp{T} response with no
+@var{n}:@var{r} pairs.
@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
@cindex @samp{T} packet reply
-The program received signal number @var{AA} (a two-digit hexidecimal
-number). Single-step and breakpoint traps are reported this way. The
-@samp{@var{n}:@var{r}} pairs give the values of important registers or
-other information:
+The program received signal number @var{AA} (a two-digit hexadecimal
+number). This is equivalent to an @samp{S} response, except that the
+@samp{@var{n}:@var{r}} pairs can carry values of important registers
+and other information directly in the stop reply packet, reducing
+round-trip latency. Single-step and breakpoint traps are reported
+this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
@enumerate
@item
-If @var{n} is a hexidecimal number, it is a register number, and the
+If @var{n} is a hexadecimal number, it is a register number, and the
corresponding @var{r} gives that register's value. @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
Reply:
@table @samp
@item QC @var{pid}
-Where @var{pid} is an unsigned hexidecimal process id.
+Where @var{pid} is an unsigned hexadecimal process id.
@item @r{(anything else)}
Any other reply implies the old pid.
@end table
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
-@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
-@cindex read special object, remote request
-@cindex @samp{qPart} packet
-Read uninterpreted bytes from the target's special data area
-identified by the keyword @var{object}. Request @var{length} bytes
-starting at @var{offset} bytes into the data. The content and
-encoding of @var{annex} is specific to the object; it can supply
-additional details about what data to access.
-
-Since this packet is ambiguous with the older @code{qP} packet, we
-plan to rename it.
-
-Here are the specific requests of this form defined so far. All
-@samp{qPart:@var{object}:read:@dots{}} requests use the same reply
-formats, listed below.
-
-@table @samp
-@item qPart:auxv:read::@var{offset},@var{length}
-Access the target's @dfn{auxiliary vector}. @xref{OS Information,
-auxiliary vector}, and see @ref{Remote configuration,
-read-aux-vector-packet}. Note @var{annex} must be empty.
-@end table
-
-Reply:
-@table @samp
-@item OK
-The @var{offset} in the request is at the end of the data.
-There is no more data to be read.
-
-@item @var{XX}@dots{}
-Hex encoded data bytes read.
-This may be fewer bytes than the @var{length} in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered reading the data.
-@var{nn} is a hex-encoded @code{errno} value.
-
-@item
-An empty reply indicates the @var{object} or @var{annex} string was not
-recognized by the stub.
-@end table
-
-@item qPart:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
-@cindex write data into object, remote request
-Write uninterpreted bytes into the target's special data area
-identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @samp{@var{data}@dots{}} is the hex-encoded data to be
-written. The content and encoding of @var{annex} is specific to the
-object; it can supply additional details about what data to access.
-
-No requests of this form are presently in use. This specification
-serves as a placeholder to document the common format that new
-specific request specifications ought to use.
-
-Reply:
-@table @samp
-@item @var{nn}
-@var{nn} (hex encoded) is the number of bytes written.
-This may be fewer bytes than supplied in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered writing the data.
-@var{nn} is a hex-encoded @code{errno} value.
-
-@item
-An empty reply indicates the @var{object} or @var{annex} string was not
-recognized by the stub, or that the object does not support writing.
-@end table
-
-@item qPart:@var{object}:@var{operation}:@dots{}
-Requests of this form may be added in the future. When a stub does
-not recognize the @var{object} keyword, or its support for
-@var{object} does not recognize the @var{operation} keyword, the stub
-must respond with an empty packet.
-
@item qRcmd,@var{command}
@cindex execute remote command, remote request
@cindex @samp{qRcmd} packet
@cindex supported packets, remote query
@cindex features of the remote protocol
@cindex @samp{qSupported} packet
+@anchor{qSupported}
Tell the remote stub about features supported by @value{GDBN}, and
query the stub for features it supports. This packet allows
@value{GDBN} and the remote stub to take advantage of each others'
@multitable @columnfractions 0.25 0.2 0.2 0.2
@c NOTE: The first row should be @headitem, but we do not yet require
@c a new enough version of Texinfo (4.7) to use @headitem.
-@item Packet Name
+@item Feature Name
@tab Value Required
@tab Default
@tab Probe Allowed
@tab @samp{-}
@tab No
+@item @samp{qXfer:auxv:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:memory-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@end multitable
These are the currently defined stub features, in more detail:
byte in its buffer for the NUL. If this stub feature is not supported,
@value{GDBN} guesses based on the size of the @samp{g} packet response.
+@item qXfer:auxv:read
+The remote stub understands the @samp{qXfer:auxv:read} packet
+(@pxref{qXfer auxiliary vector read}).
+
@end table
@item qSymbol::
@itemx qTStatus
@xref{Tracepoint Packets}.
+@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
+@cindex read special object, remote request
+@cindex @samp{qXfer} packet
+@anchor{qXfer read}
+Read uninterpreted bytes from the target's special data area
+identified by the keyword @var{object}. Request @var{length} bytes
+starting at @var{offset} bytes into the data. The content and
+encoding of @var{annex} is specific to the object; it can supply
+additional details about what data to access.
+
+Here are the specific requests of this form defined so far. All
+@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
+formats, listed below.
+
+@table @samp
+@item qXfer:auxv:read::@var{offset},@var{length}
+@anchor{qXfer auxiliary vector read}
+Access the target's @dfn{auxiliary vector}. @xref{OS Information,
+auxiliary vector}, and @ref{Remote configuration,
+read-aux-vector-packet}. Note @var{annex} must be empty.
+
+This packet is not probed by default; the remote stub must request it,
+by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
+@table @samp
+@item qXfer:memory-map:read::@var{offset},@var{length}
+@anchor{qXfer memory map read}
+Access the target's @dfn{memory-map}. @xref{Memory map format}. The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
+Reply:
+@table @samp
+@item m @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the
+target. There may be more data at a higher address (although
+it is permitted to return @samp{m} even for the last valid
+block of data, as long as at least one byte of data was read).
+@var{data} may have fewer bytes than the @var{length} in the
+request.
+
+@item l @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the target.
+There is no more data to be read. @var{data} may have fewer bytes
+than the @var{length} in the request.
+
+@item l
+The @var{offset} in the request is at the end of the data.
+There is no more data to be read.
+
+@item E00
+The request was malformed, or @var{annex} was invalid.
+
+@item E @var{nn}
+The offset was invalid, or there was an error encountered reading the data.
+@var{nn} is a hex-encoded @code{errno} value.
+
+@item
+An empty reply indicates the @var{object} string was not recognized by
+the stub, or that the object does not support reading.
+@end table
+
+@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@cindex write data into object, remote request
+Write uninterpreted bytes into the target's special data area
+identified by the keyword @var{object}, starting at @var{offset} bytes
+into the data. @samp{@var{data}@dots{}} is the binary-encoded data
+(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
+is specific to the object; it can supply additional details about what data
+to access.
+
+No requests of this form are presently in use. This specification
+serves as a placeholder to document the common format that new
+specific request specifications ought to use.
+
+Reply:
+@table @samp
+@item @var{nn}
+@var{nn} (hex encoded) is the number of bytes written.
+This may be fewer bytes than supplied in the request.
+
+@item E00
+The request was malformed, or @var{annex} was invalid.
+
+@item E @var{nn}
+The offset was invalid, or there was an error encountered writing the data.
+@var{nn} is a hex-encoded @code{errno} value.
+
+@item
+An empty reply indicates the @var{object} string was not
+recognized by the stub, or that the object does not support writing.
+@end table
+
+@item qXfer:@var{object}:@var{operation}:@dots{}
+Requests of this form may be added in the future. When a stub does
+not recognize the @var{object} keyword, or its support for
+@var{object} does not recognize the @var{operation} keyword, the stub
+must respond with an empty packet.
+
@end table
@node Register Packet Format
The following @code{g}/@code{G} packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
sixty-four bits. Those registers should be zero/sign extended (which?)
-to fill the space allocated. Register bytes are transfered in target
-byte order. The two nibbles within a register byte are transfered
+to fill the space allocated. Register bytes are transferred in target
+byte order. The two nibbles within a register byte are transferred
most-significant - least-significant.
@table @r
@item MIPS32
-All registers are transfered as thirty-two bit quantities in the order:
+All registers are transferred as thirty-two bit quantities in the order:
32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
registers; fsr; fir; fp.
@item MIPS64
-All registers are transfered as sixty-four bit quantities (including
+All registers are transferred as sixty-four bit quantities (including
thirty-two bit registers such as @code{sr}). The ordering is the same
as @code{MIPS32}.
@item R @var{mask}
Collect the registers whose bits are set in @var{mask}. @var{mask} is
-a hexidecimal number whose @var{i}'th bit is set if register number
+a hexadecimal number whose @var{i}'th bit is set if register number
@var{i} should be collected. (The least significant bit is numbered
zero.) Note that @var{mask} may be any number of digits long; it may
not fit in a 32-bit word.
number @var{basereg}, plus @var{offset}. If @var{basereg} is
@samp{-1}, then the range has a fixed address: @var{offset} is the
address of the lowest byte to collect. The @var{basereg},
-@var{offset}, and @var{len} parameters are all unsigned hexidecimal
+@var{offset}, and @var{len} parameters are all unsigned hexadecimal
values (the @samp{-1} value for @var{basereg} is a special case).
@item X @var{len},@var{expr}
@table @samp
@item F @var{f}
The selected frame is number @var{n} in the trace frame buffer;
-@var{f} is a hexidecimal number. If @var{f} is @samp{-1}, then there
+@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
was no frame matching the criteria in the request packet.
@item T @var{t}
The selected trace frame records a hit of tracepoint number @var{t};
-@var{t} is a hexidecimal number.
+@var{t} is a hexadecimal number.
@end table
@item QTFrame:pc:@var{addr}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame whose PC is @var{addr};
-@var{addr} is a hexidecimal number.
+@var{addr} is a hexadecimal number.
@item QTFrame:tdp:@var{t}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame that is a hit of tracepoint @var{t}; @var{t}
-is a hexidecimal number.
+is a hexadecimal number.
@item QTFrame:range:@var{start}:@var{end}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame whose PC is between @var{start} (inclusive)
-and @var{end} (exclusive); @var{start} and @var{end} are hexidecimal
+and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal
numbers.
@item QTFrame:outside:@var{start}:@var{end}
the Overview section (@pxref{Overview}). When a @code{0x03} byte is
transmitted as part of a packet, it is considered to be packet data
and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
-(@pxref{X packet}, used for binary downloads, may include an unescaped
+(@pxref{X packet}), used for binary downloads, may include an unescaped
@code{0x03} as part of its packet.
Stubs are not required to recognize these interrupt mechanisms and the
@itemize @bullet
@item
-The user presses @kbd{Ctrl-C}. The behaviour is as explained above, and the
+The user types @kbd{C-c}. The behaviour is as explained above, and the
@code{read}
system call is treated as finished.
@item
-The user presses @kbd{Enter}. This is treated as end of input with a trailing
+The user presses @key{RET}. This is treated as end of input with a trailing
newline.
@item
-The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing
+The user types @kbd{C-d}. This is treated as end of input. No trailing
character (neither newline nor Ctrl-D) is appended to the input.
@end itemize
<- @code{T02}
@end smallexample
+@node Memory map format
+@section Memory map format
+@cindex memory map format
+
+To be able to write into flash memory, @value{GDBN} needs to obtain a
+memory map from the target. This section describes the format of the
+memory map.
+
+The memory map is obtained using the @samp{qXfer:memory-map:read}
+(@pxref{qXfer memory map read}) packet and is an XML document that
+lists memory regions. The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE memory-map
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-memory-map.dtd">
+<memory-map>
+ region...
+</memory-map>
+@end smallexample
+
+Each region can be either:
+
+@itemize
+
+@item
+A region of RAM starting at @var{addr} and extending for @var{length}
+bytes from there:
+
+@smallexample
+<memory type="ram" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item
+A region of read-only memory:
+
+@smallexample
+<memory type="rom" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item
+A region of flash memory, with erasure blocks @var{blocksize}
+bytes in length:
+
+@smallexample
+<memory type="flash" start="@var{addr}" length="@var{length}">
+ <property name="blocksize">@var{blocksize}</property>
+</memory>
+@end smallexample
+
+@end itemize
+
+Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
+by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
+packets to write to addresses in such ranges.
+
+The formal DTD for memory map format is given below:
+
+@smallexample
+<!-- ................................................... -->
+<!-- Memory Map XML DTD ................................ -->
+<!-- File: memory-map.dtd .............................. -->
+<!-- .................................... .............. -->
+<!-- memory-map.dtd -->
+<!-- memory-map: Root element with versioning -->
+<!ELEMENT memory-map (memory | property)>
+<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
+<!ELEMENT memory (property)>
+<!-- memory: Specifies a memory region,
+ and its type, or device. -->
+<!ATTLIST memory type CDATA #REQUIRED
+ start CDATA #REQUIRED
+ length CDATA #REQUIRED
+ device CDATA #IMPLIED>
+<!-- property: Generic attribute tag -->
+<!ELEMENT property (#PCDATA | property)*>
+<!ATTLIST property name CDATA #REQUIRED>
+@end smallexample
+
@include agentexpr.texi
@include gpl.texi
projects / deliverable / binutils-gdb.git / blobdiff