\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename gdbmi.info
@settitle GDB/MI Machine Interface
@setchapternewpage off
@c %**end of header

@ifinfo
This file documents GDB/MI, a Machine Interface to GDB.

Copyright (C) 2000, Free Software Foundation, Inc.
Contributed by Cygnus Solutions.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@c  This title page illustrates only one of the
@c  two methods of forming a title page.

@titlepage
@title GDB/MI
@subtitle Version 0.2
@subtitle Feb 2000
@author Andrew Cagney, Fernando Nasser and Elena Zannoni

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Copyright @copyright{} 2000, Free Software Foundation, Inc.
@end titlepage

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Overview

@heading Function and Purpose

GDB/MI is a line based machine oriented text interface to GDB.  It is
specifically intended to support the development of systems which use
the debugger as just one small component of a larger system.

@heading This Document

This document is a specification of the GDB/MI interface.  It is written
in the form of a reference manual.

@heading Terminology

@heading Dependencies

@heading Acknowledgments

In alphabetic order: Fernando Nasser, Stan Shebs and Elena Zannoni.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Command Syntax

@section Input Syntax

@table @code

@item <command> @expansion{} 
<cli-command> | <mi-command>

@item <cli-command> @expansion{}
[ <token> ] "any existing GDB CLI command" <nl>

@item <mi-command> @expansion{}
[ <token> ] ``-'' <operation> ( `` '' <option> )* [ `` --'' ] ( `` '' <parameter> )* <nl> 

@item <token> @expansion{}
``any sequence of digits''

@item <option> @expansion{}
``-'' <parameter> [ `` '' <parameter> ]

@item <parameter> @expansion{}
<non-blank-sequence> | <c-string>

@item <operation> @expansion{}
any of the operations described in this document.

@item <non-blank-sequence> @expansion{}
anything provided it doesn't contain special characters such as ``-''
 <nl>, ``"'' and of course `` ''.

@item <c-string> @expansion{}
``"'' <seven-bit-iso-c-string-content> ``"''

@item <nl> @expansion{}
CR | CR-LF

@end table

Notes:

@itemize @bullet

@item
The CLI commands are still handled by the MI interpreter; their output
is described below

@item
The @code{<token>}, when present, is passed back when the command
finishes.

@item
Some mi commands accept optional arguments as part of the parameter
list. Each option is identified by a leading @code{-} (dash) and may be
followed by an option argument parameter.  Options occure first in the
parameter list and can be delimiated from normal parameters using
@code{--}.

@end itemize

Pragmatics:

@itemize @bullet

@item
We want easy access to the existing CLI syntax (for debugging).

@item
We want it easy to spot a MI operation

@end itemize

@section Output Syntax

The output from GDB/MI consists of zero or more out-of-band records
followed, optionally, by a single result record.  The result record
being for the most recent command.  The sequence of output records is
terminated by ``(gdb)''.

If an input command was prefixed with a @code{<token>} then the
corresponding output for that command will also be prefixed by that same
token.

@table @code
@item <output> @expansion{}
( <out-of-band-record> )* [ <result-record> ] ``(gdb)'' <nl> 

@item <result-record> @expansion{}
[ <token> ] ``^'' <result-class> ( ``,'' <result> )* <nl>

@item <out-of-band-record> @expansion{}
<async-record> | <stream-record>

@item <async-record> @expansion{}
<exec-async-output> | <status-async-output> | <notify-async-output>

@item <exec-async-output> @expansion{}
[ <token> ] ``*'' <async-output>

@item <status-async-output> @expansion{}
[ <token> ] ``+'' <async-output>

@item <notify-async-output> @expansion{}
[ <token> ] ``='' <async-output>

@item <async-output> @expansion{}
<async-class> ( ``,'' <result> )* <nl> 

@item <result-class> @expansion{} 
``done'' | ``running'' | ``connected'' | ``error'' | ``exit''

@item <async-class> @expansion{} 
``stopped'' | others (depending on needs, still in development)

@item <result> @expansion{}
[ <string> ``='' ] <value>

@item <value> @expansion{}
<const> | ``@{'' <result> ( ``,'' <result> )* ``@}''

@item <const> @expansion{}
<c-string>

@item <stream-record> @expansion{}
<console-stream-output> | <target-stream-output> | <log-stream-output>

@item <console-stream-output> @expansion{}
``~'' <c-string>

@item <target-stream-output> @expansion{}
``@@'' <c-string>

@item <log-stream-output> @expansion{}
``&'' <c-string>

@item <nl> @expansion{}
CR | CR-LF

@item <token> @expansion{}
``any sequence of digits''

@end table

In addition, the following are still being developed.

@table @code

@item <query>
This action is currently undefined.

@end table

Notes:

@itemize @bullet

@item
All output sequences end in a single line containing a period.

@item
The @code{<token>} is from the corresponding request.  If an execution
command is interrupted by the -exec-interrupt command, the token
associated with the `*stopped' message is the one of the original
execution command, not the one of the interrupt-command.

@item
<status-async-output> contains on-going status information about the progress
of a slow operation.  It can be discarded. All status output is prefixed by
the prefix `+'.

@item
<exec-async-output> contains asynchronous state change on the target
(stopped, started, disappeared). All async output is prefixed by
the prefix `*'.

@item
<notify-async-output> contains supplementary information that the client should
handle (new breakpoint information). All notify output is prefixed by
the prefix `='.

@item
<console-stream-output> is output that should be displayed as is in the
console.  It is the textual response to a CLI command. All the console
output is prefixed by the prefix ``~''.

@item
<target-stream-output> is the output produced by the target program.
All the target output is prefixed by the prefix ``@@''.

