| @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! |