X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdbint.texinfo;h=db293ef55c801f0051aa25a381ab4ec439d7fe47;hb=db034ac5129e86e2dfccebe047f0ee50fd933ec9;hp=4d353156bfd117144751045b6808de1c8df09009;hpb=8cc1c08ffc161b167ff33ac32cda5b4c77d03bfd;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 4d353156bf..433844aa00 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -1,468 +1,1940 @@ -\input texinfo +\input texinfo @c -*- texinfo -*- @setfilename gdbint.info -@c $Id$ +@include gdb-cfg.texi +@dircategory Programming & development tools. +@direntry +* Gdb-Internals: (gdbint). The GNU debugger's internals. +@end direntry @ifinfo -@format -START-INFO-DIR-ENTRY -* Gdb Internals: (gdbint). The GNU debugger internals. -END-INFO-DIR-ENTRY -@end format +This file documents the internals of the GNU debugger @value{GDBN}. +Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002 + Free Software Foundation, Inc. +Contributed by Cygnus Solutions. Written by John Gilmore. +Second Edition by Stan Shebs. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' @end ifinfo -@ifinfo -This file documents the internals of the GNU debugger GDB. - -Copyright (C) 1990, 1991 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by John Gilmore. - -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). +@setchapternewpage off +@settitle @value{GDBN} Internals -@end ignore -Permission is granted to copy or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). -@end ifinfo +@syncodeindex fn cp +@syncodeindex vr cp -@setchapternewpage off -@settitle GDB Internals @titlepage -@title{Working in GDB} +@title @value{GDBN} 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, 1991 Free Software Foundation, Inc. +Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, 2002 + Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end titlepage -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. +@contents -@end titlepage +@node Top +@c Perhaps this should be the title of the document (but only for info, +@c not for TeX). Existing GNU manuals seem inconsistent on this point. +@top Scope of this Document -@node Top, README, (dir), (dir) +This document documents the internals of the GNU debugger, @value{GDBN}. It +includes description of @value{GDBN}'s key algorithms and operations, as well +as the mechanisms that adapt @value{GDBN} to specific hosts and targets. @menu -* README:: The README File -* New Architectures:: Defining a New Host or Target Architecture -* Config:: Adding a New Configuration -* Host:: Adding a New Host -* Target:: Adding a New Target -* Languages:: Defining New Source Languages -* Releases:: Configuring GDB for Release -* 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 - +* Requirements:: +* Overall Structure:: +* Algorithms:: +* User Interface:: +* libgdb:: +* Symbol Handling:: +* Language Support:: +* Host Definition:: +* Target Architecture Definition:: +* Target Vector Definition:: +* Native Debugging:: +* Support Libraries:: +* Coding:: +* Porting GDB:: +* Releasing GDB:: +* Testsuite:: +* Hints:: + +* GNU Free Documentation License:: The license for this documentation +* Index:: @end menu -@node README, New Architectures, Top, Top -@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 +@cindex requirements for @value{GDBN} +Before diving into the internals, you should understand the formal +requirements and other expectations for @value{GDBN}. Although some +of these may seem obvious, there have been proposals for @value{GDBN} +that have run counter to these requirements. -@node New Architectures, Config, README, Top -@chapter Defining a New Host or Target Architecture +First of all, @value{GDBN} 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. -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. +@value{GDBN} is an interactive tool. Although a batch mode is +available, @value{GDBN}'s primary role is to interact with a human +programmer. -@heading What is considered ``host-dependent'' versus ``target-dependent''? +@value{GDBN} 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. -@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; unfortunately, that -means you must add @emph{both} host and target support for new machines -in this category. +@value{GDBN} 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. + +@value{GDBN} 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. + +@value{GDBN} should be able to run everywhere. No other debugger is +available for even half as many configurations as @value{GDBN} +supports. -The @file{config/mh-*}, @file{xm-*.h} and @file{*-xdep.c} files are for -host support. Similarly, the @file{config/mt-*}, @file{tm-*.h} and -@file{*-tdep.c} files are for target support. The question is, what -features or aspects of a debugging or cross-debugging environment are -considered to be ``host'' support? + +@node Overall Structure + +@chapter Overall Structure + +@value{GDBN} consists of three major subsystems: user interface, +symbol handling (the @dfn{symbol side}), and target system handling (the +@dfn{target side}). + +The user interface consists of several actual interfaces, plus +supporting code. + +The symbol side consists of object file readers, debugging info +interpreters, symbol table management, source language expression +parsing, type and value printing. + +The target side consists of execution control, stack frame analysis, and +physical target manipulation. + +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. + +@section The Symbol Side + +The symbolic side of @value{GDBN} can be thought of as ``everything +you can do in @value{GDBN} 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 + +The target side of @value{GDBN} 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. + +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, @value{GDBN} will use symbolic info to present addresses +relative to symbols rather than as raw numbers, but it will work either +way. + +@section Configurations + +@cindex host +@cindex target +@dfn{Host} refers to attributes of the system where @value{GDBN} 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. Defines and include files needed to build on the host are host support. Examples are tty support, system defined types, host byte order, host float format. -Unix child process support is considered an aspect of the host. Since -when you fork on the host you are still on the host, the various macros -needed for finding the registers in the upage, running @code{ptrace}, and such -are all in the host-dependent files. +Defines and information needed to handle the target format are target +dependent. Examples are the stack frame format, instruction set, +breakpoint instruction, registers, and how to set up and tear down the stack +to call a function. + +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. + +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 @value{GDBN} work ``native'' on a particular machine, you +have to include all three kinds of information. + + +@node Algorithms + +@chapter Algorithms +@cindex algorithms + +@value{GDBN} 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. + +@section Frames + +@cindex frame +@cindex call stack frame +A frame is a construct that @value{GDBN} uses to keep track of calling +and called functions. + +@findex create_new_frame +@vindex FRAME_FP +@code{FRAME_FP} in the machine description has no meaning to the +machine-independent part of @value{GDBN}, except that it is used when +setting up a new frame from scratch, as follows: + +@smallexample +create_new_frame (read_register (FP_REGNUM), read_pc ())); +@end smallexample + +@cindex frame pointer register +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.) + +@cindex frame chain +Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the +address of the calling function's frame. This will be used to create +a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO} +and @code{INIT_FRAME_PC} will be called for the new frame. + +@section Breakpoint Handling + +@cindex breakpoints +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. + +@cindex hardware breakpoints +@cindex program counter +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 +(shorthand for @dfn{program counter}) +ever matches a value in a breakpoint registers, the CPU raises an +exception and reports it to @value{GDBN}. + +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 @value{GDBN}'s point of view they work the same; +@value{GDBN} 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, @value{GDBN} will +start trying to set software breakpoints. (On some architectures, +notably the 32-bit x86 platforms, @value{GDBN} cannot always know +whether there's enough hardware resources to insert all the hardware +breakpoints and watchpoints. On those platforms, @value{GDBN} prints +an error message only when the program being debugged is continued.) + +@cindex software breakpoints +Software breakpoints require @value{GDBN} to do somewhat more work. +The basic theory is that @value{GDBN} will replace a program +instruction with a trap, illegal divide, or some other instruction +that will cause an exception, and then when it's encountered, +@value{GDBN} will take the exception and stop the program. When the +user says to continue, @value{GDBN} 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 writable, so this technique won't work on programs in ROM. It +can also distort the behavior of programs that examine themselves, +although such a 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. + +@findex BREAKPOINT +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 + +@cindex @code{longjmp} debugging +@value{GDBN} 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 output of the @samp{maint info breakpoint} +command. + +@findex GET_LONGJMP_TARGET +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{target}.h} file. Look in @file{tm-sun4os4.h} and +@file{sparc-tdep.c} for examples of how to do this. + +@section Watchpoints +@cindex watchpoints + +Watchpoints are a special kind of breakpoints (@pxref{Algorithms, +breakpoints}) which break when data is accessed rather than when some +instruction is executed. When you have data which changes without +your knowing what code does that, watchpoints are the silver bullet to +hunt down and kill such bugs. + +@cindex hardware watchpoints +@cindex software watchpoints +Watchpoints can be either hardware-assisted or not; the latter type is +known as ``software watchpoints.'' @value{GDBN} always uses +hardware-assisted watchpoints if they are available, and falls back on +software watchpoints otherwise. Typical situations where @value{GDBN} +will use software watchpoints are: + +@itemize @bullet +@item +The watched memory region is too large for the underlying hardware +watchpoint support. For example, each x86 debug register can watch up +to 4 bytes of memory, so trying to watch data structures whose size is +more than 16 bytes will cause @value{GDBN} to use software +watchpoints. + +@item +The value of the expression to be watched depends on data held in +registers (as opposed to memory). + +@item +Too many different watchpoints requested. (On some architectures, +this situation is impossible to detect until the debugged program is +resumed.) Note that x86 debug registers are used both for hardware +breakpoints and for watchpoints, so setting too many hardware +breakpoints might cause watchpoint insertion to fail. + +@item +No hardware-assisted watchpoints provided by the target +implementation. +@end itemize -@c FIXME so what kinds of things are target support? +Software watchpoints are very slow, since @value{GDBN} needs to +single-step the program being debugged and test the value of the +watched expression(s) after each instruction. The rest of this +section is mostly irrelevant for software watchpoints. -This is still somewhat of a grey area; I (John Gilmore) didn't do the -@file{xm-*} and @file{tm-*} split for gdb (it was done by Jim Kingdon) -so I have had to figure out the grounds on which it was split, and make -my own choices as I evolve it. I have moved many things out of the xdep -files actually, partly as a result of BFD and partly by removing -duplicated code. +@value{GDBN} uses several macros and primitives to support hardware +watchpoints: +@table @code +@findex TARGET_HAS_HARDWARE_WATCHPOINTS +@item TARGET_HAS_HARDWARE_WATCHPOINTS +If defined, the target supports hardware watchpoints. + +@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT +@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other}) +Return the number of hardware watchpoints of type @var{type} that are +possible to be set. The value is positive if @var{count} watchpoints +of this type can be set, zero if setting watchpoints of this type is +not supported, and negative if @var{count} is more than the maximum +number of watchpoints of type @var{type} that can be set. @var{other} +is non-zero if other types of watchpoints are currently enabled (there +are architectures which cannot set watchpoints of different types at +the same time). + +@findex TARGET_REGION_OK_FOR_HW_WATCHPOINT +@item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len}) +Return non-zero if hardware watchpoints can be used to watch a region +whose address is @var{addr} and whose length in bytes is @var{len}. + +@findex TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT +@item TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (@var{size}) +Return non-zero if hardware watchpoints can be used to watch a region +whose size is @var{size}. @value{GDBN} only uses this macro as a +fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not +defined. + +@findex TARGET_DISABLE_HW_WATCHPOINTS +@item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid}) +Disables watchpoints in the process identified by @var{pid}. This is +used, e.g., on HP-UX which provides operations to disable and enable +the page-level memory protection that implements hardware watchpoints +on that platform. + +@findex TARGET_ENABLE_HW_WATCHPOINTS +@item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid}) +Enables watchpoints in the process identified by @var{pid}. This is +used, e.g., on HP-UX which provides operations to disable and enable +the page-level memory protection that implements hardware watchpoints +on that platform. + +@findex target_insert_watchpoint +@findex target_remove_watchpoint +@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type}) +@itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type}) +Insert or remove a hardware watchpoint starting at @var{addr}, for +@var{len} bytes. @var{type} is the watchpoint type, one of the +possible values of the enumerated data type @code{target_hw_bp_type}, +defined by @file{breakpoint.h} as follows: + +@smallexample + enum target_hw_bp_type + @{ + hw_write = 0, /* Common (write) HW watchpoint */ + hw_read = 1, /* Read HW watchpoint */ + hw_access = 2, /* Access (read or write) HW watchpoint */ + hw_execute = 3 /* Execute HW breakpoint */ + @}; +@end smallexample -@node Config, Host, New Architectures, Top -@chapter Adding a New Configuration +@noindent +These two macros should return 0 for success, non-zero for failure. + +@cindex insert or remove hardware breakpoint +@findex target_remove_hw_breakpoint +@findex target_insert_hw_breakpoint +@item target_remove_hw_breakpoint (@var{addr}, @var{shadow}) +@itemx target_insert_hw_breakpoint (@var{addr}, @var{shadow}) +Insert or remove a hardware-assisted breakpoint at address @var{addr}. +Returns zero for success, non-zero for failure. @var{shadow} is the +real contents of the byte where the breakpoint has been inserted; it +is generally not valid when hardware breakpoints are used, but since +no other code touches these values, the implementations of the above +two macros can use them for their internal purposes. + +@findex target_stopped_data_address +@item target_stopped_data_address () +If the inferior has some watchpoint that triggered, return the address +associated with that watchpoint. Otherwise, return zero. + +@findex DECR_PC_AFTER_HW_BREAK +@item DECR_PC_AFTER_HW_BREAK +If defined, @value{GDBN} decrements the program counter by the value +of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This +overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint +that breaks is a hardware-assisted breakpoint. + +@findex HAVE_STEPPABLE_WATCHPOINT +@item HAVE_STEPPABLE_WATCHPOINT +If defined to a non-zero value, it is not necessary to disable a +watchpoint to step over it. + +@findex HAVE_NONSTEPPABLE_WATCHPOINT +@item HAVE_NONSTEPPABLE_WATCHPOINT +If defined to a non-zero value, @value{GDBN} should disable a +watchpoint to step the inferior over it. + +@findex HAVE_CONTINUABLE_WATCHPOINT +@item HAVE_CONTINUABLE_WATCHPOINT +If defined to a non-zero value, it is possible to continue the +inferior after a watchpoint has been hit. + +@findex CANNOT_STEP_HW_WATCHPOINTS +@item CANNOT_STEP_HW_WATCHPOINTS +If this is defined to a non-zero value, @value{GDBN} will remove all +watchpoints before stepping the inferior. + +@findex STOPPED_BY_WATCHPOINT +@item STOPPED_BY_WATCHPOINT (@var{wait_status}) +Return non-zero if stopped by a watchpoint. @var{wait_status} is of +the type @code{struct target_waitstatus}, defined by @file{target.h}. +@end table -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: +@subsection x86 Watchpoints +@cindex x86 debug registers +@cindex watchpoints, on x86 -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 +The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug +registers designed to facilitate debugging. @value{GDBN} provides a +generic library of functions that x86-based ports can use to implement +support for watchpoints and hardware-assisted breakpoints. This +subsection documents the x86 watchpoint facilities in @value{GDBN}. + +To use the generic x86 watchpoint support, a port should do the +following: + +@itemize @bullet +@findex I386_USE_GENERIC_WATCHPOINTS +@item +Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the +target-dependent headers. + +@item +Include the @file{config/i386/nm-i386.h} header file @emph{after} +defining @code{I386_USE_GENERIC_WATCHPOINTS}. + +@item +Add @file{i386-nat.o} to the value of the Make variable +@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or +@code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}). + +@item +Provide implementations for the @code{I386_DR_LOW_*} macros described +below. Typically, each macro should call a target-specific function +which does the real work. +@end itemize + +The x86 watchpoint support works by maintaining mirror images of the +debug registers. Values are copied between the mirror images and the +real debug registers via a set of macros which each target needs to +provide: + +@table @code +@findex I386_DR_LOW_SET_CONTROL +@item I386_DR_LOW_SET_CONTROL (@var{val}) +Set the Debug Control (DR7) register to the value @var{val}. + +@findex I386_DR_LOW_SET_ADDR +@item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr}) +Put the address @var{addr} into the debug register number @var{idx}. + +@findex I386_DR_LOW_RESET_ADDR +@item I386_DR_LOW_RESET_ADDR (@var{idx}) +Reset (i.e.@: zero out) the address stored in the debug register +number @var{idx}. + +@findex I386_DR_LOW_GET_STATUS +@item I386_DR_LOW_GET_STATUS +Return the value of the Debug Status (DR6) register. This value is +used immediately after it is returned by +@code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status +register values. +@end table + +For each one of the 4 debug registers (whose indices are from 0 to 3) +that store addresses, a reference count is maintained by @value{GDBN}, +to allow sharing of debug registers by several watchpoints. This +allows users to define several watchpoints that watch the same +expression, but with different conditions and/or commands, without +wasting debug registers which are in short supply. @value{GDBN} +maintains the reference counts internally, targets don't have to do +anything to use this feature. + +The x86 debug registers can each watch a region that is 1, 2, or 4 +bytes long. The ia32 architecture requires that each watched region +be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte +region on 4-byte boundary. However, the x86 watchpoint support in +@value{GDBN} can watch unaligned regions and regions larger than 4 +bytes (up to 16 bytes) by allocating several debug registers to watch +a single region. This allocation of several registers per a watched +region is also done automatically without target code intervention. + +The generic x86 watchpoint support provides the following API for the +@value{GDBN}'s application code: + +@table @code +@findex i386_region_ok_for_watchpoint +@item i386_region_ok_for_watchpoint (@var{addr}, @var{len}) +The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call +this function. It counts the number of debug registers required to +watch a given region, and returns a non-zero value if that number is +less than 4, the number of debug registers available to x86 +processors. + +@findex i386_stopped_data_address +@item i386_stopped_data_address (void) +The macros @code{STOPPED_BY_WATCHPOINT} and +@code{target_stopped_data_address} are set to call this function. The +argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This +function examines the breakpoint condition bits in the DR6 Debug +Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} +macro, and returns the address associated with the first bit that is +set in DR6. + +@findex i386_insert_watchpoint +@findex i386_remove_watchpoint +@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type}) +@itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type}) +Insert or remove a watchpoint. The macros +@code{target_insert_watchpoint} and @code{target_remove_watchpoint} +are set to call these functions. @code{i386_insert_watchpoint} first +looks for a debug register which is already set to watch the same +region for the same access types; if found, it just increments the +reference count of that debug register, thus implementing debug +register sharing between watchpoints. If no such register is found, +the function looks for a vacant debug register, sets its mirrored +value to @var{addr}, sets the mirrored value of DR7 Debug Control +register as appropriate for the @var{len} and @var{type} parameters, +and then passes the new values of the debug register and DR7 to the +inferior by calling @code{I386_DR_LOW_SET_ADDR} and +@code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is +required to cover the given region, the above process is repeated for +each debug register. + +@code{i386_remove_watchpoint} does the opposite: it resets the address +in the mirrored value of the debug register and its read/write and +length bits in the mirrored value of DR7, then passes these new +values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and +@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several +watchpoints, each time a @code{i386_remove_watchpoint} is called, it +decrements the reference count, and only calls +@code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when +the count goes to zero. + +@findex i386_insert_hw_breakpoint +@findex i386_remove_hw_breakpoint +@item i386_insert_hw_breakpoint (@var{addr}, @var{shadow} +@itemx i386_remove_hw_breakpoint (@var{addr}, @var{shadow}) +These functions insert and remove hardware-assisted breakpoints. The +macros @code{target_insert_hw_breakpoint} and +@code{target_remove_hw_breakpoint} are set to call these functions. +These functions work like @code{i386_insert_watchpoint} and +@code{i386_remove_watchpoint}, respectively, except that they set up +the debug registers to watch instruction execution, and each +hardware-assisted breakpoint always requires exactly one debug +register. + +@findex i386_stopped_by_hwbp +@item i386_stopped_by_hwbp (void) +This function returns non-zero if the inferior has some watchpoint or +hardware breakpoint that triggered. It works like +@code{i386_stopped_data_address}, except that it doesn't return the +address whose watchpoint triggered. + +@findex i386_cleanup_dregs +@item i386_cleanup_dregs (void) +This function clears all the reference counts, addresses, and control +bits in the mirror images of the debug registers. It doesn't affect +the actual debug registers in the inferior process. +@end table -@example -./config.sub @var{xxx} -@end example @noindent -and -@example -./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}} -@end example +@strong{Notes:} +@enumerate 1 +@item +x86 processors support setting watchpoints on I/O reads or writes. +However, since no target supports this (as of March 2001), and since +@code{enum target_hw_bp_type} doesn't even have an enumeration for I/O +watchpoints, this feature is not yet available to @value{GDBN} running +on x86. + +@item +x86 processors can enable watchpoints locally, for the current task +only, or globally, for all the tasks. For each debug register, +there's a bit in the DR7 Debug Control register that determines +whether the associated address is watched locally or globally. The +current implementation of x86 watchpoint support in @value{GDBN} +always sets watchpoints to be locally enabled, since global +watchpoints might interfere with the underlying OS and are probably +unavailable in many platforms. +@end enumerate + +@node User Interface + +@chapter User Interface + +@value{GDBN} has several user interfaces. Although the command-line interface +is the most common and most familiar, there are others. + +@section Command Interpreter + +@cindex command interpreter +@cindex CLI +The command interpreter in @value{GDBN} 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. + +For instance, the @samp{set} command just starts a lookup on the +@code{setlist} command list, while @samp{set thread} recurses +to the @code{set_thread_cmd_list}. + +@findex add_cmd +@findex add_com +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. + +@findex add_setshow_cmd +@findex add_setshow_cmd_full +To add paired @samp{set} and @samp{show} commands, use +@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is +a slightly simpler interface which is useful when you don't need to +further modify the new command structures, while the latter returns +the new command structures for manipulation. + +@cindex deprecating commands +@findex deprecate_cmd +Before removing commands from the command set it is a good idea to +deprecate them for some time. Use @code{deprecate_cmd} on commands or +aliases to set the deprecated flag. @code{deprecate_cmd} takes a +@code{struct cmd_list_element} as it's first argument. You can use the +return value from @code{add_com} or @code{add_cmd} to deprecate the +command immediately after it is created. + +The first time a command is used the user will be warned and offered a +replacement (if one exists). Note that the replacement string passed to +@code{deprecate_cmd} should be the full name of the command, i.e. the +entire string the user should type at the command line. + +@section UI-Independent Output---the @code{ui_out} Functions +@c This section is based on the documentation written by Fernando +@c Nasser . + +@cindex @code{ui_out} functions +The @code{ui_out} functions present an abstraction level for the +@value{GDBN} output code. They hide the specifics of different user +interfaces supported by @value{GDBN}, and thus free the programmer +from the need to write several versions of the same code, one each for +every UI, to produce output. + +@subsection Overview and Terminology + +In general, execution of each @value{GDBN} command produces some sort +of output, and can even generate an input request. + +Output can be generated for the following purposes: + +@itemize @bullet +@item +to display a @emph{result} of an operation; + +@item +to convey @emph{info} or produce side-effects of a requested +operation; + +@item +to provide a @emph{notification} of an asynchronous event (including +progress indication of a prolonged asynchronous operation); + +@item +to display @emph{error messages} (including warnings); + +@item +to show @emph{debug data}; + +@item +to @emph{query} or prompt a user for input (a special case). +@end itemize + @noindent -which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}} -and no error messages. +This section mainly concentrates on how to build result output, +although some of it also applies to other kinds of output. -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 GDB. - -Then edit @file{bfd/configure.in}. Add shell script code 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. - -Also, if this host requires any changes to the Makefile, create a file -@file{bfd/config/mh-@var{xxx}}, which includes the required lines. - -(If you have the binary utilities and/or GNU ld in the same tree, -you'll also have to edit @file{binutils/configure.in} or -@file{ld/configure.in} to match what you've done in the @file{bfd} -directory.) - -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}. - -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} ? - -Finally, you'll need to specify and define GDB's host- and -target-dependent @file{.h} and @file{.c} files used for your -configuration; the next two chapters discuss those. +Generation of output that displays the results of an operation +involves one or more of the following: +@itemize @bullet +@item +output of the actual data + +@item +formatting the output as appropriate for console output, to make it +easily readable by humans -@node Host, Target, Config, Top -@chapter Adding a New Host +@item +machine oriented formatting--a more terse formatting to allow for easy +parsing by programs which read @value{GDBN}'s output -Once you have specified a new configuration for your host -(@pxref{Config,,Adding a New Configuration}), there are two 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. +@item +annotation, whose purpose is to help legacy GUIs to identify interesting +parts in the output +@end itemize -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} +The @code{ui_out} routines take care of the first three aspects. +Annotations are provided by separate annotation routines. Note that use +of annotations for an interface between a GUI and @value{GDBN} is +deprecated. -Several files control GDB's configuration for host systems: +Output can be in the form of a single item, which we call a @dfn{field}; +a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of +non-identical fields; or a @dfn{table}, which is a tuple consisting of a +header and a body. In a BNF-like form: -@table @file -@item gdb/config/mh-@var{xxx} -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 -@samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC}, -@samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS}, -@samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS}, -etc.; see @file{Makefile.in}. - -@item gdb/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 some machines it doesn't exist at all. +@table @code +@item @expansion{} +@code{
} +@item
@expansion{} +@code{@{ @}} +@item @expansion{} +@code{ } +@item <body> @expansion{} +@code{@{<row>@}} @end table -There are some ``generic'' versions of routines that can be used by -various host 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}. -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}. +@subsection General Conventions + +Most @code{ui_out} routines are of type @code{void}, the exceptions are +@code{ui_out_stream_new} (which returns a pointer to the newly created +object) and the @code{make_cleanup} routines. + +The first parameter is always the @code{ui_out} vector object, a pointer +to a @code{struct ui_out}. + +The @var{format} parameter is like in @code{printf} family of functions. +When it is present, there must also be a variable list of arguments +sufficient used to satisfy the @code{%} specifiers in the supplied +format. + +When a character string argument is not used in a @code{ui_out} function +call, a @code{NULL} pointer has to be supplied instead. + + +@subsection Table, Tuple and List Functions + +@cindex list output functions +@cindex table output functions +@cindex tuple output functions +This section introduces @code{ui_out} routines for building lists, +tuples and tables. The routines to output the actual data items +(fields) are presented in the next section. + +To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field +containing information about an object; a @dfn{list} is a sequence of +fields where each field describes an identical object. + +Use the @dfn{table} functions when your output consists of a list of +rows (tuples) and the console output should include a heading. Use this +even when you are listing just one object but you still want the header. + +@cindex nesting level in @code{ui_out} functions +Tables can not be nested. Tuples and lists can be nested up to a +maximum of five levels. + +The overall structure of the table output code is something like this: + +@smallexample + ui_out_table_begin + ui_out_table_header + @dots{} + ui_out_table_body + ui_out_tuple_begin + ui_out_field_* + @dots{} + ui_out_tuple_end + @dots{} + ui_out_table_end +@end smallexample + +Here is the description of table-, tuple- and list-related @code{ui_out} +functions: + +@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid}) +The function @code{ui_out_table_begin} marks the beginning of the output +of a table. It should always be called before any other @code{ui_out} +function for a given table. @var{nbrofcols} is the number of columns in +the table. @var{nr_rows} is the number of rows in the table. +@var{tblid} is an optional string identifying the table. The string +pointed to by @var{tblid} is copied by the implementation of +@code{ui_out_table_begin}, so the application can free the string if it +was @code{malloc}ed. + +The companion function @code{ui_out_table_end}, described below, marks +the end of the table's output. +@end deftypefun + +@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr}) +@code{ui_out_table_header} provides the header information for a single +table column. You call this function several times, one each for every +column of the table, after @code{ui_out_table_begin}, but before +@code{ui_out_table_body}. + +The value of @var{width} gives the column width in characters. The +value of @var{alignment} is one of @code{left}, @code{center}, and +@code{right}, and it specifies how to align the header: left-justify, +center, or right-justify it. @var{colhdr} points to a string that +specifies the column header; the implementation copies that string, so +column header strings in @code{malloc}ed storage can be freed after the +call. +@end deftypefun + +@deftypefun void ui_out_table_body (struct ui_out *@var{uiout}) +This function delimits the table header from the table body. +@end deftypefun + +@deftypefun void ui_out_table_end (struct ui_out *@var{uiout}) +This function signals the end of a table's output. It should be called +after the table body has been produced by the list and field output +functions. -@subheading Generic Host Support Files +There should be exactly one call to @code{ui_out_table_end} for each +call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions +will signal an internal error. +@end deftypefun + +The output of the tuples that represent the table rows must follow the +call to @code{ui_out_table_body} and precede the call to +@code{ui_out_table_end}. You build a tuple by calling +@code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable +calls to functions which actually output fields between them. + +@deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id}) +This function marks the beginning of a tuple output. @var{id} points +to an optional string that identifies the tuple; it is copied by the +implementation, and so strings in @code{malloc}ed storage can be freed +after the call. +@end deftypefun + +@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout}) +This function signals an end of a tuple output. There should be exactly +one call to @code{ui_out_tuple_end} for each call to +@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will +be signaled. +@end deftypefun + +@deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) +This function first opens the tuple and then establishes a cleanup +(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient +and correct implementation of the non-portable@footnote{The function +cast is not portable ISO C.} code sequence: +@smallexample +struct cleanup *old_cleanup; +ui_out_tuple_begin (uiout, "..."); +old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end, + uiout); +@end smallexample +@end deftypefun + +@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id}) +This function marks the beginning of a list output. @var{id} points to +an optional string that identifies the list; it is copied by the +implementation, and so strings in @code{malloc}ed storage can be freed +after the call. +@end deftypefun + +@deftypefun void ui_out_list_end (struct ui_out *@var{uiout}) +This function signals an end of a list output. There should be exactly +one call to @code{ui_out_list_end} for each call to +@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will +be signaled. +@end deftypefun + +@deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) +Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function +opens a list and then establishes cleanup (@pxref{Coding, Cleanups}) +that will close the list.list. +@end deftypefun + +@subsection Item Output Functions + +@cindex item output functions +@cindex field output functions +@cindex data output +The functions described below produce output for the actual data +items, or fields, which contain information about the object. + +Choose the appropriate function accordingly to your particular needs. + +@deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...) +This is the most general output function. It produces the +representation of the data in the variable-length argument list +according to formatting specifications in @var{format}, a +@code{printf}-like format string. The optional argument @var{fldname} +supplies the name of the field. The data items themselves are +supplied as additional arguments after @var{format}. + +This generic function should be used only when it is not possible to +use one of the specialized versions (see below). +@end deftypefun + +@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value}) +This function outputs a value of an @code{int} variable. It uses the +@code{"%d"} output conversion specification. @var{fldname} specifies +the name of the field. +@end deftypefun + +@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address}) +This function outputs an address. +@end deftypefun + +@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string}) +This function outputs a string using the @code{"%s"} conversion +specification. +@end deftypefun + +Sometimes, there's a need to compose your output piece by piece using +functions that operate on a stream, such as @code{value_print} or +@code{fprintf_symbol_filtered}. These functions accept an argument of +the type @code{struct ui_file *}, a pointer to a @code{ui_file} object +used to store the data stream used for the output. When you use one +of these functions, you need a way to pass their results stored in a +@code{ui_file} object to the @code{ui_out} functions. To this end, +you first create a @code{ui_stream} object by calling +@code{ui_out_stream_new}, pass the @code{stream} member of that +@code{ui_stream} object to @code{value_print} and similar functions, +and finally call @code{ui_out_field_stream} to output the field you +constructed. When the @code{ui_stream} object is no longer needed, +you should destroy it and free its memory by calling +@code{ui_out_stream_delete}. + +@deftypefun struct ui_stream *ui_out_stream_new (struct ui_out *@var{uiout}) +This function creates a new @code{ui_stream} object which uses the +same output methods as the @code{ui_out} object whose pointer is +passed in @var{uiout}. It returns a pointer to the newly created +@code{ui_stream} object. +@end deftypefun + +@deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf}) +This functions destroys a @code{ui_stream} object specified by +@var{streambuf}. +@end deftypefun + +@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf}) +This function consumes all the data accumulated in +@code{streambuf->stream} and outputs it like +@code{ui_out_field_string} does. After a call to +@code{ui_out_field_stream}, the accumulated data no longer exists, but +the stream is still valid and may be used for producing more fields. +@end deftypefun + +@strong{Important:} If there is any chance that your code could bail +out before completing output generation and reaching the point where +@code{ui_out_stream_delete} is called, it is necessary to set up a +cleanup, to avoid leaking memory and other resources. Here's a +skeleton code to do that: + +@smallexample + struct ui_stream *mybuf = ui_out_stream_new (uiout); + struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf); + ... + do_cleanups (old); +@end smallexample + +If the function already has the old cleanup chain set (for other kinds +of cleanups), you just have to add your cleanup to it: + +@smallexample + mybuf = ui_out_stream_new (uiout); + make_cleanup (ui_out_stream_delete, mybuf); +@end smallexample + +Note that with cleanups in place, you should not call +@code{ui_out_stream_delete} directly, or you would attempt to free the +same buffer twice. + +@subsection Utility Output Functions + +@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname}) +This function skips a field in a table. Use it if you have to leave +an empty field without disrupting the table alignment. The argument +@var{fldname} specifies a name for the (missing) filed. +@end deftypefun + +@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string}) +This function outputs the text in @var{string} in a way that makes it +easy to be read by humans. For example, the console implementation of +this method filters the text through a built-in pager, to prevent it +from scrolling off the visible portion of the screen. + +Use this function for printing relatively long chunks of text around +the actual field data: the text it produces is not aligned according +to the table's format. Use @code{ui_out_field_string} to output a +string field, and use @code{ui_out_message}, described below, to +output short messages. +@end deftypefun + +@deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces}) +This function outputs @var{nspaces} spaces. It is handy to align the +text produced by @code{ui_out_text} with the rest of the table or +list. +@end deftypefun + +@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...) +This function produces a formatted message, provided that the current +verbosity level is at least as large as given by @var{verbosity}. The +current verbosity level is specified by the user with the @samp{set +verbositylevel} command.@footnote{As of this writing (April 2001), +setting verbosity level is not yet implemented, and is always returned +as zero. So calling @code{ui_out_message} with a @var{verbosity} +argument more than zero will cause the message to never be printed.} +@end deftypefun + +@deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent}) +This function gives the console output filter (a paging filter) a hint +of where to break lines which are too long. Ignored for all other +output consumers. @var{indent}, if non-@code{NULL}, is the string to +be printed to indent the wrapped text on the next line; it must remain +accessible until the next call to @code{ui_out_wrap_hint}, or until an +explicit newline is produced by one of the other functions. If +@var{indent} is @code{NULL}, the wrapped text will not be indented. +@end deftypefun + +@deftypefun void ui_out_flush (struct ui_out *@var{uiout}) +This function flushes whatever output has been accumulated so far, if +the UI buffers output. +@end deftypefun + + +@subsection Examples of Use of @code{ui_out} functions + +@cindex using @code{ui_out} functions +@cindex @code{ui_out} functions, usage examples +This section gives some practical examples of using the @code{ui_out} +functions to generalize the old console-oriented code in +@value{GDBN}. The examples all come from functions defined on the +@file{breakpoints.c} file. + +This example, from the @code{breakpoint_1} function, shows how to +produce a table. + +The original code was: + +@smallexample + if (!found_a_breakpoint++) + @{ + annotate_breakpoints_headers (); + + annotate_field (0); + printf_filtered ("Num "); + annotate_field (1); + printf_filtered ("Type "); + annotate_field (2); + printf_filtered ("Disp "); + annotate_field (3); + printf_filtered ("Enb "); + if (addressprint) + @{ + annotate_field (4); + printf_filtered ("Address "); + @} + annotate_field (5); + printf_filtered ("What\n"); + + annotate_breakpoints_table (); + @} +@end smallexample + +Here's the new version: + +@smallexample + nr_printable_breakpoints = @dots{}; + + if (addressprint) + ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable"); + else + ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable"); + + if (nr_printable_breakpoints > 0) + annotate_breakpoints_headers (); + if (nr_printable_breakpoints > 0) + annotate_field (0); + ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */ + if (nr_printable_breakpoints > 0) + annotate_field (1); + ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */ + if (nr_printable_breakpoints > 0) + annotate_field (2); + ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */ + if (nr_printable_breakpoints > 0) + annotate_field (3); + ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */ + if (addressprint) + @{ + if (nr_printable_breakpoints > 0) + annotate_field (4); + if (TARGET_ADDR_BIT <= 32) + ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */ + else + ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */ + @} + if (nr_printable_breakpoints > 0) + annotate_field (5); + ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */ + ui_out_table_body (uiout); + if (nr_printable_breakpoints > 0) + annotate_breakpoints_table (); +@end smallexample + +This example, from the @code{print_one_breakpoint} function, shows how +to produce the actual data for the table whose structure was defined +in the above example. The original code was: + +@smallexample + annotate_record (); + annotate_field (0); + printf_filtered ("%-3d ", b->number); + annotate_field (1); + if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0])) + || ((int) b->type != bptypes[(int) b->type].type)) + internal_error ("bptypes table does not describe type #%d.", + (int)b->type); + printf_filtered ("%-14s ", bptypes[(int)b->type].description); + annotate_field (2); + printf_filtered ("%-4s ", bpdisps[(int)b->disposition]); + annotate_field (3); + printf_filtered ("%-3c ", bpenables[(int)b->enable]); + @dots{} +@end smallexample + +This is the new version: + +@smallexample + annotate_record (); + ui_out_tuple_begin (uiout, "bkpt"); + annotate_field (0); + ui_out_field_int (uiout, "number", b->number); + annotate_field (1); + if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0]))) + || ((int) b->type != bptypes[(int) b->type].type)) + internal_error ("bptypes table does not describe type #%d.", + (int) b->type); + ui_out_field_string (uiout, "type", bptypes[(int)b->type].description); + annotate_field (2); + ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]); + annotate_field (3); + ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]); + @dots{} +@end smallexample + +This example, also from @code{print_one_breakpoint}, shows how to +produce a complicated output field using the @code{print_expression} +functions which requires a stream to be passed. It also shows how to +automate stream destruction with cleanups. The original code was: + +@smallexample + annotate_field (5); + print_expression (b->exp, gdb_stdout); +@end smallexample + +The new version is: + +@smallexample + struct ui_stream *stb = ui_out_stream_new (uiout); + struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb); + ... + annotate_field (5); + print_expression (b->exp, stb->stream); + ui_out_field_stream (uiout, "what", local_stream); +@end smallexample + +This example, also from @code{print_one_breakpoint}, shows how to use +@code{ui_out_text} and @code{ui_out_field_string}. The original code +was: + +@smallexample + annotate_field (5); + if (b->dll_pathname == NULL) + printf_filtered ("<any library> "); + else + printf_filtered ("library \"%s\" ", b->dll_pathname); +@end smallexample + +It became: + +@smallexample + annotate_field (5); + if (b->dll_pathname == NULL) + @{ + ui_out_field_string (uiout, "what", "<any library>"); + ui_out_spaces (uiout, 1); + @} + else + @{ + ui_out_text (uiout, "library \""); + ui_out_field_string (uiout, "what", b->dll_pathname); + ui_out_text (uiout, "\" "); + @} +@end smallexample + +The following example from @code{print_one_breakpoint} shows how to +use @code{ui_out_field_int} and @code{ui_out_spaces}. The original +code was: + +@smallexample + annotate_field (5); + if (b->forked_inferior_pid != 0) + printf_filtered ("process %d ", b->forked_inferior_pid); +@end smallexample + +It became: + +@smallexample + annotate_field (5); + if (b->forked_inferior_pid != 0) + @{ + ui_out_text (uiout, "process "); + ui_out_field_int (uiout, "what", b->forked_inferior_pid); + ui_out_spaces (uiout, 1); + @} +@end smallexample + +Here's an example of using @code{ui_out_field_string}. The original +code was: + +@smallexample + annotate_field (5); + if (b->exec_pathname != NULL) + printf_filtered ("program \"%s\" ", b->exec_pathname); +@end smallexample + +It became: + +@smallexample + annotate_field (5); + if (b->exec_pathname != NULL) + @{ + ui_out_text (uiout, "program \""); + ui_out_field_string (uiout, "what", b->exec_pathname); + ui_out_text (uiout, "\" "); + @} +@end smallexample + +Finally, here's an example of printing an address. The original code: + +@smallexample + annotate_field (4); + printf_filtered ("%s ", + local_hex_string_custom ((unsigned long) b->address, "08l")); +@end smallexample + +It became: + +@smallexample + annotate_field (4); + ui_out_field_core_addr (uiout, "Address", b->address); +@end smallexample + + +@section Console Printing + +@section TUI + +@node libgdb + +@chapter libgdb + +@section libgdb 1.0 +@cindex @code{libgdb} +@code{libgdb} 1.0 was an abortive project of years ago. The theory was +to provide an API to @value{GDBN}'s functionality. + +@section libgdb 2.0 +@cindex @code{libgdb} +@code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is +better able to support graphical and other environments. + +Since @code{libgdb} development is on-going, its architecture is still +evolving. The following components have so far been identified: -@table @file +@itemize @bullet +@item +Observer - @file{gdb-events.h}. +@item +Builder - @file{ui-out.h} +@item +Event Loop - @file{event-loop.h} +@item +Library - @file{gdb.h} +@end itemize -@item infptrace.c -This is the low level interface to inferior processes for systems -using the Unix @code{ptrace} call in a vanilla way. +The model that ties these components together is described below. -@item coredep.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{coredep.c}, and should just provide @code{fetch_core_registers} in -@code{@var{xxx}-xdep.c}. - -@item coredep.c::register_addr() -If your @code{xm-@var{xxx}.h} file defines the macro -@code{REGISTER_U_ADDR(reg)} to be the offset within the @samp{user} -struct of a register (represented as a GDB register number), -@file{coredep.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}-xdep.c} file, and be sure @code{@var{xxx}-xdep.o} is in -the @code{XDEPFILES} 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 +@section The @code{libgdb} Model -Object files needed when the target system is an @var{xxx} are listed -in the file @file{config/mt-@var{xxx}}, in the makefile macro -@samp{TDEPFILES = }@dots{}. The header file that defines the target -system should be called @file{tm-@var{xxx}.h}, and should be specified -as the value of @samp{TM_FILE} in @file{config/mt-@var{xxx}}. You can -also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, and @samp{TM_CDEPS} in -there; see @file{Makefile.in}. - -Now, you are now ready to try configuring GDB to compile for your system. -From the top level (above @file{bfd}, @file{gdb}, etc), do: - -@example -./configure @var{xxx} +target=vxworks960 -@end example - -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.) - -If this succeeds, you can try building it all with: - -@example -make -@end example - -Good luck! Comments and suggestions about this section are particularly -welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}. - -When hosting GDB 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 client of @code{libgdb} interacts with the library in two ways. -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-dep.c}; if not, it's in your @file{@var{xxx}-xdep.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.) +@itemize @bullet +@item +As an observer (using @file{gdb-events}) receiving notifications from +@code{libgdb} of any internal state changes (break point changes, run +state, etc). +@item +As a client querying @code{libgdb} (using the @file{ui-out} builder) to +obtain various status values from @value{GDBN}. +@end itemize +Since @code{libgdb} could have multiple clients (e.g. a GUI supporting +the existing @value{GDBN} CLI), those clients must co-operate when +controlling @code{libgdb}. In particular, a client must ensure that +@code{libgdb} is idle (i.e. no other client is using @code{libgdb}) +before responding to a @file{gdb-event} by making a query. -@node Target, Languages, Host, Top -@chapter Adding a New Target +@section CLI support -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. +At present @value{GDBN}'s CLI is very much entangled in with the core of +@code{libgdb}. Consequently, a client wishing to include the CLI in +their interface needs to carefully co-ordinate its own and the CLI's +requirements. -A variety of files specify attributes of the GDB target environment: +It is suggested that the client set @code{libgdb} up to be bi-modal +(alternate between CLI and client query modes). The notes below sketch +out the theory: -@table @file -@item gdb/config/mt-@var{ttt} -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}, -and other Makefile variables here; see @file{Makefile.in}. - -@item gdb/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. +@itemize @bullet +@item +The client registers itself as an observer of @code{libgdb}. +@item +The client create and install @code{cli-out} builder using its own +versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and +@code{gdb_stdout} streams. +@item +The client creates a separate custom @code{ui-out} builder that is only +used while making direct queries to @code{libgdb}. +@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. - -@item gdb/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. +When the client receives input intended for the CLI, it simply passes it +along. Since the @code{cli-out} builder is installed by default, all +the CLI output in response to that command is routed (pronounced rooted) +through to the client controlled @code{gdb_stdout} et.@: al.@: streams. +At the same time, the client is kept abreast of internal changes by +virtue of being a @code{libgdb} observer. + +The only restriction on the client is that it must wait until +@code{libgdb} becomes idle before initiating any queries (using the +client's custom builder). + +@section @code{libgdb} components + +@subheading Observer - @file{gdb-events.h} +@file{gdb-events} provides the client with a very raw mechanism that can +be used to implement an observer. At present it only allows for one +observer and that observer must, internally, handle the need to delay +the processing of any event notifications until after @code{libgdb} has +finished the current command. + +@subheading Builder - @file{ui-out.h} +@file{ui-out} provides the infrastructure necessary for a client to +create a builder. That builder is then passed down to @code{libgdb} +when doing any queries. + +@subheading Event Loop - @file{event-loop.h} +@c There could be an entire section on the event-loop +@file{event-loop}, currently non-re-entrant, provides a simple event +loop. A client would need to either plug its self into this loop or, +implement a new event-loop that GDB would use. + +The event-loop will eventually be made re-entrant. This is so that +@value{GDB} can better handle the problem of some commands blocking +instead of returning. + +@subheading Library - @file{gdb.h} +@file{libgdb} is the most obvious component of this system. It provides +the query interface. Each function is parameterized by a @code{ui-out} +builder. The result of the query is constructed using that builder +before the query function returns. + +@node Symbol Handling + +@chapter Symbol Handling + +Symbols are a key part of @value{GDBN}'s operation. Symbols include variables, +functions, and types. + +@section Symbol Reading + +@cindex symbol reading +@cindex reading of symbols +@cindex symbol files +@value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol +file is the file containing the program which @value{GDBN} is +debugging. @value{GDBN} can be directed to use a different file for +symbols (with the @samp{symbol-file} command), and it can also read +more symbols via the @samp{add-file} and @samp{load} commands, or while +reading symbols from shared libraries. + +@findex find_sym_fns +Symbol files are initially opened by code in @file{symfile.c} using +the BFD library (@pxref{Support Libraries}). BFD identifies the type +of the file by examining its header. @code{find_sym_fns} then uses +this identification to locate a set of symbol-reading functions. + +@findex add_symtab_fns +@cindex @code{sym_fns} structure +@cindex adding a symbol-reading module +Symbol-reading modules identify themselves to @value{GDBN} 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 gdb/@var{arch}-tdep.c -Similarly, there are often common subroutines that are shared by all -target machines that use this particular architecture. +The functions supplied by each module are: + +@table @code +@item @var{xyz}_symfile_init(struct sym_fns *sf) + +@cindex secondary symbol file +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. + +@item @var{xyz}_new_init() + +Called from @code{symbol_file_add} when discarding existing symbols. +This function needs only handle the symbol-reading module's internal +state; the symbol table data structures visible to the rest of +@value{GDBN} 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. + +@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) + +Called from @code{symbol_file_add} to actually read the symbols from a +symbol-file into a set of psymtabs or symtabs. + +@code{sf} points to the @code{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 + +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 @value{GDBN} symbol-handling code. + +@table @code +@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst) + +Called from @code{psymtab_to_symtab} (or the @code{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, @code{pst->readin} should have been set to 1, and +@code{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 -When adding support for a new target machine, there are various areas -of support that might need change, or might be OK. +@section Partial Symbol Tables + +@value{GDBN} has three types of symbol tables: -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. +@itemize @bullet +@cindex full symbol table +@cindex symtabs +@item +Full symbol tables (@dfn{symtabs}). These contain the main +information about symbols and addresses. + +@cindex psymtabs +@item +Partial symbol tables (@dfn{psymtabs}). These contain enough +information to know when to read the corresponding part of the full +symbol table. + +@cindex minimal symbol table +@cindex minsymtabs +@item +Minimal symbol tables (@dfn{msymtabs}). These contain information +gleaned from non-debugging symbols. +@end itemize -If you need to add a new object file format, you are beyond the scope -of this document right now. Look at the structure of the a.out -and COFF support, build a transfer vector (@code{xvec}) for your new format, -and start populating it with routines. Add it to the list in -@file{bfd/targets.c}. +@cindex partial symbol table +This section describes partial symbol tables. -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.) +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 @value{GDBN} 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}.) +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 @code{enum} values declared at file scope. -@node Languages, Releases, Target, Top -@chapter Adding a Source Language to GDB +The psymtab also contains the range of instruction addresses that the +full symbol table would represent. -To add other languages to GDB's expression parser, follow the following steps: +@cindex finding a symbol +@cindex symbol lookup +The idea is that there are only two ways for the user (or much of the +code in the debugger) to reference a symbol: + +@itemize @bullet +@findex find_pc_function +@findex find_pc_line +@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. + +@cindex lookup_symbol +@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. +@end itemize + +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. + +It is a bug for @value{GDBN} 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. + +@section Types + +@unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}). + +@cindex fundamental types +These are the fundamental types that @value{GDBN} 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 @value{GDBN} knows about for all the languages that @value{GDBN} +knows about. + +@unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}). + +@cindex type codes +Each time @value{GDBN} builds an internal type, it marks it with one +of these types. The type may be a fundamental type, such as +@code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR} +which is a pointer to another type. Typically, several @code{FT_*} +types map to one @code{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. + +@unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}). + +These are instances of type structs that roughly correspond to +fundamental types and are created as global types for @value{GDBN} to +use for various ugly historical reasons. We eventually want to +eliminate these. Note for example that @code{builtin_type_int} +initialized in @file{gdbtypes.c} is basically the same as a +@code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for +an @code{FT_INTEGER} fundamental type. The difference is that the +@code{builtin_type} is not associated with any particular objfile, and +only one instance exists, while @file{c-lang.c} builds as many +@code{TYPE_CODE_INT} types as needed, with each one associated with +some particular objfile. + +@section Object File Formats +@cindex object file formats + +@subsection a.out + +@cindex @code{a.out} format +The @code{a.out} format is the original file format for Unix. It +consists of three sections: @code{text}, @code{data}, and @code{bss}, +which are for program code, initialized data, and uninitialized data, +respectively. + +The @code{a.out} format is so simple that it doesn't have any reserved +place for debugging information. (Hey, the original Unix hackers used +@samp{adb}, which is a machine-language debugger!) The only debugging +format for @code{a.out} is stabs, which is encoded as a set of normal +symbols with distinctive attributes. + +The basic @code{a.out} reader is in @file{dbxread.c}. + +@subsection COFF + +@cindex COFF format +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. + +The COFF reader is in @file{coffread.c}. + +@subsection ECOFF + +@cindex ECOFF format +ECOFF is an extended COFF originally introduced for Mips and Alpha +workstations. + +The basic ECOFF reader is in @file{mipsread.c}. + +@subsection XCOFF + +@cindex XCOFF format +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 @code{dbx}-style stabs whose strings are located in the +@code{.debug} section (rather than the string table). For more +information, see @ref{Top,,,stabs,The Stabs Debugging Format}. + +The shared library scheme has a 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 + +@cindex PE-COFF format +Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their +executables. PE is basically COFF with additional headers. + +While BFD includes special PE support, @value{GDBN} needs only the basic +COFF reader. + +@subsection ELF + +@cindex ELF format +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. + +The basic ELF reader is in @file{elfread.c}. + +@subsection SOM + +@cindex SOM format +SOM is HP's object file and debug format (not to be confused with IBM's +SOM, which is a cross-language ABI). + +The SOM reader is in @file{hpread.c}. + +@subsection Other File Formats + +@cindex Netware Loadable Module format +Other file formats that have been supported by @value{GDBN} include Netware +Loadable Modules (@file{nlmread.c}). + +@section Debugging File Formats + +This section describes characteristics of debugging information that +are independent of the object file format. + +@subsection stabs + +@cindex stabs debugging info +@code{stabs} started out as special symbols within the @code{a.out} +format. Since then, it has been encapsulated into other file +formats, such as COFF and ELF. + +While @file{dbxread.c} does some of the basic stab processing, +including for encapsulated versions, @file{stabsread.c} does +the real work. + +@subsection COFF + +@cindex COFF debugging info +The basic COFF definition includes debugging information. The level +of support is minimal and non-extensible, and is not often used. + +@subsection Mips debug (Third Eye) + +@cindex ECOFF debugging info +ECOFF includes a definition of a special debug format. + +The file @file{mdebugread.c} implements reading for this format. + +@subsection DWARF 1 + +@cindex DWARF 1 debugging info +DWARF 1 is a debugging format that was originally designed to be +used with ELF in SVR4 systems. + +@c OBSOLETE CHILL_PRODUCER +@c GCC_PRODUCER +@c GPLUS_PRODUCER +@c LCC_PRODUCER +@c If defined, these are the producer strings in a DWARF 1 file. All of +@c these have reasonable defaults already. + +The DWARF 1 reader is in @file{dwarfread.c}. + +@subsection DWARF 2 + +@cindex DWARF 2 debugging info +DWARF 2 is an improved but incompatible version of DWARF 1. + +The DWARF 2 reader is in @file{dwarf2read.c}. + +@subsection SOM + +@cindex SOM debugging info +Like COFF, the SOM definition includes debugging information. + +@section Adding a New Symbol Reader to @value{GDBN} + +@cindex adding debugging info reader +If you are using an existing object file format (@code{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 @value{GDBN} will have to call swapping routines +from BFD and a few other BFD internal routines to locate the debugging +information. As much as possible, @value{GDBN} 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/lib@var{xyz}.h}, which is included by @value{GDBN}. + + +@node Language Support + +@chapter Language Support + +@cindex language support +@value{GDBN}'s language support is mainly driven by the symbol reader, +although it is possible for the user to set the source language +manually. + +@value{GDBN} chooses the source language by looking at the extension +of the file recorded in the debug info; @file{.c} means C, @file{.f} +means Fortran, etc. It may also use a special-purpose language +identifier if the debug format supports it, like with DWARF. + +@section Adding a Source Language to @value{GDBN} + +@cindex adding source language +To add other languages to @value{GDBN}'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}. +@cindex expression parser +This should reside in a file @file{@var{lang}-exp.y}. Routines for +building parsed expressions into a @code{union exp_element} list are in +@file{parse.c}. +@cindex language parser 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: - -@example -#define yyparse @var{lang}_parse -#define yylex @var{lang}_lex -#define yyerror @var{lang}_error -#define yylval @var{lang}_lval -#define yychar @var{lang}_char -#define yydebug @var{lang}_debug -#define yypact @var{lang}_pact -#define yyr1 @var{lang}_r1 -#define yyr2 @var{lang}_r2 -#define yydef @var{lang}_def -#define yychk @var{lang}_chk -#define yypgo @var{lang}_pgo -#define yyact @var{lang}_act -#define yyexca @var{lang}_exca -#define yyerrflag @var{lang}_errflag -#define yynerrs @var{lang}_nerrs -@end example +@strong{must} be included at the top of the YACC parser, to prevent the +various parsers from defining the same global names: + +@smallexample +#define yyparse @var{lang}_parse +#define yylex @var{lang}_lex +#define yyerror @var{lang}_error +#define yylval @var{lang}_lval +#define yychar @var{lang}_char +#define yydebug @var{lang}_debug +#define yypact @var{lang}_pact +#define yyr1 @var{lang}_r1 +#define yyr2 @var{lang}_r2 +#define yydef @var{lang}_def +#define yychk @var{lang}_chk +#define yypgo @var{lang}_pgo +#define yyact @var{lang}_act +#define yyexca @var{lang}_exca +#define yyerrflag @var{lang}_errflag +#define yynerrs @var{lang}_nerrs +@end smallexample At the bottom of your parser, define a @code{struct language_defn} and initialize it with the right values for your language. Define an @code{initialize_@var{lang}} routine and have it call -@samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB +@samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN} that your language exists. You'll need some other supporting variables and functions, which will be used via pointers from your @code{@var{lang}_language_defn}. See the declaration of @code{struct @@ -471,11 +1943,16 @@ for more information. @item Add any evaluation routines, if necessary +@cindex expression evaluation routines +@findex evaluate_subexp +@findex prefixify_subexp +@findex length_of_subexp If you need new opcodes (that represent the operations of the language), add them to the enumerated type in @file{expression.h}. Add support -code for these operations in @code{eval.c:evaluate_subexp()}. Add cases +code for these operations in the @code{evaluate_subexp} function +defined in the file @file{eval.c}. Add cases for new opcodes in two functions from @file{parse.c}: -@code{prefixify_subexp()} and @code{length_of_subexp()}. These compute +@code{prefixify_subexp} and @code{length_of_subexp}. These compute the number of @code{exp_element}s that a given operation takes up. @item Update some existing code @@ -483,20 +1960,23 @@ 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. +@vindex current_language Also included in @file{language.c} is the code that updates the variable @code{current_language}, and the routines that translate the @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. +@findex _initialize_language +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 @value{GDBN} is built for. +@findex allocate_symtab 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. This is used to determine the language to use at each stack frame level. @@ -505,30 +1985,34 @@ file. If the language can be better inferred from the symbol information, please set the language of the symtab in the symbol-reading code. -Add helper code to @code{expprint.c:print_subexp()} to handle any new +@findex print_subexp +@findex op_print_tab +Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new expression opcodes you have added to @file{expression.h}. Also, add the printed representations of your operators to @code{op_print_tab}. @item Add a place of call +@findex parse_exp_1 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in -@code{parse.c:parse_exp_1()}. +@code{parse_exp_1} (defined in @file{parse.c}). @item Use macros to trim code -The user has the option of building GDB for some or all of the -languages. If the user decides to build GDB for the language +@cindex trimming language-dependent code +The user has the option of building @value{GDBN} for some or all of the +languages. If the user decides to build @value{GDBN} for the language @var{lang}, then every file dependent on @file{language.h} will have the macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to leave out large routines that the user won't need if he or she is not using your language. -Note that you do not need to do this in your YACC parser, since if GDB +Note that you do not need to do this in your YACC parser, since if @value{GDBN} is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the -compiled form of your parser) is not linked into GDB at all. +compiled form of your parser) is not linked into @value{GDBN} at all. -See the file @file{configure.in} for how GDB is configured for different -languages. +See the file @file{configure.in} for how @value{GDBN} is configured +for different languages. @item Edit @file{Makefile.in} @@ -539,269 +2023,4514 @@ distribution! @end table -@node Releases, BFD support for GDB, Languages, Top -@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 gdb.tar.Z -@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. +With the advent of Autoconf, it's rarely necessary to have host +definition machinery anymore. The following information is provided, +mainly, as an historical reference. -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 +@cindex adding a new host +@cindex host, adding +@value{GDBN}'s host configuration support normally happens via Autoconf. +New host-specific definitions should not be needed. Older hosts +@value{GDBN} still use the host-specific definitions and files listed +below, but these mostly exist for historical reasons, and will +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). +@table @file +@item gdb/config/@var{arch}/@var{xyz}.mh +This file once contained both host and native configuration information +(@pxref{Native Debugging}) for the machine @var{xyz}. The host +configuration information is now handed by Autoconf. -For making paper, the only thing this implies is the right generation of -@file{texinfo.tex} needs to be included in the distribution. +Host configuration information included a definition of +@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC}, +@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES}, +@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}. -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. +New host only configurations do not need this file. +@item gdb/config/@var{arch}/xm-@var{xyz}.h +This file once contained definitions and includes required when hosting +gdb on machine @var{xyz}. Those definitions and includes are now +handled by Autoconf. -@node BFD support for GDB, Symbol Reading, Releases, Top -@chapter Binary File Descriptor Library Support for GDB +New host and native configurations do not need this file. -BFD provides support for GDB in several ways: +@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h} +file to define the macros @var{HOST_FLOAT_FORMAT}, +@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}. That code +also needs to be replaced with either an Autoconf or run-time test.} -@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. +@end table -@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. +@subheading Generic Host Support 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. +@cindex generic host support +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}. -@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. +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}. + +@table @file +@cindex remote debugging support +@cindex serial line support +@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. + +@item ser-go32.c +This contains serial line support for 32-bit programs running under DOS, +using the DJGPP (a.k.a.@: GO32) execution environment. + +@cindex TCP remote support +@item ser-tcp.c +This contains generic TCP support using sockets. @end table -@c The interface for symbol reading is described in @ref{Symbol -@c Reading,,Symbol Reading}. +@section Host Conditionals + +When @value{GDBN} 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: + +@ftable @code +@item @value{GDBN}INIT_FILENAME +The default name of @value{GDBN}'s initialization file (normally +@file{.gdbinit}). + +@item NO_STD_REGS +This macro is deprecated. + +@item NO_SYS_FILE +Define this if your system does not have a @code{<sys/file.h>}. + +@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 SIGWINCH_HANDLER_BODY +Define this to expand into code that will define the function named by +the expansion of @code{SIGWINCH_HANDLER}. + +@item ALIGN_STACK_ON_STARTUP +@cindex stack alignment +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 CRLF_SOURCE_FILES +@cindex DOS text 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 @code{\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"}. + +@item DEFAULT_PROMPT +@cindex prompt +The default value of the prompt string (normally @code{"(gdb) "}). + +@item DEV_TTY +@cindex terminal device +The name of the generic TTY device, defaults to @code{"/dev/tty"}. + +@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 FOPEN_RB +Define this if binary files are opened the same way as text files. + +@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 HAVE_MMAP +@findex 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 HAVE_TERMIO +Define this if the host system has @code{termio.h}. + +@item INT_MAX +@itemx INT_MIN +@itemx LONG_MAX +@itemx UINT_MAX +@itemx ULONG_MAX +Values for host-side constants. + +@item ISATTY +Substitute for isatty, if not available. + +@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 CC_HAS_LONG_LONG +@cindex @code{long long} data type +Define this if the host C compiler supports @code{long long}. This is set +by the @code{configure} script. + +@item PRINTF_HAS_LONG_LONG +Define this if the host can handle printing of long long integers via +the printf format conversion specifier @code{ll}. This is set by the +@code{configure} script. + +@item HAVE_LONG_DOUBLE +Define this if the host C compiler supports @code{long double}. This is +set by the @code{configure} script. + +@item PRINTF_HAS_LONG_DOUBLE +Define this if the host can handle printing of long double float-point +numbers via the printf format conversion specifier @code{Lg}. This is +set by the @code{configure} script. + +@item SCANF_HAS_LONG_DOUBLE +Define this if the host can handle the parsing of long double +float-point numbers via the scanf format conversion specifier +@code{Lg}. This is set by the @code{configure} script. + +@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 L_SET +This macro is used as the argument to @code{lseek} (or, most commonly, +@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead, +which is the POSIX equivalent. + +@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. + +@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 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 USE_GENERIC_DUMMY_FRAMES +@cindex generic dummy frames +Define this to 1 if the target is using the generic inferior function +call code. See @code{blockframe.c} for more information. + +@item USE_MMALLOC +@findex mmalloc +@value{GDBN} 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 @code{mmalloc} library. This +define is set when you configure with @samp{--with-mmalloc}. + +@item NO_MMCHECK +@findex 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 @code{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 @code{mmalloc}, but must define +@code{NO_MMCHECK}. + +@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, @value{GDBN} will issue a +warning. This is currently defined if you configure using +@samp{--with-mmalloc}. + +@item NO_SIGINTERRUPT +@findex siginterrupt +Define this to indicate that @code{siginterrupt} is not available. + +@item SEEK_CUR +@itemx SEEK_SET +Define these to appropriate value for the system @code{lseek}, if not already +defined. + +@item STOP_SIGNAL +This is the signal for stopping @value{GDBN}. Defaults to +@code{SIGTSTP}. (Only redefined for the Convex.) + +@item USE_O_NOCTTY +Define this if the interior's tty should be opened with the @code{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.) + +@item lint +Define this to help placate @code{lint} in some situations. + +@item volatile +Define this to override the defaults of @code{__volatile__} or +@code{/**/}. +@end ftable + + +@node Target Architecture Definition + +@chapter Target Architecture Definition + +@cindex target architecture definition +@value{GDBN}'s target architecture defines what sort of +machine-language programs @value{GDBN} can work with, and how it works +with them. + +The target architecture object is implemented as the C structure +@code{struct gdbarch *}. The structure, and its methods, are generated +using the Bourne shell script @file{gdbarch.sh}. + +@section Operating System ABI Variant Handling +@cindex OS ABI variants + +@value{GDBN} provides a mechanism for handling variations in OS +ABIs. An OS ABI variant may have influence over any number of +variables in the target architecture definition. There are two major +components in the OS ABI mechanism: sniffers and handlers. + +A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair +(the architecture may be wildcarded) in an attempt to determine the +OS ABI of that file. Sniffers with a wildcarded architecture are considered +to be @dfn{generic}, while sniffers for a specific architecture are +considered to be @dfn{specific}. A match from a specific sniffer +overrides a match from a generic sniffer. Multiple sniffers for an +architecture/flavour may exist, in order to differentiate between two +different operating systems which use the same basic file format. The +OS ABI framework provides a generic sniffer for ELF-format files which +examines the @code{EI_OSABI} field of the ELF header, as well as note +sections known to be used by several operating systems. + +@cindex fine-tuning @code{gdbarch} structure +A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the +selected OS ABI. There may be only one handler for a given OS ABI +for each BFD architecture. + +The following OS ABI variants are defined in @file{osabi.h}: +@table @code -@node Symbol Reading, Cleanups, BFD support for GDB, Top -@chapter Symbol Reading +@findex GDB_OSABI_UNKNOWN +@item GDB_OSABI_UNKNOWN +The ABI of the inferior is unknown. The default @code{gdbarch} +settings for the architecture will be used. -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. +@findex GDB_OSABI_SVR4 +@item GDB_OSABI_SVR4 +UNIX System V Release 4 -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. +@findex GDB_OSABI_HURD +@item GDB_OSABI_HURD +GNU using the Hurd kernel -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. +@findex GDB_OSABI_SOLARIS +@item GDB_OSABI_SOLARIS +Sun Solaris -The functions supplied by each module are: +@findex GDB_OSABI_OSF1 +@item GDB_OSABI_OSF1 +OSF/1, including Digital UNIX and Compaq Tru64 UNIX -@table @code -@item @var{xxx}_symfile_init(struct sym_fns *sf) +@findex GDB_OSABI_LINUX +@item GDB_OSABI_LINUX +GNU using the Linux kernel -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. +@findex GDB_OSABI_FREEBSD_AOUT +@item GDB_OSABI_FREEBSD_AOUT +FreeBSD using the a.out executable format -@item @var{xxx}_new_init() +@findex GDB_OSABI_FREEBSD_ELF +@item GDB_OSABI_FREEBSD_ELF +FreeBSD using the ELF executable format -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. +@findex GDB_OSABI_NETBSD_AOUT +@item GDB_OSABI_NETBSD_AOUT +NetBSD using the a.out executable format -@item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) +@findex GDB_OSABI_NETBSD_ELF +@item GDB_OSABI_NETBSD_ELF +NetBSD using the ELF executable format -Called from @code{symbol_file_add} to actually read the symbols from a -symbol-file into a set of psymtabs or symtabs. +@findex GDB_OSABI_WINCE +@item GDB_OSABI_WINCE +Windows CE -@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 +@findex GDB_OSABI_GO32 +@item GDB_OSABI_GO32 +DJGPP -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. +@findex GDB_OSABI_NETWARE +@item GDB_OSABI_NETWARE +Novell NetWare + +@findex GDB_OSABI_ARM_EABI_V1 +@item GDB_OSABI_ARM_EABI_V1 +ARM Embedded ABI version 1 + +@findex GDB_OSABI_ARM_EABI_V2 +@item GDB_OSABI_ARM_EABI_V2 +ARM Embedded ABI version 2 + +@findex GDB_OSABI_ARM_APCS +@item GDB_OSABI_ARM_APCS +Generic ARM Procedure Call Standard -@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 +Here are the functions that make up the OS ABI framework: + +@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi}) +Return the name of the OS ABI corresponding to @var{osabi}. +@end deftypefun + +@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch})) +Register the OS ABI handler specified by @var{init_osabi} for the +architecture/OS ABI pair specified by @var{arch} and @var{osabi}. +@end deftypefun + +@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd})) +Register the OS ABI file sniffer specified by @var{sniffer} for the +BFD architecture/flavour pair specified by @var{arch} and @var{flavour}. +If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to +be generic, and is allowed to examine @var{flavour}-flavoured files for +any architecture. +@end deftypefun + +@deftypefun enum gdb_osabi gdbarch_lookup_osabi (bfd *@var{abfd}) +Examine the file described by @var{abfd} to determine its OS ABI. +The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot +be determined. +@end deftypefun + +@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi}) +Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the +@code{gdbarch} structure specified by @var{gdbarch}. If a handler +corresponding to @var{osabi} has not been registered for @var{gdbarch}'s +architecture, a warning will be issued and the debugging session will continue +with the defaults already established for @var{gdbarch}. +@end deftypefun + +@section Registers and Memory + +@value{GDBN}'s model of the target machine is rather simple. +@value{GDBN} assumes the machine includes a bank of registers and a +block of memory. Each register may have a different size. + +@value{GDBN} 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_NAME} and related macros. + +@value{GDBN} can handle big-endian, little-endian, and bi-endian architectures. + +@section Pointers Are Not Always Addresses +@cindex pointer representation +@cindex address representation +@cindex word-addressed machines +@cindex separate data and code address spaces +@cindex spaces, separate data and code address +@cindex address spaces, separate data and code +@cindex code pointers, word-addressed +@cindex converting between pointers and addresses +@cindex D10V addresses + +On almost all 32-bit architectures, the representation of a pointer is +indistinguishable from the representation of some fixed-length number +whose value is the byte address of the object pointed to. On such +machines, the words ``pointer'' and ``address'' can be used interchangeably. +However, architectures with smaller word sizes are often cramped for +address space, so they may choose a pointer representation that breaks this +identity, and allows a larger code address space. + +For example, the Mitsubishi D10V is a 16-bit VLIW processor whose +instructions are 32 bits long@footnote{Some D10V instructions are +actually pairs of 16-bit sub-instructions. However, since you can't +jump into the middle of such a pair, code addresses can only refer to +full 32 bit instructions, which is what matters in this explanation.}. +If the D10V used ordinary byte addresses to refer to code locations, +then the processor would only be able to address 64kb of instructions. +However, since instructions must be aligned on four-byte boundaries, the +low two bits of any valid instruction's byte address are always +zero---byte addresses waste two bits. So instead of byte addresses, +the D10V uses word addresses---byte addresses shifted right two bits---to +refer to code. Thus, the D10V can use 16-bit words to address 256kb of +code space. + +However, this means that code pointers and data pointers have different +forms on the D10V. The 16-bit word @code{0xC020} refers to byte address +@code{0xC020} when used as a data address, but refers to byte address +@code{0x30080} when used as a code address. + +(The D10V also uses separate code and data address spaces, which also +affects the correspondence between pointers and addresses, but we're +going to ignore that here; this example is already too long.) + +To cope with architectures like this---the D10V is not the only +one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are +byte numbers, and @dfn{pointers}, which are the target's representation +of an address of a particular type of data. In the example above, +@code{0xC020} is the pointer, which refers to one of the addresses +@code{0xC020} or @code{0x30080}, depending on the type imposed upon it. +@value{GDBN} provides functions for turning a pointer into an address +and vice versa, in the appropriate way for the current architecture. + +Unfortunately, since addresses and pointers are identical on almost all +processors, this distinction tends to bit-rot pretty quickly. Thus, +each time you port @value{GDBN} to an architecture which does +distinguish between pointers and addresses, you'll probably need to +clean up some architecture-independent code. + +Here are functions which convert between pointers and addresses: + +@deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type}) +Treat the bytes at @var{buf} as a pointer or reference of type +@var{type}, and return the address it represents, in a manner +appropriate for the current architecture. This yields an address +@value{GDBN} can use to read target memory, disassemble, etc. Note that +@var{buf} refers to a buffer in @value{GDBN}'s memory, not the +inferior's. + +For example, if the current architecture is the Intel x86, this function +extracts a little-endian integer of the appropriate length from +@var{buf} and returns it. However, if the current architecture is the +D10V, this function will return a 16-bit integer extracted from +@var{buf}, multiplied by four if @var{type} is a pointer to a function. + +If @var{type} is not a pointer or reference type, then this function +will signal an internal error. +@end deftypefun + +@deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr}) +Store the address @var{addr} in @var{buf}, in the proper format for a +pointer of type @var{type} in the current architecture. Note that +@var{buf} refers to a buffer in @value{GDBN}'s memory, not the +inferior's. + +For example, if the current architecture is the Intel x86, this function +stores @var{addr} unmodified as a little-endian integer of the +appropriate length in @var{buf}. However, if the current architecture +is the D10V, this function divides @var{addr} by four if @var{type} is +a pointer to a function, and then stores it in @var{buf}. + +If @var{type} is not a pointer or reference type, then this function +will signal an internal error. +@end deftypefun + +@deftypefun CORE_ADDR value_as_address (struct value *@var{val}) +Assuming that @var{val} is a pointer, return the address it represents, +as appropriate for the current architecture. + +This function actually works on integral values, as well as pointers. +For pointers, it performs architecture-specific conversions as +described above for @code{extract_typed_address}. +@end deftypefun + +@deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr}) +Create and return a value representing a pointer of type @var{type} to +the address @var{addr}, as appropriate for the current architecture. +This function performs architecture-specific conversions as described +above for @code{store_typed_address}. +@end deftypefun + + +@value{GDBN} also provides functions that do the same tasks, but assume +that pointers are simply byte addresses; they aren't sensitive to the +current architecture, beyond knowing the appropriate endianness. + +@deftypefun CORE_ADDR extract_address (void *@var{addr}, int len) +Extract a @var{len}-byte number from @var{addr} in the appropriate +endianness for the current architecture, and return it. Note that +@var{addr} refers to @value{GDBN}'s memory, not the inferior's. + +This function should only be used in architecture-specific code; it +doesn't have enough information to turn bits into a true address in the +appropriate way for the current architecture. If you can, use +@code{extract_typed_address} instead. +@end deftypefun + +@deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val}) +Store @var{val} at @var{addr} as a @var{len}-byte integer, in the +appropriate endianness for the current architecture. Note that +@var{addr} refers to a buffer in @value{GDBN}'s memory, not the +inferior's. + +This function should only be used in architecture-specific code; it +doesn't have enough information to turn a true address into bits in the +appropriate way for the current architecture. If you can, use +@code{store_typed_address} instead. +@end deftypefun + + +Here are some macros which architectures can define to indicate the +relationship between pointers and addresses. These have default +definitions, appropriate for architectures on which all pointers are +simple unsigned byte addresses. + +@deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf}) +Assume that @var{buf} holds a pointer of type @var{type}, in the +appropriate format for the current architecture. Return the byte +address the pointer refers to. + +This function may safely assume that @var{type} is either a pointer or a +C@t{++} reference type. +@end deftypefn + +@deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr}) +Store in @var{buf} a pointer of type @var{type} representing the address +@var{addr}, in the appropriate format for the current architecture. + +This function may safely assume that @var{type} is either a pointer or a +C@t{++} reference type. +@end deftypefn + + +@section Raw and Virtual Register Representations +@cindex raw register representation +@cindex virtual register representation +@cindex representations, raw and virtual registers + +@emph{Maintainer note: This section is pretty much obsolete. The +functionality described here has largely been replaced by +pseudo-registers and the mechanisms described in @ref{Target +Architecture Definition, , Using Different Register and Memory Data +Representations}. See also @uref{http://www.gnu.org/software/gdb/bugs/, +Bug Tracking Database} and +@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more +up-to-date information.} + +Some architectures use one representation for a value when it lives in a +register, but use a different representation when it lives in memory. +In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in +the target registers, and the @dfn{virtual} representation is the one +used in memory, and within @value{GDBN} @code{struct value} objects. + +@emph{Maintainer note: Notice that the same mechanism is being used to +both convert a register to a @code{struct value} and alternative +register forms.} + +For almost all data types on almost all architectures, the virtual and +raw representations are identical, and no special handling is needed. +However, they do occasionally differ. For example: -@node Cleanups, Wrapping, Symbol Reading, Top -@chapter Cleanups +@itemize @bullet +@item +The x86 architecture supports an 80-bit @code{long double} type. However, when +we store those values in memory, they occupy twelve bytes: the +floating-point number occupies the first ten, and the final two bytes +are unused. This keeps the values aligned on four-byte boundaries, +allowing more efficient access. Thus, the x86 80-bit floating-point +type is the raw representation, and the twelve-byte loosely-packed +arrangement is the virtual representation. + +@item +Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit +registers, with garbage in their upper bits. @value{GDBN} ignores the top 32 +bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the +raw representation, and the trimmed 32-bit representation is the +virtual representation. +@end itemize -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. +In general, the raw representation is determined by the architecture, or +@value{GDBN}'s interface to the architecture, while the virtual representation +can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file, +@code{registers}, holds the register contents in raw format, and the +@value{GDBN} remote protocol transmits register values in raw format. + +Your architecture may define the following macros to request +conversions between the raw and virtual format: + +@deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg}) +Return non-zero if register number @var{reg}'s value needs different raw +and virtual formats. + +You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register +unless this macro returns a non-zero value for that register. +@end deftypefn + +@deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg}) +The size of register number @var{reg}'s raw value. This is the number +of bytes the register will occupy in @code{registers}, or in a @value{GDBN} +remote protocol packet. +@end deftypefn + +@deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg}) +The size of register number @var{reg}'s value, in its virtual format. +This is the size a @code{struct value}'s buffer will have, holding that +register's value. +@end deftypefn + +@deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg}) +This is the type of the virtual representation of register number +@var{reg}. Note that there is no need for a macro giving a type for the +register's raw form; once the register's value has been obtained, @value{GDBN} +always uses the virtual form. +@end deftypefn + +@deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) +Convert the value of register number @var{reg} to @var{type}, which +should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer +at @var{from} holds the register's value in raw format; the macro should +convert the value to virtual format, and place it at @var{to}. + +Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and +@code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type} +arguments in different orders. + +You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers +for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero +value. +@end deftypefn + +@deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) +Convert the value of register number @var{reg} to @var{type}, which +should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer +at @var{from} holds the register's value in raw format; the macro should +convert the value to virtual format, and place it at @var{to}. + +Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take +their @var{reg} and @var{type} arguments in different orders. +@end deftypefn + + +@section Using Different Register and Memory Data Representations +@cindex register representation +@cindex memory representation +@cindex representations, register and memory +@cindex register data formats, converting +@cindex @code{struct value}, converting register contents to + +@emph{Maintainer's note: The way GDB manipulates registers is undergoing +significant change. Many of the macros and functions refered to in this +section are likely to be subject to further revision. See +@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and +@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for +further information. cagney/2002-05-06.} + +Some architectures can represent a data object in a register using a +form that is different to the objects more normal memory representation. +For example: -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. +@itemize @bullet -Syntax: +@item +The Alpha architecture can represent 32 bit integer values in +floating-point registers. -@table @code -@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 +The x86 architecture supports 80-bit floating-point registers. The +@code{long double} data type occupies 96 bits in memory but only 80 bits +when stored in a register. +@end itemize -@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 +In general, the register representation of a data type is determined by +the architecture, or @value{GDBN}'s interface to the architecture, while +the memory representation is determined by the Application Binary +Interface. -@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. +For almost all data types on almost all architectures, the two +representations are identical, and no special handling is needed. +However, they do occasionally differ. Your architecture may define the +following macros to request conversions between the register and memory +representations of a data type: -@end table +@deftypefn {Target Macro} int CONVERT_REGISTER_P (int @var{reg}) +Return non-zero if the representation of a data value stored in this +register may be different to the representation of that same data value +when stored in memory. -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). +When non-zero, the macros @code{REGISTER_TO_VALUE} and +@code{VALUE_TO_REGISTER} are used to perform any necessary conversion. +@end deftypefn +@deftypefn {Target Macro} void REGISTER_TO_VALUE (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) +Convert the value of register number @var{reg} to a data object of type +@var{type}. The buffer at @var{from} holds the register's value in raw +format; the converted value should be placed in the buffer at @var{to}. -@node Wrapping, Frames, Cleanups, Top -@chapter Wrapping Output Lines +Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take +their @var{reg} and @var{type} arguments in different orders. -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. +You should only use @code{REGISTER_TO_VALUE} with registers for which +the @code{CONVERT_REGISTER_P} macro returns a non-zero value. +@end deftypefn -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! +@deftypefn {Target Macro} void VALUE_TO_REGISTER (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) +Convert a data value of type @var{type} to register number @var{reg}' +raw format. -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. +Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take +their @var{reg} and @var{type} arguments in different orders. -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. +You should only use @code{VALUE_TO_REGISTER} with registers for which +the @code{CONVERT_REGISTER_P} macro returns a non-zero value. +@end deftypefn +@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf}) +See @file{mips-tdep.c}. It does not do what you want. +@end deftypefn -@node Frames, , Wrapping, Top -@chapter Frames -A frame is a construct that GDB uses to keep track of calling and called -functions. +@section Frame Interpretation -@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: - -@example - create_new_frame (read_register (FP_REGNUM), read_pc ())); -@end example - -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 +@section Inferior Call Setup -@contents -@bye +@section Compiler Characteristics + +@section Target Conditionals + +This section describes the macros that you can use to define the target +machine. + +@table @code + +@item ADDITIONAL_OPTIONS +@itemx ADDITIONAL_OPTION_CASES +@itemx ADDITIONAL_OPTION_HANDLER +@itemx ADDITIONAL_OPTION_HELP +@findex ADDITIONAL_OPTION_HELP +@findex ADDITIONAL_OPTION_HANDLER +@findex ADDITIONAL_OPTION_CASES +@findex ADDITIONAL_OPTIONS +These are a set of macros that allow the addition of additional command +line options to @value{GDBN}. They are currently used only for the unsupported +i960 Nindy target, and should not be used in any other configuration. + +@item ADDR_BITS_REMOVE (addr) +@findex ADDR_BITS_REMOVE +If a raw machine instruction address includes any bits that are not +really part of the address, then define this macro to expand into an +expression that zeroes those bits in @var{addr}. This is only used for +addresses of instructions, and even then not in all contexts. + +For example, the two low-order bits of the PC on the Hewlett-Packard PA +2.0 architecture contain the privilege level of the corresponding +instruction. Since instructions must always be aligned on four-byte +boundaries, the processor masks out these bits to generate the actual +address of the instruction. ADDR_BITS_REMOVE should filter out these +bits with an expression such as @code{((addr) & ~3)}. + +@item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr}) +@findex ADDRESS_TO_POINTER +Store in @var{buf} a pointer of type @var{type} representing the address +@var{addr}, in the appropriate format for the current architecture. +This macro may safely assume that @var{type} is either a pointer or a +C@t{++} reference type. +@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. + +@item BEFORE_MAIN_LOOP_HOOK +@findex 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, @value{GDBN} will probably not compile, let alone run +correctly. This macro is currently used only for the unsupported i960 Nindy +target, and should not be used in any other configuration. + +@item BELIEVE_PCC_PROMOTION +@findex BELIEVE_PCC_PROMOTION +Define if the compiler promotes a @code{short} or @code{char} +parameter to an @code{int}, but still reports the parameter as its +original type, rather than the promoted type. + +@item BELIEVE_PCC_PROMOTION_TYPE +@findex BELIEVE_PCC_PROMOTION_TYPE +Define this if @value{GDBN} should believe the type of a @code{short} +argument when compiled by @code{pcc}, but look within a full int space to get +its value. Only defined for Sun-3 at present. + +@item BITS_BIG_ENDIAN +@findex BITS_BIG_ENDIAN +Define this if the numbering of bits in the targets does @strong{not} match the +endianness of the target byte order. A value of 1 means that the bits +are numbered in a big-endian bit order, 0 means little-endian. + +@item BREAKPOINT +@findex 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. + +@code{BREAKPOINT} has been deprecated in favor of +@code{BREAKPOINT_FROM_PC}. + +@item BIG_BREAKPOINT +@itemx LITTLE_BREAKPOINT +@findex LITTLE_BREAKPOINT +@findex BIG_BREAKPOINT +Similar to BREAKPOINT, but used for bi-endian targets. + +@code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in +favor of @code{BREAKPOINT_FROM_PC}. + +@item REMOTE_BREAKPOINT +@itemx LITTLE_REMOTE_BREAKPOINT +@itemx BIG_REMOTE_BREAKPOINT +@findex BIG_REMOTE_BREAKPOINT +@findex LITTLE_REMOTE_BREAKPOINT +@findex REMOTE_BREAKPOINT +Similar to BREAKPOINT, but used for remote targets. + +@code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been +deprecated in favor of @code{BREAKPOINT_FROM_PC}. + +@item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr}) +@findex BREAKPOINT_FROM_PC +Use the program counter to determine the contents and size of a +breakpoint instruction. It returns a pointer to a string of bytes +that encode a breakpoint instruction, stores the length of the string +to *@var{lenptr}, and adjusts pc (if necessary) to point to the actual +memory location where the breakpoint should be inserted. + +Although it is 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. + +Replaces all the other @var{BREAKPOINT} macros. + +@item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache}) +@itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache}) +@findex MEMORY_REMOVE_BREAKPOINT +@findex MEMORY_INSERT_BREAKPOINT +Insert or remove memory based breakpoints. Reasonable defaults +(@code{default_memory_insert_breakpoint} and +@code{default_memory_remove_breakpoint} respectively) have been +provided so that it is not necessary to define these for most +architectures. Architectures which may want to define +@code{MEMORY_INSERT_BREAKPOINT} and @code{MEMORY_REMOVE_BREAKPOINT} will +likely have instructions that are oddly sized or are not stored in a +conventional manner. + +It may also be desirable (from an efficiency standpoint) to define +custom breakpoint insertion and removal routines if +@code{BREAKPOINT_FROM_PC} needs to read the target's memory for some +reason. + +@item CALL_DUMMY_P +@findex CALL_DUMMY_P +A C expression that is non-zero when the target supports inferior function +calls. + +@item CALL_DUMMY_WORDS +@findex CALL_DUMMY_WORDS +Pointer to an array of @code{LONGEST} words of data containing +host-byte-ordered @code{REGISTER_BYTES} sized values that partially +specify the sequence of instructions needed for an inferior function +call. + +Should be deprecated in favor of a macro that uses target-byte-ordered +data. + +@item SIZEOF_CALL_DUMMY_WORDS +@findex SIZEOF_CALL_DUMMY_WORDS +The size of @code{CALL_DUMMY_WORDS}. When @code{CALL_DUMMY_P} this must +return a positive value. See also @code{CALL_DUMMY_LENGTH}. + +@item CALL_DUMMY +@findex CALL_DUMMY +A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated. + +@item CALL_DUMMY_LOCATION +@findex CALL_DUMMY_LOCATION +See the file @file{inferior.h}. + +@item CALL_DUMMY_STACK_ADJUST +@findex CALL_DUMMY_STACK_ADJUST +Stack adjustment needed when performing an inferior function call. + +Should be deprecated in favor of something like @code{STACK_ALIGN}. + +@item CALL_DUMMY_STACK_ADJUST_P +@findex CALL_DUMMY_STACK_ADJUST_P +Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}. + +Should be deprecated in favor of something like @code{STACK_ALIGN}. + +@item CANNOT_FETCH_REGISTER (@var{regno}) +@findex CANNOT_FETCH_REGISTER +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 CANNOT_STORE_REGISTER (@var{regno}) +@findex CANNOT_STORE_REGISTER +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, +@value{GDBN} will assume that all registers may be written. + +@item DO_DEFERRED_STORES +@itemx CLEAR_DEFERRED_STORES +@findex CLEAR_DEFERRED_STORES +@findex DO_DEFERRED_STORES +Define this to execute any deferred stores of registers into the inferior, +and to cancel any deferred stores. + +Currently only implemented correctly for native Sparc configurations? + +@item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual}) +@findex COERCE_FLOAT_TO_DOUBLE +@cindex promotion to @code{double} +@cindex @code{float} arguments +@cindex prototyped functions, passing arguments to +@cindex passing arguments to prototyped functions +Return non-zero if GDB should promote @code{float} values to +@code{double} when calling a non-prototyped function. The argument +@var{actual} is the type of the value we want to pass to the function. +The argument @var{formal} is the type of this argument, as it appears in +the function's definition. Note that @var{formal} may be zero if we +have no debugging information for the function, or if we're passing more +arguments than are officially declared (for example, varargs). This +macro is never invoked if the function definitely has a prototype. + +How you should pass arguments to a function depends on whether it was +defined in K&R style or prototype style. If you define a function using +the K&R syntax that takes a @code{float} argument, then callers must +pass that argument as a @code{double}. If you define the function using +the prototype syntax, then you must pass the argument as a @code{float}, +with no promotion. + +Unfortunately, on certain older platforms, the debug info doesn't +indicate reliably how each function was defined. A function type's +@code{TYPE_FLAG_PROTOTYPED} flag may be unset, even if the function was +defined in prototype style. When calling a function whose +@code{TYPE_FLAG_PROTOTYPED} flag is unset, GDB consults the +@code{COERCE_FLOAT_TO_DOUBLE} macro to decide what to do. + +@findex standard_coerce_float_to_double +For modern targets, it is proper to assume that, if the prototype flag +is unset, that can be trusted: @code{float} arguments should be promoted +to @code{double}. You should use the function +@code{standard_coerce_float_to_double} to get this behavior. + +@findex default_coerce_float_to_double +For some older targets, if the prototype flag is unset, that doesn't +tell us anything. So we guess that, if we don't have a type for the +formal parameter (@i{i.e.}, the first argument to +@code{COERCE_FLOAT_TO_DOUBLE} is null), then we should promote it; +otherwise, we should leave it alone. The function +@code{default_coerce_float_to_double} provides this behavior; it is the +default value, for compatibility with older configurations. + +@item int CONVERT_REGISTER_P(@var{regnum}) +@findex CONVERT_REGISTER_P +Return non-zero if register @var{regnum} can represent data values in a +non-standard form. +@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. + +@item CPLUS_MARKER +@findex CPLUS_MARKERz +Define this to expand into the character that G@t{++} 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{'.'}. + +@item DBX_PARM_SYMBOL_CLASS +@findex 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 DECR_PC_AFTER_BREAK +@findex 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 +@code{BREAKPOINT}, though not always. For most targets this value will be 0. + +@item DECR_PC_AFTER_HW_BREAK +@findex DECR_PC_AFTER_HW_BREAK +Similarly, for hardware breakpoints. + +@item DISABLE_UNSETTABLE_BREAK (@var{addr}) +@findex DISABLE_UNSETTABLE_BREAK +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 DO_REGISTERS_INFO +@findex DO_REGISTERS_INFO +If defined, use this to print the value of a register or all registers. + +@item PRINT_FLOAT_INFO() +#findex PRINT_FLOAT_INFO +If defined, then the @samp{info float} command will print information about +the processor's floating point unit. + +@item DWARF_REG_TO_REGNUM +@findex DWARF_REG_TO_REGNUM +Convert DWARF register number into @value{GDBN} regnum. If not defined, +no conversion will be performed. + +@item DWARF2_REG_TO_REGNUM +@findex DWARF2_REG_TO_REGNUM +Convert DWARF2 register number into @value{GDBN} regnum. If not +defined, no conversion will be performed. + +@item ECOFF_REG_TO_REGNUM +@findex ECOFF_REG_TO_REGNUM +Convert ECOFF register number into @value{GDBN} regnum. If not defined, +no conversion will be performed. + +@item END_OF_TEXT_DEFAULT +@findex END_OF_TEXT_DEFAULT +This is an expression that should designate the end of the text section. +@c (? FIXME ?) + +@item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf}) +@findex EXTRACT_RETURN_VALUE +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(@var{regbuf}) +@findex EXTRACT_STRUCT_VALUE_ADDRESS +When defined, extract from the array @var{regbuf} (containing the raw +register state) the @code{CORE_ADDR} at which a function should return +its structure value. + +If not defined, @code{EXTRACT_RETURN_VALUE} is used. + +@item EXTRACT_STRUCT_VALUE_ADDRESS_P() +@findex EXTRACT_STRUCT_VALUE_ADDRESS_P +Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}. + +@item FLOAT_INFO +@findex FLOAT_INFO +Deprecated in favor of @code{PRINT_FLOAT_INFO}. + +@item FP_REGNUM +@findex FP_REGNUM +If the virtual frame pointer is kept in a register, then define this +macro to be the number (greater than or equal to zero) of that register. + +This should only need to be defined if @code{TARGET_READ_FP} is not +defined. + +@item FRAMELESS_FUNCTION_INVOCATION(@var{fi}) +@findex FRAMELESS_FUNCTION_INVOCATION +Define this to an expression that returns 1 if the function invocation +represented by @var{fi} does not have a stack frame associated with it. +Otherwise return 0. + +@item FRAME_ARGS_ADDRESS_CORRECT +@findex FRAME_ARGS_ADDRESS_CORRECT +See @file{stack.c}. + +@item FRAME_CHAIN(@var{frame}) +@findex FRAME_CHAIN +Given @var{frame}, return a pointer to the calling frame. + +@item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe}) +@findex FRAME_CHAIN_VALID +Define this to be an expression that returns zero if the given frame is +an outermost frame, with no caller, and nonzero otherwise. Several +common definitions are available: + +@itemize @bullet +@item +@code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero +and given frame's PC is not inside the startup file (such as +@file{crt0.o}). + +@item +@code{func_frame_chain_valid} 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}). + +@item +@code{generic_file_frame_chain_valid} and +@code{generic_func_frame_chain_valid} are equivalent implementations for +targets using generic dummy frames. +@end itemize + +@item FRAME_INIT_SAVED_REGS(@var{frame}) +@findex FRAME_INIT_SAVED_REGS +See @file{frame.h}. Determines the address of all registers in the +current stack frame storing each in @code{frame->saved_regs}. Space for +@code{frame->saved_regs} shall be allocated by +@code{FRAME_INIT_SAVED_REGS} using either +@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}. + +@code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated. + +@item FRAME_NUM_ARGS (@var{fi}) +@findex FRAME_NUM_ARGS +For the frame described by @var{fi} return the number of arguments that +are being passed. If the number of arguments is not known, return +@code{-1}. + +@item FRAME_SAVED_PC(@var{frame}) +@findex FRAME_SAVED_PC +Given @var{frame}, return the pc saved there. This is the return +address. + +@item FUNCTION_EPILOGUE_SIZE +@findex 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 FUNCTION_START_OFFSET +@findex FUNCTION_START_OFFSET +An integer, giving the offset in bytes from a function's address (as +used in the values of symbols, function pointers, etc.), and the +function's first genuine instruction. + +This is zero on almost all machines: the function's address is usually +the address of its first instruction. However, on the VAX, for example, +each function starts with two bytes containing a bitmask indicating +which registers to save upon entry to the function. The VAX @code{call} +instructions check this value, and save the appropriate registers +automatically. Thus, since the offset from the function's address to +its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would +be 2 on the VAX. + +@item GCC_COMPILED_FLAG_SYMBOL +@itemx GCC2_COMPILED_FLAG_SYMBOL +@findex GCC2_COMPILED_FLAG_SYMBOL +@findex GCC_COMPILED_FLAG_SYMBOL +If defined, these are the names of the symbols that @value{GDBN} 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.) + +@item @value{GDBN}_MULTI_ARCH +@findex @value{GDBN}_MULTI_ARCH +If defined and non-zero, enables support for multiple architectures +within @value{GDBN}. + +This support can be enabled at two levels. At level one, only +definitions for previously undefined macros are provided; at level two, +a multi-arch definition of all architecture dependent macros will be +defined. + +@item @value{GDBN}_TARGET_IS_HPPA +@findex @value{GDBN}_TARGET_IS_HPPA +This determines whether horrible kludge code in @file{dbxread.c} and +@file{partial-stab.h} is used to mangle multiple-symbol-table files from +HPPA's. This should all be ripped out, and a scheme like @file{elfread.c} +used instead. + +@item GET_LONGJMP_TARGET +@findex 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 +the header file @file{setjmp.h} is needed to define it. + +This macro determines the target PC address that @code{longjmp} will jump to, +assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a +@code{CORE_ADDR *} as argument, and stores the target PC value through this +pointer. It examines the current state of the machine as needed. + +@item GET_SAVED_REGISTER +@findex GET_SAVED_REGISTER +@findex get_saved_register +Define this if you need to supply your own definition for the function +@code{get_saved_register}. + +@item IBM6000_TARGET +@findex 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 a haste and we are +repenting at leisure. + +@item I386_USE_GENERIC_WATCHPOINTS +An x86-based target can define this to use the generic x86 watchpoint +support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. + +@item SYMBOLS_CAN_START_WITH_DOLLAR +@findex SYMBOLS_CAN_START_WITH_DOLLAR +Some systems have routines whose names start with @samp{$}. Giving this +macro a non-zero value tells @value{GDBN}'s expression parser to check for such +routines when parsing tokens that begin with @samp{$}. + +On HP-UX, certain system routines (millicode) have names beginning with +@samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode +routine that handles inter-space procedure calls on PA-RISC. + +@item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame}) +@findex INIT_EXTRA_FRAME_INFO +If additional information about the frame is required this should be +stored in @code{frame->extra_info}. Space for @code{frame->extra_info} +is allocated using @code{frame_obstack_alloc}. + +@item INIT_FRAME_PC (@var{fromleaf}, @var{prev}) +@findex INIT_FRAME_PC +This is a C statement that sets the pc of the frame pointed to by +@var{prev}. [By default...] + +@item INNER_THAN (@var{lhs}, @var{rhs}) +@findex INNER_THAN +Returns non-zero if stack address @var{lhs} is inner than (nearer to the +stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if +the target's stack grows downward in memory, or @code{lhs > rsh} if the +stack grows upward. + +@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{pc}) +@findex gdbarch_in_function_epilogue_p +Returns non-zero if the given @var{pc} is in the epilogue of a function. +The epilogue of a function is defined as the part of a function where +the stack frame of the function already has been destroyed up to the +final `return from function call' instruction. + +@item SIGTRAMP_START (@var{pc}) +@findex SIGTRAMP_START +@itemx SIGTRAMP_END (@var{pc}) +@findex SIGTRAMP_END +Define these to be the start and end address of the @code{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 IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name}) +@findex IN_SOLIB_CALL_TRAMPOLINE +Define this to evaluate to nonzero if the program is stopped in the +trampoline that connects to a shared library. + +@item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name}) +@findex IN_SOLIB_RETURN_TRAMPOLINE +Define this to evaluate to nonzero if the program is stopped in the +trampoline that returns from a shared library. + +@item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc}) +@findex IN_SOLIB_DYNSYM_RESOLVE_CODE +Define this to evaluate to nonzero if the program is stopped in the +dynamic linker. + +@item SKIP_SOLIB_RESOLVER (@var{pc}) +@findex SKIP_SOLIB_RESOLVER +Define this to evaluate to the (nonzero) address at which execution +should continue to get past the dynamic linker's symbol resolution +function. A zero value indicates that it is not important or necessary +to set a breakpoint to get through the dynamic linker and that single +stepping will suffice. + +@item INTEGER_TO_ADDRESS (@var{type}, @var{buf}) +@findex INTEGER_TO_ADDRESS +@cindex converting integers to addresses +Define this when the architecture needs to handle non-pointer to address +conversions specially. Converts that value to an address according to +the current architectures conventions. + +@emph{Pragmatics: When the user copies a well defined expression from +their source code and passes it, as a parameter, to @value{GDBN}'s +@code{print} command, they should get the same value as would have been +computed by the target program. Any deviation from this rule can cause +major confusion and annoyance, and needs to be justified carefully. In +other words, @value{GDBN} doesn't really have the freedom to do these +conversions in clever and useful ways. It has, however, been pointed +out that users aren't complaining about how @value{GDBN} casts integers +to pointers; they are complaining that they can't take an address from a +disassembly listing and give it to @code{x/i}. Adding an architecture +method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for +@value{GDBN} to ``get it right'' in all circumstances.} + +@xref{Target Architecture Definition, , Pointers Are Not Always +Addresses}. + +@item IS_TRAPPED_INTERNALVAR (@var{name}) +@findex IS_TRAPPED_INTERNALVAR +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 @value{GDBN}. Currently only used by the h8500. Note that this +could be either a host or target conditional. + +@item NEED_TEXT_START_END +@findex NEED_TEXT_START_END +Define this if @value{GDBN} should determine the start and end addresses of the +text section. (Seems dubious.) + +@item NO_HIF_SUPPORT +@findex NO_HIF_SUPPORT +(Specific to the a29k.) + +@item POINTER_TO_ADDRESS (@var{type}, @var{buf}) +@findex POINTER_TO_ADDRESS +Assume that @var{buf} holds a pointer of type @var{type}, in the +appropriate format for the current architecture. Return the byte +address the pointer refers to. +@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. + +@item REGISTER_CONVERTIBLE (@var{reg}) +@findex REGISTER_CONVERTIBLE +Return non-zero if @var{reg} uses different raw and virtual formats. +@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. + +@item REGISTER_TO_VALUE(@var{regnum}, @var{type}, @var{from}, @var{to}) +@findex REGISTER_TO_VALUE +Convert the raw contents of register @var{regnum} into a value of type +@var{type}. +@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. + +@item REGISTER_RAW_SIZE (@var{reg}) +@findex REGISTER_RAW_SIZE +Return the raw size of @var{reg}; defaults to the size of the register's +virtual type. +@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. + +@item REGISTER_VIRTUAL_SIZE (@var{reg}) +@findex REGISTER_VIRTUAL_SIZE +Return the virtual size of @var{reg}; defaults to the size of the +register's virtual type. +Return the virtual size of @var{reg}. +@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. + +@item REGISTER_VIRTUAL_TYPE (@var{reg}) +@findex REGISTER_VIRTUAL_TYPE +Return the virtual type of @var{reg}. +@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. + +@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to}) +@findex REGISTER_CONVERT_TO_VIRTUAL +Convert the value of register @var{reg} from its raw form to its virtual +form. +@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. + +@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to}) +@findex REGISTER_CONVERT_TO_RAW +Convert the value of register @var{reg} from its virtual form to its raw +form. +@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. + +@item RETURN_VALUE_ON_STACK(@var{type}) +@findex RETURN_VALUE_ON_STACK +@cindex returning structures by value +@cindex structures, returning by value + +Return non-zero if values of type TYPE are returned on the stack, using +the ``struct convention'' (i.e., the caller provides a pointer to a +buffer in which the callee should store the return value). This +controls how the @samp{finish} command finds a function's return value, +and whether an inferior function call reserves space on the stack for +the return value. + +The full logic @value{GDBN} uses here is kind of odd. + +@itemize @bullet +@item +If the type being returned by value is not a structure, union, or array, +and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN} +concludes the value is not returned using the struct convention. + +@item +Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below). +If that returns non-zero, @value{GDBN} assumes the struct convention is +in use. +@end itemize + +In other words, to indicate that a given type is returned by value using +the struct convention, that type must be either a struct, union, array, +or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something +that @code{USE_STRUCT_CONVENTION} likes. + +Note that, in C and C@t{++}, arrays are never returned by value. In those +languages, these predicates will always see a pointer type, never an +array type. All the references above to arrays being returned by value +apply only to other languages. + +@item SOFTWARE_SINGLE_STEP_P() +@findex SOFTWARE_SINGLE_STEP_P +Define this as 1 if the target does not have a hardware single-step +mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined. + +@item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p}) +@findex SOFTWARE_SINGLE_STEP +A function that inserts or removes (depending on +@var{insert_breapoints_p}) breakpoints at each possible destinations of +the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c} +for examples. + +@item SOFUN_ADDRESS_MAYBE_MISSING +@findex SOFUN_ADDRESS_MAYBE_MISSING +Somebody clever observed that, the more actual addresses you have in the +debug information, the more time the linker has to spend relocating +them. So whenever there's some other way the debugger could find the +address it needs, you should omit it from the debug info, to make +linking faster. + +@code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of +hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN} +entries in stabs-format debugging information. @code{N_SO} stabs mark +the beginning and ending addresses of compilation units in the text +segment. @code{N_FUN} stabs mark the starts and ends of functions. + +@code{SOFUN_ADDRESS_MAYBE_MISSING} means two things: + +@itemize @bullet +@item +@code{N_FUN} stabs have an address of zero. Instead, you should find the +addresses where the function starts by taking the function name from +the stab, and then looking that up in the minsyms (the +linker/assembler symbol table). In other words, the stab has the +name, and the linker/assembler symbol table is the only place that carries +the address. + +@item +@code{N_SO} stabs have an address of zero, too. You just look at the +@code{N_FUN} stabs that appear before and after the @code{N_SO} stab, +and guess the starting and ending addresses of the compilation unit from +them. +@end itemize + +@item PCC_SOL_BROKEN +@findex PCC_SOL_BROKEN +(Used only in the Convex target.) + +@item PC_IN_CALL_DUMMY +@findex PC_IN_CALL_DUMMY +See @file{inferior.h}. + +@item PC_IN_SIGTRAMP (@var{pc}, @var{name}) +@findex PC_IN_SIGTRAMP +@cindex sigtramp +The @dfn{sigtramp} is a routine that the kernel calls (which then calls +the signal handler). On most machines it is a library routine that is +linked into the executable. + +This function, given a program counter value in @var{pc} and the +(possibly NULL) name of the function in which that @var{pc} resides, +returns nonzero if the @var{pc} and/or @var{name} show that we are in +sigtramp. + +@item PC_LOAD_SEGMENT +@findex PC_LOAD_SEGMENT +If defined, print information about the load segment for the program +counter. (Defined only for the RS/6000.) + +@item PC_REGNUM +@findex PC_REGNUM +If the program counter is kept in a register, then define this macro to +be the number (greater than or equal to zero) of that register. + +This should only need to be defined if @code{TARGET_READ_PC} and +@code{TARGET_WRITE_PC} are not defined. + +@item NPC_REGNUM +@findex NPC_REGNUM +The number of the ``next program counter'' register, if defined. + +@item PARM_BOUNDARY +@findex PARM_BOUNDARY +If non-zero, round arguments to a boundary of this many bits before +pushing them on the stack. + +@item PRINT_REGISTER_HOOK (@var{regno}) +@findex PRINT_REGISTER_HOOK +If defined, this must be a function that prints the contents of the +given register to standard output. + +@item PRINT_TYPELESS_INTEGER +@findex PRINT_TYPELESS_INTEGER +This is an obscure substitute for @code{print_longest} that seems to +have been defined for the Convex target. + +@item PROCESS_LINENUMBER_HOOK +@findex PROCESS_LINENUMBER_HOOK +A hook defined for XCOFF reading. + +@item PROLOGUE_FIRSTLINE_OVERLAP +@findex PROLOGUE_FIRSTLINE_OVERLAP +(Only used in unsupported Convex configuration.) + +@item PS_REGNUM +@findex 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 POP_FRAME +@findex POP_FRAME +@findex call_function_by_hand +@findex return_command +Used in @samp{call_function_by_hand} to remove an artificial stack +frame and in @samp{return_command} to remove a real stack frame. + +@item PUSH_ARGUMENTS (@var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) +@findex PUSH_ARGUMENTS +Define this to push arguments onto the stack for inferior function +call. Returns the updated stack pointer value. + +@item PUSH_DUMMY_FRAME +@findex PUSH_DUMMY_FRAME +Used in @samp{call_function_by_hand} to create an artificial stack frame. + +@item REGISTER_BYTES +@findex REGISTER_BYTES +The total amount of space needed to store @value{GDBN}'s copy of the machine's +register state. + +@item REGISTER_NAME(@var{i}) +@findex REGISTER_NAME +Return the name of register @var{i} as a string. May return @code{NULL} +or @code{NUL} to indicate that register @var{i} is not valid. + +@item REGISTER_NAMES +@findex REGISTER_NAMES +Deprecated in favor of @code{REGISTER_NAME}. + +@item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type}) +@findex REG_STRUCT_HAS_ADDR +Define this to return 1 if the given type will be passed by pointer +rather than directly. + +@item SAVE_DUMMY_FRAME_TOS (@var{sp}) +@findex SAVE_DUMMY_FRAME_TOS +Used in @samp{call_function_by_hand} to notify the target dependent code +of the top-of-stack value that will be passed to the the inferior code. +This is the value of the @code{SP} after both the dummy frame and space +for parameters/results have been allocated on the stack. + +@item SDB_REG_TO_REGNUM +@findex SDB_REG_TO_REGNUM +Define this to convert sdb register numbers into @value{GDBN} regnums. If not +defined, no conversion will be done. + +@c OBSOLETE @item SHIFT_INST_REGS +@c OBSOLETE @findex SHIFT_INST_REGS +@c OBSOLETE (Only used for m88k targets.) + +@item SKIP_PERMANENT_BREAKPOINT +@findex SKIP_PERMANENT_BREAKPOINT +Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally +steps over a breakpoint by removing it, stepping one instruction, and +re-inserting the breakpoint. However, permanent breakpoints are +hardwired into the inferior, and can't be removed, so this strategy +doesn't work. Calling @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's +state so that execution will resume just after the breakpoint. This +macro does the right thing even when the breakpoint is in the delay slot +of a branch or jump. + +@item SKIP_PROLOGUE (@var{pc}) +@findex SKIP_PROLOGUE +A C expression that returns the address of the ``real'' code beyond the +function entry prologue found at @var{pc}. + +@item SKIP_TRAMPOLINE_CODE (@var{pc}) +@findex SKIP_TRAMPOLINE_CODE +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 SP_REGNUM +@findex SP_REGNUM +If the stack-pointer is kept in a register, then define this macro to be +the number (greater than or equal to zero) of that register. + +This should only need to be defined if @code{TARGET_WRITE_SP} and +@code{TARGET_WRITE_SP} are not defined. + +@item STAB_REG_TO_REGNUM +@findex STAB_REG_TO_REGNUM +Define this to convert stab register numbers (as gotten from `r' +declarations) into @value{GDBN} regnums. If not defined, no conversion will be +done. + +@item STACK_ALIGN (@var{addr}) +@findex STACK_ALIGN +Define this to adjust the address to the alignment required for the +processor's stack. + +@item STEP_SKIPS_DELAY (@var{addr}) +@findex STEP_SKIPS_DELAY +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, @value{GDBN} will single-step over that instruction before resuming +normally. Currently only defined for the Mips. + +@item STORE_RETURN_VALUE (@var{type}, @var{valbuf}) +@findex STORE_RETURN_VALUE +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 SUN_FIXED_LBRAC_BUG +@findex SUN_FIXED_LBRAC_BUG +(Used only for Sun-3 and Sun-4 targets.) + +@item SYMBOL_RELOADING_DEFAULT +@findex SYMBOL_RELOADING_DEFAULT +The default value of the ``symbol-reloading'' variable. (Never defined in +current sources.) + +@item TARGET_CHAR_BIT +@findex TARGET_CHAR_BIT +Number of bits in a char; defaults to 8. + +@item TARGET_CHAR_SIGNED +@findex TARGET_CHAR_SIGNED +Non-zero if @code{char} is normally signed on this architecture; zero if +it should be unsigned. + +The ISO C standard requires the compiler to treat @code{char} as +equivalent to either @code{signed char} or @code{unsigned char}; any +character in the standard execution set is supposed to be positive. +Most compilers treat @code{char} as signed, but @code{char} is unsigned +on the IBM S/390, RS6000, and PowerPC targets. + +@item TARGET_COMPLEX_BIT +@findex TARGET_COMPLEX_BIT +Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. + +At present this macro is not used. + +@item TARGET_DOUBLE_BIT +@findex TARGET_DOUBLE_BIT +Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. + +@item TARGET_DOUBLE_COMPLEX_BIT +@findex TARGET_DOUBLE_COMPLEX_BIT +Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. + +At present this macro is not used. + +@item TARGET_FLOAT_BIT +@findex TARGET_FLOAT_BIT +Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. + +@item TARGET_INT_BIT +@findex TARGET_INT_BIT +Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. + +@item TARGET_LONG_BIT +@findex TARGET_LONG_BIT +Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. + +@item TARGET_LONG_DOUBLE_BIT +@findex TARGET_LONG_DOUBLE_BIT +Number of bits in a long double float; +defaults to @code{2 * TARGET_DOUBLE_BIT}. + +@item TARGET_LONG_LONG_BIT +@findex TARGET_LONG_LONG_BIT +Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. + +@item TARGET_PTR_BIT +@findex TARGET_PTR_BIT +Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. + +@item TARGET_SHORT_BIT +@findex TARGET_SHORT_BIT +Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. + +@item TARGET_READ_PC +@findex TARGET_READ_PC +@itemx TARGET_WRITE_PC (@var{val}, @var{pid}) +@findex TARGET_WRITE_PC +@itemx TARGET_READ_SP +@findex TARGET_READ_SP +@itemx TARGET_WRITE_SP +@findex TARGET_WRITE_SP +@itemx TARGET_READ_FP +@findex TARGET_READ_FP +@findex read_pc +@findex write_pc +@findex read_sp +@findex write_sp +@findex read_fp +These change the behavior of @code{read_pc}, @code{write_pc}, +@code{read_sp}, @code{write_sp} and @code{read_fp}. For most targets, +these may be left undefined. @value{GDBN} will call the read and write +register functions with the relevant @code{_REGNUM} argument. + +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 TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp}) +@findex TARGET_VIRTUAL_FRAME_POINTER +Returns a @code{(register, offset)} pair representing the virtual +frame pointer in use at the code address @var{pc}. If virtual +frame pointers are not used, a default definition simply returns +@code{FP_REGNUM}, with an offset of zero. + +@item TARGET_HAS_HARDWARE_WATCHPOINTS +If non-zero, the target has support for hardware-assisted +watchpoints. @xref{Algorithms, watchpoints}, for more details and +other related macros. + +@item TARGET_PRINT_INSN (@var{addr}, @var{info}) +@findex TARGET_PRINT_INSN +This is the function used by @value{GDBN} to print an assembly +instruction. It prints the instruction at address @var{addr} in +debugged memory and returns the length of the instruction, in bytes. If +a target doesn't define its own printing routine, it defaults to an +accessor function for the global pointer @code{tm_print_insn}. This +usually points to a function in the @code{opcodes} library (@pxref{Support +Libraries, ,Opcodes}). @var{info} is a structure (of type +@code{disassemble_info}) defined in @file{include/dis-asm.h} used to +pass information to the instruction decoding routine. + +@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) +@findex USE_STRUCT_CONVENTION +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 VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to}) +@findex VALUE_TO_REGISTER +Convert a value of type @var{type} into the raw contents of register +@var{regnum}'s. +@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. + +@item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p}) +@findex VARIABLES_INSIDE_BLOCK +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 @value{GDBN} has noticed the +presence of either the @code{GCC_COMPILED_SYMBOL} or the +@code{GCC2_COMPILED_SYMBOL}. By default, this is 0. + +@item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p}) +@findex OS9K_VARIABLES_INSIDE_BLOCK +Similarly, for OS/9000. Defaults to 1. +@end table + +Motorola M68K target conditionals. + +@ftable @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 REMOTE_BPT_VECTOR +Defaults to @code{1}. +@end ftable + +@section Adding a New Target + +@cindex adding a target +The following files add a target to @value{GDBN}: + +@table @file +@vindex TDEPFILES +@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{}} and @samp{TDEPLIBS=@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, replaced by autoconf, and may go away in +future versions of @value{GDBN}. + +@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. + +@item gdb/@var{arch}-tdep.c +@itemx gdb/@var{arch}-tdep.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{@var{ttt}-tdep.h}. It can be shared among many targets that use +the same processor. + +@item gdb/config/@var{arch}/tm-@var{ttt}.h +(@file{tm.h} is a link to this file, created by @code{configure}). Contains +macro definitions about the target machine's registers, stack frame +format and instructions. + +New targets do not need this file and should not create it. + +@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. + +New targets do not need this file and should not create it. + +@end table + +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}. + + +@section Converting an existing Target Architecture to Multi-arch +@cindex converting targets to multi-arch + +This section describes the current accepted best practice for converting +an existing target architecture to the multi-arch framework. + +The process consists of generating, testing, posting and committing a +sequence of patches. Each patch must contain a single change, for +instance: + +@itemize @bullet + +@item +Directly convert a group of functions into macros (the conversion does +not change the behavior of any of the functions). + +@item +Replace a non-multi-arch with a multi-arch mechanism (e.g., +@code{FRAME_INFO}). + +@item +Enable multi-arch level one. + +@item +Delete one or more files. + +@end itemize + +@noindent +There isn't a size limit on a patch, however, a developer is strongly +encouraged to keep the patch size down. + +Since each patch is well defined, and since each change has been tested +and shows no regressions, the patches are considered @emph{fairly} +obvious. Such patches, when submitted by developers listed in the +@file{MAINTAINERS} file, do not need approval. Occasional steps in the +process may be more complicated and less clear. The developer is +expected to use their judgment and is encouraged to seek advice as +needed. + +@subsection Preparation + +The first step is to establish control. Build (with @option{-Werror} +enabled) and test the target so that there is a baseline against which +the debugger can be compared. + +At no stage can the test results regress or @value{GDBN} stop compiling +with @option{-Werror}. + +@subsection Add the multi-arch initialization code + +The objective of this step is to establish the basic multi-arch +framework. It involves + +@itemize @bullet + +@item +The addition of a @code{@var{arch}_gdbarch_init} function@footnote{The +above is from the original example and uses K&R C. @value{GDBN} +has since converted to ISO C but lets ignore that.} that creates +the architecture: +@smallexample +static struct gdbarch * +d10v_gdbarch_init (info, arches) + struct gdbarch_info info; + struct gdbarch_list *arches; +@{ + struct gdbarch *gdbarch; + /* there is only one d10v architecture */ + if (arches != NULL) + return arches->gdbarch; + gdbarch = gdbarch_alloc (&info, NULL); + return gdbarch; +@} +@end smallexample +@noindent +@emph{} + +@item +A per-architecture dump function to print any architecture specific +information: +@smallexample +static void +mips_dump_tdep (struct gdbarch *current_gdbarch, + struct ui_file *file) +@{ + @dots{} code to print architecture specific info @dots{} +@} +@end smallexample + +@item +A change to @code{_initialize_@var{arch}_tdep} to register this new +architecture: +@smallexample +void +_initialize_mips_tdep (void) +@{ + gdbarch_register (bfd_arch_mips, mips_gdbarch_init, + mips_dump_tdep); +@end smallexample + +@item +Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@* +@file{config/@var{arch}/tm-@var{arch}.h}. + +@end itemize + +@subsection Update multi-arch incompatible mechanisms + +Some mechanisms do not work with multi-arch. They include: + +@table @code +@item EXTRA_FRAME_INFO +Delete. +@item FRAME_FIND_SAVED_REGS +Replaced with @code{FRAME_INIT_SAVED_REGS} +@end table + +@noindent +At this stage you could also consider converting the macros into +functions. + +@subsection Prepare for multi-arch level to one + +Temporally set @code{GDB_MULTI_ARCH} to @code{GDB_MULTI_ARCH_PARTIAL} +and then build and start @value{GDBN} (the change should not be +committed). @value{GDBN} may not build, and once built, it may die with +an internal error listing the architecture methods that must be +provided. + +Fix any build problems (patch(es)). + +Convert all the architecture methods listed, which are only macros, into +functions (patch(es)). + +Update @code{@var{arch}_gdbarch_init} to set all the missing +architecture methods and wrap the corresponding macros in @code{#if +!GDB_MULTI_ARCH} (patch(es)). + +@subsection Set multi-arch level one + +Change the value of @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL (a +single patch). + +Any problems with throwing ``the switch'' should have been fixed +already. + +@subsection Convert remaining macros + +Suggest converting macros into functions (and setting the corresponding +architecture method) in small batches. + +@subsection Set multi-arch level to two + +This should go smoothly. + +@subsection Delete the TM file + +The @file{tm-@var{arch}.h} can be deleted. @file{@var{arch}.mt} and +@file{configure.in} updated. + + +@node Target Vector Definition + +@chapter Target Vector Definition +@cindex target vector + +The target vector defines the interface between @value{GDBN}'s +abstract handling of target systems, and the nitty-gritty code that +actually exercises control over a process or a serial port. +@value{GDBN} includes some 30-40 different target vectors; however, +each configuration of @value{GDBN} includes only a few of them. + +@section File Targets + +Both executables and core files have target vectors. + +@section Standard Protocol and Remote Stubs + +@value{GDBN}'s file @file{remote.c} talks a serial protocol to code +that runs in the target system. @value{GDBN} provides several sample +@dfn{stubs} that can be integrated into target programs or operating +systems for this purpose; they are named @file{*-stub.c}. + +The @value{GDBN} 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. + +The trap handling code in the stub assumes the following upon entry to +@code{trap_low}: + +@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 + +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 +set up the hardware traps to actually execute code which calls the stub +first, and then transfers to its own trap handler. + +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. + +From reading the stub, it's probably not obvious how breakpoints work. +They are simply done by deposit/examine operations from @value{GDBN}. + +@section ROM Monitor Interface + +@section Custom Protocols + +@section Transport Layer + +@section Builtin Simulator + + +@node Native Debugging + +@chapter Native Debugging +@cindex native debugging + +Several files control @value{GDBN}'s configuration for native support: + +@table @file +@vindex NATDEPFILES +@item gdb/config/@var{arch}/@var{xyz}.mh +Specifies Makefile fragments needed by a @emph{native} configuration 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}. + +@emph{Maintainer's note: The @file{.mh} suffix is because this file +originally contained @file{Makefile} fragments for hosting @value{GDBN} +on machine @var{xyz}. While the file is no longer used for this +purpose, the @file{.mh} suffix remains. Perhaps someone will +eventually rename these fragments so that they have a @file{.mn} +suffix.} + +@item gdb/config/@var{arch}/nm-@var{xyz}.h +(@file{nm.h} is a link to this file, created by @code{configure}). Contains C +macro definitions describing the native system environment, such as +child process control and core file support. + +@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. +@end table + +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}. + +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 @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o} +into @code{NATDEPFILES}. + +@table @file +@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 procfs.c +This contains the @emph{target_ops vector} that supports Unix child +processes on systems which use /proc to control the child. + +@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 infptrace.c +This is the low level interface to inferior processes for systems using +the Unix @code{ptrace} call in a vanilla way. +@end table + +@section Native core file Support +@cindex native core files + +@table @file +@findex fetch_core_registers +@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 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 @value{GDBN} +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 +@end table + +When making @value{GDBN} 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 @code{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. + +Then back in @value{GDBN}, 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 @value{GDBN}'s ``registers'' array. + +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. + +@section ptrace + +@section /proc + +@section win32 + +@section shared libraries + +@section Native Conditionals +@cindex native conditionals + +When @value{GDBN} 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}. + +@table @code +@item ATTACH_DETACH +@findex ATTACH_DETACH +If defined, then @value{GDBN} will include support for the @code{attach} and +@code{detach} commands. + +@item CHILD_PREPARE_TO_STORE +@findex 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. + +[Note that this is incorrectly defined in @file{xm-@var{system}.h} files +currently.] + +@item FETCH_INFERIOR_REGISTERS +@findex 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 FILES_INFO_HOOK +@findex FILES_INFO_HOOK +(Only defined for Convex.) + +@item FP0_REGNUM +@findex 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, @file{/proc} support uses this +to decide whether floats are in use on this target. + +@item GET_LONGJMP_TARGET +@findex 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 +@file{setjmp.h} is needed to define it. + +This macro determines the target PC address that @code{longjmp} will jump to, +assuming that we have just stopped at a longjmp breakpoint. It takes a +@code{CORE_ADDR *} as argument, and stores the target PC value through this +pointer. It examines the current state of the machine as needed. + +@item I386_USE_GENERIC_WATCHPOINTS +An x86-based machine can define this to use the generic x86 watchpoint +support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. + +@item KERNEL_U_ADDR +@findex 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. @value{GDBN} +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 KERNEL_U_ADDR_BSD +@findex KERNEL_U_ADDR_BSD +Define this to cause @value{GDBN} 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 KERNEL_U_ADDR_HPUX +@findex KERNEL_U_ADDR_HPUX +Define this to cause @value{GDBN} 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 ONE_PROCESS_WRITETEXT +@findex 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 PREPARE_TO_PROCEED (@var{select_it}) +@findex PREPARE_TO_PROCEED +This (ugly) macro allows a native configuration to customize the way the +@code{proceed} function in @file{infrun.c} deals with switching between +threads. + +In a multi-threaded task we may select another thread and then continue +or step. But if the old thread was stopped at a breakpoint, it will +immediately cause another breakpoint stop without any execution (i.e. it +will report a breakpoint hit incorrectly). So @value{GDBN} must step over it +first. + +If defined, @code{PREPARE_TO_PROCEED} should check the current thread +against the thread that reported the most recent event. If a step-over +is required, it returns TRUE. If @var{select_it} is non-zero, it should +reselect the old thread. + +@item PROC_NAME_FMT +@findex 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 PTRACE_FP_BUG +@findex PTRACE_FP_BUG +See @file{mach386-xdep.c}. + +@item PTRACE_ARG3_TYPE +@findex 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 REGISTER_U_ADDR +@findex REGISTER_U_ADDR +Defines the offset of the registers in the ``u area''. + +@item SHELL_COMMAND_CONCAT +@findex SHELL_COMMAND_CONCAT +If defined, is a string to prefix on the shell command used to start the +inferior. + +@item SHELL_FILE +@findex SHELL_FILE +If defined, this is the name of the shell to use to run the inferior. +Defaults to @code{"/bin/sh"}. + +@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms}) +@findex SOLIB_ADD +Define this to expand into an expression that will cause the symbols in +@var{filename} to be added to @value{GDBN}'s symbol table. If +@var{readsyms} is zero symbols are not read but any necessary low level +processing for @var{filename} is still done. + +@item SOLIB_CREATE_INFERIOR_HOOK +@findex 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 START_INFERIOR_TRAPS_EXPECTED +@findex START_INFERIOR_TRAPS_EXPECTED +When starting an inferior, @value{GDBN} 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 SVR4_SHARED_LIBS +@findex SVR4_SHARED_LIBS +Define this to indicate that SVR4-style shared libraries are in use. + +@item USE_PROC_FS +@findex USE_PROC_FS +This determines whether small routines in @file{*-tdep.c}, which +translate register values between @value{GDBN}'s internal +representation and the @file{/proc} representation, are compiled. + +@item U_REGS_OFFSET +@findex 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. + +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 @code{u.u_ar0} @emph{is} the location of the registers. + +@item CLEAR_SOLIB +@findex CLEAR_SOLIB +See @file{objfiles.c}. + +@item DEBUG_PTRACE +@findex DEBUG_PTRACE +Define this to debug @code{ptrace} calls. +@end table + + +@node Support Libraries + +@chapter Support Libraries + +@section BFD +@cindex BFD library + +BFD provides support for @value{GDBN} in several ways: + +@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 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). @value{GDBN} simply +calls BFD to read or write section @var{x} at byte offset @var{y} for +length @var{z}. + +@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 locating the symbol information +@value{GDBN} uses an internal interface of BFD to determine where to find the +symbol information in an executable file or symbol-file. @value{GDBN} itself +handles the reading of symbols, since BFD does not ``understand'' debug +symbols, but @value{GDBN} uses BFD's cached information to find the symbols, +string table, etc. +@end table + +@section opcodes +@cindex opcodes library + +The opcodes library provides @value{GDBN}'s disassembler. (It's a separate +library because it's also used in binutils, for @file{objdump}). + +@section readline + +@section mmalloc + +@section libiberty + +@section gnu-regex +@cindex regular expressions library + +Regex conditionals. + +@table @code +@item C_ALLOCA + +@item NFAILURES + +@item RE_NREGS + +@item SIGN_EXTEND_CHAR + +@item SWITCH_ENUM_BUG + +@item SYNTAX_TABLE + +@item Sword + +@item sparc +@end table + +@section include + +@node Coding + +@chapter Coding + +This chapter covers topics that are lower-level than the major +algorithms of @value{GDBN}. + +@section Cleanups +@cindex cleanups + +Cleanups are a structured way to deal with things that need to be done +later. + +When your code does something (e.g., @code{xmalloc} some memory, or +@code{open} a file) that needs to be undone later (e.g., @code{xfree} +the memory or @code{close} the file), it can make a cleanup. The +cleanup will be done at some future point: when the command is finished +and control returns to the top level; when an error occurs and the stack +is unwound; or when your code decides it's time to explicitly perform +cleanups. Alternatively you can elect to discard the cleanups you +created. + +Syntax: + +@table @code +@item struct cleanup *@var{old_chain}; +Declare a variable which will hold a cleanup chain handle. + +@findex make_cleanup +@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 later be passed to @code{do_cleanups} or +@code{discard_cleanups}. Unless you are going to call +@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result +from @code{make_cleanup}. + +@findex do_cleanups +@item do_cleanups (@var{old_chain}); +Do all cleanups added to the chain since the corresponding +@code{make_cleanup} call was made. + +@findex discard_cleanups +@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 + +Cleanups are implemented as a chain. The handle returned by +@code{make_cleanups} includes the cleanup passed to the call and any +later cleanups appended to the chain (but not yet discarded or +performed). E.g.: + +@smallexample +make_cleanup (a, 0); +@{ + struct cleanup *old = make_cleanup (b, 0); + make_cleanup (c, 0) + ... + do_cleanups (old); +@} +@end smallexample + +@noindent +will call @code{c()} and @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 + +Your function should explicitly do or discard the cleanups it creates. +Failing to do this leads to non-deterministic behavior since the caller +will arbitrarily do or discard your functions cleanups. This need leads +to two common cleanup styles. + +The first style is try/finally. Before it exits, your code-block calls +@code{do_cleanups} with the old cleanup chain and thus ensures that your +code-block's cleanups are always performed. For instance, the following +code-segment avoids a memory leak problem (even when @code{error} is +called and a forced stack unwind occurs) by ensuring that the +@code{xfree} will always be called: + +@smallexample +struct cleanup *old = make_cleanup (null_cleanup, 0); +data = xmalloc (sizeof blah); +make_cleanup (xfree, data); +... blah blah ... +do_cleanups (old); +@end smallexample + +The second style is try/except. Before it exits, your code-block calls +@code{discard_cleanups} with the old cleanup chain and thus ensures that +any created cleanups are not performed. For instance, the following +code segment, ensures that the file will be closed but only if there is +an error: + +@smallexample +FILE *file = fopen ("afile", "r"); +struct cleanup *old = make_cleanup (close_file, file); +... blah blah ... +discard_cleanups (old); +return file; +@end smallexample + +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 Per-architecture module data +@cindex per-architecture module data +@cindex multi-arch data +@cindex data-pointer, per-architecture/per-module + +The multi-arch framework includes a mechanism for adding module specific +per-architecture data-pointers to the @code{struct gdbarch} architecture +object. + +A module registers one or more per-architecture data-pointers using the +function @code{register_gdbarch_data}: + +@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free}) + +The @var{init} function is used to obtain an initial value for a +per-architecture data-pointer. The function is called, after the +architecture has been created, when the data-pointer is still +uninitialized (@code{NULL}) and its value has been requested via a call +to @code{gdbarch_data}. A data-pointer can also be initialize +explicitly using @code{set_gdbarch_data}. + +The @var{free} function is called when a data-pointer needs to be +destroyed. This occurs when either the corresponding @code{struct +gdbarch} object is being destroyed or when @code{set_gdbarch_data} is +overriding a non-@code{NULL} data-pointer value. + +The function @code{register_gdbarch_data} returns a @code{struct +gdbarch_data} that is used to identify the data-pointer that was added +to the module. + +@end deftypefun + +A typical module has @code{init} and @code{free} functions of the form: + +@smallexample +static struct gdbarch_data *nozel_handle; +static void * +nozel_init (struct gdbarch *gdbarch) +@{ + struct nozel *data = XMALLOC (struct nozel); + @dots{} + return data; +@} +@dots{} +static void +nozel_free (struct gdbarch *gdbarch, void *data) +@{ + xfree (data); +@} +@end smallexample + +Since uninitialized (@code{NULL}) data-pointers are initialized +on-demand, an @code{init} function is free to call other modules that +use data-pointers. Those modules data-pointers will be initialized as +needed. Care should be taken to ensure that the @code{init} call graph +does not contain cycles. + +The data-pointer is registered with the call: + +@smallexample +void +_initialize_nozel (void) +@{ + nozel_handle = register_gdbarch_data (nozel_init, nozel_free); +@dots{} +@end smallexample + +The per-architecture data-pointer is accessed using the function: + +@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) +Given the architecture @var{arch} and module data handle +@var{data_handle} (returned by @code{register_gdbarch_data}, this +function returns the current value of the per-architecture data-pointer. +@end deftypefun + +The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should +be saved in a local variable and then used directly: + +@smallexample +int +nozel_total (struct gdbarch *gdbarch) +@{ + int total; + struct nozel *data = gdbarch_data (gdbarch, nozel_handle); + @dots{} + return total; +@} +@end smallexample + +It is also possible to directly initialize the data-pointer using: + +@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer}) +Update the data-pointer corresponding to @var{handle} with the value of +@var{pointer}. If the previous data-pointer value is non-NULL, then it +is freed using data-pointers @var{free} function. +@end deftypefun + +This function is used by modules that require a mechanism for explicitly +setting the per-architecture data-pointer during architecture creation: + +@smallexample +/* Called during architecture creation. */ +extern void +set_gdbarch_nozel (struct gdbarch *gdbarch, + int total) +@{ + struct nozel *data = XMALLOC (struct nozel); + @dots{} + set_gdbarch_data (gdbarch, nozel_handle, nozel); +@} +@end smallexample + +@smallexample +/* Default, called when nozel not set by set_gdbarch_nozel(). */ +static void * +nozel_init (struct gdbarch *gdbarch) +@{ + struct nozel *default_nozel = XMALLOC (struc nozel); + @dots{} + return default_nozel; +@} +@end smallexample + +@smallexample +void +_initialize_nozel (void) +@{ + nozel_handle = register_gdbarch_data (nozel_init, NULL); + @dots{} +@end smallexample + +@noindent +Note that an @code{init} function still needs to be registered. It is +used to initialize the data-pointer when the architecture creation phase +fail to set an initial value. + + +@section Wrapping Output Lines +@cindex line wrap in output + +@findex wrap_here +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 @value{GDBN} Coding Standards +@cindex coding standards + +@value{GDBN} follows the GNU coding standards, as described in +@file{etc/standards.texi}. This file is also available for anonymous +FTP from GNU archive sites. @value{GDBN} takes a strict interpretation +of the standard; in general, when the GNU standard recommends a practice +but does not require it, @value{GDBN} requires it. + +@value{GDBN} follows an additional set of coding standards specific to +@value{GDBN}, as described in the following sections. + + +@subsection ISO C + +@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant +compiler. + +@value{GDBN} does not assume an ISO C or POSIX compliant C library. + + +@subsection Memory Management + +@value{GDBN} does not use the functions @code{malloc}, @code{realloc}, +@code{calloc}, @code{free} and @code{asprintf}. + +@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and +@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@: +these functions do not return when the memory pool is empty. Instead, +they unwind the stack using cleanups. These functions return +@code{NULL} when requested to allocate a chunk of memory of size zero. + +@emph{Pragmatics: By using these functions, the need to check every +memory allocation is removed. These functions provide portable +behavior.} + +@value{GDBN} does not use the function @code{free}. + +@value{GDBN} uses the function @code{xfree} to return memory to the +memory pool. Consistent with ISO-C, this function ignores a request to +free a @code{NULL} pointer. + +@emph{Pragmatics: On some systems @code{free} fails when passed a +@code{NULL} pointer.} + +@value{GDBN} can use the non-portable function @code{alloca} for the +allocation of small temporary values (such as strings). + +@emph{Pragmatics: This function is very non-portable. Some systems +restrict the memory being allocated to no more than a few kilobytes.} + +@value{GDBN} uses the string function @code{xstrdup} and the print +function @code{xasprintf}. + +@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print +functions such as @code{sprintf} are very prone to buffer overflow +errors.} + + +@subsection Compiler Warnings +@cindex compiler warnings + +With few exceptions, developers should include the configuration option +@samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}. +The exceptions are listed in the file @file{gdb/MAINTAINERS}. + +This option causes @value{GDBN} (when built using GCC) to be compiled +with a carefully selected list of compiler warning flags. Any warnings +from those flags being treated as errors. + +The current list of warning flags includes: + +@table @samp +@item -Wimplicit +Since @value{GDBN} coding standard requires all functions to be declared +using a prototype, the flag has the side effect of ensuring that +prototyped functions are always visible with out resorting to +@samp{-Wstrict-prototypes}. + +@item -Wreturn-type +Such code often appears to work except on instruction set architectures +that use register windows. + +@item -Wcomment + +@item -Wtrigraphs + +@item -Wformat +Since @value{GDBN} uses the @code{format printf} attribute on all +@code{printf} like functions this checks not just @code{printf} calls +but also calls to functions such as @code{fprintf_unfiltered}. + +@item -Wparentheses +This warning includes uses of the assignment operator within an +@code{if} statement. + +@item -Wpointer-arith + +@item -Wuninitialized +@end table + +@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most +functions have unused parameters. Consequently the warning +@samp{-Wunused-parameter} is precluded from the list. The macro +@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives --- +it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that +is being used. The options @samp{-Wall} and @samp{-Wunused} are also +precluded because they both include @samp{-Wunused-parameter}.} + +@emph{Pragmatics: @value{GDBN} has not simply accepted the warnings +enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings +when and where their benefits can be demonstrated.} + +@subsection Formatting + +@cindex source code formatting +The standard GNU recommendations for formatting must be followed +strictly. + +A function declaration should not have its name in column zero. A +function definition should have its name in column zero. + +@smallexample +/* Declaration */ +static void foo (void); +/* Definition */ +void +foo (void) +@{ +@} +@end smallexample + +@emph{Pragmatics: This simplifies scripting. Function definitions can +be found using @samp{^function-name}.} + +There must be a space between a function or macro name and the opening +parenthesis of its argument list (except for macro definitions, as +required by C). There must not be a space after an open paren/bracket +or before a close paren/bracket. + +While additional whitespace is generally helpful for reading, do not use +more than one blank line to separate blocks, and avoid adding whitespace +after the end of a program line (as of 1/99, some 600 lines had +whitespace after the semicolon). Excess whitespace causes difficulties +for @code{diff} and @code{patch} utilities. + +Pointers are declared using the traditional K&R C style: + +@smallexample +void *foo; +@end smallexample + +@noindent +and not: + +@smallexample +void * foo; +void* foo; +@end smallexample + +@subsection Comments + +@cindex comment formatting +The standard GNU requirements on comments must be followed strictly. + +Block comments must appear in the following form, with no @code{/*}- or +@code{*/}-only lines, and no leading @code{*}: + +@smallexample +/* Wait for control to return from inferior to debugger. If inferior + gets a signal, we may decide to start it up again instead of + returning. That is why there is a loop in this function. When + this function actually returns it means the inferior should be left + stopped and @value{GDBN} should read more commands. */ +@end smallexample + +(Note that this format is encouraged by Emacs; tabbing for a multi-line +comment works correctly, and @kbd{M-q} fills the block consistently.) + +Put a blank line between the block comments preceding function or +variable definitions, and the definition itself. + +In general, put function-body comments on lines by themselves, rather +than trying to fit them into the 20 characters left at the end of a +line, since either the comment or the code will inevitably get longer +than will fit, and then somebody will have to move it anyhow. + +@subsection C Usage + +@cindex C data types +Code must not 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. + +@cindex function usage +Use functions freely. There are only a handful of compute-bound areas +in @value{GDBN} that might be affected by the overhead of a function +call, mainly in symbol reading. Most of @value{GDBN}'s performance is +limited by the target interface (whether serial line or system call). + +However, use functions with moderation. A thousand one-line functions +are just as hard to understand as a single thousand-line function. + +@emph{Macros are bad, M'kay.} +(But if you have to use a macro, make sure that the macro arguments are +protected with parentheses.) + +@cindex types + +Declarations like @samp{struct foo *} should be used in preference to +declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}. + + +@subsection Function Prototypes +@cindex function prototypes + +Prototypes must be used when both @emph{declaring} and @emph{defining} +a function. Prototypes for @value{GDBN} functions must include both the +argument type and name, with the name matching that used in the actual +function definition. + +All external functions should have a declaration in a header file that +callers include, except for @code{_initialize_*} functions, which must +be external so that @file{init.c} construction works, but shouldn't be +visible to random source files. + +Where a source file needs a forward declaration of a static function, +that declaration must appear in a block near the top of the source file. + + +@subsection Internal Error Recovery + +During its execution, @value{GDBN} can encounter two types of errors. +User errors and internal errors. User errors include not only a user +entering an incorrect command but also problems arising from corrupt +object files and system errors when interacting with the target. +Internal errors include situations where @value{GDBN} has detected, at +run time, a corrupt or erroneous situation. + +When reporting an internal error, @value{GDBN} uses +@code{internal_error} and @code{gdb_assert}. + +@value{GDBN} must not call @code{abort} or @code{assert}. + +@emph{Pragmatics: There is no @code{internal_warning} function. Either +the code detected a user error, recovered from it and issued a +@code{warning} or the code failed to correctly recover from the user +error and issued an @code{internal_error}.} + +@subsection File Names + +Any file used when building the core of @value{GDBN} must be in lower +case. Any file used when building the core of @value{GDBN} must be 8.3 +unique. These requirements apply to both source and generated files. + +@emph{Pragmatics: The core of @value{GDBN} must be buildable on many +platforms including DJGPP and MacOS/HFS. Every time an unfriendly file +is introduced to the build process both @file{Makefile.in} and +@file{configure.in} need to be modified accordingly. Compare the +convoluted conversion process needed to transform @file{COPYING} into +@file{copying.c} with the conversion needed to transform +@file{version.in} into @file{version.c}.} + +Any file non 8.3 compliant file (that is not used when building the core +of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}. + +@emph{Pragmatics: This is clearly a compromise.} + +When @value{GDBN} has a local version of a system header file (ex +@file{string.h}) the file name based on the POSIX header prefixed with +@file{gdb_} (@file{gdb_string.h}). + +For other files @samp{-} is used as the separator. + + +@subsection Include Files + +A @file{.c} file should include @file{defs.h} first. + +A @file{.c} file should directly include the @code{.h} file of every +declaration and/or definition it directly refers to. It cannot rely on +indirect inclusion. + +A @file{.h} file should directly include the @code{.h} file of every +declaration and/or definition it directly refers to. It cannot rely on +indirect inclusion. Exception: The file @file{defs.h} does not need to +be directly included. + +An external declaration should only appear in one include file. + +An external declaration should never appear in a @code{.c} file. +Exception: a declaration for the @code{_initialize} function that +pacifies @option{-Wmissing-declaration}. + +A @code{typedef} definition should only appear in one include file. + +An opaque @code{struct} declaration can appear in multiple @file{.h} +files. Where possible, a @file{.h} file should use an opaque +@code{struct} declaration instead of an include. + +All @file{.h} files should be wrapped in: + +@smallexample +#ifndef INCLUDE_FILE_NAME_H +#define INCLUDE_FILE_NAME_H +header body +#endif +@end smallexample + + +@subsection Clean Design and Portable Implementation + +@cindex design +In addition to getting the syntax right, there's the little question of +semantics. Some things are done in certain ways in @value{GDBN} because long +experience has shown that the more obvious ways caused various kinds of +trouble. + +@cindex assumptions about targets +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 +@value{GDBN}, or one of the swap routines defined in @file{bfd.h}, +such as @code{bfd_get_32}. + +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. + +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. + +@cindex portability +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. +@cindex system dependencies +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. + +Adding code that handles specific architectures, operating systems, +target interfaces, or hosts, is not acceptable in generic code. + +@cindex portable file name handling +@cindex file names, portability +One particularly notorious area where system dependencies tend to +creep in is handling of file names. The mainline @value{GDBN} code +assumes Posix semantics of file names: absolute file names begin with +a forward slash @file{/}, slashes are used to separate leading +directories, case-sensitive file names. These assumptions are not +necessarily true on non-Posix systems such as MS-Windows. To avoid +system-dependent code where you need to take apart or construct a file +name, use the following portable macros: + +@table @code +@findex HAVE_DOS_BASED_FILE_SYSTEM +@item HAVE_DOS_BASED_FILE_SYSTEM +This preprocessing symbol is defined to a non-zero value on hosts +whose filesystems belong to the MS-DOS/MS-Windows family. Use this +symbol to write conditional code which should only be compiled for +such hosts. + +@findex IS_DIR_SEPARATOR +@item IS_DIR_SEPARATOR (@var{c}) +Evaluates to a non-zero value if @var{c} is a directory separator +character. On Unix and GNU/Linux systems, only a slash @file{/} is +such a character, but on Windows, both @file{/} and @file{\} will +pass. + +@findex IS_ABSOLUTE_PATH +@item IS_ABSOLUTE_PATH (@var{file}) +Evaluates to a non-zero value if @var{file} is an absolute file name. +For Unix and GNU/Linux hosts, a name which begins with a slash +@file{/} is absolute. On DOS and Windows, @file{d:/foo} and +@file{x:\bar} are also absolute file names. + +@findex FILENAME_CMP +@item FILENAME_CMP (@var{f1}, @var{f2}) +Calls a function which compares file names @var{f1} and @var{f2} as +appropriate for the underlying host filesystem. For Posix systems, +this simply calls @code{strcmp}; on case-insensitive filesystems it +will call @code{strcasecmp} instead. + +@findex DIRNAME_SEPARATOR +@item DIRNAME_SEPARATOR +Evaluates to a character which separates directories in +@code{PATH}-style lists, typically held in environment variables. +This character is @samp{:} on Unix, @samp{;} on DOS and Windows. + +@findex SLASH_STRING +@item SLASH_STRING +This evaluates to a constant string you should use to produce an +absolute filename from leading directories and the file's basename. +@code{SLASH_STRING} is @code{"/"} on most systems, but might be +@code{"\\"} for some Windows-based ports. +@end table + +In addition to using these macros, be sure to use portable library +functions whenever possible. For example, to extract a directory or a +basename part from a file name, use the @code{dirname} and +@code{basename} library functions (available in @code{libiberty} for +platforms which don't provide them), instead of searching for a slash +with @code{strrchr}. + +Another way to generalize @value{GDBN} along a particular interface is with an +attribute struct. For example, @value{GDBN} has been generalized to handle +multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but +by defining the @code{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., +@code{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 @value{GDBN}'s access to multiple source languages. + +Please avoid duplicating code. For example, in @value{GDBN} 3.x all +the code interfacing between @code{ptrace} and the rest of +@value{GDBN} was duplicated in @file{*-dep.c}, and so changing +something was very painful. In @value{GDBN} 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, @code{#if defined}, etc.), and machines which are +radically different don't need to use @file{infptrace.c} at all. + +All debugging code must be controllable using the @samp{set debug +@var{module}} command. Do not use @code{printf} to print trace +messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use +@code{#ifdef DEBUG}. + + +@node Porting GDB + +@chapter Porting @value{GDBN} +@cindex porting to new machines + +Most of the work in making @value{GDBN} 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: + +@itemize @bullet +@item +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 + +@smallexample +./config.sub @var{xyz} +@end smallexample + +@noindent +and + +@smallexample +./config.sub @code{@var{arch}-@var{xvend}-@var{xos}} +@end smallexample + +@noindent +which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}} +and no error messages. + +@noindent +You need to port BFD, if that hasn't been done already. Porting BFD is +beyond the scope of this manual. + +@item +To configure @value{GDBN} 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}). + +@emph{Maintainer's note: Work in progress. The file +@file{gdb/configure.host} originally needed to be modified when either a +new native target or a new host machine was being added to @value{GDBN}. +Recent changes have removed this requirement. The file now only needs +to be modified when adding a new native configuration. This will likely +changed again in the future.} + +@item +Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and +target-dependent @file{.h} and @file{.c} files used for your +configuration. +@end itemize + +@section Configuring @value{GDBN} for Release + +@cindex preparing a release +@cindex making a distribution tarball +From the top level directory (containing @file{gdb}, @file{bfd}, +@file{libiberty}, and so on): + +@smallexample +make -f Makefile.in gdb.tar.gz +@end smallexample + +@noindent +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 Releasing GDB + +@chapter Releasing @value{GDBN} +@cindex making a new release of gdb + +@section Versions and Branches + +@subsection Version Identifiers + +@value{GDBN}'s version is determined by the file @file{gdb/version.in}. + +@value{GDBN}'s mainline uses ISO dates to differentiate between +versions. The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs +while the corresponding snapshot uses @var{YYYYMMDD}. + +@value{GDBN}'s release branch uses a slightly more complicated scheme. +When the branch is first cut, the mainline version identifier is +prefixed with the @var{major}.@var{minor} from of the previous release +series but with .90 appended. As draft releases are drawn from the +branch, the minor minor number (.90) is incremented. Once the first +release (@var{M}.@var{N}) has been made, the version prefix is updated +to @var{M}.@var{N}.0.90 (dot zero, dot ninety). Follow on releases have +an incremented minor minor version number (.0). + +Using 5.1 (previous) and 5.2 (current), the example below illustrates a +typical sequence of version identifiers: + +@table @asis +@item 5.1.1 +final release from previous branch +@item 2002-03-03-cvs +main-line the day the branch is cut +@item 5.1.90-2002-03-03-cvs +corresponding branch version +@item 5.1.91 +first draft release candidate +@item 5.1.91-2002-03-17-cvs +updated branch version +@item 5.1.92 +second draft release candidate +@item 5.1.92-2002-03-31-cvs +updated branch version +@item 5.1.93 +final release candidate (see below) +@item 5.2 +official release +@item 5.2.0.90-2002-04-07-cvs +updated CVS branch version +@item 5.2.1 +second official release +@end table + +Notes: + +@itemize @bullet +@item +Minor minor minor draft release candidates such as 5.2.0.91 have been +omitted from the example. Such release candidates are, typically, never +made. +@item +For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the +official @file{gdb-5.2.tar} renamed and compressed. +@end itemize + +To avoid version conflicts, vendors are expected to modify the file +@file{gdb/version.in} to include a vendor unique alphabetic identifier +(an official @value{GDBN} release never uses alphabetic characters in +its version identifer). + +Since @value{GDBN} does not make minor minor minor releases (e.g., +5.1.0.1) the conflict between that and a minor minor draft release +identifier (e.g., 5.1.0.90) is avoided. + + +@subsection Branches + +@value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) from a single +release branch (gdb_5_2-branch). Since minor minor minor releases +(5.1.0.1) are not made, the need to branch the release branch is avoided +(it also turns out that the effort required for such a a branch and +release is significantly greater than the effort needed to create a new +release from the head of the release branch). + +Releases 5.0 and 5.1 used branch and release tags of the form: + +@smallexample +gdb_N_M-YYYY-MM-DD-branchpoint +gdb_N_M-YYYY-MM-DD-branch +gdb_M_N-YYYY-MM-DD-release +@end smallexample + +Release 5.2 is trialing the branch and release tags: + +@smallexample +gdb_N_M-YYYY-MM-DD-branchpoint +gdb_N_M-branch +gdb_M_N-YYYY-MM-DD-release +@end smallexample + +@emph{Pragmatics: The branchpoint and release tags need to identify when +a branch and release are made. The branch tag, denoting the head of the +branch, does not have this criteria.} + + +@section Branch Commit Policy + +The branch commit policy is pretty slack. @value{GDBN} releases 5.0, +5.1 and 5.2 all used the below: + +@itemize @bullet +@item +The @file{gdb/MAINTAINERS} file still holds. +@item +Don't fix something on the branch unless/until it is also fixed in the +trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS} +file is better than committing a hack. +@item +When considering a patch for the branch, suggested criteria include: +Does it fix a build? Does it fix the sequence @kbd{break main; run} +when debugging a static binary? +@item +The further a change is from the core of @value{GDBN}, the less likely +the change will worry anyone (e.g., target specific code). +@item +Only post a proposal to change the core of @value{GDBN} after you've +sent individual bribes to all the people listed in the +@file{MAINTAINERS} file @t{;-)} +@end itemize + +@emph{Pragmatics: Provided updates are restricted to non-core +functionality there is little chance that a broken change will be fatal. +This means that changes such as adding a new architectures or (within +reason) support for a new host are considered acceptable.} + + +@section Obsoleting code + +Before anything else, poke the other developers (and around the source +code) to see if there is anything that can be removed from @value{GDBN} +(an old target, an unused file). + +Obsolete code is identified by adding an @code{OBSOLETE} prefix to every +line. Doing this means that it is easy to identify something that has +been obsoleted when greping through the sources. + +The process is done in stages --- this is mainly to ensure that the +wider @value{GDBN} community has a reasonable opportunity to respond. +Remember, everything on the Internet takes a week. + +@enumerate +@item +Post the proposal on @email{gdb@@sources.redhat.com, the GDB mailing +list} Creating a bug report to track the task's state, is also highly +recommended. +@item +Wait a week or so. +@item +Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB +Announcement mailing list}. +@item +Wait a week or so. +@item +Go through and edit all relevant files and lines so that they are +prefixed with the word @code{OBSOLETE}. +@item +Wait until the next GDB version, containing this obsolete code, has been +released. +@item +Remove the obsolete code. +@end enumerate + +@noindent +@emph{Maintainer note: While removing old code is regrettable it is +hopefully better for @value{GDBN}'s long term development. Firstly it +helps the developers by removing code that is either no longer relevant +or simply wrong. Secondly since it removes any history associated with +the file (effectively clearing the slate) the developer has a much freer +hand when it comes to fixing broken files.} + + + +@section Before the Branch + +The most important objective at this stage is to find and fix simple +changes that become a pain to track once the branch is created. For +instance, configuration problems that stop @value{GDBN} from even +building. If you can't get the problem fixed, document it in the +@file{gdb/PROBLEMS} file. + +@subheading Prompt for @file{gdb/NEWS} + +People always forget. Send a post reminding them but also if you know +something interesting happened add it yourself. The @code{schedule} +script will mention this in its e-mail. + +@subheading Review @file{gdb/README} + +Grab one of the nightly snapshots and then walk through the +@file{gdb/README} looking for anything that can be improved. The +@code{schedule} script will mention this in its e-mail. + +@subheading Refresh any imported files. + +A number of files are taken from external repositories. They include: + +@itemize @bullet +@item +@file{texinfo/texinfo.tex} +@item +@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS} +file) +@item +@file{etc/standards.texi}, @file{etc/make-stds.texi} +@end itemize + +@subheading Check the ARI + +@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script +(Awk Regression Index ;-) that checks for a number of errors and coding +conventions. The checks include things like using @code{malloc} instead +of @code{xmalloc} and file naming problems. There shouldn't be any +regressions. + +@subsection Review the bug data base + +Close anything obviously fixed. + +@subsection Check all cross targets build + +The targets are listed in @file{gdb/MAINTAINERS}. + + +@section Cut the Branch + +@subheading Create the branch + +@smallexample +$ u=5.1 +$ v=5.2 +$ V=`echo $v | sed 's/\./_/g'` +$ D=`date -u +%Y-%m-%d` +$ echo $u $V $D +5.1 5_2 2002-03-03 +$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ +-D $D-gmt gdb_$V-$D-branchpoint insight+dejagnu +cvs -f -d :ext:sources.redhat.com:/cvs/src rtag +-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight+dejagnu +$ ^echo ^^ +... +$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ +-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight+dejagnu +cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ +-b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight+dejagnu +$ ^echo ^^ +... +$ +@end smallexample + +@itemize @bullet +@item +by using @kbd{-D YYYY-MM-DD-gmt} the branch is forced to an exact +date/time. +@item +the trunk is first taged so that the branch point can easily be found +@item +Insight (which includes GDB) and dejagnu are all tagged at the same time +@item +@file{version.in} gets bumped to avoid version number conflicts +@item +the reading of @file{.cvsrc} is disabled using @file{-f} +@end itemize + +@subheading Update @file{version.in} + +@smallexample +$ u=5.1 +$ v=5.2 +$ V=`echo $v | sed 's/\./_/g'` +$ echo $u $v$V +5.1 5_2 +$ cd /tmp +$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \ +-r gdb_$V-branch src/gdb/version.in +cvs -f -d :ext:sources.redhat.com:/cvs/src co + -r gdb_5_2-branch src/gdb/version.in +$ ^echo ^^ +U src/gdb/version.in +$ cd src/gdb +$ echo $u.90-0000-00-00-cvs > version.in +$ cat version.in +5.1.90-0000-00-00-cvs +$ cvs -f commit version.in +@end smallexample + +@itemize @bullet +@item +@file{0000-00-00} is used as a date to pump prime the version.in update +mechanism +@item +@file{.90} and the previous branch version are used as fairly arbitrary +initial branch version number +@end itemize + + +@subheading Update the web and news pages + +Something? + +@subheading Tweak cron to track the new branch + +The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table. +This file needs to be updated so that: + +@itemize @bullet +@item +a daily timestamp is added to the file @file{version.in} +@item +the new branch is included in the snapshot process +@end itemize + +@noindent +See the file @file{gdbadmin/cron/README} for how to install the updated +cron table. + +The file @file{gdbadmin/ss/README} should also be reviewed to reflect +any changes. That file is copied to both the branch/ and current/ +snapshot directories. + + +@subheading Update the NEWS and README files + +The @file{NEWS} file needs to be updated so that on the branch it refers +to @emph{changes in the current release} while on the trunk it also +refers to @emph{changes since the current release}. + +The @file{README} file needs to be updated so that it refers to the +current release. + +@subheading Post the branch info + +Send an announcement to the mailing lists: + +@itemize @bullet +@item +@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list} +@item +@email{gdb@@sources.redhat.com, GDB Discsussion mailing list} and +@email{gdb-testers@@sources.redhat.com, GDB Discsussion mailing list} +@end itemize + +@emph{Pragmatics: The branch creation is sent to the announce list to +ensure that people people not subscribed to the higher volume discussion +list are alerted.} + +The announcement should include: + +@itemize @bullet +@item +the branch tag +@item +how to check out the branch using CVS +@item +the date/number of weeks until the release +@item +the branch commit policy +still holds. +@end itemize + +@section Stabilize the branch + +Something goes here. + +@section Create a Release + +The process of creating and then making available a release is broken +down into a number of stages. The first part addresses the technical +process of creating a releasable tar ball. The later stages address the +process of releasing that tar ball. + +When making a release candidate just the first section is needed. + +@subsection Create a release candidate + +The objective at this stage is to create a set of tar balls that can be +made available as a formal release (or as a less formal release +candidate). + +@subsubheading Freeze the branch + +Send out an e-mail notifying everyone that the branch is frozen to +@email{gdb-patches@@sources.redhat.com}. + +@subsubheading Establish a few defaults. + +@smallexample +$ b=gdb_5_2-branch +$ v=5.2 +$ t=/sourceware/snapshot-tmp/gdbadmin-tmp +$ echo $t/$b/$v +/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 +$ mkdir -p $t/$b/$v +$ cd $t/$b/$v +$ pwd +/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 +$ which autoconf +/home/gdbadmin/bin/autoconf +$ +@end smallexample + +@noindent +Notes: + +@itemize @bullet +@item +Check the @code{autoconf} version carefully. You want to be using the +version taken from the @file{binutils} snapshot directory, which can be +found at @uref{ftp://sources.redhat.com/pub/binutils/}. It is very +unlikely that a system installed version of @code{autoconf} (e.g., +@file{/usr/bin/autoconf}) is correct. +@end itemize + +@subsubheading Check out the relevant modules: + +@smallexample +$ for m in gdb insight dejagnu +do +( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m ) +done +$ +@end smallexample + +@noindent +Note: + +@itemize @bullet +@item +The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't +any confusion between what is written here and what your local +@code{cvs} really does. +@end itemize + +@subsubheading Update relevant files. + +@table @file + +@item gdb/NEWS + +Major releases get their comments added as part of the mainline. Minor +releases should probably mention any significant bugs that were fixed. + +Don't forget to include the @file{ChangeLog} entry. + +@smallexample +$ emacs gdb/src/gdb/NEWS +... +c-x 4 a +... +c-x c-s c-x c-c +$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS +$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog +@end smallexample + +@item gdb/README + +You'll need to update: + +@itemize @bullet +@item +the version +@item +the update date +@item +who did it +@end itemize + +@smallexample +$ emacs gdb/src/gdb/README +... +c-x 4 a +... +c-x c-s c-x c-c +$ cp gdb/src/gdb/README insight/src/gdb/README +$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog +@end smallexample + +@emph{Maintainer note: Hopefully the @file{README} file was reviewed +before the initial branch was cut so just a simple substitute is needed +to get it updated.} + +@emph{Maintainer note: Other projects generate @file{README} and +@file{INSTALL} from the core documentation. This might be worth +pursuing.} + +@item gdb/version.in + +@smallexample +$ echo $v > gdb/src/gdb/version.in +$ cat gdb/src/gdb/version.in +5.2 +$ emacs gdb/src/gdb/version.in +... +c-x 4 a +... Bump to version ... +c-x c-s c-x c-c +$ cp gdb/src/gdb/version.in insight/src/gdb/version.in +$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog +@end smallexample + +@item dejagnu/src/dejagnu/configure.in + +Dejagnu is more complicated. The version number is a parameter to +@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91. + +Don't forget to re-generate @file{configure}. + +Don't forget to include a @file{ChangeLog} entry. + +@smallexample +$ emacs dejagnu/src/dejagnu/configure.in +... +c-x 4 a +... +c-x c-s c-x c-c +$ ( cd dejagnu/src/dejagnu && autoconf ) +@end smallexample + +@end table + +@subsubheading Do the dirty work + +This is identical to the process used to create the daily snapshot. + +@smallexample +$ for m in gdb insight +do +( cd $m/src && gmake -f Makefile.in $m.tar ) +done +$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 ) +@end smallexample + +@subsubheading Check the source files + +You're looking for files that have mysteriously disappeared. +@kbd{distclean} has the habit of deleting files it shouldn't. Watch out +for the @file{version.in} update @kbd{cronjob}. + +@smallexample +$ ( cd gdb/src && cvs -f -q -n update ) +M djunpack.bat +? gdb-5.1.91.tar +? proto-toplev +@dots{} lots of generated files @dots{} +M gdb/ChangeLog +M gdb/NEWS +M gdb/README +M gdb/version.in +@dots{} lots of generated files @dots{} +$ +@end smallexample + +@noindent +@emph{Don't worry about the @file{gdb.info-??} or +@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1} +was also generated only something strange with CVS means that they +didn't get supressed). Fixing it would be nice though.} + +@subsubheading Create compressed versions of the release + +@smallexample +$ cp */src/*.tar . +$ cp */src/*.bz2 . +$ ls -F +dejagnu/ dejagnu-gdb-5.2.tar.bz2 gdb/ gdb-5.2.tar insight/ insight-5.2.tar +$ for m in gdb insight +do +bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2 +gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz +done +$ +@end smallexample + +@noindent +Note: + +@itemize @bullet +@item +A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since, +in that mode, @code{gzip} does not know the name of the file and, hence, +can not include it in the compressed file. This is also why the release +process runs @code{tar} and @code{bzip2} as separate passes. +@end itemize + +@subsection Sanity check the tar ball + +Pick a popular machine (Solaris/PPC?) and try the build on that. + +@smallexample +$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf - +$ cd gdb-5.2 +$ ./configure +$ make +@dots{} +$ ./gdb/gdb ./gdb/gdb +GNU gdb 5.2 +@dots{} +(gdb) b main +Breakpoint 1 at 0x80732bc: file main.c, line 734. +(gdb) run +Starting program: /tmp/gdb-5.2/gdb/gdb + +Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734 +734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL); +(gdb) print args +$1 = @{argc = 136426532, argv = 0x821b7f0@} +(gdb) +@end smallexample + +@subsection Make a release candidate available + +If this is a release candidate then the only remaining steps are: + +@enumerate +@item +Commit @file{version.in} and @file{ChangeLog} +@item +Tweak @file{version.in} (and @file{ChangeLog} to read +@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update +process can restart. +@item +Make the release candidate available in +@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch} +@item +Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and +@email{gdb-testers@@sources.redhat.com} that the candidate is available. +@end enumerate + +@subsection Make a formal release available + +(And you thought all that was required was to post an e-mail.) + +@subsubheading Install on sware + +Copy the new files to both the release and the old release directory: + +@smallexample +$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/ +$ cp *.bz2 *.gz ~ftp/pub/gdb/releases +@end smallexample + +@noindent +Clean up the releases directory so that only the most recent releases +are available (e.g. keep 5.2 and 5.2.1 but remove 5.1): + +@smallexample +$ cd ~ftp/pub/gdb/releases +$ rm @dots{} +@end smallexample + +@noindent +Update the file @file{README} and @file{.message} in the releases +directory: + +@smallexample +$ vi README +@dots{} +$ rm -f .message +$ ln README .message +@end smallexample + +@subsubheading Update the web pages. + +@table @file + +@item htdocs/download/ANNOUNCEMENT +This file, which is posted as the official announcement, includes: +@itemize @bullet +@item +General announcement +@item +News. If making an @var{M}.@var{N}.1 release, retain the news from +earlier @var{M}.@var{N} release. +@item +Errata +@end itemize + +@item htdocs/index.html +@itemx htdocs/news/index.html +@itemx htdocs/download/index.html +These files include: +@itemize @bullet +@item +announcement of the most recent release +@item +news entry (remember to update both the top level and the news directory). +@end itemize +These pages also need to be regenerate using @code{index.sh}. + +@item download/onlinedocs/ +You need to find the magic command that is used to generate the online +docs from the @file{.tar.bz2}. The best way is to look in the output +from one of the nightly @code{cron} jobs and then just edit accordingly. +Something like: + +@smallexample +$ ~/ss/update-web-docs \ + ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ + $PWD/www \ + /www/sourceware/htdocs/gdb/download/onlinedocs \ + gdb +@end smallexample + +@item download/ari/ +Just like the online documentation. Something like: + +@smallexample +$ /bin/sh ~/ss/update-web-ari \ + ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ + $PWD/www \ + /www/sourceware/htdocs/gdb/download/ari \ + gdb +@end smallexample + +@end table + +@subsubheading Shadow the pages onto gnu + +Something goes here. + + +@subsubheading Install the @value{GDBN} tar ball on GNU + +At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in +@file{~ftp/gnu/gdb}. + +@subsubheading Make the @file{ANNOUNCEMENT} + +Post the @file{ANNOUNCEMENT} file you created above to: + +@itemize @bullet +@item +@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list} +@item +@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a +day or so to let things get out) +@item +@email{bug-gdb@@gnu.org, GDB Bug Report mailing list} +@end itemize + +@subsection Cleanup + +The release is out but you're still not finished. + +@subsubheading Commit outstanding changes + +In particular you'll need to commit any changes to: + +@itemize @bullet +@item +@file{gdb/ChangeLog} +@item +@file{gdb/version.in} +@item +@file{gdb/NEWS} +@item +@file{gdb/README} +@end itemize + +@subsubheading Tag the release + +Something like: + +@smallexample +$ d=`date -u +%Y-%m-%d` +$ echo $d +2002-01-24 +$ ( cd insight/src/gdb && cvs -f -q update ) +$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release ) +@end smallexample + +Insight is used since that contains more of the release than +@value{GDBN} (@code{dejagnu} doesn't get tagged but I think we can live +with that). + +@subsubheading Mention the release on the trunk + +Just put something in the @file{ChangeLog} so that the trunk also +indicates when the release was made. + +@subsubheading Restart @file{gdb/version.in} + +If @file{gdb/version.in} does not contain an ISO date such as +@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having +committed all the release changes it can be set to +@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_} +is important - it affects the snapshot process). + +Don't forget the @file{ChangeLog}. + +@subsubheading Merge into trunk + +The files committed to the branch may also need changes merged into the +trunk. + +@subsubheading Revise the release schedule + +Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB +Discussion List} with an updated announcement. The schedule can be +generated by running: + +@smallexample +$ ~/ss/schedule `date +%s` schedule +@end smallexample + +@noindent +The first parameter is approximate date/time in seconds (from the epoch) +of the most recent release. + +Also update the schedule @code{cronjob}. + +@section Post release + +Remove any @code{OBSOLETE} code. + +@node Testsuite + +@chapter Testsuite +@cindex test suite + +The testsuite is an important component of the @value{GDBN} package. +While it is always worthwhile to encourage user testing, in practice +this is rarely sufficient; users typically use only a small subset of +the available commands, and it has proven all too common for a change +to cause a significant regression that went unnoticed for some time. + +The @value{GDBN} testsuite uses the DejaGNU testing framework. +DejaGNU is built using @code{Tcl} and @code{expect}. The tests +themselves are calls to various @code{Tcl} procs; the framework runs all the +procs and summarizes the passes and fails. + +@section Using the Testsuite + +@cindex running the test suite +To run the testsuite, simply go to the @value{GDBN} object directory (or to the +testsuite's objdir) and type @code{make check}. This just sets up some +environment variables and invokes DejaGNU's @code{runtest} script. While +the testsuite is running, you'll get mentions of which test file is in use, +and a mention of any unexpected passes or fails. When the testsuite is +finished, you'll get a summary that looks like this: + +@smallexample + === gdb Summary === + +# of expected passes 6016 +# of unexpected failures 58 +# of unexpected successes 5 +# of expected failures 183 +# of unresolved testcases 3 +# of untested testcases 5 +@end smallexample + +The ideal test run consists of expected passes only; however, reality +conspires to keep us from this ideal. Unexpected failures indicate +real problems, whether in @value{GDBN} or in the testsuite. Expected +failures are still failures, but ones which have been decided are too +hard to deal with at the time; for instance, a test case might work +everywhere except on AIX, and there is no prospect of the AIX case +being fixed in the near future. Expected failures should not be added +lightly, since you may be masking serious bugs in @value{GDBN}. +Unexpected successes are expected fails that are passing for some +reason, while unresolved and untested cases often indicate some minor +catastrophe, such as the compiler being unable to deal with a test +program. + +When making any significant change to @value{GDBN}, you should run the +testsuite before and after the change, to confirm that there are no +regressions. Note that truly complete testing would require that you +run the testsuite with all supported configurations and a variety of +compilers; however this is more than really necessary. In many cases +testing with a single configuration is sufficient. Other useful +options are to test one big-endian (Sparc) and one little-endian (x86) +host, a cross config with a builtin simulator (powerpc-eabi, +mips-elf), or a 64-bit host (Alpha). + +If you add new functionality to @value{GDBN}, please consider adding +tests for it as well; this way future @value{GDBN} hackers can detect +and fix their changes that break the functionality you added. +Similarly, if you fix a bug that was not previously reported as a test +failure, please add a test case for it. Some cases are extremely +difficult to test, such as code that handles host OS failures or bugs +in particular versions of compilers, and it's OK not to try to write +tests for all of those. + +@section Testsuite Organization + +@cindex test suite organization +The testsuite is entirely contained in @file{gdb/testsuite}. While the +testsuite includes some makefiles and configury, these are very minimal, +and used for little besides cleaning up, since the tests themselves +handle the compilation of the programs that @value{GDBN} will run. The file +@file{testsuite/lib/gdb.exp} contains common utility procs useful for +all @value{GDBN} tests, while the directory @file{testsuite/config} contains +configuration-specific files, typically used for special-purpose +definitions of procs like @code{gdb_load} and @code{gdb_start}. + +The tests themselves are to be found in @file{testsuite/gdb.*} and +subdirectories of those. The names of the test files must always end +with @file{.exp}. DejaGNU collects the test files by wildcarding +in the test directories, so both subdirectories and individual files +get chosen and run in alphabetical order. + +The following table lists the main types of subdirectories and what they +are for. Since DejaGNU finds test files no matter where they are +located, and since each test file sets up its own compilation and +execution environment, this organization is simply for convenience and +intelligibility. + +@table @file +@item gdb.base +This is the base testsuite. The tests in it should apply to all +configurations of @value{GDBN} (but generic native-only tests may live here). +The test programs should be in the subset of C that is valid K&R, +ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance +for prototypes). + +@item gdb.@var{lang} +Language-specific tests for any language @var{lang} besides C. Examples are +@file{gdb.c++} and @file{gdb.java}. + +@item gdb.@var{platform} +Non-portable tests. The tests are specific to a specific configuration +(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for +HP-UX. + +@item gdb.@var{compiler} +Tests specific to a particular compiler. As of this writing (June +1999), there aren't currently any groups of tests in this category that +couldn't just as sensibly be made platform-specific, but one could +imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC +extensions. + +@item gdb.@var{subsystem} +Tests that exercise a specific @value{GDBN} subsystem in more depth. For +instance, @file{gdb.disasm} exercises various disassemblers, while +@file{gdb.stabs} tests pathways through the stabs symbol reader. +@end table + +@section Writing Tests +@cindex writing tests + +In many areas, the @value{GDBN} tests are already quite comprehensive; you +should be able to copy existing tests to handle new cases. + +You should try to use @code{gdb_test} whenever possible, since it +includes cases to handle all the unexpected errors that might happen. +However, it doesn't cost anything to add new test procedures; for +instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that +calls @code{gdb_test} multiple times. + +Only use @code{send_gdb} and @code{gdb_expect} when absolutely +necessary, such as when @value{GDBN} has several valid responses to a command. + +The source language programs do @emph{not} need to be in a consistent +style. Since @value{GDBN} is used to debug programs written in many different +styles, it's worth having a mix of styles in the testsuite; for +instance, some @value{GDBN} bugs involving the display of source lines would +never manifest themselves if the programs used GNU coding style +uniformly. + +@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 @value{GDBN} +* Debugging GDB:: Debugging @value{GDBN} with itself +@end menu + +@node Getting Started,,, Hints + +@section Getting Started + +@value{GDBN} 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 @value{GDBN} Internals manual, has information which applies +generally to many parts of @value{GDBN}. + +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 @value{GDBN}; 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 have some idea of how +@value{GDBN}'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 @value{GDBN}, 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 @value{GDBN} 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. + +@cindex command implementation +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 @value{GDBN} 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 @value{GDBN} on itself and set a +breakpoint in @code{execute_command}. + +@cindex @code{bug-gdb} mailing list +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 +@value{GDBN}''---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 @value{GDBN} with itself +@cindex debugging @value{GDBN} + +If @value{GDBN} 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 @kbd{@w{./gdb +./gdb}}, which works on Suns and such, you can copy @file{gdb} to +@file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}. + +When you run @value{GDBN} in the @value{GDBN} 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 @value{GDBN} 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 @value{GDBN} with your local cc, or +have run @code{fixincludes} if you are compiling with gcc. + +@section Submitting Patches + +@cindex submitting patches +Thanks for thinking of offering your changes back to the community of +@value{GDBN} 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 @value{GDBN} maintainers will only install ``cleanly designed'' patches. +This manual summarizes what we believe to be clean design for @value{GDBN}. + +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. + +@cindex legal papers for code contributions +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 documents for doing this by sending mail to @code{gnu@@gnu.org} +and asking for it. We 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 @value{GDBN}, but GAS, Emacs, GCC, +etc) can be +contributed with only one piece of legalese pushed through the +bureaucracy and filed with the FSF. We can't start merging changes until +this paperwork is received by the FSF (their rules, which we follow +since we 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 @code{patch}. +Each message sent to me should include the changes to C code and +header files for a single feature, plus @file{ChangeLog} entries for +each directory where files were modified, and diffs for any changes +needed to the manuals (@file{gdb/doc/gdb.texinfo} or +@file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a +single feature, they can be split down into multiple messages. + +In this way, if we read and like the feature, we can add it to the +sources with a single patch command, do some testing, and check it in. +If you leave out the @file{ChangeLog}, we have to write one. If you leave +out the doc, we have to puzzle out what needs documenting. Etc., etc. + +The reason to send each change in a separate message is that we will not +install some of the changes. They'll be returned to you with questions +or comments. If we're doing our job correctly, the 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 +the acceptable changes can be installed while one or more changes are +being reworked. If multiple features are sent in a single message, we +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 we get a lot +of bug reports and a lot of patches, and many of them don't get +installed because we 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 as time +permits, which, since the maintainers have many demands to meet, may not +be for quite some time. + +Please send patches directly to +@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}. + +@section Obsolete Conditionals +@cindex obsolete code + +Fragments of old code in @value{GDBN} 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. + +@table @code +@item STACK_END_ADDR +This macro used to define where the end of the stack appeared, for use +in interpreting core file formats that don't record this address in the +core file itself. This information is now configured in BFD, and @value{GDBN} +gets the info portably from there. The values in @value{GDBN}'s configuration +files should be moved into BFD configuration files (if needed there), +and deleted from all of @value{GDBN}'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 + +@include fdl.texi + +@node Index +@unnumbered Index + +@printindex cp + +@bye