@item
<log-stream-output> is output text coming from GDB's internals, for
instance messages that should be displayed as part of an error log.  All
the log output is prefixed by the prefix ``&''.

@end itemize

@section Simple Examples

@subheading Target stop:

@example
-> -stop
<- (gdb)
@end example

(later)

@example
<- *stop,reason="stop",address="0x123",source="a.c:123"
<- (gdb)
@end example


@subheading Simple CLI command being passed through the MI and on to the CLI.

@example
-> print 1+2
<- ~3\n
<- (gdb)
@end example


@subheading Command with side effects:

@example
-> -symbol-file xyz.exe
<- *breakpoint,nr="3",address="0x123",source="a.c:123"
<- (gdb)
@end example


@subheading A bad command:

@example
-> -rubbish
<- error,"Rubbish not found"
<- (gdb)
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter CLI compatibility

To help users familiar with the GDB's existing CLI interface, the GDB/MI
will accept existing CLI commands.  As specified by the syntax, such
commands can be directly entered into the MI interface and GDB will
respond.

The mechanism is provided as an aid to developers of MI clients and not
as a reliable interface into the CLI.  Since the command is being
interpreteted in an environment that assumes MI behaviour the exact
output of such commands is likely to end up being an un-supported hybrid
of MI and CLI output.


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Output Records

@section Result Records

In addition to a number of out-of-band notifications the response to an
MI command includes one of the following result indications.

@table @code

@item ``^done'' [ ``,'' <results> ]
The synchronous operation was successful, @code{<results>} is the return
value.

@item ``^running''
The asynchronous operation was successfully started.  The target is
running.  @emph{Is this one correct should it be an out-of-band
notification?}

@item ``^error'' ``,'' <c-string>
The operation failed.  The @code{<c-string>} contains the corresponding
error message.

@end table

@section Stream Records

GDB internally maintains a number of output streams: the console, the
target, and the log.  The output intended for each of these streams is
tunneled through the MI interface using stream records.

In addition to the prefix each stream record contains a
@code{<string-output>}.  This is either raw text (with an implicit new
line) or a quoted C string (which does not contain an implicit newline).

@table @code

@item ``~'' <string-output>
The console output stream contains text that should be displayed in the
CLI console window.  It contains the textual responses to CLI commands.

@item ``@@'' <string-output>
The target output stream contains any textual output from the running
target.

@item ``&'' <string-output>
The LOG stream contains debugging messages being produced by GDB's
internals.

@end table

@section Out-of-band Records.

Out-of-band records are used to notify the MI client of additional
changes that have occurred.  Those changes can either be a consequence of
an MI (breakpoint modified) or as a result of target activity (target
stopped).

The following is a preliminary list of possible out-of-band records.

@table @code

@item ``*'' ``stop''

@end table


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Command Description Format

The remaining chapters describe blocks of commands.  Each block of
commands is laid out in a fashion similar to this chapter.

Note the the line breaks shown in the examples are here only for
readability. They don't appear in the real output.
Note that the commands with a non available example (N.A.) are not yet
implemented.

@section Motivation

What motivates the collection of commands

@section Introduction

Brief introduction to the commands as a whole.

@section Operations

@subsection -command <args>...

@subsubsection Result

@subsubsection Out-of-band

@subsubsection Notes

@subsubsection Example


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Breakpoint table commands

@section -break-after <number> <count>
The breakpoint number <number> is not in effect until it has been hit <count> times.
Note how this is reflected in the output of the -break-list command.

@subsection GDB command
ignore

@subsection Example
@example
(gdb) 
-break-insert main
^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
(gdb) 
-break-after 1 3
~
^done
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0",ignore="3"@}@}
(gdb) 
@end example

@c @section -break-catch

@c @section -break-commands

@section -break-condition <number> <expr>
Breakpoint <number> will stop the program only if the condition in <expr> is true.
The condition becomes part of the -break-list output.
@subsection GDB command
condition
@subsection Example
@example
(gdb) 
-break-condition 1 1
^done
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",times="0",ignore="3"@}@}
(gdb) 
@end example

@section -break-delete @{ <breakpoint> @}+
Delete the breakpoint(s) specified in the argument list. This is
obviously reflected in the breakpoint list.
@subsection GDB command
delete
@subsection Example
@example
(gdb) 
-break-delete 1  
^done
(gdb) 
-break-list
^done,BreakpointTable=@{@}
(gdb) 
@end example

@section -break-disable @{ <breakpoint> @}+
Disable the breakpoint(s). Note how the field 'enabled' in the break
list is now set to 'n'.
@subsection GDB command
disable
@subsection Example
@example
(gdb) 
-break-disable 2
^done
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
(gdb) 
@end example

@section -break-enable @{ <breakpoint> @}+
Enable a previously disabled breakpoint(s). 
@subsection GDB command
enable
@subsection Example
@example
(gdb) 
enable 2
^done
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
(gdb) 
@end example

@section -break-info <breakpoint>
REDUNDANT??? Get information about a single breakpoint.
@subsection GDB command
@subsection Example
N.A.

@section -break-insert [ "-t" ] [ "-h" ] [ "-r" ] [ "-c" <condition> ] [ "-i" <ignore-count> ] [ "-p" <thread> ] [ <line> | <addr> ]

<line>, if specified, accordingly to the gdb manual can be one of:
@itemize @bullet
@item function
@c @item +offset
@c @item -offset
@c @item linenum
@item filename:linenum
@item filename:function
@item *address
@end itemize

The possible forms of this command are: 

@table @samp
@item -t
Insert a tempoary breakpoint.
@item -h
Insert a hardware breakpoint.
@item -c <condition>
Make the breakpoint conditional on <condition>
@item -i <ignore-count>
Initialize the <ignore-count>
@item -r
Insert a regular breakpoint in all the functions whose names match the
given regular expression.  Other flags are not applicable to regular
expresson.
@end table


