From 8e04817fcda94aaf3925f58dc2bf194e79584854 Mon Sep 17 00:00:00 2001 From: Andrew Cagney Date: Tue, 22 Jan 2002 16:25:57 +0000 Subject: [PATCH] Move remote protocol specification to an appendix. --- gdb/doc/ChangeLog | 4 + gdb/doc/gdb.texinfo | 6843 ++++++++++++++++++++++++++------------------------- 2 files changed, 3427 insertions(+), 3420 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index e7af5fd..57ee69d 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +2002-01-22 Andrew Cagney + + * gdb.texinfo (Protocol): Move section to appendix. + 2002-01-21 Andrew Cagney * gdb.texinfo (Remote Debugging): Create a menu. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 390b488..080a2ca 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -153,6 +153,7 @@ Copyright (C) 1988-2002 Free Software Foundation, Inc. * Using History Interactively:: Using History Interactively * Installing GDB:: Installing GDB * Maintenance Commands:: Maintenance Commands +* Remove Protocol:: GDB Remote Serial Protocol * GNU Free Documentation License:: The license for this documentation * Index:: Index @end menu @@ -209,6 +210,7 @@ Copyright (C) 1988-2000 Free Software Foundation, Inc. * Using History Interactively:: Using History Interactively * Installing GDB:: Installing GDB * Maintenance Commands:: Maintenance Commands +* Remove Protocol:: GDB Remote Serial Protocol * GNU Free Documentation License:: The license for this documentation * Index:: Index @end menu @@ -9949,7 +9951,6 @@ is supported other than to try it. * Server:: Using the gdbserver program * NetWare:: Using the gdbserve.nlm program * remote stub:: Implementing a remote stub -* Protocol:: Communication protocol @end menu @node Server @@ -10114,6 +10115,17 @@ communications with the server via serial line @file{/dev/ttyb}. @node remote stub @section Implementing a remote stub +@cindex debugging stub, example +@cindex remote stub, example +@cindex stub example, remote debugging +The stub files provided with @value{GDBN} implement the target side of the +communication protocol, and the @value{GDBN} side is implemented in the +@value{GDBN} source file @file{remote.c}. Normally, you can simply allow +these subroutines to communicate, and ignore the details. (If you're +implementing your own stub file, you can still ignore the details: start +with one of the existing stub files. @file{sparc-stub.c} is the best +organized, and therefore the easiest to read.) + @cindex remote serial debugging, overview To debug a program running on another machine (the debugging @dfn{target} machine), you must first arrange for all the usual @@ -10466,1257 +10478,397 @@ If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} goes back to waiting. -@node Protocol -@section Communication protocol -@cindex debugging stub, example -@cindex remote stub, example -@cindex stub example, remote debugging -The stub files provided with @value{GDBN} implement the target side of the -communication protocol, and the @value{GDBN} side is implemented in the -@value{GDBN} source file @file{remote.c}. Normally, you can simply allow -these subroutines to communicate, and ignore the details. (If you're -implementing your own stub file, you can still ignore the details: start -with one of the existing stub files. @file{sparc-stub.c} is the best -organized, and therefore the easiest to read.) +@node Configurations +@chapter Configuration-Specific Information -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}. +While nearly all @value{GDBN} commands are available for all native and +cross versions of the debugger, there are some exceptions. This chapter +describes things that are only available in certain configurations. -In the examples below, @samp{<-} and @samp{->} are used to indicate -transmitted and received data respectfully. +There are three major categories of configurations: native +configurations, where the host and target are the same, embedded +operating system configurations, which are usually the same for several +different processor architectures, and bare embedded processors, which +are quite different from each other. -@cindex protocol, @value{GDBN} remote serial -@cindex serial protocol, @value{GDBN} remote -@cindex remote serial protocol -All @value{GDBN} commands and responses (other than acknowledgments) are -sent as a @var{packet}. A @var{packet} is introduced with the character -@samp{$}, the actual @var{packet-data}, and the terminating character -@samp{#} followed by a two-digit @var{checksum}: +@menu +* Native:: +* Embedded OS:: +* Embedded Processors:: +* Architectures:: +@end menu -@example -@code{$}@var{packet-data}@code{#}@var{checksum} -@end example -@noindent +@node Native +@section Native -@cindex checksum, for @value{GDBN} remote -@noindent -The two-digit @var{checksum} is computed as the modulo 256 sum of all -characters between the leading @samp{$} and the trailing @samp{#} (an -eight bit unsigned checksum). +This section describes details specific to particular native +configurations. -Implementors should note that prior to @value{GDBN} 5.0 the protocol -specification also included an optional two-digit @var{sequence-id}: +@menu +* HP-UX:: HP-UX +* SVR4 Process Information:: SVR4 process information +* DJGPP Native:: Features specific to the DJGPP port +@end menu -@example -@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} -@end example +@node HP-UX +@subsection HP-UX -@cindex sequence-id, for @value{GDBN} remote -@noindent -That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} -has never output @var{sequence-id}s. Stubs that handle packets added -since @value{GDBN} 5.0 must not accept @var{sequence-id}. +On HP-UX systems, if you refer to a function or variable name that +begins with a dollar sign, @value{GDBN} searches for a user or system +name first, before it searches for a convenience variable. -@cindex acknowledgment, for @value{GDBN} remote -When either the host or the target machine receives a packet, the first -response expected is an acknowledgment: either @samp{+} (to indicate -the package was received correctly) or @samp{-} (to request -retransmission): +@node SVR4 Process Information +@subsection SVR4 process information -@example -<- @code{$}@var{packet-data}@code{#}@var{checksum} --> @code{+} -@end example -@noindent +@kindex /proc +@cindex process image -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). +Many versions of SVR4 provide a facility called @samp{/proc} that can be +used to examine the image of a running process using file-system +subroutines. If @value{GDBN} is configured for an operating system with +this facility, the command @code{info proc} is available to report on +several kinds of information about the process running your program. +@code{info proc} works only on SVR4 systems that include the +@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix, +and Unixware, but not HP-UX or Linux, for example. -@var{packet-data} consists of a sequence of characters with the -exception of @samp{#} and @samp{$} (see @samp{X} packet for additional -exceptions). +@table @code +@kindex info proc +@item info proc +Summarize available information about the process. -Fields within the packet should be separated using @samp{,} @samp{;} or -@samp{:}. Except where otherwise noted all numbers are represented in -HEX with leading zeros suppressed. +@kindex info proc mappings +@item info proc mappings +Report on the address ranges accessible in the program, with information +on whether your program may read, write, or execute each range. +@ignore +@comment These sub-options of 'info proc' were not included when +@comment procfs.c was re-written. Keep their descriptions around +@comment against the day when someone finds the time to put them back in. +@kindex info proc times +@item info proc times +Starting time, user CPU time, and system CPU time for your program and +its children. -Implementors should note that prior to @value{GDBN} 5.0, the character -@samp{:} could not appear as the third character in a packet (as it -would potentially conflict with the @var{sequence-id}). +@kindex info proc id +@item info proc id +Report on the process IDs related to your program: its own process ID, +the ID of its parent, the process group ID, and the session ID. -Response @var{data} can be run-length encoded to save space. A @samp{*} -means that the next character is an @sc{ascii} encoding giving a repeat count -which stands for that many repetitions of the character preceding the -@samp{*}. The encoding is @code{n+29}, yielding a printable character -where @code{n >=3} (which is where rle starts to win). The printable -characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric -value greater than 126 should not be used. +@kindex info proc status +@item info proc status +General information on the state of the process. If the process is +stopped, this report includes the reason for stopping, and any signal +received. -Some remote systems have used a different run-length encoding mechanism -loosely refered to as the cisco encoding. Following the @samp{*} -character are two hex digits that indicate the size of the packet. +@item info proc all +Show all the above information about the process. +@end ignore +@end table -So: -@example -"@code{0* }" -@end example -@noindent -means the same as "0000". +@node DJGPP Native +@subsection Features for Debugging @sc{djgpp} Programs +@cindex @sc{djgpp} debugging +@cindex native @sc{djgpp} debugging +@cindex MS-DOS-specific commands -The error response returned for some packets includes a two character -error number. That number is not well defined. +@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and +MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs +that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on +top of real-mode DOS systems and their emulations. -For any @var{command} not supported by the stub, an empty response -(@samp{$#00}) should be returned. That way it is possible to extend the -protocol. A newer @value{GDBN} can tell if a packet is supported based -on that response. +@value{GDBN} supports native debugging of @sc{djgpp} programs, and +defines a few commands specific to the @sc{djgpp} port. This +subsection describes those commands. -A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, -@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are -optional. +@table @code +@kindex info dos +@item info dos +This is a prefix of @sc{djgpp}-specific commands which print +information about the target system and important OS structures. -Below is a complete list of all currently defined @var{command}s and -their corresponding response @var{data}: -@page -@multitable @columnfractions .30 .30 .40 -@item Packet -@tab Request -@tab Description +@kindex sysinfo +@cindex MS-DOS system info +@cindex free memory information (MS-DOS) +@item info dos sysinfo +This command displays assorted information about the underlying +platform: the CPU type and features, the OS version and flavor, the +DPMI version, and the available conventional and DPMI memory. -@item extended mode -@tab @code{!} -@tab -Enable extended mode. In extended mode, the remote server is made -persistent. The @samp{R} packet is used to restart the program being -debugged. -@item -@tab reply @samp{OK} -@tab -The remote target both supports and has enabled extended mode. +@cindex GDT +@cindex LDT +@cindex IDT +@cindex segment descriptor tables +@cindex descriptor tables display +@item info dos gdt +@itemx info dos ldt +@itemx info dos idt +These 3 commands display entries from, respectively, Global, Local, +and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor +tables are data structures which store a descriptor for each segment +that is currently in use. The segment's selector is an index into a +descriptor table; the table entry for that index holds the +descriptor's base address and limit, and its attributes and access +rights. -@item last signal -@tab @code{?} -@tab -Indicate the reason the target halted. The reply is the same as for step -and continue. -@item -@tab reply -@tab see below +A typical @sc{djgpp} program uses 3 segments: a code segment, a data +segment (used for both data and the stack), and a DOS segment (which +allows access to DOS/BIOS data structures and absolute addresses in +conventional memory). However, the DPMI host will usually define +additional segments in order to support the DPMI environment. +@cindex garbled pointers +These commands allow to display entries from the descriptor tables. +Without an argument, all entries from the specified table are +displayed. An argument, which should be an integer expression, means +display a single entry whose index is given by the argument. For +example, here's a convenient way to display information about the +debugged program's data segment: -@item reserved -@tab @code{a} -@tab Reserved for future use +@smallexample +@exdent @code{(@value{GDBP}) info dos ldt $ds} +@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} +@end smallexample -@item set program arguments @strong{(reserved)} -@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...} -@tab -@item -@tab -@tab -Initialized @samp{argv[]} array passed into program. @var{arglen} -specifies the number of bytes in the hex encoded byte stream @var{arg}. -See @file{gdbserver} for more details. -@item -@tab reply @code{OK} -@item -@tab reply @code{E}@var{NN} - -@item set baud @strong{(deprecated)} -@tab @code{b}@var{baud} -@tab -Change the serial line speed to @var{baud}. JTC: @emph{When does the -transport layer state change? When it's received, or after the ACK is -transmitted. In either case, there are problems if the command or the -acknowledgment packet is dropped.} Stan: @emph{If people really wanted -to add something like this, and get it working for the first time, they -ought to modify ser-unix.c to send some kind of out-of-band message to a -specially-setup stub and have the switch happen "in between" packets, so -that from remote protocol's point of view, nothing actually -happened.} +@noindent +This comes in handy when you want to see whether a pointer is outside +the data segment's limit (i.e.@: @dfn{garbled}). -@item set breakpoint @strong{(deprecated)} -@tab @code{B}@var{addr},@var{mode} -@tab -Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a -breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and -@samp{z} packets.} +@cindex page tables display (MS-DOS) +@item info dos pde +@itemx info dos pte +These two commands display entries from, respectively, the Page +Directory and the Page Tables. Page Directories and Page Tables are +data structures which control how virtual memory addresses are mapped +into physical addresses. A Page Table includes an entry for every +page of memory that is mapped into the program's address space; there +may be several Page Tables, each one holding up to 4096 entries. A +Page Directory has up to 4096 entries, one each for every Page Table +that is currently in use. -@item continue -@tab @code{c}@var{addr} -@tab -@var{addr} is address to resume. If @var{addr} is omitted, resume at -current address. -@item -@tab reply -@tab see below +Without an argument, @kbd{info dos pde} displays the entire Page +Directory, and @kbd{info dos pte} displays all the entries in all of +the Page Tables. An argument, an integer expression, given to the +@kbd{info dos pde} command means display only that entry from the Page +Directory table. An argument given to the @kbd{info dos pte} command +means display entries from a single Page Table, the one pointed to by +the specified entry in the Page Directory. -@item continue with signal -@tab @code{C}@var{sig}@code{;}@var{addr} -@tab -Continue with signal @var{sig} (hex signal number). If -@code{;}@var{addr} is omitted, resume at same address. -@item -@tab reply -@tab see below +@cindex direct memory access (DMA) on MS-DOS +These commands are useful when your program uses @dfn{DMA} (Direct +Memory Access), which needs physical addresses to program the DMA +controller. -@item toggle debug @strong{(deprecated)} -@tab @code{d} -@tab -toggle debug flag. +These commands are supported only with some DPMI servers. -@item detach -@tab @code{D} -@tab -Detach @value{GDBN} from the remote system. Sent to the remote target before -@value{GDBN} disconnects. -@item -@tab reply @emph{no response} -@tab -@value{GDBN} does not check for any response after sending this packet. +@cindex physical address from linear address +@item info dos address-pte @var{addr} +This command displays the Page Table entry for a specified linear +address. The argument linear address @var{addr} should already have the +appropriate segment's base address added to it, because this command +accepts addresses which may belong to @emph{any} segment. For +example, here's how to display the Page Table entry for the page where +the variable @code{i} is stored: -@item reserved -@tab @code{e} -@tab Reserved for future use +@smallexample +@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} +@exdent @code{Page Table entry for address 0x11a00d30:} +@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} +@end smallexample -@item reserved -@tab @code{E} -@tab Reserved for future use +@noindent +This says that @code{i} is stored at offset @code{0xd30} from the page +whose physical base address is @code{0x02698000}, and prints all the +attributes of that page. -@item reserved -@tab @code{f} -@tab Reserved for future use +Note that you must cast the addresses of variables to a @code{char *}, +since otherwise the value of @code{__djgpp_base_address}, the base +address of all variables and functions in a @sc{djgpp} program, will +be added using the rules of C pointer arithmetics: if @code{i} is +declared an @code{int}, @value{GDBN} will add 4 times the value of +@code{__djgpp_base_address} to the address of @code{i}. -@item reserved -@tab @code{F} -@tab Reserved for future use +Here's another example, it displays the Page Table entry for the +transfer buffer: -@item read registers -@tab @code{g} -@tab Read general registers. -@item -@tab reply @var{XX...} -@tab -Each byte of register data is described by two hex digits. The bytes -with the register are transmitted in target byte order. The size of -each register and their position within the @samp{g} @var{packet} are -determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and -@var{REGISTER_NAME} macros. The specification of several standard -@code{g} packets is specified below. -@item -@tab @code{E}@var{NN} -@tab for an error. +@smallexample +@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} +@exdent @code{Page Table entry for address 0x29110:} +@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} +@end smallexample -@item write regs -@tab @code{G}@var{XX...} -@tab -See @samp{g} for a description of the @var{XX...} data. -@item -@tab reply @code{OK} -@tab for success -@item -@tab reply @code{E}@var{NN} -@tab for an error +@noindent +(The @code{+ 3} offset is because the transfer buffer's address is the +3rd member of the @code{_go32_info_block} structure.) The output of +this command clearly shows that addresses in conventional memory are +mapped 1:1, i.e.@: the physical and linear addresses are identical. -@item reserved -@tab @code{h} -@tab Reserved for future use +This command is supported only with some DPMI servers. +@end table -@item set thread -@tab @code{H}@var{c}@var{t...} -@tab -Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, -@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and -continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for -thread used in other operations. If zero, pick a thread, any thread. -@item -@tab reply @code{OK} -@tab for success -@item -@tab reply @code{E}@var{NN} -@tab for an error +@node Embedded OS +@section Embedded Operating Systems -@c FIXME: JTC: -@c 'H': How restrictive (or permissive) is the thread model. If a -@c thread is selected and stopped, are other threads allowed -@c to continue to execute? As I mentioned above, I think the -@c semantics of each command when a thread is selected must be -@c described. For example: -@c -@c 'g': If the stub supports threads and a specific thread is -@c selected, returns the register block from that thread; -@c otherwise returns current registers. -@c -@c 'G' If the stub supports threads and a specific thread is -@c selected, sets the registers of the register block of -@c that thread; otherwise sets current registers. +This section describes configurations involving the debugging of +embedded operating systems that are available for several different +architectures. -@item cycle step @strong{(draft)} -@tab @code{i}@var{addr}@code{,}@var{nnn} -@tab -Step the remote target by a single clock cycle. If @code{,}@var{nnn} is -present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle -step starting at that address. +@menu +* VxWorks:: Using @value{GDBN} with VxWorks +@end menu -@item signal then cycle step @strong{(reserved)} -@tab @code{I} -@tab -See @samp{i} and @samp{S} for likely syntax and semantics. +@value{GDBN} includes the ability to debug programs running on +various real-time operating systems. -@item reserved -@tab @code{j} -@tab Reserved for future use +@node VxWorks +@subsection Using @value{GDBN} with VxWorks -@item reserved -@tab @code{J} -@tab Reserved for future use +@cindex VxWorks -@item kill request -@tab @code{k} -@tab -FIXME: @emph{There is no description of how operate when a specific -thread context has been selected (ie. does 'k' kill only that thread?)}. +@table @code -@item reserved -@tab @code{l} -@tab Reserved for future use +@kindex target vxworks +@item target vxworks @var{machinename} +A VxWorks system, attached via TCP/IP. The argument @var{machinename} +is the target system's machine name or IP address. -@item reserved -@tab @code{L} -@tab Reserved for future use +@end table -@item read memory -@tab @code{m}@var{addr}@code{,}@var{length} -@tab -Read @var{length} bytes of memory starting at address @var{addr}. -Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed -using word alligned accesses. FIXME: @emph{A word aligned memory -transfer mechanism is needed.} -@item -@tab reply @var{XX...} -@tab -@var{XX...} is mem contents. Can be fewer bytes than requested if able -to read only part of the data. Neither @value{GDBN} nor the stub assume that -sized memory transfers are assumed using word alligned accesses. FIXME: -@emph{A word aligned memory transfer mechanism is needed.} -@item -@tab reply @code{E}@var{NN} -@tab @var{NN} is errno +On VxWorks, @code{load} links @var{filename} dynamically on the +current target system as well as adding its symbols in @value{GDBN}. -@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 +@value{GDBN} enables developers to spawn and debug tasks running on networked +VxWorks targets from a Unix host. Already-running tasks spawned from +the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on +both the Unix host and on the VxWorks target. The program +@code{@value{GDBP}} is installed and executed on the Unix host. (It may be +installed with the name @code{vxgdb}, to distinguish it from a +@value{GDBN} for debugging programs on the host itself.) -@item reserved -@tab @code{N} -@tab Reserved for future use +@table @code +@item VxWorks-timeout @var{args} +@kindex vxworks-timeout +All VxWorks-based targets now support the option @code{vxworks-timeout}. +This option is set by the user, and @var{args} represents the number of +seconds @value{GDBN} waits for responses to rpc's. You might use this if +your VxWorks target is a slow software simulator or is on the far side +of a thin network line. +@end table -@item reserved -@tab @code{o} -@tab Reserved for future use +The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. -@item reserved -@tab @code{O} -@tab Reserved for future use +@kindex INCLUDE_RDB +To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel +to include the remote debugging interface routines in the VxWorks +library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the +VxWorks configuration file @file{configAll.h} and rebuild your VxWorks +kernel. The resulting kernel contains @file{rdb.a}, and spawns the +source debugging task @code{tRdbTask} when VxWorks is booted. For more +information on configuring and remaking VxWorks, see the manufacturer's +manual. +@c VxWorks, see the @cite{VxWorks Programmer's Guide}. -@item 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. +Once you have included @file{rdb.a} in your VxWorks system image and set +your Unix execution search path to find @value{GDBN}, you are ready to +run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or +@code{vxgdb}, depending on your installation). -@item write reg -@tab @code{P}@var{n...}@code{=}@var{r...} -@tab -Write register @var{n...} with value @var{r...}, which contains two hex -digits for each byte in the register (target byte order). -@item -@tab reply @code{OK} -@tab for success -@item -@tab reply @code{E}@var{NN} -@tab for an error +@value{GDBN} comes up showing the prompt: -@item general query -@tab @code{q}@var{query} -@tab -Request info about @var{query}. In general @value{GDBN} queries -have a leading upper case letter. Custom vendor queries should use a -company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may -optionally be followed by a @samp{,} or @samp{;} separated list. Stubs -must ensure that they match the full @var{query} name. -@item -@tab reply @code{XX...} -@tab Hex encoded data from query. The reply can not be empty. -@item -@tab reply @code{E}@var{NN} -@tab error reply -@item -@tab reply @samp{} -@tab Indicating an unrecognized @var{query}. +@example +(vxgdb) +@end example -@item general set -@tab @code{Q}@var{var}@code{=}@var{val} -@tab -Set value of @var{var} to @var{val}. See @samp{q} for a discussing of -naming conventions. +@menu +* VxWorks Connection:: Connecting to VxWorks +* VxWorks Download:: VxWorks download +* VxWorks Attach:: Running tasks +@end menu -@item reset @strong{(deprecated)} -@tab @code{r} -@tab -Reset the entire system. +@node VxWorks Connection +@subsubsection Connecting to VxWorks -@item remote restart -@tab @code{R}@var{XX} -@tab -Restart the program being debugged. @var{XX}, while needed, is ignored. -This packet is only available in extended mode. -@item -@tab -no reply -@tab -The @samp{R} packet has no reply. +The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the +network. To connect to a target whose host name is ``@code{tt}'', type: -@item step -@tab @code{s}@var{addr} -@tab -@var{addr} is address to resume. If @var{addr} is omitted, resume at -same address. -@item -@tab reply -@tab see below +@example +(vxgdb) target vxworks tt +@end example -@item step with signal -@tab @code{S}@var{sig}@code{;}@var{addr} -@tab -Like @samp{C} but step not continue. -@item -@tab reply -@tab see below +@need 750 +@value{GDBN} displays messages like these: -@item search -@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} -@tab -Search backwards starting at address @var{addr} for a match with pattern -@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 -bytes. @var{addr} must be at least 3 digits. +@smallexample +Attaching remote machine across net... +Connected to tt. +@end smallexample -@item thread alive -@tab @code{T}@var{XX} -@tab Find out if the thread XX is alive. -@item -@tab reply @code{OK} -@tab thread is still alive -@item -@tab reply @code{E}@var{NN} -@tab thread is dead +@need 1000 +@value{GDBN} then attempts to read the symbol tables of any object modules +loaded into the VxWorks target since it was last booted. @value{GDBN} locates +these files by searching the directories listed in the command search +path (@pxref{Environment, ,Your program's environment}); if it fails +to find an object file, it displays a message such as: -@item reserved -@tab @code{u} -@tab Reserved for future use +@example +prog.o: No such file or directory. +@end example -@item reserved -@tab @code{U} -@tab Reserved for future use +When this happens, add the appropriate directory to the search path with +the @value{GDBN} command @code{path}, and execute the @code{target} +command again. -@item reserved -@tab @code{v} -@tab Reserved for future use +@node VxWorks Download +@subsubsection VxWorks download -@item reserved -@tab @code{V} -@tab Reserved for future use +@cindex download to VxWorks +If you have connected to the VxWorks target and you want to debug an +object that has not yet been loaded, you can use the @value{GDBN} +@code{load} command to download a file from Unix to VxWorks +incrementally. The object file given as an argument to the @code{load} +command is actually opened twice: first by the VxWorks target in order +to download the code, then by @value{GDBN} in order to read the symbol +table. This can lead to problems if the current working directories on +the two systems differ. If both systems have NFS mounted the same +filesystems, you can avoid these problems by using absolute paths. +Otherwise, it is simplest to set the working directory on both systems +to the directory in which the object file resides, and then to reference +the file by its name, without any path. For instance, a program +@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks +and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this +program, type this on VxWorks: -@item reserved -@tab @code{w} -@tab Reserved for future use +@example +-> cd "@var{vxpath}/vw/demo/rdb" +@end example -@item reserved -@tab @code{W} -@tab Reserved for future use +@noindent +Then, in @value{GDBN}, type: -@item reserved -@tab @code{x} -@tab Reserved for future use +@example +(vxgdb) cd @var{hostpath}/vw/demo/rdb +(vxgdb) load prog.o +@end example -@item write mem (binary) -@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...} -@tab -@var{addr} is address, @var{length} is number of bytes, @var{XX...} is -binary data. The characters @code{$}, @code{#}, and @code{0x7d} are -escaped using @code{0x7d}. -@item -@tab reply @code{OK} -@tab for success -@item -@tab reply @code{E}@var{NN} -@tab for an error +@value{GDBN} displays a response similar to this: -@item reserved -@tab @code{y} -@tab Reserved for future use +@smallexample +Reading symbol data from wherever/vw/demo/rdb/prog.o... done. +@end smallexample -@item reserved -@tab @code{Y} -@tab Reserved for future use +You can also use the @code{load} command to reload an object module +after editing and recompiling the corresponding source file. Note that +this makes @value{GDBN} delete all currently-defined breakpoints, +auto-displays, and convenience variables, and to clear the value +history. (This is necessary in order to preserve the integrity of +debugger's data structures that reference the target system's symbol +table.) -@item remove break or watchpoint @strong{(draft)} -@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} -@tab -See @samp{Z}. - -@item insert break or watchpoint @strong{(draft)} -@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} -@tab -@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware -breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, -@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in -bytes. For a software breakpoint, @var{length} specifies the size of -the instruction to be patched. For hardware breakpoints and watchpoints -@var{length} specifies the memory region to be monitored. To avoid -potential problems with duplicate packets, the operations should be -implemented in an idempotent way. -@item -@tab reply @code{E}@var{NN} -@tab for an error -@item -@tab reply @code{OK} -@tab for success -@item -@tab @samp{} -@tab If not supported. - -@item reserved -@tab -@tab Reserved for future use - -@end multitable - -The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can -receive any of the below as a reply. In the case of the @samp{C}, -@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned -when the target halts. In the below the exact meaning of @samp{signal -number} is poorly defined. In general one of the UNIX signal numbering -conventions is used. - -@multitable @columnfractions .4 .6 - -@item @code{S}@var{AA} -@tab @var{AA} is the signal number - -@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} -@tab -@var{AA} = two hex digit signal number; @var{n...} = register number -(hex), @var{r...} = target byte ordered register contents, size defined -by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = -thread process ID, this is a hex integer; @var{n...} = other string not -starting with valid hex digit. @value{GDBN} should ignore this -@var{n...}, @var{r...} pair and go on to the next. This way we can -extend the protocol. - -@item @code{W}@var{AA} -@tab -The process exited, and @var{AA} is the exit status. This is only -applicable for certains sorts of targets. - -@item @code{X}@var{AA} -@tab -The process terminated with signal @var{AA}. - -@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)} -@tab -@var{AA} = signal number; @var{t...} = address of symbol "_start"; -@var{d...} = base of data section; @var{b...} = base of bss section. -@emph{Note: only used by Cisco Systems targets. The difference between -this reply and the "qOffsets" query is that the 'N' packet may arrive -spontaneously whereas the 'qOffsets' is a query initiated by the host -debugger.} - -@item @code{O}@var{XX...} -@tab -@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time -while the program is running and the debugger should continue to wait -for 'W', 'T', etc. - -@end multitable - -The following set and query packets have already been defined. - -@multitable @columnfractions .2 .2 .6 - -@item current thread -@tab @code{q}@code{C} -@tab Return the current thread id. -@item -@tab reply @code{QC}@var{pid} -@tab -Where @var{pid} is a HEX encoded 16 bit process id. -@item -@tab reply * -@tab Any other reply implies the old pid. - -@item all thread ids -@tab @code{q}@code{fThreadInfo} -@item -@tab @code{q}@code{sThreadInfo} -@tab -Obtain a list of active thread ids from the target (OS). Since there -may be too many active threads to fit into one reply packet, this query -works iteratively: it may require more than one query/reply sequence to -obtain the entire list of threads. The first query of the sequence will -be the @code{qf}@code{ThreadInfo} query; subsequent queries in the -sequence will be the @code{qs}@code{ThreadInfo} query. -@item -@tab -@tab NOTE: replaces the @code{qL} query (see below). -@item -@tab reply @code{m}@var{} -@tab A single thread id -@item -@tab reply @code{m}@var{},@var{...} -@tab a comma-separated list of thread ids -@item -@tab reply @code{l} -@tab (lower case 'el') denotes end of list. -@item -@tab -@tab -In response to each query, the target will reply with a list of one -or more thread ids, in big-endian hex, separated by commas. GDB will -respond to each reply with a request for more thread ids (using the -@code{qs} form of the query), until the target responds with @code{l} -(lower-case el, for @code{'last'}). - -@item extra thread info -@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id} -@tab -@item -@tab -@tab -Where @var{} is a thread-id in big-endian hex. -Obtain a printable string description of a thread's attributes from -the target OS. This string may contain anything that the target OS -thinks is interesting for @value{GDBN} to tell the user about the thread. -The string is displayed in @value{GDBN}'s @samp{info threads} display. -Some examples of possible thread extra info strings are "Runnable", or -"Blocked on Mutex". -@item -@tab reply @var{XX...} -@tab -Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the -printable string containing the extra information about the thread's -attributes. - -@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)} -@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} -@tab -@item -@tab -@tab -Obtain thread information from RTOS. Where: @var{startflag} (one hex -digit) is one to indicate the first query and zero to indicate a -subsequent query; @var{threadcount} (two hex digits) is the maximum -number of threads the response packet can contain; and @var{nextthread} -(eight hex digits), for subsequent queries (@var{startflag} is zero), is -returned in the response as @var{argthread}. -@item -@tab -@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo} -query (see above). -@item -@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...} -@tab -@item -@tab -@tab -Where: @var{count} (two hex digits) is the number of threads being -returned; @var{done} (one hex digit) is zero to indicate more threads -and one indicates no further threads; @var{argthreadid} (eight hex -digits) is @var{nextthread} from the request packet; @var{thread...} is -a sequence of thread IDs from the target. @var{threadid} (eight hex -digits). See @code{remote.c:parse_threadlist_response()}. - -@item compute CRC of memory block -@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length} -@tab -@item -@tab reply @code{E}@var{NN} -@tab An error (such as memory fault) -@item -@tab reply @code{C}@var{CRC32} -@tab A 32 bit cyclic redundancy check of the specified memory region. - -@item query sect offs -@tab @code{q}@code{Offsets} -@tab -Get section offsets that the target used when re-locating the downloaded -image. @emph{Note: while a @code{Bss} offset is included in the -response, @value{GDBN} ignores this and instead applies the @code{Data} -offset to the @code{Bss} section.} -@item -@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} - -@item thread info request -@tab @code{q}@code{P}@var{mode}@var{threadid} -@tab -@item -@tab -@tab -Returns information on @var{threadid}. Where: @var{mode} is a hex -encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. -@item -@tab reply * -@tab -See @code{remote.c:remote_unpack_thread_info_response()}. - -@item remote command -@tab @code{q}@code{Rcmd,}@var{COMMAND} -@tab -@item -@tab -@tab -@var{COMMAND} (hex encoded) is passed to the local interpreter for -execution. Invalid commands should be reported using the output string. -Before the final result packet, the target may also respond with a -number of intermediate @code{O}@var{OUTPUT} console output -packets. @emph{Implementors should note that providing access to a -stubs's interpreter may have security implications}. -@item -@tab reply @code{OK} -@tab -A command response with no output. -@item -@tab reply @var{OUTPUT} -@tab -A command response with the hex encoded output string @var{OUTPUT}. -@item -@tab reply @code{E}@var{NN} -@tab -Indicate a badly formed request. - -@item -@tab reply @samp{} -@tab -When @samp{q}@samp{Rcmd} is not recognized. - -@item symbol lookup -@tab @code{qSymbol::} -@tab -Notify the target that @value{GDBN} is prepared to serve symbol lookup -requests. Accept requests from the target for the values of symbols. -@item -@tab -@tab -@item -@tab reply @code{OK} -@tab -The target does not need to look up any (more) symbols. -@item -@tab reply @code{qSymbol:}@var{sym_name} -@tab -@sp 2 -@noindent -The target requests the value of symbol @var{sym_name} (hex encoded). -@value{GDBN} may provide the value by using the -@code{qSymbol:}@var{sym_value}:@var{sym_name} -message, described below. - -@item symbol value -@tab @code{qSymbol:}@var{sym_value}:@var{sym_name} -@tab -@sp 1 -@noindent -Set the value of SYM_NAME to SYM_VALUE. -@item -@tab -@tab -@var{sym_name} (hex encoded) is the name of a symbol whose value -the target has previously requested. -@item -@tab -@tab -@var{sym_value} (hex) is the value for symbol @var{sym_name}. -If @value{GDBN} cannot supply a value for @var{sym_name}, then this -field will be empty. -@item -@tab reply @code{OK} -@tab -The target does not need to look up any (more) symbols. -@item -@tab reply @code{qSymbol:}@var{sym_name} -@tab -@sp 2 -@noindent -The target requests the value of a new symbol @var{sym_name} (hex encoded). -@value{GDBN} will continue to supply the values of symbols (if available), -until the target ceases to request them. - -@end multitable - -The following @samp{g}/@samp{G} packets have previously been defined. -In the below, some thirty-two bit registers are transferred as sixty-four -bits. Those registers should be zero/sign extended (which?) to fill the -space allocated. Register bytes are transfered in target byte order. -The two nibbles within a register byte are transfered most-significant - -least-significant. - -@multitable @columnfractions .5 .5 - -@item MIPS32 -@tab -All registers are transfered as thirty-two bit quantities in the order: -32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point -registers; fsr; fir; fp. - -@item MIPS64 -@tab -All registers are transfered as sixty-four bit quantities (including -thirty-two bit registers such as @code{sr}). The ordering is the same -as @code{MIPS32}. - -@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 - - -@node Configurations -@chapter Configuration-Specific Information - -While nearly all @value{GDBN} commands are available for all native and -cross versions of the debugger, there are some exceptions. This chapter -describes things that are only available in certain configurations. - -There are three major categories of configurations: native -configurations, where the host and target are the same, embedded -operating system configurations, which are usually the same for several -different processor architectures, and bare embedded processors, which -are quite different from each other. - -@menu -* Native:: -* Embedded OS:: -* Embedded Processors:: -* Architectures:: -@end menu - -@node Native -@section Native - -This section describes details specific to particular native -configurations. - -@menu -* HP-UX:: HP-UX -* SVR4 Process Information:: SVR4 process information -* DJGPP Native:: Features specific to the DJGPP port -@end menu - -@node HP-UX -@subsection HP-UX - -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, @value{GDBN} searches for a user or system -name first, before it searches for a convenience variable. - -@node SVR4 Process Information -@subsection SVR4 process information - -@kindex /proc -@cindex process image - -Many versions of SVR4 provide a facility called @samp{/proc} that can be -used to examine the image of a running process using file-system -subroutines. If @value{GDBN} is configured for an operating system with -this facility, the command @code{info proc} is available to report on -several kinds of information about the process running your program. -@code{info proc} works only on SVR4 systems that include the -@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix, -and Unixware, but not HP-UX or Linux, for example. - -@table @code -@kindex info proc -@item info proc -Summarize available information about the process. - -@kindex info proc mappings -@item info proc mappings -Report on the address ranges accessible in the program, with information -on whether your program may read, write, or execute each range. -@ignore -@comment These sub-options of 'info proc' were not included when -@comment procfs.c was re-written. Keep their descriptions around -@comment against the day when someone finds the time to put them back in. -@kindex info proc times -@item info proc times -Starting time, user CPU time, and system CPU time for your program and -its children. - -@kindex info proc id -@item info proc id -Report on the process IDs related to your program: its own process ID, -the ID of its parent, the process group ID, and the session ID. - -@kindex info proc status -@item info proc status -General information on the state of the process. If the process is -stopped, this report includes the reason for stopping, and any signal -received. - -@item info proc all -Show all the above information about the process. -@end ignore -@end table - -@node DJGPP Native -@subsection Features for Debugging @sc{djgpp} Programs -@cindex @sc{djgpp} debugging -@cindex native @sc{djgpp} debugging -@cindex MS-DOS-specific commands - -@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and -MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs -that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on -top of real-mode DOS systems and their emulations. - -@value{GDBN} supports native debugging of @sc{djgpp} programs, and -defines a few commands specific to the @sc{djgpp} port. This -subsection describes those commands. - -@table @code -@kindex info dos -@item info dos -This is a prefix of @sc{djgpp}-specific commands which print -information about the target system and important OS structures. - -@kindex sysinfo -@cindex MS-DOS system info -@cindex free memory information (MS-DOS) -@item info dos sysinfo -This command displays assorted information about the underlying -platform: the CPU type and features, the OS version and flavor, the -DPMI version, and the available conventional and DPMI memory. - -@cindex GDT -@cindex LDT -@cindex IDT -@cindex segment descriptor tables -@cindex descriptor tables display -@item info dos gdt -@itemx info dos ldt -@itemx info dos idt -These 3 commands display entries from, respectively, Global, Local, -and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor -tables are data structures which store a descriptor for each segment -that is currently in use. The segment's selector is an index into a -descriptor table; the table entry for that index holds the -descriptor's base address and limit, and its attributes and access -rights. - -A typical @sc{djgpp} program uses 3 segments: a code segment, a data -segment (used for both data and the stack), and a DOS segment (which -allows access to DOS/BIOS data structures and absolute addresses in -conventional memory). However, the DPMI host will usually define -additional segments in order to support the DPMI environment. - -@cindex garbled pointers -These commands allow to display entries from the descriptor tables. -Without an argument, all entries from the specified table are -displayed. An argument, which should be an integer expression, means -display a single entry whose index is given by the argument. For -example, here's a convenient way to display information about the -debugged program's data segment: - -@smallexample -@exdent @code{(@value{GDBP}) info dos ldt $ds} -@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} -@end smallexample - -@noindent -This comes in handy when you want to see whether a pointer is outside -the data segment's limit (i.e.@: @dfn{garbled}). - -@cindex page tables display (MS-DOS) -@item info dos pde -@itemx info dos pte -These two commands display entries from, respectively, the Page -Directory and the Page Tables. Page Directories and Page Tables are -data structures which control how virtual memory addresses are mapped -into physical addresses. A Page Table includes an entry for every -page of memory that is mapped into the program's address space; there -may be several Page Tables, each one holding up to 4096 entries. A -Page Directory has up to 4096 entries, one each for every Page Table -that is currently in use. - -Without an argument, @kbd{info dos pde} displays the entire Page -Directory, and @kbd{info dos pte} displays all the entries in all of -the Page Tables. An argument, an integer expression, given to the -@kbd{info dos pde} command means display only that entry from the Page -Directory table. An argument given to the @kbd{info dos pte} command -means display entries from a single Page Table, the one pointed to by -the specified entry in the Page Directory. - -@cindex direct memory access (DMA) on MS-DOS -These commands are useful when your program uses @dfn{DMA} (Direct -Memory Access), which needs physical addresses to program the DMA -controller. - -These commands are supported only with some DPMI servers. - -@cindex physical address from linear address -@item info dos address-pte @var{addr} -This command displays the Page Table entry for a specified linear -address. The argument linear address @var{addr} should already have the -appropriate segment's base address added to it, because this command -accepts addresses which may belong to @emph{any} segment. For -example, here's how to display the Page Table entry for the page where -the variable @code{i} is stored: - -@smallexample -@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} -@exdent @code{Page Table entry for address 0x11a00d30:} -@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} -@end smallexample - -@noindent -This says that @code{i} is stored at offset @code{0xd30} from the page -whose physical base address is @code{0x02698000}, and prints all the -attributes of that page. - -Note that you must cast the addresses of variables to a @code{char *}, -since otherwise the value of @code{__djgpp_base_address}, the base -address of all variables and functions in a @sc{djgpp} program, will -be added using the rules of C pointer arithmetics: if @code{i} is -declared an @code{int}, @value{GDBN} will add 4 times the value of -@code{__djgpp_base_address} to the address of @code{i}. - -Here's another example, it displays the Page Table entry for the -transfer buffer: - -@smallexample -@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} -@exdent @code{Page Table entry for address 0x29110:} -@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} -@end smallexample - -@noindent -(The @code{+ 3} offset is because the transfer buffer's address is the -3rd member of the @code{_go32_info_block} structure.) The output of -this command clearly shows that addresses in conventional memory are -mapped 1:1, i.e.@: the physical and linear addresses are identical. - -This command is supported only with some DPMI servers. -@end table - -@node Embedded OS -@section Embedded Operating Systems - -This section describes configurations involving the debugging of -embedded operating systems that are available for several different -architectures. - -@menu -* VxWorks:: Using @value{GDBN} with VxWorks -@end menu - -@value{GDBN} includes the ability to debug programs running on -various real-time operating systems. - -@node VxWorks -@subsection Using @value{GDBN} with VxWorks - -@cindex VxWorks - -@table @code - -@kindex target vxworks -@item target vxworks @var{machinename} -A VxWorks system, attached via TCP/IP. The argument @var{machinename} -is the target system's machine name or IP address. - -@end table - -On VxWorks, @code{load} links @var{filename} dynamically on the -current target system as well as adding its symbols in @value{GDBN}. - -@value{GDBN} enables developers to spawn and debug tasks running on networked -VxWorks targets from a Unix host. Already-running tasks spawned from -the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on -both the Unix host and on the VxWorks target. The program -@code{@value{GDBP}} is installed and executed on the Unix host. (It may be -installed with the name @code{vxgdb}, to distinguish it from a -@value{GDBN} for debugging programs on the host itself.) - -@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{@value{GDBP}} (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 - -@noindent -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's data structures that reference the target system's symbol -table.) - -@node VxWorks Attach -@subsubsection Running tasks +@node VxWorks Attach +@subsubsection Running tasks @cindex running VxWorks tasks You can also attach to an existing task using the @code{attach} command as @@ -12007,2878 +11159,3729 @@ configurations. @table @code -@kindex target rdi -@item target rdi @var{dev} -ARM Angel monitor, via RDI library interface to ADP protocol. You may -use this target to communicate with both boards running the Angel -monitor, or with the EmbeddedICE JTAG debug device. - -@kindex target rdp -@item target rdp @var{dev} -ARM Demon monitor. +@kindex target rdi +@item target rdi @var{dev} +ARM Angel monitor, via RDI library interface to ADP protocol. You may +use this target to communicate with both boards running the Angel +monitor, or with the EmbeddedICE JTAG debug device. + +@kindex target rdp +@item target rdp @var{dev} +ARM Demon monitor. + +@end table + +@node H8/300 +@subsection Hitachi H8/300 + +@table @code + +@kindex target hms@r{, with H8/300} +@item target hms @var{dev} +A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. +Use special commands @code{device} and @code{speed} to control the serial +line and the communications speed used. + +@kindex target e7000@r{, with H8/300} +@item target e7000 @var{dev} +E7000 emulator for Hitachi H8 and SH. + +@kindex target sh3@r{, with H8/300} +@kindex target sh3e@r{, with H8/300} +@item target sh3 @var{dev} +@itemx target sh3e @var{dev} +Hitachi SH-3 and SH-3E target systems. + +@end table + +@cindex download to H8/300 or H8/500 +@cindex H8/300 or H8/500 download +@cindex download to Hitachi SH +@cindex Hitachi SH download +When you select remote debugging to a Hitachi SH, H8/300, or H8/500 +board, the @code{load} command downloads your program to the Hitachi +board and also opens it as the current executable target for +@value{GDBN} on your host (like the @code{file} command). + +@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 @value{GDBN} 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{GDBN}} command @samp{device @var{port}} if you +need to explicitly set the serial device. The default @var{port} is the +first available port on your host. This is only necessary on Unix +hosts, where it is typically something like @file{/dev/ttya}. + +@kindex speed +@cindex serial line speed, Hitachi micros +@code{@value{GDBN}} has another special command to set the communications +speed: @samp{speed @var{bps}}. This command also is only used from Unix +hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with +the DOS @code{mode} command (for instance, +@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection). + +The @samp{device} and @samp{speed} commands are available only when you +use a Unix host to debug your Hitachi microprocessor programs. If you +use a DOS host, +@value{GDBN} depends on an auxiliary terminate-and-stay-resident program +called @code{asynctsr} to communicate with the development board +through a PC serial port. You must also use the DOS @code{mode} command +to set up the serial port on the DOS side. + +The following sample session illustrates the steps needed to start a +program under @value{GDBN} control on an H8/300. The example uses a +sample H8/300 program called @file{t.x}. The procedure is the same for +the Hitachi SH and the H8/500. + +First hook up your development board. In this example, we use a +board attached to serial port @code{COM2}; if you use a different serial +port, substitute its name in the argument of the @code{mode} command. +When you call @code{asynctsr}, the auxiliary comms program used by the +debugger, you give it just the numeric part of the serial port's name; +for example, @samp{asyncstr 2} below runs @code{asyncstr} on +@code{COM2}. + +@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@r{, and serial protocol} +Now that serial communications are set up, and the development board is +connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with +the name of your program as the argument. @code{@value{GDBN}} prompts +you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special +commands to begin your debugging session: @samp{target hms} to specify +cross-debugging to the Hitachi board, and the @code{load} command to +download your program to the board. @code{load} displays the names of +the program's sections, and a @samp{*} for each 2K of data downloaded. +(If you want to refresh @value{GDBN} data on symbols or on the +executable file without downloading, use the @value{GDBN} commands +@code{file} or @code{symbol-file}. These commands, and @code{load} +itself, are described in @ref{Files,,Commands to specify files}.) + +@smallexample +(eg-C:\H8300\TEST) @value{GDBP} t.x +@value{GDBN} is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. +There is absolutely no warranty for @value{GDBN}; type "show warranty" +for details. +@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... +(@value{GDBP}) target hms +Connected to remote H8/300 HMS system. +(@value{GDBP}) load t.x +.text : 0x8000 .. 0xabde *********** +.data : 0xabde .. 0xad30 * +.stack : 0xf000 .. 0xf014 * +@end smallexample + +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@r{, with Hitachi ICE} +You can use the E7000 in-circuit emulator to develop code for either the +Hitachi SH or the H8/300H. Use one of these forms of the @samp{target +e7000} command to connect @value{GDBN} to your E7000: + +@table @code +@item target e7000 @var{port} @var{speed} +Use this form if your E7000 is connected to a serial port. The +@var{port} argument identifies what serial port to use (for example, +@samp{com2}). The third argument is the line speed in bits per second +(for example, @samp{9600}). + +@item target e7000 @var{hostname} +If your E7000 is installed as a host on a TCP/IP network, you can just +specify its hostname; @value{GDBN} uses @code{telnet} to connect. +@end table + +@node Hitachi Special +@subsubsection Special @value{GDBN} commands for Hitachi micros + +Some @value{GDBN} commands are available only for the H8/300: + +@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. @end table -@node H8/300 -@subsection Hitachi H8/300 +@node H8/500 +@subsection H8/500 @table @code -@kindex target hms@r{, with H8/300} -@item target hms @var{dev} -A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. -Use special commands @code{device} and @code{speed} to control the serial -line and the communications speed used. +@kindex set memory @var{mod} +@cindex memory models, H8/500 +@item set memory @var{mod} +@itemx show memory +Specify which H8/500 memory model (@var{mod}) you are using with +@samp{set memory}; check which memory model is in effect with @samp{show +memory}. The accepted values for @var{mod} are @code{small}, +@code{big}, @code{medium}, and @code{compact}. -@kindex target e7000@r{, with H8/300} -@item target e7000 @var{dev} -E7000 emulator for Hitachi H8 and SH. +@end table -@kindex target sh3@r{, with H8/300} -@kindex target sh3e@r{, with H8/300} -@item target sh3 @var{dev} -@itemx target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. +@node i960 +@subsection Intel i960 -@end table +@table @code -@cindex download to H8/300 or H8/500 -@cindex H8/300 or H8/500 download -@cindex download to Hitachi SH -@cindex Hitachi SH download -When you select remote debugging to a Hitachi SH, H8/300, or H8/500 -board, the @code{load} command downloads your program to the Hitachi -board and also opens it as the current executable target for -@value{GDBN} on your host (like the @code{file} command). +@kindex target mon960 +@item target mon960 @var{dev} +MON960 monitor for Intel i960. -@value{GDBN} needs to know these things to talk to your -Hitachi SH, H8/300, or H8/500: +@kindex target nindy +@item target nindy @var{devicename} +An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is +the name of the serial device to use for the connection, e.g. +@file{/dev/ttya}. -@enumerate +@end table + +@cindex Nindy +@cindex i960 +@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When +@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can +tell @value{GDBN} how to connect to the 960 in several ways: + +@itemize @bullet @item -that you want to use @samp{target hms}, the remote debugging interface -for Hitachi microprocessors, or @samp{target e7000}, the in-circuit -emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is -the default when @value{GDBN} is configured specifically for the Hitachi SH, -H8/300, or H8/500.) +Through command line options specifying serial port, version of the +Nindy protocol, and communications speed; @item -what serial device connects your host to your Hitachi board (the first -serial device available on your host is the default). +By responding to a prompt on startup; @item -what speed to use over the serial device. -@end enumerate +By using the @code{target} command at any point during your @value{GDBN} +session. @xref{Target Commands, ,Commands for managing targets}. + +@end itemize + +@cindex download to Nindy-960 +With the Nindy interface to an Intel 960 board, @code{load} +downloads @var{filename} to the 960 as well as adding its symbols in +@value{GDBN}. + +@menu +* 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 M32R/D +@subsection Mitsubishi M32R/D + +@table @code + +@kindex target m32r +@item target m32r @var{dev} +Mitsubishi M32R/D ROM monitor. + +@end table + +@node M68K +@subsection M68k + +The Motorola m68k configuration includes ColdFire support, and +target command for the following ROM monitors. + +@table @code + +@kindex target abug +@item target abug @var{dev} +ABug ROM monitor for M68K. + +@kindex target cpu32bug +@item target cpu32bug @var{dev} +CPU32BUG monitor, running on a CPU32 (M68K) board. + +@kindex target dbug +@item target dbug @var{dev} +dBUG ROM monitor for Motorola ColdFire. + +@kindex target est +@item target est @var{dev} +EST-300 ICE monitor, running on a CPU32 (M68K) board. + +@kindex target rom68k +@item target rom68k @var{dev} +ROM 68K monitor, running on an M68K IDP board. + +@end table + +If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will +instead have only a single special target command: + +@table @code + +@kindex target es1800 +@item target es1800 @var{dev} +ES-1800 emulator for M68K. + +@end table + +[context?] + +@table @code + +@kindex target rombug +@item target rombug @var{dev} +ROMBUG ROM monitor for OS/9000. + +@end table + +@node M88K +@subsection M88K + +@table @code + +@kindex target bug +@item target bug @var{dev} +BUG monitor, running on a MVME187 (m88k) board. + +@end table + +@node MIPS Embedded +@subsection MIPS Embedded + +@cindex MIPS boards +@value{GDBN} can use the MIPS remote debugging protocol to talk to a +MIPS board attached to a serial line. This is available when +you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. -@menu -* 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 +@need 1000 +Use these @value{GDBN} commands to specify the connection to your target board: -@node Hitachi Boards -@subsubsection Connecting to Hitachi boards +@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. -@c only for Unix hosts -@kindex device -@cindex serial device, Hitachi micros -Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you -need to explicitly set the serial device. The default @var{port} is the -first available port on your host. This is only necessary on Unix -hosts, where it is typically something like @file{/dev/ttya}. +For example, this sequence connects to the target board through a serial +port, and loads and runs a program called @var{prog} through the +debugger: -@kindex speed -@cindex serial line speed, Hitachi micros -@code{@value{GDBN}} has another special command to set the communications -speed: @samp{speed @var{bps}}. This command also is only used from Unix -hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with -the DOS @code{mode} command (for instance, -@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection). +@example +host$ @value{GDBP} @var{prog} +@value{GDBN} is free software and @dots{} +(@value{GDBP}) target mips /dev/ttyb +(@value{GDBP}) load @var{prog} +(@value{GDBP}) run +@end example -The @samp{device} and @samp{speed} commands are available only when you -use a Unix host to debug your Hitachi microprocessor programs. If you -use a DOS host, -@value{GDBN} depends on an auxiliary terminate-and-stay-resident program -called @code{asynctsr} to communicate with the development board -through a PC serial port. You must also use the DOS @code{mode} command -to set up the serial port on the DOS side. +@item target 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}}. -The following sample session illustrates the steps needed to start a -program under @value{GDBN} control on an H8/300. The example uses a -sample H8/300 program called @file{t.x}. The procedure is the same for -the Hitachi SH and the H8/500. +@item target pmon @var{port} +@kindex target pmon @var{port} +PMON ROM monitor. -First hook up your development board. In this example, we use a -board attached to serial port @code{COM2}; if you use a different serial -port, substitute its name in the argument of the @code{mode} command. -When you call @code{asynctsr}, the auxiliary comms program used by the -debugger, you give it just the numeric part of the serial port's name; -for example, @samp{asyncstr 2} below runs @code{asyncstr} on -@code{COM2}. +@item target ddb @var{port} +@kindex target ddb @var{port} +NEC's DDB variant of PMON for Vr4300. -@example -C:\H8300\TEST> asynctsr 2 -C:\H8300\TEST> mode com2:9600,n,8,1,p +@item target lsi @var{port} +@kindex target lsi @var{port} +LSI variant of PMON. -Resident portion of MODE loaded +@kindex target r3900 +@item target r3900 @var{dev} +Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. -COM2: 9600, n, 8, 1, p +@kindex target array +@item target array @var{dev} +Array Tech LSI33K RAID controller board. -@end example +@end table -@quotation -@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with -@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to -disable it, or even boot without it, to use @code{asynctsr} to control -your development board. -@end quotation -@kindex target hms@r{, and serial protocol} -Now that serial communications are set up, and the development board is -connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with -the name of your program as the argument. @code{@value{GDBN}} prompts -you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special -commands to begin your debugging session: @samp{target hms} to specify -cross-debugging to the Hitachi board, and the @code{load} command to -download your program to the board. @code{load} displays the names of -the program's sections, and a @samp{*} for each 2K of data downloaded. -(If you want to refresh @value{GDBN} data on symbols or on the -executable file without downloading, use the @value{GDBN} commands -@code{file} or @code{symbol-file}. These commands, and @code{load} -itself, are described in @ref{Files,,Commands to specify files}.) +@noindent +@value{GDBN} also supports these special commands for MIPS targets: -@smallexample -(eg-C:\H8300\TEST) @value{GDBP} t.x -@value{GDBN} is free software and you are welcome to distribute copies - of it under certain conditions; type "show copying" to see - the conditions. -There is absolutely no warranty for @value{GDBN}; type "show warranty" -for details. -@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... -(@value{GDBP}) target hms -Connected to remote H8/300 HMS system. -(@value{GDBP}) load t.x -.text : 0x8000 .. 0xabde *********** -.data : 0xabde .. 0xad30 * -.stack : 0xf000 .. 0xf014 * -@end smallexample +@table @code +@item set processor @var{args} +@itemx show processor +@kindex set processor @var{args} +@kindex show processor +Use the @code{set processor} command to set the type of MIPS +processor when you want to access processor-type-specific registers. +For example, @code{set processor @var{r3041}} tells @value{GDBN} +to use the CPU registers appropriate for the 3041 chip. +Use the @code{show processor} command to see what MIPS processor @value{GDBN} +is using. Use the @code{info reg} command to see what registers +@value{GDBN} is using. -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. +@item set mipsfpu double +@itemx set mipsfpu single +@itemx set mipsfpu none +@itemx show mipsfpu +@kindex set mipsfpu +@kindex show mipsfpu +@cindex MIPS remote floating point +@cindex floating point, MIPS remote +If your target board does not support the MIPS floating point +coprocessor, you should use the command @samp{set mipsfpu none} (if you +need this, you may wish to put the command in your @value{GDBN} init +file). This tells @value{GDBN} how to find the return value of +functions which return floating point values. It also allows +@value{GDBN} to avoid saving the floating point registers when calling +functions on the board. If you are using a floating point coprocessor +with only single precision floating point support, as on the @sc{r4650} +processor, use the command @samp{set mipsfpu single}. The default +double precision floating point coprocessor may be selected using +@samp{set mipsfpu double}. -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! +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. -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 +As usual, you can inquire about the @code{mipsfpu} variable with +@samp{show mipsfpu}. -@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 +@item set remotedebug @var{n} +@itemx show remotedebug +@kindex set remotedebug@r{, MIPS protocol} +@kindex show remotedebug@r{, MIPS protocol} +@cindex @code{remotedebug}, MIPS protocol +@cindex MIPS @code{remotedebug} protocol +@c FIXME! For this to be useful, you must know something about the MIPS +@c FIXME...protocol. Where is it described? +You can see some debugging information about communications with the board +by setting the @code{remotedebug} variable. If you set it to @code{1} using +@samp{set remotedebug 1}, every packet is displayed. If you set it +to @code{2}, every character is displayed. You can check the current value +at any time with the command @samp{show remotedebug}. -In either case, @value{GDBN} sees the effect of a @sc{reset} on the -development board as a ``normal exit'' of your program. +@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}.) -@node Hitachi ICE -@subsubsection Using the E7000 in-circuit emulator +The timeout set by @code{set timeout} does not apply when @value{GDBN} +is waiting for your program to stop. In that case, @value{GDBN} waits +forever because it has no way of knowing how long the program is going +to run before stopping. +@end table -@kindex target e7000@r{, with Hitachi ICE} -You can use the E7000 in-circuit emulator to develop code for either the -Hitachi SH or the H8/300H. Use one of these forms of the @samp{target -e7000} command to connect @value{GDBN} to your E7000: +@node PowerPC +@subsection PowerPC @table @code -@item target e7000 @var{port} @var{speed} -Use this form if your E7000 is connected to a serial port. The -@var{port} argument identifies what serial port to use (for example, -@samp{com2}). The third argument is the line speed in bits per second -(for example, @samp{9600}). -@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 +@kindex target dink32 +@item target dink32 @var{dev} +DINK32 ROM monitor. -@node Hitachi Special -@subsubsection Special @value{GDBN} commands for Hitachi micros +@kindex target ppcbug +@item target ppcbug @var{dev} +@kindex target ppcbug1 +@item target ppcbug1 @var{dev} +PPCBUG ROM monitor for PowerPC. -Some @value{GDBN} commands are available only for the H8/300: +@kindex target sds +@item target sds @var{dev} +SDS monitor, running on a PowerPC board (such as Motorola's ADS). + +@end table + +@node PA +@subsection HP PA Embedded @table @code -@kindex set machine -@kindex show machine -@item set machine h8300 -@itemx set machine h8300h -Condition @value{GDBN} for one of the two variants of the H8/300 -architecture with @samp{set machine}. You can use @samp{show machine} -to check which variant is currently in effect. +@kindex target op50n +@item target op50n @var{dev} +OP50N monitor, running on an OKI HPPA board. + +@kindex target w89k +@item target w89k @var{dev} +W89K monitor, running on a Winbond HPPA board. @end table -@node H8/500 -@subsection H8/500 +@node SH +@subsection Hitachi SH @table @code -@kindex set memory @var{mod} -@cindex memory models, H8/500 -@item set memory @var{mod} -@itemx show memory -Specify which H8/500 memory model (@var{mod}) you are using with -@samp{set memory}; check which memory model is in effect with @samp{show -memory}. The accepted values for @var{mod} are @code{small}, -@code{big}, @code{medium}, and @code{compact}. +@kindex target hms@r{, with Hitachi SH} +@item target hms @var{dev} +A Hitachi SH board attached via serial line to your host. Use special +commands @code{device} and @code{speed} to control the serial line and +the communications speed used. -@end table +@kindex target e7000@r{, with Hitachi SH} +@item target e7000 @var{dev} +E7000 emulator for Hitachi SH. -@node i960 -@subsection Intel i960 +@kindex target sh3@r{, with SH} +@kindex target sh3e@r{, with SH} +@item target sh3 @var{dev} +@item target sh3e @var{dev} +Hitachi SH-3 and SH-3E target systems. -@table @code +@end table -@kindex target mon960 -@item target mon960 @var{dev} -MON960 monitor for Intel i960. +@node Sparclet +@subsection Tsqware Sparclet -@kindex target nindy -@item target nindy @var{devicename} -An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is -the name of the serial device to use for the connection, e.g. -@file{/dev/ttya}. +@cindex Sparclet + +@value{GDBN} enables developers to debug tasks running on +Sparclet targets from a Unix host. +@value{GDBN} uses code that runs on +both the Unix host and on the Sparclet target. The program +@code{@value{GDBP}} is installed and executed on the Unix host. +@table @code +@item remotetimeout @var{args} +@kindex remotetimeout +@value{GDBN} supports the option @code{remotetimeout}. +This option is set by the user, and @var{args} represents the number of +seconds @value{GDBN} waits for responses. @end table -@cindex Nindy -@cindex i960 -@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When -@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can -tell @value{GDBN} how to connect to the 960 in several ways: +@cindex compiling, on Sparclet +When compiling for debugging, include the options @samp{-g} to get debug +information and @samp{-Ttext} to relocate the program to where you wish to +load it on the target. You may also want to add the options @samp{-n} or +@samp{-N} in order to reduce the size of the sections. Example: -@itemize @bullet -@item -Through command line options specifying serial port, version of the -Nindy protocol, and communications speed; +@example +sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N +@end example -@item -By responding to a prompt on startup; +You can use @code{objdump} to verify that the addresses are what you intended: -@item -By using the @code{target} command at any point during your @value{GDBN} -session. @xref{Target Commands, ,Commands for managing targets}. +@example +sparclet-aout-objdump --headers --syms prog +@end example -@end itemize +@cindex running, on Sparclet +Once you have set +your Unix execution search path to find @value{GDBN}, you are ready to +run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} +(or @code{sparclet-aout-gdb}, depending on your installation). -@cindex download to Nindy-960 -With the Nindy interface to an Intel 960 board, @code{load} -downloads @var{filename} to the 960 as well as adding its symbols in -@value{GDBN}. +@value{GDBN} comes up showing the prompt: + +@example +(gdbslet) +@end example @menu -* Nindy Startup:: Startup with Nindy -* Nindy Options:: Options for Nindy -* Nindy Reset:: Nindy reset command +* Sparclet File:: Setting the file to debug +* Sparclet Connection:: Connecting to Sparclet +* Sparclet Download:: Sparclet download +* Sparclet Execution:: Running and debugging @end menu -@node Nindy Startup -@subsubsection Startup with Nindy +@node Sparclet File +@subsubsection Setting file to debug -If you simply start @code{@value{GDBP}} without using any command-line -options, you are prompted for what serial port to use, @emph{before} you -reach the ordinary @value{GDBN} prompt: +The @value{GDBN} command @code{file} lets you choose with program to debug. @example -Attach /dev/ttyNN -- specify NN, or "quit" to quit: +(gdbslet) file prog @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}). +@need 1000 +@value{GDBN} then attempts to read the symbol table of @file{prog}. +@value{GDBN} locates +the file by searching the directories listed in the command search +path. +If the file was compiled with debug information (option "-g"), source +files will be searched as well. +@value{GDBN} locates +the source files by searching the directories listed in the directory search +path (@pxref{Environment, ,Your program's environment}). +If it fails +to find a file, it displays a message such as: -@node Nindy Options -@subsubsection Options for Nindy +@example +prog: No such file or directory. +@end example -These are the startup options for beginning your @value{GDBN} session with a -Nindy-960 board attached: +When this happens, add the appropriate directories to the search paths with +the @value{GDBN} commands @code{path} and @code{dir}, and execute the +@code{target} command again. -@table @code -@item -r @var{port} -Specify the serial port name of a serial interface to be used to connect -to the target system. This option is only available when @value{GDBN} is -configured for the Intel 960 target architecture. You may specify -@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a -device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique -suffix for a specific @code{tty} (e.g. @samp{-r a}). +@node Sparclet Connection +@subsubsection Connecting to Sparclet -@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. +The @value{GDBN} command @code{target} lets you connect to a Sparclet target. +To connect to a target on serial port ``@code{ttya}'', type: -@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 +@example +(gdbslet) target sparclet /dev/ttya +Remote target sparclet connected to /dev/ttya +main () at ../prog.c:3 +@end example -@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. +@need 750 +@value{GDBN} displays messages like these: -@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 +@example +Connected to ttya. +@end example -The standard @samp{-b} option controls the line speed used on the serial -port. +@node Sparclet Download +@subsubsection Sparclet download -@c @group -@node Nindy Reset -@subsubsection Nindy reset command +@cindex download to Sparclet +Once connected to the Sparclet target, +you can use the @value{GDBN} +@code{load} command to download the file from the host to the target. +The file name and load offset should be given as arguments to the @code{load} +command. +Since the file format is aout, the program must be loaded to the starting +address. You can use @code{objdump} to find out what this value is. The load +offset is an offset which is added to the VMA (virtual memory address) +of each of the file's sections. +For instance, if the program +@file{prog} was linked to text address 0x1201000, with data at 0x12010160 +and bss at 0x12010170, in @value{GDBN}, type: -@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 +@example +(gdbslet) load prog 0x12010000 +Loading section .text, size 0xdb0 vma 0x12010000 +@end example -@node M32R/D -@subsection Mitsubishi M32R/D +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 Sparclite +@subsection Fujitsu Sparclite @table @code -@kindex target m32r -@item target m32r @var{dev} -Mitsubishi M32R/D ROM monitor. +@kindex target sparclite +@item target sparclite @var{dev} +Fujitsu sparclite boards, used only for the purpose of loading. +You must use an additional command to debug the program. +For example: target remote @var{dev} using @value{GDBN} standard +remote protocol. @end table -@node M68K -@subsection M68k +@node ST2000 +@subsection Tandem ST2000 -The Motorola m68k configuration includes ColdFire support, and -target command for the following ROM monitors. +@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's +STDBUG protocol. -@table @code +To connect your ST2000 to the host system, see the manufacturer's +manual. Once the ST2000 is physically attached, you can run: -@kindex target abug -@item target abug @var{dev} -ABug ROM monitor for M68K. +@example +target st2000 @var{dev} @var{speed} +@end example -@kindex target cpu32bug -@item target cpu32bug @var{dev} -CPU32BUG monitor, running on a CPU32 (M68K) board. +@noindent +to establish it as your debugging environment. @var{dev} is normally +the name of a serial device, such as @file{/dev/ttya}, connected to the +ST2000 via a serial line. You can instead specify @var{dev} as a TCP +connection (for example, to a serial line attached via a terminal +concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. -@kindex target dbug -@item target dbug @var{dev} -dBUG ROM monitor for Motorola ColdFire. +The @code{load} and @code{attach} commands are @emph{not} defined for +this target; you must load your program into the ST2000 as you normally +would for standalone operation. @value{GDBN} reads debugging information +(such as symbols) from a separate, debugging version of the program +available on your host computer. +@c FIXME!! This is terribly vague; what little content is here is +@c basically hearsay. -@kindex target est -@item target est @var{dev} -EST-300 ICE monitor, running on a CPU32 (M68K) board. +@cindex ST2000 auxiliary commands +These auxiliary @value{GDBN} commands are available to help you with the ST2000 +environment: -@kindex target rom68k -@item target rom68k @var{dev} -ROM 68K monitor, running on an M68K IDP board. +@table @code +@item st2000 @var{command} +@kindex st2000 @var{cmd} +@cindex STDBUG commands (ST2000) +@cindex commands to STDBUG (ST2000) +Send a @var{command} to the STDBUG monitor. See the manufacturer's +manual for available commands. +@item connect +@cindex connect (to STDBUG) +Connect the controlling terminal to the STDBUG command monitor. When +you are done interacting with STDBUG, typing either of two character +sequences gets you back to the @value{GDBN} command prompt: +@kbd{@key{RET}~.} (Return, followed by tilde and period) or +@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). @end table -If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will -instead have only a single special target command: +@node Z8000 +@subsection Zilog Z8000 -@table @code +@cindex Z8000 +@cindex simulator, Z8000 +@cindex Zilog Z8000 simulator -@kindex target es1800 -@item target es1800 @var{dev} -ES-1800 emulator for M68K. +When configured for debugging Zilog Z8000 targets, @value{GDBN} includes +a Z8000 simulator. + +For the Z8000 family, @samp{target sim} simulates either the Z8002 (the +unsegmented variant of the Z8000 architecture) or the Z8001 (the +segmented variant). The simulator recognizes which architecture is +appropriate by inspecting the object code. +@table @code +@item target sim @var{args} +@kindex sim +@kindex target sim@r{, with Z8000} +Debug programs on a simulated CPU. If the simulator supports setup +options, specify them via @var{args}. @end table -[context?] +@noindent +After specifying this target, you can debug programs for the simulated +CPU in the same style as programs for your host computer; use the +@code{file} command to load a new program image, the @code{run} command +to run your program, and so on. + +As well as making available all the usual machine registers +(@pxref{Registers, ,Registers}), the Z8000 simulator provides three +additional items of information as specially named registers: @table @code -@kindex target rombug -@item target rombug @var{dev} -ROMBUG ROM monitor for OS/9000. +@item cycles +Counts clock-ticks in the simulator. -@end table +@item insts +Counts instructions run in the simulator. -@node M88K -@subsection M88K +@item time +Execution time in 60ths of a second. -@table @code +@end table -@kindex target bug -@item target bug @var{dev} -BUG monitor, running on a MVME187 (m88k) board. +You can refer to these values in @value{GDBN} expressions with the usual +conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a +conditional breakpoint that suspends only after at least 5000 +simulated clock ticks. -@end table +@node Architectures +@section Architectures -@node MIPS Embedded -@subsection MIPS Embedded +This section describes characteristics of architectures that affect +all uses of @value{GDBN} with the architecture, both native and cross. -@cindex MIPS boards -@value{GDBN} can use the MIPS remote debugging protocol to talk to a -MIPS board attached to a serial line. This is available when -you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. +@menu +* A29K:: +* Alpha:: +* MIPS:: +@end menu -@need 1000 -Use these @value{GDBN} commands to specify the connection to your target board: +@node A29K +@subsection A29K @table @code -@item target mips @var{port} -@kindex target mips @var{port} -To run a program on the board, start up @code{@value{GDBP}} with the -name of your program as the argument. To connect to the board, use the -command @samp{target mips @var{port}}, where @var{port} is the name of -the serial port connected to the board. If the program has not already -been downloaded to the board, you may use the @code{load} command to -download it. You can then use all the usual @value{GDBN} commands. -For example, this sequence connects to the target board through a serial -port, and loads and runs a program called @var{prog} through the -debugger: +@kindex set rstack_high_address +@cindex AMD 29K register stack +@cindex register stack, AMD29K +@item set rstack_high_address @var{address} +On AMD 29000 family processors, registers are saved in a separate +@dfn{register stack}. There is no way for @value{GDBN} to determine the +extent of this stack. Normally, @value{GDBN} just assumes that the +stack is ``large enough''. This may result in @value{GDBN} referencing +memory locations that do not exist. If necessary, you can get around +this problem by specifying the ending address of the register stack with +the @code{set rstack_high_address} command. The argument should be an +address, which you probably want to precede with @samp{0x} to specify in +hexadecimal. -@example -host$ @value{GDBP} @var{prog} -@value{GDBN} is free software and @dots{} -(@value{GDBP}) target mips /dev/ttyb -(@value{GDBP}) load @var{prog} -(@value{GDBP}) run -@end example +@kindex show rstack_high_address +@item show rstack_high_address +Display the current limit of the register stack, on AMD 29000 family +processors. -@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}}. +@end table -@item target pmon @var{port} -@kindex target pmon @var{port} -PMON ROM monitor. +@node Alpha +@subsection Alpha -@item target ddb @var{port} -@kindex target ddb @var{port} -NEC's DDB variant of PMON for Vr4300. +See the following section. -@item target lsi @var{port} -@kindex target lsi @var{port} -LSI variant of PMON. +@node MIPS +@subsection MIPS -@kindex target r3900 -@item target r3900 @var{dev} -Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. +@cindex stack on Alpha +@cindex stack on MIPS +@cindex Alpha stack +@cindex MIPS stack +Alpha- and MIPS-based computers use an unusual stack frame, which +sometimes requires @value{GDBN} to search backward in the object code to +find the beginning of a function. -@kindex target array -@item target array @var{dev} -Array Tech LSI33K RAID controller board. +@cindex response time, MIPS debugging +To improve response time (especially for embedded applications, where +@value{GDBN} may be restricted to a slow serial line for this search) +you may want to limit the size of this search, using one of these +commands: -@end table +@table @code +@cindex @code{heuristic-fence-post} (Alpha, MIPS) +@item set heuristic-fence-post @var{limit} +Restrict @value{GDBN} to examining at most @var{limit} bytes in its +search for the beginning of a function. A value of @var{0} (the +default) means there is no limit. However, except for @var{0}, the +larger the limit the more bytes @code{heuristic-fence-post} must search +and therefore the longer it takes to run. +@item show heuristic-fence-post +Display the current limit. +@end table @noindent -@value{GDBN} also supports these special commands for MIPS targets: +These commands are available @emph{only} when @value{GDBN} is configured +for debugging programs on Alpha or MIPS processors. -@table @code -@item set processor @var{args} -@itemx show processor -@kindex set processor @var{args} -@kindex show processor -Use the @code{set processor} command to set the type of MIPS -processor when you want to access processor-type-specific registers. -For example, @code{set processor @var{r3041}} tells @value{GDBN} -to use the CPU registers appropriate for the 3041 chip. -Use the @code{show processor} command to see what MIPS processor @value{GDBN} -is using. Use the @code{info reg} command to see what registers -@value{GDBN} is using. -@item set mipsfpu double -@itemx set mipsfpu single -@itemx set mipsfpu none -@itemx show mipsfpu -@kindex set mipsfpu -@kindex show mipsfpu -@cindex MIPS remote floating point -@cindex floating point, MIPS remote -If your target board does not support the MIPS floating point -coprocessor, you should use the command @samp{set mipsfpu none} (if you -need this, you may wish to put the command in your @value{GDBN} init -file). This tells @value{GDBN} how to find the return value of -functions which return floating point values. It also allows -@value{GDBN} to avoid saving the floating point registers when calling -functions on the board. If you are using a floating point coprocessor -with only single precision floating point support, as on the @sc{r4650} -processor, use the command @samp{set mipsfpu single}. The default -double precision floating point coprocessor may be selected using -@samp{set mipsfpu double}. +@node Controlling GDB +@chapter Controlling @value{GDBN} + +You can alter the way @value{GDBN} interacts with you by using the +@code{set} command. For commands controlling how @value{GDBN} displays +data, see @ref{Print Settings, ,Print settings}. Other settings are +described here. + +@menu +* Prompt:: Prompt +* Editing:: Command editing +* History:: Command history +* Screen Size:: Screen size +* Numbers:: Numbers +* Messages/Warnings:: Optional warnings and messages +* Debugging Output:: Optional messages about internal happenings +@end menu + +@node Prompt +@section Prompt -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. +@cindex prompt -As usual, you can inquire about the @code{mipsfpu} variable with -@samp{show mipsfpu}. +@value{GDBN} indicates its readiness to read a command by printing a string +called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You +can change the prompt string with the @code{set prompt} command. For +instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change +the prompt in one of the @value{GDBN} sessions so that you can always tell +which one you are talking to. -@item set remotedebug @var{n} -@itemx show remotedebug -@kindex set remotedebug@r{, MIPS protocol} -@kindex show remotedebug@r{, MIPS protocol} -@cindex @code{remotedebug}, MIPS protocol -@cindex MIPS @code{remotedebug} protocol -@c FIXME! For this to be useful, you must know something about the MIPS -@c FIXME...protocol. Where is it described? -You can see some debugging information about communications with the board -by setting the @code{remotedebug} variable. If you set it to @code{1} using -@samp{set remotedebug 1}, every packet is displayed. If you set it -to @code{2}, every character is displayed. You can check the current value -at any time with the command @samp{show remotedebug}. +@emph{Note:} @code{set prompt} does not add a space for you after the +prompt you set. This allows you to set a prompt which ends in a space +or a prompt that does not. -@item 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}.) +@table @code +@kindex set prompt +@item set prompt @var{newprompt} +Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. -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. +@kindex show prompt +@item show prompt +Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} @end table -@node PowerPC -@subsection PowerPC +@node Editing +@section Command editing +@cindex readline +@cindex command line editing -@table @code +@value{GDBN} reads its input commands via the @dfn{readline} interface. This +@sc{gnu} library provides consistent behavior for programs which provide a +command line interface to the user. Advantages are @sc{gnu} Emacs-style +or @dfn{vi}-style inline editing of commands, @code{csh}-like history +substitution, and a storage and recall of command history across +debugging sessions. -@kindex target dink32 -@item target dink32 @var{dev} -DINK32 ROM monitor. +You may control the behavior of command line editing in @value{GDBN} with the +command @code{set}. -@kindex target ppcbug -@item target ppcbug @var{dev} -@kindex target ppcbug1 -@item target ppcbug1 @var{dev} -PPCBUG ROM monitor for PowerPC. +@table @code +@kindex set editing +@cindex editing +@item set editing +@itemx set editing on +Enable command line editing (enabled by default). -@kindex target sds -@item target sds @var{dev} -SDS monitor, running on a PowerPC board (such as Motorola's ADS). +@item set editing off +Disable command line editing. +@kindex show editing +@item show editing +Show whether command line editing is enabled. @end table -@node PA -@subsection HP PA Embedded +@node History +@section Command history + +@value{GDBN} can keep track of the commands you type during your +debugging sessions, so that you can be certain of precisely what +happened. Use these commands to manage the @value{GDBN} command +history facility. @table @code +@cindex history substitution +@cindex history file +@kindex set history filename +@kindex GDBHISTFILE +@item set history filename @var{fname} +Set the name of the @value{GDBN} command history file to @var{fname}. +This is the file where @value{GDBN} reads an initial command history +list, and where it writes the command history from this session when it +exits. You can access this list through history expansion or through +the history command editing characters listed below. This file defaults +to the value of the environment variable @code{GDBHISTFILE}, or to +@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable +is not set. -@kindex target op50n -@item target op50n @var{dev} -OP50N monitor, running on an OKI HPPA board. +@cindex history save +@kindex set history save +@item set history save +@itemx set history save on +Record command history in a file, whose name may be specified with the +@code{set history filename} command. By default, this option is disabled. -@kindex target w89k -@item target w89k @var{dev} -W89K monitor, running on a Winbond HPPA board. +@item set history save off +Stop recording command history in a file. +@cindex history size +@kindex set history size +@item set history size @var{size} +Set the number of commands which @value{GDBN} keeps in its history list. +This defaults to the value of the environment variable +@code{HISTSIZE}, or to 256 if this variable is not set. @end table -@node SH -@subsection Hitachi SH +@cindex history expansion +History expansion assigns special meaning to the character @kbd{!}. +@ifset have-readline-appendices +@xref{Event Designators}. +@end ifset + +Since @kbd{!} is also the logical not operator in C, history expansion +is off by default. If you decide to enable history expansion with the +@code{set history expansion on} command, you may sometimes need to +follow @kbd{!} (when it is used as logical not, in an expression) with +a space or a tab to prevent it from being expanded. The readline +history facilities do not attempt substitution on the strings +@kbd{!=} and @kbd{!(}, even when history expansion is enabled. + +The commands to control history expansion are: @table @code +@kindex set history expansion +@item set history expansion on +@itemx set history expansion +Enable history expansion. History expansion is off by default. -@kindex target hms@r{, with Hitachi SH} -@item target hms @var{dev} -A Hitachi SH board attached via serial line to your host. Use special -commands @code{device} and @code{speed} to control the serial line and -the communications speed used. +@item set history expansion off +Disable history expansion. -@kindex target e7000@r{, with Hitachi SH} -@item target e7000 @var{dev} -E7000 emulator for Hitachi SH. +The readline code comes with more complete documentation of +editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs +or @code{vi} may wish to read it. +@ifset have-readline-appendices +@xref{Command Line Editing}. +@end ifset -@kindex target sh3@r{, with SH} -@kindex target sh3e@r{, with SH} -@item target sh3 @var{dev} -@item target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. +@c @group +@kindex show history +@item show history +@itemx show history filename +@itemx show history save +@itemx show history size +@itemx show history expansion +These commands display the state of the @value{GDBN} history parameters. +@code{show history} by itself displays all four states. +@c @end group +@end table + +@table @code +@kindex shows +@item show commands +Display the last ten commands in the command history. +@item show commands @var{n} +Print ten commands centered on command number @var{n}. + +@item show commands + +Print ten commands just after the commands last printed. @end table -@node Sparclet -@subsection Tsqware Sparclet +@node Screen Size +@section Screen size +@cindex size of screen +@cindex pauses in output -@cindex Sparclet +Certain commands to @value{GDBN} may produce large amounts of +information output to the screen. To help you read all of it, +@value{GDBN} pauses and asks you for input at the end of each page of +output. Type @key{RET} when you want to continue the output, or @kbd{q} +to discard the remaining output. Also, the screen width setting +determines when to wrap lines of output. Depending on what is being +printed, @value{GDBN} tries to break the line at a readable place, +rather than simply letting it overflow onto the following line. + +Normally @value{GDBN} knows the size of the screen from the terminal +driver software. For example, on Unix @value{GDBN} uses the termcap data base +together with the value of the @code{TERM} environment variable and the +@code{stty rows} and @code{stty cols} settings. If this is not correct, +you can override it with the @code{set height} and @code{set +width} commands: + +@table @code +@kindex set height +@kindex set width +@kindex show width +@kindex show height +@item set height @var{lpp} +@itemx show height +@itemx set width @var{cpl} +@itemx show width +These @code{set} commands specify a screen height of @var{lpp} lines and +a screen width of @var{cpl} characters. The associated @code{show} +commands display the current settings. -@value{GDBN} enables developers to debug tasks running on -Sparclet targets from a Unix host. -@value{GDBN} uses code that runs on -both the Unix host and on the Sparclet target. The program -@code{@value{GDBP}} is installed and executed on the Unix host. +If you specify a height of zero lines, @value{GDBN} does not pause during +output no matter how long the output is. This is useful if output is to a +file or to an editor buffer. -@table @code -@item remotetimeout @var{args} -@kindex remotetimeout -@value{GDBN} supports the option @code{remotetimeout}. -This option is set by the user, and @var{args} represents the number of -seconds @value{GDBN} waits for responses. +Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} +from wrapping its output. @end table -@cindex compiling, on Sparclet -When compiling for debugging, include the options @samp{-g} to get debug -information and @samp{-Ttext} to relocate the program to where you wish to -load it on the target. You may also want to add the options @samp{-n} or -@samp{-N} in order to reduce the size of the sections. Example: - -@example -sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N -@end example +@node Numbers +@section Numbers +@cindex number representation +@cindex entering numbers -You can use @code{objdump} to verify that the addresses are what you intended: +You can always enter numbers in octal, decimal, or hexadecimal in +@value{GDBN} by the usual conventions: octal numbers begin with +@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers +begin with @samp{0x}. Numbers that begin with none of these are, by +default, entered in base 10; likewise, the default display for +numbers---when no particular format is specified---is base 10. You can +change the default base for both input and output with the @code{set +radix} command. -@example -sparclet-aout-objdump --headers --syms prog -@end example +@table @code +@kindex set input-radix +@item set input-radix @var{base} +Set the default base for numeric input. Supported choices +for @var{base} are decimal 8, 10, or 16. @var{base} must itself be +specified either unambiguously or using the current default radix; for +example, any of -@cindex running, on Sparclet -Once you have set -your Unix execution search path to find @value{GDBN}, you are ready to -run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} -(or @code{sparclet-aout-gdb}, depending on your installation). +@smallexample +set radix 012 +set radix 10. +set radix 0xa +@end smallexample -@value{GDBN} comes up showing the prompt: +@noindent +sets the base to decimal. On the other hand, @samp{set radix 10} +leaves the radix unchanged no matter what it was. -@example -(gdbslet) -@end example +@kindex set output-radix +@item set output-radix @var{base} +Set the default base for numeric display. Supported choices +for @var{base} are decimal 8, 10, or 16. @var{base} must itself be +specified either unambiguously or using the current default radix. -@menu -* Sparclet File:: Setting the file to debug -* Sparclet Connection:: Connecting to Sparclet -* Sparclet Download:: Sparclet download -* Sparclet Execution:: Running and debugging -@end menu +@kindex show input-radix +@item show input-radix +Display the current default base for numeric input. -@node Sparclet File -@subsubsection Setting file to debug +@kindex show output-radix +@item show output-radix +Display the current default base for numeric display. +@end table -The @value{GDBN} command @code{file} lets you choose with program to debug. +@node Messages/Warnings +@section Optional warnings and messages -@example -(gdbslet) file prog -@end example +By default, @value{GDBN} is silent about its inner workings. If you are +running on a slow machine, you may want to use the @code{set verbose} +command. This makes @value{GDBN} tell you when it does a lengthy +internal operation, so you will not think it has crashed. -@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: +Currently, the messages controlled by @code{set verbose} are those +which announce that the symbol table for a source file is being read; +see @code{symbol-file} in @ref{Files, ,Commands to specify files}. -@example -prog: No such file or directory. -@end example +@table @code +@kindex set verbose +@item set verbose on +Enables @value{GDBN} output of certain informational messages. -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. +@item set verbose off +Disables @value{GDBN} output of certain informational messages. -@node Sparclet Connection -@subsubsection Connecting to Sparclet +@kindex show verbose +@item show verbose +Displays whether @code{set verbose} is on or off. +@end table -The @value{GDBN} command @code{target} lets you connect to a Sparclet target. -To connect to a target on serial port ``@code{ttya}'', type: +By default, if @value{GDBN} encounters bugs in the symbol table of an +object file, it is silent; but if you are debugging a compiler, you may +find this information useful (@pxref{Symbol Errors, ,Errors reading +symbol files}). -@example -(gdbslet) target sparclet /dev/ttya -Remote target sparclet connected to /dev/ttya -main () at ../prog.c:3 -@end example +@table @code -@need 750 -@value{GDBN} displays messages like these: +@kindex set complaints +@item set complaints @var{limit} +Permits @value{GDBN} to output @var{limit} complaints about each type of +unusual symbols before becoming silent about the problem. Set +@var{limit} to zero to suppress all complaints; set it to a large number +to prevent complaints from being suppressed. -@example -Connected to ttya. -@end example +@kindex show complaints +@item show complaints +Displays how many symbol complaints @value{GDBN} is permitted to produce. -@node Sparclet Download -@subsubsection Sparclet download +@end table -@cindex download to Sparclet -Once connected to the Sparclet target, -you can use the @value{GDBN} -@code{load} command to download the file from the host to the target. -The file name and load offset should be given as arguments to the @code{load} -command. -Since the file format is aout, the program must be loaded to the starting -address. You can use @code{objdump} to find out what this value is. The load -offset is an offset which is added to the VMA (virtual memory address) -of each of the file's sections. -For instance, if the program -@file{prog} was linked to text address 0x1201000, with data at 0x12010160 -and bss at 0x12010170, in @value{GDBN}, type: +By default, @value{GDBN} is cautious, and asks what sometimes seems to be a +lot of stupid questions to confirm certain commands. For example, if +you try to run a program which is already running: @example -(gdbslet) load prog 0x12010000 -Loading section .text, size 0xdb0 vma 0x12010000 +(@value{GDBP}) run +The program being debugged has been started already. +Start it from the beginning? (y or n) @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. +If you are willing to unflinchingly face the consequences of your own +commands, you can disable this ``feature'': -@node Sparclet Execution -@subsubsection Running and debugging +@table @code -@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. +@kindex set confirm +@cindex flinching +@cindex confirmation +@cindex stupid questions +@item set confirm off +Disables confirmation requests. -@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 +@item set confirm on +Enables confirmation requests (the default). -@node Sparclite -@subsection Fujitsu Sparclite +@kindex show confirm +@item show confirm +Displays state of confirmation requests. + +@end table +@node Debugging Output +@section Optional messages about internal happenings @table @code +@kindex set debug arch +@item set debug arch +Turns on or off display of gdbarch debugging info. The default is off +@kindex show debug arch +@item show debug arch +Displays the current state of displaying gdbarch debugging info. +@kindex set debug event +@item set debug event +Turns on or off display of @value{GDBN} event debugging info. The +default is off. +@kindex show debug event +@item show debug event +Displays the current state of displaying @value{GDBN} event debugging +info. +@kindex set debug expression +@item set debug expression +Turns on or off display of @value{GDBN} expression debugging info. The +default is off. +@kindex show debug expression +@item show debug expression +Displays the current state of displaying @value{GDBN} expression +debugging info. +@kindex set debug overload +@item set debug overload +Turns on or off display of @value{GDBN} C@t{++} overload debugging +info. This includes info such as ranking of functions, etc. The default +is off. +@kindex show debug overload +@item show debug overload +Displays the current state of displaying @value{GDBN} C@t{++} overload +debugging info. +@kindex set debug remote +@cindex packets, reporting on stdout +@cindex serial connections, debugging +@item set debug remote +Turns on or off display of reports on all packets sent back and forth across +the serial line to the remote machine. The info is printed on the +@value{GDBN} standard output stream. The default is off. +@kindex show debug remote +@item show debug remote +Displays the state of display of remote packets. +@kindex set debug serial +@item set debug serial +Turns on or off display of @value{GDBN} serial debugging info. The +default is off. +@kindex show debug serial +@item show debug serial +Displays the current state of displaying @value{GDBN} serial debugging +info. +@kindex set debug target +@item set debug target +Turns on or off display of @value{GDBN} target debugging info. This info +includes what is going on at the target level of GDB, as it happens. The +default is off. +@kindex show debug target +@item show debug target +Displays the current state of displaying @value{GDBN} target debugging +info. +@kindex set debug varobj +@item set debug varobj +Turns on or off display of @value{GDBN} variable object debugging +info. The default is off. +@kindex show debug varobj +@item show debug varobj +Displays the current state of displaying @value{GDBN} variable object +debugging info. +@end table -@kindex target sparclite -@item target sparclite @var{dev} -Fujitsu sparclite boards, used only for the purpose of loading. -You must use an additional command to debug the program. -For example: target remote @var{dev} using @value{GDBN} standard -remote protocol. +@node Sequences +@chapter Canned Sequences of Commands -@end table +Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint +command lists}), @value{GDBN} provides two ways to store sequences of +commands for execution as a unit: user-defined commands and command +files. -@node ST2000 -@subsection Tandem ST2000 +@menu +* Define:: User-defined commands +* Hooks:: User-defined command hooks +* Command Files:: Command files +* Output:: Commands for controlled output +@end menu -@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's -STDBUG protocol. +@node Define +@section User-defined commands -To connect your ST2000 to the host system, see the manufacturer's -manual. Once the ST2000 is physically attached, you can run: +@cindex user-defined command +A @dfn{user-defined command} is a sequence of @value{GDBN} commands to +which you assign a new name as a command. This is done with the +@code{define} command. User commands may accept up to 10 arguments +separated by whitespace. Arguments are accessed within the user command +via @var{$arg0@dots{}$arg9}. A trivial example: -@example -target st2000 @var{dev} @var{speed} -@end example +@smallexample +define adder + print $arg0 + $arg1 + $arg2 +@end smallexample @noindent -to establish it as your debugging environment. @var{dev} is normally -the name of a serial device, such as @file{/dev/ttya}, connected to the -ST2000 via a serial line. You can instead specify @var{dev} as a TCP -connection (for example, to a serial line attached via a terminal -concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. +To execute the command use: -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. +@smallexample +adder 1 2 3 +@end smallexample -@cindex ST2000 auxiliary commands -These auxiliary @value{GDBN} commands are available to help you with the ST2000 -environment: +@noindent +This defines the command @code{adder}, which prints the sum of +its three arguments. Note the arguments are text substitutions, so they may +reference variables, use complex expressions, or even perform inferior +functions calls. @table @code -@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 Z8000 -@subsection Zilog Z8000 - -@cindex 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. +@kindex define +@item define @var{commandname} +Define a command named @var{commandname}. If there is already a command +by that name, you are asked to confirm that you want to redefine it. -@table @code -@item target sim @var{args} -@kindex sim -@kindex target sim@r{, with Z8000} -Debug programs on a simulated CPU. If the simulator supports setup -options, specify them via @var{args}. -@end table +The definition of the command is made up of other @value{GDBN} command lines, +which are given following the @code{define} command. The end of these +commands is marked by a line containing @code{end}. -@noindent -After specifying this target, you can debug programs for the simulated -CPU in the same style as programs for your host computer; use the -@code{file} command to load a new program image, the @code{run} command -to run your program, and so on. +@kindex if +@kindex else +@item if +Takes a single argument, which is an expression to evaluate. +It is followed by a series of commands that are executed +only if the expression is true (nonzero). +There can then optionally be a line @code{else}, followed +by a series of commands that are only executed if the expression +was false. The end of the list is marked by a line containing @code{end}. -As well as making available all the usual machine registers -(@pxref{Registers, ,Registers}), the Z8000 simulator provides three -additional items of information as specially named registers: +@kindex while +@item while +The syntax is similar to @code{if}: the command takes a single argument, +which is an expression to evaluate, and must be followed by the commands to +execute, one per line, terminated by an @code{end}. +The commands are executed repeatedly as long as the expression +evaluates to true. -@table @code +@kindex document +@item document @var{commandname} +Document the user-defined command @var{commandname}, so that it can be +accessed by @code{help}. The command @var{commandname} must already be +defined. This command reads lines of documentation just as @code{define} +reads the lines of the command definition, ending with @code{end}. +After the @code{document} command is finished, @code{help} on command +@var{commandname} displays the documentation you have written. -@item cycles -Counts clock-ticks in the simulator. +You may use the @code{document} command again to change the +documentation of a command. Redefining the command with @code{define} +does not change the documentation. -@item insts -Counts instructions run in the simulator. +@kindex help user-defined +@item help user-defined +List all user-defined commands, with the first line of the documentation +(if any) for each. -@item time -Execution time in 60ths of a second. +@kindex show user +@item show user +@itemx show user @var{commandname} +Display the @value{GDBN} commands used to define @var{commandname} (but +not its documentation). If no @var{commandname} is given, display the +definitions for all user-defined commands. @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. +When user-defined commands are executed, the +commands of the definition are not printed. An error in any command +stops execution of the user-defined command. -@node Architectures -@section Architectures +If used interactively, commands that would ask for confirmation proceed +without asking when used inside a user-defined command. Many @value{GDBN} +commands that normally print messages to say what they are doing omit the +messages when used in a user-defined command. -This section describes characteristics of architectures that affect -all uses of @value{GDBN} with the architecture, both native and cross. +@node Hooks +@section User-defined command hooks +@cindex command hooks +@cindex hooks, for commands +@cindex hooks, pre-command -@menu -* A29K:: -* Alpha:: -* MIPS:: -@end menu +@kindex hook +@kindex hook- +You may define @dfn{hooks}, which are a special kind of user-defined +command. Whenever you run the command @samp{foo}, if the user-defined +command @samp{hook-foo} exists, it is executed (with no arguments) +before that command. -@node A29K -@subsection A29K +@cindex hooks, post-command +@kindex hookpost +@kindex hookpost- +A hook may also be defined which is run after the command you executed. +Whenever you run the command @samp{foo}, if the user-defined command +@samp{hookpost-foo} exists, it is executed (with no arguments) after +that command. Post-execution hooks may exist simultaneously with +pre-execution hooks, for the same command. -@table @code +It is valid for a hook to call the command which it hooks. If this +occurs, the hook is not re-executed, thereby avoiding infinte recursion. -@kindex set rstack_high_address -@cindex AMD 29K register stack -@cindex register stack, AMD29K -@item set rstack_high_address @var{address} -On AMD 29000 family processors, registers are saved in a separate -@dfn{register stack}. There is no way for @value{GDBN} to determine the -extent of this stack. Normally, @value{GDBN} just assumes that the -stack is ``large enough''. This may result in @value{GDBN} referencing -memory locations that do not exist. If necessary, you can get around -this problem by specifying the ending address of the register stack with -the @code{set rstack_high_address} command. The argument should be an -address, which you probably want to precede with @samp{0x} to specify in -hexadecimal. +@c It would be nice if hookpost could be passed a parameter indicating +@c if the command it hooks executed properly or not. FIXME! -@kindex show rstack_high_address -@item show rstack_high_address -Display the current limit of the register stack, on AMD 29000 family -processors. +@kindex stop@r{, a pseudo-command} +In addition, a pseudo-command, @samp{stop} exists. Defining +(@samp{hook-stop}) makes the associated commands execute every time +execution stops in your program: before breakpoint commands are run, +displays are printed, or the stack frame is printed. -@end table +For example, to ignore @code{SIGALRM} signals while +single-stepping, but treat them normally during normal execution, +you could define: -@node Alpha -@subsection Alpha +@example +define hook-stop +handle SIGALRM nopass +end -See the following section. +define hook-run +handle SIGALRM pass +end -@node MIPS -@subsection MIPS +define hook-continue +handle SIGLARM pass +end +@end example -@cindex stack on Alpha -@cindex stack on MIPS -@cindex Alpha stack -@cindex MIPS stack -Alpha- and MIPS-based computers use an unusual stack frame, which -sometimes requires @value{GDBN} to search backward in the object code to -find the beginning of a function. +As a further example, to hook at the begining and end of the @code{echo} +command, and to add extra text to the beginning and end of the message, +you could define: -@cindex response time, MIPS debugging -To improve response time (especially for embedded applications, where -@value{GDBN} may be restricted to a slow serial line for this search) -you may want to limit the size of this search, using one of these -commands: +@example +define hook-echo +echo <<<--- +end -@table @code -@cindex @code{heuristic-fence-post} (Alpha, MIPS) -@item set heuristic-fence-post @var{limit} -Restrict @value{GDBN} to examining at most @var{limit} bytes in its -search for the beginning of a function. A value of @var{0} (the -default) means there is no limit. However, except for @var{0}, the -larger the limit the more bytes @code{heuristic-fence-post} must search -and therefore the longer it takes to run. +define hookpost-echo +echo --->>>\n +end -@item show heuristic-fence-post -Display the current limit. -@end table +(@value{GDBP}) echo Hello World +<<<---Hello World--->>> +(@value{GDBP}) -@noindent -These commands are available @emph{only} when @value{GDBN} is configured -for debugging programs on Alpha or MIPS processors. +@end example +You can define a hook for any single-word command in @value{GDBN}, but +not for command aliases; you should define a hook for the basic command +name, e.g. @code{backtrace} rather than @code{bt}. +@c FIXME! So how does Joe User discover whether a command is an alias +@c or not? +If an error occurs during the execution of your hook, execution of +@value{GDBN} commands stops and @value{GDBN} issues a prompt +(before the command that you actually typed had a chance to run). -@node Controlling GDB -@chapter Controlling @value{GDBN} +If you try to define a hook which does not match any known command, you +get a warning from the @code{define} command. -You can alter the way @value{GDBN} interacts with you by using the -@code{set} command. For commands controlling how @value{GDBN} displays -data, see @ref{Print Settings, ,Print settings}. Other settings are -described here. +@node Command Files +@section Command files -@menu -* Prompt:: Prompt -* Editing:: Command editing -* History:: Command history -* Screen Size:: Screen size -* Numbers:: Numbers -* Messages/Warnings:: Optional warnings and messages -* Debugging Output:: Optional messages about internal happenings -@end menu +@cindex command files +A command file for @value{GDBN} is a file of lines that are @value{GDBN} +commands. Comments (lines starting with @kbd{#}) may also be included. +An empty line in a command file does nothing; it does not mean to repeat +the last command, as it would from the terminal. -@node Prompt -@section Prompt +@cindex init file +@cindex @file{.gdbinit} +@cindex @file{gdb.ini} +When you start @value{GDBN}, it automatically executes commands from its +@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP +port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the +limitations of file names imposed by DOS filesystems.}. +During startup, @value{GDBN} does the following: -@cindex prompt +@enumerate +@item +Reads the init file (if any) in your home directory@footnote{On +DOS/Windows systems, the home directory is the one pointed to by the +@code{HOME} environment variable.}. -@value{GDBN} indicates its readiness to read a command by printing a string -called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You -can change the prompt string with the @code{set prompt} command. For -instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change -the prompt in one of the @value{GDBN} sessions so that you can always tell -which one you are talking to. +@item +Processes command line options and operands. -@emph{Note:} @code{set prompt} does not add a space for you after the -prompt you set. This allows you to set a prompt which ends in a space -or a prompt that does not. +@item +Reads the init file (if any) in the current working directory. -@table @code -@kindex set prompt -@item set prompt @var{newprompt} -Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. +@item +Reads command files specified by the @samp{-x} option. +@end enumerate -@kindex show prompt -@item show prompt -Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} -@end table +The init file in your home directory can set options (such as @samp{set +complaints}) that affect subsequent processing of command line options +and operands. Init files are not executed if you use the @samp{-nx} +option (@pxref{Mode Options, ,Choosing modes}). -@node Editing -@section Command editing -@cindex readline -@cindex command line editing +@cindex init file name +On some configurations of @value{GDBN}, the init file is known by a +different name (these are typically environments where a specialized +form of @value{GDBN} may need to coexist with other forms, hence a +different name for the specialized version's init file). These are the +environments with special init file names: -@value{GDBN} reads its input commands via the @dfn{readline} interface. This -@sc{gnu} library provides consistent behavior for programs which provide a -command line interface to the user. Advantages are @sc{gnu} Emacs-style -or @dfn{vi}-style inline editing of commands, @code{csh}-like history -substitution, and a storage and recall of command history across -debugging sessions. +@cindex @file{.vxgdbinit} +@itemize @bullet +@item +VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit} -You may control the behavior of command line editing in @value{GDBN} with the -command @code{set}. +@cindex @file{.os68gdbinit} +@item +OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit} -@table @code -@kindex set editing -@cindex editing -@item set editing -@itemx set editing on -Enable command line editing (enabled by default). +@cindex @file{.esgdbinit} +@item +ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit} +@end itemize -@item set editing off -Disable command line editing. +You can also request the execution of a command file with the +@code{source} command: -@kindex show editing -@item show editing -Show whether command line editing is enabled. +@table @code +@kindex source +@item source @var{filename} +Execute the command file @var{filename}. @end table -@node History -@section Command history - -@value{GDBN} can keep track of the commands you type during your -debugging sessions, so that you can be certain of precisely what -happened. Use these commands to manage the @value{GDBN} command -history facility. - -@table @code -@cindex history substitution -@cindex history file -@kindex set history filename -@kindex GDBHISTFILE -@item set history filename @var{fname} -Set the name of the @value{GDBN} command history file to @var{fname}. -This is the file where @value{GDBN} reads an initial command history -list, and where it writes the command history from this session when it -exits. You can access this list through history expansion or through -the history command editing characters listed below. This file defaults -to the value of the environment variable @code{GDBHISTFILE}, or to -@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable -is not set. +The lines in a command file are executed sequentially. They are not +printed as they are executed. An error in any command terminates execution +of the command file. -@cindex history save -@kindex set history save -@item set history save -@itemx set history save on -Record command history in a file, whose name may be specified with the -@code{set history filename} command. By default, this option is disabled. +Commands that would ask for confirmation if used interactively proceed +without asking when used in a command file. Many @value{GDBN} commands that +normally print messages to say what they are doing omit the messages +when called from command files. -@item set history save off -Stop recording command history in a file. +@value{GDBN} also accepts command input from standard input. In this +mode, normal output goes to standard output and error output goes to +standard error. Errors in a command file supplied on standard input do +not terminate execution of the command file --- execution continues with +the next command. -@cindex history size -@kindex set history size -@item set history size @var{size} -Set the number of commands which @value{GDBN} keeps in its history list. -This defaults to the value of the environment variable -@code{HISTSIZE}, or to 256 if this variable is not set. -@end table +@example +gdb < cmds > log 2>&1 +@end example -@cindex history expansion -History expansion assigns special meaning to the character @kbd{!}. -@ifset have-readline-appendices -@xref{Event Designators}. -@end ifset +(The syntax above will vary depending on the shell used.) This example +will execute commands from the file @file{cmds}. All output and errors +would be directed to @file{log}. -Since @kbd{!} is also the logical not operator in C, history expansion -is off by default. If you decide to enable history expansion with the -@code{set history expansion on} command, you may sometimes need to -follow @kbd{!} (when it is used as logical not, in an expression) with -a space or a tab to prevent it from being expanded. The readline -history facilities do not attempt substitution on the strings -@kbd{!=} and @kbd{!(}, even when history expansion is enabled. +@node Output +@section Commands for controlled output -The commands to control history expansion are: +During the execution of a command file or a user-defined command, normal +@value{GDBN} output is suppressed; the only output that appears is what is +explicitly printed by the commands in the definition. This section +describes three commands useful for generating exactly the output you +want. @table @code -@kindex set history expansion -@item set history expansion on -@itemx set history expansion -Enable history expansion. History expansion is off by default. - -@item set history expansion off -Disable history expansion. +@kindex echo +@item echo @var{text} +@c I do not consider backslash-space a standard C escape sequence +@c because it is not in ANSI. +Print @var{text}. Nonprinting characters can be included in +@var{text} using C escape sequences, such as @samp{\n} to print a +newline. @strong{No newline is printed unless you specify one.} +In addition to the standard C escape sequences, a backslash followed +by a space stands for a space. This is useful for displaying a +string with spaces at the beginning or the end, since leading and +trailing spaces are otherwise trimmed from all arguments. +To print @samp{@w{ }and foo =@w{ }}, use the command +@samp{echo \@w{ }and foo = \@w{ }}. -The readline code comes with more complete documentation of -editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs -or @code{vi} may wish to read it. -@ifset have-readline-appendices -@xref{Command Line Editing}. -@end ifset +A backslash at the end of @var{text} can be used, as in C, to continue +the command onto subsequent lines. For example, -@c @group -@kindex show history -@item show history -@itemx show history filename -@itemx show history save -@itemx show history size -@itemx show history expansion -These commands display the state of the @value{GDBN} history parameters. -@code{show history} by itself displays all four states. -@c @end group -@end table +@example +echo This is some text\n\ +which is continued\n\ +onto several lines.\n +@end example -@table @code -@kindex shows -@item show commands -Display the last ten commands in the command history. +produces the same output as -@item show commands @var{n} -Print ten commands centered on command number @var{n}. +@example +echo This is some text\n +echo which is continued\n +echo onto several lines.\n +@end example -@item show commands + -Print ten commands just after the commands last printed. -@end table +@kindex output +@item output @var{expression} +Print the value of @var{expression} and nothing but that value: no +newlines, no @samp{$@var{nn} = }. The value is not entered in the +value history either. @xref{Expressions, ,Expressions}, for more information +on expressions. -@node Screen Size -@section Screen size -@cindex size of screen -@cindex pauses in output +@item output/@var{fmt} @var{expression} +Print the value of @var{expression} in format @var{fmt}. You can use +the same formats as for @code{print}. @xref{Output Formats,,Output +formats}, for more information. -Certain commands to @value{GDBN} may produce large amounts of -information output to the screen. To help you read all of it, -@value{GDBN} pauses and asks you for input at the end of each page of -output. Type @key{RET} when you want to continue the output, or @kbd{q} -to discard the remaining output. Also, the screen width setting -determines when to wrap lines of output. Depending on what is being -printed, @value{GDBN} tries to break the line at a readable place, -rather than simply letting it overflow onto the following line. +@kindex printf +@item printf @var{string}, @var{expressions}@dots{} +Print the values of the @var{expressions} under the control of +@var{string}. The @var{expressions} are separated by commas and may be +either numbers or pointers. Their values are printed as specified by +@var{string}, exactly as if your program were to execute the C +subroutine +@c FIXME: the above implies that at least all ANSI C formats are +@c supported, but it isn't true: %E and %G don't work (or so it seems). +@c Either this is a bug, or the manual should document what formats are +@c supported. -Normally @value{GDBN} knows the size of the screen from the terminal -driver software. For example, on Unix @value{GDBN} uses the termcap data base -together with the value of the @code{TERM} environment variable and the -@code{stty rows} and @code{stty cols} settings. If this is not correct, -you can override it with the @code{set height} and @code{set -width} commands: +@example +printf (@var{string}, @var{expressions}@dots{}); +@end example -@table @code -@kindex set height -@kindex set width -@kindex show width -@kindex show height -@item set height @var{lpp} -@itemx show height -@itemx set width @var{cpl} -@itemx show width -These @code{set} commands specify a screen height of @var{lpp} lines and -a screen width of @var{cpl} characters. The associated @code{show} -commands display the current settings. +For example, you can print two values in hex like this: -If you specify a height of zero lines, @value{GDBN} does not pause during -output no matter how long the output is. This is useful if output is to a -file or to an editor buffer. +@smallexample +printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo +@end smallexample -Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} -from wrapping its output. +The only backslash-escape sequences that you can use in the format +string are the simple ones that consist of backslash followed by a +letter. @end table -@node Numbers -@section Numbers -@cindex number representation -@cindex entering numbers - -You can always enter numbers in octal, decimal, or hexadecimal in -@value{GDBN} by the usual conventions: octal numbers begin with -@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers -begin with @samp{0x}. Numbers that begin with none of these are, by -default, entered in base 10; likewise, the default display for -numbers---when no particular format is specified---is base 10. You can -change the default base for both input and output with the @code{set -radix} command. +@node TUI +@chapter @value{GDBN} Text User Interface +@cindex TUI -@table @code -@kindex set input-radix -@item set input-radix @var{base} -Set the default base for numeric input. Supported choices -for @var{base} are decimal 8, 10, or 16. @var{base} must itself be -specified either unambiguously or using the current default radix; for -example, any of +@menu +* TUI Overview:: TUI overview +* TUI Keys:: TUI key bindings +* TUI Commands:: TUI specific commands +* TUI Configuration:: TUI configuration variables +@end menu -@smallexample -set radix 012 -set radix 10. -set radix 0xa -@end smallexample +The @value{GDBN} Text User Interface, TUI in short, +is a terminal interface which uses the @code{curses} library +to show the source file, the assembly output, the program registers +and @value{GDBN} commands in separate text windows. +The TUI is available only when @value{GDBN} is configured +with the @code{--enable-tui} configure option (@pxref{Configure Options}). -@noindent -sets the base to decimal. On the other hand, @samp{set radix 10} -leaves the radix unchanged no matter what it was. +@node TUI Overview +@section TUI overview -@kindex set output-radix -@item set output-radix @var{base} -Set the default base for numeric display. Supported choices -for @var{base} are decimal 8, 10, or 16. @var{base} must itself be -specified either unambiguously or using the current default radix. +The TUI has two display modes that can be switched while +@value{GDBN} runs: -@kindex show input-radix -@item show input-radix -Display the current default base for numeric input. +@itemize @bullet +@item +A curses (or TUI) mode in which it displays several text +windows on the terminal. -@kindex show output-radix -@item show output-radix -Display the current default base for numeric display. -@end table +@item +A standard mode which corresponds to the @value{GDBN} configured without +the TUI. +@end itemize -@node Messages/Warnings -@section Optional warnings and messages +In the TUI mode, @value{GDBN} can display several text window +on the terminal: -By default, @value{GDBN} is silent about its inner workings. If you are -running on a slow machine, you may want to use the @code{set verbose} -command. This makes @value{GDBN} tell you when it does a lengthy -internal operation, so you will not think it has crashed. +@table @emph +@item command +This window is the @value{GDBN} command window with the @value{GDBN} +prompt and the @value{GDBN} outputs. The @value{GDBN} input is still +managed using readline but through the TUI. The @emph{command} +window is always visible. -Currently, the messages controlled by @code{set verbose} are those -which announce that the symbol table for a source file is being read; -see @code{symbol-file} in @ref{Files, ,Commands to specify files}. +@item source +The source window shows the source file of the program. The current +line as well as active breakpoints are displayed in this window. +The current program position is shown with the @samp{>} marker and +active breakpoints are shown with @samp{*} markers. -@table @code -@kindex set verbose -@item set verbose on -Enables @value{GDBN} output of certain informational messages. +@item assembly +The assembly window shows the disassembly output of the program. -@item set verbose off -Disables @value{GDBN} output of certain informational messages. +@item register +This window shows the processor registers. It detects when +a register is changed and when this is the case, registers that have +changed are highlighted. -@kindex show verbose -@item show verbose -Displays whether @code{set verbose} is on or off. @end table -By default, if @value{GDBN} encounters bugs in the symbol table of an -object file, it is silent; but if you are debugging a compiler, you may -find this information useful (@pxref{Symbol Errors, ,Errors reading -symbol files}). +The source, assembly and register windows are attached to the thread +and the frame position. They are updated when the current thread +changes, when the frame changes or when the program counter changes. +These three windows are arranged by the TUI according to several +layouts. The layout defines which of these three windows are visible. +The following layouts are available: -@table @code +@itemize @bullet +@item +source -@kindex set complaints -@item set complaints @var{limit} -Permits @value{GDBN} to output @var{limit} complaints about each type of -unusual symbols before becoming silent about the problem. Set -@var{limit} to zero to suppress all complaints; set it to a large number -to prevent complaints from being suppressed. +@item +assembly + +@item +source and assembly + +@item +source and registers -@kindex show complaints -@item show complaints -Displays how many symbol complaints @value{GDBN} is permitted to produce. +@item +assembly and registers -@end table +@end itemize -By default, @value{GDBN} is cautious, and asks what sometimes seems to be a -lot of stupid questions to confirm certain commands. For example, if -you try to run a program which is already running: +@node TUI Keys +@section TUI Key Bindings +@cindex TUI key bindings -@example -(@value{GDBP}) run -The program being debugged has been started already. -Start it from the beginning? (y or n) -@end example +The TUI installs several key bindings in the readline keymaps +(@pxref{Command Line Editing}). +They allow to leave or enter in the TUI mode or they operate +directly on the TUI layout and windows. The following key bindings +are installed for both TUI mode and the @value{GDBN} standard mode. -If you are willing to unflinchingly face the consequences of your own -commands, you can disable this ``feature'': +@table @kbd +@kindex C-x C-a +@item C-x C-a +@kindex C-x a +@itemx C-x a +@kindex C-x A +@itemx C-x A +Enter or leave the TUI mode. When the TUI mode is left, +the curses window management is left and @value{GDBN} operates using +its standard mode writing on the terminal directly. When the TUI +mode is entered, the control is given back to the curses windows. +The screen is then refreshed. -@table @code +@kindex C-x 1 +@item C-x 1 +Use a TUI layout with only one window. The layout will +either be @samp{source} or @samp{assembly}. When the TUI mode +is not active, it will switch to the TUI mode. -@kindex set confirm -@cindex flinching -@cindex confirmation -@cindex stupid questions -@item set confirm off -Disables confirmation requests. +Think of this key binding as the Emacs @kbd{C-x 1} binding. -@item set confirm on -Enables confirmation requests (the default). +@kindex C-x 2 +@item C-x 2 +Use a TUI layout with at least two windows. When the current +layout shows already two windows, a next layout with two windows is used. +When a new layout is chosen, one window will always be common to the +previous layout and the new one. -@kindex show confirm -@item show confirm -Displays state of confirmation requests. +Think of it as the Emacs @kbd{C-x 2} binding. @end table -@node Debugging Output -@section Optional messages about internal happenings -@table @code -@kindex set debug arch -@item set debug arch -Turns on or off display of gdbarch debugging info. The default is off -@kindex show debug arch -@item show debug arch -Displays the current state of displaying gdbarch debugging info. -@kindex set debug event -@item set debug event -Turns on or off display of @value{GDBN} event debugging info. The -default is off. -@kindex show debug event -@item show debug event -Displays the current state of displaying @value{GDBN} event debugging -info. -@kindex set debug expression -@item set debug expression -Turns on or off display of @value{GDBN} expression debugging info. The -default is off. -@kindex show debug expression -@item show debug expression -Displays the current state of displaying @value{GDBN} expression -debugging info. -@kindex set debug overload -@item set debug overload -Turns on or off display of @value{GDBN} C@t{++} overload debugging -info. This includes info such as ranking of functions, etc. The default -is off. -@kindex show debug overload -@item show debug overload -Displays the current state of displaying @value{GDBN} C@t{++} overload -debugging info. -@kindex set debug remote -@cindex packets, reporting on stdout -@cindex serial connections, debugging -@item set debug remote -Turns on or off display of reports on all packets sent back and forth across -the serial line to the remote machine. The info is printed on the -@value{GDBN} standard output stream. The default is off. -@kindex show debug remote -@item show debug remote -Displays the state of display of remote packets. -@kindex set debug serial -@item set debug serial -Turns on or off display of @value{GDBN} serial debugging info. The -default is off. -@kindex show debug serial -@item show debug serial -Displays the current state of displaying @value{GDBN} serial debugging -info. -@kindex set debug target -@item set debug target -Turns on or off display of @value{GDBN} target debugging info. This info -includes what is going on at the target level of GDB, as it happens. The -default is off. -@kindex show debug target -@item show debug target -Displays the current state of displaying @value{GDBN} target debugging -info. -@kindex set debug varobj -@item set debug varobj -Turns on or off display of @value{GDBN} variable object debugging -info. The default is off. -@kindex show debug varobj -@item show debug varobj -Displays the current state of displaying @value{GDBN} variable object -debugging info. -@end table +The following key bindings are handled only by the TUI mode: -@node Sequences -@chapter Canned Sequences of Commands +@table @key +@kindex PgUp +@item PgUp +Scroll the active window one page up. -Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint -command lists}), @value{GDBN} provides two ways to store sequences of -commands for execution as a unit: user-defined commands and command -files. +@kindex PgDn +@item PgDn +Scroll the active window one page down. -@menu -* Define:: User-defined commands -* Hooks:: User-defined command hooks -* Command Files:: Command files -* Output:: Commands for controlled output -@end menu +@kindex Up +@item Up +Scroll the active window one line up. -@node Define -@section User-defined commands +@kindex Down +@item Down +Scroll the active window one line down. -@cindex user-defined command -A @dfn{user-defined command} is a sequence of @value{GDBN} commands to -which you assign a new name as a command. This is done with the -@code{define} command. User commands may accept up to 10 arguments -separated by whitespace. Arguments are accessed within the user command -via @var{$arg0@dots{}$arg9}. A trivial example: +@kindex Left +@item Left +Scroll the active window one column left. -@smallexample -define adder - print $arg0 + $arg1 + $arg2 -@end smallexample +@kindex Right +@item Right +Scroll the active window one column right. -@noindent -To execute the command use: +@kindex C-L +@item C-L +Refresh the screen. -@smallexample -adder 1 2 3 -@end smallexample +@end table -@noindent -This defines the command @code{adder}, which prints the sum of -its three arguments. Note the arguments are text substitutions, so they may -reference variables, use complex expressions, or even perform inferior -functions calls. +In the TUI mode, the arrow keys are used by the active window +for scrolling. This means they are not available for readline. It is +necessary to use other readline key bindings such as @key{C-p}, @key{C-n}, +@key{C-b} and @key{C-f}. + +@node TUI Commands +@section TUI specific commands +@cindex TUI commands + +The TUI has specific commands to control the text windows. +These commands are always available, that is they do not depend on +the current terminal mode in which @value{GDBN} runs. When @value{GDBN} +is in the standard mode, using these commands will automatically switch +in the TUI mode. @table @code +@item layout next +@kindex layout next +Display the next layout. -@kindex define -@item define @var{commandname} -Define a command named @var{commandname}. If there is already a command -by that name, you are asked to confirm that you want to redefine it. +@item layout prev +@kindex layout prev +Display the previous layout. -The definition of the command is made up of other @value{GDBN} command lines, -which are given following the @code{define} command. The end of these -commands is marked by a line containing @code{end}. +@item layout src +@kindex layout src +Display the source window only. -@kindex if -@kindex else -@item if -Takes a single argument, which is an expression to evaluate. -It is followed by a series of commands that are executed -only if the expression is true (nonzero). -There can then optionally be a line @code{else}, followed -by a series of commands that are only executed if the expression -was false. The end of the list is marked by a line containing @code{end}. +@item layout asm +@kindex layout asm +Display the assembly window only. -@kindex while -@item while -The syntax is similar to @code{if}: the command takes a single argument, -which is an expression to evaluate, and must be followed by the commands to -execute, one per line, terminated by an @code{end}. -The commands are executed repeatedly as long as the expression -evaluates to true. +@item layout split +@kindex layout split +Display the source and assembly window. -@kindex document -@item document @var{commandname} -Document the user-defined command @var{commandname}, so that it can be -accessed by @code{help}. The command @var{commandname} must already be -defined. This command reads lines of documentation just as @code{define} -reads the lines of the command definition, ending with @code{end}. -After the @code{document} command is finished, @code{help} on command -@var{commandname} displays the documentation you have written. +@item layout regs +@kindex layout regs +Display the register window together with the source or assembly window. + +@item focus next | prev | src | asm | regs | split +@kindex focus +Set the focus to the named window. +This command allows to change the active window so that scrolling keys +can be affected to another window. -You may use the @code{document} command again to change the -documentation of a command. Redefining the command with @code{define} -does not change the documentation. +@item refresh +@kindex refresh +Refresh the screen. This is similar to using @key{C-L} key. -@kindex help user-defined -@item help user-defined -List all user-defined commands, with the first line of the documentation -(if any) for each. +@item update +@kindex update +Update the source window and the current execution point. -@kindex show user -@item show user -@itemx show user @var{commandname} -Display the @value{GDBN} commands used to define @var{commandname} (but -not its documentation). If no @var{commandname} is given, display the -definitions for all user-defined commands. +@item winheight @var{name} +@var{count} +@itemx winheight @var{name} -@var{count} +@kindex winheight +Change the height of the window @var{name} by @var{count} +lines. Positive counts increase the height, while negative counts +decrease it. @end table -When user-defined commands are executed, the -commands of the definition are not printed. An error in any command -stops execution of the user-defined command. +@node TUI Configuration +@section TUI configuration variables +@cindex TUI configuration variables -If used interactively, commands that would ask for confirmation proceed -without asking when used inside a user-defined command. Many @value{GDBN} -commands that normally print messages to say what they are doing omit the -messages when used in a user-defined command. +The TUI has several configuration variables that control the +appearance of windows on the terminal. -@node Hooks -@section User-defined command hooks -@cindex command hooks -@cindex hooks, for commands -@cindex hooks, pre-command +@table @code +@item set tui border-kind @var{kind} +@kindex set tui border-kind +Select the border appearance for the source, assembly and register windows. +The possible values are the following: +@table @code +@item space +Use a space character to draw the border. -@kindex hook -@kindex hook- -You may define @dfn{hooks}, which are a special kind of user-defined -command. Whenever you run the command @samp{foo}, if the user-defined -command @samp{hook-foo} exists, it is executed (with no arguments) -before that command. +@item ascii +Use ascii characters + - and | to draw the border. -@cindex hooks, post-command -@kindex hookpost -@kindex hookpost- -A hook may also be defined which is run after the command you executed. -Whenever you run the command @samp{foo}, if the user-defined command -@samp{hookpost-foo} exists, it is executed (with no arguments) after -that command. Post-execution hooks may exist simultaneously with -pre-execution hooks, for the same command. +@item acs +Use the Alternate Character Set to draw the border. The border is +drawn using character line graphics if the terminal supports them. -It is valid for a hook to call the command which it hooks. If this -occurs, the hook is not re-executed, thereby avoiding infinte recursion. +@end table -@c It would be nice if hookpost could be passed a parameter indicating -@c if the command it hooks executed properly or not. FIXME! +@item set tui active-border-mode @var{mode} +@kindex set tui active-border-mode +Select the attributes to display the border of the active window. +The possible values are @code{normal}, @code{standout}, @code{reverse}, +@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}. -@kindex stop@r{, a pseudo-command} -In addition, a pseudo-command, @samp{stop} exists. Defining -(@samp{hook-stop}) makes the associated commands execute every time -execution stops in your program: before breakpoint commands are run, -displays are printed, or the stack frame is printed. +@item set tui border-mode @var{mode} +@kindex set tui border-mode +Select the attributes to display the border of other windows. +The @var{mode} can be one of the following: +@table @code +@item normal +Use normal attributes to display the border. -For example, to ignore @code{SIGALRM} signals while -single-stepping, but treat them normally during normal execution, -you could define: +@item standout +Use standout mode. -@example -define hook-stop -handle SIGALRM nopass -end +@item reverse +Use reverse video mode. -define hook-run -handle SIGALRM pass -end +@item half +Use half bright mode. -define hook-continue -handle SIGLARM pass -end -@end example +@item half-standout +Use half bright and standout mode. -As a further example, to hook at the begining and end of the @code{echo} -command, and to add extra text to the beginning and end of the message, -you could define: +@item bold +Use extra bright or bold mode. -@example -define hook-echo -echo <<<--- -end +@item bold-standout +Use extra bright or bold and standout mode. -define hookpost-echo -echo --->>>\n -end +@end table -(@value{GDBP}) echo Hello World -<<<---Hello World--->>> -(@value{GDBP}) +@end table -@end example +@node Emacs +@chapter Using @value{GDBN} under @sc{gnu} Emacs -You can define a hook for any single-word command in @value{GDBN}, but -not for command aliases; you should define a hook for the basic command -name, e.g. @code{backtrace} rather than @code{bt}. -@c FIXME! So how does Joe User discover whether a command is an alias -@c or not? -If an error occurs during the execution of your hook, execution of -@value{GDBN} commands stops and @value{GDBN} issues a prompt -(before the command that you actually typed had a chance to run). +@cindex Emacs +@cindex @sc{gnu} Emacs +A special interface allows you to use @sc{gnu} Emacs to view (and +edit) the source files for the program you are debugging with +@value{GDBN}. -If you try to define a hook which does not match any known command, you -get a warning from the @code{define} command. +To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the +executable file you want to debug as an argument. This command starts +@value{GDBN} as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. +@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) -@node Command Files -@section Command files +Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two +things: -@cindex command files -A command file for @value{GDBN} is a file of lines that are @value{GDBN} -commands. Comments (lines starting with @kbd{#}) may also be included. -An empty line in a command file does nothing; it does not mean to repeat -the last command, as it would from the terminal. +@itemize @bullet +@item +All ``terminal'' input and output goes through the Emacs buffer. +@end itemize -@cindex init file -@cindex @file{.gdbinit} -@cindex @file{gdb.ini} -When you start @value{GDBN}, it automatically executes commands from its -@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP -port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the -limitations of file names imposed by DOS filesystems.}. -During startup, @value{GDBN} does the following: +This applies both to @value{GDBN} commands and their output, and to the input +and output done by the program you are debugging. -@enumerate -@item -Reads the init file (if any) in your home directory@footnote{On -DOS/Windows systems, the home directory is the one pointed to by the -@code{HOME} environment variable.}. +This is useful because it means that you can copy the text of previous +commands and input them again; you can even use parts of the output +in this way. -@item -Processes command line options and operands. +All the facilities of Emacs' Shell mode are available for interacting +with your program. In particular, you can send signals the usual +way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a +stop. +@itemize @bullet @item -Reads the init file (if any) in the current working directory. +@value{GDBN} displays source code through Emacs. +@end itemize -@item -Reads command files specified by the @samp{-x} option. -@end enumerate +Each time @value{GDBN} displays a stack frame, Emacs automatically finds the +source file for that frame and puts an arrow (@samp{=>}) at the +left margin of the current line. Emacs uses a separate buffer for +source display, and splits the screen to show both your @value{GDBN} session +and the source. -The init file in your home directory can set options (such as @samp{set -complaints}) that affect subsequent processing of command line options -and operands. Init files are not executed if you use the @samp{-nx} -option (@pxref{Mode Options, ,Choosing modes}). +Explicit @value{GDBN} @code{list} or search commands still produce output as +usual, but you probably have no reason to use them from Emacs. -@cindex init file name -On some configurations of @value{GDBN}, the init file is known by a -different name (these are typically environments where a specialized -form of @value{GDBN} may need to coexist with other forms, hence a -different name for the specialized version's init file). These are the -environments with special init file names: +@quotation +@emph{Warning:} If the directory where your program resides is not your +current directory, it can be easy to confuse Emacs about the location of +the source files, in which case the auxiliary display buffer does not +appear to show your source. @value{GDBN} can find programs by searching your +environment's @code{PATH} variable, so the @value{GDBN} input and output +session proceeds normally; but Emacs does not get enough information +back from @value{GDBN} to locate the source files in this situation. To +avoid this problem, either start @value{GDBN} mode from the directory where +your program resides, or specify an absolute file name when prompted for the +@kbd{M-x gdb} argument. -@cindex @file{.vxgdbinit} -@itemize @bullet -@item -VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit} +A similar confusion can result if you use the @value{GDBN} @code{file} command to +switch to debugging a program in some other location, from an existing +@value{GDBN} buffer in Emacs. +@end quotation + +By default, @kbd{M-x gdb} calls the program called @file{gdb}. If +you need to call @value{GDBN} by a different name (for example, if you keep +several configurations around, with different names) you can set the +Emacs variable @code{gdb-command-name}; for example, + +@example +(setq gdb-command-name "mygdb") +@end example + +@noindent +(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or +in your @file{.emacs} file) makes Emacs call the program named +``@code{mygdb}'' instead. + +In the @value{GDBN} I/O buffer, you can use these special Emacs commands in +addition to the standard Shell mode commands: -@cindex @file{.os68gdbinit} -@item -OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit} +@table @kbd +@item C-h m +Describe the features of Emacs' @value{GDBN} Mode. -@cindex @file{.esgdbinit} -@item -ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit} -@end itemize +@item M-s +Execute to another source line, like the @value{GDBN} @code{step} command; also +update the display window to show the current file and location. -You can also request the execution of a command file with the -@code{source} command: +@item M-n +Execute to next source line in this function, skipping all function +calls, like the @value{GDBN} @code{next} command. Then update the display window +to show the current file and location. -@table @code -@kindex source -@item source @var{filename} -Execute the command file @var{filename}. -@end table +@item M-i +Execute one instruction, like the @value{GDBN} @code{stepi} command; update +display window accordingly. -The lines in a command file are executed sequentially. They are not -printed as they are executed. An error in any command terminates execution -of the command file. +@item M-x gdb-nexti +Execute to next instruction, using the @value{GDBN} @code{nexti} command; update +display window accordingly. -Commands that would ask for confirmation if used interactively proceed -without asking when used in a command file. Many @value{GDBN} commands that -normally print messages to say what they are doing omit the messages -when called from command files. +@item C-c C-f +Execute until exit from the selected stack frame, like the @value{GDBN} +@code{finish} command. -@value{GDBN} also accepts command input from standard input. In this -mode, normal output goes to standard output and error output goes to -standard error. Errors in a command file supplied on standard input do -not terminate execution of the command file --- execution continues with -the next command. +@item M-c +Continue execution of your program, like the @value{GDBN} @code{continue} +command. -@example -gdb < cmds > log 2>&1 -@end example +@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}. -(The syntax above will vary depending on the shell used.) This example -will execute commands from the file @file{cmds}. All output and errors -would be directed to @file{log}. +@item M-u +Go up the number of frames indicated by the numeric argument +(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), +like the @value{GDBN} @code{up} command. -@node Output -@section Commands for controlled output +@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}. -During the execution of a command file or a user-defined command, normal -@value{GDBN} output is suppressed; the only output that appears is what is -explicitly printed by the commands in the definition. This section -describes three commands useful for generating exactly the output you -want. +@item M-d +Go down the number of frames indicated by the numeric argument, like the +@value{GDBN} @code{down} command. -@table @code -@kindex echo -@item echo @var{text} -@c I do not consider backslash-space a standard C escape sequence -@c because it is not in ANSI. -Print @var{text}. Nonprinting characters can be included in -@var{text} using C escape sequences, such as @samp{\n} to print a -newline. @strong{No newline is printed unless you specify one.} -In addition to the standard C escape sequences, a backslash followed -by a space stands for a space. This is useful for displaying a -string with spaces at the beginning or the end, since leading and -trailing spaces are otherwise trimmed from all arguments. -To print @samp{@w{ }and foo =@w{ }}, use the command -@samp{echo \@w{ }and foo = \@w{ }}. +@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}. -A backslash at the end of @var{text} can be used, as in C, to continue -the command onto subsequent lines. For example, +@item C-x & +Read the number where the cursor is positioned, and insert it at the end +of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code +around an address that was displayed earlier, type @kbd{disassemble}; +then move the cursor to the address display, and pick up the +argument for @code{disassemble} by typing @kbd{C-x &}. -@example -echo This is some text\n\ -which is continued\n\ -onto several lines.\n -@end example +You can customize this further by defining elements of the list +@code{gdb-print-command}; once it is defined, you can format or +otherwise process numbers picked up by @kbd{C-x &} before they are +inserted. A numeric argument to @kbd{C-x &} indicates that you +wish special formatting, and also acts as an index to pick an element of the +list. If the list element is a string, the number to be inserted is +formatted using the Emacs function @code{format}; otherwise the number +is passed as an argument to the corresponding list element. +@end table -produces the same output as +In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) +tells @value{GDBN} to set a breakpoint on the source line point is on. -@example -echo This is some text\n -echo which is continued\n -echo onto several lines.\n -@end example +If you accidentally delete the source-display buffer, an easy way to get +it back is to type the command @code{f} in the @value{GDBN} buffer, to +request a frame display; when you run under Emacs, this recreates +the source buffer if necessary to show you the context of the current +frame. -@kindex output -@item output @var{expression} -Print the value of @var{expression} and nothing but that value: no -newlines, no @samp{$@var{nn} = }. The value is not entered in the -value history either. @xref{Expressions, ,Expressions}, for more information -on expressions. +The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit +the files with these buffers if you wish; but keep in mind that @value{GDBN} +communicates with Emacs in terms of line numbers. If you add or +delete lines from the text, the line numbers that @value{GDBN} knows cease +to correspond properly with the code. -@item output/@var{fmt} @var{expression} -Print the value of @var{expression} in format @var{fmt}. You can use -the same formats as for @code{print}. @xref{Output Formats,,Output -formats}, for more information. +@c The following dropped because Epoch is nonstandard. Reactivate +@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 +@ignore +@kindex Emacs Epoch environment +@kindex Epoch +@kindex inspect -@kindex printf -@item printf @var{string}, @var{expressions}@dots{} -Print the values of the @var{expressions} under the control of -@var{string}. The @var{expressions} are separated by commas and may be -either numbers or pointers. Their values are printed as specified by -@var{string}, exactly as if your program were to execute the C -subroutine -@c FIXME: the above implies that at least all ANSI C formats are -@c supported, but it isn't true: %E and %G don't work (or so it seems). -@c Either this is a bug, or the manual should document what formats are -@c supported. +Version 18 of @sc{gnu} Emacs has a built-in window system +called the @code{epoch} +environment. Users of this environment can use a new command, +@code{inspect} which performs identically to @code{print} except that +each value is printed in its own window. +@end ignore -@example -printf (@var{string}, @var{expressions}@dots{}); -@end example +@include annotate.texi +@include gdbmi.texinfo -For example, you can print two values in hex like this: +@node GDB Bugs +@chapter Reporting Bugs in @value{GDBN} +@cindex bugs in @value{GDBN} +@cindex reporting bugs in @value{GDBN} -@smallexample -printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo -@end smallexample +Your bug reports play an essential role in making @value{GDBN} reliable. -The only backslash-escape sequences that you can use in the format -string are the simple ones that consist of backslash followed by a -letter. -@end table +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of @value{GDBN} work better. Bug +reports are your contribution to the maintenance of @value{GDBN}. -@node TUI -@chapter @value{GDBN} Text User Interface -@cindex TUI +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. @menu -* TUI Overview:: TUI overview -* TUI Keys:: TUI key bindings -* TUI Commands:: TUI specific commands -* TUI Configuration:: TUI configuration variables +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs @end menu -The @value{GDBN} Text User Interface, TUI in short, -is a terminal interface which uses the @code{curses} library -to show the source file, the assembly output, the program registers -and @value{GDBN} commands in separate text windows. -The TUI is available only when @value{GDBN} is configured -with the @code{--enable-tui} configure option (@pxref{Configure Options}). - -@node TUI Overview -@section TUI overview +@node Bug Criteria +@section Have you found a bug? +@cindex bug criteria -The TUI has two display modes that can be switched while -@value{GDBN} runs: +If you are not sure whether you have found a bug, here are some guidelines: @itemize @bullet +@cindex fatal signal +@cindex debugger crash +@cindex crash of debugger @item -A curses (or TUI) mode in which it displays several text -windows on the terminal. +If the debugger gets a fatal signal, for any input whatever, that is a +@value{GDBN} bug. Reliable debuggers never crash. + +@cindex error on valid input +@item +If @value{GDBN} produces an error message for valid input, that is a +bug. (Note that if you're cross debugging, the problem may also be +somewhere in the connection to the target.) +@cindex invalid input @item -A standard mode which corresponds to the @value{GDBN} configured without -the TUI. +If @value{GDBN} does not produce an error message for invalid input, +that is a bug. However, you should note that your idea of +``invalid input'' might be our idea of ``an extension'' or ``support +for traditional practice''. + +@item +If you are an experienced user of debugging tools, your suggestions +for improvement of @value{GDBN} are welcome in any case. @end itemize -In the TUI mode, @value{GDBN} can display several text window -on the terminal: +@node Bug Reporting +@section How to report bugs +@cindex bug reports +@cindex @value{GDBN} bugs, reporting + +A number of companies and individuals offer support for @sc{gnu} products. +If you obtained @value{GDBN} from a support organization, we recommend you +contact that organization first. + +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. +@c should add a web page ref... + +In any event, we also recommend that you send bug reports for +@value{GDBN} to this addresses: + +@example +bug-gdb@@gnu.org +@end example + +@strong{Do not send bug reports to @samp{info-gdb}, or to +@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do +not want to receive bug reports. Those that do have arranged to receive +@samp{bug-gdb}. + +The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which +serves as a repeater. The mailing list and the newsgroup carry exactly +the same messages. Often people think of posting bug reports to the +newsgroup instead of mailing them. This appears to work, but it has one +problem which can be crucial: a newsgroup posting often lacks a mail +path back to the sender. Thus, if we need to ask for more information, +we may be unable to reach you. For this reason, it is better to send +bug reports to the mailing list. -@table @emph -@item command -This window is the @value{GDBN} command window with the @value{GDBN} -prompt and the @value{GDBN} outputs. The @value{GDBN} input is still -managed using readline but through the TUI. The @emph{command} -window is always visible. +As a last resort, send bug reports on paper to: -@item source -The source window shows the source file of the program. The current -line as well as active breakpoints are displayed in this window. -The current program position is shown with the @samp{>} marker and -active breakpoints are shown with @samp{*} markers. +@example +@sc{gnu} Debugger Bugs +Free Software Foundation Inc. +59 Temple Place - Suite 330 +Boston, MA 02111-1307 +USA +@end example -@item assembly -The assembly window shows the disassembly output of the program. +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! -@item register -This window shows the processor registers. It detects when -a register is changed and when this is the case, registers that have -changed are highlighted. +Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of the variable you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is a +stray memory reference which happens to fetch from the location where that +name is stored in memory; perhaps, if the name were different, the contents +of that location would fool the debugger into doing the right thing despite +the bug. Play it safe and give a specific, complete example. That is the +easiest thing for you to do, and the most helpful. -@end table +Keep in mind that the purpose of a bug report is to enable us to fix the +bug. It may be that the bug has been reported previously, but neither +you nor we can know that unless your bug report is complete and +self-contained. -The source, assembly and register windows are attached to the thread -and the frame position. They are updated when the current thread -changes, when the frame changes or when the program counter changes. -These three windows are arranged by the TUI according to several -layouts. The layout defines which of these three windows are visible. -The following layouts are available: +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' Those bug reports are useless, and we urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. + +To enable us to fix the bug, you should include all these things: @itemize @bullet @item -source +The version of @value{GDBN}. @value{GDBN} announces it if you start +with no arguments; you can also print it at any time using @code{show +version}. -@item -assembly +Without this, we will not know whether there is any point in looking for +the bug in the current version of @value{GDBN}. @item -source and assembly +The type of machine you are using, and the operating system name and +version number. @item -source and registers +What compiler (and its version) was used to compile @value{GDBN}---e.g. +``@value{GCC}--2.8.1''. @item -assembly and registers - -@end itemize - -@node TUI Keys -@section TUI Key Bindings -@cindex TUI key bindings +What compiler (and its version) was used to compile the program you are +debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP +C Compiler''. For GCC, you can say @code{gcc --version} to get this +information; for other compilers, see the documentation for those +compilers. -The TUI installs several key bindings in the readline keymaps -(@pxref{Command Line Editing}). -They allow to leave or enter in the TUI mode or they operate -directly on the TUI layout and windows. The following key bindings -are installed for both TUI mode and the @value{GDBN} standard mode. +@item +The command arguments you gave the compiler to compile your example and +observe the bug. For example, did you use @samp{-O}? To guarantee +you will not omit something important, list them all. A copy of the +Makefile (or the output from make) is sufficient. -@table @kbd -@kindex C-x C-a -@item C-x C-a -@kindex C-x a -@itemx C-x a -@kindex C-x A -@itemx C-x A -Enter or leave the TUI mode. When the TUI mode is left, -the curses window management is left and @value{GDBN} operates using -its standard mode writing on the terminal directly. When the TUI -mode is entered, the control is given back to the curses windows. -The screen is then refreshed. +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. -@kindex C-x 1 -@item C-x 1 -Use a TUI layout with only one window. The layout will -either be @samp{source} or @samp{assembly}. When the TUI mode -is not active, it will switch to the TUI mode. +@item +A complete input script, and all necessary source files, that will +reproduce the bug. -Think of this key binding as the Emacs @kbd{C-x 1} binding. +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal.'' -@kindex C-x 2 -@item C-x 2 -Use a TUI layout with at least two windows. When the current -layout shows already two windows, a next layout with two windows is used. -When a new layout is chosen, one window will always be common to the -previous layout and the new one. +Of course, if the bug is that @value{GDBN} gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might +not notice unless it is glaringly wrong. You might as well not give us +a chance to make a mistake. -Think of it as the Emacs @kbd{C-x 2} binding. +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of @value{GDBN} is out of synch, or you have encountered a bug in +the C library on your system. (This has happened!) Your copy might +crash and ours would not. If you told us to expect a crash, then when +ours fails to crash, we would know that the bug was not happening for +us. If you had not told us to expect a crash, then we would not be able +to draw any conclusion from our observations. -@end table +@item +If you wish to suggest changes to the @value{GDBN} source, send us context +diffs. If you even discuss something in the @value{GDBN} source, refer to +it by context, not by line number. -The following key bindings are handled only by the TUI mode: +The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. -@table @key -@kindex PgUp -@item PgUp -Scroll the active window one page up. +@end itemize -@kindex PgDn -@item PgDn -Scroll the active window one page down. +Here are some things that are not necessary: -@kindex Up -@item Up -Scroll the active window one line up. +@itemize @bullet +@item +A description of the envelope of the bug. -@kindex Down -@item Down -Scroll the active window one line down. +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. -@kindex Left -@item Left -Scroll the active window one column left. +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. -@kindex Right -@item Right -Scroll the active window one column right. +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. -@kindex C-L -@item C-L -Refresh the screen. +However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. -@end table +@item +A patch for the bug. -In the TUI mode, the arrow keys are used by the active window -for scrolling. This means they are not available for readline. It is -necessary to use other readline key bindings such as @key{C-p}, @key{C-n}, -@key{C-b} and @key{C-f}. +A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. -@node TUI Commands -@section TUI specific commands -@cindex TUI commands +Sometimes with a program as complicated as @value{GDBN} it is very hard to +construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be able +to construct one, so we will not be able to verify that the bug is fixed. -The TUI has specific commands to control the text windows. -These commands are always available, that is they do not depend on -the current terminal mode in which @value{GDBN} runs. When @value{GDBN} -is in the standard mode, using these commands will automatically switch -in the TUI mode. +And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. -@table @code -@item layout next -@kindex layout next -Display the next layout. +@item +A guess about what the bug is or what it depends on. -@item layout prev -@kindex layout prev -Display the previous layout. +Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +@end itemize -@item layout src -@kindex layout src -Display the source window only. +@c The readline documentation is distributed with the readline code +@c and consists of the two following files: +@c rluser.texinfo +@c inc-hist.texinfo +@c Use -I with makeinfo to point to the appropriate directory, +@c environment var TEXINPUTS with TeX. +@include rluser.texinfo +@include inc-hist.texinfo -@item layout asm -@kindex layout asm -Display the assembly window only. -@item layout split -@kindex layout split -Display the source and assembly window. +@node Formatting Documentation +@appendix Formatting Documentation -@item layout regs -@kindex layout regs -Display the register window together with the source or assembly window. +@cindex @value{GDBN} reference card +@cindex reference card +The @value{GDBN} 4 release includes an already-formatted reference card, ready +for printing with PostScript or Ghostscript, in the @file{gdb} +subdirectory of the main source directory@footnote{In +@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} +release.}. If you can use PostScript or Ghostscript with your printer, +you can print the reference card immediately with @file{refcard.ps}. -@item focus next | prev | src | asm | regs | split -@kindex focus -Set the focus to the named window. -This command allows to change the active window so that scrolling keys -can be affected to another window. +The release also includes the source for the reference card. You +can format it, using @TeX{}, by typing: -@item refresh -@kindex refresh -Refresh the screen. This is similar to using @key{C-L} key. +@example +make refcard.dvi +@end example -@item update -@kindex update -Update the source window and the current execution point. +The @value{GDBN} reference card is designed to print in @dfn{landscape} +mode on US ``letter'' size paper; +that is, on a sheet 11 inches wide by 8.5 inches +high. You will need to specify this form of printing as an option to +your @sc{dvi} output program. -@item winheight @var{name} +@var{count} -@itemx winheight @var{name} -@var{count} -@kindex winheight -Change the height of the window @var{name} by @var{count} -lines. Positive counts increase the height, while negative counts -decrease it. +@cindex documentation -@end table +All the documentation for @value{GDBN} comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and @TeX{} (or @code{texi2roff}) to typeset the printed version. -@node TUI Configuration -@section TUI configuration variables -@cindex TUI configuration variables +@value{GDBN} includes an already formatted copy of the on-line Info +version of this manual in the @file{gdb} subdirectory. The main Info +file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to +subordinate files matching @samp{gdb.info*} in the same directory. If +necessary, you can print out these files, or read them with any editor; +but they are easier to read using the @code{info} subsystem in @sc{gnu} +Emacs or the standalone @code{info} program, available as part of the +@sc{gnu} Texinfo distribution. -The TUI has several configuration variables that control the -appearance of windows on the terminal. +If you want to format these Info files yourself, you need one of the +Info formatting programs, such as @code{texinfo-format-buffer} or +@code{makeinfo}. -@table @code -@item set tui border-kind @var{kind} -@kindex set tui border-kind -Select the border appearance for the source, assembly and register windows. -The possible values are the following: -@table @code -@item space -Use a space character to draw the border. +If you have @code{makeinfo} installed, and are in the top level +@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of +version @value{GDBVN}), you can make the Info file by typing: -@item ascii -Use ascii characters + - and | to draw the border. +@example +cd gdb +make gdb.info +@end example -@item acs -Use the Alternate Character Set to draw the border. The border is -drawn using character line graphics if the terminal supports them. +If you want to typeset and print copies of this manual, you need @TeX{}, +a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the +Texinfo definitions file. -@end table +@TeX{} is a typesetting program; it does not print files directly, but +produces output files called @sc{dvi} files. To print a typeset +document, you need a program to print @sc{dvi} files. If your system +has @TeX{} installed, chances are it has such a program. The precise +command to use depends on your system; @kbd{lpr -d} is common; another +(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may +require a file name without any extension or a @samp{.dvi} extension. -@item set tui active-border-mode @var{mode} -@kindex set tui active-border-mode -Select the attributes to display the border of the active window. -The possible values are @code{normal}, @code{standout}, @code{reverse}, -@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}. +@TeX{} also requires a macro definitions file called +@file{texinfo.tex}. This file tells @TeX{} how to typeset a document +written in Texinfo format. On its own, @TeX{} cannot either read or +typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB +and is located in the @file{gdb-@var{version-number}/texinfo} +directory. -@item set tui border-mode @var{mode} -@kindex set tui border-mode -Select the attributes to display the border of other windows. -The @var{mode} can be one of the following: -@table @code -@item normal -Use normal attributes to display the border. +If you have @TeX{} and a @sc{dvi} printer program installed, you can +typeset and print this manual. First switch to the the @file{gdb} +subdirectory of the main source directory (for example, to +@file{gdb-@value{GDBVN}/gdb}) and type: -@item standout -Use standout mode. +@example +make gdb.dvi +@end example -@item reverse -Use reverse video mode. +Then give @file{gdb.dvi} to your @sc{dvi} printing program. -@item half -Use half bright mode. +@node Installing GDB +@appendix Installing @value{GDBN} +@cindex configuring @value{GDBN} +@cindex installation -@item half-standout -Use half bright and standout mode. +@value{GDBN} comes with a @code{configure} script that automates the process +of preparing @value{GDBN} for installation; you can then use @code{make} to +build the @code{gdb} program. +@iftex +@c irrelevant in info file; it's as current as the code it lives with. +@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, +look at the @file{README} file in the sources; we may have improved the +installation procedures since publishing this manual.} +@end iftex -@item bold -Use extra bright or bold mode. +The @value{GDBN} distribution includes all the source code you need for +@value{GDBN} in a single directory, whose name is usually composed by +appending the version number to @samp{gdb}. -@item bold-standout -Use extra bright or bold and standout mode. +For example, the @value{GDBN} version @value{GDBVN} distribution is in the +@file{gdb-@value{GDBVN}} directory. That directory contains: -@end table +@table @code +@item gdb-@value{GDBVN}/configure @r{(and supporting files)} +script for configuring @value{GDBN} and all its supporting libraries -@end table +@item gdb-@value{GDBVN}/gdb +the source specific to @value{GDBN} itself -@node Emacs -@chapter Using @value{GDBN} under @sc{gnu} Emacs +@item gdb-@value{GDBVN}/bfd +source for the Binary File Descriptor library -@cindex Emacs -@cindex @sc{gnu} Emacs -A special interface allows you to use @sc{gnu} Emacs to view (and -edit) the source files for the program you are debugging with -@value{GDBN}. +@item gdb-@value{GDBVN}/include +@sc{gnu} include files -To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the -executable file you want to debug as an argument. This command starts -@value{GDBN} as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. -@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) +@item gdb-@value{GDBVN}/libiberty +source for the @samp{-liberty} free software library -Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two -things: +@item gdb-@value{GDBVN}/opcodes +source for the library of opcode tables and disassemblers -@itemize @bullet -@item -All ``terminal'' input and output goes through the Emacs buffer. -@end itemize +@item gdb-@value{GDBVN}/readline +source for the @sc{gnu} command-line interface -This applies both to @value{GDBN} commands and their output, and to the input -and output done by the program you are debugging. +@item gdb-@value{GDBVN}/glob +source for the @sc{gnu} filename pattern-matching subroutine -This is useful because it means that you can copy the text of previous -commands and input them again; you can even use parts of the output -in this way. +@item gdb-@value{GDBVN}/mmalloc +source for the @sc{gnu} memory-mapped malloc package +@end table -All the facilities of Emacs' Shell mode are available for interacting -with your program. In particular, you can send signals the usual -way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a -stop. +The simplest way to configure and build @value{GDBN} is to run @code{configure} +from the @file{gdb-@var{version-number}} source directory, which in +this example is the @file{gdb-@value{GDBVN}} directory. -@itemize @bullet -@item -@value{GDBN} displays source code through Emacs. -@end itemize +First switch to the @file{gdb-@var{version-number}} source directory +if you are not already in it; then run @code{configure}. Pass the +identifier for the platform on which @value{GDBN} will run as an +argument. -Each time @value{GDBN} displays a stack frame, Emacs automatically finds the -source file for that frame and puts an arrow (@samp{=>}) at the -left margin of the current line. Emacs uses a separate buffer for -source display, and splits the screen to show both your @value{GDBN} session -and the source. +For example: -Explicit @value{GDBN} @code{list} or search commands still produce output as -usual, but you probably have no reason to use them from Emacs. +@example +cd gdb-@value{GDBVN} +./configure @var{host} +make +@end example -@quotation -@emph{Warning:} If the directory where your program resides is not your -current directory, it can be easy to confuse Emacs about the location of -the source files, in which case the auxiliary display buffer does not -appear to show your source. @value{GDBN} can find programs by searching your -environment's @code{PATH} variable, so the @value{GDBN} input and output -session proceeds normally; but Emacs does not get enough information -back from @value{GDBN} to locate the source files in this situation. To -avoid this problem, either start @value{GDBN} mode from the directory where -your program resides, or specify an absolute file name when prompted for the -@kbd{M-x gdb} argument. +@noindent +where @var{host} is an identifier such as @samp{sun4} or +@samp{decstation}, that identifies the platform where @value{GDBN} will run. +(You can often leave off @var{host}; @code{configure} tries to guess the +correct value by examining your system.) -A similar confusion can result if you use the @value{GDBN} @code{file} command to -switch to debugging a program in some other location, from an existing -@value{GDBN} buffer in Emacs. -@end quotation +Running @samp{configure @var{host}} and then running @code{make} builds the +@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} +libraries, then @code{gdb} itself. The configured source files, and the +binaries, are left in the corresponding source directories. -By default, @kbd{M-x gdb} calls the program called @file{gdb}. If -you need to call @value{GDBN} by a different name (for example, if you keep -several configurations around, with different names) you can set the -Emacs variable @code{gdb-command-name}; for example, +@need 750 +@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your +system does not recognize this automatically when you run a different +shell, you may need to run @code{sh} on it explicitly: @example -(setq gdb-command-name "mygdb") +sh configure @var{host} @end example -@noindent -(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or -in your @file{.emacs} file) makes Emacs call the program named -``@code{mygdb}'' instead. +If you run @code{configure} from a directory that contains source +directories for multiple libraries or programs, such as the +@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure} +creates configuration files for every directory level underneath (unless +you tell it not to, with the @samp{--norecursion} option). + +You can run the @code{configure} script from any of the +subordinate directories in the @value{GDBN} distribution if you only want to +configure that subdirectory, but be sure to specify a path to it. -In the @value{GDBN} I/O buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: +For example, with version @value{GDBVN}, type the following to configure only +the @code{bfd} subdirectory: -@table @kbd -@item C-h m -Describe the features of Emacs' @value{GDBN} Mode. +@example +@group +cd gdb-@value{GDBVN}/bfd +../configure @var{host} +@end group +@end example -@item M-s -Execute to another source line, like the @value{GDBN} @code{step} command; also -update the display window to show the current file and location. +You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. +However, you should make sure that the shell on your path (named by +the @samp{SHELL} environment variable) is publicly readable. Remember +that @value{GDBN} uses the shell to start your program---some systems refuse to +let @value{GDBN} debug child processes whose programs are not readable. -@item M-n -Execute to next source line in this function, skipping all function -calls, like the @value{GDBN} @code{next} command. Then update the display window -to show the current file and location. +@menu +* Separate Objdir:: Compiling @value{GDBN} in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure +@end menu -@item M-i -Execute one instruction, like the @value{GDBN} @code{stepi} command; update -display window accordingly. +@node Separate Objdir +@section Compiling @value{GDBN} in another directory -@item M-x gdb-nexti -Execute to next instruction, using the @value{GDBN} @code{nexti} command; update -display window accordingly. +If you want to run @value{GDBN} versions for several host or target machines, +you need a different @code{gdb} compiled for each combination of +host and target. @code{configure} is designed to make this easy by +allowing you to generate each configuration in a separate subdirectory, +rather than in the source directory. If your @code{make} program +handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running +@code{make} in each of these directories builds the @code{gdb} +program specified there. -@item C-c C-f -Execute until exit from the selected stack frame, like the @value{GDBN} -@code{finish} command. +To build @code{gdb} in a separate directory, run @code{configure} +with the @samp{--srcdir} option to specify where to find the source. +(You also need to specify a path to find @code{configure} +itself from your working directory. If the path to @code{configure} +would be the same as the argument to @samp{--srcdir}, you can leave out +the @samp{--srcdir} option; it is assumed.) -@item M-c -Continue execution of your program, like the @value{GDBN} @code{continue} -command. +For example, with version @value{GDBVN}, you can build @value{GDBN} in a +separate directory for a Sun 4 like this: -@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}. +@example +@group +cd gdb-@value{GDBVN} +mkdir ../gdb-sun4 +cd ../gdb-sun4 +../gdb-@value{GDBVN}/configure sun4 +make +@end group +@end example -@item M-u -Go up the number of frames indicated by the numeric argument -(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), -like the @value{GDBN} @code{up} command. +When @code{configure} builds a configuration using a remote source +directory, it creates a tree for the binaries with the same structure +(and using the same names) as the tree under the source directory. In +the example, you'd find the Sun 4 library @file{libiberty.a} in the +directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in +@file{gdb-sun4/gdb}. -@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}. +One popular reason to build several @value{GDBN} configurations in separate +directories is to configure @value{GDBN} for cross-compiling (where +@value{GDBN} runs on one machine---the @dfn{host}---while debugging +programs that run on another machine---the @dfn{target}). +You specify a cross-debugging target by +giving the @samp{--target=@var{target}} option to @code{configure}. -@item M-d -Go down the number of frames indicated by the numeric argument, like the -@value{GDBN} @code{down} command. +When you run @code{make} to build a program or library, you must run +it in a configured directory---whatever directory you were in when you +called @code{configure} (or one of its subdirectories). -@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}. +The @code{Makefile} that @code{configure} generates in each source +directory also runs recursively. If you type @code{make} in a source +directory such as @file{gdb-@value{GDBVN}} (or in a separate configured +directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you +will build all the required libraries, and then build GDB. -@item C-x & -Read the number where the cursor is positioned, and insert it at the end -of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code -around an address that was displayed earlier, type @kbd{disassemble}; -then move the cursor to the address display, and pick up the -argument for @code{disassemble} by typing @kbd{C-x &}. +When you have multiple hosts or targets configured in separate +directories, you can run @code{make} on them in parallel (for example, +if they are NFS-mounted on each of the hosts); they will not interfere +with each other. -You can customize this further by defining elements of the list -@code{gdb-print-command}; once it is defined, you can format or -otherwise process numbers picked up by @kbd{C-x &} before they are -inserted. A numeric argument to @kbd{C-x &} indicates that you -wish special formatting, and also acts as an index to pick an element of the -list. If the list element is a string, the number to be inserted is -formatted using the Emacs function @code{format}; otherwise the number -is passed as an argument to the corresponding list element. -@end table +@node Config Names +@section Specifying names for hosts and targets -In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) -tells @value{GDBN} to set a breakpoint on the source line point is on. +The specifications used for hosts and targets in the @code{configure} +script are based on a three-part naming scheme, but some short predefined +aliases are also supported. The full naming scheme encodes three pieces +of information in the following pattern: -If you accidentally delete the source-display buffer, an easy way to get -it back is to type the command @code{f} in the @value{GDBN} buffer, to -request a frame display; when you run under Emacs, this recreates -the source buffer if necessary to show you the context of the current -frame. +@example +@var{architecture}-@var{vendor}-@var{os} +@end example -The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit -the files with these buffers if you wish; but keep in mind that @value{GDBN} -communicates with Emacs in terms of line numbers. If you add or -delete lines from the text, the line numbers that @value{GDBN} knows cease -to correspond properly with the code. +For example, you can use the alias @code{sun4} as a @var{host} argument, +or as the value for @var{target} in a @code{--target=@var{target}} +option. The equivalent full name is @samp{sparc-sun-sunos4}. -@c The following dropped because Epoch is nonstandard. Reactivate -@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 -@ignore -@kindex Emacs Epoch environment -@kindex Epoch -@kindex inspect +The @code{configure} script accompanying @value{GDBN} does not provide +any query facility to list all supported host and target names or +aliases. @code{configure} calls the Bourne shell script +@code{config.sub} to map abbreviations to full names; you can read the +script, if you wish, or you can use it to test your guesses on +abbreviations---for example: -Version 18 of @sc{gnu} Emacs has a built-in window system -called the @code{epoch} -environment. Users of this environment can use a new command, -@code{inspect} which performs identically to @code{print} except that -each value is printed in its own window. -@end ignore +@smallexample +% sh config.sub i386-linux +i386-pc-linux-gnu +% sh config.sub alpha-linux +alpha-unknown-linux-gnu +% sh config.sub hp9k700 +hppa1.1-hp-hpux +% sh config.sub sun4 +sparc-sun-sunos4.1.1 +% sh config.sub sun3 +m68k-sun-sunos4.1.1 +% sh config.sub i986v +Invalid configuration `i986v': machine `i986v' not recognized +@end smallexample -@include annotate.texi -@include gdbmi.texinfo +@noindent +@code{config.sub} is also distributed in the @value{GDBN} source +directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). -@node GDB Bugs -@chapter Reporting Bugs in @value{GDBN} -@cindex bugs in @value{GDBN} -@cindex reporting bugs in @value{GDBN} +@node Configure Options +@section @code{configure} options -Your bug reports play an essential role in making @value{GDBN} reliable. +Here is a summary of the @code{configure} options and arguments that +are most often useful for building @value{GDBN}. @code{configure} also has +several other options not listed here. @inforef{What Configure +Does,,configure.info}, for a full explanation of @code{configure}. -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of @value{GDBN} work better. Bug -reports are your contribution to the maintenance of @value{GDBN}. +@example +configure @r{[}--help@r{]} + @r{[}--prefix=@var{dir}@r{]} + @r{[}--exec-prefix=@var{dir}@r{]} + @r{[}--srcdir=@var{dirname}@r{]} + @r{[}--norecursion@r{]} @r{[}--rm@r{]} + @r{[}--target=@var{target}@r{]} + @var{host} +@end example -In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. +@noindent +You may introduce options with a single @samp{-} rather than +@samp{--} if you prefer; but you may abbreviate option names if you use +@samp{--}. -@menu -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs -@end menu +@table @code +@item --help +Display a quick summary of how to invoke @code{configure}. -@node Bug Criteria -@section Have you found a bug? -@cindex bug criteria +@item --prefix=@var{dir} +Configure the source to install programs and files under directory +@file{@var{dir}}. -If you are not sure whether you have found a bug, here are some guidelines: +@item --exec-prefix=@var{dir} +Configure the source to install programs under directory +@file{@var{dir}}. -@itemize @bullet -@cindex fatal signal -@cindex debugger crash -@cindex crash of debugger -@item -If the debugger gets a fatal signal, for any input whatever, that is a -@value{GDBN} bug. Reliable debuggers never crash. +@c avoid splitting the warning from the explanation: +@need 2000 +@item --srcdir=@var{dirname} +@strong{Warning: using this option requires @sc{gnu} @code{make}, or another +@code{make} that implements the @code{VPATH} feature.}@* +Use this option to make configurations in directories separate from the +@value{GDBN} source directories. Among other things, you can use this to +build (or maintain) several configurations simultaneously, in separate +directories. @code{configure} writes configuration specific files in +the current directory, but arranges for them to use the source in the +directory @var{dirname}. @code{configure} creates directories under +the working directory in parallel to the source directories below +@var{dirname}. -@cindex error on valid input -@item -If @value{GDBN} produces an error message for valid input, that is a -bug. (Note that if you're cross debugging, the problem may also be -somewhere in the connection to the target.) +@item --norecursion +Configure only the directory level where @code{configure} is executed; do not +propagate configuration to subdirectories. -@cindex invalid input -@item -If @value{GDBN} does not produce an error message for invalid input, -that is a bug. However, you should note that your idea of -``invalid input'' might be our idea of ``an extension'' or ``support -for traditional practice''. +@item --target=@var{target} +Configure @value{GDBN} for cross-debugging programs running on the specified +@var{target}. Without this option, @value{GDBN} is configured to debug +programs that run on the same machine (@var{host}) as @value{GDBN} itself. -@item -If you are an experienced user of debugging tools, your suggestions -for improvement of @value{GDBN} are welcome in any case. -@end itemize +There is no convenient way to generate a list of all available targets. -@node Bug Reporting -@section How to report bugs -@cindex bug reports -@cindex @value{GDBN} bugs, reporting +@item @var{host} @dots{} +Configure @value{GDBN} to run on the specified @var{host}. -A number of companies and individuals offer support for @sc{gnu} products. -If you obtained @value{GDBN} from a support organization, we recommend you -contact that organization first. +There is no convenient way to generate a list of all available hosts. +@end table -You can find contact information for many support companies and -individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs -distribution. -@c should add a web page ref... +There are many other options available as well, but they are generally +needed for special purposes only. -In any event, we also recommend that you send bug reports for -@value{GDBN} to this addresses: +@node Maintenance Commands +@appendix Maintenance Commands +@cindex maintenance commands +@cindex internal commands -@example -bug-gdb@@gnu.org -@end example +In addition to commands intended for @value{GDBN} users, @value{GDBN} +includes a number of commands intended for @value{GDBN} developers. +These commands are provided here for reference. -@strong{Do not send bug reports to @samp{info-gdb}, or to -@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do -not want to receive bug reports. Those that do have arranged to receive -@samp{bug-gdb}. +@table @code +@kindex maint info breakpoints +@item @anchor{maint info breakpoints}maint info breakpoints +Using the same format as @samp{info breakpoints}, display both the +breakpoints you've set explicitly, and those @value{GDBN} is using for +internal purposes. Internal breakpoints are shown with negative +breakpoint numbers. The type column identifies what kind of breakpoint +is shown: -The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which -serves as a repeater. The mailing list and the newsgroup carry exactly -the same messages. Often people think of posting bug reports to the -newsgroup instead of mailing them. This appears to work, but it has one -problem which can be crucial: a newsgroup posting often lacks a mail -path back to the sender. Thus, if we need to ask for more information, -we may be unable to reach you. For this reason, it is better to send -bug reports to the mailing list. +@table @code +@item breakpoint +Normal, explicitly set breakpoint. -As a last resort, send bug reports on paper to: +@item watchpoint +Normal, explicitly set watchpoint. -@example -@sc{gnu} Debugger Bugs -Free Software Foundation Inc. -59 Temple Place - Suite 330 -Boston, MA 02111-1307 -USA -@end example +@item longjmp +Internal breakpoint, used to handle correctly stepping through +@code{longjmp} calls. -The fundamental principle of reporting bugs usefully is this: -@strong{report all the facts}. If you are not sure whether to state a -fact or leave it out, state it! +@item longjmp resume +Internal breakpoint at the target of a @code{longjmp}. -Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of the variable you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is a -stray memory reference which happens to fetch from the location where that -name is stored in memory; perhaps, if the name were different, the contents -of that location would fool the debugger into doing the right thing despite -the bug. Play it safe and give a specific, complete example. That is the -easiest thing for you to do, and the most helpful. +@item until +Temporary internal breakpoint used by the @value{GDBN} @code{until} command. -Keep in mind that the purpose of a bug report is to enable us to fix the -bug. It may be that the bug has been reported previously, but neither -you nor we can know that unless your bug report is complete and -self-contained. +@item finish +Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. -Sometimes people give a few sketchy facts and ask, ``Does this ring a -bell?'' Those bug reports are useless, and we urge everyone to -@emph{refuse to respond to them} except to chide the sender to report -bugs properly. +@item shlib events +Shared library events. -To enable us to fix the bug, you should include all these things: +@end table -@itemize @bullet -@item -The version of @value{GDBN}. @value{GDBN} announces it if you start -with no arguments; you can also print it at any time using @code{show -version}. +@end table -Without this, we will not know whether there is any point in looking for -the bug in the current version of @value{GDBN}. -@item -The type of machine you are using, and the operating system name and -version number. +@node Remove Protocol +@appendix @value{GDBN} Remote Serial Protocol -@item -What compiler (and its version) was used to compile @value{GDBN}---e.g. -``@value{GCC}--2.8.1''. +There may be occasions when you need to know something about the +protocol---for example, if there is only one serial port to your target +machine, you might want your program to do something special if it +recognizes a packet meant for @value{GDBN}. -@item -What compiler (and its version) was used to compile the program you are -debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP -C Compiler''. For GCC, you can say @code{gcc --version} to get this -information; for other compilers, see the documentation for those -compilers. +In the examples below, @samp{<-} and @samp{->} are used to indicate +transmitted and received data respectfully. -@item -The command arguments you gave the compiler to compile your example and -observe the bug. For example, did you use @samp{-O}? To guarantee -you will not omit something important, list them all. A copy of the -Makefile (or the output from make) is sufficient. +@cindex protocol, @value{GDBN} remote serial +@cindex serial protocol, @value{GDBN} remote +@cindex remote serial protocol +All @value{GDBN} commands and responses (other than acknowledgments) are +sent as a @var{packet}. A @var{packet} is introduced with the character +@samp{$}, the actual @var{packet-data}, and the terminating character +@samp{#} followed by a two-digit @var{checksum}: -If we were to try to guess the arguments, we would probably guess wrong -and then we might not encounter the bug. +@example +@code{$}@var{packet-data}@code{#}@var{checksum} +@end example +@noindent -@item -A complete input script, and all necessary source files, that will -reproduce the bug. +@cindex checksum, for @value{GDBN} remote +@noindent +The two-digit @var{checksum} is computed as the modulo 256 sum of all +characters between the leading @samp{$} and the trailing @samp{#} (an +eight bit unsigned checksum). -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``It gets a fatal signal.'' +Implementors should note that prior to @value{GDBN} 5.0 the protocol +specification also included an optional two-digit @var{sequence-id}: -Of course, if the bug is that @value{GDBN} gets a fatal signal, then we -will certainly notice it. But if the bug is incorrect output, we might -not notice unless it is glaringly wrong. You might as well not give us -a chance to make a mistake. +@example +@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} +@end example -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of @value{GDBN} is out of synch, or you have encountered a bug in -the C library on your system. (This has happened!) Your copy might -crash and ours would not. If you told us to expect a crash, then when -ours fails to crash, we would know that the bug was not happening for -us. If you had not told us to expect a crash, then we would not be able -to draw any conclusion from our observations. +@cindex sequence-id, for @value{GDBN} remote +@noindent +That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} +has never output @var{sequence-id}s. Stubs that handle packets added +since @value{GDBN} 5.0 must not accept @var{sequence-id}. -@item -If you wish to suggest changes to the @value{GDBN} source, send us context -diffs. If you even discuss something in the @value{GDBN} source, refer to -it by context, not by line number. +@cindex acknowledgment, for @value{GDBN} remote +When either the host or the target machine receives a packet, the first +response expected is an acknowledgment: either @samp{+} (to indicate +the package was received correctly) or @samp{-} (to request +retransmission): -The line numbers in our development sources will not match those in your -sources. Your line numbers would convey no useful information to us. +@example +<- @code{$}@var{packet-data}@code{#}@var{checksum} +-> @code{+} +@end example +@noindent -@end itemize +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). -Here are some things that are not necessary: +@var{packet-data} consists of a sequence of characters with the +exception of @samp{#} and @samp{$} (see @samp{X} packet for additional +exceptions). -@itemize @bullet -@item -A description of the envelope of the bug. +Fields within the packet should be separated using @samp{,} @samp{;} or +@samp{:}. Except where otherwise noted all numbers are represented in +HEX with leading zeros suppressed. -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. +Implementors should note that prior to @value{GDBN} 5.0, the character +@samp{:} could not appear as the third character in a packet (as it +would potentially conflict with the @var{sequence-id}). -This is often time consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -We recommend that you save your time for something else. +Response @var{data} can be run-length encoded to save space. A @samp{*} +means that the next character is an @sc{ascii} encoding giving a repeat count +which stands for that many repetitions of the character preceding the +@samp{*}. The encoding is @code{n+29}, yielding a printable character +where @code{n >=3} (which is where rle starts to win). The printable +characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric +value greater than 126 should not be used. -Of course, if you can find a simpler example to report @emph{instead} -of the original one, that is a convenience for us. Errors in the -output will be easier to spot, running under the debugger will take -less time, and so on. +Some remote systems have used a different run-length encoding mechanism +loosely refered to as the cisco encoding. Following the @samp{*} +character are two hex digits that indicate the size of the packet. -However, simplification is not vital; if you do not want to do this, -report the bug anyway and send us the entire test case you used. +So: +@example +"@code{0* }" +@end example +@noindent +means the same as "0000". -@item -A patch for the bug. +The error response returned for some packets includes a two character +error number. That number is not well defined. -A patch for the bug does help us if it is a good one. But do not omit -the necessary information, such as the test case, on the assumption that -a patch is all we need. We might see problems with your patch and decide -to fix the problem another way, or we might not understand it at all. +For any @var{command} not supported by the stub, an empty response +(@samp{$#00}) should be returned. That way it is possible to extend the +protocol. A newer @value{GDBN} can tell if a packet is supported based +on that response. -Sometimes with a program as complicated as @value{GDBN} it is very hard to -construct an example that will make the program follow a certain path -through the code. If you do not send us the example, we will not be able -to construct one, so we will not be able to verify that the bug is fixed. +A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, +@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are +optional. -And if we cannot understand what bug you are trying to fix, or why your -patch should be an improvement, we will not install it. A test case will -help us to understand. +Below is a complete list of all currently defined @var{command}s and +their corresponding response @var{data}: +@page +@multitable @columnfractions .30 .30 .40 +@item Packet +@tab Request +@tab Description +@item extended mode +@tab @code{!} +@tab +Enable extended mode. In extended mode, the remote server is made +persistent. The @samp{R} packet is used to restart the program being +debugged. @item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even we cannot guess right about such -things without first using the debugger to find the facts. -@end itemize +@tab reply @samp{OK} +@tab +The remote target both supports and has enabled extended mode. -@c The readline documentation is distributed with the readline code -@c and consists of the two following files: -@c rluser.texinfo -@c inc-hist.texinfo -@c Use -I with makeinfo to point to the appropriate directory, -@c environment var TEXINPUTS with TeX. -@include rluser.texinfo -@include inc-hist.texinfo +@item last signal +@tab @code{?} +@tab +Indicate the reason the target halted. The reply is the same as for step +and continue. +@item +@tab reply +@tab see below -@node Formatting Documentation -@appendix Formatting Documentation +@item reserved +@tab @code{a} +@tab Reserved for future use -@cindex @value{GDBN} reference card -@cindex reference card -The @value{GDBN} 4 release includes an already-formatted reference card, ready -for printing with PostScript or Ghostscript, in the @file{gdb} -subdirectory of the main source directory@footnote{In -@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} -release.}. If you can use PostScript or Ghostscript with your printer, -you can print the reference card immediately with @file{refcard.ps}. +@item set program arguments @strong{(reserved)} +@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...} +@tab +@item +@tab +@tab +Initialized @samp{argv[]} array passed into program. @var{arglen} +specifies the number of bytes in the hex encoded byte stream @var{arg}. +See @file{gdbserver} for more details. +@item +@tab reply @code{OK} +@item +@tab reply @code{E}@var{NN} -The release also includes the source for the reference card. You -can format it, using @TeX{}, by typing: +@item set baud @strong{(deprecated)} +@tab @code{b}@var{baud} +@tab +Change the serial line speed to @var{baud}. JTC: @emph{When does the +transport layer state change? When it's received, or after the ACK is +transmitted. In either case, there are problems if the command or the +acknowledgment packet is dropped.} Stan: @emph{If people really wanted +to add something like this, and get it working for the first time, they +ought to modify ser-unix.c to send some kind of out-of-band message to a +specially-setup stub and have the switch happen "in between" packets, so +that from remote protocol's point of view, nothing actually +happened.} -@example -make refcard.dvi -@end example +@item set breakpoint @strong{(deprecated)} +@tab @code{B}@var{addr},@var{mode} +@tab +Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a +breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and +@samp{z} packets.} -The @value{GDBN} reference card is designed to print in @dfn{landscape} -mode on US ``letter'' size paper; -that is, on a sheet 11 inches wide by 8.5 inches -high. You will need to specify this form of printing as an option to -your @sc{dvi} output program. +@item continue +@tab @code{c}@var{addr} +@tab +@var{addr} is address to resume. If @var{addr} is omitted, resume at +current address. +@item +@tab reply +@tab see below -@cindex documentation +@item continue with signal +@tab @code{C}@var{sig}@code{;}@var{addr} +@tab +Continue with signal @var{sig} (hex signal number). If +@code{;}@var{addr} is omitted, resume at same address. +@item +@tab reply +@tab see below -All the documentation for @value{GDBN} comes as part of the machine-readable -distribution. The documentation is written in Texinfo format, which is -a documentation system that uses a single source file to produce both -on-line information and a printed manual. You can use one of the Info -formatting commands to create the on-line version of the documentation -and @TeX{} (or @code{texi2roff}) to typeset the printed version. +@item toggle debug @strong{(deprecated)} +@tab @code{d} +@tab +toggle debug flag. -@value{GDBN} includes an already formatted copy of the on-line Info -version of this manual in the @file{gdb} subdirectory. The main Info -file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to -subordinate files matching @samp{gdb.info*} in the same directory. If -necessary, you can print out these files, or read them with any editor; -but they are easier to read using the @code{info} subsystem in @sc{gnu} -Emacs or the standalone @code{info} program, available as part of the -@sc{gnu} Texinfo distribution. +@item detach +@tab @code{D} +@tab +Detach @value{GDBN} from the remote system. Sent to the remote target before +@value{GDBN} disconnects. +@item +@tab reply @emph{no response} +@tab +@value{GDBN} does not check for any response after sending this packet. -If you want to format these Info files yourself, you need one of the -Info formatting programs, such as @code{texinfo-format-buffer} or -@code{makeinfo}. +@item reserved +@tab @code{e} +@tab Reserved for future use -If you have @code{makeinfo} installed, and are in the top level -@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of -version @value{GDBVN}), you can make the Info file by typing: +@item reserved +@tab @code{E} +@tab Reserved for future use -@example -cd gdb -make gdb.info -@end example +@item reserved +@tab @code{f} +@tab Reserved for future use -If you want to typeset and print copies of this manual, you need @TeX{}, -a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the -Texinfo definitions file. +@item reserved +@tab @code{F} +@tab Reserved for future use -@TeX{} is a typesetting program; it does not print files directly, but -produces output files called @sc{dvi} files. To print a typeset -document, you need a program to print @sc{dvi} files. If your system -has @TeX{} installed, chances are it has such a program. The precise -command to use depends on your system; @kbd{lpr -d} is common; another -(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may -require a file name without any extension or a @samp{.dvi} extension. +@item read registers +@tab @code{g} +@tab Read general registers. +@item +@tab reply @var{XX...} +@tab +Each byte of register data is described by two hex digits. The bytes +with the register are transmitted in target byte order. The size of +each register and their position within the @samp{g} @var{packet} are +determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and +@var{REGISTER_NAME} macros. The specification of several standard +@code{g} packets is specified below. +@item +@tab @code{E}@var{NN} +@tab for an error. -@TeX{} also requires a macro definitions file called -@file{texinfo.tex}. This file tells @TeX{} how to typeset a document -written in Texinfo format. On its own, @TeX{} cannot either read or -typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB -and is located in the @file{gdb-@var{version-number}/texinfo} -directory. +@item write regs +@tab @code{G}@var{XX...} +@tab +See @samp{g} for a description of the @var{XX...} data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error -If you have @TeX{} and a @sc{dvi} printer program installed, you can -typeset and print this manual. First switch to the the @file{gdb} -subdirectory of the main source directory (for example, to -@file{gdb-@value{GDBVN}/gdb}) and type: +@item reserved +@tab @code{h} +@tab Reserved for future use -@example -make gdb.dvi -@end example +@item set thread +@tab @code{H}@var{c}@var{t...} +@tab +Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, +@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and +continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for +thread used in other operations. If zero, pick a thread, any thread. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error -Then give @file{gdb.dvi} to your @sc{dvi} printing program. +@c FIXME: JTC: +@c 'H': How restrictive (or permissive) is the thread model. If a +@c thread is selected and stopped, are other threads allowed +@c to continue to execute? As I mentioned above, I think the +@c semantics of each command when a thread is selected must be +@c described. For example: +@c +@c 'g': If the stub supports threads and a specific thread is +@c selected, returns the register block from that thread; +@c otherwise returns current registers. +@c +@c 'G' If the stub supports threads and a specific thread is +@c selected, sets the registers of the register block of +@c that thread; otherwise sets current registers. -@node Installing GDB -@appendix Installing @value{GDBN} -@cindex configuring @value{GDBN} -@cindex installation +@item cycle step @strong{(draft)} +@tab @code{i}@var{addr}@code{,}@var{nnn} +@tab +Step the remote target by a single clock cycle. If @code{,}@var{nnn} is +present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle +step starting at that address. -@value{GDBN} comes with a @code{configure} script that automates the process -of preparing @value{GDBN} for installation; you can then use @code{make} to -build the @code{gdb} program. -@iftex -@c irrelevant in info file; it's as current as the code it lives with. -@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, -look at the @file{README} file in the sources; we may have improved the -installation procedures since publishing this manual.} -@end iftex +@item signal then cycle step @strong{(reserved)} +@tab @code{I} +@tab +See @samp{i} and @samp{S} for likely syntax and semantics. -The @value{GDBN} distribution includes all the source code you need for -@value{GDBN} in a single directory, whose name is usually composed by -appending the version number to @samp{gdb}. +@item reserved +@tab @code{j} +@tab Reserved for future use -For example, the @value{GDBN} version @value{GDBVN} distribution is in the -@file{gdb-@value{GDBVN}} directory. That directory contains: +@item reserved +@tab @code{J} +@tab Reserved for future use -@table @code -@item gdb-@value{GDBVN}/configure @r{(and supporting files)} -script for configuring @value{GDBN} and all its supporting libraries +@item kill request +@tab @code{k} +@tab +FIXME: @emph{There is no description of how operate when a specific +thread context has been selected (ie. does 'k' kill only that thread?)}. -@item gdb-@value{GDBVN}/gdb -the source specific to @value{GDBN} itself +@item reserved +@tab @code{l} +@tab Reserved for future use -@item gdb-@value{GDBVN}/bfd -source for the Binary File Descriptor library +@item reserved +@tab @code{L} +@tab Reserved for future use -@item gdb-@value{GDBVN}/include -@sc{gnu} include files +@item read memory +@tab @code{m}@var{addr}@code{,}@var{length} +@tab +Read @var{length} bytes of memory starting at address @var{addr}. +Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed +using word alligned accesses. FIXME: @emph{A word aligned memory +transfer mechanism is needed.} +@item +@tab reply @var{XX...} +@tab +@var{XX...} is mem contents. Can be fewer bytes than requested if able +to read only part of the data. Neither @value{GDBN} nor the stub assume that +sized memory transfers are assumed using word alligned accesses. FIXME: +@emph{A word aligned memory transfer mechanism is needed.} +@item +@tab reply @code{E}@var{NN} +@tab @var{NN} is errno -@item gdb-@value{GDBVN}/libiberty -source for the @samp{-liberty} free software library +@item write mem +@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...} +@tab +Write @var{length} bytes of memory starting at address @var{addr}. +@var{XX...} is the data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab +for an error (this includes the case where only part of the data was +written). -@item gdb-@value{GDBVN}/opcodes -source for the library of opcode tables and disassemblers +@item reserved +@tab @code{n} +@tab Reserved for future use -@item gdb-@value{GDBVN}/readline -source for the @sc{gnu} command-line interface +@item reserved +@tab @code{N} +@tab Reserved for future use -@item gdb-@value{GDBVN}/glob -source for the @sc{gnu} filename pattern-matching subroutine +@item reserved +@tab @code{o} +@tab Reserved for future use -@item gdb-@value{GDBVN}/mmalloc -source for the @sc{gnu} memory-mapped malloc package -@end table +@item reserved +@tab @code{O} +@tab Reserved for future use -The simplest way to configure and build @value{GDBN} is to run @code{configure} -from the @file{gdb-@var{version-number}} source directory, which in -this example is the @file{gdb-@value{GDBVN}} directory. +@item read reg @strong{(reserved)} +@tab @code{p}@var{n...} +@tab +See write register. +@item +@tab return @var{r....} +@tab The hex encoded value of the register in target byte order. -First switch to the @file{gdb-@var{version-number}} source directory -if you are not already in it; then run @code{configure}. Pass the -identifier for the platform on which @value{GDBN} will run as an -argument. +@item write reg +@tab @code{P}@var{n...}@code{=}@var{r...} +@tab +Write register @var{n...} with value @var{r...}, which contains two hex +digits for each byte in the register (target byte order). +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error -For example: +@item general query +@tab @code{q}@var{query} +@tab +Request info about @var{query}. In general @value{GDBN} queries +have a leading upper case letter. Custom vendor queries should use a +company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may +optionally be followed by a @samp{,} or @samp{;} separated list. Stubs +must ensure that they match the full @var{query} name. +@item +@tab reply @code{XX...} +@tab Hex encoded data from query. The reply can not be empty. +@item +@tab reply @code{E}@var{NN} +@tab error reply +@item +@tab reply @samp{} +@tab Indicating an unrecognized @var{query}. -@example -cd gdb-@value{GDBVN} -./configure @var{host} -make -@end example +@item general set +@tab @code{Q}@var{var}@code{=}@var{val} +@tab +Set value of @var{var} to @var{val}. See @samp{q} for a discussing of +naming conventions. -@noindent -where @var{host} is an identifier such as @samp{sun4} or -@samp{decstation}, that identifies the platform where @value{GDBN} will run. -(You can often leave off @var{host}; @code{configure} tries to guess the -correct value by examining your system.) +@item reset @strong{(deprecated)} +@tab @code{r} +@tab +Reset the entire system. -Running @samp{configure @var{host}} and then running @code{make} builds the -@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} -libraries, then @code{gdb} itself. The configured source files, and the -binaries, are left in the corresponding source directories. +@item remote restart +@tab @code{R}@var{XX} +@tab +Restart the program being debugged. @var{XX}, while needed, is ignored. +This packet is only available in extended mode. +@item +@tab +no reply +@tab +The @samp{R} packet has no reply. -@need 750 -@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your -system does not recognize this automatically when you run a different -shell, you may need to run @code{sh} on it explicitly: +@item step +@tab @code{s}@var{addr} +@tab +@var{addr} is address to resume. If @var{addr} is omitted, resume at +same address. +@item +@tab reply +@tab see below -@example -sh configure @var{host} -@end example +@item step with signal +@tab @code{S}@var{sig}@code{;}@var{addr} +@tab +Like @samp{C} but step not continue. +@item +@tab reply +@tab see below -If you run @code{configure} from a directory that contains source -directories for multiple libraries or programs, such as the -@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure} -creates configuration files for every directory level underneath (unless -you tell it not to, with the @samp{--norecursion} option). +@item search +@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} +@tab +Search backwards starting at address @var{addr} for a match with pattern +@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 +bytes. @var{addr} must be at least 3 digits. -You can run the @code{configure} script from any of the -subordinate directories in the @value{GDBN} distribution if you only want to -configure that subdirectory, but be sure to specify a path to it. +@item thread alive +@tab @code{T}@var{XX} +@tab Find out if the thread XX is alive. +@item +@tab reply @code{OK} +@tab thread is still alive +@item +@tab reply @code{E}@var{NN} +@tab thread is dead -For example, with version @value{GDBVN}, type the following to configure only -the @code{bfd} subdirectory: +@item reserved +@tab @code{u} +@tab Reserved for future use -@example -@group -cd gdb-@value{GDBVN}/bfd -../configure @var{host} -@end group -@end example +@item reserved +@tab @code{U} +@tab Reserved for future use -You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. -However, you should make sure that the shell on your path (named by -the @samp{SHELL} environment variable) is publicly readable. Remember -that @value{GDBN} uses the shell to start your program---some systems refuse to -let @value{GDBN} debug child processes whose programs are not readable. +@item reserved +@tab @code{v} +@tab Reserved for future use -@menu -* Separate Objdir:: Compiling @value{GDBN} in another directory -* Config Names:: Specifying names for hosts and targets -* Configure Options:: Summary of options for configure -@end menu +@item reserved +@tab @code{V} +@tab Reserved for future use -@node Separate Objdir -@section Compiling @value{GDBN} in another directory +@item reserved +@tab @code{w} +@tab Reserved for future use -If you want to run @value{GDBN} versions for several host or target machines, -you need a different @code{gdb} compiled for each combination of -host and target. @code{configure} is designed to make this easy by -allowing you to generate each configuration in a separate subdirectory, -rather than in the source directory. If your @code{make} program -handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running -@code{make} in each of these directories builds the @code{gdb} -program specified there. +@item reserved +@tab @code{W} +@tab Reserved for future use -To build @code{gdb} in a separate directory, run @code{configure} -with the @samp{--srcdir} option to specify where to find the source. -(You also need to specify a path to find @code{configure} -itself from your working directory. If the path to @code{configure} -would be the same as the argument to @samp{--srcdir}, you can leave out -the @samp{--srcdir} option; it is assumed.) +@item reserved +@tab @code{x} +@tab Reserved for future use -For example, with version @value{GDBVN}, you can build @value{GDBN} in a -separate directory for a Sun 4 like this: +@item write mem (binary) +@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...} +@tab +@var{addr} is address, @var{length} is number of bytes, @var{XX...} is +binary data. The characters @code{$}, @code{#}, and @code{0x7d} are +escaped using @code{0x7d}. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error -@example -@group -cd gdb-@value{GDBVN} -mkdir ../gdb-sun4 -cd ../gdb-sun4 -../gdb-@value{GDBVN}/configure sun4 -make -@end group -@end example +@item reserved +@tab @code{y} +@tab Reserved for future use -When @code{configure} builds a configuration using a remote source -directory, it creates a tree for the binaries with the same structure -(and using the same names) as the tree under the source directory. In -the example, you'd find the Sun 4 library @file{libiberty.a} in the -directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in -@file{gdb-sun4/gdb}. +@item reserved +@tab @code{Y} +@tab Reserved for future use -One popular reason to build several @value{GDBN} configurations in separate -directories is to configure @value{GDBN} for cross-compiling (where -@value{GDBN} runs on one machine---the @dfn{host}---while debugging -programs that run on another machine---the @dfn{target}). -You specify a cross-debugging target by -giving the @samp{--target=@var{target}} option to @code{configure}. +@item remove break or watchpoint @strong{(draft)} +@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} +@tab +See @samp{Z}. -When you run @code{make} to build a program or library, you must run -it in a configured directory---whatever directory you were in when you -called @code{configure} (or one of its subdirectories). +@item insert break or watchpoint @strong{(draft)} +@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} +@tab +@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware +breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, +@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in +bytes. For a software breakpoint, @var{length} specifies the size of +the instruction to be patched. For hardware breakpoints and watchpoints +@var{length} specifies the memory region to be monitored. To avoid +potential problems with duplicate packets, the operations should be +implemented in an idempotent way. +@item +@tab reply @code{E}@var{NN} +@tab for an error +@item +@tab reply @code{OK} +@tab for success +@item +@tab @samp{} +@tab If not supported. -The @code{Makefile} that @code{configure} generates in each source -directory also runs recursively. If you type @code{make} in a source -directory such as @file{gdb-@value{GDBVN}} (or in a separate configured -directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you -will build all the required libraries, and then build GDB. +@item reserved +@tab +@tab Reserved for future use -When you have multiple hosts or targets configured in separate -directories, you can run @code{make} on them in parallel (for example, -if they are NFS-mounted on each of the hosts); they will not interfere -with each other. +@end multitable -@node Config Names -@section Specifying names for hosts and targets +The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can +receive any of the below as a reply. In the case of the @samp{C}, +@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned +when the target halts. In the below the exact meaning of @samp{signal +number} is poorly defined. In general one of the UNIX signal numbering +conventions is used. -The specifications used for hosts and targets in the @code{configure} -script are based on a three-part naming scheme, but some short predefined -aliases are also supported. The full naming scheme encodes three pieces -of information in the following pattern: +@multitable @columnfractions .4 .6 -@example -@var{architecture}-@var{vendor}-@var{os} -@end example +@item @code{S}@var{AA} +@tab @var{AA} is the signal number -For example, you can use the alias @code{sun4} as a @var{host} argument, -or as the value for @var{target} in a @code{--target=@var{target}} -option. The equivalent full name is @samp{sparc-sun-sunos4}. +@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} +@tab +@var{AA} = two hex digit signal number; @var{n...} = register number +(hex), @var{r...} = target byte ordered register contents, size defined +by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = +thread process ID, this is a hex integer; @var{n...} = other string not +starting with valid hex digit. @value{GDBN} should ignore this +@var{n...}, @var{r...} pair and go on to the next. This way we can +extend the protocol. -The @code{configure} script accompanying @value{GDBN} does not provide -any query facility to list all supported host and target names or -aliases. @code{configure} calls the Bourne shell script -@code{config.sub} to map abbreviations to full names; you can read the -script, if you wish, or you can use it to test your guesses on -abbreviations---for example: +@item @code{W}@var{AA} +@tab +The process exited, and @var{AA} is the exit status. This is only +applicable for certains sorts of targets. -@smallexample -% sh config.sub i386-linux -i386-pc-linux-gnu -% sh config.sub alpha-linux -alpha-unknown-linux-gnu -% sh config.sub hp9k700 -hppa1.1-hp-hpux -% sh config.sub sun4 -sparc-sun-sunos4.1.1 -% sh config.sub sun3 -m68k-sun-sunos4.1.1 -% sh config.sub i986v -Invalid configuration `i986v': machine `i986v' not recognized -@end smallexample +@item @code{X}@var{AA} +@tab +The process terminated with signal @var{AA}. -@noindent -@code{config.sub} is also distributed in the @value{GDBN} source -directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). +@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)} +@tab +@var{AA} = signal number; @var{t...} = address of symbol "_start"; +@var{d...} = base of data section; @var{b...} = base of bss section. +@emph{Note: only used by Cisco Systems targets. The difference between +this reply and the "qOffsets" query is that the 'N' packet may arrive +spontaneously whereas the 'qOffsets' is a query initiated by the host +debugger.} -@node Configure Options -@section @code{configure} options +@item @code{O}@var{XX...} +@tab +@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time +while the program is running and the debugger should continue to wait +for 'W', 'T', etc. -Here is a summary of the @code{configure} options and arguments that -are most often useful for building @value{GDBN}. @code{configure} also has -several other options not listed here. @inforef{What Configure -Does,,configure.info}, for a full explanation of @code{configure}. +@end multitable -@example -configure @r{[}--help@r{]} - @r{[}--prefix=@var{dir}@r{]} - @r{[}--exec-prefix=@var{dir}@r{]} - @r{[}--srcdir=@var{dirname}@r{]} - @r{[}--norecursion@r{]} @r{[}--rm@r{]} - @r{[}--target=@var{target}@r{]} - @var{host} -@end example +The following set and query packets have already been defined. -@noindent -You may introduce options with a single @samp{-} rather than -@samp{--} if you prefer; but you may abbreviate option names if you use -@samp{--}. +@multitable @columnfractions .2 .2 .6 -@table @code -@item --help -Display a quick summary of how to invoke @code{configure}. +@item current thread +@tab @code{q}@code{C} +@tab Return the current thread id. +@item +@tab reply @code{QC}@var{pid} +@tab +Where @var{pid} is a HEX encoded 16 bit process id. +@item +@tab reply * +@tab Any other reply implies the old pid. -@item --prefix=@var{dir} -Configure the source to install programs and files under directory -@file{@var{dir}}. +@item all thread ids +@tab @code{q}@code{fThreadInfo} +@item +@tab @code{q}@code{sThreadInfo} +@tab +Obtain a list of active thread ids from the target (OS). Since there +may be too many active threads to fit into one reply packet, this query +works iteratively: it may require more than one query/reply sequence to +obtain the entire list of threads. The first query of the sequence will +be the @code{qf}@code{ThreadInfo} query; subsequent queries in the +sequence will be the @code{qs}@code{ThreadInfo} query. +@item +@tab +@tab NOTE: replaces the @code{qL} query (see below). +@item +@tab reply @code{m}@var{} +@tab A single thread id +@item +@tab reply @code{m}@var{},@var{...} +@tab a comma-separated list of thread ids +@item +@tab reply @code{l} +@tab (lower case 'el') denotes end of list. +@item +@tab +@tab +In response to each query, the target will reply with a list of one +or more thread ids, in big-endian hex, separated by commas. GDB will +respond to each reply with a request for more thread ids (using the +@code{qs} form of the query), until the target responds with @code{l} +(lower-case el, for @code{'last'}). -@item --exec-prefix=@var{dir} -Configure the source to install programs under directory -@file{@var{dir}}. +@item extra thread info +@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id} +@tab +@item +@tab +@tab +Where @var{} is a thread-id in big-endian hex. +Obtain a printable string description of a thread's attributes from +the target OS. This string may contain anything that the target OS +thinks is interesting for @value{GDBN} to tell the user about the thread. +The string is displayed in @value{GDBN}'s @samp{info threads} display. +Some examples of possible thread extra info strings are "Runnable", or +"Blocked on Mutex". +@item +@tab reply @var{XX...} +@tab +Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the +printable string containing the extra information about the thread's +attributes. -@c avoid splitting the warning from the explanation: -@need 2000 -@item --srcdir=@var{dirname} -@strong{Warning: using this option requires @sc{gnu} @code{make}, or another -@code{make} that implements the @code{VPATH} feature.}@* -Use this option to make configurations in directories separate from the -@value{GDBN} source directories. Among other things, you can use this to -build (or maintain) several configurations simultaneously, in separate -directories. @code{configure} writes configuration specific files in -the current directory, but arranges for them to use the source in the -directory @var{dirname}. @code{configure} creates directories under -the working directory in parallel to the source directories below -@var{dirname}. +@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)} +@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} +@tab +@item +@tab +@tab +Obtain thread information from RTOS. Where: @var{startflag} (one hex +digit) is one to indicate the first query and zero to indicate a +subsequent query; @var{threadcount} (two hex digits) is the maximum +number of threads the response packet can contain; and @var{nextthread} +(eight hex digits), for subsequent queries (@var{startflag} is zero), is +returned in the response as @var{argthread}. +@item +@tab +@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo} +query (see above). +@item +@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...} +@tab +@item +@tab +@tab +Where: @var{count} (two hex digits) is the number of threads being +returned; @var{done} (one hex digit) is zero to indicate more threads +and one indicates no further threads; @var{argthreadid} (eight hex +digits) is @var{nextthread} from the request packet; @var{thread...} is +a sequence of thread IDs from the target. @var{threadid} (eight hex +digits). See @code{remote.c:parse_threadlist_response()}. -@item --norecursion -Configure only the directory level where @code{configure} is executed; do not -propagate configuration to subdirectories. +@item compute CRC of memory block +@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length} +@tab +@item +@tab reply @code{E}@var{NN} +@tab An error (such as memory fault) +@item +@tab reply @code{C}@var{CRC32} +@tab A 32 bit cyclic redundancy check of the specified memory region. -@item --target=@var{target} -Configure @value{GDBN} for cross-debugging programs running on the specified -@var{target}. Without this option, @value{GDBN} is configured to debug -programs that run on the same machine (@var{host}) as @value{GDBN} itself. +@item query sect offs +@tab @code{q}@code{Offsets} +@tab +Get section offsets that the target used when re-locating the downloaded +image. @emph{Note: while a @code{Bss} offset is included in the +response, @value{GDBN} ignores this and instead applies the @code{Data} +offset to the @code{Bss} section.} +@item +@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} -There is no convenient way to generate a list of all available targets. +@item thread info request +@tab @code{q}@code{P}@var{mode}@var{threadid} +@tab +@item +@tab +@tab +Returns information on @var{threadid}. Where: @var{mode} is a hex +encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. +@item +@tab reply * +@tab +See @code{remote.c:remote_unpack_thread_info_response()}. -@item @var{host} @dots{} -Configure @value{GDBN} to run on the specified @var{host}. +@item remote command +@tab @code{q}@code{Rcmd,}@var{COMMAND} +@tab +@item +@tab +@tab +@var{COMMAND} (hex encoded) is passed to the local interpreter for +execution. Invalid commands should be reported using the output string. +Before the final result packet, the target may also respond with a +number of intermediate @code{O}@var{OUTPUT} console output +packets. @emph{Implementors should note that providing access to a +stubs's interpreter may have security implications}. +@item +@tab reply @code{OK} +@tab +A command response with no output. +@item +@tab reply @var{OUTPUT} +@tab +A command response with the hex encoded output string @var{OUTPUT}. +@item +@tab reply @code{E}@var{NN} +@tab +Indicate a badly formed request. -There is no convenient way to generate a list of all available hosts. -@end table +@item +@tab reply @samp{} +@tab +When @samp{q}@samp{Rcmd} is not recognized. -There are many other options available as well, but they are generally -needed for special purposes only. +@item symbol lookup +@tab @code{qSymbol::} +@tab +Notify the target that @value{GDBN} is prepared to serve symbol lookup +requests. Accept requests from the target for the values of symbols. +@item +@tab +@tab +@item +@tab reply @code{OK} +@tab +The target does not need to look up any (more) symbols. +@item +@tab reply @code{qSymbol:}@var{sym_name} +@tab +@sp 2 +@noindent +The target requests the value of symbol @var{sym_name} (hex encoded). +@value{GDBN} may provide the value by using the +@code{qSymbol:}@var{sym_value}:@var{sym_name} +message, described below. -@node Maintenance Commands -@appendix Maintenance Commands -@cindex maintenance commands -@cindex internal commands +@item symbol value +@tab @code{qSymbol:}@var{sym_value}:@var{sym_name} +@tab +@sp 1 +@noindent +Set the value of SYM_NAME to SYM_VALUE. +@item +@tab +@tab +@var{sym_name} (hex encoded) is the name of a symbol whose value +the target has previously requested. +@item +@tab +@tab +@var{sym_value} (hex) is the value for symbol @var{sym_name}. +If @value{GDBN} cannot supply a value for @var{sym_name}, then this +field will be empty. +@item +@tab reply @code{OK} +@tab +The target does not need to look up any (more) symbols. +@item +@tab reply @code{qSymbol:}@var{sym_name} +@tab +@sp 2 +@noindent +The target requests the value of a new symbol @var{sym_name} (hex encoded). +@value{GDBN} will continue to supply the values of symbols (if available), +until the target ceases to request them. -In addition to commands intended for @value{GDBN} users, @value{GDBN} -includes a number of commands intended for @value{GDBN} developers. -These commands are provided here for reference. +@end multitable -@table @code -@kindex maint info breakpoints -@item @anchor{maint info breakpoints}maint info breakpoints -Using the same format as @samp{info breakpoints}, display both the -breakpoints you've set explicitly, and those @value{GDBN} is using for -internal purposes. Internal breakpoints are shown with negative -breakpoint numbers. The type column identifies what kind of breakpoint -is shown: +The following @samp{g}/@samp{G} packets have previously been defined. +In the below, some thirty-two bit registers are transferred as sixty-four +bits. Those registers should be zero/sign extended (which?) to fill the +space allocated. Register bytes are transfered in target byte order. +The two nibbles within a register byte are transfered most-significant - +least-significant. -@table @code -@item breakpoint -Normal, explicitly set breakpoint. +@multitable @columnfractions .5 .5 -@item watchpoint -Normal, explicitly set watchpoint. +@item MIPS32 +@tab +All registers are transfered as thirty-two bit quantities in the order: +32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point +registers; fsr; fir; fp. -@item longjmp -Internal breakpoint, used to handle correctly stepping through -@code{longjmp} calls. +@item MIPS64 +@tab +All registers are transfered as sixty-four bit quantities (including +thirty-two bit registers such as @code{sr}). The ordering is the same +as @code{MIPS32}. -@item longjmp resume -Internal breakpoint at the target of a @code{longjmp}. +@end multitable -@item until -Temporary internal breakpoint used by the @value{GDBN} @code{until} command. +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: -@item finish -Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. +@example +<- @code{R00} +-> @code{+} +@emph{target restarts} +<- @code{?} +-> @code{+} +-> @code{T001:1234123412341234} +<- @code{+} +@end example -@item shlib events -Shared library events. +Example sequence of a target being stepped by a single instruction: -@end table +@example +<- @code{G1445...} +-> @code{+} +<- @code{s} +-> @code{+} +@emph{time passes} +-> @code{T001:1234123412341234} +<- @code{+} +<- @code{g} +-> @code{+} +-> @code{1455...} +<- @code{+} +@end example -@end table @include fdl.texi -- 2.7.4