diff options
Diffstat (limited to 'gdb/doc/gdb.info-6')
| -rw-r--r-- | gdb/doc/gdb.info-6 | 1226 |
1 files changed, 0 insertions, 1226 deletions
diff --git a/gdb/doc/gdb.info-6 b/gdb/doc/gdb.info-6 deleted file mode 100644 index 77a351e..0000000 --- a/gdb/doc/gdb.info-6 +++ /dev/null @@ -1,1226 +0,0 @@ -This is Info file ./gdb.info, produced by Makeinfo version 1.68 from -the input file gdb.texinfo. - -START-INFO-DIR-ENTRY -* Gdb: (gdb). The GNU debugger. -END-INFO-DIR-ENTRY - This file documents the GNU debugger GDB. - - This is the Seventh Edition, February 1999, of `Debugging with GDB: -the GNU Source-Level Debugger' for GDB Version 4.18. - - Copyright (C) 1988-1999 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -File: gdb.info, Node: Files, Next: Symbol Errors, Prev: GDB Files, Up: GDB Files - -Commands to specify files -========================= - - You may want to specify executable and core dump file names. The -usual way to do this is at start-up time, using the arguments to GDB's -start-up commands (*note Getting In and Out of GDB: Invocation.). - - Occasionally it is necessary to change to a different file during a -GDB session. Or you may run GDB and forget to specify a file you want -to use. In these situations the GDB commands to specify new files are -useful. - -`file FILENAME' - Use FILENAME as the program to be debugged. It is read for its - symbols and for the contents of pure memory. It is also the - program executed when you use the `run' command. If you do not - specify a directory and the file is not found in the GDB working - directory, GDB uses the environment variable `PATH' as a list of - directories to search, just as the shell does when looking for a - program to run. You can change the value of this variable, for - both GDB and your program, using the `path' command. - - On systems with memory-mapped files, an auxiliary file - `FILENAME.syms' may hold symbol table information for FILENAME. - If so, GDB maps in the symbol table from `FILENAME.syms', starting - up more quickly. See the descriptions of the file options - `-mapped' and `-readnow' (available on the command line, and with - the commands `file', `symbol-file', or `add-symbol-file', - described below), for more information. - -`file' - `file' with no argument makes GDB discard any information it has - on both executable file and the symbol table. - -`exec-file [ FILENAME ]' - Specify that the program to be run (but not the symbol table) is - found in FILENAME. GDB searches the environment variable `PATH' - if necessary to locate your program. Omitting FILENAME means to - discard information on the executable file. - -`symbol-file [ FILENAME ]' - Read symbol table information from file FILENAME. `PATH' is - searched when necessary. Use the `file' command to get both symbol - table and program to run from the same file. - - `symbol-file' with no argument clears out GDB information on your - program's symbol table. - - The `symbol-file' command causes GDB to forget the contents of its - convenience variables, the value history, and all breakpoints and - auto-display expressions. This is because they may contain - pointers to the internal data recording symbols and data types, - which are part of the old symbol table data being discarded inside - GDB. - - `symbol-file' does not repeat if you press <RET> again after - executing it once. - - When GDB is configured for a particular environment, it - understands debugging information in whatever format is the - standard generated for that environment; you may use either a GNU - compiler, or other compilers that adhere to the local conventions. - Best results are usually obtained from GNU compilers; for example, - using `gcc' you can generate debugging information for optimized - code. - - For most kinds of object files, with the exception of old SVR3 - systems using COFF, the `symbol-file' command does not normally - read the symbol table in full right away. Instead, it scans the - symbol table quickly to find which source files and which symbols - are present. The details are read later, one source file at a - time, as they are needed. - - The purpose of this two-stage reading strategy is to make GDB - start up faster. For the most part, it is invisible except for - occasional pauses while the symbol table details for a particular - source file are being read. (The `set verbose' command can turn - these pauses into messages if desired. *Note Optional warnings - and messages: Messages/Warnings.) - - We have not implemented the two-stage strategy for COFF yet. When - the symbol table is stored in COFF format, `symbol-file' reads the - symbol table data in full right away. Note that "stabs-in-COFF" - still does the two-stage strategy, since the debug info is actually - in stabs format. - -`symbol-file FILENAME [ -readnow ] [ -mapped ]' -`file FILENAME [ -readnow ] [ -mapped ]' - You can override the GDB two-stage strategy for reading symbol - tables by using the `-readnow' option with any of the commands that - load symbol table information, if you want to be sure GDB has the - entire symbol table available. - - If memory-mapped files are available on your system through the - `mmap' system call, you can use another option, `-mapped', to - cause GDB to write the symbols for your program into a reusable - file. Future GDB debugging sessions map in symbol information - from this auxiliary symbol file (if the program has not changed), - rather than spending time reading the symbol table from the - executable program. Using the `-mapped' option has the same - effect as starting GDB with the `-mapped' command-line option. - - You can use both options together, to make sure the auxiliary - symbol file has all the symbol information for your program. - - The auxiliary symbol file for a program called MYPROG is called - `MYPROG.syms'. Once this file exists (so long as it is newer than - the corresponding executable), GDB always attempts to use it when - you debug MYPROG; no special options or commands are needed. - - The `.syms' file is specific to the host machine where you run - GDB. It holds an exact image of the internal GDB symbol table. - It cannot be shared across multiple host platforms. - -`core-file [ FILENAME ]' - Specify the whereabouts of a core dump file to be used as the - "contents of memory". Traditionally, core files contain only some - parts of the address space of the process that generated them; GDB - can access the executable file itself for other parts. - - `core-file' with no argument specifies that no core file is to be - used. - - Note that the core file is ignored when your program is actually - running under GDB. So, if you have been running your program and - you wish to debug a core file instead, you must kill the - subprocess in which the program is running. To do this, use the - `kill' command (*note Killing the child process: Kill Process.). - -`add-symbol-file FILENAME ADDRESS' -`add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]' - The `add-symbol-file' command reads additional symbol table - information from the file FILENAME. You would use this command - when FILENAME has been dynamically loaded (by some other means) - into the program that is running. ADDRESS should be the memory - address at which the file has been loaded; GDB cannot figure this - out for itself. You can specify ADDRESS as an expression. - - The symbol table of the file FILENAME is added to the symbol table - originally read with the `symbol-file' command. You can use the - `add-symbol-file' command any number of times; the new symbol data - thus read keeps adding to the old. To discard all old symbol data - instead, use the `symbol-file' command. - - `add-symbol-file' does not repeat if you press <RET> after using - it. - - You can use the `-mapped' and `-readnow' options just as with the - `symbol-file' command, to change how GDB manages the symbol table - information for FILENAME. - -`add-shared-symbol-file' - The `add-shared-symbol-file' command can be used only under - Harris' CXUX operating system for the Motorola 88k. GDB - automatically looks for shared libraries, however if GDB does not - find yours, you can run `add-shared-symbol-file'. It takes no - arguments. - -`section' - The `section' command changes the base address of section SECTION - of the exec file to ADDR. This can be used if the exec file does - not contain section addresses, (such as in the a.out format), or - when the addresses specified in the file itself are wrong. Each - section must be changed separately. The "info files" command - lists all the sections and their addresses. - -`info files' -`info target' - `info files' and `info target' are synonymous; both print the - current target (*note Specifying a Debugging Target: Targets.), - including the names of the executable and core dump files - currently in use by GDB, and the files from which symbols were - loaded. The command `help target' lists all possible targets - rather than current ones. - - All file-specifying commands allow both absolute and relative file -names as arguments. GDB always converts the file name to an absolute -file name and remembers it that way. - - GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared -libraries. GDB automatically loads symbol definitions from shared -libraries when you use the `run' command, or when you examine a core -file. (Before you issue the `run' command, GDB does not understand -references to a function in a shared library, however--unless you are -debugging a core file). - -`info share' -`info sharedlibrary' - Print the names of the shared libraries which are currently loaded. - -`sharedlibrary REGEX' -`share REGEX' - Load shared object library symbols for files matching a Unix - regular expression. As with files loaded automatically, it only - loads shared libraries required by your program for a core file or - after typing `run'. If REGEX is omitted all shared libraries - required by your program are loaded. - - -File: gdb.info, Node: Symbol Errors, Prev: Files, Up: GDB Files - -Errors reading symbol files -=========================== - - While reading a symbol file, GDB occasionally encounters problems, -such as symbol types it does not recognize, or known bugs in compiler -output. By default, GDB does not notify you of such problems, since -they are relatively common and primarily of interest to people -debugging compilers. If you are interested in seeing information about -ill-constructed symbol tables, you can either ask GDB to print only one -message about each such type of problem, no matter how many times the -problem occurs; or you can ask GDB to print more messages, to see how -many times the problems occur, with the `set complaints' command (*note -Optional warnings and messages: Messages/Warnings.). - - The messages currently printed, and their meanings, include: - -`inner block not inside outer block in SYMBOL' - The symbol information shows where symbol scopes begin and end - (such as at the start of a function or a block of statements). - This error indicates that an inner scope block is not fully - contained in its outer scope blocks. - - GDB circumvents the problem by treating the inner block as if it - had the same scope as the outer block. In the error message, - SYMBOL may be shown as "`(don't know)'" if the outer block is not a - function. - -`block at ADDRESS out of order' - The symbol information for symbol scope blocks should occur in - order of increasing addresses. This error indicates that it does - not do so. - - GDB does not circumvent this problem, and has trouble locating - symbols in the source file whose symbols it is reading. (You can - often determine what source file is affected by specifying `set - verbose on'. *Note Optional warnings and messages: - Messages/Warnings.) - -`bad block start address patched' - The symbol information for a symbol scope block has a start address - smaller than the address of the preceding source line. This is - known to occur in the SunOS 4.1.1 (and earlier) C compiler. - - GDB circumvents the problem by treating the symbol scope block as - starting on the previous source line. - -`bad string table offset in symbol N' - Symbol number N contains a pointer into the string table which is - larger than the size of the string table. - - GDB circumvents the problem by considering the symbol to have the - name `foo', which may cause other problems if many symbols end up - with this name. - -`unknown symbol type `0xNN'' - The symbol information contains new data types that GDB does not - yet know how to read. `0xNN' is the symbol type of the - misunderstood information, in hexadecimal. - - GDB circumvents the error by ignoring this symbol information. - This usually allows you to debug your program, though certain - symbols are not accessible. If you encounter such a problem and - feel like debugging it, you can debug `gdb' with itself, - breakpoint on `complain', then go up to the function - `read_dbx_symtab' and examine `*bufp' to see the symbol. - -`stub type has NULL name' - GDB could not find the full definition for a struct or class. - -`const/volatile indicator missing (ok if using g++ v1.x), got...' - The symbol information for a C++ member function is missing some - information that recent versions of the compiler should have output - for it. - -`info mismatch between compiler and debugger' - GDB could not parse a type specification output by the compiler. - - -File: gdb.info, Node: Targets, Next: Controlling GDB, Prev: GDB Files, Up: Top - -Specifying a Debugging Target -***************************** - - A "target" is the execution environment occupied by your program. -Often, GDB runs in the same host environment as your program; in that -case, the debugging target is specified as a side effect when you use -the `file' or `core' commands. When you need more flexibility--for -example, running GDB on a physically separate host, or controlling a -standalone system over a serial port or a realtime system over a TCP/IP -connection--you can use the `target' command to specify one of the -target types configured for GDB (*note Commands for managing targets: -Target Commands.). - -* Menu: - -* Active Targets:: Active targets -* Target Commands:: Commands for managing targets - -* Byte Order:: Choosing target byte order -* Remote:: Remote debugging - - -File: gdb.info, Node: Active Targets, Next: Target Commands, Prev: Targets, Up: Targets - -Active targets -============== - - There are three classes of targets: processes, core files, and -executable files. GDB can work concurrently on up to three active -targets, one in each class. This allows you to (for example) start a -process and inspect its activity without abandoning your work on a core -file. - - For example, if you execute `gdb a.out', then the executable file -`a.out' is the only active target. If you designate a core file as -well--presumably from a prior run that crashed and coredumped--then GDB -has two active targets and uses them in tandem, looking first in the -corefile target, then in the executable file, to satisfy requests for -memory addresses. (Typically, these two classes of target are -complementary, since core files contain only a program's read-write -memory--variables and so on--plus machine status, while executable -files contain only the program text and initialized data.) - - When you type `run', your executable file becomes an active process -target as well. When a process target is active, all GDB commands -requesting memory addresses refer to that target; addresses in an -active core file or executable file target are obscured while the -process target is active. - - Use the `core-file' and `exec-file' commands to select a new core -file or executable target (*note Commands to specify files: Files.). -To specify as a target a process that is already running, use the -`attach' command (*note Debugging an already-running process: Attach.). - - -File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets - -Commands for managing targets -============================= - -`target TYPE PARAMETERS' - Connects the GDB host environment to a target machine or process. - A target is typically a protocol for talking to debugging - facilities. You use the argument TYPE to specify the type or - protocol of the target machine. - - Further PARAMETERS are interpreted by the target protocol, but - typically include things like device names or host names to connect - with, process numbers, and baud rates. - - The `target' command does not repeat if you press <RET> again - after executing the command. - -`help target' - Displays the names of all targets available. To display targets - currently selected, use either `info target' or `info files' - (*note Commands to specify files: Files.). - -`help target NAME' - Describe a particular target, including any parameters necessary to - select it. - -`set gnutarget ARGS' - GDB uses its own library BFD to read your files. GDB knows - whether it is reading an "executable", a "core", or a ".o" file; - however, you can specify the file format with the `set gnutarget' - command. Unlike most `target' commands, with `gnutarget' the - `target' refers to a program, not a machine. - - *Warning:* To specify a file format with `set gnutarget', you must - know the actual BFD name. - - *Note Commands to specify files: Files. - -`show gnutarget' - Use the `show gnutarget' command to display what file format - `gnutarget' is set to read. If you have not set `gnutarget', GDB - will determine the file format for each file automatically, and - `show gnutarget' displays `The current BDF target is "auto"'. - - Here are some common targets (available, or not, depending on the GDB -configuration): - -`target exec PROGRAM' - An executable file. `target exec PROGRAM' is the same as - `exec-file PROGRAM'. - -`target core FILENAME' - A core dump file. `target core FILENAME' is the same as - `core-file FILENAME'. - -`target remote DEV' - Remote serial target in GDB-specific protocol. The argument DEV - specifies what serial device to use for the connection (e.g. - `/dev/ttya'). *Note Remote debugging: Remote. `target remote' now - supports the `load' command. This is only useful if you have some - other way of getting the stub to the target system, and you can put - it somewhere in memory where it won't get clobbered by the - download. - -`target sim' - CPU simulator. *Note Simulated CPU Target: Simulator. - - The following targets are all CPU-specific, and only available for -specific configurations. - -`target abug DEV' - ABug ROM monitor for M68K. - -`target adapt DEV' - Adapt monitor for A29K. - -`target amd-eb DEV SPEED PROG' - Remote PC-resident AMD EB29K board, attached over serial lines. - DEV is the serial device, as for `target remote'; SPEED allows you - to specify the linespeed; and PROG is the name of the program to - be debugged, as it appears to DOS on the PC. *Note The EBMON - protocol for AMD29K: EB29K Remote. - -`target array DEV' - Array Tech LSI33K RAID controller board. - -`target bug DEV' - BUG monitor, running on a MVME187 (m88k) board. - -`target cpu32bug DEV' - CPU32BUG monitor, running on a CPU32 (M68K) board. - -`target dbug DEV' - dBUG ROM monitor for Motorola ColdFire. - -`target ddb DEV' - NEC's DDB monitor for Mips Vr4300. - -`target dink32 DEV' - DINK32 ROM monitor for PowerPC. - -`target e7000 DEV' - E7000 emulator for Hitachi H8 and SH. - -`target es1800 DEV' - ES-1800 emulator for M68K. - -`target est DEV' - EST-300 ICE monitor, running on a CPU32 (M68K) board. - -`target hms DEV' - A Hitachi SH, H8/300, or H8/500 board, attached via serial line to - your host. Use special commands `device' and `speed' to control - the serial line and the communications speed used. *Note GDB and - Hitachi Microprocessors: Hitachi Remote. - -`target lsi DEV' - LSI ROM monitor for Mips. - -`target m32r DEV' - Mitsubishi M32R/D ROM monitor. - -`target mips DEV' - IDT/SIM ROM monitor for Mips. - -`target mon960 DEV' - MON960 monitor for Intel i960. - -`target nindy DEVICENAME' - An Intel 960 board controlled by a Nindy Monitor. DEVICENAME is - the name of the serial device to use for the connection, e.g. - `/dev/ttya'. *Note GDB with a remote i960 (Nindy): i960-Nindy - Remote. - -`target nrom DEV' - NetROM ROM emulator. This target only supports downloading. - -`target op50n DEV' - OP50N monitor, running on an OKI HPPA board. - -`target pmon DEV' - PMON ROM monitor for Mips. - -`target ppcbug DEV' - -`target ppcbug1 DEV' - PPCBUG ROM monitor for PowerPC. - -`target r3900 DEV' - Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. - -`target rdi DEV' - ARM Angel monitor, via RDI library interface. - -`target rdp DEV' - ARM Demon monitor. - -`target rom68k DEV' - ROM 68K monitor, running on an M68K IDP board. - -`target rombug DEV' - ROMBUG ROM monitor for OS/9000. - -`target sds DEV' - SDS monitor, running on a PowerPC board (such as Motorola's ADS). - -`target sparclite 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 DEV using GDB standard remote protocol. - -`target sh3 DEV' - -`target sh3e DEV' - Hitachi SH-3 and SH-3E target systems. - -`target st2000 DEV SPEED' - A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. - DEV is the name of the device attached to the ST2000 serial line; - SPEED is the communication line speed. The arguments are not used - if GDB is configured to connect to the ST2000 using TCP or Telnet. - *Note GDB with a Tandem ST2000: ST2000 Remote. - -`target udi KEYWORD' - Remote AMD29K target, using the AMD UDI protocol. The KEYWORD - argument specifies which 29K board or simulator to use. *Note The - UDI protocol for AMD29K: UDI29K Remote. - -`target vxworks MACHINENAME' - A VxWorks system, attached via TCP/IP. The argument MACHINENAME - is the target system's machine name or IP address. *Note GDB and - VxWorks: VxWorks Remote. - -`target w89k DEV' - W89K monitor, running on a Winbond HPPA board. - - Different targets are available on different configurations of GDB; -your configuration may have more or fewer targets. - - Many remote targets require you to download the executable's code -once you've successfully established a connection. - -`load FILENAME' - Depending on what remote debugging facilities are configured into - GDB, the `load' command may be available. Where it exists, it is - meant to make FILENAME (an executable) available for debugging on - the remote system--by downloading, or dynamic linking, for example. - `load' also records the FILENAME symbol table in GDB, like the - `add-symbol-file' command. - - If your GDB does not have a `load' command, attempting to execute - it gets the error message "`You can't do that when your target is - ...'" - - The file is loaded at whatever address is specified in the - executable. For some object file formats, you can specify the - load address when you link the program; for other formats, like - a.out, the object file format specifies a fixed address. - - On VxWorks, `load' links FILENAME dynamically on the current - target system as well as adding its symbols in GDB. - - With the Nindy interface to an Intel 960 board, `load' downloads - FILENAME to the 960 as well as adding its symbols in GDB. - - When you select remote debugging to a Hitachi SH, H8/300, or - H8/500 board (*note GDB and Hitachi Microprocessors: Hitachi - Remote.), the `load' command downloads your program to the Hitachi - board and also opens it as the current executable target for GDB - on your host (like the `file' command). - - `load' does not repeat if you press <RET> again after using it. - - -File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets - -Choosing target byte order -========================== - - Some types of processors, such as the MIPS, PowerPC, and Hitachi SH, -offer the ability to run either big-endian or little-endian byte -orders. Usually the executable or symbol will include a bit to -designate the endian-ness, and you will not need to worry about which -to use. However, you may still find it useful to adjust GDB's idea of -processor endian-ness manually. - -`set endian big' - Instruct GDB to assume the target is big-endian. - -`set endian little' - Instruct GDB to assume the target is little-endian. - -`set endian auto' - Instruct GDB to use the byte order associated with the executable. - -`show endian' - Display GDB's current idea of the target byte order. - - Note that these commands merely adjust interpretation of symbolic -data on the host, and that they have absolutely no effect on the target -system. - - -File: gdb.info, Node: Remote, Prev: Byte Order, Up: Targets - -Remote debugging -================ - - If you are trying to debug a program running on a machine that -cannot run GDB in the usual way, it is often useful to use remote -debugging. For example, you might use remote debugging on an operating -system kernel, or on a small system which does not have a general -purpose operating system powerful enough to run a full-featured -debugger. - - Some configurations of GDB have special serial or TCP/IP interfaces -to make this work with particular debugging targets. In addition, GDB -comes with a generic serial protocol (specific to GDB, but not specific -to any particular target system) which you can use if you write the -remote stubs--the code that runs on the remote system to communicate -with GDB. - - Other remote targets may be available in your configuration of GDB; -use `help target' to list them. - -* Menu: - - -* Remote Serial:: GDB remote serial protocol - -* i960-Nindy Remote:: GDB with a remote i960 (Nindy) - -* UDI29K Remote:: The UDI protocol for AMD29K -* EB29K Remote:: The EBMON protocol for AMD29K - -* VxWorks Remote:: GDB and VxWorks - -* ST2000 Remote:: GDB with a Tandem ST2000 - -* Hitachi Remote:: GDB and Hitachi Microprocessors - -* MIPS Remote:: GDB and MIPS boards - -* Sparclet Remote:: GDB and Sparclet boards - -* Simulator:: Simulated CPU target - - -File: gdb.info, Node: Remote Serial, Next: i960-Nindy Remote, Up: Remote - -The GDB remote serial protocol ------------------------------- - - To debug a program running on another machine (the debugging -"target" machine), you must first arrange for all the usual -prerequisites for the program to run by itself. For example, for a C -program, you need: - - 1. A startup routine to set up the C runtime environment; these - usually have a name like `crt0'. The startup routine may be - supplied by your hardware supplier, or you may have to write your - own. - - 2. You probably need a C subroutine library to support your program's - subroutine calls, notably managing input and output. - - 3. A way of getting your program to the other machine--for example, a - download program. These are often supplied by the hardware - manufacturer, but you may have to write your own from hardware - documentation. - - The next step is to arrange for your program to use a serial port to -communicate with the machine where GDB is running (the "host" machine). -In general terms, the scheme looks like this: - -*On the host,* - GDB already understands how to use this protocol; when everything - else is set up, you can simply use the `target remote' command - (*note Specifying a Debugging Target: Targets.). - -*On the target,* - you must link with your program a few special-purpose subroutines - that implement the GDB remote serial protocol. The file - containing these subroutines is called a "debugging stub". - - On certain remote targets, you can use an auxiliary program - `gdbserver' instead of linking a stub into your program. *Note - Using the `gdbserver' program: Server, for details. - - The debugging stub is specific to the architecture of the remote -machine; for example, use `sparc-stub.c' to debug programs on SPARC -boards. - - These working remote stubs are distributed with GDB: - -`i386-stub.c' - For Intel 386 and compatible architectures. - -`m68k-stub.c' - For Motorola 680x0 architectures. - -`sh-stub.c' - For Hitachi SH architectures. - -`sparc-stub.c' - For SPARC architectures. - -`sparcl-stub.c' - For Fujitsu SPARCLITE architectures. - - The `README' file in the GDB distribution may list other recently -added stubs. - -* Menu: - -* Stub Contents:: What the stub can do for you -* Bootstrapping:: What you must do for the stub -* Debug Session:: Putting it all together -* Protocol:: Outline of the communication protocol - -* Server:: Using the `gdbserver' program - -* NetWare:: Using the `gdbserve.nlm' program - - -File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Serial - -What the stub can do for you -............................ - - The debugging stub for your architecture supplies these three -subroutines: - -`set_debug_traps' - This routine arranges for `handle_exception' to run when your - program stops. You must call this subroutine explicitly near the - beginning of your program. - -`handle_exception' - This is the central workhorse, but your program never calls it - explicitly--the setup code arranges for `handle_exception' to run - when a trap is triggered. - - `handle_exception' takes control when your program stops during - execution (for example, on a breakpoint), and mediates - communications with GDB on the host machine. This is where the - communications protocol is implemented; `handle_exception' acts as - the GDB representative on the target machine; it begins by sending - summary information on the state of your program, then continues - to execute, retrieving and transmitting any information GDB needs, - until you execute a GDB command that makes your program resume; at - that point, `handle_exception' returns control to your own code on - the target machine. - -`breakpoint' - Use this auxiliary subroutine to make your program contain a - breakpoint. Depending on the particular situation, this may be - the only way for GDB to get control. For instance, if your target - machine has some sort of interrupt button, you won't need to call - this; pressing the interrupt button transfers control to - `handle_exception'--in effect, to GDB. On some machines, simply - receiving characters on the serial port may also trigger a trap; - again, in that situation, you don't need to call `breakpoint' from - your own program--simply running `target remote' from the host GDB - session gets control. - - Call `breakpoint' if none of these is true, or if you simply want - to make certain your program stops at a predetermined point for the - start of your debugging session. - - -File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Serial - -What you must do for the stub -............................. - - The debugging stubs that come with GDB are set up for a particular -chip architecture, but they have no information about the rest of your -debugging target machine. - - First of all you need to tell the stub how to communicate with the -serial port. - -`int getDebugChar()' - Write this subroutine to read a single character from the serial - port. It may be identical to `getchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - -`void putDebugChar(int)' - Write this subroutine to write a single character to the serial - port. It may be identical to `putchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - - If you want GDB to be able to stop your program while it is running, -you need to use an interrupt-driven serial driver, and arrange for it -to stop when it receives a `^C' (`\003', the control-C character). -That is the character which GDB uses to tell the remote system to stop. - - Getting the debugging target to return the proper status to GDB -probably requires changes to the standard stub; one quick and dirty way -is to just execute a breakpoint instruction (the "dirty" part is that -GDB reports a `SIGTRAP' instead of a `SIGINT'). - - Other routines you need to supply are: - -`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' - Write this function to install EXCEPTION_ADDRESS in the exception - handling tables. You need to do this because the stub does not - have any way of knowing what the exception handling tables on your - target system are like (for example, the processor's table might - be in ROM, containing entries which point to a table in RAM). - EXCEPTION_NUMBER is the exception number which should be changed; - its meaning is architecture-dependent (for example, different - numbers might represent divide by zero, misaligned access, etc). - When this exception occurs, control should be transferred directly - to EXCEPTION_ADDRESS, and the processor state (stack, registers, - and so on) should be just as it is when a processor exception - occurs. So if you want to use a jump instruction to reach - EXCEPTION_ADDRESS, it should be a simple jump, not a jump to - subroutine. - - For the 386, EXCEPTION_ADDRESS should be installed as an interrupt - gate so that interrupts are masked while the handler runs. The - gate should be at privilege level 0 (the most privileged level). - The SPARC and 68k stubs are able to mask interrup themselves - without help from `exceptionHandler'. - -`void flush_i_cache()' - (sparc and sparclite only) Write this subroutine to flush the - instruction cache, if any, on your target machine. If there is no - instruction cache, this subroutine may be a no-op. - - On target machines that have instruction caches, GDB requires this - function to make certain that the state of your program is stable. - -You must also make sure this library routine is available: - -`void *memset(void *, int, int)' - This is the standard library function `memset' that sets an area of - memory to a known value. If you have one of the free versions of - `libc.a', `memset' can be found there; otherwise, you must either - obtain it from your hardware manufacturer, or write your own. - - If you do not use the GNU C compiler, you may need other standard -library subroutines as well; this varies from one stub to another, but -in general the stubs are likely to use any of the common library -subroutines which `gcc' generates as inline code. - - -File: gdb.info, Node: Debug Session, Next: Protocol, Prev: Bootstrapping, Up: Remote Serial - -Putting it all together -....................... - - In summary, when your program is ready to debug, you must follow -these steps. - - 1. Make sure you have the supporting low-level routines (*note What - you must do for the stub: Bootstrapping.): - `getDebugChar', `putDebugChar', - `flush_i_cache', `memset', `exceptionHandler'. - - 2. Insert these lines near the top of your program: - - set_debug_traps(); - breakpoint(); - - 3. For the 680x0 stub only, you need to provide a variable called - `exceptionHook'. Normally you just use: - - void (*exceptionHook)() = 0; - - but if before calling `set_debug_traps', you set it to point to a - function in your program, that function is called when `GDB' - continues after stopping on a trap (for example, bus error). The - function indicated by `exceptionHook' is called with one - parameter: an `int' which is the exception number. - - 4. Compile and link together: your program, the GDB debugging stub for - your target architecture, and the supporting subroutines. - - 5. Make sure you have a serial connection between your target machine - and the GDB host, and identify the serial port on the host. - - 6. Download your program to your target machine (or get it there by - whatever means the manufacturer provides), and start it. - - 7. To start remote debugging, run GDB on the host machine, and specify - as an executable file the program that is running in the remote - machine. This tells GDB how to find your program's symbols and - the contents of its pure text. - - Then establish communication using the `target remote' command. - Its argument specifies how to communicate with the target - machine--either via a devicename attached to a direct serial line, - or a TCP port (usually to a terminal server which in turn has a - serial line to the target). For example, to use a serial line - connected to the device named `/dev/ttyb': - - target remote /dev/ttyb - - To use a TCP connection, use an argument of the form `HOST:port'. - For example, to connect to port 2828 on a terminal server named - `manyfarms': - - target remote manyfarms:2828 - - Now you can use all the usual commands to examine and change data -and to step and continue the remote program. - - To resume the remote program and stop debugging it, use the `detach' -command. - - Whenever GDB is waiting for the remote program, if you type the -interrupt character (often <C-C>), GDB attempts to stop the program. -This may or may not succeed, depending in part on the hardware and the -serial drivers the remote system uses. If you type the interrupt -character once again, GDB displays this prompt: - - Interrupted while waiting for the program. - Give up (and stop debugging it)? (y or n) - - If you type `y', GDB abandons the remote debugging session. (If you -decide you want to try again later, you can use `target remote' again -to connect once more.) If you type `n', GDB goes back to waiting. - - -File: gdb.info, Node: Protocol, Next: Server, Prev: Debug Session, Up: Remote Serial - -Communication protocol -...................... - - The stub files provided with GDB implement the target side of the -communication protocol, and the GDB side is implemented in the GDB -source 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. `sparc-stub.c' is the best -organized, and therefore the easiest to read.) - - However, there may be occasions when you need to know something about -the protocol--for example, if there is only one serial port to your -target machine, you might want your program to do something special if -it recognizes a packet meant for GDB. - - All GDB commands and responses (other than acknowledgements, which -are single characters) are sent as a packet which includes a checksum. -A packet is introduced with the character `$', and ends with the -character `#' followed by a two-digit checksum: - - $PACKET INFO#CHECKSUM - -CHECKSUM is computed as the modulo 256 sum of the PACKET INFO -characters. - - When either the host or the target machine receives a packet, the -first response expected is an acknowledgement: a single character, -either `+' (to indicate the package was received correctly) or `-' (to -request retransmission). - - The host (GDB) sends commands, and the target (the debugging stub -incorporated in your program) sends data in response. The target also -sends data when your program stops. - - Command packets are distinguished by their first character, which -identifies the kind of command. - - These are some of the commands currently supported (for a complete -list of commands, look in `gdb/remote.c.'): - -`g' - Requests the values of CPU registers. - -`G' - Sets the values of CPU registers. - -`mADDR,COUNT' - Read COUNT bytes at location ADDR. - -`MADDR,COUNT:...' - Write COUNT bytes at location ADDR. - -`c' -`cADDR' - Resume execution at the current address (or at ADDR if supplied). - -`s' -`sADDR' - Step the target program for one instruction, from either the - current program counter or from ADDR if supplied. - -`k' - Kill the target program. - -`?' - Report the most recent signal. To allow you to take advantage of - the GDB signal handling commands, one of the functions of the - debugging stub is to report CPU traps as the corresponding POSIX - signal values. - -`T' - Allows the remote stub to send only the registers that GDB needs - to make a quick decision about single-stepping or conditional - breakpoints. This eliminates the need to fetch the entire - register set for each instruction being stepped through. - - GDB now implements a write-through cache for registers and only - re-reads the registers if the target has run. - - If you have trouble with the serial connection, you can use the -command `set remotedebug'. This makes GDB report on all packets sent -back and forth across the serial line to the remote machine. The -packet-debugging information is printed on the GDB standard output -stream. `set remotedebug off' turns it off, and `show remotedebug' -shows you its current state. - - -File: gdb.info, Node: Server, Next: NetWare, Prev: Protocol, Up: Remote Serial - -Using the `gdbserver' program -............................. - - `gdbserver' is a control program for Unix-like systems, which allows -you to connect your program with a remote GDB via `target remote'--but -without linking in the usual debugging stub. - - `gdbserver' is not a complete replacement for the debugging stubs, -because it requires essentially the same operating-system facilities -that GDB itself does. In fact, a system that can run `gdbserver' to -connect to a remote GDB could also run GDB locally! `gdbserver' is -sometimes useful nevertheless, because it is a much smaller program -than GDB itself. It is also easier to port than all of GDB, so you may -be able to get started more quickly on a new system by using -`gdbserver'. Finally, if you develop code for real-time systems, you -may find that the tradeoffs involved in real-time operation make it -more convenient to do as much development work as possible on another -system, for example by cross-compiling. You can use `gdbserver' to -make a similar choice for debugging. - - GDB and `gdbserver' communicate via either a serial line or a TCP -connection, using the standard GDB remote serial protocol. - -*On the target machine,* - you need to have a copy of the program you want to debug. - `gdbserver' does not need your program's symbol table, so you can - strip the program if necessary to save space. GDB on the host - system does all the symbol handling. - - To use the server, you must tell it how to communicate with GDB; - the name of your program; and the arguments for your program. The - syntax is: - - target> gdbserver COMM PROGRAM [ ARGS ... ] - - COMM is either a device name (to use a serial line) or a TCP - hostname and portnumber. For example, to debug Emacs with the - argument `foo.txt' and communicate with GDB over the serial port - `/dev/com1': - - target> gdbserver /dev/com1 emacs foo.txt - - `gdbserver' waits passively for the host GDB to communicate with - it. - - To use a TCP connection instead of a serial line: - - target> gdbserver host:2345 emacs foo.txt - - The only difference from the previous example is the first - argument, specifying that you are communicating with the host GDB - via TCP. The `host:2345' argument means that `gdbserver' is to - expect a TCP connection from machine `host' to local TCP port 2345. - (Currently, the `host' part is ignored.) You can choose any number - you want for the port number as long as it does not conflict with - any TCP ports already in use on the target system (for example, - `23' is reserved for `telnet').(1) You must use the same port - number with the host GDB `target remote' command. - -*On the GDB host machine,* - you need an unstripped copy of your program, since GDB needs - symbols and debugging information. Start up GDB as usual, using - the name of the local copy of your program as the first argument. - (You may also need the `--baud' option if the serial line is - running at anything other than 9600 bps.) After that, use `target - remote' to establish communications with `gdbserver'. Its argument - is either a device name (usually a serial device, like - `/dev/ttyb'), or a TCP port descriptor in the form `HOST:PORT'. - For example: - - (gdb) target remote /dev/ttyb - - communicates with the server via serial line `/dev/ttyb', and - - (gdb) target remote the-target:2345 - - communicates via a TCP connection to port 2345 on host - `the-target'. For TCP connections, you must start up `gdbserver' - prior to using the `target remote' command. Otherwise you may get - an error whose text depends on the host system, but which usually - looks something like `Connection refused'. - - ---------- Footnotes ---------- - - (1) If you choose a port number that conflicts with another service, -`gdbserver' prints an error message and exits. - - -File: gdb.info, Node: NetWare, Prev: Server, Up: Remote Serial - -Using the `gdbserve.nlm' program -................................ - - `gdbserve.nlm' is a control program for NetWare systems, which -allows you to connect your program with a remote GDB via `target -remote'. - - GDB and `gdbserve.nlm' communicate via a serial line, using the -standard GDB remote serial protocol. - -*On the target machine,* - you need to have a copy of the program you want to debug. - `gdbserve.nlm' does not need your program's symbol table, so you - can strip the program if necessary to save space. GDB on the host - system does all the symbol handling. - - To use the server, you must tell it how to communicate with GDB; - the name of your program; and the arguments for your program. The - syntax is: - - load gdbserve [ BOARD=BOARD ] [ PORT=PORT ] - [ BAUD=BAUD ] PROGRAM [ ARGS ... ] - - BOARD and PORT specify the serial line; BAUD specifies the baud - rate used by the connection. PORT and NODE default to 0, BAUD - defaults to 9600 bps. - - For example, to debug Emacs with the argument `foo.txt'and - communicate with GDB over serial port number 2 or board 1 using a - 19200 bps connection: - - load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt - -*On the GDB host machine,* - you need an unstripped copy of your program, since GDB needs - symbols and debugging information. Start up GDB as usual, using - the name of the local copy of your program as the first argument. - (You may also need the `--baud' option if the serial line is - running at anything other than 9600 bps. After that, use `target - remote' to establish communications with `gdbserve.nlm'. Its - argument is a device name (usually a serial device, like - `/dev/ttyb'). For example: - - (gdb) target remote /dev/ttyb - - communications with the server via serial line `/dev/ttyb'. - - -File: gdb.info, Node: i960-Nindy Remote, Next: UDI29K Remote, Prev: Remote Serial, Up: Remote - -GDB with a remote i960 (Nindy) ------------------------------- - - "Nindy" is a ROM Monitor program for Intel 960 target systems. When -GDB is configured to control a remote Intel 960 using Nindy, you can -tell GDB how to connect to the 960 in several ways: - - * Through command line options specifying serial port, version of the - Nindy protocol, and communications speed; - - * By responding to a prompt on startup; - - * By using the `target' command at any point during your GDB - session. *Note Commands for managing targets: Target Commands. - -* Menu: - -* Nindy Startup:: Startup with Nindy -* Nindy Options:: Options for Nindy -* Nindy Reset:: Nindy reset command - - -File: gdb.info, Node: Nindy Startup, Next: Nindy Options, Up: i960-Nindy Remote - -Startup with Nindy -.................. - - If you simply start `gdb' without using any command-line options, -you are prompted for what serial port to use, *before* you reach the -ordinary GDB prompt: - - Attach /dev/ttyNN -- specify NN, or "quit" to quit: - -Respond to the prompt with whatever suffix (after `/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 `target' (*note Commands for managing targets: Target Commands.). - |