Add mi/ and testsuite/gdb.mi/ subdirectories.

Add --enable-gdbmi option to configury.
Add mi rules to Makefile.in
Add mi conditional output to event-top.c infrun.c main.c top.c.
Add -i=mi option.

1 files changed, 2513 insertions, 0 deletions

diff --git a/gdb/mi/gdbmi.texinfo b/gdb/mi/gdbmi.texinfo
new file mode 100644
index 0000000..ec2590e
--- /dev/null
+++ b/gdb/mi/gdbmi.texinfo
@@ -0,0 +1,2513 @@
+\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 <begin> <end> <mode> <number-of-lines>
+Where
+@table @samp
+@item <begin>
+Is a function name or an address (or $pc)
+@item <end>
+can be 0 (in which case the enclosing function will be disassembled), or
+an address.
+@item <mode>
+can be 0 (only disassembly) or 1 (mixed source and disassembly).
+@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>.
+@end table
+
+The output for each instruction is composed of two fields:
+@itemize @bullet
+@item Address
+@item Instruction
+@end itemize
+Note that whatever included in those fields, is not manipulated
+directely by Flathead, i.e. it is not possible to adjust their format.
+@subsection GDB command
+N.A. No direct mapping.
+
+@subsection Example 1
+@example
+(gdb)
+-data-disassemble main 0 0 -1
+^done,asm_insns=@{
+@{address="0x100b8 <main>",inst=" stwu r1,-16(r1)"@},
+@{address="0x100bc <main+4>",inst="mflr r0"@},
+@{address="0x100c0 <main+8>",inst=" stw r31,12(r1)"@},
+@{address="0x100c4 <main+12>",inst=" stw r0,20(r1)"@},
+@{address="0x100c8 <main+16>",inst=" mr r31,r1"@},
+@{address="0x100cc <main+20>",inst=" bl0x1013c <__eabi>"@},
+@{address="0x100d0 <main+24>",inst=" lis r9,2"@},
+@{address="0x100d4 <main+28>",inst=" addi r3,r9,-25680"@},
+@{address="0x100d8 <main+32>",inst=" bl 0x10fc8 <printf>"@},
+@{address="0x100dc <main+36>",inst=" bl 0x10100 <foo>"@},
+@{address="0x100e0 <main+40>",inst=" li r3,0"@},
+@{address="0x100e4 <main+44>",inst=" b 0x100e8 <main+48>"@},
+@{address="0x100e8 <main+48>",inst=" lwz r11,0(r1)"@},
+@{address="0x100ec <main+52>",inst=" lwz r0,4(r11)"@},
+@{address="0x100f0 <main+56>",inst=" mtlr r0"@},
+@{address="0x100f4 <main+60>",inst=" lwz r31,-4(r11)"@},
+@{address="0x100f8 <main+64>",inst=" mr r1,r11"@},
+@{address="0x100fc <main+68>",inst=" blr"@}
+(gdb) 
+@end example
+
+@subsection Example 2
+@example
+(gdb)
+-data-disassemble main 0 0 3
+^done,asm_insns=@{
+@{address=" 0x100b8 <main>",inst=" stwu r1,-16(r1)"@},
+@{address=" 0x100bc <main+4>",inst="mflr r0"@},
+@{address=" 0x100c0 <main+8>",inst=" stw r31,12(r1)"@}
+(gdb) 
+@end example
+
+@subsection Example 3
+@example
+(gdb) 
+-data-disassemble foo 0 1 -1
+^done,asm_insns=@{src_and_asm_line=@{line="11",file="hello.c",
+line_asm_insn=@{
+@{address="    0x10100 <foo>",inst="      stwu        r1,-16(r1)"@},
+@{address="    0x10104 <foo+4>",inst="           mflrr0"@},
+@{address="    0x10108 <foo+8>",inst="           stw r31,12(r1)"@},
+@{address="    0x1010c <foo+12>",inst="         stw  r0,20(r1)"@},
+@{address="    0x10110 <foo+16>",inst="           mr  r31,r1"@}@}@},
+src_and_asm_line=@{line="12",file="hello.c",
+line_asm_insn=@{
+@{address="    0x10114 <foo+20>",inst="          lisr9,2"@},
+@{address="    0x10118 <foo+24>",inst="         addi        r3,r9,-25664"@},
+@{address="    0x1011c <foo+28>",inst="        bl  0x10fc8 <printf>"@}@}@},
+src_and_asm_line=@{line="14",file="hello.c",
+line_asm_insn=@{
+@{address="    0x10120 <foo+32>",inst="        lwz r11,0(r1)"@},
+@{address="    0x10124 <foo+36>",inst="           lwz r0,4(r11)"@},
+@{address="    0x10128 <foo+40>",inst="           mtlr        r0"@},
+@{address="    0x1012c <foo+44>",inst="          lwz r31,-4(r11)"@},
+@{address="    0x10130 <foo+48>",inst="         mr r1,r11"@},
+@{address="    0x10134 <foo+52>",inst="       blr"@}@}@}@}
+(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