@c -*- Texinfo -*-
@c Copyright (c) 1990 1991 1992 1993 Free Software Foundation, Inc.
@c This file is part of the source for the GDB manual.
-@c This text diverted to "Remote Debugging" section in general case;
-@c however, if we're doing a manual specifically for one of these, it
-@c belongs up front (in "Getting In and Out" chapter).
-@ifset REMOTESTUB
@node Remote Serial
@subsection The @value{GDBN} remote serial protocol
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
+program, you need:
@enumerate
@item
implement the @value{GDBN} remote serial protocol. The file containing these
subroutines is called a @dfn{debugging stub}.
-@ifset GDBSERVER
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 ifset
@end table
The debugging stub is specific to the architecture of the remote
These working remote stubs are distributed with @value{GDBN}:
@table @code
-@item sparc-stub.c
-@kindex sparc-stub.c
-For @sc{sparc} architectures.
+
+@item i386-stub.c
+@kindex i386-stub.c
+@cindex Intel
+@cindex i386
+For Intel 386 and compatible architectures.
@item m68k-stub.c
@kindex m68k-stub.c
@cindex Motorola 680x0
-@cindex 680x0
+@cindex m680x0
For Motorola 680x0 architectures.
-@item i386-stub.c
-@kindex i386-stub.c
-@cindex Intel
-@cindex 386
-For Intel 386 and compatible architectures.
+@item sh-stub.c
+@kindex sh-stub.c
+@cindex Hitachi
+@cindex SH
+For Hitachi SH architectures.
+
+@item sparc-stub.c
+@kindex sparc-stub.c
+@cindex Sparc
+For @sc{sparc} architectures.
+
+@item sparcl-stub.c
+@kindex sparcl-stub.c
+@cindex Fujitsu
+@cindex SparcLite
+For Fujitsu @sc{sparclite} architectures.
+
@end table
The @file{README} file in the @value{GDBN} distribution may list other
* Bootstrapping:: What you must do for the stub
* Debug Session:: Putting it all together
* Protocol:: Outline of the communication protocol
-@ifset GDBSERVER
* Server:: Using the `gdbserver' program
-@end ifset
+* NetWare:: Using the `gdbserve.nlm' program
@end menu
@node Stub Contents
breakpoint. Depending on the particular situation, this may be the only
way for @value{GDBN} to get control. For instance, if your target
machine has some sort of interrupt button, you won't need to call this;
-pressing the interrupt button will transfer control to
+pressing the interrupt button transfers control to
@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
simply receiving characters on the serial port may also trigger a trap;
again, in that situation, you don't need to call @code{breakpoint} from
your own program---simply running @samp{target remote} from the host
-@value{GDBN} session will get control.
+@value{GDBN} session gets control.
Call @code{breakpoint} if none of these is true, or if you simply want
to make certain your program stops at a predetermined point for the
@cindex remote stub, support routines
The debugging stubs that come with @value{GDBN} are set up for a particular
chip architecture, but they have no information about the rest of your
-debugging target machine. To allow the stub to work, you must supply
-these special low-level subroutines:
+debugging target machine.
+
+First of all you need to tell the stub how to communicate with the
+serial port.
@table @code
@item int getDebugChar()
Write this subroutine to write a single character to the serial port.
It may be identical to @code{putchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
+@end table
+@cindex control C, and remote debugging
+@cindex interrupting remote targets
+If you want @value{GDBN} to be able to stop your program while it is
+running, you need to use an interrupt-driven serial driver, and arrange
+for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
+character). That is the character which @value{GDBN} uses to tell the
+remote system to stop.
+
+Getting the debugging target to return the proper status to @value{GDBN}
+probably requires changes to the standard stub; one quick and dirty way
+is to just execute a breakpoint instruction (the ``dirty'' part is that
+@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
+
+Other routines you need to supply are:
+
+@table @code
@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
@kindex exceptionHandler
Write this function to install @var{exception_address} in the exception
might represent divide by zero, misaligned access, etc). When this
exception occurs, control should be transferred directly to
@var{exception_address}, and the processor state (stack, registers,
-etc.) should be just as it is when a processor exception occurs. So if
+and so on) should be just as it is when a processor exception occurs. So if
you want to use a jump instruction to reach @var{exception_address}, it
should be a simple jump, not a jump to subroutine.
For the 386, @var{exception_address} should be installed as an interrupt
gate so that interrupts are masked while the handler runs. The gate
should be at privilege level 0 (the most privileged level). The
-@sc{sparc} and 68k stubs are able to mask interrupts themself without
+@sc{sparc} and 68k stubs are able to mask interrupts themselves without
help from @code{exceptionHandler}.
@item void flush_i_cache()
@kindex flush_i_cache
-Write this subroutine to flush the instruction cache, if any, on your
-target machine. If there is no instruction cache, this subroutine may
-be a no-op.
+(sparc and sparclite only) Write this subroutine to flush the
+instruction cache, if any, on your target machine. If there is no
+instruction cache, this subroutine may be a no-op.
On target machines that have instruction caches, @value{GDBN} requires this
function to make certain that the state of your program is stable.
@end table
If you do not use the GNU C compiler, you may need other standard
-library subroutines as well; this will vary from one stub to another,
+library subroutines as well; this varies from one stub to another,
but in general the stubs are likely to use any of the common library
subroutines which @code{gcc} generates as inline code.
@item
For the 680x0 stub only, you need to provide a variable called
-@code{exceptionHook}. Normally you just use
+@code{exceptionHook}. Normally you just use:
@example
void (*exceptionHook)() = 0;
@item
Make sure you have a serial connection between your target machine and
-the @value{GDBN} host, and identify the serial port used for this on the host.
+the @value{GDBN} host, and identify the serial port on the host.
@item
@c The "remote" target now provides a `load' command, so we should
goes back to waiting.
@node Protocol
-@subsubsection Outline of the communication protocol
+@subsubsection Communication protocol
@cindex debugging stub, example
@cindex remote stub, example
Command packets are distinguished by their first character, which
identifies the kind of command.
-These are the commands currently supported:
+These are some of the commands currently supported (for a complete list of
+commands, look in @file{gdb/remote.c.}):
@table @code
@item g
@item M@var{addr},@var{count}:@dots{}
Write @var{count} bytes at location @var{addr}.
+@need 500
@item c
@itemx c@var{addr}
Resume execution at the current address (or at @var{addr} if supplied).
+@need 500
@item s
@itemx s@var{addr}
Step the target program for one instruction, from either the current
Report the most recent signal. To allow you to take advantage of the
@value{GDBN} signal handling commands, one of the functions of the debugging
stub is to report CPU traps as the corresponding POSIX signal values.
+
+@item T
+Allows the remote stub to send only the registers that @value{GDBN} needs
+to make a quick decision about single-stepping or conditional breakpoints.
+This eliminates the need to fetch the entire register set for each instruction
+being stepped through.
+
+@value{GDBN} now implements a write-through cache for registers and only
+re-reads the registers if the target has run.
@end table
@kindex set remotedebug
back and forth across the serial line to the remote machine. The
packet-debugging information is printed on the @value{GDBN} standard output
stream. @code{set remotedebug off} turns it off, and @code{show
-remotedebug} will show you its current state.
+remotedebug} shows you its current state.
-@ifset GDBSERVER
@node Server
@subsubsection Using the @code{gdbserver} program
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
-@var{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
+@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 @var{GDBN}, so you may be able to get
+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,
+@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{GDB};
+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:
@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
+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}:
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.@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.
-
-@item On the host,
-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
-@samp{--baud} option if the serial line is running at anything other than 9600 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 descriptof in the form @code{@var{host}:@var{PORT}}. For example:
+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.
+
+@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 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 via a TCP connection to port 2345 on host @file{the-target}.
+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
-@end ifset
-@end ifset
+@node NetWare
+@subsubsection 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 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 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 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
-@ifset I960
@node i960-Nindy Remote
@subsection @value{GDBN} with a remote i960 (Nindy)
a break is detected.
@end table
@c @end group
-@end ifset
-@ifset AMD29K
@node UDI29K Remote
-@subsection @value{GDBN} and the UDI protocol for AMD29K
+@subsection The UDI protocol for AMD29K
@cindex UDI
@cindex AMD29K via UDI
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
+use @value{GDBN} with the UDI-conformant a29k simulator program
@code{ISSTIP}, also available from AMD.
@table @code
@end table
@node EB29K Remote
-@subsection @value{GDBN} and the EBMON protocol for AMD29K
+@subsection The EBMON protocol for AMD29K
@cindex EB29K board
@cindex running 29K programs
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? ---pesch@cygnus.com, 25feb91
+@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
To give control of the PC to the Unix side of the serial line, type
the following at the DOS console:
@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... ---pesch@cygnus.com, 25feb91
+@c stdout redirected... ---doc@cygnus.com, 25feb91
@kindex EBMON
Using the @code{tip} or @code{cu} connection, change the DOS working
@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} will keep
+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
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} will @emph{not} download it over the
+from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
serial line.
@node gdb-EB29K
@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). ---pesch@cygnus.com, 25feb91
+@c single-minded about case of letters). ---doc@cygnus.com, 25feb91
@end example
@noindent
another window often helps to understand trouble with @code{EBMON}, or
unexpected events on the PC side of the connection.
-@end ifset
-
-@ifset ST2000
@node ST2000 Remote
@subsection @value{GDBN} with a Tandem ST2000
To connect your ST2000 to the host system, see the manufacturer's
-manual. Once the ST2000 is physically attached, you can run
+manual. Once the ST2000 is physically attached, you can run:
@example
target st2000 @var{dev} @var{speed}
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} will read debugging information
+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
@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 will get you back to the @value{GDBN} command prompt:
+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
-@end ifset
-@ifset VXWORKS
@node VxWorks Remote
@subsection @value{GDBN} and VxWorks
+
@cindex VxWorks
@value{GDBN} enables developers to spawn and debug tasks running on networked
installed with the name @code{vxgdb}, to distinguish it from a
@value{GDBN} for debugging programs on the host itself.)
+@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.
-The remote debugging interface (RDB) routines are installed and executed
-on the VxWorks target. These routines are included in the VxWorks library
-@file{rdb.a} and are incorporated into the system image when source-level
-debugging is enabled in the VxWorks configuration.
-
@kindex INCLUDE_RDB
-If you wish, you can define @code{INCLUDE_RDB} in the VxWorks
-configuration file @file{configAll.h} to include the RDB interface
-routines and spawn the source debugging task @code{tRdbTask} when
-VxWorks is booted. For more information on configuring and remaking
-VxWorks, see the manufacturer's manual.
+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}.
-Once you have included the RDB interface 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{gdb} (or
-@code{vxgdb}, depending on your installation).
+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{gdb} (or @code{vxgdb},
+depending on your installation).
@value{GDBN} comes up showing the prompt:
(vxgdb) target vxworks tt
@end example
+@need 750
@value{GDBN} displays messages like these:
@smallexample
Connected to tt.
@end smallexample
+@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
@example
-> cd "@var{vxpath}/vw/demo/rdb"
@end example
-
+v
Then, in @value{GDBN}, type:
@example
You can also use the @code{load} command to reload an object module
after editing and recompiling the corresponding source file. Note that
-this will cause @value{GDBN} to delete all currently-defined breakpoints,
+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 data structures that reference the target system's symbol
@noindent
where @var{task} is the VxWorks hexadecimal task ID. The task can be running
-or suspended when you attach to it. If running, it will be suspended at
+or suspended when you attach to it. Running tasks are suspended at
the time of attachment.
-@end ifset
-@ifset H8
+@node Sparclet Remote
+@subsection @value{GDBN} and Sparclet
+@cindex Sparclet
+
+@value{GDBN} enables developers to debug tasks running on
+Sparclet targets from a Unix host.
+@value{GDBN} uses code that runs on
+both the Unix host and on the Sparclet target. The program
+@code{gdb} is installed and executed on the Unix host.
+
+@table @code
+@item timeout @var{args}
+@kindex remotetimeout
+@value{GDBN} now 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 Compiling
+When compiling for debugging, include the options "-g" to get debug
+information and "-Ttext" to relocate the program to where you wish to
+load it on the target. You may also want to add the options "-n" or
+"-N" in order to reduce the size of the sections.
+
+@example
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end example
+
+You can use objdump to verify that the addresses are what you intended.
+
+@example
+sparclet-aout-objdump --headers --syms prog
+@end example
+
+@kindex Running
+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{gdb}
+(or @code{sparclet-aout-gdb}, depending on your installation).
+
+@value{GDBN} comes up showing the prompt:
+
+@example
+(gdbslet)
+@end example
+
+@menu
+* Sparclet File:: Setting the file to debug
+* Sparclet Connection:: Connecting to Sparclet
+* Sparclet Download:: Sparclet download
+* Sparclet Execution:: Running and debugging
+@end menu
+
+@node Sparclet File
+@subsubsection Setting file to debug
+
+The @value{GDBN} command @code{file} lets you choose with program to debug.
+
+@example
+(gdbslet) file prog
+@end example
+
+@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:
+
+@example
+prog: No such file or directory.
+@end example
+
+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.
+
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
+
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
+
+@example
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3
+@end example
+
+@need 750
+@value{GDBN} displays messages like these:
+
+@smallexample
+Connected to ttya.
+@end smallexample
+
+@node Sparclet Download
+@subsubsection Sparclet download
+
+@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 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:
+
+@example
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end example
+
+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.
+
+@node Sparclet Execution
+@subsubsection Running and debugging
+
+@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.
+
+@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
+
@node Hitachi Remote
-@subsection @value{GDBN} and Hitachi Microprocessors
+@subsection @value{GDBN} and Hitachi microprocessors
@value{GDBN} needs to know these things to talk to your
Hitachi SH, H8/300, or H8/500:
@enumerate
@item
that you want to use @samp{target hms}, the remote debugging interface
-for Hitachi microprocessors (this is the default when GDB is configured
-specifically for the Hitachi SH, H8/300, or H8/500);
+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 GDB is configured specifically for the Hitachi SH,
+H8/300, or H8/500.)
@item
what serial device connects your host to your Hitachi board (the first
-serial device available on your host is the default);
+serial device available on your host is the default).
-@ignore
-@c this is only for Unix hosts, not currently of interest.
@item
what speed to use over the serial device.
-@end ignore
@end enumerate
-@ifclear H8EXCLUSIVE
+@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 Hitachi Boards
+@subsubsection Connecting to Hitachi boards
+
@c only for Unix hosts
@kindex device
@cindex serial device, Hitachi micros
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,
-@end ifclear
@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.
-@ifset DOSHOST
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
@code{COM2}.
@example
-(eg-C:\H8300\TEST) mode com2:9600,n,8,1,p
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
Resident portion of MODE loaded
COM2: 9600, n, 8, 1, p
-(eg-C:\H8300\TEST) asynctsr 2
@end example
@quotation
to detect program completion.
@end itemize
-In either case, @value{GDBN} will see the effect of a @sc{reset} on the
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
development board as a ``normal exit'' of your program.
-@end ifset
-@end ifset
-@ifset MIPS
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
+
+@kindex target e7000
+You can use the E7000 in-circuit emulator to develop code for either the
+Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
+e7000} command to connect @value{GDBN} to your E7000:
+
+@table @code
+@item target e7000 @var{port} @var{speed}
+Use this form if your E7000 is connected to a serial port. The
+@var{port} argument identifies what serial port to use (for example,
+@samp{com2}). The third argument is the line speed in bits per second
+(for example, @samp{9600}).
+
+@item target e7000 @var{hostname}
+If your E7000 is installed as a host on a TCP/IP network, you can just
+specify its hostname; @value{GDBN} uses @code{telnet} to connect.
+@end table
+
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
+
+Some @value{GDBN} commands are available only on the H8/300 or the
+H8/500 configurations:
+
+@table @code
+@kindex set machine
+@kindex show machine
+@item set machine h8300
+@itemx set machine h8300h
+Condition @value{GDBN} for one of the two variants of the H8/300
+architecture with @samp{set machine}. You can use @samp{show machine}
+to check which variant is currently in effect.
+
+@kindex set memory @var{mod}
+@cindex memory models, H8/500
+@item set memory @var{mod}
+@itemx show memory
+Specify which H8/500 memory model (@var{mod}) you are using with
+@samp{set memory}; check which memory model is in effect with @samp{show
+memory}. The accepted values for @var{mod} are @code{small},
+@code{big}, @code{medium}, and @code{compact}.
+@end table
+
@node MIPS Remote
@subsection @value{GDBN} and remote MIPS boards
MIPS board attached to a serial line. This is available when
you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
+
+@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
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.
-You can also specify @var{port} as a TCP connection (for instance, to a
-serial line managed by a terminal concentrator), using the syntax
-@code{@var{hostname}:@var{portnumber}}.
+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}
+GDB is free software and @dots{}
+(gdb) target mips /dev/ttyb
+(gdb) load @var{prog}
+(gdb) run
+@end example
+
+@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}
+
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+
+@item target lsi @var{port}
+@kindex target lsi @var{port}
+
+@end table
+
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
+
+@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 CPO registers appropriate for the 3041 chip.
+Use the @code{show processor} command to see what MIPS processor @value{GDBN}
+is using. Use the @code{info reg} command to see what registers
+@value{GDBN} is using.
+
+@item set mipsfpu double
+@itemx set mipsfpu single
+@itemx set mipsfpu none
+@itemx show mipsfpu
+@kindex set mipsfpu
+@kindex show mipsfpu
+@cindex MIPS remote floating point
+@cindex floating point, MIPS remote
+If your target board does not support the MIPS floating point
+coprocessor, you should use the command @samp{set mipsfpu none} (if you
+need this, you may wish to put the command in your @value{GDBINIT}
+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}.
+
+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.
+
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
+
+@item set remotedebug @var{n}
+@itemx show remotedebug
+@kindex set remotedebug
+@kindex show remotedebug
@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 1 using
-@samp{set remotedebug 1} every packet will be displayed. If you set it
-to 2 every character will be displayed. You can check the current value
+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}.
+@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
retransmit-timeout}. (These commands are @emph{only} available when
@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
-@kindex set mipsfpu off
-@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 off} (you may
-wish to put this in your @value{GDBINIT} 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.
-@end ifset
-
-@ifset SIMS
+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
+
@node Simulator
@subsection Simulated CPU target
-@ifset GENERIC
@cindex simulator
@cindex simulator, Z8000
@cindex Z8000 simulator
@cindex Hitachi SH simulator
@cindex CPU simulator
For some configurations, @value{GDBN} includes a CPU simulator that you
-can use instead of a hardware CPU to debug your programs. Currently,
-a simulator is available when @value{GDBN} is configured to debug Zilog
-Z8000 or Hitachi microprocessor targets.
-@end ifset
+can use instead of a hardware CPU to debug your programs.
+Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300,
+H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
+W65, and Z8000.
-@ifclear GENERIC
-@ifset H8
-@cindex simulator, H8/300 or H8/500
-@cindex Hitachi H8/300 or H8/500 simulator
-@cindex simulator, Hitachi SH
-@cindex Hitachi SH simulator
-When configured for debugging Hitachi microprocessor targets,
-@value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH,
-H8/300, or H8/500).
-@end ifset
-
-@ifset Z8K
@cindex simulator, Z8000
@cindex Zilog Z8000 simulator
When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
a Z8000 simulator.
-@end ifset
-@end ifclear
-@ifset Z8K
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.
-@end ifset
@table @code
-@item target sim
+@item target sim @var{args}
@kindex sim
@kindex target sim
-Debug programs on a simulated CPU
-@ifset GENERIC
-(which CPU depends on the @value{GDBN} configuration)
-@end ifset
+Debug programs on a simulated CPU. If the simulator supports setup
+options, specify them via @var{args}.
@end table
@noindent
to run your program, and so on.
As well as making available all the usual machine registers (see
-@code{info reg}), this debugging target provides three additional items
+@code{info reg}), the Z8000 simulator provides three additional items
of information as specially named registers:
@table @code
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 will suspend only after at least 5000
+conditional breakpoint that suspends only after at least 5000
simulated clock ticks.
-@end ifset
+
+@c need to add much more detail about sims!
projects / deliverable / binutils-gdb.git / blobdiff