The result is in the form:

^done,bkptno="<gdb number for this breakpoint>",func="<name of the
function where the breakpoint was inserted>",file="<source file which
contains this function>",line="<source line number within the file>"

Note: this is open to change.  An out-of-band breakpoint instead of part
of the result?
@subsection GDB command
break, tbreak, hbreak, thbreak, rbreak.
@subsection Example
@example
(gdb) 
-break-insert main
^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
(gdb) 
-break-insert -t foo
^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x0001072c",
func="main",file="recursive2.c",line="4",times="0"@},
bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",addr="0x00010774",
func="foo",file="recursive2.c",line="11",times="0"@}@}
(gdb) 
-break-insert -r foo.*
~int foo(int, int);
^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
(gdb) 
@end example

@section -break-list
Displays the list of inserted breakpoints, showing the following fields:
@table @samp
@item Number
Number of the breakpoint
@item Type
Type of the breakpoint: breakpoint or watchpoint
@item Disposition
Should the breakpoint be deleted or disabled when it is hit: keep or nokeep
@item Enabled
Is the breakpoint enabled or no: y or n
@item Address
Memory location at which the breakpoint is set.
@item What
Logical location of the breakpoint, expressed by function name, file name, line number.
@item times
Number of times the breakpoint has been hit.
@end table

If there are no breakpoints or watchpoints, the BreakpointTable field is
an empty list.
@subsection GDB command
info break

@subsection Example 1
@example
(gdb)
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
(gdb)
@end example
@subsection Example 2
@example
(gdb)
-break-list
^done,BreakpointTable=@{@}
(gdb) 
@end example

@section -break-watch [ "-a" | "-r" ]
Create a watchpoint.  With the ``-a'' option it will create an access
watchpoint, i.e. a watchpoints that triggers either on a read or on a
write on the memory location.  With the ``-r'' option, the watchoint
created is a read watchpoint, i.e. it will trigger only when the memory
location os accessed for reading.  Without either of the options, the
watchpoint created is a regular watchpoint, i.e. it will trigger whe the
memory location is accessed for writing.

Note that ``-break-list'' will report a single list of watchpoints and
breakpoints inserted.

@subsection GDB command
watch, awatch, rwatch

@subsection Example 1
Watchpoint on a variable in main().
@example
(gdb) 
-break-watch x
^done,wpt=@{number="2",exp="x"@}
(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",line="5"@}
(gdb) 
@end example
@subsection Example 2
Watchpoint on a variable local to a function. Gdb will stop the program execution 
twice: first for the variable changing value, then for the watchpoint going out of scope.
@example
(gdb) 
-break-watch C
^done,wpt=@{number="5",exp="C"@}
(gdb) 
-exec-continue
^running
^done,reason="watchpoint-trigger",
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=@{@},file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
line="13"@}
(gdb) 
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
frame=@{func="callee3",args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@},
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(gdb) 
@end example

@subsection Example 3
Listing breakpoints and watchpoints, at different points in the program execution.
Note that once the watchpoint goes out of scope, it is deleted.
@example
(gdb) 
-break-watch C
^done,wpt=@{number="2",exp="C"@}
(gdb) 
-break-list   
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
func="callee4",
file="../../../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"@}@}
(gdb) 
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=@{@},
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
func="callee4",
file="../../../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"@}@}
(gdb) 
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
frame=@{func="callee3",args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@},
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(gdb) 
-break-list
^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
(gdb) 
@end example
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Data manipulation

@c REMOVED FROM THE ITNERFACE.
@c @section -data-assign
@c Change the value of a program variable. Plenty of side effects.
@c @subsection GDB command
@c set variable
@c @subsection Example 
@c N.A.

@section -data-disassemble ( -s <start-addr> -e <end-addr> ) | (-f <filename> -l <linenum> [-n <lines> ]] -- <mode>
Where
@table @samp
@item <start-addr>
Is the beginning address (or $pc).
@item <end-addr>
End address.
@item <filename>
Name of the file to disassemble.
@item <linenum>
Line number to disassemble around.
@item <number-of-lines>
specifies the number of disassembly lines to be produced. If it is -1
the whole function will be disassembled, in case no <end> address is
specified.  If <end> is specified as a non-zero value, and
<number-of-lines> is lower that the number of disassembly lines between
<begin> and <end>, we'll display only <number-of-lines> lines, vice
versa if <number-of-lines> is higher than the number of lines between
<begin> and <end>, we'll display only the lines up to <end>.
@item <mode>
can be 0 (only disassembly) or 1 (mixed source and disassembly).
@end table

The output for each instruction is composed of two 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 Flathead, i.e. it is not possible to adjust its format.
@subsection GDB command
N.A. No direct mapping.

@subsection Example 1
Disassemble from the current PC value to PC + 20.

@example
(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 example

@subsection Example 2
Disassemble the whole function main. Line 32 is part of main.
@example
-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"},
[...]
{address="0x0001081c",func-name="main",offset="96",inst="ret "},
{address="0x00010820",func-name="main",offset="100",inst="restore "}}
(gdb)
@end example

