1 This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
2 the input file gdb.texinfo.
5 * Gdb: (gdb). The GNU debugger.
7 This file documents the GNU debugger GDB.
9 This is the Seventh Edition, February 1999, of `Debugging with GDB:
10 the GNU Source-Level Debugger' for GDB Version 4.18.
12 Copyright (C) 1988-1999 Free Software Foundation, Inc.
14 Permission is granted to make and distribute verbatim copies of this
15 manual provided the copyright notice and this permission notice are
16 preserved on all copies.
18 Permission is granted to copy and distribute modified versions of
19 this manual under the conditions for verbatim copying, provided also
20 that the entire resulting derived work is distributed under the terms
21 of a permission notice identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
28 File: gdb.info, Node: Files, Next: Symbol Errors, Prev: GDB Files, Up: GDB Files
30 Commands to specify files
31 =========================
33 You may want to specify executable and core dump file names. The
34 usual way to do this is at start-up time, using the arguments to GDB's
35 start-up commands (*note Getting In and Out of GDB: Invocation.).
37 Occasionally it is necessary to change to a different file during a
38 GDB session. Or you may run GDB and forget to specify a file you want
39 to use. In these situations the GDB commands to specify new files are
43 Use FILENAME as the program to be debugged. It is read for its
44 symbols and for the contents of pure memory. It is also the
45 program executed when you use the `run' command. If you do not
46 specify a directory and the file is not found in the GDB working
47 directory, GDB uses the environment variable `PATH' as a list of
48 directories to search, just as the shell does when looking for a
49 program to run. You can change the value of this variable, for
50 both GDB and your program, using the `path' command.
52 On systems with memory-mapped files, an auxiliary file
53 `FILENAME.syms' may hold symbol table information for FILENAME.
54 If so, GDB maps in the symbol table from `FILENAME.syms', starting
55 up more quickly. See the descriptions of the file options
56 `-mapped' and `-readnow' (available on the command line, and with
57 the commands `file', `symbol-file', or `add-symbol-file',
58 described below), for more information.
61 `file' with no argument makes GDB discard any information it has
62 on both executable file and the symbol table.
64 `exec-file [ FILENAME ]'
65 Specify that the program to be run (but not the symbol table) is
66 found in FILENAME. GDB searches the environment variable `PATH'
67 if necessary to locate your program. Omitting FILENAME means to
68 discard information on the executable file.
70 `symbol-file [ FILENAME ]'
71 Read symbol table information from file FILENAME. `PATH' is
72 searched when necessary. Use the `file' command to get both symbol
73 table and program to run from the same file.
75 `symbol-file' with no argument clears out GDB information on your
76 program's symbol table.
78 The `symbol-file' command causes GDB to forget the contents of its
79 convenience variables, the value history, and all breakpoints and
80 auto-display expressions. This is because they may contain
81 pointers to the internal data recording symbols and data types,
82 which are part of the old symbol table data being discarded inside
85 `symbol-file' does not repeat if you press <RET> again after
88 When GDB is configured for a particular environment, it
89 understands debugging information in whatever format is the
90 standard generated for that environment; you may use either a GNU
91 compiler, or other compilers that adhere to the local conventions.
92 Best results are usually obtained from GNU compilers; for example,
93 using `gcc' you can generate debugging information for optimized
96 For most kinds of object files, with the exception of old SVR3
97 systems using COFF, the `symbol-file' command does not normally
98 read the symbol table in full right away. Instead, it scans the
99 symbol table quickly to find which source files and which symbols
100 are present. The details are read later, one source file at a
101 time, as they are needed.
103 The purpose of this two-stage reading strategy is to make GDB
104 start up faster. For the most part, it is invisible except for
105 occasional pauses while the symbol table details for a particular
106 source file are being read. (The `set verbose' command can turn
107 these pauses into messages if desired. *Note Optional warnings
108 and messages: Messages/Warnings.)
110 We have not implemented the two-stage strategy for COFF yet. When
111 the symbol table is stored in COFF format, `symbol-file' reads the
112 symbol table data in full right away. Note that "stabs-in-COFF"
113 still does the two-stage strategy, since the debug info is actually
116 `symbol-file FILENAME [ -readnow ] [ -mapped ]'
117 `file FILENAME [ -readnow ] [ -mapped ]'
118 You can override the GDB two-stage strategy for reading symbol
119 tables by using the `-readnow' option with any of the commands that
120 load symbol table information, if you want to be sure GDB has the
121 entire symbol table available.
123 If memory-mapped files are available on your system through the
124 `mmap' system call, you can use another option, `-mapped', to
125 cause GDB to write the symbols for your program into a reusable
126 file. Future GDB debugging sessions map in symbol information
127 from this auxiliary symbol file (if the program has not changed),
128 rather than spending time reading the symbol table from the
129 executable program. Using the `-mapped' option has the same
130 effect as starting GDB with the `-mapped' command-line option.
132 You can use both options together, to make sure the auxiliary
133 symbol file has all the symbol information for your program.
135 The auxiliary symbol file for a program called MYPROG is called
136 `MYPROG.syms'. Once this file exists (so long as it is newer than
137 the corresponding executable), GDB always attempts to use it when
138 you debug MYPROG; no special options or commands are needed.
140 The `.syms' file is specific to the host machine where you run
141 GDB. It holds an exact image of the internal GDB symbol table.
142 It cannot be shared across multiple host platforms.
144 `core-file [ FILENAME ]'
145 Specify the whereabouts of a core dump file to be used as the
146 "contents of memory". Traditionally, core files contain only some
147 parts of the address space of the process that generated them; GDB
148 can access the executable file itself for other parts.
150 `core-file' with no argument specifies that no core file is to be
153 Note that the core file is ignored when your program is actually
154 running under GDB. So, if you have been running your program and
155 you wish to debug a core file instead, you must kill the
156 subprocess in which the program is running. To do this, use the
157 `kill' command (*note Killing the child process: Kill Process.).
159 `add-symbol-file FILENAME ADDRESS'
160 `add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]'
161 The `add-symbol-file' command reads additional symbol table
162 information from the file FILENAME. You would use this command
163 when FILENAME has been dynamically loaded (by some other means)
164 into the program that is running. ADDRESS should be the memory
165 address at which the file has been loaded; GDB cannot figure this
166 out for itself. You can specify ADDRESS as an expression.
168 The symbol table of the file FILENAME is added to the symbol table
169 originally read with the `symbol-file' command. You can use the
170 `add-symbol-file' command any number of times; the new symbol data
171 thus read keeps adding to the old. To discard all old symbol data
172 instead, use the `symbol-file' command.
174 `add-symbol-file' does not repeat if you press <RET> after using
177 You can use the `-mapped' and `-readnow' options just as with the
178 `symbol-file' command, to change how GDB manages the symbol table
179 information for FILENAME.
181 `add-shared-symbol-file'
182 The `add-shared-symbol-file' command can be used only under
183 Harris' CXUX operating system for the Motorola 88k. GDB
184 automatically looks for shared libraries, however if GDB does not
185 find yours, you can run `add-shared-symbol-file'. It takes no
189 The `section' command changes the base address of section SECTION
190 of the exec file to ADDR. This can be used if the exec file does
191 not contain section addresses, (such as in the a.out format), or
192 when the addresses specified in the file itself are wrong. Each
193 section must be changed separately. The "info files" command
194 lists all the sections and their addresses.
198 `info files' and `info target' are synonymous; both print the
199 current target (*note Specifying a Debugging Target: Targets.),
200 including the names of the executable and core dump files
201 currently in use by GDB, and the files from which symbols were
202 loaded. The command `help target' lists all possible targets
203 rather than current ones.
205 All file-specifying commands allow both absolute and relative file
206 names as arguments. GDB always converts the file name to an absolute
207 file name and remembers it that way.
209 GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
210 libraries. GDB automatically loads symbol definitions from shared
211 libraries when you use the `run' command, or when you examine a core
212 file. (Before you issue the `run' command, GDB does not understand
213 references to a function in a shared library, however--unless you are
214 debugging a core file).
218 Print the names of the shared libraries which are currently loaded.
220 `sharedlibrary REGEX'
222 Load shared object library symbols for files matching a Unix
223 regular expression. As with files loaded automatically, it only
224 loads shared libraries required by your program for a core file or
225 after typing `run'. If REGEX is omitted all shared libraries
226 required by your program are loaded.
229 File: gdb.info, Node: Symbol Errors, Prev: Files, Up: GDB Files
231 Errors reading symbol files
232 ===========================
234 While reading a symbol file, GDB occasionally encounters problems,
235 such as symbol types it does not recognize, or known bugs in compiler
236 output. By default, GDB does not notify you of such problems, since
237 they are relatively common and primarily of interest to people
238 debugging compilers. If you are interested in seeing information about
239 ill-constructed symbol tables, you can either ask GDB to print only one
240 message about each such type of problem, no matter how many times the
241 problem occurs; or you can ask GDB to print more messages, to see how
242 many times the problems occur, with the `set complaints' command (*note
243 Optional warnings and messages: Messages/Warnings.).
245 The messages currently printed, and their meanings, include:
247 `inner block not inside outer block in SYMBOL'
248 The symbol information shows where symbol scopes begin and end
249 (such as at the start of a function or a block of statements).
250 This error indicates that an inner scope block is not fully
251 contained in its outer scope blocks.
253 GDB circumvents the problem by treating the inner block as if it
254 had the same scope as the outer block. In the error message,
255 SYMBOL may be shown as "`(don't know)'" if the outer block is not a
258 `block at ADDRESS out of order'
259 The symbol information for symbol scope blocks should occur in
260 order of increasing addresses. This error indicates that it does
263 GDB does not circumvent this problem, and has trouble locating
264 symbols in the source file whose symbols it is reading. (You can
265 often determine what source file is affected by specifying `set
266 verbose on'. *Note Optional warnings and messages:
269 `bad block start address patched'
270 The symbol information for a symbol scope block has a start address
271 smaller than the address of the preceding source line. This is
272 known to occur in the SunOS 4.1.1 (and earlier) C compiler.
274 GDB circumvents the problem by treating the symbol scope block as
275 starting on the previous source line.
277 `bad string table offset in symbol N'
278 Symbol number N contains a pointer into the string table which is
279 larger than the size of the string table.
281 GDB circumvents the problem by considering the symbol to have the
282 name `foo', which may cause other problems if many symbols end up
285 `unknown symbol type `0xNN''
286 The symbol information contains new data types that GDB does not
287 yet know how to read. `0xNN' is the symbol type of the
288 misunderstood information, in hexadecimal.
290 GDB circumvents the error by ignoring this symbol information.
291 This usually allows you to debug your program, though certain
292 symbols are not accessible. If you encounter such a problem and
293 feel like debugging it, you can debug `gdb' with itself,
294 breakpoint on `complain', then go up to the function
295 `read_dbx_symtab' and examine `*bufp' to see the symbol.
297 `stub type has NULL name'
298 GDB could not find the full definition for a struct or class.
300 `const/volatile indicator missing (ok if using g++ v1.x), got...'
301 The symbol information for a C++ member function is missing some
302 information that recent versions of the compiler should have output
305 `info mismatch between compiler and debugger'
306 GDB could not parse a type specification output by the compiler.
309 File: gdb.info, Node: Targets, Next: Controlling GDB, Prev: GDB Files, Up: Top
311 Specifying a Debugging Target
312 *****************************
314 A "target" is the execution environment occupied by your program.
315 Often, GDB runs in the same host environment as your program; in that
316 case, the debugging target is specified as a side effect when you use
317 the `file' or `core' commands. When you need more flexibility--for
318 example, running GDB on a physically separate host, or controlling a
319 standalone system over a serial port or a realtime system over a TCP/IP
320 connection--you can use the `target' command to specify one of the
321 target types configured for GDB (*note Commands for managing targets:
326 * Active Targets:: Active targets
327 * Target Commands:: Commands for managing targets
329 * Byte Order:: Choosing target byte order
330 * Remote:: Remote debugging
333 File: gdb.info, Node: Active Targets, Next: Target Commands, Prev: Targets, Up: Targets
338 There are three classes of targets: processes, core files, and
339 executable files. GDB can work concurrently on up to three active
340 targets, one in each class. This allows you to (for example) start a
341 process and inspect its activity without abandoning your work on a core
344 For example, if you execute `gdb a.out', then the executable file
345 `a.out' is the only active target. If you designate a core file as
346 well--presumably from a prior run that crashed and coredumped--then GDB
347 has two active targets and uses them in tandem, looking first in the
348 corefile target, then in the executable file, to satisfy requests for
349 memory addresses. (Typically, these two classes of target are
350 complementary, since core files contain only a program's read-write
351 memory--variables and so on--plus machine status, while executable
352 files contain only the program text and initialized data.)
354 When you type `run', your executable file becomes an active process
355 target as well. When a process target is active, all GDB commands
356 requesting memory addresses refer to that target; addresses in an
357 active core file or executable file target are obscured while the
358 process target is active.
360 Use the `core-file' and `exec-file' commands to select a new core
361 file or executable target (*note Commands to specify files: Files.).
362 To specify as a target a process that is already running, use the
363 `attach' command (*note Debugging an already-running process: Attach.).
366 File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets
368 Commands for managing targets
369 =============================
371 `target TYPE PARAMETERS'
372 Connects the GDB host environment to a target machine or process.
373 A target is typically a protocol for talking to debugging
374 facilities. You use the argument TYPE to specify the type or
375 protocol of the target machine.
377 Further PARAMETERS are interpreted by the target protocol, but
378 typically include things like device names or host names to connect
379 with, process numbers, and baud rates.
381 The `target' command does not repeat if you press <RET> again
382 after executing the command.
385 Displays the names of all targets available. To display targets
386 currently selected, use either `info target' or `info files'
387 (*note Commands to specify files: Files.).
390 Describe a particular target, including any parameters necessary to
394 GDB uses its own library BFD to read your files. GDB knows
395 whether it is reading an "executable", a "core", or a ".o" file;
396 however, you can specify the file format with the `set gnutarget'
397 command. Unlike most `target' commands, with `gnutarget' the
398 `target' refers to a program, not a machine.
400 *Warning:* To specify a file format with `set gnutarget', you must
401 know the actual BFD name.
403 *Note Commands to specify files: Files.
406 Use the `show gnutarget' command to display what file format
407 `gnutarget' is set to read. If you have not set `gnutarget', GDB
408 will determine the file format for each file automatically, and
409 `show gnutarget' displays `The current BDF target is "auto"'.
411 Here are some common targets (available, or not, depending on the GDB
414 `target exec PROGRAM'
415 An executable file. `target exec PROGRAM' is the same as
418 `target core FILENAME'
419 A core dump file. `target core FILENAME' is the same as
420 `core-file FILENAME'.
423 Remote serial target in GDB-specific protocol. The argument DEV
424 specifies what serial device to use for the connection (e.g.
425 `/dev/ttya'). *Note Remote debugging: Remote. `target remote' now
426 supports the `load' command. This is only useful if you have some
427 other way of getting the stub to the target system, and you can put
428 it somewhere in memory where it won't get clobbered by the
432 CPU simulator. *Note Simulated CPU Target: Simulator.
434 The following targets are all CPU-specific, and only available for
435 specific configurations.
438 ABug ROM monitor for M68K.
441 Adapt monitor for A29K.
443 `target amd-eb DEV SPEED PROG'
444 Remote PC-resident AMD EB29K board, attached over serial lines.
445 DEV is the serial device, as for `target remote'; SPEED allows you
446 to specify the linespeed; and PROG is the name of the program to
447 be debugged, as it appears to DOS on the PC. *Note The EBMON
448 protocol for AMD29K: EB29K Remote.
451 Array Tech LSI33K RAID controller board.
454 BUG monitor, running on a MVME187 (m88k) board.
456 `target cpu32bug DEV'
457 CPU32BUG monitor, running on a CPU32 (M68K) board.
460 dBUG ROM monitor for Motorola ColdFire.
463 NEC's DDB monitor for Mips Vr4300.
466 DINK32 ROM monitor for PowerPC.
469 E7000 emulator for Hitachi H8 and SH.
472 ES-1800 emulator for M68K.
475 EST-300 ICE monitor, running on a CPU32 (M68K) board.
478 A Hitachi SH, H8/300, or H8/500 board, attached via serial line to
479 your host. Use special commands `device' and `speed' to control
480 the serial line and the communications speed used. *Note GDB and
481 Hitachi Microprocessors: Hitachi Remote.
484 LSI ROM monitor for Mips.
487 Mitsubishi M32R/D ROM monitor.
490 IDT/SIM ROM monitor for Mips.
493 MON960 monitor for Intel i960.
495 `target nindy DEVICENAME'
496 An Intel 960 board controlled by a Nindy Monitor. DEVICENAME is
497 the name of the serial device to use for the connection, e.g.
498 `/dev/ttya'. *Note GDB with a remote i960 (Nindy): i960-Nindy
502 NetROM ROM emulator. This target only supports downloading.
505 OP50N monitor, running on an OKI HPPA board.
508 PMON ROM monitor for Mips.
513 PPCBUG ROM monitor for PowerPC.
516 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
519 ARM Angel monitor, via RDI library interface.
525 ROM 68K monitor, running on an M68K IDP board.
528 ROMBUG ROM monitor for OS/9000.
531 SDS monitor, running on a PowerPC board (such as Motorola's ADS).
533 `target sparclite DEV'
534 Fujitsu sparclite boards, used only for the purpose of loading.
535 You must use an additional command to debug the program. For
536 example: target remote DEV using GDB standard remote protocol.
541 Hitachi SH-3 and SH-3E target systems.
543 `target st2000 DEV SPEED'
544 A Tandem ST2000 phone switch, running Tandem's STDBUG protocol.
545 DEV is the name of the device attached to the ST2000 serial line;
546 SPEED is the communication line speed. The arguments are not used
547 if GDB is configured to connect to the ST2000 using TCP or Telnet.
548 *Note GDB with a Tandem ST2000: ST2000 Remote.
551 Remote AMD29K target, using the AMD UDI protocol. The KEYWORD
552 argument specifies which 29K board or simulator to use. *Note The
553 UDI protocol for AMD29K: UDI29K Remote.
555 `target vxworks MACHINENAME'
556 A VxWorks system, attached via TCP/IP. The argument MACHINENAME
557 is the target system's machine name or IP address. *Note GDB and
558 VxWorks: VxWorks Remote.
561 W89K monitor, running on a Winbond HPPA board.
563 Different targets are available on different configurations of GDB;
564 your configuration may have more or fewer targets.
566 Many remote targets require you to download the executable's code
567 once you've successfully established a connection.
570 Depending on what remote debugging facilities are configured into
571 GDB, the `load' command may be available. Where it exists, it is
572 meant to make FILENAME (an executable) available for debugging on
573 the remote system--by downloading, or dynamic linking, for example.
574 `load' also records the FILENAME symbol table in GDB, like the
575 `add-symbol-file' command.
577 If your GDB does not have a `load' command, attempting to execute
578 it gets the error message "`You can't do that when your target is
581 The file is loaded at whatever address is specified in the
582 executable. For some object file formats, you can specify the
583 load address when you link the program; for other formats, like
584 a.out, the object file format specifies a fixed address.
586 On VxWorks, `load' links FILENAME dynamically on the current
587 target system as well as adding its symbols in GDB.
589 With the Nindy interface to an Intel 960 board, `load' downloads
590 FILENAME to the 960 as well as adding its symbols in GDB.
592 When you select remote debugging to a Hitachi SH, H8/300, or
593 H8/500 board (*note GDB and Hitachi Microprocessors: Hitachi
594 Remote.), the `load' command downloads your program to the Hitachi
595 board and also opens it as the current executable target for GDB
596 on your host (like the `file' command).
598 `load' does not repeat if you press <RET> again after using it.
601 File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets
603 Choosing target byte order
604 ==========================
606 Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
607 offer the ability to run either big-endian or little-endian byte
608 orders. Usually the executable or symbol will include a bit to
609 designate the endian-ness, and you will not need to worry about which
610 to use. However, you may still find it useful to adjust GDB's idea of
611 processor endian-ness manually.
614 Instruct GDB to assume the target is big-endian.
617 Instruct GDB to assume the target is little-endian.
620 Instruct GDB to use the byte order associated with the executable.
623 Display GDB's current idea of the target byte order.
625 Note that these commands merely adjust interpretation of symbolic
626 data on the host, and that they have absolutely no effect on the target
630 File: gdb.info, Node: Remote, Prev: Byte Order, Up: Targets
635 If you are trying to debug a program running on a machine that
636 cannot run GDB in the usual way, it is often useful to use remote
637 debugging. For example, you might use remote debugging on an operating
638 system kernel, or on a small system which does not have a general
639 purpose operating system powerful enough to run a full-featured
642 Some configurations of GDB have special serial or TCP/IP interfaces
643 to make this work with particular debugging targets. In addition, GDB
644 comes with a generic serial protocol (specific to GDB, but not specific
645 to any particular target system) which you can use if you write the
646 remote stubs--the code that runs on the remote system to communicate
649 Other remote targets may be available in your configuration of GDB;
650 use `help target' to list them.
655 * Remote Serial:: GDB remote serial protocol
657 * i960-Nindy Remote:: GDB with a remote i960 (Nindy)
659 * UDI29K Remote:: The UDI protocol for AMD29K
660 * EB29K Remote:: The EBMON protocol for AMD29K
662 * VxWorks Remote:: GDB and VxWorks
664 * ST2000 Remote:: GDB with a Tandem ST2000
666 * Hitachi Remote:: GDB and Hitachi Microprocessors
668 * MIPS Remote:: GDB and MIPS boards
670 * Sparclet Remote:: GDB and Sparclet boards
672 * Simulator:: Simulated CPU target
675 File: gdb.info, Node: Remote Serial, Next: i960-Nindy Remote, Up: Remote
677 The GDB remote serial protocol
678 ------------------------------
680 To debug a program running on another machine (the debugging
681 "target" machine), you must first arrange for all the usual
682 prerequisites for the program to run by itself. For example, for a C
685 1. A startup routine to set up the C runtime environment; these
686 usually have a name like `crt0'. The startup routine may be
687 supplied by your hardware supplier, or you may have to write your
690 2. You probably need a C subroutine library to support your program's
691 subroutine calls, notably managing input and output.
693 3. A way of getting your program to the other machine--for example, a
694 download program. These are often supplied by the hardware
695 manufacturer, but you may have to write your own from hardware
698 The next step is to arrange for your program to use a serial port to
699 communicate with the machine where GDB is running (the "host" machine).
700 In general terms, the scheme looks like this:
703 GDB already understands how to use this protocol; when everything
704 else is set up, you can simply use the `target remote' command
705 (*note Specifying a Debugging Target: Targets.).
708 you must link with your program a few special-purpose subroutines
709 that implement the GDB remote serial protocol. The file
710 containing these subroutines is called a "debugging stub".
712 On certain remote targets, you can use an auxiliary program
713 `gdbserver' instead of linking a stub into your program. *Note
714 Using the `gdbserver' program: Server, for details.
716 The debugging stub is specific to the architecture of the remote
717 machine; for example, use `sparc-stub.c' to debug programs on SPARC
720 These working remote stubs are distributed with GDB:
723 For Intel 386 and compatible architectures.
726 For Motorola 680x0 architectures.
729 For Hitachi SH architectures.
732 For SPARC architectures.
735 For Fujitsu SPARCLITE architectures.
737 The `README' file in the GDB distribution may list other recently
742 * Stub Contents:: What the stub can do for you
743 * Bootstrapping:: What you must do for the stub
744 * Debug Session:: Putting it all together
745 * Protocol:: Outline of the communication protocol
747 * Server:: Using the `gdbserver' program
749 * NetWare:: Using the `gdbserve.nlm' program
752 File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Serial
754 What the stub can do for you
755 ............................
757 The debugging stub for your architecture supplies these three
761 This routine arranges for `handle_exception' to run when your
762 program stops. You must call this subroutine explicitly near the
763 beginning of your program.
766 This is the central workhorse, but your program never calls it
767 explicitly--the setup code arranges for `handle_exception' to run
768 when a trap is triggered.
770 `handle_exception' takes control when your program stops during
771 execution (for example, on a breakpoint), and mediates
772 communications with GDB on the host machine. This is where the
773 communications protocol is implemented; `handle_exception' acts as
774 the GDB representative on the target machine; it begins by sending
775 summary information on the state of your program, then continues
776 to execute, retrieving and transmitting any information GDB needs,
777 until you execute a GDB command that makes your program resume; at
778 that point, `handle_exception' returns control to your own code on
782 Use this auxiliary subroutine to make your program contain a
783 breakpoint. Depending on the particular situation, this may be
784 the only way for GDB to get control. For instance, if your target
785 machine has some sort of interrupt button, you won't need to call
786 this; pressing the interrupt button transfers control to
787 `handle_exception'--in effect, to GDB. On some machines, simply
788 receiving characters on the serial port may also trigger a trap;
789 again, in that situation, you don't need to call `breakpoint' from
790 your own program--simply running `target remote' from the host GDB
791 session gets control.
793 Call `breakpoint' if none of these is true, or if you simply want
794 to make certain your program stops at a predetermined point for the
795 start of your debugging session.
798 File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Serial
800 What you must do for the stub
801 .............................
803 The debugging stubs that come with GDB are set up for a particular
804 chip architecture, but they have no information about the rest of your
805 debugging target machine.
807 First of all you need to tell the stub how to communicate with the
811 Write this subroutine to read a single character from the serial
812 port. It may be identical to `getchar' for your target system; a
813 different name is used to allow you to distinguish the two if you
816 `void putDebugChar(int)'
817 Write this subroutine to write a single character to the serial
818 port. It may be identical to `putchar' for your target system; a
819 different name is used to allow you to distinguish the two if you
822 If you want GDB to be able to stop your program while it is running,
823 you need to use an interrupt-driven serial driver, and arrange for it
824 to stop when it receives a `^C' (`\003', the control-C character).
825 That is the character which GDB uses to tell the remote system to stop.
827 Getting the debugging target to return the proper status to GDB
828 probably requires changes to the standard stub; one quick and dirty way
829 is to just execute a breakpoint instruction (the "dirty" part is that
830 GDB reports a `SIGTRAP' instead of a `SIGINT').
832 Other routines you need to supply are:
834 `void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
835 Write this function to install EXCEPTION_ADDRESS in the exception
836 handling tables. You need to do this because the stub does not
837 have any way of knowing what the exception handling tables on your
838 target system are like (for example, the processor's table might
839 be in ROM, containing entries which point to a table in RAM).
840 EXCEPTION_NUMBER is the exception number which should be changed;
841 its meaning is architecture-dependent (for example, different
842 numbers might represent divide by zero, misaligned access, etc).
843 When this exception occurs, control should be transferred directly
844 to EXCEPTION_ADDRESS, and the processor state (stack, registers,
845 and so on) should be just as it is when a processor exception
846 occurs. So if you want to use a jump instruction to reach
847 EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
850 For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
851 gate so that interrupts are masked while the handler runs. The
852 gate should be at privilege level 0 (the most privileged level).
853 The SPARC and 68k stubs are able to mask interrup themselves
854 without help from `exceptionHandler'.
856 `void flush_i_cache()'
857 (sparc and sparclite only) Write this subroutine to flush the
858 instruction cache, if any, on your target machine. If there is no
859 instruction cache, this subroutine may be a no-op.
861 On target machines that have instruction caches, GDB requires this
862 function to make certain that the state of your program is stable.
864 You must also make sure this library routine is available:
866 `void *memset(void *, int, int)'
867 This is the standard library function `memset' that sets an area of
868 memory to a known value. If you have one of the free versions of
869 `libc.a', `memset' can be found there; otherwise, you must either
870 obtain it from your hardware manufacturer, or write your own.
872 If you do not use the GNU C compiler, you may need other standard
873 library subroutines as well; this varies from one stub to another, but
874 in general the stubs are likely to use any of the common library
875 subroutines which `gcc' generates as inline code.
878 File: gdb.info, Node: Debug Session, Next: Protocol, Prev: Bootstrapping, Up: Remote Serial
880 Putting it all together
881 .......................
883 In summary, when your program is ready to debug, you must follow
886 1. Make sure you have the supporting low-level routines (*note What
887 you must do for the stub: Bootstrapping.):
888 `getDebugChar', `putDebugChar',
889 `flush_i_cache', `memset', `exceptionHandler'.
891 2. Insert these lines near the top of your program:
896 3. For the 680x0 stub only, you need to provide a variable called
897 `exceptionHook'. Normally you just use:
899 void (*exceptionHook)() = 0;
901 but if before calling `set_debug_traps', you set it to point to a
902 function in your program, that function is called when `GDB'
903 continues after stopping on a trap (for example, bus error). The
904 function indicated by `exceptionHook' is called with one
905 parameter: an `int' which is the exception number.
907 4. Compile and link together: your program, the GDB debugging stub for
908 your target architecture, and the supporting subroutines.
910 5. Make sure you have a serial connection between your target machine
911 and the GDB host, and identify the serial port on the host.
913 6. Download your program to your target machine (or get it there by
914 whatever means the manufacturer provides), and start it.
916 7. To start remote debugging, run GDB on the host machine, and specify
917 as an executable file the program that is running in the remote
918 machine. This tells GDB how to find your program's symbols and
919 the contents of its pure text.
921 Then establish communication using the `target remote' command.
922 Its argument specifies how to communicate with the target
923 machine--either via a devicename attached to a direct serial line,
924 or a TCP port (usually to a terminal server which in turn has a
925 serial line to the target). For example, to use a serial line
926 connected to the device named `/dev/ttyb':
928 target remote /dev/ttyb
930 To use a TCP connection, use an argument of the form `HOST:port'.
931 For example, to connect to port 2828 on a terminal server named
934 target remote manyfarms:2828
936 Now you can use all the usual commands to examine and change data
937 and to step and continue the remote program.
939 To resume the remote program and stop debugging it, use the `detach'
942 Whenever GDB is waiting for the remote program, if you type the
943 interrupt character (often <C-C>), GDB attempts to stop the program.
944 This may or may not succeed, depending in part on the hardware and the
945 serial drivers the remote system uses. If you type the interrupt
946 character once again, GDB displays this prompt:
948 Interrupted while waiting for the program.
949 Give up (and stop debugging it)? (y or n)
951 If you type `y', GDB abandons the remote debugging session. (If you
952 decide you want to try again later, you can use `target remote' again
953 to connect once more.) If you type `n', GDB goes back to waiting.
956 File: gdb.info, Node: Protocol, Next: Server, Prev: Debug Session, Up: Remote Serial
958 Communication protocol
959 ......................
961 The stub files provided with GDB implement the target side of the
962 communication protocol, and the GDB side is implemented in the GDB
963 source file `remote.c'. Normally, you can simply allow these
964 subroutines to communicate, and ignore the details. (If you're
965 implementing your own stub file, you can still ignore the details: start
966 with one of the existing stub files. `sparc-stub.c' is the best
967 organized, and therefore the easiest to read.)
969 However, there may be occasions when you need to know something about
970 the protocol--for example, if there is only one serial port to your
971 target machine, you might want your program to do something special if
972 it recognizes a packet meant for GDB.
974 All GDB commands and responses (other than acknowledgements, which
975 are single characters) are sent as a packet which includes a checksum.
976 A packet is introduced with the character `$', and ends with the
977 character `#' followed by a two-digit checksum:
979 $PACKET INFO#CHECKSUM
981 CHECKSUM is computed as the modulo 256 sum of the PACKET INFO
984 When either the host or the target machine receives a packet, the
985 first response expected is an acknowledgement: a single character,
986 either `+' (to indicate the package was received correctly) or `-' (to
987 request retransmission).
989 The host (GDB) sends commands, and the target (the debugging stub
990 incorporated in your program) sends data in response. The target also
991 sends data when your program stops.
993 Command packets are distinguished by their first character, which
994 identifies the kind of command.
996 These are some of the commands currently supported (for a complete
997 list of commands, look in `gdb/remote.c.'):
1000 Requests the values of CPU registers.
1003 Sets the values of CPU registers.
1006 Read COUNT bytes at location ADDR.
1009 Write COUNT bytes at location ADDR.
1013 Resume execution at the current address (or at ADDR if supplied).
1017 Step the target program for one instruction, from either the
1018 current program counter or from ADDR if supplied.
1021 Kill the target program.
1024 Report the most recent signal. To allow you to take advantage of
1025 the GDB signal handling commands, one of the functions of the
1026 debugging stub is to report CPU traps as the corresponding POSIX
1030 Allows the remote stub to send only the registers that GDB needs
1031 to make a quick decision about single-stepping or conditional
1032 breakpoints. This eliminates the need to fetch the entire
1033 register set for each instruction being stepped through.
1035 GDB now implements a write-through cache for registers and only
1036 re-reads the registers if the target has run.
1038 If you have trouble with the serial connection, you can use the
1039 command `set remotedebug'. This makes GDB report on all packets sent
1040 back and forth across the serial line to the remote machine. The
1041 packet-debugging information is printed on the GDB standard output
1042 stream. `set remotedebug off' turns it off, and `show remotedebug'
1043 shows you its current state.
1046 File: gdb.info, Node: Server, Next: NetWare, Prev: Protocol, Up: Remote Serial
1048 Using the `gdbserver' program
1049 .............................
1051 `gdbserver' is a control program for Unix-like systems, which allows
1052 you to connect your program with a remote GDB via `target remote'--but
1053 without linking in the usual debugging stub.
1055 `gdbserver' is not a complete replacement for the debugging stubs,
1056 because it requires essentially the same operating-system facilities
1057 that GDB itself does. In fact, a system that can run `gdbserver' to
1058 connect to a remote GDB could also run GDB locally! `gdbserver' is
1059 sometimes useful nevertheless, because it is a much smaller program
1060 than GDB itself. It is also easier to port than all of GDB, so you may
1061 be able to get started more quickly on a new system by using
1062 `gdbserver'. Finally, if you develop code for real-time systems, you
1063 may find that the tradeoffs involved in real-time operation make it
1064 more convenient to do as much development work as possible on another
1065 system, for example by cross-compiling. You can use `gdbserver' to
1066 make a similar choice for debugging.
1068 GDB and `gdbserver' communicate via either a serial line or a TCP
1069 connection, using the standard GDB remote serial protocol.
1071 *On the target machine,*
1072 you need to have a copy of the program you want to debug.
1073 `gdbserver' does not need your program's symbol table, so you can
1074 strip the program if necessary to save space. GDB on the host
1075 system does all the symbol handling.
1077 To use the server, you must tell it how to communicate with GDB;
1078 the name of your program; and the arguments for your program. The
1081 target> gdbserver COMM PROGRAM [ ARGS ... ]
1083 COMM is either a device name (to use a serial line) or a TCP
1084 hostname and portnumber. For example, to debug Emacs with the
1085 argument `foo.txt' and communicate with GDB over the serial port
1088 target> gdbserver /dev/com1 emacs foo.txt
1090 `gdbserver' waits passively for the host GDB to communicate with
1093 To use a TCP connection instead of a serial line:
1095 target> gdbserver host:2345 emacs foo.txt
1097 The only difference from the previous example is the first
1098 argument, specifying that you are communicating with the host GDB
1099 via TCP. The `host:2345' argument means that `gdbserver' is to
1100 expect a TCP connection from machine `host' to local TCP port 2345.
1101 (Currently, the `host' part is ignored.) You can choose any number
1102 you want for the port number as long as it does not conflict with
1103 any TCP ports already in use on the target system (for example,
1104 `23' is reserved for `telnet').(1) You must use the same port
1105 number with the host GDB `target remote' command.
1107 *On the GDB host machine,*
1108 you need an unstripped copy of your program, since GDB needs
1109 symbols and debugging information. Start up GDB as usual, using
1110 the name of the local copy of your program as the first argument.
1111 (You may also need the `--baud' option if the serial line is
1112 running at anything other than 9600 bps.) After that, use `target
1113 remote' to establish communications with `gdbserver'. Its argument
1114 is either a device name (usually a serial device, like
1115 `/dev/ttyb'), or a TCP port descriptor in the form `HOST:PORT'.
1118 (gdb) target remote /dev/ttyb
1120 communicates with the server via serial line `/dev/ttyb', and
1122 (gdb) target remote the-target:2345
1124 communicates via a TCP connection to port 2345 on host
1125 `the-target'. For TCP connections, you must start up `gdbserver'
1126 prior to using the `target remote' command. Otherwise you may get
1127 an error whose text depends on the host system, but which usually
1128 looks something like `Connection refused'.
1130 ---------- Footnotes ----------
1132 (1) If you choose a port number that conflicts with another service,
1133 `gdbserver' prints an error message and exits.
1136 File: gdb.info, Node: NetWare, Prev: Server, Up: Remote Serial
1138 Using the `gdbserve.nlm' program
1139 ................................
1141 `gdbserve.nlm' is a control program for NetWare systems, which
1142 allows you to connect your program with a remote GDB via `target
1145 GDB and `gdbserve.nlm' communicate via a serial line, using the
1146 standard GDB remote serial protocol.
1148 *On the target machine,*
1149 you need to have a copy of the program you want to debug.
1150 `gdbserve.nlm' does not need your program's symbol table, so you
1151 can strip the program if necessary to save space. GDB on the host
1152 system does all the symbol handling.
1154 To use the server, you must tell it how to communicate with GDB;
1155 the name of your program; and the arguments for your program. The
1158 load gdbserve [ BOARD=BOARD ] [ PORT=PORT ]
1159 [ BAUD=BAUD ] PROGRAM [ ARGS ... ]
1161 BOARD and PORT specify the serial line; BAUD specifies the baud
1162 rate used by the connection. PORT and NODE default to 0, BAUD
1163 defaults to 9600 bps.
1165 For example, to debug Emacs with the argument `foo.txt'and
1166 communicate with GDB over serial port number 2 or board 1 using a
1167 19200 bps connection:
1169 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
1171 *On the GDB host machine,*
1172 you need an unstripped copy of your program, since GDB needs
1173 symbols and debugging information. Start up GDB as usual, using
1174 the name of the local copy of your program as the first argument.
1175 (You may also need the `--baud' option if the serial line is
1176 running at anything other than 9600 bps. After that, use `target
1177 remote' to establish communications with `gdbserve.nlm'. Its
1178 argument is a device name (usually a serial device, like
1179 `/dev/ttyb'). For example:
1181 (gdb) target remote /dev/ttyb
1183 communications with the server via serial line `/dev/ttyb'.
1186 File: gdb.info, Node: i960-Nindy Remote, Next: UDI29K Remote, Prev: Remote Serial, Up: Remote
1188 GDB with a remote i960 (Nindy)
1189 ------------------------------
1191 "Nindy" is a ROM Monitor program for Intel 960 target systems. When
1192 GDB is configured to control a remote Intel 960 using Nindy, you can
1193 tell GDB how to connect to the 960 in several ways:
1195 * Through command line options specifying serial port, version of the
1196 Nindy protocol, and communications speed;
1198 * By responding to a prompt on startup;
1200 * By using the `target' command at any point during your GDB
1201 session. *Note Commands for managing targets: Target Commands.
1205 * Nindy Startup:: Startup with Nindy
1206 * Nindy Options:: Options for Nindy
1207 * Nindy Reset:: Nindy reset command
1210 File: gdb.info, Node: Nindy Startup, Next: Nindy Options, Up: i960-Nindy Remote
1215 If you simply start `gdb' without using any command-line options,
1216 you are prompted for what serial port to use, *before* you reach the
1217 ordinary GDB prompt:
1219 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
1221 Respond to the prompt with whatever suffix (after `/dev/tty')
1222 identifies the serial port you want to use. You can, if you choose,
1223 simply start up with no Nindy connection by responding to the prompt
1224 with an empty line. If you do this and later wish to attach to Nindy,
1225 use `target' (*note Commands for managing targets: Target Commands.).