\input texinfo @c -*-texinfo-*-
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001
+@c 1999, 2000, 2001, 2002
@c Free Software Foundation, Inc.
@c
@c %**start of header
@set EDITION Ninth
@c !!set GDB manual's revision date
-@set DATE April 2001
+@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.
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
- Free Software Foundation, Inc.
+Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
+ 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being ``A Sample GDB Session'' and ``Free
-Software'', with the Front-Cover texts being ``A GNU Manual,'' and
-with the Back-Cover Texts as in (a) below.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
@end ifinfo
@titlepage
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
- Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
+1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being ``A Sample GDB Session'' and ``Free
-Software'', with the Front-Cover texts being ``A GNU Manual,'' and
-with the Back-Cover Texts as in (a) below.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
@end titlepage
@page
-@ifinfo
+@ifnottex
@node Top, Summary, (dir), (dir)
@top Debugging with @value{GDBN}
This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2001 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @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
* Languages:: Using @value{GDBN} with different languages
* 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
+* 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.
* Command Line Editing:: Command Line Editing
* 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
-
-* 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
-* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
-* Annotations:: @value{GDBN}'s annotation 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
-* 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}
you have these freedoms and that you cannot take these freedoms away
from anyone else.
+@unnumberedsec Free Software Needs Free Documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software. Many of our most important
+programs do not come with free reference manuals and free introductory
+texts. Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap. We have many such
+gaps today.
+
+Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last. Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The
+problem is the restrictions on the use of the manual. Free manuals
+are available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program. A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok. It is also no problem to require modified versions
+to include notice that they were modified. Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one). These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels. Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval---you
+don't have to let the publisher decide. Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want. If the publisher you are dealing with refuses, please
+try other publishers. If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation
+at all. Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try to reward the publishers that
+have paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
+@url{http://www.fsf.org/doc/other-free-books.html}.
+
@node Contributors
@unnumberedsec Contributors to @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
``process'', and there is often no way to get a core dump. @value{GDBN}
will warn you if it is unable to attach or to read core dumps.
+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.
+@smallexample
+gdb --args gcc -O2 -c foo.c
+@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}.
+
You can run @code{@value{GDBP}} without printing the front material, which describes
@value{GDBN}'s non-warranty, by specifying @code{-silent}:
@noindent
Type
-@example
+@smallexample
@value{GDBP} -help
-@end example
+@end smallexample
@noindent
to display all available options and briefly describe their use
When @value{GDBN} starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
the same as if the arguments were specified by the @samp{-se} and
-@samp{-c} options respectively. (@value{GDBN} reads the first argument
-that does not have an associated option flag as equivalent to the
-@samp{-se} option followed by that argument; and the second argument
-that does not have an associated option flag, if any, as equivalent to
-the @samp{-c} option followed by that argument.)
+@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the
+first argument that does not have an associated option flag as
+equivalent to the @samp{-se} option followed by that argument; and the
+second argument that does not have an associated option flag, if any, as
+equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
+If the second argument begins with a decimal digit, @value{GDBN} will
+first attempt to attach to it as a process, and if that fails, attempt
+to open it as a corefile. If you have a corefile whose name begins with
+a digit, you can prevent @value{GDBN} from treating it as a pid by
+prefixing it with @file{./}, eg. @file{./12345}.
If @value{GDBN} has not been configured to included core file support,
such as for most embedded targets, then it will complain about a second
@itemx -c @var{file}
@cindex @code{--core}
@cindex @code{-c}
-Use file @var{file} as a core dump to examine.
+Use file @var{file} as a core dump to examine.
@item -c @var{number}
-Connect to process ID @var{number}, as with the @code{attach} command
-(unless there is a file in core-dump format named @var{number}, in which
-case @samp{-c} specifies that file as a core dump to read).
+@item -pid @var{number}
+@itemx -p @var{number}
+@cindex @code{--pid}
+@cindex @code{-p}
+Connect to process ID @var{number}, as with the @code{attach} command.
+If there is no such process, @value{GDBN} will attempt to open a core
+file named @var{number}.
@item -command @var{file}
@itemx -x @var{file}
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
@itemx -n
@cindex @code{--nx}
@cindex @code{-n}
-Do not execute commands found in any initialization files (normally
-called @file{.gdbinit}, or @file{gdb.ini} on PCs). Normally,
+Do not execute commands found in any initialization files. Normally,
@value{GDBN} executes the commands in these files after all the command
options and arguments have been processed. @xref{Command Files,,Command
files}.
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
@cindex @code{--noasync}
Disable the asynchronous event loop for the command-line interface.
+@item --args
+@cindex @code{--args}
+Change interpretation of command line so that arguments following the
+executable file are passed as command line arguments to the inferior.
+This option stops option processing.
+
@item -baud @var{bps}
@itemx -b @var{bps}
@cindex @code{--baud}
@c FIXME: kingdon thinks there is more to -tty. Investigate.
@c resolve the situation of these eventually
-@c @item -tui
-@c @cindex @code{--tui}
-@c Use a Terminal User Interface. For information, use your Web browser to
-@c read the file @file{TUI.html}, which is usually installed in the
-@c directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use
-@c this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
-@c @value{GDBN} under @sc{gnu} Emacs}).
+@item -tui
+@cindex @code{--tui}
+Activate the Terminal User Interface when starting.
+The Terminal User Interface manages several text windows on the terminal,
+showing source, assembly, registers and @value{GDBN} command outputs
+(@pxref{TUI, ,@value{GDBN} Text User Interface}).
+Do not use this option if you run @value{GDBN} from Emacs
+(@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
@c @item -xdb
@c @cindex @code{--xdb}
@cindex @code{--interpreter}
Use the interpreter @var{interp} for interface with the controlling
program or device. This option is meant to be set by programs which
-communicate with @value{GDBN} using it as a back end. For example,
-@samp{--interpreter=mi} causes @value{GDBN} to use the @dfn{gdbmi
-interface} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}).
+communicate with @value{GDBN} using it as a back end.
+
+@samp{--interpreter=mi} (or @samp{--interpreter=mi1}) causes
+@value{GDBN} to use the @dfn{gdb/mi interface} (@pxref{GDB/MI, , The
+@sc{gdb/mi} Interface}). The older @sc{gdb/mi} interface, included in
+@value{GDBN} version 5.0 can be selected with @samp{--interpreter=mi0}.
@item -write
@cindex @code{--write}
nothing. This is useful mainly in command files (@pxref{Command
Files,,Command files}).
+@cindex repeating command sequences
+@kindex C-o @r{(operate-and-get-next)}
+The @kbd{C-o} binding is useful for repeating a complex sequence of
+commands. This command accepts the current line, like @kbd{RET}, and
+then fetches the next line relative to the current line from the history
+for editing.
+
@node Completion
@section Command completion
@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}
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
-@value{GDBN} itself sometimes sets breakpoints in your program for special
-purposes, such as proper handling of @code{longjmp} (in C programs).
-These internal breakpoints are assigned negative numbers, starting with
-@code{-1}; @samp{info breakpoints} does not display them.
-
+@value{GDBN} itself sometimes sets breakpoints in your program for
+special purposes, such as proper handling of @code{longjmp} (in C
+programs). These internal breakpoints are assigned negative numbers,
+starting with @code{-1}; @samp{info breakpoints} does not display them.
You can see these breakpoints with the @value{GDBN} maintenance command
-@samp{maint info breakpoints}.
-
-@table @code
-@kindex maint info breakpoints
-@item 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:
-
-@table @code
-@item breakpoint
-Normal, explicitly set breakpoint.
-
-@item watchpoint
-Normal, explicitly set watchpoint.
-
-@item longjmp
-Internal breakpoint, used to handle correctly stepping through
-@code{longjmp} calls.
-
-@item longjmp resume
-Internal breakpoint at the target of a @code{longjmp}.
-
-@item until
-Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
-
-@item finish
-Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
-
-@item shlib events
-Shared library events.
-
-@end table
-
-@end table
+@samp{maint info breakpoints} (@pxref{maint info breakpoints}).
@node Set Watchpoints
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
signal.
@cindex handling signals
-Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM}
-(so as not to interfere with their role in the functioning of your program)
+Normally, @value{GDBN} is set up to let the non-erroneous signals like
+@code{SIGALRM} be silently passed to your program
+(so as not to interfere with their role in the program's functioning)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the @code{handle} command.
@item handle @var{signal} @var{keywords}@dots{}
Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
can be the number of a signal or its name (with or without the
-@samp{SIG} at the beginning); a list of signal numberss of the form
+@samp{SIG} at the beginning); a list of signal numbers of the form
@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
known signals. The @var{keywords} say what change to make.
@end table
command with @code{pass} or @code{nopass} to control whether your
program sees that signal when you continue.
+The default is set to @code{nostop}, @code{noprint}, @code{pass} for
+non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
+@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
+erroneous signals.
+
You can also use the @code{signal} command to prevent your program from
seeing a signal, or cause it to see a signal it normally would not see,
or to give it any signal at any time. For example, if your program stopped
@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
unobtrusively, hopefully not disturbing the program's behavior.
The tracepoint facility is currently available only for remote
-targets. @xref{Targets}.
+targets. @xref{Targets}. In addition, your remote target must know how
+to collect trace data. This functionality is implemented in the remote
+stub; however, none of the stubs distributed with @value{GDBN} support
+tracepoints as of this writing.
This chapter describes the tracepoint commands and features.
Examples:
@smallexample
-(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of tracepoint 2
+(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
- // most recently defined tracepoint.
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
(@value{GDBP}) @b{trace foo}
(@value{GDBP}) @b{pass 3}
(@value{GDBP}) @b{trace bar}
(@value{GDBP}) @b{pass 2}
(@value{GDBP}) @b{trace baz}
(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
- // executed 3 times OR when bar has
- // been executed 2 times
- // OR when baz has been executed 1 time.
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
+@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
@end smallexample
@end table
@smallexample
(@value{GDBP}) @b{collect @var{data}} // collect some data
-(@value{GDBP}) @b{while-stepping 5} // single-step 5 times and collect data
+(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
-(@value{GDBP}) @b{end} // signals the end of actions.
+(@value{GDBP}) @b{end} // signals the end of actions.
@end smallexample
In the following example, the action list begins with @code{collect}
@kindex info tracepoints
@cindex information about tracepoints
@item info tracepoints @r{[}@var{num}@r{]}
-Display information the tracepoint @var{num}. If you don't specify a
-tracepoint number displays information about all the tracepoints
+Display information about the tracepoint @var{num}. If you don't specify
+a tracepoint number, displays information about all the tracepoints
defined so far. For each tracepoint, the following information is
shown:
(@value{GDBP}) @b{info trace}
Num Enb Address PassC StepC What
1 y 0x002117c4 0 0 <gdb_asm>
-2 y 0x0020dc64 0 0 in gdb_test at gdb_test.c:375
-3 y 0x0020b1f4 0 0 in collect_data at ../foo.c:1741
+2 y 0x0020dc64 0 0 in g_test at g_test.c:1375
+3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
(@value{GDBP})
@end smallexample
> end
@end smallexample
-@node Languages
-@chapter Using @value{GDBN} with Different Languages
-@cindex languages
-
-Although programming languages generally have common aspects, they are
-rarely expressed in the same manner. For instance, in ANSI C,
-dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
-Modula-2, it is accomplished by @code{p^}. Values can also be
-represented (and displayed) differently. Hex numbers in C appear as
-@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
+@node Overlays
+@chapter Debugging Programs That Use Overlays
+@cindex overlays
-@cindex working language
-Language-specific information is built into @value{GDBN} for some languages,
-allowing you to express operations like the above in your program's
-native language, and allowing @value{GDBN} to output values in a manner
-consistent with the syntax of your program's native language. The
-language you use to build expressions is called the @dfn{working
-language}.
+If your program is too large to fit completely in your target system's
+memory, you can sometimes use @dfn{overlays} to work around this
+problem. @value{GDBN} provides some support for debugging programs that
+use overlays.
@menu
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-* Checks:: Type and range checks
-* Support:: Supported languages
+* How Overlays Work:: A general explanation of overlays.
+* Overlay Commands:: Managing overlays in @value{GDBN}.
+* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
+ mapped by asking the inferior.
+* Overlay Sample Program:: A sample program using overlays.
@end menu
-@node Setting
-@section Switching between source languages
-
-There are two ways to control the working language---either have @value{GDBN}
-set it automatically, or select it manually yourself. You can use the
-@code{set language} command for either purpose. On startup, @value{GDBN}
-defaults to setting the language automatically. The working language is
-used to determine how expressions you type are interpreted, how values
-are printed, etc.
+@node How Overlays Work
+@section How Overlays Work
+@cindex mapped overlays
+@cindex unmapped overlays
+@cindex load address, overlay's
+@cindex mapped address
+@cindex overlay area
+
+Suppose you have a computer whose instruction address space is only 64
+kilobytes long, but which has much more memory which can be accessed by
+other means: special instructions, segment registers, or memory
+management hardware, for example. Suppose further that you want to
+adapt a program which is larger than 64 kilobytes to run on this system.
+
+One solution is to identify modules of your program which are relatively
+independent, and need not call each other directly; call these modules
+@dfn{overlays}. Separate the overlays from the main program, and place
+their machine code in the larger memory. Place your main program in
+instruction memory, but leave at least enough space there to hold the
+largest overlay as well.
+
+Now, to call a function located in an overlay, you must first copy that
+overlay's machine code from the large memory into the space set aside
+for it in the instruction memory, and then jump to its entry point
+there.
+
+@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.
-In addition to the working language, every source file that
-@value{GDBN} knows about has its own working language. For some object
+@smallexample
+@group
+ 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 smallexample
+
+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
+instruction memory. An overlay not present (or only partially present)
+in instruction memory is called @dfn{unmapped}; its @dfn{load address}
+is its address in the larger memory. The mapped address is also called
+the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
+called the @dfn{load memory address}, or @dfn{LMA}.
+
+Unfortunately, overlays are not a completely transparent way to adapt a
+program to limited instruction memory. They introduce a new set of
+global constraints you must keep in mind as you design your program:
+
+@itemize @bullet
+
+@item
+Before calling or returning to a function in an overlay, your program
+must make sure that overlay is actually mapped. Otherwise, the call or
+return will transfer control to the right address, but in the wrong
+overlay, and your program will probably crash.
+
+@item
+If the process of mapping an overlay is expensive on your system, you
+will need to choose your overlays carefully to minimize their effect on
+your program's performance.
+
+@item
+The executable file you load onto your system must contain each
+overlay's instructions, appearing at the overlay's load address, not its
+mapped address. However, each overlay's instructions must be relocated
+and its symbols defined as if the overlay were at its mapped address.
+You can use GNU linker scripts to specify different load and relocation
+addresses for pieces of your program; see @ref{Overlay Description,,,
+ld.info, Using ld: the GNU linker}.
+
+@item
+The procedure for loading executable files onto your system must be able
+to load their contents into the larger address space as well as the
+instruction and data spaces.
+
+@end itemize
+
+The overlay system described above is rather simple, and could be
+improved in many ways:
+
+@itemize @bullet
+
+@item
+If your system has suitable bank switch registers or memory management
+hardware, you could use those facilities to make an overlay's load area
+contents simply appear at their mapped address in instruction space.
+This would probably be faster than copying the overlay to its mapped
+area in the usual way.
+
+@item
+If your overlays are small enough, you could set aside more than one
+overlay area, and have more than one overlay mapped at a time.
+
+@item
+You can use overlays to manage data, as well as instructions. In
+general, data overlays are even less transparent to your design than
+code overlays: whereas code overlays only require care when you call or
+return to functions, data overlays require care every time you access
+the data. Also, if you change the contents of a data overlay, you
+must copy its contents back out to its load address before you can copy a
+different data overlay into the same mapped area.
+
+@end itemize
+
+
+@node Overlay Commands
+@section Overlay Commands
+
+To use @value{GDBN}'s overlay support, each overlay in your program must
+correspond to a separate section of the executable file. The section's
+virtual memory address and load memory address must be the overlay's
+mapped and load addresses. Identifying overlays with sections allows
+@value{GDBN} to determine the appropriate address of a function or
+variable, depending on whether the overlay is mapped or not.
+
+@value{GDBN}'s overlay commands all start with the word @code{overlay};
+you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
+
+@table @code
+@item overlay off
+@kindex overlay off
+Disable @value{GDBN}'s overlay support. When overlay support is
+disabled, @value{GDBN} assumes that all functions and variables are
+always present at their mapped addresses. By default, @value{GDBN}'s
+overlay support is disabled.
+
+@item overlay manual
+@kindex overlay manual
+@cindex manual overlay debugging
+Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
+relies on you to tell it which overlays are mapped, and which are not,
+using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
+commands described below.
+
+@item overlay map-overlay @var{overlay}
+@itemx overlay map @var{overlay}
+@kindex overlay map-overlay
+@cindex map an overlay
+Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
+be the name of the object file section containing the overlay. When an
+overlay is mapped, @value{GDBN} assumes it can find the overlay's
+functions and variables at their mapped addresses. @value{GDBN} assumes
+that any other overlays whose mapped ranges overlap that of
+@var{overlay} are now unmapped.
+
+@item overlay unmap-overlay @var{overlay}
+@itemx overlay unmap @var{overlay}
+@kindex overlay unmap-overlay
+@cindex unmap an overlay
+Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
+must be the name of the object file section containing the overlay.
+When an overlay is unmapped, @value{GDBN} assumes it can find the
+overlay's functions and variables at their load addresses.
+
+@item overlay auto
+@kindex overlay auto
+Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
+consults a data structure the overlay manager maintains in the inferior
+to see which overlays are mapped. For details, see @ref{Automatic
+Overlay Debugging}.
+
+@item overlay load-target
+@itemx overlay load
+@kindex overlay load-target
+@cindex reloading the overlay table
+Re-read the overlay table from the inferior. Normally, @value{GDBN}
+re-reads the table @value{GDBN} automatically each time the inferior
+stops, so this command should only be necessary if you have changed the
+overlay mapping yourself using @value{GDBN}. This command is only
+useful when using automatic overlay debugging.
+
+@item overlay list-overlays
+@itemx overlay list
+@cindex listing mapped overlays
+Display a list of the overlays currently mapped, along with their mapped
+addresses, load addresses, and sizes.
+
+@end table
+
+Normally, when @value{GDBN} prints a code address, it includes the name
+of the function the address falls in:
+
+@smallexample
+(gdb) print main
+$3 = @{int ()@} 0x11a0 <main>
+@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:
+
+@smallexample
+(gdb) overlay list
+No sections are mapped.
+(gdb) print foo
+$5 = @{int (int)@} 0x100000 <*foo*>
+@end smallexample
+@noindent
+When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
+name normally:
+
+@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 smallexample
+
+When overlay debugging is enabled, @value{GDBN} can find the correct
+address for functions and variables in an overlay, whether or not the
+overlay is mapped. This allows most @value{GDBN} commands, like
+@code{break} and @code{disassemble}, to work normally, even on unmapped
+code. However, @value{GDBN}'s breakpoint support has some limitations:
+
+@itemize @bullet
+@item
+@cindex breakpoints in overlays
+@cindex overlays, setting breakpoints in
+You can set breakpoints in functions in unmapped overlays, as long as
+@value{GDBN} can write to the overlay at its load address.
+@item
+@value{GDBN} can not set hardware or simulator-based breakpoints in
+unmapped overlays. However, if you set a breakpoint at the end of your
+overlay manager (and tell @value{GDBN} which overlays are now mapped, if
+you are using manual overlay management), @value{GDBN} will re-set its
+breakpoints properly.
+@end itemize
+
+
+@node Automatic Overlay Debugging
+@section Automatic Overlay Debugging
+@cindex automatic overlay debugging
+
+@value{GDBN} can automatically track which overlays are mapped and which
+are not, given some simple co-operation from the overlay manager in the
+inferior. If you enable automatic overlay debugging with the
+@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
+looks in the inferior's memory for certain variables describing the
+current state of the overlays.
+
+Here are the variables your overlay manager must define to support
+@value{GDBN}'s automatic overlay debugging:
+
+@table @asis
+
+@item @code{_ovly_table}:
+This variable must be an array of the following structures:
+
+@smallexample
+struct
+@{
+ /* The overlay's mapped address. */
+ unsigned long vma;
+
+ /* The size of the overlay, in bytes. */
+ unsigned long size;
+
+ /* The overlay's load address. */
+ unsigned long lma;
+
+ /* Non-zero if the overlay is currently mapped;
+ zero otherwise. */
+ unsigned long mapped;
+@}
+@end smallexample
+
+@item @code{_novlys}:
+This variable must be a four-byte signed integer, holding the total
+number of elements in @code{_ovly_table}.
+
+@end table
+
+To decide whether a particular overlay is mapped or not, @value{GDBN}
+looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
+@code{lma} members equal the VMA and LMA of the overlay's section in the
+executable file. When @value{GDBN} finds a matching entry, it consults
+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
+@cindex overlay example program
+
+When linking a program which uses overlays, you must place the overlays
+at their load addresses, while relocating them to run at their mapped
+addresses. To do this, you must write a linker script (@pxref{Overlay
+Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
+since linker scripts are specific to a particular host system, target
+architecture, and target memory layout, this manual cannot provide
+portable sample code demonstrating @value{GDBN}'s overlay support.
+
+However, the @value{GDBN} source distribution does contain an overlaid
+program, with linker scripts for a few systems, as part of its test
+suite. The program consists of the following files from
+@file{gdb/testsuite/gdb.base}:
+
+@table @file
+@item overlays.c
+The main program file.
+@item ovlymgr.c
+A simple overlay manager, used by @file{overlays.c}.
+@item foo.c
+@itemx bar.c
+@itemx baz.c
+@itemx grbx.c
+Overlay modules, loaded and used by @file{overlays.c}.
+@item d10v.ld
+@itemx m32r.ld
+Linker scripts for linking the test program on the @code{d10v-elf}
+and @code{m32r-elf} targets.
+@end table
+
+You can build the test program using the @code{d10v-elf} GCC
+cross-compiler like this:
+
+@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 bar.c
+$ d10v-elf-gcc -g -c baz.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 smallexample
+
+The build process is identical for any other architecture, except that
+you must substitute the appropriate compiler and linker script for the
+target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
+
+
+@node Languages
+@chapter Using @value{GDBN} with Different Languages
+@cindex languages
+
+Although programming languages generally have common aspects, they are
+rarely expressed in the same manner. For instance, in ANSI C,
+dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
+Modula-2, it is accomplished by @code{p^}. Values can also be
+represented (and displayed) differently. Hex numbers in C appear as
+@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
+
+@cindex working language
+Language-specific information is built into @value{GDBN} for some languages,
+allowing you to express operations like the above in your program's
+native language, and allowing @value{GDBN} to output values in a manner
+consistent with the syntax of your program's native language. The
+language you use to build expressions is called the @dfn{working
+language}.
+
+@menu
+* Setting:: Switching between source languages
+* Show:: Displaying the language
+* Checks:: Type and range checks
+* Support:: Supported languages
+@end menu
+
+@node Setting
+@section Switching between source languages
+
+There are two ways to control the working language---either have @value{GDBN}
+set it automatically, or select it manually yourself. You can use the
+@code{set language} command for either purpose. On startup, @value{GDBN}
+defaults to setting the language automatically. The working language is
+used to determine how expressions you type are interpreted, how values
+are printed, etc.
+
+In addition to the working language, every source file that
+@value{GDBN} knows about has its own working language. For some object
file formats, the compiler might indicate which language a particular
source file is in. However, most of the time @value{GDBN} infers the
language from the name of the file. The language of a source file
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 @code{>=} on sets as an error.
@end quotation
-@cindex Modula-2 built-ins
+
@node Built-In Func/Proc
@subsubsection Built-in functions and procedures
+@cindex Modula-2 built-ins
Modula-2 also makes available several built-in procedures and functions.
In describing these, the following metavariables are used:
(@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
whose names contain a match for regular expression @var{regexp}.
Thus, @samp{info fun step} finds all functions whose names
include @code{step}; @samp{info fun ^step} finds those whose names
-start with @code{step}.
+start with @code{step}. If a function name contains characters
+that conflict with the regular expression language (eg.
+@samp{operator*()}), they may be quoted with a backslash.
@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.
-For the A29K, a user-controlled variable @code{call_scratch_address},
-specifies the location of a scratch area to be used when @value{GDBN}
-calls a function in the target. This is necessary because the usual
-method of putting the scratch area on the stack does not work in systems
-that have separate instruction and data spaces.
-
@node Patching
@section Patching programs
@cindex dynamic linking
@item add-symbol-file @var{filename} @var{address}
@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address}
+@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
thus read keeps adding to the old. To discard all old symbol data
instead, use the @code{symbol-file} command without any arguments.
+@cindex relocatable object files, reading symbols from
+@cindex object files, relocatable, reading symbols from
+@cindex reading symbols from relocatable object files
+@cindex symbols, reading from relocatable object files
+@cindex @file{.o} files, reading symbols from
+Although @var{filename} is typically a shared library file, an
+executable file, or some other object file which has been fully
+relocated for loading into a process, you can also load symbolic
+information from relocatable @file{.o} files, as long as:
+
+@itemize @bullet
+@item
+the file's symbolic information refers only to linker symbols defined in
+that file, not to symbols defined by other object files,
+@item
+every section the file's symbolic information refers to has actually
+been loaded into the inferior, as it appears in the file, and
+@item
+you can determine the address at which every section was loaded, and
+provide these to the @code{add-symbol-file} command.
+@end itemize
+
+@noindent
+Some embedded operating systems, like Sun Chorus and VxWorks, can load
+relocatable files into an already running program; such systems
+typically make the requirements above easy to meet. However, it's
+important to recognize that many native systems use complex link
+procedures (@code{.linkonce} section factoring and C++ constructor table
+assembly, for example) that make the requirements difficult to meet. In
+general, one cannot assume that using @code{add-symbol-file} to read a
+relocatable object file's symbolic information will have the same effect
+as linking the relocatable object file into the program in the normal
+way.
+
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
You can use the @samp{-mapped} and @samp{-readnow} options just as with
command @code{help target} lists all possible targets rather than
current ones.
+@kindex maint info sections
+@item maint info sections
+Another command that can give you extra information about program sections
+is @code{maint info sections}. In addition to the section information
+displayed by @code{info files}, this command displays the flags and file
+offset of each section in the executable and core dump files. In addition,
+@code{maint info sections} provides the following command options (which
+may be arbitrarily combined):
+
+@table @code
+@item ALLOBJ
+Display sections for all loaded object files, including shared libraries.
+@item @var{sections}
+Display info only for named @var{sections}.
+@item @var{section-flags}
+Display info only for sections for which @var{section-flags} are true.
+The section flags that @value{GDBN} currently knows about are:
+@table @code
+@item ALLOC
+Section will have space allocated in the process when loaded.
+Set for all sections except those containing debug information.
+@item LOAD
+Section will be loaded from the file into the child process memory.
+Set for pre-initialized code and data, clear for @code{.bss} sections.
+@item RELOC
+Section needs to be relocated before loading.
+@item READONLY
+Section cannot be modified by the child process.
+@item CODE
+Section contains executable code only.
+@item DATA
+Section contains data only (no executable code).
+@item ROM
+Section will reside in ROM.
+@item CONSTRUCTOR
+Section contains data for constructor/destructor lists.
+@item HAS_CONTENTS
+Section is not empty.
+@item NEVER_LOAD
+An instruction to the linker to not output the section.
+@item COFF_SHARED_LIBRARY
+A notification to the linker that the section contains
+COFF shared library information.
+@item IS_COMMON
+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
@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
@c FIXME...lib; check this from time to time when updating manual
+There are times, however, when you may wish to not automatically load
+symbol definitions from shared libraries, such as when they are
+particularly large or there are many of them.
+
+To control the automatic loading of shared library symbols, use the
+commands:
+
+@table @code
+@kindex set auto-solib-add
+@item set auto-solib-add @var{mode}
+If @var{mode} is @code{on}, symbols from all shared object libraries
+will be loaded automatically when the inferior begins execution, you
+attach to an independently started inferior, or when the dynamic linker
+informs @value{GDBN} that a new library has been loaded. If @var{mode}
+is @code{off}, symbols must be loaded manually, using the
+@code{sharedlibrary} command. The default value is @code{on}.
+
+@kindex show auto-solib-add
+@item show auto-solib-add
+Display the current autoloading mode.
+@end table
+
+To explicitly load shared library symbols, use the @code{sharedlibrary}
+command:
+
@table @code
@kindex info sharedlibrary
@kindex info share
loaded.
@end table
-On HP-UX systems, @value{GDBN} detects the loading of a shared library
-and automatically reads in symbols from the newly loaded library, up to
-a threshold that is initially set but that you can modify if you wish.
+On some systems, such as HP-UX systems, @value{GDBN} supports
+autoloading shared library symbols until a limiting threshold size is
+reached. This provides the benefit of allowing autoloading to remain on
+by default, but avoids autoloading excessively large shared libraries,
+up to a threshold that is initially set, but which you can modify if you
+wish.
Beyond that threshold, symbols from shared libraries must be explicitly
loaded. To load these symbols, use the command @code{sharedlibrary
To display or set the threshold, use the commands:
@table @code
-@kindex set auto-solib-add
-@item set auto-solib-add @var{threshold}
-Set the autoloading size threshold, in megabytes. If @var{threshold} is
-nonzero, symbols from all shared object libraries will be loaded
-automatically when the inferior begins execution or when the dynamic
-linker informs @value{GDBN} that a new library has been loaded, until
-the symbol table of the program and libraries exceeds this threshold.
+@kindex set auto-solib-limit
+@item set auto-solib-limit @var{threshold}
+Set the autoloading size threshold, in an integral number of megabytes.
+If @var{threshold} is nonzero and shared library autoloading is enabled,
+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 megabytes.
+@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100
+Mb).
-@kindex show auto-solib-add
-@item show auto-solib-add
+@kindex show auto-solib-limit
+@item show auto-solib-limit
Display the current autoloading size threshold, in megabytes.
@end table
@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
Other remote targets may be available in your
configuration of @value{GDBN}; use @code{help target} to list them.
-@menu
-* Remote Serial:: @value{GDBN} remote serial protocol
-@end menu
+@node KOD
+@section Kernel Object Display
-@node Remote Serial
-@subsection The @value{GDBN} remote serial protocol
+@cindex kernel object display
+@cindex kernel object
+@cindex KOD
-@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
-prerequisites for the program to run by itself. For example, for a C
-program, you need:
+Some targets support kernel object display. Using this facility,
+@value{GDBN} communicates specially with the underlying operating system
+and can display information about operating system-level objects such as
+mutexes and other synchronization objects. Exactly which objects can be
+displayed is determined on a per-OS basis.
-@enumerate
-@item
-A startup routine to set up the C runtime environment; these usually
-have a name like @file{crt0}. The startup routine may be supplied by
-your hardware supplier, or you may have to write your own.
+Use the @code{set os} command to set the operating system. This tells
+@value{GDBN} which kernel object display module to initialize:
-@item
-A C subroutine library to support your program's
-subroutine calls, notably managing input and output.
+@smallexample
+(@value{GDBP}) set os cisco
+@end smallexample
-@item
-A way of getting your program to the other machine---for example, a
-download program. These are often supplied by the hardware
-manufacturer, but you may have to write your own from hardware
-documentation.
-@end enumerate
+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:
-The next step is to arrange for your program to use a serial port to
-communicate with the machine where @value{GDBN} is running (the @dfn{host}
-machine). In general terms, the scheme looks like this:
+@smallexample
+(@value{GDBP}) info cisco
+List of Cisco Kernel Objects
+Object Description
+any Any and all objects
+@end smallexample
-@table @emph
-@item On the host,
-@value{GDBN} already understands how to use this protocol; when everything
-else is set up, you can simply use the @samp{target remote} command
-(@pxref{Targets,,Specifying a Debugging Target}).
+Further subcommands can be used to query about particular objects known
+by the kernel.
-@item On the target,
-you must link with your program a few special-purpose subroutines that
-implement the @value{GDBN} remote serial protocol. The file containing these
-subroutines is called a @dfn{debugging stub}.
+There is currently no way to determine whether a given operating system
+is supported other than to try it.
-On certain remote targets, you can use an auxiliary program
-@code{gdbserver} instead of linking a stub into your program.
-@xref{Server,,Using the @code{gdbserver} program}, for details.
-@end table
-The debugging stub is specific to the architecture of the remote
-machine; for example, use @file{sparc-stub.c} to debug programs on
-@sc{sparc} boards.
+@node Remote Debugging
+@chapter Debugging remote programs
-@cindex remote serial stub list
-These working remote stubs are distributed with @value{GDBN}:
+@menu
+* Server:: Using the gdbserver program
+* NetWare:: Using the gdbserve.nlm program
+* remote stub:: Implementing a remote stub
+@end menu
-@table @code
+@node Server
+@section Using the @code{gdbserver} program
-@item i386-stub.c
+@kindex gdbserver
+@cindex remote connection without stubs
+@code{gdbserver} is a control program for Unix-like systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}---but without linking in the usual debugging stub.
+
+@code{gdbserver} is not a complete replacement for the debugging stubs,
+because it requires essentially the same operating-system facilities
+that @value{GDBN} itself does. In fact, a system that can run
+@code{gdbserver} to connect to a remote @value{GDBN} could also run
+@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
+because it is a much smaller program than @value{GDBN} itself. It is
+also easier to port than all of @value{GDBN}, so you may be able to get
+started more quickly on a new system by using @code{gdbserver}.
+Finally, if you develop code for real-time systems, you may find that
+the tradeoffs involved in real-time operation make it more convenient to
+do as much development work as possible on another system, for example
+by cross-compiling. You can use @code{gdbserver} to make a similar
+choice for debugging.
+
+@value{GDBN} and @code{gdbserver} communicate via either a serial line
+or a TCP connection, using the standard @value{GDBN} remote serial
+protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserver} does not need your program's symbol table, so you can
+strip the program if necessary to save space. @value{GDBN} on the host
+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 usual
+syntax is:
+
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@var{comm} is either a device name (to use a serial line) or a TCP
+hostname and portnumber. For example, to debug Emacs with the argument
+@samp{foo.txt} and communicate with @value{GDBN} over the serial port
+@file{/dev/com1}:
+
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
+
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
+
+To use a TCP connection instead of a serial line:
+
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
+
+The only difference from the previous example is the first argument,
+specifying that you are communicating with the host @value{GDBN} via
+TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
+expect a TCP connection from machine @samp{host} to local TCP port 2345.
+(Currently, the @samp{host} part is ignored.) You can choose any number
+you want for the port number as long as it does not conflict with any
+TCP ports already in use on the target system (for example, @code{23} is
+reserved for @code{telnet}).@footnote{If you choose a port number that
+conflicts with another service, @code{gdbserver} prints an error message
+and exits.} You must use the same port number with the host @value{GDBN}
+@code{target remote} command.
+
+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.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}.) After that, use @code{target
+remote} to establish communications with @code{gdbserver}. Its argument
+is either a device name (usually a serial device, like
+@file{/dev/ttyb}), or a TCP port descriptor in the form
+@code{@var{host}:@var{PORT}}. For example:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
+
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
+
+@noindent
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
+For TCP connections, you must start up @code{gdbserver} prior to using
+the @code{target remote} command. Otherwise you may get an error whose
+text depends on the host system, but which usually looks something like
+@samp{Connection refused}.
+@end table
+
+@node NetWare
+@section Using the @code{gdbserve.nlm} program
+
+@kindex gdbserve.nlm
+@code{gdbserve.nlm} is a control program for NetWare systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}.
+
+@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
+using the standard @value{GDBN} remote serial protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserve.nlm} does not need your program's symbol table, so you
+can strip the program if necessary to save space. @value{GDBN} on the
+host 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 syntax is:
+
+@smallexample
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+ [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@var{board} and @var{port} specify the serial line; @var{baud} specifies
+the baud rate used by the connection. @var{port} and @var{node} default
+to 0, @var{baud} defaults to 9600@dmn{bps}.
+
+For example, to debug Emacs with the argument @samp{foo.txt}and
+communicate with @value{GDBN} over serial port number 2 or board 1
+using a 19200@dmn{bps} connection:
+
+@smallexample
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@end smallexample
+
+@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.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600@dmn{bps}. After that, use @code{target
+remote} to establish communications with @code{gdbserve.nlm}. Its
+argument is a device name (usually a serial device, like
+@file{/dev/ttyb}). For example:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communications with the server via serial line @file{/dev/ttyb}.
+@end table
+
+@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
+prerequisites for the program to run by itself. For example, for a C
+program, you need:
+
+@enumerate
+@item
+A startup routine to set up the C runtime environment; these usually
+have a name like @file{crt0}. The startup routine may be supplied by
+your hardware supplier, or you may have to write your own.
+
+@item
+A C subroutine library to support your program's
+subroutine calls, notably managing input and output.
+
+@item
+A way of getting your program to the other machine---for example, a
+download program. These are often supplied by the hardware
+manufacturer, but you may have to write your own from hardware
+documentation.
+@end enumerate
+
+The next step is to arrange for your program to use a serial port to
+communicate with the machine where @value{GDBN} is running (the @dfn{host}
+machine). In general terms, the scheme looks like this:
+
+@table @emph
+@item On the host,
+@value{GDBN} already understands how to use this protocol; when everything
+else is set up, you can simply use the @samp{target remote} command
+(@pxref{Targets,,Specifying a Debugging Target}).
+
+@item On the target,
+you must link with your program a few special-purpose subroutines that
+implement the @value{GDBN} remote serial protocol. The file containing these
+subroutines is called a @dfn{debugging stub}.
+
+On certain remote targets, you can use an auxiliary program
+@code{gdbserver} instead of linking a stub into your program.
+@xref{Server,,Using the @code{gdbserver} program}, for details.
+@end table
+
+The debugging stub is specific to the architecture of the remote
+machine; for example, use @file{sparc-stub.c} to debug programs on
+@sc{sparc} boards.
+
+@cindex remote serial stub list
+These working remote stubs are distributed with @value{GDBN}:
+
+@table @code
+
+@item i386-stub.c
@cindex @file{i386-stub.c}
@cindex Intel
@cindex i386
* Stub Contents:: What the stub can do for you
* Bootstrapping:: What you must do for the stub
* Debug Session:: Putting it all together
-* Protocol:: Definition of the communication protocol
-* Server:: Using the `gdbserver' program
-* NetWare:: Using the `gdbserve.nlm' program
@end menu
@node Stub Contents
-@subsubsection What the stub can do for you
+@subsection What the stub can do for you
@cindex remote serial stub
The debugging stub for your architecture supplies these three
@end table
@node Bootstrapping
-@subsubsection What you must do for the stub
+@subsection What you must do for the stub
@cindex remote stub, support routines
The debugging stubs that come with @value{GDBN} are set up for a particular
@node Debug Session
-@subsubsection Putting it all together
+@subsection Putting it all together
@cindex remote serial debugging summary
In summary, when your program is ready to debug, you must follow these
@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:
+
+@smallexample
+target remote :1234
+@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
-@subsubsection 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
+
+@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.
+
+@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.
+
+@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.
+
+@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.
+
+@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.
+
+@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:
-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.
+@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
-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.
+@noindent
+This comes in handy when you want to see whether a pointer is outside
+the data segment's limit (i.e.@: @dfn{garbled}).
+
+@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.
+
+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.
+
+@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.
+
+These commands are supported only with some DPMI servers.
+
+@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:
+
+@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
-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
+@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 extended ops
-@tab @code{!}
-@tab
-Use the extended remote protocol. Sticky---only needs to be set once.
-The extended remote protocol supports the @samp{R} packet.
-@item
-@tab reply @samp{}
-@tab
-Stubs that support the extended remote protocol return @samp{} which,
-unfortunately, is identical to the response returned by stubs that do not
-support protocol extensions.
+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 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
+Here's another example, it displays the Page Table entry for the
+transfer buffer:
+@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 reserved
-@tab @code{a}
-@tab Reserved for future use
+@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
+
+@node Cygwin Native
+@subsection Features for Debugging MS Windows PE executables
+@cindex MS Windows debugging
+@cindex native Cygwin debugging
+@cindex Cygwin-specific commands
+
+@value{GDBN} supports native debugging of MS Windows programs, and
+defines a few commands specific to the Cygwin port. This
+subsection describes those commands.
+
+@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 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 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}
+@end table
-@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.}
+@node Embedded OS
+@section Embedded Operating Systems
-@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.}
+This section describes configurations involving the debugging of
+embedded operating systems that are available for several different
+architectures.
-@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
+@menu
+* VxWorks:: Using @value{GDBN} with VxWorks
+@end menu
-@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
+@value{GDBN} includes the ability to debug programs running on
+various real-time operating systems.
-@item toggle debug @strong{(deprecated)}
-@tab @code{d}
-@tab
-toggle debug flag.
+@node VxWorks
+@subsection Using @value{GDBN} with VxWorks
-@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 VxWorks
-@item reserved
-@tab @code{e}
-@tab Reserved for future use
+@table @code
-@item reserved
-@tab @code{E}
-@tab Reserved for future use
+@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 reserved
-@tab @code{f}
-@tab Reserved for future use
+@end table
-@item reserved
-@tab @code{F}
-@tab Reserved for future use
+On VxWorks, @code{load} links @var{filename} dynamically on the
+current target system as well as adding its symbols in @value{GDBN}.
-@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.
+@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 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
+@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 reserved
-@tab @code{h}
-@tab Reserved for future use
+The following information on connecting to VxWorks was current when
+this manual was produced; newer releases of VxWorks may use revised
+procedures.
-@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
+@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}.
-@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.
+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 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 up showing the prompt:
-@item signal then cycle step @strong{(reserved)}
-@tab @code{I}
-@tab
-See @samp{i} and @samp{S} for likely syntax and semantics.
+@smallexample
+(vxgdb)
+@end smallexample
-@item reserved
-@tab @code{j}
-@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{J}
-@tab Reserved for future use
+@node VxWorks Connection
+@subsubsection Connecting to VxWorks
-@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?)}.
+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{l}
-@tab Reserved for future use
+@smallexample
+(vxgdb) target vxworks tt
+@end smallexample
-@item reserved
-@tab @code{L}
-@tab Reserved for future use
+@need 750
+@value{GDBN} displays messages like these:
-@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
+@smallexample
+Attaching remote machine across net...
+Connected to tt.
+@end smallexample
-@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).
+@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{n}
-@tab Reserved for future use
+@smallexample
+prog.o: No such file or directory.
+@end smallexample
-@item reserved
-@tab @code{N}
-@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 reserved
-@tab @code{o}
-@tab Reserved for future use
+@node VxWorks Download
+@subsubsection VxWorks download
-@item reserved
-@tab @code{O}
-@tab Reserved for future use
+@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:
-@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.
+@smallexample
+-> cd "@var{vxpath}/vw/demo/rdb"
+@end smallexample
-@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
+@noindent
+Then, in @value{GDBN}, type:
-@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}.
+@smallexample
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) load prog.o
+@end smallexample
-@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.
-
-@item reset @strong{(deprecated)}
-@tab @code{r}
-@tab
-Reset the entire system.
-
-@item remote restart
-@tab @code{R}@var{XX}
-@tab
-Restart the remote server. @var{XX} while needed has no clear
-definition. FIXME: @emph{An example interaction explaining how this
-packet is used in extended-remote mode is needed}.
-
-@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
-
-@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
-
-@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.
-
-@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
-
-@item reserved
-@tab @code{u}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{U}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{v}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{V}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{w}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{W}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{x}
-@tab Reserved for future use
-
-@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
-
-@item reserved
-@tab @code{y}
-@tab Reserved for future use
-
-@item reserved
-@tab @code{Y}
-@tab Reserved for future use
-
-@item remove break or watchpoint @strong{(draft)}
-@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
-@tab
-See @samp{Z}.
-
-@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.}
+@value{GDBN} displays a response similar to this:
-@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.
+@smallexample
+Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+@end smallexample
-@end multitable
+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.)
-The following set and query packets have already been defined.
+@node VxWorks Attach
+@subsubsection Running tasks
-@multitable @columnfractions .2 .2 .6
+@cindex running VxWorks tasks
+You can also attach to an existing task using the @code{attach} command as
+follows:
-@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.
+@smallexample
+(vxgdb) attach @var{task}
+@end smallexample
-@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'}).
+@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.
-@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.
+@node Embedded Processors
+@section Embedded Processors
-@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()}.
+This section goes into details specific to particular embedded
+configurations.
-@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}
+@menu
+* 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
-@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()}.
+@node ARM
+@subsection ARM
-@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.
+@table @code
-@item
-@tab reply @samp{}
-@tab
-When @samp{q}@samp{Rcmd} is not recognized.
+@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.
-@end multitable
+@kindex target rdp
+@item target rdp @var{dev}
+ARM Demon monitor.
-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.
+@end table
-@multitable @columnfractions .5 .5
+@node H8/300
+@subsection Hitachi H8/300
-@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.
+@table @code
-@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}.
+@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.
-@end multitable
+@kindex target e7000@r{, with H8/300}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
-Example sequence of a target being re-started. Notice how the restart
-does not get any direct output:
+@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.
-@example
-<- @code{R00}
--> @code{+}
-@emph{target restarts}
-<- @code{?}
--> @code{+}
--> @code{T001:1234123412341234}
-<- @code{+}
-@end example
+@end table
-Example sequence of a target being stepped by a single instruction:
+@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).
-@example
-<- @code{G1445...}
--> @code{+}
-<- @code{s}
--> @code{+}
-@emph{time passes}
--> @code{T001:1234123412341234}
-<- @code{+}
-<- @code{g}
--> @code{+}
--> @code{1455...}
-<- @code{+}
-@end example
+@value{GDBN} needs to know these things to talk to your
+Hitachi SH, H8/300, or H8/500:
-@node Server
-@subsubsection Using the @code{gdbserver} program
+@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 gdbserver
-@cindex remote connection without stubs
-@code{gdbserver} is a control program for Unix-like systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}---but without linking in the usual debugging stub.
+@item
+what serial device connects your host to your Hitachi board (the first
+serial device available on your host is the default).
-@code{gdbserver} is not a complete replacement for the debugging stubs,
-because it requires essentially the same operating-system facilities
-that @value{GDBN} itself does. In fact, a system that can run
-@code{gdbserver} to connect to a remote @value{GDBN} could also run
-@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
-because it is a much smaller program than @value{GDBN} itself. It is
-also easier to port than all of @value{GDBN}, so you may be able to get
-started more quickly on a new system by using @code{gdbserver}.
-Finally, if you develop code for real-time systems, you may find that
-the tradeoffs involved in real-time operation make it more convenient to
-do as much development work as possible on another system, for example
-by cross-compiling. You can use @code{gdbserver} to make a similar
-choice for debugging.
+@item
+what speed to use over the serial device.
+@end enumerate
-@value{GDBN} and @code{gdbserver} communicate via either a serial line
-or a TCP connection, using the standard @value{GDBN} remote serial
-protocol.
+@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
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserver} does not need your program's symbol table, so you can
-strip the program if necessary to save space. @value{GDBN} on the host
-system does all the symbol handling.
+@node Hitachi Boards
+@subsubsection Connecting to Hitachi boards
-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
-syntax is:
+@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}.
-@smallexample
-target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@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).
-@var{comm} is either a device name (to use a serial line) or a TCP
-hostname and portnumber. For example, to debug Emacs with the argument
-@samp{foo.txt} and communicate with @value{GDBN} over the serial port
-@file{/dev/com1}:
+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.
+
+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.
+
+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}.
@smallexample
-target> gdbserver /dev/com1 emacs foo.txt
-@end smallexample
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
+Resident portion of MODE loaded
-To use a TCP connection instead of a serial line:
+COM2: 9600, n, 8, 1, p
-@smallexample
-target> gdbserver host:2345 emacs foo.txt
@end smallexample
-The only difference from the previous example is the first argument,
-specifying that you are communicating with the host @value{GDBN} via
-TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
-expect a TCP connection from machine @samp{host} to local TCP port 2345.
-(Currently, the @samp{host} part is ignored.) You can choose any number
-you want for the port number as long as it does not conflict with any
-TCP ports already in use on the target system (for example, @code{23} is
-reserved for @code{telnet}).@footnote{If you choose a port number that
-conflicts with another service, @code{gdbserver} prints an error message
-and exits.} You must use the same port number with the host @value{GDBN}
-@code{target remote} command.
+@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
-@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.
-(You may also need the @w{@samp{--baud}} option if the serial line is
-running at anything other than 9600@dmn{bps}.) After that, use @code{target
-remote} to establish communications with @code{gdbserver}. Its argument
-is either a device name (usually a serial device, like
-@file{/dev/ttyb}), or a TCP port descriptor in the form
-@code{@var{host}:@var{PORT}}. For example:
+@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
-(@value{GDBP}) target remote /dev/ttyb
+(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
-communicates with the server via serial line @file{/dev/ttyb}, and
-
-@smallexample
-(@value{GDBP}) target remote the-target:2345
-@end smallexample
+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.
-@noindent
-communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
-For TCP connections, you must start up @code{gdbserver} prior to using
-the @code{target remote} command. Otherwise you may get an error whose
-text depends on the host system, but which usually looks something like
-@samp{Connection refused}.
-@end table
+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!
-@node NetWare
-@subsubsection Using the @code{gdbserve.nlm} program
+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
-@kindex gdbserve.nlm
-@code{gdbserve.nlm} is a control program for NetWare systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}.
+@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} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
+development board as a ``normal exit'' of your program.
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserve.nlm} does not need your program's symbol table, so you
-can strip the program if necessary to save space. @value{GDBN} on the
-host system does all the symbol handling.
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
-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 syntax is:
+@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:
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
- [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
+@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}).
-@var{board} and @var{port} specify the serial line; @var{baud} specifies
-the baud rate used by the connection. @var{port} and @var{node} default
-to 0, @var{baud} defaults to 9600@dmn{bps}.
+@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
-For example, to debug Emacs with the argument @samp{foo.txt}and
-communicate with @value{GDBN} over serial port number 2 or board 1
-using a 19200@dmn{bps} connection:
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
+Some @value{GDBN} commands are available only for the H8/300:
-@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.
-(You may also need the @w{@samp{--baud}} option if the serial line is
-running at anything other than 9600@dmn{bps}. After that, use @code{target
-remote} to establish communications with @code{gdbserve.nlm}. Its
-argument is a device name (usually a serial device, like
-@file{/dev/ttyb}). For example:
+@table @code
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@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.
-@noindent
-communications with the server via serial line @file{/dev/ttyb}.
@end table
-@node KOD
-@section Kernel Object Display
-
-@cindex kernel object display
-@cindex kernel object
-@cindex KOD
+@node H8/500
+@subsection H8/500
-Some targets support kernel object display. Using this facility,
-@value{GDBN} communicates specially with the underlying operating system
-and can display information about operating system-level objects such as
-mutexes and other synchronization objects. Exactly which objects can be
-displayed is determined on a per-OS basis.
+@table @code
-Use the @code{set os} command to set the operating system. This tells
-@value{GDBN} which kernel object display module to initialize:
+@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}.
-@example
-(@value{GDBP}) set os cisco
-@end example
+@end table
-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:
+@node i960
+@subsection Intel i960
-@example
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object Description
-any Any and all objects
-@end example
+@table @code
-Further subcommands can be used to query about particular objects known
-by the kernel.
+@kindex target mon960
+@item target mon960 @var{dev}
+MON960 monitor for Intel i960.
-There is currently no way to determine whether a given operating system
-is supported other than to try it.
+@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}.
+@end table
-@node Configurations
-@chapter Configuration-Specific Information
+@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:
-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.
+@itemize @bullet
+@item
+Through command line options specifying serial port, version of the
+Nindy protocol, and communications speed;
-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.
+@item
+By responding to a prompt on startup;
-@menu
-* Native::
-* Embedded OS::
-* Embedded Processors::
-* Architectures::
-@end menu
+@item
+By using the @code{target} command at any point during your @value{GDBN}
+session. @xref{Target Commands, ,Commands for managing targets}.
-@node Native
-@section Native
+@end itemize
-This section describes details specific to particular native
-configurations.
+@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}.
@menu
-* HP-UX:: HP-UX
-* SVR4 Process Information:: SVR4 process information
+* Nindy Startup:: Startup with Nindy
+* Nindy Options:: Options for Nindy
+* Nindy Reset:: Nindy reset command
@end menu
-@node HP-UX
-@subsection HP-UX
+@node Nindy Startup
+@subsubsection Startup with Nindy
-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.
+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:
-@node SVR4 Process Information
-@subsection SVR4 process information
+@smallexample
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
+@end smallexample
-@kindex /proc
-@cindex process image
+@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}).
-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 Nindy Options
+@subsubsection Options for Nindy
+
+These are the startup options for beginning your @value{GDBN} session with a
+Nindy-960 board attached:
@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.
+@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}).
-@kindex info proc times
-@item info proc times
-Starting time, user CPU time, and system CPU time for your program and
-its children.
+@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.
-@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.
+@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
-@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.
+@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.
-@item info proc all
-Show all the above information about the process.
+@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
-@node Embedded OS
-@section Embedded Operating Systems
-
-This section describes configurations involving the debugging of
-embedded operating systems that are available for several different
-architectures.
-
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
+The standard @samp{-b} option controls the line speed used on the serial
+port.
-@value{GDBN} includes the ability to debug programs running on
-various real-time operating systems.
+@c @group
+@node Nindy Reset
+@subsubsection Nindy reset command
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
+@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
-@cindex VxWorks
+@node M32R/D
+@subsection Mitsubishi M32R/D
@table @code
-@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.
+@kindex target m32r
+@item target m32r @var{dev}
+Mitsubishi M32R/D ROM monitor.
@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 M68K
+@subsection M68k
-@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.)
+The Motorola m68k configuration includes ColdFire support, and
+target command for the following ROM monitors.
@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
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
+@kindex target abug
+@item target abug @var{dev}
+ABug ROM monitor for M68K.
-@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}.
+@kindex target cpu32bug
+@item target cpu32bug @var{dev}
+CPU32BUG monitor, running on a CPU32 (M68K) board.
-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).
+@kindex target dbug
+@item target dbug @var{dev}
+dBUG ROM monitor for Motorola ColdFire.
-@value{GDBN} comes up showing the prompt:
+@kindex target est
+@item target est @var{dev}
+EST-300 ICE monitor, running on a CPU32 (M68K) board.
-@example
-(vxgdb)
-@end example
+@kindex target rom68k
+@item target rom68k @var{dev}
+ROM 68K monitor, running on an M68K IDP board.
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
+@end table
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
+If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
+instead have only a single special target command:
-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:
+@table @code
-@example
-(vxgdb) target vxworks tt
-@end example
+@kindex target es1800
+@item target es1800 @var{dev}
+ES-1800 emulator for M68K.
-@need 750
-@value{GDBN} displays messages like these:
+@end table
-@smallexample
-Attaching remote machine across net...
-Connected to tt.
-@end smallexample
+[context?]
-@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:
+@table @code
-@example
-prog.o: No such file or directory.
-@end example
+@kindex target rombug
+@item target rombug @var{dev}
+ROMBUG ROM monitor for OS/9000.
-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.
+@end table
-@node VxWorks Download
-@subsubsection VxWorks download
+@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
-@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:
+@node MIPS Embedded
+@subsection MIPS Embedded
-@example
--> cd "@var{vxpath}/vw/demo/rdb"
-@end example
+@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}.
-@noindent
-Then, in @value{GDBN}, type:
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
-@example
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end example
+@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.
-@value{GDBN} displays a response similar to this:
+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:
@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+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
-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 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}}.
+
+@item target pmon @var{port}
+@kindex target pmon @var{port}
+PMON ROM monitor.
+
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+NEC's DDB variant of PMON for Vr4300.
+
+@item target lsi @var{port}
+@kindex target lsi @var{port}
+LSI variant of PMON.
-@node VxWorks Attach
-@subsubsection Running tasks
+@kindex target r3900
+@item target r3900 @var{dev}
+Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
+@kindex target array
+@item target array @var{dev}
+Array Tech LSI33K RAID controller board.
+
+@end table
-@example
-(vxgdb) attach @var{task}
-@end example
@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.
+@value{GDBN} also supports these special commands for MIPS targets:
-@node Embedded Processors
-@section Embedded 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.
-This section goes into details specific to particular embedded
-configurations.
+@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}.
-@menu
-* A29K Embedded:: AMD A29K Embedded
-* 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
+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.
-@node A29K Embedded
-@subsection AMD A29K Embedded
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
-@menu
-* A29K UDI::
-* A29K EB29K::
-* Comms (EB29K):: Communications setup
-* gdb-EB29K:: EB29K cross-debugging
-* Remote Log:: Remote log
-@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}.
-@table @code
+@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}.)
-@kindex target adapt
-@item target adapt @var{dev}
-Adapt monitor for A29K.
+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
-@kindex target amd-eb
-@item target amd-eb @var{dev} @var{speed} @var{PROG}
-@cindex AMD EB29K
-Remote PC-resident AMD EB29K board, attached over serial lines.
-@var{dev} is the serial device, as for @code{target remote};
-@var{speed} allows you to specify the linespeed; and @var{PROG} is the
-name of the program to be debugged, as it appears to DOS on the PC.
-@xref{A29K EB29K, ,EBMON protocol for AMD29K}.
+@node PowerPC
+@subsection PowerPC
-@end table
+@table @code
-@node A29K UDI
-@subsubsection A29K UDI
+@kindex target dink32
+@item target dink32 @var{dev}
+DINK32 ROM monitor.
-@cindex UDI
-@cindex AMD29K via UDI
+@kindex target ppcbug
+@item target ppcbug @var{dev}
+@kindex target ppcbug1
+@item target ppcbug1 @var{dev}
+PPCBUG ROM monitor for PowerPC.
-@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
-protocol for debugging the a29k processor family. To use this
-configuration with AMD targets running the MiniMON monitor, you need the
-program @code{MONTIP}, available from AMD at no charge. You can also
-use @value{GDBN} with the UDI-conformant a29k simulator program
-@code{ISSTIP}, also available from AMD.
+@kindex target sds
+@item target sds @var{dev}
+SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-@table @code
-@item target udi @var{keyword}
-@kindex udi
-Select the UDI interface to a remote a29k board or simulator, where
-@var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
-This file contains keyword entries which specify parameters used to
-connect to a29k targets. If the @file{udi_soc} file is not in your
-working directory, you must set the environment variable @samp{UDICONF}
-to its pathname.
@end table
-@node A29K EB29K
-@subsubsection EBMON protocol for AMD29K
+@node PA
+@subsection HP PA Embedded
-@cindex EB29K board
-@cindex running 29K programs
+@table @code
-AMD distributes a 29K development board meant to fit in a PC, together
-with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
-term, this development system is called the ``EB29K''. To use
-@value{GDBN} from a Unix system to run programs on the EB29K board, you
-must first connect a serial cable between the PC (which hosts the EB29K
-board) and a serial port on the Unix system. In the following, we
-assume you've hooked the cable between the PC's @file{COM1} port and
-@file{/dev/ttya} on the Unix system.
+@kindex target op50n
+@item target op50n @var{dev}
+OP50N monitor, running on an OKI HPPA board.
-@node Comms (EB29K)
-@subsubsection Communications setup
+@kindex target w89k
+@item target w89k @var{dev}
+W89K monitor, running on a Winbond HPPA board.
-The next step is to set up the PC's port, by doing something like this
-in DOS on the PC:
+@end table
-@example
-C:\> MODE com1:9600,n,8,1,none
-@end example
+@node SH
+@subsection Hitachi SH
-@noindent
-This example---run on an MS DOS 4.0 system---sets the PC port to 9600
-bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
-you must match the communications parameters when establishing the Unix
-end of the connection as well.
-@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
-@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
-@c
-@c It's optional, but it's unwise to omit it: who knows what is the
-@c default value set when the DOS machines boots? "No retry" means that
-@c the DOS serial device driver won't retry the operation if it fails;
-@c I understand that this is needed because the GDB serial protocol
-@c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
+@table @code
-To give control of the PC to the Unix side of the serial line, type
-the following at the DOS console:
+@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.
-@example
-C:\> CTTY com1
-@end example
+@kindex target e7000@r{, with Hitachi SH}
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi SH.
-@noindent
-(Later, if you wish to return control to the DOS console, you can use
-the command @code{CTTY con}---but you must send it over the device that
-had control, in our example over the @file{COM1} serial line.)
+@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.
-From the Unix host, use a communications program such as @code{tip} or
-@code{cu} to communicate with the PC; for example,
+@end table
-@example
-cu -s 9600 -l /dev/ttya
-@end example
+@node Sparclet
+@subsection Tsqware Sparclet
-@noindent
-The @code{cu} options shown specify, respectively, the linespeed and the
-serial port to use. If you use @code{tip} instead, your command line
-may look something like the following:
+@cindex Sparclet
-@example
-tip -9600 /dev/ttya
-@end example
+@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.
-@noindent
-Your system may require a different name where we show
-@file{/dev/ttya} as the argument to @code{tip}. The communications
-parameters, including which port to use, are associated with the
-@code{tip} argument in the ``remote'' descriptions file---normally the
-system table @file{/etc/remote}.
-@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
-@c the DOS side's comms setup? cu can support -o (odd
-@c parity), -e (even parity)---apparently no settings for no parity or
-@c for character size. Taken from stty maybe...? John points out tip
-@c can set these as internal variables, eg ~s parity=none; man stty
-@c suggests that it *might* work to stty these options with stdin or
-@c stdout redirected... ---doc@cygnus.com, 25feb91
-@c
-@c There's nothing to be done for the "none" part of the DOS MODE
-@c command. The rest of the parameters should be matched by the
-@c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
-
-@kindex EBMON
-Using the @code{tip} or @code{cu} connection, change the DOS working
-directory to the directory containing a copy of your 29K program, then
-start the PC program @code{EBMON} (an EB29K control program supplied
-with your board by AMD). You should see an initial display from
-@code{EBMON} similar to the one that follows, ending with the
-@code{EBMON} prompt @samp{#}---
-
-@example
-C:\> G:
-
-G:\> CD \usr\joe\work29k
-
-G:\USR\JOE\WORK29K> EBMON
-Am29000 PC Coprocessor Board Monitor, version 3.0-18
-Copyright 1990 Advanced Micro Devices, Inc.
-Written by Gibbons and Associates, Inc.
-
-Enter '?' or 'H' for help
-
-PC Coprocessor Type = EB29K
-I/O Base = 0x208
-Memory Base = 0xd0000
-
-Data Memory Size = 2048KB
-Available I-RAM Range = 0x8000 to 0x1fffff
-Available D-RAM Range = 0x80002000 to 0x801fffff
-
-PageSize = 0x400
-Register Stack Size = 0x800
-Memory Stack Size = 0x1800
-
-CPU PRL = 0x3
-Am29027 Available = No
-Byte Write Available = Yes
-
-# ~.
-@end example
-
-Then exit the @code{cu} or @code{tip} program (done in the example by
-typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
-running, ready for @value{GDBN} to take over.
-
-For this example, we've assumed what is probably the most convenient
-way to make sure the same 29K program is on both the PC and the Unix
-system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
-PC as a file system on the Unix host. If you do not have PC/NFS or
-something similar connecting the two systems, you must arrange some
-other way---perhaps floppy-disk transfer---of getting the 29K program
-from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
-serial line.
-
-@node gdb-EB29K
-@subsubsection EB29K cross-debugging
-
-Finally, @code{cd} to the directory containing an image of your 29K
-program on the Unix system, and start @value{GDBN}---specifying as argument the
-name of your 29K program:
-
-@example
-cd /usr/joe/work29k
-@value{GDBP} myfoo
-@end example
-
-@need 500
-Now you can use the @code{target} command:
-
-@example
-target amd-eb /dev/ttya 9600 MYFOO
-@c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
-@c emphasize that this is the name as seen by DOS (since I think DOS is
-@c single-minded about case of letters). ---doc@cygnus.com, 25feb91
-@end example
+@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
-@noindent
-In this example, we've assumed your program is in a file called
-@file{myfoo}. Note that the filename given as the last argument to
-@code{target amd-eb} should be the name of the program as it appears to DOS.
-In our example this is simply @code{MYFOO}, but in general it can include
-a DOS path, and depending on your transfer mechanism may not resemble
-the name on the Unix side.
-
-At this point, you can set any breakpoints you wish; when you are ready
-to see your program run on the 29K board, use the @value{GDBN} command
-@code{run}.
-
-To stop debugging the remote program, use the @value{GDBN} @code{detach}
-command.
+@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:
-To return control of the PC to its console, use @code{tip} or @code{cu}
-once again, after your @value{GDBN} session has concluded, to attach to
-@code{EBMON}. You can then type the command @code{q} to shut down
-@code{EBMON}, returning control to the DOS command-line interpreter.
-Type @kbd{CTTY con} to return command input to the main DOS console,
-and type @kbd{~.} to leave @code{tip} or @code{cu}.
-
-@node Remote Log
-@subsubsection Remote log
-@cindex @file{eb.log}, a log file for EB29K
-@cindex log file for EB29K
-
-The @code{target amd-eb} command creates a file @file{eb.log} in the
-current working directory, to help debug problems with the connection.
-@file{eb.log} records all the output from @code{EBMON}, including echoes
-of the commands sent to it. Running @samp{tail -f} on this file in
-another window often helps to understand trouble with @code{EBMON}, or
-unexpected events on the PC side of the connection.
+@smallexample
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end smallexample
-@node ARM
-@subsection ARM
+You can use @code{objdump} to verify that the addresses are what you intended:
-@table @code
+@smallexample
+sparclet-aout-objdump --headers --syms prog
+@end smallexample
-@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.
+@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).
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
+@value{GDBN} comes up showing the prompt:
-@end table
+@smallexample
+(gdbslet)
+@end smallexample
-@node H8/300
-@subsection Hitachi H8/300
+@menu
+* Sparclet File:: Setting the file to debug
+* Sparclet Connection:: Connecting to Sparclet
+* Sparclet Download:: Sparclet download
+* Sparclet Execution:: Running and debugging
+@end menu
-@table @code
+@node Sparclet File
+@subsubsection Setting file to debug
-@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.
+The @value{GDBN} command @code{file} lets you choose with program to debug.
-@kindex target e7000@r{, with H8/300}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi H8 and SH.
+@smallexample
+(gdbslet) file prog
+@end smallexample
-@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.
+@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:
+
+@smallexample
+prog: No such file or directory.
+@end smallexample
-@end table
+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.
-@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).
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
-@value{GDBN} needs to know these things to talk to your
-Hitachi SH, H8/300, or H8/500:
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
-@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.)
+@smallexample
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3
+@end smallexample
-@item
-what serial device connects your host to your Hitachi board (the first
-serial device available on your host is the default).
+@need 750
+@value{GDBN} displays messages like these:
-@item
-what speed to use over the serial device.
-@end enumerate
+@smallexample
+Connected to ttya.
+@end smallexample
-@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
+@node Sparclet Download
+@subsubsection Sparclet download
-@node Hitachi Boards
-@subsubsection Connecting to Hitachi boards
+@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:
-@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}.
+@smallexample
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end smallexample
-@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).
+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.
-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.
+@node Sparclet Execution
+@subsubsection Running and debugging
-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 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.
-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}.
+@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
-@example
-C:\H8300\TEST> asynctsr 2
-C:\H8300\TEST> mode com2:9600,n,8,1,p
+@node Sparclite
+@subsection Fujitsu Sparclite
-Resident portion of MODE loaded
+@table @code
-COM2: 9600, n, 8, 1, p
+@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 example
+@end table
-@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
+@node ST2000
+@subsection Tandem ST2000
-@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}.)
+@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
+STDBUG protocol.
+
+To connect your ST2000 to the host system, see the manufacturer's
+manual. Once the ST2000 is physically attached, you can run:
@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 *
+target st2000 @var{dev} @var{speed}
@end smallexample
-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.
+@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}}.
-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!
+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.
-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
+@cindex ST2000 auxiliary commands
+These auxiliary @value{GDBN} commands are available to help you with the ST2000
+environment:
-@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
+@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.
-In either case, @value{GDBN} sees the effect of a @sc{reset} on the
-development board as a ``normal exit'' of your program.
+@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 Hitachi ICE
-@subsubsection Using the E7000 in-circuit emulator
+@node Z8000
+@subsection Zilog Z8000
-@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:
+@cindex Z8000
+@cindex simulator, Z8000
+@cindex Zilog Z8000 simulator
-@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}).
+When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
+a Z8000 simulator.
-@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.
+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
-@node Hitachi Special
-@subsubsection Special @value{GDBN} commands for Hitachi micros
+@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.
-Some @value{GDBN} commands are available only for the H8/300:
+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 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.
+@item cycles
+Counts clock-ticks in the simulator.
+
+@item insts
+Counts instructions run in the simulator.
+
+@item time
+Execution time in 60ths of a second.
@end table
-@node H8/500
-@subsection H8/500
+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.
-@table @code
+@node Architectures
+@section Architectures
-@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}.
+This section describes characteristics of architectures that affect
+all uses of @value{GDBN} with the architecture, both native and cross.
-@end table
+@menu
+* A29K::
+* Alpha::
+* MIPS::
+@end menu
-@node i960
-@subsection Intel i960
+@node A29K
+@subsection A29K
@table @code
-@kindex target mon960
-@item target mon960 @var{dev}
-MON960 monitor for Intel i960.
+@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 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}.
+@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
-@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:
+@node Alpha
+@subsection Alpha
-@itemize @bullet
-@item
-Through command line options specifying serial port, version of the
-Nindy protocol, and communications speed;
+See the following section.
-@item
-By responding to a prompt on startup;
+@node MIPS
+@subsection MIPS
-@item
-By using the @code{target} command at any point during your @value{GDBN}
-session. @xref{Target Commands, ,Commands for managing targets}.
+@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.
-@end itemize
+@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 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}.
+@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.
-@menu
-* Nindy Startup:: Startup with Nindy
-* Nindy Options:: Options for Nindy
-* Nindy Reset:: Nindy reset command
-@end menu
+@item show heuristic-fence-post
+Display the current limit.
+@end table
-@node Nindy Startup
-@subsubsection Startup with Nindy
+@noindent
+These commands are available @emph{only} when @value{GDBN} is configured
+for debugging programs on Alpha or MIPS processors.
-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
-Attach /dev/ttyNN -- specify NN, or "quit" to quit:
-@end example
+@node Controlling GDB
+@chapter Controlling @value{GDBN}
-@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}).
+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.
-@node Nindy Options
-@subsubsection Options for Nindy
+@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
-These are the startup options for beginning your @value{GDBN} session with a
-Nindy-960 board attached:
+@node Prompt
+@section Prompt
-@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}).
+@cindex prompt
-@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.
+@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.
-@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
+@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.
-@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.
+@table @code
+@kindex set prompt
+@item set prompt @var{newprompt}
+Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
-@quotation
-@emph{Warning:} Many target systems do not have the hardware that this
-requires; it only works with a few boards.
-@end quotation
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
-The standard @samp{-b} option controls the line speed used on the serial
-port.
+@node Editing
+@section Command editing
+@cindex readline
+@cindex command line editing
-@c @group
-@node Nindy Reset
-@subsubsection Nindy reset 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.
+
+You may control the behavior of command line editing in @value{GDBN} with the
+command @code{set}.
@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.
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
+
+@item set editing off
+Disable command line editing.
+
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
@end table
-@c @end group
-@node M32R/D
-@subsection Mitsubishi M32R/D
+@node History
+@section Command history
+
+@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.
@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 m32r
-@item target m32r @var{dev}
-Mitsubishi M32R/D ROM monitor.
+@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.
+
+@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 M68K
-@subsection M68k
+@cindex history expansion
+History expansion assigns special meaning to the character @kbd{!}.
+@ifset have-readline-appendices
+@xref{Event Designators}.
+@end ifset
-The Motorola m68k configuration includes ColdFire support, and
-target command for the following ROM monitors.
+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.
+
+The commands to control history expansion are:
@table @code
+@kindex set history expansion
+@item set history expansion on
+@itemx set history expansion
+Enable history expansion. History expansion is off by default.
-@kindex target abug
-@item target abug @var{dev}
-ABug ROM monitor for M68K.
+@item set history expansion off
+Disable history expansion.
-@kindex target cpu32bug
-@item target cpu32bug @var{dev}
-CPU32BUG monitor, running on a CPU32 (M68K) board.
+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
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
+@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
-@kindex target est
-@item target est @var{dev}
-EST-300 ICE monitor, running on a CPU32 (M68K) board.
+@table @code
+@kindex shows
+@item show commands
+Display the last ten commands in the command history.
-@kindex target rom68k
-@item target rom68k @var{dev}
-ROM 68K monitor, running on an M68K IDP board.
+@item show commands @var{n}
+Print ten commands centered on command number @var{n}.
+@item show commands +
+Print ten commands just after the commands last printed.
@end table
-If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
-instead have only a single special target command:
+@node Screen Size
+@section Screen size
+@cindex size of screen
+@cindex pauses in output
+
+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.
+
+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:
@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.
-@kindex target es1800
-@item target es1800 @var{dev}
-ES-1800 emulator for M68K.
+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.
+Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
+from wrapping its output.
@end table
-[context?]
+@node Numbers
+@section Numbers
+@cindex number representation
+@cindex entering numbers
-@table @code
+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.
-@kindex target rombug
-@item target rombug @var{dev}
-ROMBUG ROM monitor for OS/9000.
+@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
-@end table
+@smallexample
+set radix 012
+set radix 10.
+set radix 0xa
+@end smallexample
-@node M88K
-@subsection M88K
+@noindent
+sets the base to decimal. On the other hand, @samp{set radix 10}
+leaves the radix unchanged no matter what it was.
-@table @code
+@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.
-@kindex target bug
-@item target bug @var{dev}
-BUG monitor, running on a MVME187 (m88k) board.
+@kindex show input-radix
+@item show input-radix
+Display the current default base for numeric input.
+@kindex show output-radix
+@item show output-radix
+Display the current default base for numeric display.
@end table
-@node MIPS Embedded
-@subsection MIPS Embedded
+@node Messages/Warnings
+@section Optional warnings and messages
-@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}.
+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.
-@need 1000
-Use these @value{GDBN} commands to specify the connection to your target board:
+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}.
@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:
-
-@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 set verbose
+@item set verbose on
+Enables @value{GDBN} output of certain informational messages.
-@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}}.
+@item set verbose off
+Disables @value{GDBN} output of certain informational messages.
-@item target pmon @var{port}
-@kindex target pmon @var{port}
-PMON ROM monitor.
+@kindex show verbose
+@item show verbose
+Displays whether @code{set verbose} is on or off.
+@end table
-@item target ddb @var{port}
-@kindex target ddb @var{port}
-NEC's DDB variant of PMON for Vr4300.
+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 target lsi @var{port}
-@kindex target lsi @var{port}
-LSI variant of PMON.
+@table @code
-@kindex target r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
+@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 target array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints @value{GDBN} is permitted to produce.
@end table
+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:
-@noindent
-@value{GDBN} also supports these special commands for MIPS targets:
+@smallexample
+(@value{GDBP}) run
+The program being debugged has been started already.
+Start it from the beginning? (y or n)
+@end smallexample
-@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.
+If you are willing to unflinchingly face the consequences of your own
+commands, you can disable this ``feature'':
-@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}.
+@table @code
-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.
+@kindex set confirm
+@cindex flinching
+@cindex confirmation
+@cindex stupid questions
+@item set confirm off
+Disables confirmation requests.
-As usual, you can inquire about the @code{mipsfpu} variable with
-@samp{show mipsfpu}.
+@item set confirm on
+Enables confirmation requests (the default).
-@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}.
+@kindex show confirm
+@item show confirm
+Displays state of confirmation requests.
-@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}.)
+@end table
-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.
+@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
-@node PowerPC
-@subsection PowerPC
+@node Sequences
+@chapter Canned Sequences of Commands
-@table @code
+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 target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor.
+@menu
+* Define:: User-defined commands
+* Hooks:: User-defined command hooks
+* Command Files:: Command files
+* Output:: Commands for controlled output
+@end menu
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
+@node Define
+@section User-defined commands
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+@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:
-@end table
+@smallexample
+define adder
+ print $arg0 + $arg1 + $arg2
+@end smallexample
-@node PA
-@subsection HP PA Embedded
+@noindent
+To execute the command use:
+
+@smallexample
+adder 1 2 3
+@end smallexample
+
+@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.
@table @code
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
+@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.
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
+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}.
-@end table
+@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}.
+
+@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.
-@node SH
-@subsection Hitachi SH
+@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.
-@table @code
+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.
-@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.
+@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 target e7000@r{, with Hitachi SH}
-@item target e7000 @var{dev}
-E7000 emulator for Hitachi SH.
+@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 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.
+@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 Sparclet
-@subsection Tsqware Sparclet
+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.
-@cindex Sparclet
+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.
-@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.
+@node Hooks
+@section User-defined command hooks
+@cindex command hooks
+@cindex hooks, for commands
+@cindex hooks, pre-command
-@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 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 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:
+@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.
-@example
-sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
-@end example
+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.
-You can use @code{objdump} to verify that the addresses are what you intended:
+@c It would be nice if hookpost could be passed a parameter indicating
+@c if the command it hooks executed properly or not. FIXME!
-@example
-sparclet-aout-objdump --headers --syms prog
-@end example
+@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.
-@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).
+For example, to ignore @code{SIGALRM} signals while
+single-stepping, but treat them normally during normal execution,
+you could define:
-@value{GDBN} comes up showing the prompt:
+@smallexample
+define hook-stop
+handle SIGALRM nopass
+end
-@example
-(gdbslet)
-@end example
+define hook-run
+handle SIGALRM pass
+end
-@menu
-* Sparclet File:: Setting the file to debug
-* Sparclet Connection:: Connecting to Sparclet
-* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
-@end menu
+define hook-continue
+handle SIGLARM pass
+end
+@end smallexample
-@node Sparclet File
-@subsubsection Setting file to debug
+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:
-The @value{GDBN} command @code{file} lets you choose with program to debug.
+@smallexample
+define hook-echo
+echo <<<---
+end
-@example
-(gdbslet) file prog
-@end example
+define hookpost-echo
+echo --->>>\n
+end
-@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:
+(@value{GDBP}) echo Hello World
+<<<---Hello World--->>>
+(@value{GDBP})
-@example
-prog: No such file or directory.
-@end example
+@end smallexample
-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 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 Sparclet Connection
-@subsubsection Connecting to Sparclet
+If you try to define a hook which does not match any known command, you
+get a warning from the @code{define} command.
-The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
-To connect to a target on serial port ``@code{ttya}'', type:
+@node Command Files
+@section Command files
-@example
-(gdbslet) target sparclet /dev/ttya
-Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
-@end example
+@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.
-@need 750
-@value{GDBN} displays messages like these:
+@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:
-@example
-Connected to ttya.
-@end example
+@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.}.
-@node Sparclet Download
-@subsubsection Sparclet download
+@item
+Processes command line options and operands.
-@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:
+@item
+Reads the init file (if any) in the current working directory.
-@example
-(gdbslet) load prog 0x12010000
-Loading section .text, size 0xdb0 vma 0x12010000
-@end example
+@item
+Reads command files specified by the @samp{-x} option.
+@end enumerate
-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.
+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}).
-@node Sparclet Execution
-@subsubsection Running and debugging
+@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 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.
+@cindex @file{.vxgdbinit}
+@itemize @bullet
+@item
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-@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
+@cindex @file{.os68gdbinit}
+@item
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+
+@cindex @file{.esgdbinit}
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
+@end itemize
-@node Sparclite
-@subsection Fujitsu Sparclite
+You can also request the execution of a command file with the
+@code{source} command:
@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 source
+@item source @var{filename}
+Execute the command file @var{filename}.
@end table
-@node ST2000
-@subsection Tandem ST2000
+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.
-@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
-STDBUG protocol.
+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.
-To connect your ST2000 to the host system, see the manufacturer's
-manual. Once the ST2000 is physically attached, you can run:
+@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.
-@example
-target st2000 @var{dev} @var{speed}
-@end example
+@smallexample
+gdb < cmds > log 2>&1
+@end smallexample
-@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}}.
+(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 @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.
+@node Output
+@section Commands for controlled output
-@cindex ST2000 auxiliary commands
-These auxiliary @value{GDBN} commands are available to help you with the ST2000
-environment:
+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
-@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 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 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
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines. For example,
-@node Z8000
-@subsection Zilog Z8000
+@smallexample
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end smallexample
-@cindex Z8000
-@cindex simulator, Z8000
-@cindex Zilog Z8000 simulator
+produces the same output as
-When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
-a Z8000 simulator.
+@smallexample
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end smallexample
-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.
+@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
-@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
+@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.
-@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.
+@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.
-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
+printf (@var{string}, @var{expressions}@dots{});
+@end smallexample
-@table @code
+For example, you can print two values in hex like this:
-@item cycles
-Counts clock-ticks in the simulator.
+@smallexample
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@end smallexample
-@item insts
-Counts instructions run in the simulator.
+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
-@item time
-Execution time in 60ths of a second.
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
-@end table
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Commands:: TUI specific commands
+* TUI Configuration:: TUI configuration variables
+@end menu
-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 @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 Architectures
-@section Architectures
+@node TUI Overview
+@section TUI overview
-This section describes characteristics of architectures that affect
-all uses of @value{GDBN} with the architecture, both native and cross.
+The TUI has two display modes that can be switched while
+@value{GDBN} runs:
-@menu
-* A29K::
-* Alpha::
-* MIPS::
-@end menu
+@itemize @bullet
+@item
+A curses (or TUI) mode in which it displays several text
+windows on the terminal.
-@node A29K
-@subsection A29K
+@item
+A standard mode which corresponds to the @value{GDBN} configured without
+the TUI.
+@end itemize
-@table @code
+In the TUI mode, @value{GDBN} can display several text window
+on the terminal:
-@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.
+@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.
-@kindex show rstack_high_address
-@item show rstack_high_address
-Display the current limit of the register stack, on AMD 29000 family
-processors.
+@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.
+
+@item assembly
+The assembly window shows the disassembly output of the program.
+
+@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.
@end table
-@node Alpha
-@subsection Alpha
+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:
-See the following section.
+@itemize @bullet
+@item
+source
-@node MIPS
-@subsection MIPS
+@item
+assembly
-@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.
+@item
+source and assembly
-@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:
+@item
+source and registers
-@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
+assembly and registers
-@item show heuristic-fence-post
-Display the current limit.
-@end table
+@end itemize
-@noindent
-These commands are available @emph{only} when @value{GDBN} is configured
-for debugging programs on Alpha or MIPS processors.
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
+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.
-@node Controlling GDB
-@chapter Controlling @value{GDBN}
+@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.
-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.
+@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.
-@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
+Think of this key binding as the Emacs @kbd{C-x 1} binding.
+
+@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.
+
+Think of it as the Emacs @kbd{C-x 2} binding.
-@node Prompt
-@section Prompt
+@end table
-@cindex prompt
+The following key bindings are handled only by the TUI mode:
-@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.
+@table @key
+@kindex PgUp
+@item PgUp
+Scroll the active window one page up.
-@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.
+@kindex PgDn
+@item PgDn
+Scroll the active window one page down.
-@table @code
-@kindex set prompt
-@item set prompt @var{newprompt}
-Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
+@kindex Up
+@item Up
+Scroll the active window one line up.
+
+@kindex Down
+@item Down
+Scroll the active window one line down.
+
+@kindex Left
+@item Left
+Scroll the active window one column left.
+
+@kindex Right
+@item Right
+Scroll the active window one column right.
+
+@kindex C-L
+@item C-L
+Refresh the screen.
-@kindex show prompt
-@item show prompt
-Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
-@node Editing
-@section Command editing
-@cindex readline
-@cindex command line editing
+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}.
-@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 TUI Commands
+@section TUI specific commands
+@cindex TUI commands
-You may control the behavior of command line editing in @value{GDBN} with the
-command @code{set}.
+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
-@kindex set editing
-@cindex editing
-@item set editing
-@itemx set editing on
-Enable command line editing (enabled by default).
+@item layout next
+@kindex layout next
+Display the next layout.
-@item set editing off
-Disable command line editing.
+@item layout prev
+@kindex layout prev
+Display the previous layout.
-@kindex show editing
-@item show editing
-Show whether command line editing is enabled.
-@end table
+@item layout src
+@kindex layout src
+Display the source window only.
-@node History
-@section Command history
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
-@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 layout split
+@kindex layout split
+Display the source and assembly window.
-@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.
+@item layout regs
+@kindex layout regs
+Display the register window together with the source or assembly window.
-@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.
+@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.
-@item set history save off
-Stop recording command history in a file.
+@item refresh
+@kindex refresh
+Refresh the screen. This is similar to using @key{C-L} key.
-@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
+@item update
+@kindex update
+Update the source window and the current execution point.
-@cindex history expansion
-History expansion assigns special meaning to the character @kbd{!}.
-@ifset have-readline-appendices
-@xref{Event Designators}.
-@end ifset
+@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.
-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.
+@end table
-The commands to control history expansion are:
+@node TUI Configuration
+@section TUI configuration variables
+@cindex TUI configuration variables
+
+The TUI has several configuration variables that control the
+appearance of windows on the terminal.
@table @code
-@kindex set history expansion
-@item set history expansion on
-@itemx set history expansion
-Enable history expansion. History expansion is off by default.
+@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.
-@item set history expansion off
-Disable history expansion.
+@item ascii
+Use ascii characters + - and | to draw the border.
-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
+@item acs
+Use the Alternate Character Set to draw the border. The border is
+drawn using character line graphics if the terminal supports them.
-@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
+@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}.
+
+@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
-@kindex shows
-@item show commands
-Display the last ten commands in the command history.
+@item normal
+Use normal attributes to display the border.
-@item show commands @var{n}
-Print ten commands centered on command number @var{n}.
+@item standout
+Use standout mode.
-@item show commands +
-Print ten commands just after the commands last printed.
-@end table
+@item reverse
+Use reverse video mode.
-@node Screen Size
-@section Screen size
-@cindex size of screen
-@cindex pauses in output
+@item half
+Use half bright mode.
-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.
+@item half-standout
+Use half bright and standout mode.
-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:
+@item bold
+Use extra bright or bold mode.
-@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 bold-standout
+Use extra bright or bold and standout mode.
-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.
+@end table
-Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
-from wrapping its output.
@end table
-@node Numbers
-@section Numbers
-@cindex number representation
-@cindex entering numbers
+@node Emacs
+@chapter Using @value{GDBN} under @sc{gnu} Emacs
-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.
+@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}.
-@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
+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.)
-@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
+Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
+things:
+
+@itemize @bullet
+@item
+All ``terminal'' input and output goes through the Emacs buffer.
+@end itemize
+
+This applies both to @value{GDBN} commands and their output, and to the input
+and output done by the program you are debugging.
+
+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.
+
+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
+@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.
+
+Explicit @value{GDBN} @code{list} or search commands still produce output as
+usual, but you probably have no reason to use them from Emacs.
+
+@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.
+
+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
+
+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,
+
+@smallexample
+(setq gdb-command-name "mygdb")
@end smallexample
@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+(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.
-@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.
+In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
+addition to the standard Shell mode commands:
-@kindex show input-radix
-@item show input-radix
-Display the current default base for numeric input.
+@table @kbd
+@item C-h m
+Describe the features of Emacs' @value{GDBN} Mode.
-@kindex show output-radix
-@item show output-radix
-Display the current default base for numeric display.
-@end table
+@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.
-@node Messages/Warnings
-@section Optional warnings and messages
+@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.
-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 M-i
+Execute one instruction, like the @value{GDBN} @code{stepi} command; update
+display window accordingly.
-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 M-x gdb-nexti
+Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
+display window accordingly.
-@table @code
-@kindex set verbose
-@item set verbose on
-Enables @value{GDBN} output of certain informational messages.
+@item C-c C-f
+Execute until exit from the selected stack frame, like the @value{GDBN}
+@code{finish} command.
-@item set verbose off
-Disables @value{GDBN} output of certain informational messages.
+@item M-c
+Continue execution of your program, like the @value{GDBN} @code{continue}
+command.
-@kindex show verbose
-@item show verbose
-Displays whether @code{set verbose} is on or off.
-@end table
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
-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 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.
-@table @code
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
-@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 M-d
+Go down the number of frames indicated by the numeric argument, like the
+@value{GDBN} @code{down} command.
-@kindex show complaints
-@item show complaints
-Displays how many symbol complaints @value{GDBN} is permitted to produce.
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
+
+@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 &}.
+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
-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:
+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.
-@example
-(@value{GDBP}) run
-The program being debugged has been started already.
-Start it from the beginning? (y or n)
-@end example
+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.
-If you are willing to unflinchingly face the consequences of your own
-commands, you can disable this ``feature'':
+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.
-@table @code
+@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
-@kindex set confirm
-@cindex flinching
-@cindex confirmation
-@cindex stupid questions
-@item set confirm off
-Disables confirmation requests.
+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
-@item set confirm on
-Enables confirmation requests (the default).
+@include annotate.texi
+@include gdbmi.texinfo
-@kindex show confirm
-@item show confirm
-Displays state of confirmation requests.
+@node GDB Bugs
+@chapter Reporting Bugs in @value{GDBN}
+@cindex bugs in @value{GDBN}
+@cindex reporting bugs in @value{GDBN}
-@end table
+Your bug reports play an essential role in making @value{GDBN} reliable.
-@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
+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
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+@end menu
+
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@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.
+
+@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.)
-@node Sequences
-@chapter Canned Sequences of Commands
+@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''.
-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.
+@item
+If you are an experienced user of debugging tools, your suggestions
+for improvement of @value{GDBN} are welcome in any case.
+@end itemize
-@menu
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
-@end menu
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex @value{GDBN} bugs, reporting
-@node Define
-@section User-defined commands
+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.
-@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:
+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...
-@smallexample
-define adder
- print $arg0 + $arg1 + $arg2
-@end smallexample
+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.
-@noindent
-To execute the command use:
+@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}.
-@smallexample
-adder 1 2 3
-@end smallexample
+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.
-@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.
+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!
-@table @code
+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.
-@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.
+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.
-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}.
+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.
-@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}.
+To enable us to fix the bug, you should include all these things:
-@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.
+@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}.
-@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.
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @value{GDBN}.
-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
+The type of machine you are using, and the operating system name and
+version number.
-@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
+What compiler (and its version) was used to compile @value{GDBN}---e.g.
+``@value{GCC}--2.8.1''.
-@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
+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.
-@end table
+@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.
-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.
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
-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.
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.
-@node Hooks
-@section User-defined command hooks
-@cindex command hooks
-@cindex hooks, for commands
-@cindex hooks, pre-command
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
-@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.
+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.
-@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.
+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.
+
+@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 line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
+
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+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.
+
+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.
+
+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.
+
+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.
+
+@item
+A patch for the bug.
+
+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.
+
+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.
+
+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.
+
+@item
+A guess about what the bug is or what it depends on.
-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.
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
-@c It would be nice if hookpost could be passed a parameter indicating
-@c if the command it hooks executed properly or not. FIXME!
+@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
-@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 Formatting Documentation
+@appendix Formatting Documentation
-@example
-define hook-stop
-handle SIGALRM nopass
-end
+@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}.
-define hook-run
-handle SIGALRM pass
-end
+The release also includes the source for the reference card. You
+can format it, using @TeX{}, by typing:
-define hook-continue
-handle SIGLARM pass
-end
-@end example
+@smallexample
+make refcard.dvi
+@end smallexample
-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:
+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.
-@example
-define hook-echo
-echo <<<---
-end
+@cindex documentation
-define hookpost-echo
-echo --->>>\n
-end
+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.
-(@value{GDBP}) echo Hello World
-<<<---Hello World--->>>
-(@value{GDBP})
+@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.
-@end example
+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}.
-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).
+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:
-If you try to define a hook which does not match any known command, you
-get a warning from the @code{define} command.
+@smallexample
+cd gdb
+make gdb.info
+@end smallexample
-@node Command Files
-@section Command files
+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.
-@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.
+@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.
-@cindex init file
-@cindex @file{.gdbinit}
-@cindex @file{gdb.ini}
-When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}. These are files named @file{.gdbinit} on Unix and
-@file{gdb.ini} on DOS/Windows. During startup, @value{GDBN} does the
-following:
+@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.
-@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.}.
+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
-Processes command line options and operands.
+@smallexample
+make gdb.dvi
+@end smallexample
-@item
-Reads the init file (if any) in the current working directory.
+Then give @file{gdb.dvi} to your @sc{dvi} printing program.
-@item
-Reads command files specified by the @samp{-x} option.
-@end enumerate
+@node Installing GDB
+@appendix Installing @value{GDBN}
+@cindex configuring @value{GDBN}
+@cindex installation
-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}).
+@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
-@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:
+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}.
-@cindex @file{.vxgdbinit}
-@itemize @bullet
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+For example, the @value{GDBN} version @value{GDBVN} distribution is in the
+@file{gdb-@value{GDBVN}} directory. That directory contains:
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+@table @code
+@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
+script for configuring @value{GDBN} and all its supporting libraries
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-@end itemize
+@item gdb-@value{GDBVN}/gdb
+the source specific to @value{GDBN} itself
-You can also request the execution of a command file with the
-@code{source} command:
+@item gdb-@value{GDBVN}/bfd
+source for the Binary File Descriptor library
-@table @code
-@kindex source
-@item source @var{filename}
-Execute the command file @var{filename}.
-@end table
+@item gdb-@value{GDBVN}/include
+@sc{gnu} include files
-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 gdb-@value{GDBVN}/libiberty
+source for the @samp{-liberty} free software library
-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 gdb-@value{GDBVN}/opcodes
+source for the library of opcode tables and disassemblers
-@node Output
-@section Commands for controlled output
+@item gdb-@value{GDBVN}/readline
+source for the @sc{gnu} command-line interface
-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.
+@item gdb-@value{GDBVN}/glob
+source for the @sc{gnu} filename pattern-matching subroutine
-@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 gdb-@value{GDBVN}/mmalloc
+source for the @sc{gnu} memory-mapped malloc package
+@end table
-A backslash at the end of @var{text} can be used, as in C, to continue
-the command onto subsequent lines. For example,
+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.
-@example
-echo This is some text\n\
-which is continued\n\
-onto several lines.\n
-@end example
+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.
+
+For example:
+
+@smallexample
+cd gdb-@value{GDBVN}
+./configure @var{host}
+make
+@end smallexample
-produces the same output as
+@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.)
-@example
-echo This is some text\n
-echo which is continued\n
-echo onto several lines.\n
-@end example
+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.
-@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.
+@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 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.
+@smallexample
+sh configure @var{host}
+@end smallexample
-@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.
+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).
-@example
-printf (@var{string}, @var{expressions}@dots{});
-@end example
+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.
-For example, you can print two values in hex like this:
+For example, with version @value{GDBVN}, type the following to configure only
+the @code{bfd} subdirectory:
@smallexample
-printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@group
+cd gdb-@value{GDBVN}/bfd
+../configure @var{host}
+@end group
@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
+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.
-@node Emacs
-@chapter Using @value{GDBN} under @sc{gnu} Emacs
+@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
-@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}.
+@node Separate Objdir
+@section Compiling @value{GDBN} in another directory
-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 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.
-Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
-things:
+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.)
-@itemize @bullet
-@item
-All ``terminal'' input and output goes through the Emacs buffer.
-@end itemize
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+separate directory for a Sun 4 like this:
-This applies both to @value{GDBN} commands and their output, and to the input
-and output done by the program you are debugging.
+@smallexample
+@group
+cd gdb-@value{GDBVN}
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-@value{GDBVN}/configure sun4
+make
+@end group
+@end smallexample
-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.
+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}.
-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.
+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}.
-@itemize @bullet
-@item
-@value{GDBN} displays source code through Emacs.
-@end itemize
+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).
-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.
+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.
-Explicit @value{GDBN} @code{list} or search commands still produce output as
-usual, but you probably have no reason to use them from Emacs.
+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.
-@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.
+@node Config Names
+@section Specifying names for hosts and targets
-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 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:
-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,
+@smallexample
+@var{architecture}-@var{vendor}-@var{os}
+@end smallexample
-@example
-(setq gdb-command-name "mygdb")
-@end example
+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}.
-@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.
+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:
-In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
-addition to the standard Shell mode commands:
+@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
-@table @kbd
-@item C-h m
-Describe the features of Emacs' @value{GDBN} Mode.
+@noindent
+@code{config.sub} is also distributed in the @value{GDBN} source
+directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-@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.
+@node Configure Options
+@section @code{configure} options
-@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.
+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}.
-@item M-i
-Execute one instruction, like the @value{GDBN} @code{stepi} command; update
-display window accordingly.
+@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
-@item M-x gdb-nexti
-Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
-display window accordingly.
+@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{--}.
-@item C-c C-f
-Execute until exit from the selected stack frame, like the @value{GDBN}
-@code{finish} command.
+@table @code
+@item --help
+Display a quick summary of how to invoke @code{configure}.
-@item M-c
-Continue execution of your program, like the @value{GDBN} @code{continue}
-command.
+@item --prefix=@var{dir}
+Configure the source to install programs and files under directory
+@file{@var{dir}}.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
+@item --exec-prefix=@var{dir}
+Configure the source to install programs under directory
+@file{@var{dir}}.
-@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.
+@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}.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
+@item --norecursion
+Configure only the directory level where @code{configure} is executed; do not
+propagate configuration to subdirectories.
-@item M-d
-Go down the number of frames indicated by the numeric argument, like the
-@value{GDBN} @code{down} command.
+@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.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
+There is no convenient way to generate a list of all available targets.
-@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 &}.
+@item @var{host} @dots{}
+Configure @value{GDBN} to run on the specified @var{host}.
-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.
+There is no convenient way to generate a list of all available hosts.
@end table
-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.
+There are many other options available as well, but they are generally
+needed for special purposes only.
-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.
+@node Maintenance Commands
+@appendix Maintenance Commands
+@cindex maintenance commands
+@cindex internal commands
-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.
+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.
-@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
+@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:
-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
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
-@include annotate.texi
-@include gdbmi.texinfo
+@item watchpoint
+Normal, explicitly set watchpoint.
-@node GDB Bugs
-@chapter Reporting Bugs in @value{GDBN}
-@cindex bugs in @value{GDBN}
-@cindex reporting bugs in @value{GDBN}
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
-Your bug reports play an essential role in making @value{GDBN} reliable.
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
-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}.
+@item until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
-In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
-@menu
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-@end menu
+@item shlib events
+Shared library events.
-@node Bug Criteria
-@section Have you found a bug?
-@cindex bug criteria
+@end table
-If you are not sure whether you have found a bug, here are some guidelines:
+@end table
-@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.
-@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.)
+@node Remote Protocol
+@appendix @value{GDBN} Remote Serial Protocol
-@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''.
+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
-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 examples below, @samp{<-} and @samp{->} are used to indicate
+transmitted and received data respectfully.
-@node Bug Reporting
-@section How to report bugs
-@cindex bug reports
-@cindex @value{GDBN} bugs, reporting
+@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}:
-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.
+@smallexample
+@code{$}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
+@noindent
-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...
+@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).
+
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
-In any event, we also recommend that you send bug reports for
-@value{GDBN} to this addresses:
+@smallexample
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end smallexample
-@example
-bug-gdb@@gnu.org
-@end example
+@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}.
-@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}.
+@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):
-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.
+@smallexample
+<- @code{$}@var{packet-data}@code{#}@var{checksum}
+-> @code{+}
+@end smallexample
+@noindent
-As a last resort, send bug reports on paper to:
+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).
-@example
-@sc{gnu} Debugger Bugs
-Free Software Foundation Inc.
-59 Temple Place - Suite 330
-Boston, MA 02111-1307
-USA
-@end example
+@var{packet-data} consists of a sequence of characters with the
+exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
+exceptions).
-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!
+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.
-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.
+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}).
+
+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.
-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.
+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.
-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.
+So:
+@smallexample
+"@code{0* }"
+@end smallexample
+@noindent
+means the same as "0000".
-To enable us to fix the bug, you should include all these things:
+The error response returned for some packets includes a two character
+error number. That number is not well defined.
-@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}.
+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.
-Without this, we will not know whether there is any point in looking for
-the bug in the current version of @value{GDBN}.
+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
-The type of machine you are using, and the operating system name and
-version number.
+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
+@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
-What compiler (and its version) was used to compile @value{GDBN}---e.g.
-``@value{GCC}--2.8.1''.
+@tab reply @samp{OK}
+@tab
+The remote target both supports and has enabled extended mode.
+@item last signal
+@tab @code{?}
+@tab
+Indicate the reason the target halted. The reply is the same as for step
+and continue.
@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.
+@tab reply
+@tab see below
-@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.
-If we were to try to guess the arguments, we would probably guess wrong
-and then we might not encounter the bug.
+@item reserved
+@tab @code{a}
+@tab Reserved for future use
+@item set program arguments @strong{(reserved)}
+@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
+@tab
@item
-A complete input script, and all necessary source files, that will
-reproduce the bug.
-
+@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
-A description of what behavior you observe that you believe is
-incorrect. For example, ``It gets a fatal signal.''
+@tab reply @code{OK}
+@item
+@tab reply @code{E}@var{NN}
-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.
+@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.}
-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.
+@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.}
+@item continue
+@tab @code{c}@var{addr}
+@tab
+@var{addr} is address to resume. If @var{addr} is omitted, resume at
+current address.
@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 line numbers in our development sources will not match those in your
-sources. Your line numbers would convey no useful information to us.
+@tab reply
+@tab see below
-@end itemize
+@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
-Here are some things that are not necessary:
+@item toggle debug @strong{(deprecated)}
+@tab @code{d}
+@tab
+toggle debug flag.
-@itemize @bullet
+@item detach
+@tab @code{D}
+@tab
+Detach @value{GDBN} from the remote system. Sent to the remote target before
+@value{GDBN} disconnects.
@item
-A description of the envelope of the bug.
+@tab reply @emph{no response}
+@tab
+@value{GDBN} does not check for any response after sending this packet.
-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.
+@item reserved
+@tab @code{e}
+@tab Reserved for future use
-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.
+@item reserved
+@tab @code{E}
+@tab Reserved for future use
-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.
+@item reserved
+@tab @code{f}
+@tab Reserved for future use
-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.
+@item reserved
+@tab @code{F}
+@tab Reserved for future use
+@item read registers
+@tab @code{g}
+@tab Read general registers.
@item
-A patch for the bug.
-
-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.
-
-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.
-
-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.
-
+@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
-A guess about what the bug is or what it depends on.
-
-Such guesses are usually wrong. Even we cannot guess right about such
-things without first using the debugger to find the facts.
-@end itemize
-
-@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
+@tab @code{E}@var{NN}
+@tab for an error.
+@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
-@node Formatting Documentation
-@appendix Formatting Documentation
+@item reserved
+@tab @code{h}
+@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 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
-The release also includes the source for the reference card. You
-can format it, using @TeX{}, by typing:
+@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.
-@example
-make refcard.dvi
-@end example
+@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.
-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 signal then cycle step @strong{(reserved)}
+@tab @code{I}
+@tab
+See @samp{i} and @samp{S} for likely syntax and semantics.
-@cindex documentation
+@item reserved
+@tab @code{j}
+@tab Reserved for future use
-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 reserved
+@tab @code{J}
+@tab Reserved for future use
-@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 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?)}.
-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{l}
+@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{L}
+@tab Reserved for future use
-@example
-cd gdb
-make gdb.info
-@end example
+@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
-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 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).
-@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 reserved
+@tab @code{n}
+@tab Reserved for future use
-@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 reserved
+@tab @code{N}
+@tab Reserved for future use
-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{o}
+@tab Reserved for future use
-@example
-make gdb.dvi
-@end example
+@item reserved
+@tab @code{O}
+@tab Reserved for future use
-Then give @file{gdb.dvi} to your @sc{dvi} printing program.
+@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.
-@node Installing GDB
-@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
-@cindex installation
+@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
-@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 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}.
-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 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.
-For example, the @value{GDBN} version @value{GDBVN} distribution is in the
-@file{gdb-@value{GDBVN}} directory. That directory contains:
+@item reset @strong{(deprecated)}
+@tab @code{r}
+@tab
+Reset the entire system.
-@table @code
-@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
-script for configuring @value{GDBN} and all its supporting libraries
+@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.
-@item gdb-@value{GDBVN}/gdb
-the source specific to @value{GDBN} itself
+@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
-@item gdb-@value{GDBVN}/bfd
-source for the Binary File Descriptor library
+@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
-@item gdb-@value{GDBVN}/include
-@sc{gnu} include files
+@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.
-@item gdb-@value{GDBVN}/libiberty
-source for the @samp{-liberty} free software library
+@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
-@item gdb-@value{GDBVN}/opcodes
-source for the library of opcode tables and disassemblers
+@item reserved
+@tab @code{u}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/readline
-source for the @sc{gnu} command-line interface
+@item reserved
+@tab @code{U}
+@tab Reserved for future use
-@item gdb-@value{GDBVN}/glob
-source for the @sc{gnu} filename pattern-matching subroutine
+@item reserved
+@tab @code{v}
+@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{V}
+@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 reserved
+@tab @code{w}
+@tab Reserved for future use
-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 reserved
+@tab @code{W}
+@tab Reserved for future use
-For example:
+@item reserved
+@tab @code{x}
+@tab Reserved for future use
-@example
-cd gdb-@value{GDBVN}
-./configure @var{host}
-make
-@end example
+@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
-@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 reserved
+@tab @code{y}
+@tab Reserved for future use
-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 reserved
+@tab @code{Y}
+@tab Reserved for future use
-@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 remove break or watchpoint @strong{(draft)}
+@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
+@tab
+See @samp{Z}.
-@example
-sh configure @var{host}
-@end example
+@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.
-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 reserved
+@tab <other>
+@tab Reserved for future use
-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.
+@end multitable
-For example, with version @value{GDBVN}, type the following to configure only
-the @code{bfd} subdirectory:
+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.
-@example
-@group
-cd gdb-@value{GDBVN}/bfd
-../configure @var{host}
-@end group
-@end example
+@multitable @columnfractions .4 .6
-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 @code{S}@var{AA}
+@tab @var{AA} is the signal number
-@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 @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.
-@node Separate Objdir
-@section Compiling @value{GDBN} in another directory
+@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.
-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 @code{X}@var{AA}
+@tab
+The process terminated with signal @var{AA}.
-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 @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.}
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
-separate directory for a Sun 4 like this:
+@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.
-@example
-@group
-cd gdb-@value{GDBVN}
-mkdir ../gdb-sun4
-cd ../gdb-sun4
-../gdb-@value{GDBVN}/configure sun4
-make
-@end group
-@end example
+@end multitable
-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}.
+The following set and query packets have already been defined.
-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}.
+@multitable @columnfractions .2 .2 .6
-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 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.
-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 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'}).
-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.
+@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.
-@node Config Names
-@section Specifying names for hosts and targets
+@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()}.
-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:
+@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.
-@example
-@var{architecture}-@var{vendor}-@var{os}
-@end example
+@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}
-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 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()}.
-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 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.
-@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
+@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
-@code{config.sub} is also distributed in the @value{GDBN} source
-directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
-
-@node Configure Options
-@section @code{configure} options
+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.
-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}.
+@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.
-@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
+@end multitable
-@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{--}.
+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 --help
-Display a quick summary of how to invoke @code{configure}.
+@multitable @columnfractions .5 .5
-@item --prefix=@var{dir}
-Configure the source to install programs and files under directory
-@file{@var{dir}}.
+@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 --exec-prefix=@var{dir}
-Configure the source to install programs under directory
-@file{@var{dir}}.
+@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}.
-@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}.
+@end multitable
-@item --norecursion
-Configure only the directory level where @code{configure} is executed; do not
-propagate configuration to subdirectories.
+Example sequence of a target being re-started. Notice how the restart
+does not get any direct output:
-@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.
+@smallexample
+<- @code{R00}
+-> @code{+}
+@emph{target restarts}
+<- @code{?}
+-> @code{+}
+-> @code{T001:1234123412341234}
+<- @code{+}
+@end smallexample
-There is no convenient way to generate a list of all available targets.
+Example sequence of a target being stepped by a single instruction:
-@item @var{host} @dots{}
-Configure @value{GDBN} to run on the specified @var{host}.
+@smallexample
+<- @code{G1445...}
+-> @code{+}
+<- @code{s}
+-> @code{+}
+@emph{time passes}
+-> @code{T001:1234123412341234}
+<- @code{+}
+<- @code{g}
+-> @code{+}
+-> @code{1455...}
+<- @code{+}
+@end smallexample
-There is no convenient way to generate a list of all available hosts.
-@end table
+@include gpl.texi
-There are many other options available as well, but they are generally
-needed for special purposes only.
+@include fdl.texi
@node Index
@unnumbered Index
% 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