This is ./gdb.info, produced by makeinfo version 4.0b from gdb.texinfo. INFO-DIR-SECTION Programming & development tools. START-INFO-DIR-ENTRY * Gdb: (gdb). The GNU debugger. END-INFO-DIR-ENTRY This file documents the GNU debugger GDB. This is the Ninth Edition, January 2002, of `Debugging with GDB: the GNU Source-Level Debugger' for GDB Version 5.1.1. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Free Software" and "Free Software Needs Free Documentation", with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. (a) The Free Software Foundation's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  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. In the examples below, `<-' and `->' are used to indicate transmitted and received data respectfully. All GDB commands and responses (other than acknowledgments) are sent as a PACKET. A PACKET is introduced with the character `$', the actual PACKET-DATA, and the terminating character `#' followed by a two-digit CHECKSUM: `$'PACKET-DATA`#'CHECKSUM The two-digit CHECKSUM is computed as the modulo 256 sum of all characters between the leading `$' and the trailing `#' (an eight bit unsigned checksum). Implementors should note that prior to GDB 5.0 the protocol specification also included an optional two-digit SEQUENCE-ID: `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM That SEQUENCE-ID was appended to the acknowledgment. GDB has never output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must not accept SEQUENCE-ID. When either the host or the target machine receives a packet, the first response expected is an acknowledgment: either `+' (to indicate the package was received correctly) or `-' (to request retransmission): <- `$'PACKET-DATA`#'CHECKSUM -> `+' The host (GDB) sends COMMANDs, and the target (the debugging stub incorporated in your program) sends a RESPONSE. In the case of step and continue COMMANDs, the response is only sent when the operation has completed (the target has again stopped). PACKET-DATA consists of a sequence of characters with the exception of `#' and `$' (see `X' packet for additional exceptions). Fields within the packet should be separated using `,' `;' or `:'. Except where otherwise noted all numbers are represented in HEX with leading zeros suppressed. Implementors should note that prior to GDB 5.0, the character `:' could not appear as the third character in a packet (as it would potentially conflict with the SEQUENCE-ID). Response DATA can be run-length encoded to save space. A `*' means that the next character is an ASCII encoding giving a repeat count which stands for that many repetitions of the character preceding the `*'. The encoding is `n+29', yielding a printable character where `n >=3' (which is where rle starts to win). The printable characters `$', `#', `+' and `-' or with a numeric value greater than 126 should not be used. Some remote systems have used a different run-length encoding mechanism loosely refered to as the cisco encoding. Following the `*' character are two hex digits that indicate the size of the packet. So: "`0* '" means the same as "0000". The error response returned for some packets includes a two character error number. That number is not well defined. For any COMMAND not supported by the stub, an empty response (`$#00') should be returned. That way it is possible to extend the protocol. A newer GDB can tell if a packet is supported based on that response. A stub is required to support the `g', `G', `m', `M', `c', and `s' COMMANDs. All other COMMANDs are optional. Below is a complete list of all currently defined COMMANDs and their corresponding response DATA: Packet Request Description extended mode `!' Enable extended mode. In extended mode, the remote server is made persistent. The `R' packet is used to restart the program being debugged. reply `OK' The remote target both supports and has enabled extended mode. last signal `?' Indicate the reason the target halted. The reply is the same as for step and continue. reply see below reserved `a' Reserved for future use set program arguments `A'ARGLEN`,'ARGNUM`,'ARG`,...' *(reserved)* Initialized `argv[]' array passed into program. ARGLEN specifies the number of bytes in the hex encoded byte stream ARG. See `gdbserver' for more details. reply `OK' reply `E'NN set baud `b'BAUD Change the serial line speed *(deprecated)* to BAUD. JTC: _When does the transport layer state change? When it's received, or after the ACK is transmitted. In either case, there are problems if the command or the acknowledgment packet is dropped._ Stan: _If people really wanted to add something like this, and get it working for the first time, they ought to modify ser-unix.c to send some kind of out-of-band message to a specially-setup stub and have the switch happen "in between" packets, so that from remote protocol's point of view, nothing actually happened._ set breakpoint `B'ADDR,MODE Set (MODE is `S') or clear *(deprecated)* (MODE is `C') a breakpoint at ADDR. _This has been replaced by the `Z' and `z' packets._ continue `c'ADDR ADDR is address to resume. If ADDR is omitted, resume at current address. reply see below continue with signal `C'SIG`;'ADDR Continue with signal SIG (hex signal number). If `;'ADDR is omitted, resume at same address. reply see below toggle debug `d' toggle debug flag. *(deprecated)* detach `D' Detach GDB from the remote system. Sent to the remote target before GDB disconnects. reply _no response_ GDB does not check for any response after sending this packet. reserved `e' Reserved for future use reserved `E' Reserved for future use reserved `f' Reserved for future use reserved `F' Reserved for future use read registers `g' Read general registers. reply XX... Each byte of register data is described by two hex digits. The bytes with the register are transmitted in target byte order. The size of each register and their position within the `g' PACKET are determined by the GDB internal macros REGISTER_RAW_SIZE and REGISTER_NAME macros. The specification of several standard `g' packets is specified below. `E'NN for an error. write regs `G'XX... See `g' for a description of the XX... data. reply `OK' for success reply `E'NN for an error reserved `h' Reserved for future use set thread `H'CT... Set thread for subsequent operations (`m', `M', `g', `G', et.al.). C = `c' for thread used in step and continue; T... can be -1 for all threads. C = `g' for thread used in other operations. If zero, pick a thread, any thread. reply `OK' for success reply `E'NN for an error cycle step *(draft)* `i'ADDR`,'NNN Step the remote target by a single clock cycle. If `,'NNN is present, cycle step NNN cycles. If ADDR is present, cycle step starting at that address. signal then cycle `I' See `i' and `S' for likely step *(reserved)* syntax and semantics. reserved `j' Reserved for future use reserved `J' Reserved for future use kill request `k' FIXME: _There is no description of how operate when a specific thread context has been selected (ie. does 'k' kill only that thread?)_. reserved `l' Reserved for future use reserved `L' Reserved for future use read memory `m'ADDR`,'LENGTH Read LENGTH bytes of memory starting at address ADDR. Neither GDB nor the stub assume that sized memory transfers are assumed using word alligned accesses. FIXME: _A word aligned memory transfer mechanism is needed._ reply XX... XX... is mem contents. Can be fewer bytes than requested if able to read only part of the data. Neither GDB nor the stub assume that sized memory transfers are assumed using word alligned accesses. FIXME: _A word aligned memory transfer mechanism is needed._ reply `E'NN NN is errno write mem `M'ADDR,LENGTH`:'XX... Write LENGTH bytes of memory starting at address ADDR. XX... is the data. reply `OK' for success reply `E'NN for an error (this includes the case where only part of the data was written). reserved `n' Reserved for future use reserved `N' Reserved for future use reserved `o' Reserved for future use reserved `O' Reserved for future use read reg *(reserved)* `p'N... See write register. return R.... The hex encoded value of the register in target byte order. write reg `P'N...`='R... Write register N... with value R..., which contains two hex digits for each byte in the register (target byte order). reply `OK' for success reply `E'NN for an error general query `q'QUERY Request info about QUERY. In general GDB queries have a leading upper case letter. Custom vendor queries should use a company prefix (in lower case) ex: `qfsf.var'. QUERY may optionally be followed by a `,' or `;' separated list. Stubs must ensure that they match the full QUERY name. reply `XX...' Hex encoded data from query. The reply can not be empty. reply `E'NN error reply reply `' Indicating an unrecognized QUERY. general set `Q'VAR`='VAL Set value of VAR to VAL. See `q' for a discussing of naming conventions. reset *(deprecated)* `r' Reset the entire system. remote restart `R'XX Restart the program being debugged. XX, while needed, is ignored. This packet is only available in extended mode. no reply The `R' packet has no reply. step `s'ADDR ADDR is address to resume. If ADDR is omitted, resume at same address. reply see below step with signal `S'SIG`;'ADDR Like `C' but step not continue. reply see below search `t'ADDR`:'PP`,'MM Search backwards starting at address ADDR for a match with pattern PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 digits. thread alive `T'XX Find out if the thread XX is alive. reply `OK' thread is still alive reply `E'NN thread is dead reserved `u' Reserved for future use reserved `U' Reserved for future use reserved `v' Reserved for future use reserved `V' Reserved for future use reserved `w' Reserved for future use reserved `W' Reserved for future use reserved `x' Reserved for future use write mem (binary) `X'ADDR`,'LENGTH:XX... ADDR is address, LENGTH is number of bytes, XX... is binary data. The characters `$', `#', and `0x7d' are escaped using `0x7d'. reply `OK' for success reply `E'NN for an error reserved `y' Reserved for future use reserved `Y' Reserved for future use remove break or `z'T`,'ADDR`,'LENGTH See `Z'. watchpoint *(draft)* insert break or `Z'T`,'ADDR`,'LENGTH T is type: `0' - software watchpoint *(draft)* breakpoint, `1' - hardware breakpoint, `2' - write watchpoint, `3' - read watchpoint, `4' - access watchpoint; ADDR is address; LENGTH is in bytes. For a software breakpoint, LENGTH specifies the size of the instruction to be patched. For hardware breakpoints and watchpoints LENGTH specifies the memory region to be monitored. To avoid potential problems with duplicate packets, the operations should be implemented in an idempotent way. reply `E'NN for an error reply `OK' for success `' If not supported. reserved Reserved for future use The `C', `c', `S', `s' and `?' packets can receive any of the below as a reply. In the case of the `C', `c', `S' and `s' packets, that reply is only returned when the target halts. In the below the exact meaning of `signal number' is poorly defined. In general one of the UNIX signal numbering conventions is used. `S'AA AA is the signal number `T'AAN...`:'R...`;'N...`:'R...`;'N...`:'R...`;'AA = two hex digit signal number; N... = register number (hex), R... = target byte ordered register contents, size defined by `REGISTER_RAW_SIZE'; N... = `thread', R... = thread process ID, this is a hex integer; N... = other string not starting with valid hex digit. GDB should ignore this N..., R... pair and go on to the next. This way we can extend the protocol. `W'AA The process exited, and AA is the exit status. This is only applicable for certains sorts of targets. `X'AA The process terminated with signal AA. `N'AA`;'T...`;'D...`;'B... AA = signal number; T... = address of *(obsolete)* symbol "_start"; D... = base of data section; B... = base of bss section. _Note: only used by Cisco Systems targets. The difference between this reply and the "qOffsets" query is that the 'N' packet may arrive spontaneously whereas the 'qOffsets' is a query initiated by the host debugger._ `O'XX... XX... is hex encoding of ASCII data. This can happen at any time while the program is running and the debugger should continue to wait for 'W', 'T', etc. The following set and query packets have already been defined. current thread `q'`C' Return the current thread id. reply `QC'PID Where PID is a HEX encoded 16 bit process id. reply * Any other reply implies the old pid. all thread ids `q'`fThreadInfo' `q'`sThreadInfo'Obtain a list of active thread ids from the target (OS). Since there may be too many active threads to fit into one reply packet, this query works iteratively: it may require more than one query/reply sequence to obtain the entire list of threads. The first query of the sequence will be the `qf'`ThreadInfo' query; subsequent queries in the sequence will be the `qs'`ThreadInfo' query. NOTE: replaces the `qL' query (see below). reply `m' A single thread id reply a comma-separated list of thread ids `m',... reply `l' (lower case 'el') denotes end of list. In response to each query, the target will reply with a list of one or more thread ids, in big-endian hex, separated by commas. GDB will respond to each reply with a request for more thread ids (using the `qs' form of the query), until the target responds with `l' (lower-case el, for `'last''). extra thread `q'`ThreadExtraInfo'`,'ID info Where is a thread-id in big-endian hex. Obtain a printable string description of a thread's attributes from the target OS. This string may contain anything that the target OS thinks is interesting for GDB to tell the user about the thread. The string is displayed in GDB's `info threads' display. Some examples of possible thread extra info strings are "Runnable", or "Blocked on Mutex". reply XX... Where XX... is a hex encoding of ASCII data, comprising the printable string containing the extra information about the thread's attributes. query LIST or `q'`L'STARTFLAGTHREADCOUNTNEXTTHREAD THREADLIST *(deprecated)* Obtain thread information from RTOS. Where: STARTFLAG (one hex digit) is one to indicate the first query and zero to indicate a subsequent query; THREADCOUNT (two hex digits) is the maximum number of threads the response packet can contain; and NEXTTHREAD (eight hex digits), for subsequent queries (STARTFLAG is zero), is returned in the response as ARGTHREAD. NOTE: this query is replaced by the `q'`fThreadInfo' query (see above). reply `q'`M'COUNTDONEARGTHREADTHREAD... Where: COUNT (two hex digits) is the number of threads being returned; DONE (one hex digit) is zero to indicate more threads and one indicates no further threads; ARGTHREADID (eight hex digits) is NEXTTHREAD from the request packet; THREAD... is a sequence of thread IDs from the target. THREADID (eight hex digits). See `remote.c:parse_threadlist_response()'. compute CRC `q'`CRC:'ADDR`,'LENGTH of memory block reply `E'NN An error (such as memory fault) reply `C'CRC32 A 32 bit cyclic redundancy check of the specified memory region. query sect `q'`Offsets' Get section offsets that the target used offs when re-locating the downloaded image. _Note: while a `Bss' offset is included in the response, GDB ignores this and instead applies the `Data' offset to the `Bss' section._ reply `Text='XXX`;Data='YYY`;Bss='ZZZ thread info `q'`P'MODETHREADID request Returns information on THREADID. Where: MODE is a hex encoded 32 bit mode; THREADID is a hex encoded 64 bit thread ID. reply * See `remote.c:remote_unpack_thread_info_response()'. remote command `q'`Rcmd,'COMMAND COMMAND (hex encoded) is passed to the local interpreter for execution. Invalid commands should be reported using the output string. Before the final result packet, the target may also respond with a number of intermediate `O'OUTPUT console output packets. _Implementors should note that providing access to a stubs's interpreter may have security implications_. reply `OK' A command response with no output. reply OUTPUT A command response with the hex encoded output string OUTPUT. reply `E'NN Indicate a badly formed request. reply `' When `q'`Rcmd' is not recognized. symbol lookup `qSymbol::' Notify the target that GDB is prepared to serve symbol lookup requests. Accept requests from the target for the values of symbols. reply `OK' The target does not need to look up any (more) symbols. reply `qSymbol:'SYM_NAME The target requests the value of symbol SYM_NAME (hex encoded). GDB may provide the value by using the `qSymbol:'SYM_VALUE:SYM_NAME message, described below. symbol value `qSymbol:'SYM_VALUE:SYM_NAME Set the value of SYM_NAME to SYM_VALUE. SYM_NAME (hex encoded) is the name of a symbol whose value the target has previously requested. SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot supply a value for SYM_NAME, then this field will be empty. reply `OK' The target does not need to look up any (more) symbols. reply `qSymbol:'SYM_NAME The target requests the value of a new symbol SYM_NAME (hex encoded). GDB will continue to supply the values of symbols (if available), until the target ceases to request them. The following `g'/`G' packets have previously been defined. In the below, some thirty-two bit registers are transferred as sixty-four bits. Those registers should be zero/sign extended (which?) to fill the space allocated. Register bytes are transfered in target byte order. The two nibbles within a register byte are transfered most-significant - least-significant. MIPS32 All registers are transfered as thirty-two bit quantities in the order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point registers; fsr; fir; fp. MIPS64 All registers are transfered as sixty-four bit quantities (including thirty-two bit registers such as `sr'). The ordering is the same as `MIPS32'. Example sequence of a target being re-started. Notice how the restart does not get any direct output: <- `R00' -> `+' _target restarts_ <- `?' -> `+' -> `T001:1234123412341234' <- `+' Example sequence of a target being stepped by a single instruction: <- `G1445...' -> `+' <- `s' -> `+' _time passes_ -> `T001:1234123412341234' <- `+' <- `g' -> `+' -> `1455...' <- `+'  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 9600bps.) 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 9600bps. For example, to debug Emacs with the argument `foo.txt'and communicate with GDB over serial port number 2 or board 1 using a 19200bps 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 9600bps. 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: KOD, Prev: Remote, Up: Targets Kernel Object Display ===================== Some targets support kernel object display. Using this facility, GDB communicates specially with the underlying operating system and can display information about operating system-level objects such as mutexes and other synchronization objects. Exactly which objects can be displayed is determined on a per-OS basis. Use the `set os' command to set the operating system. This tells GDB which kernel object display module to initialize: (gdb) set os cisco If `set os' succeeds, GDB will display some information about the operating system, and will create a new `info' command which can be used to query the target. The `info' command is named after the operating system: (gdb) info cisco List of Cisco Kernel Objects Object Description any Any and all objects Further subcommands can be used to query about particular objects known by the kernel. There is currently no way to determine whether a given operating system is supported other than to try it.  File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Targets, Up: Top Configuration-Specific Information ********************************** While nearly all GDB commands are available for all native and cross versions of the debugger, there are some exceptions. This chapter describes things that are only available in certain configurations. There are three major categories of configurations: native configurations, where the host and target are the same, embedded operating system configurations, which are usually the same for several different processor architectures, and bare embedded processors, which are quite different from each other. * Menu: * Native:: * Embedded OS:: * Embedded Processors:: * Architectures::  File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations Native ====== This section describes details specific to particular native configurations. * Menu: * HP-UX:: HP-UX * SVR4 Process Information:: SVR4 process information * DJGPP Native:: Features specific to the DJGPP port  File: gdb.info, Node: HP-UX, Next: SVR4 Process Information, Up: Native HP-UX ----- On HP-UX systems, if you refer to a function or variable name that begins with a dollar sign, GDB searches for a user or system name first, before it searches for a convenience variable.  File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: HP-UX, Up: Native SVR4 process information ------------------------ Many versions of SVR4 provide a facility called `/proc' that can be used to examine the image of a running process using file-system subroutines. If GDB is configured for an operating system with this facility, the command `info proc' is available to report on several kinds of information about the process running your program. `info proc' works only on SVR4 systems that include the `procfs' code. This includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not HP-UX or Linux, for example. `info proc' Summarize available information about the process. `info proc mappings' Report on the address ranges accessible in the program, with information on whether your program may read, write, or execute each range. `info proc times' Starting time, user CPU time, and system CPU time for your program and its children. `info proc id' Report on the process IDs related to your program: its own process ID, the ID of its parent, the process group ID, and the session ID. `info proc status' General information on the state of the process. If the process is stopped, this report includes the reason for stopping, and any signal received. `info proc all' Show all the above information about the process.  File: gdb.info, Node: DJGPP Native, Prev: SVR4 Process Information, Up: Native Features for Debugging DJGPP Programs ------------------------------------- DJGPP is the port of GNU development tools to MS-DOS and MS-Windows. DJGPP programs are 32-bit protected-mode programs that use the "DPMI" (DOS Protected-Mode Interface) API to run on top of real-mode DOS systems and their emulations. GDB supports native debugging of DJGPP programs, and defines a few commands specific to the DJGPP port. This subsection describes those commands. `info dos' This is a prefix of DJGPP-specific commands which print information about the target system and important OS structures. `info dos sysinfo' This command displays assorted information about the underlying platform: the CPU type and features, the OS version and flavor, the DPMI version, and the available conventional and DPMI memory. `info dos gdt' `info dos ldt' `info dos idt' These 3 commands display entries from, respectively, Global, Local, and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor tables are data structures which store a descriptor for each segment that is currently in use. The segment's selector is an index into a descriptor table; the table entry for that index holds the descriptor's base address and limit, and its attributes and access rights. A typical DJGPP program uses 3 segments: a code segment, a data segment (used for both data and the stack), and a DOS segment (which allows access to DOS/BIOS data structures and absolute addresses in conventional memory). However, the DPMI host will usually define additional segments in order to support the DPMI environment. These commands allow to display entries from the descriptor tables. Without an argument, all entries from the specified table are displayed. An argument, which should be an integer expression, means display a single entry whose index is given by the argument. For example, here's a convenient way to display information about the debugged program's data segment: `(gdb) info dos ldt $ds' `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' This comes in handy when you want to see whether a pointer is outside the data segment's limit (i.e. "garbled"). `info dos pde' `info dos pte' These two commands display entries from, respectively, the Page Directory and the Page Tables. Page Directories and Page Tables are data structures which control how virtual memory addresses are mapped into physical addresses. A Page Table includes an entry for every page of memory that is mapped into the program's address space; there may be several Page Tables, each one holding up to 4096 entries. A Page Directory has up to 4096 entries, one each for every Page Table that is currently in use. Without an argument, `info dos pde' displays the entire Page Directory, and `info dos pte' displays all the entries in all of the Page Tables. An argument, an integer expression, given to the `info dos pde' command means display only that entry from the Page Directory table. An argument given to the `info dos pte' command means display entries from a single Page Table, the one pointed to by the specified entry in the Page Directory. These commands are useful when your program uses "DMA" (Direct Memory Access), which needs physical addresses to program the DMA controller. These commands are supported only with some DPMI servers. `info dos address-pte ADDR' This command displays the Page Table entry for a specified linear address. The argument linear address ADDR should already have the appropriate segment's base address added to it, because this command accepts addresses which may belong to _any_ segment. For example, here's how to display the Page Table entry for the page where the variable `i' is stored: `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' `Page Table entry for address 0x11a00d30:' `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' This says that `i' is stored at offset `0xd30' from the page whose physical base address is `0x02698000', and prints all the attributes of that page. Note that you must cast the addresses of variables to a `char *', since otherwise the value of `__djgpp_base_address', the base address of all variables and functions in a DJGPP program, will be added using the rules of C pointer arithmetics: if `i' is declared an `int', GDB will add 4 times the value of `__djgpp_base_address' to the address of `i'. Here's another example, it displays the Page Table entry for the transfer buffer: `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' `Page Table entry for address 0x29110:' `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' (The `+ 3' offset is because the transfer buffer's address is the 3rd member of the `_go32_info_block' structure.) The output of this command clearly shows that addresses in conventional memory are mapped 1:1, i.e. the physical and linear addresses are identical. This command is supported only with some DPMI servers.  File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations Embedded Operating Systems ========================== This section describes configurations involving the debugging of embedded operating systems that are available for several different architectures. * Menu: * VxWorks:: Using GDB with VxWorks GDB includes the ability to debug programs running on various real-time operating systems.