@subsection Example 3
Disassemble 3 instruction from the start of main.
@example
(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 example

@subsection Example 4
Disassemble 3 instruction from the start of main in mixed mode.
@example
(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 example

@section -data-evaluate-expression
Evaluate 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.
@subsection GDB command
print, output, gdb_eval
@subsection Example
@example
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 example

@section -data-list-changed-registers
Display a list of the registers that have changed.
@subsection GDB command
gdb_changed_register_list. This is in gdbtk only.
@subsection Example
On a PPC MBX board.
@example
(gdb) 
-exec-continue
^running

(gdb) 
*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
args=@{@},file="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 example

@section -data-list-register-names
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 corresponding to the arguments.
@subsection GDB command
gdb_regnames
@subsection Example
For the PPC MBX board:
@example
(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 example

@section -data-list-register-values
Display the registers contents.  Arguments are the format according to
which the registers contents are to be returned, and a list of numbers
specifying the registers to display. A missing list of number indicates
that the contents of all the registers must be returned.
Allowed formats are:
@itemize @bullet
@item 'x': Hexadecimal
@item 'o': Octal
@item 't': Binary
@item 'd': Decimal
@item 'r': Raw
@item 'N': Natural
@end itemize

@subsection GDB command
info reg, info all-reg  AND/OR gdb_fetch_registers
@subsection Example
For a PPC MBX board. Note, line breaks are for readability only, they
don't appear in the actual output.
@example
(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 example

@section -data-read-memory [ -o <byte-offset> ] [ -- ] <address> <word-format> <word-size> <nr-rows> <nr-cols> [ <aschar> ]
Where
@table @samp
@item <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.
@item <word-format>
The format to be used to print the memory words.  The notation is the
same as for GDB's @code{print} command.
@item <word-size>
The size of each memory word in bytes.
@item <nr-rows>
The number of rows in the output table.
@item <nr-cols>
The number of columns in the output table.
@item <aschar>
If present, indicates that each row should include an ascii dump.  The
value of <aschar> is used as a padding character when a byte is not a
member of the printable ascii character set (@code{<32} or @code{>126}).
@item <byte-offset>
An offset to add to the <address> before fetching memory.
@end table
Display memory contents as a table of <nr-rows> by <nr-cols> words.
Each word being <word-size> bytes.  In total @code{<nr-rows> * <nr-cols>
* <word-size>} bytes are read (returned as @code{total-bytes}.  Should
less then the requested number of bytes be returned by the target, the
missing words are identified using @code{N/A}.  The number of bytes read
from the target is returned in @code{nr-bytes} and the starting address
used to read memory by @code{addr}.

The address of the next/previous page or row is available in
@code{next-row} and @code{prev-row}, @code{next-page} and
@code{prev-page}.
@subsection GDB command
x AND/OR gdb_get_mem AND/OR GDBtk's memory read.
@subsection Example 1
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.
@example
(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 example
@subsection Example 2
Read two bytes of memory starting at address @code{shorts + 64} and
display as a single word formatted in decimal.
@example
(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 example
@subsection Example 3
Read thirty two bytes of memory starting at @code{bytes+16} and format
as eight rows of four columns.  Include a string encoding with @code{x}
used as the non-printable character.
@example
(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 example

@section -display-delete <number>
Delete the display <number>.
@subsection GDB command
delete display 
@subsection Example
N.A.

@section -display-disable <number>
Disable display <number>
@subsection GDB command
disable display
@subsection Example
N.A.

@section -display-enable <number>
Enable display <number>
@subsection GDB command
enable display
@subsection Example
N.A.

@section -display-insert <expression>
Display <expression> every time the program stops.
@subsection GDB command
display
@subsection Example
N.A.

@section -display-list
List the displays. Do not show the current values.
@subsection GDB command
info display
@subsection Example
N.A.

@section -environment-cd <pathdir>
Set GDB's working directory.
@subsection GDB command
cd
@subsection Example
@example
(gdb) 
-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done
(gdb) 
@end example

@section -environment-directory <pathdir>
Add directory <pathdir> to beginning of search path for source files.
@subsection GDB command
dir
@subsection Example
@example
(gdb) 
-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done
(gdb)
@end example 

@section -environment-path @{ <pathdir> @}+
Add directories to beginning of search path for object files.
@subsection GDB command
path
@subsection Example
@example
(gdb) 
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
^done
(gdb)
@end example 

@section -environment-pwd
Show the current working directory
@subsection GDB command
pwd
@subsection Example
@example
(gdb) 
-environment-pwd
~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
^done
(gdb) 
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Program control

@section Program termination
As a result of execution, the inferior program can run to completion, if
it doesn't encouter any breakpoints.  In this case the ouput will
include an exit code, if the program has exited exceptionally.
@subsection Example 1
Program exited normally:
@example
(gdb) 
-exec-run
^running
(gdb)
x = 55
*stopped,reason="exited-normally"
(gdb) 
@end example

@subsection Example 2
Program exited exceptionally:
@example
(gdb) 
-exec-run
^running
(gdb)
x = 55
*stopped,reason="exited",exit-code="01"
(gdb) 
@end example

Another way the program can terminate is if it receives a signal like SIGINT.
@subsection Example 
Program exited with signal (for a more complete example, see the exec-interrupt command).
@example
(gdb) 
*stopped,reason="exited-signalled",signal-name="SIGINT",signal-meaning="Interrupt"
@end example


@section -exec-abort
Kill the inferior running program.

@subsection GDB command
kill

@subsection Example
N.A.

@section -exec-arguments
Set the inferior program arguments, to be used in the next -exec-run.

@subsection GDB command
set args

@subsection Example
Don't have it around.

@section -exec-continue
Asynchronous command. Resumes the execution of the inferior program until
a breakpoint is encountered, or the inferior exits.

@subsection GDB command
continue

@subsection Example
@example
-exec-continue
^running
(gdb) 
@@Hello world
*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
file="hello.c",line="13"@}
(gdb)
@end example

@section -exec-finish
Asynchronous command. Resumes the execution of the inferior program until the
current function is exited. Displays the results returned by the function (???).

@subsection GDB command
finish

@subsection Example 1
Function returning 'void'.
@example
-exec-finish
^running
(gdb) 
@@hello from foo
*stopped,reason="function-finished",frame=@{func="main",args=@{@},
file="hello.c",line="7"@}
(gdb) 
@end example
@subsection Example 2
Function returning other than 'void'. The name of the internal gdb variable storing the
result is printed, and the value itself.
@example
-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",line="14"@},
gdb-result-var="$1",return-value="0"
(gdb) 

@end example
@section -exec-interrupt
Asynchronous command. 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 '^done' output.  If the user is trying to
interrupt a non running program, an error message will be printed.
@subsection GDB command
interrupt

@subsection Example
@example
(gdb) 
111-exec-continue
111^running

(gdb) 
222-exec-interrupt
222^done
(gdb) 
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
(gdb) 

(gdb) 
-exec-interrupt
^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
(gdb) 

@end example

@section -exec-next
Asynchronous command. Resumes execution of the inferior program, stopping
when the beginning of the next source line is reached.

@subsection GDB command
next

@subsection Example
@example
-exec-next
^running
(gdb) 
*stopped,reason="end-stepping-range",line="8",file="hello.c"
(gdb) 
@end example

@section -exec-next-instruction
Asynchronous command. 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.
@subsection GDB command
nexti

@subsection Example
@example
(gdb) 
-exec-next-instruction
^running

(gdb) 
*stopped,reason="end-stepping-range",
addr="0x000100d4",line="5",file="hello.c"
(gdb) 
@end example

@section -exec-return
Makes current function return immediately. Doesn't execute the inferior.
It displays the new current frame.

@subsection GDB command
return

@subsection Example
@example
(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",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",line="18"@}
(gdb)
@end example

@section -exec-run
Asynchronous command. Starts execution of the inferior from the
beginning. The inferior executes until either a breakpoint is
encountered or the program exits.

@subsection GDB command
run

@subsection Example
@example
(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",line="4"@}
(gdb) 
@end example


@section -exec-show-arguments
Print the arguments of the program.
@subsection GDB command
show args
@subsection Example
N.A.

@c @section -exec-signal

@section -exec-step
Asynchronous command. 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.

@subsection GDB command
step

@subsection Example 1
Stepping into a function:
@example
-exec-step
^running
(gdb) 
*stopped,reason="end-stepping-range",frame=@{func="foo",args=@{@{name="a",value="10"@},
@{name="b",value="0"@}@},file="recursive2.c",line="11"@}
(gdb) 
@end example
@subsection Example 2
Regular stepping 
@example
-exec-step
^running
(gdb) 
*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
(gdb) 
@end example

@section -exec-step-instruction
Asynchronous command. Resumes the inferior which executes one machine
instruction. The output, once stop, will vary depend 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.

@subsection GDB command
stepi

@subsection Example
@example
(gdb) 
-exec-step-instruction
^running

(gdb) 
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=@{@},file="try.c",line="10"@}
(gdb) 
-exec-step-instruction
^running

(gdb) 
*stopped,reason="end-stepping-range",
frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
(gdb) 
@end example

@section -exec-until
Asynchronous command. Executes the inferior until the 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 ``location-reached''.
@subsection GDB command
until

@subsection Example
@example
(gdb) 
-exec-until recursive2.c:6
^running
(gdb) 
x = 55
*stopped,reason="location-reached",frame=@{func="main",args=@{@},
file="recursive2.c",line="6"@}
(gdb) 
@end example

@section -file-clear
Is this going away????

@section -file-exec-and-symbols <file>
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, it clears
the executable and symbol information.  If breakpoints are set when
using this command with no arguments, gdb will produce errors. No output
is produced, except a completion notification.
@subsection GDB command
file <file>

@subsection Example
@example
(gdb)
-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)
@end example

@section -file-exec-file <file>
Specify the executable file to be debugged. The symbol table is not read
from this file. If used without argument gdb clears the information
about the executable file.  No output is produced, except a completion
notification.
@subsection GDB command
exec-file <file>

@subsection Example
@example
(gdb) 
-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb) 
@end example

@section -file-list-exec-sections
List the sections of the current executable file.
@subsection GDB command
info file (only part of it), gdb_load_info
@subsection Example
N.A.

@section -file-list-exec-source-files
List the source files for the current executable.
@subsection GDB command
gdb_listfiles (gdbtk).
@subsection Example
N.A.

@section -file-list-shared-libraries
List the shared libraries in the program.
@subsection GDB command
info shared
@subsection Example
N.A.

@section -file-list-symbol-files
List symbol files.
@subsection GDB command
info file (part of it).
@subsection Example
N.A.

@section -file-symbol-file <file>
Read symbol table info from the file specified as argument.  Used
without arguments clears gdb's symbol table info.  No output is
produced, except a completion notification.
@subsection GDB command
symbol-file <file>

@subsection Example
@example
(gdb) 
-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb) 
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Misc GDB commands

@c @section -gdb-complete

@section -gdb-exit

Exit GDB immediately.
@subsection GDB command
Approximately corresponds to 'quit'.

@subsection Example
@example
(gdb) 
-gdb-exit
@end example

@section -gdb-set
Set an internal GDB variable.
IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????

@subsection GDB command
set

@subsection Example
@example
(gdb)
-gdb-set $foo=3
^done
(gdb) 
@end example

@section -gdb-show
Show the current value of a GDB variable.

@subsection GDB command
show

@subsection Example
@example
(gdb) 
-gdb-show annotate
^done,value="0"
(gdb) 
@end example

@c @section -gdb-source

@section -gdb-version
Show version information for gdb. Used in testing mostly.

@subsection GDB command
No equivalent.

@subsection Example
@example
(gdb)
-gdb-version
~GNU gdb 4.18.1 HEADLESS
~Copyright 1998 Free Software Foundation, Inc.
~GDB is free software, covered by the GNU General Public License, and you are
~welcome to change it and/or distribute copies of it under certain conditions.
~Type "show copying" to see the conditions.
~There is absolutely no warranty for GDB.  Type "show warranty" for details.
~This GDB was configured as "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
^done
(gdb) 
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Kod Commands

The Kod commands are not implemented.

@c @section -kod-info

@c @section -kod-list

@c @section -kod-list-object-types

@c @section -kod-show

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Memory Overlay Commands

the memory overlay commands not implemented.

@c @section -overlay-auto

@c @section -overlay-list-mapping-state

@c @section -overlay-list-overlays

@c @section -overlay-map

@c @section -overlay-off

@c @section -overlay-on

@c @section -overlay-unmap

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Signal Handling Commands

Signal handling commands are not implemented.

@c @section -signal-handle

@c @section -signal-list-handle-actions

@c @section -signal-list-signal-types

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Stack manipulation commands

@section -stack-info-frame
Get info on the current frame.
@subsection GDB command
info frame or frame (w/o args).
@subsection Example
N.A.

@section -stack-info-depth [max-depth]
Return the depth of the stack. If the integer argument <max-depth> is specified, do not
count beyond max-depth frames. 
@subsection GDB command
No equivalent.
@subsection Example
For a stack with frame levels 0 through 11:
@example
(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 example

@section -stack-list-arguments <show-values> [ <low-frame> <high-frame> ]
Display a list of the arguments for the frames between low-frame and
high-frame (inclusive). If low-frame and high-frame are not provided, it
will list the arguments for the whole stack. The 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 argumetns are printed.
@subsection GDB command
gdb_get_args (partially).
@subsection Example
@example
(gdb) 
-stack-list-frames
^done,
stack=@{
frame=@{level="0 ",addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
frame=@{level="1 ",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
frame=@{level="2 ",addr="0x0001078c",func="callee2",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
frame=@{level="3 ",addr="0x000107b4",func="callee1",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
frame=@{level="4 ",addr="0x000107e0",func="main",
file="../../../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 example

@c @section -stack-list-exception-handlers

@section -stack-list-frames [ <low-frame> <high-frame> ]
List the frames currently on the stack. For each frame it displays the following info:
@table @samp
@item <level>
The frame number, 0 being the topmost frame, i.e. the innermost function.
@item <addr>
Pc value for that frame.
@item <func>
Function name 
@item <file>
File name of the source fle where the function lives.
@item <line>
Line number corresponding to the pc.
@end table

If invoked without arguments, it 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.

@subsection GDB command
backtrace or where

@subsection Example 1
Whole stack backtrace.

@example
(gdb)
-stack-list-frames
^done,stack=
@{frame=@{level="0 ",addr="0x0001076c",func="foo",file="recursive2.c",line="11"@},
frame=@{level="1 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="2 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="4 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="5 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="6 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="7 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="8 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="9 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="10",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="11",addr="0x00010738",func="main",file="recursive2.c",line="4"@}@}

(gdb) 
@end example

@subsection Example 2
Show frames between low_frame and high_frame.
@example
(gdb) 
-stack-list-frames 3 5
^done,stack=
@{frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="4 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
frame=@{level="5 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@}@}
(gdb) 
@end example
@subsection Example 3
Show one single frame.
@example
(gdb) 
-stack-list-frames 3 3
^done,stack=
@{frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@}@}
(gdb) 
@end example

@section -stack-list-locals <print-values>
Display the local variables names for the current frame.  With an
argument of 0 prints only the names of the variables, with argument of 1
prints also the values.
@subsection GDB command
gdb_get_locals

@subsection Example
@example
(gdb) 
-stack-list-locals 0
^done,locals=@{name="A",name="B",name="C"@}
(gdb) 
-stack-list-locals 1
^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},@{name="C",value="3"@}@}
(gdb) 
@end example

@section -stack-select-frame <framenum>
Change the current frame. Select a different frame on the stack.
@subsection GDB command
frame (part), up, down
AND/OR select-frame,
up-silent, down-silent
@subsection Example
@example
(gdb) 
-stack-select-frame 2
^done
(gdb) 
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Symbol query commands

@section -symbol-info-address <symbol>
Describe where <symbol> is stored.
@subsection GDB command
Info address
@subsection Example
N.A.

@section -symbol-info-file
Show the file for the symbol [NOT SURE]
@subsection GDB command
gdb_filnd_file (gdbtk).
@subsection Example
N.A.

@section -symbol-info-function
Show which function the symbol lives in. [NOT SURE]
@subsection GDB command
gdb_get_function (gdbtk)
@subsection Example
N.A.

@section -symbol-info-line
Core addresses of the code for a source line.
@subsection GDB command
info line , gdb_get_line, gdb_get_file
@subsection Example
N.A.

@section -symbol-info-symbol
Describe what symbol is at location ADDR [NOT SURE]
@subsection GDB command
info symbol
@subsection Example
N.A.

@section -symbol-list-functions
List the functions in the executable.
@subsection GDB command
info functions, gdb_listfunc, gdb_search
@subsection Example
N.A.

@section -symbol-list-types
List all the type names.
@subsection GDB command
info types, gdb_search
@subsection Example
N.A.

@section -symbol-list-variables
List all global and static variable names.
@subsection GDB command
Info variables, gdb_search
@subsection Example
N.A.

@section -symbol-locate
@subsection GDB command
gdb_loc (gdbtk)
@subsection Example
N.A.

@section -symbol-type
Show type of a variable.
@subsection GDB command
ptype, gdb_obj_variable
@subsection Example
N.A.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Target manipulation commands

@section -target-attach
Attach to a process or file outside of GDB.
@subsection GDB command
attach
@subsection Example
N.A.

@section -target-compare-sections
Compare section data on target to the exec file.
@subsection GDB command
compare-sections
@subsection Example
N.A.

@section -target-detach
Disconnect from the remote target.
No output.

@subsection GDB command
detach

@subsection Example
@example
(gdb) 
-target-detach
^done
(gdb) 
@end example

@section -target-download
Loads the executable onto the remote target.
It prints out an update message every half second, which includes the fields:
@itemize @bullet
@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 itemize
Each message is sent as status record.

In addition it prints the name and size of the sections, as they are
downloaded. These messages include the fields:
@itemize @bullet
@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 itemize
At the end a summary is printed.
@subsection GDB command
load

@subsection Example
Note: Each status message appears on a single line. Here the messages
have been broken down, so they can fit into a page.
@example
(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 example

@section -target-exec-status
Provide information on the state of the target. Whether it is running or not, for instance.
@subsection GDB command
No equivalent
@subsection Example
N.A.

@section -target-list-available-targets
List the possible targets to connect to.
@subsection GDB command
help target
@subsection Example
N.A.

@section -target-list-current-targets
What the current target is.
@subsection GDB command
info file (part of it).
@subsection Example
N.A.

@section -target-list-parameters
????
@subsection GDB command
No equivalent
@subsection Example
N.A.

@section -target-select
Connect GDB to the remote target.
It takes two args:

-target-select <type> <parameters>.

Where:

@table @samp
@item <type>
The type of target, for instance async, remote, etc.
@item <parameters>
Device names, host names and the like.
@end table
The output is a connection notification, followed by the address at
which the target program is, in the following form: 
^connected,addr="<address>",func="<function name>",args=@{<arg list>@}

@subsection GDB command
target

@subsection Example
@example
(gdb) 
-target-select async /dev/ttya
^connected,addr="0xfe00a300",func="??",args=@{@}
(gdb) 
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Thread commands

@section -thread-info
@subsection GDB command
@subsection Example

@section -thread-list-all-threads
@subsection GDB command
@subsection Example

@section -thread-list-ids
Produces a list of the currently known gdb thread ids. At the end of the
list it also prints the toal number of such threads.
@subsection GDB command
None equivalent. (Maybe part of info threads).
@subsection Example 1
No threads present, besides the main process.
@example
(gdb) 
-thread-list-ids
^done,thread-ids=@{@},number-of-threads="0"
(gdb) 
@end example
@subsection Example 2
Several threads.
@example
(gdb) 
-thread-list-ids
^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
number-of-threads="3"
(gdb) 
@end example

@section -thread-select <threadnum>
Make <threadnum> the current thread. It prints the number of the new
current thread, and the topmost frame for that thread.
@subsection GDB command
thread
@subsection Example
@example
(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 example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Tracepoint Commands

The tracepoint commands are not implemented.

@c @section -trace-actions

@c @section -trace-delete

@c @section -trace-disable

@c @section -trace-dump

@c @section -trace-enable

@c @section -trace-exists

@c @section -trace-find

@c @section -trace-frame-number

@c @section -trace-info

@c @section -trace-insert

@c @section -trace-list

@c @section -trace-pass-count

@c @section -trace-save

@c @section -trace-start

@c @section -trace-stop


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@chapter Variable Objects

@section Motivation

For the implementation of a variable debugger window (locals, watched
expressions, etc.), we are proposing the adaptation of the existent code
used by Insight.

The two main reason for that are:

@enumerate 1
@item
It has been proven in practice (it is already on it's second generation)
@item
It will shorten development time (needless to say how important it is
now)
@end enumerate

The original interface was designed to be used by Tcl code, so it was
slightly changed so it can be used through flathead.  This document
describes the flathead operations that will be available and gives some
hints about its use.

@emph{Note}: In addition to the set of operations described here, we
expect the GUI implementation of a variable window to require, at least,
the following operations:
@itemize bullet
@item -gdb-show output-radix
@item -stack-list-arguments
@item -stack-list-locals
@item -stack-select-frame
@end itemize

@section Introduction

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 struct type variable is the root
and the children will represent the struct members.  If a children is
itself of a complex type, it will also have children of its own.
Appropriate language differences are handled for C, C++ 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 the a default format automatically chosen
based on the variable type (like decimal for int, hex for pointers,
etc.).

The following is the complete set of flathead operations defined to
access this functionality:

@multitable @columnfractions .3 .6
@item @strong{Operation}
@tab @strong{Description}

@item -var-create
@tab create a variable object
@item -var-delete
@tab delete the variable object and its children
@item -var-set-format
@tab set the display format of this variable
@item -var-show-format
@tab show the display format of this variable
@item -var-info-num-children
@tab tells how many children this object has
@item -var-list-children
@tab return a list of the object's children
@item -var-info-type
@tab show the type of this variable object
@item -var-info-expression
@tab print what this variable object represents
@item -var-show-attributes
@tab is this variable editable? does it exist here?
@item -var-evaluate-expression
@tab get the value of this variable
@item -var-assign
@tab set the value of this variable
@item -var-update
@tab update the variable and its children
@end multitable

In the next section we describe each operation in detail and suggest how
it can be used.


@section Operations Description And Use

@subsection -var-create @{<name> | '-'@} @{<frame-addr> | '*'@} <expression>

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 <name> parameter is the string by which the object can be
referenced.  It must be unique.  If '-' is specified, the varobj system
will generate a string "varNNNNNN" automatically.  It will be unique
provided that one does not specify <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.  A '*' indicates that the current frame should be used.

Expression is any expression valid on the current language set (must not
begin with '*') or: *<addr> - The address of a memory cell
*<addr>-<addr> - An memory address range (TBD) $<regname> - A CPU
register
  
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
gdb CLI.

name="<name>",numchild="N",type="<type>"

@subsection -var-delete <name>

Deletes a previously created variable object and all of it's children.

Returns an error if the object <name> is not found.

@subsection -var-set-format <name> <format-spec>

Sets the output format for the value of the object.

<format-spec> = @{binary | decimal | hexadecimal | octal | natural@}

@subsection -var-show-format <name>

Returns the format used to display the value of the object.

format="<format-spec>"

@subsection -var-info-num-children <name>

Returns the number of children of a variable object.

numchild="N"

@subsection -var-list-children <name>

Returns a list of the children of the specified variable object.

numchild="N",children=@{@{name="<name>",numchild="N",type="<type>"@},(repeats N times)@}

@subsection -var-info-type <name>

Returns the type of the specified variable.  The type is returned as a
string in the same format as it is output by gdb's CLI.

type="<type>"

@subsection -var-info-expression <name>

Returns what is represented by the specified variable object.

lang="<lang-spec>",exp="<expression>"

where <lang-spec> = @{"C" | "C++" | "Java"@}

@subsection -var-show-attributes <name>

List attributes of the specified variable object.

status="<attr>[,<attr>]*"

where <attr> = @{ @{ editable | noneditable @} | TBD @}

@subsection -var-evaluate-expression <name>

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.

value="<value>"

@subsection -var-assign <name> <expression>

Assigns a new value for the variable object specified.  The object must
be "editable".

@subsection -var-update @{<name> | '*'@}

Update the value of the variable object by evaluating its expression
after fetching all the new values from memory or registers.  A '*'
causes all existing variable objects to be updated.


@c%%%%%%%%%%%%%%%%%%%%%%%%%%%% APPENDIX %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@appendix Proposed v2.0 Output Syntax

This appendix is not part of the MI specification.  It is provided as a
discussion point.

The output from GDB/MI consists of zero or more out-of-band records
optionally followed by a single result record.  The result record being
for the most recent command input.  The sequence being terminated by
``(gdb)''.

Asynchronous GDB/MI output is similar.

Each output record directly associated with an input command is prefixed
by the input commands @code{<token>}.

@table @code
@item <output> @expansion{}
@{ <out-of-band-record> @} [ <result-record> ] ``(gdb)'' <nl> 

@item <result-record> @expansion{}
[ <token> ] ``^'' <result-class> @{ ``,'' <result> @} <nl>

@item <out-of-band-record> @expansion{}
<async-record> | <stream-record>

@item <async-record> @expansion{}
<exec-async-output> | <status-async-output> | <notify-async-output>

@item <exec-async-output> @expansion{}
[ <token> ] ``*'' <async-output>

@item <status-async-output> @expansion{}
[ <token> ] ``+'' <async-output>

@item <notify-async-output> @expansion{}
[ <token> ] ``='' <async-output>

@item <async-output> @expansion{}
<async-class> @{ ``,'' <result> @} <nl> 

@item <result-class> @expansion{} 
``done'' | ``running'' | ``connected'' | ``error'' | ``exit''

@item <async-class> @expansion{} 
``stopped'' | @emph{others depending on need as still in development}

@item <result> @expansion{}
<string> ``='' <value>

@item <value> @expansion{}
<c-string> | <tupple> | <list>

@item <tupple> @expansion{}
``@{@}'' | ``@{'' <result> @{ ``,'' <result> @} ``@}''

@item <list> @expansion{}
``[]'' | ``['' <value> @{ ``,'' <value> @} ``]''

@item <string> @expansion{}
@emph{[-A-Za-z\.0-9_]*}

@item <c-string> @expansion{}
@emph{See the input specification}

@item <stream-record> @expansion{}
<console-stream-output> | <target-stream-output> | <log-stream-output>

@item <console-stream-output> @expansion{}
``~'' <c-string>

@item <target-stream-output> @expansion{}
``@@'' <c-string>

@item <log-stream-output> @expansion{}
``&'' <c-string>

@item <nl> @expansion{}
CR | CR-LF

@item <token> @expansion{}
``any sequence of digits''

@end table

In addition, the following are still being developed.

@table @code

@item <query>
This action is currently undefined.

@end table

Notes:

@itemize @bullet

@item
All output sequences end in a single line containing a period.

@item
The @code{<token>} is from the corresponding request.  If an execution
command is interrupted by the -exec-interrupt command, the token
associated with the `*stopped' message is the one of the original
execution command, not the one of the interrupt-command.

@item
<status-async-output> contains on-going status information about the progress
of a slow operation.  It can be discarded. All status output is prefixed by
the prefix `+'.

@item
<exec-async-output> contains asynchronous state change on the target
(stopped, started, disappeared). All async output is prefixed by
the prefix `*'.

@item
<notify-async-output> contains supplementary information that the client should
handle (new breakpoint information). All notify output is prefixed by
the prefix `='.

@item
<console-stream-output> is output that should be displayed as is in the
console.  It is the textual response to a CLI command. All the console
output is prefixed by the prefix ``~''.

@item
<target-stream-output> is the output produced by the target program.
All the target output is prefixed by the prefix ``@@''.

@item
<log-stream-output> is output text coming from GDB's internals, for
instance messages that should be displayed as part of an error log.  All
the log output is prefixed by the prefix ``&''.

@end itemize


@c Local variables:
@c change-log-default-name: "ChangeLog-mi"
@c End:
@bye