diff options
| author | Stan Shebs <shebs@codesourcery.com> | 2013-09-16 18:00:34 +0000 |
|---|---|---|
| committer | Stan Shebs <shebs@codesourcery.com> | 2013-09-16 18:00:34 +0000 |
| commit | 0a7cfe2cf50b450d0cf9db16ee4bd027e08763e8 (patch) | |
| tree | f03cdc93796ed3410f5dfe1c9e41989cee434455 /gdb/doc | |
| parent | a280dbd16004e14560b76141a1aaf1e4659dd33f (diff) | |
| download | gdb-0a7cfe2cf50b450d0cf9db16ee4bd027e08763e8.zip gdb-0a7cfe2cf50b450d0cf9db16ee4bd027e08763e8.tar.gz gdb-0a7cfe2cf50b450d0cf9db16ee4bd027e08763e8.tar.bz2 | |
* README: Update references to writing code for GDB.
* configure.ac (build_warnings): Remove obsolete comment.
* configure: Regenerate.
* gdbarch.sh: Remove references to gdbint.texinfo.
* gdbarch.h: Regenerate.
* gdbtypes.c (objfile_type): Remove comments referencing internals
manual and D10V.
[gdb/doc]
Remove the internals manual gdbint.texinfo.
* Makefile.in (INFO_DEPS): Remove gdbint.info.
(PDFFILES): Remove gdbint.pdf.
(HTMLFILES): Remove gdbint/index.html.
(HTMLFILES_INSTALL): Remove gdbint.
(GDBINT_DOC_FILES): Remove.
(dvi): Remove gdbint.dvi.
(ps): Remove gdbint.ps.
* gdbint.texinfo: Remove file.
* gdb.texinfo (Maintenance Commands): Remove reference to gdbint.
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 13 | ||||
| -rw-r--r-- | gdb/doc/Makefile.in | 53 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 3 | ||||
| -rw-r--r-- | gdb/doc/gdbint.texinfo | 8282 |
4 files changed, 20 insertions, 8331 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index e183332..f5e4a04 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,16 @@ +2013-09-16 Stan Shebs <stan@codesourcery.com> + + Remove the internals manual gdbint.texinfo. + * Makefile.in (INFO_DEPS): Remove gdbint.info. + (PDFFILES): Remove gdbint.pdf. + (HTMLFILES): Remove gdbint/index.html. + (HTMLFILES_INSTALL): Remove gdbint. + (GDBINT_DOC_FILES): Remove. + (dvi): Remove gdbint.dvi. + (ps): Remove gdbint.ps. + * gdbint.texinfo: Remove file. + * gdb.texinfo (Maintenance Commands): Remove reference to gdbint. + 2013-09-16 Sergio Durigan Junior <sergiodj@redhat.com> * gdb.texinfo (Convenience Functions): Mention new convenience diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index ba8dd39..60feae3 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -79,13 +79,13 @@ SET_TEXINPUTS = \ TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$(GDBMI_DIR):$$TEXINPUTS # Files which should be generated via 'info' and installed by 'install-info' -INFO_DEPS = gdb.info gdbint.info stabs.info annotate.info +INFO_DEPS = gdb.info stabs.info annotate.info # Files which should be generated via 'pdf' and installed by 'install-pdf' -PDFFILES = gdb.pdf gdbint.pdf stabs.pdf refcard.pdf annotate.pdf +PDFFILES = gdb.pdf stabs.pdf refcard.pdf annotate.pdf # Files which should be generated via 'html' and installed by 'install-html' -HTMLFILES = gdb/index.html gdbint/index.html stabs/index.html annotate/index.html -HTMLFILES_INSTALL = gdb gdbint stabs annotate +HTMLFILES = gdb/index.html stabs/index.html annotate/index.html +HTMLFILES_INSTALL = gdb stabs annotate # There may be alternate predefined collections of switches to configure # the GDB manual. Normally this is not done in synch with the software @@ -133,18 +133,6 @@ GDB_DOC_FILES = \ $(GDB_DOC_SOURCE_INCLUDES) \ $(GDB_DOC_BUILD_INCLUDES) -# Internals Manual -GDBINT_DOC_SOURCE_INCLUDES = \ - $(srcdir)/fdl.texi \ - $(srcdir)/observer.texi -GDBINT_DOC_BUILD_INCLUDES = \ - gdb-cfg.texi \ - GDBvn.texi -GDBINT_DOC_FILES = \ - $(srcdir)/gdbint.texinfo \ - $(GDBINT_DOC_SOURCE_INCLUDES) \ - $(GDBINT_DOC_BUILD_INCLUDES) - # Stabs manual: All files STABS_DOC_SOURCE_INCLUDES = \ $(srcdir)/fdl.texi @@ -191,8 +179,8 @@ HAVE_NATIVE_GCORE_TARGET = @HAVE_NATIVE_GCORE_TARGET@ all: info: $(INFO_DEPS) -dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi annotate.dvi -ps: gdb.ps gdbint.ps stabs.ps refcard.ps annotate.ps +dvi: gdb.dvi stabs.dvi refcard.dvi annotate.dvi +ps: gdb.ps stabs.ps refcard.ps annotate.ps html: $(HTMLFILES) pdf: $(PDFFILES) man: $(MANS) @@ -530,34 +518,6 @@ gdb.mm: $(GDB_DOC_FILES) links2roff gdb/index.html: ${GDB_DOC_FILES} $(MAKEHTML) $(MAKEHTMLFLAGS) $(READLINE_TEXI_INCFLAG) -I ${GDBMI_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo -# Clean these up before each run. Avoids a catch 22 with not being -# able to re-generate these files (to fix a corruption) because these -# files contain a corruption. -GDBINT_TEX_TMPS = gdbint.aux gdbint.cp* gdbint.fn* gdbint.ky* \ - gdbint.log gdbint.pg* gdbint.toc gdbint.tp* gdbint.vr* - -# GDB INTERNALS MANUAL: TeX dvi file -gdbint.dvi: $(GDBINT_DOC_FILES) - rm -f $(GDBINT_TEX_TMPS) - $(TEXI2DVI) -I $(srcdir) $(srcdir)/gdbint.texinfo - -gdbint.ps : gdbint.dvi - $(DVIPS) -o $@ $? - -gdbint.pdf: $(GDBINT_DOC_FILES) - rm -f $(GDBINT_TEX_TMPS) - $(TEXI2DVI) --pdf -I $(srcdir) $(srcdir)/gdbint.texinfo - -# GDB INTERNALS MANUAL: info file - -gdbint.info: $(GDBINT_DOC_FILES) - $(MAKEINFO_CMD) -I $(srcdir) -o gdbint.info $(srcdir)/gdbint.texinfo - -# GDB INTERNALS MANUAL: HTML file - -gdbint/index.html: $(GDBINT_DOC_FILES) - $(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/gdbint.texinfo - stabs.info: $(STABS_DOC_FILES) $(MAKEINFO_CMD) -I $(srcdir) -o stabs.info $(srcdir)/stabs.texinfo @@ -649,7 +609,6 @@ Makefile: Makefile.in $(host_makefile_frag) ../config.status mostlyclean: rm -f gdb.mm gdb.ms gdb.me links2roff rm -f $(GDB_TEX_TMPS) - rm -f $(GDBINT_TEX_TMPS) rm -f $(STABS_TEX_TMPS) rm -f $(ANNOTATE_TEX_TMPS) rm -f sedref.dvi sedref.tex tmp.sed diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 65f63e4..60d2877 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -36870,8 +36870,7 @@ including registers which aren't available on the target nor visible to user; the command @code{maint print register-groups} includes the groups that each register is a member of; and the command @code{maint print remote-registers} includes the remote target's register numbers -and offsets in the `G' packets. @xref{Registers,, Registers, gdbint, -@value{GDBN} Internals}. +and offsets in the `G' packets. These commands take an optional parameter, a file name to which to write the information. diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo deleted file mode 100644 index b0f133f..0000000 --- a/gdb/doc/gdbint.texinfo +++ /dev/null @@ -1,8282 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@setfilename gdbint.info -@include gdb-cfg.texi -@settitle @value{GDBN} Internals -@setchapternewpage off -@dircategory Software development -@direntry -* Gdb-Internals: (gdbint). The GNU debugger's internals. -@end direntry - -@copying -Copyright @copyright{} 1990-2013 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.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end copying - -@ifnottex -This file documents the internals of the GNU debugger @value{GDBN}. - -@insertcopying -@end ifnottex - -@syncodeindex vr fn - -@titlepage -@title @value{GDBN} Internals -@subtitle A guide to the internals of the GNU debugger -@author John Gilmore -@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 Solutions\par -\hfill \manvers\par -\hfill \TeX{}info \texinfoversion\par -} -@end tex - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@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 - -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 -* Summary:: -* Overall Structure:: -* Algorithms:: -* User Interface:: -* libgdb:: -* Values:: -* Stack Frames:: -* Symbol Handling:: -* Language Support:: -* Host Definition:: -* Target Architecture Definition:: -* Target Descriptions:: -* Target Vector Definition:: -* Native Debugging:: -* Support Libraries:: -* Coding Standards:: -* Misc Guidelines:: -* Porting GDB:: -* Versions and Branches:: -* Start of New Year Procedure:: -* Releasing GDB:: -* Testsuite:: -* Hints:: - -* GDB Observers:: @value{GDBN} Currently available observers -* GNU Free Documentation License:: The license for this documentation -* Concept Index:: -* Function and Variable Index:: -@end menu - -@node Summary -@chapter Summary - -@menu -* Requirements:: -* Contributors:: -@end menu - -@node Requirements -@section 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. - -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. - -@value{GDBN} is an interactive tool. Although a batch mode is -available, @value{GDBN}'s primary role is to interact with a human -programmer. - -@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. - -@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. - -@node Contributors -@section Contributors - -The first edition of this document was written by John Gilmore of -Cygnus Solutions. The current second edition was written by Stan Shebs -of Cygnus Solutions, who continues to update the manual. - -Over the years, many others have made additions and changes to this -document. This section attempts to record the significant contributors -to that effort. One of the virtues of free software is that everyone -is free to contribute to it; with regret, we cannot actually -acknowledge everyone here. - -@quotation -@emph{Plea:} This section has only been added relatively recently (four -years after publication of the second edition). Additions to this -section are particularly welcome. If you or your friends (or enemies, -to be evenhanded) have been unfairly omitted from this list, we would -like to add your names! -@end quotation - -A document such as this relies on being kept up to date by numerous -small updates by contributing engineers as they make changes to the -code base. The file @file{ChangeLog} in the @value{GDBN} distribution -approximates a blow-by-blow account. The most prolific contributors to -this important, but low profile task are Andrew Cagney (responsible -for over half the entries), Daniel Jacobowitz, Mark Kettenis, Jim -Blandy and Eli Zaretskii. - -Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting -watchpoints. - -Jeremy Bennett updated the sections on initializing a new architecture -and register representation, and added the section on Frame Interpretation. - - -@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. These are all calculated by @code{autoconf} -when the debugger is built. - -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, calling @code{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 as the traditional native debugger -on a system, you will need to supply both target and native information. - -@section Source Tree Structure -@cindex @value{GDBN} source tree structure - -The @value{GDBN} source directory has a mostly flat structure---there -are only a few subdirectories. A file's name usually gives a hint as -to what it does; for example, @file{stabsread.c} reads stabs, -@file{dwarf2read.c} reads @sc{DWARF 2}, etc. - -Files that are related to some common task have names that share -common substrings. For example, @file{*-thread.c} files deal with -debugging threads on various platforms; @file{*read.c} files deal with -reading various kinds of symbol and object files; @file{inf*.c} files -deal with direct control of the @dfn{inferior program} (@value{GDBN} -parlance for the program being debugged). - -There are several dozens of files in the @file{*-tdep.c} family. -@samp{tdep} stands for @dfn{target-dependent code}---each of these -files implements debug support for a specific target architecture -(sparc, mips, etc). Usually, only one of these will be used in a -specific @value{GDBN} configuration (sometimes two, closely related). - -Similarly, there are many @file{*-nat.c} files, each one for native -debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for -native debugging of Sparc machines running the Linux kernel). - -The few subdirectories of the source tree are: - -@table @file -@item cli -Code that implements @dfn{CLI}, the @value{GDBN} Command-Line -Interpreter. @xref{User Interface, Command Interpreter}. - -@item gdbserver -Code for the @value{GDBN} remote server. - -@item gdbtk -Code for Insight, the @value{GDBN} TK-based GUI front-end. - -@item mi -The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter. - -@item signals -Target signal translation code. - -@item tui -Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User -Interface. @xref{User Interface, TUI}. -@end table - -@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 Prologue Analysis - -@cindex prologue analysis -@cindex call frame information -@cindex CFI (call frame information) -To produce a backtrace and allow the user to manipulate older frames' -variables and arguments, @value{GDBN} needs to find the base addresses -of older frames, and discover where those frames' registers have been -saved. Since a frame's ``callee-saves'' registers get saved by -younger frames if and when they're reused, a frame's registers may be -scattered unpredictably across younger frames. This means that -changing the value of a register-allocated variable in an older frame -may actually entail writing to a save slot in some younger frame. - -Modern versions of GCC emit Dwarf call frame information (``CFI''), -which describes how to find frame base addresses and saved registers. -But CFI is not always available, so as a fallback @value{GDBN} uses a -technique called @dfn{prologue analysis} to find frame sizes and saved -registers. A prologue analyzer disassembles the function's machine -code starting from its entry point, and looks for instructions that -allocate frame space, save the stack pointer in a frame pointer -register, save registers, and so on. Obviously, this can't be done -accurately in general, but it's tractable to do well enough to be very -helpful. Prologue analysis predates the GNU toolchain's support for -CFI; at one time, prologue analysis was the only mechanism -@value{GDBN} used for stack unwinding at all, when the function -calling conventions didn't specify a fixed frame layout. - -In the olden days, function prologues were generated by hand-written, -target-specific code in GCC, and treated as opaque and untouchable by -optimizers. Looking at this code, it was usually straightforward to -write a prologue analyzer for @value{GDBN} that would accurately -understand all the prologues GCC would generate. However, over time -GCC became more aggressive about instruction scheduling, and began to -understand more about the semantics of the prologue instructions -themselves; in response, @value{GDBN}'s analyzers became more complex -and fragile. Keeping the prologue analyzers working as GCC (and the -instruction sets themselves) evolved became a substantial task. - -@cindex @file{prologue-value.c} -@cindex abstract interpretation of function prologues -@cindex pseudo-evaluation of function prologues -To try to address this problem, the code in @file{prologue-value.h} -and @file{prologue-value.c} provides a general framework for writing -prologue analyzers that are simpler and more robust than ad-hoc -analyzers. When we analyze a prologue using the prologue-value -framework, we're really doing ``abstract interpretation'' or -``pseudo-evaluation'': running the function's code in simulation, but -using conservative approximations of the values registers and memory -would hold when the code actually runs. For example, if our function -starts with the instruction: - -@example -addi r1, 42 # add 42 to r1 -@end example -@noindent -we don't know exactly what value will be in @code{r1} after executing -this instruction, but we do know it'll be 42 greater than its original -value. - -If we then see an instruction like: - -@example -addi r1, 22 # add 22 to r1 -@end example -@noindent -we still don't know what @code{r1's} value is, but again, we can say -it is now 64 greater than its original value. - -If the next instruction were: - -@example -mov r2, r1 # set r2 to r1's value -@end example -@noindent -then we can say that @code{r2's} value is now the original value of -@code{r1} plus 64. - -It's common for prologues to save registers on the stack, so we'll -need to track the values of stack frame slots, as well as the -registers. So after an instruction like this: - -@example -mov (fp+4), r2 -@end example -@noindent -then we'd know that the stack slot four bytes above the frame pointer -holds the original value of @code{r1} plus 64. - -And so on. - -Of course, this can only go so far before it gets unreasonable. If we -wanted to be able to say anything about the value of @code{r1} after -the instruction: - -@example -xor r1, r3 # exclusive-or r1 and r3, place result in r1 -@end example -@noindent -then things would get pretty complex. But remember, we're just doing -a conservative approximation; if exclusive-or instructions aren't -relevant to prologues, we can just say @code{r1}'s value is now -``unknown''. We can ignore things that are too complex, if that loss of -information is acceptable for our application. - -So when we say ``conservative approximation'' here, what we mean is an -approximation that is either accurate, or marked ``unknown'', but -never inaccurate. - -Using this framework, a prologue analyzer is simply an interpreter for -machine code, but one that uses conservative approximations for the -contents of registers and memory instead of actual values. Starting -from the function's entry point, you simulate instructions up to the -current PC, or an instruction that you don't know how to simulate. -Now you can examine the state of the registers and stack slots you've -kept track of. - -@itemize @bullet - -@item -To see how large your stack frame is, just check the value of the -stack pointer register; if it's the original value of the SP -minus a constant, then that constant is the stack frame's size. -If the SP's value has been marked as ``unknown'', then that means -the prologue has done something too complex for us to track, and -we don't know the frame size. - -@item -To see where we've saved the previous frame's registers, we just -search the values we've tracked --- stack slots, usually, but -registers, too, if you want --- for something equal to the register's -original value. If the calling conventions suggest a standard place -to save a given register, then we can check there first, but really, -anything that will get us back the original value will probably work. -@end itemize - -This does take some work. But prologue analyzers aren't -quick-and-simple pattern patching to recognize a few fixed prologue -forms any more; they're big, hairy functions. Along with inferior -function calls, prologue analysis accounts for a substantial portion -of the time needed to stabilize a @value{GDBN} port. So it's -worthwhile to look for an approach that will be easier to understand -and maintain. In the approach described above: - -@itemize @bullet - -@item -It's easier to see that the analyzer is correct: you just see -whether the analyzer properly (albeit conservatively) simulates -the effect of each instruction. - -@item -It's easier to extend the analyzer: you can add support for new -instructions, and know that you haven't broken anything that -wasn't already broken before. - -@item -It's orthogonal: to gather new information, you don't need to -complicate the code for each instruction. As long as your domain -of conservative values is already detailed enough to tell you -what you need, then all the existing instruction simulations are -already gathering the right data for you. - -@end itemize - -The file @file{prologue-value.h} contains detailed comments explaining -the framework and how to use it. - - -@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 anything 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. - -Basic breakpoint object handling is in @file{breakpoint.c}. However, -much of the interesting breakpoint action is in @file{infrun.c}. - -@table @code -@cindex insert or remove software breakpoint -@findex target_remove_breakpoint -@findex target_insert_breakpoint -@item target_remove_breakpoint (@var{bp_tgt}) -@itemx target_insert_breakpoint (@var{bp_tgt}) -Insert or remove a software breakpoint at address -@code{@var{bp_tgt}->placed_address}. Returns zero for success, -non-zero for failure. On input, @var{bp_tgt} contains the address of the -breakpoint, and is otherwise initialized to zero. The fields of the -@code{struct bp_target_info} pointed to by @var{bp_tgt} are updated -to contain other information about the breakpoint on output. The field -@code{placed_address} may be updated if the breakpoint was placed at a -related address; the field @code{shadow_contents} contains the real -contents of the bytes where the breakpoint has been inserted, -if reading memory would return the breakpoint instead of the -underlying memory; the field @code{shadow_len} is the length of -memory cached in @code{shadow_contents}, if any; and the field -@code{placed_size} is optionally set and used by the target, if -it could differ from @code{shadow_len}. - -For example, the remote target @samp{Z0} packet does not require -shadowing memory, so @code{shadow_len} is left at zero. However, -the length reported by @code{gdbarch_breakpoint_from_pc} is cached in -@code{placed_size}, so that a matching @samp{z0} packet can be -used to remove the breakpoint. - -@cindex insert or remove hardware breakpoint -@findex target_remove_hw_breakpoint -@findex target_insert_hw_breakpoint -@item target_remove_hw_breakpoint (@var{bp_tgt}) -@itemx target_insert_hw_breakpoint (@var{bp_tgt}) -Insert or remove a hardware-assisted breakpoint at address -@code{@var{bp_tgt}->placed_address}. Returns zero for success, -non-zero for failure. See @code{target_insert_breakpoint} for -a description of the @code{struct bp_target_info} pointed to by -@var{bp_tgt}; the @code{shadow_contents} and -@code{shadow_len} members are not used for hardware breakpoints, -but @code{placed_size} may be. -@end table - -@section Single Stepping - -@section Stepping over runtime loader dynamic symbol resolution code -@cindex Procedure Linkage Table, stepping over -@cindex PLT, stepping over -@cindex resolver, stepping over - -If the program uses ELF-style shared libraries, then calls to -functions in shared libraries go through stubs, which live in a table -called the PLT (@dfn{Procedure Linkage Table}). The first time the -function is called, the stub sends control to the dynamic linker, -which looks up the function's real address, patches the stub so that -future calls will go directly to the function, and then passes control -to the function. - -If we are stepping at the source level, we don't want to see any of -this --- we just want to skip over the stub and the dynamic linker. -The simple approach is to single-step until control leaves the dynamic -linker. - -However, on some systems (e.g., Red Hat's 5.2 distribution) the -dynamic linker calls functions in the shared C library, so you can't -tell from the PC alone whether the dynamic linker is still running. -In this case, we use a step-resume breakpoint to get us past the -dynamic linker, as if we were using @code{next} to step over a -function call. - -The @code{in_solib_dynsym_resolve_code} function says whether we're in -the dynamic linker code or not. Normally, this means we single-step. -However, if @code{gdbarch_skip_solib_resolver} then returns non-zero, -then its value is an address where we can place a step-resume -breakpoint to get past the linker's symbol resolution function. - -The @code{in_dynsym_resolve_code} hook of the @code{target_so_ops} -vector can generally be implemented in a pretty portable way, by -comparing the PC against the address ranges of the dynamic linker's -sections. - -The @code{gdbarch_skip_solib_resolver} implementation is generally -going to be system-specific, since it depends on internal details of -the dynamic linker. It's usually not too hard to figure out where to -put a breakpoint, but it certainly isn't portable. -@code{gdbarch_skip_solib_resolver} should do plenty of sanity -checking. If it can't figure things out, returning zero and getting -the (possibly confusing) stepping behavior is better than signaling an -error, which will obscure the change in the inferior's state. */ - -@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 gdbarch_get_longjmp_target -To make this work, you need to define a function called -@code{gdbarch_get_longjmp_target}, which will examine the -@code{jmp_buf} structure and extract the @code{longjmp} target address. -Since @code{jmp_buf} is target specific and typically defined in a -target header not available to @value{GDBN}, you will need to -determine the offset of the PC manually and return that; many targets -define a @code{jb_pc_offset} field in the tdep structure to save the -value once calculated. - -@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 - -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. - -When the inferior stops, @value{GDBN} tries to establish, among other -possible reasons, whether it stopped due to a watchpoint being hit. -It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint -was hit. If not, all watchpoint checking is skipped. - -Then @value{GDBN} calls @code{target_stopped_data_address} exactly -once. This method returns the address of the watchpoint which -triggered, if the target can determine it. If the triggered address -is available, @value{GDBN} compares the address returned by this -method with each watched memory address in each active watchpoint. -For data-read and data-access watchpoints, @value{GDBN} announces -every watchpoint that watches the triggered address as being hit. -For this reason, data-read and data-access watchpoints -@emph{require} that the triggered address be available; if not, read -and access watchpoints will never be considered hit. For data-write -watchpoints, if the triggered address is available, @value{GDBN} -considers only those watchpoints which match that address; -otherwise, @value{GDBN} considers all data-write watchpoints. For -each data-write watchpoint that @value{GDBN} considers, it evaluates -the expression whose value is being watched, and tests whether the -watched value has changed. Watchpoints whose watched values have -changed are announced as hit. - -@c FIXME move these to the main lists of target/native defns - -@value{GDBN} uses several macros and primitives to support hardware -watchpoints: - -@table @code -@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}. - -@cindex insert or remove hardware watchpoint -@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 - -@noindent -These two macros should return 0 for success, non-zero for failure. - -@findex target_stopped_data_address -@item target_stopped_data_address (@var{addr_p}) -If the inferior has some watchpoint that triggered, place the address -associated with the watchpoint at the location pointed to by -@var{addr_p} and return non-zero. Otherwise, return zero. This -is required for data-read and data-access watchpoints. It is -not required for data-write watchpoints, but @value{GDBN} uses -it to improve handling of those also. - -@value{GDBN} will only call this method once per watchpoint stop, -immediately after calling @code{STOPPED_BY_WATCHPOINT}. If the -target's watchpoint indication is sticky, i.e., stays set after -resuming, this method should clear it. For instance, the x86 debug -control register has sticky triggered flags. - -@findex target_watchpoint_addr_within_range -@item target_watchpoint_addr_within_range (@var{target}, @var{addr}, @var{start}, @var{length}) -Check whether @var{addr} (as returned by @code{target_stopped_data_address}) -lies within the hardware-defined watchpoint region described by -@var{start} and @var{length}. This only needs to be provided if the -granularity of a watchpoint is greater than one byte, i.e., if the -watchpoint can also trigger on nearby addresses outside of the watched -region. - -@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. Like @code{gdbarch_have_nonsteppable_watchpoint}, -this is usually set when watchpoints trigger at the instruction -which will perform an interesting read or write. It should be -set if there is a temporary disable bit which allows the processor -to step over the interesting instruction without raising the -watchpoint exception again. - -@findex gdbarch_have_nonsteppable_watchpoint -@item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch}) -If it returns a non-zero value, @value{GDBN} should disable a -watchpoint to step the inferior over it. This is usually set when -watchpoints trigger at the instruction which will perform an -interesting read or write. - -@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. This is usually set -when watchpoints trigger at the instruction following an interesting -read or write. - -@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}. -Normally, this macro is defined to invoke the function pointed to by -the @code{to_stopped_by_watchpoint} member of the structure (of the -type @code{target_ops}, defined on @file{target.h}) that describes the -target-specific operations; @code{to_stopped_by_watchpoint} ignores -the @var{wait_status} argument. - -@value{GDBN} does not require the non-zero value returned by -@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot -determine for sure whether the inferior stopped due to a watchpoint, -it could return non-zero ``just in case''. -@end table - -@subsection Watchpoints and Threads -@cindex watchpoints, with threads - -@value{GDBN} only supports process-wide watchpoints, which trigger -in all threads. @value{GDBN} uses the thread ID to make watchpoints -act as if they were thread-specific, but it cannot set hardware -watchpoints that only trigger in a specific thread. Therefore, even -if the target supports threads, per-thread debug registers, and -watchpoints which only affect a single thread, it should set the -per-thread debug registers for all threads to the same value. On -@sc{gnu}/Linux native targets, this is accomplished by using -@code{ALL_LWPS} in @code{target_insert_watchpoint} and -@code{target_remove_watchpoint} and by using -@code{linux_set_new_thread} to register a handler for newly created -threads. - -@value{GDBN}'s @sc{gnu}/Linux support only reports a single event -at a time, although multiple events can trigger simultaneously for -multi-threaded programs. When multiple events occur, @file{linux-nat.c} -queues subsequent events and returns them the next time the program -is resumed. This means that @code{STOPPED_BY_WATCHPOINT} and -@code{target_stopped_data_address} only need to consult the current -thread's state---the thread indicated by @code{inferior_ptid}. If -two threads have hit watchpoints simultaneously, those routines -will be called a second time for the second thread. - -@subsection x86 Watchpoints -@cindex x86 debug registers -@cindex watchpoints, on x86 - -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}. - -(At present, the library functions read and write debug registers directly, and are -thus only available for native configurations.) - -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}). - -@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 (@var{addr_p}) -The target function -@code{target_stopped_data_address} is set to call this function. -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_stopped_by_watchpoint -@item i386_stopped_by_watchpoint (void) -The macro @code{STOPPED_BY_WATCHPOINT} -is 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 true if any bit is set. Otherwise, false is -returned. - -@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{bp_tgt}) -@itemx i386_remove_hw_breakpoint (@var{bp_tgt}) -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. -The argument is a @code{struct bp_target_info *}, as described in -the documentation for @code{target_insert_breakpoint}. -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_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 - -@noindent -@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 - -@section Checkpoints -@cindex checkpoints -@cindex restart -In the abstract, a checkpoint is a point in the execution history of -the program, which the user may wish to return to at some later time. - -Internally, a checkpoint is a saved copy of the program state, including -whatever information is required in order to restore the program to that -state at a later time. This can be expected to include the state of -registers and memory, and may include external state such as the state -of open files and devices. - -There are a number of ways in which checkpoints may be implemented -in gdb, e.g.@: as corefiles, as forked processes, and as some opaque -method implemented on the target side. - -A corefile can be used to save an image of target memory and register -state, which can in principle be restored later --- but corefiles do -not typically include information about external entities such as -open files. Currently this method is not implemented in gdb. - -A forked process can save the state of user memory and registers, -as well as some subset of external (kernel) state. This method -is used to implement checkpoints on Linux, and in principle might -be used on other systems. - -Some targets, e.g.@: simulators, might have their own built-in -method for saving checkpoints, and gdb might be able to take -advantage of that capability without necessarily knowing any -details of how it is done. - - -@section Observing changes in @value{GDBN} internals -@cindex observer pattern interface -@cindex notifications about changes in internals - -In order to function properly, several modules need to be notified when -some changes occur in the @value{GDBN} internals. Traditionally, these -modules have relied on several paradigms, the most common ones being -hooks and gdb-events. Unfortunately, none of these paradigms was -versatile enough to become the standard notification mechanism in -@value{GDBN}. The fact that they only supported one ``client'' was also -a strong limitation. - -A new paradigm, based on the Observer pattern of the @cite{Design -Patterns} book, has therefore been implemented. The goal was to provide -a new interface overcoming the issues with the notification mechanisms -previously available. This new interface needed to be strongly typed, -easy to extend, and versatile enough to be used as the standard -interface when adding new notifications. - -See @ref{GDB Observers} for a brief description of the observers -currently implemented in GDB. The rationale for the current -implementation is also briefly discussed. - -@node User Interface - -@chapter User Interface - -@value{GDBN} has several user interfaces, of which the traditional -command-line interface is perhaps the most familiar. - -@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. - -@anchor{UI-Independent Output} -@section UI-Independent Output---the @code{ui_out} Functions -@c This section is based on the documentation written by Fernando -@c Nasser <fnasser@redhat.com>. - -@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 -This section mainly concentrates on how to build result output, -although some of it also applies to other kinds of output. - -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 - -@item -machine oriented formatting--a more terse formatting to allow for easy -parsing by programs which read @value{GDBN}'s output - -@item -annotation, whose purpose is to help legacy GUIs to identify interesting -parts in the output -@end itemize - -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. - -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 @code -@item <table> @expansion{} -@code{<header> <body>} -@item <header> @expansion{} -@code{@{ <column> @}} -@item <column> @expansion{} -@code{<width> <alignment> <title>} -@item <body> @expansion{} -@code{@{<row>@}} -@end table - - -@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. - -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{Misc Guidelines, 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{Misc Guidelines, Cleanups}) -that will close the 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_fmt_int (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{fldname}, int @var{value}) -This function outputs a value of an @code{int} variable. It differs from -@code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output. -@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}, struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address}) -This function outputs an address as appropriate for @var{gdbarch}. -@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 (print_address_bits <= 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 ", - hex_string_custom ((unsigned long) b->address, 8)); -@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: - -@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 - -The model that ties these components together is described below. - -@section The @code{libgdb} Model - -A client of @code{libgdb} interacts with the library in two ways. - -@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. - -@section CLI support - -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. - -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: - -@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 - -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 @value{GDBN} would use. - -The event-loop will eventually be made re-entrant. This is so that -@value{GDBN} 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 Values -@chapter Values -@section Values - -@cindex values -@cindex @code{value} structure -@value{GDBN} uses @code{struct value}, or @dfn{values}, as an internal -abstraction for the representation of a variety of inferior objects -and @value{GDBN} convenience objects. - -Values have an associated @code{struct type}, that describes a virtual -view of the raw data or object stored in or accessed through the -value. - -A value is in addition discriminated by its lvalue-ness, given its -@code{enum lval_type} enumeration type: - -@cindex @code{lval_type} enumeration, for values. -@table @code -@item @code{not_lval} -This value is not an lval. It can't be assigned to. - -@item @code{lval_memory} -This value represents an object in memory. - -@item @code{lval_register} -This value represents an object that lives in a register. - -@item @code{lval_internalvar} -Represents the value of an internal variable. - -@item @code{lval_internalvar_component} -Represents part of a @value{GDBN} internal variable. E.g., a -structure field. - -@cindex computed values -@item @code{lval_computed} -These are ``computed'' values. They allow creating specialized value -objects for specific purposes, all abstracted away from the core value -support code. The creator of such a value writes specialized -functions to handle the reading and writing to/from the value's -backend data, and optionally, a ``copy operator'' and a -``destructor''. - -Pointers to these functions are stored in a @code{struct lval_funcs} -instance (declared in @file{value.h}), and passed to the -@code{allocate_computed_value} function, as in the example below. - -@smallexample -static void -nil_value_read (struct value *v) -@{ - /* This callback reads data from some backend, and stores it in V. - In this case, we always read null data. You'll want to fill in - something more interesting. */ - - memset (value_contents_all_raw (v), - value_offset (v), - TYPE_LENGTH (value_type (v))); -@} - -static void -nil_value_write (struct value *v, struct value *fromval) -@{ - /* Takes the data from FROMVAL and stores it in the backend of V. */ - - to_oblivion (value_contents_all_raw (fromval), - value_offset (v), - TYPE_LENGTH (value_type (fromval))); -@} - -static struct lval_funcs nil_value_funcs = - @{ - nil_value_read, - nil_value_write - @}; - -struct value * -make_nil_value (void) -@{ - struct type *type; - struct value *v; - - type = make_nils_type (); - v = allocate_computed_value (type, &nil_value_funcs, NULL); - - return v; -@} -@end smallexample - -See the implementation of the @code{$_siginfo} convenience variable in -@file{infrun.c} as a real example use of lval_computed. - -@end table - -@node Stack Frames -@chapter Stack Frames - -@cindex frame -@cindex call stack frame -A frame is a construct that @value{GDBN} uses to keep track of calling -and called functions. - -@cindex unwind frame -@value{GDBN}'s frame model, a fresh design, was implemented with the -need to support @sc{dwarf}'s Call Frame Information in mind. In fact, -the term ``unwind'' is taken directly from that specification. -Developers wishing to learn more about unwinders, are encouraged to -read the @sc{dwarf} specification, available from -@url{http://www.dwarfstd.org}. - -@findex frame_register_unwind -@findex get_frame_register -@value{GDBN}'s model is that you find a frame's registers by -``unwinding'' them from the next younger frame. That is, -@samp{get_frame_register} which returns the value of a register in -frame #1 (the next-to-youngest frame), is implemented by calling frame -#0's @code{frame_register_unwind} (the youngest frame). But then the -obvious question is: how do you access the registers of the youngest -frame itself? - -@cindex sentinel frame -@findex get_frame_type -@vindex SENTINEL_FRAME -To answer this question, @value{GDBN} has the @dfn{sentinel} frame, the -``-1st'' frame. Unwinding registers from the sentinel frame gives you -the current values of the youngest real frame's registers. If @var{f} -is a sentinel frame, then @code{get_frame_type (@var{f}) @equiv{} -SENTINEL_FRAME}. - -@section Selecting an Unwinder - -@findex frame_unwind_prepend_unwinder -@findex frame_unwind_append_unwinder -The architecture registers a list of frame unwinders (@code{struct -frame_unwind}), using the functions -@code{frame_unwind_prepend_unwinder} and -@code{frame_unwind_append_unwinder}. Each unwinder includes a -sniffer. Whenever @value{GDBN} needs to unwind a frame (to fetch the -previous frame's registers or the current frame's ID), it calls -registered sniffers in order to find one which recognizes the frame. -The first time a sniffer returns non-zero, the corresponding unwinder -is assigned to the frame. - -@section Unwinding the Frame ID -@cindex frame ID - -Every frame has an associated ID, of type @code{struct frame_id}. -The ID includes the stack base and function start address for -the frame. The ID persists through the entire life of the frame, -including while other called frames are running; it is used to -locate an appropriate @code{struct frame_info} from the cache. - -Every time the inferior stops, and at various other times, the frame -cache is flushed. Because of this, parts of @value{GDBN} which need -to keep track of individual frames cannot use pointers to @code{struct -frame_info}. A frame ID provides a stable reference to a frame, even -when the unwinder must be run again to generate a new @code{struct -frame_info} for the same frame. - -The frame's unwinder's @code{this_id} method is called to find the ID. -Note that this is different from register unwinding, where the next -frame's @code{prev_register} is called to unwind this frame's -registers. - -Both stack base and function address are required to identify the -frame, because a recursive function has the same function address for -two consecutive frames and a leaf function may have the same stack -address as its caller. On some platforms, a third address is part of -the ID to further disambiguate frames---for instance, on IA-64 -the separate register stack address is included in the ID. - -An invalid frame ID (@code{outer_frame_id}) returned from the -@code{this_id} method means to stop unwinding after this frame. - -@code{null_frame_id} is another invalid frame ID which should be used -when there is no frame. For instance, certain breakpoints are attached -to a specific frame, and that frame is identified through its frame ID -(we use this to implement the "finish" command). Using -@code{null_frame_id} as the frame ID for a given breakpoint means -that the breakpoint is not specific to any frame. The @code{this_id} -method should never return @code{null_frame_id}. - -@section Unwinding Registers - -Each unwinder includes a @code{prev_register} method. This method -takes a frame, an associated cache pointer, and a register number. -It returns a @code{struct value *} describing the requested register, -as saved by this frame. This is the value of the register that is -current in this frame's caller. - -The returned value must have the same type as the register. It may -have any lvalue type. In most circumstances one of these routines -will generate the appropriate value: - -@table @code -@item frame_unwind_got_optimized -@findex frame_unwind_got_optimized -This register was not saved. - -@item frame_unwind_got_register -@findex frame_unwind_got_register -This register was copied into another register in this frame. This -is also used for unchanged registers; they are ``copied'' into the -same register. - -@item frame_unwind_got_memory -@findex frame_unwind_got_memory -This register was saved in memory. - -@item frame_unwind_got_constant -@findex frame_unwind_got_constant -This register was not saved, but the unwinder can compute the previous -value some other way. - -@item frame_unwind_got_address -@findex frame_unwind_got_address -Same as @code{frame_unwind_got_constant}, except that the value is a target -address. This is frequently used for the stack pointer, which is not -explicitly saved but has a known offset from this frame's stack -pointer. For architectures with a flat unified address space, this is -generally the same as @code{frame_unwind_got_constant}. -@end table - -@node Symbol Handling - -@chapter Symbol Handling - -Symbols are a key part of @value{GDBN}'s operation. Symbols include -variables, functions, and types. - -Symbol information for a large program can be truly massive, and -reading of symbol information is one of the major performance -bottlenecks in @value{GDBN}; it can take many minutes to process it -all. Studies have shown that nearly all the time spent is -computational, rather than file reading. - -One of the ways for @value{GDBN} to provide a good user experience is -to start up quickly, taking no more than a few seconds. It is simply -not possible to process all of a program's debugging info in that -time, and so we attempt to handle symbols incrementally. For instance, -we create @dfn{partial symbol tables} consisting of only selected -symbols, and only expand them to full symbol tables when necessary. - -@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. In -addition, it may bring in more symbols while loading 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. - -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 - -@section Partial Symbol Tables - -@value{GDBN} has three types of symbol tables: - -@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 - -@cindex partial symbol table -This section describes partial symbol tables. - -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. - -The psymtab also contains the range of instruction addresses that the -full symbol table would represent. - -@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. - -Whether or not psymtabs are created depends on the objfile's symbol -reader. The core of @value{GDBN} hides the details of partial symbols -and partial symbol tables behind a set of function pointers known as -the @dfn{quick symbol functions}. These are documented in -@file{symfile.h}. - -@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. GNU's COFF-using configs often use stabs-type info, -encapsulated in special sections. - -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. Debugging info may be either stabs -encapsulated in ELF sections, or more commonly these days, DWARF. - -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{somread.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. - -@c mention DWARF 1 as a formerly-supported format - -@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 Compressed DWARF 2 - -@cindex Compressed DWARF 2 debugging info -Compressed DWARF 2 is not technically a separate debugging format, but -merely DWARF 2 debug information that has been compressed. In this -format, every object-file section holding DWARF 2 debugging -information is compressed and prepended with a header. (The section -is also typically renamed, so a section called @code{.debug_info} in a -DWARF 2 binary would be called @code{.zdebug_info} in a compressed -DWARF 2 binary.) The header is 12 bytes long: - -@itemize @bullet -@item -4 bytes: the literal string ``ZLIB'' -@item -8 bytes: the uncompressed size of the section, in big-endian byte -order. -@end itemize - -The same reader is used for both compressed an normal DWARF 2 info. -Section decompression is done in @code{zlib_decompress_section} in -@file{dwarf2read.c}. - -@subsection DWARF 3 - -@cindex DWARF 3 debugging info -DWARF 3 is an improved version of DWARF 2. - -@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}. - -@section Memory Management for Symbol Files - -Most memory associated with a loaded symbol file is stored on -its @code{objfile_obstack}. This includes symbols, types, -namespace data, and other information produced by the symbol readers. - -Because this data lives on the objfile's obstack, it is automatically -released when the objfile is unloaded or reloaded. Therefore one -objfile must not reference symbol or type data from another objfile; -they could be unloaded at different times. - -User convenience variables, et cetera, have associated types. Normally -these types live in the associated objfile. However, when the objfile -is unloaded, those types are deep copied to global memory, so that -the values of the user variables and history items are not lost. - - -@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. - -@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 -@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 @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 -language_defn} in @file{language.h}, and the other @file{*-exp.y} files, -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 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 -the number of @code{exp_element}s that a given operation takes up. - -@item Update some existing code - -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 -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. - -@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. -Currently, the language is set based upon the extension of the source -file. If the language can be better inferred from the symbol -information, please set the language of the symtab in the symbol-reading -code. - -@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_exp_1} (defined in @file{parse.c}). - -@item Edit @file{Makefile.in} - -Add dependencies in @file{Makefile.in}. Make sure you update the macro -variables such as @code{HFILES} and @code{OBJS}, otherwise your code may -not get linked in, or, worse yet, it may not get @code{tar}red into the -distribution! -@end table - - -@node Host Definition - -@chapter Host Definition - -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. - -@section Adding a New Host - -@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. - -@table @file -@item gdb/config/@var{arch}/@var{xyz}.mh -This file is a Makefile fragment that once contained both host and -native configuration information (@pxref{Native Debugging}) for the -machine @var{xyz}. The host configuration information is now handled -by Autoconf. - -Host configuration information included 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}. - -New host-only configurations do not need this file. - -@end table - -(Files named @file{gdb/config/@var{arch}/xm-@var{xyz}.h} were once -used to define host-specific macros, but were no longer needed and -have all been removed.) - -@subheading Generic Host Support Files - -@cindex generic host support -There are some ``generic'' versions of routines that can be used by -various systems. - -@table @file -@cindex remote debugging support -@cindex serial line support -@item ser-unix.c -This contains serial line support for Unix systems. It is included by -default on all Unix-like hosts. - -@item ser-pipe.c -This contains serial pipe support for Unix systems. It is included by -default on all Unix-like hosts. - -@item ser-mingw.c -This contains serial line support for 32-bit programs running under -Windows using MinGW. - -@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. It is included by -default on all Unix-like hosts and with MinGW. -@end table - -@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. While formerly they could be set in -host-specific header files, at present they can be changed only by -setting @code{CFLAGS} when building, or by editing the source code. - -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 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 ISATTY -Substitute for isatty, if not available. - -@item FOPEN_RB -Define this if binary files are opened the same way as text files. - -@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 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 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}. - -@menu -* OS ABI Variant Handling:: -* Initialize New Architecture:: -* Registers and Memory:: -* Pointers and Addresses:: -* Address Classes:: -* Register Representation:: -* Frame Interpretation:: -* Inferior Call Setup:: -* Adding support for debugging core files:: -* Defining Other Architecture Features:: -* Adding a New Target:: -@end menu - -@node OS ABI Variant Handling -@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{defs.h}: - -@table @code - -@findex GDB_OSABI_UNINITIALIZED -@item GDB_OSABI_UNINITIALIZED -Used for struct gdbarch_info if ABI is still uninitialized. - -@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. - -@findex GDB_OSABI_SVR4 -@item GDB_OSABI_SVR4 -UNIX System V Release 4. - -@findex GDB_OSABI_HURD -@item GDB_OSABI_HURD -GNU using the Hurd kernel. - -@findex GDB_OSABI_SOLARIS -@item GDB_OSABI_SOLARIS -Sun Solaris. - -@findex GDB_OSABI_OSF1 -@item GDB_OSABI_OSF1 -OSF/1, including Digital UNIX and Compaq Tru64 UNIX. - -@findex GDB_OSABI_LINUX -@item GDB_OSABI_LINUX -GNU using the Linux kernel. - -@findex GDB_OSABI_FREEBSD_AOUT -@item GDB_OSABI_FREEBSD_AOUT -FreeBSD using the @code{a.out} executable format. - -@findex GDB_OSABI_FREEBSD_ELF -@item GDB_OSABI_FREEBSD_ELF -FreeBSD using the ELF executable format. - -@findex GDB_OSABI_NETBSD_AOUT -@item GDB_OSABI_NETBSD_AOUT -NetBSD using the @code{a.out} executable format. - -@findex GDB_OSABI_NETBSD_ELF -@item GDB_OSABI_NETBSD_ELF -NetBSD using the ELF executable format. - -@findex GDB_OSABI_OPENBSD_ELF -@item GDB_OSABI_OPENBSD_ELF -OpenBSD using the ELF executable format. - -@findex GDB_OSABI_WINCE -@item GDB_OSABI_WINCE -Windows CE. - -@findex GDB_OSABI_GO32 -@item GDB_OSABI_GO32 -DJGPP. - -@findex GDB_OSABI_IRIX -@item GDB_OSABI_IRIX -Irix. - -@findex GDB_OSABI_INTERIX -@item GDB_OSABI_INTERIX -Interix (Posix layer for MS-Windows systems). - -@findex GDB_OSABI_HPUX_ELF -@item GDB_OSABI_HPUX_ELF -HP/UX using the ELF executable format. - -@findex GDB_OSABI_HPUX_SOM -@item GDB_OSABI_HPUX_SOM -HP/UX using the SOM executable format. - -@findex GDB_OSABI_QNXNTO -@item GDB_OSABI_QNXNTO -QNX Neutrino. - -@findex GDB_OSABI_CYGWIN -@item GDB_OSABI_CYGWIN -Cygwin. - -@findex GDB_OSABI_AIX -@item GDB_OSABI_AIX -AIX. - -@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}, unsigned long @var{machine}, 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, machine type and OS ABI specified by @var{arch}, -@var{machine} and @var{osabi}. In most cases, a value of zero for the -machine type, which implies the architecture's default machine type, -will suffice. -@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 - -@deftypefun void generic_elf_osabi_sniff_abi_tag_sections (bfd *@var{abfd}, asection *@var{sect}, void *@var{obj}) -Helper routine for ELF file sniffers. Examine the file described by -@var{abfd} and look at ABI tag note sections to determine the OS ABI -from the note. This function should be called via -@code{bfd_map_over_sections}. -@end deftypefun - -@node Initialize New Architecture -@section Initializing a New Architecture - -@menu -* How an Architecture is Represented:: -* Looking Up an Existing Architecture:: -* Creating a New Architecture:: -@end menu - -@node How an Architecture is Represented -@subsection How an Architecture is Represented -@cindex architecture representation -@cindex representation of architecture - -Each @code{gdbarch} is associated with a single @sc{bfd} architecture, -via a @code{bfd_arch_@var{arch}} in the @code{bfd_architecture} -enumeration. The @code{gdbarch} is registered by a call to -@code{register_gdbarch_init}, usually from the file's -@code{_initialize_@var{filename}} routine, which will be automatically -called during @value{GDBN} startup. The arguments are a @sc{bfd} -architecture constant and an initialization function. - -@findex _initialize_@var{arch}_tdep -@cindex @file{@var{arch}-tdep.c} -A @value{GDBN} description for a new architecture, @var{arch} is created by -defining a global function @code{_initialize_@var{arch}_tdep}, by -convention in the source file @file{@var{arch}-tdep.c}. For example, -in the case of the OpenRISC 1000, this function is called -@code{_initialize_or1k_tdep} and is found in the file -@file{or1k-tdep.c}. - -@cindex @file{configure.tgt} -@cindex @code{gdbarch} -@findex gdbarch_register -The resulting object files containing the implementation of the -@code{_initialize_@var{arch}_tdep} function are specified in the @value{GDBN} -@file{configure.tgt} file, which includes a large case statement -pattern matching against the @code{--target} option of the -@code{configure} script. The new @code{struct gdbarch} is created -within the @code{_initialize_@var{arch}_tdep} function by calling -@code{gdbarch_register}: - -@smallexample -void gdbarch_register (enum bfd_architecture @var{architecture}, - gdbarch_init_ftype *@var{init_func}, - gdbarch_dump_tdep_ftype *@var{tdep_dump_func}); -@end smallexample - -The @var{architecture} will identify the unique @sc{bfd} to be -associated with this @code{gdbarch}. The @var{init_func} funciton is -called to create and return the new @code{struct gdbarch}. The -@var{tdep_dump_func} function will dump the target specific details -associated with this architecture. - -For example the function @code{_initialize_or1k_tdep} creates its -architecture for 32-bit OpenRISC 1000 architectures by calling: - -@smallexample -gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep); -@end smallexample - -@node Looking Up an Existing Architecture -@subsection Looking Up an Existing Architecture -@cindex @code{gdbarch} lookup - -The initialization function has this prototype: - -@smallexample -static struct gdbarch * -@var{arch}_gdbarch_init (struct gdbarch_info @var{info}, - struct gdbarch_list *@var{arches}) -@end smallexample - -The @var{info} argument contains parameters used to select the correct -architecture, and @var{arches} is a list of architectures which -have already been created with the same @code{bfd_arch_@var{arch}} -value. - -The initialization function should first make sure that @var{info} -is acceptable, and return @code{NULL} if it is not. Then, it should -search through @var{arches} for an exact match to @var{info}, and -return one if found. Lastly, if no exact match was found, it should -create a new architecture based on @var{info} and return it. - -@findex gdbarch_list_lookup_by_info -@cindex @code{gdbarch_info} -The lookup is done using @code{gdbarch_list_lookup_by_info}. It is -passed the list of existing architectures, @var{arches}, and the -@code{struct gdbarch_info}, @var{info}, and returns the first matching -architecture it finds, or @code{NULL} if none are found. If an -architecture is found it can be returned as the result from the -initialization function, otherwise a new @code{struct gdbach} will need -to be created. - -The struct gdbarch_info has the following components: - -@smallexample -struct gdbarch_info -@{ - const struct bfd_arch_info *bfd_arch_info; - int byte_order; - bfd *abfd; - struct gdbarch_tdep_info *tdep_info; - enum gdb_osabi osabi; - const struct target_desc *target_desc; -@}; -@end smallexample - -@vindex bfd_arch_info -The @code{bfd_arch_info} member holds the key details about the -architecture. The @code{byte_order} member is a value in an -enumeration indicating the endianism. The @code{abfd} member is a -pointer to the full @sc{bfd}, the @code{tdep_info} member is -additional custom target specific information, @code{osabi} identifies -which (if any) of a number of operating specific ABIs are used by this -architecture and the @code{target_desc} member is a set of name-value -pairs with information about register usage in this target. - -When the @code{struct gdbarch} initialization function is called, not -all the fields are provided---only those which can be deduced from the -@sc{bfd}. The @code{struct gdbarch_info}, @var{info} is used as a -look-up key with the list of existing architectures, @var{arches} to -see if a suitable architecture already exists. The @var{tdep_info}, -@var{osabi} and @var{target_desc} fields may be added before this -lookup to refine the search. - -Only information in @var{info} should be used to choose the new -architecture. Historically, @var{info} could be sparse, and -defaults would be collected from the first element on @var{arches}. -However, @value{GDBN} now fills in @var{info} more thoroughly, -so new @code{gdbarch} initialization functions should not take -defaults from @var{arches}. - -@node Creating a New Architecture -@subsection Creating a New Architecture -@cindex @code{struct gdbarch} creation - -@findex gdbarch_alloc -@cindex @code{gdbarch_tdep} when allocating new @code{gdbarch} -If no architecture is found, then a new architecture must be created, -by calling @code{gdbarch_alloc} using the supplied @code{@w{struct -gdbarch_info}} and any additional custom target specific -information in a @code{struct gdbarch_tdep}. The prototype for -@code{gdbarch_alloc} is: - -@smallexample -struct gdbarch *gdbarch_alloc (const struct gdbarch_info *@var{info}, - struct gdbarch_tdep *@var{tdep}); -@end smallexample - -@cindex @code{set_gdbarch} functions -@cindex @code{gdbarch} accessor functions -The newly created struct gdbarch must then be populated. Although -there are default values, in most cases they are not what is -required. - -For each element, @var{X}, there is are a pair of corresponding accessor -functions, one to set the value of that element, -@code{set_gdbarch_@var{X}}, the second to either get the value of an -element (if it is a variable) or to apply the element (if it is a -function), @code{gdbarch_@var{X}}. Note that both accessor functions -take a pointer to the @code{@w{struct gdbarch}} as first -argument. Populating the new @code{gdbarch} should use the -@code{set_gdbarch} functions. - -The following sections identify the main elements that should be set -in this way. This is not the complete list, but represents the -functions and elements that must commonly be specified for a new -architecture. Many of the functions and variables are described in the -header file @file{gdbarch.h}. - -This is the main work in defining a new architecture. Implementing the -set of functions to populate the @code{struct gdbarch}. - -@cindex @code{gdbarch_tdep} definition -@code{struct gdbarch_tdep} is not defined within @value{GDBN}---it is up -to the user to define this struct if it is needed to hold custom target -information that is not covered by the standard @code{@w{struct -gdbarch}}. For example with the OpenRISC 1000 architecture it is used to -hold the number of matchpoints available in the target (along with other -information). - -If there is no additional target specific information, it can be set to -@code{NULL}. - -@node Registers and Memory -@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{gdbarch_register_name} and related functions. - -@value{GDBN} can handle big-endian, little-endian, and bi-endian architectures. - -@node Pointers and Addresses -@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. - -@c D10V is gone from sources - more current example? - -For example, the Renesas 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 - -Here are two functions 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. - -@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{gdbarch}, 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 deftypefun - -@deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{gdbarch}, 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 deftypefun - -@node Address Classes -@section Address Classes -@cindex address classes -@cindex DW_AT_byte_size -@cindex DW_AT_address_class - -Sometimes information about different kinds of addresses is available -via the debug information. For example, some programming environments -define addresses of several different sizes. If the debug information -distinguishes these kinds of address classes through either the size -info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit -address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the -following macros should be defined in order to disambiguate these -types within @value{GDBN} as well as provide the added information to -a @value{GDBN} user when printing type expressions. - -@deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class}) -Returns the type flags needed to construct a pointer type whose size -is @var{byte_size} and whose address class is @var{dwarf2_addr_class}. -This function is normally called from within a symbol reader. See -@file{dwarf2read.c}. -@end deftypefun - -@deftypefun {char *} gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{gdbarch}, int @var{type_flags}) -Given the type flags representing an address class qualifier, return -its name. -@end deftypefun -@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{gdbarch}, int @var{name}, int *@var{type_flags_ptr}) -Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags -for that address class qualifier. -@end deftypefun - -Since the need for address classes is rather rare, none of -the address class functions are defined by default. Predicate -functions are provided to detect when they are defined. - -Consider a hypothetical architecture in which addresses are normally -32-bits wide, but 16-bit addresses are also supported. Furthermore, -suppose that the @w{DWARF 2} information for this architecture simply -uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one -of these "short" pointers. The following functions could be defined -to implement the address class functions: - -@smallexample -somearch_address_class_type_flags (int byte_size, - int dwarf2_addr_class) -@{ - if (byte_size == 2) - return TYPE_FLAG_ADDRESS_CLASS_1; - else - return 0; -@} - -static char * -somearch_address_class_type_flags_to_name (int type_flags) -@{ - if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1) - return "short"; - else - return NULL; -@} - -int -somearch_address_class_name_to_type_flags (char *name, - int *type_flags_ptr) -@{ - if (strcmp (name, "short") == 0) - @{ - *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1; - return 1; - @} - else - return 0; -@} -@end smallexample - -The qualifier @code{@@short} is used in @value{GDBN}'s type expressions -to indicate the presence of one of these ``short'' pointers. For -example if the debug information indicates that @code{short_ptr_var} is -one of these short pointers, @value{GDBN} might show the following -behavior: - -@smallexample -(gdb) ptype short_ptr_var -type = int * @@short -@end smallexample - - -@node Register Representation -@section Register Representation - -@menu -* Raw and Cooked Registers:: -* Register Architecture Functions & Variables:: -* Register Information Functions:: -* Register and Memory Data:: -* Register Caching:: -@end menu - -@node Raw and Cooked Registers -@subsection Raw and Cooked Registers -@cindex raw register representation -@cindex cooked register representation -@cindex representations, raw and cooked registers - -@value{GDBN} considers registers to be a set with members numbered -linearly from 0 upwards. The first part of that set corresponds to real -physical registers, the second part to any @dfn{pseudo-registers}. -Pseudo-registers have no independent physical existence, but are useful -representations of information within the architecture. For example the -OpenRISC 1000 architecture has up to 32 general purpose registers, which -are typically represented as 32-bit (or 64-bit) integers. However the -GPRs are also used as operands to the floating point operations, and it -could be convenient to define a set of pseudo-registers, to show the -GPRs represented as floating point values. - -For any architecture, the implementer will decide on a mapping from -hardware to @value{GDBN} register numbers. The registers corresponding to real -hardware are referred to as @dfn{raw} registers, the remaining registers are -@dfn{pseudo-registers}. The total register set (raw and pseudo) is called -the @dfn{cooked} register set. - - -@node Register Architecture Functions & Variables -@subsection Functions and Variables Specifying the Register Architecture -@cindex @code{gdbarch} register architecture functions - -These @code{struct gdbarch} functions and variables specify the number -and type of registers in the architecture. - -@deftypefn {Architecture Function} CORE_ADDR read_pc (struct regcache *@var{regcache}) -@end deftypefn -@deftypefn {Architecture Function} void write_pc (struct regcache *@var{regcache}, CORE_ADDR @var{val}) - -Read or write the program counter. The default value of both -functions is @code{NULL} (no function available). If the program -counter is just an ordinary register, it can be specified in -@code{struct gdbarch} instead (see @code{pc_regnum} below) and it will -be read or written using the standard routines to access registers. This -function need only be specified if the program counter is not an -ordinary register. - -Any register information can be obtained using the supplied register -cache, @var{regcache}. @xref{Register Caching, , Register Caching}. - -@end deftypefn - -@deftypefn {Architecture Function} void pseudo_register_read (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf}) -@end deftypefn -@deftypefn {Architecture Function} void pseudo_register_write (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf}) - -These functions should be defined if there are any pseudo-registers. -The default value is @code{NULL}. @var{regnum} is the number of the -register to read or write (which will be a @dfn{cooked} register -number) and @var{buf} is the buffer where the value read will be -placed, or from which the value to be written will be taken. The -value in the buffer may be converted to or from a signed or unsigned -integral value using one of the utility functions (@pxref{Register and -Memory Data, , Using Different Register and Memory Data -Representations}). - -The access should be for the specified architecture, -@var{gdbarch}. Any register information can be obtained using the -supplied register cache, @var{regcache}. @xref{Register Caching, , -Register Caching}. - -@end deftypefn - -@deftypevr {Architecture Variable} int sp_regnum -@vindex sp_regnum -@cindex stack pointer -@cindex @kbd{$sp} - -This specifies the register holding the stack pointer, which may be a -raw or pseudo-register. It defaults to -1 (not defined), but it is an -error for it not to be defined. - -The value of the stack pointer register can be accessed withing -@value{GDBN} as the variable @kbd{$sp}. - -@end deftypevr - -@deftypevr {Architecture Variable} int pc_regnum -@vindex pc_regnum -@cindex program counter -@cindex @kbd{$pc} - -This specifies the register holding the program counter, which may be a -raw or pseudo-register. It defaults to -1 (not defined). If -@code{pc_regnum} is not defined, then the functions @code{read_pc} and -@code{write_pc} (see above) must be defined. - -The value of the program counter (whether defined as a register, or -through @code{read_pc} and @code{write_pc}) can be accessed withing -@value{GDBN} as the variable @kbd{$pc}. - -@end deftypevr - -@deftypevr {Architecture Variable} int ps_regnum -@vindex ps_regnum -@cindex processor status register -@cindex status register -@cindex @kbd{$ps} - -This specifies the register holding the processor status (often called -the status register), which may be a raw or pseudo-register. It -defaults to -1 (not defined). - -If defined, the value of this register can be accessed withing -@value{GDBN} as the variable @kbd{$ps}. - -@end deftypevr - -@deftypevr {Architecture Variable} int fp0_regnum -@vindex fp0_regnum -@cindex first floating point register - -This specifies the first floating point register. It defaults to -0. @code{fp0_regnum} is not needed unless the target offers support -for floating point. - -@end deftypevr - -@node Register Information Functions -@subsection Functions Giving Register Information -@cindex @code{gdbarch} register information functions - -These functions return information about registers. - -@deftypefn {Architecture Function} {const char *} register_name (struct gdbarch *@var{gdbarch}, int @var{regnum}) - -This function should convert a register number (raw or pseudo) to a -register name (as a C @code{const char *}). This is used both to -determine the name of a register for output and to work out the meaning -of any register names used as input. The function may also return -@code{NULL}, to indicate that @var{regnum} is not a valid register. - -For example with the OpenRISC 1000, @value{GDBN} registers 0-31 are the -General Purpose Registers, register 32 is the program counter and -register 33 is the supervision register (i.e.@: the processor status -register), which map to the strings @code{"gpr00"} through -@code{"gpr31"}, @code{"pc"} and @code{"sr"} respectively. This means -that the @value{GDBN} command @kbd{print $gpr5} should print the value of -the OR1K general purpose register 5@footnote{ -@cindex frame pointer -@cindex @kbd{$fp} -Historically, @value{GDBN} always had a concept of a frame pointer -register, which could be accessed via the @value{GDBN} variable, -@kbd{$fp}. That concept is now deprecated, recognizing that not all -architectures have a frame pointer. However if an architecture does -have a frame pointer register, and defines a register or -pseudo-register with the name @code{"fp"}, then that register will be -used as the value of the @kbd{$fp} variable.}. - -The default value for this function is @code{NULL}, meaning -undefined. It should always be defined. - -The access should be for the specified architecture, @var{gdbarch}. - -@end deftypefn - -@deftypefn {Architecture Function} {struct type *} register_type (struct gdbarch *@var{gdbarch}, int @var{regnum}) - -Given a register number, this function identifies the type of data it -may be holding, specified as a @code{struct type}. @value{GDBN} allows -creation of arbitrary types, but a number of built in types are -provided (@code{builtin_type_void}, @code{builtin_type_int32} etc), -together with functions to derive types from these. - -Typically the program counter will have a type of ``pointer to -function'' (it points to code), the frame pointer and stack pointer -will have types of ``pointer to void'' (they point to data on the stack) -and all other integer registers will have a type of 32-bit integer or -64-bit integer. - -This information guides the formatting when displaying register -information. The default value is @code{NULL} meaning no information is -available to guide formatting when displaying registers. - -@end deftypefn - -@deftypefn {Architecture Function} void print_registers_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, int @var{regnum}, int @var{all}) - -Define this function to print out one or all of the registers for the -@value{GDBN} @kbd{info registers} command. The default value is the -function @code{default_print_registers_info}, which uses the register -type information (see @code{register_type} above) to determine how each -register should be printed. Define a custom version of this function -for fuller control over how the registers are displayed. - -The access should be for the specified architecture, @var{gdbarch}, -with output to the file specified by the User Interface -Independent Output file handle, @var{file} (@pxref{UI-Independent -Output, , UI-Independent Output---the @code{ui_out} -Functions}). - -The registers should show their values in the frame specified by -@var{frame}. If @var{regnum} is -1 and @var{all} is zero, then all -the ``significant'' registers should be shown (the implementer should -decide which registers are ``significant''). Otherwise only the value of -the register specified by @var{regnum} should be output. If -@var{regnum} is -1 and @var{all} is non-zero (true), then the value of -all registers should be shown. - -By default @code{default_print_registers_info} prints one register per -line, and if @var{all} is zero omits floating-point registers. - -@end deftypefn - -@deftypefn {Architecture Function} void print_float_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args}) - -Define this function to provide output about the floating point unit and -registers for the @value{GDBN} @kbd{info float} command respectively. -The default value is @code{NULL} (not defined), meaning no information -will be provided. - -The @var{gdbarch} and @var{file} and @var{frame} arguments have the same -meaning as in the @code{print_registers_info} function above. The string -@var{args} contains any supplementary arguments to the @kbd{info float} -command. - -Define this function if the target supports floating point operations. - -@end deftypefn - -@deftypefn {Architecture Function} void print_vector_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args}) - -Define this function to provide output about the vector unit and -registers for the @value{GDBN} @kbd{info vector} command respectively. -The default value is @code{NULL} (not defined), meaning no information -will be provided. - -The @var{gdbarch}, @var{file} and @var{frame} arguments have the -same meaning as in the @code{print_registers_info} function above. The -string @var{args} contains any supplementary arguments to the @kbd{info -vector} command. - -Define this function if the target supports vector operations. - -@end deftypefn - -@deftypefn {Architecture Function} int register_reggroup_p (struct gdbarch *@var{gdbarch}, int @var{regnum}, struct reggroup *@var{group}) - -@value{GDBN} groups registers into different categories (general, -vector, floating point etc). This function, given a register, -@var{regnum}, and group, @var{group}, returns 1 (true) if the register -is in the group and 0 (false) otherwise. - -The information should be for the specified architecture, -@var{gdbarch} - -The default value is the function @code{default_register_reggroup_p} -which will do a reasonable job based on the type of the register (see -the function @code{register_type} above), with groups for general -purpose registers, floating point registers, vector registers and raw -(i.e not pseudo) registers. - -@end deftypefn - -@node Register and Memory Data -@subsection 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 - -Some architectures have different representations of data objects, -depending whether the object is held in a register or memory. For -example: - -@itemize @bullet - -@item -The Alpha architecture can represent 32 bit integer values in -floating-point registers. - -@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 - -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. - -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. An architecture may define the -following @code{struct gdbarch} functions to request conversions -between the register and memory representations of a data type: - -@deftypefn {Architecture Function} int gdbarch_convert_register_p (struct gdbarch *@var{gdbarch}, int @var{reg}) - -Return non-zero (true) 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. The default value is @code{NULL} -(undefined). - -If this function is defined and returns non-zero, the @code{struct -gdbarch} functions @code{gdbarch_register_to_value} and -@code{gdbarch_value_to_register} (see below) should be used to perform -any necessary conversion. - -If defined, this function should return zero for the register's native -type, when no conversion is necessary. -@end deftypefn - -@deftypefn {Architecture Function} void gdbarch_register_to_value (struct gdbarch *@var{gdbarch}, 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}. - -@quotation -@emph{Note:} @code{gdbarch_register_to_value} and -@code{gdbarch_value_to_register} take their @var{reg} and @var{type} -arguments in different orders. -@end quotation - -@code{gdbarch_register_to_value} should only be used with registers -for which the @code{gdbarch_convert_register_p} function returns a -non-zero value. - -@end deftypefn - -@deftypefn {Architecture Function} void gdbarch_value_to_register (struct gdbarch *@var{gdbarch}, 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. - -@quotation -@emph{Note:} @code{gdbarch_register_to_value} and -@code{gdbarch_value_to_register} take their @var{reg} and @var{type} -arguments in different orders. -@end quotation - -@code{gdbarch_value_to_register} should only be used with registers -for which the @code{gdbarch_convert_register_p} function returns a -non-zero value. - -@end deftypefn - -@node Register Caching -@subsection Register Caching -@cindex register caching - -Caching of registers is used, so that the target does not need to be -accessed and reanalyzed multiple times for each register in -circumstances where the register value cannot have changed. - -@cindex @code{struct regcache} -@value{GDBN} provides @code{struct regcache}, associated with a -particular @code{struct gdbarch} to hold the cached values of the raw -registers. A set of functions is provided to access both the raw -registers (with @code{raw} in their name) and the full set of cooked -registers (with @code{cooked} in their name). Functions are provided -to ensure the register cache is kept synchronized with the values of -the actual registers in the target. - -Accessing registers through the @code{struct regcache} routines will -ensure that the appropriate @code{struct gdbarch} functions are called -when necessary to access the underlying target architecture. In general -users should use the @dfn{cooked} functions, since these will map to the -@dfn{raw} functions automatically as appropriate. - -@findex regcache_cooked_read -@findex regcache_cooked_write -@cindex @code{gdb_byte} -@findex regcache_cooked_read_signed -@findex regcache_cooked_read_unsigned -@findex regcache_cooked_write_signed -@findex regcache_cooked_write_unsigned -The two key functions are @code{regcache_cooked_read} and -@code{regcache_cooked_write} which read or write a register from or to -a byte buffer (type @code{gdb_byte *}). For convenience the wrapper -functions @code{regcache_cooked_read_signed}, -@code{regcache_cooked_read_unsigned}, -@code{regcache_cooked_write_signed} and -@code{regcache_cooked_write_unsigned} are provided, which read or -write the value using the buffer and convert to or from an integral -value as appropriate. - -@node Frame Interpretation -@section Frame Interpretation - -@menu -* All About Stack Frames:: -* Frame Handling Terminology:: -* Prologue Caches:: -* Functions and Variable to Analyze Frames:: -* Functions to Access Frame Data:: -* Analyzing Stacks---Frame Sniffers:: -@end menu - -@node All About Stack Frames -@subsection All About Stack Frames - -@value{GDBN} needs to understand the stack on which local (automatic) -variables are stored. The area of the stack containing all the local -variables for a function invocation is known as the @dfn{stack frame} -for that function (or colloquially just as the @dfn{frame}). In turn the -function that called the function will have its stack frame, and so on -back through the chain of functions that have been called. - -Almost all architectures have one register dedicated to point to the -end of the stack (the @dfn{stack pointer}). Many have a second register -which points to the start of the currently active stack frame (the -@dfn{frame pointer}). The specific arrangements for an architecture are -a key part of the ABI. - -A diagram helps to explain this. Here is a simple program to compute -factorials: - -@smallexample -#include <stdio.h> -int fact (int n) -@{ - if (0 == n) - @{ - return 1; - @} - else - @{ - return n * fact (n - 1); - @} -@} - -main () -@{ - int i; - - for (i = 0; i < 10; i++) - @{ - int f = fact (i); - printf ("%d! = %d\n", i, f); - @} -@} -@end smallexample - -Consider the state of the stack when the code reaches line 6 after the -main program has called @code{fact@w{ }(3)}. The chain of function -calls will be @code{main ()}, @code{fact@w{ }(3)}, @code{fact@w{ -}(2)}, @code{@w{fact (1)}} and @code{fact@w{ }(0)}. - -In this illustration the stack is falling (as used for example by the -OpenRISC 1000 ABI). The stack pointer (SP) is at the end of the stack -(lowest address) and the frame pointer (FP) is at the highest address -in the current stack frame. The following diagram shows how the stack -looks. - -@center @image{stack_frame,14cm} - -In each stack frame, offset 0 from the stack pointer is the frame -pointer of the previous frame and offset 4 (this is illustrating a -32-bit architecture) from the stack pointer is the return address. -Local variables are indexed from the frame pointer, with negative -indexes. In the function @code{fact}, offset -4 from the frame -pointer is the argument @var{n}. In the @code{main} function, offset --4 from the frame pointer is the local variable @var{i} and offset -8 -from the frame pointer is the local variable @var{f}@footnote{This is -a simplified example for illustrative purposes only. Good optimizing -compilers would not put anything on the stack for such simple -functions. Indeed they might eliminate the recursion and use of the -stack entirely!}. - -It is very easy to get confused when examining stacks. @value{GDBN} -has terminology it uses rigorously throughout. The stack frame of the -function currently executing, or where execution stopped is numbered -zero. In this example frame #0 is the stack frame of the call to -@code{fact@w{ }(0)}. The stack frame of its calling function -(@code{fact@w{ }(1)} in this case) is numbered #1 and so on back -through the chain of calls. - -The main @value{GDBN} data structure describing frames is - @code{@w{struct frame_info}}. It is not used directly, but only via -its accessor functions. @code{frame_info} includes information about -the registers in the frame and a pointer to the code of the function -with which the frame is associated. The entire stack is represented as -a linked list of @code{frame_info} structs. - -@node Frame Handling Terminology -@subsection Frame Handling Terminology - -It is easy to get confused when referencing stack frames. @value{GDBN} -uses some precise terminology. - -@itemize @bullet - -@item -@cindex THIS frame -@cindex stack frame, definition of THIS frame -@cindex frame, definition of THIS frame -@dfn{THIS} frame is the frame currently under consideration. - -@item -@cindex NEXT frame -@cindex stack frame, definition of NEXT frame -@cindex frame, definition of NEXT frame -The @dfn{NEXT} frame, also sometimes called the inner or newer frame is the -frame of the function called by the function of THIS frame. - -@item -@cindex PREVIOUS frame -@cindex stack frame, definition of PREVIOUS frame -@cindex frame, definition of PREVIOUS frame -The @dfn{PREVIOUS} frame, also sometimes called the outer or older frame is -the frame of the function which called the function of THIS frame. - -@end itemize - -So in the example in the previous section (@pxref{All About Stack -Frames, , All About Stack Frames}), if THIS frame is #3 (the call to -@code{fact@w{ }(3)}), the NEXT frame is frame #2 (the call to -@code{fact@w{ }(2)}) and the PREVIOUS frame is frame #4 (the call to -@code{main@w{ }()}). - -@cindex innermost frame -@cindex stack frame, definition of innermost frame -@cindex frame, definition of innermost frame -The @dfn{innermost} frame is the frame of the current executing -function, or where the program stopped, in this example, in the middle -of the call to @code{@w{fact (0))}}. It is always numbered frame #0. - -@cindex base of a frame -@cindex stack frame, definition of base of a frame -@cindex frame, definition of base of a frame -The @dfn{base} of a frame is the address immediately before the start -of the NEXT frame. For a stack which grows down in memory (a -@dfn{falling} stack) this will be the lowest address and for a stack -which grows up in memory (a @dfn{rising} stack) this will be the -highest address in the frame. - -@value{GDBN} functions to analyze the stack are typically given a -pointer to the NEXT frame to determine information about THIS -frame. Information about THIS frame includes data on where the -registers of the PREVIOUS frame are stored in this stack frame. In -this example the frame pointer of the PREVIOUS frame is stored at -offset 0 from the stack pointer of THIS frame. - -@cindex unwinding -@cindex stack frame, definition of unwinding -@cindex frame, definition of unwinding -The process whereby a function is given a pointer to the NEXT -frame to work out information about THIS frame is referred to as -@dfn{unwinding}. The @value{GDBN} functions involved in this typically -include unwind in their name. - -@cindex sniffing -@cindex stack frame, definition of sniffing -@cindex frame, definition of sniffing -The process of analyzing a target to determine the information that -should go in struct frame_info is called @dfn{sniffing}. The functions -that carry this out are called sniffers and typically include sniffer -in their name. More than one sniffer may be required to extract all -the information for a particular frame. - -@cindex sentinel frame -@cindex stack frame, definition of sentinel frame -@cindex frame, definition of sentinel frame -Because so many functions work using the NEXT frame, there is an issue -about addressing the innermost frame---it has no NEXT frame. To solve -this @value{GDBN} creates a dummy frame #-1, known as the -@dfn{sentinel} frame. - -@node Prologue Caches -@subsection Prologue Caches - -@cindex function prologue -@cindex prologue of a function -All the frame sniffing functions typically examine the code at the -start of the corresponding function, to determine the state of -registers. The ABI will save old values and set new values of key -registers at the start of each function in what is known as the -function @dfn{prologue}. - -@cindex prologue cache -For any particular stack frame this data does not change, so all the -standard unwinding functions, in addition to receiving a pointer to -the NEXT frame as their first argument, receive a pointer to a -@dfn{prologue cache} as their second argument. This can be used to store -values associated with a particular frame, for reuse on subsequent -calls involving the same frame. - -It is up to the user to define the structure used (it is a -@code{void@w{ }*} pointer) and arrange allocation and deallocation of -storage. However for general use, @value{GDBN} provides -@code{@w{struct trad_frame_cache}}, with a set of accessor -routines. This structure holds the stack and code address of -THIS frame, the base address of the frame, a pointer to the -struct @code{frame_info} for the NEXT frame and details of -where the registers of the PREVIOUS frame may be found in THIS -frame. - -Typically the first time any sniffer function is called with NEXT -frame, the prologue sniffer for THIS frame will be @code{NULL}. The -sniffer will analyze the frame, allocate a prologue cache structure -and populate it. Subsequent calls using the same NEXT frame will -pass in this prologue cache, so the data can be returned with no -additional analysis. - -@node Functions and Variable to Analyze Frames -@subsection Functions and Variable to Analyze Frames - -These struct @code{gdbarch} functions and variable should be defined -to provide analysis of the stack frame and allow it to be adjusted as -required. - -@deftypefn {Architecture Function} CORE_ADDR skip_prologue (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{pc}) - -The prologue of a function is the code at the beginning of the -function which sets up the stack frame, saves the return address -etc. The code representing the behavior of the function starts after -the prologue. - -This function skips past the prologue of a function if the program -counter, @var{pc}, is within the prologue of a function. The result is -the program counter immediately after the prologue. With modern -optimizing compilers, this may be a far from trivial exercise. However -the required information may be within the binary as DWARF2 debugging -information, making the job much easier. - -The default value is @code{NULL} (not defined). This function should always -be provided, but can take advantage of DWARF2 debugging information, -if that is available. - -@end deftypefn - -@deftypefn {Architecture Function} int inner_than (CORE_ADDR @var{lhs}, CORE_ADDR @var{rhs}) -@findex core_addr_lessthan -@findex core_addr_greaterthan - -Given two frame or stack pointers, return non-zero (true) if the first -represents the @dfn{inner} stack frame and 0 (false) otherwise. This -is used to determine whether the target has a stack which grows up in -memory (rising stack) or grows down in memory (falling stack). -@xref{All About Stack Frames, , All About Stack Frames}, for an -explanation of @dfn{inner} frames. - -The default value of this function is @code{NULL} and it should always -be defined. However for almost all architectures one of the built-in -functions can be used: @code{core_addr_lessthan} (for stacks growing -down in memory) or @code{core_addr_greaterthan} (for stacks growing up -in memory). - -@end deftypefn - -@anchor{frame_align} -@deftypefn {Architecture Function} CORE_ADDR frame_align (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address}) -@findex align_down -@findex align_up - -The architecture may have constraints on how its frames are -aligned. For example the OpenRISC 1000 ABI requires stack frames to be -double-word aligned, but 32-bit versions of the architecture allocate -single-word values to the stack. Thus extra padding may be needed at -the end of a stack frame. - -Given a proposed address for the stack pointer, this function -returns a suitably aligned address (by expanding the stack frame). - -The default value is @code{NULL} (undefined). This function should be defined -for any architecture where it is possible the stack could become -misaligned. The utility functions @code{align_down} (for falling -stacks) and @code{align_up} (for rising stacks) will facilitate the -implementation of this function. - -@end deftypefn - -@deftypevr {Architecture Variable} int frame_red_zone_size - -Some ABIs reserve space beyond the end of the stack for use by leaf -functions without prologue or epilogue or by exception handlers (for -example the OpenRISC 1000). - -This is known as a @dfn{red zone} (AMD terminology). The @sc{amd64} -(nee x86-64) ABI documentation refers to the @dfn{red zone} when -describing this scratch area. - -The default value is 0. Set this field if the architecture has such a -red zone. The value must be aligned as required by the ABI (see -@code{frame_align} above for an explanation of stack frame alignment). - -@end deftypevr - -@node Functions to Access Frame Data -@subsection Functions to Access Frame Data - -These functions provide access to key registers and arguments in the -stack frame. - -@deftypefn {Architecture Function} CORE_ADDR unwind_pc (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) - -This function is given a pointer to the NEXT stack frame (@pxref{All -About Stack Frames, , All About Stack Frames}, for how frames are -represented) and returns the value of the program counter in the -PREVIOUS frame (i.e.@: the frame of the function that called THIS -one). This is commonly referred to as the @dfn{return address}. - -The implementation, which must be frame agnostic (work with any frame), -is typically no more than: - -@smallexample -ULONGEST pc; -pc = frame_unwind_register_unsigned (next_frame, @var{ARCH}_PC_REGNUM); -return gdbarch_addr_bits_remove (gdbarch, pc); -@end smallexample - -@end deftypefn - -@deftypefn {Architecture Function} CORE_ADDR unwind_sp (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) - -This function is given a pointer to the NEXT stack frame -(@pxref{All About Stack Frames, , All About Stack Frames} for how -frames are represented) and returns the value of the stack pointer in -the PREVIOUS frame (i.e.@: the frame of the function that called -THIS one). - -The implementation, which must be frame agnostic (work with any frame), -is typically no more than: - -@smallexample -ULONGEST sp; -sp = frame_unwind_register_unsigned (next_frame, @var{ARCH}_SP_REGNUM); -return gdbarch_addr_bits_remove (gdbarch, sp); -@end smallexample - -@end deftypefn - -@deftypefn {Architecture Function} int frame_num_args (struct gdbarch *@var{gdbarch}, struct frame_info *@var{this_frame}) - -This function is given a pointer to THIS stack frame (@pxref{All -About Stack Frames, , All About Stack Frames} for how frames are -represented), and returns the number of arguments that are being -passed, or -1 if not known. - -The default value is @code{NULL} (undefined), in which case the number of -arguments passed on any stack frame is always unknown. For many -architectures this will be a suitable default. - -@end deftypefn - -@node Analyzing Stacks---Frame Sniffers -@subsection Analyzing Stacks---Frame Sniffers - -When a program stops, @value{GDBN} needs to construct the chain of -struct @code{frame_info} representing the state of the stack using -appropriate @dfn{sniffers}. - -Each architecture requires appropriate sniffers, but they do not form -entries in @code{@w{struct gdbarch}}, since more than one sniffer may -be required and a sniffer may be suitable for more than one -@code{@w{struct gdbarch}}. Instead sniffers are associated with -architectures using the following functions. - -@itemize @bullet - -@item -@findex frame_unwind_append_sniffer -@code{frame_unwind_append_sniffer} is used to add a new sniffer to -analyze THIS frame when given a pointer to the NEXT frame. - -@item -@findex frame_base_append_sniffer -@code{frame_base_append_sniffer} is used to add a new sniffer -which can determine information about the base of a stack frame. - -@item -@findex frame_base_set_default -@code{frame_base_set_default} is used to specify the default base -sniffer. - -@end itemize - -These functions all take a reference to @code{@w{struct gdbarch}}, so -they are associated with a specific architecture. They are usually -called in the @code{gdbarch} initialization function, after the -@code{gdbarch} struct has been set up. Unless a default has been set, the -most recently appended sniffer will be tried first. - -The main frame unwinding sniffer (as set by -@code{frame_unwind_append_sniffer)} returns a structure specifying -a set of sniffing functions: - -@cindex @code{frame_unwind} -@smallexample -struct frame_unwind -@{ - enum frame_type type; - frame_this_id_ftype *this_id; - frame_prev_register_ftype *prev_register; - const struct frame_data *unwind_data; - frame_sniffer_ftype *sniffer; - frame_prev_pc_ftype *prev_pc; - frame_dealloc_cache_ftype *dealloc_cache; -@}; -@end smallexample - -The @code{type} field indicates the type of frame this sniffer can -handle: normal, dummy (@pxref{Functions Creating Dummy Frames, , -Functions Creating Dummy Frames}), signal handler or sentinel. Signal -handlers sometimes have their own simplified stack structure for -efficiency, so may need their own handlers. - -The @code{unwind_data} field holds additional information which may be -relevant to particular types of frame. For example it may hold -additional information for signal handler frames. - -The remaining fields define functions that yield different types of -information when given a pointer to the NEXT stack frame. Not all -functions need be provided. If an entry is @code{NULL}, the next sniffer will -be tried instead. - -@itemize @bullet - -@item -@code{this_id} determines the stack pointer and function (code -entry point) for THIS stack frame. - -@item -@code{prev_register} determines where the values of registers for -the PREVIOUS stack frame are stored in THIS stack frame. - -@item -@code{sniffer} takes a look at THIS frame's registers to -determine if this is the appropriate unwinder. - -@item -@code{prev_pc} determines the program counter for THIS -frame. Only needed if the program counter is not an ordinary register -(@pxref{Register Architecture Functions & Variables, -, Functions and Variables Specifying the Register Architecture}). - -@item -@code{dealloc_cache} frees any additional memory associated with -the prologue cache for this frame (@pxref{Prologue Caches, , Prologue -Caches}). - -@end itemize - -In general it is only the @code{this_id} and @code{prev_register} -fields that need be defined for custom sniffers. - -The frame base sniffer is much simpler. It is a @code{@w{struct -frame_base}}, which refers to the corresponding @code{frame_unwind} -struct and whose fields refer to functions yielding various addresses -within the frame. - -@cindex @code{frame_base} -@smallexample -struct frame_base -@{ - const struct frame_unwind *unwind; - frame_this_base_ftype *this_base; - frame_this_locals_ftype *this_locals; - frame_this_args_ftype *this_args; -@}; -@end smallexample - -All the functions referred to take a pointer to the NEXT frame as -argument. The function referred to by @code{this_base} returns the -base address of THIS frame, the function referred to by -@code{this_locals} returns the base address of local variables in THIS -frame and the function referred to by @code{this_args} returns the -base address of the function arguments in this frame. - -As described above, the base address of a frame is the address -immediately before the start of the NEXT frame. For a falling -stack, this is the lowest address in the frame and for a rising stack -it is the highest address in the frame. For most architectures the -same address is also the base address for local variables and -arguments, in which case the same function can be used for all three -entries@footnote{It is worth noting that if it cannot be determined in any -other way (for example by there being a register with the name -@code{"fp"}), then the result of the @code{this_base} function will be -used as the value of the frame pointer variable @kbd{$fp} in -@value{GDBN}. This is very often not correct (for example with the -OpenRISC 1000, this value is the stack pointer, @kbd{$sp}). In this -case a register (raw or pseudo) with the name @code{"fp"} should be -defined. It will be used in preference as the value of @kbd{$fp}.}. - -@node Inferior Call Setup -@section Inferior Call Setup -@cindex calls to the inferior - -@menu -* About Dummy Frames:: -* Functions Creating Dummy Frames:: -@end menu - -@node About Dummy Frames -@subsection About Dummy Frames -@cindex dummy frames - -@value{GDBN} can call functions in the target code (for example by -using the @kbd{call} or @kbd{print} commands). These functions may be -breakpointed, and it is essential that if a function does hit a -breakpoint, commands like @kbd{backtrace} work correctly. - -This is achieved by making the stack look as though the function had -been called from the point where @value{GDBN} had previously stopped. -This requires that @value{GDBN} can set up stack frames appropriate for -such function calls. - -@node Functions Creating Dummy Frames -@subsection Functions Creating Dummy Frames - -The following functions provide the functionality to set up such -@dfn{dummy} stack frames. - -@deftypefn {Architecture Function} CORE_ADDR push_dummy_call (struct gdbarch *@var{gdbarch}, struct value *@var{function}, struct regcache *@var{regcache}, CORE_ADDR @var{bp_addr}, int @var{nargs}, struct value **@var{args}, CORE_ADDR @var{sp}, int @var{struct_return}, CORE_ADDR @var{struct_addr}) - -This function sets up a dummy stack frame for the function about to be -called. @code{push_dummy_call} is given the arguments to be passed -and must copy them into registers or push them on to the stack as -appropriate for the ABI. - -@var{function} is a pointer to the function -that will be called and @var{regcache} the register cache from which -values should be obtained. @var{bp_addr} is the address to which the -function should return (which is breakpointed, so @value{GDBN} can -regain control, hence the name). @var{nargs} is the number of -arguments to pass and @var{args} an array containing the argument -values. @var{struct_return} is non-zero (true) if the function returns -a structure, and if so @var{struct_addr} is the address in which the -structure should be returned. - - After calling this function, @value{GDBN} will pass control to the -target at the address of the function, which will find the stack and -registers set up just as expected. - -The default value of this function is @code{NULL} (undefined). If the -function is not defined, then @value{GDBN} will not allow the user to -call functions within the target being debugged. - -@end deftypefn - -@deftypefn {Architecture Function} {struct frame_id} unwind_dummy_id (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) - -This is the inverse of @code{push_dummy_call} which restores the stack -pointer and program counter after a call to evaluate a function using -a dummy stack frame. The result is a @code{@w{struct frame_id}}, which -contains the value of the stack pointer and program counter to be -used. - -The NEXT frame pointer is provided as argument, -@var{next_frame}. THIS frame is the frame of the dummy function, -which can be unwound, to yield the required stack pointer and program -counter from the PREVIOUS frame. - -The default value is @code{NULL} (undefined). If @code{push_dummy_call} is -defined, then this function should also be defined. - -@end deftypefn - -@deftypefn {Architecture Function} CORE_ADDR push_dummy_code (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{sp}, CORE_ADDR @var{funaddr}, struct value **@var{args}, int @var{nargs}, struct type *@var{value_type}, CORE_ADDR *@var{real_pc}, CORE_ADDR *@var{bp_addr}, struct regcache *@var{regcache}) - -If this function is not defined (its default value is @code{NULL}), a dummy -call will use the entry point of the currently loaded code on the -target as its return address. A temporary breakpoint will be set -there, so the location must be writable and have room for a -breakpoint. - -It is possible that this default is not suitable. It might not be -writable (in ROM possibly), or the ABI might require code to be -executed on return from a call to unwind the stack before the -breakpoint is encountered. - -If either of these is the case, then push_dummy_code should be defined -to push an instruction sequence onto the end of the stack to which the -dummy call should return. - -The arguments are essentially the same as those to -@code{push_dummy_call}. However the function is provided with the -type of the function result, @var{value_type}, @var{bp_addr} is used -to return a value (the address at which the breakpoint instruction -should be inserted) and @var{real pc} is used to specify the resume -address when starting the call sequence. The function should return -the updated innermost stack address. - -@quotation -@emph{Note:} This does require that code in the stack can be executed. -Some Harvard architectures may not allow this. -@end quotation - -@end deftypefn - -@node Adding support for debugging core files -@section Adding support for debugging core files -@cindex core files - -The prerequisite for adding core file support in @value{GDBN} is to have -core file support in BFD. - -Once BFD support is available, writing the apropriate -@code{regset_from_core_section} architecture function should be all -that is needed in order to add support for core files in @value{GDBN}. - -@node Defining Other Architecture Features -@section Defining Other Architecture Features - -This section describes other functions and values in @code{gdbarch}, -together with some useful macros, that you can use to define the -target architecture. - -@table @code - -@item CORE_ADDR gdbarch_addr_bits_remove (@var{gdbarch}, @var{addr}) -@findex gdbarch_addr_bits_remove -If a raw machine instruction address includes any bits that are not -really part of the address, then this function is used to zero 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. @code{gdbarch_addr_bits_remove} would then for -example look like that: -@smallexample -arch_addr_bits_remove (CORE_ADDR addr) -@{ - return (addr &= ~0x3); -@} -@end smallexample - -@item int address_class_name_to_type_flags (@var{gdbarch}, @var{name}, @var{type_flags_ptr}) -@findex address_class_name_to_type_flags -If @var{name} is a valid address class qualifier name, set the @code{int} -referenced by @var{type_flags_ptr} to the mask representing the qualifier -and return 1. If @var{name} is not a valid address class qualifier name, -return 0. - -The value for @var{type_flags_ptr} should be one of -@code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or -possibly some combination of these values or'd together. -@xref{Target Architecture Definition, , Address Classes}. - -@item int address_class_name_to_type_flags_p (@var{gdbarch}) -@findex address_class_name_to_type_flags_p -Predicate which indicates whether @code{address_class_name_to_type_flags} -has been defined. - -@item int gdbarch_address_class_type_flags (@var{gdbarch}, @var{byte_size}, @var{dwarf2_addr_class}) -@findex gdbarch_address_class_type_flags -Given a pointers byte size (as described by the debug information) and -the possible @code{DW_AT_address_class} value, return the type flags -used by @value{GDBN} to represent this address class. The value -returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1}, -@code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these -values or'd together. -@xref{Target Architecture Definition, , Address Classes}. - -@item int gdbarch_address_class_type_flags_p (@var{gdbarch}) -@findex gdbarch_address_class_type_flags_p -Predicate which indicates whether @code{gdbarch_address_class_type_flags_p} has -been defined. - -@item const char *gdbarch_address_class_type_flags_to_name (@var{gdbarch}, @var{type_flags}) -@findex gdbarch_address_class_type_flags_to_name -Return the name of the address class qualifier associated with the type -flags given by @var{type_flags}. - -@item int gdbarch_address_class_type_flags_to_name_p (@var{gdbarch}) -@findex gdbarch_address_class_type_flags_to_name_p -Predicate which indicates whether @code{gdbarch_address_class_type_flags_to_name} has been defined. -@xref{Target Architecture Definition, , Address Classes}. - -@item void gdbarch_address_to_pointer (@var{gdbarch}, @var{type}, @var{buf}, @var{addr}) -@findex gdbarch_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 function 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 int gdbarch_believe_pcc_promotion (@var{gdbarch}) -@findex gdbarch_believe_pcc_promotion -Used to notify 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 gdbarch_bits_big_endian (@var{gdbarch}) -@findex gdbarch_bits_big_endian -This is used if the numbering of bits in the targets does @strong{not} match -the endianism 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 set_gdbarch_bits_big_endian (@var{gdbarch}, @var{bits_big_endian}) -@findex set_gdbarch_bits_big_endian -Calling set_gdbarch_bits_big_endian with a value of 1 indicates that the -bits in the target are numbered in a big-endian bit order, 0 indicates -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{gdbarch_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{gdbarch_breakpoint_from_pc}. - -@item const gdb_byte *gdbarch_breakpoint_from_pc (@var{gdbarch}, @var{pcptr}, @var{lenptr}) -@findex gdbarch_breakpoint_from_pc -@anchor{gdbarch_breakpoint_from_pc} Use the program counter to determine the -contents and size of a breakpoint instruction. It returns a pointer to -a static string of bytes that encode a breakpoint instruction, stores the -length of the string to @code{*@var{lenptr}}, and adjusts the program -counter (if necessary) to point to the actual memory location where the -breakpoint should be inserted. On input, the program counter -(@code{*@var{pcptr}} is the encoded inferior's PC register. If software -breakpoints are supported, the function sets this argument to the PC's -plain address. If software breakpoints are not supported, the function -returns NULL instead of the encoded breakpoint instruction. - -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. - -Provided breakpoint bytes can be also used by @code{bp_loc_is_permanent} to -detect permanent breakpoints. @code{gdbarch_breakpoint_from_pc} should return -an unchanged memory copy if it was called for a location with permanent -breakpoint as some architectures use breakpoint instructions containing -arbitrary parameter value. - -Replaces all the other @var{BREAKPOINT} macros. - -@item int gdbarch_memory_insert_breakpoint (@var{gdbarch}, @var{bp_tgt}) -@itemx gdbarch_memory_remove_breakpoint (@var{gdbarch}, @var{bp_tgt}) -@findex gdbarch_memory_remove_breakpoint -@findex gdbarch_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 set these for most -architectures. Architectures which may want to set -@code{gdbarch_memory_insert_breakpoint} and @code{gdbarch_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{gdbarch_breakpoint_from_pc} needs to read the target's memory for some -reason. - -@item CORE_ADDR gdbarch_adjust_breakpoint_address (@var{gdbarch}, @var{bpaddr}) -@findex gdbarch_adjust_breakpoint_address -@cindex breakpoint address adjusted -Given an address at which a breakpoint is desired, return a breakpoint -address adjusted to account for architectural constraints on -breakpoint placement. This method is not needed by most targets. - -The FR-V target (see @file{frv-tdep.c}) requires this method. -The FR-V is a VLIW architecture in which a number of RISC-like -instructions are grouped (packed) together into an aggregate -instruction or instruction bundle. When the processor executes -one of these bundles, the component instructions are executed -in parallel. - -In the course of optimization, the compiler may group instructions -from distinct source statements into the same bundle. The line number -information associated with one of the latter statements will likely -refer to some instruction other than the first one in the bundle. So, -if the user attempts to place a breakpoint on one of these latter -statements, @value{GDBN} must be careful to @emph{not} place the break -instruction on any instruction other than the first one in the bundle. -(Remember though that the instructions within a bundle execute -in parallel, so the @emph{first} instruction is the instruction -at the lowest address and has nothing to do with execution order.) - -The FR-V's @code{gdbarch_adjust_breakpoint_address} method will adjust a -breakpoint's address by scanning backwards for the beginning of -the bundle, returning the address of the bundle. - -Since the adjustment of a breakpoint may significantly alter a user's -expectation, @value{GDBN} prints a warning when an adjusted breakpoint -is initially set and each time that that breakpoint is hit. - -@item int gdbarch_call_dummy_location (@var{gdbarch}) -@findex gdbarch_call_dummy_location -See the file @file{inferior.h}. - -This method has been replaced by @code{gdbarch_push_dummy_code} -(@pxref{gdbarch_push_dummy_code}). - -@item int gdbarch_cannot_fetch_register (@var{gdbarch}, @var{regum}) -@findex gdbarch_cannot_fetch_register -This function should return nonzero if @var{regno} cannot be fetched -from an inferior process. - -@item int gdbarch_cannot_store_register (@var{gdbarch}, @var{regnum}) -@findex gdbarch_cannot_store_register -This function should return 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. This function returns 0 as -default so that @value{GDBN} will assume that all registers may be written. - -@item int gdbarch_convert_register_p (@var{gdbarch}, @var{regnum}, struct type *@var{type}) -@findex gdbarch_convert_register_p -Return non-zero if register @var{regnum} represents data values of type -@var{type} in a non-standard form. -@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. - -@item int gdbarch_fp0_regnum (@var{gdbarch}) -@findex gdbarch_fp0_regnum -This function returns the number of the first floating point register, -if the machine has such registers. Otherwise, it returns -1. - -@item CORE_ADDR gdbarch_decr_pc_after_break (@var{gdbarch}) -@findex gdbarch_decr_pc_after_break -This function shall return 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 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 int gdbarch_dwarf2_reg_to_regnum (@var{gdbarch}, @var{dwarf2_regnr}) -@findex gdbarch_dwarf2_reg_to_regnum -Convert DWARF2 register number @var{dwarf2_regnr} into @value{GDBN} regnum. -If not defined, no conversion will be performed. - -@item int gdbarch_ecoff_reg_to_regnum (@var{gdbarch}, @var{ecoff_regnr}) -@findex gdbarch_ecoff_reg_to_regnum -Convert ECOFF register number @var{ecoff_regnr} into @value{GDBN} regnum. If -not defined, no conversion will be performed. - -@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 gdbarch_get_longjmp_target -@findex gdbarch_get_longjmp_target -This function 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, typically by using a manually-determined -offset into the @code{jmp_buf}. (While we might like to get the offset -from the target's @file{jmpbuf.h}, that header file cannot be assumed -to be available when building a cross-debugger.) - -@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 gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{addr}) -@findex gdbarch_in_function_epilogue_p -Returns non-zero if the given @var{addr} 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 int gdbarch_in_solib_return_trampoline (@var{gdbarch}, @var{pc}, @var{name}) -@findex gdbarch_in_solib_return_trampoline -Define this function to return nonzero if the program is stopped in the -trampoline that returns from a shared library. - -@item target_so_ops.in_dynsym_resolve_code (@var{pc}) -@findex in_dynsym_resolve_code -Define this to return 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 CORE_ADDR gdbarch_integer_to_address (@var{gdbarch}, @var{type}, @var{buf}) -@findex gdbarch_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{gdbarch_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 CORE_ADDR gdbarch_pointer_to_address (@var{gdbarch}, @var{type}, @var{buf}) -@findex gdbarch_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 void gdbarch_register_to_value(@var{gdbarch}, @var{frame}, @var{regnum}, @var{type}, @var{fur}) -@findex gdbarch_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_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 const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size}) -@findex regset_from_core_section -Return the appropriate register set for a core file section with name -@var{sect_name} and size @var{sect_size}. - -@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_breakpoints_p}) -@findex SOFTWARE_SINGLE_STEP -A function that inserts or removes (depending on -@var{insert_breakpoints_p}) breakpoints at each possible destinations of -the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c} -for examples. - -@item set_gdbarch_sofun_address_maybe_missing (@var{gdbarch}, @var{set}) -@findex set_gdbarch_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. - -Calling @code{set_gdbarch_sofun_address_maybe_missing} with a non-zero -argument @var{set} 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. - -In this case, @value{GDBN} assumes two things: - -@itemize @bullet -@item -@code{N_FUN} stabs have an address of zero. Instead of using those -addresses, you should find the address 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 int gdbarch_stabs_argument_has_addr (@var{gdbarch}, @var{type}) -@findex gdbarch_stabs_argument_has_addr -@anchor{gdbarch_stabs_argument_has_addr} Define this function to return -nonzero if a function argument of type @var{type} is passed by reference -instead of value. - -@item CORE_ADDR gdbarch_push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{bp_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) -@findex gdbarch_push_dummy_call -@anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to -the inferior function onto the stack. In addition to pushing @var{nargs}, the -code should push @var{struct_addr} (when @var{struct_return} is non-zero), and -the return address (@var{bp_addr}, in inferior's PC register encoding). - -@var{function} is a pointer to a @code{struct value}; on architectures that use -function descriptors, this contains the function descriptor value. - -Returns the updated top-of-stack pointer. - -@item CORE_ADDR gdbarch_push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr}, @var{regcache}) -@findex gdbarch_push_dummy_code -@anchor{gdbarch_push_dummy_code} Given a stack based call dummy, push the -instruction sequence (including space for a breakpoint) to which the -called function should return. - -Set @var{bp_addr} to the address at which the breakpoint instruction -should be inserted (in inferior's PC register encoding), @var{real_pc} to the -resume address when starting the call sequence, and return the updated -inner-most stack address. - -By default, the stack is grown sufficient to hold a frame-aligned -(@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address -reserved for that breakpoint (in inferior's PC register encoding), and -@var{real_pc} set to @var{funaddr}. - -This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}}. - -@item int gdbarch_sdb_reg_to_regnum (@var{gdbarch}, @var{sdb_regnr}) -@findex gdbarch_sdb_reg_to_regnum -Use this function to convert sdb register @var{sdb_regnr} into @value{GDBN} -regnum. If not defined, no conversion will be done. - -@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf}) -@findex gdbarch_return_value -@anchor{gdbarch_return_value} Given a function with a return-value of -type @var{rettype}, return which return-value convention that function -would use. - -@value{GDBN} currently recognizes two function return-value conventions: -@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found -in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return -value is found in memory and the address of that memory location is -passed in as the function's first parameter. - -If the register convention is being used, and @var{writebuf} is -non-@code{NULL}, also copy the return-value in @var{writebuf} into -@var{regcache}. - -If the register convention is being used, and @var{readbuf} is -non-@code{NULL}, also copy the return value from @var{regcache} into -@var{readbuf} (@var{regcache} contains a copy of the registers from the -just returned function). - -@emph{Maintainer note: This method replaces separate predicate, extract, -store methods. By having only one method, the logic needed to determine -the return-value convention need only be implemented in one place. If -@value{GDBN} were written in an @sc{oo} language, this method would -instead return an object that knew how to perform the register -return-value extract and store.} - -@emph{Maintainer note: This method does not take a @var{gcc_p} -parameter, and such a parameter should not be added. If an architecture -that requires per-compiler or per-function information be identified, -then the replacement of @var{rettype} with @code{struct value} -@var{function} should be pursued.} - -@emph{Maintainer note: The @var{regcache} parameter limits this methods -to the inner most frame. While replacing @var{regcache} with a -@code{struct frame_info} @var{frame} parameter would remove that -limitation there has yet to be a demonstrated need for such a change.} - -@item void gdbarch_skip_permanent_breakpoint (@var{gdbarch}, @var{regcache}) -@findex gdbarch_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{gdbarch_skip_permanent_breakpoint} adjusts the -processor's state so that execution will resume just after the breakpoint. -This function does the right thing even when the breakpoint is in the delay slot -of a branch or jump. - -@item CORE_ADDR gdbarch_skip_trampoline_code (@var{gdbarch}, @var{frame}, @var{pc}) -@findex gdbarch_skip_trampoline_code -If the target machine has trampoline code that sits between callers and -the functions being called, then define this function to return a new PC -that is at the start of the real function. - -@item int gdbarch_deprecated_fp_regnum (@var{gdbarch}) -@findex gdbarch_deprecated_fp_regnum -If the frame pointer is in a register, use this function to return the -number of that register. - -@item int gdbarch_stab_reg_to_regnum (@var{gdbarch}, @var{stab_regnr}) -@findex gdbarch_stab_reg_to_regnum -Use this function to convert stab register @var{stab_regnr} into @value{GDBN} -regnum. If not defined, no conversion will be done. - -@item TARGET_CHAR_BIT -@findex TARGET_CHAR_BIT -Number of bits in a char; defaults to 8. - -@item int gdbarch_char_signed (@var{gdbarch}) -@findex gdbarch_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 int gdbarch_double_bit (@var{gdbarch}) -@findex gdbarch_double_bit -Number of bits in a double float; defaults to @w{@code{8 * TARGET_CHAR_BIT}}. - -@item int gdbarch_float_bit (@var{gdbarch}) -@findex gdbarch_float_bit -Number of bits in a float; defaults to @w{@code{4 * TARGET_CHAR_BIT}}. - -@item int gdbarch_int_bit (@var{gdbarch}) -@findex gdbarch_int_bit -Number of bits in an integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}. - -@item int gdbarch_long_bit (@var{gdbarch}) -@findex gdbarch_long_bit -Number of bits in a long integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}. - -@item int gdbarch_long_double_bit (@var{gdbarch}) -@findex gdbarch_long_double_bit -Number of bits in a long double float; -defaults to @w{@code{2 * gdbarch_double_bit (@var{gdbarch})}}. - -@item int gdbarch_long_long_bit (@var{gdbarch}) -@findex gdbarch_long_long_bit -Number of bits in a long long integer; defaults to -@w{@code{2 * gdbarch_long_bit (@var{gdbarch})}}. - -@item int gdbarch_ptr_bit (@var{gdbarch}) -@findex gdbarch_ptr_bit -Number of bits in a pointer; defaults to -@w{@code{gdbarch_int_bit (@var{gdbarch})}}. - -@item int gdbarch_short_bit (@var{gdbarch}) -@findex gdbarch_short_bit -Number of bits in a short integer; defaults to @w{@code{2 * TARGET_CHAR_BIT}}. - -@item void gdbarch_virtual_frame_pointer (@var{gdbarch}, @var{pc}, @var{frame_regnum}, @var{frame_offset}) -@findex gdbarch_virtual_frame_pointer -Returns a @code{(@var{register}, @var{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{gdbarch_deprecated_fp_regnum} (or @code{gdbarch_sp_regnum}, if -no frame pointer is defined), with an offset of zero. - -@c need to explain virtual frame pointers, they are recorded in agent -@c expressions for tracepoints - -@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 int gdbarch_print_insn (@var{gdbarch}, @var{vma}, @var{info}) -@findex gdbarch_print_insn -This is the function used by @value{GDBN} to print an assembly -instruction. It prints the instruction at address @var{vma} in -debugged memory and returns the length of the instruction, in bytes. -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 the header file -@file{include/dis-asm.h}, and used to pass information to the -instruction decoding routine. - -@item frame_id gdbarch_dummy_id (@var{gdbarch}, @var{frame}) -@findex gdbarch_dummy_id -@anchor{gdbarch_dummy_id} Given @var{frame} return a @w{@code{struct -frame_id}} that uniquely identifies an inferior function call's dummy -frame. The value returned must match the dummy frame stack value -previously saved by @code{call_function_by_hand}. - -@item void gdbarch_value_to_register (@var{gdbarch}, @var{frame}, @var{type}, @var{buf}) -@findex gdbarch_value_to_register -Convert a value of type @var{type} into the raw contents of a register. -@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. - -@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 - -@node Adding a New Target -@section Adding a New Target - -@cindex adding a target -The following files add a target to @value{GDBN}: - -@table @file -@cindex target dependent files - -@item gdb/@var{ttt}-tdep.c -Contains any miscellaneous code required for this target machine. On -some machines it doesn't exist at all. - -@item gdb/@var{arch}-tdep.c -@itemx gdb/@var{arch}-tdep.h -This is required to describe the basic layout of the target machine's -processor chip (registers, stack, etc.). It can be shared among many -targets that use the same processor architecture. - -@end table - -(Target header files such as -@file{gdb/config/@var{arch}/tm-@var{ttt}.h}, -@file{gdb/config/@var{arch}/tm-@var{arch}.h}, and -@file{config/tm-@var{os}.h} are no longer used.) - -@findex _initialize_@var{arch}_tdep -A @value{GDBN} description for a new architecture, arch is created by -defining a global function @code{_initialize_@var{arch}_tdep}, by -convention in the source file @file{@var{arch}-tdep.c}. For -example, in the case of the OpenRISC 1000, this function is called -@code{_initialize_or1k_tdep} and is found in the file -@file{or1k-tdep.c}. - -The object file resulting from compiling this source file, which will -contain the implementation of the -@code{_initialize_@var{arch}_tdep} function is specified in the -@value{GDBN} @file{configure.tgt} file, which includes a large case -statement pattern matching against the @code{--target} option of the -@kbd{configure} script. - -@quotation -@emph{Note:} If the architecture requires multiple source files, the -corresponding binaries should be included in -@file{configure.tgt}. However if there are header files, the -dependencies on these will not be picked up from the entries in -@file{configure.tgt}. The @file{Makefile.in} file will need extending to -show these dependencies. -@end quotation - -@findex gdbarch_register -A new struct gdbarch, defining the new architecture, is created within -the @code{_initialize_@var{arch}_tdep} function by calling -@code{gdbarch_register}: - -@smallexample -void gdbarch_register (enum bfd_architecture architecture, - gdbarch_init_ftype *init_func, - gdbarch_dump_tdep_ftype *tdep_dump_func); -@end smallexample - -This function has been described fully in an earlier -section. @xref{How an Architecture is Represented, , How an -Architecture is Represented}. - -The new @code{@w{struct gdbarch}} should contain implementations of -the necessary functions (described in the previous sections) to -describe the basic layout of the target machine's processor chip -(registers, stack, etc.). It can be shared among many targets that use -the same processor architecture. - -@node Target Descriptions -@chapter Target Descriptions -@cindex target descriptions - -The target architecture definition (@pxref{Target Architecture Definition}) -contains @value{GDBN}'s hard-coded knowledge about an architecture. For -some platforms, it is handy to have more flexible knowledge about a specific -instance of the architecture---for instance, a processor or development board. -@dfn{Target descriptions} provide a mechanism for the user to tell @value{GDBN} -more about what their target supports, or for the target to tell @value{GDBN} -directly. - -For details on writing, automatically supplying, and manually selecting -target descriptions, see @ref{Target Descriptions, , , gdb, -Debugging with @value{GDBN}}. This section will cover some related -topics about the @value{GDBN} internals. - -@menu -* Target Descriptions Implementation:: -* Adding Target Described Register Support:: -@end menu - -@node Target Descriptions Implementation -@section Target Descriptions Implementation -@cindex target descriptions, implementation - -Before @value{GDBN} connects to a new target, or runs a new program on -an existing target, it discards any existing target description and -reverts to a default gdbarch. Then, after connecting, it looks for a -new target description by calling @code{target_find_description}. - -A description may come from a user specified file (XML), the remote -@samp{qXfer:features:read} packet (also XML), or from any custom -@code{to_read_description} routine in the target vector. For instance, -the remote target supports guessing whether a MIPS target is 32-bit or -64-bit based on the size of the @samp{g} packet. - -If any target description is found, @value{GDBN} creates a new gdbarch -incorporating the description by calling @code{gdbarch_update_p}. Any -@samp{<architecture>} element is handled first, to determine which -architecture's gdbarch initialization routine is called to create the -new architecture. Then the initialization routine is called, and has -a chance to adjust the constructed architecture based on the contents -of the target description. For instance, it can recognize any -properties set by a @code{to_read_description} routine. Also -see @ref{Adding Target Described Register Support}. - -@node Adding Target Described Register Support -@section Adding Target Described Register Support -@cindex target descriptions, adding register support - -Target descriptions can report additional registers specific to an -instance of the target. But it takes a little work in the architecture -specific routines to support this. - -A target description must either have no registers or a complete -set---this avoids complexity in trying to merge standard registers -with the target defined registers. It is the architecture's -responsibility to validate that a description with registers has -everything it needs. To keep architecture code simple, the same -mechanism is used to assign fixed internal register numbers to -standard registers. - -If @code{tdesc_has_registers} returns 1, the description contains -registers. The architecture's @code{gdbarch_init} routine should: - -@itemize @bullet - -@item -Call @code{tdesc_data_alloc} to allocate storage, early, before -searching for a matching gdbarch or allocating a new one. - -@item -Use @code{tdesc_find_feature} to locate standard features by name. - -@item -Use @code{tdesc_numbered_register} and @code{tdesc_numbered_register_choices} -to locate the expected registers in the standard features. - -@item -Return @code{NULL} if a required feature is missing, or if any standard -feature is missing expected registers. This will produce a warning that -the description was incomplete. - -@item -Free the allocated data before returning, unless @code{tdesc_use_registers} -is called. - -@item -Call @code{set_gdbarch_num_regs} as usual, with a number higher than any -fixed number passed to @code{tdesc_numbered_register}. - -@item -Call @code{tdesc_use_registers} after creating a new gdbarch, before -returning it. - -@end itemize - -After @code{tdesc_use_registers} has been called, the architecture's -@code{register_name}, @code{register_type}, and @code{register_reggroup_p} -routines will not be called; that information will be taken from -the target description. @code{num_regs} may be increased to account -for any additional registers in the description. - -Pseudo-registers require some extra care: - -@itemize @bullet - -@item -Using @code{tdesc_numbered_register} allows the architecture to give -constant register numbers to standard architectural registers, e.g.@: -as an @code{enum} in @file{@var{arch}-tdep.h}. But because -pseudo-registers are always numbered above @code{num_regs}, -which may be increased by the description, constant numbers -can not be used for pseudos. They must be numbered relative to -@code{num_regs} instead. - -@item -The description will not describe pseudo-registers, so the -architecture must call @code{set_tdesc_pseudo_register_name}, -@code{set_tdesc_pseudo_register_type}, and -@code{set_tdesc_pseudo_register_reggroup_p} to supply routines -describing pseudo registers. These routines will be passed -internal register numbers, so the same routines used for the -gdbarch equivalents are usually suitable. - -@end itemize - - -@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. - -@menu -* Managing Execution State:: -* Existing Targets:: -@end menu - -@node Managing Execution State -@section Managing Execution State -@cindex execution state - -A target vector can be completely inactive (not pushed on the target -stack), active but not running (pushed, but not connected to a fully -manifested inferior), or completely active (pushed, with an accessible -inferior). Most targets are only completely inactive or completely -active, but some support persistent connections to a target even -when the target has exited or not yet started. - -For example, connecting to the simulator using @code{target sim} does -not create a running program. Neither registers nor memory are -accessible until @code{run}. Similarly, after @code{kill}, the -program can not continue executing. But in both cases @value{GDBN} -remains connected to the simulator, and target-specific commands -are directed to the simulator. - -A target which only supports complete activation should push itself -onto the stack in its @code{to_open} routine (by calling -@code{push_target}), and unpush itself from the stack in its -@code{to_mourn_inferior} routine (by calling @code{unpush_target}). - -A target which supports both partial and complete activation should -still call @code{push_target} in @code{to_open}, but not call -@code{unpush_target} in @code{to_mourn_inferior}. Instead, it should -call either @code{target_mark_running} or @code{target_mark_exited} -in its @code{to_open}, depending on whether the target is fully active -after connection. It should also call @code{target_mark_running} any -time the inferior becomes fully active (e.g.@: in -@code{to_create_inferior} and @code{to_attach}), and -@code{target_mark_exited} when the inferior becomes inactive (in -@code{to_mourn_inferior}). The target should also make sure to call -@code{target_mourn_inferior} from its @code{to_kill}, to return the -target to inactive state. - -@node Existing Targets -@section Existing Targets -@cindex targets - -@subsection File Targets - -Both executables and core files have target vectors. - -@subsection 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{@var{cpu}-stub.c}. Many -operating systems, embedded targets, emulators, and simulators already -have a @value{GDBN} stub built into them, and maintenance of the remote -protocol must be careful to preserve compatibility. - -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}. - -@subsection ROM Monitor Interface - -@subsection Custom Protocols - -@subsection Transport Layer - -@subsection 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}, @samp{NAT_GENERATED_FILES}, 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 ptrace - -@section /proc - -@section win32 - -@section shared libraries - -@subsection AIX Shared Library Support - -Shared library support on AIX is based on reading some data provided -by the loader. With a live process, this information is accessed -via a @code{ptrace} call (@code{PT_LDINFO}), while it is obtained -by reading the @samp{.ldinfo} section when debugging from a core file. -In both cases, the data has the same format, provided by the -@file{sys/ldr.h} system header file. - -Internally, the relevant portions of the loader information is -transformed into an XML representation, which lists all objects -currently mapped in memory. The associated DTD can be found in -@file{gdb/features/library-list-aix.dtd}. For each library element, -the following parameters are reported: - -@itemize @minus - -@item -@code{name}, the path name of an object. This is usually the name -of an archive, or the name of the main executable. - -@item -If the @code{name} parameter refers to an archive, @code{member} provides -the name of the object inside the archive on which the program depends. -Otherwise, this field should be omitted. - -@item -@code{text_addr}, the address where the @code{.text} section was mapped -in memory. - -@item -@code{text_size}, the size of the @code{.text} section. - -@item -@code{data_addr}, the address where the @code{.data} section was mapped -in memory. - -@item -@code{data_size}, the size of the @code{.data} section. - -@end itemize - -By convention, the library list always has at least one element, and -the first entry always refers to the main executable. - -Below is an example of such XML representation for a small program: - -@smallexample -<library-list-aix version="1.0"> - <library name="simple" - text_addr="0x0000000010000000" - text_size="128720" - data_addr="0x0000000020000f00" - data_size="31148"> - </library> - <library name="/lib/libc.a" - member="shr.o" - text_addr="0x00000000d0100700" - text_size="4152684" - data_addr="0x00000000f0633e50" - data_size="875944"> - </library> -</library-list-aix> -@end smallexample - -In that example, the list shows that the main executable is named -@file{simple}, and its text section was loaded at 0x10000000. -This program depends on member @file{shr.o} from the @file{/lib/libc.a} -archive, whose text and data sections were loaded at (resp.) -0xd0100700 and 0xf0633e50. - -@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 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 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. - -@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 -@cindex readline library -The @code{readline} library provides a set of functions for use by applications -that allow users to edit command lines as they are typed in. - -@section libiberty -@cindex @code{libiberty} library - -The @code{libiberty} library provides a set of functions and features -that integrate and improve on functionality found in modern operating -systems. Broadly speaking, such features can be divided into three -groups: supplemental functions (functions that may be missing in some -environments and operating systems), replacement functions (providing -a uniform and easier to use interface for commonly used standard -functions), and extensions (which provide additional functionality -beyond standard functions). - -@value{GDBN} uses various features provided by the @code{libiberty} -library, for instance the C@t{++} demangler, the @acronym{IEEE} -floating format support functions, the input options parser -@samp{getopt}, the @samp{obstack} extension, and other functions. - -@subsection @code{obstacks} in @value{GDBN} -@cindex @code{obstacks} - -The obstack mechanism provides a convenient way to allocate and free -chunks of memory. Each obstack is a pool of memory that is managed -like a stack. Objects (of any nature, size and alignment) are -allocated and freed in a @acronym{LIFO} fashion on an obstack (see -@code{libiberty}'s documentation for a more detailed explanation of -@code{obstacks}). - -The most noticeable use of the @code{obstacks} in @value{GDBN} is in -object files. There is an obstack associated with each internal -representation of an object file. Lots of things get allocated on -these @code{obstacks}: dictionary entries, blocks, blockvectors, -symbols, minimal symbols, types, vectors of fundamental types, class -fields of types, object files section lists, object files section -offset lists, line tables, symbol tables, partial symbol tables, -string tables, symbol table private data, macros tables, debug -information sections and entries, import and export lists (som), -unwind information (hppa), dwarf2 location expressions data. Plus -various strings such as directory names strings, debug format strings, -names of types. - -An essential and convenient property of all data on @code{obstacks} is -that memory for it gets allocated (with @code{obstack_alloc}) at -various times during a debugging session, but it is released all at -once using the @code{obstack_free} function. The @code{obstack_free} -function takes a pointer to where in the stack it must start the -deletion from (much like the cleanup chains have a pointer to where to -start the cleanups). Because of the stack like structure of the -@code{obstacks}, this allows to free only a top portion of the -obstack. There are a few instances in @value{GDBN} where such thing -happens. Calls to @code{obstack_free} are done after some local data -is allocated to the obstack. Only the local data is deleted from the -obstack. Of course this assumes that nothing between the -@code{obstack_alloc} and the @code{obstack_free} allocates anything -else on the same obstack. For this reason it is best and safest to -use temporary @code{obstacks}. - -Releasing the whole obstack is also not safe per se. It is safe only -under the condition that we know the @code{obstacks} memory is no -longer needed. In @value{GDBN} we get rid of the @code{obstacks} only -when we get rid of the whole objfile(s), for instance upon reading a -new symbol file. - -@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 Array Containers -@cindex Array Containers -@cindex VEC - -Often it is necessary to manipulate a dynamic array of a set of -objects. C forces some bookkeeping on this, which can get cumbersome -and repetitive. The @file{vec.h} file contains macros for defining -and using a typesafe vector type. The functions defined will be -inlined when compiling, and so the abstraction cost should be zero. -Domain checks are added to detect programming errors. - -An example use would be an array of symbols or section information. -The array can be grown as symbols are read in (or preallocated), and -the accessor macros provided keep care of all the necessary -bookkeeping. Because the arrays are type safe, there is no danger of -accidentally mixing up the contents. Think of these as C++ templates, -but implemented in C. - -Because of the different behavior of structure objects, scalar objects -and of pointers, there are three flavors of vector, one for each of -these variants. Both the structure object and pointer variants pass -pointers to objects around --- in the former case the pointers are -stored into the vector and in the latter case the pointers are -dereferenced and the objects copied into the vector. The scalar -object variant is suitable for @code{int}-like objects, and the vector -elements are returned by value. - -There are both @code{index} and @code{iterate} accessors. The iterator -returns a boolean iteration condition and updates the iteration -variable passed by reference. Because the iterator will be inlined, -the address-of can be optimized away. - -The vectors are implemented using the trailing array idiom, thus they -are not resizeable without changing the address of the vector object -itself. This means you cannot have variables or fields of vector type ---- always use a pointer to a vector. The one exception is the final -field of a structure, which could be a vector type. You will have to -use the @code{embedded_size} & @code{embedded_init} calls to create -such objects, and they will probably not be resizeable (so don't use -the @dfn{safe} allocation variants). The trailing array idiom is used -(rather than a pointer to an array of data), because, if we allow -@code{NULL} to also represent an empty vector, empty vectors occupy -minimal space in the structure containing them. - -Each operation that increases the number of active elements is -available in @dfn{quick} and @dfn{safe} variants. The former presumes -that there is sufficient allocated space for the operation to succeed -(it dies if there is not). The latter will reallocate the vector, if -needed. Reallocation causes an exponential increase in vector size. -If you know you will be adding N elements, it would be more efficient -to use the reserve operation before adding the elements with the -@dfn{quick} operation. This will ensure there are at least as many -elements as you ask for, it will exponentially increase if there are -too few spare slots. If you want reserve a specific number of slots, -but do not want the exponential increase (for instance, you know this -is the last allocation), use a negative number for reservation. You -can also create a vector of a specific size from the get go. - -You should prefer the push and pop operations, as they append and -remove from the end of the vector. If you need to remove several items -in one go, use the truncate operation. The insert and remove -operations allow you to change elements in the middle of the vector. -There are two remove operations, one which preserves the element -ordering @code{ordered_remove}, and one which does not -@code{unordered_remove}. The latter function copies the end element -into the removed slot, rather than invoke a memmove operation. The -@code{lower_bound} function will determine where to place an item in -the array using insert that will maintain sorted order. - -If you need to directly manipulate a vector, then the @code{address} -accessor will return the address of the start of the vector. Also the -@code{space} predicate will tell you whether there is spare capacity in the -vector. You will not normally need to use these two functions. - -Vector types are defined using a -@code{DEF_VEC_@{O,P,I@}(@var{typename})} macro. Variables of vector -type are declared using a @code{VEC(@var{typename})} macro. The -characters @code{O}, @code{P} and @code{I} indicate whether -@var{typename} is an object (@code{O}), pointer (@code{P}) or integral -(@code{I}) type. Be careful to pick the correct one, as you'll get an -awkward and inefficient API if you use the wrong one. There is a -check, which results in a compile-time warning, for the @code{P} and -@code{I} versions, but there is no check for the @code{O} versions, as -that is not possible in plain C. - -An example of their use would be, - -@smallexample -DEF_VEC_P(tree); // non-managed tree vector. - -struct my_struct @{ - VEC(tree) *v; // A (pointer to) a vector of tree pointers. -@}; - -struct my_struct *s; - -if (VEC_length(tree, s->v)) @{ we have some contents @} -VEC_safe_push(tree, s->v, decl); // append some decl onto the end -for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++) - @{ do something with elt @} - -@end smallexample - -The @file{vec.h} file provides details on how to invoke the various -accessors provided. They are enumerated here: - -@table @code -@item VEC_length -Return the number of items in the array, - -@item VEC_empty -Return true if the array has no elements. - -@item VEC_last -@itemx VEC_index -Return the last or arbitrary item in the array. - -@item VEC_iterate -Access an array element and indicate whether the array has been -traversed. - -@item VEC_alloc -@itemx VEC_free -Create and destroy an array. - -@item VEC_embedded_size -@itemx VEC_embedded_init -Helpers for embedding an array as the final element of another struct. - -@item VEC_copy -Duplicate an array. - -@item VEC_space -Return the amount of free space in an array. - -@item VEC_reserve -Ensure a certain amount of free space. - -@item VEC_quick_push -@itemx VEC_safe_push -Append to an array, either assuming the space is available, or making -sure that it is. - -@item VEC_pop -Remove the last item from an array. - -@item VEC_truncate -Remove several items from the end of an array. - -@item VEC_safe_grow -Add several items to the end of an array. - -@item VEC_replace -Overwrite an item in the array. - -@item VEC_quick_insert -@itemx VEC_safe_insert -Insert an item into the middle of the array. Either the space must -already exist, or the space is created. - -@item VEC_ordered_remove -@itemx VEC_unordered_remove -Remove an item from the array, preserving order or not. - -@item VEC_block_remove -Remove a set of items from the array. - -@item VEC_address -Provide the address of the first element. - -@item VEC_lower_bound -Binary search the array. - -@end table - -@section include - -@node Coding Standards - -@chapter Coding Standards -@cindex coding standards - -@section @value{GDBN} C 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 Formatting - -@cindex source code formatting -The standard GNU recommendations for formatting must be followed -strictly. Any @value{GDBN}-specific deviation from GNU -recomendations is described below. - -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 - -In addition, whitespace around casts and unary operators should follow -the following guidelines: - -@multitable @columnfractions .2 .2 .8 -@item Use... @tab ...instead of @tab - -@item @code{!x} -@tab @code{! x} -@item @code{~x} -@tab @code{~ x} -@item @code{-x} -@tab @code{- x} -@tab (unary minus) -@item @code{(foo) x} -@tab @code{(foo)x} -@tab (cast) -@item @code{*x} -@tab @code{* x} -@tab (pointer dereference) -@end multitable - -Any two or more lines in code should be wrapped in braces, even if -they are comments, as they look like separate statements: - -@smallexample -if (i) - @{ - /* Return success. */ - return 0; - @} -@end smallexample - -@noindent -and not: - -@smallexample -if (i) - /* Return success. */ - return 0; -@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}. - -Zero constant (@code{0}) is not interchangeable with a null pointer -constant (@code{NULL}) anywhere. @sc{gcc} does not give a warning for -such interchange. Specifically: - -@multitable @columnfractions .2 .5 -@item incorrect -@tab @code{if (pointervar) @{@}} -@item incorrect -@tab @code{if (!pointervar) @{@}} -@item incorrect -@tab @code{if (pointervar != 0) @{@}} -@item incorrect -@tab @code{if (pointervar == 0) @{@}} -@item correct -@tab @code{if (pointervar != NULL) @{@}} -@item correct -@tab @code{if (pointervar == NULL) @{@}} -@end multitable - -@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, that declaration should use the @code{extern} modifier. -The only exception concerns @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 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}). These headers should be relatively -independent: they should use only macros defined by @file{configure}, -the compiler, or the host; they should include only system headers; they -should refer only to system types. They may be shared between multiple -programs, e.g.@: @value{GDBN} and @sc{gdbserver}. - -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 - -@section @value{GDBN} Python Coding Standards - -@value{GDBN} follows the published @code{Python} coding standards in -@uref{http://www.python.org/dev/peps/pep-0008/, @code{PEP008}}. - -In addition, the guidelines in the -@uref{http://google-styleguide.googlecode.com/svn/trunk/pyguide.html, -Google Python Style Guide} are also followed where they do not -conflict with @code{PEP008}. - -@subsection @value{GDBN}-specific exceptions - -There are a few exceptions to the published standards. -They exist mainly for consistency with the @code{C} standards. - -@c It is expected that there are a few more exceptions, -@c so we use itemize here. - -@itemize @bullet - -@item -Use @code{FIXME} instead of @code{TODO}. - -@end itemize - -@node Misc Guidelines - -@chapter Misc Guidelines - -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: - -@deftypefn {Architecture Function} {struct gdbarch_data *} gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init}) -@var{pre_init} is used to, on-demand, allocate an initial value for a -per-architecture data-pointer using the architecture's obstack (passed -in as a parameter). Since @var{pre_init} can be called during -architecture creation, it is not parameterized with the architecture. -and must not call modules that use per-architecture data. -@end deftypefn - -@deftypefn {Architecture Function} {struct gdbarch_data *} gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init}) -@var{post_init} is used to obtain an initial value for a -per-architecture data-pointer @emph{after}. Since @var{post_init} is -always called after architecture creation, it both receives the fully -initialized architecture and is free to call modules that use -per-architecture data (care needs to be taken to ensure that those -other modules do not try to call back to this module as that will -create in cycles in the initialization call graph). -@end deftypefn - -These functions return a @code{struct gdbarch_data} that is used to -identify the per-architecture data-pointer added for that module. - -The per-architecture data-pointer is accessed using the function: - -@deftypefn {Architecture Function} {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{gdbarch_data_register_pre_init} -or @code{gdbarch_data_register_post_init}), this function returns the -current value of the per-architecture data-pointer. If the data -pointer is @code{NULL}, it is first initialized by calling the -corresponding @var{pre_init} or @var{post_init} method. -@end deftypefn - -The examples below assume the following definitions: - -@smallexample -struct nozel @{ int total; @}; -static struct gdbarch_data *nozel_handle; -@end smallexample - -A module can extend the architecture vector, adding additional -per-architecture data, using the @var{pre_init} method. The module's -per-architecture data is then initialized during architecture -creation. - -In the below, the module's per-architecture @emph{nozel} is added. An -architecture can specify its nozel by calling @code{set_gdbarch_nozel} -from @code{gdbarch_init}. - -@smallexample -static void * -nozel_pre_init (struct obstack *obstack) -@{ - struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel); - return data; -@} -@end smallexample - -@smallexample -extern void -set_gdbarch_nozel (struct gdbarch *gdbarch, int total) -@{ - struct nozel *data = gdbarch_data (gdbarch, nozel_handle); - data->total = nozel; -@} -@end smallexample - -A module can on-demand create architecture dependent data structures -using @code{post_init}. - -In the below, the nozel's total is computed on-demand by -@code{nozel_post_init} using information obtained from the -architecture. - -@smallexample -static void * -nozel_post_init (struct gdbarch *gdbarch) -@{ - struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); - nozel->total = gdbarch@dots{} (gdbarch); - return data; -@} -@end smallexample - -@smallexample -extern int -nozel_total (struct gdbarch *gdbarch) -@{ - struct nozel *data = gdbarch_data (gdbarch, nozel_handle); - return data->total; -@} -@end smallexample - -@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 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{xstrprintf}. - -@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print -functions such as @code{sprintf} are very prone to buffer overflow -errors.} - - -@section Compiler Warnings -@cindex compiler warnings - -With few exceptions, developers should avoid the configuration option -@samp{--disable-werror} when building @value{GDBN}. The exceptions -are listed in the file @file{gdb/MAINTAINERS}. The default, when -building with @sc{gcc}, is @samp{--enable-werror}. - -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 are treated as errors. - -The current list of warning flags includes: - -@table @samp -@item -Wall -Recommended @sc{gcc} warnings. - -@item -Wdeclaration-after-statement - -@sc{gcc} 3.x (and later) and @sc{c99} allow declarations mixed with -code, but @sc{gcc} 2.x and @sc{c89} do not. - -@item -Wpointer-arith - -@item -Wformat-nonliteral -Non-literal format strings, with a few exceptions, are bugs - they -might contain unintended user-supplied format specifiers. -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 -Wpointer-sign -This helps make sure @value{GDBN} code uses @code{gdb_byte} which is -really @code{unsigned char} for raw bytes instead of @code{char}, -whose signedness is host-dependent. @sc{gcc} enables this with -@code{-Wall} since version 4.0. We enable it explicitly too to be -decoupled from future @sc{gcc} (or other compiler)'s defaults. - -@item -Wno-unused-parameter -Due to the way that @value{GDBN} is implemented many functions have -unused parameters. Consequently this warning is avoided. 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. - -@item -Wno-unused -@itemx -Wno-switch -@itemx -Wno-char-subscripts -These are warnings which might be useful for @value{GDBN}, but are -currently too noisy to enable with @samp{-Werror}. - -@end table - -@section 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}.} - -@section Command Names - -GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}. - -@section 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. Porting a new -architecture to @value{GDBN} can be broken into a number of steps. - -@itemize @bullet - -@item -Ensure a @sc{bfd} exists for executables of the target architecture in -the @file{bfd} directory. If one does not exist, create one by -modifying an existing similar one. - -@item -Implement a disassembler for the target architecture in the @file{opcodes} -directory. - -@item -Define the target architecture in the @file{gdb} directory -(@pxref{Adding a New Target, , Adding a New Target}). Add the pattern -for the new target to @file{configure.tgt} with the names of the files -that contain the code. By convention the target architecture -definition for an architecture @var{arch} is placed in -@file{@var{arch}-tdep.c}. - -Within @file{@var{arch}-tdep.c} define the function -@code{_initialize_@var{arch}_tdep} which calls -@code{gdbarch_register} to create the new @code{@w{struct -gdbarch}} for the architecture. - -@item -If a new remote target is needed, consider adding a new remote target -by defining a function -@code{_initialize_remote_@var{arch}}. However if at all possible -use the @value{GDBN} @emph{Remote Serial Protocol} for this and implement -the server side protocol independently with the target. - -@item -If desired implement a simulator in the @file{sim} directory. This -should create the library @file{libsim.a} implementing the interface -in @file{remote-sim.h} (found in the @file{include} directory). - -@item -Build and test. If desired, lobby the @sc{gdb} steering group to -have the new port included in the main distribution! - -@item -Add a description of the new architecture to the main @value{GDBN} user -guide (@pxref{Configuration Specific Information, , Configuration -Specific Information, gdb, Debugging with @value{GDBN}}). - -@end itemize - -@node Versions and Branches -@chapter Versions and Branches - -@section Versions - -@value{GDBN}'s version is determined by the file -@file{gdb/version.in} and takes one of the following forms: - -@table @asis -@item @var{major}.@var{minor} -@itemx @var{major}.@var{minor}.@var{patchlevel} -an official release (e.g., 6.2 or 6.2.1) -@item @var{major}.@var{minor}.@var{patchlevel}.DATE -a snapshot; the string @samp{DATE} is replace with the date from -@file{bfd/version.h} -@item @var{major}.@var{minor}.@var{patchlevel}.DATE-cvs -a @sc{cvs} check out; the string @samp{DATE} is replace with the date from -@file{bfd/version.h} -@item @var{major}.@var{minor}.@var{patchlevel}.DATE (@var{vendor}) -a vendor specific release of @value{GDBN}, that while based on@* -@var{major}.@var{minor}.@var{patchlevel}.DATE, -may include additional changes -@end table - -@value{GDBN}'s mainline uses the @var{major} and @var{minor} version -numbers from the most recent release branch, with a @var{patchlevel} -of 50. At the time each new release branch is created, the mainline's -@var{major} and @var{minor} version numbers are updated. - -@value{GDBN}'s release branch is similar. When the branch is cut, the -@var{patchlevel} is changed from 50 to 90. As draft releases are -drawn from the branch, the @var{patchlevel} is incremented. Once the -first release (@var{major}.@var{minor}) has been made, the -@var{patchlevel} is set to 0 and updates have an incremented -@var{patchlevel}. - -For snapshots, and @sc{cvs} check outs, it is also possible to -identify the @sc{cvs} origin: - -@table @asis -@item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD} -drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302) -@item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD} -@itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{} -drawn from a release branch prior to the release (e.g., -6.1.90.20020304) -@item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD} -@itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{} -drawn from a release branch after the release (e.g., 6.2.0.20020308) -@end table - -If the previous @value{GDBN} version is 6.1 and the current version is -6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor}, -here's an illustration of a typical sequence: - -@smallexample - <HEAD> - | -6.1.50.20020302-cvs - | - +--------------------------. - | <gdb_6_2-branch> - | | -6.2.50.20020303-cvs 6.1.90 (draft #1) - | | -6.2.50.20020304-cvs 6.1.90.20020304-cvs - | | -6.2.50.20020305-cvs 6.1.91 (draft #2) - | | -6.2.50.20020306-cvs 6.1.91.20020306-cvs - | | -6.2.50.20020307-cvs 6.2 (release) - | | -6.2.50.20020308-cvs 6.2.0.20020308-cvs - | | -6.2.50.20020309-cvs 6.2.1 (update) - | | -6.2.50.20020310-cvs <branch closed> - | -6.2.50.20020311-cvs - | - +--------------------------. - | <gdb_6_3-branch> - | | -6.3.50.20020312-cvs 6.2.90 (draft #1) - | | -@end smallexample - -@section Release Branches -@cindex Release Branches - -@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a -single release branch, and identifies that branch using the @sc{cvs} -branch tags: - -@smallexample -gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint -gdb_@var{major}_@var{minor}-branch -gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release -@end smallexample - -@emph{Pragmatics: To help identify the date at which a branch or -release is made, both the branchpoint and release tags include the -date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The -branch tag, denoting the head of the branch, does not need this.} - -@section Vendor Branches -@cindex vendor branches - -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 identifier). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit -Inc Patch 2)}. - -@section Experimental Branches -@cindex experimental branches - -@subsection Guidelines - -@value{GDBN} permits the creation of branches, cut from the @sc{cvs} -repository, for experimental development. Branches make it possible -for developers to share preliminary work, and maintainers to examine -significant new developments. - -The following are a set of guidelines for creating such branches: - -@table @emph - -@item a branch has an owner -The owner can set further policy for a branch, but may not change the -ground rules. In particular, they can set a policy for commits (be it -adding more reviewers or deciding who can commit). - -@item all commits are posted -All changes committed to a branch shall also be posted to -@email{gdb-patches@@sourceware.org, the @value{GDBN} patches -mailing list}. While commentary on such changes are encouraged, people -should remember that the changes only apply to a branch. - -@item all commits are covered by an assignment -This ensures that all changes belong to the Free Software Foundation, -and avoids the possibility that the branch may become contaminated. - -@item a branch is focused -A focused branch has a single objective or goal, and does not contain -unnecessary or irrelevant changes. Cleanups, where identified, being -be pushed into the mainline as soon as possible. - -@item a branch tracks mainline -This keeps the level of divergence under control. It also keeps the -pressure on developers to push cleanups and other stuff into the -mainline. - -@item a branch shall contain the entire @value{GDBN} module -The @value{GDBN} module @code{gdb} should be specified when creating a -branch (branches of individual files should be avoided). @xref{Tags}. - -@item a branch shall be branded using @file{version.in} -The file @file{gdb/version.in} shall be modified so that it identifies -the branch @var{owner} and branch @var{name}, e.g., -@samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}. - -@end table - -@subsection Tags -@anchor{Tags} - -To simplify the identification of @value{GDBN} branches, the following -branch tagging convention is strongly recommended: - -@table @code - -@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint -@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch -The branch point and corresponding branch tag. @var{YYYYMMDD} is the -date that the branch was created. A branch is created using the -sequence: @anchor{experimental branch tags} -@smallexample -cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb -cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \ - @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb -@end smallexample - -@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint -The tagged point, on the mainline, that was used when merging the branch -on @var{yyyymmdd}. To merge in all changes since the branch was cut, -use a command sequence like: -@smallexample -cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb -cvs update \ - -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint - -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint -@end smallexample -@noindent -Similar sequences can be used to just merge in changes since the last -merge. - -@end table - -@noindent -For further information on @sc{cvs}, see -@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}. - -@node Start of New Year Procedure -@chapter Start of New Year Procedure -@cindex new year procedure - -At the start of each new year, the following actions should be performed: - -@itemize @bullet -@item -Rotate the ChangeLog file - -The current @file{ChangeLog} file should be renamed into -@file{ChangeLog-YYYY} where YYYY is the year that has just passed. -A new @file{ChangeLog} file should be created, and its contents should -contain a reference to the previous ChangeLog. The following should -also be preserved at the end of the new ChangeLog, in order to provide -the appropriate settings when editing this file with Emacs: -@smallexample -Local Variables: -mode: change-log -left-margin: 8 -fill-column: 74 -version-control: never -coding: utf-8 -End: -@end smallexample - -@item -Add an entry for the newly created ChangeLog file (@file{ChangeLog-YYYY}) -in @file{gdb/config/djgpp/fnchange.lst}. - -@item -Update the copyright year in the startup message - -Update the copyright year in: -@itemize @bullet - @item - file @file{top.c}, function @code{print_gdb_version} - @item - file @file{gdbserver/server.c}, function @code{gdbserver_version} - @item - file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version} -@end itemize - -@item -Run the @file{copyright.py} Python script to add the new year in the copyright -notices of most source files. This script has been tested with Python -2.6 and 2.7. - -@end itemize - -@node Releasing GDB - -@chapter Releasing @value{GDBN} -@cindex making a new release of gdb - -@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@@sourceware.org, 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@@sourceware.org, 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://sourceware.org/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:sourceware.org:/cvs/src rtag \ --D $D-gmt gdb_$V-$D-branchpoint insight -cvs -f -d :ext:sourceware.org:/cvs/src rtag --D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight -$ ^echo ^^ -... -$ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \ --b -r gdb_$V-$D-branchpoint gdb_$V-branch insight -cvs -f -d :ext:sourceware.org:/cvs/src rtag \ --b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight -$ ^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 tagged so that the branch point can easily be found. -@item -Insight, which includes @value{GDBN}, is 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:sourceware.org:/cvs/src co \ --r gdb_$V-branch src/gdb/version.in -cvs -f -d :ext:sourceware.org:/cvs/src co - -r gdb_5_2-branch src/gdb/version.in -$ ^echo ^^ -U src/gdb/version.in -$ cd src/gdb -$ echo $u.90-DATE-cvs > version.in -$ cat version.in -5.1.90-DATE-cvs -$ cvs -f commit version.in -@end smallexample - -@itemize @bullet -@item -The string @samp{DATE} is used to substitute the checkout date at -build time; the date comes from @file{bfd/version.h}. -@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{bfd/version.h}. -@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@@sourceware.org, GDB Announcement mailing list} -@item -@email{gdb@@sourceware.org, GDB Discussion mailing list} and -@email{gdb-testers@@sourceware.org, GDB Testers 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@@sourceware.org}. - -@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 documented in the toplevel @file{README-maintainer-mode} file. -It is very unlikely that the version of @code{autoconf} installed in -system directories (e.g., @file{/usr/bin/autoconf}) is correct. -@end itemize - -@subsubheading Check out the relevant modules: - -@smallexample -$ for m in gdb insight -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 - -@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 src-release $m.tar ) -done -@end smallexample - -If the top level source directory does not have @file{src-release} -(@value{GDBN} version 5.3.1 or earlier), try these commands instead: - -@smallexample -$ for m in gdb insight -do -( cd $m/src && gmake -f Makefile.in $m.tar ) -done -@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. - -@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 -@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 suppressed). Fixing it would be nice though.} - -@subsubheading Create compressed versions of the release - -@smallexample -$ cp */src/*.tar . -$ cp */src/*.bz2 . -$ ls -F -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}-DATE-cvs so that the version substitution -process can restart. -@item -Make the release candidate available in -@uref{ftp://sourceware.org/pub/gdb/snapshots/branch} -@item -Notify the relevant mailing lists ( @email{gdb@@sourceware.org} and -@email{gdb-testers@@sourceware.org} 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@@sourceware.org, 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}. - -@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 have the string @samp{DATE} then -builds will not include the checkout date in their resulting version. -Having committed all the release changes it can be set to -@file{5.2.0_DATE-cvs} which will restart things. - -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@@sourceware.org, 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. 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 - -To run a specific test script, type: -@example -make check RUNTESTFLAGS='@var{tests}' -@end example -where @var{tests} is a list of test script file names, separated by -spaces. - -If you use GNU make, you can use its @option{-j} option to run the -testsuite in parallel. This can greatly reduce the amount of time it -takes for the testsuite to run. In this case, if you set -@code{RUNTESTFLAGS} then, by default, the tests will be run serially -even under @option{-j}. You can override this and force a parallel run -by setting the @code{make} variable @code{FORCE_PARALLEL} to any -non-empty value. Note that the parallel @kbd{make check} assumes -that you want to run the entire testsuite, so it is not compatible -with some dejagnu options, like @option{--directory}. - -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. - -DejaGNU supports separate build, host, and target machines. However, -some @value{GDBN} test scripts do not work if the build machine and -the host machine are not the same. In such an environment, these scripts -will give a result of ``UNRESOLVED'', like this: - -@smallexample -UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host. -@end smallexample - -@section Testsuite Parameters - -Several variables exist to modify the behavior of the testsuite. - -@table @code - -@item TRANSCRIPT - -Sometimes it is convenient to get a transcript of the commands which -the testsuite sends to @value{GDBN}. For example, if @value{GDBN} -crashes during testing, a transcript can be used to more easily -reconstruct the failure when running @value{GDBN} under @value{GDBN}. - -You can instruct the @value{GDBN} testsuite to write transcripts by -setting the DejaGNU variable @code{TRANSCRIPT} (to any value) -before invoking @code{runtest} or @kbd{make check}. The transcripts -will be written into DejaGNU's output directory. One transcript will -be made for each invocation of @value{GDBN}; they will be named -@file{transcript.@var{n}}, where @var{n} is an integer. The first -line of the transcript file will show how @value{GDBN} was invoked; -each subsequent line is a command sent as input to @value{GDBN}. - -@smallexample -make check RUNTESTFLAGS=TRANSCRIPT=y -@end smallexample - -Note that the transcript is not always complete. In particular, tests -of completion can yield partial command lines. - -@item GDB - -Sometimes one wishes to test a different @value{GDBN} than the one in the build -directory. For example, one may wish to run the testsuite on -@file{/usr/bin/gdb}. - -@smallexample -make check RUNTESTFLAGS=GDB=/usr/bin/gdb -@end smallexample - -@item GDBSERVER - -When testing a different @value{GDBN}, it is often useful to also test a -different gdbserver. - -@smallexample -make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver" -@end smallexample - -@item INTERNAL_GDBFLAGS - -When running the testsuite normally one doesn't want whatever is in -@file{~/.gdbinit} to interfere with the tests, therefore the test harness -passes @option{-nx} to @value{GDBN}. One also doesn't want any windowed -version of @value{GDBN}, e.g., @samp{gdb -tui}, to run. -This is achieved via @code{INTERNAL_GDBFLAGS}. - -@smallexample -set INTERNAL_GDBFLAGS "-nw -nx" -@end smallexample - -This is all well and good, except when testing an installed @value{GDBN} -that has been configured with @option{--with-system-gdbinit}. Here one -does not want @file{~/.gdbinit} loaded but one may want the system -@file{.gdbinit} file loaded. This can be achieved by pointing @code{$HOME} -at a directory without a @file{.gdbinit} and by overriding -@code{INTERNAL_GDBFLAGS} and removing @option{-nx}. - -@smallexample -cd testsuite -HOME=`pwd` runtest \ - GDB=/usr/bin/gdb \ - GDBSERVER=/usr/bin/gdbserver \ - INTERNAL_GDBFLAGS=-nw -@end smallexample - -@item GDB_PARALLEL - -When testing natively (that is, not with a remote host), the -@value{GDBN} test suite can be run in a fully parallel mode. In this -mode, each @file{.exp} file can be run separately. The test suite -will ensure that all the temporary files created by the test suite do -not clash, by putting them into separate directories. This mode is -primarily intended for use by the @file{Makefile}. - -To use this mode, set the @code{GDB_PARALLEL} on the @command{runtest} -command line. Before starting the tests, you must ensure that the -directories @file{cache}, @file{outputs}, and @file{temp} in the test -suite build directory are either empty or have been deleted. -@file{cache} in particular is used to share data across invocations of -@command{runtest}, and files there may affect the test results. Note -that the @file{Makefile} automatically does these deletions. - -@item GDB_INOTIFY - -For debugging parallel mode, it is handy to be able to see when a test -case writes to a file outside of its designated output directory. - -If you have the @samp{inotify-tools} package installed, you can set -the @code{GDB_INOTIFY} variable on the @command{runtest} command line. -This will cause the test suite to watch for parallel-unsafe file -creations and report them, both on @samp{stdout} and in the test suite -@file{.log} file. - -This setting is only meaningful in conjunction with -@code{GDB_PARALLEL}. - -@end table - -There are two ways to run the testsuite and pass additional parameters -to DejaGnu. The first is with @kbd{make check} and specifying the -makefile variable @samp{RUNTESTFLAGS}. - -@smallexample -make check RUNTESTFLAGS=TRANSCRIPT=y -@end smallexample - -The second is to cd to the @file{testsuite} directory and invoke the DejaGnu -@command{runtest} command directly. - -@smallexample -cd testsuite -make site.exp -runtest TRANSCRIPT=y -@end smallexample - -@section Testsuite Configuration -@cindex Testsuite Configuration - -It is possible to adjust the behavior of the testsuite by defining -the global variables listed below, either in a @file{site.exp} file, -or in a board file. - -@itemize @bullet - -@item @code{gdb_test_timeout} - -Defining this variable changes the default timeout duration used during -communication with @value{GDBN}. More specifically, the global variable -used during testing is @code{timeout}, but this variable gets reset to -@code{gdb_test_timeout} at the beginning of each testcase, making sure -that any local change to @code{timeout} in a testcase does not affect -subsequent testcases. - -This global variable comes in handy when the debugger is slower than -normal due to the testing environment, triggering unexpected @code{TIMEOUT} -test failures. Examples include when testing on a remote machine, or -against a system where communications are slow. - -If not specifically defined, this variable gets automatically defined -to the same value as @code{timeout} during the testsuite initialization. -The default value of the timeout is defined in the file -@file{gdb/testsuite/config/unix.exp} that is part of the @value{GDBN} -test suite@footnote{If you are using a board file, it could override -the test-suite default; search the board file for "timeout".}. - -@end itemize - -@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@t{++} (@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.cp} 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. Even if @value{GDBN} has several valid responses to -a command, you can use @code{gdb_test_multiple}. Like @code{gdb_test}, -@code{gdb_test_multiple} recognizes internal errors and unexpected -prompts. - -Do not write tests which expect a literal tab character from @value{GDBN}. -On some operating systems (e.g.@: OpenBSD) the TTY layer expands tabs to -spaces, so by the time @value{GDBN}'s output reaches expect the tab is gone. - -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. - -Some testcase results need more detailed explanation: - -@table @code -@item KFAIL -Known problem of @value{GDBN} itself. You must specify the @value{GDBN} bug -report number like in these sample tests: -@smallexample -kfail "gdb/13392" "continue to marker 2" -@end smallexample -or -@smallexample -setup_kfail gdb/13392 "*-*-*" -kfail "continue to marker 2" -@end smallexample - -@item XFAIL -Known problem of environment. This typically includes @value{NGCC} but it -includes also many other system components which cannot be fixed in the -@value{GDBN} project. Sample test with sanity check not knowing the specific -cause of the problem: -@smallexample -# On x86_64 it is commonly about 4MB. -if @{$stub_size > 25000000@} @{ - xfail "stub size $stub_size is too large" - return -@} -@end smallexample - -You should provide bug report number for the failing component of the -environment, if such bug report is available: -@smallexample -if @{[test_compiler_info @{gcc-[0-3]-*@}] - || [test_compiler_info @{gcc-4-[0-5]-*@}]@} @{ - setup_xfail "gcc/46955" *-*-* -@} -gdb_test "python print ttype.template_argument(2)" "&C::c" -@end smallexample -@end table - -@section Board settings -In @value{GDBN} testsuite, the tests can be configured or customized in the board -file by means of @dfn{Board Settings}. Each setting should be consulted by -test cases that depend on the corresponding feature. - -Here are the supported board settings: - -@table @code - -@item gdb,cannot_call_functions -The board does not support inferior call, that is, invoking inferior functions -in @value{GDBN}. -@item gdb,can_reverse -The board supports reverse execution. -@item gdb,no_hardware_watchpoints -The board does not support hardware watchpoints. -@item gdb,nofileio -@value{GDBN} is unable to intercept target file operations in remote and perform -them on the host. -@item gdb,noinferiorio -The board is unable to provide I/O capability to the inferior. -@c @item gdb,noresults -@c NEED DOCUMENT. -@item gdb,nosignals -The board does not support signals. -@item gdb,skip_huge_test -Skip time-consuming tests on the board with slow connection. -@item gdb,skip_float_tests -Skip tests related to float points on target board. -@item gdb,use_precord -The board supports process record. -@item gdb_server_prog -The location of GDBserver. If GDBserver somewhere other than its default -location is used in test, specify the location of GDBserver in this variable. -The location is a file name of GDBserver that can be either absolute or -relative to testsuite subdirectory in build directory. -@item in_proc_agent -The location of in-process agent. If in-process agent other than its default -location is used in test, specify the location of in-process agent in -this variable. The location is a file name of in-process agent that can be -either absolute or relative to testsuite subdirectory in build directory. -@item noargs -@value{GDBN} does not support argument passing for inferior. -@item no_long_long -The board does not support type @code{long long}. -@c @item use_cygmon -@c NEED DOCUMENT. -@item use_gdb_stub -The tests are running with gdb stub. -@item gdb,predefined_tsv -The predefined trace state variables the board has. - -@end table - -@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 - -@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 - -@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 -@file{gdb-gdb.gdb} file (plus possibly @file{gdb-gdb.py} 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{gdb-gdb.gdb} 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@@sourceware.org, the @value{GDBN} maintainers}. - -@section Build Script - -@cindex build script - -The script @file{gdb_buildall.sh} builds @value{GDBN} with flag -@option{--enable-targets=all} set. This builds @value{GDBN} with all supported -targets activated. This helps testing @value{GDBN} when doing changes that -affect more than one architecture and is much faster than using -@file{gdb_mbuild.sh}. - -After building @value{GDBN} the script checks which architectures are -supported and then switches the current architecture to each of those to get -information about the architecture. The test results are stored in log files -in the directory the script was called from. - -@include observer.texi - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include fdl.texi - -@node Concept Index -@unnumbered Concept Index - -@printindex cp - -@node Function and Variable Index -@unnumbered Function and Variable Index - -@printindex fn - -@bye |