From 3cee93ac7a3fec53c2499862c9f68413e5f6043d Mon Sep 17 00:00:00 2001 From: Christopher Faylor Date: Thu, 5 Nov 1998 14:08:48 +0000 Subject: [PATCH] * top.c (gdb_readline): Allow CRLF line termination on systems which define CRLF_SOURCE_FILES. * win32-nat.c: 1) Add thread support, 2) fix ability to attach to a running process, and 3) implement limited support for cygwin signals. (thread_rec): New function. (child_add_thread): Ditto. (child_init_thread_list): Ditto. (child_delete_thread): Ditto. (do_child_fetch_inferior_registers): Ditto. (do_child_store_inferior_registers): Ditto. (handle_output_debug_string): Ditto. (child_fetch_inferior_registers): Use do_* function to perform operation. (child_store_inferior_registers): Ditto. (child_continue): Ditto. (child_thread_alive): Ditto. (cygwin_pid_to_str): Ditto. (handle_load_dll): Reorganize, add first attempt at reading dll names from attached processes. Change info messages to provide more information when dll is already loaded. (handle_exception): Changes mandated by new thread-aware structures. (child_wait): Track thread creation/destruction. Handle cygwin signals. (child_create_inferior): Ditto. (child_resume): Ditto. (child_kill_inferior): Ditto. Close child process handle to avoid a handle leak. (child_ops): Fill out child_ops fields that deal with threads. * config/i386/tm-cygwin32.h: Declare function and macro needed for converting a cygwin "pid" to a string. * config/i386/xm-cygwin32.h: define HAVE_SIGSETMASK as 0 since sigsetmask is not defined in cygwin. --- gdb/ChangeLog | 36 + gdb/config/i386/tm-cygwin32.h | 4 +- gdb/config/i386/xm-cygwin32.h | 2 + gdb/doc/gdbint.texinfo | 3890 ++++++++++++++++----------------- gdb/top.c | 8 + gdb/win32-nat.c | 735 ++++--- 6 files changed, 2460 insertions(+), 2215 deletions(-) diff --git a/gdb/ChangeLog b/gdb/ChangeLog index 0b9904b4016..ea79e13a757 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,3 +1,39 @@ +Thu Nov 5 08:41:33 1998 Christopher Faylor + + * top.c (gdb_readline): Allow CRLF line termination on systems + which define CRLF_SOURCE_FILES. + * win32-nat.c: 1) Add thread support, 2) fix ability to attach to + a running process, and 3) implement limited support for cygwin + signals. + (thread_rec): New function. + (child_add_thread): Ditto. + (child_init_thread_list): Ditto. + (child_delete_thread): Ditto. + (do_child_fetch_inferior_registers): Ditto. + (do_child_store_inferior_registers): Ditto. + (handle_output_debug_string): Ditto. + (child_fetch_inferior_registers): Use do_* function to perform + operation. + (child_store_inferior_registers): Ditto. + (child_continue): Ditto. + (child_thread_alive): Ditto. + (cygwin_pid_to_str): Ditto. + (handle_load_dll): Reorganize, add first attempt at reading + dll names from attached processes. Change info messages to provide + more information when dll is already loaded. + (handle_exception): Changes mandated by new thread-aware structures. + (child_wait): Track thread creation/destruction. Handle cygwin + signals. + (child_create_inferior): Ditto. + (child_resume): Ditto. + (child_kill_inferior): Ditto. Close child process handle to avoid a + handle leak. + (child_ops): Fill out child_ops fields that deal with threads. + * config/i386/tm-cygwin32.h: Declare function and macro needed + for converting a cygwin "pid" to a string. + * config/i386/xm-cygwin32.h: define HAVE_SIGSETMASK as 0 since + sigsetmask is not defined in cygwin. + Thu Nov 5 08:38:18 1998 Christopher Faylor * win32-nat.c: Remove obsolete PPC conditionals. diff --git a/gdb/config/i386/tm-cygwin32.h b/gdb/config/i386/tm-cygwin32.h index f7464ba66cb..b1ad894aa3a 100644 --- a/gdb/config/i386/tm-cygwin32.h +++ b/gdb/config/i386/tm-cygwin32.h @@ -119,7 +119,9 @@ double_to_i387 PARAMS ((char *, char *)); #define NAMES_HAVE_UNDERSCORE - #define IN_SOLIB_CALL_TRAMPOLINE(pc, name) skip_trampoline_code (pc, name) #define SKIP_TRAMPOLINE_CODE(pc) skip_trampoline_code (pc, 0) extern CORE_ADDR skip_trampoline_code PARAMS ((CORE_ADDR pc, char *name)); + +extern char *cygwin_pid_to_str PARAMS ((int pid)); +#define target_pid_to_str(PID) cygwin_pid_to_str (PID) diff --git a/gdb/config/i386/xm-cygwin32.h b/gdb/config/i386/xm-cygwin32.h index b722f974805..4482780c9d3 100644 --- a/gdb/config/i386/xm-cygwin32.h +++ b/gdb/config/i386/xm-cygwin32.h @@ -34,3 +34,5 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /* Define this if source files use \r\n rather than just \n. */ #define CRLF_SOURCE_FILES + +#define HAVE_SIGSETMASK 0 diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 412020ee2cb..bbc5437d259 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -1,6 +1,5 @@ \input texinfo @setfilename gdbint.info -@c $Id$ @ifinfo @format @@ -13,18 +12,19 @@ END-INFO-DIR-ENTRY @ifinfo This file documents the internals of the GNU debugger GDB. -Copyright 1990, 91, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by John Gilmore. +Copyright 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. +Contributed by Cygnus Solutions. Written by John Gilmore. +Second Edition by Stan Shebs. -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 make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. @ignore Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). @end ignore Permission is granted to copy or distribute modified versions of this @@ -34,24 +34,28 @@ regarded as a program in the language TeX). @setchapternewpage off @settitle GDB Internals + @titlepage -@title{Working in GDB} +@title{GDB Internals} @subtitle{A guide to the internals of the GNU debugger} @author John Gilmore -@author Cygnus Support +@author Cygnus Solutions +@author Second Edition: +@author Stan Shebs +@author Cygnus Solutions @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ \xdef\manvers{\$Revision$} % For use in headers, footers too {\parskip=0pt -\hfill Cygnus Support\par +\hfill Cygnus Solutions\par \hfill \manvers\par \hfill \TeX{}info \texinfoversion\par } @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1990, 91, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. +Copyright @copyright{} 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -64,181 +68,111 @@ are preserved on all copies. @c not for TeX). Existing GNU manuals seem inconsistent on this point. @top Scope of this Document -This document documents the internals of the GNU debugger, GDB. It is -intended to document aspects of GDB which apply across many different -parts of GDB (for example, @pxref{Coding Style}), or which are global -aspects of design (for example, what are the major modules and which -files document them in detail?). Information which pertains to specific -data structures, functions, variables, etc., should be put in comments -in the source code, not here. It is more likely to get noticed and kept -up to date there. Some of the information in this document should -probably be moved into comments. +This document documents the internals of the GNU debugger, GDB. It +includes description of GDB's key algorithms and operations, as well +as the mechanisms that adapt GDB to specific hosts and targets. @menu -* README:: The README File -* Getting Started:: Getting started working on GDB -* Debugging GDB:: Debugging GDB with itself -* New Architectures:: Defining a New Host or Target Architecture -* Config:: Adding a New Configuration -* Host:: Adding a New Host -* Native:: Adding a New Native Configuration -* Target:: Adding a New Target -* Languages:: Defining New Source Languages -* Releases:: Configuring GDB for Release -* Partial Symbol Tables:: How GDB reads symbols quickly at startup -* Types:: How GDB keeps track of types -* BFD support for GDB:: How BFD and GDB interface -* Symbol Reading:: Defining New Symbol Readers -* Cleanups:: Cleanups -* Wrapping:: Wrapping Output Lines -* Frames:: Keeping track of function calls -* Remote Stubs:: Code that runs in targets and talks to GDB -* Longjmp Support:: Stepping through longjmp's in the target -* Coding Style:: Strunk and White for GDB maintainers -* Clean Design:: Frank Lloyd Wright for GDB maintainers -* Submitting Patches:: How to get your changes into GDB releases -* Host Conditionals:: What features exist in the host -* Target Conditionals:: What features exist in the target -* Native Conditionals:: Conditionals for when host and target are same -* Obsolete Conditionals:: Conditionals that don't exist any more -* XCOFF:: The Object file format used on IBM's RS/6000 +* Requirements:: +* Overall Structure:: +* Algorithms:: +* User Interface:: +* Symbol Handling:: +* Language Support:: +* Host Definition:: +* Target Architecture Definition:: +* Target Vector Definition:: +* Native Debugging:: +* Support Libraries:: +* Coding:: +* Porting GDB:: +* Hints:: @end menu -@node README -@chapter The @file{README} File +@node Requirements -Check the @file{README} file, it often has useful information that does not -appear anywhere else in the directory. +@chapter Requirements -@node Getting Started -@chapter Getting Started Working on GDB +Before diving into the internals, you should understand the formal +requirements and other expectations for GDB. Although some of these may +seem obvious, there have been proposals for GDB that have run counter to +these requirements. -GDB is a large and complicated program, and if you first starting to -work on it, it can be hard to know where to start. Fortunately, if you -know how to go about it, there are ways to figure out what is going on: +First of all, GDB is a debugger. It's not designed to be a front panel +for embedded systems. It's not a text editor. It's not a shell. It's +not a programming environment. -@itemize @bullet -@item -This manual, the GDB Internals manual, has information which applies -generally to many parts of GDB. +GDB is an interactive tool. Although a batch mode is available, GDB's +primary role is to interact with a human programmer. -@item -Information about particular functions or data structures are located in -comments with those functions or data structures. If you run across a -function or a global variable which does not have a comment correctly -explaining what is does, this can be thought of as a bug in GDB; feel -free to submit a bug report, with a suggested comment if you can figure -out what the comment should say (@pxref{Submitting Patches}). If you -find a comment which is actually wrong, be especially sure to report that. +GDB should be responsive to the user. A programmer hot on the trail of +a nasty bug, and operating under a looming deadline, is going to be very +impatient of everything, including the response time to debugger +commands. -Comments explaining the function of macros defined in host, target, or -native dependent files can be in several places. Sometimes they are -repeated every place the macro is defined. Sometimes they are where the -macro is used. Sometimes there is a header file which supplies a -default definition of the macro, and the comment is there. This manual -also has a list of macros (@pxref{Host Conditionals}, @pxref{Target -Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete -Conditionals}) with some documentation. +GDB should be relatively permissive, such as for expressions. While the +compiler should be picky (or have the option to be made picky), since +source code lives for a long time usually, the programmer doing +debugging shouldn't be spending time figuring out to mollify the +debugger. -@item -Start with the header files. Once you some idea of how GDB's internal -symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you -will find it much easier to understand the code which uses and creates -those symbol tables. +GDB will be called upon to deal with really large programs. Executable +sizes of 50 to 100 megabytes occur regularly, and we've heard reports of +programs approaching 1 gigabyte in size. -@item -You may wish to process the information you are getting somehow, to -enhance your understanding of it. Summarize it, translate it to another -language, add some (perhaps trivial or non-useful) feature to GDB, use -the code to predict what a test case would do and write the test case -and verify your prediction, etc. If you are reading code and your eyes -are starting to glaze over, this is a sign you need to use a more active -approach. +GDB should be able to run everywhere. No other debugger is available +for even half as many configurations as GDB supports. -@item -Once you have a part of GDB to start with, you can find more -specifically the part you are looking for by stepping through each -function with the @code{next} command. Do not use @code{step} or you -will quickly get distracted; when the function you are stepping through -calls another function try only to get a big-picture understanding -(perhaps using the comment at the beginning of the function being -called) of what it does. This way you can identify which of the -functions being called by the function you are stepping through is the -one which you are interested in. You may need to examine the data -structures generated at each stage, with reference to the comments in -the header files explaining what the data structures are supposed to -look like. -Of course, this same technique can be used if you are just reading the -code, rather than actually stepping through it. The same general -principle applies---when the code you are looking at calls something -else, just try to understand generally what the code being called does, -rather than worrying about all its details. +@node Overall Structure -@item -A good place to start when tracking down some particular area is with a -command which invokes that feature. Suppose you want to know how -single-stepping works. As a GDB user, you know that the @code{step} -command invokes single-stepping. The command is invoked via command -tables (see @file{command.h}); by convention the function which actually -performs the command is formed by taking the name of the command and -adding @samp{_command}, or in the case of an @code{info} subcommand, -@samp{_info}. For example, the @code{step} command invokes the -@code{step_command} function and the @code{info display} command invokes -@code{display_info}. When this convention is not followed, you might -have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on -itself and set a breakpoint in @code{execute_command}. +@chapter Overall Structure -@item -If all of the above fail, it may be appropriate to ask for information -on @code{bug-gdb}. But @emph{never} post a generic question like ``I was -wondering if anyone could give me some tips about understanding -GDB''---if we had some magic secret we would put it in this manual. -Suggestions for improving the manual are always welcome, of course. -@end itemize +GDB consists of three major subsystems: user interface, symbol handling +(the ``symbol side''), and target system handling (the ``target side''). -Good luck! +Ther user interface consists of several actual interfaces, plus +supporting code. -@node Debugging GDB -@chapter Debugging GDB with itself -If GDB is limping on your machine, this is the preferred way to get it -fully functional. Be warned that in some ancient Unix systems, like -Ultrix 4.2, a program can't be running in one process while it is being -debugged in another. Rather than typing the command @code{@w{./gdb -./gdb}}, which works on Suns and such, you can copy @file{gdb} to -@file{gdb2} and then type @code{@w{./gdb ./gdb2}}. +The symbol side consists of object file readers, debugging info +interpreters, symbol table management, source language expression +parsing, type and value printing. -When you run GDB in the GDB source directory, it will read a -@file{.gdbinit} file that sets up some simple things to make debugging -gdb easier. The @code{info} command, when executed without a subcommand -in a GDB being debugged by gdb, will pop you back up to the top level -gdb. See @file{.gdbinit} for details. +The target side consists of execution control, stack frame analysis, and +physical target manipulation. -If you use emacs, you will probably want to do a @code{make TAGS} after -you configure your distribution; this will put the machine dependent -routines for your local machine where they will be accessed first by -@kbd{M-.} +The target side/symbol side division is not formal, and there are a +number of exceptions. For instance, core file support involves symbolic +elements (the basic core file reader is in BFD) and target elements (it +supplies the contents of memory and the values of registers). Instead, +this division is useful for understanding how the minor subsystems +should fit together. -Also, make sure that you've either compiled GDB with your local cc, or -have run @code{fixincludes} if you are compiling with gcc. +@section The Symbol Side + +The symbolic side of GDB can be thought of as ``everything you can do in +GDB without having a live program running''. For instance, you can look +at the types of variables, and evaluate many kinds of expressions. + +@section The Target Side -@node New Architectures -@chapter Defining a New Host or Target Architecture +The target side of GDB is the ``bits and bytes manipulator''. Although +it may make reference to symbolic info here and there, most of the +target side will run with only a stripped executable available -- or +even no executable at all, in remote debugging cases. -When building support for a new host and/or target, much of the work you -need to do is handled by specifying configuration files; -@pxref{Config,,Adding a New Configuration}. Further work can be -divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and -``target-dependent'' (@pxref{Target,,Adding a New Target}). The -following discussion is meant to explain the difference between hosts -and targets. +Operations such as disassembly, stack frame crawls, and register +display, are able to work with no symbolic info at all. In some cases, +such as disassembly, GDB will use symbolic info to present addresses +relative to symbols rather than as raw numbers, but it will work either +way. -@heading What is considered ``host-dependent'' versus ``target-dependent''? +@section Configurations @dfn{Host} refers to attributes of the system where GDB runs. @dfn{Target} refers to the system where the program being debugged -executes. In most cases they are the same machine, in which case -a third type of @dfn{Native} attributes come into play. +executes. In most cases they are the same machine, in which case a +third type of @dfn{Native} attributes come into play. Defines and include files needed to build on the host are host support. Examples are tty support, system defined types, host byte order, host @@ -253,461 +187,481 @@ Information that is only needed when the host and target are the same, is native dependent. One example is Unix child process support; if the host and target are not the same, doing a fork to start the target process is a bad idea. The various macros needed for finding the -registers in the @code{upage}, running @code{ptrace}, and such are all in the -native-dependent files. +registers in the @code{upage}, running @code{ptrace}, and such are all +in the native-dependent files. -Another example of native-dependent code is support for features -that are really part of the target environment, but which require -@code{#include} files that are only available on the host system. -Core file handling and @code{setjmp} handling are two common cases. +Another example of native-dependent code is support for features that +are really part of the target environment, but which require +@code{#include} files that are only available on the host system. Core +file handling and @code{setjmp} handling are two common cases. -When you want to make GDB work ``native'' on a particular -machine, you have to include all three kinds of information. +When you want to make GDB work ``native'' on a particular machine, you +have to include all three kinds of information. -The dependent information in GDB is organized into files by naming -conventions. -Host-Dependent Files -@table @file -@item config/*/*.mh -Sets Makefile parameters -@item config/*/xm-*.h -Global #include's and #define's and definitions -@item *-xdep.c -Global variables and functions -@end table - -Native-Dependent Files -@table @file -@item config/*/*.mh -Sets Makefile parameters (for @emph{both} host and native) -@item config/*/nm-*.h -#include's and #define's and definitions. This file -is only included by the small number of modules that need it, -so beware of doing feature-test #define's from its macros. -@item *-nat.c -global variables and functions -@end table +@node Algorithms -Target-Dependent Files -@table @file -@item config/*/*.mt -Sets Makefile parameters -@item config/*/tm-*.h -Global #include's and #define's and definitions -@item *-tdep.c -Global variables and functions -@end table +@chapter Algorithms -At this writing, most supported hosts have had their host and native -dependencies sorted out properly. There are a few stragglers, which -can be recognized by the absence of NATDEPFILES lines in their -@file{config/*/*.mh}. +GDB uses a number of debugging-specific algorithms. They are often not +very complicated, but get lost in the thicket of special cases and +real-world issues. This chapter describes the basic algorithms and +mentions some of the specific target definitions that they use. -@node Config -@chapter Adding a New Configuration +@section Frames -Most of the work in making GDB compile on a new machine is in specifying -the configuration of the machine. This is done in a dizzying variety of -header files and configuration scripts, which we hope to make more -sensible soon. Let's say your new host is called an @var{xxx} (e.g. -@samp{sun4}), and its full three-part configuration name is -@code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In -particular: +A frame is a construct that GDB uses to keep track of calling and called +functions. -In the top level directory, edit @file{config.sub} and add @var{xarch}, -@var{xvend}, and @var{xos} to the lists of supported architectures, -vendors, and operating systems near the bottom of the file. Also, add -@var{xxx} as an alias that maps to -@code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by -running +@code{FRAME_FP} in the machine description has no meaning to the +machine-independent part of GDB, except that it is used when setting up +a new frame from scratch, as follows: @example -./config.sub @var{xxx} -@end example -@noindent -and -@example -./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}} + create_new_frame (read_register (FP_REGNUM), read_pc ())); @end example -@noindent -which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}} -and no error messages. -Now, go to the @file{bfd} directory and -create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the -other @file{h-*.h} files as templates, and create one that brings in the -right include files for your system, and defines any host-specific -macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories. -(They all share the bfd @file{hosts} directory and the @file{configure.host} -file.) - -Then edit @file{bfd/configure.host}. Add a line to recognize your -@code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set -@code{my_host} to @var{xxx} when you recognize it. This will cause your -file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration -time. When creating the line that recognizes your configuration, -only match the fields that you really need to match; e.g. don't -match the architecture or manufacturer if the OS is sufficient -to distinguish the configuration that your @file{h-@var{xxx}.h} file supports. -Don't match the manufacturer name unless you really need to. -This should make future ports easier. - -Also, if this host requires any changes to the Makefile, create a file -@file{bfd/config/@var{xxx}.mh}, which includes the required lines. - -It's possible that the @file{libiberty} and @file{readline} directories -won't need any changes for your configuration, but if they do, you can -change the @file{configure.in} file there to recognize your system and -map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}} -to the @file{config/} subdirectory, to set any makefile variables you -need. The only current options in there are things like @samp{-DSYSV}. -(This @file{mh-@var{xxx}} naming convention differs from elsewhere -in GDB, by historical accident. It should be cleaned up so that all -such files are called @file{@var{xxx}.mh}.) - -Aha! Now to configure GDB itself! Edit -@file{gdb/configure.in} to recognize your system and set @code{gdb_host} -to @var{xxx}, and (unless your desired target is already available) also -set @code{gdb_target} to something appropriate (for instance, -@var{xxx}). To handle new hosts, modify the segment after the comment -@samp{# per-host}; to handle new targets, modify after @samp{# -per-target}. -@c Would it be simpler to just use different per-host and per-target -@c *scripts*, and call them from {configure} ? +Other than that, all the meaning imparted to @code{FP_REGNUM} is +imparted by the machine-dependent code. So, @code{FP_REGNUM} can have +any value that is convenient for the code that creates new frames. +(@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is +defined; that is where you should use the @code{FP_REGNUM} value, if +your frames are nonstandard.) + +Given a GDB frame, define @code{FRAME_CHAIN} to determine the address of +the calling function's frame. This will be used to create a new GDB +frame struct, and then @code{INIT_EXTRA_FRAME_INFO} and +@code{INIT_FRAME_PC} will be called for the new frame. + +@section Breakpoint Handling + +In general, a breakpoint is a user-designated location in the program +where the user wants to regain control if program execution ever reaches +that location. + +There are two main ways to implement breakpoints; either as ``hardware'' +breakpoints or as ``software'' breakpoints. + +Hardware breakpoints are sometimes available as a builtin debugging +features with some chips. Typically these work by having dedicated +register into which the breakpoint address may be stored. If the PC +ever matches a value in a breakpoint registers, the CPU raises an +exception and reports it to GDB. Another possibility is when an +emulator is in use; many emulators include circuitry that watches the +address lines coming out from the processor, and force it to stop if the +address matches a breakpoint's address. A third possibility is that the +target already has the ability to do breakpoints somehow; for instance, +a ROM monitor may do its own software breakpoints. So although these +are not literally ``hardware breakpoints'', from GDB's point of view +they work the same; GDB need not do nothing more than set the breakpoint +and wait for something to happen. + +Since they depend on hardware resources, hardware breakpoints may be +limited in number; when the user asks for more, GDB will start trying to +set software breakpoints. + +Software breakpoints require GDB to do somewhat more work. The basic +theory is that GDB will replace a program instruction a trap, illegal +divide, or some other instruction that will cause an exception, and then +when it's encountered, GDB will take the exception and stop the program. +When the user says to continue, GDB will restore the original +instruction, single-step, re-insert the trap, and continue on. + +Since it literally overwrites the program being tested, the program area +must be writeable, so this technique won't work on programs in ROM. It +can also distort the behavior of programs that examine themselves, +although the situation would be highly unusual. + +Also, the software breakpoint instruction should be the smallest size of +instruction, so it doesn't overwrite an instruction that might be a jump +target, and cause disaster when the program jumps into the middle of the +breakpoint instruction. (Strictly speaking, the breakpoint must be no +larger than the smallest interval between instructions that may be jump +targets; perhaps there is an architecture where only even-numbered +instructions may jumped to.) Note that it's possible for an instruction +set not to have any instructions usable for a software breakpoint, +although in practice only the ARC has failed to define such an +instruction. + +The basic definition of the software breakpoint is the macro +@code{BREAKPOINT}. + +Basic breakpoint object handling is in @file{breakpoint.c}. However, +much of the interesting breakpoint action is in @file{infrun.c}. + +@section Single Stepping + +@section Signal Handling + +@section Thread Handling + +@section Inferior Function Calls + +@section Longjmp Support -Finally, you'll need to specify and define GDB's host-, native-, and -target-dependent @file{.h} and @file{.c} files used for your -configuration; the next two chapters discuss those. +GDB has support for figuring out that the target is doing a +@code{longjmp} and for stopping at the target of the jump, if we are +stepping. This is done with a few specialized internal breakpoints, +which are visible in the @code{maint info breakpoint} command. +To make this work, you need to define a macro called +@code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf} +structure and extract the longjmp target address. Since @code{jmp_buf} +is target specific, you will need to define it in the appropriate +@file{tm-@var{xyz}.h} file. Look in @file{tm-sun4os4.h} and +@file{sparc-tdep.c} for examples of how to do this. -@node Host -@chapter Adding a New Host +@node User Interface -Once you have specified a new configuration for your host -(@pxref{Config,,Adding a New Configuration}), there are three remaining -pieces to making GDB work on a new machine. First, you have to make it -host on the new machine (compile there, handle that machine's terminals -properly, etc). If you will be cross-debugging to some other kind of -system that's already supported, you are done. +@chapter User Interface -If you want to use GDB to debug programs that run on the new machine, -you have to get it to understand the machine's object files, symbol -files, and interfaces to processes; @pxref{Target,,Adding a New Target} -and @pxref{Native,,Adding a New Native Configuration} +GDB has several user interfaces. Although the command-line interface +is the most common and most familiar, there are others. -Several files control GDB's configuration for host systems: +@section Command Interpreter -@table @file -@item gdb/config/@var{arch}/@var{xxx}.mh -Specifies Makefile fragments needed when hosting on machine @var{xxx}. -In particular, this lists the required machine-dependent object files, -by defining @samp{XDEPFILES=@dots{}}. Also -specifies the header file which describes host @var{xxx}, by defining -@code{XM_FILE= xm-@var{xxx}.h}. You can also define @code{CC}, -@code{REGEX} and @code{REGEX1}, @code{SYSV_DEFINE}, @code{XM_CFLAGS}, -@code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS}, -etc.; see @file{Makefile.in}. +The command interpreter in GDB is fairly simple. It is designed to +allow for the set of commands to be augmented dynamically, and also +has a recursive subcommand capability, where the first argument to +a command may itself direct a lookup on a different command list. -@item gdb/config/@var{arch}/xm-@var{xxx}.h -(@file{xm.h} is a link to this file, created by configure). -Contains C macro definitions describing the host system environment, -such as byte order, host C compiler and library, ptrace support, -and core file structure. Crib from existing @file{xm-*.h} files -to create a new one. - -@item gdb/@var{xxx}-xdep.c -Contains any miscellaneous C code required for this machine -as a host. On many machines it doesn't exist at all. If it does -exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line -in @file{gdb/config/mh-@var{xxx}}. -@end table +For instance, the @code{set} command just starts a lookup on the +@code{setlist} command list, while @code{set thread} recurses +to the @code{set_thread_cmd_list}. -@subheading Generic Host Support Files +To add commands in general, use @code{add_cmd}. @code{add_com} adds to +the main command list, and should be used for those commands. The usual +place to add commands is in the @code{_initialize_@var{xyz}} routines at the +ends of most source files. -There are some ``generic'' versions of routines that can be used by -various systems. These can be customized in various ways by macros -defined in your @file{xm-@var{xxx}.h} file. If these routines work for -the @var{xxx} host, you can just include the generic file's name (with -@samp{.o}, not @samp{.c}) in @code{XDEPFILES}. +@section Console Printing -Otherwise, if your machine needs custom support routines, you will need -to write routines that perform the same functions as the generic file. -Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o} -into @code{XDEPFILES}. +@section TUI -@table @file -@item ser-bsd.c -This contains serial line support for Berkeley-derived Unix systems. +@section libgdb -@item ser-go32.c -This contains serial line support for 32-bit programs running under DOS -using the GO32 execution environment. +@code{libgdb} was an abortive project of years ago. The theory was to +provide an API to GDB's functionality. -@item ser-termios.c -This contains serial line support for System V-derived Unix systems. -@end table +@node Symbol Handling -Now, you are now ready to try configuring GDB to compile using your system -as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do: +@chapter Symbol Handling -@example -./configure @var{xxx} --target=vxworks960 -@end example +Symbols are a key part of GDB's operation. Symbols include variables, +functions, and types. + +@section Symbol Reading -This will configure your system to cross-compile for VxWorks on -the Intel 960, which is probably not what you really want, but it's -a test case that works at this stage. (You haven't set up to be -able to debug programs that run @emph{on} @var{xxx} yet.) +GDB reads symbols from ``symbol files''. The usual symbol file is the +file containing the program which GDB is debugging. GDB can be directed +to use a different file for symbols (with the @code{symbol-file} +command), and it can also read more symbols via the ``add-file'' and +``load'' commands, or while reading symbols from shared libraries. -If this succeeds, you can try building it all with: +Symbol files are initially opened by code in @file{symfile.c} using the +BFD library. BFD identifies the type of the file by examining its +header. @code{symfile_init} then uses this identification to locate a +set of symbol-reading functions. -@example -make -@end example +Symbol reading modules identify themselves to GDB by calling +@code{add_symtab_fns} during their module initialization. The argument +to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the +name (or name prefix) of the symbol format, the length of the prefix, +and pointers to four functions. These functions are called at various +times to process symbol-files whose identification matches the specified +prefix. + +The functions supplied by each module are: -Repeat until the program configures, compiles, links, and runs. -When run, it won't be able to do much (unless you have a VxWorks/960 -board on your network) but you will know that the host support is -pretty well done. +@table @code +@item @var{xyz}_symfile_init(struct sym_fns *sf) -Good luck! Comments and suggestions about this section are particularly -welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}. +Called from @code{symbol_file_add} when we are about to read a new +symbol file. This function should clean up any internal state (possibly +resulting from half-read previous files, for example) and prepare to +read a new symbol file. Note that the symbol file which we are reading +might be a new "main" symbol file, or might be a secondary symbol file +whose symbols are being added to the existing symbol table. + +The argument to @code{@var{xyz}_symfile_init} is a newly allocated +@code{struct sym_fns} whose @code{bfd} field contains the BFD for the +new symbol file being read. Its @code{private} field has been zeroed, +and can be modified as desired. Typically, a struct of private +information will be @code{malloc}'d, and a pointer to it will be placed +in the @code{private} field. + +There is no result from @code{@var{xyz}_symfile_init}, but it can call +@code{error} if it detects an unavoidable problem. -@node Native -@chapter Adding a New Native Configuration +@item @var{xyz}_new_init() -If you are making GDB run native on the @var{xxx} machine, you have -plenty more work to do. Several files control GDB's configuration for -native support: +Called from @code{symbol_file_add} when discarding existing symbols. +This function need only handle the symbol-reading module's internal +state; the symbol table data structures visible to the rest of GDB will +be discarded by @code{symbol_file_add}. It has no arguments and no +result. It may be called after @code{@var{xyz}_symfile_init}, if a new +symbol table is being read, or may be called alone if all symbols are +simply being discarded. -@table @file -@item gdb/config/@var{xarch}/@var{xxx}.mh -Specifies Makefile fragments needed when hosting @emph{or native} -on machine @var{xxx}. -In particular, this lists the required native-dependent object files, -by defining @samp{NATDEPFILES=@dots{}}. Also -specifies the header file which describes native support on @var{xxx}, -by defining @samp{NAT_FILE= nm-@var{xxx}.h}. -You can also define @samp{NAT_CFLAGS}, -@samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS}, -etc.; see @file{Makefile.in}. +@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) -@item gdb/config/@var{arch}/nm-@var{xxx}.h -(@file{nm.h} is a link to this file, created by configure). -Contains C macro definitions describing the native system environment, -such as child process control and core file support. -Crib from existing @file{nm-*.h} files to create a new one. +Called from @code{symbol_file_add} to actually read the symbols from a +symbol-file into a set of psymtabs or symtabs. -@item gdb/@var{xxx}-nat.c -Contains any miscellaneous C code required for this native support -of this machine. On some machines it doesn't exist at all. +@code{sf} points to the struct sym_fns originally passed to +@code{@var{xyz}_sym_init} for possible initialization. @code{addr} is +the offset between the file's specified start address and its true +address in memory. @code{mainline} is 1 if this is the main symbol +table being read, and 0 if a secondary symbol file (e.g. shared library +or dynamically loaded file) is being read.@refill @end table -@subheading Generic Native Support Files +In addition, if a symbol-reading module creates psymtabs when +@var{xyz}_symfile_read is called, these psymtabs will contain a pointer +to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called +from any point in the GDB symbol-handling code. -There are some ``generic'' versions of routines that can be used by -various systems. These can be customized in various ways by macros -defined in your @file{nm-@var{xxx}.h} file. If these routines work for -the @var{xxx} host, you can just include the generic file's name (with -@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}. +@table @code +@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst) + +Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB macro) if +the psymtab has not already been read in and had its @code{pst->symtab} +pointer set. The argument is the psymtab to be fleshed-out into a +symtab. Upon return, pst->readin should have been set to 1, and +pst->symtab should contain a pointer to the new corresponding symtab, or +zero if there were no symbols in that part of the symbol file. +@end table -Otherwise, if your machine needs custom support routines, you will need -to write routines that perform the same functions as the generic file. -Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o} -into @code{NATDEPFILES}. +@section Partial Symbol Tables -@table @file +GDB has three types of symbol tables. -@item inftarg.c -This contains the @emph{target_ops vector} that supports Unix child -processes on systems which use ptrace and wait to control the child. +@itemize @bullet -@item procfs.c -This contains the @emph{target_ops vector} that supports Unix child -processes on systems which use /proc to control the child. +@item full symbol tables (symtabs). These contain the main information +about symbols and addresses. -@item fork-child.c -This does the low-level grunge that uses Unix system calls -to do a "fork and exec" to start up a child process. +@item partial symbol tables (psymtabs). These contain enough +information to know when to read the corresponding part of the full +symbol table. -@item infptrace.c -This is the low level interface to inferior processes for systems -using the Unix @code{ptrace} call in a vanilla way. +@item minimal symbol tables (msymtabs). These contain information +gleaned from non-debugging symbols. -@item core-aout.c::fetch_core_registers() -Support for reading registers out of a core file. This routine calls -@code{register_addr()}, see below. -Now that BFD is used to read core files, virtually all machines should -use @code{core-aout.c}, and should just provide @code{fetch_core_registers} in -@code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}). +@end itemize -@item core-aout.c::register_addr() -If your @code{nm-@var{xxx}.h} file defines the macro -@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to -set @code{addr} to the offset within the @samp{user} -struct of GDB register number @code{regno}. @code{blockend} is the -offset within the ``upage'' of @code{u.u_ar0}. -If @code{REGISTER_U_ADDR} is defined, -@file{core-aout.c} will define the @code{register_addr()} function and use -the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you -are using the standard @code{fetch_core_registers()}, you will need to -define your own version of @code{register_addr()}, put it into your -@code{@var{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in -the @code{NATDEPFILES} list. If you have your own -@code{fetch_core_registers()}, you may not need a separate -@code{register_addr()}. Many custom @code{fetch_core_registers()} -implementations simply locate the registers themselves.@refill -@end table +This section describes partial symbol tables. -When making GDB run native on a new operating system, -to make it possible to debug -core files, you will need to either write specific code for parsing your -OS's core files, or customize @file{bfd/trad-core.c}. First, use -whatever @code{#include} files your machine uses to define the struct of -registers that is accessible (possibly in the u-area) in a core file -(rather than @file{machine/reg.h}), and an include file that defines whatever -header exists on a core file (e.g. the u-area or a @samp{struct core}). Then -modify @code{trad_unix_core_file_p()} to use these values to set up the -section information for the data segment, stack segment, any other -segments in the core file (perhaps shared library contents or control -information), ``registers'' segment, and if there are two discontiguous -sets of registers (e.g. integer and float), the ``reg2'' segment. This -section information basically delimits areas in the core file in a -standard way, which the section-reading routines in BFD know how to seek -around in. +A psymtab is constructed by doing a very quick pass over an executable +file's debugging information. Small amounts of information are +extracted -- enough to identify which parts of the symbol table will +need to be re-read and fully digested later, when the user needs the +information. The speed of this pass causes GDB to start up very +quickly. Later, as the detailed rereading occurs, it occurs in small +pieces, at various times, and the delay therefrom is mostly invisible to +the user. +@c (@xref{Symbol Reading}.) -Then back in GDB, you need a matching routine called -@code{fetch_core_registers()}. If you can use the generic one, it's in -@file{core-aout.c}; if not, it's in your @file{@var{xxx}-nat.c} file. -It will be passed a char pointer to the entire ``registers'' segment, -its length, and a zero; or a char pointer to the entire ``regs2'' -segment, its length, and a 2. The routine should suck out the supplied -register values and install them into GDB's ``registers'' array. -(@xref{New Architectures,,Defining a New Host or Target Architecture}, -for more info about this.) +The symbols that show up in a file's psymtab should be, roughly, those +visible to the debugger's user when the program is not running code from +that file. These include external symbols and types, static symbols and +types, and enum values declared at file scope. -If your system uses @file{/proc} to control processes, and uses ELF -format core files, then you may be able to use the same routines -for reading the registers out of processes and out of core files. +The psymtab also contains the range of instruction addresses that the +full symbol table would represent. -@node Target -@chapter Adding a New Target +The idea is that there are only two ways for the user (or much of the +code in the debugger) to reference a symbol: -For a new target called @var{ttt}, first specify the configuration as -described in @ref{Config,,Adding a New Configuration}. If your new -target is the same as your new host, you've probably already done that. +@itemize @bullet -A variety of files specify attributes of the GDB target environment: +@item by its address +(e.g. execution stops at some address which is inside a function in this +file). The address will be noticed to be in the range of this psymtab, +and the full symtab will be read in. @code{find_pc_function}, +@code{find_pc_line}, and other @code{find_pc_@dots{}} functions handle +this. -@table @file -@item gdb/config/@var{arch}/@var{ttt}.mt -Contains a Makefile fragment specific to this target. -Specifies what object files are needed for target @var{ttt}, by -defining @samp{TDEPFILES=@dots{}}. -Also specifies the header file which describes @var{ttt}, by defining -@samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS}, -@samp{TM_CLIBS}, @samp{TM_CDEPS}, -and other Makefile variables here; see @file{Makefile.in}. +@item by its name +(e.g. the user asks to print a variable, or set a breakpoint on a +function). Global names and file-scope names will be found in the +psymtab, which will cause the symtab to be pulled in. Local names will +have to be qualified by a global name, or a file-scope name, in which +case we will have already read in the symtab as we evaluated the +qualifier. Or, a local symbol can be referenced when we are "in" a +local scope, in which case the first case applies. @code{lookup_symbol} +does most of the work here. -@item gdb/config/@var{arch}/tm-@var{ttt}.h -(@file{tm.h} is a link to this file, created by configure). -Contains macro definitions about the target machine's -registers, stack frame format and instructions. -Crib from existing @file{tm-*.h} files when building a new one. +@end itemize -@item gdb/@var{ttt}-tdep.c -Contains any miscellaneous code required for this target machine. -On some machines it doesn't exist at all. Sometimes the macros -in @file{tm-@var{ttt}.h} become very complicated, so they are -implemented as functions here instead, and the macro is simply -defined to call the function. - -@item gdb/exec.c -Defines functions for accessing files that are -executable on the target system. These functions open and examine an -exec file, extract data from one, write data to one, print information -about one, etc. Now that executable files are handled with BFD, every -target should be able to use the generic exec.c rather than its -own custom code. - -@item gdb/@var{arch}-pinsn.c -Prints (disassembles) the target machine's instructions. -This file is usually shared with other target machines which use the -same processor, which is why it is @file{@var{arch}-pinsn.c} rather -than @file{@var{ttt}-pinsn.c}. - -@item gdb/@var{arch}-opcode.h -Contains some large initialized -data structures describing the target machine's instructions. -This is a bit strange for a @file{.h} file, but it's OK since -it is only included in one place. @file{@var{arch}-opcode.h} is shared -between the debugger and the assembler, if the GNU assembler has been -ported to the target machine. +The only reason that psymtabs exist is to cause a symtab to be read in +at the right moment. Any symbol that can be elided from a psymtab, +while still causing that to happen, should not appear in it. Since +psymtabs don't have the idea of scope, you can't put local symbols in +them anyway. Psymtabs don't have the idea of the type of a symbol, +either, so types need not appear, unless they will be referenced by +name. -@item gdb/config/@var{arch}/tm-@var{arch}.h -This often exists to describe the basic layout of the target machine's -processor chip (registers, stack, etc). -If used, it is included by @file{tm-@var{xxx}.h}. It can -be shared among many targets that use the same processor. +It is a bug for GDB to behave one way when only a psymtab has been read, +and another way if the corresponding symtab has been read in. Such bugs +are typically caused by a psymtab that does not contain all the visible +symbols, or which has the wrong instruction address ranges. -@item gdb/@var{arch}-tdep.c -Similarly, there are often common subroutines that are shared by all -target machines that use this particular architecture. -@end table +The psymtab for a particular section of a symbol-file (objfile) could be +thrown away after the symtab has been read in. The symtab should always +be searched before the psymtab, so the psymtab will never be used (in a +bug-free environment). Currently, psymtabs are allocated on an obstack, +and all the psymbols themselves are allocated in a pair of large arrays +on an obstack, so there is little to be gained by trying to free them +unless you want to do a lot more work. -When adding support for a new target machine, there are various areas -of support that might need change, or might be OK. +@section Types -If you are using an existing object file format (a.out or COFF), -there is probably little to be done. See @file{bfd/doc/bfd.texinfo} -for more information on writing new a.out or COFF versions. +Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). -If you need to add a new object file format, you must first add it to -BFD. This is beyond the scope of this document right now. Basically -you must build a transfer vector (of type @code{bfd_target}), which will -mean writing all the required routines, and add it to the list in -@file{bfd/targets.c}. +These are the fundamental types that GDB uses internally. Fundamental +types from the various debugging formats (stabs, ELF, etc) are mapped +into one of these. They are basically a union of all fundamental types +that gdb knows about for all the languages that GDB knows about. -You must then arrange for the BFD code to provide access to the -debugging symbols. Generally GDB will have to call swapping routines -from BFD and a few other BFD internal routines to locate the debugging -information. As much as possible, GDB should not depend on the BFD -internal data structures. +Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). -For some targets (e.g., COFF), there is a special transfer vector used -to call swapping routines, since the external data structures on various -platforms have different sizes and layouts. Specialized routines that +Each time GDB builds an internal type, it marks it with one of these +types. The type may be a fundamental type, such as TYPE_CODE_INT, or a +derived type, such as TYPE_CODE_PTR which is a pointer to another type. +Typically, several FT_* types map to one TYPE_CODE_* type, and are +distinguished by other members of the type struct, such as whether the +type is signed or unsigned, and how many bits it uses. + +Builtin Types (e.g., builtin_type_void, builtin_type_char). + +These are instances of type structs that roughly correspond to +fundamental types and are created as global types for GDB to use for +various ugly historical reasons. We eventually want to eliminate these. +Note for example that builtin_type_int initialized in gdbtypes.c is +basically the same as a TYPE_CODE_INT type that is initialized in +c-lang.c for an FT_INTEGER fundamental type. The difference is that the +builtin_type is not associated with any particular objfile, and only one +instance exists, while c-lang.c builds as many TYPE_CODE_INT types as +needed, with each one associated with some particular objfile. + +@section Object File Formats + +@subsection a.out + +The @file{a.out} format is the original file format for Unix. It +consists of three sections: text, data, and bss, which are for program +code, initialized data, and uninitialized data, respectively. + +The @file{a.out} format is so simple that it doesn't have any reserved +place for debugging information. (Hey, the original Unix hackers used +@file{adb}, which is a machine-language debugger.) The only debugging +format for @file{a.out} is stabs, which for this format are encoded as +symbols with distinctive properties. + +@subsection COFF + +The COFF format was introduced with System V Release 3 (SVR3) Unix. +COFF files may have multiple sections, each prefixed by a header. The +number of sections is limited. + +The COFF specification includes support for debugging. Although this +was a step forward, the debugging information was woefully limited. For +instance, it was not possible to represent code that came from an +included file. + +@subsection ECOFF + +@subsection XCOFF + +The IBM RS/6000 running AIX uses an object file format called XCOFF. +The COFF sections, symbols, and line numbers are used, but debugging +symbols are dbx-style stabs whose strings are located in the +@samp{.debug} section (rather than the string table). For more +information, see @xref{Top,,,stabs,The Stabs Debugging Format}. + +The shared library scheme has a nice clean interface for figuring out +what shared libraries are in use, but the catch is that everything which +refers to addresses (symbol tables and breakpoints at least) needs to be +relocated for both shared libraries and the main executable. At least +using the standard mechanism this can only be done once the program has +been run (or the core file has been read). + +@subsection PE + +Windows 95 and NT use the PE (Portable Executable) format for their +executables. PE is basically COFF with an additional header or two. + +@subsection ELF + +The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar +to COFF in being organized into a number of sections, but it removes +many of COFF's limitations. + +@subsection SOM + +@section Debugging File Formats + +@subsection stabs + +@subsection COFF + +@subsection DWARF 1 + +@subsection DWARF 2 + +@subsection SOM + +@section Adding a New Symbol Reader to GDB + +If you are using an existing object file format (a.out, COFF, ELF, etc), +there is probably little to be done. + +If you need to add a new object file format, you must first add it to +BFD. This is beyond the scope of this document. + +You must then arrange for the BFD code to provide access to the +debugging symbols. Generally GDB will have to call swapping routines +from BFD and a few other BFD internal routines to locate the debugging +information. As much as possible, GDB should not depend on the BFD +internal data structures. + +For some targets (e.g., COFF), there is a special transfer vector used +to call swapping routines, since the external data structures on various +platforms have different sizes and layouts. Specialized routines that will only ever be implemented by one object file format may be called directly. This interface should be described in a file -@file{bfd/libxxx.h}, which is included by GDB. +@file{bfd/libxyz.h}, which is included by GDB. -If you are adding a new operating system for an existing CPU chip, add a -@file{tm-@var{xos}.h} file that describes the operating system -facilities that are unusual (extra symbol table info; the breakpoint -instruction needed; etc). Then write a -@file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s -@file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have -three-part configuration names, this will probably get revised to -separate the @var{xos} configuration from the @var{xarch} -configuration.) +@node Language Support + +@chapter Language Support -@node Languages -@chapter Adding a Source Language to GDB +GDB's language support is mainly driven by the symbol reader, although +it is possible for the user to set the source language manually. -To add other languages to GDB's expression parser, follow the following steps: +GDB chooses the source language by looking at the extension of the file +recorded in the debug info; @code{.c} means C, @code{.f} means Fortran, +etc. It may also use a special-purpose language identifier if the debug +format supports it, such as DWARF. + +@section Adding a Source Language to GDB + +To add other languages to GDB's expression parser, follow the following +steps: @table @emph @item Create the expression parser. -This should reside in a file @file{@var{lang}-exp.y}. Routines for building -parsed expressions into a @samp{union exp_element} list are in @file{parse.c}. +This should reside in a file @file{@var{lang}-exp.y}. Routines for +building parsed expressions into a @samp{union exp_element} list are in +@file{parse.c}. Since we can't depend upon everyone having Bison, and YACC produces parsers that define a bunch of global names, the following lines -@emph{must} be included at the top of the YACC parser, to prevent -the various parsers from defining the same global names: +@emph{must} be included at the top of the YACC parser, to prevent the +various parsers from defining the same global names: @example #define yyparse @var{lang}_parse @@ -752,9 +706,9 @@ the number of @code{exp_element}s that a given operation takes up. Add an enumerated identifier for your language to the enumerated type @code{enum language} in @file{defs.h}. -Update the routines in @file{language.c} so your language is included. These -routines include type predicates and such, which (in some cases) are -language dependent. If your language does not appear in the switch +Update the routines in @file{language.c} so your language is included. +These routines include type predicates and such, which (in some cases) +are language dependent. If your language does not appear in the switch statement, an error is reported. Also included in @file{language.c} is the code that updates the variable @@ -762,9 +716,9 @@ Also included in @file{language.c} is the code that updates the variable @code{language_@var{lang}} enumerated identifier into a printable string. -Update the function @code{_initialize_language} to include your language. This -function picks the default language upon startup, so is dependent upon -which languages that GDB is built for. +Update the function @code{_initialize_language} to include your +language. This function picks the default language upon startup, so is +dependent upon which languages that GDB is built for. Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading code so that the language of each symtab (source file) is set properly. @@ -805,1742 +759,1770 @@ Add dependencies in @file{Makefile.in}. Make sure you update the macro variables such as @code{HFILES} and @code{OBJS}, otherwise your code may not get linked in, or, worse yet, it may not get @code{tar}red into the distribution! + @end table -@node Releases -@chapter Configuring GDB for Release +@node Host Definition -From the top level directory (containing @file{gdb}, @file{bfd}, -@file{libiberty}, and so on): -@example -make -f Makefile.in gdb.tar.gz -@end example +@chapter Host Definition -This will properly configure, clean, rebuild any files that are -distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}), -and will then make a tarfile. (If the top level directory has already -been configured, you can just do @code{make gdb.tar.gz} instead.) +With the advent of autoconf, it's rarely necessary to have host +definition machinery anymore. -This procedure requires: -@itemize @bullet -@item symbolic links -@item @code{makeinfo} (texinfo2 level) -@item @TeX{} -@item @code{dvips} -@item @code{yacc} or @code{bison} -@end itemize -@noindent -@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.). +@section Adding a New Host -@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION +Most of GDB's host configuration support happens via autoconf. It +should be rare to need new host-specific definitions. GDB still uses +the host-specific definitions and files listed below, but these mostly +exist for historical reasons, and should eventually disappear. -@file{gdb.texinfo} is currently marked up using the texinfo-2 macros, -which are not yet a default for anything (but we have to start using -them sometime). +Several files control GDB's configuration for host systems: -For making paper, the only thing this implies is the right generation of -@file{texinfo.tex} needs to be included in the distribution. +@table @file -For making info files, however, rather than duplicating the texinfo2 -distribution, generate @file{gdb-all.texinfo} locally, and include the files -@file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will -split the document into one overall file and five or so included files. +@item gdb/config/@var{arch}/@var{xyz}.mh +Specifies Makefile fragments needed when hosting on machine @var{xyz}. +In particular, this lists the required machine-dependent object files, +by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file +which describes host @var{xyz}, by defining @code{XM_FILE= +xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE}, +@code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS}, +etc.; see @file{Makefile.in}. +@item gdb/config/@var{arch}/xm-@var{xyz}.h +(@file{xm.h} is a link to this file, created by configure). Contains C +macro definitions describing the host system environment, such as byte +order, host C compiler and library. -@node Partial Symbol Tables -@chapter Partial Symbol Tables +@item gdb/@var{xyz}-xdep.c +Contains any miscellaneous C code required for this machine as a host. +On most machines it doesn't exist at all. If it does exist, put +@file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in +@file{gdb/config/@var{arch}/@var{xyz}.mh}. -GDB has three types of symbol tables. +@end table -@itemize @bullet -@item full symbol tables (symtabs). These contain the main -information about symbols and addresses. -@item partial symbol tables (psymtabs). These contain enough -information to know when to read the corresponding -part of the full symbol table. -@item minimal symbol tables (msymtabs). These contain information -gleaned from non-debugging symbols. -@end itemize +@subheading Generic Host Support Files -This section describes partial symbol tables. +There are some ``generic'' versions of routines that can be used by +various systems. These can be customized in various ways by macros +defined in your @file{xm-@var{xyz}.h} file. If these routines work for +the @var{xyz} host, you can just include the generic file's name (with +@samp{.o}, not @samp{.c}) in @code{XDEPFILES}. -A psymtab is constructed by doing a very quick pass over an executable -file's debugging information. Small amounts of information are -extracted -- enough to identify which parts of the symbol table will -need to be re-read and fully digested later, when the user needs the -information. The speed of this pass causes GDB to start up very -quickly. Later, as the detailed rereading occurs, it occurs in small -pieces, at various times, and the delay therefrom is mostly invisible to -the user. (@xref{Symbol Reading}.) +Otherwise, if your machine needs custom support routines, you will need +to write routines that perform the same functions as the generic file. +Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o} +into @code{XDEPFILES}. -The symbols that show up in a file's psymtab should be, roughly, those -visible to the debugger's user when the program is not running code from -that file. These include external symbols and types, static -symbols and types, and enum values declared at file scope. +@table @file -The psymtab also contains the range of instruction addresses that the -full symbol table would represent. +@item ser-unix.c +This contains serial line support for Unix systems. This is always +included, via the makefile variable @code{SER_HARDWIRE}; override this +variable in the @file{.mh} file to avoid it. -The idea is that there are only two ways for the user (or much of -the code in the debugger) to reference a symbol: +@item ser-go32.c +This contains serial line support for 32-bit programs running under DOS, +using the GO32 execution environment. -@itemize @bullet +@item ser-tcp.c +This contains generic TCP support using sockets. -@item by its address -(e.g. execution stops at some address which is inside a function -in this file). The address will be noticed to be in the -range of this psymtab, and the full symtab will be read in. -@code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}} -functions handle this. +@end table -@item by its name -(e.g. the user asks to print a variable, or set a breakpoint on a -function). Global names and file-scope names will be found in the -psymtab, which will cause the symtab to be pulled in. Local names will -have to be qualified by a global name, or a file-scope name, in which -case we will have already read in the symtab as we evaluated the -qualifier. Or, a local symbol can be referenced when -we are "in" a local scope, in which case the first case applies. -@code{lookup_symbol} does most of the work here. +@section Host Conditionals -@end itemize +When GDB is configured and compiled, various macros are defined or left +undefined, to control compilation based on the attributes of the host +system. These macros and their meanings (or if the meaning is not +documented here, then one of the source files where they are used is +indicated) are: -The only reason that psymtabs exist is to cause a symtab to be read in -at the right moment. Any symbol that can be elided from a psymtab, -while still causing that to happen, should not appear in it. Since -psymtabs don't have the idea of scope, you can't put local symbols in -them anyway. Psymtabs don't have the idea of the type of a symbol, -either, so types need not appear, unless they will be referenced by -name. +@table @code -It is a bug for GDB to behave one way when only a psymtab has been read, -and another way if the corresponding symtab has been read in. Such -bugs are typically caused by a psymtab that does not contain all the -visible symbols, or which has the wrong instruction address ranges. - -The psymtab for a particular section of a symbol-file (objfile) -could be thrown away after the symtab has been read in. The symtab -should always be searched before the psymtab, so the psymtab will -never be used (in a bug-free environment). Currently, -psymtabs are allocated on an obstack, and all the psymbols themselves -are allocated in a pair of large arrays on an obstack, so there is -little to be gained by trying to free them unless you want to do a lot -more work. - -@node Types -@chapter Types +@item GDBINIT_FILENAME +The default name of GDB's initialization file (normally @file{.gdbinit}). -Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). +@item MEM_FNS_DECLARED +Your host config file defines this if it includes declarations of +@code{memcpy} and @code{memset}. Define this to avoid conflicts between +the native include files and the declarations in @file{defs.h}. -These are the fundamental types that GDB uses internally. Fundamental -types from the various debugging formats (stabs, ELF, etc) are mapped into -one of these. They are basically a union of all fundamental types that -gdb knows about for all the languages that GDB knows about. +@item NO_SYS_FILE +Define this if your system does not have a @code{}. -Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). +@item SIGWINCH_HANDLER +If your host defines @code{SIGWINCH}, you can define this to be the name +of a function to be called if @code{SIGWINCH} is received. -Each time GDB builds an internal type, it marks it with one of these -types. The type may be a fundamental type, such as TYPE_CODE_INT, or -a derived type, such as TYPE_CODE_PTR which is a pointer to another -type. Typically, several FT_* types map to one TYPE_CODE_* type, and -are distinguished by other members of the type struct, such as whether -the type is signed or unsigned, and how many bits it uses. +@item SIGWINCH_HANDLER_BODY +Define this to expand into code that will define the function named by +the expansion of @code{SIGWINCH_HANDLER}. -Builtin Types (e.g., builtin_type_void, builtin_type_char). +@item ALIGN_STACK_ON_STARTUP +Define this if your system is of a sort that will crash in +@code{tgetent} if the stack happens not to be longword-aligned when +@code{main} is called. This is a rare situation, but is known to occur +on several different types of systems. -These are instances of type structs that roughly correspond to fundamental -types and are created as global types for GDB to use for various ugly -historical reasons. We eventually want to eliminate these. Note for -example that builtin_type_int initialized in gdbtypes.c is basically the -same as a TYPE_CODE_INT type that is initialized in c-lang.c for an -FT_INTEGER fundamental type. The difference is that the builtin_type is -not associated with any particular objfile, and only one instance exists, -while c-lang.c builds as many TYPE_CODE_INT types as needed, with each -one associated with some particular objfile. +@item CRLF_SOURCE_FILES +Define this if host files use @code{\r\n} rather than @code{\n} as a +line terminator. This will cause source file listings to omit @code{\r} +characters when printing and it will allow \r\n line endings of files +which are "sourced" by gdb. It must be possible to open files in binary +mode using @code{O_BINARY} or, for fopen, @code{"rb"}. -@node BFD support for GDB -@chapter Binary File Descriptor Library Support for GDB +@item DEFAULT_PROMPT +The default value of the prompt string (normally @code{"(gdb) "}). -BFD provides support for GDB in several ways: +@item DEV_TTY +The name of the generic TTY device, defaults to @code{"/dev/tty"}. -@table @emph -@item identifying executable and core files -BFD will identify a variety of file types, including a.out, coff, and -several variants thereof, as well as several kinds of core files. +@item FCLOSE_PROVIDED +Define this if the system declares @code{fclose} in the headers included +in @code{defs.h}. This isn't needed unless your compiler is unusually +anal. -@item access to sections of files -BFD parses the file headers to determine the names, virtual addresses, -sizes, and file locations of all the various named sections in files -(such as the text section or the data section). GDB simply calls -BFD to read or write section X at byte offset Y for length Z. +@item FOPEN_RB +Define this if binary files are opened the same way as text files. -@item specialized core file support -BFD provides routines to determine the failing command name stored -in a core file, the signal with which the program failed, and whether -a core file matches (i.e. could be a core dump of) a particular executable -file. +@item GETENV_PROVIDED +Define this if the system declares @code{getenv} in its headers included +in @code{defs.h}. This isn't needed unless your compiler is unusually +anal. -@item locating the symbol information -GDB uses an internal interface of BFD to determine where to find the -symbol information in an executable file or symbol-file. GDB itself -handles the reading of symbols, since BFD does not ``understand'' debug -symbols, but GDB uses BFD's cached information to find the symbols, -string table, etc. -@end table +@item HAVE_MMAP +In some cases, use the system call @code{mmap} for reading symbol +tables. For some machines this allows for sharing and quick updates. -@c The interface for symbol reading is described in @ref{Symbol -@c Reading,,Symbol Reading}. +@item HAVE_SIGSETMASK +Define this if the host system has job control, but does not define +@code{sigsetmask()}. Currently, this is only true of the RS/6000. +@item HAVE_TERMIO +Define this if the host system has @code{termio.h}. -@node Symbol Reading -@chapter Symbol Reading +@item HOST_BYTE_ORDER +The ordering of bytes in the host. This must be defined to be either +@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. -GDB reads symbols from "symbol files". The usual symbol file is the -file containing the program which GDB is debugging. GDB can be directed -to use a different file for symbols (with the ``symbol-file'' -command), and it can also read more symbols via the ``add-file'' and ``load'' -commands, or while reading symbols from shared libraries. +@item INT_MAX +@item INT_MIN +@item LONG_MAX +@item UINT_MAX +@item ULONG_MAX +Values for host-side constants. -Symbol files are initially opened by @file{symfile.c} using the BFD -library. BFD identifies the type of the file by examining its header. -@code{symfile_init} then uses this identification to locate a -set of symbol-reading functions. +@item ISATTY +Substitute for isatty, if not available. -Symbol reading modules identify themselves to GDB by calling -@code{add_symtab_fns} during their module initialization. The argument -to @code{add_symtab_fns} is a @code{struct sym_fns} which contains -the name (or name prefix) of the symbol format, the length of the prefix, -and pointers to four functions. These functions are called at various -times to process symbol-files whose identification matches the specified -prefix. +@item LONGEST +This is the longest integer type available on the host. If not defined, +it will default to @code{long long} or @code{long}, depending on +@code{CC_HAS_LONG_LONG}. -The functions supplied by each module are: +@item CC_HAS_LONG_LONG +Define this if the host C compiler supports ``long long''. This is set +by the configure script. -@table @code -@item @var{xxx}_symfile_init(struct sym_fns *sf) +@item PRINTF_HAS_LONG_LONG +Define this if the host can handle printing of long long integers via +the printf format directive ``ll''. This is set by the configure script. -Called from @code{symbol_file_add} when we are about to read a new -symbol file. This function should clean up any internal state -(possibly resulting from half-read previous files, for example) -and prepare to read a new symbol file. Note that the symbol file -which we are reading might be a new "main" symbol file, or might -be a secondary symbol file whose symbols are being added to the -existing symbol table. - -The argument to @code{@var{xxx}_symfile_init} is a newly allocated -@code{struct sym_fns} whose @code{bfd} field contains the BFD -for the new symbol file being read. Its @code{private} field -has been zeroed, and can be modified as desired. Typically, -a struct of private information will be @code{malloc}'d, and -a pointer to it will be placed in the @code{private} field. - -There is no result from @code{@var{xxx}_symfile_init}, but it can call -@code{error} if it detects an unavoidable problem. +@item HAVE_LONG_DOUBLE +Define this if the host C compiler supports ``long double''. This is +set by the configure script. -@item @var{xxx}_new_init() +@item PRINTF_HAS_LONG_DOUBLE +Define this if the host can handle printing of long double float-point +numbers via the printf format directive ``Lg''. This is set by the +configure script. -Called from @code{symbol_file_add} when discarding existing symbols. -This function need only handle -the symbol-reading module's internal state; the symbol table data -structures visible to the rest of GDB will be discarded by -@code{symbol_file_add}. It has no arguments and no result. -It may be called after @code{@var{xxx}_symfile_init}, if a new symbol -table is being read, or may be called alone if all symbols are -simply being discarded. +@item SCANF_HAS_LONG_DOUBLE +Define this if the host can handle the parsing of long double +float-point numbers via the scanf format directive directive +``Lg''. This is set by the configure script. -@item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) +@item LSEEK_NOT_LINEAR +Define this if @code{lseek (n)} does not necessarily move to byte number +@code{n} in the file. This is only used when reading source files. It +is normally faster to define @code{CRLF_SOURCE_FILES} when possible. -Called from @code{symbol_file_add} to actually read the symbols from a -symbol-file into a set of psymtabs or symtabs. +@item L_SET +This macro is used as the argument to lseek (or, most commonly, +bfd_seek). FIXME, should be replaced by SEEK_SET instead, which is the +POSIX equivalent. -@code{sf} points to the struct sym_fns originally passed to -@code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the -offset between the file's specified start address and its true address -in memory. @code{mainline} is 1 if this is the main symbol table being -read, and 0 if a secondary symbol file (e.g. shared library or -dynamically loaded file) is being read.@refill -@end table +@item MAINTENANCE_CMDS +If the value of this is 1, then a number of optional maintenance +commands are compiled in. -In addition, if a symbol-reading module creates psymtabs when -@var{xxx}_symfile_read is called, these psymtabs will contain a pointer to -a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from -any point in the GDB symbol-handling code. +@item MALLOC_INCOMPATIBLE +Define this if the system's prototype for @code{malloc} differs from the +@sc{ANSI} definition. -@table @code -@item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst) - -Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB -macro) if the psymtab has not already been read in and had its -@code{pst->symtab} pointer set. The argument is the psymtab -to be fleshed-out into a symtab. Upon return, pst->readin -should have been set to 1, and pst->symtab should contain a -pointer to the new corresponding symtab, or zero if there -were no symbols in that part of the symbol file. -@end table +@item MMAP_BASE_ADDRESS +When using HAVE_MMAP, the first mapping should go at this address. +@item MMAP_INCREMENT +when using HAVE_MMAP, this is the increment between mappings. -@node Cleanups -@chapter Cleanups +@item NEED_POSIX_SETPGID +Define this to use the POSIX version of @code{setpgid} to determine +whether job control is available. -Cleanups are a structured way to deal with things that need to be done -later. When your code does something (like @code{malloc} some memory, or open -a file) that needs to be undone later (e.g. free the memory or close -the file), it can make a cleanup. The cleanup will be done at some -future point: when the command is finished, when an error occurs, or -when your code decides it's time to do cleanups. +@item NORETURN +If defined, this should be one or more tokens, such as @code{volatile}, +that can be used in both the declaration and definition of functions to +indicate that they never return. The default is already set correctly +if compiling with GCC. This will almost never need to be defined. -You can also discard cleanups, that is, throw them away without doing -what they say. This is only done if you ask that it be done. +@item ATTR_NORETURN +If defined, this should be one or more tokens, such as +@code{__attribute__ ((noreturn))}, that can be used in the declarations +of functions to indicate that they never return. The default is already +set correctly if compiling with GCC. This will almost never need to be +defined. -Syntax: +@item USE_MMALLOC +GDB will use the @code{mmalloc} library for memory allocation for symbol +reading if this symbol is defined. Be careful defining it since there +are systems on which @code{mmalloc} does not work for some reason. One +example is the DECstation, where its RPC library can't cope with our +redefinition of @code{malloc} to call @code{mmalloc}. When defining +@code{USE_MMALLOC}, you will also have to set @code{MMALLOC} in the +Makefile, to point to the mmalloc library. This define is set when you +configure with --with-mmalloc. -@table @code -@item struct cleanup *@var{old_chain}; -Declare a variable which will hold a cleanup chain handle. +@item NO_MMCHECK +Define this if you are using @code{mmalloc}, but don't want the overhead +of checking the heap with @code{mmcheck}. Note that on some systems, +the C runtime makes calls to malloc prior to calling @code{main}, and if +@code{free} is ever called with these pointers after calling +@code{mmcheck} to enable checking, a memory corruption abort is certain +to occur. These systems can still use mmalloc, but must define +NO_MMCHECK. -@item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); -Make a cleanup which will cause @var{function} to be called with @var{arg} -(a @code{char *}) later. The result, @var{old_chain}, is a handle that can be -passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are -going to call @code{do_cleanups} or @code{discard_cleanups} yourself, -you can ignore the result from @code{make_cleanup}. +@item MMCHECK_FORCE +Define this to 1 if the C runtime allocates memory prior to +@code{mmcheck} being called, but that memory is never freed so we don't +have to worry about it triggering a memory corruption abort. The +default is 0, which means that @code{mmcheck} will only install the heap +checking functions if there has not yet been any memory allocation +calls, and if it fails to install the functions, gdb will issue a +warning. This is currently defined if you configure using +--with-mmalloc. +@item NO_SIGINTERRUPT +Define this to indicate that siginterrupt() is not available. -@item do_cleanups (@var{old_chain}); -Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}. -E.g.: -@example -make_cleanup (a, 0); -old = make_cleanup (b, 0); -do_cleanups (old); -@end example -@noindent -will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain -in the cleanup chain, and will be done later unless otherwise discarded.@refill +@item R_OK +Define if this is not in a system .h file. -@item discard_cleanups (@var{old_chain}); -Same as @code{do_cleanups} except that it just removes the cleanups from the -chain and does not call the specified functions. +@item SEEK_CUR +@item SEEK_SET +Define these to appropriate value for the system lseek(), if not already +defined. -@end table +@item STOP_SIGNAL +This is the signal for stopping GDB. Defaults to SIGTSTP. (Only +redefined for the Convex.) -Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they -``should not be called when cleanups are not in place''. This means -that any actions you need to reverse in the case of an error or -interruption must be on the cleanup chain before you call these functions, -since they might never return to your code (they @samp{longjmp} instead). +@item USE_O_NOCTTY +Define this if the interior's tty should be opened with the O_NOCTTY +flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is +always linked in.) +@item USG +Means that System V (prior to SVR4) include files are in use. (FIXME: +This symbol is abused in @file{infrun.c}, @file{regex.c}, +@file{remote-nindy.c}, and @file{utils.c} for other things, at the +moment.) -@node Wrapping -@chapter Wrapping Output Lines +@item lint +Define this to help placate lint in some situations. -Output that goes through @code{printf_filtered} or @code{fputs_filtered} or -@code{fputs_demangled} needs only to have calls to @code{wrap_here} added -in places that would be good breaking points. The utility routines -will take care of actually wrapping if the line width is exceeded. +@item volatile +Define this to override the defaults of @code{__volatile__} or +@code{/**/}. -The argument to @code{wrap_here} is an indentation string which is printed -@emph{only} if the line breaks there. This argument is saved away and used -later. It must remain valid until the next call to @code{wrap_here} or -until a newline has been printed through the @code{*_filtered} functions. -Don't pass in a local variable and then return! +@end table -It is usually best to call @code{wrap_here()} after printing a comma or space. -If you call it before printing a space, make sure that your indentation -properly accounts for the leading space that will print if the line wraps -there. -Any function or set of functions that produce filtered output must finish -by printing a newline, to flush the wrap buffer, before switching to -unfiltered (``@code{printf}'') output. Symbol reading routines that print -warnings are a good example. +@node Target Architecture Definition +@chapter Target Architecture Definition -@node Frames -@chapter Frames +GDB's target architecture defines what sort of machine-language programs +GDB can work with, and how it works with them. -A frame is a construct that GDB uses to keep track of calling and called -functions. +At present, the target architecture definition consists of a number of C +macros. -@table @code -@item FRAME_FP -in the machine description has no meaning to the machine-independent -part of GDB, except that it is used when setting up a new frame from -scratch, as follows: +@section Registers and Memory -@example - create_new_frame (read_register (FP_REGNUM), read_pc ())); -@end example +GDB's model of the target machine is rather simple. GDB assumes the +machine includes a bank of registers and a block of memory. Each +register may have a different size. -Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by -the machine-dependent code. So, @code{FP_REGNUM} can have any value that -is convenient for the code that creates new frames. (@code{create_new_frame} -calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should -use the @code{FP_REGNUM} value, if your frames are nonstandard.) - -@item FRAME_CHAIN -Given a GDB frame, determine the address of the calling function's -frame. This will be used to create a new GDB frame struct, and then -@code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for -the new frame. -@end table +GDB does not have a magical way to match up with the compiler's idea of +which registers are which; however, it is critical that they do match up +accurately. The only way to make this work is to get accurate +information about the order that the compiler uses, and to reflect that +in the @code{REGISTER_NAMES} and related macros. -@node Remote Stubs -@chapter Remote Stubs +GDB can handle big-endian, little-endian, and bi-endian architectures. -GDB's file @file{remote.c} talks a serial protocol to code that runs -in the target system. GDB provides several sample ``stubs'' that can -be integrated into target programs or operating systems for this purpose; -they are named @file{*-stub.c}. +@section Frame Interpretation -The GDB user's manual describes how to put such a stub into your target -code. What follows is a discussion of integrating the SPARC stub -into a complicated operating system (rather than a simple program), -by Stu Grossman, the author of this stub. +@section Inferior Call Setup -The trap handling code in the stub assumes the following upon entry to -trap_low: +@section Compiler Characteristics -@enumerate -@item %l1 and %l2 contain pc and npc respectively at the time of the trap -@item traps are disabled -@item you are in the correct trap window -@end enumerate +@section Target Conditionals -As long as your trap handler can guarantee those conditions, then there is no -reason why you shouldn't be able to `share' traps with the stub. The stub has -no requirement that it be jumped to directly from the hardware trap vector. -That is why it calls @code{exceptionHandler()}, which is provided by the external -environment. For instance, this could setup the hardware traps to actually -execute code which calls the stub first, and then transfers to its own trap -handler. +This section describes the macros that you can use to define the target +machine. -For the most point, there probably won't be much of an issue with `sharing' -traps, as the traps we use are usually not used by the kernel, and often -indicate unrecoverable error conditions. Anyway, this is all controlled by a -table, and is trivial to modify. -The most important trap for us is for @code{ta 1}. Without that, we -can't single step or do breakpoints. Everything else is unnecessary -for the proper operation of the debugger/stub. +@table @code -From reading the stub, it's probably not obvious how breakpoints work. They -are simply done by deposit/examine operations from GDB. +@item ADDITIONAL_OPTIONS +@item ADDITIONAL_OPTION_CASES +@item ADDITIONAL_OPTION_HANDLER +@item ADDITIONAL_OPTION_HELP +These are a set of macros that allow the addition of additional command +line options to GDB. They are currently used only for the unsupported +i960 Nindy target, and should not be used in any other configuration. -@node Longjmp Support -@chapter Longjmp Support +@item ADDR_BITS_REMOVE (addr) +If a raw machine address includes any bits that are not really part of +the address, then define this macro to expand into an expression that +zeros those bits in @var{addr}. For example, the two low-order bits of +a Motorola 88K address may be used by some kernels for their own +purposes, since addresses must always be 4-byte aligned, and so are of +no use for addressing. Those bits should be filtered out with an +expression such as @code{((addr) & ~3)}. -GDB has support for figuring out that the target is doing a -@code{longjmp} and for stopping at the target of the jump, if we are -stepping. This is done with a few specialized internal breakpoints, -which are visible in the @code{maint info breakpoint} command. +@item BEFORE_MAIN_LOOP_HOOK +Define this to expand into any code that you want to execute before the +main loop starts. Although this is not, strictly speaking, a target +conditional, that is how it is currently being used. Note that if a +configuration were to define it one way for a host and a different way +for the target, GDB will probably not compile, let alone run correctly. +This is currently used only for the unsupported i960 Nindy target, and +should not be used in any other configuration. -To make this work, you need to define a macro called -@code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf} -structure and extract the longjmp target address. Since @code{jmp_buf} -is target specific, you will need to define it in the appropriate -@file{tm-xxx.h} file. Look in @file{tm-sun4os4.h} and -@file{sparc-tdep.c} for examples of how to do this. +@item BELIEVE_PCC_PROMOTION +Define if the compiler promotes a short or char parameter to an int, but +still reports the parameter as its original type, rather than the +promoted type. -@node Coding Style -@chapter Coding Style +@item BELIEVE_PCC_PROMOTION_TYPE +Define this if GDB should believe the type of a short argument when +compiled by pcc, but look within a full int space to get its value. +Only defined for Sun-3 at present. -GDB is generally written using the GNU coding standards, as described in -@file{standards.texi}, which is available for anonymous FTP from GNU -archive sites. There are some additional considerations for GDB -maintainers that reflect the unique environment and style of GDB -maintenance. If you follow these guidelines, GDB will be more -consistent and easier to maintain. +@item BITS_BIG_ENDIAN +Define this if the numbering of bits in the targets does *not* match the +endianness of the target byte order. A value of 1 means that the bits +are numbered in a big-endian order, 0 means little-endian. -GDB's policy on the use of prototypes is that prototypes are used -to @emph{declare} functions but never to @emph{define} them. Simple -macros are used in the declarations, so that a non-ANSI compiler can -compile GDB without trouble. The simple macro calls are used like -this: +@item BREAKPOINT +This is the character array initializer for the bit pattern to put into +memory where a breakpoint is set. Although it's common to use a trap +instruction for a breakpoint, it's not required; for instance, the bit +pattern could be an invalid instruction. The breakpoint must be no +longer than the shortest instruction of the architecture. -@example @code -extern int -memory_remove_breakpoint PARAMS ((CORE_ADDR, char *)); -@end example +@item BIG_BREAKPOINT +@item LITTLE_BREAKPOINT +Similar to BREAKPOINT, but used for bi-endian targets. -Note the double parentheses around the parameter types. This allows -an arbitrary number of parameters to be described, without freaking -out the C preprocessor. When the function has no parameters, it -should be described like: +@item CALL_DUMMY +valops.c +@item CALL_DUMMY_LOCATION +inferior.h +@item CALL_DUMMY_STACK_ADJUST +valops.c -@example @code -void -noprocess PARAMS ((void)); -@end example +@item CANNOT_FETCH_REGISTER (regno) +A C expression that should be nonzero if @var{regno} cannot be fetched +from an inferior process. This is only relevant if +@code{FETCH_INFERIOR_REGISTERS} is not defined. -The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple -@code{()} in traditional C. +@item CANNOT_STORE_REGISTER (regno) +A C expression that should be nonzero if @var{regno} should not be +written to the target. This is often the case for program counters, +status words, and other special registers. If this is not defined, GDB +will assume that all registers may be written. -All external functions should have a @code{PARAMS} declaration in a -header file that callers include. All static functions should have such -a declaration near the top of their source file. +@item CHILL_PRODUCER +@item GCC_PRODUCER +@item GPLUS_PRODUCER +@item LCC_PRODUCER +If defined, these are the producer strings in a DWARF 1 file. All of +these have reasonable defaults already. -We don't have a gcc option that will properly check that these rules -have been followed, but it's GDB policy, and we periodically check it -using the tools available (plus manual labor), and clean up any remnants. +@item DO_DEFERRED_STORES +@item CLEAR_DEFERRED_STORES +Define this to execute any deferred stores of registers into the inferior, +and to cancel any deferred stores. -@node Clean Design -@chapter Clean Design +Currently only implemented correctly for native Sparc configurations? -In addition to getting the syntax right, there's the little question of -semantics. Some things are done in certain ways in GDB because long -experience has shown that the more obvious ways caused various kinds of -trouble. In particular: +@item CPLUS_MARKER +Define this to expand into the character that G++ uses to distinguish +compiler-generated identifiers from programmer-specified identifiers. +By default, this expands into @code{'$'}. Most System V targets should +define this to @code{'.'}. -@table @bullet -@item -You can't assume the byte order of anything that comes from a -target (including @var{value}s, object files, and instructions). Such -things must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB, -or one of the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}. +@item DBX_PARM_SYMBOL_CLASS +Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol +information. In the i960, parameters can be stored as locals or as +args, depending on the type of the debug record. -@item -You can't assume that you know what interface is being used to talk to -the target system. All references to the target must go through the -current @code{target_ops} vector. +@item DECR_PC_AFTER_BREAK +Define this to be the amount by which to decrement the PC after the +program encounters a breakpoint. This is often the number of bytes in +BREAKPOINT, though not always. For most targets this value will be 0. -@item -You can't assume that the host and target machines are the same machine -(except in the ``native'' support modules). -In particular, you can't assume that the target machine's header files -will be available on the host machine. Target code must bring along its -own header files -- written from scratch or explicitly donated by their -owner, to avoid copyright problems. +@item DECR_PC_AFTER_HW_BREAK +Similarly, for hardware breakpoints. -@item -Insertion of new @code{#ifdef}'s will be frowned upon. It's much better -to write the code portably than to conditionalize it for various systems. +@item DISABLE_UNSETTABLE_BREAK addr +If defined, this should evaluate to 1 if @var{addr} is in a shared +library in which breakpoints cannot be set and so should be disabled. -@item -New @code{#ifdef}'s which test for specific compilers or manufacturers -or operating systems are unacceptable. All @code{#ifdef}'s should test -for features. The information about which configurations contain which -features should be segregated into the configuration files. Experience -has proven far too often that a feature unique to one particular system -often creeps into other systems; and that a conditional based on -some predefined macro for your current system will become worthless -over time, as new versions of your system come out that behave differently -with regard to this feature. +@item DO_REGISTERS_INFO +If defined, use this to print the value of a register or all registers. -@item -Adding code that handles specific architectures, operating systems, target -interfaces, or hosts, is not acceptable in generic code. If a hook -is needed at that point, invent a generic hook and define it for your -configuration, with something like: +@item END_OF_TEXT_DEFAULT +This is an expression that should designate the end of the text section +(? FIXME ?) -@example -#ifdef WRANGLE_SIGNALS - WRANGLE_SIGNALS (signo); -#endif -@end example +@item EXTRACT_RETURN_VALUE(type,regbuf,valbuf) +Define this to extract a function's return value of type @var{type} from +the raw register state @var{regbuf} and copy that, in virtual format, +into @var{valbuf}. + +@item EXTRACT_STRUCT_VALUE_ADDRESS(regbuf) +Define this to extract from an array @var{regbuf} containing the (raw) +register state, the address in which a function should return its +structure value, as a CORE_ADDR (or an expression that can be used as +one). -In your host, target, or native configuration file, as appropriate, -define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take -a bit of care in defining the hook, so that it can be used by other -ports in the future, if they need a hook in the same place. +@item EXTRA_FRAME_INFO +If defined, this must be a list of slots that may be inserted into the +@code{frame_info} structure defined in @code{frame.h}. -If the hook is not defined, the code should do whatever "most" machines -want. Using @code{#ifdef}, as above, is the preferred way to do this, -but sometimes that gets convoluted, in which case use +@item FLOAT_INFO +If defined, then the `info float' command will print information about +the processor's floating point unit. -@example -#ifndef SPECIAL_FOO_HANDLING -#define SPECIAL_FOO_HANDLING(pc, sp) (0) -#endif -@end example +@item FP_REGNUM +The number of the frame pointer register. -where the macro is used or in an appropriate header file. +@item FRAMELESS_FUNCTION_INVOCATION(fi, frameless) +Define this to set the variable @var{frameless} to 1 if the function +invocation represented by @var{fi} does not have a stack frame +associated with it. Otherwise set it to 0. -Whether to include a @dfn{small} hook, a hook around the exact pieces of -code which are system-dependent, or whether to replace a whole function -with a hook depends on the case. A good example of this dilemma can be -found in @code{get_saved_register}. All machines that GDB 2.8 ran on -just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved -registers. Then the SPARC and Pyramid came along, and -@code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were -introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER} -hook. The first three are examples of small hooks; the latter replaces -a whole function. In this specific case, it is useful to have both -kinds; it would be a bad idea to replace all the uses of the small hooks -with @code{GET_SAVED_REGISTER}, since that would result in much -duplicated code. Other times, duplicating a few lines of code here or -there is much cleaner than introducing a large number of small hooks. +@item FRAME_ARGS_ADDRESS_CORRECT +stack.c -Another way to generalize GDB along a particular interface is with an -attribute struct. For example, GDB has been generalized to handle -multiple kinds of remote interfaces -- not by #ifdef's everywhere, but -by defining the "target_ops" structure and having a current target (as -well as a stack of targets below it, for memory references). Whenever -something needs to be done that depends on which remote interface we are -using, a flag in the current target_ops structure is tested (e.g. -`target_has_stack'), or a function is called through a pointer in the -current target_ops structure. In this way, when a new remote interface -is added, only one module needs to be touched -- the one that actually -implements the new remote interface. Other examples of -attribute-structs are BFD access to multiple kinds of object file -formats, or GDB's access to multiple source languages. +@item FRAME_CHAIN(frame) +Given @var{frame}, return a pointer to the calling frame. -Please avoid duplicating code. For example, in GDB 3.x all the code -interfacing between @code{ptrace} and the rest of GDB was duplicated in -@file{*-dep.c}, and so changing something was very painful. In GDB 4.x, -these have all been consolidated into @file{infptrace.c}. -@file{infptrace.c} can deal with variations between systems the same way -any system-independent file would (hooks, #if defined, etc.), and -machines which are radically different don't need to use infptrace.c at -all. +@item FRAME_CHAIN_COMBINE(chain,frame) +Define this to take the frame chain pointer and the frame's nominal +address and produce the nominal address of the caller's frame. +Presently only defined for HP PA. -@item -@emph{Do} write code that doesn't depend on the sizes of C data types, -the format of the host's floating point numbers, the alignment of anything, -or the order of evaluation of expressions. In short, follow good -programming practices for writing portable C code. +@item FRAME_CHAIN_VALID(chain,thisframe) +Define this to be an expression that returns zero if the given frame is +an outermost frame, with no caller, and nonzero otherwise. The default +definition is nonzero if the chain pointer is nonzero and given frame's +PC is not inside the startup file (such as @file{crt0.o}). The +alternate default definition (which is used if +FRAME_CHAIN_VALID_ALTERNATE is defined) is nonzero if the chain pointer +is nonzero and the given frame's PC is not in @code{main()} or a known +entry point function (such as @code{_start()}). -@end table +@item FRAME_CHAIN_VALID_ALTERNATE +Define this in order to use the alternate default definition of +@code{FRAME_CHAIN_VALID}. -@node Submitting Patches -@chapter Submitting Patches +@item FRAME_FIND_SAVED_REGS +stack.c -Thanks for thinking of offering your changes back to the community of -GDB users. In general we like to get well designed enhancements. -Thanks also for checking in advance about the best way to transfer the -changes. +@item FRAME_NUM_ARGS (val, fi) +For the frame described by @var{fi}, set @var{val} to the number of arguments +that are being passed. -The two main problems with getting your patches in are, +@item FRAME_SAVED_PC(frame) +Given @var{frame}, return the pc saved there. That is, the return +address. -@table @bullet -@item -The GDB maintainers will only install ``cleanly designed'' patches. -You may not always agree on what is clean design. -@pxref{Coding Style}, @pxref{Clean Design}. +@item FUNCTION_EPILOGUE_SIZE +For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the +function end symbol is 0. For such targets, you must define +@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a +function's epilogue. -@item -If the maintainers don't have time to put the patch in when it -arrives, or if there is any question about a patch, it -goes into a large queue with everyone else's patches and -bug reports. -@end table +@item GCC_COMPILED_FLAG_SYMBOL +@item GCC2_COMPILED_FLAG_SYMBOL +If defined, these are the names of the symbols that GDB will look for to +detect that GCC compiled the file. The default symbols are +@code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently +only defined for the Delta 68.) -I don't know how to get past these problems except by continuing to try. +@item GDB_TARGET_IS_HPPA +This determines whether horrible kludge code in dbxread.c and +partial-stab.h is used to mangle multiple-symbol-table files from +HPPA's. This should all be ripped out, and a scheme like elfread.c +used. -There are two issues here -- technical and legal. +@item GDB_TARGET_IS_MACH386 +@item GDB_TARGET_IS_SUN3 +@item GDB_TARGET_IS_SUN386 +Kludges that should go away. -The legal issue is that to incorporate substantial changes requires a -copyright assignment from you and/or your employer, granting ownership -of the changes to the Free Software Foundation. You can get the -standard document for doing this by sending mail to -@code{gnu@@prep.ai.mit.edu} and asking for it. I recommend that people -write in "All programs owned by the Free Software Foundation" as "NAME -OF PROGRAM", so that changes in many programs (not just GDB, but GAS, -Emacs, GCC, etc) can be contributed with only one piece of legalese -pushed through the bureacracy and filed with the FSF. I can't start -merging changes until this paperwork is received by the FSF (their -rules, which I follow since I maintain it for them). +@item GET_LONGJMP_TARGET +For most machines, this is a target-dependent parameter. On the +DECstation and the Iris, this is a native-dependent parameter, since + is needed to define it. -Technically, the easiest way to receive changes is to receive each -feature as a small context diff or unidiff, suitable for "patch". -Each message sent to me should include the changes to C code and -header files for a single feature, plus ChangeLog entries for each -directory where files were modified, and diffs for any changes needed -to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there -are a lot of changes for a single feature, they can be split down -into multiple messages. +This macro determines the target PC address that longjmp() will jump to, +assuming that we have just stopped at a longjmp breakpoint. It takes a +CORE_ADDR * as argument, and stores the target PC value through this +pointer. It examines the current state of the machine as needed. -In this way, if I read and like the feature, I can add it to the -sources with a single patch command, do some testing, and check it in. -If you leave out the ChangeLog, I have to write one. If you leave -out the doc, I have to puzzle out what needs documenting. Etc. +@item GET_SAVED_REGISTER +Define this if you need to supply your own definition for the function +@code{get_saved_register}. Currently this is only done for the a29k. -The reason to send each change in a separate message is that I will -not install some of the changes. They'll be returned to you with -questions or comments. If I'm doing my job, my message back to you -will say what you have to fix in order to make the change acceptable. -The reason to have separate messages for separate features is so -that other changes (which I @emph{am} willing to accept) can be installed -while one or more changes are being reworked. If multiple features -are sent in a single message, I tend to not put in the effort to sort -out the acceptable changes from the unacceptable, so none of the -features get installed until all are acceptable. +@item HAVE_REGISTER_WINDOWS +Define this if the target has register windows. +@item REGISTER_IN_WINDOW_P (regnum) +Define this to be an expression that is 1 if the given register is in +the window. -If this sounds painful or authoritarian, well, it is. But I get a lot -of bug reports and a lot of patches, and most of them don't get -installed because I don't have the time to finish the job that the bug -reporter or the contributor could have done. Patches that arrive -complete, working, and well designed, tend to get installed on the day -they arrive. The others go into a queue and get installed if and when -I scan back over the queue -- which can literally take months -sometimes. It's in both our interests to make patch installation easy --- you get your changes installed, and I make some forward progress on -GDB in a normal 12-hour day (instead of them having to wait until I -have a 14-hour or 16-hour day to spend cleaning up patches before I -can install them). +@item IBM6000_TARGET +Shows that we are configured for an IBM RS/6000 target. This +conditional should be eliminated (FIXME) and replaced by +feature-specific macros. It was introduced in haste and we are +repenting at leisure. -Please send patches to @code{bug-gdb@@prep.ai.mit.edu}, if they are less -than about 25,000 characters. If longer than that, either make them -available somehow (e.g. anonymous FTP), and announce it on -@code{bug-gdb}, or send them directly to the GDB maintainers at -@code{gdb-patches@@cygnus.com}. +@item IEEE_FLOAT +Define this if the target system uses IEEE-format floating point numbers. -@node Host Conditionals -@chapter Host Conditionals +@item INIT_EXTRA_FRAME_INFO (fromleaf, fci) +If defined, this should be a C expression or statement that fills in the +@code{EXTRA_FRAME_INFO} slots of the given frame @var{fci}. -When GDB is configured and compiled, various macros are defined or left -undefined, to control compilation based on the attributes of the host -system. These macros and their meanings (or if the meaning is not -documented here, then one of the source files where they are used is -indicated) are: +@item INIT_FRAME_PC (fromleaf, prev) +This is a C statement that sets the pc of the frame pointed to by +@var{prev}. [By default...] -@emph{NOTE: For now, both host and target conditionals are here. -Eliminate target conditionals from this list as they are identified.} +@item INNER_THAN +Define this to be either @code{<} if the target's stack grows downward +in memory, or @code{>} is the stack grows upwards. -@table @code +@item IN_SIGTRAMP (pc, name) +Define this to return true if the given @var{pc} and/or @var{name} +indicates that the current function is a sigtramp. -@item BLOCK_ADDRESS_FUNCTION_RELATIVE -dbxread.c +@item SIGTRAMP_START (pc) +@item SIGTRAMP_END (pc) +Define these to be the start and end address of the sigtramp for the +given @var{pc}. On machines where the address is just a compile time +constant, the macro expansion will typically just ignore the supplied +@var{pc}. -@item GDBINIT_FILENAME -The default name of GDB's initialization file (normally @file{.gdbinit}). - -@item MEM_FNS_DECLARED -Your host config file defines this if it includes -declarations of @code{memcpy} and @code{memset}. Define this -to avoid conflicts between the native include -files and the declarations in @file{defs.h}. +@item IN_SOLIB_TRAMPOLINE pc name +Define this to evaluate to nonzero if the program is stopped in the +trampoline that connects to a shared library. -@item NO_SYS_FILE -Define this if your system does not have a @code{}. +@item IS_TRAPPED_INTERNALVAR (name) +This is an ugly hook to allow the specification of special actions that +should occur as a side-effect of setting the value of a variable +internal to GDB. Currently only used by the h8500. Note that this +could be either a host or target conditional. -@item SIGWINCH_HANDLER -If your host defines @code{SIGWINCH}, you can define this to -be the name of a function to be called if @code{SIGWINCH} is received. +@item KERNEL_DEBUGGING +tm-ultra3.h -@item SIGWINCH_HANDLER_BODY -Define this to expand into code that will define the function -named by the expansion of @code{SIGWINCH_HANDLER}. +@item MIPSEL +mips-tdep.c -@item ADDITIONAL_OPTIONS -main.c -@item ADDITIONAL_OPTION_CASES -main.c -@item ADDITIONAL_OPTION_HANDLER -main.c -@item ADDITIONAL_OPTION_HELP -main.c +@item NEED_TEXT_START_END +Define this if GDB should determine the start and end addresses of the +text section. (Seems dubious.) -@item AIX_BUGGY_PTRACE_CONTINUE -infptrace.c +@item NO_HIF_SUPPORT +(Specific to the a29k.) -@item ALIGN_STACK_ON_STARTUP -Define this if your system is of a sort that will crash in @code{tgetent} -if the stack happens not to be longword-aligned when @code{main} is -called. This is a rare situation, but is known to occur on several -different types of systems. +@item NO_SINGLE_STEP +Define this if the target does not support single-stepping. If this is +defined, you must supply, in @code{*-tdep.c}, the function +@code{single_step}, which takes a target_signal as argument and returns +nothing. It must insert breakpoints at each possible destinations of +the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c} +for examples. -@item CFRONT_PRODUCER -dwarfread.c +@item PCC_SOL_BROKEN +(Used only in the Convex target.) -@item CRLF_SOURCE_FILES -Define this if host files use @code{\r\n} rather than @code{\n} as a -line terminator. This will cause source file listings to omit @code{\r} -characters when printing. It must be possible to open files in binary -mode using @code{O_BINARY} or, for fopen, @code{"rb"}. +@item PC_IN_CALL_DUMMY +inferior.h -@item DBX_PARM_SYMBOL_CLASS -stabsread.c +@item PC_LOAD_SEGMENT +If defined, print information about the load segment for the program +counter. (Defined only for the RS/6000.) -@item DEFAULT_PROMPT -The default value of the prompt string (normally @code{"(gdb) "}). +@item PC_REGNUM +If the program counter is kept in a register, then define this macro to +be the number of that register. This need be defined only if +@code{TARGET_WRITE_PC} is not defined. -@item DEV_TTY -symmisc.c -@item DO_REGISTERS_INFO -infcmd.c +@item NPC_REGNUM +The number of the ``next program counter'' register, if defined. -@item FCLOSE_PROVIDED -Define this if the system declares @code{fclose} in the headers included in -@code{defs.h}. This isn't needed unless your compiler is unusually anal. +@item NNPC_REGNUM +The number of the ``next next program counter'' register, if defined. +Currently, this is only defined for the Motorola 88K. -@sc{ANSI} definition. +@item PRINT_REGISTER_HOOK (regno) +If defined, this must be a function that prints the contents of the +given register to standard output. -@item FILES_INFO_HOOK -target.c -@item FLOAT_INFO -infcmd.c +@item PRINT_TYPELESS_INTEGER +This is an obscure substitute for @code{print_longest} that seems to +have been defined for the Convex target. -@item FOPEN_RB -Define this if binary files are opened the same way as text files. +@item PROCESS_LINENUMBER_HOOK +A hook defined for XCOFF reading. -@item GCC2_COMPILED_FLAG_SYMBOL -dbxread.c -@item GCC_COMPILED_FLAG_SYMBOL -dbxread.c -@item GCC_MANGLE_BUG -symtab.c -@item GCC_PRODUCER -dwarfread.c +@item PROLOGUE_FIRSTLINE_OVERLAP +(Only used in unsupported Convex configuration.) -@item GETENV_PROVIDED -Define this if the system declares @code{getenv} in its headers included in -@code{defs.h}. This isn't needed unless your compiler is unusually anal. +@item PS_REGNUM +If defined, this is the number of the processor status register. (This +definition is only used in generic code when parsing "$ps".) -@item GPLUS_PRODUCER -dwarfread.c +@item POP_FRAME +Used in @samp{call_function_by_hand} to remove an artificial stack +frame. -@item HAVE_MMAP -In some cases, use the system call @code{mmap} for reading symbol -tables. For some machines this allows for sharing and quick updates. +@item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr) +Define this to push arguments onto the stack for inferior function call. -@item HAVE_SIGSETMASK -Define this if the host system has job control, but does not -define @code{sigsetmask()}. -Currently, this is only true of the RS/6000. +@item PUSH_DUMMY_FRAME +Used in @samp{call_function_by_hand} to create an artificial stack frame. -@item HAVE_TERMIO -inflow.c +@item REGISTER_BYTES +The total amount of space needed to store GDB's copy of the machine's +register state. -@item HOST_BYTE_ORDER -The ordering of bytes in the host. -This must be defined to be either @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. +@item REGISTER_NAMES +Define this to expand into an initializer of an array of strings. Each +string is the name of a register. -@item INT_MAX -@item INT_MIN -@item LONG_MAX -@item UINT_MAX -@item ULONG_MAX -Values for host-side constants. +@item REG_STRUCT_HAS_ADDR (gcc_p, type) +Define this to return 1 if the given type will be passed by pointer +rather than directly. -@item ISATTY -Substitute for isatty, if not available. +@item SDB_REG_TO_REGNUM +Define this to convert sdb register numbers into GDB regnums. If not +defined, no conversion will be done. -@item KERNEL_DEBUGGING -tm-ultra3.h +@item SHIFT_INST_REGS +(Only used for m88k targets.) -@item KERNEL_U_ADDR -Define this to the address of the @code{u} structure (the ``user struct'', -also known as the ``u-page'') in kernel virtual memory. GDB needs to know -this so that it can subtract this address from absolute addresses in -the upage, that are obtained via ptrace or from core files. On systems -that don't need this value, set it to zero. +@item SKIP_PROLOGUE (pc) +A C statement that advances the @var{pc} across any function entry +prologue instructions so as to reach ``real'' code. -@item KERNEL_U_ADDR_BSD -Define this to cause GDB to determine the address of @code{u} at runtime, -by using Berkeley-style @code{nlist} on the kernel's image in the root -directory. +@item SKIP_PROLOGUE_FRAMELESS_P +A C statement that should behave similarly, but that can stop as soon as +the function is known to have a frame. If not defined, +@code{SKIP_PROLOGUE} will be used instead. -@item KERNEL_U_ADDR_HPUX -Define this to cause GDB to determine the address of @code{u} at runtime, -by using HP-style @code{nlist} on the kernel's image in the root -directory. +@item SKIP_TRAMPOLINE_CODE (pc) +If the target machine has trampoline code that sits between callers and +the functions being called, then define this macro to return a new PC +that is at the start of the real function. -@item LCC_PRODUCER -dwarfread.c +@item SP_REGNUM +Define this to be the number of the register that serves as the stack +pointer. -@item LONGEST -This is the longest integer type available on the host. -If not defined, it will default to @code{long long} or @code{long}, -depending on @code{CC_HAS_LONG_LONG}. +@item STAB_REG_TO_REGNUM +Define this to convert stab register numbers (as gotten from `r' +declarations) into GDB regnums. If not defined, no conversion will be +done. -@item CC_HAS_LONG_LONG -Define this if the host C compiler supports ``long long''. -This is set by the configure script. +@item STACK_ALIGN (addr) +Define this to adjust the address to the alignment required for the +processor's stack. -@item PRINTF_HAS_LONG_LONG -Define this if the host can handle printing of long long integers via -the printf format directive ``ll''. This is set by the configure script. +@item STEP_SKIPS_DELAY (addr) +Define this to return true if the address is of an instruction with a +delay slot. If a breakpoint has been placed in the instruction's delay +slot, GDB will single-step over that instruction before resuming +normally. Currently only defined for the Mips. -@item HAVE_LONG_DOUBLE -Define this if the host C compiler supports ``long double''. -This is set by the configure script. +@item STORE_RETURN_VALUE (type, valbuf) +A C expression that stores a function return value of type @var{type}, +where @var{valbuf} is the address of the value to be stored. -@item PRINTF_HAS_LONG_DOUBLE -Define this if the host can handle printing of long double float-point -numbers via the printf format directive ``Lg''. This is set by the -configure script. +@item SUN_FIXED_LBRAC_BUG +(Used only for Sun-3 and Sun-4 targets.) -@item SCANF_HAS_LONG_DOUBLE -Define this if the host can handle the parsing of long double -float-point numbers via the scanf format directive directive -``Lg''. This is set by the configure script. +@item SYMBOL_RELOADING_DEFAULT +The default value of the `symbol-reloading' variable. (Never defined in +current sources.) -@item LSEEK_NOT_LINEAR -Define this if @code{lseek (n)} does not necessarily move to byte number -@code{n} in the file. This is only used when reading source files. It -is normally faster to define @code{CRLF_SOURCE_FILES} when possible. +@item TARGET_BYTE_ORDER +The ordering of bytes in the target. This must be defined to be either +@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. -@item L_LNNO32 -coffread.c +@item TARGET_CHAR_BIT +Number of bits in a char; defaults to 8. -@item L_SET -This macro is used as the argument to lseek (or, most commonly, bfd_seek). -FIXME, should be replaced by SEEK_SET instead, which is the POSIX equivalent. +@item TARGET_COMPLEX_BIT +Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. -@item MAINTENANCE_CMDS -If the value of this is 1, then a number of optional maintenance commands -are compiled in. +@item TARGET_DOUBLE_BIT +Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. -@item MALLOC_INCOMPATIBLE -Define this if the system's prototype for @code{malloc} differs from the -@sc{ANSI} definition. +@item TARGET_DOUBLE_COMPLEX_BIT +Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. -@item MMAP_BASE_ADDRESS -When using HAVE_MMAP, the first mapping should go at this address. +@item TARGET_FLOAT_BIT +Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. -@item MMAP_INCREMENT -when using HAVE_MMAP, this is the increment between mappings. +@item TARGET_INT_BIT +Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. -@item NEED_POSIX_SETPGID -Define this to use the POSIX version of @code{setpgid} to determine -whether job control is available. +@item TARGET_LONG_BIT +Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. -@item NORETURN -If defined, this should be one or more tokens, such as @code{volatile}, -that can be used in both the declaration and definition of functions -to indicate that they never return. The default is already set -correctly if compiling with GCC. -This will almost never need to be defined. +@item TARGET_LONG_DOUBLE_BIT +Number of bits in a long double float; +defaults to @code{2 * TARGET_DOUBLE_BIT}. -@item ATTR_NORETURN -If defined, this should be one or more tokens, such as -@code{__attribute__ ((noreturn))}, that can be used in the declarations -of functions to indicate that they never return. The default is already -set correctly if compiling with GCC. -This will almost never need to be defined. +@item TARGET_LONG_LONG_BIT +Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. -@item NOTICE_SIGNAL_HANDLING_CHANGE -infrun.c -@item NO_HIF_SUPPORT -remote-mm.c -@item NO_JOB_CONTROL -signals.h +@item TARGET_PTR_BIT +Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. -@item USE_MMALLOC -GDB will use the @code{mmalloc} library for memory allocation for symbol -reading if this symbol is defined. Be careful defining it since there -are systems on which @code{mmalloc} does not -work for some reason. One example is the DECstation, where its RPC -library can't cope with our redefinition of @code{malloc} to call -@code{mmalloc}. When defining @code{USE_MMALLOC}, you will also have -to set @code{MMALLOC} in the Makefile, to point to the mmalloc library. -This define is set when you configure with --with-mmalloc. +@item TARGET_SHORT_BIT +Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. -@item NO_MMCHECK -Define this if you are using @code{mmalloc}, but don't want the overhead -of checking the heap with @code{mmcheck}. Note that on some systems, -the C runtime makes calls to malloc prior to calling @code{main}, and if -@code{free} is ever called with these pointers after calling @code{mmcheck} -to enable checking, a memory corruption abort is certain to occur. These -systems can still use mmalloc, but must define NO_MMCHECK. +@item TARGET_READ_PC +@item TARGET_WRITE_PC (val, pid) +@item TARGET_READ_SP +@item TARGET_WRITE_SP +@item TARGET_READ_FP +@item TARGET_WRITE_FP +These change the behavior of @code{read_pc}, @code{write_pc}, +@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}. +For most targets, these may be left undefined. GDB will call the read +and write register functions with the relevant @code{_REGNUM} argument. -@item MMCHECK_FORCE -Define this to 1 if the C runtime allocates memory prior to @code{mmcheck} -being called, but that memory is never freed so we don't have to worry -about it triggering a memory corruption abort. The default is 0, which -means that @code{mmcheck} will only install the heap checking functions -if there has not yet been any memory allocation calls, and if it fails -to install the functions, gdb will issue a warning. This is currently -defined if you configure using --with-mmalloc. +These macros are useful when a target keeps one of these registers in a +hard to get at place; for example, part in a segment register and part +in an ordinary register. -@item NO_SIGINTERRUPT -remote-adapt.c -@item NUMERIC_REG_NAMES -mips-tdep.c -@item N_SETV -dbxread.c -@item N_SET_MAGIC -hppabsd-tdep.c -@item ONE_PROCESS_WRITETEXT -breakpoint.c -@item O_BINARY -exec.c -@item O_RDONLY -xm-ultra3.h -@item PCC_SOL_BROKEN -dbxread.c -@item PC_LOAD_SEGMENT -stack.c -@item PRINT_RANDOM_SIGNAL -infcmd.c -@item PRINT_REGISTER_HOOK -infcmd.c -@item PROCESS_LINENUMBER_HOOK -buildsym.c -@item PROLOGUE_FIRSTLINE_OVERLAP -infrun.c -@item PUSH_ARGUMENTS -valops.c -@item PYRAMID_CONTROL_FRAME_DEBUGGING -pyr-xdep.c -@item PYRAMID_CORE -pyr-xdep.c -@item PYRAMID_PTRACE -pyr-xdep.c -@item REGISTER_BYTES -remote.c -@item REG_STACK_SEGMENT -exec.c -@item REG_STRUCT_HAS_ADDR -findvar.c -@item R_FP -dwarfread.c -@item R_OK -xm-altos.h -@item SEEK_END -state.c -@item SEEK_SET -state.c -@item SEM -coffread.c +@item USE_STRUCT_CONVENTION (gcc_p, type) +If defined, this must be an expression that is nonzero if a value of the +given @var{type} being returned from a function must have space +allocated for it on the stack. @var{gcc_p} is true if the function +being considered is known to have been compiled by GCC; this is helpful +for systems where GCC is known to use different calling convention than +other compilers. -@item SHELL_COMMAND_CONCAT -infrun.c -@item SHELL_FILE -infrun.c -@item SHIFT_INST_REGS -breakpoint.c -@item SIGTRAP_STOP_AFTER_LOAD -infrun.c -@item STACK_ALIGN -valops.c -@item STOP_SIGNAL -main.c -@item SUN4_COMPILER_FEATURE -infrun.c -@item SUN_FIXED_LBRAC_BUG -dbxread.c -@item SVR4_SHARED_LIBS -solib.c -@item SYMBOL_RELOADING_DEFAULT -symfile.c -@item TIOCGETC -inflow.c -@item TIOCGLTC -inflow.c -@item TIOCGPGRP -inflow.c -@item TIOCLGET -inflow.c -@item TIOCLSET -inflow.c -@item TIOCNOTTY -inflow.c -@item UPAGES -altos-xdep.c -@item USE_O_NOCTTY -inflow.c +@item VARIABLES_INSIDE_BLOCK (desc, gcc_p) +For dbx-style debugging information, if the compiler puts variable +declarations inside LBRAC/RBRAC blocks, this should be defined to be +nonzero. @var{desc} is the value of @code{n_desc} from the +@code{N_RBRAC} symbol, and @var{gcc_p} is true if GDB has noticed the +presence of either the @code{GCC_COMPILED_SYMBOL} or the +@code{GCC2_COMPILED_SYMBOL}. By default, this is 0. -@item USG -Means that System V (prior to SVR4) include files are in use. -(FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c}, -@file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.) +@item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p) +Similarly, for OS/9000. Defaults to 1. -@item WRS_ORIG -remote-vx.c -@item alloca -defs.h -@item const -defs.h +@end table -@item lint -Define this to help lint in some stupid way. +Motorola M68K target conditionals. -@item volatile -Define this to override the defaults of @code{__volatile__} or @code{/**/}. +@table @code -@end table +@item BPT_VECTOR +Define this to be the 4-bit location of the breakpoint trap vector. If +not defined, it will default to @code{0xf}. -Platform-specific host conditionals. +@item REMOTE_BPT_VECTOR +Defaults to @code{1}. -@table @code +@end table -@item ALTOS -altos-xdep.c -@item ALTOS_AS -xm-altos.h -@item MOTOROLA -xm-altos.h -@item NBPG -altos-xdep.c +@section Adding a New Target -@item BCS -tm-delta88.h +The following files define a target to GDB: -@item DELTA88 -m88k-xdep.c -@item DGUX -m88k-xdep.c +@table @file -@item F_OK -xm-ultra3.h +@item gdb/config/@var{arch}/@var{ttt}.mt +Contains a Makefile fragment specific to this target. Specifies what +object files are needed for target @var{ttt}, by defining +@samp{TDEPFILES=@dots{}}. Also specifies the header file which +describes @var{ttt}, by defining @samp{TM_FILE= tm-@var{ttt}.h}. You +can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS}, but +these are now deprecated and may go away in future versions of GDB. -@end table +@item gdb/config/@var{arch}/tm-@var{ttt}.h +(@file{tm.h} is a link to this file, created by configure). Contains +macro definitions about the target machine's registers, stack frame +format and instructions. -Regex conditionals. +@item gdb/@var{ttt}-tdep.c +Contains any miscellaneous code required for this target machine. On +some machines it doesn't exist at all. Sometimes the macros in +@file{tm-@var{ttt}.h} become very complicated, so they are implemented +as functions here instead, and the macro is simply defined to call the +function. This is vastly preferable, since it is easier to understand +and debug. -@table @code +@item gdb/config/@var{arch}/tm-@var{arch}.h +This often exists to describe the basic layout of the target machine's +processor chip (registers, stack, etc). If used, it is included by +@file{tm-@var{ttt}.h}. It can be shared among many targets that use the +same processor. -@item C_ALLOCA -regex.c -@item NFAILURES -regex.c -@item RE_NREGS -regex.h -@item SIGN_EXTEND_CHAR -regex.c -@item SWITCH_ENUM_BUG -regex.c -@item SYNTAX_TABLE -regex.c -@item Sword -regex.c -@item sparc -regex.c -@item test -regex.c +@item gdb/@var{arch}-tdep.c +Similarly, there are often common subroutines that are shared by all +target machines that use this particular architecture. @end table -@node Target Conditionals -@chapter Target Conditionals +If you are adding a new operating system for an existing CPU chip, add a +@file{config/tm-@var{os}.h} file that describes the operating system +facilities that are unusual (extra symbol table info; the breakpoint +instruction needed; etc). Then write a @file{@var{arch}/tm-@var{os}.h} +that just @code{#include}s @file{tm-@var{arch}.h} and +@file{config/tm-@var{os}.h}. -When GDB is configured and compiled, various macros are defined or left -undefined, to control compilation based on the attributes of the target -system. These macros and their meanings are: -@emph{NOTE: For now, both host and target conditionals are here. -Eliminate host conditionals from this list as they are identified.} +@node Target Vector Definition -@table @code +@chapter Target Vector Definition -@item PUSH_DUMMY_FRAME -Used in @samp{call_function_by_hand} to create an artificial stack frame. +The target vector defines the interface between GDB's abstract handling +of target systems, and the nitty-gritty code that actually exercises +control over a process or a serial port. GDB includes some 30-40 +different target vectors; however, each configuration of GDB includes +only a few of them. -@item POP_FRAME -Used in @samp{call_function_by_hand} to remove an artificial stack frame. +@section File Targets -@item BLOCK_ADDRESS_FUNCTION_RELATIVE -dbxread.c -@item PYRAMID_CONTROL_FRAME_DEBUGGING -pyr-xdep.c -@item ADDITIONAL_OPTIONS -main.c -@item ADDITIONAL_OPTION_CASES -main.c -@item ADDITIONAL_OPTION_HANDLER -main.c -@item ADDITIONAL_OPTION_HELP -main.c +Both executables and core files have target vectors. -@item ADDR_BITS_REMOVE (addr) -If a raw machine address includes any bits that are not really part -of the address, then define this macro to expand into an expression -that zeros those bits in @var{addr}. For example, the two low-order -bits of a Motorola 88K address may be used by some kernels for their -own purposes, since addresses must always be 4-byte aligned, and so -are of no use for addressing. Those bits should be filtered out with -an expression such as @code{((addr) & ~3)}. +@section Standard Protocol and Remote Stubs -@item ALIGN_STACK_ON_STARTUP -main.c -@item ALTOS -altos-xdep.c -@item ALTOS_AS -xm-altos.h -@item BCS -tm-delta88.h +GDB's file @file{remote.c} talks a serial protocol to code that runs in +the target system. GDB provides several sample ``stubs'' that can be +integrated into target programs or operating systems for this purpose; +they are named @file{*-stub.c}. -@item BEFORE_MAIN_LOOP_HOOK -Define this to expand into any code that you want to execute before -the main loop starts. Although this is not, strictly speaking, -a target conditional, that is how it is currently being used. -Note that if a configuration were to define it one way for a host -and a different way for the target, GDB will probably not compile, -let alone run correctly. +The GDB user's manual describes how to put such a stub into your target +code. What follows is a discussion of integrating the SPARC stub into a +complicated operating system (rather than a simple program), by Stu +Grossman, the author of this stub. -@item BELIEVE_PCC_PROMOTION -coffread.c -@item BELIEVE_PCC_PROMOTION_TYPE -stabsread.c +The trap handling code in the stub assumes the following upon entry to +trap_low: -@item BITS_BIG_ENDIAN -Define this if the numbering of bits in the targets does *not* match -the endianness of the target byte order. -A value of 1 means that the bits are numbered in a big-endian order, -0 means little-endian. +@enumerate -@item BLOCK_ADDRESS_ABSOLUTE -dbxread.c -@item BREAKPOINT -tm-m68k.h +@item %l1 and %l2 contain pc and npc respectively at the time of the trap -@item CALL_DUMMY -valops.c -@item CALL_DUMMY_LOCATION -inferior.h -@item CALL_DUMMY_STACK_ADJUST -valops.c +@item traps are disabled -@item CANNOT_FETCH_REGISTER (regno) -A C expression that should be nonzero if @var{regno} cannot be -fetched from an inferior process. -This is only relevant if @code{FETCH_INFERIOR_REGISTERS} is not -defined. +@item you are in the correct trap window -@item CANNOT_STORE_REGISTER (regno) -A C expression that should be nonzero if @var{regno} should not be -written to the target. This is often the case for program counters, -status words, and other special registers. If this is not defined, -GDB will assume that all registers may be written. +@end enumerate -@item CFRONT_PRODUCER -dwarfread.c +As long as your trap handler can guarantee those conditions, then there +is no reason why you shouldn't be able to `share' traps with the stub. +The stub has no requirement that it be jumped to directly from the +hardware trap vector. That is why it calls @code{exceptionHandler()}, +which is provided by the external environment. For instance, this could +setup the hardware traps to actually execute code which calls the stub +first, and then transfers to its own trap handler. -@item DO_DEFERRED_STORES -@item CLEAR_DEFERRED_STORES -Define this to execute any deferred stores of registers into the inferior, -and to cancel any deferred stores. +For the most point, there probably won't be much of an issue with +`sharing' traps, as the traps we use are usually not used by the kernel, +and often indicate unrecoverable error conditions. Anyway, this is all +controlled by a table, and is trivial to modify. The most important +trap for us is for @code{ta 1}. Without that, we can't single step or +do breakpoints. Everything else is unnecessary for the proper operation +of the debugger/stub. -Currently only implemented correctly for native Sparc configurations? +From reading the stub, it's probably not obvious how breakpoints work. +They are simply done by deposit/examine operations from GDB. -@item CPLUS_MARKER -Define this to expand into the character that G++ uses to -distinguish compiler-generated identifiers from programmer-specified -identifiers. By default, this expands into @code{'$'}. -Most System V targets should define this to @code{'.'}. +@section ROM Monitor Interface -@item DBX_PARM_SYMBOL_CLASS -stabsread.c +@section Custom Protocols -@item DECR_PC_AFTER_BREAK -Define this to be the amount by which to decrement the PC after -the program encounters a breakpoint. -This is often the number of bytes in BREAKPOINT, though not always. -For most targets this value will be 0. +@section Transport Layer -@item DECR_PC_AFTER_HW_BREAK -Similarly, for hardware breakpoints. +@section Builtin Simulator -@item DELTA88 -m88k-xdep.c -@item DEV_TTY -symmisc.c -@item DGUX -m88k-xdep.c -@item DISABLE_UNSETTABLE_BREAK addr -If defined, this should evaluate to 1 if @var{addr} is in a shared -library in which breakpoints cannot be set and so should be disabled. +@node Native Debugging -@item DO_REGISTERS_INFO -infcmd.c +@chapter Native Debugging -@item END_OF_TEXT_DEFAULT -This is an expression that should designate the end of the text section -(? FIXME ?) +Several files control GDB's configuration for native support: -@item EXTRACT_RETURN_VALUE -tm-m68k.h -@item EXTRACT_STRUCT_VALUE_ADDRESS -values.c +@table @file -@item EXTRA_FRAME_INFO -If defined, this must be a list of slots that may be inserted into -the @code{frame_info} structure defined in @code{frame.h}. +@item gdb/config/@var{arch}/@var{xyz}.mh +Specifies Makefile fragments needed when hosting @emph{or native} on +machine @var{xyz}. In particular, this lists the required +native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}. +Also specifies the header file which describes native support on +@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also +define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, +@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}. -@item EXTRA_SYMTAB_INFO -If defined, this must be a list of slots that may be inserted into -the @code{symtab} structure defined in @code{symtab.h}. +@item gdb/config/@var{arch}/nm-@var{xyz}.h +(@file{nm.h} is a link to this file, created by configure). Contains C +macro definitions describing the native system environment, such as +child process control and core file support. -@item FILES_INFO_HOOK -target.c -@item FLOAT_INFO -infcmd.c -@item FP0_REGNUM -a68v-xdep.c -@item FPC_REGNUM -mach386-xdep.c -@item FP_REGNUM -parse.c -@item FRAMELESS_FUNCTION_INVOCATION -blockframe.c -@item FRAME_ARGS_ADDRESS_CORRECT -stack.c +@item gdb/@var{xyz}-nat.c +Contains any miscellaneous C code required for this native support of +this machine. On some machines it doesn't exist at all. -@item FRAME_CHAIN -Given FRAME, return a pointer to the calling frame. +@end table -@item FRAME_CHAIN_COMBINE -blockframe.c -@item FRAME_CHAIN_VALID -frame.h -@item FRAME_CHAIN_VALID_ALTERNATE -frame.h -@item FRAME_FIND_SAVED_REGS -stack.c -@item FRAME_GET_BASEREG_VALUE -frame.h +There are some ``generic'' versions of routines that can be used by +various systems. These can be customized in various ways by macros +defined in your @file{nm-@var{xyz}.h} file. If these routines work for +the @var{xyz} host, you can just include the generic file's name (with +@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}. -@item FRAME_NUM_ARGS (val, fi) -For the frame described by fi, set val to the number of arguments -that are being passed. +Otherwise, if your machine needs custom support routines, you will need +to write routines that perform the same functions as the generic file. +Put them into @code{@var{xyz}-nat.c}, and put @code{@var{xyz}-nat.o} +into @code{NATDEPFILES}. -@item FRAME_SPECIFICATION_DYADIC -stack.c +@table @file -@item FRAME_SAVED_PC -Given FRAME, return the pc saved there. That is, the return address. +@item inftarg.c +This contains the @emph{target_ops vector} that supports Unix child +processes on systems which use ptrace and wait to control the child. -@item FUNCTION_EPILOGUE_SIZE -For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the -function end symbol is 0. For such targets, you must define -@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size -of a function's epilogue. +@item procfs.c +This contains the @emph{target_ops vector} that supports Unix child +processes on systems which use /proc to control the child. -@item GCC2_COMPILED_FLAG_SYMBOL -dbxread.c -@item GCC_COMPILED_FLAG_SYMBOL -dbxread.c -@item GCC_MANGLE_BUG -symtab.c -@item GCC_PRODUCER -dwarfread.c +@item fork-child.c +This does the low-level grunge that uses Unix system calls to do a "fork +and exec" to start up a child process. -@item GDB_TARGET_IS_HPPA -This determines whether horrible kludge code in dbxread.c and partial-stab.h -is used to mangle multiple-symbol-table files from HPPA's. This should all -be ripped out, and a scheme like elfread.c used. +@item infptrace.c +This is the low level interface to inferior processes for systems using +the Unix @code{ptrace} call in a vanilla way. -@item GDB_TARGET_IS_MACH386 -mach386-xdep.c -@item GDB_TARGET_IS_SUN3 -a68v-xdep.c -@item GDB_TARGET_IS_SUN386 -sun386-xdep.c +@end table -@item GET_LONGJMP_TARGET -For most machines, this is a target-dependent parameter. On the DECstation -and the Iris, this is a native-dependent parameter, since is -needed to define it. +@section Native core file Support -This macro determines the target PC address that longjmp() will jump -to, assuming that we have just stopped at a longjmp breakpoint. It -takes a CORE_ADDR * as argument, and stores the target PC value through -this pointer. It examines the current state of the machine as needed. +@table @file -@item GET_SAVED_REGISTER -Define this if you need to supply your own definition for the -function @code{get_saved_register}. -Currently this is only done for the a29k. +@item core-aout.c::fetch_core_registers() +Support for reading registers out of a core file. This routine calls +@code{register_addr()}, see below. Now that BFD is used to read core +files, virtually all machines should use @code{core-aout.c}, and should +just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or +@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}). -@item GPLUS_PRODUCER -dwarfread.c +@item core-aout.c::register_addr() +If your @code{nm-@var{xyz}.h} file defines the macro +@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to +set @code{addr} to the offset within the @samp{user} struct of GDB +register number @code{regno}. @code{blockend} is the offset within the +``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined, +@file{core-aout.c} will define the @code{register_addr()} function and +use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but +you are using the standard @code{fetch_core_registers()}, you will need +to define your own version of @code{register_addr()}, put it into your +@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in +the @code{NATDEPFILES} list. If you have your own +@code{fetch_core_registers()}, you may not need a separate +@code{register_addr()}. Many custom @code{fetch_core_registers()} +implementations simply locate the registers themselves.@refill -@item GR64_REGNUM -Very a29k-specific. +@end table -@item HAVE_REGISTER_WINDOWS -Define this if the target has register windows. -@item REGISTER_IN_WINDOW_P regnum -Define this to be an expression that is 1 is the given register is -in the window. +When making GDB run native on a new operating system, to make it +possible to debug core files, you will need to either write specific +code for parsing your OS's core files, or customize +@file{bfd/trad-core.c}. First, use whatever @code{#include} files your +machine uses to define the struct of registers that is accessible +(possibly in the u-area) in a core file (rather than +@file{machine/reg.h}), and an include file that defines whatever header +exists on a core file (e.g. the u-area or a @samp{struct core}). Then +modify @code{trad_unix_core_file_p()} to use these values to set up the +section information for the data segment, stack segment, any other +segments in the core file (perhaps shared library contents or control +information), ``registers'' segment, and if there are two discontiguous +sets of registers (e.g. integer and float), the ``reg2'' segment. This +section information basically delimits areas in the core file in a +standard way, which the section-reading routines in BFD know how to seek +around in. -@item IBM6000_TARGET -Shows that we are configured for an IBM RS/6000 target. This conditional -should be eliminated (FIXME) and replaced by feature-specific macros. -It was introduced in haste and we are repenting at leisure. +Then back in GDB, you need a matching routine called +@code{fetch_core_registers()}. If you can use the generic one, it's in +@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file. +It will be passed a char pointer to the entire ``registers'' segment, +its length, and a zero; or a char pointer to the entire ``regs2'' +segment, its length, and a 2. The routine should suck out the supplied +register values and install them into GDB's ``registers'' array. -@item IEEE_FLOAT -Define this if the target system uses IEEE-format floating point numbers. +If your system uses @file{/proc} to control processes, and uses ELF +format core files, then you may be able to use the same routines for +reading the registers out of processes and out of core files. -@item IGNORE_SYMBOL type -This seems to be no longer used. +@section ptrace -@item INIT_EXTRA_FRAME_INFO (fromleaf, fci) -If defined, this should be a C expression or statement that fills -in the @code{EXTRA_FRAME_INFO} slots of the given frame @var{fci}. +@section /proc -@item INIT_EXTRA_SYMTAB_INFO -symfile.c +@section win32 -@item INIT_FRAME_PC (fromleaf, prev) -This is a C statement that sets the pc of the frame pointed -to by @var{prev}. [By default...] +@section shared libraries -@item INNER_THAN -Define this to be either @code{<} if the target's stack grows -downward in memory, or @code{>} is the stack grows upwards. +@section Native Conditionals -@item IN_SIGTRAMP (pc name) -Define this to return true if the given pc and/or name indicates -that the current function is a sigtramp. +When GDB is configured and compiled, various macros are defined or left +undefined, to control compilation when the host and target systems are +the same. These macros should be defined (or left undefined) in +@file{nm-@var{system}.h}. -@item SIGTRAMP_START (pc) -@item SIGTRAMP_END (pc) -Define these to be the start and end address of the sigtramp for the given pc. -On machines where the address is just a compile time constant, the macro -expansion will typically just ignore the supplied pc. +@table @code -@item IN_SOLIB_TRAMPOLINE pc name -Define this to evaluate to nonzero if the program is stopped in -the trampoline that connects to a shared library. +@item ATTACH_DETACH +If defined, then GDB will include support for the @code{attach} and +@code{detach} commands. -@item IS_TRAPPED_INTERNALVAR name -This is an ugly hook to allow the specification of special actions -that should occur as a side-effect of setting the value of a variable -internal to GDB. Currently only used by the h8500. -Note that this could be either a host or target conditional. +@item CHILD_PREPARE_TO_STORE +If the machine stores all registers at once in the child process, then +define this to ensure that all values are correct. This usually entails +a read from the child. -@item KERNEL_DEBUGGING -tm-ultra3.h -@item LCC_PRODUCER -dwarfread.c -@item L_LNNO32 -coffread.c -@item MIPSEL -mips-tdep.c -@item MOTOROLA -xm-altos.h -@item NBPG -altos-xdep.c +[Note that this is incorrectly defined in @file{xm-@var{system}.h} files +currently.] -@item NEED_TEXT_START_END -Define this if GDB should determine the start and end addresses -of the text section. (Seems dubious.) +@item FETCH_INFERIOR_REGISTERS +Define this if the native-dependent code will provide its own routines +@code{fetch_inferior_registers} and @code{store_inferior_registers} in +@file{@var{HOST}-nat.c}. If this symbol is @emph{not} defined, and +@file{infptrace.c} is included in this configuration, the default +routines in @file{infptrace.c} are used for these functions. -@item NOTICE_SIGNAL_HANDLING_CHANGE -infrun.c -@item NO_HIF_SUPPORT -remote-mm.c -@item NO_SIGINTERRUPT -remote-adapt.c +@item FILES_INFO_HOOK +(Only defined for Convex.) -@item NO_SINGLE_STEP -Define this if the target does not support single-stepping. -If this is defined, you must supply, in @code{*-tdep.c}, the function -@code{single_step}, which takes a target_signal as argument and returns nothing. -It must insert breakpoints at each possible destinations of the next -instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c} -for examples. +@item FP0_REGNUM +This macro is normally defined to be the number of the first floating +point register, if the machine has such registers. As such, it would +appear only in target-specific code. However, /proc support uses this +to decide whether floats are in use on this target. -@item NUMERIC_REG_NAMES -mips-tdep.c -@item N_SETV -dbxread.c -@item N_SET_MAGIC -hppabsd-tdep.c -@item ONE_PROCESS_WRITETEXT -breakpoint.c -@item PCC_SOL_BROKEN -dbxread.c -@item PC_IN_CALL_DUMMY -inferior.h -@item PC_LOAD_SEGMENT -stack.c +@item GET_LONGJMP_TARGET +For most machines, this is a target-dependent parameter. On the +DECstation and the Iris, this is a native-dependent parameter, since + is needed to define it. -@item PC_REGNUM -If the program counter is kept in a register, then define this macro -to be the number of that register. -This need be defined only if @code{TARGET_WRITE_PC} is not defined. +This macro determines the target PC address that longjmp() will jump to, +assuming that we have just stopped at a longjmp breakpoint. It takes a +CORE_ADDR * as argument, and stores the target PC value through this +pointer. It examines the current state of the machine as needed. -@item NPC_REGNUM -The number of the ``next program counter'' register, if defined. +@item KERNEL_U_ADDR +Define this to the address of the @code{u} structure (the ``user +struct'', also known as the ``u-page'') in kernel virtual memory. GDB +needs to know this so that it can subtract this address from absolute +addresses in the upage, that are obtained via ptrace or from core files. +On systems that don't need this value, set it to zero. -@item NNPC_REGNUM -The number of the ``next next program counter'' register, if defined. -Currently, this is only defined for the Motorola 88K. +@item KERNEL_U_ADDR_BSD +Define this to cause GDB to determine the address of @code{u} at +runtime, by using Berkeley-style @code{nlist} on the kernel's image in +the root directory. -@item PRINT_RANDOM_SIGNAL -infcmd.c -@item PRINT_REGISTER_HOOK -infcmd.c +@item KERNEL_U_ADDR_HPUX +Define this to cause GDB to determine the address of @code{u} at +runtime, by using HP-style @code{nlist} on the kernel's image in the +root directory. -@item PRINT_TYPELESS_INTEGER -This is an obscure substitute for @code{print_longest} that -seems to have been defined for the Convex target. +@item ONE_PROCESS_WRITETEXT +Define this to be able to, when a breakpoint insertion fails, warn the +user that another process may be running with the same executable. -@item PROCESS_LINENUMBER_HOOK -buildsym.c -@item PROLOGUE_FIRSTLINE_OVERLAP -infrun.c -@item PS_REGNUM -parse.c -@item PUSH_ARGUMENTS -valops.c -@item REGISTER_BYTES -remote.c +@item PROC_NAME_FMT +Defines the format for the name of a @file{/proc} device. Should be +defined in @file{nm.h} @emph{only} in order to override the default +definition in @file{procfs.c}. -@item REGISTER_NAMES -Define this to expand into an initializer of an array of strings. -Each string is the name of a register. -[more detail] +@item PTRACE_FP_BUG +mach386-xdep.c -@item REG_STACK_SEGMENT -exec.c -@item REG_STRUCT_HAS_ADDR -findvar.c -@item R_FP -dwarfread.c -@item R_OK -xm-altos.h +@item PTRACE_ARG3_TYPE +The type of the third argument to the @code{ptrace} system call, if it +exists and is different from @code{int}. -@item SDB_REG_TO_REGNUM -Define this to convert sdb register numbers -into GDB regnums. If not defined, no conversion will be done. +@item REGISTER_U_ADDR +Defines the offset of the registers in the ``u area''. -@item SEEK_END -state.c -@item SEEK_SET -state.c -@item SEM -coffread.c @item SHELL_COMMAND_CONCAT -infrun.c +If defined, is a string to prefix on the shell command used to start the +inferior. + @item SHELL_FILE -infrun.c -@item SHIFT_INST_REGS -breakpoint.c -@item SIGTRAP_STOP_AFTER_LOAD -infrun.c +If defined, this is the name of the shell to use to run the inferior. +Defaults to @code{"/bin/sh"}. -@item SKIP_PROLOGUE -A C statement that advances the PC across any function entry -prologue instructions so as to reach ``real'' code. +@item SOLIB_ADD (filename, from_tty, targ) +Define this to expand into an expression that will cause the symbols in +@var{filename} to be added to GDB's symbol table. -@item SKIP_PROLOGUE_FRAMELESS_P -A C statement that should behave similarly, but that can stop -as soon as the function is known to have a frame. -If not defined, @code{SKIP_PROLOGUE} will be used instead. +@item SOLIB_CREATE_INFERIOR_HOOK +Define this to expand into any shared-library-relocation code that you +want to be run just after the child process has been forked. -@item SKIP_TRAMPOLINE_CODE (pc) -If the target machine has trampoline code that sits between callers -and the functions being called, then define this macro to return -a new PC that is at the start of the real function. +@item START_INFERIOR_TRAPS_EXPECTED +When starting an inferior, GDB normally expects to trap twice; once when +the shell execs, and once when the program itself execs. If the actual +number of traps is something other than 2, then define this macro to +expand into the number expected. -@item SP_REGNUM -parse.c +@item SVR4_SHARED_LIBS +Define this to indicate that SVR4-style shared libraries are in use. -@item STAB_REG_TO_REGNUM -Define this to convert stab register numbers (as gotten from `r' declarations) -into GDB regnums. If not defined, no conversion will be done. +@item USE_PROC_FS +This determines whether small routines in @file{*-tdep.c}, which +translate register values between GDB's internal representation and the +/proc representation, are compiled. -@item STACK_ALIGN -valops.c -@item STOP_SIGNAL -main.c +@item U_REGS_OFFSET +This is the offset of the registers in the upage. It need only be +defined if the generic ptrace register access routines in +@file{infptrace.c} are being used (that is, @file{infptrace.c} is +configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If +the default value from @file{infptrace.c} is good enough, leave it +undefined. -@item STORE_RETURN_VALUE (type, valbuf) -A C expression that stores a function return value of type @var{type}, -where @var{valbuf} is the address of the value to be stored. +The default value means that u.u_ar0 @emph{points to} the location of +the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means +that u.u_ar0 @emph{is} the location of the registers. -@item SUN4_COMPILER_FEATURE -infrun.c -@item SUN_FIXED_LBRAC_BUG -dbxread.c -@item SVR4_SHARED_LIBS -solib.c -@item SYMBOL_RELOADING_DEFAULT -symfile.c +@item CLEAR_SOLIB +objfiles.c -@item TARGET_BYTE_ORDER -The ordering of bytes in the target. -This must be defined to be either @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. +@item DEBUG_PTRACE +Define this to debug ptrace calls. -@item TARGET_CHAR_BIT -Number of bits in a char; defaults to 8. +@end table -@item TARGET_COMPLEX_BIT -Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. -@item TARGET_DOUBLE_BIT -Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. +@node Support Libraries -@item TARGET_DOUBLE_COMPLEX_BIT -Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. +@chapter Support Libraries -@item TARGET_FLOAT_BIT -Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. +@section BFD -@item TARGET_INT_BIT -Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. +BFD provides support for GDB in several ways: -@item TARGET_LONG_BIT -Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. +@table @emph -@item TARGET_LONG_DOUBLE_BIT -Number of bits in a long double float; -defaults to @code{2 * TARGET_DOUBLE_BIT}. +@item identifying executable and core files +BFD will identify a variety of file types, including a.out, coff, and +several variants thereof, as well as several kinds of core files. -@item TARGET_LONG_LONG_BIT -Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. +@item access to sections of files +BFD parses the file headers to determine the names, virtual addresses, +sizes, and file locations of all the various named sections in files +(such as the text section or the data section). GDB simply calls BFD to +read or write section X at byte offset Y for length Z. -@item TARGET_PTR_BIT -Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. +@item specialized core file support +BFD provides routines to determine the failing command name stored in a +core file, the signal with which the program failed, and whether a core +file matches (i.e. could be a core dump of) a particular executable +file. -@item TARGET_SHORT_BIT -Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. +@item locating the symbol information +GDB uses an internal interface of BFD to determine where to find the +symbol information in an executable file or symbol-file. GDB itself +handles the reading of symbols, since BFD does not ``understand'' debug +symbols, but GDB uses BFD's cached information to find the symbols, +string table, etc. -@item TARGET_READ_PC -@item TARGET_WRITE_PC (val, pid) -@item TARGET_READ_SP -@item TARGET_WRITE_SP -@item TARGET_READ_FP -@item TARGET_WRITE_FP -These change the behavior of @code{read_pc}, @code{write_pc}, -@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}. -For most targets, these may be left undefined. GDB will call the -read and write register functions with the relevant @code{_REGNUM} argument. +@end table -These macros are useful when a target keeps one of these registers in a -hard to get at place; for example, part in a segment register and part -in an ordinary register. +@section opcodes -@item USE_STRUCT_CONVENTION (gcc_p, type) -If defined, this must be an expression that is nonzero if a value -of the given @var{type} being returned from a function must have -space allocated for it on the stack. @var{gcc_p} is true if the -function being considered is known to have been compiled by GCC; -this is helpful for systems where GCC is known to use different calling -convention than other compilers. +The opcodes library provides GDB's disassembler. (It's a separate +library because it's also used in binutils, for @file{objdump}). -@item VARIABLES_INSIDE_BLOCK (desc, gcc_p) -For dbx-style debugging information, if the compiler puts variable -declarations inside LBRAC/RBRAC blocks, this should be defined -to be nonzero. @var{desc} is the value of @code{n_desc} from the -@code{N_RBRAC} symbol, and @var{gcc_p} is true if GDB has noticed -the presence of either the @code{GCC_COMPILED_SYMBOL} or the -@code{GCC2_COMPILED_SYMBOL}. -By default, this is 0. +@section readline -@item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p) -Similarly, for OS/9000. Defaults to 1. +@section mmalloc + +@section libiberty + +@section gnu-regex + +Regex conditionals. + +@table @code + +@item C_ALLOCA + +@item NFAILURES + +@item RE_NREGS + +@item SIGN_EXTEND_CHAR -@item WRS_ORIG -remote-vx.c +@item SWITCH_ENUM_BUG -@item test -(Define this to enable testing code in regex.c.) +@item SYNTAX_TABLE + +@item Sword + +@item sparc @end table -Motorola M68K target conditionals. +@section include + +@node Coding + +@chapter Coding + +This chapter covers topics that are lower-level than the major +algorithms of GDB. + +@section Cleanups + +Cleanups are a structured way to deal with things that need to be done +later. When your code does something (like @code{malloc} some memory, +or open a file) that needs to be undone later (e.g. free the memory or +close the file), it can make a cleanup. The cleanup will be done at +some future point: when the command is finished, when an error occurs, +or when your code decides it's time to do cleanups. + +You can also discard cleanups, that is, throw them away without doing +what they say. This is only done if you ask that it be done. + +Syntax: @table @code -@item BPT_VECTOR -Define this to be the 4-bit location of the breakpoint trap vector. -If not defined, it will default to @code{0xf}. +@item struct cleanup *@var{old_chain}; +Declare a variable which will hold a cleanup chain handle. -@item REMOTE_BPT_VECTOR -Defaults to @code{1}. +@item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); +Make a cleanup which will cause @var{function} to be called with +@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a +handle that can be passed to @code{do_cleanups} or +@code{discard_cleanups} later. Unless you are going to call +@code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore +the result from @code{make_cleanup}. + +@item do_cleanups (@var{old_chain}); +Perform all cleanups done since @code{make_cleanup} returned +@var{old_chain}. E.g.: +@example +make_cleanup (a, 0); +old = make_cleanup (b, 0); +do_cleanups (old); +@end example +@noindent +will call @code{b()} but will not call @code{a()}. The cleanup that +calls @code{a()} will remain in the cleanup chain, and will be done +later unless otherwise discarded.@refill + +@item discard_cleanups (@var{old_chain}); +Same as @code{do_cleanups} except that it just removes the cleanups from +the chain and does not call the specified functions. @end table -@node Native Conditionals -@chapter Native Conditionals +Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify +that they ``should not be called when cleanups are not in place''. This +means that any actions you need to reverse in the case of an error or +interruption must be on the cleanup chain before you call these +functions, since they might never return to your code (they +@samp{longjmp} instead). + +@section Wrapping Output Lines + +Output that goes through @code{printf_filtered} or @code{fputs_filtered} +or @code{fputs_demangled} needs only to have calls to @code{wrap_here} +added in places that would be good breaking points. The utility +routines will take care of actually wrapping if the line width is +exceeded. + +The argument to @code{wrap_here} is an indentation string which is +printed @emph{only} if the line breaks there. This argument is saved +away and used later. It must remain valid until the next call to +@code{wrap_here} or until a newline has been printed through the +@code{*_filtered} functions. Don't pass in a local variable and then +return! + +It is usually best to call @code{wrap_here()} after printing a comma or +space. If you call it before printing a space, make sure that your +indentation properly accounts for the leading space that will print if +the line wraps there. + +Any function or set of functions that produce filtered output must +finish by printing a newline, to flush the wrap buffer, before switching +to unfiltered (``@code{printf}'') output. Symbol reading routines that +print warnings are a good example. + +@section Coding Style + +GDB follows the GNU coding standards, as described in +@file{etc/standards.texi}. This file is also available for anonymous +FTP from GNU archive sites. There are some additional considerations +for GDB maintainers that reflect the unique environment and style of GDB +maintenance. If you follow these guidelines, GDB will be more +consistent and easier to maintain. -When GDB is configured and compiled, various macros are defined or left -undefined, to control compilation when the host and target systems -are the same. These macros should be defined (or left undefined) -in @file{nm-@var{system}.h}. +GDB's policy on the use of prototypes is that prototypes are used to +@emph{declare} functions but never to @emph{define} them. Simple macros +are used in the declarations, so that a non-ANSI compiler can compile +GDB without trouble. The simple macro calls are used like this: -@table @code +@example @code +extern int memory_remove_breakpoint PARAMS ((CORE_ADDR, char *)); +@end example -@item ATTACH_DETACH -If defined, then GDB will include support for the @code{attach} and -@code{detach} commands. +Note the double parentheses around the parameter types. This allows an +arbitrary number of parameters to be described, without freaking out the +C preprocessor. When the function has no parameters, it should be +described like: -@item CHILD_PREPARE_TO_STORE -If the machine stores all registers at once in the child process, -then define this to ensure that all values are correct. -This usually entails a read from the child. +@example @code +void noprocess PARAMS ((void)); +@end example -[Note that this is incorrectly defined in @file{xm-@var{system}.h} -files currently.] +The @code{PARAMS} macro expands to its argument in ANSI C, or to a +simple @code{()} in traditional C. -@item FETCH_INFERIOR_REGISTERS -Define this if the native-dependent code will provide its -own routines -@code{fetch_inferior_registers} and @code{store_inferior_registers} in -@file{@var{HOST}-nat.c}. -If this symbol is @emph{not} defined, and @file{infptrace.c} -is included in this configuration, the default routines in -@file{infptrace.c} are used for these functions. +All external functions should have a @code{PARAMS} declaration in a +header file that callers include. All static functions should have such +a declaration near the top of their source file. -@item GET_LONGJMP_TARGET -For most machines, this is a target-dependent parameter. On the DECstation -and the Iris, this is a native-dependent parameter, since is -needed to define it. +We don't have a gcc option that will properly check that these rules +have been followed, but it's GDB policy, and we periodically check it +using the tools available (plus manual labor), and clean up any +remnants. -This macro determines the target PC address that longjmp() will jump -to, assuming that we have just stopped at a longjmp breakpoint. It -takes a CORE_ADDR * as argument, and stores the target PC value through -this pointer. It examines the current state of the machine as needed. +@section Clean Design -@item PROC_NAME_FMT -Defines the format for the name of a @file{/proc} device. Should be -defined in @file{nm.h} @emph{only} in order to override the default -definition in @file{procfs.c}. +In addition to getting the syntax right, there's the little question of +semantics. Some things are done in certain ways in GDB because long +experience has shown that the more obvious ways caused various kinds of +trouble. -@item PTRACE_FP_BUG -mach386-xdep.c +You can't assume the byte order of anything that comes from a target +(including @var{value}s, object files, and instructions). Such things +must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB, or one of +the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}. -@item PTRACE_ARG3_TYPE -The type of the third argument to the @code{ptrace} system call, if it exists -and is different from @code{int}. +You can't assume that you know what interface is being used to talk to +the target system. All references to the target must go through the +current @code{target_ops} vector. -@item REGISTER_U_ADDR -Defines the offset of the registers in the ``u area''; @pxref{Host}. +You can't assume that the host and target machines are the same machine +(except in the ``native'' support modules). In particular, you can't +assume that the target machine's header files will be available on the +host machine. Target code must bring along its own header files -- +written from scratch or explicitly donated by their owner, to avoid +copyright problems. -@item SOLIB_ADD (filename, from_tty, targ) -Define this to expand into an expression that will cause the symbols -in @var{filename} to be added to GDB's symbol table. +Insertion of new @code{#ifdef}'s will be frowned upon. It's much better +to write the code portably than to conditionalize it for various +systems. -@item SOLIB_CREATE_INFERIOR_HOOK -Define this to expand into any shared-library-relocation code -that you want to be run just after the child process has been forked. +New @code{#ifdef}'s which test for specific compilers or manufacturers +or operating systems are unacceptable. All @code{#ifdef}'s should test +for features. The information about which configurations contain which +features should be segregated into the configuration files. Experience +has proven far too often that a feature unique to one particular system +often creeps into other systems; and that a conditional based on some +predefined macro for your current system will become worthless over +time, as new versions of your system come out that behave differently +with regard to this feature. -@item START_INFERIOR_TRAPS_EXPECTED -When starting an inferior, GDB normally expects to trap twice; -once when the shell execs, and once when the program itself execs. -If the actual number of traps is something other than 2, then -define this macro to expand into the number expected. +Adding code that handles specific architectures, operating systems, +target interfaces, or hosts, is not acceptable in generic code. If a +hook is needed at that point, invent a generic hook and define it for +your configuration, with something like: -@item USE_PROC_FS -This determines whether small routines in @file{*-tdep.c}, which -translate register values -between GDB's internal representation and the /proc representation, -are compiled. +@example +#ifdef WRANGLE_SIGNALS + WRANGLE_SIGNALS (signo); +#endif +@end example -@item U_REGS_OFFSET -This is the offset of the registers in the upage. It need only be -defined if the generic ptrace register access routines in -@file{infptrace.c} are being used (that is, -@file{infptrace.c} is configured in, and -@code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value -from @file{infptrace.c} is good enough, leave it undefined. +In your host, target, or native configuration file, as appropriate, +define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take a +bit of care in defining the hook, so that it can be used by other ports +in the future, if they need a hook in the same place. -The default value means that u.u_ar0 @emph{points to} the location of the -registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that -u.u_ar0 @emph{is} the location of the registers. +If the hook is not defined, the code should do whatever "most" machines +want. Using @code{#ifdef}, as above, is the preferred way to do this, +but sometimes that gets convoluted, in which case use -@item CLEAR_SOLIB -objfiles.c +@example +#ifndef SPECIAL_FOO_HANDLING +#define SPECIAL_FOO_HANDLING(pc, sp) (0) +#endif +@end example -@item DEBUG_PTRACE -Define this to debug ptrace calls. +where the macro is used or in an appropriate header file. -@end table +Whether to include a @dfn{small} hook, a hook around the exact pieces of +code which are system-dependent, or whether to replace a whole function +with a hook depends on the case. A good example of this dilemma can be +found in @code{get_saved_register}. All machines that GDB 2.8 ran on +just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved +registers. Then the SPARC and Pyramid came along, and +@code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were +introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER} +hook. The first three are examples of small hooks; the latter replaces +a whole function. In this specific case, it is useful to have both +kinds; it would be a bad idea to replace all the uses of the small hooks +with @code{GET_SAVED_REGISTER}, since that would result in much +duplicated code. Other times, duplicating a few lines of code here or +there is much cleaner than introducing a large number of small hooks. -@node Obsolete Conditionals -@chapter Obsolete Conditionals +Another way to generalize GDB along a particular interface is with an +attribute struct. For example, GDB has been generalized to handle +multiple kinds of remote interfaces -- not by #ifdef's everywhere, but +by defining the "target_ops" structure and having a current target (as +well as a stack of targets below it, for memory references). Whenever +something needs to be done that depends on which remote interface we are +using, a flag in the current target_ops structure is tested (e.g. +`target_has_stack'), or a function is called through a pointer in the +current target_ops structure. In this way, when a new remote interface +is added, only one module needs to be touched -- the one that actually +implements the new remote interface. Other examples of +attribute-structs are BFD access to multiple kinds of object file +formats, or GDB's access to multiple source languages. + +Please avoid duplicating code. For example, in GDB 3.x all the code +interfacing between @code{ptrace} and the rest of GDB was duplicated in +@file{*-dep.c}, and so changing something was very painful. In GDB 4.x, +these have all been consolidated into @file{infptrace.c}. +@file{infptrace.c} can deal with variations between systems the same way +any system-independent file would (hooks, #if defined, etc.), and +machines which are radically different don't need to use infptrace.c at +all. + +@emph{Do} write code that doesn't depend on the sizes of C data types, +the format of the host's floating point numbers, the alignment of anything, +or the order of evaluation of expressions. In short, follow good +programming practices for writing portable C code. + + +@node Porting GDB + +@chapter Porting GDB + +Most of the work in making GDB compile on a new machine is in specifying +the configuration of the machine. This is done in a dizzying variety of +header files and configuration scripts, which we hope to make more +sensible soon. Let's say your new host is called an @var{xyz} (e.g. +@samp{sun4}), and its full three-part configuration name is +@code{@var{arch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). +In particular: + +In the top level directory, edit @file{config.sub} and add @var{arch}, +@var{xvend}, and @var{xos} to the lists of supported architectures, +vendors, and operating systems near the bottom of the file. Also, add +@var{xyz} as an alias that maps to +@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by +running + +@example +./config.sub @var{xyz} +@end example +@noindent +and +@example +./config.sub @code{@var{arch}-@var{xvend}-@var{xos}} +@end example +@noindent +which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}} +and no error messages. + +You need to port BFD, if that hasn't been done already. Porting BFD is +beyond the scope of this manual. + +To configure GDB itself, edit @file{gdb/configure.host} to recognize +your system and set @code{gdb_host} to @var{xyz}, and (unless your +desired target is already available) also edit @file{gdb/configure.tgt}, +setting @code{gdb_target} to something appropriate (for instance, +@var{xyz}). + +Finally, you'll need to specify and define GDB's host-, native-, and +target-dependent @file{.h} and @file{.c} files used for your +configuration. + +@section Configuring GDB for Release + +From the top level directory (containing @file{gdb}, @file{bfd}, +@file{libiberty}, and so on): +@example +make -f Makefile.in gdb.tar.gz +@end example + +This will properly configure, clean, rebuild any files that are +distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}), +and will then make a tarfile. (If the top level directory has already +been configured, you can just do @code{make gdb.tar.gz} instead.) + +This procedure requires: +@itemize @bullet +@item symbolic links +@item @code{makeinfo} (texinfo2 level) +@item @TeX{} +@item @code{dvips} +@item @code{yacc} or @code{bison} +@end itemize +@noindent +@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.). + +@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION + +@file{gdb.texinfo} is currently marked up using the texinfo-2 macros, +which are not yet a default for anything (but we have to start using +them sometime). + +For making paper, the only thing this implies is the right generation of +@file{texinfo.tex} needs to be included in the distribution. + +For making info files, however, rather than duplicating the texinfo2 +distribution, generate @file{gdb-all.texinfo} locally, and include the +files @file{gdb.info*} in the distribution. Note the plural; +@code{makeinfo} will split the document into one overall file and five +or so included files. + +@node Hints + +@chapter Hints + +Check the @file{README} file, it often has useful information that does not +appear anywhere else in the directory. + +@menu +* Getting Started:: Getting started working on GDB +* Debugging GDB:: Debugging GDB with itself +@end menu + +@node Getting Started,,, Hints + +@section Getting Started + +GDB is a large and complicated program, and if you first starting to +work on it, it can be hard to know where to start. Fortunately, if you +know how to go about it, there are ways to figure out what is going on. + +This manual, the GDB Internals manual, has information which applies +generally to many parts of GDB. + +Information about particular functions or data structures are located in +comments with those functions or data structures. If you run across a +function or a global variable which does not have a comment correctly +explaining what is does, this can be thought of as a bug in GDB; feel +free to submit a bug report, with a suggested comment if you can figure +out what the comment should say. If you find a comment which is +actually wrong, be especially sure to report that. + +Comments explaining the function of macros defined in host, target, or +native dependent files can be in several places. Sometimes they are +repeated every place the macro is defined. Sometimes they are where the +macro is used. Sometimes there is a header file which supplies a +default definition of the macro, and the comment is there. This manual +also documents all the available macros. +@c (@pxref{Host Conditionals}, @pxref{Target +@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete +@c Conditionals}) + +Start with the header files. Once you some idea of how GDB's internal +symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you +will find it much easier to understand the code which uses and creates +those symbol tables. + +You may wish to process the information you are getting somehow, to +enhance your understanding of it. Summarize it, translate it to another +language, add some (perhaps trivial or non-useful) feature to GDB, use +the code to predict what a test case would do and write the test case +and verify your prediction, etc. If you are reading code and your eyes +are starting to glaze over, this is a sign you need to use a more active +approach. + +Once you have a part of GDB to start with, you can find more +specifically the part you are looking for by stepping through each +function with the @code{next} command. Do not use @code{step} or you +will quickly get distracted; when the function you are stepping through +calls another function try only to get a big-picture understanding +(perhaps using the comment at the beginning of the function being +called) of what it does. This way you can identify which of the +functions being called by the function you are stepping through is the +one which you are interested in. You may need to examine the data +structures generated at each stage, with reference to the comments in +the header files explaining what the data structures are supposed to +look like. + +Of course, this same technique can be used if you are just reading the +code, rather than actually stepping through it. The same general +principle applies---when the code you are looking at calls something +else, just try to understand generally what the code being called does, +rather than worrying about all its details. + +A good place to start when tracking down some particular area is with a +command which invokes that feature. Suppose you want to know how +single-stepping works. As a GDB user, you know that the @code{step} +command invokes single-stepping. The command is invoked via command +tables (see @file{command.h}); by convention the function which actually +performs the command is formed by taking the name of the command and +adding @samp{_command}, or in the case of an @code{info} subcommand, +@samp{_info}. For example, the @code{step} command invokes the +@code{step_command} function and the @code{info display} command invokes +@code{display_info}. When this convention is not followed, you might +have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on +itself and set a breakpoint in @code{execute_command}. + +If all of the above fail, it may be appropriate to ask for information +on @code{bug-gdb}. But @emph{never} post a generic question like ``I was +wondering if anyone could give me some tips about understanding +GDB''---if we had some magic secret we would put it in this manual. +Suggestions for improving the manual are always welcome, of course. + +@node Debugging GDB,,,Hints + +@section Debugging GDB with itself + +If GDB is limping on your machine, this is the preferred way to get it +fully functional. Be warned that in some ancient Unix systems, like +Ultrix 4.2, a program can't be running in one process while it is being +debugged in another. Rather than typing the command @code{@w{./gdb +./gdb}}, which works on Suns and such, you can copy @file{gdb} to +@file{gdb2} and then type @code{@w{./gdb ./gdb2}}. + +When you run GDB in the GDB source directory, it will read a +@file{.gdbinit} file that sets up some simple things to make debugging +gdb easier. The @code{info} command, when executed without a subcommand +in a GDB being debugged by gdb, will pop you back up to the top level +gdb. See @file{.gdbinit} for details. + +If you use emacs, you will probably want to do a @code{make TAGS} after +you configure your distribution; this will put the machine dependent +routines for your local machine where they will be accessed first by +@kbd{M-.} + +Also, make sure that you've either compiled GDB with your local cc, or +have run @code{fixincludes} if you are compiling with gcc. + +@section Submitting Patches + +Thanks for thinking of offering your changes back to the community of +GDB users. In general we like to get well designed enhancements. +Thanks also for checking in advance about the best way to transfer the +changes. + +The GDB maintainers will only install ``cleanly designed'' patches. You +may not always agree on what is clean design. +@c @pxref{Coding Style}, @pxref{Clean Design}. + +If the maintainers don't have time to put the patch in when it arrives, +or if there is any question about a patch, it goes into a large queue +with everyone else's patches and bug reports. + +The legal issue is that to incorporate substantial changes requires a +copyright assignment from you and/or your employer, granting ownership +of the changes to the Free Software Foundation. You can get the +standard document for doing this by sending mail to +@code{gnu@@prep.ai.mit.edu} and asking for it. I recommend that people +write in "All programs owned by the Free Software Foundation" as "NAME +OF PROGRAM", so that changes in many programs (not just GDB, but GAS, +Emacs, GCC, etc) can be contributed with only one piece of legalese +pushed through the bureacracy and filed with the FSF. I can't start +merging changes until this paperwork is received by the FSF (their +rules, which I follow since I maintain it for them). + +Technically, the easiest way to receive changes is to receive each +feature as a small context diff or unidiff, suitable for "patch". +Each message sent to me should include the changes to C code and +header files for a single feature, plus ChangeLog entries for each +directory where files were modified, and diffs for any changes needed +to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there +are a lot of changes for a single feature, they can be split down +into multiple messages. + +In this way, if I read and like the feature, I can add it to the +sources with a single patch command, do some testing, and check it in. +If you leave out the ChangeLog, I have to write one. If you leave +out the doc, I have to puzzle out what needs documenting. Etc. + +The reason to send each change in a separate message is that I will +not install some of the changes. They'll be returned to you with +questions or comments. If I'm doing my job, my message back to you +will say what you have to fix in order to make the change acceptable. +The reason to have separate messages for separate features is so +that other changes (which I @emph{am} willing to accept) can be installed +while one or more changes are being reworked. If multiple features +are sent in a single message, I tend to not put in the effort to sort +out the acceptable changes from the unacceptable, so none of the +features get installed until all are acceptable. + +If this sounds painful or authoritarian, well, it is. But I get a lot +of bug reports and a lot of patches, and most of them don't get +installed because I don't have the time to finish the job that the bug +reporter or the contributor could have done. Patches that arrive +complete, working, and well designed, tend to get installed on the day +they arrive. The others go into a queue and get installed if and when +I scan back over the queue -- which can literally take months +sometimes. It's in both our interests to make patch installation easy +-- you get your changes installed, and I make some forward progress on +GDB in a normal 12-hour day (instead of them having to wait until I +have a 14-hour or 16-hour day to spend cleaning up patches before I +can install them). + +Please send patches directly to the GDB maintainers at +@code{gdb-patches@@cygnus.com}. + +@section Obsolete Conditionals Fragments of old code in GDB sometimes reference or set the following -configuration macros. They should not be used by new code, and -old uses should be removed as those parts of the debugger are -otherwise touched. +configuration macros. They should not be used by new code, and old uses +should be removed as those parts of the debugger are otherwise touched. @table @code @@ -2555,24 +2537,18 @@ and deleted from all of GDB's config files. Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR is so old that it has never been converted to use BFD. Now that's old! -@end table +@item PYRAMID_CONTROL_FRAME_DEBUGGING +pyr-xdep.c +@item PYRAMID_CORE +pyr-xdep.c +@item PYRAMID_PTRACE +pyr-xdep.c -@node XCOFF -@chapter The XCOFF Object File Format +@item REG_STACK_SEGMENT +exec.c -The IBM RS/6000 running AIX uses an object file format called xcoff. -The COFF sections, symbols, and line numbers are used, but debugging -symbols are dbx-style stabs whose strings are located in the -@samp{.debug} section (rather than the string table). For more -information, @xref{Top,,,stabs,The Stabs Debugging Format}, and search -for XCOFF. +@end table -The shared library scheme has a nice clean interface for figuring out -what shared libraries are in use, but the catch is that everything which -refers to addresses (symbol tables and breakpoints at least) needs to be -relocated for both shared libraries and the main executable. At least -using the standard mechanism this can only be done once the program has -been run (or the core file has been read). @contents @bye diff --git a/gdb/top.c b/gdb/top.c index 18be6491d61..5d3c1163ffd 100644 --- a/gdb/top.c +++ b/gdb/top.c @@ -1447,7 +1447,15 @@ gdb_readline (prrompt) } if (c == '\n') +#ifndef CRLF_SOURCE_FILES break; +#else + { + if (input_index > 0 && result[input_index - 1] == '\r') + input_index--; + break; + } +#endif result[input_index++] = c; while (input_index >= result_size) diff --git a/gdb/win32-nat.c b/gdb/win32-nat.c index c1c67587185..2110e6a034f 100644 --- a/gdb/win32-nat.c +++ b/gdb/win32-nat.c @@ -21,7 +21,7 @@ /* by Steve Chamberlain, sac@cygnus.com */ -/* We assume we're being built with and will be used for cygwin32. */ +/* We assume we're being built with and will be used for cygwin. */ #include "defs.h" #include "frame.h" /* required by inferior.h */ @@ -50,6 +50,10 @@ #include #include +/* The string sent by cygwin when it processes a signal. + FIXME: This should be in a cygwin include file. */ +#define CYGWIN_SIGNAL_STRING "cygwin: signal" + #define CHECK(x) check (x, __FILE__,__LINE__) #define DEBUG_EXEC(x) if (debug_exec) printf x #define DEBUG_EVENTS(x) if (debug_events) printf x @@ -60,18 +64,32 @@ extern struct target_ops child_ops; static void child_stop PARAMS ((void)); +static int child_thread_alive PARAMS ((int)); + +static int last_sig = 0; /* Set if a signal was received from the + debugged process */ -/* The most recently read context. Inspect ContextFlags to see what - bits are valid. */ +/* Thread information structure used to track information that is + not available in gdb's thread structure. */ +typedef struct thread_info_struct +{ + struct thread_info_struct *next; + DWORD id; + HANDLE h; + char *name; + int suspend_count; + CONTEXT context; +} thread_info; -static CONTEXT context; +static thread_info thread_head = {NULL}; /* The process and thread handles for the above context. */ -static HANDLE current_process; -static HANDLE current_thread; -static int current_process_id; -static int current_thread_id; +static DEBUG_EVENT current_event; /* The current debug event from + WaitForDebugEvent */ +static HANDLE current_process_handle; /* Currently executing process */ +static thread_info *current_thread; /* Info on currently selected thread */ +static DWORD main_thread_id; /* Thread ID of the main thread */ /* Counts of things. */ static int exception_count = 0; @@ -86,9 +104,9 @@ static int debug_memory = 0; /* show target memory accesses */ static int debug_exceptions = 0; /* show target exceptions */ /* This vector maps GDB's idea of a register's number into an address - in the win32 exception context vector. + in the win32 exception context vector. - It also contains the bit mask needed to load the register in question. + It also contains the bit mask needed to load the register in question. One day we could read a reg, we could inspect the context we already have loaded, if it doesn't have the bit set that we need, @@ -98,40 +116,33 @@ static int debug_exceptions = 0; /* show target exceptions */ the other regs of the group, and then we copy the info in and set out bit. */ -struct regmappings - { - char *incontext; - int mask; - }; - -static const struct regmappings mappings[] = +#define context_offset(x) ((int)&(((CONTEXT *)NULL)->x)) +static const int mappings[] = { -#ifdef i386 - {(char *) &context.Eax, CONTEXT_INTEGER}, - {(char *) &context.Ecx, CONTEXT_INTEGER}, - {(char *) &context.Edx, CONTEXT_INTEGER}, - {(char *) &context.Ebx, CONTEXT_INTEGER}, - {(char *) &context.Esp, CONTEXT_CONTROL}, - {(char *) &context.Ebp, CONTEXT_CONTROL}, - {(char *) &context.Esi, CONTEXT_INTEGER}, - {(char *) &context.Edi, CONTEXT_INTEGER}, - {(char *) &context.Eip, CONTEXT_CONTROL}, - {(char *) &context.EFlags, CONTEXT_CONTROL}, - {(char *) &context.SegCs, CONTEXT_SEGMENTS}, - {(char *) &context.SegSs, CONTEXT_SEGMENTS}, - {(char *) &context.SegDs, CONTEXT_SEGMENTS}, - {(char *) &context.SegEs, CONTEXT_SEGMENTS}, - {(char *) &context.SegFs, CONTEXT_SEGMENTS}, - {(char *) &context.SegGs, CONTEXT_SEGMENTS}, - {&context.FloatSave.RegisterArea[0 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[1 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[2 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[3 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[4 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[5 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[6 * 10], CONTEXT_FLOATING_POINT}, - {&context.FloatSave.RegisterArea[7 * 10], CONTEXT_FLOATING_POINT}, -#endif + context_offset(Eax), + context_offset(Ecx), + context_offset(Edx), + context_offset(Ebx), + context_offset(Esp), + context_offset(Ebp), + context_offset(Esi), + context_offset(Edi), + context_offset(Eip), + context_offset(EFlags), + context_offset(SegCs), + context_offset(SegSs), + context_offset(SegDs), + context_offset(SegEs), + context_offset(SegFs), + context_offset(SegGs), + context_offset(FloatSave.RegisterArea[0 * 10]), + context_offset(FloatSave.RegisterArea[1 * 10]), + context_offset(FloatSave.RegisterArea[2 * 10]), + context_offset(FloatSave.RegisterArea[3 * 10]), + context_offset(FloatSave.RegisterArea[4 * 10]), + context_offset(FloatSave.RegisterArea[5 * 10]), + context_offset(FloatSave.RegisterArea[6 * 10]), + context_offset(FloatSave.RegisterArea[7 * 10]), }; /* This vector maps the target's idea of an exception (extracted @@ -153,72 +164,199 @@ static const struct xlate_exception {EXCEPTION_SINGLE_STEP, TARGET_SIGNAL_TRAP}, {-1, -1}}; -static void -check (BOOL ok, const char *file, int line) +/* Find a thread record given a thread id. + If get_context then also retrieve the context for this + thread. */ +static thread_info * +thread_rec (DWORD id, int get_context) { - if (!ok) - printf_filtered ("error return %s:%d was %d\n", file, line, GetLastError ()); + thread_info *th; + + for (th = &thread_head; (th = th->next) != NULL; ) + if (th->id == id) + { + if (!th->suspend_count && get_context) + { + if (get_context > 0) + th->suspend_count = SuspendThread (th->h) + 1; + else if (get_context < 0) + th->suspend_count = -1; + + th->context.ContextFlags = CONTEXT_DEBUGGER; + GetThreadContext (th->h, &th->context); + } + return th; + } + + return NULL; +} + +/* Add a thread to the thread list */ +static thread_info * +child_add_thread(DWORD id, HANDLE h) +{ + thread_info *th; + + if ((th = thread_rec (id, FALSE))) + return th; + + th = (thread_info *) xmalloc (sizeof (*th)); + memset(th, 0, sizeof (*th)); + th->id = id; + th->h = h; + th->next = thread_head.next; + thread_head.next = th; + add_thread (id); + return th; } +/* Clear out any old thread list and reintialize it to a + pristine state. */ static void -child_fetch_inferior_registers (int r) +child_init_thread_list () { - if (r < 0) + thread_info *th = &thread_head; + + DEBUG_EVENTS (("gdb: child_init_thread_list\n")); + init_thread_list (); + while (th->next != NULL) { - for (r = 0; r < NUM_REGS; r++) - child_fetch_inferior_registers (r); + thread_info *here = th->next; + th->next = here->next; + (void) CloseHandle (here->h); + free (here); } - else +} + +/* Delete a thread from the list of threads */ +static void +child_delete_thread (DWORD id) +{ + thread_info *th; + + if (info_verbose) + printf_unfiltered ("[Deleting %s]\n", target_pid_to_str (id)); + delete_thread (id); + + for (th = &thread_head; + th->next != NULL && th->next->id != id; + th = th->next) + continue; + + if (th->next != NULL) { - supply_register (r, mappings[r].incontext); + thread_info *here = th->next; + th->next = here->next; + CloseHandle (here->h); + free (here); } } static void -child_store_inferior_registers (int r) +check (BOOL ok, const char *file, int line) +{ + if (!ok) + printf_filtered ("error return %s:%d was %d\n", file, line, GetLastError ()); +} + +static void +do_child_fetch_inferior_registers (int r) { - if (r < 0) + if (r >= 0) + supply_register (r, ((char *) ¤t_thread->context) + mappings[r]); + else { for (r = 0; r < NUM_REGS; r++) - child_store_inferior_registers (r); + do_child_fetch_inferior_registers (r); } +} + +static void +child_fetch_inferior_registers (int r) +{ + current_thread = thread_rec (inferior_pid, TRUE); + do_child_fetch_inferior_registers (r); +} + +static void +do_child_store_inferior_registers (int r) +{ + if (r >= 0) + read_register_gen (r, ((char *) ¤t_thread->context) + mappings[r]); else { - read_register_gen (r, mappings[r].incontext); + for (r = 0; r < NUM_REGS; r++) + do_child_store_inferior_registers (r); } } +/* Store a new register value into the current thread context */ +static void +child_store_inferior_registers (int r) +{ + current_thread = thread_rec (inferior_pid, TRUE); + do_child_store_inferior_registers (r); +} /* Wait for child to do something. Return pid of child, or -1 in case of error; store status through argument pointer OURSTATUS. */ static int -handle_load_dll (char *eventp) +handle_load_dll (char *dummy) { - DEBUG_EVENT * event = (DEBUG_EVENT *)eventp; + LOAD_DLL_DEBUG_INFO * event = ¤t_event.u.LoadDll; DWORD dll_name_ptr; DWORD done; + char dll_buf[MAX_PATH + 1]; + char *p, *dll_name = NULL, *dll_basename; + struct objfile *objfile; + MEMORY_BASIC_INFORMATION minfo; + + dll_buf[0] = dll_buf[sizeof(dll_buf) - 1] = '\0'; + + /* The following code attempts to find the name of the dll by reading the + name from the processes memory. Unfortunately it doesn't work right. + Doing this the "right way" for Windows is very difficult. FIXME */ +#ifdef DOESNT_WORK + memset (&minfo, 0, sizeof minfo); + if (VirtualQueryEx (current_process_handle, (LPCVOID) event->lpBaseOfDll, + &minfo, sizeof(minfo)) && minfo.BaseAddress) { + DWORD len; + IMAGE_DOS_HEADER *hmm0 = (IMAGE_DOS_HEADER *) minfo.BaseAddress; + HMODULE hmm = (HMODULE) (((DWORD) hmm0) + hmm0->e_lfanew); + + if ((len = GetModuleFileName (hmm, dll_buf, MAX_PATH))) + { + dll_name = dll_buf; + dll_name[len] = '\0'; + } + } +#endif - ReadProcessMemory (current_process, - (DWORD) event->u.LoadDll.lpImageName, - (char *) &dll_name_ptr, - sizeof (dll_name_ptr), &done); - - /* See if we could read the address of a string, and that the - address isn't null. */ - - if (done == sizeof (dll_name_ptr) && dll_name_ptr) + /* Attempt to read the name of the dll that was detected. + This is documented to work only when actively debugging + a program. It will not work for attached processes. */ + if (dll_name == NULL || *dll_name == '\0') { - char *dll_name, *dll_basename; - struct objfile *objfile; - char unix_dll_name[MAX_PATH]; - int size = event->u.LoadDll.fUnicode ? sizeof (WCHAR) : sizeof (char); + int size = event->fUnicode ? sizeof (WCHAR) : sizeof (char); int len = 0; char b[2]; + + ReadProcessMemory (current_process_handle, + (LPCVOID) event->lpImageName, + (char *) &dll_name_ptr, + sizeof (dll_name_ptr), &done); + + /* See if we could read the address of a string, and that the + address isn't null. */ + + if (done != sizeof (dll_name_ptr) || !dll_name_ptr) + return 1; + do { - ReadProcessMemory (current_process, - dll_name_ptr + len * size, + ReadProcessMemory (current_process_handle, + (LPCVOID) (dll_name_ptr + len * size), &b, size, &done); @@ -228,11 +366,11 @@ handle_load_dll (char *eventp) dll_name = alloca (len); - if (event->u.LoadDll.fUnicode) + if (event->fUnicode) { WCHAR *unicode_dll_name = (WCHAR *) alloca (len * sizeof (WCHAR)); - ReadProcessMemory (current_process, - dll_name_ptr, + ReadProcessMemory (current_process_handle, + (LPCVOID) dll_name_ptr, unicode_dll_name, len * sizeof (WCHAR), &done); @@ -243,211 +381,273 @@ handle_load_dll (char *eventp) } else { - ReadProcessMemory (current_process, - dll_name_ptr, + ReadProcessMemory (current_process_handle, + (LPCVOID) dll_name_ptr, dll_name, len, &done); } - - /* FIXME: Can we delete this call? */ - cygwin32_conv_to_posix_path (dll_name, unix_dll_name); - - /* FIXME!! It would be nice to define one symbol which pointed to the - front of the dll if we can't find any symbols. */ - - if (!(dll_basename = strrchr(dll_name, '\\'))) - dll_basename = strrchr(dll_name, '/'); - - ALL_OBJFILES(objfile) - { - char *objfile_basename; - if (!(objfile_basename = strrchr(objfile->name, '\\'))) - objfile_basename = strrchr(objfile->name, '/'); - - if (dll_basename && objfile_basename && - strcmp(dll_basename+1, objfile_basename+1) == 0) - { - printf_unfiltered ("%s (symbols previously loaded)\n", - dll_basename + 1); - return 1; - } - } - - context.ContextFlags = CONTEXT_FULL | CONTEXT_FLOATING_POINT; - GetThreadContext (current_thread, &context); - - /* The symbols in a dll are offset by 0x1000, which is the - the offset from 0 of the first byte in an image - because - of the file header and the section alignment. - - FIXME: Is this the real reason that we need the 0x1000 ? */ - - - symbol_file_add (unix_dll_name, 0, - (int) event->u.LoadDll.lpBaseOfDll + 0x1000, 0, 0, 0); - - printf_unfiltered ("%x:%s\n", event->u.LoadDll.lpBaseOfDll, - unix_dll_name); } + + if (!dll_name) + return 1; + + while ((p = strchr (dll_name, '\\'))) + *p = '/'; + + /* FIXME!! It would be nice to define one symbol which pointed to the + front of the dll if we can't find any symbols. */ + + if (!(dll_basename = strrchr(dll_name, '/'))) + dll_basename = dll_name; + else + dll_basename++; + + ALL_OBJFILES(objfile) + { + char *objfile_basename; + objfile_basename = strrchr(objfile->name, '/'); + + if (objfile_basename && + strcmp(dll_basename, objfile_basename + 1) == 0) + { + printf_unfiltered ("%x:%s (symbols previously loaded)\n", + event->lpBaseOfDll, dll_name); + goto out; + } + } + + /* The symbols in a dll are offset by 0x1000, which is the + the offset from 0 of the first byte in an image - because + of the file header and the section alignment. + + FIXME: Is this the real reason that we need the 0x1000 ? */ + + printf_unfiltered ("%x:%s", event->lpBaseOfDll, dll_name); + symbol_file_add (dll_name, 0, (int) event->lpBaseOfDll + 0x1000, 0, 0, 0); + printf_unfiltered ("\n"); + +out: return 1; } +/* Handle DEBUG_STRING output from child process. + Cygwin prepends its messages with a "cygwin:". Interpret this as + a Cygwin signal. Otherwise just print the string as a warning. */ +static int +handle_output_debug_string (struct target_waitstatus *ourstatus) +{ + char *s; + int gotasig = FALSE; + + if (!target_read_string + ((CORE_ADDR) current_event.u.DebugString.lpDebugStringData, &s, 1024, 0) + || !s || !*s) + return gotasig; + + if (strncmp(s, CYGWIN_SIGNAL_STRING, sizeof(CYGWIN_SIGNAL_STRING) - 1)) + { + warning (s); + } + else + { + char *p; + /*last_sig = */strtol(s + sizeof(CYGWIN_SIGNAL_STRING) - 1, &p, 0); + if (gotasig = (ourstatus->value.sig = target_signal_from_host (last_sig))) + ourstatus->kind = TARGET_WAITKIND_STOPPED; + } + + free (s); + return gotasig; +} static int -handle_exception (DEBUG_EVENT * event, struct target_waitstatus *ourstatus) +handle_exception (struct target_waitstatus *ourstatus) { int i; int done = 0; + thread_info *th; + ourstatus->kind = TARGET_WAITKIND_STOPPED; + /* Record the context of the current thread */ + th = thread_rec (current_event.dwThreadId, -1); - switch (event->u.Exception.ExceptionRecord.ExceptionCode) + switch (current_event.u.Exception.ExceptionRecord.ExceptionCode) { case EXCEPTION_ACCESS_VIOLATION: DEBUG_EXCEPT (("gdb: Target exception ACCESS_VIOLATION at 0x%08x\n", - event->u.Exception.ExceptionRecord.ExceptionAddress)); + current_event.u.Exception.ExceptionRecord.ExceptionAddress)); ourstatus->value.sig = TARGET_SIGNAL_SEGV; break; case STATUS_STACK_OVERFLOW: DEBUG_EXCEPT (("gdb: Target exception STACK_OVERFLOW at 0x%08x\n", - event->u.Exception.ExceptionRecord.ExceptionAddress)); + current_event.u.Exception.ExceptionRecord.ExceptionAddress)); ourstatus->value.sig = TARGET_SIGNAL_SEGV; break; case EXCEPTION_BREAKPOINT: DEBUG_EXCEPT (("gdb: Target exception BREAKPOINT at 0x%08x\n", - event->u.Exception.ExceptionRecord.ExceptionAddress)); + current_event.u.Exception.ExceptionRecord.ExceptionAddress)); ourstatus->value.sig = TARGET_SIGNAL_TRAP; break; case DBG_CONTROL_C: DEBUG_EXCEPT (("gdb: Target exception CONTROL_C at 0x%08x\n", - event->u.Exception.ExceptionRecord.ExceptionAddress)); + current_event.u.Exception.ExceptionRecord.ExceptionAddress)); ourstatus->value.sig = TARGET_SIGNAL_INT; + /* User typed CTRL-C. Continue with this status */ + last_sig = SIGINT; /* FIXME - should check pass state */ break; case EXCEPTION_SINGLE_STEP: DEBUG_EXCEPT (("gdb: Target exception SINGLE_STEP at 0x%08x\n", - event->u.Exception.ExceptionRecord.ExceptionAddress)); + current_event.u.Exception.ExceptionRecord.ExceptionAddress)); ourstatus->value.sig = TARGET_SIGNAL_TRAP; break; default: /* This may be a structured exception handling exception. In - that case, we want to let the program try to handle it, and - only break if we see the exception a second time. */ - if (event->u.Exception.dwFirstChance) + that case, we want to let the program try to handle it, and + only break if we see the exception a second time. */ + if (current_event.u.Exception.dwFirstChance) return 0; printf_unfiltered ("gdb: unknown target exception 0x%08x at 0x%08x\n", - event->u.Exception.ExceptionRecord.ExceptionCode, - event->u.Exception.ExceptionRecord.ExceptionAddress); + current_event.u.Exception.ExceptionRecord.ExceptionCode, + current_event.u.Exception.ExceptionRecord.ExceptionAddress); ourstatus->value.sig = TARGET_SIGNAL_UNKNOWN; break; } - context.ContextFlags = CONTEXT_FULL | CONTEXT_FLOATING_POINT; - GetThreadContext (current_thread, &context); exception_count++; return 1; } +/* Resume all artificially suspended threads if we are continuing + execution */ +static BOOL +child_continue (DWORD continue_status, int id) +{ + int i; + thread_info *th; + BOOL res; + + DEBUG_EVENTS (("ContinueDebugEvent (cpid=%d, ctid=%d, DBG_CONTINUE);\n", + current_event.dwProcessId, current_event.dwThreadId)); + if (res = ContinueDebugEvent (current_event.dwProcessId, + current_event.dwThreadId, + continue_status)) + for (th = &thread_head; (th = th->next) != NULL; ) + if (((id == -1) || (id == th->id)) && th->suspend_count) + { + for (i = 0; i < th->suspend_count; i++) + (void) ResumeThread (th->h); + th->suspend_count = 0; + } + + return res; +} + static int child_wait (int pid, struct target_waitstatus *ourstatus) { /* We loop when we get a non-standard exception rather than return with a SPURIOUS because resume can try and step or modify things, - which needs a current_thread. But some of these exceptions mark + which needs a current_thread->h. But some of these exceptions mark the birth or death of threads, which mean that the current thread isn't necessarily what you think it is. */ while (1) { - DEBUG_EVENT event; - BOOL t = WaitForDebugEvent (&event, INFINITE); - char *p; DWORD continue_status; + BOOL t = WaitForDebugEvent (¤t_event, INFINITE); + char *p; + thread_info *th; + int sig; event_count++; - current_thread_id = event.dwThreadId; - current_process_id = event.dwProcessId; - continue_status = DBG_CONTINUE; - switch (event.dwDebugEventCode) + switch (current_event.dwDebugEventCode) { case CREATE_THREAD_DEBUG_EVENT: - DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%x code=%s)\n", + current_event.dwProcessId, current_event.dwThreadId, "CREATE_THREAD_DEBUG_EVENT")); + /* Record the existence of this thread */ + child_add_thread (current_event.dwThreadId, + current_event.u.CreateThread.hThread); + if (info_verbose) + printf_unfiltered ("[New %s]\n", + target_pid_to_str (current_event.dwThreadId)); break; + case EXIT_THREAD_DEBUG_EVENT: DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "EXIT_THREAD_DEBUG_EVENT")); + child_delete_thread (current_event.dwThreadId); break; + case CREATE_PROCESS_DEBUG_EVENT: DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "CREATE_PROCESS_DEBUG_EVENT")); + current_process_handle = current_event.u.CreateProcessInfo.hProcess; + + main_thread_id = inferior_pid = current_event.dwThreadId; + /* Add the main thread */ + current_thread = child_add_thread (inferior_pid, + current_event.u.CreateProcessInfo.hThread); break; case EXIT_PROCESS_DEBUG_EVENT: DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "EXIT_PROCESS_DEBUG_EVENT")); ourstatus->kind = TARGET_WAITKIND_EXITED; - ourstatus->value.integer = event.u.ExitProcess.dwExitCode; - CloseHandle (current_process); - CloseHandle (current_thread); - return current_process_id; + ourstatus->value.integer = current_event.u.ExitProcess.dwExitCode; + CloseHandle (current_process_handle); + return current_event.dwProcessId; break; case LOAD_DLL_DEBUG_EVENT: DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "LOAD_DLL_DEBUG_EVENT")); - catch_errors (handle_load_dll, - (char*) &event, - "\n[failed reading symbols from DLL]\n", - RETURN_MASK_ALL); + catch_errors (handle_load_dll, NULL, "", RETURN_MASK_ALL); registers_changed(); /* mark all regs invalid */ break; + case UNLOAD_DLL_DEBUG_EVENT: DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "UNLOAD_DLL_DEBUG_EVENT")); break; /* FIXME: don't know what to do here */ - case EXCEPTION_DEBUG_EVENT: + + case EXCEPTION_DEBUG_EVENT: DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "EXCEPTION_DEBUG_EVENT")); - if (handle_exception (&event, ourstatus)) - return current_process_id; + if (handle_exception (ourstatus)) + return current_event.dwThreadId; continue_status = DBG_EXCEPTION_NOT_HANDLED; break; case OUTPUT_DEBUG_STRING_EVENT: /* message from the kernel */ DEBUG_EVENTS (("gdb: kernel event for pid=%d tid=%d code=%s)\n", - event.dwProcessId, event.dwThreadId, + current_event.dwProcessId, current_event.dwThreadId, "OUTPUT_DEBUG_STRING_EVENT")); - if (target_read_string - ((CORE_ADDR) event.u.DebugString.lpDebugStringData, - &p, 1024, 0) && p && *p) - { - warning(p); - free(p); - } + if (handle_output_debug_string (ourstatus)) + return main_thread_id; break; default: printf_unfiltered ("gdb: kernel event for pid=%d tid=%d\n", - event.dwProcessId, event.dwThreadId); + current_event.dwProcessId, + current_event.dwThreadId); printf_unfiltered (" unknown event code %d\n", - event.dwDebugEventCode); + current_event.dwDebugEventCode); break; } - DEBUG_EVENTS (("ContinueDebugEvent (cpid=%d, ctid=%d, DBG_CONTINUE);\n", - current_process_id, current_thread_id)); - CHECK (ContinueDebugEvent (current_process_id, - current_thread_id, - continue_status)); + + CHECK (child_continue (continue_status, -1)); } } @@ -463,9 +663,9 @@ child_attach (args, from_tty) if (!args) error_no_arg ("process-id to attach"); - current_process_id = strtoul (args, 0, 0); + current_event.dwProcessId = strtoul (args, 0, 0); - ok = DebugActiveProcess (current_process_id); + ok = DebugActiveProcess (current_event.dwProcessId); if (!ok) error ("Can't attach to process."); @@ -479,15 +679,14 @@ child_attach (args, from_tty) if (exec_file) printf_unfiltered ("Attaching to program `%s', %s\n", exec_file, - target_pid_to_str (current_process_id)); + target_pid_to_str (current_event.dwProcessId)); else printf_unfiltered ("Attaching to %s\n", - target_pid_to_str (current_process_id)); + target_pid_to_str (current_event.dwProcessId)); gdb_flush (gdb_stdout); } - inferior_pid = current_process_id; push_target (&child_ops); } @@ -560,9 +759,9 @@ child_create_inferior (exec_file, allargs, env) memset (&si, 0, sizeof (si)); si.cb = sizeof (si); - cygwin32_conv_to_win32_path (exec_file, real_path); + cygwin_conv_to_win32_path (exec_file, real_path); - flags = DEBUG_ONLY_THIS_PROCESS; + flags = DEBUG_ONLY_THIS_PROCESS; if (new_group) flags |= CREATE_NEW_PROCESS_GROUP; @@ -606,9 +805,9 @@ child_create_inferior (exec_file, allargs, env) len = strlen (conv_path_names[j]); if (strncmp (conv_path_names[j], env[i], len) == 0) { - if (cygwin32_posix_path_list_p (env[i] + len)) + if (cygwin_posix_path_list_p (env[i] + len)) envlen += len - + cygwin32_posix_to_win32_path_list_buf_size (env[i] + len); + + cygwin_posix_to_win32_path_list_buf_size (env[i] + len); else envlen += strlen (env[i]) + 1; break; @@ -621,7 +820,7 @@ child_create_inferior (exec_file, allargs, env) winenv = alloca (envlen + 1); /* Copy env strings into new buffer. */ - for (temp = winenv, i = 0; env[i] && *env[i]; i++) + for (temp = winenv, i = 0; env[i] && *env[i]; i++) { int j, len; @@ -630,10 +829,10 @@ child_create_inferior (exec_file, allargs, env) len = strlen (conv_path_names[j]); if (strncmp (conv_path_names[j], env[i], len) == 0) { - if (cygwin32_posix_path_list_p (env[i] + len)) + if (cygwin_posix_path_list_p (env[i] + len)) { memcpy (temp, env[i], len); - cygwin32_posix_to_win32_path_list (env[i] + len, temp + len); + cygwin_posix_to_win32_path_list (env[i] + len, temp + len); } else strcpy (temp, env[i]); @@ -666,13 +865,12 @@ child_create_inferior (exec_file, allargs, env) exception_count = 0; event_count = 0; - inferior_pid = pi.dwProcessId; - current_process = pi.hProcess; - current_thread = pi.hThread; - current_process_id = pi.dwProcessId; - current_thread_id = pi.dwThreadId; + current_process_handle = pi.hProcess; + current_event.dwProcessId = pi.dwProcessId; + memset (¤t_event, 0, sizeof (current_event)); + inferior_pid = current_event.dwThreadId = pi.dwThreadId; push_target (&child_ops); - init_thread_list (); + child_init_thread_list (); init_wait_for_inferior (); clear_proceed_status (); target_terminal_init (); @@ -687,9 +885,7 @@ child_create_inferior (exec_file, allargs, env) static void child_mourn_inferior () { - (void) ContinueDebugEvent (current_process_id, - current_thread_id, - DBG_CONTINUE); + (void) child_continue (DBG_CONTINUE, -1); unpush_target (&child_ops); generic_mourn_inferior (); } @@ -714,14 +910,16 @@ child_xfer_memory (CORE_ADDR memaddr, char *our, int len, { DEBUG_MEM (("gdb: write target memory, %d bytes at 0x%08x\n", len, memaddr)); - WriteProcessMemory (current_process, memaddr, our, len, &done); - FlushInstructionCache (current_process, memaddr, len); + WriteProcessMemory (current_process_handle, (LPVOID) memaddr, our, + len, &done); + FlushInstructionCache (current_process_handle, (LPCVOID) memaddr, len); } else { DEBUG_MEM (("gdb: read target memory, %d bytes at 0x%08x\n", len, memaddr)); - ReadProcessMemory (current_process, memaddr, our, len, &done); + ReadProcessMemory (current_process_handle, (LPCVOID) memaddr, our, len, + &done); } return done; } @@ -729,59 +927,60 @@ child_xfer_memory (CORE_ADDR memaddr, char *our, int len, void child_kill_inferior (void) { - CHECK (TerminateProcess (current_process, 0)); - + CHECK (TerminateProcess (current_process_handle, 0)); + for (;;) { - DEBUG_EVENT event; - if (!ContinueDebugEvent (current_process_id, - current_thread_id, - DBG_CONTINUE)) + if (!child_continue (DBG_CONTINUE, -1)) break; - if (!WaitForDebugEvent (&event, INFINITE)) + if (!WaitForDebugEvent (¤t_event, INFINITE)) break; - current_thread_id = event.dwThreadId; - current_process_id = event.dwProcessId; - if (event.dwDebugEventCode == EXIT_PROCESS_DEBUG_EVENT) + if (current_event.dwDebugEventCode == EXIT_PROCESS_DEBUG_EVENT) break; } - CHECK (CloseHandle (current_process)); - CHECK (CloseHandle (current_thread)); + CHECK (CloseHandle (current_process_handle)); + + /* this may fail in an attached process so don't check. */ + (void) CloseHandle (current_thread->h); target_mourn_inferior(); /* or just child_mourn_inferior? */ } void -child_resume (int pid, int step, enum target_signal signal) +child_resume (int pid, int step, enum target_signal sig) { - DEBUG_EXEC (("gdb: child_resume (pid=%d, step=%d, signal=%d);\n", - pid, step, signal)); + int i; + thread_info *th; + DWORD continue_status = last_sig > 0 && last_sig < NSIG ? + DBG_EXCEPTION_NOT_HANDLED : DBG_CONTINUE; + DEBUG_EXEC (("gdb: child_resume (pid=%d, step=%d, sig=%d);\n", + pid, step, sig)); + + /* Get context for currently selected thread */ + th = thread_rec (current_event.dwThreadId, FALSE); if (step) { #ifdef i386 /* Single step by setting t bit */ child_fetch_inferior_registers (PS_REGNUM); - context.EFlags |= FLAG_TRACE_BIT; + th->context.EFlags |= FLAG_TRACE_BIT; #endif } - if (context.ContextFlags) + if (th->context.ContextFlags) { - CHECK (SetThreadContext (current_thread, &context)); - context.ContextFlags = 0; + CHECK (SetThreadContext (th->h, &th->context)); + th->context.ContextFlags = 0; } - if (signal) - { - fprintf_unfiltered (gdb_stderr, "Can't send signals to the child.\n"); - } + /* Allow continuing with the same signal that interrupted us. + Otherwise complain. */ + if (sig && sig != last_sig) + fprintf_unfiltered (gdb_stderr, "Can't send signals to the child. signal %d\n", sig); - DEBUG_EVENTS (("gdb: ContinueDebugEvent (cpid=%d, ctid=%d, DBG_CONTINUE);\n", - current_process_id, current_thread_id)); - CHECK (ContinueDebugEvent (current_process_id, - current_thread_id, - DBG_CONTINUE)); + last_sig = 0; + child_continue (continue_status, pid); } static void @@ -806,45 +1005,45 @@ struct target_ops child_ops ; static void init_child_ops(void) { - child_ops.to_shortname = "child"; + child_ops.to_shortname = "child"; child_ops.to_longname = "Win32 child process"; - child_ops.to_doc = "Win32 child process (started by the \"run\" command)."; - child_ops.to_open = child_open; - child_ops.to_close = child_close; - child_ops.to_attach = child_attach; - child_ops.to_detach = child_detach; - child_ops.to_resume = child_resume; - child_ops.to_wait = child_wait; + child_ops.to_doc = "Win32 child process (started by the \"run\" command)."; + child_ops.to_open = child_open; + child_ops.to_close = child_close; + child_ops.to_attach = child_attach; + child_ops.to_detach = child_detach; + child_ops.to_resume = child_resume; + child_ops.to_wait = child_wait; child_ops.to_fetch_registers = child_fetch_inferior_registers; child_ops.to_store_registers = child_store_inferior_registers; - child_ops.to_prepare_to_store = child_prepare_to_store; - child_ops.to_xfer_memory = child_xfer_memory; - child_ops.to_files_info = child_files_info; + child_ops.to_prepare_to_store = child_prepare_to_store; + child_ops.to_xfer_memory = child_xfer_memory; + child_ops.to_files_info = child_files_info; child_ops.to_insert_breakpoint = memory_insert_breakpoint; child_ops.to_remove_breakpoint = memory_remove_breakpoint; child_ops.to_terminal_init = terminal_init_inferior; - child_ops.to_terminal_inferior = terminal_inferior; + child_ops.to_terminal_inferior = terminal_inferior; child_ops.to_terminal_ours_for_output = terminal_ours_for_output; - child_ops.to_terminal_ours = terminal_ours; - child_ops.to_terminal_info = child_terminal_info; - child_ops.to_kill = child_kill_inferior; - child_ops.to_load = 0; - child_ops.to_lookup_symbol = 0; + child_ops.to_terminal_ours = terminal_ours; + child_ops.to_terminal_info = child_terminal_info; + child_ops.to_kill = child_kill_inferior; + child_ops.to_load = 0; + child_ops.to_lookup_symbol = 0; child_ops.to_create_inferior = child_create_inferior; - child_ops.to_mourn_inferior = child_mourn_inferior; - child_ops.to_can_run = child_can_run; - child_ops.to_notice_signals = 0; - child_ops.to_thread_alive = 0; - child_ops.to_stop = child_stop; + child_ops.to_mourn_inferior = child_mourn_inferior; + child_ops.to_can_run = child_can_run; + child_ops.to_notice_signals = 0; + child_ops.to_thread_alive = child_thread_alive; + child_ops.to_stop = child_stop; child_ops.to_stratum = process_stratum; - child_ops.DONT_USE = 0; - child_ops.to_has_all_memory = 1; - child_ops.to_has_memory = 1; - child_ops.to_has_stack = 1; - child_ops.to_has_registers = 1; - child_ops.to_has_execution = 1; - child_ops.to_sections = 0; - child_ops.to_sections_end = 0; + child_ops.DONT_USE = 0; + child_ops.to_has_all_memory = 1; + child_ops.to_has_memory = 1; + child_ops.to_has_stack = 1; + child_ops.to_has_registers = 1; + child_ops.to_has_execution = 1; + child_ops.to_sections = 0; + child_ops.to_sections_end = 0; child_ops.to_magic = OPS_MAGIC; } @@ -898,3 +1097,25 @@ _initialize_inftarg () add_target (&child_ops); } + +/* Determine if the thread referenced by "pid" is alive + by "polling" it. If WaitForSingleObject returns WAIT_OBJECT_0 + it means that the pid has died. Otherwise it is assumed to be alive. */ +static int +child_thread_alive (int pid) +{ + return WaitForSingleObject(thread_rec (pid, FALSE)->h, 0) == WAIT_OBJECT_0 ? + FALSE : TRUE; +} + +/* Convert pid to printable format. */ +char * +cygwin_pid_to_str (int pid) +{ + static char buf[80]; + if (pid == current_event.dwProcessId) + sprintf (buf, "process %d", pid); + else + sprintf (buf, "thread %d.0x%x", current_event.dwProcessId, pid); + return buf; +} -- 2.30.2