2203 lines
74 KiB
Plaintext
2203 lines
74 KiB
Plaintext
@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.
|
|
|
|
@node Remote Serial
|
|
@subsection The @value{GDBN} remote serial protocol
|
|
|
|
@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
|
|
You probably need 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
|
|
@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 m680x0
|
|
For Motorola 680x0 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
|
|
recently added stubs.
|
|
|
|
@menu
|
|
* 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
|
|
|
|
@cindex remote serial stub
|
|
The debugging stub for your architecture supplies these three
|
|
subroutines:
|
|
|
|
@table @code
|
|
@item set_debug_traps
|
|
@kindex set_debug_traps
|
|
@cindex remote serial stub, initialization
|
|
This routine arranges for @code{handle_exception} to run when your
|
|
program stops. You must call this subroutine explicitly near the
|
|
beginning of your program.
|
|
|
|
@item handle_exception
|
|
@kindex handle_exception
|
|
@cindex remote serial stub, main routine
|
|
This is the central workhorse, but your program never calls it
|
|
explicitly---the setup code arranges for @code{handle_exception} to
|
|
run when a trap is triggered.
|
|
|
|
@code{handle_exception} takes control when your program stops during
|
|
execution (for example, on a breakpoint), and mediates communications
|
|
with @value{GDBN} on the host machine. This is where the communications
|
|
protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
|
|
representative on the target machine; it begins by sending summary
|
|
information on the state of your program, then continues to execute,
|
|
retrieving and transmitting any information @value{GDBN} needs, until you
|
|
execute a @value{GDBN} command that makes your program resume; at that point,
|
|
@code{handle_exception} returns control to your own code on the target
|
|
machine.
|
|
|
|
@item breakpoint
|
|
@cindex @code{breakpoint} subroutine, remote
|
|
Use this auxiliary subroutine to make your program contain a
|
|
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 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 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
|
|
start of your debugging session.
|
|
@end table
|
|
|
|
@node Bootstrapping
|
|
@subsubsection 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
|
|
chip architecture, but they have no information about the rest of your
|
|
debugging target machine.
|
|
|
|
First of all you need to tell the stub how to communicate with the
|
|
serial port.
|
|
|
|
@table @code
|
|
@item int getDebugChar()
|
|
@kindex getDebugChar
|
|
Write this subroutine to read a single character from the serial port.
|
|
It may be identical to @code{getchar} for your target system; a
|
|
different name is used to allow you to distinguish the two if you wish.
|
|
|
|
@item void putDebugChar(int)
|
|
@kindex putDebugChar
|
|
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
|
|
handling tables. You need to do this because the stub does not have any
|
|
way of knowing what the exception handling tables on your target system
|
|
are like (for example, the processor's table might be in @sc{rom},
|
|
containing entries which point to a table in @sc{ram}).
|
|
@var{exception_number} is the exception number which should be changed;
|
|
its meaning is architecture-dependent (for example, different numbers
|
|
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,
|
|
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 themselves without
|
|
help from @code{exceptionHandler}.
|
|
|
|
@item void flush_i_cache()
|
|
@kindex flush_i_cache
|
|
(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
|
|
|
|
@noindent
|
|
You must also make sure this library routine is available:
|
|
|
|
@table @code
|
|
@item void *memset(void *, int, int)
|
|
@kindex memset
|
|
This is the standard library function @code{memset} that sets an area of
|
|
memory to a known value. If you have one of the free versions of
|
|
@code{libc.a}, @code{memset} can be found there; otherwise, you must
|
|
either obtain it from your hardware manufacturer, or write your own.
|
|
@end table
|
|
|
|
If you do not use the GNU C compiler, you may need other standard
|
|
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.
|
|
|
|
|
|
@node Debug Session
|
|
@subsubsection Putting it all together
|
|
|
|
@cindex remote serial debugging summary
|
|
In summary, when your program is ready to debug, you must follow these
|
|
steps.
|
|
|
|
@enumerate
|
|
@item
|
|
Make sure you have the supporting low-level routines
|
|
(@pxref{Bootstrapping,,What you must do for the stub}):
|
|
@display
|
|
@code{getDebugChar}, @code{putDebugChar},
|
|
@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
|
|
@end display
|
|
|
|
@item
|
|
Insert these lines near the top of your program:
|
|
|
|
@example
|
|
set_debug_traps();
|
|
breakpoint();
|
|
@end example
|
|
|
|
@item
|
|
For the 680x0 stub only, you need to provide a variable called
|
|
@code{exceptionHook}. Normally you just use:
|
|
|
|
@example
|
|
void (*exceptionHook)() = 0;
|
|
@end example
|
|
|
|
but if before calling @code{set_debug_traps}, you set it to point to a
|
|
function in your program, that function is called when
|
|
@code{@value{GDBN}} continues after stopping on a trap (for example, bus
|
|
error). The function indicated by @code{exceptionHook} is called with
|
|
one parameter: an @code{int} which is the exception number.
|
|
|
|
@item
|
|
Compile and link together: your program, the @value{GDBN} debugging stub for
|
|
your target architecture, and the supporting subroutines.
|
|
|
|
@item
|
|
Make sure you have a serial connection between your target machine and
|
|
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
|
|
@c document that. FIXME.
|
|
Download your program to your target machine (or get it there by
|
|
whatever means the manufacturer provides), and start it.
|
|
|
|
@item
|
|
To start remote debugging, run @value{GDBN} on the host machine, and specify
|
|
as an executable file the program that is running in the remote machine.
|
|
This tells @value{GDBN} how to find your program's symbols and the contents
|
|
of its pure text.
|
|
|
|
@cindex serial line, @code{target remote}
|
|
Then 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
|
|
to the target). For example, to use a serial line connected to the
|
|
device named @file{/dev/ttyb}:
|
|
|
|
@example
|
|
target remote /dev/ttyb
|
|
@end example
|
|
|
|
@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
|
|
terminal server named @code{manyfarms}:
|
|
|
|
@example
|
|
target remote manyfarms:2828
|
|
@end example
|
|
@end enumerate
|
|
|
|
Now you can use all the usual commands to examine and change data and to
|
|
step and continue the remote program.
|
|
|
|
To resume the remote program and stop debugging it, use the @code{detach}
|
|
command.
|
|
|
|
@cindex interrupting remote programs
|
|
@cindex remote programs, interrupting
|
|
Whenever @value{GDBN} is waiting for the remote program, if you type the
|
|
interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
|
|
program. This may or may not succeed, depending in part on the hardware
|
|
and the serial drivers the remote system uses. If you type the
|
|
interrupt character once again, @value{GDBN} displays this prompt:
|
|
|
|
@example
|
|
Interrupted while waiting for the program.
|
|
Give up (and stop debugging it)? (y or n)
|
|
@end example
|
|
|
|
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}.
|
|
|
|
In the examples below, @samp{<-} and @samp{->} are used to indicate
|
|
transmitted and received data respectfully.
|
|
|
|
@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{$}, this is followed by an optional two-digit
|
|
@var{sequence-id} and the character @samp{:}, the actual
|
|
@var{packet-data}, and the terminating character @samp{#} followed by a
|
|
two-digit @var{checksum}:
|
|
|
|
@example
|
|
@code{$}@var{packet-data}@code{#}@var{checksum}
|
|
@end example
|
|
@noindent
|
|
or, with the optional @var{sequence-id}:
|
|
@example
|
|
@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
|
|
@end example
|
|
|
|
@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{#} (that
|
|
consisting of both the optional @var{sequence-id}@code{:} and the actual
|
|
@var{packet-data}).
|
|
|
|
@cindex sequence-id, for @value{GDBN} remote
|
|
@noindent
|
|
The two-digit @var{sequence-id}, when present, is returned with the
|
|
acknowledgment. Beyond that its meaning is poorly defined.
|
|
@value{GDBN} is not known to output @var{sequence-id}s.
|
|
|
|
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):
|
|
|
|
@example
|
|
<- @code{$}@var{packet-data}@code{#}@var{checksum}
|
|
-> @code{+}
|
|
@end example
|
|
@noindent
|
|
If the received packet included a @var{sequence-id} than that is
|
|
appended to a positive acknowledgment:
|
|
|
|
@example
|
|
<- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
|
|
-> @code{+}@var{sequence-id}
|
|
@end example
|
|
|
|
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).
|
|
|
|
@var{packet-data} consists of a sequence of characters with the
|
|
exception of @samp{#} and @samp{$} (see @samp{X} packet for an
|
|
exception). @samp{:} can not appear as the third character in a packet.
|
|
Fields within the packet should be separated using @samp{,} and @samp{;}
|
|
(unfortunately some packets chose to use @samp{:}). Except where
|
|
otherwise noted all numbers are represented in HEX with leading zeros
|
|
suppressed.
|
|
|
|
Response @var{data} can be run-length encoded to save space. A @samp{*}
|
|
means that the next character is an 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). Don't use an
|
|
@code{n > 126}.
|
|
|
|
So:
|
|
@example
|
|
"@code{0* }"
|
|
@end example
|
|
@noindent
|
|
means the same as "0000".
|
|
|
|
The error response, returned for some packets includes a two character
|
|
error number. That number is not well defined.
|
|
|
|
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 the response.
|
|
|
|
Below is a complete list of all currently defined @var{command}s and
|
|
their corresponding response @var{data}:
|
|
|
|
@multitable @columnfractions .30 .30 .40
|
|
@item Packet
|
|
@tab Request
|
|
@tab Description
|
|
|
|
@item extended ops @emph{(optional)}
|
|
@tab @code{!}
|
|
@tab
|
|
Use the extended remote protocol. Sticky -- only needs to be set once.
|
|
The extended remote protocol support 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.
|
|
|
|
@item last signal
|
|
@tab @code{?}
|
|
@tab
|
|
Reply the current reason for stopping. This is the same reply as is
|
|
generated for step or cont : @code{S}@var{AA} where @var{AA} is the
|
|
signal number.
|
|
|
|
@item reserved
|
|
@tab @code{a}
|
|
@tab Reserved for future use
|
|
|
|
@item set program arguments @strong{(reserved)} @emph{(optional)}
|
|
@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
|
|
@tab
|
|
Initialized @samp{argv[]} array passed into program. @var{arglen}
|
|
specifies the number of bytes in the hex encoded byte stream @var{arg}.
|
|
@item
|
|
@tab reply @code{OK}
|
|
@item
|
|
@tab reply @code{E}@var{NN}
|
|
|
|
@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.}
|
|
|
|
@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
|
|
@tab reply
|
|
@tab see below
|
|
|
|
@item continue with signal @emph{(optional)}
|
|
@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
|
|
|
|
@item toggle debug @emph{(optional)}
|
|
@tab @code{d}
|
|
@tab
|
|
toggle debug flag (see 386 & 68k stubs)
|
|
|
|
@item detach @emph{(optional)}
|
|
@tab @code{D}
|
|
@tab Reply OK.
|
|
|
|
@item reserved
|
|
@tab @code{e}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{E}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{f}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{F}
|
|
@tab Reserved for future use
|
|
|
|
@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} is
|
|
determined by the @var{REGISTER_RAW_SIZE} and @var{REGISTER_NAME}
|
|
macros.
|
|
@item
|
|
@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
|
|
|
|
@item reserved
|
|
@tab @code{h}
|
|
@tab Reserved for future use
|
|
|
|
@item set thread @emph{(optional)}
|
|
@tab @code{H}@var{c}@var{t...}
|
|
@tab
|
|
Set thread for subsequent operations. @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
|
|
|
|
@item cycle step @strong{(draft)} @emph{(optional)}
|
|
@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.
|
|
|
|
@item signal then cycle step @strong{(reserved)} @emph{(optional)}
|
|
@tab @code{I}
|
|
@tab
|
|
See @samp{i} and @samp{S} for likely syntax and semantics.
|
|
|
|
@item reserved
|
|
@tab @code{j}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{J}
|
|
@tab Reserved for future use
|
|
|
|
@item kill request @emph{(optional)}
|
|
@tab @code{k}
|
|
@tab
|
|
|
|
@item reserved
|
|
@tab @code{l}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{L}
|
|
@tab Reserved for future use
|
|
|
|
@item read memory
|
|
@tab @code{m}@var{addr}@code{,}@var{length}
|
|
@tab
|
|
Read @var{length} bytes of memory starting at address @var{addr}.
|
|
@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.
|
|
@item
|
|
@tab reply @code{E}@var{NN}
|
|
@tab @var{NN} is errno
|
|
|
|
@item write mem
|
|
@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
|
|
@tab
|
|
Write @var{length} bytes of memory starting at address @var{addr}.
|
|
@var{XX...} is the data.
|
|
@item
|
|
@tab reply @code{OK}
|
|
@tab for success
|
|
@item
|
|
@tab reply @code{E}@var{NN}
|
|
@tab
|
|
for an error (this includes the case where only part of the data was
|
|
written).
|
|
|
|
@item reserved
|
|
@tab @code{n}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{N}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{o}
|
|
@tab Reserved for future use
|
|
|
|
@item reserved
|
|
@tab @code{O}
|
|
@tab Reserved for future use
|
|
|
|
@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.
|
|
|
|
@item write reg @emph{(optional)}
|
|
@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
|
|
|
|
@item general query @emph{(optional)}
|
|
@tab @code{q}@var{query}
|
|
@tab
|
|
Request info about @var{query}. In general @value{GDBN} @var{query}'s
|
|
have a leading upper case letter. Custom vendor queries should use a
|
|
leading lower case letter and a company prefix, ex: @samp{qfsf.var}.
|
|
@var{query} may optionally be followed by a @samp{,} or @samp{;}
|
|
separated list. Stubs should ensure that they fully match any
|
|
@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}.
|
|
|
|
@item current thread
|
|
@tab @code{q}@code{C}
|
|
@tab Return the current thread id.
|
|
@item
|
|
@tab reply @code{QC}@var{pid}
|
|
@tab
|
|
Where @var{pid} is a HEX encoded 16 bit process id.
|
|
@item
|
|
@tab reply *
|
|
@tab Any other reply implies the old pid.
|
|
|
|
@item 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 @var{LIST} or @var{threadLIST}
|
|
@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
|
|
@tab
|
|
Obtain thread information from RTOS. @var{startflag} is one hex digit;
|
|
@var{threadcount} is two hex digits; and @var{nextthread} is 16 hex
|
|
digits.
|
|
@item
|
|
@tab reply *
|
|
@tab
|
|
See @code{remote.c:parse_threadlist_response()}.
|
|
|
|
@item query sect offs
|
|
@tab @code{q}@code{Offsets}
|
|
@tab Get section offsets.
|
|
@item
|
|
@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
|
|
|
|
@item thread info request
|
|
@tab @code{q}@code{P}@var{mode}@var{threadid}
|
|
@tab
|
|
Returns information on @var{threadid}. Where: @var{mode} is a hex
|
|
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
|
|
@item
|
|
@tab reply *
|
|
@tab
|
|
See @code{remote.c:remote_unpack_thread_info_response()}.
|
|
|
|
@item remote command
|
|
@tab @code{q}@code{Rcmd,}@var{COMMAND}
|
|
@tab
|
|
@var{COMMAND} (hex encoded) is passed to the local interpreter for
|
|
execution. Invalid commands should be reported using the output string.
|
|
Before the final result packet, the target may also respond with a
|
|
number of intermediate @code{O}@var{OUTPUT} console output
|
|
packets. @emph{Implementors should note that providing access to a
|
|
stubs's interpreter may have security implications}.
|
|
@item
|
|
@tab reply @code{OK}
|
|
@tab
|
|
A command response with no output.
|
|
@item
|
|
@tab reply @var{OUTPUT}
|
|
@tab
|
|
A command response with the hex encoded output string @var{OUTPUT}.
|
|
@item
|
|
@tab reply @code{E}@var{NN}
|
|
@tab
|
|
Indicate a badly formed request.
|
|
|
|
@item
|
|
@tab reply @samp{}
|
|
@tab
|
|
When @samp{q}@samp{Rcmd} is not recognized.
|
|
|
|
@item general set @emph{(optional)}
|
|
@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 @emph{(optional)}
|
|
@tab r
|
|
@tab reset -- see sparc stub.
|
|
|
|
@item remote restart @emph{(optional)}
|
|
@tab @code{R}@var{XX}
|
|
@tab
|
|
Restart the remote server. @var{XX} while needed has no clear
|
|
definition.
|
|
|
|
@item step @emph{(optional)}
|
|
@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 @emph{(optional)}
|
|
@tab @code{S}@var{sig}@code{;}@var{addr}
|
|
@tab
|
|
Like @samp{C} but step not continue.
|
|
@item
|
|
@tab reply
|
|
@tab see below
|
|
|
|
@item search @emph{(optional)}
|
|
@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 @emph{(optional)}
|
|
@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) @emph{(optional)}
|
|
@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.
|
|
@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)} @emph{(optional)}
|
|
@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
|
|
@tab
|
|
See @samp{Z}.
|
|
|
|
@item insert break or watchpoint @strong{(draft)} @emph{(optional)}
|
|
@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.
|
|
@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
|
|
|
|
In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets,
|
|
there is no immediate response. The reply, described below, comes when
|
|
the machine stops:
|
|
|
|
@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{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)}
|
|
@tab
|
|
@var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
|
|
@var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss
|
|
section. @emph{Note: only used by Cisco Systems targets. The difference
|
|
between this reply and the "qOffsets" query is that the 'N' packet may
|
|
arrive spontaneously whereas the 'qOffsets' is a query initiated by the
|
|
host debugger.}
|
|
|
|
@item @code{O}@var{XX...}
|
|
@tab
|
|
@var{XX...} is hex encoding of ASCII data. This can happen at any time
|
|
while the program is running and the debugger should continue to wait
|
|
for 'W', 'T', etc.
|
|
|
|
@end multitable
|
|
|
|
Example sequence of a target being re-started. Notice how the restart
|
|
does not get any direct output:
|
|
|
|
@example
|
|
<- @code{R00}
|
|
-> @code{+}
|
|
@emph{target restarts}
|
|
<- @code{?}
|
|
-> @code{+}
|
|
-> @code{T001:1234123412341234}
|
|
<- @code{+}
|
|
@end example
|
|
|
|
Example sequence of a target being stepped by a single instruction:
|
|
|
|
@example
|
|
<- @code{G1445...}
|
|
-> @code{+}
|
|
<- @code{s}
|
|
-> @code{+}
|
|
@emph{time passes}
|
|
-> @code{T001:1234123412341234}
|
|
<- @code{+}
|
|
<- @code{g}
|
|
-> @code{+}
|
|
-> @code{1455...}
|
|
<- @code{+}
|
|
@end example
|
|
|
|
@kindex set remotedebug
|
|
@kindex show remotedebug
|
|
@cindex packets, reporting on stdout
|
|
@cindex serial connections, debugging
|
|
If you have trouble with the serial connection, you can use the command
|
|
@code{set remotedebug}. This makes @value{GDBN} report on all packets sent
|
|
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} shows you its current state.
|
|
|
|
@node Server
|
|
@subsubsection Using the @code{gdbserver} program
|
|
|
|
@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
|
|
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.
|
|
|
|
@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 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
|
|
@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
|
|
|
|
@node i960-Nindy Remote
|
|
@subsection @value{GDBN} with a remote i960 (Nindy)
|
|
|
|
@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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Through command line options specifying serial port, version of the
|
|
Nindy protocol, and communications speed;
|
|
|
|
@item
|
|
By responding to a prompt on startup;
|
|
|
|
@item
|
|
By using the @code{target} command at any point during your @value{GDBN}
|
|
session. @xref{Target Commands, ,Commands for managing targets}.
|
|
|
|
@end itemize
|
|
|
|
@menu
|
|
* Nindy Startup:: Startup with Nindy
|
|
* Nindy Options:: Options for Nindy
|
|
* Nindy Reset:: Nindy reset command
|
|
@end menu
|
|
|
|
@node Nindy Startup
|
|
@subsubsection Startup with Nindy
|
|
|
|
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
|
|
|
|
@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}).
|
|
|
|
@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
|
|
@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}).
|
|
|
|
@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.
|
|
|
|
@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
|
|
|
|
@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.
|
|
|
|
@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
|
|
|
|
The standard @samp{-b} option controls the line speed used on the serial
|
|
port.
|
|
|
|
@c @group
|
|
@node Nindy Reset
|
|
@subsubsection Nindy reset command
|
|
|
|
@table @code
|
|
@item reset
|
|
@kindex reset
|
|
For a Nindy target, this command sends a ``break'' to the remote target
|
|
system; this is only useful if the target has been equipped with a
|
|
circuit to perform a hard reset (or some other interesting action) when
|
|
a break is detected.
|
|
@end table
|
|
@c @end group
|
|
|
|
@node UDI29K Remote
|
|
@subsection The UDI protocol for AMD29K
|
|
|
|
@cindex UDI
|
|
@cindex AMD29K via UDI
|
|
@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.
|
|
|
|
@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 EB29K Remote
|
|
@subsection The EBMON protocol for AMD29K
|
|
|
|
@cindex EB29K board
|
|
@cindex running 29K programs
|
|
|
|
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.
|
|
|
|
@menu
|
|
* Comms (EB29K):: Communications setup
|
|
* gdb-EB29K:: EB29K cross-debugging
|
|
* Remote Log:: Remote log
|
|
@end menu
|
|
|
|
@node Comms (EB29K)
|
|
@subsubsection Communications setup
|
|
|
|
The next step is to set up the PC's port, by doing something like this
|
|
in DOS on the PC:
|
|
|
|
@example
|
|
C:\> MODE com1:9600,n,8,1,none
|
|
@end example
|
|
|
|
@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
|
|
|
|
To give control of the PC to the Unix side of the serial line, type
|
|
the following at the DOS console:
|
|
|
|
@example
|
|
C:\> CTTY com1
|
|
@end example
|
|
|
|
@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).
|
|
|
|
From the Unix host, use a communications program such as @code{tip} or
|
|
@code{cu} to communicate with the PC; for example,
|
|
|
|
@example
|
|
cu -s 9600 -l /dev/ttya
|
|
@end example
|
|
|
|
@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:
|
|
|
|
@example
|
|
tip -9600 /dev/ttya
|
|
@end example
|
|
|
|
@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
|
|
|
|
@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 @code{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
|
|
|
|
@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.
|
|
|
|
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 @code{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
|
|
@kindex eb.log
|
|
@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.
|
|
|
|
@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:
|
|
|
|
@example
|
|
target st2000 @var{dev} @var{speed}
|
|
@end example
|
|
|
|
@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 @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.
|
|
|
|
@cindex ST2000 auxiliary commands
|
|
These auxiliary @value{GDBN} commands are available to help you with the ST2000
|
|
environment:
|
|
|
|
@table @code
|
|
@item st2000 @var{command}
|
|
@kindex st2000 @var{cmd}
|
|
@cindex STDBUG commands (ST2000)
|
|
@cindex commands to STDBUG (ST2000)
|
|
Send a @var{command} to the STDBUG monitor. See the manufacturer's
|
|
manual for available commands.
|
|
|
|
@item connect
|
|
@cindex connect (to STDBUG)
|
|
Connect the controlling terminal to the STDBUG command monitor. When
|
|
you are done interacting with STDBUG, typing either of two character
|
|
sequences gets you back to the @value{GDBN} command prompt:
|
|
@kbd{@key{RET}~.} (Return, followed by tilde and period) or
|
|
@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
|
|
@end table
|
|
|
|
@node VxWorks Remote
|
|
@subsection @value{GDBN} and VxWorks
|
|
|
|
@cindex VxWorks
|
|
|
|
@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{gdb} 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.)
|
|
|
|
@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 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}.
|
|
|
|
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:
|
|
|
|
@example
|
|
(vxgdb)
|
|
@end example
|
|
|
|
@menu
|
|
* VxWorks Connection:: Connecting to VxWorks
|
|
* VxWorks Download:: VxWorks download
|
|
* VxWorks Attach:: Running tasks
|
|
@end menu
|
|
|
|
@node VxWorks Connection
|
|
@subsubsection Connecting to VxWorks
|
|
|
|
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:
|
|
|
|
@example
|
|
(vxgdb) target vxworks tt
|
|
@end example
|
|
|
|
@need 750
|
|
@value{GDBN} displays messages like these:
|
|
|
|
@smallexample
|
|
Attaching remote machine across net...
|
|
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
|
|
path (@pxref{Environment, ,Your program's environment}); if it fails
|
|
to find an object file, it displays a message such as:
|
|
|
|
@example
|
|
prog.o: No such file or directory.
|
|
@end example
|
|
|
|
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.
|
|
|
|
@node VxWorks Download
|
|
@subsubsection VxWorks download
|
|
|
|
@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:
|
|
|
|
@example
|
|
-> cd "@var{vxpath}/vw/demo/rdb"
|
|
@end example
|
|
v
|
|
Then, in @value{GDBN}, type:
|
|
|
|
@example
|
|
(vxgdb) cd @var{hostpath}/vw/demo/rdb
|
|
(vxgdb) load prog.o
|
|
@end example
|
|
|
|
@value{GDBN} displays a response similar to this:
|
|
|
|
@smallexample
|
|
Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
|
|
@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 data structures that reference the target system's symbol
|
|
table.)
|
|
|
|
@node VxWorks Attach
|
|
@subsubsection Running tasks
|
|
|
|
@cindex running VxWorks tasks
|
|
You can also attach to an existing task using the @code{attach} command as
|
|
follows:
|
|
|
|
@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.
|
|
|
|
@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
|
|
@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, 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).
|
|
|
|
@item
|
|
what speed to use over the serial device.
|
|
@end enumerate
|
|
|
|
@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
|
|
Use the special @code{@value{GDBP}} 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}.
|
|
|
|
@kindex speed
|
|
@cindex serial line speed, Hitachi micros
|
|
@code{@value{GDBP}} 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 GDB with
|
|
the DOS @kbd{mode} command (for instance, @w{@samp{mode
|
|
com2:9600,n,8,1,p}} for a 9600 bps connection).
|
|
|
|
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
|
|
degugger, 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}.
|
|
|
|
@example
|
|
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
|
|
|
|
@end example
|
|
|
|
@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
|
|
|
|
@kindex target hms
|
|
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{GDBP}} 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
|
|
(eg-C:\H8300\TEST) @value{GDBP} t.x
|
|
GDB 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 GDB; type "show warranty"
|
|
for details.
|
|
GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
|
|
(gdb) target hms
|
|
Connected to remote H8/300 HMS system.
|
|
(gdb) load t.x
|
|
.text : 0x8000 .. 0xabde ***********
|
|
.data : 0xabde .. 0xad30 *
|
|
.stack : 0xf000 .. 0xf014 *
|
|
@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.
|
|
|
|
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!
|
|
|
|
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
|
|
|
|
@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
|
|
|
|
In either case, @value{GDBN} sees the effect of a @sc{reset} on the
|
|
development board as a ``normal exit'' of your program.
|
|
|
|
@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
|
|
|
|
@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}.
|
|
|
|
@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
|
|
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}
|
|
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 @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
|
|
@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}.)
|
|
|
|
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
|
|
|
|
@cindex simulator
|
|
@cindex simulator, Z8000
|
|
@cindex Z8000 simulator
|
|
@cindex simulator, H8/300 or H8/500
|
|
@cindex H8/300 or H8/500 simulator
|
|
@cindex simulator, Hitachi SH
|
|
@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, simulators are available for ARM, D10V, D30V, FR30, H8/300,
|
|
H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
|
|
W65, and Z8000.
|
|
|
|
@cindex simulator, Z8000
|
|
@cindex Zilog Z8000 simulator
|
|
When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
|
|
a Z8000 simulator.
|
|
|
|
For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
|
|
unsegmented variant of the Z8000 architecture) or the Z8001 (the
|
|
segmented variant). The simulator recognizes which architecture is
|
|
appropriate by inspecting the object code.
|
|
|
|
@table @code
|
|
@item target sim @var{args}
|
|
@kindex sim
|
|
@kindex target sim
|
|
Debug programs on a simulated CPU. If the simulator supports setup
|
|
options, specify them via @var{args}.
|
|
@end table
|
|
|
|
@noindent
|
|
After specifying this target, you can debug programs for the simulated
|
|
CPU in the same style as programs for your host computer; use the
|
|
@code{file} command to load a new program image, the @code{run} command
|
|
to run your program, and so on.
|
|
|
|
As well as making available all the usual machine registers (see
|
|
@code{info reg}), the Z8000 simulator provides three additional items
|
|
of information as specially named registers:
|
|
|
|
@table @code
|
|
@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
|
|
|
|
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.
|
|
|
|
@c need to add much more detail about sims!
|