@c !!set GDB manual's revision date
@set DATE December 2001
-@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
+@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
@end titlepage
@page
-@ifinfo
+@ifnottex
@node Top, Summary, (dir), (dir)
@top Debugging with @value{GDBN}
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
+* Macros:: Preprocessor Macros
* Tracepoints:: Debugging remote targets non-intrusively
* Overlays:: Debugging programs that use overlays
* Altering:: Altering execution
* GDB Files:: @value{GDBN} files
* Targets:: Specifying a debugging target
+* Remote Debugging:: Debugging remote programs
* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
* Using History Interactively:: Using History Interactively
* Installing GDB:: Installing GDB
* Maintenance Commands:: Maintenance Commands
+* Remote Protocol:: GDB Remote Serial Protocol
+* Copying:: GNU General Public License says
+ how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
* Index:: Index
@end menu
-@end ifinfo
-
-@c the replication sucks, but this avoids a texinfo 3.12 lameness
-
-@ifhtml
-@node Top
-
-@top Debugging with @value{GDBN}
-
-This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-
-This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
-@value{GDBVN}.
-
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
-
-@menu
-* Summary:: Summary of @value{GDBN}
-* Sample Session:: A sample @value{GDBN} session
-
-* Invocation:: Getting in and out of @value{GDBN}
-* Commands:: @value{GDBN} commands
-* Running:: Running programs under @value{GDBN}
-* Stopping:: Stopping and continuing
-* Stack:: Examining the stack
-* Source:: Examining source files
-* Data:: Examining data
-* Tracepoints:: Debugging remote targets non-intrusively
-* Overlays:: Debugging programs that use overlays
-
-* Languages:: Using @value{GDBN} with different languages
-
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Configurations:: Configuration-specific information
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* TUI:: @value{GDBN} Text User Interface
-* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
-* Annotations:: @value{GDBN}'s annotation interface.
-* GDB/MI:: @value{GDBN}'s Machine Interface.
-
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print @value{GDBN} documentation
-
-* Command Line Editing:: Command Line Editing
-* Using History Interactively:: Using History Interactively
-* Installing GDB:: Installing GDB
-* Maintenance Commands:: Maintenance Commands
-* GNU Free Documentation License:: The license for this documentation
-* Index:: Index
-@end menu
-
-@end ifhtml
+@end ifnottex
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@iftex
@contents
-@end iftex
@node Summary
@unnumbered Summary of @value{GDBN}
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
Zuhn have made contributions both large and small.
+Jim Blandy added support for preprocessor macros, while working for Red
+Hat.
@node Sample Session
@chapter A Sample @value{GDBN} Session
The most usual way to start @value{GDBN} is with one argument,
specifying an executable program:
-@example
+@smallexample
@value{GDBP} @var{program}
-@end example
+@end smallexample
@noindent
You can also start with both an executable program and a core file
specified:
-@example
+@smallexample
@value{GDBP} @var{program} @var{core}
-@end example
+@end smallexample
You can, instead, specify a process ID as a second argument, if you want
to debug a running process:
-@example
+@smallexample
@value{GDBP} @var{program} 1234
-@end example
+@end smallexample
@noindent
would attach @value{GDBN} to process @code{1234} (unless you also have a file
You can optionally have @code{@value{GDBP}} pass any arguments after the
executable file to the inferior using @code{--args}. This option stops
option processing.
-@example
+@smallexample
gdb --args gcc -O2 -c foo.c
-@end example
+@end smallexample
This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
@noindent
Type
-@example
+@smallexample
@value{GDBP} -help
-@end example
+@end smallexample
@noindent
to display all available options and briefly describe their use
on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
but build a @file{.syms} file for future use is:
-@example
+@smallexample
gdb -batch -nx -mapped -readnow programname
-@end example
+@end smallexample
@node Mode Options
@subsection Choosing modes
example to download and run a program on another computer; in order to
make this more useful, the message
-@example
+@smallexample
Program exited normally.
-@end example
+@end smallexample
@noindent
(which is ordinarily issued whenever a program running under
@c complete accuracy in these examples; space introduced for clarity.
@c If texinfo enhancements make it unnecessary, it would be nice to
@c replace " @key" by "@key" in the following...
-@example
+@smallexample
(@value{GDBP}) info bre @key{TAB}
-@end example
+@end smallexample
@noindent
@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
the only @code{info} subcommand beginning with @samp{bre}:
-@example
+@smallexample
(@value{GDBP}) info breakpoints
-@end example
+@end smallexample
@noindent
You can either press @key{RET} at this point, to run the @code{info
function names in your program that begin with those characters, for
example:
-@example
+@smallexample
(@value{GDBP}) b make_ @key{TAB}
@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
make_a_section_from_file make_environ
make_cleanup make_reference_type
make_command make_symbol_completion_list
(@value{GDBP}) b make_
-@end example
+@end smallexample
@noindent
After displaying the available possibilities, @value{GDBN} copies your
@value{GDBN} that it may need to consider more information than usual
when you press @key{TAB} or @kbd{M-?} to request word completion:
-@example
+@smallexample
(@value{GDBP}) b 'bubble( @kbd{M-?}
bubble(double,double) bubble(int,int)
(@value{GDBP}) b 'bubble(
-@end example
+@end smallexample
In some cases, @value{GDBN} can tell that completing a name requires using
quotes. When this happens, @value{GDBN} inserts the quote for you (while
completing as much as it can) if you do not type the quote in the first
place:
-@example
+@smallexample
(@value{GDBP}) b bub @key{TAB}
@exdent @value{GDBN} alters your input line to the following, and rings a bell:
(@value{GDBP}) b 'bubble(
-@end example
+@end smallexample
@noindent
In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
To request debugging information, specify the @samp{-g} option when you run
the compiler.
+Most compilers do not include information about preprocessor macros in
+the debugging information if you specify the @option{-g} flag alone,
+because this information is rather large. Version 3.1 of @value{NGCC},
+the @sc{gnu} C compiler, provides macro information if you specify the
+options @option{-gdwarf-2} and @option{-g3}; the former option requests
+debugging information in the Dwarf 2 format, and the latter requests
+``extra information''. In the future, we hope to find more compact ways
+to represent macro information, so that it can be included with
+@option{-g} alone.
+
Many C compilers are unable to handle the @samp{-g} and @samp{-O}
options together. Using those compilers, you cannot generate optimized
executables containing debugging information.
For example, this command:
-@example
+@smallexample
set env USER = foo
-@end example
+@end smallexample
@noindent
tells the debugged program, when subsequently run, that its user is named
You can redirect your program's input and/or output using shell
redirection with the @code{run} command. For example,
-@example
+@smallexample
run > outfile
-@end example
+@end smallexample
@noindent
starts your program, diverting its output to the file @file{outfile}.
commands. It also resets the controlling terminal for the child
process, for future @code{run} commands. For example,
-@example
+@smallexample
tty /dev/ttyb
-@end example
+@end smallexample
@noindent
directs that processes started with subsequent @code{run} commands
whose form varies depending on the particular system. For example, on
LynxOS, you might see
-@example
+@smallexample
[New process 35 thread 27]
-@end example
+@end smallexample
@noindent
when @value{GDBN} notices a new thread. In contrast, on an SGI system,
@c FIXME!! (1) Does the [New...] message appear even for the very first
@c thread of a program, or does it only appear for the
-@c second---i.e., when it becomes obvious we have a multithread
+@c second---i.e.@: when it becomes obvious we have a multithread
@c program?
@c (2) *Is* there necessarily a first thread always? Or do some
@c multithread systems permit starting a program with multiple
whose form varies depending on the particular system. For example, on
HP-UX, you see
-@example
+@smallexample
[New thread 2 (system thread 26594)]
-@end example
+@end smallexample
@noindent
when @value{GDBN} notices a new thread.
@end table
@c end table here to get a little more width for example
-@example
+@smallexample
(@value{GDBP}) info threads
* 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
at quicksort.c:137
from /usr/lib/libc.2
1 system thread 27905 0x7b003498 in _brk () \@*
from /usr/lib/libc.2
-@end example
+@end smallexample
@table @code
@kindex thread @var{threadno}
When you issue the @code{watch} command, @value{GDBN} reports
-@example
+@smallexample
Hardware watchpoint @var{num}: @var{expr}
-@end example
+@end smallexample
@noindent
if it was able to set a hardware watchpoint.
raised by calling a library function named @code{__raise_exception}
which has the following ANSI C interface:
-@example
+@smallexample
/* @var{addr} is where the exception identifier is stored.
@var{id} is the exception identifier. */
void __raise_exception (void **addr, void *id);
-@end example
+@end smallexample
@noindent
To make the debugger catch all exceptions before any stack
symbols not referenced in the context of the breakpoint, @value{GDBN}
prints an error message:
-@example
+@smallexample
No symbol "foo" in current context.
-@end example
+@end smallexample
@noindent
@value{GDBN} does
For example, here is how you could use breakpoint commands to print the
value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
-@example
+@smallexample
break foo if x>0
commands
silent
printf "x is %d\n",x
cont
end
-@end example
+@end smallexample
One application for breakpoint commands is to compensate for one bug so
you can test for another. Put a breakpoint just after the erroneous line
so that your program does not stop, and start with the @code{silent}
command so that no output is produced. Here is an example:
-@example
+@smallexample
break 403
commands
silent
set x = y + 4
cont
end
-@end example
+@end smallexample
@node Breakpoint Menus
@subsection Breakpoint menus
attempting to run or continue a program with a breakpoint causes
@value{GDBN} to print an error message:
-@example
+@smallexample
Cannot insert breakpoints.
The same program may be running in another process.
-@end example
+@end smallexample
When this happens, you have three ways to proceed:
(@code{frame}) command shows that execution is stopped at line
@code{206}; yet when we use @code{until}, we get to line @code{195}:
-@example
+@smallexample
(@value{GDBP}) f
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
206 expand_input();
(@value{GDBP}) until
195 for ( ; argc > 0; NEXTARG) @{
-@end example
+@end smallexample
This happened because, for execution efficiency, the compiler had
generated code for the loop closure test at the end, rather than the
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
without stack frames. (For example, the @value{GCC} option
-@example
+@smallexample
@samp{-fomit-frame-pointer}
-@end example
+@end smallexample
generates functions without a frame.)
This is occasionally done with heavily used library functions to save
the frame setup time. @value{GDBN} has limited facilities for dealing
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
* Memory Region Attributes:: Memory region attributes
+* Dump/Restore Files:: Copy between memory and a file
@end menu
@node Expressions
@code{print} and many other @value{GDBN} commands accept an expression and
compute its value. Any kind of constant, variable or operator defined
by the programming language you are using is valid in an expression in
-@value{GDBN}. This includes conditional expressions, function calls, casts
-and string constants. It unfortunately does not include symbols defined
-by preprocessor @code{#define} commands.
+@value{GDBN}. This includes conditional expressions, function calls,
+casts, and string constants. It also includes preprocessor macros, if
+you compiled your program to include this information; see
+@ref{Compilation}.
@value{GDBN} supports array constants in expressions input by
the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
@noindent This means that in the function
-@example
+@smallexample
foo (a)
int a;
@{
bar (b);
@}
@}
-@end example
+@end smallexample
@noindent
you can examine and use the variable @code{a} whenever your program is
@c info cannot cope with a :: index entry, but why deprive hard copy readers?
@cindex @code{::}, context for variables/functions
@end iftex
-@example
+@smallexample
@var{file}::@var{variable}
@var{function}::@var{variable}
-@end example
+@end smallexample
@noindent
Here @var{file} or @var{function} is the name of the context for the
make sure @value{GDBN} parses the file name as a single word---for example,
to print a global value of @code{x} defined in @file{f2.c}:
-@example
+@smallexample
(@value{GDBP}) p 'f2.c'::x
-@end example
+@end smallexample
@cindex C@t{++} scope resolution
This use of @samp{::} is very rarely in conflict with the very similar
might not be able to display values for such local variables. If that
happens, @value{GDBN} will print a message like this:
-@example
+@smallexample
No symbol "foo" in current context.
-@end example
+@end smallexample
To solve such problems, either recompile without optimizations, or use a
different debug info format, if the compiler supports several such
following those that hold the first element, and so on. Here is an
example. If a program says
-@example
+@smallexample
int *array = (int *) malloc (len * sizeof (int));
-@end example
+@end smallexample
@noindent
you can print the contents of @code{array} with
-@example
+@smallexample
p *array@@len
-@end example
+@end smallexample
The left operand of @samp{@@} must reside in memory. Array values made
with @samp{@@} in this way behave just like other arrays in terms of
Another way to create an artificial array is to use a cast.
This re-interprets a value as if it were an array.
The value need not be in memory:
-@example
+@smallexample
(@value{GDBP}) p/x (short[2])0x12345678
$1 = @{0x1234, 0x5678@}
-@end example
+@end smallexample
As a convenience, if you leave the array length out (as in
@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
-@example
+@smallexample
(@value{GDBP}) p/x (short[])0x12345678
$2 = @{0x1234, 0x5678@}
-@end example
+@end smallexample
Sometimes the artificial array mechanism is not quite enough; in
moderately complex data structures, the elements of interest may not
structures, and you are interested in the values of a field @code{fv}
in each structure. Here is an example of what you might type:
-@example
+@smallexample
set $i = 0
p dtab[$i++]->fv
@key{RET}
@key{RET}
@dots{}
-@end example
+@end smallexample
@node Output Formats
@section Output formats
the nearest preceding symbol. You can use this format used to discover
where (in what function) an unknown address is located:
-@example
+@smallexample
(@value{GDBP}) p/a 0x54320
$3 = 0x54320 <_initialize_vx+396>
-@end example
+@end smallexample
@noindent
The command @code{info symbol 0x54320} yields similar results.
For example, to print the program counter in hex (@pxref{Registers}), type
-@example
+@smallexample
p/x $pc
-@end example
+@end smallexample
@noindent
Note that no space is required before the slash; this is because command
to remove an expression from the list, you specify that number.
The automatic display looks like this:
-@example
+@smallexample
2: foo = 38
3: bar[5] = (struct hack *) 0x3804
-@end example
+@end smallexample
@noindent
This display shows item numbers, expressions and their current values. As with
For example, here @value{GDBN} shows that a variable @code{ptt} points
at another variable @code{t}, defined in @file{hi2.c}:
-@example
+@smallexample
(@value{GDBP}) set print symbol-filename on
(@value{GDBP}) p/a ptt
$4 = 0xe008 <t in hi2.c>
-@end example
+@end smallexample
@quotation
@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
For example, suppose you have just printed a pointer to a structure and
want to see the contents of the structure. It suffices to type
-@example
+@smallexample
p *$
-@end example
+@end smallexample
If you have a chain of structures where the component @code{next} points
to the next one, you can print the contents of the next one with this:
-@example
+@smallexample
p *$.next
-@end example
+@end smallexample
@noindent
You can print successive links in the chain by repeating this
Note that the history records values, not expressions. If the value of
@code{x} is 4 and you type these commands:
-@example
+@smallexample
print x
set x=5
-@end example
+@end smallexample
@noindent
then the value recorded in the value history by the @code{print} command
expression, just as you would set a variable in your program.
For example:
-@example
+@smallexample
set $foo = *object_ptr
-@end example
+@end smallexample
@noindent
would save in @code{$foo} the value contained in the object pointed to by
incremented or a pointer to be advanced. For example, to print
a field from successive elements of an array of structures:
-@example
+@smallexample
set $i = 0
print bar[$i++]->contents
-@end example
+@end smallexample
@noindent
Repeat that command by typing @key{RET}.
register that contains the processor status. For example,
you could print the program counter in hex with
-@example
+@smallexample
p/x $pc
-@end example
+@end smallexample
@noindent
or print the instruction to be executed next with
-@example
+@smallexample
x/i $pc
-@end example
+@end smallexample
@noindent
or add four to the stack pointer@footnote{This is a way of removing
regardless of machine architecture, use @code{return};
see @ref{Returning, ,Returning from a function}.} with
-@example
+@smallexample
set $sp += 4
-@end example
+@end smallexample
Whenever possible, these four standard register names are available on
your machine even though the machine has different canonical mnemonics,
@end table
@node Memory Region Attributes
-@section Memory Region Attributes
+@section Memory region attributes
@cindex memory region attributes
@dfn{Memory region attributes} allow you to describe special handling
@table @code
@kindex mem
-@item mem @var{address1} @var{address1} @var{attributes}@dots{}
-Define memory region bounded by @var{address1} and @var{address2}
-with attributes @var{attributes}@dots{}.
+@item mem @var{lower} @var{upper} @var{attributes}@dots{}
+Define memory region bounded by @var{lower} and @var{upper} with
+attributes @var{attributes}@dots{}. Note that @var{upper} == 0 is a
+special case: it is treated as the the target's maximum memory address.
+(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
@kindex delete mem
@item delete mem @var{nums}@dots{}
-Remove memory region numbers @var{nums}.
+Remove memory regions @var{nums}@dots{}.
@kindex disable mem
@item disable mem @var{nums}@dots{}
-Disable memory region numbers @var{nums}.
+Disable memory regions @var{nums}@dots{}.
A disabled memory region is not forgotten.
It may be enabled again later.
@kindex enable mem
@item enable mem @var{nums}@dots{}
-Enable memory region numbers @var{nums}.
+Enable memory regions @var{nums}@dots{}.
@kindex info mem
@item info mem
@item wo
Memory is write only.
@item rw
-Memory is read/write (default).
+Memory is read/write. This is the default.
@end table
@subsubsection Memory Access Size
@table @code
@item cache
Enable @value{GDBN} to cache target memory.
-@item nocache (default)
-Disable @value{GDBN} from caching target memory.
+@item nocache
+Disable @value{GDBN} from caching target memory. This is the default.
@end table
@c @subsubsection Memory Write Verification
@c @item noverify (default)
@c @end table
+@node Dump/Restore Files
+@section Copy between memory and a file
+@cindex dump/restore files
+@cindex append data to a file
+@cindex dump data to a file
+@cindex restore data from a file
+@kindex dump
+@kindex append
+@kindex restore
+
+The commands @code{dump}, @code{append}, and @code{restore} are used
+for copying data between target memory and a file. Data is written
+into a file using @code{dump} or @code{append}, and restored from a
+file into memory by using @code{restore}. Files may be binary, srec,
+intel hex, or tekhex (but only binary files can be appended).
+
+@table @code
+@kindex dump binary
+@kindex append binary
+@item dump binary memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+raw binary format file @var{filename}.
+
+@item append binary memory @var{filename} @var{start_addr} @var{end_addr}
+Append contents of memory from @var{start_addr} to @var{end_addr} to
+raw binary format file @var{filename}.
+
+@item dump binary value @var{filename} @var{expression}
+Dump value of @var{expression} into raw binary format file @var{filename}.
+
+@item append binary memory @var{filename} @var{expression}
+Append value of @var{expression} to raw binary format file @var{filename}.
+
+@kindex dump ihex
+@item dump ihex memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+intel hex format file @var{filename}.
+
+@item dump ihex value @var{filename} @var{expression}
+Dump value of @var{expression} into intel hex format file @var{filename}.
+
+@kindex dump srec
+@item dump srec memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+srec format file @var{filename}.
+
+@item dump srec value @var{filename} @var{expression}
+Dump value of @var{expression} into srec format file @var{filename}.
+
+@kindex dump tekhex
+@item dump tekhex memory @var{filename} @var{start_addr} @var{end_addr}
+Dump contents of memory from @var{start_addr} to @var{end_addr} into
+tekhex format file @var{filename}.
+
+@item dump tekhex value @var{filename} @var{expression}
+Dump value of @var{expression} into tekhex format file @var{filename}.
+
+@item restore @var{filename} @var{[binary]} @var{bias} @var{start} @var{end}
+Restore the contents of file @var{filename} into memory. The @code{restore}
+command can automatically recognize any known bfd file format, except for
+raw binary. To restore a raw binary file you must use the optional argument
+@var{binary} after the filename.
+
+If @var{bias} is non-zero, its value will be added to the addresses
+contained in the file. Binary files always start at address zero, so
+they will be restored at address @var{bias}. Other bfd files have
+a built-in location; they will be restored at offset @var{bias}
+from that location.
+
+If @var{start} and/or @var{end} are non-zero, then only data between
+file offset @var{start} and file offset @var{end} will be restored.
+These offsets are relative to the addresses in the file, before
+the @var{bias} argument is applied.
+
+@end table
+
+@node Macros
+@chapter C Preprocessor Macros
+
+Some languages, such as C and C++, provide a way to define and invoke
+``preprocessor macros'' which expand into strings of tokens.
+@value{GDBN} can evaluate expressions containing macro invocations, show
+the result of macro expansion, and show a macro's definition, including
+where it was defined.
+
+You may need to compile your program specially to provide @value{GDBN}
+with information about preprocessor macros. Most compilers do not
+include macros in their debugging information, even when you compile
+with the @option{-g} flag. @xref{Compilation}.
+
+A program may define a macro at one point, remove that definition later,
+and then provide a different definition after that. Thus, at different
+points in the program, a macro may have different definitions, or have
+no definition at all. If there is a current stack frame, @value{GDBN}
+uses the macros in scope at that frame's source code line. Otherwise,
+@value{GDBN} uses the macros in scope at the current listing location;
+see @ref{List}.
+
+At the moment, @value{GDBN} does not support the @code{##}
+token-splicing operator, the @code{#} stringification operator, or
+variable-arity macros.
+
+Whenever @value{GDBN} evaluates an expression, it always expands any
+macro invocations present in the expression. @value{GDBN} also provides
+the following commands for working with macros explicitly.
+
+@table @code
+
+@kindex macro expand
+@cindex macro expansion, showing the results of preprocessor
+@cindex preprocessor macro expansion, showing the results of
+@cindex expanding preprocessor macros
+@item macro expand @var{expression}
+@itemx macro exp @var{expression}
+Show the results of expanding all preprocessor macro invocations in
+@var{expression}. Since @value{GDBN} simply expands macros, but does
+not parse the result, @var{expression} need not be a valid expression;
+it can be any string of tokens.
+
+@kindex macro expand-once
+@item macro expand-once @var{expression}
+@itemx macro exp1 @var{expression}
+@i{(This command is not yet implemented.)} Show the results of
+expanding those preprocessor macro invocations that appear explicitly in
+@var{expression}. Macro invocations appearing in that expansion are
+left unchanged. This command allows you to see the effect of a
+particular macro more clearly, without being confused by further
+expansions. Since @value{GDBN} simply expands macros, but does not
+parse the result, @var{expression} need not be a valid expression; it
+can be any string of tokens.
+
+@kindex info macro
+@cindex macro definition, showing
+@cindex definition, showing a macro's
+@item info macro @var{macro}
+Show the definition of the macro named @var{macro}, and describe the
+source location where that definition was established.
+
+@kindex macro define
+@cindex user-defined macros
+@cindex defining macros interactively
+@cindex macros, user-defined
+@item macro define @var{macro} @var{replacement-list}
+@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
+@i{(This command is not yet implemented.)} Introduce a definition for a
+preprocessor macro named @var{macro}, invocations of which are replaced
+by the tokens given in @var{replacement-list}. The first form of this
+command defines an ``object-like'' macro, which takes no arguments; the
+second form defines a ``function-like'' macro, which takes the arguments
+given in @var{arglist}.
+
+A definition introduced by this command is in scope in every expression
+evaluated in @value{GDBN}, until it is removed with the @command{macro
+undef} command, described below. The definition overrides all
+definitions for @var{macro} present in the program being debugged, as
+well as any previous user-supplied definition.
+
+@kindex macro undef
+@item macro undef @var{macro}
+@i{(This command is not yet implemented.)} Remove any user-supplied
+definition for the macro named @var{macro}. This command only affects
+definitions provided with the @command{macro define} command, described
+above; it cannot remove definitions present in the program being
+debugged.
+
+@end table
+
+@cindex macros, example of debugging with
+Here is a transcript showing the above commands in action. First, we
+show our source files:
+
+@smallexample
+$ cat sample.c
+#include <stdio.h>
+#include "sample.h"
+
+#define M 42
+#define ADD(x) (M + x)
+
+main ()
+@{
+#define N 28
+ printf ("Hello, world!\n");
+#undef N
+ printf ("We're so creative.\n");
+#define N 1729
+ printf ("Goodbye, world!\n");
+@}
+$ cat sample.h
+#define Q <
+$
+@end smallexample
+
+Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
+We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
+compiler includes information about preprocessor macros in the debugging
+information.
+
+@smallexample
+$ gcc -gdwarf-2 -g3 sample.c -o sample
+$
+@end smallexample
+
+Now, we start @value{GDBN} on our sample program:
+
+@smallexample
+$ gdb -nw sample
+GNU gdb 2002-05-06-cvs
+Copyright 2002 Free Software Foundation, Inc.
+GDB is free software, @dots{}
+(gdb)
+@end smallexample
+
+We can expand macros and examine their definitions, even when the
+program is not running. @value{GDBN} uses the current listing position
+to decide which macro definitions are in scope:
+
+@smallexample
+(gdb) list main
+3
+4 #define M 42
+5 #define ADD(x) (M + x)
+6
+7 main ()
+8 @{
+9 #define N 28
+10 printf ("Hello, world!\n");
+11 #undef N
+12 printf ("We're so creative.\n");
+(gdb) info macro ADD
+Defined at /home/jimb/gdb/macros/play/sample.c:5
+#define ADD(x) (M + x)
+(gdb) info macro Q
+Defined at /home/jimb/gdb/macros/play/sample.h:1
+ included at /home/jimb/gdb/macros/play/sample.c:2
+#define Q <
+(gdb) macro expand ADD(1)
+expands to: (42 + 1)
+(gdb) macro expand-once ADD(1)
+expands to: once (M + 1)
+(gdb)
+@end smallexample
+
+In the example above, note that @command{macro expand-once} expands only
+the macro invocation explicit in the original text --- the invocation of
+@code{ADD} --- but does not expand the invocation of the macro @code{M},
+which was introduced by @code{ADD}.
+
+Once the program is running, GDB uses the macro definitions in force at
+the source line of the current stack frame:
+
+@smallexample
+(gdb) break main
+Breakpoint 1 at 0x8048370: file sample.c, line 10.
+(gdb) run
+Starting program: /home/jimb/gdb/macros/play/sample
+
+Breakpoint 1, main () at sample.c:10
+10 printf ("Hello, world!\n");
+(gdb)
+@end smallexample
+
+At line 10, the definition of the macro @code{N} at line 9 is in force:
+
+@smallexample
+(gdb) info macro N
+Defined at /home/jimb/gdb/macros/play/sample.c:9
+#define N 28
+(gdb) macro expand N Q M
+expands to: 28 < 42
+(gdb) print N Q M
+$1 = 1
+(gdb)
+@end smallexample
+
+As we step over directives that remove @code{N}'s definition, and then
+give it a new definition, @value{GDBN} finds the definition (or lack
+thereof) in force at each point:
+
+@smallexample
+(gdb) next
+Hello, world!
+12 printf ("We're so creative.\n");
+(gdb) info macro N
+The symbol `N' has no definition as a C/C++ preprocessor macro
+at /home/jimb/gdb/macros/play/sample.c:12
+(gdb) next
+We're so creative.
+14 printf ("Goodbye, world!\n");
+(gdb) info macro N
+Defined at /home/jimb/gdb/macros/play/sample.c:13
+#define N 1729
+(gdb) macro expand N Q M
+expands to: 1729 < 42
+(gdb) print N Q M
+$2 = 0
+(gdb)
+@end smallexample
+
+
@node Tracepoints
@chapter Tracepoints
@c This chapter is based on the documentation written by Michael
for it in the instruction memory, and then jump to its entry point
there.
-@example
+@c NB: In the below the mapped area's size is greater or equal to the
+@c size of all overlays. This is intentional to remind the developer
+@c that overlays don't necessarily need to be the same size.
+
+@smallexample
@group
- Data Instruction Larger
-Address Space Address Space Address Space
-+-----------+ +-----------+ +-----------+
-| | | | | |
-+-----------+ +-----------+ +-----------+<-- overlay 1
-| program | | main | | | load address
-| variables | | program | | overlay 1 |
-| and heap | | | ,---| |
-+-----------+ | | | | |
-| | +-----------+ | +-----------+
-+-----------+ | | | | |
- mapped --->+-----------+ / +-----------+<-- overlay 2
- address | overlay | <-' | overlay 2 | load address
- | area | <-----| |
- | | <---. +-----------+
- | | | | |
- +-----------+ | | |
- | | | +-----------+<-- overlay 3
- +-----------+ `--| | load address
- | overlay 3 |
- | |
- +-----------+
- | |
- +-----------+
-
- To map an overlay, copy its code from the larger address space
- to the instruction address space. Since the overlays shown here
- all use the same mapped address, only one may be mapped at a time.
+ Data Instruction Larger
+Address Space Address Space Address Space
++-----------+ +-----------+ +-----------+
+| | | | | |
++-----------+ +-----------+ +-----------+<-- overlay 1
+| program | | main | .----| overlay 1 | load address
+| variables | | program | | +-----------+
+| and heap | | | | | |
++-----------+ | | | +-----------+<-- overlay 2
+| | +-----------+ | | | load address
++-----------+ | | | .-| overlay 2 |
+ | | | | | |
+ mapped --->+-----------+ | | +-----------+
+ address | | | | | |
+ | overlay | <-' | | |
+ | area | <---' +-----------+<-- overlay 3
+ | | <---. | | load address
+ +-----------+ `--| overlay 3 |
+ | | | |
+ +-----------+ | |
+ +-----------+
+ | |
+ +-----------+
+
+ @anchor{A code overlay}A code overlay
@end group
-@end example
+@end smallexample
-This diagram shows a system with separate data and instruction address
-spaces. For a system with a single address space for data and
-instructions, the diagram would be similar, except that the program
-variables and heap would share an address space with the main program
-and the overlay area.
+The diagram (@pxref{A code overlay}) shows a system with separate data
+and instruction address spaces. To map an overlay, the program copies
+its code from the larger address space to the instruction address space.
+Since the overlays shown here all use the same mapped address, only one
+may be mapped at a time. For a system with a single address space for
+data and instructions, the diagram would be similar, except that the
+program variables and heap would share an address space with the main
+program and the overlay area.
An overlay loaded into instruction memory and ready for use is called a
@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
Normally, when @value{GDBN} prints a code address, it includes the name
of the function the address falls in:
-@example
+@smallexample
(gdb) print main
$3 = @{int ()@} 0x11a0 <main>
-@end example
+@end smallexample
@noindent
When overlay debugging is enabled, @value{GDBN} recognizes code in
unmapped overlays, and prints the names of unmapped functions with
asterisks around them. For example, if @code{foo} is a function in an
unmapped overlay, @value{GDBN} prints it this way:
-@example
+@smallexample
(gdb) overlay list
No sections are mapped.
(gdb) print foo
$5 = @{int (int)@} 0x100000 <*foo*>
-@end example
+@end smallexample
@noindent
When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
name normally:
-@example
+@smallexample
(gdb) overlay list
Section .ov.foo.text, loaded at 0x100000 - 0x100034,
mapped at 0x1016 - 0x104a
(gdb) print foo
$6 = @{int (int)@} 0x1016 <foo>
-@end example
+@end smallexample
When overlay debugging is enabled, @value{GDBN} can find the correct
address for functions and variables in an overlay, whether or not the
@item @code{_ovly_table}:
This variable must be an array of the following structures:
-@example
+@smallexample
struct
@{
/* The overlay's mapped address. */
zero otherwise. */
unsigned long mapped;
@}
-@end example
+@end smallexample
@item @code{_novlys}:
This variable must be a four-byte signed integer, holding the total
the entry's @code{mapped} member to determine whether the overlay is
currently mapped.
+In addition, your overlay manager may define a function called
+@code{_ovly_debug_event}. If this function is defined, @value{GDBN}
+will silently set a breakpoint there. If the overlay manager then
+calls this function whenever it has changed the overlay table, this
+will enable @value{GDBN} to accurately keep track of which overlays
+are in program memory, and update any breakpoints that may be set
+in overlays. This will allow breakpoints to work even if the
+overlays are kept in ROM or other non-writable memory while they
+are not being executed.
@node Overlay Sample Program
@section Overlay Sample Program
You can build the test program using the @code{d10v-elf} GCC
cross-compiler like this:
-@example
+@smallexample
$ d10v-elf-gcc -g -c overlays.c
$ d10v-elf-gcc -g -c ovlymgr.c
$ d10v-elf-gcc -g -c foo.c
$ d10v-elf-gcc -g -c grbx.c
$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
baz.o grbx.o -Wl,-Td10v.ld -o overlays
-@end example
+@end smallexample
The build process is identical for any other architecture, except that
you must substitute the appropriate compiler and linker script for the
source file were written in C, and @value{GDBN} was parsing Modula-2, a
command such as:
-@example
+@smallexample
print a = b + c
-@end example
+@end smallexample
@noindent
might not have the effect you intended. In C, this means to add
result to ``wrap around'' to lower values---for example, if @var{m} is
the largest integer value, and @var{s} is the smallest, then
-@example
+@smallexample
@var{m} + 1 @result{} @var{s}
-@end example
+@end smallexample
This, too, is specific to individual languages, and in some cases
specific to individual compilers or machines. @xref{Support, ,
@itemize @bullet
@item
Integer constants are a sequence of digits. Octal constants are
-specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
-a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
+specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
+by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
@samp{l}, specifying that the constant should be treated as a
@code{long} value.
@item
Member function calls are allowed; you can use expressions like
-@example
+@smallexample
count = aml->GetOriginal(x, y)
-@end example
+@end smallexample
@vindex this@r{, inside C@t{++} member functions}
@cindex namespace in C@t{++}
(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
similar syntax:
-@example
+@smallexample
@var{module} . @var{id}
@var{scope} :: @var{id}
-@end example
+@end smallexample
@noindent
where @var{scope} is the name of a module or a procedure,
@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
-@example
+@smallexample
p 'foo.c'::x
-@end example
+@end smallexample
@noindent
looks up the value of @code{x} in the scope of the file @file{foo.c}.
If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
nearest symbol and an offset from it:
-@example
+@smallexample
(@value{GDBP}) info symbol 0x54320
_initialize_vx + 396 in section .text
-@end example
+@end smallexample
@noindent
This is the opposite of the @code{info address} command. You can use
For example, for this variable declaration:
-@example
+@smallexample
struct complex @{double real; double imag;@} v;
-@end example
+@end smallexample
@noindent
the two commands give this output:
-@example
+@smallexample
@group
(@value{GDBP}) whatis v
type = struct complex
double imag;
@}
@end group
-@end example
+@end smallexample
@noindent
As with @code{whatis}, using @code{ptype} without an argument refers to
@kindex info source
@item info source
-Show the name of the current source file---that is, the source file for
-the function containing the current point of execution---and the language
-it was written in.
+Show information about the current source file---that is, the source file for
+the function containing the current point of execution:
+@itemize @bullet
+@item
+the name of the source file, and the directory containing it,
+@item
+the directory it was compiled in,
+@item
+its length, in lines,
+@item
+which programming language it is written in,
+@item
+whether the executable includes debugging information for that file, and
+if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
+@item
+whether the debugging information includes information about
+preprocessor macros.
+@end itemize
+
@kindex info sources
@item info sources
@kindex info variables
@item info variables
Print the names and data types of all variables that are declared
-outside of functions (i.e., excluding local variables).
+outside of functions (i.e.@: excluding local variables).
@item info variables @var{regexp}
Print the names and data types of all variables (except for local
To alter the value of a variable, evaluate an assignment expression.
@xref{Expressions, ,Expressions}. For example,
-@example
+@smallexample
print x=4
-@end example
+@end smallexample
@noindent
stores the value 4 into the variable @code{x}, and then prints the
a new value with just @samp{set width=13}, because @value{GDBN} has the
command @code{set width}:
-@example
+@smallexample
(@value{GDBP}) whatis width
type = double
(@value{GDBP}) p width
$4 = 13
(@value{GDBP}) set width=47
Invalid syntax in expression.
-@end example
+@end smallexample
@noindent
The invalid expression, of course, is @samp{=47}. In
order to actually set the program's variable @code{width}, use
-@example
+@smallexample
(@value{GDBP}) set var width=47
-@end example
+@end smallexample
Because the @code{set} command has many subcommands that can conflict
with the names of program variables, it is a good idea to use the
to set a new value with just @samp{set g=4}, because @value{GDBN} has
the command @code{set gnutarget}, abbreviated @code{set g}:
-@example
+@smallexample
@group
(@value{GDBP}) whatis g
type = double
(@value{GDBP}) show g
The current BFD target is "=4".
@end group
-@end example
+@end smallexample
@noindent
The program variable @code{g} did not change, and you silently set the
@code{gnutarget} to an invalid value. In order to set the variable
@code{g}, use
-@example
+@smallexample
(@value{GDBP}) set var g=4
-@end example
+@end smallexample
@value{GDBN} allows more implicit conversions in assignments than C; you can
freely store an integer value into a pointer variable or vice versa,
to memory location @code{0x83040} as an integer (which implies a certain size
and representation in memory), and
-@example
+@smallexample
set @{int@}0x83040 = 4
-@end example
+@end smallexample
@noindent
stores the value 4 into that memory location.
changes the address of where it @emph{will} run when you continue. For
example,
-@example
+@smallexample
set $pc = 0x485
-@end example
+@end smallexample
@noindent
makes the next @code{continue} command or stepping command execute at
with @code{void} returned values. If the result is not void, it
is printed and saved in the value history.
-@c OBSOLETE For the A29K, a user-controlled variable @code{call_scratch_address},
-@c OBSOLETE specifies the location of a scratch area to be used when @value{GDBN}
-@c OBSOLETE calls a function in the target. This is necessary because the usual
-@c OBSOLETE method of putting the scratch area on the stack does not work in systems
-@c OBSOLETE that have separate instruction and data spaces.
-
@node Patching
@section Patching programs
Section contains common symbols.
@end table
@end table
+@kindex set trust-readonly-sections
+@item set trust-readonly-sections on
+Tell @value{GDBN} that readonly sections in your object file
+really are read-only (i.e.@: that their contents will not change).
+In that case, @value{GDBN} can fetch values from these sections
+out of the object file, rather than from the target program.
+For some targets (notably embedded ones), this can be a significant
+enhancement to debugging performance.
+
+The default is off.
+
+@item set trust-readonly-sections off
+Tell @value{GDBN} not to trust readonly sections. This means that
+the contents of the section might change while the program is running,
+and must therefore be fetched from the target when needed.
@end table
All file-specifying commands allow both absolute and relative file names
symbols from all shared object libraries will be loaded until the total
size of the loaded shared library symbols exceeds this threshold.
Otherwise, symbols must be loaded manually, using the
-@code{sharedlibrary} command. The default threshold is 100 (i.e. 100
+@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100
Mb).
@kindex show auto-solib-limit
@item target sim
Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
In general,
-@example
+@smallexample
target sim
load
run
-@end example
+@end smallexample
@noindent
works; however, you cannot assume that a specific memory map, device
drivers, or even basic I/O is available, although some simulators do
Use the @code{set os} command to set the operating system. This tells
@value{GDBN} which kernel object display module to initialize:
-@example
+@smallexample
(@value{GDBP}) set os cisco
-@end example
+@end smallexample
If @code{set os} succeeds, @value{GDBN} will display some information
about the operating system, and will create a new @code{info} command
which can be used to query the target. The @code{info} command is named
after the operating system:
-@example
+@smallexample
(@value{GDBP}) info cisco
List of Cisco Kernel Objects
Object Description
any Any and all objects
-@end example
+@end smallexample
Further subcommands can be used to query about particular objects known
by the kernel.
@node Remote Debugging
@chapter Debugging remote programs
+@menu
+* Server:: Using the gdbserver program
+* NetWare:: Using the gdbserve.nlm program
+* remote stub:: Implementing a remote stub
+@end menu
+
@node Server
@section Using the @code{gdbserver} program
system does all the symbol handling.
To use the server, you must tell it how to communicate with @value{GDBN};
-the name of your program; and the arguments for your program. The
+the name of your program; and the arguments for your program. The usual
syntax is:
@smallexample
and exits.} You must use the same port number with the host @value{GDBN}
@code{target remote} command.
-@item On the @value{GDBN} host machine,
+On some targets, @code{gdbserver} can also attach to running programs.
+This is accomplished via the @code{--attach} argument. The syntax is:
+
+@smallexample
+target> gdbserver @var{comm} --attach @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process. It isn't necessary
+to point @code{gdbserver} at a binary for the running process.
+
+@item On the @value{GDBN} host machine,
you need an unstripped copy of your program, since @value{GDBN} needs
symbols and debugging information. Start up @value{GDBN} as usual,
using the name of the local copy of your program as the first argument.
@node remote stub
@section Implementing a remote stub
+@cindex debugging stub, example
+@cindex remote stub, example
+@cindex stub example, remote debugging
+The stub files provided with @value{GDBN} implement the target side of the
+communication protocol, and the @value{GDBN} side is implemented in the
+@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
+these subroutines to communicate, and ignore the details. (If you're
+implementing your own stub file, you can still ignore the details: start
+with one of the existing stub files. @file{sparc-stub.c} is the best
+organized, and therefore the easiest to read.)
+
@cindex remote serial debugging, overview
To debug a program running on another machine (the debugging
@dfn{target} machine), you must first arrange for all the usual
@item
Insert these lines near the top of your program:
-@example
+@smallexample
set_debug_traps();
breakpoint();
-@end example
+@end smallexample
@item
For the 680x0 stub only, you need to provide a variable called
@code{exceptionHook}. Normally you just use:
-@example
+@smallexample
void (*exceptionHook)() = 0;
-@end example
+@end smallexample
@noindent
but if before calling @code{set_debug_traps}, you set it to point to a
Establish communication using the @code{target remote} command.
Its argument specifies how to communicate with the target
machine---either via a devicename attached to a direct serial line, or a
-TCP port (usually to a terminal server which in turn has a serial line
+TCP or UDP port (usually to a terminal server which in turn has a serial line
to the target). For example, to use a serial line connected to the
device named @file{/dev/ttyb}:
-@example
+@smallexample
target remote /dev/ttyb
-@end example
+@end smallexample
@cindex TCP port, @code{target remote}
To use a TCP connection, use an argument of the form
-@code{@var{host}:port}. For example, to connect to port 2828 on a
+@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}.
+For example, to connect to port 2828 on a
terminal server named @code{manyfarms}:
-@example
+@smallexample
target remote manyfarms:2828
-@end example
+@end smallexample
If your remote target is actually running on the same machine as
your debugger session (e.g.@: a simulator of your target running on
the same host), you can omit the hostname. For example, to connect
to port 1234 on your local machine:
-@example
+@smallexample
target remote :1234
-@end example
+@end smallexample
@noindent
Note that the colon is still required here.
+
+@cindex UDP port, @code{target remote}
+To use a UDP connection, use an argument of the form
+@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828
+on a terminal server named @code{manyfarms}:
+
+@smallexample
+target remote udp:manyfarms:2828
+@end smallexample
+
+When using a UDP connection for remote debugging, you should keep in mind
+that the `U' stands for ``Unreliable''. UDP can silently drop packets on
+busy or unreliable networks, which will cause havoc with your debugging
+session.
+
@end enumerate
Now you can use all the usual commands to examine and change data and to
and the serial drivers the remote system uses. If you type the
interrupt character once again, @value{GDBN} displays this prompt:
-@example
+@smallexample
Interrupted while waiting for the program.
Give up (and stop debugging it)? (y or n)
-@end example
+@end smallexample
If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
(If you decide you want to try again later, you can use @samp{target
remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
goes back to waiting.
-@node Protocol
-@section Communication protocol
-
-@cindex debugging stub, example
-@cindex remote stub, example
-@cindex stub example, remote debugging
-The stub files provided with @value{GDBN} implement the target side of the
-communication protocol, and the @value{GDBN} side is implemented in the
-@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
-these subroutines to communicate, and ignore the details. (If you're
-implementing your own stub file, you can still ignore the details: start
-with one of the existing stub files. @file{sparc-stub.c} is the best
-organized, and therefore the easiest to read.)
-However, there may be occasions when you need to know something about
-the protocol---for example, if there is only one serial port to your
-target machine, you might want your program to do something special if
-it recognizes a packet meant for @value{GDBN}.
+@node Configurations
+@chapter Configuration-Specific Information
-In the examples below, @samp{<-} and @samp{->} are used to indicate
-transmitted and received data respectfully.
+While nearly all @value{GDBN} commands are available for all native and
+cross versions of the debugger, there are some exceptions. This chapter
+describes things that are only available in certain configurations.
-@cindex protocol, @value{GDBN} remote serial
-@cindex serial protocol, @value{GDBN} remote
-@cindex remote serial protocol
-All @value{GDBN} commands and responses (other than acknowledgments) are
-sent as a @var{packet}. A @var{packet} is introduced with the character
-@samp{$}, the actual @var{packet-data}, and the terminating character
-@samp{#} followed by a two-digit @var{checksum}:
+There are three major categories of configurations: native
+configurations, where the host and target are the same, embedded
+operating system configurations, which are usually the same for several
+different processor architectures, and bare embedded processors, which
+are quite different from each other.
-@example
-@code{$}@var{packet-data}@code{#}@var{checksum}
-@end example
-@noindent
+@menu
+* Native::
+* Embedded OS::
+* Embedded Processors::
+* Architectures::
+@end menu
-@cindex checksum, for @value{GDBN} remote
-@noindent
-The two-digit @var{checksum} is computed as the modulo 256 sum of all
-characters between the leading @samp{$} and the trailing @samp{#} (an
-eight bit unsigned checksum).
+@node Native
+@section Native
-Implementors should note that prior to @value{GDBN} 5.0 the protocol
-specification also included an optional two-digit @var{sequence-id}:
+This section describes details specific to particular native
+configurations.
-@example
-@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
-@end example
+@menu
+* HP-UX:: HP-UX
+* SVR4 Process Information:: SVR4 process information
+* DJGPP Native:: Features specific to the DJGPP port
+* Cygwin Native:: Features specific to the Cygwin port
+@end menu
-@cindex sequence-id, for @value{GDBN} remote
-@noindent
-That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
-has never output @var{sequence-id}s. Stubs that handle packets added
-since @value{GDBN} 5.0 must not accept @var{sequence-id}.
+@node HP-UX
+@subsection HP-UX
-@cindex acknowledgment, for @value{GDBN} remote
-When either the host or the target machine receives a packet, the first
-response expected is an acknowledgment: either @samp{+} (to indicate
-the package was received correctly) or @samp{-} (to request
-retransmission):
+On HP-UX systems, if you refer to a function or variable name that
+begins with a dollar sign, @value{GDBN} searches for a user or system
+name first, before it searches for a convenience variable.
-@example
-<- @code{$}@var{packet-data}@code{#}@var{checksum}
--> @code{+}
-@end example
-@noindent
+@node SVR4 Process Information
+@subsection SVR4 process information
-The host (@value{GDBN}) sends @var{command}s, and the target (the
-debugging stub incorporated in your program) sends a @var{response}. In
-the case of step and continue @var{command}s, the response is only sent
-when the operation has completed (the target has again stopped).
+@kindex /proc
+@cindex process image
-@var{packet-data} consists of a sequence of characters with the
-exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
-exceptions).
+Many versions of SVR4 provide a facility called @samp{/proc} that can be
+used to examine the image of a running process using file-system
+subroutines. If @value{GDBN} is configured for an operating system with
+this facility, the command @code{info proc} is available to report on
+several kinds of information about the process running your program.
+@code{info proc} works only on SVR4 systems that include the
+@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix,
+and Unixware, but not HP-UX or Linux, for example.
-Fields within the packet should be separated using @samp{,} @samp{;} or
-@samp{:}. Except where otherwise noted all numbers are represented in
-HEX with leading zeros suppressed.
+@table @code
+@kindex info proc
+@item info proc
+Summarize available information about the process.
-Implementors should note that prior to @value{GDBN} 5.0, the character
-@samp{:} could not appear as the third character in a packet (as it
-would potentially conflict with the @var{sequence-id}).
+@kindex info proc mappings
+@item info proc mappings
+Report on the address ranges accessible in the program, with information
+on whether your program may read, write, or execute each range.
+@ignore
+@comment These sub-options of 'info proc' were not included when
+@comment procfs.c was re-written. Keep their descriptions around
+@comment against the day when someone finds the time to put them back in.
+@kindex info proc times
+@item info proc times
+Starting time, user CPU time, and system CPU time for your program and
+its children.
-Response @var{data} can be run-length encoded to save space. A @samp{*}
-means that the next character is an @sc{ascii} encoding giving a repeat count
-which stands for that many repetitions of the character preceding the
-@samp{*}. The encoding is @code{n+29}, yielding a printable character
-where @code{n >=3} (which is where rle starts to win). The printable
-characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
-value greater than 126 should not be used.
+@kindex info proc id
+@item info proc id
+Report on the process IDs related to your program: its own process ID,
+the ID of its parent, the process group ID, and the session ID.
-Some remote systems have used a different run-length encoding mechanism
-loosely refered to as the cisco encoding. Following the @samp{*}
-character are two hex digits that indicate the size of the packet.
+@kindex info proc status
+@item info proc status
+General information on the state of the process. If the process is
+stopped, this report includes the reason for stopping, and any signal
+received.
-So:
-@example
-"@code{0* }"
-@end example
-@noindent
-means the same as "0000".
+@item info proc all
+Show all the above information about the process.
+@end ignore
+@end table
-The error response returned for some packets includes a two character
-error number. That number is not well defined.
+@node DJGPP Native
+@subsection Features for Debugging @sc{djgpp} Programs
+@cindex @sc{djgpp} debugging
+@cindex native @sc{djgpp} debugging
+@cindex MS-DOS-specific commands
-For any @var{command} not supported by the stub, an empty response
-(@samp{$#00}) should be returned. That way it is possible to extend the
-protocol. A newer @value{GDBN} can tell if a packet is supported based
-on that response.
+@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and
+MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
+that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
+top of real-mode DOS systems and their emulations.
-A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
-@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
-optional.
+@value{GDBN} supports native debugging of @sc{djgpp} programs, and
+defines a few commands specific to the @sc{djgpp} port. This
+subsection describes those commands.
-Below is a complete list of all currently defined @var{command}s and
-their corresponding response @var{data}:
-@page
-@multitable @columnfractions .30 .30 .40
-@item Packet
-@tab Request
-@tab Description
+@table @code
+@kindex info dos
+@item info dos
+This is a prefix of @sc{djgpp}-specific commands which print
+information about the target system and important OS structures.
-@item extended mode
-@tab @code{!}
-@tab
-Enable extended mode. In extended mode, the remote server is made
-persistent. The @samp{R} packet is used to restart the program being
-debugged.
-@item
-@tab reply @samp{OK}
-@tab
-The remote target both supports and has enabled extended mode.
+@kindex sysinfo
+@cindex MS-DOS system info
+@cindex free memory information (MS-DOS)
+@item info dos sysinfo
+This command displays assorted information about the underlying
+platform: the CPU type and features, the OS version and flavor, the
+DPMI version, and the available conventional and DPMI memory.
-@item last signal
-@tab @code{?}
-@tab
-Indicate the reason the target halted. The reply is the same as for step
-and continue.
-@item
-@tab reply
-@tab see below
+@cindex GDT
+@cindex LDT
+@cindex IDT
+@cindex segment descriptor tables
+@cindex descriptor tables display
+@item info dos gdt
+@itemx info dos ldt
+@itemx info dos idt
+These 3 commands display entries from, respectively, Global, Local,
+and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
+tables are data structures which store a descriptor for each segment
+that is currently in use. The segment's selector is an index into a
+descriptor table; the table entry for that index holds the
+descriptor's base address and limit, and its attributes and access
+rights.
+A typical @sc{djgpp} program uses 3 segments: a code segment, a data
+segment (used for both data and the stack), and a DOS segment (which
+allows access to DOS/BIOS data structures and absolute addresses in
+conventional memory). However, the DPMI host will usually define
+additional segments in order to support the DPMI environment.
-@item reserved
-@tab @code{a}
-@tab Reserved for future use
+@cindex garbled pointers
+These commands allow to display entries from the descriptor tables.
+Without an argument, all entries from the specified table are
+displayed. An argument, which should be an integer expression, means
+display a single entry whose index is given by the argument. For
+example, here's a convenient way to display information about the
+debugged program's data segment:
-@item set program arguments @strong{(reserved)}
-@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
-@tab
-@item
-@tab
-@tab
-Initialized @samp{argv[]} array passed into program. @var{arglen}
-specifies the number of bytes in the hex encoded byte stream @var{arg}.
-See @file{gdbserver} for more details.
-@item
-@tab reply @code{OK}
-@item
-@tab reply @code{E}@var{NN}
+@smallexample
+@exdent @code{(@value{GDBP}) info dos ldt $ds}
+@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
+@end smallexample
-@item set baud @strong{(deprecated)}
-@tab @code{b}@var{baud}
-@tab
-Change the serial line speed to @var{baud}. JTC: @emph{When does the
-transport layer state change? When it's received, or after the ACK is
-transmitted. In either case, there are problems if the command or the
-acknowledgment packet is dropped.} Stan: @emph{If people really wanted
-to add something like this, and get it working for the first time, they
-ought to modify ser-unix.c to send some kind of out-of-band message to a
-specially-setup stub and have the switch happen "in between" packets, so
-that from remote protocol's point of view, nothing actually
-happened.}
+@noindent
+This comes in handy when you want to see whether a pointer is outside
+the data segment's limit (i.e.@: @dfn{garbled}).
-@item set breakpoint @strong{(deprecated)}
-@tab @code{B}@var{addr},@var{mode}
-@tab
-Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
-breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
-@samp{z} packets.}
+@cindex page tables display (MS-DOS)
+@item info dos pde
+@itemx info dos pte
+These two commands display entries from, respectively, the Page
+Directory and the Page Tables. Page Directories and Page Tables are
+data structures which control how virtual memory addresses are mapped
+into physical addresses. A Page Table includes an entry for every
+page of memory that is mapped into the program's address space; there
+may be several Page Tables, each one holding up to 4096 entries. A
+Page Directory has up to 4096 entries, one each for every Page Table
+that is currently in use.
-@item continue
-@tab @code{c}@var{addr}
-@tab
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-current address.
-@item
-@tab reply
-@tab see below
+Without an argument, @kbd{info dos pde} displays the entire Page
+Directory, and @kbd{info dos pte} displays all the entries in all of
+the Page Tables. An argument, an integer expression, given to the
+@kbd{info dos pde} command means display only that entry from the Page
+Directory table. An argument given to the @kbd{info dos pte} command
+means display entries from a single Page Table, the one pointed to by
+the specified entry in the Page Directory.
-@item continue with signal
-@tab @code{C}@var{sig}@code{;}@var{addr}
-@tab
-Continue with signal @var{sig} (hex signal number). If
-@code{;}@var{addr} is omitted, resume at same address.
-@item
-@tab reply
-@tab see below
+@cindex direct memory access (DMA) on MS-DOS
+These commands are useful when your program uses @dfn{DMA} (Direct
+Memory Access), which needs physical addresses to program the DMA
+controller.
-@item toggle debug @strong{(deprecated)}
-@tab @code{d}
-@tab
-toggle debug flag.
+These commands are supported only with some DPMI servers.
-@item detach
-@tab @code{D}
-@tab
-Detach @value{GDBN} from the remote system. Sent to the remote target before
-@value{GDBN} disconnects.
-@item
-@tab reply @emph{no response}
-@tab
-@value{GDBN} does not check for any response after sending this packet.
+@cindex physical address from linear address
+@item info dos address-pte @var{addr}
+This command displays the Page Table entry for a specified linear
+address. The argument linear address @var{addr} should already have the
+appropriate segment's base address added to it, because this command
+accepts addresses which may belong to @emph{any} segment. For
+example, here's how to display the Page Table entry for the page where
+the variable @code{i} is stored:
-@item reserved
-@tab @code{e}
-@tab Reserved for future use
+@smallexample
+@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
+@exdent @code{Page Table entry for address 0x11a00d30:}
+@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
+@end smallexample
-@item reserved
-@tab @code{E}
-@tab Reserved for future use
+@noindent
+This says that @code{i} is stored at offset @code{0xd30} from the page
+whose physical base address is @code{0x02698000}, and prints all the
+attributes of that page.
-@item reserved
-@tab @code{f}
-@tab Reserved for future use
+Note that you must cast the addresses of variables to a @code{char *},
+since otherwise the value of @code{__djgpp_base_address}, the base
+address of all variables and functions in a @sc{djgpp} program, will
+be added using the rules of C pointer arithmetics: if @code{i} is
+declared an @code{int}, @value{GDBN} will add 4 times the value of
+@code{__djgpp_base_address} to the address of @code{i}.
-@item reserved
-@tab @code{F}
-@tab Reserved for future use
+Here's another example, it displays the Page Table entry for the
+transfer buffer:
-@item read registers
-@tab @code{g}
-@tab Read general registers.
-@item
-@tab reply @var{XX...}
-@tab
-Each byte of register data is described by two hex digits. The bytes
-with the register are transmitted in target byte order. The size of
-each register and their position within the @samp{g} @var{packet} are
-determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and
-@var{REGISTER_NAME} macros. The specification of several standard
-@code{g} packets is specified below.
-@item
-@tab @code{E}@var{NN}
-@tab for an error.
+@smallexample
+@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
+@exdent @code{Page Table entry for address 0x29110:}
+@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
+@end smallexample
-@item write regs
-@tab @code{G}@var{XX...}
-@tab
-See @samp{g} for a description of the @var{XX...} data.
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
+@noindent
+(The @code{+ 3} offset is because the transfer buffer's address is the
+3rd member of the @code{_go32_info_block} structure.) The output of
+this command clearly shows that addresses in conventional memory are
+mapped 1:1, i.e.@: the physical and linear addresses are identical.
-@item reserved
-@tab @code{h}
-@tab Reserved for future use
+This command is supported only with some DPMI servers.
+@end table
-@item set thread
-@tab @code{H}@var{c}@var{t...}
-@tab
-Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
-@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and
-continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for
-thread used in other operations. If zero, pick a thread, any thread.
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
+@node Cygwin Native
+@subsection Features for Debugging MS Windows PE executables
+@cindex MS Windows debugging
+@cindex native Cygwin debugging
+@cindex Cygwin-specific commands
-@c FIXME: JTC:
-@c 'H': How restrictive (or permissive) is the thread model. If a
-@c thread is selected and stopped, are other threads allowed
-@c to continue to execute? As I mentioned above, I think the
-@c semantics of each command when a thread is selected must be
-@c described. For example:
-@c
-@c 'g': If the stub supports threads and a specific thread is
-@c selected, returns the register block from that thread;
-@c otherwise returns current registers.
-@c
-@c 'G' If the stub supports threads and a specific thread is
-@c selected, sets the registers of the register block of
-@c that thread; otherwise sets current registers.
+@value{GDBN} supports native debugging of MS Windows programs, and
+defines a few commands specific to the Cygwin port. This
+subsection describes those commands.
-@item cycle step @strong{(draft)}
-@tab @code{i}@var{addr}@code{,}@var{nnn}
-@tab
-Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
-present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
-step starting at that address.
+@table @code
+@kindex info w32
+@item info w32
+This is a prefix of MS Windows specific commands which print
+information about the target system and important OS structures.
-@item signal then cycle step @strong{(reserved)}
-@tab @code{I}
-@tab
-See @samp{i} and @samp{S} for likely syntax and semantics.
+@item info w32 selector
+This command displays information returned by
+the Win32 API @code{GetThreadSelectorEntry} function.
+It takes an optional argument that is evaluated to
+a long value to give the information about this given selector.
+Without argument, this command displays information
+about the the six segment registers.
+
+@kindex info dll
+@item info dll
+This is a Cygwin specific alias of info shared.
+
+@kindex dll-symbols
+@item dll-symbols
+This command loads symbols from a dll similarly to
+add-sym command but without the need to specify a base address.
+
+@kindex set new-console
+@item set new-console @var{mode}
+If @var{mode} is @code{on} the debuggee will
+be started in a new console on next start.
+If @var{mode} is @code{off}i, the debuggee will
+be started in the same console as the debugger.
+
+@kindex show new-console
+@item show new-console
+Displays whether a new console is used
+when the debuggee is started.
+
+@kindex set new-group
+@item set new-group @var{mode}
+This boolean value controls whether the debuggee should
+start a new group or stay in the same group as the debugger.
+This affects the way the Windows OS handles
+Ctrl-C.
+
+@kindex show new-group
+@item show new-group
+Displays current value of new-group boolean.
+
+@kindex set debugevents
+@item set debugevents
+This boolean value adds debug output concerning events seen by the debugger.
+
+@kindex set debugexec
+@item set debugexec
+This boolean value adds debug output concerning execute events
+seen by the debugger.
+
+@kindex set debugexceptions
+@item set debugexceptions
+This boolean value adds debug ouptut concerning exception events
+seen by the debugger.
+
+@kindex set debugmemory
+@item set debugmemory
+This boolean value adds debug ouptut concerning memory events
+seen by the debugger.
+
+@kindex set shell
+@item set shell
+This boolean values specifies whether the debuggee is called
+via a shell or directly (default value is on).
+
+@kindex show shell
+@item show shell
+Displays if the debuggee will be started with a shell.
-@item reserved
-@tab @code{j}
-@tab Reserved for future use
+@end table
-@item reserved
-@tab @code{J}
-@tab Reserved for future use
+@node Embedded OS
+@section Embedded Operating Systems
-@item kill request
-@tab @code{k}
-@tab
-FIXME: @emph{There is no description of how operate when a specific
-thread context has been selected (ie. does 'k' kill only that thread?)}.
+This section describes configurations involving the debugging of
+embedded operating systems that are available for several different
+architectures.
-@item reserved
-@tab @code{l}
-@tab Reserved for future use
+@menu
+* VxWorks:: Using @value{GDBN} with VxWorks
+@end menu
-@item reserved
-@tab @code{L}
-@tab Reserved for future use
+@value{GDBN} includes the ability to debug programs running on
+various real-time operating systems.
-@item read memory
-@tab @code{m}@var{addr}@code{,}@var{length}
-@tab
-Read @var{length} bytes of memory starting at address @var{addr}.
-Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed
-using word alligned accesses. FIXME: @emph{A word aligned memory
-transfer mechanism is needed.}
-@item
-@tab reply @var{XX...}
-@tab
-@var{XX...} is mem contents. Can be fewer bytes than requested if able
-to read only part of the data. Neither @value{GDBN} nor the stub assume that
-sized memory transfers are assumed using word alligned accesses. FIXME:
-@emph{A word aligned memory transfer mechanism is needed.}
-@item
-@tab reply @code{E}@var{NN}
-@tab @var{NN} is errno
-
-@item write mem
-@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
-@tab
-Write @var{length} bytes of memory starting at address @var{addr}.
-@var{XX...} is the data.
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab reply @code{E}@var{NN}
-@tab
-for an error (this includes the case where only part of the data was
-written).
-
-@item reserved
-@tab @code{n}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{N}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{o}
-@tab Reserved for future use
+@node VxWorks
+@subsection Using @value{GDBN} with VxWorks
-@item reserved
-@tab @code{O}
-@tab Reserved for future use
+@cindex VxWorks
-@item read reg @strong{(reserved)}
-@tab @code{p}@var{n...}
-@tab
-See write register.
-@item
-@tab return @var{r....}
-@tab The hex encoded value of the register in target byte order.
+@table @code
-@item write reg
-@tab @code{P}@var{n...}@code{=}@var{r...}
-@tab
-Write register @var{n...} with value @var{r...}, which contains two hex
-digits for each byte in the register (target byte order).
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
+@kindex target vxworks
+@item target vxworks @var{machinename}
+A VxWorks system, attached via TCP/IP. The argument @var{machinename}
+is the target system's machine name or IP address.
-@item general query
-@tab @code{q}@var{query}
-@tab
-Request info about @var{query}. In general @value{GDBN} queries
-have a leading upper case letter. Custom vendor queries should use a
-company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may
-optionally be followed by a @samp{,} or @samp{;} separated list. Stubs
-must ensure that they match the full @var{query} name.
-@item
-@tab reply @code{XX...}
-@tab Hex encoded data from query. The reply can not be empty.
-@item
-@tab reply @code{E}@var{NN}
-@tab error reply
-@item
-@tab reply @samp{}
-@tab Indicating an unrecognized @var{query}.
+@end table
-@item general set
-@tab @code{Q}@var{var}@code{=}@var{val}
-@tab
-Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
-naming conventions.
+On VxWorks, @code{load} links @var{filename} dynamically on the
+current target system as well as adding its symbols in @value{GDBN}.
-@item reset @strong{(deprecated)}
-@tab @code{r}
-@tab
-Reset the entire system.
+@value{GDBN} enables developers to spawn and debug tasks running on networked
+VxWorks targets from a Unix host. Already-running tasks spawned from
+the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
+both the Unix host and on the VxWorks target. The program
+@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
+installed with the name @code{vxgdb}, to distinguish it from a
+@value{GDBN} for debugging programs on the host itself.)
-@item remote restart
-@tab @code{R}@var{XX}
-@tab
-Restart the program being debugged. @var{XX}, while needed, is ignored.
-This packet is only available in extended mode.
-@item
-@tab
-no reply
-@tab
-The @samp{R} packet has no reply.
+@table @code
+@item VxWorks-timeout @var{args}
+@kindex vxworks-timeout
+All VxWorks-based targets now support the option @code{vxworks-timeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses to rpc's. You might use this if
+your VxWorks target is a slow software simulator or is on the far side
+of a thin network line.
+@end table
-@item step
-@tab @code{s}@var{addr}
-@tab
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-same address.
-@item
-@tab reply
-@tab see below
+The following information on connecting to VxWorks was current when
+this manual was produced; newer releases of VxWorks may use revised
+procedures.
-@item step with signal
-@tab @code{S}@var{sig}@code{;}@var{addr}
-@tab
-Like @samp{C} but step not continue.
-@item
-@tab reply
-@tab see below
+@kindex INCLUDE_RDB
+To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
+to include the remote debugging interface routines in the VxWorks
+library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
+VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
+kernel. The resulting kernel contains @file{rdb.a}, and spawns the
+source debugging task @code{tRdbTask} when VxWorks is booted. For more
+information on configuring and remaking VxWorks, see the manufacturer's
+manual.
+@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
-@item search
-@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
-@tab
-Search backwards starting at address @var{addr} for a match with pattern
-@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
-bytes. @var{addr} must be at least 3 digits.
+Once you have included @file{rdb.a} in your VxWorks system image and set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
+@code{vxgdb}, depending on your installation).
-@item thread alive
-@tab @code{T}@var{XX}
-@tab Find out if the thread XX is alive.
-@item
-@tab reply @code{OK}
-@tab thread is still alive
-@item
-@tab reply @code{E}@var{NN}
-@tab thread is dead
+@value{GDBN} comes up showing the prompt:
-@item reserved
-@tab @code{u}
-@tab Reserved for future use
+@smallexample
+(vxgdb)
+@end smallexample
-@item reserved
-@tab @code{U}
-@tab Reserved for future use
+@menu
+* VxWorks Connection:: Connecting to VxWorks
+* VxWorks Download:: VxWorks download
+* VxWorks Attach:: Running tasks
+@end menu
-@item reserved
-@tab @code{v}
-@tab Reserved for future use
+@node VxWorks Connection
+@subsubsection Connecting to VxWorks
-@item reserved
-@tab @code{V}
-@tab Reserved for future use
+The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
+network. To connect to a target whose host name is ``@code{tt}'', type:
-@item reserved
-@tab @code{w}
-@tab Reserved for future use
+@smallexample
+(vxgdb) target vxworks tt
+@end smallexample
-@item reserved
-@tab @code{W}
-@tab Reserved for future use
+@need 750
+@value{GDBN} displays messages like these:
-@item reserved
-@tab @code{x}
-@tab Reserved for future use
+@smallexample
+Attaching remote machine across net...
+Connected to tt.
+@end smallexample
-@item write mem (binary)
-@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
-@tab
-@var{addr} is address, @var{length} is number of bytes, @var{XX...} is
-binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
-escaped using @code{0x7d}.
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
+@need 1000
+@value{GDBN} then attempts to read the symbol tables of any object modules
+loaded into the VxWorks target since it was last booted. @value{GDBN} locates
+these files by searching the directories listed in the command search
+path (@pxref{Environment, ,Your program's environment}); if it fails
+to find an object file, it displays a message such as:
-@item reserved
-@tab @code{y}
-@tab Reserved for future use
+@smallexample
+prog.o: No such file or directory.
+@end smallexample
-@item reserved
-@tab @code{Y}
-@tab Reserved for future use
+When this happens, add the appropriate directory to the search path with
+the @value{GDBN} command @code{path}, and execute the @code{target}
+command again.
-@item remove break or watchpoint @strong{(draft)}
-@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-See @samp{Z}.
+@node VxWorks Download
+@subsubsection VxWorks download
-@item insert break or watchpoint @strong{(draft)}
-@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
-breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
-@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
-bytes. For a software breakpoint, @var{length} specifies the size of
-the instruction to be patched. For hardware breakpoints and watchpoints
-@var{length} specifies the memory region to be monitored. To avoid
-potential problems with duplicate packets, the operations should be
-implemented in an idempotent way.
-@item
-@tab reply @code{E}@var{NN}
-@tab for an error
-@item
-@tab reply @code{OK}
-@tab for success
-@item
-@tab @samp{}
-@tab If not supported.
-
-@item reserved
-@tab <other>
-@tab Reserved for future use
-
-@end multitable
-
-The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
-receive any of the below as a reply. In the case of the @samp{C},
-@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
-when the target halts. In the below the exact meaning of @samp{signal
-number} is poorly defined. In general one of the UNIX signal numbering
-conventions is used.
-
-@multitable @columnfractions .4 .6
-
-@item @code{S}@var{AA}
-@tab @var{AA} is the signal number
-
-@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
-@tab
-@var{AA} = two hex digit signal number; @var{n...} = register number
-(hex), @var{r...} = target byte ordered register contents, size defined
-by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
-thread process ID, this is a hex integer; @var{n...} = other string not
-starting with valid hex digit. @value{GDBN} should ignore this
-@var{n...}, @var{r...} pair and go on to the next. This way we can
-extend the protocol.
-
-@item @code{W}@var{AA}
-@tab
-The process exited, and @var{AA} is the exit status. This is only
-applicable for certains sorts of targets.
-
-@item @code{X}@var{AA}
-@tab
-The process terminated with signal @var{AA}.
-
-@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
-@tab
-@var{AA} = signal number; @var{t...} = address of symbol "_start";
-@var{d...} = base of data section; @var{b...} = base of bss section.
-@emph{Note: only used by Cisco Systems targets. The difference between
-this reply and the "qOffsets" query is that the 'N' packet may arrive
-spontaneously whereas the 'qOffsets' is a query initiated by the host
-debugger.}
-
-@item @code{O}@var{XX...}
-@tab
-@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
-while the program is running and the debugger should continue to wait
-for 'W', 'T', etc.
-
-@end multitable
-
-The following set and query packets have already been defined.
-
-@multitable @columnfractions .2 .2 .6
-
-@item current thread
-@tab @code{q}@code{C}
-@tab Return the current thread id.
-@item
-@tab reply @code{QC}@var{pid}
-@tab
-Where @var{pid} is a HEX encoded 16 bit process id.
-@item
-@tab reply *
-@tab Any other reply implies the old pid.
-
-@item all thread ids
-@tab @code{q}@code{fThreadInfo}
-@item
-@tab @code{q}@code{sThreadInfo}
-@tab
-Obtain a list of active thread ids from the target (OS). Since there
-may be too many active threads to fit into one reply packet, this query
-works iteratively: it may require more than one query/reply sequence to
-obtain the entire list of threads. The first query of the sequence will
-be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
-sequence will be the @code{qs}@code{ThreadInfo} query.
-@item
-@tab
-@tab NOTE: replaces the @code{qL} query (see below).
-@item
-@tab reply @code{m}@var{<id>}
-@tab A single thread id
-@item
-@tab reply @code{m}@var{<id>},@var{<id>...}
-@tab a comma-separated list of thread ids
-@item
-@tab reply @code{l}
-@tab (lower case 'el') denotes end of list.
-@item
-@tab
-@tab
-In response to each query, the target will reply with a list of one
-or more thread ids, in big-endian hex, separated by commas. GDB will
-respond to each reply with a request for more thread ids (using the
-@code{qs} form of the query), until the target responds with @code{l}
-(lower-case el, for @code{'last'}).
-
-@item extra thread info
-@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
-@tab
-@item
-@tab
-@tab
-Where @var{<id>} is a thread-id in big-endian hex.
-Obtain a printable string description of a thread's attributes from
-the target OS. This string may contain anything that the target OS
-thinks is interesting for @value{GDBN} to tell the user about the thread.
-The string is displayed in @value{GDBN}'s @samp{info threads} display.
-Some examples of possible thread extra info strings are "Runnable", or
-"Blocked on Mutex".
-@item
-@tab reply @var{XX...}
-@tab
-Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
-printable string containing the extra information about the thread's
-attributes.
-
-@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
-@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
-@tab
-@item
-@tab
-@tab
-Obtain thread information from RTOS. Where: @var{startflag} (one hex
-digit) is one to indicate the first query and zero to indicate a
-subsequent query; @var{threadcount} (two hex digits) is the maximum
-number of threads the response packet can contain; and @var{nextthread}
-(eight hex digits), for subsequent queries (@var{startflag} is zero), is
-returned in the response as @var{argthread}.
-@item
-@tab
-@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
-query (see above).
-@item
-@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
-@tab
-@item
-@tab
-@tab
-Where: @var{count} (two hex digits) is the number of threads being
-returned; @var{done} (one hex digit) is zero to indicate more threads
-and one indicates no further threads; @var{argthreadid} (eight hex
-digits) is @var{nextthread} from the request packet; @var{thread...} is
-a sequence of thread IDs from the target. @var{threadid} (eight hex
-digits). See @code{remote.c:parse_threadlist_response()}.
-
-@item compute CRC of memory block
-@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
-@tab
-@item
-@tab reply @code{E}@var{NN}
-@tab An error (such as memory fault)
-@item
-@tab reply @code{C}@var{CRC32}
-@tab A 32 bit cyclic redundancy check of the specified memory region.
-
-@item query sect offs
-@tab @code{q}@code{Offsets}
-@tab
-Get section offsets that the target used when re-locating the downloaded
-image. @emph{Note: while a @code{Bss} offset is included in the
-response, @value{GDBN} ignores this and instead applies the @code{Data}
-offset to the @code{Bss} section.}
-@item
-@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
-
-@item thread info request
-@tab @code{q}@code{P}@var{mode}@var{threadid}
-@tab
-@item
-@tab
-@tab
-Returns information on @var{threadid}. Where: @var{mode} is a hex
-encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
-@item
-@tab reply *
-@tab
-See @code{remote.c:remote_unpack_thread_info_response()}.
-
-@item remote command
-@tab @code{q}@code{Rcmd,}@var{COMMAND}
-@tab
-@item
-@tab
-@tab
-@var{COMMAND} (hex encoded) is passed to the local interpreter for
-execution. Invalid commands should be reported using the output string.
-Before the final result packet, the target may also respond with a
-number of intermediate @code{O}@var{OUTPUT} console output
-packets. @emph{Implementors should note that providing access to a
-stubs's interpreter may have security implications}.
-@item
-@tab reply @code{OK}
-@tab
-A command response with no output.
-@item
-@tab reply @var{OUTPUT}
-@tab
-A command response with the hex encoded output string @var{OUTPUT}.
-@item
-@tab reply @code{E}@var{NN}
-@tab
-Indicate a badly formed request.
-
-@item
-@tab reply @samp{}
-@tab
-When @samp{q}@samp{Rcmd} is not recognized.
-
-@item symbol lookup
-@tab @code{qSymbol::}
-@tab
-Notify the target that @value{GDBN} is prepared to serve symbol lookup
-requests. Accept requests from the target for the values of symbols.
-@item
-@tab
-@tab
-@item
-@tab reply @code{OK}
-@tab
-The target does not need to look up any (more) symbols.
-@item
-@tab reply @code{qSymbol:}@var{sym_name}
-@tab
-@sp 2
-@noindent
-The target requests the value of symbol @var{sym_name} (hex encoded).
-@value{GDBN} may provide the value by using the
-@code{qSymbol:}@var{sym_value}:@var{sym_name}
-message, described below.
-
-@item symbol value
-@tab @code{qSymbol:}@var{sym_value}:@var{sym_name}
-@tab
-@sp 1
-@noindent
-Set the value of SYM_NAME to SYM_VALUE.
-@item
-@tab
-@tab
-@var{sym_name} (hex encoded) is the name of a symbol whose value
-the target has previously requested.
-@item
-@tab
-@tab
-@var{sym_value} (hex) is the value for symbol @var{sym_name}.
-If @value{GDBN} cannot supply a value for @var{sym_name}, then this
-field will be empty.
-@item
-@tab reply @code{OK}
-@tab
-The target does not need to look up any (more) symbols.
-@item
-@tab reply @code{qSymbol:}@var{sym_name}
-@tab
-@sp 2
-@noindent
-The target requests the value of a new symbol @var{sym_name} (hex encoded).
-@value{GDBN} will continue to supply the values of symbols (if available),
-until the target ceases to request them.
-
-@end multitable
+@cindex download to VxWorks
+If you have connected to the VxWorks target and you want to debug an
+object that has not yet been loaded, you can use the @value{GDBN}
+@code{load} command to download a file from Unix to VxWorks
+incrementally. The object file given as an argument to the @code{load}
+command is actually opened twice: first by the VxWorks target in order
+to download the code, then by @value{GDBN} in order to read the symbol
+table. This can lead to problems if the current working directories on
+the two systems differ. If both systems have NFS mounted the same
+filesystems, you can avoid these problems by using absolute paths.
+Otherwise, it is simplest to set the working directory on both systems
+to the directory in which the object file resides, and then to reference
+the file by its name, without any path. For instance, a program
+@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
+and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
+program, type this on VxWorks:
-The following @samp{g}/@samp{G} packets have previously been defined.
-In the below, some thirty-two bit registers are transferred as sixty-four
-bits. Those registers should be zero/sign extended (which?) to fill the
-space allocated. Register bytes are transfered in target byte order.
-The two nibbles within a register byte are transfered most-significant -
-least-significant.
+@smallexample
+-> cd "@var{vxpath}/vw/demo/rdb"
+@end smallexample
-@multitable @columnfractions .5 .5
+@noindent
+Then, in @value{GDBN}, type:
-@item MIPS32
-@tab
-All registers are transfered as thirty-two bit quantities in the order:
-32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
-registers; fsr; fir; fp.
+@smallexample
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) load prog.o
+@end smallexample
-@item MIPS64
-@tab
-All registers are transfered as sixty-four bit quantities (including
-thirty-two bit registers such as @code{sr}). The ordering is the same
-as @code{MIPS32}.
+@value{GDBN} displays a response similar to this:
-@end multitable
+@smallexample
+Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+@end smallexample
-Example sequence of a target being re-started. Notice how the restart
-does not get any direct output:
+You can also use the @code{load} command to reload an object module
+after editing and recompiling the corresponding source file. Note that
+this makes @value{GDBN} delete all currently-defined breakpoints,
+auto-displays, and convenience variables, and to clear the value
+history. (This is necessary in order to preserve the integrity of
+debugger's data structures that reference the target system's symbol
+table.)
-@example
-<- @code{R00}
--> @code{+}
-@emph{target restarts}
-<- @code{?}
--> @code{+}
--> @code{T001:1234123412341234}
-<- @code{+}
-@end example
+@node VxWorks Attach
+@subsubsection Running tasks
-Example sequence of a target being stepped by a single instruction:
+@cindex running VxWorks tasks
+You can also attach to an existing task using the @code{attach} command as
+follows:
-@example
-<- @code{G1445...}
--> @code{+}
-<- @code{s}
--> @code{+}
-@emph{time passes}
--> @code{T001:1234123412341234}
-<- @code{+}
-<- @code{g}
--> @code{+}
--> @code{1455...}
-<- @code{+}
-@end example
+@smallexample
+(vxgdb) attach @var{task}
+@end smallexample
+@noindent
+where @var{task} is the VxWorks hexadecimal task ID. The task can be running
+or suspended when you attach to it. Running tasks are suspended at
+the time of attachment.
-@node Configurations
-@chapter Configuration-Specific Information
+@node Embedded Processors
+@section Embedded Processors
-While nearly all @value{GDBN} commands are available for all native and
-cross versions of the debugger, there are some exceptions. This chapter
-describes things that are only available in certain configurations.
+This section goes into details specific to particular embedded
+configurations.
-There are three major categories of configurations: native
-configurations, where the host and target are the same, embedded
-operating system configurations, which are usually the same for several
-different processor architectures, and bare embedded processors, which
-are quite different from each other.
@menu
-* Native::
-* Embedded OS::
-* Embedded Processors::
-* Architectures::
+* ARM:: ARM
+* H8/300:: Hitachi H8/300
+* H8/500:: Hitachi H8/500
+* i960:: Intel i960
+* M32R/D:: Mitsubishi M32R/D
+* M68K:: Motorola M68K
+@c OBSOLETE * M88K:: Motorola M88K
+* MIPS Embedded:: MIPS Embedded
+* PA:: HP PA Embedded
+* PowerPC: PowerPC
+* SH:: Hitachi SH
+* Sparclet:: Tsqware Sparclet
+* Sparclite:: Fujitsu Sparclite
+* ST2000:: Tandem ST2000
+* Z8000:: Zilog Z8000
@end menu
-@node Native
-@section Native
-
-This section describes details specific to particular native
-configurations.
-
-@menu
-* HP-UX:: HP-UX
-* SVR4 Process Information:: SVR4 process information
-* DJGPP Native:: Features specific to the DJGPP port
-@end menu
+@node ARM
+@subsection ARM
-@node HP-UX
-@subsection HP-UX
+@table @code
-On HP-UX systems, if you refer to a function or variable name that
-begins with a dollar sign, @value{GDBN} searches for a user or system
-name first, before it searches for a convenience variable.
+@kindex target rdi
+@item target rdi @var{dev}
+ARM Angel monitor, via RDI library interface to ADP protocol. You may
+use this target to communicate with both boards running the Angel
+monitor, or with the EmbeddedICE JTAG debug device.
-@node SVR4 Process Information
-@subsection SVR4 process information
+@kindex target rdp
+@item target rdp @var{dev}
+ARM Demon monitor.
-@kindex /proc
-@cindex process image
+@end table
-Many versions of SVR4 provide a facility called @samp{/proc} that can be
-used to examine the image of a running process using file-system
-subroutines. If @value{GDBN} is configured for an operating system with
-this facility, the command @code{info proc} is available to report on
-several kinds of information about the process running your program.
-@code{info proc} works only on SVR4 systems that include the
-@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix,
-and Unixware, but not HP-UX or Linux, for example.
+@node H8/300
+@subsection Hitachi H8/300
@table @code
-@kindex info proc
-@item info proc
-Summarize available information about the process.
-@kindex info proc mappings
-@item info proc mappings
-Report on the address ranges accessible in the program, with information
-on whether your program may read, write, or execute each range.
-@ignore
-@comment These sub-options of 'info proc' were not included when
-@comment procfs.c was re-written. Keep their descriptions around
-@comment against the day when someone finds the time to put them back in.
-@kindex info proc times
-@item info proc times
-Starting time, user CPU time, and system CPU time for your program and
-its children.
+@kindex target hms@r{, with H8/300}
+@item target hms @var{dev}
+A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
+Use special commands @code{device} and @code{speed} to control the serial
+line and the communications speed used.
-@kindex info proc id
-@item info proc id
-Report on the process IDs related to your program: its own process ID,
-the ID of its parent, the process group ID, and the session ID.
+@kindex target e7000@r{, with H8/300}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
-@kindex info proc status
-@item info proc status
-General information on the state of the process. If the process is
-stopped, this report includes the reason for stopping, and any signal
-received.
+@kindex target sh3@r{, with H8/300}
+@kindex target sh3e@r{, with H8/300}
+@item target sh3 @var{dev}
+@itemx target sh3e @var{dev}
+Hitachi SH-3 and SH-3E target systems.
-@item info proc all
-Show all the above information about the process.
-@end ignore
@end table
-@node DJGPP Native
-@subsection Features for Debugging @sc{djgpp} Programs
-@cindex @sc{djgpp} debugging
-@cindex native @sc{djgpp} debugging
-@cindex MS-DOS-specific commands
-
-@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and
-MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
-that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
-top of real-mode DOS systems and their emulations.
+@cindex download to H8/300 or H8/500
+@cindex H8/300 or H8/500 download
+@cindex download to Hitachi SH
+@cindex Hitachi SH download
+When you select remote debugging to a Hitachi SH, H8/300, or H8/500
+board, the @code{load} command downloads your program to the Hitachi
+board and also opens it as the current executable target for
+@value{GDBN} on your host (like the @code{file} command).
-@value{GDBN} supports native debugging of @sc{djgpp} programs, and
-defines a few commands specific to the @sc{djgpp} port. This
-subsection describes those commands.
+@value{GDBN} needs to know these things to talk to your
+Hitachi SH, H8/300, or H8/500:
-@table @code
-@kindex info dos
-@item info dos
-This is a prefix of @sc{djgpp}-specific commands which print
-information about the target system and important OS structures.
+@enumerate
+@item
+that you want to use @samp{target hms}, the remote debugging interface
+for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
+emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
+the default when @value{GDBN} is configured specifically for the Hitachi SH,
+H8/300, or H8/500.)
-@kindex sysinfo
-@cindex MS-DOS system info
-@cindex free memory information (MS-DOS)
-@item info dos sysinfo
-This command displays assorted information about the underlying
-platform: the CPU type and features, the OS version and flavor, the
-DPMI version, and the available conventional and DPMI memory.
+@item
+what serial device connects your host to your Hitachi board (the first
+serial device available on your host is the default).
-@cindex GDT
-@cindex LDT
-@cindex IDT
-@cindex segment descriptor tables
-@cindex descriptor tables display
-@item info dos gdt
-@itemx info dos ldt
-@itemx info dos idt
-These 3 commands display entries from, respectively, Global, Local,
-and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
-tables are data structures which store a descriptor for each segment
-that is currently in use. The segment's selector is an index into a
-descriptor table; the table entry for that index holds the
-descriptor's base address and limit, and its attributes and access
-rights.
+@item
+what speed to use over the serial device.
+@end enumerate
-A typical @sc{djgpp} program uses 3 segments: a code segment, a data
-segment (used for both data and the stack), and a DOS segment (which
-allows access to DOS/BIOS data structures and absolute addresses in
-conventional memory). However, the DPMI host will usually define
-additional segments in order to support the DPMI environment.
+@menu
+* Hitachi Boards:: Connecting to Hitachi boards.
+* Hitachi ICE:: Using the E7000 In-Circuit Emulator.
+* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
+@end menu
-@cindex garbled pointers
-These commands allow to display entries from the descriptor tables.
-Without an argument, all entries from the specified table are
-displayed. An argument, which should be an integer expression, means
-display a single entry whose index is given by the argument. For
-example, here's a convenient way to display information about the
-debugged program's data segment:
+@node Hitachi Boards
+@subsubsection Connecting to Hitachi boards
-@smallexample
-@exdent @code{(@value{GDBP}) info dos ldt $ds}
-@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
-@end smallexample
+@c only for Unix hosts
+@kindex device
+@cindex serial device, Hitachi micros
+Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
+need to explicitly set the serial device. The default @var{port} is the
+first available port on your host. This is only necessary on Unix
+hosts, where it is typically something like @file{/dev/ttya}.
-@noindent
-This comes in handy when you want to see whether a pointer is outside
-the data segment's limit (i.e.@: @dfn{garbled}).
+@kindex speed
+@cindex serial line speed, Hitachi micros
+@code{@value{GDBN}} has another special command to set the communications
+speed: @samp{speed @var{bps}}. This command also is only used from Unix
+hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
+the DOS @code{mode} command (for instance,
+@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
-@cindex page tables display (MS-DOS)
-@item info dos pde
-@itemx info dos pte
-These two commands display entries from, respectively, the Page
-Directory and the Page Tables. Page Directories and Page Tables are
-data structures which control how virtual memory addresses are mapped
-into physical addresses. A Page Table includes an entry for every
-page of memory that is mapped into the program's address space; there
-may be several Page Tables, each one holding up to 4096 entries. A
-Page Directory has up to 4096 entries, one each for every Page Table
-that is currently in use.
+The @samp{device} and @samp{speed} commands are available only when you
+use a Unix host to debug your Hitachi microprocessor programs. If you
+use a DOS host,
+@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
+called @code{asynctsr} to communicate with the development board
+through a PC serial port. You must also use the DOS @code{mode} command
+to set up the serial port on the DOS side.
-Without an argument, @kbd{info dos pde} displays the entire Page
-Directory, and @kbd{info dos pte} displays all the entries in all of
-the Page Tables. An argument, an integer expression, given to the
-@kbd{info dos pde} command means display only that entry from the Page
-Directory table. An argument given to the @kbd{info dos pte} command
-means display entries from a single Page Table, the one pointed to by
-the specified entry in the Page Directory.
+The following sample session illustrates the steps needed to start a
+program under @value{GDBN} control on an H8/300. The example uses a
+sample H8/300 program called @file{t.x}. The procedure is the same for
+the Hitachi SH and the H8/500.
-@cindex direct memory access (DMA) on MS-DOS
-These commands are useful when your program uses @dfn{DMA} (Direct
-Memory Access), which needs physical addresses to program the DMA
-controller.
+First hook up your development board. In this example, we use a
+board attached to serial port @code{COM2}; if you use a different serial
+port, substitute its name in the argument of the @code{mode} command.
+When you call @code{asynctsr}, the auxiliary comms program used by the
+debugger, you give it just the numeric part of the serial port's name;
+for example, @samp{asyncstr 2} below runs @code{asyncstr} on
+@code{COM2}.
-These commands are supported only with some DPMI servers.
+@smallexample
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
-@cindex physical address from linear address
-@item info dos address-pte @var{addr}
-This command displays the Page Table entry for a specified linear
-address. The argument linear address @var{addr} should already have the
-appropriate segment's base address added to it, because this command
-accepts addresses which may belong to @emph{any} segment. For
-example, here's how to display the Page Table entry for the page where
-the variable @code{i} is stored:
+Resident portion of MODE loaded
-@smallexample
-@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
-@exdent @code{Page Table entry for address 0x11a00d30:}
-@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
-@end smallexample
+COM2: 9600, n, 8, 1, p
-@noindent
-This says that @code{i} is stored at offset @code{0xd30} from the page
-whose physical base address is @code{0x02698000}, and prints all the
-attributes of that page.
+@end smallexample
-Note that you must cast the addresses of variables to a @code{char *},
-since otherwise the value of @code{__djgpp_base_address}, the base
-address of all variables and functions in a @sc{djgpp} program, will
-be added using the rules of C pointer arithmetics: if @code{i} is
-declared an @code{int}, @value{GDBN} will add 4 times the value of
-@code{__djgpp_base_address} to the address of @code{i}.
+@quotation
+@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
+@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
+disable it, or even boot without it, to use @code{asynctsr} to control
+your development board.
+@end quotation
-Here's another example, it displays the Page Table entry for the
-transfer buffer:
+@kindex target hms@r{, and serial protocol}
+Now that serial communications are set up, and the development board is
+connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
+the name of your program as the argument. @code{@value{GDBN}} prompts
+you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
+commands to begin your debugging session: @samp{target hms} to specify
+cross-debugging to the Hitachi board, and the @code{load} command to
+download your program to the board. @code{load} displays the names of
+the program's sections, and a @samp{*} for each 2K of data downloaded.
+(If you want to refresh @value{GDBN} data on symbols or on the
+executable file without downloading, use the @value{GDBN} commands
+@code{file} or @code{symbol-file}. These commands, and @code{load}
+itself, are described in @ref{Files,,Commands to specify files}.)
@smallexample
-@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
-@exdent @code{Page Table entry for address 0x29110:}
-@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
+(eg-C:\H8300\TEST) @value{GDBP} t.x
+@value{GDBN} is free software and you are welcome to distribute copies
+ of it under certain conditions; type "show copying" to see
+ the conditions.
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
+for details.
+@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
+(@value{GDBP}) target hms
+Connected to remote H8/300 HMS system.
+(@value{GDBP}) load t.x
+.text : 0x8000 .. 0xabde ***********
+.data : 0xabde .. 0xad30 *
+.stack : 0xf000 .. 0xf014 *
@end smallexample
-@noindent
-(The @code{+ 3} offset is because the transfer buffer's address is the
-3rd member of the @code{_go32_info_block} structure.) The output of
-this command clearly shows that addresses in conventional memory are
-mapped 1:1, i.e.@: the physical and linear addresses are identical.
-
-This command is supported only with some DPMI servers.
-@end table
+At this point, you're ready to run or debug your program. From here on,
+you can use all the usual @value{GDBN} commands. The @code{break} command
+sets breakpoints; the @code{run} command starts your program;
+@code{print} or @code{x} display data; the @code{continue} command
+resumes execution after stopping at a breakpoint. You can use the
+@code{help} command at any time to find out more about @value{GDBN} commands.
-@node Embedded OS
-@section Embedded Operating Systems
+Remember, however, that @emph{operating system} facilities aren't
+available on your development board; for example, if your program hangs,
+you can't send an interrupt---but you can press the @sc{reset} switch!
-This section describes configurations involving the debugging of
-embedded operating systems that are available for several different
-architectures.
+Use the @sc{reset} button on the development board
+@itemize @bullet
+@item
+to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
+no way to pass an interrupt signal to the development board); and
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
+@item
+to return to the @value{GDBN} command prompt after your program finishes
+normally. The communications protocol provides no other way for @value{GDBN}
+to detect program completion.
+@end itemize
-@value{GDBN} includes the ability to debug programs running on
-various real-time operating systems.
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
+development board as a ``normal exit'' of your program.
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
-@cindex VxWorks
+@kindex target e7000@r{, with Hitachi ICE}
+You can use the E7000 in-circuit emulator to develop code for either the
+Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
+e7000} command to connect @value{GDBN} to your E7000:
@table @code
+@item target e7000 @var{port} @var{speed}
+Use this form if your E7000 is connected to a serial port. The
+@var{port} argument identifies what serial port to use (for example,
+@samp{com2}). The third argument is the line speed in bits per second
+(for example, @samp{9600}).
-@kindex target vxworks
-@item target vxworks @var{machinename}
-A VxWorks system, attached via TCP/IP. The argument @var{machinename}
-is the target system's machine name or IP address.
-
+@item target e7000 @var{hostname}
+If your E7000 is installed as a host on a TCP/IP network, you can just
+specify its hostname; @value{GDBN} uses @code{telnet} to connect.
@end table
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
-@value{GDBN} enables developers to spawn and debug tasks running on networked
-VxWorks targets from a Unix host. Already-running tasks spawned from
-the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
-both the Unix host and on the VxWorks target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
-installed with the name @code{vxgdb}, to distinguish it from a
-@value{GDBN} for debugging programs on the host itself.)
+Some @value{GDBN} commands are available only for the H8/300:
@table @code
-@item VxWorks-timeout @var{args}
-@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
-of a thin network line.
+
+@kindex set machine
+@kindex show machine
+@item set machine h8300
+@itemx set machine h8300h
+Condition @value{GDBN} for one of the two variants of the H8/300
+architecture with @samp{set machine}. You can use @samp{show machine}
+to check which variant is currently in effect.
+
@end table
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
+@node H8/500
+@subsection H8/500
-@kindex INCLUDE_RDB
-To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
-to include the remote debugging interface routines in the VxWorks
-library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
-VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
-kernel. The resulting kernel contains @file{rdb.a}, and spawns the
-source debugging task @code{tRdbTask} when VxWorks is booted. For more
-information on configuring and remaking VxWorks, see the manufacturer's
-manual.
-@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
+@table @code
+
+@kindex set memory @var{mod}
+@cindex memory models, H8/500
+@item set memory @var{mod}
+@itemx show memory
+Specify which H8/500 memory model (@var{mod}) you are using with
+@samp{set memory}; check which memory model is in effect with @samp{show
+memory}. The accepted values for @var{mod} are @code{small},
+@code{big}, @code{medium}, and @code{compact}.
+
+@end table
-Once you have included @file{rdb.a} in your VxWorks system image and set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
-@code{vxgdb}, depending on your installation).
+@node i960
+@subsection Intel i960
-@value{GDBN} comes up showing the prompt:
+@table @code
-@example
-(vxgdb)
-@end example
+@kindex target mon960
+@item target mon960 @var{dev}
+MON960 monitor for Intel i960.
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
+@kindex target nindy
+@item target nindy @var{devicename}
+An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
+the name of the serial device to use for the connection, e.g.
+@file{/dev/ttya}.
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
+@end table
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
-network. To connect to a target whose host name is ``@code{tt}'', type:
+@cindex Nindy
+@cindex i960
+@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
+@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
+tell @value{GDBN} how to connect to the 960 in several ways:
-@example
-(vxgdb) target vxworks tt
-@end example
+@itemize @bullet
+@item
+Through command line options specifying serial port, version of the
+Nindy protocol, and communications speed;
-@need 750
-@value{GDBN} displays messages like these:
+@item
+By responding to a prompt on startup;
-@smallexample
-Attaching remote machine across net...
-Connected to tt.
-@end smallexample
+@item
+By using the @code{target} command at any point during your @value{GDBN}
+session. @xref{Target Commands, ,Commands for managing targets}.
-@need 1000
-@value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted. @value{GDBN} locates
-these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your program's environment}); if it fails
-to find an object file, it displays a message such as:
+@end itemize
-@example
-prog.o: No such file or directory.
-@end example
+@cindex download to Nindy-960
+With the Nindy interface to an Intel 960 board, @code{load}
+downloads @var{filename} to the 960 as well as adding its symbols in
+@value{GDBN}.
-When this happens, add the appropriate directory to the search path with
-the @value{GDBN} command @code{path}, and execute the @code{target}
-command again.
+@menu
+* Nindy Startup:: Startup with Nindy
+* Nindy Options:: Options for Nindy
+* Nindy Reset:: Nindy reset command
+@end menu
-@node VxWorks Download
-@subsubsection VxWorks download
+@node Nindy Startup
+@subsubsection Startup with Nindy
-@cindex download to VxWorks
-If you have connected to the VxWorks target and you want to debug an
-object that has not yet been loaded, you can use the @value{GDBN}
-@code{load} command to download a file from Unix to VxWorks
-incrementally. The object file given as an argument to the @code{load}
-command is actually opened twice: first by the VxWorks target in order
-to download the code, then by @value{GDBN} in order to read the symbol
-table. This can lead to problems if the current working directories on
-the two systems differ. If both systems have NFS mounted the same
-filesystems, you can avoid these problems by using absolute paths.
-Otherwise, it is simplest to set the working directory on both systems
-to the directory in which the object file resides, and then to reference
-the file by its name, without any path. For instance, a program
-@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
-and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
-program, type this on VxWorks:
+If you simply start @code{@value{GDBP}} without using any command-line
+options, you are prompted for what serial port to use, @emph{before} you
+reach the ordinary @value{GDBN} prompt:
-@example
--> cd "@var{vxpath}/vw/demo/rdb"
-@end example
+@smallexample
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
+@end smallexample
@noindent
-Then, in @value{GDBN}, type:
+Respond to the prompt with whatever suffix (after @samp{/dev/tty})
+identifies the serial port you want to use. You can, if you choose,
+simply start up with no Nindy connection by responding to the prompt
+with an empty line. If you do this and later wish to attach to Nindy,
+use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
-@example
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end example
+@node Nindy Options
+@subsubsection Options for Nindy
-@value{GDBN} displays a response similar to this:
+These are the startup options for beginning your @value{GDBN} session with a
+Nindy-960 board attached:
-@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
-@end smallexample
+@table @code
+@item -r @var{port}
+Specify the serial port name of a serial interface to be used to connect
+to the target system. This option is only available when @value{GDBN} is
+configured for the Intel 960 target architecture. You may specify
+@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
+device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
+suffix for a specific @code{tty} (e.g. @samp{-r a}).
-You can also use the @code{load} command to reload an object module
-after editing and recompiling the corresponding source file. Note that
-this makes @value{GDBN} delete all currently-defined breakpoints,
-auto-displays, and convenience variables, and to clear the value
-history. (This is necessary in order to preserve the integrity of
-debugger's data structures that reference the target system's symbol
-table.)
+@item -O
+(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
+the ``old'' Nindy monitor protocol to connect to the target system.
+This option is only available when @value{GDBN} is configured for the Intel 960
+target architecture.
-@node VxWorks Attach
-@subsubsection Running tasks
+@quotation
+@emph{Warning:} if you specify @samp{-O}, but are actually trying to
+connect to a target system that expects the newer protocol, the connection
+fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
+attempts to reconnect at several different line speeds. You can abort
+this process with an interrupt.
+@end quotation
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
+@item -brk
+Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
+system, in an attempt to reset it, before connecting to a Nindy target.
-@example
-(vxgdb) attach @var{task}
-@end example
+@quotation
+@emph{Warning:} Many target systems do not have the hardware that this
+requires; it only works with a few boards.
+@end quotation
+@end table
-@noindent
-where @var{task} is the VxWorks hexadecimal task ID. The task can be running
-or suspended when you attach to it. Running tasks are suspended at
-the time of attachment.
+The standard @samp{-b} option controls the line speed used on the serial
+port.
-@node Embedded Processors
-@section Embedded Processors
+@c @group
+@node Nindy Reset
+@subsubsection Nindy reset command
-This section goes into details specific to particular embedded
-configurations.
+@table @code
+@item reset
+@kindex reset
+For a Nindy target, this command sends a ``break'' to the remote target
+system; this is only useful if the target has been equipped with a
+circuit to perform a hard reset (or some other interesting action) when
+a break is detected.
+@end table
+@c @end group
+@node M32R/D
+@subsection Mitsubishi M32R/D
-@c OBSOLETE * A29K Embedded:: AMD A29K Embedded
-@menu
-* ARM:: ARM
-* H8/300:: Hitachi H8/300
-* H8/500:: Hitachi H8/500
-* i960:: Intel i960
-* M32R/D:: Mitsubishi M32R/D
-* M68K:: Motorola M68K
-* M88K:: Motorola M88K
-* MIPS Embedded:: MIPS Embedded
-* PA:: HP PA Embedded
-* PowerPC: PowerPC
-* SH:: Hitachi SH
-* Sparclet:: Tsqware Sparclet
-* Sparclite:: Fujitsu Sparclite
-* ST2000:: Tandem ST2000
-* Z8000:: Zilog Z8000
-@end menu
+@table @code
-@c OBSOLETE @node A29K Embedded
-@c OBSOLETE @subsection AMD A29K Embedded
-@c OBSOLETE
-@c OBSOLETE @menu
-@c OBSOLETE * A29K UDI::
-@c OBSOLETE * A29K EB29K::
-@c OBSOLETE * Comms (EB29K):: Communications setup
-@c OBSOLETE * gdb-EB29K:: EB29K cross-debugging
-@c OBSOLETE * Remote Log:: Remote log
-@c OBSOLETE @end menu
-@c OBSOLETE
-@c OBSOLETE @table @code
-@c OBSOLETE
-@c OBSOLETE @kindex target adapt
-@c OBSOLETE @item target adapt @var{dev}
-@c OBSOLETE Adapt monitor for A29K.
-@c OBSOLETE
-@c OBSOLETE @kindex target amd-eb
-@c OBSOLETE @item target amd-eb @var{dev} @var{speed} @var{PROG}
-@c OBSOLETE @cindex AMD EB29K
-@c OBSOLETE Remote PC-resident AMD EB29K board, attached over serial lines.
-@c OBSOLETE @var{dev} is the serial device, as for @code{target remote};
-@c OBSOLETE @var{speed} allows you to specify the linespeed; and @var{PROG} is the
-@c OBSOLETE name of the program to be debugged, as it appears to DOS on the PC.
-@c OBSOLETE @xref{A29K EB29K, ,EBMON protocol for AMD29K}.
-@c OBSOLETE
-@c OBSOLETE @end table
-@c OBSOLETE
-@c OBSOLETE @node A29K UDI
-@c OBSOLETE @subsubsection A29K UDI
-@c OBSOLETE
-@c OBSOLETE @cindex UDI
-@c OBSOLETE @cindex AMD29K via UDI
-@c OBSOLETE
-@c OBSOLETE @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
-@c OBSOLETE protocol for debugging the a29k processor family. To use this
-@c OBSOLETE configuration with AMD targets running the MiniMON monitor, you need the
-@c OBSOLETE program @code{MONTIP}, available from AMD at no charge. You can also
-@c OBSOLETE use @value{GDBN} with the UDI-conformant a29k simulator program
-@c OBSOLETE @code{ISSTIP}, also available from AMD.
-@c OBSOLETE
-@c OBSOLETE @table @code
-@c OBSOLETE @item target udi @var{keyword}
-@c OBSOLETE @kindex udi
-@c OBSOLETE Select the UDI interface to a remote a29k board or simulator, where
-@c OBSOLETE @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
-@c OBSOLETE This file contains keyword entries which specify parameters used to
-@c OBSOLETE connect to a29k targets. If the @file{udi_soc} file is not in your
-@c OBSOLETE working directory, you must set the environment variable @samp{UDICONF}
-@c OBSOLETE to its pathname.
-@c OBSOLETE @end table
-@c OBSOLETE
-@c OBSOLETE @node A29K EB29K
-@c OBSOLETE @subsubsection EBMON protocol for AMD29K
-@c OBSOLETE
-@c OBSOLETE @cindex EB29K board
-@c OBSOLETE @cindex running 29K programs
-@c OBSOLETE
-@c OBSOLETE AMD distributes a 29K development board meant to fit in a PC, together
-@c OBSOLETE with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
-@c OBSOLETE term, this development system is called the ``EB29K''. To use
-@c OBSOLETE @value{GDBN} from a Unix system to run programs on the EB29K board, you
-@c OBSOLETE must first connect a serial cable between the PC (which hosts the EB29K
-@c OBSOLETE board) and a serial port on the Unix system. In the following, we
-@c OBSOLETE assume you've hooked the cable between the PC's @file{COM1} port and
-@c OBSOLETE @file{/dev/ttya} on the Unix system.
-@c OBSOLETE
-@c OBSOLETE @node Comms (EB29K)
-@c OBSOLETE @subsubsection Communications setup
-@c OBSOLETE
-@c OBSOLETE The next step is to set up the PC's port, by doing something like this
-@c OBSOLETE in DOS on the PC:
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE C:\> MODE com1:9600,n,8,1,none
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE @noindent
-@c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600
-@c OBSOLETE bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
-@c OBSOLETE you must match the communications parameters when establishing the Unix
-@c OBSOLETE end of the connection as well.
-@c OBSOLETE @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
-@c OBSOLETE @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
-@c OBSOLETE @c
-@c OBSOLETE @c It's optional, but it's unwise to omit it: who knows what is the
-@c OBSOLETE @c default value set when the DOS machines boots? "No retry" means that
-@c OBSOLETE @c the DOS serial device driver won't retry the operation if it fails;
-@c OBSOLETE @c I understand that this is needed because the GDB serial protocol
-@c OBSOLETE @c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
-@c OBSOLETE
-@c OBSOLETE To give control of the PC to the Unix side of the serial line, type
-@c OBSOLETE the following at the DOS console:
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE C:\> CTTY com1
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE @noindent
-@c OBSOLETE (Later, if you wish to return control to the DOS console, you can use
-@c OBSOLETE the command @code{CTTY con}---but you must send it over the device that
-@c OBSOLETE had control, in our example over the @file{COM1} serial line.)
-@c OBSOLETE
-@c OBSOLETE From the Unix host, use a communications program such as @code{tip} or
-@c OBSOLETE @code{cu} to communicate with the PC; for example,
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE cu -s 9600 -l /dev/ttya
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE @noindent
-@c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the
-@c OBSOLETE serial port to use. If you use @code{tip} instead, your command line
-@c OBSOLETE may look something like the following:
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE tip -9600 /dev/ttya
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE @noindent
-@c OBSOLETE Your system may require a different name where we show
-@c OBSOLETE @file{/dev/ttya} as the argument to @code{tip}. The communications
-@c OBSOLETE parameters, including which port to use, are associated with the
-@c OBSOLETE @code{tip} argument in the ``remote'' descriptions file---normally the
-@c OBSOLETE system table @file{/etc/remote}.
-@c OBSOLETE @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
-@c OBSOLETE @c the DOS side's comms setup? cu can support -o (odd
-@c OBSOLETE @c parity), -e (even parity)---apparently no settings for no parity or
-@c OBSOLETE @c for character size. Taken from stty maybe...? John points out tip
-@c OBSOLETE @c can set these as internal variables, eg ~s parity=none; man stty
-@c OBSOLETE @c suggests that it *might* work to stty these options with stdin or
-@c OBSOLETE @c stdout redirected... ---doc@cygnus.com, 25feb91
-@c OBSOLETE @c
-@c OBSOLETE @c There's nothing to be done for the "none" part of the DOS MODE
-@c OBSOLETE @c command. The rest of the parameters should be matched by the
-@c OBSOLETE @c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
-@c OBSOLETE
-@c OBSOLETE @kindex EBMON
-@c OBSOLETE Using the @code{tip} or @code{cu} connection, change the DOS working
-@c OBSOLETE directory to the directory containing a copy of your 29K program, then
-@c OBSOLETE start the PC program @code{EBMON} (an EB29K control program supplied
-@c OBSOLETE with your board by AMD). You should see an initial display from
-@c OBSOLETE @code{EBMON} similar to the one that follows, ending with the
-@c OBSOLETE @code{EBMON} prompt @samp{#}---
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE C:\> G:
-@c OBSOLETE
-@c OBSOLETE G:\> CD \usr\joe\work29k
-@c OBSOLETE
-@c OBSOLETE G:\USR\JOE\WORK29K> EBMON
-@c OBSOLETE Am29000 PC Coprocessor Board Monitor, version 3.0-18
-@c OBSOLETE Copyright 1990 Advanced Micro Devices, Inc.
-@c OBSOLETE Written by Gibbons and Associates, Inc.
-@c OBSOLETE
-@c OBSOLETE Enter '?' or 'H' for help
-@c OBSOLETE
-@c OBSOLETE PC Coprocessor Type = EB29K
-@c OBSOLETE I/O Base = 0x208
-@c OBSOLETE Memory Base = 0xd0000
-@c OBSOLETE
-@c OBSOLETE Data Memory Size = 2048KB
-@c OBSOLETE Available I-RAM Range = 0x8000 to 0x1fffff
-@c OBSOLETE Available D-RAM Range = 0x80002000 to 0x801fffff
-@c OBSOLETE
-@c OBSOLETE PageSize = 0x400
-@c OBSOLETE Register Stack Size = 0x800
-@c OBSOLETE Memory Stack Size = 0x1800
-@c OBSOLETE
-@c OBSOLETE CPU PRL = 0x3
-@c OBSOLETE Am29027 Available = No
-@c OBSOLETE Byte Write Available = Yes
-@c OBSOLETE
-@c OBSOLETE # ~.
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by
-@c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
-@c OBSOLETE running, ready for @value{GDBN} to take over.
-@c OBSOLETE
-@c OBSOLETE For this example, we've assumed what is probably the most convenient
-@c OBSOLETE way to make sure the same 29K program is on both the PC and the Unix
-@c OBSOLETE system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
-@c OBSOLETE PC as a file system on the Unix host. If you do not have PC/NFS or
-@c OBSOLETE something similar connecting the two systems, you must arrange some
-@c OBSOLETE other way---perhaps floppy-disk transfer---of getting the 29K program
-@c OBSOLETE from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
-@c OBSOLETE serial line.
-@c OBSOLETE
-@c OBSOLETE @node gdb-EB29K
-@c OBSOLETE @subsubsection EB29K cross-debugging
-@c OBSOLETE
-@c OBSOLETE Finally, @code{cd} to the directory containing an image of your 29K
-@c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the
-@c OBSOLETE name of your 29K program:
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE cd /usr/joe/work29k
-@c OBSOLETE @value{GDBP} myfoo
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE @need 500
-@c OBSOLETE Now you can use the @code{target} command:
-@c OBSOLETE
-@c OBSOLETE @example
-@c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO
-@c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
-@c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is
-@c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
-@c OBSOLETE @end example
-@c OBSOLETE
-@c OBSOLETE @noindent
-@c OBSOLETE In this example, we've assumed your program is in a file called
-@c OBSOLETE @file{myfoo}. Note that the filename given as the last argument to
-@c OBSOLETE @code{target amd-eb} should be the name of the program as it appears to DOS.
-@c OBSOLETE In our example this is simply @code{MYFOO}, but in general it can include
-@c OBSOLETE a DOS path, and depending on your transfer mechanism may not resemble
-@c OBSOLETE the name on the Unix side.
-@c OBSOLETE
-@c OBSOLETE At this point, you can set any breakpoints you wish; when you are ready
-@c OBSOLETE to see your program run on the 29K board, use the @value{GDBN} command
-@c OBSOLETE @code{run}.
-@c OBSOLETE
-@c OBSOLETE To stop debugging the remote program, use the @value{GDBN} @code{detach}
-@c OBSOLETE command.
-@c OBSOLETE
-@c OBSOLETE To return control of the PC to its console, use @code{tip} or @code{cu}
-@c OBSOLETE once again, after your @value{GDBN} session has concluded, to attach to
-@c OBSOLETE @code{EBMON}. You can then type the command @code{q} to shut down
-@c OBSOLETE @code{EBMON}, returning control to the DOS command-line interpreter.
-@c OBSOLETE Type @kbd{CTTY con} to return command input to the main DOS console,
-@c OBSOLETE and type @kbd{~.} to leave @code{tip} or @code{cu}.
-@c OBSOLETE
-@c OBSOLETE @node Remote Log
-@c OBSOLETE @subsubsection Remote log
-@c OBSOLETE @cindex @file{eb.log}, a log file for EB29K
-@c OBSOLETE @cindex log file for EB29K
-@c OBSOLETE
-@c OBSOLETE The @code{target amd-eb} command creates a file @file{eb.log} in the
-@c OBSOLETE current working directory, to help debug problems with the connection.
-@c OBSOLETE @file{eb.log} records all the output from @code{EBMON}, including echoes
-@c OBSOLETE of the commands sent to it. Running @samp{tail -f} on this file in
-@c OBSOLETE another window often helps to understand trouble with @code{EBMON}, or
-@c OBSOLETE unexpected events on the PC side of the connection.
+@kindex target m32r
+@item target m32r @var{dev}
+Mitsubishi M32R/D ROM monitor.
-@node ARM
-@subsection ARM
+@end table
+
+@node M68K
+@subsection M68k
+
+The Motorola m68k configuration includes ColdFire support, and
+target command for the following ROM monitors.
@table @code
-@kindex target rdi
-@item target rdi @var{dev}
-ARM Angel monitor, via RDI library interface to ADP protocol. You may
-use this target to communicate with both boards running the Angel
-monitor, or with the EmbeddedICE JTAG debug device.
+@kindex target abug
+@item target abug @var{dev}
+ABug ROM monitor for M68K.
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
+@kindex target cpu32bug
+@item target cpu32bug @var{dev}
+CPU32BUG monitor, running on a CPU32 (M68K) board.
+
+@kindex target dbug
+@item target dbug @var{dev}
+dBUG ROM monitor for Motorola ColdFire.
+
+@kindex target est
+@item target est @var{dev}
+EST-300 ICE monitor, running on a CPU32 (M68K) board.
+
+@kindex target rom68k
+@item target rom68k @var{dev}
+ROM 68K monitor, running on an M68K IDP board.
@end table
-@node H8/300
-@subsection Hitachi H8/300
+If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
+instead have only a single special target command:
@table @code
-@kindex target hms@r{, with H8/300}
-@item target hms @var{dev}
-A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
-Use special commands @code{device} and @code{speed} to control the serial
-line and the communications speed used.
+@kindex target es1800
+@item target es1800 @var{dev}
+ES-1800 emulator for M68K.
-@kindex target e7000@r{, with H8/300}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi H8 and SH.
+@end table
-@kindex target sh3@r{, with H8/300}
-@kindex target sh3e@r{, with H8/300}
-@item target sh3 @var{dev}
-@itemx target sh3e @var{dev}
-Hitachi SH-3 and SH-3E target systems.
+[context?]
+
+@table @code
+
+@kindex target rombug
+@item target rombug @var{dev}
+ROMBUG ROM monitor for OS/9000.
@end table
-@cindex download to H8/300 or H8/500
-@cindex H8/300 or H8/500 download
-@cindex download to Hitachi SH
-@cindex Hitachi SH download
-When you select remote debugging to a Hitachi SH, H8/300, or H8/500
-board, the @code{load} command downloads your program to the Hitachi
-board and also opens it as the current executable target for
-@value{GDBN} on your host (like the @code{file} command).
+@c OBSOLETE @node M88K
+@c OBSOLETE @subsection M88K
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE
+@c OBSOLETE @kindex target bug
+@c OBSOLETE @item target bug @var{dev}
+@c OBSOLETE BUG monitor, running on a MVME187 (m88k) board.
+@c OBSOLETE
+@c OBSOLETE @end table
-@value{GDBN} needs to know these things to talk to your
-Hitachi SH, H8/300, or H8/500:
+@node MIPS Embedded
+@subsection MIPS Embedded
-@enumerate
-@item
-that you want to use @samp{target hms}, the remote debugging interface
-for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
-emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
-the default when @value{GDBN} is configured specifically for the Hitachi SH,
-H8/300, or H8/500.)
+@cindex MIPS boards
+@value{GDBN} can use the MIPS remote debugging protocol to talk to a
+MIPS board attached to a serial line. This is available when
+you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
-@item
-what serial device connects your host to your Hitachi board (the first
-serial device available on your host is the default).
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
-@item
-what speed to use over the serial device.
-@end enumerate
+@table @code
+@item target mips @var{port}
+@kindex target mips @var{port}
+To run a program on the board, start up @code{@value{GDBP}} with the
+name of your program as the argument. To connect to the board, use the
+command @samp{target mips @var{port}}, where @var{port} is the name of
+the serial port connected to the board. If the program has not already
+been downloaded to the board, you may use the @code{load} command to
+download it. You can then use all the usual @value{GDBN} commands.
-@menu
-* Hitachi Boards:: Connecting to Hitachi boards.
-* Hitachi ICE:: Using the E7000 In-Circuit Emulator.
-* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
-@end menu
+For example, this sequence connects to the target board through a serial
+port, and loads and runs a program called @var{prog} through the
+debugger:
-@node Hitachi Boards
-@subsubsection Connecting to Hitachi boards
+@smallexample
+host$ @value{GDBP} @var{prog}
+@value{GDBN} is free software and @dots{}
+(@value{GDBP}) target mips /dev/ttyb
+(@value{GDBP}) load @var{prog}
+(@value{GDBP}) run
+@end smallexample
-@c only for Unix hosts
-@kindex device
-@cindex serial device, Hitachi micros
-Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
-need to explicitly set the serial device. The default @var{port} is the
-first available port on your host. This is only necessary on Unix
-hosts, where it is typically something like @file{/dev/ttya}.
+@item target mips @var{hostname}:@var{portnumber}
+On some @value{GDBN} host configurations, you can specify a TCP
+connection (for instance, to a serial line managed by a terminal
+concentrator) instead of a serial port, using the syntax
+@samp{@var{hostname}:@var{portnumber}}.
-@kindex speed
-@cindex serial line speed, Hitachi micros
-@code{@value{GDBN}} has another special command to set the communications
-speed: @samp{speed @var{bps}}. This command also is only used from Unix
-hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
-the DOS @code{mode} command (for instance,
-@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
+@item target pmon @var{port}
+@kindex target pmon @var{port}
+PMON ROM monitor.
-The @samp{device} and @samp{speed} commands are available only when you
-use a Unix host to debug your Hitachi microprocessor programs. If you
-use a DOS host,
-@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
-called @code{asynctsr} to communicate with the development board
-through a PC serial port. You must also use the DOS @code{mode} command
-to set up the serial port on the DOS side.
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+NEC's DDB variant of PMON for Vr4300.
-The following sample session illustrates the steps needed to start a
-program under @value{GDBN} control on an H8/300. The example uses a
-sample H8/300 program called @file{t.x}. The procedure is the same for
-the Hitachi SH and the H8/500.
+@item target lsi @var{port}
+@kindex target lsi @var{port}
+LSI variant of PMON.
-First hook up your development board. In this example, we use a
-board attached to serial port @code{COM2}; if you use a different serial
-port, substitute its name in the argument of the @code{mode} command.
-When you call @code{asynctsr}, the auxiliary comms program used by the
-debugger, you give it just the numeric part of the serial port's name;
-for example, @samp{asyncstr 2} below runs @code{asyncstr} on
-@code{COM2}.
+@kindex target r3900
+@item target r3900 @var{dev}
+Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-@example
-C:\H8300\TEST> asynctsr 2
-C:\H8300\TEST> mode com2:9600,n,8,1,p
+@kindex target array
+@item target array @var{dev}
+Array Tech LSI33K RAID controller board.
-Resident portion of MODE loaded
+@end table
-COM2: 9600, n, 8, 1, p
-@end example
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
-@quotation
-@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
-@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
-disable it, or even boot without it, to use @code{asynctsr} to control
-your development board.
-@end quotation
+@table @code
+@item set processor @var{args}
+@itemx show processor
+@kindex set processor @var{args}
+@kindex show processor
+Use the @code{set processor} command to set the type of MIPS
+processor when you want to access processor-type-specific registers.
+For example, @code{set processor @var{r3041}} tells @value{GDBN}
+to use the CPU registers appropriate for the 3041 chip.
+Use the @code{show processor} command to see what MIPS processor @value{GDBN}
+is using. Use the @code{info reg} command to see what registers
+@value{GDBN} is using.
-@kindex target hms@r{, and serial protocol}
-Now that serial communications are set up, and the development board is
-connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
-the name of your program as the argument. @code{@value{GDBN}} prompts
-you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
-commands to begin your debugging session: @samp{target hms} to specify
-cross-debugging to the Hitachi board, and the @code{load} command to
-download your program to the board. @code{load} displays the names of
-the program's sections, and a @samp{*} for each 2K of data downloaded.
-(If you want to refresh @value{GDBN} data on symbols or on the
-executable file without downloading, use the @value{GDBN} commands
-@code{file} or @code{symbol-file}. These commands, and @code{load}
-itself, are described in @ref{Files,,Commands to specify files}.)
+@item set mipsfpu double
+@itemx set mipsfpu single
+@itemx set mipsfpu none
+@itemx show mipsfpu
+@kindex set mipsfpu
+@kindex show mipsfpu
+@cindex MIPS remote floating point
+@cindex floating point, MIPS remote
+If your target board does not support the MIPS floating point
+coprocessor, you should use the command @samp{set mipsfpu none} (if you
+need this, you may wish to put the command in your @value{GDBN} init
+file). This tells @value{GDBN} how to find the return value of
+functions which return floating point values. It also allows
+@value{GDBN} to avoid saving the floating point registers when calling
+functions on the board. If you are using a floating point coprocessor
+with only single precision floating point support, as on the @sc{r4650}
+processor, use the command @samp{set mipsfpu single}. The default
+double precision floating point coprocessor may be selected using
+@samp{set mipsfpu double}.
-@smallexample
-(eg-C:\H8300\TEST) @value{GDBP} t.x
-@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
- the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
-for details.
-@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
-(@value{GDBP}) target hms
-Connected to remote H8/300 HMS system.
-(@value{GDBP}) load t.x
-.text : 0x8000 .. 0xabde ***********
-.data : 0xabde .. 0xad30 *
-.stack : 0xf000 .. 0xf014 *
-@end smallexample
+In previous versions the only choices were double precision or no
+floating point, so @samp{set mipsfpu on} will select double precision
+and @samp{set mipsfpu off} will select no floating point.
-At this point, you're ready to run or debug your program. From here on,
-you can use all the usual @value{GDBN} commands. The @code{break} command
-sets breakpoints; the @code{run} command starts your program;
-@code{print} or @code{x} display data; the @code{continue} command
-resumes execution after stopping at a breakpoint. You can use the
-@code{help} command at any time to find out more about @value{GDBN} commands.
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
+
+@item set remotedebug @var{n}
+@itemx show remotedebug
+@kindex set remotedebug@r{, MIPS protocol}
+@kindex show remotedebug@r{, MIPS protocol}
+@cindex @code{remotedebug}, MIPS protocol
+@cindex MIPS @code{remotedebug} protocol
+@c FIXME! For this to be useful, you must know something about the MIPS
+@c FIXME...protocol. Where is it described?
+You can see some debugging information about communications with the board
+by setting the @code{remotedebug} variable. If you set it to @code{1} using
+@samp{set remotedebug 1}, every packet is displayed. If you set it
+to @code{2}, every character is displayed. You can check the current value
+at any time with the command @samp{show remotedebug}.
-Remember, however, that @emph{operating system} facilities aren't
-available on your development board; for example, if your program hangs,
-you can't send an interrupt---but you can press the @sc{reset} switch!
+@item set timeout @var{seconds}
+@itemx set retransmit-timeout @var{seconds}
+@itemx show timeout
+@itemx show retransmit-timeout
+@cindex @code{timeout}, MIPS protocol
+@cindex @code{retransmit-timeout}, MIPS protocol
+@kindex set timeout
+@kindex show timeout
+@kindex set retransmit-timeout
+@kindex show retransmit-timeout
+You can control the timeout used while waiting for a packet, in the MIPS
+remote protocol, with the @code{set timeout @var{seconds}} command. The
+default is 5 seconds. Similarly, you can control the timeout used while
+waiting for an acknowledgement of a packet with the @code{set
+retransmit-timeout @var{seconds}} command. The default is 3 seconds.
+You can inspect both values with @code{show timeout} and @code{show
+retransmit-timeout}. (These commands are @emph{only} available when
+@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
-Use the @sc{reset} button on the development board
-@itemize @bullet
-@item
-to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
-no way to pass an interrupt signal to the development board); and
+The timeout set by @code{set timeout} does not apply when @value{GDBN}
+is waiting for your program to stop. In that case, @value{GDBN} waits
+forever because it has no way of knowing how long the program is going
+to run before stopping.
+@end table
-@item
-to return to the @value{GDBN} command prompt after your program finishes
-normally. The communications protocol provides no other way for @value{GDBN}
-to detect program completion.
-@end itemize
+@node PowerPC
+@subsection PowerPC
-In either case, @value{GDBN} sees the effect of a @sc{reset} on the
-development board as a ``normal exit'' of your program.
+@table @code
-@node Hitachi ICE
-@subsubsection Using the E7000 in-circuit emulator
+@kindex target dink32
+@item target dink32 @var{dev}
+DINK32 ROM monitor.
-@kindex target e7000@r{, with Hitachi ICE}
-You can use the E7000 in-circuit emulator to develop code for either the
-Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
-e7000} command to connect @value{GDBN} to your E7000:
+@kindex target ppcbug
+@item target ppcbug @var{dev}
+@kindex target ppcbug1
+@item target ppcbug1 @var{dev}
+PPCBUG ROM monitor for PowerPC.
-@table @code
-@item target e7000 @var{port} @var{speed}
-Use this form if your E7000 is connected to a serial port. The
-@var{port} argument identifies what serial port to use (for example,
-@samp{com2}). The third argument is the line speed in bits per second
-(for example, @samp{9600}).
+@kindex target sds
+@item target sds @var{dev}
+SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-@item target e7000 @var{hostname}
-If your E7000 is installed as a host on a TCP/IP network, you can just
-specify its hostname; @value{GDBN} uses @code{telnet} to connect.
@end table
-@node Hitachi Special
-@subsubsection Special @value{GDBN} commands for Hitachi micros
-
-Some @value{GDBN} commands are available only for the H8/300:
+@node PA
+@subsection HP PA Embedded
@table @code
-@kindex set machine
-@kindex show machine
-@item set machine h8300
-@itemx set machine h8300h
-Condition @value{GDBN} for one of the two variants of the H8/300
-architecture with @samp{set machine}. You can use @samp{show machine}
-to check which variant is currently in effect.
+@kindex target op50n
+@item target op50n @var{dev}
+OP50N monitor, running on an OKI HPPA board.
+
+@kindex target w89k
+@item target w89k @var{dev}
+W89K monitor, running on a Winbond HPPA board.
@end table
-@node H8/500
-@subsection H8/500
+@node SH
+@subsection Hitachi SH
@table @code
-@kindex set memory @var{mod}
-@cindex memory models, H8/500
-@item set memory @var{mod}
-@itemx show memory
-Specify which H8/500 memory model (@var{mod}) you are using with
-@samp{set memory}; check which memory model is in effect with @samp{show
-memory}. The accepted values for @var{mod} are @code{small},
-@code{big}, @code{medium}, and @code{compact}.
+@kindex target hms@r{, with Hitachi SH}
+@item target hms @var{dev}
+A Hitachi SH board attached via serial line to your host. Use special
+commands @code{device} and @code{speed} to control the serial line and
+the communications speed used.
-@end table
+@kindex target e7000@r{, with Hitachi SH}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi SH.
-@node i960
-@subsection Intel i960
+@kindex target sh3@r{, with SH}
+@kindex target sh3e@r{, with SH}
+@item target sh3 @var{dev}
+@item target sh3e @var{dev}
+Hitachi SH-3 and SH-3E target systems.
-@table @code
+@end table
-@kindex target mon960
-@item target mon960 @var{dev}
-MON960 monitor for Intel i960.
+@node Sparclet
+@subsection Tsqware Sparclet
-@kindex target nindy
-@item target nindy @var{devicename}
-An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
-the name of the serial device to use for the connection, e.g.
-@file{/dev/ttya}.
+@cindex Sparclet
+
+@value{GDBN} enables developers to debug tasks running on
+Sparclet targets from a Unix host.
+@value{GDBN} uses code that runs on
+both the Unix host and on the Sparclet target. The program
+@code{@value{GDBP}} is installed and executed on the Unix host.
+@table @code
+@item remotetimeout @var{args}
+@kindex remotetimeout
+@value{GDBN} supports the option @code{remotetimeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses.
@end table
-@cindex Nindy
-@cindex i960
-@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
-@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
-tell @value{GDBN} how to connect to the 960 in several ways:
+@cindex compiling, on Sparclet
+When compiling for debugging, include the options @samp{-g} to get debug
+information and @samp{-Ttext} to relocate the program to where you wish to
+load it on the target. You may also want to add the options @samp{-n} or
+@samp{-N} in order to reduce the size of the sections. Example:
-@itemize @bullet
-@item
-Through command line options specifying serial port, version of the
-Nindy protocol, and communications speed;
+@smallexample
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end smallexample
-@item
-By responding to a prompt on startup;
+You can use @code{objdump} to verify that the addresses are what you intended:
-@item
-By using the @code{target} command at any point during your @value{GDBN}
-session. @xref{Target Commands, ,Commands for managing targets}.
+@smallexample
+sparclet-aout-objdump --headers --syms prog
+@end smallexample
-@end itemize
+@cindex running, on Sparclet
+Once you have set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
+(or @code{sparclet-aout-gdb}, depending on your installation).
-@cindex download to Nindy-960
-With the Nindy interface to an Intel 960 board, @code{load}
-downloads @var{filename} to the 960 as well as adding its symbols in
-@value{GDBN}.
+@value{GDBN} comes up showing the prompt:
+
+@smallexample
+(gdbslet)
+@end smallexample
@menu
-* Nindy Startup:: Startup with Nindy
-* Nindy Options:: Options for Nindy
-* Nindy Reset:: Nindy reset command
+* Sparclet File:: Setting the file to debug
+* Sparclet Connection:: Connecting to Sparclet
+* Sparclet Download:: Sparclet download
+* Sparclet Execution:: Running and debugging
@end menu
-@node Nindy Startup
-@subsubsection Startup with Nindy
+@node Sparclet File
+@subsubsection Setting file to debug
-If you simply start @code{@value{GDBP}} without using any command-line
-options, you are prompted for what serial port to use, @emph{before} you
-reach the ordinary @value{GDBN} prompt:
+The @value{GDBN} command @code{file} lets you choose with program to debug.
-@example
-Attach /dev/ttyNN -- specify NN, or "quit" to quit:
-@end example
+@smallexample
+(gdbslet) file prog
+@end smallexample
-@noindent
-Respond to the prompt with whatever suffix (after @samp{/dev/tty})
-identifies the serial port you want to use. You can, if you choose,
-simply start up with no Nindy connection by responding to the prompt
-with an empty line. If you do this and later wish to attach to Nindy,
-use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
+@need 1000
+@value{GDBN} then attempts to read the symbol table of @file{prog}.
+@value{GDBN} locates
+the file by searching the directories listed in the command search
+path.
+If the file was compiled with debug information (option "-g"), source
+files will be searched as well.
+@value{GDBN} locates
+the source files by searching the directories listed in the directory search
+path (@pxref{Environment, ,Your program's environment}).
+If it fails
+to find a file, it displays a message such as:
-@node Nindy Options
-@subsubsection Options for Nindy
+@smallexample
+prog: No such file or directory.
+@end smallexample
-These are the startup options for beginning your @value{GDBN} session with a
-Nindy-960 board attached:
+When this happens, add the appropriate directories to the search paths with
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the
+@code{target} command again.
-@table @code
-@item -r @var{port}
-Specify the serial port name of a serial interface to be used to connect
-to the target system. This option is only available when @value{GDBN} is
-configured for the Intel 960 target architecture. You may specify
-@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
-device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
-suffix for a specific @code{tty} (e.g. @samp{-r a}).
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
+
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
+
+@smallexample
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3
+@end smallexample
-@item -O
-(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
-the ``old'' Nindy monitor protocol to connect to the target system.
-This option is only available when @value{GDBN} is configured for the Intel 960
-target architecture.
+@need 750
+@value{GDBN} displays messages like these:
-@quotation
-@emph{Warning:} if you specify @samp{-O}, but are actually trying to
-connect to a target system that expects the newer protocol, the connection
-fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
-attempts to reconnect at several different line speeds. You can abort
-this process with an interrupt.
-@end quotation
+@smallexample
+Connected to ttya.
+@end smallexample
-@item -brk
-Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
-system, in an attempt to reset it, before connecting to a Nindy target.
+@node Sparclet Download
+@subsubsection Sparclet download
-@quotation
-@emph{Warning:} Many target systems do not have the hardware that this
-requires; it only works with a few boards.
-@end quotation
-@end table
+@cindex download to Sparclet
+Once connected to the Sparclet target,
+you can use the @value{GDBN}
+@code{load} command to download the file from the host to the target.
+The file name and load offset should be given as arguments to the @code{load}
+command.
+Since the file format is aout, the program must be loaded to the starting
+address. You can use @code{objdump} to find out what this value is. The load
+offset is an offset which is added to the VMA (virtual memory address)
+of each of the file's sections.
+For instance, if the program
+@file{prog} was linked to text address 0x1201000, with data at 0x12010160
+and bss at 0x12010170, in @value{GDBN}, type:
-The standard @samp{-b} option controls the line speed used on the serial
-port.
+@smallexample
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end smallexample
-@c @group
-@node Nindy Reset
-@subsubsection Nindy reset command
+If the code is loaded at a different address then what the program was linked
+to, you may need to use the @code{section} and @code{add-symbol-file} commands
+to tell @value{GDBN} where to map the symbol table.
-@table @code
-@item reset
-@kindex reset
-For a Nindy target, this command sends a ``break'' to the remote target
-system; this is only useful if the target has been equipped with a
-circuit to perform a hard reset (or some other interesting action) when
-a break is detected.
-@end table
-@c @end group
+@node Sparclet Execution
+@subsubsection Running and debugging
-@node M32R/D
-@subsection Mitsubishi M32R/D
+@cindex running and debugging Sparclet programs
+You can now begin debugging the task using @value{GDBN}'s execution control
+commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
+manual for the list of commands.
+
+@smallexample
+(gdbslet) b main
+Breakpoint 1 at 0x12010000: file prog.c, line 3.
+(gdbslet) run
+Starting program: prog
+Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
+3 char *symarg = 0;
+(gdbslet) step
+4 char *execarg = "hello!";
+(gdbslet)
+@end smallexample
+
+@node Sparclite
+@subsection Fujitsu Sparclite
@table @code
-@kindex target m32r
-@item target m32r @var{dev}
-Mitsubishi M32R/D ROM monitor.
+@kindex target sparclite
+@item target sparclite @var{dev}
+Fujitsu sparclite boards, used only for the purpose of loading.
+You must use an additional command to debug the program.
+For example: target remote @var{dev} using @value{GDBN} standard
+remote protocol.
@end table
-@node M68K
-@subsection M68k
+@node ST2000
+@subsection Tandem ST2000
-The Motorola m68k configuration includes ColdFire support, and
-target command for the following ROM monitors.
+@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
+STDBUG protocol.
-@table @code
+To connect your ST2000 to the host system, see the manufacturer's
+manual. Once the ST2000 is physically attached, you can run:
-@kindex target abug
-@item target abug @var{dev}
-ABug ROM monitor for M68K.
+@smallexample
+target st2000 @var{dev} @var{speed}
+@end smallexample
-@kindex target cpu32bug
-@item target cpu32bug @var{dev}
-CPU32BUG monitor, running on a CPU32 (M68K) board.
+@noindent
+to establish it as your debugging environment. @var{dev} is normally
+the name of a serial device, such as @file{/dev/ttya}, connected to the
+ST2000 via a serial line. You can instead specify @var{dev} as a TCP
+connection (for example, to a serial line attached via a terminal
+concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
+The @code{load} and @code{attach} commands are @emph{not} defined for
+this target; you must load your program into the ST2000 as you normally
+would for standalone operation. @value{GDBN} reads debugging information
+(such as symbols) from a separate, debugging version of the program
+available on your host computer.
+@c FIXME!! This is terribly vague; what little content is here is
+@c basically hearsay.
-@kindex target est
-@item target est @var{dev}
-EST-300 ICE monitor, running on a CPU32 (M68K) board.
+@cindex ST2000 auxiliary commands
+These auxiliary @value{GDBN} commands are available to help you with the ST2000
+environment:
-@kindex target rom68k
-@item target rom68k @var{dev}
-ROM 68K monitor, running on an M68K IDP board.
+@table @code
+@item st2000 @var{command}
+@kindex st2000 @var{cmd}
+@cindex STDBUG commands (ST2000)
+@cindex commands to STDBUG (ST2000)
+Send a @var{command} to the STDBUG monitor. See the manufacturer's
+manual for available commands.
+@item connect
+@cindex connect (to STDBUG)
+Connect the controlling terminal to the STDBUG command monitor. When
+you are done interacting with STDBUG, typing either of two character
+sequences gets you back to the @value{GDBN} command prompt:
+@kbd{@key{RET}~.} (Return, followed by tilde and period) or
+@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
@end table
-If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
-instead have only a single special target command:
+@node Z8000
+@subsection Zilog Z8000
-@table @code
+@cindex Z8000
+@cindex simulator, Z8000
+@cindex Zilog Z8000 simulator
-@kindex target es1800
-@item target es1800 @var{dev}
-ES-1800 emulator for M68K.
+When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
+a Z8000 simulator.
+
+For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
+unsegmented variant of the Z8000 architecture) or the Z8001 (the
+segmented variant). The simulator recognizes which architecture is
+appropriate by inspecting the object code.
+@table @code
+@item target sim @var{args}
+@kindex sim
+@kindex target sim@r{, with Z8000}
+Debug programs on a simulated CPU. If the simulator supports setup
+options, specify them via @var{args}.
@end table
-[context?]
+@noindent
+After specifying this target, you can debug programs for the simulated
+CPU in the same style as programs for your host computer; use the
+@code{file} command to load a new program image, the @code{run} command
+to run your program, and so on.
+
+As well as making available all the usual machine registers
+(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
+additional items of information as specially named registers:
@table @code
-@kindex target rombug
-@item target rombug @var{dev}
-ROMBUG ROM monitor for OS/9000.
+@item cycles
+Counts clock-ticks in the simulator.
-@end table
+@item insts
+Counts instructions run in the simulator.
-@node M88K
-@subsection M88K
+@item time
+Execution time in 60ths of a second.
-@table @code
+@end table
-@kindex target bug
-@item target bug @var{dev}
-BUG monitor, running on a MVME187 (m88k) board.
+You can refer to these values in @value{GDBN} expressions with the usual
+conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
+conditional breakpoint that suspends only after at least 5000
+simulated clock ticks.
-@end table
+@node Architectures
+@section Architectures
-@node MIPS Embedded
-@subsection MIPS Embedded
+This section describes characteristics of architectures that affect
+all uses of @value{GDBN} with the architecture, both native and cross.
-@cindex MIPS boards
-@value{GDBN} can use the MIPS remote debugging protocol to talk to a
-MIPS board attached to a serial line. This is available when
-you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
+@menu
+* A29K::
+* Alpha::
+* MIPS::
+@end menu
-@need 1000
-Use these @value{GDBN} commands to specify the connection to your target board:
+@node A29K
+@subsection A29K
@table @code
-@item target mips @var{port}
-@kindex target mips @var{port}
-To run a program on the board, start up @code{@value{GDBP}} with the
-name of your program as the argument. To connect to the board, use the
-command @samp{target mips @var{port}}, where @var{port} is the name of
-the serial port connected to the board. If the program has not already
-been downloaded to the board, you may use the @code{load} command to
-download it. You can then use all the usual @value{GDBN} commands.
-For example, this sequence connects to the target board through a serial
-port, and loads and runs a program called @var{prog} through the
-debugger:
+@kindex set rstack_high_address
+@cindex AMD 29K register stack
+@cindex register stack, AMD29K
+@item set rstack_high_address @var{address}
+On AMD 29000 family processors, registers are saved in a separate
+@dfn{register stack}. There is no way for @value{GDBN} to determine the
+extent of this stack. Normally, @value{GDBN} just assumes that the
+stack is ``large enough''. This may result in @value{GDBN} referencing
+memory locations that do not exist. If necessary, you can get around
+this problem by specifying the ending address of the register stack with
+the @code{set rstack_high_address} command. The argument should be an
+address, which you probably want to precede with @samp{0x} to specify in
+hexadecimal.
-@example
-host$ @value{GDBP} @var{prog}
-@value{GDBN} is free software and @dots{}
-(@value{GDBP}) target mips /dev/ttyb
-(@value{GDBP}) load @var{prog}
-(@value{GDBP}) run
-@end example
+@kindex show rstack_high_address
+@item show rstack_high_address
+Display the current limit of the register stack, on AMD 29000 family
+processors.
+
+@end table
-@item target mips @var{hostname}:@var{portnumber}
-On some @value{GDBN} host configurations, you can specify a TCP
-connection (for instance, to a serial line managed by a terminal
-concentrator) instead of a serial port, using the syntax
-@samp{@var{hostname}:@var{portnumber}}.
+@node Alpha
+@subsection Alpha
-@item target pmon @var{port}
-@kindex target pmon @var{port}
-PMON ROM monitor.
+See the following section.
-@item target ddb @var{port}
-@kindex target ddb @var{port}
-NEC's DDB variant of PMON for Vr4300.
+@node MIPS
+@subsection MIPS
-@item target lsi @var{port}
-@kindex target lsi @var{port}
-LSI variant of PMON.
+@cindex stack on Alpha
+@cindex stack on MIPS
+@cindex Alpha stack
+@cindex MIPS stack
+Alpha- and MIPS-based computers use an unusual stack frame, which
+sometimes requires @value{GDBN} to search backward in the object code to
+find the beginning of a function.
-@kindex target r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
+@cindex response time, MIPS debugging
+To improve response time (especially for embedded applications, where
+@value{GDBN} may be restricted to a slow serial line for this search)
+you may want to limit the size of this search, using one of these
+commands:
-@kindex target array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
+@table @code
+@cindex @code{heuristic-fence-post} (Alpha, MIPS)
+@item set heuristic-fence-post @var{limit}
+Restrict @value{GDBN} to examining at most @var{limit} bytes in its
+search for the beginning of a function. A value of @var{0} (the
+default) means there is no limit. However, except for @var{0}, the
+larger the limit the more bytes @code{heuristic-fence-post} must search
+and therefore the longer it takes to run.
+@item show heuristic-fence-post
+Display the current limit.
@end table
-
@noindent
-@value{GDBN} also supports these special commands for MIPS targets:
+These commands are available @emph{only} when @value{GDBN} is configured
+for debugging programs on Alpha or MIPS processors.
-@table @code
-@item set processor @var{args}
-@itemx show processor
-@kindex set processor @var{args}
-@kindex show processor
-Use the @code{set processor} command to set the type of MIPS
-processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
-to use the CPU registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
-is using. Use the @code{info reg} command to see what registers
-@value{GDBN} is using.
-@item set mipsfpu double
-@itemx set mipsfpu single
-@itemx set mipsfpu none
-@itemx show mipsfpu
-@kindex set mipsfpu
-@kindex show mipsfpu
-@cindex MIPS remote floating point
-@cindex floating point, MIPS remote
-If your target board does not support the MIPS floating point
-coprocessor, you should use the command @samp{set mipsfpu none} (if you
-need this, you may wish to put the command in your @value{GDBN} init
-file). This tells @value{GDBN} how to find the return value of
-functions which return floating point values. It also allows
-@value{GDBN} to avoid saving the floating point registers when calling
-functions on the board. If you are using a floating point coprocessor
-with only single precision floating point support, as on the @sc{r4650}
-processor, use the command @samp{set mipsfpu single}. The default
-double precision floating point coprocessor may be selected using
-@samp{set mipsfpu double}.
+@node Controlling GDB
+@chapter Controlling @value{GDBN}
-In previous versions the only choices were double precision or no
-floating point, so @samp{set mipsfpu on} will select double precision
-and @samp{set mipsfpu off} will select no floating point.
+You can alter the way @value{GDBN} interacts with you by using the
+@code{set} command. For commands controlling how @value{GDBN} displays
+data, see @ref{Print Settings, ,Print settings}. Other settings are
+described here.
-As usual, you can inquire about the @code{mipsfpu} variable with
-@samp{show mipsfpu}.
+@menu
+* Prompt:: Prompt
+* Editing:: Command editing
+* History:: Command history
+* Screen Size:: Screen size
+* Numbers:: Numbers
+* Messages/Warnings:: Optional warnings and messages
+* Debugging Output:: Optional messages about internal happenings
+@end menu
-@item set remotedebug @var{n}
-@itemx show remotedebug
-@kindex set remotedebug@r{, MIPS protocol}
-@kindex show remotedebug@r{, MIPS protocol}
-@cindex @code{remotedebug}, MIPS protocol
-@cindex MIPS @code{remotedebug} protocol
-@c FIXME! For this to be useful, you must know something about the MIPS
-@c FIXME...protocol. Where is it described?
-You can see some debugging information about communications with the board
-by setting the @code{remotedebug} variable. If you set it to @code{1} using
-@samp{set remotedebug 1}, every packet is displayed. If you set it
-to @code{2}, every character is displayed. You can check the current value
-at any time with the command @samp{show remotedebug}.
+@node Prompt
+@section Prompt
-@item set timeout @var{seconds}
-@itemx set retransmit-timeout @var{seconds}
-@itemx show timeout
-@itemx show retransmit-timeout
-@cindex @code{timeout}, MIPS protocol
-@cindex @code{retransmit-timeout}, MIPS protocol
-@kindex set timeout
-@kindex show timeout
-@kindex set retransmit-timeout
-@kindex show retransmit-timeout
-You can control the timeout used while waiting for a packet, in the MIPS
-remote protocol, with the @code{set timeout @var{seconds}} command. The
-default is 5 seconds. Similarly, you can control the timeout used while
-waiting for an acknowledgement of a packet with the @code{set
-retransmit-timeout @var{seconds}} command. The default is 3 seconds.
-You can inspect both values with @code{show timeout} and @code{show
-retransmit-timeout}. (These commands are @emph{only} available when
-@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
+@cindex prompt
-The timeout set by @code{set timeout} does not apply when @value{GDBN}
-is waiting for your program to stop. In that case, @value{GDBN} waits
-forever because it has no way of knowing how long the program is going
-to run before stopping.
-@end table
+@value{GDBN} indicates its readiness to read a command by printing a string
+called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
+can change the prompt string with the @code{set prompt} command. For
+instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
+the prompt in one of the @value{GDBN} sessions so that you can always tell
+which one you are talking to.
-@node PowerPC
-@subsection PowerPC
+@emph{Note:} @code{set prompt} does not add a space for you after the
+prompt you set. This allows you to set a prompt which ends in a space
+or a prompt that does not.
@table @code
+@kindex set prompt
+@item set prompt @var{newprompt}
+Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
-@kindex target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor.
-
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
+@end table
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+@node Editing
+@section Command editing
+@cindex readline
+@cindex command line editing
-@end table
+@value{GDBN} reads its input commands via the @dfn{readline} interface. This
+@sc{gnu} library provides consistent behavior for programs which provide a
+command line interface to the user. Advantages are @sc{gnu} Emacs-style
+or @dfn{vi}-style inline editing of commands, @code{csh}-like history
+substitution, and a storage and recall of command history across
+debugging sessions.
-@node PA
-@subsection HP PA Embedded
+You may control the behavior of command line editing in @value{GDBN} with the
+command @code{set}.
@table @code
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
-
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
+@item set editing off
+Disable command line editing.
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
@end table
-@node SH
-@subsection Hitachi SH
+@node History
+@section Command history
-@table @code
+@value{GDBN} can keep track of the commands you type during your
+debugging sessions, so that you can be certain of precisely what
+happened. Use these commands to manage the @value{GDBN} command
+history facility.
-@kindex target hms@r{, with Hitachi SH}
-@item target hms @var{dev}
-A Hitachi SH board attached via serial line to your host. Use special
-commands @code{device} and @code{speed} to control the serial line and
-the communications speed used.
+@table @code
+@cindex history substitution
+@cindex history file
+@kindex set history filename
+@kindex GDBHISTFILE
+@item set history filename @var{fname}
+Set the name of the @value{GDBN} command history file to @var{fname}.
+This is the file where @value{GDBN} reads an initial command history
+list, and where it writes the command history from this session when it
+exits. You can access this list through history expansion or through
+the history command editing characters listed below. This file defaults
+to the value of the environment variable @code{GDBHISTFILE}, or to
+@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
+is not set.
-@kindex target e7000@r{, with Hitachi SH}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi SH.
+@cindex history save
+@kindex set history save
+@item set history save
+@itemx set history save on
+Record command history in a file, whose name may be specified with the
+@code{set history filename} command. By default, this option is disabled.
-@kindex target sh3@r{, with SH}
-@kindex target sh3e@r{, with SH}
-@item target sh3 @var{dev}
-@item target sh3e @var{dev}
-Hitachi SH-3 and SH-3E target systems.
+@item set history save off
+Stop recording command history in a file.
+@cindex history size
+@kindex set history size
+@item set history size @var{size}
+Set the number of commands which @value{GDBN} keeps in its history list.
+This defaults to the value of the environment variable
+@code{HISTSIZE}, or to 256 if this variable is not set.
@end table
-@node Sparclet
-@subsection Tsqware Sparclet
+@cindex history expansion
+History expansion assigns special meaning to the character @kbd{!}.
+@ifset have-readline-appendices
+@xref{Event Designators}.
+@end ifset
-@cindex Sparclet
+Since @kbd{!} is also the logical not operator in C, history expansion
+is off by default. If you decide to enable history expansion with the
+@code{set history expansion on} command, you may sometimes need to
+follow @kbd{!} (when it is used as logical not, in an expression) with
+a space or a tab to prevent it from being expanded. The readline
+history facilities do not attempt substitution on the strings
+@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
-@value{GDBN} enables developers to debug tasks running on
-Sparclet targets from a Unix host.
-@value{GDBN} uses code that runs on
-both the Unix host and on the Sparclet target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host.
+The commands to control history expansion are:
@table @code
-@item remotetimeout @var{args}
-@kindex remotetimeout
-@value{GDBN} supports the option @code{remotetimeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses.
-@end table
+@kindex set history expansion
+@item set history expansion on
+@itemx set history expansion
+Enable history expansion. History expansion is off by default.
-@cindex compiling, on Sparclet
-When compiling for debugging, include the options @samp{-g} to get debug
-information and @samp{-Ttext} to relocate the program to where you wish to
-load it on the target. You may also want to add the options @samp{-n} or
-@samp{-N} in order to reduce the size of the sections. Example:
+@item set history expansion off
+Disable history expansion.
-@example
-sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
-@end example
+The readline code comes with more complete documentation of
+editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
+or @code{vi} may wish to read it.
+@ifset have-readline-appendices
+@xref{Command Line Editing}.
+@end ifset
-You can use @code{objdump} to verify that the addresses are what you intended:
+@c @group
+@kindex show history
+@item show history
+@itemx show history filename
+@itemx show history save
+@itemx show history size
+@itemx show history expansion
+These commands display the state of the @value{GDBN} history parameters.
+@code{show history} by itself displays all four states.
+@c @end group
+@end table
-@example
-sparclet-aout-objdump --headers --syms prog
-@end example
+@table @code
+@kindex shows
+@item show commands
+Display the last ten commands in the command history.
-@cindex running, on Sparclet
-Once you have set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
-(or @code{sparclet-aout-gdb}, depending on your installation).
+@item show commands @var{n}
+Print ten commands centered on command number @var{n}.
-@value{GDBN} comes up showing the prompt:
+@item show commands +
+Print ten commands just after the commands last printed.
+@end table
-@example
-(gdbslet)
-@end example
+@node Screen Size
+@section Screen size
+@cindex size of screen
+@cindex pauses in output
-@menu
-* Sparclet File:: Setting the file to debug
-* Sparclet Connection:: Connecting to Sparclet
-* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
-@end menu
+Certain commands to @value{GDBN} may produce large amounts of
+information output to the screen. To help you read all of it,
+@value{GDBN} pauses and asks you for input at the end of each page of
+output. Type @key{RET} when you want to continue the output, or @kbd{q}
+to discard the remaining output. Also, the screen width setting
+determines when to wrap lines of output. Depending on what is being
+printed, @value{GDBN} tries to break the line at a readable place,
+rather than simply letting it overflow onto the following line.
-@node Sparclet File
-@subsubsection Setting file to debug
+Normally @value{GDBN} knows the size of the screen from the terminal
+driver software. For example, on Unix @value{GDBN} uses the termcap data base
+together with the value of the @code{TERM} environment variable and the
+@code{stty rows} and @code{stty cols} settings. If this is not correct,
+you can override it with the @code{set height} and @code{set
+width} commands:
-The @value{GDBN} command @code{file} lets you choose with program to debug.
+@table @code
+@kindex set height
+@kindex set width
+@kindex show width
+@kindex show height
+@item set height @var{lpp}
+@itemx show height
+@itemx set width @var{cpl}
+@itemx show width
+These @code{set} commands specify a screen height of @var{lpp} lines and
+a screen width of @var{cpl} characters. The associated @code{show}
+commands display the current settings.
-@example
-(gdbslet) file prog
-@end example
+If you specify a height of zero lines, @value{GDBN} does not pause during
+output no matter how long the output is. This is useful if output is to a
+file or to an editor buffer.
-@need 1000
-@value{GDBN} then attempts to read the symbol table of @file{prog}.
-@value{GDBN} locates
-the file by searching the directories listed in the command search
-path.
-If the file was compiled with debug information (option "-g"), source
-files will be searched as well.
-@value{GDBN} locates
-the source files by searching the directories listed in the directory search
-path (@pxref{Environment, ,Your program's environment}).
-If it fails
-to find a file, it displays a message such as:
+Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
+from wrapping its output.
+@end table
-@example
-prog: No such file or directory.
-@end example
+@node Numbers
+@section Numbers
+@cindex number representation
+@cindex entering numbers
-When this happens, add the appropriate directories to the search paths with
-the @value{GDBN} commands @code{path} and @code{dir}, and execute the
-@code{target} command again.
+You can always enter numbers in octal, decimal, or hexadecimal in
+@value{GDBN} by the usual conventions: octal numbers begin with
+@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
+begin with @samp{0x}. Numbers that begin with none of these are, by
+default, entered in base 10; likewise, the default display for
+numbers---when no particular format is specified---is base 10. You can
+change the default base for both input and output with the @code{set
+radix} command.
-@node Sparclet Connection
-@subsubsection Connecting to Sparclet
+@table @code
+@kindex set input-radix
+@item set input-radix @var{base}
+Set the default base for numeric input. Supported choices
+for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+specified either unambiguously or using the current default radix; for
+example, any of
-The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
-To connect to a target on serial port ``@code{ttya}'', type:
+@smallexample
+set radix 012
+set radix 10.
+set radix 0xa
+@end smallexample
-@example
-(gdbslet) target sparclet /dev/ttya
-Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
-@end example
+@noindent
+sets the base to decimal. On the other hand, @samp{set radix 10}
+leaves the radix unchanged no matter what it was.
-@need 750
-@value{GDBN} displays messages like these:
+@kindex set output-radix
+@item set output-radix @var{base}
+Set the default base for numeric display. Supported choices
+for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+specified either unambiguously or using the current default radix.
-@example
-Connected to ttya.
-@end example
+@kindex show input-radix
+@item show input-radix
+Display the current default base for numeric input.
-@node Sparclet Download
-@subsubsection Sparclet download
+@kindex show output-radix
+@item show output-radix
+Display the current default base for numeric display.
+@end table
-@cindex download to Sparclet
-Once connected to the Sparclet target,
-you can use the @value{GDBN}
-@code{load} command to download the file from the host to the target.
-The file name and load offset should be given as arguments to the @code{load}
-command.
-Since the file format is aout, the program must be loaded to the starting
-address. You can use @code{objdump} to find out what this value is. The load
-offset is an offset which is added to the VMA (virtual memory address)
-of each of the file's sections.
-For instance, if the program
-@file{prog} was linked to text address 0x1201000, with data at 0x12010160
-and bss at 0x12010170, in @value{GDBN}, type:
+@node Messages/Warnings
+@section Optional warnings and messages
-@example
-(gdbslet) load prog 0x12010000
-Loading section .text, size 0xdb0 vma 0x12010000
-@end example
+By default, @value{GDBN} is silent about its inner workings. If you are
+running on a slow machine, you may want to use the @code{set verbose}
+command. This makes @value{GDBN} tell you when it does a lengthy
+internal operation, so you will not think it has crashed.
-If the code is loaded at a different address then what the program was linked
-to, you may need to use the @code{section} and @code{add-symbol-file} commands
-to tell @value{GDBN} where to map the symbol table.
+Currently, the messages controlled by @code{set verbose} are those
+which announce that the symbol table for a source file is being read;
+see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
-@node Sparclet Execution
-@subsubsection Running and debugging
+@table @code
+@kindex set verbose
+@item set verbose on
+Enables @value{GDBN} output of certain informational messages.
-@cindex running and debugging Sparclet programs
-You can now begin debugging the task using @value{GDBN}'s execution control
-commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
-manual for the list of commands.
+@item set verbose off
+Disables @value{GDBN} output of certain informational messages.
-@example
-(gdbslet) b main
-Breakpoint 1 at 0x12010000: file prog.c, line 3.
-(gdbslet) run
-Starting program: prog
-Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
-3 char *symarg = 0;
-(gdbslet) step
-4 char *execarg = "hello!";
-(gdbslet)
-@end example
+@kindex show verbose
+@item show verbose
+Displays whether @code{set verbose} is on or off.
+@end table
-@node Sparclite
-@subsection Fujitsu Sparclite
+By default, if @value{GDBN} encounters bugs in the symbol table of an
+object file, it is silent; but if you are debugging a compiler, you may
+find this information useful (@pxref{Symbol Errors, ,Errors reading
+symbol files}).
@table @code
-@kindex target sparclite
-@item target sparclite @var{dev}
-Fujitsu sparclite boards, used only for the purpose of loading.
-You must use an additional command to debug the program.
-For example: target remote @var{dev} using @value{GDBN} standard
-remote protocol.
+@kindex set complaints
+@item set complaints @var{limit}
+Permits @value{GDBN} to output @var{limit} complaints about each type of
+unusual symbols before becoming silent about the problem. Set
+@var{limit} to zero to suppress all complaints; set it to a large number
+to prevent complaints from being suppressed.
+
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints @value{GDBN} is permitted to produce.
@end table
-@node ST2000
-@subsection Tandem ST2000
-
-@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
-STDBUG protocol.
+By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
+lot of stupid questions to confirm certain commands. For example, if
+you try to run a program which is already running:
-To connect your ST2000 to the host system, see the manufacturer's
-manual. Once the ST2000 is physically attached, you can run:
+@smallexample
+(@value{GDBP}) run
+The program being debugged has been started already.
+Start it from the beginning? (y or n)
+@end smallexample
-@example
-target st2000 @var{dev} @var{speed}
-@end example
+If you are willing to unflinchingly face the consequences of your own
+commands, you can disable this ``feature'':
-@noindent
-to establish it as your debugging environment. @var{dev} is normally
-the name of a serial device, such as @file{/dev/ttya}, connected to the
-ST2000 via a serial line. You can instead specify @var{dev} as a TCP
-connection (for example, to a serial line attached via a terminal
-concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
+@table @code
-The @code{load} and @code{attach} commands are @emph{not} defined for
-this target; you must load your program into the ST2000 as you normally
-would for standalone operation. @value{GDBN} reads debugging information
-(such as symbols) from a separate, debugging version of the program
-available on your host computer.
-@c FIXME!! This is terribly vague; what little content is here is
-@c basically hearsay.
+@kindex set confirm
+@cindex flinching
+@cindex confirmation
+@cindex stupid questions
+@item set confirm off
+Disables confirmation requests.
-@cindex ST2000 auxiliary commands
-These auxiliary @value{GDBN} commands are available to help you with the ST2000
-environment:
+@item set confirm on
+Enables confirmation requests (the default).
-@table @code
-@item st2000 @var{command}
-@kindex st2000 @var{cmd}
-@cindex STDBUG commands (ST2000)
-@cindex commands to STDBUG (ST2000)
-Send a @var{command} to the STDBUG monitor. See the manufacturer's
-manual for available commands.
+@kindex show confirm
+@item show confirm
+Displays state of confirmation requests.
-@item connect
-@cindex connect (to STDBUG)
-Connect the controlling terminal to the STDBUG command monitor. When
-you are done interacting with STDBUG, typing either of two character
-sequences gets you back to the @value{GDBN} command prompt:
-@kbd{@key{RET}~.} (Return, followed by tilde and period) or
-@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
@end table
-@node Z8000
-@subsection Zilog Z8000
+@node Debugging Output
+@section Optional messages about internal happenings
+@table @code
+@kindex set debug arch
+@item set debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug arch
+@item show debug arch
+Displays the current state of displaying gdbarch debugging info.
+@kindex set debug event
+@item set debug event
+Turns on or off display of @value{GDBN} event debugging info. The
+default is off.
+@kindex show debug event
+@item show debug event
+Displays the current state of displaying @value{GDBN} event debugging
+info.
+@kindex set debug expression
+@item set debug expression
+Turns on or off display of @value{GDBN} expression debugging info. The
+default is off.
+@kindex show debug expression
+@item show debug expression
+Displays the current state of displaying @value{GDBN} expression
+debugging info.
+@kindex set debug overload
+@item set debug overload
+Turns on or off display of @value{GDBN} C@t{++} overload debugging
+info. This includes info such as ranking of functions, etc. The default
+is off.
+@kindex show debug overload
+@item show debug overload
+Displays the current state of displaying @value{GDBN} C@t{++} overload
+debugging info.
+@kindex set debug remote
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+@item set debug remote
+Turns on or off display of reports on all packets sent back and forth across
+the serial line to the remote machine. The info is printed on the
+@value{GDBN} standard output stream. The default is off.
+@kindex show debug remote
+@item show debug remote
+Displays the state of display of remote packets.
+@kindex set debug serial
+@item set debug serial
+Turns on or off display of @value{GDBN} serial debugging info. The
+default is off.
+@kindex show debug serial
+@item show debug serial
+Displays the current state of displaying @value{GDBN} serial debugging
+info.
+@kindex set debug target
+@item set debug target
+Turns on or off display of @value{GDBN} target debugging info. This info
+includes what is going on at the target level of GDB, as it happens. The
+default is off.
+@kindex show debug target
+@item show debug target
+Displays the current state of displaying @value{GDBN} target debugging
+info.
+@kindex set debug varobj
+@item set debug varobj
+Turns on or off display of @value{GDBN} variable object debugging
+info. The default is off.
+@kindex show debug varobj
+@item show debug varobj
+Displays the current state of displaying @value{GDBN} variable object
+debugging info.
+@end table
-@cindex Z8000
-@cindex simulator, Z8000
-@cindex Zilog Z8000 simulator
+@node Sequences
+@chapter Canned Sequences of Commands
-When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
-a Z8000 simulator.
+Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
+command lists}), @value{GDBN} provides two ways to store sequences of
+commands for execution as a unit: user-defined commands and command
+files.
-For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
-unsegmented variant of the Z8000 architecture) or the Z8001 (the
-segmented variant). The simulator recognizes which architecture is
-appropriate by inspecting the object code.
+@menu
+* Define:: User-defined commands
+* Hooks:: User-defined command hooks
+* Command Files:: Command files
+* Output:: Commands for controlled output
+@end menu
-@table @code
-@item target sim @var{args}
-@kindex sim
-@kindex target sim@r{, with Z8000}
-Debug programs on a simulated CPU. If the simulator supports setup
-options, specify them via @var{args}.
-@end table
+@node Define
+@section User-defined commands
-@noindent
-After specifying this target, you can debug programs for the simulated
-CPU in the same style as programs for your host computer; use the
-@code{file} command to load a new program image, the @code{run} command
-to run your program, and so on.
+@cindex user-defined command
+A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
+which you assign a new name as a command. This is done with the
+@code{define} command. User commands may accept up to 10 arguments
+separated by whitespace. Arguments are accessed within the user command
+via @var{$arg0@dots{}$arg9}. A trivial example:
-As well as making available all the usual machine registers
-(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
-additional items of information as specially named registers:
+@smallexample
+define adder
+ print $arg0 + $arg1 + $arg2
+@end smallexample
-@table @code
+@noindent
+To execute the command use:
-@item cycles
-Counts clock-ticks in the simulator.
+@smallexample
+adder 1 2 3
+@end smallexample
-@item insts
-Counts instructions run in the simulator.
+@noindent
+This defines the command @code{adder}, which prints the sum of
+its three arguments. Note the arguments are text substitutions, so they may
+reference variables, use complex expressions, or even perform inferior
+functions calls.
-@item time
-Execution time in 60ths of a second.
+@table @code
-@end table
+@kindex define
+@item define @var{commandname}
+Define a command named @var{commandname}. If there is already a command
+by that name, you are asked to confirm that you want to redefine it.
-You can refer to these values in @value{GDBN} expressions with the usual
-conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
-conditional breakpoint that suspends only after at least 5000
-simulated clock ticks.
+The definition of the command is made up of other @value{GDBN} command lines,
+which are given following the @code{define} command. The end of these
+commands is marked by a line containing @code{end}.
-@node Architectures
-@section Architectures
+@kindex if
+@kindex else
+@item if
+Takes a single argument, which is an expression to evaluate.
+It is followed by a series of commands that are executed
+only if the expression is true (nonzero).
+There can then optionally be a line @code{else}, followed
+by a series of commands that are only executed if the expression
+was false. The end of the list is marked by a line containing @code{end}.
-This section describes characteristics of architectures that affect
-all uses of @value{GDBN} with the architecture, both native and cross.
+@kindex while
+@item while
+The syntax is similar to @code{if}: the command takes a single argument,
+which is an expression to evaluate, and must be followed by the commands to
+execute, one per line, terminated by an @code{end}.
+The commands are executed repeatedly as long as the expression
+evaluates to true.
-@menu
-* A29K::
-* Alpha::
-* MIPS::
-@end menu
+@kindex document
+@item document @var{commandname}
+Document the user-defined command @var{commandname}, so that it can be
+accessed by @code{help}. The command @var{commandname} must already be
+defined. This command reads lines of documentation just as @code{define}
+reads the lines of the command definition, ending with @code{end}.
+After the @code{document} command is finished, @code{help} on command
+@var{commandname} displays the documentation you have written.
-@node A29K
-@subsection A29K
+You may use the @code{document} command again to change the
+documentation of a command. Redefining the command with @code{define}
+does not change the documentation.
-@table @code
+@kindex help user-defined
+@item help user-defined
+List all user-defined commands, with the first line of the documentation
+(if any) for each.
-@kindex set rstack_high_address
-@cindex AMD 29K register stack
-@cindex register stack, AMD29K
-@item set rstack_high_address @var{address}
-On AMD 29000 family processors, registers are saved in a separate
-@dfn{register stack}. There is no way for @value{GDBN} to determine the
-extent of this stack. Normally, @value{GDBN} just assumes that the
-stack is ``large enough''. This may result in @value{GDBN} referencing
-memory locations that do not exist. If necessary, you can get around
-this problem by specifying the ending address of the register stack with
-the @code{set rstack_high_address} command. The argument should be an
-address, which you probably want to precede with @samp{0x} to specify in
-hexadecimal.
+@kindex show user
+@item show user
+@itemx show user @var{commandname}
+Display the @value{GDBN} commands used to define @var{commandname} (but
+not its documentation). If no @var{commandname} is given, display the
+definitions for all user-defined commands.
-@kindex show rstack_high_address
-@item show rstack_high_address
-Display the current limit of the register stack, on AMD 29000 family
-processors.
+@kindex show max-user-call-depth
+@kindex set max-user-call-depth
+@item show max-user-call-depth
+@itemx set max-user-call-depth
+The value of @code{max-user-call-depth} controls how many recursion
+levels are allowed in user-defined commands before GDB suspects an
+infinite recursion and aborts the command.
@end table
-@node Alpha
-@subsection Alpha
+When user-defined commands are executed, the
+commands of the definition are not printed. An error in any command
+stops execution of the user-defined command.
-See the following section.
+If used interactively, commands that would ask for confirmation proceed
+without asking when used inside a user-defined command. Many @value{GDBN}
+commands that normally print messages to say what they are doing omit the
+messages when used in a user-defined command.
-@node MIPS
-@subsection MIPS
+@node Hooks
+@section User-defined command hooks
+@cindex command hooks
+@cindex hooks, for commands
+@cindex hooks, pre-command
-@cindex stack on Alpha
-@cindex stack on MIPS
-@cindex Alpha stack
-@cindex MIPS stack
-Alpha- and MIPS-based computers use an unusual stack frame, which
-sometimes requires @value{GDBN} to search backward in the object code to
-find the beginning of a function.
+@kindex hook
+@kindex hook-
+You may define @dfn{hooks}, which are a special kind of user-defined
+command. Whenever you run the command @samp{foo}, if the user-defined
+command @samp{hook-foo} exists, it is executed (with no arguments)
+before that command.
-@cindex response time, MIPS debugging
-To improve response time (especially for embedded applications, where
-@value{GDBN} may be restricted to a slow serial line for this search)
-you may want to limit the size of this search, using one of these
-commands:
+@cindex hooks, post-command
+@kindex hookpost
+@kindex hookpost-
+A hook may also be defined which is run after the command you executed.
+Whenever you run the command @samp{foo}, if the user-defined command
+@samp{hookpost-foo} exists, it is executed (with no arguments) after
+that command. Post-execution hooks may exist simultaneously with
+pre-execution hooks, for the same command.
-@table @code
-@cindex @code{heuristic-fence-post} (Alpha, MIPS)
-@item set heuristic-fence-post @var{limit}
-Restrict @value{GDBN} to examining at most @var{limit} bytes in its
-search for the beginning of a function. A value of @var{0} (the
-default) means there is no limit. However, except for @var{0}, the
-larger the limit the more bytes @code{heuristic-fence-post} must search
-and therefore the longer it takes to run.
+It is valid for a hook to call the command which it hooks. If this
+occurs, the hook is not re-executed, thereby avoiding infinte recursion.
-@item show heuristic-fence-post
-Display the current limit.
-@end table
+@c It would be nice if hookpost could be passed a parameter indicating
+@c if the command it hooks executed properly or not. FIXME!
-@noindent
-These commands are available @emph{only} when @value{GDBN} is configured
-for debugging programs on Alpha or MIPS processors.
+@kindex stop@r{, a pseudo-command}
+In addition, a pseudo-command, @samp{stop} exists. Defining
+(@samp{hook-stop}) makes the associated commands execute every time
+execution stops in your program: before breakpoint commands are run,
+displays are printed, or the stack frame is printed.
+For example, to ignore @code{SIGALRM} signals while
+single-stepping, but treat them normally during normal execution,
+you could define:
-@node Controlling GDB
-@chapter Controlling @value{GDBN}
+@smallexample
+define hook-stop
+handle SIGALRM nopass
+end
-You can alter the way @value{GDBN} interacts with you by using the
-@code{set} command. For commands controlling how @value{GDBN} displays
-data, see @ref{Print Settings, ,Print settings}. Other settings are
-described here.
+define hook-run
+handle SIGALRM pass
+end
-@menu
-* Prompt:: Prompt
-* Editing:: Command editing
-* History:: Command history
-* Screen Size:: Screen size
-* Numbers:: Numbers
-* Messages/Warnings:: Optional warnings and messages
-* Debugging Output:: Optional messages about internal happenings
-@end menu
+define hook-continue
+handle SIGLARM pass
+end
+@end smallexample
-@node Prompt
-@section Prompt
+As a further example, to hook at the begining and end of the @code{echo}
+command, and to add extra text to the beginning and end of the message,
+you could define:
-@cindex prompt
+@smallexample
+define hook-echo
+echo <<<---
+end
-@value{GDBN} indicates its readiness to read a command by printing a string
-called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
-can change the prompt string with the @code{set prompt} command. For
-instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
-the prompt in one of the @value{GDBN} sessions so that you can always tell
-which one you are talking to.
+define hookpost-echo
+echo --->>>\n
+end
-@emph{Note:} @code{set prompt} does not add a space for you after the
-prompt you set. This allows you to set a prompt which ends in a space
-or a prompt that does not.
+(@value{GDBP}) echo Hello World
+<<<---Hello World--->>>
+(@value{GDBP})
-@table @code
-@kindex set prompt
-@item set prompt @var{newprompt}
-Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
+@end smallexample
-@kindex show prompt
-@item show prompt
-Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
-@end table
+You can define a hook for any single-word command in @value{GDBN}, but
+not for command aliases; you should define a hook for the basic command
+name, e.g. @code{backtrace} rather than @code{bt}.
+@c FIXME! So how does Joe User discover whether a command is an alias
+@c or not?
+If an error occurs during the execution of your hook, execution of
+@value{GDBN} commands stops and @value{GDBN} issues a prompt
+(before the command that you actually typed had a chance to run).
-@node Editing
-@section Command editing
-@cindex readline
-@cindex command line editing
+If you try to define a hook which does not match any known command, you
+get a warning from the @code{define} command.
-@value{GDBN} reads its input commands via the @dfn{readline} interface. This
-@sc{gnu} library provides consistent behavior for programs which provide a
-command line interface to the user. Advantages are @sc{gnu} Emacs-style
-or @dfn{vi}-style inline editing of commands, @code{csh}-like history
-substitution, and a storage and recall of command history across
-debugging sessions.
+@node Command Files
+@section Command files
-You may control the behavior of command line editing in @value{GDBN} with the
-command @code{set}.
+@cindex command files
+A command file for @value{GDBN} is a file of lines that are @value{GDBN}
+commands. Comments (lines starting with @kbd{#}) may also be included.
+An empty line in a command file does nothing; it does not mean to repeat
+the last command, as it would from the terminal.
-@table @code
-@kindex set editing
-@cindex editing
-@item set editing
-@itemx set editing on
-Enable command line editing (enabled by default).
+@cindex init file
+@cindex @file{.gdbinit}
+@cindex @file{gdb.ini}
+When you start @value{GDBN}, it automatically executes commands from its
+@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
+port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
+limitations of file names imposed by DOS filesystems.}.
+During startup, @value{GDBN} does the following:
-@item set editing off
-Disable command line editing.
+@enumerate
+@item
+Reads the init file (if any) in your home directory@footnote{On
+DOS/Windows systems, the home directory is the one pointed to by the
+@code{HOME} environment variable.}.
-@kindex show editing
-@item show editing
-Show whether command line editing is enabled.
-@end table
+@item
+Processes command line options and operands.
-@node History
-@section Command history
+@item
+Reads the init file (if any) in the current working directory.
-@value{GDBN} can keep track of the commands you type during your
-debugging sessions, so that you can be certain of precisely what
-happened. Use these commands to manage the @value{GDBN} command
-history facility.
+@item
+Reads command files specified by the @samp{-x} option.
+@end enumerate
-@table @code
-@cindex history substitution
-@cindex history file
-@kindex set history filename
-@kindex GDBHISTFILE
-@item set history filename @var{fname}
-Set the name of the @value{GDBN} command history file to @var{fname}.
-This is the file where @value{GDBN} reads an initial command history
-list, and where it writes the command history from this session when it
-exits. You can access this list through history expansion or through
-the history command editing characters listed below. This file defaults
-to the value of the environment variable @code{GDBHISTFILE}, or to
-@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
-is not set.
+The init file in your home directory can set options (such as @samp{set
+complaints}) that affect subsequent processing of command line options
+and operands. Init files are not executed if you use the @samp{-nx}
+option (@pxref{Mode Options, ,Choosing modes}).
-@cindex history save
-@kindex set history save
-@item set history save
-@itemx set history save on
-Record command history in a file, whose name may be specified with the
-@code{set history filename} command. By default, this option is disabled.
+@cindex init file name
+On some configurations of @value{GDBN}, the init file is known by a
+different name (these are typically environments where a specialized
+form of @value{GDBN} may need to coexist with other forms, hence a
+different name for the specialized version's init file). These are the
+environments with special init file names:
+
+@cindex @file{.vxgdbinit}
+@itemize @bullet
+@item
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+
+@cindex @file{.os68gdbinit}
+@item
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-@item set history save off
-Stop recording command history in a file.
+@cindex @file{.esgdbinit}
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
+@end itemize
-@cindex history size
-@kindex set history size
-@item set history size @var{size}
-Set the number of commands which @value{GDBN} keeps in its history list.
-This defaults to the value of the environment variable
-@code{HISTSIZE}, or to 256 if this variable is not set.
+You can also request the execution of a command file with the
+@code{source} command:
+
+@table @code
+@kindex source
+@item source @var{filename}
+Execute the command file @var{filename}.
@end table
-@cindex history expansion
-History expansion assigns special meaning to the character @kbd{!}.
-@ifset have-readline-appendices
-@xref{Event Designators}.
-@end ifset
+The lines in a command file are executed sequentially. They are not
+printed as they are executed. An error in any command terminates
+execution of the command file and control is returned to the console.
-Since @kbd{!} is also the logical not operator in C, history expansion
-is off by default. If you decide to enable history expansion with the
-@code{set history expansion on} command, you may sometimes need to
-follow @kbd{!} (when it is used as logical not, in an expression) with
-a space or a tab to prevent it from being expanded. The readline
-history facilities do not attempt substitution on the strings
-@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
+Commands that would ask for confirmation if used interactively proceed
+without asking when used in a command file. Many @value{GDBN} commands that
+normally print messages to say what they are doing omit the messages
+when called from command files.
-The commands to control history expansion are:
+@value{GDBN} also accepts command input from standard input. In this
+mode, normal output goes to standard output and error output goes to
+standard error. Errors in a command file supplied on standard input do
+not terminate execution of the command file --- execution continues with
+the next command.
-@table @code
-@kindex set history expansion
-@item set history expansion on
-@itemx set history expansion
-Enable history expansion. History expansion is off by default.
+@smallexample
+gdb < cmds > log 2>&1
+@end smallexample
-@item set history expansion off
-Disable history expansion.
+(The syntax above will vary depending on the shell used.) This example
+will execute commands from the file @file{cmds}. All output and errors
+would be directed to @file{log}.
-The readline code comes with more complete documentation of
-editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
-or @code{vi} may wish to read it.
-@ifset have-readline-appendices
-@xref{Command Line Editing}.
-@end ifset
+@node Output
+@section Commands for controlled output
-@c @group
-@kindex show history
-@item show history
-@itemx show history filename
-@itemx show history save
-@itemx show history size
-@itemx show history expansion
-These commands display the state of the @value{GDBN} history parameters.
-@code{show history} by itself displays all four states.
-@c @end group
-@end table
+During the execution of a command file or a user-defined command, normal
+@value{GDBN} output is suppressed; the only output that appears is what is
+explicitly printed by the commands in the definition. This section
+describes three commands useful for generating exactly the output you
+want.
@table @code
-@kindex shows
-@item show commands
-Display the last ten commands in the command history.
+@kindex echo
+@item echo @var{text}
+@c I do not consider backslash-space a standard C escape sequence
+@c because it is not in ANSI.
+Print @var{text}. Nonprinting characters can be included in
+@var{text} using C escape sequences, such as @samp{\n} to print a
+newline. @strong{No newline is printed unless you specify one.}
+In addition to the standard C escape sequences, a backslash followed
+by a space stands for a space. This is useful for displaying a
+string with spaces at the beginning or the end, since leading and
+trailing spaces are otherwise trimmed from all arguments.
+To print @samp{@w{ }and foo =@w{ }}, use the command
+@samp{echo \@w{ }and foo = \@w{ }}.
-@item show commands @var{n}
-Print ten commands centered on command number @var{n}.
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines. For example,
-@item show commands +
-Print ten commands just after the commands last printed.
-@end table
+@smallexample
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end smallexample
-@node Screen Size
-@section Screen size
-@cindex size of screen
-@cindex pauses in output
+produces the same output as
-Certain commands to @value{GDBN} may produce large amounts of
-information output to the screen. To help you read all of it,
-@value{GDBN} pauses and asks you for input at the end of each page of
-output. Type @key{RET} when you want to continue the output, or @kbd{q}
-to discard the remaining output. Also, the screen width setting
-determines when to wrap lines of output. Depending on what is being
-printed, @value{GDBN} tries to break the line at a readable place,
-rather than simply letting it overflow onto the following line.
+@smallexample
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end smallexample
-Normally @value{GDBN} knows the size of the screen from the terminal
-driver software. For example, on Unix @value{GDBN} uses the termcap data base
-together with the value of the @code{TERM} environment variable and the
-@code{stty rows} and @code{stty cols} settings. If this is not correct,
-you can override it with the @code{set height} and @code{set
-width} commands:
+@kindex output
+@item output @var{expression}
+Print the value of @var{expression} and nothing but that value: no
+newlines, no @samp{$@var{nn} = }. The value is not entered in the
+value history either. @xref{Expressions, ,Expressions}, for more information
+on expressions.
-@table @code
-@kindex set height
-@kindex set width
-@kindex show width
-@kindex show height
-@item set height @var{lpp}
-@itemx show height
-@itemx set width @var{cpl}
-@itemx show width
-These @code{set} commands specify a screen height of @var{lpp} lines and
-a screen width of @var{cpl} characters. The associated @code{show}
-commands display the current settings.
+@item output/@var{fmt} @var{expression}
+Print the value of @var{expression} in format @var{fmt}. You can use
+the same formats as for @code{print}. @xref{Output Formats,,Output
+formats}, for more information.
-If you specify a height of zero lines, @value{GDBN} does not pause during
-output no matter how long the output is. This is useful if output is to a
-file or to an editor buffer.
+@kindex printf
+@item printf @var{string}, @var{expressions}@dots{}
+Print the values of the @var{expressions} under the control of
+@var{string}. The @var{expressions} are separated by commas and may be
+either numbers or pointers. Their values are printed as specified by
+@var{string}, exactly as if your program were to execute the C
+subroutine
+@c FIXME: the above implies that at least all ANSI C formats are
+@c supported, but it isn't true: %E and %G don't work (or so it seems).
+@c Either this is a bug, or the manual should document what formats are
+@c supported.
-Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
-from wrapping its output.
+@smallexample
+printf (@var{string}, @var{expressions}@dots{});
+@end smallexample
+
+For example, you can print two values in hex like this:
+
+@smallexample
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@end smallexample
+
+The only backslash-escape sequences that you can use in the format
+string are the simple ones that consist of backslash followed by a
+letter.
@end table
-@node Numbers
-@section Numbers
-@cindex number representation
-@cindex entering numbers
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
-You can always enter numbers in octal, decimal, or hexadecimal in
-@value{GDBN} by the usual conventions: octal numbers begin with
-@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
-begin with @samp{0x}. Numbers that begin with none of these are, by
-default, entered in base 10; likewise, the default display for
-numbers---when no particular format is specified---is base 10. You can
-change the default base for both input and output with the @code{set
-radix} command.
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Commands:: TUI specific commands
+* TUI Configuration:: TUI configuration variables
+@end menu
-@table @code
-@kindex set input-radix
-@item set input-radix @var{base}
-Set the default base for numeric input. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix; for
-example, any of
+The @value{GDBN} Text User Interface, TUI in short,
+is a terminal interface which uses the @code{curses} library
+to show the source file, the assembly output, the program registers
+and @value{GDBN} commands in separate text windows.
+The TUI is available only when @value{GDBN} is configured
+with the @code{--enable-tui} configure option (@pxref{Configure Options}).
-@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
-@end smallexample
+@node TUI Overview
+@section TUI overview
-@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+The TUI has two display modes that can be switched while
+@value{GDBN} runs:
-@kindex set output-radix
-@item set output-radix @var{base}
-Set the default base for numeric display. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix.
+@itemize @bullet
+@item
+A curses (or TUI) mode in which it displays several text
+windows on the terminal.
-@kindex show input-radix
-@item show input-radix
-Display the current default base for numeric input.
+@item
+A standard mode which corresponds to the @value{GDBN} configured without
+the TUI.
+@end itemize
-@kindex show output-radix
-@item show output-radix
-Display the current default base for numeric display.
-@end table
+In the TUI mode, @value{GDBN} can display several text window
+on the terminal:
+
+@table @emph
+@item command
+This window is the @value{GDBN} command window with the @value{GDBN}
+prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
+managed using readline but through the TUI. The @emph{command}
+window is always visible.
-@node Messages/Warnings
-@section Optional warnings and messages
+@item source
+The source window shows the source file of the program. The current
+line as well as active breakpoints are displayed in this window.
+The current program position is shown with the @samp{>} marker and
+active breakpoints are shown with @samp{*} markers.
-By default, @value{GDBN} is silent about its inner workings. If you are
-running on a slow machine, you may want to use the @code{set verbose}
-command. This makes @value{GDBN} tell you when it does a lengthy
-internal operation, so you will not think it has crashed.
+@item assembly
+The assembly window shows the disassembly output of the program.
-Currently, the messages controlled by @code{set verbose} are those
-which announce that the symbol table for a source file is being read;
-see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
+@item register
+This window shows the processor registers. It detects when
+a register is changed and when this is the case, registers that have
+changed are highlighted.
-@table @code
-@kindex set verbose
-@item set verbose on
-Enables @value{GDBN} output of certain informational messages.
+@end table
-@item set verbose off
-Disables @value{GDBN} output of certain informational messages.
+The source, assembly and register windows are attached to the thread
+and the frame position. They are updated when the current thread
+changes, when the frame changes or when the program counter changes.
+These three windows are arranged by the TUI according to several
+layouts. The layout defines which of these three windows are visible.
+The following layouts are available:
-@kindex show verbose
-@item show verbose
-Displays whether @code{set verbose} is on or off.
-@end table
+@itemize @bullet
+@item
+source
-By default, if @value{GDBN} encounters bugs in the symbol table of an
-object file, it is silent; but if you are debugging a compiler, you may
-find this information useful (@pxref{Symbol Errors, ,Errors reading
-symbol files}).
+@item
+assembly
-@table @code
+@item
+source and assembly
-@kindex set complaints
-@item set complaints @var{limit}
-Permits @value{GDBN} to output @var{limit} complaints about each type of
-unusual symbols before becoming silent about the problem. Set
-@var{limit} to zero to suppress all complaints; set it to a large number
-to prevent complaints from being suppressed.
+@item
+source and registers
-@kindex show complaints
-@item show complaints
-Displays how many symbol complaints @value{GDBN} is permitted to produce.
+@item
+assembly and registers
-@end table
+@end itemize
-By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
-lot of stupid questions to confirm certain commands. For example, if
-you try to run a program which is already running:
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
-@example
-(@value{GDBP}) run
-The program being debugged has been started already.
-Start it from the beginning? (y or n)
-@end example
+The TUI installs several key bindings in the readline keymaps
+(@pxref{Command Line Editing}).
+They allow to leave or enter in the TUI mode or they operate
+directly on the TUI layout and windows. The following key bindings
+are installed for both TUI mode and the @value{GDBN} standard mode.
-If you are willing to unflinchingly face the consequences of your own
-commands, you can disable this ``feature'':
+@table @kbd
+@kindex C-x C-a
+@item C-x C-a
+@kindex C-x a
+@itemx C-x a
+@kindex C-x A
+@itemx C-x A
+Enter or leave the TUI mode. When the TUI mode is left,
+the curses window management is left and @value{GDBN} operates using
+its standard mode writing on the terminal directly. When the TUI
+mode is entered, the control is given back to the curses windows.
+The screen is then refreshed.
-@table @code
+@kindex C-x 1
+@item C-x 1
+Use a TUI layout with only one window. The layout will
+either be @samp{source} or @samp{assembly}. When the TUI mode
+is not active, it will switch to the TUI mode.
-@kindex set confirm
-@cindex flinching
-@cindex confirmation
-@cindex stupid questions
-@item set confirm off
-Disables confirmation requests.
+Think of this key binding as the Emacs @kbd{C-x 1} binding.
-@item set confirm on
-Enables confirmation requests (the default).
+@kindex C-x 2
+@item C-x 2
+Use a TUI layout with at least two windows. When the current
+layout shows already two windows, a next layout with two windows is used.
+When a new layout is chosen, one window will always be common to the
+previous layout and the new one.
-@kindex show confirm
-@item show confirm
-Displays state of confirmation requests.
+Think of it as the Emacs @kbd{C-x 2} binding.
@end table
-@node Debugging Output
-@section Optional messages about internal happenings
-@table @code
-@kindex set debug arch
-@item set debug arch
-Turns on or off display of gdbarch debugging info. The default is off
-@kindex show debug arch
-@item show debug arch
-Displays the current state of displaying gdbarch debugging info.
-@kindex set debug event
-@item set debug event
-Turns on or off display of @value{GDBN} event debugging info. The
-default is off.
-@kindex show debug event
-@item show debug event
-Displays the current state of displaying @value{GDBN} event debugging
-info.
-@kindex set debug expression
-@item set debug expression
-Turns on or off display of @value{GDBN} expression debugging info. The
-default is off.
-@kindex show debug expression
-@item show debug expression
-Displays the current state of displaying @value{GDBN} expression
-debugging info.
-@kindex set debug overload
-@item set debug overload
-Turns on or off display of @value{GDBN} C@t{++} overload debugging
-info. This includes info such as ranking of functions, etc. The default
-is off.
-@kindex show debug overload
-@item show debug overload
-Displays the current state of displaying @value{GDBN} C@t{++} overload
-debugging info.
-@kindex set debug remote
-@cindex packets, reporting on stdout
-@cindex serial connections, debugging
-@item set debug remote
-Turns on or off display of reports on all packets sent back and forth across
-the serial line to the remote machine. The info is printed on the
-@value{GDBN} standard output stream. The default is off.
-@kindex show debug remote
-@item show debug remote
-Displays the state of display of remote packets.
-@kindex set debug serial
-@item set debug serial
-Turns on or off display of @value{GDBN} serial debugging info. The
-default is off.
-@kindex show debug serial
-@item show debug serial
-Displays the current state of displaying @value{GDBN} serial debugging
-info.
-@kindex set debug target
-@item set debug target
-Turns on or off display of @value{GDBN} target debugging info. This info
-includes what is going on at the target level of GDB, as it happens. The
-default is off.
-@kindex show debug target
-@item show debug target
-Displays the current state of displaying @value{GDBN} target debugging
-info.
-@kindex set debug varobj
-@item set debug varobj
-Turns on or off display of @value{GDBN} variable object debugging
-info. The default is off.
-@kindex show debug varobj
-@item show debug varobj
-Displays the current state of displaying @value{GDBN} variable object
-debugging info.
-@end table
+The following key bindings are handled only by the TUI mode:
-@node Sequences
-@chapter Canned Sequences of Commands
+@table @key
+@kindex PgUp
+@item PgUp
+Scroll the active window one page up.
-Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
-command lists}), @value{GDBN} provides two ways to store sequences of
-commands for execution as a unit: user-defined commands and command
-files.
+@kindex PgDn
+@item PgDn
+Scroll the active window one page down.
-@menu
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
-@end menu
+@kindex Up
+@item Up
+Scroll the active window one line up.
-@node Define
-@section User-defined commands
+@kindex Down
+@item Down
+Scroll the active window one line down.
-@cindex user-defined command
-A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
-which you assign a new name as a command. This is done with the
-@code{define} command. User commands may accept up to 10 arguments
-separated by whitespace. Arguments are accessed within the user command
-via @var{$arg0@dots{}$arg9}. A trivial example:
+@kindex Left
+@item Left
+Scroll the active window one column left.
-@smallexample
-define adder
- print $arg0 + $arg1 + $arg2
-@end smallexample
+@kindex Right
+@item Right
+Scroll the active window one column right.
-@noindent
-To execute the command use:
+@kindex C-L
+@item C-L
+Refresh the screen.
-@smallexample
-adder 1 2 3
-@end smallexample
+@end table
-@noindent
-This defines the command @code{adder}, which prints the sum of
-its three arguments. Note the arguments are text substitutions, so they may
-reference variables, use complex expressions, or even perform inferior
-functions calls.
+In the TUI mode, the arrow keys are used by the active window
+for scrolling. This means they are not available for readline. It is
+necessary to use other readline key bindings such as @key{C-p}, @key{C-n},
+@key{C-b} and @key{C-f}.
+
+@node TUI Commands
+@section TUI specific commands
+@cindex TUI commands
+
+The TUI has specific commands to control the text windows.
+These commands are always available, that is they do not depend on
+the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
+is in the standard mode, using these commands will automatically switch
+in the TUI mode.
@table @code
+@item layout next
+@kindex layout next
+Display the next layout.
-@kindex define
-@item define @var{commandname}
-Define a command named @var{commandname}. If there is already a command
-by that name, you are asked to confirm that you want to redefine it.
+@item layout prev
+@kindex layout prev
+Display the previous layout.
-The definition of the command is made up of other @value{GDBN} command lines,
-which are given following the @code{define} command. The end of these
-commands is marked by a line containing @code{end}.
+@item layout src
+@kindex layout src
+Display the source window only.
-@kindex if
-@kindex else
-@item if
-Takes a single argument, which is an expression to evaluate.
-It is followed by a series of commands that are executed
-only if the expression is true (nonzero).
-There can then optionally be a line @code{else}, followed
-by a series of commands that are only executed if the expression
-was false. The end of the list is marked by a line containing @code{end}.
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
-@kindex while
-@item while
-The syntax is similar to @code{if}: the command takes a single argument,
-which is an expression to evaluate, and must be followed by the commands to
-execute, one per line, terminated by an @code{end}.
-The commands are executed repeatedly as long as the expression
-evaluates to true.
+@item layout split
+@kindex layout split
+Display the source and assembly window.
-@kindex document
-@item document @var{commandname}
-Document the user-defined command @var{commandname}, so that it can be
-accessed by @code{help}. The command @var{commandname} must already be
-defined. This command reads lines of documentation just as @code{define}
-reads the lines of the command definition, ending with @code{end}.
-After the @code{document} command is finished, @code{help} on command
-@var{commandname} displays the documentation you have written.
+@item layout regs
+@kindex layout regs
+Display the register window together with the source or assembly window.
-You may use the @code{document} command again to change the
-documentation of a command. Redefining the command with @code{define}
-does not change the documentation.
+@item focus next | prev | src | asm | regs | split
+@kindex focus
+Set the focus to the named window.
+This command allows to change the active window so that scrolling keys
+can be affected to another window.
-@kindex help user-defined
-@item help user-defined
-List all user-defined commands, with the first line of the documentation
-(if any) for each.
+@item refresh
+@kindex refresh
+Refresh the screen. This is similar to using @key{C-L} key.
-@kindex show user
-@item show user
-@itemx show user @var{commandname}
-Display the @value{GDBN} commands used to define @var{commandname} (but
-not its documentation). If no @var{commandname} is given, display the
-definitions for all user-defined commands.
+@item update
+@kindex update
+Update the source window and the current execution point.
+
+@item winheight @var{name} +@var{count}
+@itemx winheight @var{name} -@var{count}
+@kindex winheight
+Change the height of the window @var{name} by @var{count}
+lines. Positive counts increase the height, while negative counts
+decrease it.
@end table
-When user-defined commands are executed, the
-commands of the definition are not printed. An error in any command
-stops execution of the user-defined command.
+@node TUI Configuration
+@section TUI configuration variables
+@cindex TUI configuration variables
-If used interactively, commands that would ask for confirmation proceed
-without asking when used inside a user-defined command. Many @value{GDBN}
-commands that normally print messages to say what they are doing omit the
-messages when used in a user-defined command.
+The TUI has several configuration variables that control the
+appearance of windows on the terminal.
-@node Hooks
-@section User-defined command hooks
-@cindex command hooks
-@cindex hooks, for commands
-@cindex hooks, pre-command
+@table @code
+@item set tui border-kind @var{kind}
+@kindex set tui border-kind
+Select the border appearance for the source, assembly and register windows.
+The possible values are the following:
+@table @code
+@item space
+Use a space character to draw the border.
-@kindex hook
-@kindex hook-
-You may define @dfn{hooks}, which are a special kind of user-defined
-command. Whenever you run the command @samp{foo}, if the user-defined
-command @samp{hook-foo} exists, it is executed (with no arguments)
-before that command.
+@item ascii
+Use ascii characters + - and | to draw the border.
-@cindex hooks, post-command
-@kindex hookpost
-@kindex hookpost-
-A hook may also be defined which is run after the command you executed.
-Whenever you run the command @samp{foo}, if the user-defined command
-@samp{hookpost-foo} exists, it is executed (with no arguments) after
-that command. Post-execution hooks may exist simultaneously with
-pre-execution hooks, for the same command.
+@item acs
+Use the Alternate Character Set to draw the border. The border is
+drawn using character line graphics if the terminal supports them.
-It is valid for a hook to call the command which it hooks. If this
-occurs, the hook is not re-executed, thereby avoiding infinte recursion.
+@end table
-@c It would be nice if hookpost could be passed a parameter indicating
-@c if the command it hooks executed properly or not. FIXME!
+@item set tui active-border-mode @var{mode}
+@kindex set tui active-border-mode
+Select the attributes to display the border of the active window.
+The possible values are @code{normal}, @code{standout}, @code{reverse},
+@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
-@kindex stop@r{, a pseudo-command}
-In addition, a pseudo-command, @samp{stop} exists. Defining
-(@samp{hook-stop}) makes the associated commands execute every time
-execution stops in your program: before breakpoint commands are run,
-displays are printed, or the stack frame is printed.
+@item set tui border-mode @var{mode}
+@kindex set tui border-mode
+Select the attributes to display the border of other windows.
+The @var{mode} can be one of the following:
+@table @code
+@item normal
+Use normal attributes to display the border.
-For example, to ignore @code{SIGALRM} signals while
-single-stepping, but treat them normally during normal execution,
-you could define:
+@item standout
+Use standout mode.
-@example
-define hook-stop
-handle SIGALRM nopass
-end
+@item reverse
+Use reverse video mode.
-define hook-run
-handle SIGALRM pass
-end
+@item half
+Use half bright mode.
-define hook-continue
-handle SIGLARM pass
-end
-@end example
+@item half-standout
+Use half bright and standout mode.
-As a further example, to hook at the begining and end of the @code{echo}
-command, and to add extra text to the beginning and end of the message,
-you could define:
+@item bold
+Use extra bright or bold mode.
-@example
-define hook-echo
-echo <<<---
-end
+@item bold-standout
+Use extra bright or bold and standout mode.
-define hookpost-echo
-echo --->>>\n
-end
+@end table
-(@value{GDBP}) echo Hello World
-<<<---Hello World--->>>
-(@value{GDBP})
+@end table
+
+@node Emacs
+@chapter Using @value{GDBN} under @sc{gnu} Emacs
-@end example
+@cindex Emacs
+@cindex @sc{gnu} Emacs
+A special interface allows you to use @sc{gnu} Emacs to view (and
+edit) the source files for the program you are debugging with
+@value{GDBN}.
-You can define a hook for any single-word command in @value{GDBN}, but
-not for command aliases; you should define a hook for the basic command
-name, e.g. @code{backtrace} rather than @code{bt}.
-@c FIXME! So how does Joe User discover whether a command is an alias
-@c or not?
-If an error occurs during the execution of your hook, execution of
-@value{GDBN} commands stops and @value{GDBN} issues a prompt
-(before the command that you actually typed had a chance to run).
+To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
+executable file you want to debug as an argument. This command starts
+@value{GDBN} as a subprocess of Emacs, with input and output through a newly
+created Emacs buffer.
+@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
-If you try to define a hook which does not match any known command, you
-get a warning from the @code{define} command.
+Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
+things:
-@node Command Files
-@section Command files
+@itemize @bullet
+@item
+All ``terminal'' input and output goes through the Emacs buffer.
+@end itemize
-@cindex command files
-A command file for @value{GDBN} is a file of lines that are @value{GDBN}
-commands. Comments (lines starting with @kbd{#}) may also be included.
-An empty line in a command file does nothing; it does not mean to repeat
-the last command, as it would from the terminal.
+This applies both to @value{GDBN} commands and their output, and to the input
+and output done by the program you are debugging.
-@cindex init file
-@cindex @file{.gdbinit}
-@cindex @file{gdb.ini}
-When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
-port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
-limitations of file names imposed by DOS filesystems.}.
-During startup, @value{GDBN} does the following:
+This is useful because it means that you can copy the text of previous
+commands and input them again; you can even use parts of the output
+in this way.
-@enumerate
+All the facilities of Emacs' Shell mode are available for interacting
+with your program. In particular, you can send signals the usual
+way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
+stop.
+
+@itemize @bullet
@item
-Reads the init file (if any) in your home directory@footnote{On
-DOS/Windows systems, the home directory is the one pointed to by the
-@code{HOME} environment variable.}.
+@value{GDBN} displays source code through Emacs.
+@end itemize
+
+Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
+source file for that frame and puts an arrow (@samp{=>}) at the
+left margin of the current line. Emacs uses a separate buffer for
+source display, and splits the screen to show both your @value{GDBN} session
+and the source.
-@item
-Processes command line options and operands.
+Explicit @value{GDBN} @code{list} or search commands still produce output as
+usual, but you probably have no reason to use them from Emacs.
-@item
-Reads the init file (if any) in the current working directory.
+@quotation
+@emph{Warning:} If the directory where your program resides is not your
+current directory, it can be easy to confuse Emacs about the location of
+the source files, in which case the auxiliary display buffer does not
+appear to show your source. @value{GDBN} can find programs by searching your
+environment's @code{PATH} variable, so the @value{GDBN} input and output
+session proceeds normally; but Emacs does not get enough information
+back from @value{GDBN} to locate the source files in this situation. To
+avoid this problem, either start @value{GDBN} mode from the directory where
+your program resides, or specify an absolute file name when prompted for the
+@kbd{M-x gdb} argument.
-@item
-Reads command files specified by the @samp{-x} option.
-@end enumerate
+A similar confusion can result if you use the @value{GDBN} @code{file} command to
+switch to debugging a program in some other location, from an existing
+@value{GDBN} buffer in Emacs.
+@end quotation
-The init file in your home directory can set options (such as @samp{set
-complaints}) that affect subsequent processing of command line options
-and operands. Init files are not executed if you use the @samp{-nx}
-option (@pxref{Mode Options, ,Choosing modes}).
+By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
+you need to call @value{GDBN} by a different name (for example, if you keep
+several configurations around, with different names) you can set the
+Emacs variable @code{gdb-command-name}; for example,
-@cindex init file name
-On some configurations of @value{GDBN}, the init file is known by a
-different name (these are typically environments where a specialized
-form of @value{GDBN} may need to coexist with other forms, hence a
-different name for the specialized version's init file). These are the
-environments with special init file names:
+@smallexample
+(setq gdb-command-name "mygdb")
+@end smallexample
-@cindex @file{.vxgdbinit}
-@itemize @bullet
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+@noindent
+(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or
+in your @file{.emacs} file) makes Emacs call the program named
+``@code{mygdb}'' instead.
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
+addition to the standard Shell mode commands:
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-@end itemize
+@table @kbd
+@item C-h m
+Describe the features of Emacs' @value{GDBN} Mode.
-You can also request the execution of a command file with the
-@code{source} command:
+@item M-s
+Execute to another source line, like the @value{GDBN} @code{step} command; also
+update the display window to show the current file and location.
-@table @code
-@kindex source
-@item source @var{filename}
-Execute the command file @var{filename}.
-@end table
+@item M-n
+Execute to next source line in this function, skipping all function
+calls, like the @value{GDBN} @code{next} command. Then update the display window
+to show the current file and location.
-The lines in a command file are executed sequentially. They are not
-printed as they are executed. An error in any command terminates execution
-of the command file.
+@item M-i
+Execute one instruction, like the @value{GDBN} @code{stepi} command; update
+display window accordingly.
-Commands that would ask for confirmation if used interactively proceed
-without asking when used in a command file. Many @value{GDBN} commands that
-normally print messages to say what they are doing omit the messages
-when called from command files.
+@item M-x gdb-nexti
+Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
+display window accordingly.
-@value{GDBN} also accepts command input from standard input. In this
-mode, normal output goes to standard output and error output goes to
-standard error. Errors in a command file supplied on standard input do
-not terminate execution of the command file --- execution continues with
-the next command.
+@item C-c C-f
+Execute until exit from the selected stack frame, like the @value{GDBN}
+@code{finish} command.
-@example
-gdb < cmds > log 2>&1
-@end example
+@item M-c
+Continue execution of your program, like the @value{GDBN} @code{continue}
+command.
-(The syntax above will vary depending on the shell used.) This example
-will execute commands from the file @file{cmds}. All output and errors
-would be directed to @file{log}.
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
-@node Output
-@section Commands for controlled output
+@item M-u
+Go up the number of frames indicated by the numeric argument
+(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
+like the @value{GDBN} @code{up} command.
-During the execution of a command file or a user-defined command, normal
-@value{GDBN} output is suppressed; the only output that appears is what is
-explicitly printed by the commands in the definition. This section
-describes three commands useful for generating exactly the output you
-want.
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
-@table @code
-@kindex echo
-@item echo @var{text}
-@c I do not consider backslash-space a standard C escape sequence
-@c because it is not in ANSI.
-Print @var{text}. Nonprinting characters can be included in
-@var{text} using C escape sequences, such as @samp{\n} to print a
-newline. @strong{No newline is printed unless you specify one.}
-In addition to the standard C escape sequences, a backslash followed
-by a space stands for a space. This is useful for displaying a
-string with spaces at the beginning or the end, since leading and
-trailing spaces are otherwise trimmed from all arguments.
-To print @samp{@w{ }and foo =@w{ }}, use the command
-@samp{echo \@w{ }and foo = \@w{ }}.
+@item M-d
+Go down the number of frames indicated by the numeric argument, like the
+@value{GDBN} @code{down} command.
-A backslash at the end of @var{text} can be used, as in C, to continue
-the command onto subsequent lines. For example,
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
-@example
-echo This is some text\n\
-which is continued\n\
-onto several lines.\n
-@end example
+@item C-x &
+Read the number where the cursor is positioned, and insert it at the end
+of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
+around an address that was displayed earlier, type @kbd{disassemble};
+then move the cursor to the address display, and pick up the
+argument for @code{disassemble} by typing @kbd{C-x &}.
-produces the same output as
+You can customize this further by defining elements of the list
+@code{gdb-print-command}; once it is defined, you can format or
+otherwise process numbers picked up by @kbd{C-x &} before they are
+inserted. A numeric argument to @kbd{C-x &} indicates that you
+wish special formatting, and also acts as an index to pick an element of the
+list. If the list element is a string, the number to be inserted is
+formatted using the Emacs function @code{format}; otherwise the number
+is passed as an argument to the corresponding list element.
+@end table
-@example
-echo This is some text\n
-echo which is continued\n
-echo onto several lines.\n
-@end example
+In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
+tells @value{GDBN} to set a breakpoint on the source line point is on.
-@kindex output
-@item output @var{expression}
-Print the value of @var{expression} and nothing but that value: no
-newlines, no @samp{$@var{nn} = }. The value is not entered in the
-value history either. @xref{Expressions, ,Expressions}, for more information
-on expressions.
+If you accidentally delete the source-display buffer, an easy way to get
+it back is to type the command @code{f} in the @value{GDBN} buffer, to
+request a frame display; when you run under Emacs, this recreates
+the source buffer if necessary to show you the context of the current
+frame.
-@item output/@var{fmt} @var{expression}
-Print the value of @var{expression} in format @var{fmt}. You can use
-the same formats as for @code{print}. @xref{Output Formats,,Output
-formats}, for more information.
+The source files displayed in Emacs are in ordinary Emacs buffers
+which are visiting the source files in the usual way. You can edit
+the files with these buffers if you wish; but keep in mind that @value{GDBN}
+communicates with Emacs in terms of line numbers. If you add or
+delete lines from the text, the line numbers that @value{GDBN} knows cease
+to correspond properly with the code.
-@kindex printf
-@item printf @var{string}, @var{expressions}@dots{}
-Print the values of the @var{expressions} under the control of
-@var{string}. The @var{expressions} are separated by commas and may be
-either numbers or pointers. Their values are printed as specified by
-@var{string}, exactly as if your program were to execute the C
-subroutine
-@c FIXME: the above implies that at least all ANSI C formats are
-@c supported, but it isn't true: %E and %G don't work (or so it seems).
-@c Either this is a bug, or the manual should document what formats are
-@c supported.
+@c The following dropped because Epoch is nonstandard. Reactivate
+@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
+@ignore
+@kindex Emacs Epoch environment
+@kindex Epoch
+@kindex inspect
-@example
-printf (@var{string}, @var{expressions}@dots{});
-@end example
+Version 18 of @sc{gnu} Emacs has a built-in window system
+called the @code{epoch}
+environment. Users of this environment can use a new command,
+@code{inspect} which performs identically to @code{print} except that
+each value is printed in its own window.
+@end ignore
-For example, you can print two values in hex like this:
+@include annotate.texi
+@include gdbmi.texinfo
-@smallexample
-printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
-@end smallexample
+@node GDB Bugs
+@chapter Reporting Bugs in @value{GDBN}
+@cindex bugs in @value{GDBN}
+@cindex reporting bugs in @value{GDBN}
-The only backslash-escape sequences that you can use in the format
-string are the simple ones that consist of backslash followed by a
-letter.
-@end table
+Your bug reports play an essential role in making @value{GDBN} reliable.
-@node TUI
-@chapter @value{GDBN} Text User Interface
-@cindex TUI
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not. But in any case the principal function of a bug report is to help
+the entire community by making the next version of @value{GDBN} work better. Bug
+reports are your contribution to the maintenance of @value{GDBN}.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
@menu
-* TUI Overview:: TUI overview
-* TUI Keys:: TUI key bindings
-* TUI Commands:: TUI specific commands
-* TUI Configuration:: TUI configuration variables
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
@end menu
-The @value{GDBN} Text User Interface, TUI in short,
-is a terminal interface which uses the @code{curses} library
-to show the source file, the assembly output, the program registers
-and @value{GDBN} commands in separate text windows.
-The TUI is available only when @value{GDBN} is configured
-with the @code{--enable-tui} configure option (@pxref{Configure Options}).
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
-@node TUI Overview
-@section TUI overview
+If you are not sure whether you have found a bug, here are some guidelines:
-The TUI has two display modes that can be switched while
-@value{GDBN} runs:
+@itemize @bullet
+@cindex fatal signal
+@cindex debugger crash
+@cindex crash of debugger
+@item
+If the debugger gets a fatal signal, for any input whatever, that is a
+@value{GDBN} bug. Reliable debuggers never crash.
-@itemize @bullet
+@cindex error on valid input
@item
-A curses (or TUI) mode in which it displays several text
-windows on the terminal.
+If @value{GDBN} produces an error message for valid input, that is a
+bug. (Note that if you're cross debugging, the problem may also be
+somewhere in the connection to the target.)
+
+@cindex invalid input
+@item
+If @value{GDBN} does not produce an error message for invalid input,
+that is a bug. However, you should note that your idea of
+``invalid input'' might be our idea of ``an extension'' or ``support
+for traditional practice''.
@item
-A standard mode which corresponds to the @value{GDBN} configured without
-the TUI.
+If you are an experienced user of debugging tools, your suggestions
+for improvement of @value{GDBN} are welcome in any case.
@end itemize
-In the TUI mode, @value{GDBN} can display several text window
-on the terminal:
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex @value{GDBN} bugs, reporting
-@table @emph
-@item command
-This window is the @value{GDBN} command window with the @value{GDBN}
-prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
-managed using readline but through the TUI. The @emph{command}
-window is always visible.
+A number of companies and individuals offer support for @sc{gnu} products.
+If you obtained @value{GDBN} from a support organization, we recommend you
+contact that organization first.
-@item source
-The source window shows the source file of the program. The current
-line as well as active breakpoints are displayed in this window.
-The current program position is shown with the @samp{>} marker and
-active breakpoints are shown with @samp{*} markers.
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+@c should add a web page ref...
-@item assembly
-The assembly window shows the disassembly output of the program.
+In any event, we also recommend that you submit bug reports for
+@value{GDBN}. The prefered method is to submit them directly using
+@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
+page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
+be used.
-@item register
-This window shows the processor registers. It detects when
-a register is changed and when this is the case, registers that have
-changed are highlighted.
+@strong{Do not send bug reports to @samp{info-gdb}, or to
+@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
+not want to receive bug reports. Those that do have arranged to receive
+@samp{bug-gdb}.
-@end table
+The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
+serves as a repeater. The mailing list and the newsgroup carry exactly
+the same messages. Often people think of posting bug reports to the
+newsgroup instead of mailing them. This appears to work, but it has one
+problem which can be crucial: a newsgroup posting often lacks a mail
+path back to the sender. Thus, if we need to ask for more information,
+we may be unable to reach you. For this reason, it is better to send
+bug reports to the mailing list.
-The source, assembly and register windows are attached to the thread
-and the frame position. They are updated when the current thread
-changes, when the frame changes or when the program counter changes.
-These three windows are arranged by the TUI according to several
-layouts. The layout defines which of these three windows are visible.
-The following layouts are available:
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}. If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter. Thus, you might
+assume that the name of the variable you use in an example does not matter.
+Well, probably it does not, but one cannot be sure. Perhaps the bug is a
+stray memory reference which happens to fetch from the location where that
+name is stored in memory; perhaps, if the name were different, the contents
+of that location would fool the debugger into doing the right thing despite
+the bug. Play it safe and give a specific, complete example. That is the
+easiest thing for you to do, and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the
+bug. It may be that the bug has been reported previously, but neither
+you nor we can know that unless your bug report is complete and
+self-contained.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?'' Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
@itemize @bullet
@item
-source
+The version of @value{GDBN}. @value{GDBN} announces it if you start
+with no arguments; you can also print it at any time using @code{show
+version}.
-@item
-assembly
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @value{GDBN}.
@item
-source and assembly
+The type of machine you are using, and the operating system name and
+version number.
@item
-source and registers
+What compiler (and its version) was used to compile @value{GDBN}---e.g.
+``@value{GCC}--2.8.1''.
@item
-assembly and registers
-
-@end itemize
-
-@node TUI Keys
-@section TUI Key Bindings
-@cindex TUI key bindings
+What compiler (and its version) was used to compile the program you are
+debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
+C Compiler''. For GCC, you can say @code{gcc --version} to get this
+information; for other compilers, see the documentation for those
+compilers.
-The TUI installs several key bindings in the readline keymaps
-(@pxref{Command Line Editing}).
-They allow to leave or enter in the TUI mode or they operate
-directly on the TUI layout and windows. The following key bindings
-are installed for both TUI mode and the @value{GDBN} standard mode.
+@item
+The command arguments you gave the compiler to compile your example and
+observe the bug. For example, did you use @samp{-O}? To guarantee
+you will not omit something important, list them all. A copy of the
+Makefile (or the output from make) is sufficient.
-@table @kbd
-@kindex C-x C-a
-@item C-x C-a
-@kindex C-x a
-@itemx C-x a
-@kindex C-x A
-@itemx C-x A
-Enter or leave the TUI mode. When the TUI mode is left,
-the curses window management is left and @value{GDBN} operates using
-its standard mode writing on the terminal directly. When the TUI
-mode is entered, the control is given back to the curses windows.
-The screen is then refreshed.
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
-@kindex C-x 1
-@item C-x 1
-Use a TUI layout with only one window. The layout will
-either be @samp{source} or @samp{assembly}. When the TUI mode
-is not active, it will switch to the TUI mode.
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.
-Think of this key binding as the Emacs @kbd{C-x 1} binding.
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
-@kindex C-x 2
-@item C-x 2
-Use a TUI layout with at least two windows. When the current
-layout shows already two windows, a next layout with two windows is used.
-When a new layout is chosen, one window will always be common to the
-previous layout and the new one.
+Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
+will certainly notice it. But if the bug is incorrect output, we might
+not notice unless it is glaringly wrong. You might as well not give us
+a chance to make a mistake.
-Think of it as the Emacs @kbd{C-x 2} binding.
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly. Suppose something strange is going on, such as, your
+copy of @value{GDBN} is out of synch, or you have encountered a bug in
+the C library on your system. (This has happened!) Your copy might
+crash and ours would not. If you told us to expect a crash, then when
+ours fails to crash, we would know that the bug was not happening for
+us. If you had not told us to expect a crash, then we would not be able
+to draw any conclusion from our observations.
-@end table
+@item
+If you wish to suggest changes to the @value{GDBN} source, send us context
+diffs. If you even discuss something in the @value{GDBN} source, refer to
+it by context, not by line number.
-The following key bindings are handled only by the TUI mode:
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
-@table @key
-@kindex PgUp
-@item PgUp
-Scroll the active window one page up.
+@end itemize
-@kindex PgDn
-@item PgDn
-Scroll the active window one page down.
+Here are some things that are not necessary:
-@kindex Up
-@item Up
-Scroll the active window one line up.
+@itemize @bullet
+@item
+A description of the envelope of the bug.
-@kindex Down
-@item Down
-Scroll the active window one line down.
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
-@kindex Left
-@item Left
-Scroll the active window one column left.
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
-@kindex Right
-@item Right
-Scroll the active window one column right.
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us. Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
-@kindex C-L
-@item C-L
-Refresh the screen.
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
-@end table
+@item
+A patch for the bug.
-In the TUI mode, the arrow keys are used by the active window
-for scrolling. This means they are not available for readline. It is
-necessary to use other readline key bindings such as @key{C-p}, @key{C-n},
-@key{C-b} and @key{C-f}.
+A patch for the bug does help us if it is a good one. But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need. We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
-@node TUI Commands
-@section TUI specific commands
-@cindex TUI commands
+Sometimes with a program as complicated as @value{GDBN} it is very hard to
+construct an example that will make the program follow a certain path
+through the code. If you do not send us the example, we will not be able
+to construct one, so we will not be able to verify that the bug is fixed.
-The TUI has specific commands to control the text windows.
-These commands are always available, that is they do not depend on
-the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
-is in the standard mode, using these commands will automatically switch
-in the TUI mode.
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it. A test case will
+help us to understand.
-@table @code
-@item layout next
-@kindex layout next
-Display the next layout.
+@item
+A guess about what the bug is or what it depends on.
-@item layout prev
-@kindex layout prev
-Display the previous layout.
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
-@item layout src
-@kindex layout src
-Display the source window only.
+@c The readline documentation is distributed with the readline code
+@c and consists of the two following files:
+@c rluser.texinfo
+@c inc-hist.texinfo
+@c Use -I with makeinfo to point to the appropriate directory,
+@c environment var TEXINPUTS with TeX.
+@include rluser.texinfo
+@include inc-hist.texinfo
-@item layout asm
-@kindex layout asm
-Display the assembly window only.
-@item layout split
-@kindex layout split
-Display the source and assembly window.
+@node Formatting Documentation
+@appendix Formatting Documentation
-@item layout regs
-@kindex layout regs
-Display the register window together with the source or assembly window.
+@cindex @value{GDBN} reference card
+@cindex reference card
+The @value{GDBN} 4 release includes an already-formatted reference card, ready
+for printing with PostScript or Ghostscript, in the @file{gdb}
+subdirectory of the main source directory@footnote{In
+@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
+release.}. If you can use PostScript or Ghostscript with your printer,
+you can print the reference card immediately with @file{refcard.ps}.
-@item focus next | prev | src | asm | regs | split
-@kindex focus
-Set the focus to the named window.
-This command allows to change the active window so that scrolling keys
-can be affected to another window.
+The release also includes the source for the reference card. You
+can format it, using @TeX{}, by typing:
-@item refresh
-@kindex refresh
-Refresh the screen. This is similar to using @key{C-L} key.
+@smallexample
+make refcard.dvi
+@end smallexample
-@item update
-@kindex update
-Update the source window and the current execution point.
+The @value{GDBN} reference card is designed to print in @dfn{landscape}
+mode on US ``letter'' size paper;
+that is, on a sheet 11 inches wide by 8.5 inches
+high. You will need to specify this form of printing as an option to
+your @sc{dvi} output program.
-@item winheight @var{name} +@var{count}
-@itemx winheight @var{name} -@var{count}
-@kindex winheight
-Change the height of the window @var{name} by @var{count}
-lines. Positive counts increase the height, while negative counts
-decrease it.
+@cindex documentation
-@end table
+All the documentation for @value{GDBN} comes as part of the machine-readable
+distribution. The documentation is written in Texinfo format, which is
+a documentation system that uses a single source file to produce both
+on-line information and a printed manual. You can use one of the Info
+formatting commands to create the on-line version of the documentation
+and @TeX{} (or @code{texi2roff}) to typeset the printed version.
-@node TUI Configuration
-@section TUI configuration variables
-@cindex TUI configuration variables
+@value{GDBN} includes an already formatted copy of the on-line Info
+version of this manual in the @file{gdb} subdirectory. The main Info
+file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
+subordinate files matching @samp{gdb.info*} in the same directory. If
+necessary, you can print out these files, or read them with any editor;
+but they are easier to read using the @code{info} subsystem in @sc{gnu}
+Emacs or the standalone @code{info} program, available as part of the
+@sc{gnu} Texinfo distribution.
-The TUI has several configuration variables that control the
-appearance of windows on the terminal.
+If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as @code{texinfo-format-buffer} or
+@code{makeinfo}.
-@table @code
-@item set tui border-kind @var{kind}
-@kindex set tui border-kind
-Select the border appearance for the source, assembly and register windows.
-The possible values are the following:
-@table @code
-@item space
-Use a space character to draw the border.
+If you have @code{makeinfo} installed, and are in the top level
+@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
+version @value{GDBVN}), you can make the Info file by typing:
-@item ascii
-Use ascii characters + - and | to draw the border.
+@smallexample
+cd gdb
+make gdb.info
+@end smallexample
-@item acs
-Use the Alternate Character Set to draw the border. The border is
-drawn using character line graphics if the terminal supports them.
+If you want to typeset and print copies of this manual, you need @TeX{},
+a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
+Texinfo definitions file.
-@end table
+@TeX{} is a typesetting program; it does not print files directly, but
+produces output files called @sc{dvi} files. To print a typeset
+document, you need a program to print @sc{dvi} files. If your system
+has @TeX{} installed, chances are it has such a program. The precise
+command to use depends on your system; @kbd{lpr -d} is common; another
+(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
+require a file name without any extension or a @samp{.dvi} extension.
-@item set tui active-border-mode @var{mode}
-@kindex set tui active-border-mode
-Select the attributes to display the border of the active window.
-The possible values are @code{normal}, @code{standout}, @code{reverse},
-@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
+@TeX{} also requires a macro definitions file called
+@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
+written in Texinfo format. On its own, @TeX{} cannot either read or
+typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
+and is located in the @file{gdb-@var{version-number}/texinfo}
+directory.
-@item set tui border-mode @var{mode}
-@kindex set tui border-mode
-Select the attributes to display the border of other windows.
-The @var{mode} can be one of the following:
-@table @code
-@item normal
-Use normal attributes to display the border.
+If you have @TeX{} and a @sc{dvi} printer program installed, you can
+typeset and print this manual. First switch to the the @file{gdb}
+subdirectory of the main source directory (for example, to
+@file{gdb-@value{GDBVN}/gdb}) and type:
-@item standout
-Use standout mode.
+@smallexample
+make gdb.dvi
+@end smallexample
-@item reverse
-Use reverse video mode.
+Then give @file{gdb.dvi} to your @sc{dvi} printing program.
-@item half
-Use half bright mode.
+@node Installing GDB
+@appendix Installing @value{GDBN}
+@cindex configuring @value{GDBN}
+@cindex installation
-@item half-standout
-Use half bright and standout mode.
+@value{GDBN} comes with a @code{configure} script that automates the process
+of preparing @value{GDBN} for installation; you can then use @code{make} to
+build the @code{gdb} program.
+@iftex
+@c irrelevant in info file; it's as current as the code it lives with.
+@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
+look at the @file{README} file in the sources; we may have improved the
+installation procedures since publishing this manual.}
+@end iftex
-@item bold
-Use extra bright or bold mode.
+The @value{GDBN} distribution includes all the source code you need for
+@value{GDBN} in a single directory, whose name is usually composed by
+appending the version number to @samp{gdb}.
-@item bold-standout
-Use extra bright or bold and standout mode.
+For example, the @value{GDBN} version @value{GDBVN} distribution is in the
+@file{gdb-@value{GDBVN}} directory. That directory contains:
-@end table
+@table @code
+@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
+script for configuring @value{GDBN} and all its supporting libraries
-@end table
+@item gdb-@value{GDBVN}/gdb
+the source specific to @value{GDBN} itself
-@node Emacs
-@chapter Using @value{GDBN} under @sc{gnu} Emacs
+@item gdb-@value{GDBVN}/bfd
+source for the Binary File Descriptor library
-@cindex Emacs
-@cindex @sc{gnu} Emacs
-A special interface allows you to use @sc{gnu} Emacs to view (and
-edit) the source files for the program you are debugging with
-@value{GDBN}.
+@item gdb-@value{GDBVN}/include
+@sc{gnu} include files
-To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
-executable file you want to debug as an argument. This command starts
-@value{GDBN} as a subprocess of Emacs, with input and output through a newly
-created Emacs buffer.
-@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
+@item gdb-@value{GDBVN}/libiberty
+source for the @samp{-liberty} free software library
-Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
-things:
+@item gdb-@value{GDBVN}/opcodes
+source for the library of opcode tables and disassemblers
-@itemize @bullet
-@item
-All ``terminal'' input and output goes through the Emacs buffer.
-@end itemize
+@item gdb-@value{GDBVN}/readline
+source for the @sc{gnu} command-line interface
-This applies both to @value{GDBN} commands and their output, and to the input
-and output done by the program you are debugging.
+@item gdb-@value{GDBVN}/glob
+source for the @sc{gnu} filename pattern-matching subroutine
-This is useful because it means that you can copy the text of previous
-commands and input them again; you can even use parts of the output
-in this way.
+@item gdb-@value{GDBVN}/mmalloc
+source for the @sc{gnu} memory-mapped malloc package
+@end table
-All the facilities of Emacs' Shell mode are available for interacting
-with your program. In particular, you can send signals the usual
-way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
-stop.
+The simplest way to configure and build @value{GDBN} is to run @code{configure}
+from the @file{gdb-@var{version-number}} source directory, which in
+this example is the @file{gdb-@value{GDBVN}} directory.
-@itemize @bullet
-@item
-@value{GDBN} displays source code through Emacs.
-@end itemize
+First switch to the @file{gdb-@var{version-number}} source directory
+if you are not already in it; then run @code{configure}. Pass the
+identifier for the platform on which @value{GDBN} will run as an
+argument.
-Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
-source file for that frame and puts an arrow (@samp{=>}) at the
-left margin of the current line. Emacs uses a separate buffer for
-source display, and splits the screen to show both your @value{GDBN} session
-and the source.
+For example:
-Explicit @value{GDBN} @code{list} or search commands still produce output as
-usual, but you probably have no reason to use them from Emacs.
+@smallexample
+cd gdb-@value{GDBVN}
+./configure @var{host}
+make
+@end smallexample
-@quotation
-@emph{Warning:} If the directory where your program resides is not your
-current directory, it can be easy to confuse Emacs about the location of
-the source files, in which case the auxiliary display buffer does not
-appear to show your source. @value{GDBN} can find programs by searching your
-environment's @code{PATH} variable, so the @value{GDBN} input and output
-session proceeds normally; but Emacs does not get enough information
-back from @value{GDBN} to locate the source files in this situation. To
-avoid this problem, either start @value{GDBN} mode from the directory where
-your program resides, or specify an absolute file name when prompted for the
-@kbd{M-x gdb} argument.
+@noindent
+where @var{host} is an identifier such as @samp{sun4} or
+@samp{decstation}, that identifies the platform where @value{GDBN} will run.
+(You can often leave off @var{host}; @code{configure} tries to guess the
+correct value by examining your system.)
-A similar confusion can result if you use the @value{GDBN} @code{file} command to
-switch to debugging a program in some other location, from an existing
-@value{GDBN} buffer in Emacs.
-@end quotation
+Running @samp{configure @var{host}} and then running @code{make} builds the
+@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
+libraries, then @code{gdb} itself. The configured source files, and the
+binaries, are left in the corresponding source directories.
-By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
-you need to call @value{GDBN} by a different name (for example, if you keep
-several configurations around, with different names) you can set the
-Emacs variable @code{gdb-command-name}; for example,
+@need 750
+@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
+system does not recognize this automatically when you run a different
+shell, you may need to run @code{sh} on it explicitly:
-@example
-(setq gdb-command-name "mygdb")
-@end example
+@smallexample
+sh configure @var{host}
+@end smallexample
-@noindent
-(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or
-in your @file{.emacs} file) makes Emacs call the program named
-``@code{mygdb}'' instead.
+If you run @code{configure} from a directory that contains source
+directories for multiple libraries or programs, such as the
+@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
+creates configuration files for every directory level underneath (unless
+you tell it not to, with the @samp{--norecursion} option).
-In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
-addition to the standard Shell mode commands:
+You can run the @code{configure} script from any of the
+subordinate directories in the @value{GDBN} distribution if you only want to
+configure that subdirectory, but be sure to specify a path to it.
-@table @kbd
-@item C-h m
-Describe the features of Emacs' @value{GDBN} Mode.
+For example, with version @value{GDBVN}, type the following to configure only
+the @code{bfd} subdirectory:
-@item M-s
-Execute to another source line, like the @value{GDBN} @code{step} command; also
-update the display window to show the current file and location.
+@smallexample
+@group
+cd gdb-@value{GDBVN}/bfd
+../configure @var{host}
+@end group
+@end smallexample
-@item M-n
-Execute to next source line in this function, skipping all function
-calls, like the @value{GDBN} @code{next} command. Then update the display window
-to show the current file and location.
+You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
+However, you should make sure that the shell on your path (named by
+the @samp{SHELL} environment variable) is publicly readable. Remember
+that @value{GDBN} uses the shell to start your program---some systems refuse to
+let @value{GDBN} debug child processes whose programs are not readable.
-@item M-i
-Execute one instruction, like the @value{GDBN} @code{stepi} command; update
-display window accordingly.
+@menu
+* Separate Objdir:: Compiling @value{GDBN} in another directory
+* Config Names:: Specifying names for hosts and targets
+* Configure Options:: Summary of options for configure
+@end menu
-@item M-x gdb-nexti
-Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
-display window accordingly.
+@node Separate Objdir
+@section Compiling @value{GDBN} in another directory
-@item C-c C-f
-Execute until exit from the selected stack frame, like the @value{GDBN}
-@code{finish} command.
+If you want to run @value{GDBN} versions for several host or target machines,
+you need a different @code{gdb} compiled for each combination of
+host and target. @code{configure} is designed to make this easy by
+allowing you to generate each configuration in a separate subdirectory,
+rather than in the source directory. If your @code{make} program
+handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
+@code{make} in each of these directories builds the @code{gdb}
+program specified there.
-@item M-c
-Continue execution of your program, like the @value{GDBN} @code{continue}
-command.
+To build @code{gdb} in a separate directory, run @code{configure}
+with the @samp{--srcdir} option to specify where to find the source.
+(You also need to specify a path to find @code{configure}
+itself from your working directory. If the path to @code{configure}
+would be the same as the argument to @samp{--srcdir}, you can leave out
+the @samp{--srcdir} option; it is assumed.)
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+separate directory for a Sun 4 like this:
-@item M-u
-Go up the number of frames indicated by the numeric argument
-(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
-like the @value{GDBN} @code{up} command.
+@smallexample
+@group
+cd gdb-@value{GDBVN}
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-@value{GDBVN}/configure sun4
+make
+@end group
+@end smallexample
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
+When @code{configure} builds a configuration using a remote source
+directory, it creates a tree for the binaries with the same structure
+(and using the same names) as the tree under the source directory. In
+the example, you'd find the Sun 4 library @file{libiberty.a} in the
+directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
+@file{gdb-sun4/gdb}.
-@item M-d
-Go down the number of frames indicated by the numeric argument, like the
-@value{GDBN} @code{down} command.
+One popular reason to build several @value{GDBN} configurations in separate
+directories is to configure @value{GDBN} for cross-compiling (where
+@value{GDBN} runs on one machine---the @dfn{host}---while debugging
+programs that run on another machine---the @dfn{target}).
+You specify a cross-debugging target by
+giving the @samp{--target=@var{target}} option to @code{configure}.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
+When you run @code{make} to build a program or library, you must run
+it in a configured directory---whatever directory you were in when you
+called @code{configure} (or one of its subdirectories).
-@item C-x &
-Read the number where the cursor is positioned, and insert it at the end
-of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
-around an address that was displayed earlier, type @kbd{disassemble};
-then move the cursor to the address display, and pick up the
-argument for @code{disassemble} by typing @kbd{C-x &}.
+The @code{Makefile} that @code{configure} generates in each source
+directory also runs recursively. If you type @code{make} in a source
+directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
+directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
+will build all the required libraries, and then build GDB.
-You can customize this further by defining elements of the list
-@code{gdb-print-command}; once it is defined, you can format or
-otherwise process numbers picked up by @kbd{C-x &} before they are
-inserted. A numeric argument to @kbd{C-x &} indicates that you
-wish special formatting, and also acts as an index to pick an element of the
-list. If the list element is a string, the number to be inserted is
-formatted using the Emacs function @code{format}; otherwise the number
-is passed as an argument to the corresponding list element.
-@end table
+When you have multiple hosts or targets configured in separate
+directories, you can run @code{make} on them in parallel (for example,
+if they are NFS-mounted on each of the hosts); they will not interfere
+with each other.
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
-tells @value{GDBN} to set a breakpoint on the source line point is on.
+@node Config Names
+@section Specifying names for hosts and targets
-If you accidentally delete the source-display buffer, an easy way to get
-it back is to type the command @code{f} in the @value{GDBN} buffer, to
-request a frame display; when you run under Emacs, this recreates
-the source buffer if necessary to show you the context of the current
-frame.
+The specifications used for hosts and targets in the @code{configure}
+script are based on a three-part naming scheme, but some short predefined
+aliases are also supported. The full naming scheme encodes three pieces
+of information in the following pattern:
-The source files displayed in Emacs are in ordinary Emacs buffers
-which are visiting the source files in the usual way. You can edit
-the files with these buffers if you wish; but keep in mind that @value{GDBN}
-communicates with Emacs in terms of line numbers. If you add or
-delete lines from the text, the line numbers that @value{GDBN} knows cease
-to correspond properly with the code.
+@smallexample
+@var{architecture}-@var{vendor}-@var{os}
+@end smallexample
-@c The following dropped because Epoch is nonstandard. Reactivate
-@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
-@ignore
-@kindex Emacs Epoch environment
-@kindex Epoch
-@kindex inspect
+For example, you can use the alias @code{sun4} as a @var{host} argument,
+or as the value for @var{target} in a @code{--target=@var{target}}
+option. The equivalent full name is @samp{sparc-sun-sunos4}.
-Version 18 of @sc{gnu} Emacs has a built-in window system
-called the @code{epoch}
-environment. Users of this environment can use a new command,
-@code{inspect} which performs identically to @code{print} except that
-each value is printed in its own window.
-@end ignore
+The @code{configure} script accompanying @value{GDBN} does not provide
+any query facility to list all supported host and target names or
+aliases. @code{configure} calls the Bourne shell script
+@code{config.sub} to map abbreviations to full names; you can read the
+script, if you wish, or you can use it to test your guesses on
+abbreviations---for example:
-@include annotate.texi
-@include gdbmi.texinfo
+@smallexample
+% sh config.sub i386-linux
+i386-pc-linux-gnu
+% sh config.sub alpha-linux
+alpha-unknown-linux-gnu
+% sh config.sub hp9k700
+hppa1.1-hp-hpux
+% sh config.sub sun4
+sparc-sun-sunos4.1.1
+% sh config.sub sun3
+m68k-sun-sunos4.1.1
+% sh config.sub i986v
+Invalid configuration `i986v': machine `i986v' not recognized
+@end smallexample
-@node GDB Bugs
-@chapter Reporting Bugs in @value{GDBN}
-@cindex bugs in @value{GDBN}
-@cindex reporting bugs in @value{GDBN}
+@noindent
+@code{config.sub} is also distributed in the @value{GDBN} source
+directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-Your bug reports play an essential role in making @value{GDBN} reliable.
+@node Configure Options
+@section @code{configure} options
-Reporting a bug may help you by bringing a solution to your problem, or it
-may not. But in any case the principal function of a bug report is to help
-the entire community by making the next version of @value{GDBN} work better. Bug
-reports are your contribution to the maintenance of @value{GDBN}.
+Here is a summary of the @code{configure} options and arguments that
+are most often useful for building @value{GDBN}. @code{configure} also has
+several other options not listed here. @inforef{What Configure
+Does,,configure.info}, for a full explanation of @code{configure}.
-In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
+@smallexample
+configure @r{[}--help@r{]}
+ @r{[}--prefix=@var{dir}@r{]}
+ @r{[}--exec-prefix=@var{dir}@r{]}
+ @r{[}--srcdir=@var{dirname}@r{]}
+ @r{[}--norecursion@r{]} @r{[}--rm@r{]}
+ @r{[}--target=@var{target}@r{]}
+ @var{host}
+@end smallexample
-@menu
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-@end menu
+@noindent
+You may introduce options with a single @samp{-} rather than
+@samp{--} if you prefer; but you may abbreviate option names if you use
+@samp{--}.
-@node Bug Criteria
-@section Have you found a bug?
-@cindex bug criteria
+@table @code
+@item --help
+Display a quick summary of how to invoke @code{configure}.
-If you are not sure whether you have found a bug, here are some guidelines:
+@item --prefix=@var{dir}
+Configure the source to install programs and files under directory
+@file{@var{dir}}.
-@itemize @bullet
-@cindex fatal signal
-@cindex debugger crash
-@cindex crash of debugger
-@item
-If the debugger gets a fatal signal, for any input whatever, that is a
-@value{GDBN} bug. Reliable debuggers never crash.
+@item --exec-prefix=@var{dir}
+Configure the source to install programs under directory
+@file{@var{dir}}.
-@cindex error on valid input
-@item
-If @value{GDBN} produces an error message for valid input, that is a
-bug. (Note that if you're cross debugging, the problem may also be
-somewhere in the connection to the target.)
+@c avoid splitting the warning from the explanation:
+@need 2000
+@item --srcdir=@var{dirname}
+@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
+@code{make} that implements the @code{VPATH} feature.}@*
+Use this option to make configurations in directories separate from the
+@value{GDBN} source directories. Among other things, you can use this to
+build (or maintain) several configurations simultaneously, in separate
+directories. @code{configure} writes configuration specific files in
+the current directory, but arranges for them to use the source in the
+directory @var{dirname}. @code{configure} creates directories under
+the working directory in parallel to the source directories below
+@var{dirname}.
-@cindex invalid input
-@item
-If @value{GDBN} does not produce an error message for invalid input,
-that is a bug. However, you should note that your idea of
-``invalid input'' might be our idea of ``an extension'' or ``support
-for traditional practice''.
+@item --norecursion
+Configure only the directory level where @code{configure} is executed; do not
+propagate configuration to subdirectories.
-@item
-If you are an experienced user of debugging tools, your suggestions
-for improvement of @value{GDBN} are welcome in any case.
-@end itemize
+@item --target=@var{target}
+Configure @value{GDBN} for cross-debugging programs running on the specified
+@var{target}. Without this option, @value{GDBN} is configured to debug
+programs that run on the same machine (@var{host}) as @value{GDBN} itself.
-@node Bug Reporting
-@section How to report bugs
-@cindex bug reports
-@cindex @value{GDBN} bugs, reporting
+There is no convenient way to generate a list of all available targets.
-A number of companies and individuals offer support for @sc{gnu} products.
-If you obtained @value{GDBN} from a support organization, we recommend you
-contact that organization first.
+@item @var{host} @dots{}
+Configure @value{GDBN} to run on the specified @var{host}.
-You can find contact information for many support companies and
-individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
-distribution.
-@c should add a web page ref...
+There is no convenient way to generate a list of all available hosts.
+@end table
-In any event, we also recommend that you send bug reports for
-@value{GDBN} to this addresses:
+There are many other options available as well, but they are generally
+needed for special purposes only.
-@example
-bug-gdb@@gnu.org
-@end example
+@node Maintenance Commands
+@appendix Maintenance Commands
+@cindex maintenance commands
+@cindex internal commands
-@strong{Do not send bug reports to @samp{info-gdb}, or to
-@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
-not want to receive bug reports. Those that do have arranged to receive
-@samp{bug-gdb}.
+In addition to commands intended for @value{GDBN} users, @value{GDBN}
+includes a number of commands intended for @value{GDBN} developers.
+These commands are provided here for reference.
-The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
-serves as a repeater. The mailing list and the newsgroup carry exactly
-the same messages. Often people think of posting bug reports to the
-newsgroup instead of mailing them. This appears to work, but it has one
-problem which can be crucial: a newsgroup posting often lacks a mail
-path back to the sender. Thus, if we need to ask for more information,
-we may be unable to reach you. For this reason, it is better to send
-bug reports to the mailing list.
+@table @code
+@kindex maint info breakpoints
+@item @anchor{maint info breakpoints}maint info breakpoints
+Using the same format as @samp{info breakpoints}, display both the
+breakpoints you've set explicitly, and those @value{GDBN} is using for
+internal purposes. Internal breakpoints are shown with negative
+breakpoint numbers. The type column identifies what kind of breakpoint
+is shown:
-As a last resort, send bug reports on paper to:
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
-@example
-@sc{gnu} Debugger Bugs
-Free Software Foundation Inc.
-59 Temple Place - Suite 330
-Boston, MA 02111-1307
-USA
-@end example
+@item watchpoint
+Normal, explicitly set watchpoint.
-The fundamental principle of reporting bugs usefully is this:
-@strong{report all the facts}. If you are not sure whether to state a
-fact or leave it out, state it!
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
-Often people omit facts because they think they know what causes the
-problem and assume that some details do not matter. Thus, you might
-assume that the name of the variable you use in an example does not matter.
-Well, probably it does not, but one cannot be sure. Perhaps the bug is a
-stray memory reference which happens to fetch from the location where that
-name is stored in memory; perhaps, if the name were different, the contents
-of that location would fool the debugger into doing the right thing despite
-the bug. Play it safe and give a specific, complete example. That is the
-easiest thing for you to do, and the most helpful.
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
-Keep in mind that the purpose of a bug report is to enable us to fix the
-bug. It may be that the bug has been reported previously, but neither
-you nor we can know that unless your bug report is complete and
-self-contained.
+@item until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
-Sometimes people give a few sketchy facts and ask, ``Does this ring a
-bell?'' Those bug reports are useless, and we urge everyone to
-@emph{refuse to respond to them} except to chide the sender to report
-bugs properly.
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
-To enable us to fix the bug, you should include all these things:
+@item shlib events
+Shared library events.
-@itemize @bullet
-@item
-The version of @value{GDBN}. @value{GDBN} announces it if you start
-with no arguments; you can also print it at any time using @code{show
-version}.
+@end table
-Without this, we will not know whether there is any point in looking for
-the bug in the current version of @value{GDBN}.
+@end table
-@item
-The type of machine you are using, and the operating system name and
-version number.
-@item
-What compiler (and its version) was used to compile @value{GDBN}---e.g.
-``@value{GCC}--2.8.1''.
+@node Remote Protocol
+@appendix @value{GDBN} Remote Serial Protocol
-@item
-What compiler (and its version) was used to compile the program you are
-debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
-C Compiler''. For GCC, you can say @code{gcc --version} to get this
-information; for other compilers, see the documentation for those
-compilers.
+There may be occasions when you need to know something about the
+protocol---for example, if there is only one serial port to your target
+machine, you might want your program to do something special if it
+recognizes a packet meant for @value{GDBN}.
-@item
-The command arguments you gave the compiler to compile your example and
-observe the bug. For example, did you use @samp{-O}? To guarantee
-you will not omit something important, list them all. A copy of the
-Makefile (or the output from make) is sufficient.
+In the examples below, @samp{<-} and @samp{->} are used to indicate
+transmitted and received data respectfully.
-If we were to try to guess the arguments, we would probably guess wrong
-and then we might not encounter the bug.
+@cindex protocol, @value{GDBN} remote serial
+@cindex serial protocol, @value{GDBN} remote
+@cindex remote serial protocol
+All @value{GDBN} commands and responses (other than acknowledgments) are
+sent as a @var{packet}. A @var{packet} is introduced with the character
+@samp{$}, the actual @var{packet-data}, and the terminating character
+@samp{#} followed by a two-digit @var{checksum}:
-@item
-A complete input script, and all necessary source files, that will
-reproduce the bug.
+@smallexample
+@code{$}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
+@noindent
-@item
-A description of what behavior you observe that you believe is
-incorrect. For example, ``It gets a fatal signal.''
+@cindex checksum, for @value{GDBN} remote
+@noindent
+The two-digit @var{checksum} is computed as the modulo 256 sum of all
+characters between the leading @samp{$} and the trailing @samp{#} (an
+eight bit unsigned checksum).
-Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
-will certainly notice it. But if the bug is incorrect output, we might
-not notice unless it is glaringly wrong. You might as well not give us
-a chance to make a mistake.
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
-Even if the problem you experience is a fatal signal, you should still
-say so explicitly. Suppose something strange is going on, such as, your
-copy of @value{GDBN} is out of synch, or you have encountered a bug in
-the C library on your system. (This has happened!) Your copy might
-crash and ours would not. If you told us to expect a crash, then when
-ours fails to crash, we would know that the bug was not happening for
-us. If you had not told us to expect a crash, then we would not be able
-to draw any conclusion from our observations.
+@smallexample
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
-@item
-If you wish to suggest changes to the @value{GDBN} source, send us context
-diffs. If you even discuss something in the @value{GDBN} source, refer to
-it by context, not by line number.
+@cindex sequence-id, for @value{GDBN} remote
+@noindent
+That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
+has never output @var{sequence-id}s. Stubs that handle packets added
+since @value{GDBN} 5.0 must not accept @var{sequence-id}.
-The line numbers in our development sources will not match those in your
-sources. Your line numbers would convey no useful information to us.
+@cindex acknowledgment, for @value{GDBN} remote
+When either the host or the target machine receives a packet, the first
+response expected is an acknowledgment: either @samp{+} (to indicate
+the package was received correctly) or @samp{-} (to request
+retransmission):
-@end itemize
+@smallexample
+<- @code{$}@var{packet-data}@code{#}@var{checksum}
+-> @code{+}
+@end smallexample
+@noindent
-Here are some things that are not necessary:
+The host (@value{GDBN}) sends @var{command}s, and the target (the
+debugging stub incorporated in your program) sends a @var{response}. In
+the case of step and continue @var{command}s, the response is only sent
+when the operation has completed (the target has again stopped).
-@itemize @bullet
-@item
-A description of the envelope of the bug.
+@var{packet-data} consists of a sequence of characters with the
+exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
+exceptions).
-Often people who encounter a bug spend a lot of time investigating
-which changes to the input file will make the bug go away and which
-changes will not affect it.
+Fields within the packet should be separated using @samp{,} @samp{;} or
+@samp{:}. Except where otherwise noted all numbers are represented in
+HEX with leading zeros suppressed.
-This is often time consuming and not very useful, because the way we
-will find the bug is by running a single example under the debugger
-with breakpoints, not by pure deduction from a series of examples.
-We recommend that you save your time for something else.
+Implementors should note that prior to @value{GDBN} 5.0, the character
+@samp{:} could not appear as the third character in a packet (as it
+would potentially conflict with the @var{sequence-id}).
-Of course, if you can find a simpler example to report @emph{instead}
-of the original one, that is a convenience for us. Errors in the
-output will be easier to spot, running under the debugger will take
-less time, and so on.
+Response @var{data} can be run-length encoded to save space. A @samp{*}
+means that the next character is an @sc{ascii} encoding giving a repeat count
+which stands for that many repetitions of the character preceding the
+@samp{*}. The encoding is @code{n+29}, yielding a printable character
+where @code{n >=3} (which is where rle starts to win). The printable
+characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
+value greater than 126 should not be used.
-However, simplification is not vital; if you do not want to do this,
-report the bug anyway and send us the entire test case you used.
+Some remote systems have used a different run-length encoding mechanism
+loosely refered to as the cisco encoding. Following the @samp{*}
+character are two hex digits that indicate the size of the packet.
-@item
-A patch for the bug.
+So:
+@smallexample
+"@code{0* }"
+@end smallexample
+@noindent
+means the same as "0000".
-A patch for the bug does help us if it is a good one. But do not omit
-the necessary information, such as the test case, on the assumption that
-a patch is all we need. We might see problems with your patch and decide
-to fix the problem another way, or we might not understand it at all.
+The error response returned for some packets includes a two character
+error number. That number is not well defined.
-Sometimes with a program as complicated as @value{GDBN} it is very hard to
-construct an example that will make the program follow a certain path
-through the code. If you do not send us the example, we will not be able
-to construct one, so we will not be able to verify that the bug is fixed.
+For any @var{command} not supported by the stub, an empty response
+(@samp{$#00}) should be returned. That way it is possible to extend the
+protocol. A newer @value{GDBN} can tell if a packet is supported based
+on that response.
-And if we cannot understand what bug you are trying to fix, or why your
-patch should be an improvement, we will not install it. A test case will
-help us to understand.
+A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
+@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
+optional.
-@item
-A guess about what the bug is or what it depends on.
+Below is a complete list of all currently defined @var{command}s and
+their corresponding response @var{data}:
+@page
+@multitable @columnfractions .30 .30 .40
+@item Packet
+@tab Request
+@tab Description
-Such guesses are usually wrong. Even we cannot guess right about such
-things without first using the debugger to find the facts.
-@end itemize
+@item extended mode
+@tab @code{!}
+@tab
+Enable extended mode. In extended mode, the remote server is made
+persistent. The @samp{R} packet is used to restart the program being
+debugged.
+@item
+@tab reply @samp{OK}
+@tab
+The remote target both supports and has enabled extended mode.
-@c The readline documentation is distributed with the readline code
-@c and consists of the two following files:
-@c rluser.texinfo
-@c inc-hist.texinfo
-@c Use -I with makeinfo to point to the appropriate directory,
-@c environment var TEXINPUTS with TeX.
-@include rluser.texinfo
-@include inc-hist.texinfo
+@item last signal
+@tab @code{?}
+@tab
+Indicate the reason the target halted. The reply is the same as for step
+and continue.
+@item
+@tab reply
+@tab see below
-@node Formatting Documentation
-@appendix Formatting Documentation
+@item reserved
+@tab @code{a}
+@tab Reserved for future use
-@cindex @value{GDBN} reference card
-@cindex reference card
-The @value{GDBN} 4 release includes an already-formatted reference card, ready
-for printing with PostScript or Ghostscript, in the @file{gdb}
-subdirectory of the main source directory@footnote{In
-@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
-release.}. If you can use PostScript or Ghostscript with your printer,
-you can print the reference card immediately with @file{refcard.ps}.
+@item set program arguments @strong{(reserved)}
+@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
+@tab
+@item
+@tab
+@tab
+Initialized @samp{argv[]} array passed into program. @var{arglen}
+specifies the number of bytes in the hex encoded byte stream @var{arg}.
+See @file{gdbserver} for more details.
+@item
+@tab reply @code{OK}
+@item
+@tab reply @code{E}@var{NN}
-The release also includes the source for the reference card. You
-can format it, using @TeX{}, by typing:
+@item set baud @strong{(deprecated)}
+@tab @code{b}@var{baud}
+@tab
+Change the serial line speed to @var{baud}. JTC: @emph{When does the
+transport layer state change? When it's received, or after the ACK is
+transmitted. In either case, there are problems if the command or the
+acknowledgment packet is dropped.} Stan: @emph{If people really wanted
+to add something like this, and get it working for the first time, they
+ought to modify ser-unix.c to send some kind of out-of-band message to a
+specially-setup stub and have the switch happen "in between" packets, so
+that from remote protocol's point of view, nothing actually
+happened.}
-@example
-make refcard.dvi
-@end example
+@item set breakpoint @strong{(deprecated)}
+@tab @code{B}@var{addr},@var{mode}
+@tab
+Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
+breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
+@samp{z} packets.}
-The @value{GDBN} reference card is designed to print in @dfn{landscape}
-mode on US ``letter'' size paper;
-that is, on a sheet 11 inches wide by 8.5 inches
-high. You will need to specify this form of printing as an option to
-your @sc{dvi} output program.
+@item continue
+@tab @code{c}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+current address.
+@item
+@tab reply
+@tab see below
-@cindex documentation
+@item continue with signal
+@tab @code{C}@var{sig}@code{;}@var{addr}
+@tab
+Continue with signal @var{sig} (hex signal number). If
+@code{;}@var{addr} is omitted, resume at same address.
+@item
+@tab reply
+@tab see below
-All the documentation for @value{GDBN} comes as part of the machine-readable
-distribution. The documentation is written in Texinfo format, which is
-a documentation system that uses a single source file to produce both
-on-line information and a printed manual. You can use one of the Info
-formatting commands to create the on-line version of the documentation
-and @TeX{} (or @code{texi2roff}) to typeset the printed version.
+@item toggle debug @strong{(deprecated)}
+@tab @code{d}
+@tab
+toggle debug flag.
-@value{GDBN} includes an already formatted copy of the on-line Info
-version of this manual in the @file{gdb} subdirectory. The main Info
-file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
-subordinate files matching @samp{gdb.info*} in the same directory. If
-necessary, you can print out these files, or read them with any editor;
-but they are easier to read using the @code{info} subsystem in @sc{gnu}
-Emacs or the standalone @code{info} program, available as part of the
-@sc{gnu} Texinfo distribution.
+@item detach
+@tab @code{D}
+@tab
+Detach @value{GDBN} from the remote system. Sent to the remote target before
+@value{GDBN} disconnects.
+@item
+@tab reply @emph{no response}
+@tab
+@value{GDBN} does not check for any response after sending this packet.
-If you want to format these Info files yourself, you need one of the
-Info formatting programs, such as @code{texinfo-format-buffer} or
-@code{makeinfo}.
+@item reserved
+@tab @code{e}
+@tab Reserved for future use
-If you have @code{makeinfo} installed, and are in the top level
-@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
-version @value{GDBVN}), you can make the Info file by typing:
+@item reserved
+@tab @code{E}
+@tab Reserved for future use
-@example
-cd gdb
-make gdb.info
-@end example
+@item reserved
+@tab @code{f}
+@tab Reserved for future use
-If you want to typeset and print copies of this manual, you need @TeX{},
-a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
-Texinfo definitions file.
+@item reserved
+@tab @code{F}
+@tab Reserved for future use
-@TeX{} is a typesetting program; it does not print files directly, but
-produces output files called @sc{dvi} files. To print a typeset
-document, you need a program to print @sc{dvi} files. If your system
-has @TeX{} installed, chances are it has such a program. The precise
-command to use depends on your system; @kbd{lpr -d} is common; another
-(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
-require a file name without any extension or a @samp{.dvi} extension.
+@item read registers
+@tab @code{g}
+@tab Read general registers.
+@item
+@tab reply @var{XX...}
+@tab
+Each byte of register data is described by two hex digits. The bytes
+with the register are transmitted in target byte order. The size of
+each register and their position within the @samp{g} @var{packet} are
+determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and
+@var{REGISTER_NAME} macros. The specification of several standard
+@code{g} packets is specified below.
+@item
+@tab @code{E}@var{NN}
+@tab for an error.
-@TeX{} also requires a macro definitions file called
-@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
-written in Texinfo format. On its own, @TeX{} cannot either read or
-typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
-and is located in the @file{gdb-@var{version-number}/texinfo}
-directory.
+@item write regs
+@tab @code{G}@var{XX...}
+@tab
+See @samp{g} for a description of the @var{XX...} data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
-If you have @TeX{} and a @sc{dvi} printer program installed, you can
-typeset and print this manual. First switch to the the @file{gdb}
-subdirectory of the main source directory (for example, to
-@file{gdb-@value{GDBVN}/gdb}) and type:
+@item reserved
+@tab @code{h}
+@tab Reserved for future use
-@example
-make gdb.dvi
-@end example
+@item set thread
+@tab @code{H}@var{c}@var{t...}
+@tab
+Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
+@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and
+continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for
+thread used in other operations. If zero, pick a thread, any thread.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
-Then give @file{gdb.dvi} to your @sc{dvi} printing program.
+@c FIXME: JTC:
+@c 'H': How restrictive (or permissive) is the thread model. If a
+@c thread is selected and stopped, are other threads allowed
+@c to continue to execute? As I mentioned above, I think the
+@c semantics of each command when a thread is selected must be
+@c described. For example:
+@c
+@c 'g': If the stub supports threads and a specific thread is
+@c selected, returns the register block from that thread;
+@c otherwise returns current registers.
+@c
+@c 'G' If the stub supports threads and a specific thread is
+@c selected, sets the registers of the register block of
+@c that thread; otherwise sets current registers.
-@node Installing GDB
-@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
-@cindex installation
+@item cycle step @strong{(draft)}
+@tab @code{i}@var{addr}@code{,}@var{nnn}
+@tab
+Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
+present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
+step starting at that address.
-@value{GDBN} comes with a @code{configure} script that automates the process
-of preparing @value{GDBN} for installation; you can then use @code{make} to
-build the @code{gdb} program.
-@iftex
-@c irrelevant in info file; it's as current as the code it lives with.
-@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
-look at the @file{README} file in the sources; we may have improved the
-installation procedures since publishing this manual.}
-@end iftex
+@item signal then cycle step @strong{(reserved)}
+@tab @code{I}
+@tab
+See @samp{i} and @samp{S} for likely syntax and semantics.
-The @value{GDBN} distribution includes all the source code you need for
-@value{GDBN} in a single directory, whose name is usually composed by
-appending the version number to @samp{gdb}.
+@item reserved
+@tab @code{j}
+@tab Reserved for future use
-For example, the @value{GDBN} version @value{GDBVN} distribution is in the
-@file{gdb-@value{GDBVN}} directory. That directory contains:
+@item reserved
+@tab @code{J}
+@tab Reserved for future use
-@table @code
-@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
-script for configuring @value{GDBN} and all its supporting libraries
+@item kill request
+@tab @code{k}
+@tab
+FIXME: @emph{There is no description of how to operate when a specific
+thread context has been selected (i.e.@: does 'k' kill only that thread?)}.
-@item gdb-@value{GDBVN}/gdb
-the source specific to @value{GDBN} itself
+@item reserved
+@tab @code{l}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/bfd
-source for the Binary File Descriptor library
+@item reserved
+@tab @code{L}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/include
-@sc{gnu} include files
+@item read memory
+@tab @code{m}@var{addr}@code{,}@var{length}
+@tab
+Read @var{length} bytes of memory starting at address @var{addr}.
+Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed
+using word alligned accesses. FIXME: @emph{A word aligned memory
+transfer mechanism is needed.}
+@item
+@tab reply @var{XX...}
+@tab
+@var{XX...} is mem contents. Can be fewer bytes than requested if able
+to read only part of the data. Neither @value{GDBN} nor the stub assume that
+sized memory transfers are assumed using word alligned accesses. FIXME:
+@emph{A word aligned memory transfer mechanism is needed.}
+@item
+@tab reply @code{E}@var{NN}
+@tab @var{NN} is errno
-@item gdb-@value{GDBVN}/libiberty
-source for the @samp{-liberty} free software library
+@item write mem
+@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
+@tab
+Write @var{length} bytes of memory starting at address @var{addr}.
+@var{XX...} is the data.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab
+for an error (this includes the case where only part of the data was
+written).
-@item gdb-@value{GDBVN}/opcodes
-source for the library of opcode tables and disassemblers
+@item reserved
+@tab @code{n}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/readline
-source for the @sc{gnu} command-line interface
+@item reserved
+@tab @code{N}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/glob
-source for the @sc{gnu} filename pattern-matching subroutine
+@item reserved
+@tab @code{o}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/mmalloc
-source for the @sc{gnu} memory-mapped malloc package
-@end table
+@item reserved
+@tab @code{O}
+@tab Reserved for future use
-The simplest way to configure and build @value{GDBN} is to run @code{configure}
-from the @file{gdb-@var{version-number}} source directory, which in
-this example is the @file{gdb-@value{GDBVN}} directory.
+@item read reg @strong{(reserved)}
+@tab @code{p}@var{n...}
+@tab
+See write register.
+@item
+@tab return @var{r....}
+@tab The hex encoded value of the register in target byte order.
-First switch to the @file{gdb-@var{version-number}} source directory
-if you are not already in it; then run @code{configure}. Pass the
-identifier for the platform on which @value{GDBN} will run as an
-argument.
+@item write reg
+@tab @code{P}@var{n...}@code{=}@var{r...}
+@tab
+Write register @var{n...} with value @var{r...}, which contains two hex
+digits for each byte in the register (target byte order).
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
-For example:
+@item general query
+@tab @code{q}@var{query}
+@tab
+Request info about @var{query}. In general @value{GDBN} queries
+have a leading upper case letter. Custom vendor queries should use a
+company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may
+optionally be followed by a @samp{,} or @samp{;} separated list. Stubs
+must ensure that they match the full @var{query} name.
+@item
+@tab reply @code{XX...}
+@tab Hex encoded data from query. The reply can not be empty.
+@item
+@tab reply @code{E}@var{NN}
+@tab error reply
+@item
+@tab reply @samp{}
+@tab Indicating an unrecognized @var{query}.
-@example
-cd gdb-@value{GDBVN}
-./configure @var{host}
-make
-@end example
+@item general set
+@tab @code{Q}@var{var}@code{=}@var{val}
+@tab
+Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
+naming conventions.
-@noindent
-where @var{host} is an identifier such as @samp{sun4} or
-@samp{decstation}, that identifies the platform where @value{GDBN} will run.
-(You can often leave off @var{host}; @code{configure} tries to guess the
-correct value by examining your system.)
+@item reset @strong{(deprecated)}
+@tab @code{r}
+@tab
+Reset the entire system.
-Running @samp{configure @var{host}} and then running @code{make} builds the
-@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
-libraries, then @code{gdb} itself. The configured source files, and the
-binaries, are left in the corresponding source directories.
+@item remote restart
+@tab @code{R}@var{XX}
+@tab
+Restart the program being debugged. @var{XX}, while needed, is ignored.
+This packet is only available in extended mode.
+@item
+@tab
+no reply
+@tab
+The @samp{R} packet has no reply.
-@need 750
-@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
-system does not recognize this automatically when you run a different
-shell, you may need to run @code{sh} on it explicitly:
+@item step
+@tab @code{s}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+same address.
+@item
+@tab reply
+@tab see below
-@example
-sh configure @var{host}
-@end example
+@item step with signal
+@tab @code{S}@var{sig}@code{;}@var{addr}
+@tab
+Like @samp{C} but step not continue.
+@item
+@tab reply
+@tab see below
-If you run @code{configure} from a directory that contains source
-directories for multiple libraries or programs, such as the
-@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
-creates configuration files for every directory level underneath (unless
-you tell it not to, with the @samp{--norecursion} option).
+@item search
+@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
+@tab
+Search backwards starting at address @var{addr} for a match with pattern
+@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
+bytes. @var{addr} must be at least 3 digits.
-You can run the @code{configure} script from any of the
-subordinate directories in the @value{GDBN} distribution if you only want to
-configure that subdirectory, but be sure to specify a path to it.
+@item thread alive
+@tab @code{T}@var{XX}
+@tab Find out if the thread XX is alive.
+@item
+@tab reply @code{OK}
+@tab thread is still alive
+@item
+@tab reply @code{E}@var{NN}
+@tab thread is dead
-For example, with version @value{GDBVN}, type the following to configure only
-the @code{bfd} subdirectory:
+@item reserved
+@tab @code{u}
+@tab Reserved for future use
-@example
-@group
-cd gdb-@value{GDBVN}/bfd
-../configure @var{host}
-@end group
-@end example
+@item reserved
+@tab @code{U}
+@tab Reserved for future use
-You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
-However, you should make sure that the shell on your path (named by
-the @samp{SHELL} environment variable) is publicly readable. Remember
-that @value{GDBN} uses the shell to start your program---some systems refuse to
-let @value{GDBN} debug child processes whose programs are not readable.
+@item reserved
+@tab @code{v}
+@tab Reserved for future use
-@menu
-* Separate Objdir:: Compiling @value{GDBN} in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
-@end menu
+@item reserved
+@tab @code{V}
+@tab Reserved for future use
-@node Separate Objdir
-@section Compiling @value{GDBN} in another directory
+@item reserved
+@tab @code{w}
+@tab Reserved for future use
-If you want to run @value{GDBN} versions for several host or target machines,
-you need a different @code{gdb} compiled for each combination of
-host and target. @code{configure} is designed to make this easy by
-allowing you to generate each configuration in a separate subdirectory,
-rather than in the source directory. If your @code{make} program
-handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
-@code{make} in each of these directories builds the @code{gdb}
-program specified there.
+@item reserved
+@tab @code{W}
+@tab Reserved for future use
-To build @code{gdb} in a separate directory, run @code{configure}
-with the @samp{--srcdir} option to specify where to find the source.
-(You also need to specify a path to find @code{configure}
-itself from your working directory. If the path to @code{configure}
-would be the same as the argument to @samp{--srcdir}, you can leave out
-the @samp{--srcdir} option; it is assumed.)
+@item reserved
+@tab @code{x}
+@tab Reserved for future use
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
-separate directory for a Sun 4 like this:
+@item write mem (binary)
+@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
+@tab
+@var{addr} is address, @var{length} is number of bytes, @var{XX...} is
+binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
+escaped using @code{0x7d}.
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
-@example
-@group
-cd gdb-@value{GDBVN}
-mkdir ../gdb-sun4
-cd ../gdb-sun4
-../gdb-@value{GDBVN}/configure sun4
-make
-@end group
-@end example
+@item reserved
+@tab @code{y}
+@tab Reserved for future use
-When @code{configure} builds a configuration using a remote source
-directory, it creates a tree for the binaries with the same structure
-(and using the same names) as the tree under the source directory. In
-the example, you'd find the Sun 4 library @file{libiberty.a} in the
-directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
-@file{gdb-sun4/gdb}.
+@item reserved
+@tab @code{Y}
+@tab Reserved for future use
-One popular reason to build several @value{GDBN} configurations in separate
-directories is to configure @value{GDBN} for cross-compiling (where
-@value{GDBN} runs on one machine---the @dfn{host}---while debugging
-programs that run on another machine---the @dfn{target}).
-You specify a cross-debugging target by
-giving the @samp{--target=@var{target}} option to @code{configure}.
+@item remove break or watchpoint @strong{(draft)}
+@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+See @samp{Z}.
-When you run @code{make} to build a program or library, you must run
-it in a configured directory---whatever directory you were in when you
-called @code{configure} (or one of its subdirectories).
+@item insert break or watchpoint @strong{(draft)}
+@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
+breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
+@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
+bytes. For a software breakpoint, @var{length} specifies the size of
+the instruction to be patched. For hardware breakpoints and watchpoints
+@var{length} specifies the memory region to be monitored. To avoid
+potential problems with duplicate packets, the operations should be
+implemented in an idempotent way.
+@item
+@tab reply @code{E}@var{NN}
+@tab for an error
+@item
+@tab reply @code{OK}
+@tab for success
+@item
+@tab @samp{}
+@tab If not supported.
-The @code{Makefile} that @code{configure} generates in each source
-directory also runs recursively. If you type @code{make} in a source
-directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
-directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
-will build all the required libraries, and then build GDB.
+@item reserved
+@tab <other>
+@tab Reserved for future use
-When you have multiple hosts or targets configured in separate
-directories, you can run @code{make} on them in parallel (for example,
-if they are NFS-mounted on each of the hosts); they will not interfere
-with each other.
+@end multitable
-@node Config Names
-@section Specifying names for hosts and targets
+The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
+receive any of the below as a reply. In the case of the @samp{C},
+@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
+when the target halts. In the below the exact meaning of @samp{signal
+number} is poorly defined. In general one of the UNIX signal numbering
+conventions is used.
-The specifications used for hosts and targets in the @code{configure}
-script are based on a three-part naming scheme, but some short predefined
-aliases are also supported. The full naming scheme encodes three pieces
-of information in the following pattern:
+@multitable @columnfractions .4 .6
-@example
-@var{architecture}-@var{vendor}-@var{os}
-@end example
+@item @code{S}@var{AA}
+@tab @var{AA} is the signal number
-For example, you can use the alias @code{sun4} as a @var{host} argument,
-or as the value for @var{target} in a @code{--target=@var{target}}
-option. The equivalent full name is @samp{sparc-sun-sunos4}.
+@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
+@tab
+@var{AA} = two hex digit signal number; @var{n...} = register number
+(hex), @var{r...} = target byte ordered register contents, size defined
+by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
+thread process ID, this is a hex integer; @var{n...} = other string not
+starting with valid hex digit. @value{GDBN} should ignore this
+@var{n...}, @var{r...} pair and go on to the next. This way we can
+extend the protocol.
-The @code{configure} script accompanying @value{GDBN} does not provide
-any query facility to list all supported host and target names or
-aliases. @code{configure} calls the Bourne shell script
-@code{config.sub} to map abbreviations to full names; you can read the
-script, if you wish, or you can use it to test your guesses on
-abbreviations---for example:
+@item @code{W}@var{AA}
+@tab
+The process exited, and @var{AA} is the exit status. This is only
+applicable for certains sorts of targets.
-@smallexample
-% sh config.sub i386-linux
-i386-pc-linux-gnu
-% sh config.sub alpha-linux
-alpha-unknown-linux-gnu
-% sh config.sub hp9k700
-hppa1.1-hp-hpux
-% sh config.sub sun4
-sparc-sun-sunos4.1.1
-% sh config.sub sun3
-m68k-sun-sunos4.1.1
-% sh config.sub i986v
-Invalid configuration `i986v': machine `i986v' not recognized
-@end smallexample
+@item @code{X}@var{AA}
+@tab
+The process terminated with signal @var{AA}.
-@noindent
-@code{config.sub} is also distributed in the @value{GDBN} source
-directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
+@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
+@tab
+@var{AA} = signal number; @var{t...} = address of symbol "_start";
+@var{d...} = base of data section; @var{b...} = base of bss section.
+@emph{Note: only used by Cisco Systems targets. The difference between
+this reply and the "qOffsets" query is that the 'N' packet may arrive
+spontaneously whereas the 'qOffsets' is a query initiated by the host
+debugger.}
-@node Configure Options
-@section @code{configure} options
+@item @code{O}@var{XX...}
+@tab
+@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
+while the program is running and the debugger should continue to wait
+for 'W', 'T', etc.
-Here is a summary of the @code{configure} options and arguments that
-are most often useful for building @value{GDBN}. @code{configure} also has
-several other options not listed here. @inforef{What Configure
-Does,,configure.info}, for a full explanation of @code{configure}.
+@end multitable
-@example
-configure @r{[}--help@r{]}
- @r{[}--prefix=@var{dir}@r{]}
- @r{[}--exec-prefix=@var{dir}@r{]}
- @r{[}--srcdir=@var{dirname}@r{]}
- @r{[}--norecursion@r{]} @r{[}--rm@r{]}
- @r{[}--target=@var{target}@r{]}
- @var{host}
-@end example
+The following set and query packets have already been defined.
-@noindent
-You may introduce options with a single @samp{-} rather than
-@samp{--} if you prefer; but you may abbreviate option names if you use
-@samp{--}.
+@multitable @columnfractions .2 .2 .6
-@table @code
-@item --help
-Display a quick summary of how to invoke @code{configure}.
+@item current thread
+@tab @code{q}@code{C}
+@tab Return the current thread id.
+@item
+@tab reply @code{QC}@var{pid}
+@tab
+Where @var{pid} is a HEX encoded 16 bit process id.
+@item
+@tab reply *
+@tab Any other reply implies the old pid.
-@item --prefix=@var{dir}
-Configure the source to install programs and files under directory
-@file{@var{dir}}.
+@item all thread ids
+@tab @code{q}@code{fThreadInfo}
+@item
+@tab @code{q}@code{sThreadInfo}
+@tab
+Obtain a list of active thread ids from the target (OS). Since there
+may be too many active threads to fit into one reply packet, this query
+works iteratively: it may require more than one query/reply sequence to
+obtain the entire list of threads. The first query of the sequence will
+be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
+sequence will be the @code{qs}@code{ThreadInfo} query.
+@item
+@tab
+@tab NOTE: replaces the @code{qL} query (see below).
+@item
+@tab reply @code{m}@var{<id>}
+@tab A single thread id
+@item
+@tab reply @code{m}@var{<id>},@var{<id>...}
+@tab a comma-separated list of thread ids
+@item
+@tab reply @code{l}
+@tab (lower case 'el') denotes end of list.
+@item
+@tab
+@tab
+In response to each query, the target will reply with a list of one
+or more thread ids, in big-endian hex, separated by commas. GDB will
+respond to each reply with a request for more thread ids (using the
+@code{qs} form of the query), until the target responds with @code{l}
+(lower-case el, for @code{'last'}).
-@item --exec-prefix=@var{dir}
-Configure the source to install programs under directory
-@file{@var{dir}}.
+@item extra thread info
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
+@tab
+@item
+@tab
+@tab
+Where @var{<id>} is a thread-id in big-endian hex.
+Obtain a printable string description of a thread's attributes from
+the target OS. This string may contain anything that the target OS
+thinks is interesting for @value{GDBN} to tell the user about the thread.
+The string is displayed in @value{GDBN}'s @samp{info threads} display.
+Some examples of possible thread extra info strings are "Runnable", or
+"Blocked on Mutex".
+@item
+@tab reply @var{XX...}
+@tab
+Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
+printable string containing the extra information about the thread's
+attributes.
-@c avoid splitting the warning from the explanation:
-@need 2000
-@item --srcdir=@var{dirname}
-@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
-@code{make} that implements the @code{VPATH} feature.}@*
-Use this option to make configurations in directories separate from the
-@value{GDBN} source directories. Among other things, you can use this to
-build (or maintain) several configurations simultaneously, in separate
-directories. @code{configure} writes configuration specific files in
-the current directory, but arranges for them to use the source in the
-directory @var{dirname}. @code{configure} creates directories under
-the working directory in parallel to the source directories below
-@var{dirname}.
+@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
+@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
+@tab
+@item
+@tab
+@tab
+Obtain thread information from RTOS. Where: @var{startflag} (one hex
+digit) is one to indicate the first query and zero to indicate a
+subsequent query; @var{threadcount} (two hex digits) is the maximum
+number of threads the response packet can contain; and @var{nextthread}
+(eight hex digits), for subsequent queries (@var{startflag} is zero), is
+returned in the response as @var{argthread}.
+@item
+@tab
+@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
+query (see above).
+@item
+@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
+@tab
+@item
+@tab
+@tab
+Where: @var{count} (two hex digits) is the number of threads being
+returned; @var{done} (one hex digit) is zero to indicate more threads
+and one indicates no further threads; @var{argthreadid} (eight hex
+digits) is @var{nextthread} from the request packet; @var{thread...} is
+a sequence of thread IDs from the target. @var{threadid} (eight hex
+digits). See @code{remote.c:parse_threadlist_response()}.
-@item --norecursion
-Configure only the directory level where @code{configure} is executed; do not
-propagate configuration to subdirectories.
+@item compute CRC of memory block
+@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@tab
+@item
+@tab reply @code{E}@var{NN}
+@tab An error (such as memory fault)
+@item
+@tab reply @code{C}@var{CRC32}
+@tab A 32 bit cyclic redundancy check of the specified memory region.
-@item --target=@var{target}
-Configure @value{GDBN} for cross-debugging programs running on the specified
-@var{target}. Without this option, @value{GDBN} is configured to debug
-programs that run on the same machine (@var{host}) as @value{GDBN} itself.
+@item query sect offs
+@tab @code{q}@code{Offsets}
+@tab
+Get section offsets that the target used when re-locating the downloaded
+image. @emph{Note: while a @code{Bss} offset is included in the
+response, @value{GDBN} ignores this and instead applies the @code{Data}
+offset to the @code{Bss} section.}
+@item
+@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
-There is no convenient way to generate a list of all available targets.
+@item thread info request
+@tab @code{q}@code{P}@var{mode}@var{threadid}
+@tab
+@item
+@tab
+@tab
+Returns information on @var{threadid}. Where: @var{mode} is a hex
+encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
+@item
+@tab reply *
+@tab
+See @code{remote.c:remote_unpack_thread_info_response()}.
-@item @var{host} @dots{}
-Configure @value{GDBN} to run on the specified @var{host}.
+@item remote command
+@tab @code{q}@code{Rcmd,}@var{COMMAND}
+@tab
+@item
+@tab
+@tab
+@var{COMMAND} (hex encoded) is passed to the local interpreter for
+execution. Invalid commands should be reported using the output string.
+Before the final result packet, the target may also respond with a
+number of intermediate @code{O}@var{OUTPUT} console output
+packets. @emph{Implementors should note that providing access to a
+stubs's interpreter may have security implications}.
+@item
+@tab reply @code{OK}
+@tab
+A command response with no output.
+@item
+@tab reply @var{OUTPUT}
+@tab
+A command response with the hex encoded output string @var{OUTPUT}.
+@item
+@tab reply @code{E}@var{NN}
+@tab
+Indicate a badly formed request.
-There is no convenient way to generate a list of all available hosts.
-@end table
+@item
+@tab reply @samp{}
+@tab
+When @samp{q}@samp{Rcmd} is not recognized.
-There are many other options available as well, but they are generally
-needed for special purposes only.
+@item symbol lookup
+@tab @code{qSymbol::}
+@tab
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests. Accept requests from the target for the values of symbols.
+@item
+@tab
+@tab
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of symbol @var{sym_name} (hex encoded).
+@value{GDBN} may provide the value by using the
+@code{qSymbol:}@var{sym_value}:@var{sym_name}
+message, described below.
-@node Maintenance Commands
-@appendix Maintenance Commands
-@cindex maintenance commands
-@cindex internal commands
+@item symbol value
+@tab @code{qSymbol:}@var{sym_value}:@var{sym_name}
+@tab
+@sp 1
+@noindent
+Set the value of SYM_NAME to SYM_VALUE.
+@item
+@tab
+@tab
+@var{sym_name} (hex encoded) is the name of a symbol whose value
+the target has previously requested.
+@item
+@tab
+@tab
+@var{sym_value} (hex) is the value for symbol @var{sym_name}.
+If @value{GDBN} cannot supply a value for @var{sym_name}, then this
+field will be empty.
+@item
+@tab reply @code{OK}
+@tab
+The target does not need to look up any (more) symbols.
+@item
+@tab reply @code{qSymbol:}@var{sym_name}
+@tab
+@sp 2
+@noindent
+The target requests the value of a new symbol @var{sym_name} (hex encoded).
+@value{GDBN} will continue to supply the values of symbols (if available),
+until the target ceases to request them.
-In addition to commands intended for @value{GDBN} users, @value{GDBN}
-includes a number of commands intended for @value{GDBN} developers.
-These commands are provided here for reference.
+@end multitable
-@table @code
-@kindex maint info breakpoints
-@item @anchor{maint info breakpoints}maint info breakpoints
-Using the same format as @samp{info breakpoints}, display both the
-breakpoints you've set explicitly, and those @value{GDBN} is using for
-internal purposes. Internal breakpoints are shown with negative
-breakpoint numbers. The type column identifies what kind of breakpoint
-is shown:
+The following @samp{g}/@samp{G} packets have previously been defined.
+In the below, some thirty-two bit registers are transferred as sixty-four
+bits. Those registers should be zero/sign extended (which?) to fill the
+space allocated. Register bytes are transfered in target byte order.
+The two nibbles within a register byte are transfered most-significant -
+least-significant.
-@table @code
-@item breakpoint
-Normal, explicitly set breakpoint.
+@multitable @columnfractions .5 .5
-@item watchpoint
-Normal, explicitly set watchpoint.
+@item MIPS32
+@tab
+All registers are transfered as thirty-two bit quantities in the order:
+32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
+registers; fsr; fir; fp.
-@item longjmp
-Internal breakpoint, used to handle correctly stepping through
-@code{longjmp} calls.
+@item MIPS64
+@tab
+All registers are transfered as sixty-four bit quantities (including
+thirty-two bit registers such as @code{sr}). The ordering is the same
+as @code{MIPS32}.
-@item longjmp resume
-Internal breakpoint at the target of a @code{longjmp}.
+@end multitable
-@item until
-Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
+Example sequence of a target being re-started. Notice how the restart
+does not get any direct output:
-@item finish
-Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
+@smallexample
+<- @code{R00}
+-> @code{+}
+@emph{target restarts}
+<- @code{?}
+-> @code{+}
+-> @code{T001:1234123412341234}
+<- @code{+}
+@end smallexample
-@item shlib events
-Shared library events.
+Example sequence of a target being stepped by a single instruction:
-@end table
+@smallexample
+<- @code{G1445...}
+-> @code{+}
+<- @code{s}
+-> @code{+}
+@emph{time passes}
+-> @code{T001:1234123412341234}
+<- @code{+}
+<- @code{g}
+-> @code{+}
+-> @code{1455...}
+<- @code{+}
+@end smallexample
-@end table
+@include gpl.texi
@include fdl.texi
% Blame: doc@cygnus.com, 1991.
@end tex
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@ifinfo
-@contents
-@end ifinfo
-@ifhtml
-@contents
-@end ifhtml
-
@bye
projects / deliverable / binutils-gdb.git / blobdiff