gdb/
[deliverable/binutils-gdb.git] / gdb / doc / gdbint.texinfo
CommitLineData
9742079a 1\input texinfo @c -*- texinfo -*-
c906108c 2@setfilename gdbint.info
25822942 3@include gdb-cfg.texi
03727ca6 4@dircategory Software development
e9c75b65 5@direntry
c906108c 6* Gdb-Internals: (gdbint). The GNU debugger's internals.
e9c75b65 7@end direntry
c906108c
SS
8
9@ifinfo
25822942 10This file documents the internals of the GNU debugger @value{GDBN}.
c02a867d 11Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
c91d38aa 12 2002, 2003, 2004, 2005, 2006
e9c75b65 13 Free Software Foundation, Inc.
c906108c
SS
14Contributed by Cygnus Solutions. Written by John Gilmore.
15Second Edition by Stan Shebs.
16
e9c75b65
EZ
17Permission is granted to copy, distribute and/or modify this document
18under the terms of the GNU Free Documentation License, Version 1.1 or
2a6585f0 19any later version published by the Free Software Foundation; with no
e5249f67
AC
20Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
21Texts. A copy of the license is included in the section entitled ``GNU
22Free Documentation License''.
c906108c
SS
23@end ifinfo
24
25@setchapternewpage off
25822942 26@settitle @value{GDBN} Internals
c906108c 27
56caf160
EZ
28@syncodeindex fn cp
29@syncodeindex vr cp
30
c906108c 31@titlepage
25822942 32@title @value{GDBN} Internals
c906108c
SS
33@subtitle{A guide to the internals of the GNU debugger}
34@author John Gilmore
35@author Cygnus Solutions
36@author Second Edition:
37@author Stan Shebs
38@author Cygnus Solutions
39@page
40@tex
41\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
42\xdef\manvers{\$Revision$} % For use in headers, footers too
43{\parskip=0pt
44\hfill Cygnus Solutions\par
45\hfill \manvers\par
46\hfill \TeX{}info \texinfoversion\par
47}
48@end tex
49
50@vskip 0pt plus 1filll
1e698235 51Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,
c91d38aa 52 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
c906108c 53
e9c75b65
EZ
54Permission is granted to copy, distribute and/or modify this document
55under the terms of the GNU Free Documentation License, Version 1.1 or
2a6585f0 56any later version published by the Free Software Foundation; with no
e5249f67
AC
57Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
58Texts. A copy of the license is included in the section entitled ``GNU
59Free Documentation License''.
c906108c
SS
60@end titlepage
61
449f3b6c 62@contents
449f3b6c 63
c906108c
SS
64@node Top
65@c Perhaps this should be the title of the document (but only for info,
66@c not for TeX). Existing GNU manuals seem inconsistent on this point.
67@top Scope of this Document
68
25822942
DB
69This document documents the internals of the GNU debugger, @value{GDBN}. It
70includes description of @value{GDBN}'s key algorithms and operations, as well
71as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
c906108c
SS
72
73@menu
74* Requirements::
75* Overall Structure::
76* Algorithms::
77* User Interface::
89437448 78* libgdb::
c906108c
SS
79* Symbol Handling::
80* Language Support::
81* Host Definition::
82* Target Architecture Definition::
123dc839 83* Target Descriptions::
c906108c
SS
84* Target Vector Definition::
85* Native Debugging::
86* Support Libraries::
87* Coding::
88* Porting GDB::
d52fe014 89* Versions and Branches::
55f6ca0f 90* Start of New Year Procedure::
8973da3a 91* Releasing GDB::
085dd6e6 92* Testsuite::
c906108c 93* Hints::
aab4e0ec 94
bcd7e15f 95* GDB Observers:: @value{GDBN} Currently available observers
aab4e0ec 96* GNU Free Documentation License:: The license for this documentation
56caf160 97* Index::
c906108c
SS
98@end menu
99
100@node Requirements
101
102@chapter Requirements
56caf160 103@cindex requirements for @value{GDBN}
c906108c
SS
104
105Before diving into the internals, you should understand the formal
56caf160
EZ
106requirements and other expectations for @value{GDBN}. Although some
107of these may seem obvious, there have been proposals for @value{GDBN}
108that have run counter to these requirements.
c906108c 109
56caf160
EZ
110First of all, @value{GDBN} is a debugger. It's not designed to be a
111front panel for embedded systems. It's not a text editor. It's not a
112shell. It's not a programming environment.
c906108c 113
56caf160
EZ
114@value{GDBN} is an interactive tool. Although a batch mode is
115available, @value{GDBN}'s primary role is to interact with a human
116programmer.
c906108c 117
56caf160
EZ
118@value{GDBN} should be responsive to the user. A programmer hot on
119the trail of a nasty bug, and operating under a looming deadline, is
120going to be very impatient of everything, including the response time
121to debugger commands.
c906108c 122
56caf160
EZ
123@value{GDBN} should be relatively permissive, such as for expressions.
124While the compiler should be picky (or have the option to be made
be9c6c35 125picky), since source code lives for a long time usually, the
56caf160
EZ
126programmer doing debugging shouldn't be spending time figuring out to
127mollify the debugger.
c906108c 128
56caf160
EZ
129@value{GDBN} will be called upon to deal with really large programs.
130Executable sizes of 50 to 100 megabytes occur regularly, and we've
131heard reports of programs approaching 1 gigabyte in size.
c906108c 132
56caf160
EZ
133@value{GDBN} should be able to run everywhere. No other debugger is
134available for even half as many configurations as @value{GDBN}
135supports.
c906108c
SS
136
137
138@node Overall Structure
139
140@chapter Overall Structure
141
56caf160
EZ
142@value{GDBN} consists of three major subsystems: user interface,
143symbol handling (the @dfn{symbol side}), and target system handling (the
144@dfn{target side}).
c906108c 145
2e685b93 146The user interface consists of several actual interfaces, plus
c906108c
SS
147supporting code.
148
149The symbol side consists of object file readers, debugging info
150interpreters, symbol table management, source language expression
151parsing, type and value printing.
152
153The target side consists of execution control, stack frame analysis, and
154physical target manipulation.
155
156The target side/symbol side division is not formal, and there are a
157number of exceptions. For instance, core file support involves symbolic
158elements (the basic core file reader is in BFD) and target elements (it
159supplies the contents of memory and the values of registers). Instead,
160this division is useful for understanding how the minor subsystems
161should fit together.
162
163@section The Symbol Side
164
56caf160
EZ
165The symbolic side of @value{GDBN} can be thought of as ``everything
166you can do in @value{GDBN} without having a live program running''.
167For instance, you can look at the types of variables, and evaluate
168many kinds of expressions.
c906108c
SS
169
170@section The Target Side
171
56caf160
EZ
172The target side of @value{GDBN} is the ``bits and bytes manipulator''.
173Although it may make reference to symbolic info here and there, most
174of the target side will run with only a stripped executable
175available---or even no executable at all, in remote debugging cases.
c906108c
SS
176
177Operations such as disassembly, stack frame crawls, and register
178display, are able to work with no symbolic info at all. In some cases,
25822942 179such as disassembly, @value{GDBN} will use symbolic info to present addresses
c906108c
SS
180relative to symbols rather than as raw numbers, but it will work either
181way.
182
183@section Configurations
184
56caf160
EZ
185@cindex host
186@cindex target
25822942 187@dfn{Host} refers to attributes of the system where @value{GDBN} runs.
c906108c
SS
188@dfn{Target} refers to the system where the program being debugged
189executes. In most cases they are the same machine, in which case a
190third type of @dfn{Native} attributes come into play.
191
192Defines and include files needed to build on the host are host support.
193Examples are tty support, system defined types, host byte order, host
194float format.
195
196Defines and information needed to handle the target format are target
197dependent. Examples are the stack frame format, instruction set,
198breakpoint instruction, registers, and how to set up and tear down the stack
199to call a function.
200
201Information that is only needed when the host and target are the same,
202is native dependent. One example is Unix child process support; if the
203host and target are not the same, doing a fork to start the target
204process is a bad idea. The various macros needed for finding the
205registers in the @code{upage}, running @code{ptrace}, and such are all
206in the native-dependent files.
207
208Another example of native-dependent code is support for features that
209are really part of the target environment, but which require
210@code{#include} files that are only available on the host system. Core
211file handling and @code{setjmp} handling are two common cases.
212
25822942 213When you want to make @value{GDBN} work ``native'' on a particular machine, you
c906108c
SS
214have to include all three kinds of information.
215
25ab7e6d
EZ
216@section Source Tree Structure
217@cindex @value{GDBN} source tree structure
218
219The @value{GDBN} source directory has a mostly flat structure---there
220are only a few subdirectories. A file's name usually gives a hint as
221to what it does; for example, @file{stabsread.c} reads stabs,
7ce59000 222@file{dwarf2read.c} reads @sc{DWARF 2}, etc.
25ab7e6d
EZ
223
224Files that are related to some common task have names that share
225common substrings. For example, @file{*-thread.c} files deal with
226debugging threads on various platforms; @file{*read.c} files deal with
227reading various kinds of symbol and object files; @file{inf*.c} files
228deal with direct control of the @dfn{inferior program} (@value{GDBN}
229parlance for the program being debugged).
230
231There are several dozens of files in the @file{*-tdep.c} family.
232@samp{tdep} stands for @dfn{target-dependent code}---each of these
233files implements debug support for a specific target architecture
234(sparc, mips, etc). Usually, only one of these will be used in a
235specific @value{GDBN} configuration (sometimes two, closely related).
236
237Similarly, there are many @file{*-nat.c} files, each one for native
238debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for
239native debugging of Sparc machines running the Linux kernel).
240
241The few subdirectories of the source tree are:
242
243@table @file
244@item cli
245Code that implements @dfn{CLI}, the @value{GDBN} Command-Line
246Interpreter. @xref{User Interface, Command Interpreter}.
247
248@item gdbserver
249Code for the @value{GDBN} remote server.
250
251@item gdbtk
252Code for Insight, the @value{GDBN} TK-based GUI front-end.
253
254@item mi
255The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter.
256
257@item signals
258Target signal translation code.
259
260@item tui
261Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User
262Interface. @xref{User Interface, TUI}.
263@end table
c906108c
SS
264
265@node Algorithms
266
267@chapter Algorithms
56caf160 268@cindex algorithms
c906108c 269
56caf160
EZ
270@value{GDBN} uses a number of debugging-specific algorithms. They are
271often not very complicated, but get lost in the thicket of special
272cases and real-world issues. This chapter describes the basic
273algorithms and mentions some of the specific target definitions that
274they use.
c906108c
SS
275
276@section Frames
277
56caf160
EZ
278@cindex frame
279@cindex call stack frame
280A frame is a construct that @value{GDBN} uses to keep track of calling
281and called functions.
c906108c 282
410dd08e 283@cindex frame, unwind
c5e30d01
AC
284@value{GDBN}'s frame model, a fresh design, was implemented with the
285need to support @sc{dwarf}'s Call Frame Information in mind. In fact,
286the term ``unwind'' is taken directly from that specification.
287Developers wishing to learn more about unwinders, are encouraged to
d3e8051b 288read the @sc{dwarf} specification.
410dd08e
JB
289
290@findex frame_register_unwind
c5e30d01
AC
291@findex get_frame_register
292@value{GDBN}'s model is that you find a frame's registers by
293``unwinding'' them from the next younger frame. That is,
294@samp{get_frame_register} which returns the value of a register in
295frame #1 (the next-to-youngest frame), is implemented by calling frame
296#0's @code{frame_register_unwind} (the youngest frame). But then the
297obvious question is: how do you access the registers of the youngest
298frame itself?
410dd08e
JB
299
300@cindex sentinel frame
301@findex get_frame_type
302@vindex SENTINEL_FRAME
303To answer this question, GDB has the @dfn{sentinel} frame, the
304``-1st'' frame. Unwinding registers from the sentinel frame gives you
305the current values of the youngest real frame's registers. If @var{f}
306is a sentinel frame, then @code{get_frame_type (@var{f}) ==
307SENTINEL_FRAME}.
308
7d30c22d
JB
309@section Prologue Analysis
310
311@cindex prologue analysis
312@cindex call frame information
313@cindex CFI (call frame information)
314To produce a backtrace and allow the user to manipulate older frames'
315variables and arguments, @value{GDBN} needs to find the base addresses
316of older frames, and discover where those frames' registers have been
317saved. Since a frame's ``callee-saves'' registers get saved by
318younger frames if and when they're reused, a frame's registers may be
319scattered unpredictably across younger frames. This means that
320changing the value of a register-allocated variable in an older frame
321may actually entail writing to a save slot in some younger frame.
322
323Modern versions of GCC emit Dwarf call frame information (``CFI''),
324which describes how to find frame base addresses and saved registers.
325But CFI is not always available, so as a fallback @value{GDBN} uses a
326technique called @dfn{prologue analysis} to find frame sizes and saved
327registers. A prologue analyzer disassembles the function's machine
328code starting from its entry point, and looks for instructions that
329allocate frame space, save the stack pointer in a frame pointer
330register, save registers, and so on. Obviously, this can't be done
b247355e 331accurately in general, but it's tractable to do well enough to be very
7d30c22d
JB
332helpful. Prologue analysis predates the GNU toolchain's support for
333CFI; at one time, prologue analysis was the only mechanism
334@value{GDBN} used for stack unwinding at all, when the function
335calling conventions didn't specify a fixed frame layout.
336
337In the olden days, function prologues were generated by hand-written,
338target-specific code in GCC, and treated as opaque and untouchable by
339optimizers. Looking at this code, it was usually straightforward to
340write a prologue analyzer for @value{GDBN} that would accurately
341understand all the prologues GCC would generate. However, over time
342GCC became more aggressive about instruction scheduling, and began to
343understand more about the semantics of the prologue instructions
344themselves; in response, @value{GDBN}'s analyzers became more complex
345and fragile. Keeping the prologue analyzers working as GCC (and the
346instruction sets themselves) evolved became a substantial task.
347
348@cindex @file{prologue-value.c}
349@cindex abstract interpretation of function prologues
350@cindex pseudo-evaluation of function prologues
351To try to address this problem, the code in @file{prologue-value.h}
352and @file{prologue-value.c} provides a general framework for writing
353prologue analyzers that are simpler and more robust than ad-hoc
354analyzers. When we analyze a prologue using the prologue-value
355framework, we're really doing ``abstract interpretation'' or
356``pseudo-evaluation'': running the function's code in simulation, but
357using conservative approximations of the values registers and memory
358would hold when the code actually runs. For example, if our function
359starts with the instruction:
360
361@example
362addi r1, 42 # add 42 to r1
363@end example
364@noindent
365we don't know exactly what value will be in @code{r1} after executing
366this instruction, but we do know it'll be 42 greater than its original
367value.
368
369If we then see an instruction like:
370
371@example
372addi r1, 22 # add 22 to r1
373@end example
374@noindent
375we still don't know what @code{r1's} value is, but again, we can say
376it is now 64 greater than its original value.
377
378If the next instruction were:
379
380@example
381mov r2, r1 # set r2 to r1's value
382@end example
383@noindent
384then we can say that @code{r2's} value is now the original value of
385@code{r1} plus 64.
386
387It's common for prologues to save registers on the stack, so we'll
388need to track the values of stack frame slots, as well as the
389registers. So after an instruction like this:
390
391@example
392mov (fp+4), r2
393@end example
394@noindent
395then we'd know that the stack slot four bytes above the frame pointer
396holds the original value of @code{r1} plus 64.
397
398And so on.
399
400Of course, this can only go so far before it gets unreasonable. If we
401wanted to be able to say anything about the value of @code{r1} after
402the instruction:
403
404@example
405xor r1, r3 # exclusive-or r1 and r3, place result in r1
406@end example
407@noindent
408then things would get pretty complex. But remember, we're just doing
409a conservative approximation; if exclusive-or instructions aren't
410relevant to prologues, we can just say @code{r1}'s value is now
411``unknown''. We can ignore things that are too complex, if that loss of
412information is acceptable for our application.
413
414So when we say ``conservative approximation'' here, what we mean is an
415approximation that is either accurate, or marked ``unknown'', but
416never inaccurate.
417
418Using this framework, a prologue analyzer is simply an interpreter for
419machine code, but one that uses conservative approximations for the
420contents of registers and memory instead of actual values. Starting
421from the function's entry point, you simulate instructions up to the
422current PC, or an instruction that you don't know how to simulate.
423Now you can examine the state of the registers and stack slots you've
424kept track of.
425
426@itemize @bullet
427
428@item
429To see how large your stack frame is, just check the value of the
430stack pointer register; if it's the original value of the SP
431minus a constant, then that constant is the stack frame's size.
432If the SP's value has been marked as ``unknown'', then that means
433the prologue has done something too complex for us to track, and
434we don't know the frame size.
435
436@item
437To see where we've saved the previous frame's registers, we just
438search the values we've tracked --- stack slots, usually, but
439registers, too, if you want --- for something equal to the register's
440original value. If the calling conventions suggest a standard place
441to save a given register, then we can check there first, but really,
442anything that will get us back the original value will probably work.
443@end itemize
444
445This does take some work. But prologue analyzers aren't
446quick-and-simple pattern patching to recognize a few fixed prologue
447forms any more; they're big, hairy functions. Along with inferior
448function calls, prologue analysis accounts for a substantial portion
449of the time needed to stabilize a @value{GDBN} port. So it's
450worthwhile to look for an approach that will be easier to understand
451and maintain. In the approach described above:
452
453@itemize @bullet
454
455@item
456It's easier to see that the analyzer is correct: you just see
b247355e 457whether the analyzer properly (albeit conservatively) simulates
7d30c22d
JB
458the effect of each instruction.
459
460@item
461It's easier to extend the analyzer: you can add support for new
462instructions, and know that you haven't broken anything that
463wasn't already broken before.
464
465@item
466It's orthogonal: to gather new information, you don't need to
467complicate the code for each instruction. As long as your domain
468of conservative values is already detailed enough to tell you
469what you need, then all the existing instruction simulations are
470already gathering the right data for you.
471
472@end itemize
473
474The file @file{prologue-value.h} contains detailed comments explaining
475the framework and how to use it.
476
477
c906108c
SS
478@section Breakpoint Handling
479
56caf160 480@cindex breakpoints
c906108c
SS
481In general, a breakpoint is a user-designated location in the program
482where the user wants to regain control if program execution ever reaches
483that location.
484
485There are two main ways to implement breakpoints; either as ``hardware''
486breakpoints or as ``software'' breakpoints.
487
56caf160
EZ
488@cindex hardware breakpoints
489@cindex program counter
c906108c
SS
490Hardware breakpoints are sometimes available as a builtin debugging
491features with some chips. Typically these work by having dedicated
492register into which the breakpoint address may be stored. If the PC
56caf160 493(shorthand for @dfn{program counter})
c906108c 494ever matches a value in a breakpoint registers, the CPU raises an
56caf160
EZ
495exception and reports it to @value{GDBN}.
496
497Another possibility is when an emulator is in use; many emulators
498include circuitry that watches the address lines coming out from the
499processor, and force it to stop if the address matches a breakpoint's
500address.
501
502A third possibility is that the target already has the ability to do
503breakpoints somehow; for instance, a ROM monitor may do its own
504software breakpoints. So although these are not literally ``hardware
505breakpoints'', from @value{GDBN}'s point of view they work the same;
50e3ee83 506@value{GDBN} need not do anything more than set the breakpoint and wait
56caf160 507for something to happen.
c906108c
SS
508
509Since they depend on hardware resources, hardware breakpoints may be
56caf160 510limited in number; when the user asks for more, @value{GDBN} will
9742079a 511start trying to set software breakpoints. (On some architectures,
937f164b 512notably the 32-bit x86 platforms, @value{GDBN} cannot always know
9742079a
EZ
513whether there's enough hardware resources to insert all the hardware
514breakpoints and watchpoints. On those platforms, @value{GDBN} prints
515an error message only when the program being debugged is continued.)
56caf160
EZ
516
517@cindex software breakpoints
518Software breakpoints require @value{GDBN} to do somewhat more work.
519The basic theory is that @value{GDBN} will replace a program
520instruction with a trap, illegal divide, or some other instruction
521that will cause an exception, and then when it's encountered,
522@value{GDBN} will take the exception and stop the program. When the
523user says to continue, @value{GDBN} will restore the original
c906108c
SS
524instruction, single-step, re-insert the trap, and continue on.
525
526Since it literally overwrites the program being tested, the program area
be9c6c35 527must be writable, so this technique won't work on programs in ROM. It
c906108c 528can also distort the behavior of programs that examine themselves,
56caf160 529although such a situation would be highly unusual.
c906108c
SS
530
531Also, the software breakpoint instruction should be the smallest size of
532instruction, so it doesn't overwrite an instruction that might be a jump
533target, and cause disaster when the program jumps into the middle of the
534breakpoint instruction. (Strictly speaking, the breakpoint must be no
535larger than the smallest interval between instructions that may be jump
536targets; perhaps there is an architecture where only even-numbered
537instructions may jumped to.) Note that it's possible for an instruction
538set not to have any instructions usable for a software breakpoint,
539although in practice only the ARC has failed to define such an
540instruction.
541
56caf160 542@findex BREAKPOINT
c906108c
SS
543The basic definition of the software breakpoint is the macro
544@code{BREAKPOINT}.
545
546Basic breakpoint object handling is in @file{breakpoint.c}. However,
547much of the interesting breakpoint action is in @file{infrun.c}.
548
8181d85f
DJ
549@table @code
550@cindex insert or remove software breakpoint
551@findex target_remove_breakpoint
552@findex target_insert_breakpoint
553@item target_remove_breakpoint (@var{bp_tgt})
554@itemx target_insert_breakpoint (@var{bp_tgt})
555Insert or remove a software breakpoint at address
556@code{@var{bp_tgt}->placed_address}. Returns zero for success,
557non-zero for failure. On input, @var{bp_tgt} contains the address of the
558breakpoint, and is otherwise initialized to zero. The fields of the
559@code{struct bp_target_info} pointed to by @var{bp_tgt} are updated
560to contain other information about the breakpoint on output. The field
561@code{placed_address} may be updated if the breakpoint was placed at a
562related address; the field @code{shadow_contents} contains the real
563contents of the bytes where the breakpoint has been inserted,
564if reading memory would return the breakpoint instead of the
565underlying memory; the field @code{shadow_len} is the length of
566memory cached in @code{shadow_contents}, if any; and the field
567@code{placed_size} is optionally set and used by the target, if
568it could differ from @code{shadow_len}.
569
570For example, the remote target @samp{Z0} packet does not require
571shadowing memory, so @code{shadow_len} is left at zero. However,
4a9bb1df 572the length reported by @code{gdbarch_breakpoint_from_pc} is cached in
8181d85f
DJ
573@code{placed_size}, so that a matching @samp{z0} packet can be
574used to remove the breakpoint.
575
576@cindex insert or remove hardware breakpoint
577@findex target_remove_hw_breakpoint
578@findex target_insert_hw_breakpoint
579@item target_remove_hw_breakpoint (@var{bp_tgt})
580@itemx target_insert_hw_breakpoint (@var{bp_tgt})
581Insert or remove a hardware-assisted breakpoint at address
582@code{@var{bp_tgt}->placed_address}. Returns zero for success,
583non-zero for failure. See @code{target_insert_breakpoint} for
584a description of the @code{struct bp_target_info} pointed to by
585@var{bp_tgt}; the @code{shadow_contents} and
586@code{shadow_len} members are not used for hardware breakpoints,
587but @code{placed_size} may be.
588@end table
589
c906108c
SS
590@section Single Stepping
591
592@section Signal Handling
593
594@section Thread Handling
595
596@section Inferior Function Calls
597
598@section Longjmp Support
599
56caf160 600@cindex @code{longjmp} debugging
25822942 601@value{GDBN} has support for figuring out that the target is doing a
c906108c
SS
602@code{longjmp} and for stopping at the target of the jump, if we are
603stepping. This is done with a few specialized internal breakpoints,
56caf160
EZ
604which are visible in the output of the @samp{maint info breakpoint}
605command.
c906108c 606
4a9bb1df
UW
607@findex gdbarch_get_longjmp_target
608To make this work, you need to define a function called
609@code{gdbarch_get_longjmp_target}, which will examine the @code{jmp_buf}
c906108c
SS
610structure and extract the longjmp target address. Since @code{jmp_buf}
611is target specific, you will need to define it in the appropriate
56caf160 612@file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and
c906108c
SS
613@file{sparc-tdep.c} for examples of how to do this.
614
9742079a
EZ
615@section Watchpoints
616@cindex watchpoints
617
618Watchpoints are a special kind of breakpoints (@pxref{Algorithms,
619breakpoints}) which break when data is accessed rather than when some
620instruction is executed. When you have data which changes without
621your knowing what code does that, watchpoints are the silver bullet to
622hunt down and kill such bugs.
623
624@cindex hardware watchpoints
625@cindex software watchpoints
626Watchpoints can be either hardware-assisted or not; the latter type is
627known as ``software watchpoints.'' @value{GDBN} always uses
628hardware-assisted watchpoints if they are available, and falls back on
629software watchpoints otherwise. Typical situations where @value{GDBN}
630will use software watchpoints are:
631
632@itemize @bullet
633@item
634The watched memory region is too large for the underlying hardware
635watchpoint support. For example, each x86 debug register can watch up
636to 4 bytes of memory, so trying to watch data structures whose size is
637more than 16 bytes will cause @value{GDBN} to use software
638watchpoints.
639
640@item
641The value of the expression to be watched depends on data held in
642registers (as opposed to memory).
643
644@item
645Too many different watchpoints requested. (On some architectures,
646this situation is impossible to detect until the debugged program is
647resumed.) Note that x86 debug registers are used both for hardware
648breakpoints and for watchpoints, so setting too many hardware
649breakpoints might cause watchpoint insertion to fail.
650
651@item
652No hardware-assisted watchpoints provided by the target
653implementation.
654@end itemize
655
656Software watchpoints are very slow, since @value{GDBN} needs to
657single-step the program being debugged and test the value of the
658watched expression(s) after each instruction. The rest of this
659section is mostly irrelevant for software watchpoints.
660
b6b8ece6
EZ
661When the inferior stops, @value{GDBN} tries to establish, among other
662possible reasons, whether it stopped due to a watchpoint being hit.
d983da9c
DJ
663It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint
664was hit. If not, all watchpoint checking is skipped.
665
666Then @value{GDBN} calls @code{target_stopped_data_address} exactly
667once. This method returns the address of the watchpoint which
668triggered, if the target can determine it. If the triggered address
669is available, @value{GDBN} compares the address returned by this
670method with each watched memory address in each active watchpoint.
671For data-read and data-access watchpoints, @value{GDBN} announces
672every watchpoint that watches the triggered address as being hit.
673For this reason, data-read and data-access watchpoints
674@emph{require} that the triggered address be available; if not, read
675and access watchpoints will never be considered hit. For data-write
676watchpoints, if the triggered address is available, @value{GDBN}
677considers only those watchpoints which match that address;
678otherwise, @value{GDBN} considers all data-write watchpoints. For
679each data-write watchpoint that @value{GDBN} considers, it evaluates
680the expression whose value is being watched, and tests whether the
681watched value has changed. Watchpoints whose watched values have
682changed are announced as hit.
b6b8ece6 683
9742079a
EZ
684@value{GDBN} uses several macros and primitives to support hardware
685watchpoints:
686
687@table @code
688@findex TARGET_HAS_HARDWARE_WATCHPOINTS
689@item TARGET_HAS_HARDWARE_WATCHPOINTS
690If defined, the target supports hardware watchpoints.
691
692@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
693@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
694Return the number of hardware watchpoints of type @var{type} that are
695possible to be set. The value is positive if @var{count} watchpoints
696of this type can be set, zero if setting watchpoints of this type is
697not supported, and negative if @var{count} is more than the maximum
698number of watchpoints of type @var{type} that can be set. @var{other}
699is non-zero if other types of watchpoints are currently enabled (there
700are architectures which cannot set watchpoints of different types at
701the same time).
702
703@findex TARGET_REGION_OK_FOR_HW_WATCHPOINT
704@item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len})
705Return non-zero if hardware watchpoints can be used to watch a region
706whose address is @var{addr} and whose length in bytes is @var{len}.
707
b6b8ece6 708@cindex insert or remove hardware watchpoint
9742079a
EZ
709@findex target_insert_watchpoint
710@findex target_remove_watchpoint
711@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
712@itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type})
713Insert or remove a hardware watchpoint starting at @var{addr}, for
714@var{len} bytes. @var{type} is the watchpoint type, one of the
715possible values of the enumerated data type @code{target_hw_bp_type},
716defined by @file{breakpoint.h} as follows:
717
474c8240 718@smallexample
9742079a
EZ
719 enum target_hw_bp_type
720 @{
721 hw_write = 0, /* Common (write) HW watchpoint */
722 hw_read = 1, /* Read HW watchpoint */
723 hw_access = 2, /* Access (read or write) HW watchpoint */
724 hw_execute = 3 /* Execute HW breakpoint */
725 @};
474c8240 726@end smallexample
9742079a
EZ
727
728@noindent
729These two macros should return 0 for success, non-zero for failure.
730
9742079a 731@findex target_stopped_data_address
ac77d04f
JJ
732@item target_stopped_data_address (@var{addr_p})
733If the inferior has some watchpoint that triggered, place the address
734associated with the watchpoint at the location pointed to by
d983da9c
DJ
735@var{addr_p} and return non-zero. Otherwise, return zero. This
736is required for data-read and data-access watchpoints. It is
737not required for data-write watchpoints, but @value{GDBN} uses
738it to improve handling of those also.
739
740@value{GDBN} will only call this method once per watchpoint stop,
741immediately after calling @code{STOPPED_BY_WATCHPOINT}. If the
742target's watchpoint indication is sticky, i.e., stays set after
743resuming, this method should clear it. For instance, the x86 debug
744control register has sticky triggered flags.
9742079a 745
9742079a
EZ
746@findex HAVE_STEPPABLE_WATCHPOINT
747@item HAVE_STEPPABLE_WATCHPOINT
748If defined to a non-zero value, it is not necessary to disable a
d983da9c
DJ
749watchpoint to step over it. Like @code{gdbarch_have_nonsteppable_watchpoint},
750this is usually set when watchpoints trigger at the instruction
751which will perform an interesting read or write. It should be
752set if there is a temporary disable bit which allows the processor
753to step over the interesting instruction without raising the
754watchpoint exception again.
9742079a 755
4a9bb1df
UW
756@findex gdbarch_have_nonsteppable_watchpoint
757@item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch})
758If it returns a non-zero value, @value{GDBN} should disable a
d983da9c
DJ
759watchpoint to step the inferior over it. This is usually set when
760watchpoints trigger at the instruction which will perform an
761interesting read or write.
9742079a
EZ
762
763@findex HAVE_CONTINUABLE_WATCHPOINT
764@item HAVE_CONTINUABLE_WATCHPOINT
765If defined to a non-zero value, it is possible to continue the
d983da9c
DJ
766inferior after a watchpoint has been hit. This is usually set
767when watchpoints trigger at the instruction following an interesting
768read or write.
9742079a
EZ
769
770@findex CANNOT_STEP_HW_WATCHPOINTS
771@item CANNOT_STEP_HW_WATCHPOINTS
772If this is defined to a non-zero value, @value{GDBN} will remove all
773watchpoints before stepping the inferior.
774
775@findex STOPPED_BY_WATCHPOINT
776@item STOPPED_BY_WATCHPOINT (@var{wait_status})
777Return non-zero if stopped by a watchpoint. @var{wait_status} is of
778the type @code{struct target_waitstatus}, defined by @file{target.h}.
b6b8ece6
EZ
779Normally, this macro is defined to invoke the function pointed to by
780the @code{to_stopped_by_watchpoint} member of the structure (of the
781type @code{target_ops}, defined on @file{target.h}) that describes the
782target-specific operations; @code{to_stopped_by_watchpoint} ignores
783the @var{wait_status} argument.
784
785@value{GDBN} does not require the non-zero value returned by
786@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot
787determine for sure whether the inferior stopped due to a watchpoint,
788it could return non-zero ``just in case''.
9742079a
EZ
789@end table
790
d983da9c
DJ
791@subsection Watchpoints and Threads
792@cindex watchpoints, with threads
793
794@value{GDBN} only supports process-wide watchpoints, which trigger
795in all threads. @value{GDBN} uses the thread ID to make watchpoints
796act as if they were thread-specific, but it cannot set hardware
797watchpoints that only trigger in a specific thread. Therefore, even
798if the target supports threads, per-thread debug registers, and
799watchpoints which only affect a single thread, it should set the
800per-thread debug registers for all threads to the same value. On
801@sc{gnu}/Linux native targets, this is accomplished by using
802@code{ALL_LWPS} in @code{target_insert_watchpoint} and
803@code{target_remove_watchpoint} and by using
804@code{linux_set_new_thread} to register a handler for newly created
805threads.
806
807@value{GDBN}'s @sc{gnu}/Linux support only reports a single event
808at a time, although multiple events can trigger simultaneously for
809multi-threaded programs. When multiple events occur, @file{linux-nat.c}
810queues subsequent events and returns them the next time the program
811is resumed. This means that @code{STOPPED_BY_WATCHPOINT} and
812@code{target_stopped_data_address} only need to consult the current
813thread's state---the thread indicated by @code{inferior_ptid}. If
814two threads have hit watchpoints simultaneously, those routines
815will be called a second time for the second thread.
816
9742079a
EZ
817@subsection x86 Watchpoints
818@cindex x86 debug registers
819@cindex watchpoints, on x86
820
821The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug
822registers designed to facilitate debugging. @value{GDBN} provides a
823generic library of functions that x86-based ports can use to implement
824support for watchpoints and hardware-assisted breakpoints. This
825subsection documents the x86 watchpoint facilities in @value{GDBN}.
826
827To use the generic x86 watchpoint support, a port should do the
828following:
829
830@itemize @bullet
831@findex I386_USE_GENERIC_WATCHPOINTS
832@item
833Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the
834target-dependent headers.
835
836@item
837Include the @file{config/i386/nm-i386.h} header file @emph{after}
838defining @code{I386_USE_GENERIC_WATCHPOINTS}.
839
840@item
841Add @file{i386-nat.o} to the value of the Make variable
842@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or
843@code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}).
844
845@item
846Provide implementations for the @code{I386_DR_LOW_*} macros described
847below. Typically, each macro should call a target-specific function
848which does the real work.
849@end itemize
850
851The x86 watchpoint support works by maintaining mirror images of the
852debug registers. Values are copied between the mirror images and the
853real debug registers via a set of macros which each target needs to
854provide:
855
856@table @code
857@findex I386_DR_LOW_SET_CONTROL
858@item I386_DR_LOW_SET_CONTROL (@var{val})
859Set the Debug Control (DR7) register to the value @var{val}.
860
861@findex I386_DR_LOW_SET_ADDR
862@item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr})
863Put the address @var{addr} into the debug register number @var{idx}.
864
865@findex I386_DR_LOW_RESET_ADDR
866@item I386_DR_LOW_RESET_ADDR (@var{idx})
867Reset (i.e.@: zero out) the address stored in the debug register
868number @var{idx}.
869
870@findex I386_DR_LOW_GET_STATUS
871@item I386_DR_LOW_GET_STATUS
872Return the value of the Debug Status (DR6) register. This value is
873used immediately after it is returned by
874@code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status
875register values.
876@end table
877
878For each one of the 4 debug registers (whose indices are from 0 to 3)
879that store addresses, a reference count is maintained by @value{GDBN},
880to allow sharing of debug registers by several watchpoints. This
881allows users to define several watchpoints that watch the same
882expression, but with different conditions and/or commands, without
883wasting debug registers which are in short supply. @value{GDBN}
884maintains the reference counts internally, targets don't have to do
885anything to use this feature.
886
887The x86 debug registers can each watch a region that is 1, 2, or 4
888bytes long. The ia32 architecture requires that each watched region
889be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte
890region on 4-byte boundary. However, the x86 watchpoint support in
891@value{GDBN} can watch unaligned regions and regions larger than 4
892bytes (up to 16 bytes) by allocating several debug registers to watch
893a single region. This allocation of several registers per a watched
894region is also done automatically without target code intervention.
895
896The generic x86 watchpoint support provides the following API for the
897@value{GDBN}'s application code:
898
899@table @code
900@findex i386_region_ok_for_watchpoint
901@item i386_region_ok_for_watchpoint (@var{addr}, @var{len})
902The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call
903this function. It counts the number of debug registers required to
904watch a given region, and returns a non-zero value if that number is
905less than 4, the number of debug registers available to x86
906processors.
907
908@findex i386_stopped_data_address
ac77d04f
JJ
909@item i386_stopped_data_address (@var{addr_p})
910The target function
911@code{target_stopped_data_address} is set to call this function.
912This
9742079a
EZ
913function examines the breakpoint condition bits in the DR6 Debug
914Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
915macro, and returns the address associated with the first bit that is
916set in DR6.
917
ac77d04f
JJ
918@findex i386_stopped_by_watchpoint
919@item i386_stopped_by_watchpoint (void)
920The macro @code{STOPPED_BY_WATCHPOINT}
921is set to call this function. The
922argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
923function examines the breakpoint condition bits in the DR6 Debug
924Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
925macro, and returns true if any bit is set. Otherwise, false is
926returned.
927
9742079a
EZ
928@findex i386_insert_watchpoint
929@findex i386_remove_watchpoint
930@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
931@itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type})
932Insert or remove a watchpoint. The macros
933@code{target_insert_watchpoint} and @code{target_remove_watchpoint}
934are set to call these functions. @code{i386_insert_watchpoint} first
935looks for a debug register which is already set to watch the same
936region for the same access types; if found, it just increments the
937reference count of that debug register, thus implementing debug
938register sharing between watchpoints. If no such register is found,
937f164b
FF
939the function looks for a vacant debug register, sets its mirrored
940value to @var{addr}, sets the mirrored value of DR7 Debug Control
9742079a
EZ
941register as appropriate for the @var{len} and @var{type} parameters,
942and then passes the new values of the debug register and DR7 to the
943inferior by calling @code{I386_DR_LOW_SET_ADDR} and
944@code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is
945required to cover the given region, the above process is repeated for
946each debug register.
947
948@code{i386_remove_watchpoint} does the opposite: it resets the address
937f164b
FF
949in the mirrored value of the debug register and its read/write and
950length bits in the mirrored value of DR7, then passes these new
9742079a
EZ
951values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and
952@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several
953watchpoints, each time a @code{i386_remove_watchpoint} is called, it
954decrements the reference count, and only calls
955@code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when
956the count goes to zero.
957
958@findex i386_insert_hw_breakpoint
959@findex i386_remove_hw_breakpoint
8181d85f
DJ
960@item i386_insert_hw_breakpoint (@var{bp_tgt})
961@itemx i386_remove_hw_breakpoint (@var{bp_tgt})
9742079a
EZ
962These functions insert and remove hardware-assisted breakpoints. The
963macros @code{target_insert_hw_breakpoint} and
964@code{target_remove_hw_breakpoint} are set to call these functions.
8181d85f
DJ
965The argument is a @code{struct bp_target_info *}, as described in
966the documentation for @code{target_insert_breakpoint}.
9742079a
EZ
967These functions work like @code{i386_insert_watchpoint} and
968@code{i386_remove_watchpoint}, respectively, except that they set up
969the debug registers to watch instruction execution, and each
970hardware-assisted breakpoint always requires exactly one debug
971register.
972
973@findex i386_stopped_by_hwbp
974@item i386_stopped_by_hwbp (void)
975This function returns non-zero if the inferior has some watchpoint or
976hardware breakpoint that triggered. It works like
ac77d04f 977@code{i386_stopped_data_address}, except that it doesn't record the
9742079a
EZ
978address whose watchpoint triggered.
979
980@findex i386_cleanup_dregs
981@item i386_cleanup_dregs (void)
982This function clears all the reference counts, addresses, and control
983bits in the mirror images of the debug registers. It doesn't affect
984the actual debug registers in the inferior process.
985@end table
986
987@noindent
988@strong{Notes:}
989@enumerate 1
990@item
991x86 processors support setting watchpoints on I/O reads or writes.
992However, since no target supports this (as of March 2001), and since
993@code{enum target_hw_bp_type} doesn't even have an enumeration for I/O
994watchpoints, this feature is not yet available to @value{GDBN} running
995on x86.
996
997@item
998x86 processors can enable watchpoints locally, for the current task
999only, or globally, for all the tasks. For each debug register,
1000there's a bit in the DR7 Debug Control register that determines
1001whether the associated address is watched locally or globally. The
1002current implementation of x86 watchpoint support in @value{GDBN}
1003always sets watchpoints to be locally enabled, since global
1004watchpoints might interfere with the underlying OS and are probably
1005unavailable in many platforms.
1006@end enumerate
1007
5c95884b
MS
1008@section Checkpoints
1009@cindex checkpoints
1010@cindex restart
1011In the abstract, a checkpoint is a point in the execution history of
1012the program, which the user may wish to return to at some later time.
1013
1014Internally, a checkpoint is a saved copy of the program state, including
1015whatever information is required in order to restore the program to that
1016state at a later time. This can be expected to include the state of
1017registers and memory, and may include external state such as the state
1018of open files and devices.
1019
1020There are a number of ways in which checkpoints may be implemented
b247355e 1021in gdb, e.g.@: as corefiles, as forked processes, and as some opaque
5c95884b
MS
1022method implemented on the target side.
1023
1024A corefile can be used to save an image of target memory and register
1025state, which can in principle be restored later --- but corefiles do
1026not typically include information about external entities such as
1027open files. Currently this method is not implemented in gdb.
1028
1029A forked process can save the state of user memory and registers,
1030as well as some subset of external (kernel) state. This method
1031is used to implement checkpoints on Linux, and in principle might
1032be used on other systems.
1033
b247355e 1034Some targets, e.g.@: simulators, might have their own built-in
5c95884b
MS
1035method for saving checkpoints, and gdb might be able to take
1036advantage of that capability without necessarily knowing any
1037details of how it is done.
1038
1039
bcd7e15f
JB
1040@section Observing changes in @value{GDBN} internals
1041@cindex observer pattern interface
1042@cindex notifications about changes in internals
1043
1044In order to function properly, several modules need to be notified when
1045some changes occur in the @value{GDBN} internals. Traditionally, these
1046modules have relied on several paradigms, the most common ones being
1047hooks and gdb-events. Unfortunately, none of these paradigms was
1048versatile enough to become the standard notification mechanism in
1049@value{GDBN}. The fact that they only supported one ``client'' was also
1050a strong limitation.
1051
1052A new paradigm, based on the Observer pattern of the @cite{Design
1053Patterns} book, has therefore been implemented. The goal was to provide
1054a new interface overcoming the issues with the notification mechanisms
1055previously available. This new interface needed to be strongly typed,
1056easy to extend, and versatile enough to be used as the standard
1057interface when adding new notifications.
1058
1059See @ref{GDB Observers} for a brief description of the observers
1060currently implemented in GDB. The rationale for the current
1061implementation is also briefly discussed.
1062
c906108c
SS
1063@node User Interface
1064
1065@chapter User Interface
1066
25822942 1067@value{GDBN} has several user interfaces. Although the command-line interface
c906108c
SS
1068is the most common and most familiar, there are others.
1069
1070@section Command Interpreter
1071
56caf160 1072@cindex command interpreter
0ee54786 1073@cindex CLI
25822942 1074The command interpreter in @value{GDBN} is fairly simple. It is designed to
c906108c
SS
1075allow for the set of commands to be augmented dynamically, and also
1076has a recursive subcommand capability, where the first argument to
1077a command may itself direct a lookup on a different command list.
1078
56caf160
EZ
1079For instance, the @samp{set} command just starts a lookup on the
1080@code{setlist} command list, while @samp{set thread} recurses
c906108c
SS
1081to the @code{set_thread_cmd_list}.
1082
56caf160
EZ
1083@findex add_cmd
1084@findex add_com
c906108c
SS
1085To add commands in general, use @code{add_cmd}. @code{add_com} adds to
1086the main command list, and should be used for those commands. The usual
cfeada60 1087place to add commands is in the @code{_initialize_@var{xyz}} routines at
9742079a 1088the ends of most source files.
cfeada60 1089
40dd2248
TT
1090@findex add_setshow_cmd
1091@findex add_setshow_cmd_full
1092To add paired @samp{set} and @samp{show} commands, use
1093@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is
1094a slightly simpler interface which is useful when you don't need to
1095further modify the new command structures, while the latter returns
1096the new command structures for manipulation.
1097
56caf160
EZ
1098@cindex deprecating commands
1099@findex deprecate_cmd
cfeada60
FN
1100Before removing commands from the command set it is a good idea to
1101deprecate them for some time. Use @code{deprecate_cmd} on commands or
1102aliases to set the deprecated flag. @code{deprecate_cmd} takes a
1103@code{struct cmd_list_element} as it's first argument. You can use the
1104return value from @code{add_com} or @code{add_cmd} to deprecate the
1105command immediately after it is created.
1106
c72e7388 1107The first time a command is used the user will be warned and offered a
cfeada60 1108replacement (if one exists). Note that the replacement string passed to
d3e8051b 1109@code{deprecate_cmd} should be the full name of the command, i.e., the
cfeada60 1110entire string the user should type at the command line.
c906108c 1111
0ee54786
EZ
1112@section UI-Independent Output---the @code{ui_out} Functions
1113@c This section is based on the documentation written by Fernando
1114@c Nasser <fnasser@redhat.com>.
1115
1116@cindex @code{ui_out} functions
1117The @code{ui_out} functions present an abstraction level for the
1118@value{GDBN} output code. They hide the specifics of different user
1119interfaces supported by @value{GDBN}, and thus free the programmer
1120from the need to write several versions of the same code, one each for
1121every UI, to produce output.
1122
1123@subsection Overview and Terminology
1124
1125In general, execution of each @value{GDBN} command produces some sort
1126of output, and can even generate an input request.
1127
1128Output can be generated for the following purposes:
1129
1130@itemize @bullet
1131@item
1132to display a @emph{result} of an operation;
1133
1134@item
1135to convey @emph{info} or produce side-effects of a requested
1136operation;
1137
1138@item
1139to provide a @emph{notification} of an asynchronous event (including
1140progress indication of a prolonged asynchronous operation);
1141
1142@item
1143to display @emph{error messages} (including warnings);
1144
1145@item
1146to show @emph{debug data};
1147
1148@item
1149to @emph{query} or prompt a user for input (a special case).
1150@end itemize
1151
1152@noindent
1153This section mainly concentrates on how to build result output,
1154although some of it also applies to other kinds of output.
1155
1156Generation of output that displays the results of an operation
1157involves one or more of the following:
1158
1159@itemize @bullet
1160@item
1161output of the actual data
1162
1163@item
1164formatting the output as appropriate for console output, to make it
1165easily readable by humans
1166
1167@item
1168machine oriented formatting--a more terse formatting to allow for easy
1169parsing by programs which read @value{GDBN}'s output
1170
1171@item
c72e7388
AC
1172annotation, whose purpose is to help legacy GUIs to identify interesting
1173parts in the output
0ee54786
EZ
1174@end itemize
1175
1176The @code{ui_out} routines take care of the first three aspects.
c72e7388
AC
1177Annotations are provided by separate annotation routines. Note that use
1178of annotations for an interface between a GUI and @value{GDBN} is
0ee54786
EZ
1179deprecated.
1180
c72e7388
AC
1181Output can be in the form of a single item, which we call a @dfn{field};
1182a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
1183non-identical fields; or a @dfn{table}, which is a tuple consisting of a
1184header and a body. In a BNF-like form:
0ee54786 1185
c72e7388
AC
1186@table @code
1187@item <table> @expansion{}
1188@code{<header> <body>}
1189@item <header> @expansion{}
1190@code{@{ <column> @}}
1191@item <column> @expansion{}
1192@code{<width> <alignment> <title>}
1193@item <body> @expansion{}
1194@code{@{<row>@}}
1195@end table
0ee54786
EZ
1196
1197
1198@subsection General Conventions
1199
c72e7388
AC
1200Most @code{ui_out} routines are of type @code{void}, the exceptions are
1201@code{ui_out_stream_new} (which returns a pointer to the newly created
1202object) and the @code{make_cleanup} routines.
0ee54786 1203
c72e7388
AC
1204The first parameter is always the @code{ui_out} vector object, a pointer
1205to a @code{struct ui_out}.
0ee54786 1206
c72e7388
AC
1207The @var{format} parameter is like in @code{printf} family of functions.
1208When it is present, there must also be a variable list of arguments
1209sufficient used to satisfy the @code{%} specifiers in the supplied
0ee54786
EZ
1210format.
1211
c72e7388
AC
1212When a character string argument is not used in a @code{ui_out} function
1213call, a @code{NULL} pointer has to be supplied instead.
0ee54786
EZ
1214
1215
c72e7388 1216@subsection Table, Tuple and List Functions
0ee54786
EZ
1217
1218@cindex list output functions
1219@cindex table output functions
c72e7388
AC
1220@cindex tuple output functions
1221This section introduces @code{ui_out} routines for building lists,
1222tuples and tables. The routines to output the actual data items
1223(fields) are presented in the next section.
0ee54786 1224
c72e7388
AC
1225To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
1226containing information about an object; a @dfn{list} is a sequence of
1227fields where each field describes an identical object.
0ee54786 1228
c72e7388
AC
1229Use the @dfn{table} functions when your output consists of a list of
1230rows (tuples) and the console output should include a heading. Use this
1231even when you are listing just one object but you still want the header.
0ee54786
EZ
1232
1233@cindex nesting level in @code{ui_out} functions
c72e7388
AC
1234Tables can not be nested. Tuples and lists can be nested up to a
1235maximum of five levels.
0ee54786
EZ
1236
1237The overall structure of the table output code is something like this:
1238
474c8240 1239@smallexample
0ee54786
EZ
1240 ui_out_table_begin
1241 ui_out_table_header
c72e7388 1242 @dots{}
0ee54786 1243 ui_out_table_body
c72e7388 1244 ui_out_tuple_begin
0ee54786 1245 ui_out_field_*
c72e7388
AC
1246 @dots{}
1247 ui_out_tuple_end
1248 @dots{}
0ee54786 1249 ui_out_table_end
474c8240 1250@end smallexample
0ee54786 1251
c72e7388 1252Here is the description of table-, tuple- and list-related @code{ui_out}
0ee54786
EZ
1253functions:
1254
c72e7388
AC
1255@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
1256The function @code{ui_out_table_begin} marks the beginning of the output
1257of a table. It should always be called before any other @code{ui_out}
1258function for a given table. @var{nbrofcols} is the number of columns in
1259the table. @var{nr_rows} is the number of rows in the table.
1260@var{tblid} is an optional string identifying the table. The string
1261pointed to by @var{tblid} is copied by the implementation of
1262@code{ui_out_table_begin}, so the application can free the string if it
1263was @code{malloc}ed.
0ee54786
EZ
1264
1265The companion function @code{ui_out_table_end}, described below, marks
1266the end of the table's output.
1267@end deftypefun
1268
c72e7388
AC
1269@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})
1270@code{ui_out_table_header} provides the header information for a single
1271table column. You call this function several times, one each for every
1272column of the table, after @code{ui_out_table_begin}, but before
1273@code{ui_out_table_body}.
0ee54786
EZ
1274
1275The value of @var{width} gives the column width in characters. The
1276value of @var{alignment} is one of @code{left}, @code{center}, and
1277@code{right}, and it specifies how to align the header: left-justify,
1278center, or right-justify it. @var{colhdr} points to a string that
1279specifies the column header; the implementation copies that string, so
c72e7388
AC
1280column header strings in @code{malloc}ed storage can be freed after the
1281call.
0ee54786
EZ
1282@end deftypefun
1283
1284@deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
c72e7388 1285This function delimits the table header from the table body.
0ee54786
EZ
1286@end deftypefun
1287
1288@deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
c72e7388
AC
1289This function signals the end of a table's output. It should be called
1290after the table body has been produced by the list and field output
1291functions.
0ee54786
EZ
1292
1293There should be exactly one call to @code{ui_out_table_end} for each
c72e7388
AC
1294call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
1295will signal an internal error.
0ee54786
EZ
1296@end deftypefun
1297
c72e7388 1298The output of the tuples that represent the table rows must follow the
0ee54786 1299call to @code{ui_out_table_body} and precede the call to
c72e7388
AC
1300@code{ui_out_table_end}. You build a tuple by calling
1301@code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
0ee54786
EZ
1302calls to functions which actually output fields between them.
1303
c72e7388
AC
1304@deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})
1305This function marks the beginning of a tuple output. @var{id} points
1306to an optional string that identifies the tuple; it is copied by the
1307implementation, and so strings in @code{malloc}ed storage can be freed
1308after the call.
1309@end deftypefun
1310
1311@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
1312This function signals an end of a tuple output. There should be exactly
1313one call to @code{ui_out_tuple_end} for each call to
1314@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
1315be signaled.
1316@end deftypefun
1317
1318@deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
1319This function first opens the tuple and then establishes a cleanup
1320(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient
1321and correct implementation of the non-portable@footnote{The function
b9aa90c9 1322cast is not portable ISO C.} code sequence:
c72e7388
AC
1323@smallexample
1324struct cleanup *old_cleanup;
1325ui_out_tuple_begin (uiout, "...");
1326old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
1327 uiout);
1328@end smallexample
1329@end deftypefun
1330
1331@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})
1332This function marks the beginning of a list output. @var{id} points to
1333an optional string that identifies the list; it is copied by the
1334implementation, and so strings in @code{malloc}ed storage can be freed
1335after the call.
0ee54786
EZ
1336@end deftypefun
1337
1338@deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
c72e7388
AC
1339This function signals an end of a list output. There should be exactly
1340one call to @code{ui_out_list_end} for each call to
1341@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
1342be signaled.
1343@end deftypefun
1344
1345@deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
1346Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
1347opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
f66d1690 1348that will close the list.
0ee54786
EZ
1349@end deftypefun
1350
1351@subsection Item Output Functions
1352
1353@cindex item output functions
1354@cindex field output functions
1355@cindex data output
1356The functions described below produce output for the actual data
1357items, or fields, which contain information about the object.
1358
1359Choose the appropriate function accordingly to your particular needs.
1360
1361@deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...)
1362This is the most general output function. It produces the
1363representation of the data in the variable-length argument list
1364according to formatting specifications in @var{format}, a
1365@code{printf}-like format string. The optional argument @var{fldname}
1366supplies the name of the field. The data items themselves are
1367supplied as additional arguments after @var{format}.
1368
1369This generic function should be used only when it is not possible to
1370use one of the specialized versions (see below).
1371@end deftypefun
1372
c72e7388 1373@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
0ee54786
EZ
1374This function outputs a value of an @code{int} variable. It uses the
1375@code{"%d"} output conversion specification. @var{fldname} specifies
1376the name of the field.
1377@end deftypefun
8d19fbd2
JJ
1378
1379@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})
1380This function outputs a value of an @code{int} variable. It differs from
1381@code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output.
1382@var{fldname} specifies
1383the name of the field.
1384@end deftypefun
0ee54786 1385
c72e7388 1386@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
0ee54786
EZ
1387This function outputs an address.
1388@end deftypefun
1389
c72e7388 1390@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
0ee54786
EZ
1391This function outputs a string using the @code{"%s"} conversion
1392specification.
1393@end deftypefun
1394
1395Sometimes, there's a need to compose your output piece by piece using
1396functions that operate on a stream, such as @code{value_print} or
1397@code{fprintf_symbol_filtered}. These functions accept an argument of
1398the type @code{struct ui_file *}, a pointer to a @code{ui_file} object
1399used to store the data stream used for the output. When you use one
1400of these functions, you need a way to pass their results stored in a
1401@code{ui_file} object to the @code{ui_out} functions. To this end,
1402you first create a @code{ui_stream} object by calling
1403@code{ui_out_stream_new}, pass the @code{stream} member of that
1404@code{ui_stream} object to @code{value_print} and similar functions,
1405and finally call @code{ui_out_field_stream} to output the field you
1406constructed. When the @code{ui_stream} object is no longer needed,
1407you should destroy it and free its memory by calling
1408@code{ui_out_stream_delete}.
1409
1410@deftypefun struct ui_stream *ui_out_stream_new (struct ui_out *@var{uiout})
1411This function creates a new @code{ui_stream} object which uses the
1412same output methods as the @code{ui_out} object whose pointer is
1413passed in @var{uiout}. It returns a pointer to the newly created
1414@code{ui_stream} object.
1415@end deftypefun
1416
1417@deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf})
1418This functions destroys a @code{ui_stream} object specified by
1419@var{streambuf}.
1420@end deftypefun
1421
c72e7388 1422@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
0ee54786
EZ
1423This function consumes all the data accumulated in
1424@code{streambuf->stream} and outputs it like
1425@code{ui_out_field_string} does. After a call to
1426@code{ui_out_field_stream}, the accumulated data no longer exists, but
1427the stream is still valid and may be used for producing more fields.
1428@end deftypefun
1429
1430@strong{Important:} If there is any chance that your code could bail
1431out before completing output generation and reaching the point where
1432@code{ui_out_stream_delete} is called, it is necessary to set up a
1433cleanup, to avoid leaking memory and other resources. Here's a
1434skeleton code to do that:
1435
1436@smallexample
1437 struct ui_stream *mybuf = ui_out_stream_new (uiout);
1438 struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
1439 ...
1440 do_cleanups (old);
1441@end smallexample
1442
1443If the function already has the old cleanup chain set (for other kinds
1444of cleanups), you just have to add your cleanup to it:
1445
1446@smallexample
1447 mybuf = ui_out_stream_new (uiout);
1448 make_cleanup (ui_out_stream_delete, mybuf);
1449@end smallexample
1450
1451Note that with cleanups in place, you should not call
1452@code{ui_out_stream_delete} directly, or you would attempt to free the
1453same buffer twice.
1454
1455@subsection Utility Output Functions
1456
c72e7388 1457@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
0ee54786
EZ
1458This function skips a field in a table. Use it if you have to leave
1459an empty field without disrupting the table alignment. The argument
1460@var{fldname} specifies a name for the (missing) filed.
1461@end deftypefun
1462
c72e7388 1463@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
0ee54786
EZ
1464This function outputs the text in @var{string} in a way that makes it
1465easy to be read by humans. For example, the console implementation of
1466this method filters the text through a built-in pager, to prevent it
1467from scrolling off the visible portion of the screen.
1468
1469Use this function for printing relatively long chunks of text around
1470the actual field data: the text it produces is not aligned according
1471to the table's format. Use @code{ui_out_field_string} to output a
1472string field, and use @code{ui_out_message}, described below, to
1473output short messages.
1474@end deftypefun
1475
1476@deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})
1477This function outputs @var{nspaces} spaces. It is handy to align the
1478text produced by @code{ui_out_text} with the rest of the table or
1479list.
1480@end deftypefun
1481
c72e7388 1482@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
0ee54786
EZ
1483This function produces a formatted message, provided that the current
1484verbosity level is at least as large as given by @var{verbosity}. The
1485current verbosity level is specified by the user with the @samp{set
1486verbositylevel} command.@footnote{As of this writing (April 2001),
1487setting verbosity level is not yet implemented, and is always returned
1488as zero. So calling @code{ui_out_message} with a @var{verbosity}
1489argument more than zero will cause the message to never be printed.}
1490@end deftypefun
1491
1492@deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent})
1493This function gives the console output filter (a paging filter) a hint
1494of where to break lines which are too long. Ignored for all other
1495output consumers. @var{indent}, if non-@code{NULL}, is the string to
1496be printed to indent the wrapped text on the next line; it must remain
1497accessible until the next call to @code{ui_out_wrap_hint}, or until an
1498explicit newline is produced by one of the other functions. If
1499@var{indent} is @code{NULL}, the wrapped text will not be indented.
1500@end deftypefun
1501
1502@deftypefun void ui_out_flush (struct ui_out *@var{uiout})
1503This function flushes whatever output has been accumulated so far, if
1504the UI buffers output.
1505@end deftypefun
1506
1507
1508@subsection Examples of Use of @code{ui_out} functions
1509
1510@cindex using @code{ui_out} functions
1511@cindex @code{ui_out} functions, usage examples
1512This section gives some practical examples of using the @code{ui_out}
1513functions to generalize the old console-oriented code in
1514@value{GDBN}. The examples all come from functions defined on the
1515@file{breakpoints.c} file.
1516
1517This example, from the @code{breakpoint_1} function, shows how to
1518produce a table.
1519
1520The original code was:
1521
474c8240 1522@smallexample
0ee54786
EZ
1523 if (!found_a_breakpoint++)
1524 @{
1525 annotate_breakpoints_headers ();
1526
1527 annotate_field (0);
1528 printf_filtered ("Num ");
1529 annotate_field (1);
1530 printf_filtered ("Type ");
1531 annotate_field (2);
1532 printf_filtered ("Disp ");
1533 annotate_field (3);
1534 printf_filtered ("Enb ");
1535 if (addressprint)
1536 @{
1537 annotate_field (4);
1538 printf_filtered ("Address ");
1539 @}
1540 annotate_field (5);
1541 printf_filtered ("What\n");
1542
1543 annotate_breakpoints_table ();
1544 @}
474c8240 1545@end smallexample
0ee54786
EZ
1546
1547Here's the new version:
1548
474c8240 1549@smallexample
c72e7388
AC
1550 nr_printable_breakpoints = @dots{};
1551
1552 if (addressprint)
1553 ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
1554 else
1555 ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
1556
1557 if (nr_printable_breakpoints > 0)
1558 annotate_breakpoints_headers ();
1559 if (nr_printable_breakpoints > 0)
1560 annotate_field (0);
1561 ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
1562 if (nr_printable_breakpoints > 0)
1563 annotate_field (1);
1564 ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
1565 if (nr_printable_breakpoints > 0)
1566 annotate_field (2);
1567 ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
1568 if (nr_printable_breakpoints > 0)
1569 annotate_field (3);
1570 ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
1571 if (addressprint)
1572 @{
1573 if (nr_printable_breakpoints > 0)
1574 annotate_field (4);
4a9bb1df 1575 if (gdbarch_addr_bit (current_gdbarch) <= 32)
c72e7388 1576 ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
0ee54786 1577 else
c72e7388
AC
1578 ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
1579 @}
1580 if (nr_printable_breakpoints > 0)
1581 annotate_field (5);
1582 ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
1583 ui_out_table_body (uiout);
1584 if (nr_printable_breakpoints > 0)
1585 annotate_breakpoints_table ();
474c8240 1586@end smallexample
0ee54786
EZ
1587
1588This example, from the @code{print_one_breakpoint} function, shows how
1589to produce the actual data for the table whose structure was defined
1590in the above example. The original code was:
1591
474c8240 1592@smallexample
0ee54786
EZ
1593 annotate_record ();
1594 annotate_field (0);
1595 printf_filtered ("%-3d ", b->number);
1596 annotate_field (1);
1597 if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
1598 || ((int) b->type != bptypes[(int) b->type].type))
1599 internal_error ("bptypes table does not describe type #%d.",
1600 (int)b->type);
1601 printf_filtered ("%-14s ", bptypes[(int)b->type].description);
1602 annotate_field (2);
1603 printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
1604 annotate_field (3);
1605 printf_filtered ("%-3c ", bpenables[(int)b->enable]);
c72e7388 1606 @dots{}
474c8240 1607@end smallexample
0ee54786
EZ
1608
1609This is the new version:
1610
474c8240 1611@smallexample
0ee54786 1612 annotate_record ();
c72e7388 1613 ui_out_tuple_begin (uiout, "bkpt");
0ee54786
EZ
1614 annotate_field (0);
1615 ui_out_field_int (uiout, "number", b->number);
1616 annotate_field (1);
1617 if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
1618 || ((int) b->type != bptypes[(int) b->type].type))
1619 internal_error ("bptypes table does not describe type #%d.",
1620 (int) b->type);
1621 ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
1622 annotate_field (2);
1623 ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
1624 annotate_field (3);
1625 ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
c72e7388 1626 @dots{}
474c8240 1627@end smallexample
0ee54786
EZ
1628
1629This example, also from @code{print_one_breakpoint}, shows how to
1630produce a complicated output field using the @code{print_expression}
1631functions which requires a stream to be passed. It also shows how to
1632automate stream destruction with cleanups. The original code was:
1633
474c8240 1634@smallexample
0ee54786
EZ
1635 annotate_field (5);
1636 print_expression (b->exp, gdb_stdout);
474c8240 1637@end smallexample
0ee54786
EZ
1638
1639The new version is:
1640
474c8240 1641@smallexample
0ee54786
EZ
1642 struct ui_stream *stb = ui_out_stream_new (uiout);
1643 struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
1644 ...
1645 annotate_field (5);
1646 print_expression (b->exp, stb->stream);
1647 ui_out_field_stream (uiout, "what", local_stream);
474c8240 1648@end smallexample
0ee54786
EZ
1649
1650This example, also from @code{print_one_breakpoint}, shows how to use
1651@code{ui_out_text} and @code{ui_out_field_string}. The original code
1652was:
1653
474c8240 1654@smallexample
0ee54786
EZ
1655 annotate_field (5);
1656 if (b->dll_pathname == NULL)
1657 printf_filtered ("<any library> ");
1658 else
1659 printf_filtered ("library \"%s\" ", b->dll_pathname);
474c8240 1660@end smallexample
0ee54786
EZ
1661
1662It became:
1663
474c8240 1664@smallexample
0ee54786
EZ
1665 annotate_field (5);
1666 if (b->dll_pathname == NULL)
1667 @{
1668 ui_out_field_string (uiout, "what", "<any library>");
1669 ui_out_spaces (uiout, 1);
1670 @}
1671 else
1672 @{
1673 ui_out_text (uiout, "library \"");
1674 ui_out_field_string (uiout, "what", b->dll_pathname);
1675 ui_out_text (uiout, "\" ");
1676 @}
474c8240 1677@end smallexample
0ee54786
EZ
1678
1679The following example from @code{print_one_breakpoint} shows how to
1680use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
1681code was:
1682
474c8240 1683@smallexample
0ee54786
EZ
1684 annotate_field (5);
1685 if (b->forked_inferior_pid != 0)
1686 printf_filtered ("process %d ", b->forked_inferior_pid);
474c8240 1687@end smallexample
0ee54786
EZ
1688
1689It became:
1690
474c8240 1691@smallexample
0ee54786
EZ
1692 annotate_field (5);
1693 if (b->forked_inferior_pid != 0)
1694 @{
1695 ui_out_text (uiout, "process ");
1696 ui_out_field_int (uiout, "what", b->forked_inferior_pid);
1697 ui_out_spaces (uiout, 1);
1698 @}
474c8240 1699@end smallexample
0ee54786
EZ
1700
1701Here's an example of using @code{ui_out_field_string}. The original
1702code was:
1703
474c8240 1704@smallexample
0ee54786
EZ
1705 annotate_field (5);
1706 if (b->exec_pathname != NULL)
1707 printf_filtered ("program \"%s\" ", b->exec_pathname);
474c8240 1708@end smallexample
0ee54786
EZ
1709
1710It became:
1711
474c8240 1712@smallexample
0ee54786
EZ
1713 annotate_field (5);
1714 if (b->exec_pathname != NULL)
1715 @{
1716 ui_out_text (uiout, "program \"");
1717 ui_out_field_string (uiout, "what", b->exec_pathname);
1718 ui_out_text (uiout, "\" ");
1719 @}
474c8240 1720@end smallexample
0ee54786
EZ
1721
1722Finally, here's an example of printing an address. The original code:
1723
474c8240 1724@smallexample
0ee54786
EZ
1725 annotate_field (4);
1726 printf_filtered ("%s ",
15a661f3 1727 hex_string_custom ((unsigned long) b->address, 8));
474c8240 1728@end smallexample
0ee54786
EZ
1729
1730It became:
1731
474c8240 1732@smallexample
0ee54786
EZ
1733 annotate_field (4);
1734 ui_out_field_core_addr (uiout, "Address", b->address);
474c8240 1735@end smallexample
0ee54786
EZ
1736
1737
c906108c
SS
1738@section Console Printing
1739
1740@section TUI
1741
89437448 1742@node libgdb
c906108c 1743
89437448
AC
1744@chapter libgdb
1745
1746@section libgdb 1.0
1747@cindex @code{libgdb}
1748@code{libgdb} 1.0 was an abortive project of years ago. The theory was
1749to provide an API to @value{GDBN}'s functionality.
1750
1751@section libgdb 2.0
56caf160 1752@cindex @code{libgdb}
89437448
AC
1753@code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is
1754better able to support graphical and other environments.
1755
1756Since @code{libgdb} development is on-going, its architecture is still
1757evolving. The following components have so far been identified:
1758
1759@itemize @bullet
1760@item
1761Observer - @file{gdb-events.h}.
1762@item
1763Builder - @file{ui-out.h}
1764@item
1765Event Loop - @file{event-loop.h}
1766@item
1767Library - @file{gdb.h}
1768@end itemize
1769
1770The model that ties these components together is described below.
1771
1772@section The @code{libgdb} Model
1773
1774A client of @code{libgdb} interacts with the library in two ways.
1775
1776@itemize @bullet
1777@item
1778As an observer (using @file{gdb-events}) receiving notifications from
1779@code{libgdb} of any internal state changes (break point changes, run
1780state, etc).
1781@item
1782As a client querying @code{libgdb} (using the @file{ui-out} builder) to
1783obtain various status values from @value{GDBN}.
1784@end itemize
1785
c1468174 1786Since @code{libgdb} could have multiple clients (e.g., a GUI supporting
89437448
AC
1787the existing @value{GDBN} CLI), those clients must co-operate when
1788controlling @code{libgdb}. In particular, a client must ensure that
1789@code{libgdb} is idle (i.e. no other client is using @code{libgdb})
1790before responding to a @file{gdb-event} by making a query.
1791
1792@section CLI support
1793
1794At present @value{GDBN}'s CLI is very much entangled in with the core of
1795@code{libgdb}. Consequently, a client wishing to include the CLI in
1796their interface needs to carefully co-ordinate its own and the CLI's
1797requirements.
1798
1799It is suggested that the client set @code{libgdb} up to be bi-modal
1800(alternate between CLI and client query modes). The notes below sketch
1801out the theory:
1802
1803@itemize @bullet
1804@item
1805The client registers itself as an observer of @code{libgdb}.
1806@item
1807The client create and install @code{cli-out} builder using its own
1808versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and
1809@code{gdb_stdout} streams.
1810@item
1811The client creates a separate custom @code{ui-out} builder that is only
1812used while making direct queries to @code{libgdb}.
1813@end itemize
1814
1815When the client receives input intended for the CLI, it simply passes it
1816along. Since the @code{cli-out} builder is installed by default, all
1817the CLI output in response to that command is routed (pronounced rooted)
1818through to the client controlled @code{gdb_stdout} et.@: al.@: streams.
1819At the same time, the client is kept abreast of internal changes by
1820virtue of being a @code{libgdb} observer.
1821
1822The only restriction on the client is that it must wait until
1823@code{libgdb} becomes idle before initiating any queries (using the
1824client's custom builder).
1825
1826@section @code{libgdb} components
1827
1828@subheading Observer - @file{gdb-events.h}
1829@file{gdb-events} provides the client with a very raw mechanism that can
1830be used to implement an observer. At present it only allows for one
1831observer and that observer must, internally, handle the need to delay
1832the processing of any event notifications until after @code{libgdb} has
1833finished the current command.
1834
1835@subheading Builder - @file{ui-out.h}
1836@file{ui-out} provides the infrastructure necessary for a client to
1837create a builder. That builder is then passed down to @code{libgdb}
1838when doing any queries.
1839
1840@subheading Event Loop - @file{event-loop.h}
1841@c There could be an entire section on the event-loop
1842@file{event-loop}, currently non-re-entrant, provides a simple event
1843loop. A client would need to either plug its self into this loop or,
1844implement a new event-loop that GDB would use.
1845
1846The event-loop will eventually be made re-entrant. This is so that
a9f12a31 1847@value{GDBN} can better handle the problem of some commands blocking
89437448
AC
1848instead of returning.
1849
1850@subheading Library - @file{gdb.h}
1851@file{libgdb} is the most obvious component of this system. It provides
1852the query interface. Each function is parameterized by a @code{ui-out}
1853builder. The result of the query is constructed using that builder
1854before the query function returns.
c906108c
SS
1855
1856@node Symbol Handling
1857
1858@chapter Symbol Handling
1859
25822942 1860Symbols are a key part of @value{GDBN}'s operation. Symbols include variables,
c906108c
SS
1861functions, and types.
1862
1863@section Symbol Reading
1864
56caf160
EZ
1865@cindex symbol reading
1866@cindex reading of symbols
1867@cindex symbol files
1868@value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol
1869file is the file containing the program which @value{GDBN} is
1870debugging. @value{GDBN} can be directed to use a different file for
1871symbols (with the @samp{symbol-file} command), and it can also read
1872more symbols via the @samp{add-file} and @samp{load} commands, or while
1873reading symbols from shared libraries.
1874
1875@findex find_sym_fns
1876Symbol files are initially opened by code in @file{symfile.c} using
1877the BFD library (@pxref{Support Libraries}). BFD identifies the type
1878of the file by examining its header. @code{find_sym_fns} then uses
1879this identification to locate a set of symbol-reading functions.
1880
1881@findex add_symtab_fns
1882@cindex @code{sym_fns} structure
1883@cindex adding a symbol-reading module
1884Symbol-reading modules identify themselves to @value{GDBN} by calling
c906108c
SS
1885@code{add_symtab_fns} during their module initialization. The argument
1886to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
1887name (or name prefix) of the symbol format, the length of the prefix,
1888and pointers to four functions. These functions are called at various
56caf160 1889times to process symbol files whose identification matches the specified
c906108c
SS
1890prefix.
1891
1892The functions supplied by each module are:
1893
1894@table @code
1895@item @var{xyz}_symfile_init(struct sym_fns *sf)
1896
56caf160 1897@cindex secondary symbol file
c906108c
SS
1898Called from @code{symbol_file_add} when we are about to read a new
1899symbol file. This function should clean up any internal state (possibly
1900resulting from half-read previous files, for example) and prepare to
56caf160
EZ
1901read a new symbol file. Note that the symbol file which we are reading
1902might be a new ``main'' symbol file, or might be a secondary symbol file
c906108c
SS
1903whose symbols are being added to the existing symbol table.
1904
1905The argument to @code{@var{xyz}_symfile_init} is a newly allocated
1906@code{struct sym_fns} whose @code{bfd} field contains the BFD for the
1907new symbol file being read. Its @code{private} field has been zeroed,
1908and can be modified as desired. Typically, a struct of private
1909information will be @code{malloc}'d, and a pointer to it will be placed
1910in the @code{private} field.
1911
1912There is no result from @code{@var{xyz}_symfile_init}, but it can call
1913@code{error} if it detects an unavoidable problem.
1914
1915@item @var{xyz}_new_init()
1916
1917Called from @code{symbol_file_add} when discarding existing symbols.
56caf160
EZ
1918This function needs only handle the symbol-reading module's internal
1919state; the symbol table data structures visible to the rest of
1920@value{GDBN} will be discarded by @code{symbol_file_add}. It has no
1921arguments and no result. It may be called after
1922@code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
1923may be called alone if all symbols are simply being discarded.
c906108c
SS
1924
1925@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
1926
1927Called from @code{symbol_file_add} to actually read the symbols from a
1928symbol-file into a set of psymtabs or symtabs.
1929
56caf160 1930@code{sf} points to the @code{struct sym_fns} originally passed to
c906108c
SS
1931@code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
1932the offset between the file's specified start address and its true
1933address in memory. @code{mainline} is 1 if this is the main symbol
c1468174 1934table being read, and 0 if a secondary symbol file (e.g., shared library
c906108c
SS
1935or dynamically loaded file) is being read.@refill
1936@end table
1937
1938In addition, if a symbol-reading module creates psymtabs when
1939@var{xyz}_symfile_read is called, these psymtabs will contain a pointer
1940to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
25822942 1941from any point in the @value{GDBN} symbol-handling code.
c906108c
SS
1942
1943@table @code
1944@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
1945
56caf160 1946Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
c906108c
SS
1947the psymtab has not already been read in and had its @code{pst->symtab}
1948pointer set. The argument is the psymtab to be fleshed-out into a
56caf160
EZ
1949symtab. Upon return, @code{pst->readin} should have been set to 1, and
1950@code{pst->symtab} should contain a pointer to the new corresponding symtab, or
c906108c
SS
1951zero if there were no symbols in that part of the symbol file.
1952@end table
1953
1954@section Partial Symbol Tables
1955
56caf160 1956@value{GDBN} has three types of symbol tables:
c906108c
SS
1957
1958@itemize @bullet
56caf160
EZ
1959@cindex full symbol table
1960@cindex symtabs
1961@item
1962Full symbol tables (@dfn{symtabs}). These contain the main
1963information about symbols and addresses.
c906108c 1964
56caf160
EZ
1965@cindex psymtabs
1966@item
1967Partial symbol tables (@dfn{psymtabs}). These contain enough
c906108c
SS
1968information to know when to read the corresponding part of the full
1969symbol table.
1970
56caf160
EZ
1971@cindex minimal symbol table
1972@cindex minsymtabs
1973@item
1974Minimal symbol tables (@dfn{msymtabs}). These contain information
c906108c 1975gleaned from non-debugging symbols.
c906108c
SS
1976@end itemize
1977
56caf160 1978@cindex partial symbol table
c906108c
SS
1979This section describes partial symbol tables.
1980
1981A psymtab is constructed by doing a very quick pass over an executable
1982file's debugging information. Small amounts of information are
56caf160 1983extracted---enough to identify which parts of the symbol table will
c906108c 1984need to be re-read and fully digested later, when the user needs the
25822942 1985information. The speed of this pass causes @value{GDBN} to start up very
c906108c
SS
1986quickly. Later, as the detailed rereading occurs, it occurs in small
1987pieces, at various times, and the delay therefrom is mostly invisible to
1988the user.
1989@c (@xref{Symbol Reading}.)
1990
1991The symbols that show up in a file's psymtab should be, roughly, those
1992visible to the debugger's user when the program is not running code from
1993that file. These include external symbols and types, static symbols and
56caf160 1994types, and @code{enum} values declared at file scope.
c906108c
SS
1995
1996The psymtab also contains the range of instruction addresses that the
1997full symbol table would represent.
1998
56caf160
EZ
1999@cindex finding a symbol
2000@cindex symbol lookup
c906108c
SS
2001The idea is that there are only two ways for the user (or much of the
2002code in the debugger) to reference a symbol:
2003
2004@itemize @bullet
56caf160
EZ
2005@findex find_pc_function
2006@findex find_pc_line
2007@item
c1468174 2008By its address (e.g., execution stops at some address which is inside a
56caf160
EZ
2009function in this file). The address will be noticed to be in the
2010range of this psymtab, and the full symtab will be read in.
2011@code{find_pc_function}, @code{find_pc_line}, and other
2012@code{find_pc_@dots{}} functions handle this.
c906108c 2013
56caf160
EZ
2014@cindex lookup_symbol
2015@item
2016By its name
c1468174 2017(e.g., the user asks to print a variable, or set a breakpoint on a
c906108c
SS
2018function). Global names and file-scope names will be found in the
2019psymtab, which will cause the symtab to be pulled in. Local names will
2020have to be qualified by a global name, or a file-scope name, in which
2021case we will have already read in the symtab as we evaluated the
56caf160 2022qualifier. Or, a local symbol can be referenced when we are ``in'' a
c906108c
SS
2023local scope, in which case the first case applies. @code{lookup_symbol}
2024does most of the work here.
c906108c
SS
2025@end itemize
2026
2027The only reason that psymtabs exist is to cause a symtab to be read in
2028at the right moment. Any symbol that can be elided from a psymtab,
2029while still causing that to happen, should not appear in it. Since
2030psymtabs don't have the idea of scope, you can't put local symbols in
2031them anyway. Psymtabs don't have the idea of the type of a symbol,
2032either, so types need not appear, unless they will be referenced by
2033name.
2034
56caf160
EZ
2035It is a bug for @value{GDBN} to behave one way when only a psymtab has
2036been read, and another way if the corresponding symtab has been read
2037in. Such bugs are typically caused by a psymtab that does not contain
2038all the visible symbols, or which has the wrong instruction address
2039ranges.
c906108c 2040
56caf160 2041The psymtab for a particular section of a symbol file (objfile) could be
c906108c
SS
2042thrown away after the symtab has been read in. The symtab should always
2043be searched before the psymtab, so the psymtab will never be used (in a
2044bug-free environment). Currently, psymtabs are allocated on an obstack,
2045and all the psymbols themselves are allocated in a pair of large arrays
2046on an obstack, so there is little to be gained by trying to free them
2047unless you want to do a lot more work.
2048
2049@section Types
2050
56caf160 2051@unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).
c906108c 2052
56caf160 2053@cindex fundamental types
25822942 2054These are the fundamental types that @value{GDBN} uses internally. Fundamental
c906108c
SS
2055types from the various debugging formats (stabs, ELF, etc) are mapped
2056into one of these. They are basically a union of all fundamental types
56caf160
EZ
2057that @value{GDBN} knows about for all the languages that @value{GDBN}
2058knows about.
c906108c 2059
56caf160 2060@unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).
c906108c 2061
56caf160
EZ
2062@cindex type codes
2063Each time @value{GDBN} builds an internal type, it marks it with one
2064of these types. The type may be a fundamental type, such as
2065@code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR}
2066which is a pointer to another type. Typically, several @code{FT_*}
2067types map to one @code{TYPE_CODE_*} type, and are distinguished by
2068other members of the type struct, such as whether the type is signed
2069or unsigned, and how many bits it uses.
c906108c 2070
56caf160 2071@unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).
c906108c
SS
2072
2073These are instances of type structs that roughly correspond to
56caf160
EZ
2074fundamental types and are created as global types for @value{GDBN} to
2075use for various ugly historical reasons. We eventually want to
2076eliminate these. Note for example that @code{builtin_type_int}
2077initialized in @file{gdbtypes.c} is basically the same as a
2078@code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for
2079an @code{FT_INTEGER} fundamental type. The difference is that the
2080@code{builtin_type} is not associated with any particular objfile, and
2081only one instance exists, while @file{c-lang.c} builds as many
2082@code{TYPE_CODE_INT} types as needed, with each one associated with
2083some particular objfile.
c906108c
SS
2084
2085@section Object File Formats
56caf160 2086@cindex object file formats
c906108c
SS
2087
2088@subsection a.out
2089
56caf160
EZ
2090@cindex @code{a.out} format
2091The @code{a.out} format is the original file format for Unix. It
2092consists of three sections: @code{text}, @code{data}, and @code{bss},
2093which are for program code, initialized data, and uninitialized data,
2094respectively.
c906108c 2095
56caf160 2096The @code{a.out} format is so simple that it doesn't have any reserved
c906108c 2097place for debugging information. (Hey, the original Unix hackers used
56caf160
EZ
2098@samp{adb}, which is a machine-language debugger!) The only debugging
2099format for @code{a.out} is stabs, which is encoded as a set of normal
c906108c
SS
2100symbols with distinctive attributes.
2101
56caf160 2102The basic @code{a.out} reader is in @file{dbxread.c}.
c906108c
SS
2103
2104@subsection COFF
2105
56caf160 2106@cindex COFF format
c906108c
SS
2107The COFF format was introduced with System V Release 3 (SVR3) Unix.
2108COFF files may have multiple sections, each prefixed by a header. The
2109number of sections is limited.
2110
2111The COFF specification includes support for debugging. Although this
2112was a step forward, the debugging information was woefully limited. For
2113instance, it was not possible to represent code that came from an
2114included file.
2115
2116The COFF reader is in @file{coffread.c}.
2117
2118@subsection ECOFF
2119
56caf160 2120@cindex ECOFF format
c906108c
SS
2121ECOFF is an extended COFF originally introduced for Mips and Alpha
2122workstations.
2123
2124The basic ECOFF reader is in @file{mipsread.c}.
2125
2126@subsection XCOFF
2127
56caf160 2128@cindex XCOFF format
c906108c
SS
2129The IBM RS/6000 running AIX uses an object file format called XCOFF.
2130The COFF sections, symbols, and line numbers are used, but debugging
56caf160
EZ
2131symbols are @code{dbx}-style stabs whose strings are located in the
2132@code{.debug} section (rather than the string table). For more
2133information, see @ref{Top,,,stabs,The Stabs Debugging Format}.
c906108c
SS
2134
2135The shared library scheme has a clean interface for figuring out what
2136shared libraries are in use, but the catch is that everything which
2137refers to addresses (symbol tables and breakpoints at least) needs to be
2138relocated for both shared libraries and the main executable. At least
2139using the standard mechanism this can only be done once the program has
2140been run (or the core file has been read).
2141
2142@subsection PE
2143
56caf160
EZ
2144@cindex PE-COFF format
2145Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their
c906108c
SS
2146executables. PE is basically COFF with additional headers.
2147
25822942 2148While BFD includes special PE support, @value{GDBN} needs only the basic
c906108c
SS
2149COFF reader.
2150
2151@subsection ELF
2152
56caf160 2153@cindex ELF format
c906108c
SS
2154The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
2155to COFF in being organized into a number of sections, but it removes
2156many of COFF's limitations.
2157
2158The basic ELF reader is in @file{elfread.c}.
2159
2160@subsection SOM
2161
56caf160 2162@cindex SOM format
c906108c
SS
2163SOM is HP's object file and debug format (not to be confused with IBM's
2164SOM, which is a cross-language ABI).
2165
1a92f856 2166The SOM reader is in @file{somread.c}.
c906108c 2167
c906108c
SS
2168@section Debugging File Formats
2169
2170This section describes characteristics of debugging information that
2171are independent of the object file format.
2172
2173@subsection stabs
2174
56caf160 2175@cindex stabs debugging info
c906108c
SS
2176@code{stabs} started out as special symbols within the @code{a.out}
2177format. Since then, it has been encapsulated into other file
2178formats, such as COFF and ELF.
2179
2180While @file{dbxread.c} does some of the basic stab processing,
2181including for encapsulated versions, @file{stabsread.c} does
2182the real work.
2183
2184@subsection COFF
2185
56caf160 2186@cindex COFF debugging info
c906108c
SS
2187The basic COFF definition includes debugging information. The level
2188of support is minimal and non-extensible, and is not often used.
2189
2190@subsection Mips debug (Third Eye)
2191
56caf160 2192@cindex ECOFF debugging info
c906108c
SS
2193ECOFF includes a definition of a special debug format.
2194
2195The file @file{mdebugread.c} implements reading for this format.
2196
c906108c
SS
2197@subsection DWARF 2
2198
56caf160 2199@cindex DWARF 2 debugging info
c906108c
SS
2200DWARF 2 is an improved but incompatible version of DWARF 1.
2201
2202The DWARF 2 reader is in @file{dwarf2read.c}.
2203
2204@subsection SOM
2205
56caf160 2206@cindex SOM debugging info
c906108c
SS
2207Like COFF, the SOM definition includes debugging information.
2208
25822942 2209@section Adding a New Symbol Reader to @value{GDBN}
c906108c 2210
56caf160
EZ
2211@cindex adding debugging info reader
2212If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
c906108c
SS
2213there is probably little to be done.
2214
2215If you need to add a new object file format, you must first add it to
2216BFD. This is beyond the scope of this document.
2217
2218You must then arrange for the BFD code to provide access to the
25822942 2219debugging symbols. Generally @value{GDBN} will have to call swapping routines
c906108c 2220from BFD and a few other BFD internal routines to locate the debugging
25822942 2221information. As much as possible, @value{GDBN} should not depend on the BFD
c906108c
SS
2222internal data structures.
2223
2224For some targets (e.g., COFF), there is a special transfer vector used
2225to call swapping routines, since the external data structures on various
2226platforms have different sizes and layouts. Specialized routines that
2227will only ever be implemented by one object file format may be called
2228directly. This interface should be described in a file
56caf160 2229@file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
c906108c 2230
c91d38aa
DJ
2231@section Memory Management for Symbol Files
2232
2233Most memory associated with a loaded symbol file is stored on
2234its @code{objfile_obstack}. This includes symbols, types,
2235namespace data, and other information produced by the symbol readers.
2236
2237Because this data lives on the objfile's obstack, it is automatically
2238released when the objfile is unloaded or reloaded. Therefore one
2239objfile must not reference symbol or type data from another objfile;
2240they could be unloaded at different times.
2241
2242User convenience variables, et cetera, have associated types. Normally
2243these types live in the associated objfile. However, when the objfile
2244is unloaded, those types are deep copied to global memory, so that
2245the values of the user variables and history items are not lost.
2246
c906108c
SS
2247
2248@node Language Support
2249
2250@chapter Language Support
2251
56caf160
EZ
2252@cindex language support
2253@value{GDBN}'s language support is mainly driven by the symbol reader,
2254although it is possible for the user to set the source language
2255manually.
c906108c 2256
56caf160
EZ
2257@value{GDBN} chooses the source language by looking at the extension
2258of the file recorded in the debug info; @file{.c} means C, @file{.f}
2259means Fortran, etc. It may also use a special-purpose language
2260identifier if the debug format supports it, like with DWARF.
c906108c 2261
25822942 2262@section Adding a Source Language to @value{GDBN}
c906108c 2263
56caf160
EZ
2264@cindex adding source language
2265To add other languages to @value{GDBN}'s expression parser, follow the
2266following steps:
c906108c
SS
2267
2268@table @emph
2269@item Create the expression parser.
2270
56caf160 2271@cindex expression parser
c906108c 2272This should reside in a file @file{@var{lang}-exp.y}. Routines for
56caf160 2273building parsed expressions into a @code{union exp_element} list are in
c906108c
SS
2274@file{parse.c}.
2275
56caf160 2276@cindex language parser
c906108c
SS
2277Since we can't depend upon everyone having Bison, and YACC produces
2278parsers that define a bunch of global names, the following lines
56caf160 2279@strong{must} be included at the top of the YACC parser, to prevent the
c906108c
SS
2280various parsers from defining the same global names:
2281
474c8240 2282@smallexample
56caf160
EZ
2283#define yyparse @var{lang}_parse
2284#define yylex @var{lang}_lex
2285#define yyerror @var{lang}_error
2286#define yylval @var{lang}_lval
2287#define yychar @var{lang}_char
2288#define yydebug @var{lang}_debug
2289#define yypact @var{lang}_pact
2290#define yyr1 @var{lang}_r1
2291#define yyr2 @var{lang}_r2
2292#define yydef @var{lang}_def
2293#define yychk @var{lang}_chk
2294#define yypgo @var{lang}_pgo
2295#define yyact @var{lang}_act
2296#define yyexca @var{lang}_exca
2297#define yyerrflag @var{lang}_errflag
2298#define yynerrs @var{lang}_nerrs
474c8240 2299@end smallexample
c906108c
SS
2300
2301At the bottom of your parser, define a @code{struct language_defn} and
2302initialize it with the right values for your language. Define an
2303@code{initialize_@var{lang}} routine and have it call
25822942 2304@samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
c906108c
SS
2305that your language exists. You'll need some other supporting variables
2306and functions, which will be used via pointers from your
2307@code{@var{lang}_language_defn}. See the declaration of @code{struct
2308language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
2309for more information.
2310
2311@item Add any evaluation routines, if necessary
2312
56caf160
EZ
2313@cindex expression evaluation routines
2314@findex evaluate_subexp
2315@findex prefixify_subexp
2316@findex length_of_subexp
c906108c
SS
2317If you need new opcodes (that represent the operations of the language),
2318add them to the enumerated type in @file{expression.h}. Add support
56caf160
EZ
2319code for these operations in the @code{evaluate_subexp} function
2320defined in the file @file{eval.c}. Add cases
c906108c 2321for new opcodes in two functions from @file{parse.c}:
56caf160 2322@code{prefixify_subexp} and @code{length_of_subexp}. These compute
c906108c
SS
2323the number of @code{exp_element}s that a given operation takes up.
2324
2325@item Update some existing code
2326
2327Add an enumerated identifier for your language to the enumerated type
2328@code{enum language} in @file{defs.h}.
2329
2330Update the routines in @file{language.c} so your language is included.
2331These routines include type predicates and such, which (in some cases)
2332are language dependent. If your language does not appear in the switch
2333statement, an error is reported.
2334
56caf160 2335@vindex current_language
c906108c
SS
2336Also included in @file{language.c} is the code that updates the variable
2337@code{current_language}, and the routines that translate the
2338@code{language_@var{lang}} enumerated identifier into a printable
2339string.
2340
56caf160 2341@findex _initialize_language
c906108c
SS
2342Update the function @code{_initialize_language} to include your
2343language. This function picks the default language upon startup, so is
25822942 2344dependent upon which languages that @value{GDBN} is built for.
c906108c 2345
56caf160 2346@findex allocate_symtab
c906108c
SS
2347Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
2348code so that the language of each symtab (source file) is set properly.
2349This is used to determine the language to use at each stack frame level.
2350Currently, the language is set based upon the extension of the source
2351file. If the language can be better inferred from the symbol
2352information, please set the language of the symtab in the symbol-reading
2353code.
2354
56caf160
EZ
2355@findex print_subexp
2356@findex op_print_tab
2357Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
c906108c
SS
2358expression opcodes you have added to @file{expression.h}. Also, add the
2359printed representations of your operators to @code{op_print_tab}.
2360
2361@item Add a place of call
2362
56caf160 2363@findex parse_exp_1
c906108c 2364Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
56caf160 2365@code{parse_exp_1} (defined in @file{parse.c}).
c906108c
SS
2366
2367@item Use macros to trim code
2368
56caf160 2369@cindex trimming language-dependent code
25822942
DB
2370The user has the option of building @value{GDBN} for some or all of the
2371languages. If the user decides to build @value{GDBN} for the language
c906108c
SS
2372@var{lang}, then every file dependent on @file{language.h} will have the
2373macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
2374leave out large routines that the user won't need if he or she is not
2375using your language.
2376
25822942 2377Note that you do not need to do this in your YACC parser, since if @value{GDBN}
c906108c 2378is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
25822942 2379compiled form of your parser) is not linked into @value{GDBN} at all.
c906108c 2380
56caf160
EZ
2381See the file @file{configure.in} for how @value{GDBN} is configured
2382for different languages.
c906108c
SS
2383
2384@item Edit @file{Makefile.in}
2385
2386Add dependencies in @file{Makefile.in}. Make sure you update the macro
2387variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
2388not get linked in, or, worse yet, it may not get @code{tar}red into the
2389distribution!
c906108c
SS
2390@end table
2391
2392
2393@node Host Definition
2394
2395@chapter Host Definition
2396
56caf160 2397With the advent of Autoconf, it's rarely necessary to have host
7fd60527
AC
2398definition machinery anymore. The following information is provided,
2399mainly, as an historical reference.
c906108c
SS
2400
2401@section Adding a New Host
2402
56caf160
EZ
2403@cindex adding a new host
2404@cindex host, adding
7fd60527
AC
2405@value{GDBN}'s host configuration support normally happens via Autoconf.
2406New host-specific definitions should not be needed. Older hosts
2407@value{GDBN} still use the host-specific definitions and files listed
2408below, but these mostly exist for historical reasons, and will
56caf160 2409eventually disappear.
c906108c 2410
c906108c 2411@table @file
c906108c 2412@item gdb/config/@var{arch}/@var{xyz}.mh
7fd60527
AC
2413This file once contained both host and native configuration information
2414(@pxref{Native Debugging}) for the machine @var{xyz}. The host
2415configuration information is now handed by Autoconf.
2416
2417Host configuration information included a definition of
2418@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC},
7708fa01
AC
2419@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},
2420@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.
c906108c 2421
7fd60527
AC
2422New host only configurations do not need this file.
2423
c906108c 2424@item gdb/config/@var{arch}/xm-@var{xyz}.h
7fd60527
AC
2425This file once contained definitions and includes required when hosting
2426gdb on machine @var{xyz}. Those definitions and includes are now
2427handled by Autoconf.
2428
2429New host and native configurations do not need this file.
2430
2431@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h}
2432file to define the macros @var{HOST_FLOAT_FORMAT},
2433@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}. That code
2434also needs to be replaced with either an Autoconf or run-time test.}
c906108c 2435
c906108c
SS
2436@end table
2437
2438@subheading Generic Host Support Files
2439
56caf160 2440@cindex generic host support
c906108c
SS
2441There are some ``generic'' versions of routines that can be used by
2442various systems. These can be customized in various ways by macros
2443defined in your @file{xm-@var{xyz}.h} file. If these routines work for
2444the @var{xyz} host, you can just include the generic file's name (with
2445@samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
2446
2447Otherwise, if your machine needs custom support routines, you will need
2448to write routines that perform the same functions as the generic file.
2449Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
2450into @code{XDEPFILES}.
2451
2452@table @file
56caf160
EZ
2453@cindex remote debugging support
2454@cindex serial line support
c906108c
SS
2455@item ser-unix.c
2456This contains serial line support for Unix systems. This is always
2457included, via the makefile variable @code{SER_HARDWIRE}; override this
2458variable in the @file{.mh} file to avoid it.
2459
2460@item ser-go32.c
2461This contains serial line support for 32-bit programs running under DOS,
56caf160 2462using the DJGPP (a.k.a.@: GO32) execution environment.
c906108c 2463
56caf160 2464@cindex TCP remote support
c906108c
SS
2465@item ser-tcp.c
2466This contains generic TCP support using sockets.
c906108c
SS
2467@end table
2468
2469@section Host Conditionals
2470
56caf160
EZ
2471When @value{GDBN} is configured and compiled, various macros are
2472defined or left undefined, to control compilation based on the
2473attributes of the host system. These macros and their meanings (or if
2474the meaning is not documented here, then one of the source files where
2475they are used is indicated) are:
c906108c 2476
56caf160 2477@ftable @code
25822942 2478@item @value{GDBN}INIT_FILENAME
56caf160
EZ
2479The default name of @value{GDBN}'s initialization file (normally
2480@file{.gdbinit}).
c906108c 2481
cce74817
JM
2482@item NO_STD_REGS
2483This macro is deprecated.
2484
c906108c
SS
2485@item SIGWINCH_HANDLER
2486If your host defines @code{SIGWINCH}, you can define this to be the name
2487of a function to be called if @code{SIGWINCH} is received.
2488
2489@item SIGWINCH_HANDLER_BODY
2490Define this to expand into code that will define the function named by
2491the expansion of @code{SIGWINCH_HANDLER}.
2492
c906108c 2493@item CRLF_SOURCE_FILES
56caf160 2494@cindex DOS text files
c906108c
SS
2495Define this if host files use @code{\r\n} rather than @code{\n} as a
2496line terminator. This will cause source file listings to omit @code{\r}
56caf160
EZ
2497characters when printing and it will allow @code{\r\n} line endings of files
2498which are ``sourced'' by gdb. It must be possible to open files in binary
c906108c
SS
2499mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
2500
2501@item DEFAULT_PROMPT
56caf160 2502@cindex prompt
c906108c
SS
2503The default value of the prompt string (normally @code{"(gdb) "}).
2504
2505@item DEV_TTY
56caf160 2506@cindex terminal device
c906108c
SS
2507The name of the generic TTY device, defaults to @code{"/dev/tty"}.
2508
c906108c
SS
2509@item FOPEN_RB
2510Define this if binary files are opened the same way as text files.
2511
c906108c 2512@item HAVE_MMAP
56caf160 2513@findex mmap
c906108c
SS
2514In some cases, use the system call @code{mmap} for reading symbol
2515tables. For some machines this allows for sharing and quick updates.
2516
c906108c
SS
2517@item HAVE_TERMIO
2518Define this if the host system has @code{termio.h}.
2519
c906108c 2520@item INT_MAX
9742079a
EZ
2521@itemx INT_MIN
2522@itemx LONG_MAX
2523@itemx UINT_MAX
2524@itemx ULONG_MAX
c906108c
SS
2525Values for host-side constants.
2526
2527@item ISATTY
2528Substitute for isatty, if not available.
2529
2530@item LONGEST
2531This is the longest integer type available on the host. If not defined,
2532it will default to @code{long long} or @code{long}, depending on
2533@code{CC_HAS_LONG_LONG}.
2534
2535@item CC_HAS_LONG_LONG
56caf160
EZ
2536@cindex @code{long long} data type
2537Define this if the host C compiler supports @code{long long}. This is set
2538by the @code{configure} script.
c906108c
SS
2539
2540@item PRINTF_HAS_LONG_LONG
2541Define this if the host can handle printing of long long integers via
56caf160
EZ
2542the printf format conversion specifier @code{ll}. This is set by the
2543@code{configure} script.
c906108c
SS
2544
2545@item HAVE_LONG_DOUBLE
56caf160
EZ
2546Define this if the host C compiler supports @code{long double}. This is
2547set by the @code{configure} script.
c906108c
SS
2548
2549@item PRINTF_HAS_LONG_DOUBLE
2550Define this if the host can handle printing of long double float-point
56caf160
EZ
2551numbers via the printf format conversion specifier @code{Lg}. This is
2552set by the @code{configure} script.
c906108c
SS
2553
2554@item SCANF_HAS_LONG_DOUBLE
2555Define this if the host can handle the parsing of long double
56caf160
EZ
2556float-point numbers via the scanf format conversion specifier
2557@code{Lg}. This is set by the @code{configure} script.
c906108c
SS
2558
2559@item LSEEK_NOT_LINEAR
2560Define this if @code{lseek (n)} does not necessarily move to byte number
2561@code{n} in the file. This is only used when reading source files. It
2562is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
2563
2564@item L_SET
56caf160
EZ
2565This macro is used as the argument to @code{lseek} (or, most commonly,
2566@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
2567which is the POSIX equivalent.
c906108c 2568
c906108c
SS
2569@item NORETURN
2570If defined, this should be one or more tokens, such as @code{volatile},
2571that can be used in both the declaration and definition of functions to
2572indicate that they never return. The default is already set correctly
2573if compiling with GCC. This will almost never need to be defined.
2574
2575@item ATTR_NORETURN
2576If defined, this should be one or more tokens, such as
2577@code{__attribute__ ((noreturn))}, that can be used in the declarations
2578of functions to indicate that they never return. The default is already
2579set correctly if compiling with GCC. This will almost never need to be
2580defined.
2581
c906108c 2582@item SEEK_CUR
9742079a 2583@itemx SEEK_SET
56caf160 2584Define these to appropriate value for the system @code{lseek}, if not already
c906108c
SS
2585defined.
2586
2587@item STOP_SIGNAL
56caf160
EZ
2588This is the signal for stopping @value{GDBN}. Defaults to
2589@code{SIGTSTP}. (Only redefined for the Convex.)
c906108c 2590
c906108c
SS
2591@item USG
2592Means that System V (prior to SVR4) include files are in use. (FIXME:
7ca9f392
AC
2593This symbol is abused in @file{infrun.c}, @file{regex.c}, and
2594@file{utils.c} for other things, at the moment.)
c906108c
SS
2595
2596@item lint
56caf160 2597Define this to help placate @code{lint} in some situations.
c906108c
SS
2598
2599@item volatile
2600Define this to override the defaults of @code{__volatile__} or
2601@code{/**/}.
56caf160 2602@end ftable
c906108c
SS
2603
2604
2605@node Target Architecture Definition
2606
2607@chapter Target Architecture Definition
2608
56caf160
EZ
2609@cindex target architecture definition
2610@value{GDBN}'s target architecture defines what sort of
2611machine-language programs @value{GDBN} can work with, and how it works
2612with them.
c906108c 2613
af6c57ea
AC
2614The target architecture object is implemented as the C structure
2615@code{struct gdbarch *}. The structure, and its methods, are generated
93c2c750 2616using the Bourne shell script @file{gdbarch.sh}.
c906108c 2617
b6fd0dfb
NR
2618@menu
2619* OS ABI Variant Handling::
2620* Initialize New Architecture::
2621* Registers and Memory::
2622* Pointers and Addresses::
2623* Address Classes::
2624* Raw and Virtual Registers::
2625* Register and Memory Data::
2626* Frame Interpretation::
2627* Inferior Call Setup::
2628* Compiler Characteristics::
2629* Target Conditionals::
2630* Adding a New Target::
b6fd0dfb
NR
2631@end menu
2632
2633@node OS ABI Variant Handling
70f80edf
JT
2634@section Operating System ABI Variant Handling
2635@cindex OS ABI variants
2636
2637@value{GDBN} provides a mechanism for handling variations in OS
2638ABIs. An OS ABI variant may have influence over any number of
2639variables in the target architecture definition. There are two major
2640components in the OS ABI mechanism: sniffers and handlers.
2641
2642A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair
2643(the architecture may be wildcarded) in an attempt to determine the
2644OS ABI of that file. Sniffers with a wildcarded architecture are considered
2645to be @dfn{generic}, while sniffers for a specific architecture are
2646considered to be @dfn{specific}. A match from a specific sniffer
2647overrides a match from a generic sniffer. Multiple sniffers for an
2648architecture/flavour may exist, in order to differentiate between two
2649different operating systems which use the same basic file format. The
2650OS ABI framework provides a generic sniffer for ELF-format files which
2651examines the @code{EI_OSABI} field of the ELF header, as well as note
2652sections known to be used by several operating systems.
2653
2654@cindex fine-tuning @code{gdbarch} structure
2655A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the
2656selected OS ABI. There may be only one handler for a given OS ABI
2657for each BFD architecture.
2658
f4b3909f 2659The following OS ABI variants are defined in @file{defs.h}:
70f80edf
JT
2660
2661@table @code
2662
f4b3909f
EZ
2663@findex GDB_OSABI_UNINITIALIZED
2664@item GDB_OSABI_UNINITIALIZED
2665Used for struct gdbarch_info if ABI is still uninitialized.
2666
70f80edf
JT
2667@findex GDB_OSABI_UNKNOWN
2668@item GDB_OSABI_UNKNOWN
2669The ABI of the inferior is unknown. The default @code{gdbarch}
2670settings for the architecture will be used.
2671
2672@findex GDB_OSABI_SVR4
2673@item GDB_OSABI_SVR4
f4b3909f 2674UNIX System V Release 4.
70f80edf
JT
2675
2676@findex GDB_OSABI_HURD
2677@item GDB_OSABI_HURD
f4b3909f 2678GNU using the Hurd kernel.
70f80edf
JT
2679
2680@findex GDB_OSABI_SOLARIS
2681@item GDB_OSABI_SOLARIS
f4b3909f 2682Sun Solaris.
70f80edf
JT
2683
2684@findex GDB_OSABI_OSF1
2685@item GDB_OSABI_OSF1
f4b3909f 2686OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
70f80edf
JT
2687
2688@findex GDB_OSABI_LINUX
2689@item GDB_OSABI_LINUX
f4b3909f 2690GNU using the Linux kernel.
70f80edf
JT
2691
2692@findex GDB_OSABI_FREEBSD_AOUT
2693@item GDB_OSABI_FREEBSD_AOUT
f4b3909f 2694FreeBSD using the @code{a.out} executable format.
70f80edf
JT
2695
2696@findex GDB_OSABI_FREEBSD_ELF
2697@item GDB_OSABI_FREEBSD_ELF
f4b3909f 2698FreeBSD using the ELF executable format.
70f80edf
JT
2699
2700@findex GDB_OSABI_NETBSD_AOUT
2701@item GDB_OSABI_NETBSD_AOUT
f4b3909f 2702NetBSD using the @code{a.out} executable format.
70f80edf
JT
2703
2704@findex GDB_OSABI_NETBSD_ELF
2705@item GDB_OSABI_NETBSD_ELF
f4b3909f
EZ
2706NetBSD using the ELF executable format.
2707
2708@findex GDB_OSABI_OPENBSD_ELF
2709@item GDB_OSABI_OPENBSD_ELF
2710OpenBSD using the ELF executable format.
70f80edf
JT
2711
2712@findex GDB_OSABI_WINCE
2713@item GDB_OSABI_WINCE
f4b3909f 2714Windows CE.
70f80edf 2715
1029b7fa
MK
2716@findex GDB_OSABI_GO32
2717@item GDB_OSABI_GO32
f4b3909f 2718DJGPP.
1029b7fa 2719
f4b3909f
EZ
2720@findex GDB_OSABI_IRIX
2721@item GDB_OSABI_IRIX
2722Irix.
2723
f4b3909f
EZ
2724@findex GDB_OSABI_INTERIX
2725@item GDB_OSABI_INTERIX
2726Interix (Posix layer for MS-Windows systems).
1029b7fa 2727
f4b3909f
EZ
2728@findex GDB_OSABI_HPUX_ELF
2729@item GDB_OSABI_HPUX_ELF
2730HP/UX using the ELF executable format.
70f80edf 2731
f4b3909f
EZ
2732@findex GDB_OSABI_HPUX_SOM
2733@item GDB_OSABI_HPUX_SOM
2734HP/UX using the SOM executable format.
70f80edf 2735
f4b3909f
EZ
2736@findex GDB_OSABI_QNXNTO
2737@item GDB_OSABI_QNXNTO
2738QNX Neutrino.
2739
2740@findex GDB_OSABI_CYGWIN
2741@item GDB_OSABI_CYGWIN
2742Cygwin.
2743
2744@findex GDB_OSABI_AIX
2745@item GDB_OSABI_AIX
2746AIX.
70f80edf
JT
2747
2748@end table
2749
2750Here are the functions that make up the OS ABI framework:
2751
2752@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi})
2753Return the name of the OS ABI corresponding to @var{osabi}.
2754@end deftypefun
2755
c133ab7a 2756@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}))
70f80edf 2757Register the OS ABI handler specified by @var{init_osabi} for the
c133ab7a
MK
2758architecture, machine type and OS ABI specified by @var{arch},
2759@var{machine} and @var{osabi}. In most cases, a value of zero for the
2760machine type, which implies the architecture's default machine type,
2761will suffice.
70f80edf
JT
2762@end deftypefun
2763
2764@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd}))
2765Register the OS ABI file sniffer specified by @var{sniffer} for the
2766BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.
2767If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to
2768be generic, and is allowed to examine @var{flavour}-flavoured files for
2769any architecture.
2770@end deftypefun
2771
2772@deftypefun enum gdb_osabi gdbarch_lookup_osabi (bfd *@var{abfd})
2773Examine the file described by @var{abfd} to determine its OS ABI.
2774The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot
2775be determined.
2776@end deftypefun
2777
2778@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi})
2779Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the
2780@code{gdbarch} structure specified by @var{gdbarch}. If a handler
2781corresponding to @var{osabi} has not been registered for @var{gdbarch}'s
2782architecture, a warning will be issued and the debugging session will continue
2783with the defaults already established for @var{gdbarch}.
2784@end deftypefun
2785
f4b3909f
EZ
2786@deftypefun void generic_elf_osabi_sniff_abi_tag_sections (bfd *@var{abfd}, asection *@var{sect}, void *@var{obj})
2787Helper routine for ELF file sniffers. Examine the file described by
2788@var{abfd} and look at ABI tag note sections to determine the OS ABI
2789from the note. This function should be called via
2790@code{bfd_map_over_sections}.
2791@end deftypefun
2792
b6fd0dfb 2793@node Initialize New Architecture
7a107747
DJ
2794@section Initializing a New Architecture
2795
2796Each @code{gdbarch} is associated with a single @sc{bfd} architecture,
2797via a @code{bfd_arch_@var{arch}} constant. The @code{gdbarch} is
2798registered by a call to @code{register_gdbarch_init}, usually from
2799the file's @code{_initialize_@var{filename}} routine, which will
2800be automatically called during @value{GDBN} startup. The arguments
2801are a @sc{bfd} architecture constant and an initialization function.
2802
2803The initialization function has this type:
2804
2805@smallexample
2806static struct gdbarch *
2807@var{arch}_gdbarch_init (struct gdbarch_info @var{info},
2808 struct gdbarch_list *@var{arches})
2809@end smallexample
2810
2811The @var{info} argument contains parameters used to select the correct
2812architecture, and @var{arches} is a list of architectures which
2813have already been created with the same @code{bfd_arch_@var{arch}}
2814value.
2815
2816The initialization function should first make sure that @var{info}
2817is acceptable, and return @code{NULL} if it is not. Then, it should
2818search through @var{arches} for an exact match to @var{info}, and
2819return one if found. Lastly, if no exact match was found, it should
2820create a new architecture based on @var{info} and return it.
2821
2822Only information in @var{info} should be used to choose the new
2823architecture. Historically, @var{info} could be sparse, and
2824defaults would be collected from the first element on @var{arches}.
2825However, @value{GDBN} now fills in @var{info} more thoroughly,
2826so new @code{gdbarch} initialization functions should not take
2827defaults from @var{arches}.
2828
b6fd0dfb 2829@node Registers and Memory
c906108c
SS
2830@section Registers and Memory
2831
56caf160
EZ
2832@value{GDBN}'s model of the target machine is rather simple.
2833@value{GDBN} assumes the machine includes a bank of registers and a
2834block of memory. Each register may have a different size.
c906108c 2835
56caf160
EZ
2836@value{GDBN} does not have a magical way to match up with the
2837compiler's idea of which registers are which; however, it is critical
2838that they do match up accurately. The only way to make this work is
2839to get accurate information about the order that the compiler uses,
4a9bb1df 2840and to reflect that in the @code{gdbarch_register_name} and related functions.
c906108c 2841
25822942 2842@value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
c906108c 2843
b6fd0dfb 2844@node Pointers and Addresses
93e79dbd
JB
2845@section Pointers Are Not Always Addresses
2846@cindex pointer representation
2847@cindex address representation
2848@cindex word-addressed machines
2849@cindex separate data and code address spaces
2850@cindex spaces, separate data and code address
2851@cindex address spaces, separate data and code
2852@cindex code pointers, word-addressed
2853@cindex converting between pointers and addresses
2854@cindex D10V addresses
2855
2856On almost all 32-bit architectures, the representation of a pointer is
2857indistinguishable from the representation of some fixed-length number
2858whose value is the byte address of the object pointed to. On such
56caf160 2859machines, the words ``pointer'' and ``address'' can be used interchangeably.
93e79dbd
JB
2860However, architectures with smaller word sizes are often cramped for
2861address space, so they may choose a pointer representation that breaks this
2862identity, and allows a larger code address space.
2863
172c2a43 2864For example, the Renesas D10V is a 16-bit VLIW processor whose
93e79dbd
JB
2865instructions are 32 bits long@footnote{Some D10V instructions are
2866actually pairs of 16-bit sub-instructions. However, since you can't
2867jump into the middle of such a pair, code addresses can only refer to
2868full 32 bit instructions, which is what matters in this explanation.}.
2869If the D10V used ordinary byte addresses to refer to code locations,
2870then the processor would only be able to address 64kb of instructions.
2871However, since instructions must be aligned on four-byte boundaries, the
56caf160
EZ
2872low two bits of any valid instruction's byte address are always
2873zero---byte addresses waste two bits. So instead of byte addresses,
2874the D10V uses word addresses---byte addresses shifted right two bits---to
93e79dbd
JB
2875refer to code. Thus, the D10V can use 16-bit words to address 256kb of
2876code space.
2877
2878However, this means that code pointers and data pointers have different
2879forms on the D10V. The 16-bit word @code{0xC020} refers to byte address
2880@code{0xC020} when used as a data address, but refers to byte address
2881@code{0x30080} when used as a code address.
2882
2883(The D10V also uses separate code and data address spaces, which also
2884affects the correspondence between pointers and addresses, but we're
2885going to ignore that here; this example is already too long.)
2886
56caf160
EZ
2887To cope with architectures like this---the D10V is not the only
2888one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
93e79dbd
JB
2889byte numbers, and @dfn{pointers}, which are the target's representation
2890of an address of a particular type of data. In the example above,
2891@code{0xC020} is the pointer, which refers to one of the addresses
2892@code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
2893@value{GDBN} provides functions for turning a pointer into an address
2894and vice versa, in the appropriate way for the current architecture.
2895
2896Unfortunately, since addresses and pointers are identical on almost all
2897processors, this distinction tends to bit-rot pretty quickly. Thus,
2898each time you port @value{GDBN} to an architecture which does
2899distinguish between pointers and addresses, you'll probably need to
2900clean up some architecture-independent code.
2901
2902Here are functions which convert between pointers and addresses:
2903
2904@deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
2905Treat the bytes at @var{buf} as a pointer or reference of type
2906@var{type}, and return the address it represents, in a manner
2907appropriate for the current architecture. This yields an address
2908@value{GDBN} can use to read target memory, disassemble, etc. Note that
2909@var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2910inferior's.
2911
2912For example, if the current architecture is the Intel x86, this function
2913extracts a little-endian integer of the appropriate length from
2914@var{buf} and returns it. However, if the current architecture is the
2915D10V, this function will return a 16-bit integer extracted from
2916@var{buf}, multiplied by four if @var{type} is a pointer to a function.
2917
2918If @var{type} is not a pointer or reference type, then this function
2919will signal an internal error.
2920@end deftypefun
2921
2922@deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
2923Store the address @var{addr} in @var{buf}, in the proper format for a
2924pointer of type @var{type} in the current architecture. Note that
2925@var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2926inferior's.
2927
2928For example, if the current architecture is the Intel x86, this function
2929stores @var{addr} unmodified as a little-endian integer of the
2930appropriate length in @var{buf}. However, if the current architecture
2931is the D10V, this function divides @var{addr} by four if @var{type} is
2932a pointer to a function, and then stores it in @var{buf}.
2933
2934If @var{type} is not a pointer or reference type, then this function
2935will signal an internal error.
2936@end deftypefun
2937
f23631e4 2938@deftypefun CORE_ADDR value_as_address (struct value *@var{val})
93e79dbd
JB
2939Assuming that @var{val} is a pointer, return the address it represents,
2940as appropriate for the current architecture.
2941
2942This function actually works on integral values, as well as pointers.
2943For pointers, it performs architecture-specific conversions as
2944described above for @code{extract_typed_address}.
2945@end deftypefun
2946
2947@deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
2948Create and return a value representing a pointer of type @var{type} to
2949the address @var{addr}, as appropriate for the current architecture.
2950This function performs architecture-specific conversions as described
2951above for @code{store_typed_address}.
2952@end deftypefun
2953
4a9bb1df 2954Here are two functions which architectures can define to indicate the
93e79dbd
JB
2955relationship between pointers and addresses. These have default
2956definitions, appropriate for architectures on which all pointers are
fc0c74b1 2957simple unsigned byte addresses.
93e79dbd 2958
4a9bb1df 2959@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{current_gdbarch}, struct type *@var{type}, char *@var{buf})
93e79dbd
JB
2960Assume that @var{buf} holds a pointer of type @var{type}, in the
2961appropriate format for the current architecture. Return the byte
2962address the pointer refers to.
2963
2964This function may safely assume that @var{type} is either a pointer or a
56caf160 2965C@t{++} reference type.
4a9bb1df 2966@end deftypefun
93e79dbd 2967
4a9bb1df 2968@deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{current_gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
93e79dbd
JB
2969Store in @var{buf} a pointer of type @var{type} representing the address
2970@var{addr}, in the appropriate format for the current architecture.
2971
2972This function may safely assume that @var{type} is either a pointer or a
56caf160 2973C@t{++} reference type.
4a9bb1df 2974@end deftypefun
93e79dbd 2975
b6fd0dfb 2976@node Address Classes
b5b0480a
KB
2977@section Address Classes
2978@cindex address classes
2979@cindex DW_AT_byte_size
2980@cindex DW_AT_address_class
2981
2982Sometimes information about different kinds of addresses is available
2983via the debug information. For example, some programming environments
2984define addresses of several different sizes. If the debug information
2985distinguishes these kinds of address classes through either the size
2986info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit
2987address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the
2988following macros should be defined in order to disambiguate these
2989types within @value{GDBN} as well as provide the added information to
2990a @value{GDBN} user when printing type expressions.
2991
4a9bb1df 2992@deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class})
b5b0480a
KB
2993Returns the type flags needed to construct a pointer type whose size
2994is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.
2995This function is normally called from within a symbol reader. See
2996@file{dwarf2read.c}.
4a9bb1df 2997@end deftypefun
b5b0480a 2998
4a9bb1df 2999@deftypefun char *gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{current_gdbarch}, int @var{type_flags})
b5b0480a
KB
3000Given the type flags representing an address class qualifier, return
3001its name.
4a9bb1df
UW
3002@end deftypefun
3003@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{name}, int *var{type_flags_ptr})
d3e8051b 3004Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags
b5b0480a 3005for that address class qualifier.
4a9bb1df 3006@end deftypefun
b5b0480a
KB
3007
3008Since the need for address classes is rather rare, none of
4a9bb1df
UW
3009the address class functions are defined by default. Predicate
3010functions are provided to detect when they are defined.
b5b0480a
KB
3011
3012Consider a hypothetical architecture in which addresses are normally
301332-bits wide, but 16-bit addresses are also supported. Furthermore,
3014suppose that the @w{DWARF 2} information for this architecture simply
3015uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one
3016of these "short" pointers. The following functions could be defined
4a9bb1df 3017to implement the address class functions:
b5b0480a
KB
3018
3019@smallexample
3020somearch_address_class_type_flags (int byte_size,
3021 int dwarf2_addr_class)
f2abfe65 3022@{
b5b0480a
KB
3023 if (byte_size == 2)
3024 return TYPE_FLAG_ADDRESS_CLASS_1;
3025 else
3026 return 0;
f2abfe65 3027@}
b5b0480a
KB
3028
3029static char *
3030somearch_address_class_type_flags_to_name (int type_flags)
f2abfe65 3031@{
b5b0480a
KB
3032 if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
3033 return "short";
3034 else
3035 return NULL;
f2abfe65 3036@}
b5b0480a
KB
3037
3038int
3039somearch_address_class_name_to_type_flags (char *name,
3040 int *type_flags_ptr)
f2abfe65 3041@{
b5b0480a 3042 if (strcmp (name, "short") == 0)
f2abfe65 3043 @{
b5b0480a
KB
3044 *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
3045 return 1;
f2abfe65 3046 @}
b5b0480a
KB
3047 else
3048 return 0;
f2abfe65 3049@}
b5b0480a
KB
3050@end smallexample
3051
3052The qualifier @code{@@short} is used in @value{GDBN}'s type expressions
3053to indicate the presence of one of these "short" pointers. E.g, if
3054the debug information indicates that @code{short_ptr_var} is one of these
3055short pointers, @value{GDBN} might show the following behavior:
3056
3057@smallexample
3058(gdb) ptype short_ptr_var
3059type = int * @@short
3060@end smallexample
3061
93e79dbd 3062
b6fd0dfb 3063@node Raw and Virtual Registers
13d01224
AC
3064@section Raw and Virtual Register Representations
3065@cindex raw register representation
3066@cindex virtual register representation
3067@cindex representations, raw and virtual registers
3068
3069@emph{Maintainer note: This section is pretty much obsolete. The
3070functionality described here has largely been replaced by
3071pseudo-registers and the mechanisms described in @ref{Target
3072Architecture Definition, , Using Different Register and Memory Data
3073Representations}. See also @uref{http://www.gnu.org/software/gdb/bugs/,
3074Bug Tracking Database} and
3075@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more
3076up-to-date information.}
af6c57ea 3077
9fb4dd36
JB
3078Some architectures use one representation for a value when it lives in a
3079register, but use a different representation when it lives in memory.
25822942 3080In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
9fb4dd36 3081the target registers, and the @dfn{virtual} representation is the one
25822942 3082used in memory, and within @value{GDBN} @code{struct value} objects.
9fb4dd36 3083
13d01224
AC
3084@emph{Maintainer note: Notice that the same mechanism is being used to
3085both convert a register to a @code{struct value} and alternative
3086register forms.}
3087
9fb4dd36
JB
3088For almost all data types on almost all architectures, the virtual and
3089raw representations are identical, and no special handling is needed.
3090However, they do occasionally differ. For example:
3091
3092@itemize @bullet
9fb4dd36 3093@item
56caf160 3094The x86 architecture supports an 80-bit @code{long double} type. However, when
9fb4dd36
JB
3095we store those values in memory, they occupy twelve bytes: the
3096floating-point number occupies the first ten, and the final two bytes
3097are unused. This keeps the values aligned on four-byte boundaries,
3098allowing more efficient access. Thus, the x86 80-bit floating-point
3099type is the raw representation, and the twelve-byte loosely-packed
3100arrangement is the virtual representation.
3101
3102@item
25822942
DB
3103Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit
3104registers, with garbage in their upper bits. @value{GDBN} ignores the top 32
9fb4dd36
JB
3105bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the
3106raw representation, and the trimmed 32-bit representation is the
3107virtual representation.
9fb4dd36
JB
3108@end itemize
3109
3110In general, the raw representation is determined by the architecture, or
25822942
DB
3111@value{GDBN}'s interface to the architecture, while the virtual representation
3112can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file,
56caf160
EZ
3113@code{registers}, holds the register contents in raw format, and the
3114@value{GDBN} remote protocol transmits register values in raw format.
9fb4dd36 3115
56caf160
EZ
3116Your architecture may define the following macros to request
3117conversions between the raw and virtual format:
9fb4dd36
JB
3118
3119@deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
3120Return non-zero if register number @var{reg}'s value needs different raw
3121and virtual formats.
6f6ef15a
EZ
3122
3123You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
3124unless this macro returns a non-zero value for that register.
9fb4dd36
JB
3125@end deftypefn
3126
12c266ea 3127@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg})
9fb4dd36 3128The size of register number @var{reg}'s raw value. This is the number
25822942 3129of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
9fb4dd36
JB
3130remote protocol packet.
3131@end deftypefn
3132
f30992d4 3133@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg})
9fb4dd36
JB
3134The size of register number @var{reg}'s value, in its virtual format.
3135This is the size a @code{struct value}'s buffer will have, holding that
3136register's value.
3137@end deftypefn
3138
2e092625 3139@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg})
9fb4dd36
JB
3140This is the type of the virtual representation of register number
3141@var{reg}. Note that there is no need for a macro giving a type for the
25822942 3142register's raw form; once the register's value has been obtained, @value{GDBN}
9fb4dd36
JB
3143always uses the virtual form.
3144@end deftypefn
3145
3146@deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
3147Convert the value of register number @var{reg} to @var{type}, which
2e092625 3148should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
9fb4dd36
JB
3149at @var{from} holds the register's value in raw format; the macro should
3150convert the value to virtual format, and place it at @var{to}.
3151
6f6ef15a
EZ
3152Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and
3153@code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
3154arguments in different orders.
3155
3156You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
3157for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
3158value.
9fb4dd36
JB
3159@end deftypefn
3160
3161@deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
3162Convert the value of register number @var{reg} to @var{type}, which
2e092625 3163should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
9fb4dd36
JB
3164at @var{from} holds the register's value in raw format; the macro should
3165convert the value to virtual format, and place it at @var{to}.
3166
3167Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
3168their @var{reg} and @var{type} arguments in different orders.
3169@end deftypefn
3170
3171
b6fd0dfb 3172@node Register and Memory Data
13d01224
AC
3173@section Using Different Register and Memory Data Representations
3174@cindex register representation
3175@cindex memory representation
3176@cindex representations, register and memory
3177@cindex register data formats, converting
3178@cindex @code{struct value}, converting register contents to
3179
3180@emph{Maintainer's note: The way GDB manipulates registers is undergoing
d3e8051b 3181significant change. Many of the macros and functions referred to in this
13d01224
AC
3182section are likely to be subject to further revision. See
3183@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and
3184@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for
3185further information. cagney/2002-05-06.}
3186
3187Some architectures can represent a data object in a register using a
3188form that is different to the objects more normal memory representation.
3189For example:
3190
3191@itemize @bullet
3192
3193@item
3194The Alpha architecture can represent 32 bit integer values in
3195floating-point registers.
3196
3197@item
3198The x86 architecture supports 80-bit floating-point registers. The
3199@code{long double} data type occupies 96 bits in memory but only 80 bits
3200when stored in a register.
3201
3202@end itemize
3203
3204In general, the register representation of a data type is determined by
3205the architecture, or @value{GDBN}'s interface to the architecture, while
3206the memory representation is determined by the Application Binary
3207Interface.
3208
3209For almost all data types on almost all architectures, the two
3210representations are identical, and no special handling is needed.
3211However, they do occasionally differ. Your architecture may define the
3212following macros to request conversions between the register and memory
3213representations of a data type:
3214
4a9bb1df 3215@deftypefun int gdbarch_convert_register_p (struct gdbarch *@var{gdbarch}, int @var{reg})
13d01224
AC
3216Return non-zero if the representation of a data value stored in this
3217register may be different to the representation of that same data value
3218when stored in memory.
3219
4a9bb1df
UW
3220When non-zero, the macros @code{gdbarch_register_to_value} and
3221@code{value_to_register} are used to perform any necessary conversion.
83acabca
DJ
3222
3223This function should return zero for the register's native type, when
3224no conversion is necessary.
4a9bb1df 3225@end deftypefun
13d01224 3226
4a9bb1df 3227@deftypefun void gdbarch_register_to_value (struct gdbarch *@var{gdbarch}, int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
13d01224
AC
3228Convert the value of register number @var{reg} to a data object of type
3229@var{type}. The buffer at @var{from} holds the register's value in raw
3230format; the converted value should be placed in the buffer at @var{to}.
3231
4a9bb1df
UW
3232Note that @code{gdbarch_register_to_value} and @code{gdbarch_value_to_register}
3233take their @var{reg} and @var{type} arguments in different orders.
13d01224 3234
4a9bb1df
UW
3235You should only use @code{gdbarch_register_to_value} with registers for which
3236the @code{gdbarch_convert_register_p} function returns a non-zero value.
3237@end deftypefun
13d01224 3238
4a9bb1df 3239@deftypefun void gdbarch_value_to_register (struct gdbarch *@var{gdbarch}, struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
13d01224
AC
3240Convert a data value of type @var{type} to register number @var{reg}'
3241raw format.
3242
4a9bb1df
UW
3243Note that @code{gdbarch_register_to_value} and @code{gdbarch_value_to_register}
3244take their @var{reg} and @var{type} arguments in different orders.
13d01224 3245
4a9bb1df
UW
3246You should only use @code{gdbarch_value_to_register} with registers for which
3247the @code{gdbarch_convert_register_p} function returns a non-zero value.
3248@end deftypefun
13d01224
AC
3249
3250@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf})
3251See @file{mips-tdep.c}. It does not do what you want.
3252@end deftypefn
3253
b6fd0dfb 3254@node Frame Interpretation
c906108c
SS
3255@section Frame Interpretation
3256
b6fd0dfb 3257@node Inferior Call Setup
c906108c
SS
3258@section Inferior Call Setup
3259
b6fd0dfb 3260@node Compiler Characteristics
c906108c
SS
3261@section Compiler Characteristics
3262
b6fd0dfb 3263@node Target Conditionals
c906108c
SS
3264@section Target Conditionals
3265
4a9bb1df
UW
3266This section describes the macros and functions that you can use to define the
3267target machine.
c906108c
SS
3268
3269@table @code
3270
4a9bb1df
UW
3271@item CORE_ADDR gdbarch_addr_bits_remove (@var{gdbarch}, @var{addr})
3272@findex gdbarch_addr_bits_remove
adf40b2e 3273If a raw machine instruction address includes any bits that are not
4a9bb1df
UW
3274really part of the address, then this function is used to zero those bits in
3275@var{addr}. This is only used for addresses of instructions, and even then not
3276in all contexts.
adf40b2e
JM
3277
3278For example, the two low-order bits of the PC on the Hewlett-Packard PA
32792.0 architecture contain the privilege level of the corresponding
3280instruction. Since instructions must always be aligned on four-byte
3281boundaries, the processor masks out these bits to generate the actual
4a9bb1df
UW
3282address of the instruction. @code{gdbarch_addr_bits_remove} would then for
3283example look like that:
3284@smallexample
3285arch_addr_bits_remove (CORE_ADDR addr)
3286@{
3287 return (addr &= ~0x3);
3288@}
3289@end smallexample
c906108c 3290
4a9bb1df
UW
3291@item int address_class_name_to_type_flags (@var{gdbarch}, @var{name}, @var{type_flags_ptr})
3292@findex address_class_name_to_type_flags
b5b0480a
KB
3293If @var{name} is a valid address class qualifier name, set the @code{int}
3294referenced by @var{type_flags_ptr} to the mask representing the qualifier
3295and return 1. If @var{name} is not a valid address class qualifier name,
3296return 0.
3297
3298The value for @var{type_flags_ptr} should be one of
3299@code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or
3300possibly some combination of these values or'd together.
3301@xref{Target Architecture Definition, , Address Classes}.
3302
4a9bb1df
UW
3303@item int address_class_name_to_type_flags_p (@var{gdbarch})
3304@findex address_class_name_to_type_flags_p
3305Predicate which indicates whether @code{address_class_name_to_type_flags}
b5b0480a
KB
3306has been defined.
3307
4a9bb1df
UW
3308@item int gdbarch_address_class_type_flags (@var{gdbarch}, @var{byte_size}, @var{dwarf2_addr_class})
3309@findex gdbarch_address_class_type_flags
b5b0480a
KB
3310Given a pointers byte size (as described by the debug information) and
3311the possible @code{DW_AT_address_class} value, return the type flags
3312used by @value{GDBN} to represent this address class. The value
3313returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1},
3314@code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these
3315values or'd together.
3316@xref{Target Architecture Definition, , Address Classes}.
3317
4a9bb1df
UW
3318@item int gdbarch_address_class_type_flags_p (@var{gdbarch})
3319@findex gdbarch_address_class_type_flags_p
3320Predicate which indicates whether @code{gdbarch_address_class_type_flags_p} has
b5b0480a
KB
3321been defined.
3322
4a9bb1df
UW
3323@item const char *gdbarch_address_class_type_flags_to_name (@var{gdbarch}, @var{type_flags})
3324@findex gdbarch_address_class_type_flags_to_name
b5b0480a
KB
3325Return the name of the address class qualifier associated with the type
3326flags given by @var{type_flags}.
3327
4a9bb1df
UW
3328@item int gdbarch_address_class_type_flags_to_name_p (@var{gdbarch})
3329@findex gdbarch_address_class_type_flags_to_name_p
3330Predicate which indicates whether @code{gdbarch_address_class_type_flags_to_name} has been defined.
b5b0480a
KB
3331@xref{Target Architecture Definition, , Address Classes}.
3332
4a9bb1df
UW
3333@item void gdbarch_address_to_pointer (@var{gdbarch}, @var{type}, @var{buf}, @var{addr})
3334@findex gdbarch_address_to_pointer
93e79dbd
JB
3335Store in @var{buf} a pointer of type @var{type} representing the address
3336@var{addr}, in the appropriate format for the current architecture.
4a9bb1df 3337This function may safely assume that @var{type} is either a pointer or a
56caf160 3338C@t{++} reference type.
93e79dbd
JB
3339@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
3340
4a9bb1df
UW
3341@item int gdbarch_believe_pcc_promotion (@var{gdbarch})
3342@findex gdbarch_believe_pcc_promotion
3343Used to notify if the compiler promotes a @code{short} or @code{char}
56caf160
EZ
3344parameter to an @code{int}, but still reports the parameter as its
3345original type, rather than the promoted type.
c906108c 3346
c906108c 3347@item BITS_BIG_ENDIAN
56caf160
EZ
3348@findex BITS_BIG_ENDIAN
3349Define this if the numbering of bits in the targets does @strong{not} match the
c906108c 3350endianness of the target byte order. A value of 1 means that the bits
56caf160 3351are numbered in a big-endian bit order, 0 means little-endian.
c906108c
SS
3352
3353@item BREAKPOINT
56caf160 3354@findex BREAKPOINT
c906108c
SS
3355This is the character array initializer for the bit pattern to put into
3356memory where a breakpoint is set. Although it's common to use a trap
3357instruction for a breakpoint, it's not required; for instance, the bit
3358pattern could be an invalid instruction. The breakpoint must be no
3359longer than the shortest instruction of the architecture.
3360
56caf160 3361@code{BREAKPOINT} has been deprecated in favor of
4a9bb1df 3362@code{gdbarch_breakpoint_from_pc}.
7a292a7a 3363
c906108c 3364@item BIG_BREAKPOINT
56caf160
EZ
3365@itemx LITTLE_BREAKPOINT
3366@findex LITTLE_BREAKPOINT
3367@findex BIG_BREAKPOINT
c906108c
SS
3368Similar to BREAKPOINT, but used for bi-endian targets.
3369
56caf160 3370@code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
4a9bb1df 3371favor of @code{gdbarch_breakpoint_from_pc}.
7a292a7a 3372
4a9bb1df
UW
3373@item const gdb_byte *gdbarch_breakpoint_from_pc (@var{gdbarch}, @var{pcptr}, @var{lenptr})
3374@findex gdbarch_breakpoint_from_pc
3375@anchor{gdbarch_breakpoint_from_pc} Use the program counter to determine the
2dd0da42
AC
3376contents and size of a breakpoint instruction. It returns a pointer to
3377a string of bytes that encode a breakpoint instruction, stores the
3378length of the string to @code{*@var{lenptr}}, and adjusts the program
3379counter (if necessary) to point to the actual memory location where the
3380breakpoint should be inserted.
c906108c
SS
3381
3382Although it is common to use a trap instruction for a breakpoint, it's
3383not required; for instance, the bit pattern could be an invalid
3384instruction. The breakpoint must be no longer than the shortest
3385instruction of the architecture.
3386
7a292a7a
SS
3387Replaces all the other @var{BREAKPOINT} macros.
3388
4a9bb1df
UW
3389@item int gdbarch_memory_insert_breakpoint (@var{gdbarch}, @var{bp_tgt})
3390@itemx gdbarch_memory_remove_breakpoint (@var{gdbarch}, @var{bp_tgt})
3391@findex gdbarch_memory_remove_breakpoint
3392@findex gdbarch_memory_insert_breakpoint
917317f4
JM
3393Insert or remove memory based breakpoints. Reasonable defaults
3394(@code{default_memory_insert_breakpoint} and
3395@code{default_memory_remove_breakpoint} respectively) have been
4a9bb1df
UW
3396provided so that it is not necessary to set these for most
3397architectures. Architectures which may want to set
3398@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
917317f4
JM
3399conventional manner.
3400
3401It may also be desirable (from an efficiency standpoint) to define
3402custom breakpoint insertion and removal routines if
4a9bb1df 3403@code{gdbarch_breakpoint_from_pc} needs to read the target's memory for some
917317f4
JM
3404reason.
3405
4a9bb1df
UW
3406@item CORE_ADDR gdbarch_adjust_breakpoint_address (@var{gdbarch}, @var{bpaddr})
3407@findex gdbarch_adjust_breakpoint_address
1485d690
KB
3408@cindex breakpoint address adjusted
3409Given an address at which a breakpoint is desired, return a breakpoint
3410address adjusted to account for architectural constraints on
3411breakpoint placement. This method is not needed by most targets.
3412
3413The FR-V target (see @file{frv-tdep.c}) requires this method.
3414The FR-V is a VLIW architecture in which a number of RISC-like
3415instructions are grouped (packed) together into an aggregate
3416instruction or instruction bundle. When the processor executes
3417one of these bundles, the component instructions are executed
3418in parallel.
3419
3420In the course of optimization, the compiler may group instructions
3421from distinct source statements into the same bundle. The line number
3422information associated with one of the latter statements will likely
3423refer to some instruction other than the first one in the bundle. So,
3424if the user attempts to place a breakpoint on one of these latter
3425statements, @value{GDBN} must be careful to @emph{not} place the break
3426instruction on any instruction other than the first one in the bundle.
3427(Remember though that the instructions within a bundle execute
3428in parallel, so the @emph{first} instruction is the instruction
3429at the lowest address and has nothing to do with execution order.)
3430
4a9bb1df 3431The FR-V's @code{gdbarch_adjust_breakpoint_address} method will adjust a
1485d690
KB
3432breakpoint's address by scanning backwards for the beginning of
3433the bundle, returning the address of the bundle.
3434
3435Since the adjustment of a breakpoint may significantly alter a user's
3436expectation, @value{GDBN} prints a warning when an adjusted breakpoint
3437is initially set and each time that that breakpoint is hit.
3438
4a9bb1df
UW
3439@item int gdbarch_call_dummy_location (@var{gdbarch})
3440@findex gdbarch_call_dummy_location
56caf160 3441See the file @file{inferior.h}.
7a292a7a 3442
4a9bb1df
UW
3443This method has been replaced by @code{gdbarch_push_dummy_code}
3444(@pxref{gdbarch_push_dummy_code}).
7043d8dc 3445
4a9bb1df
UW
3446@item int gdbarch_cannot_fetch_register (@var{gdbarch}, @var{regum})
3447@findex gdbarch_cannot_fetch_register
3448This function should return nonzero if @var{regno} cannot be fetched
c906108c
SS
3449from an inferior process. This is only relevant if
3450@code{FETCH_INFERIOR_REGISTERS} is not defined.
3451
4a9bb1df
UW
3452@item int gdbarch_cannot_store_register (@var{gdbarch}, @var{regnum})
3453@findex gdbarch_cannot_store_register
3454This function should return nonzero if @var{regno} should not be
c906108c 3455written to the target. This is often the case for program counters,
4a9bb1df
UW
3456status words, and other special registers. This function returns 0 as
3457default so that @value{GDBN} will assume that all registers may be written.
c906108c 3458
4a9bb1df
UW
3459@item int gdbarch_convert_register_p (@var{gdbarch}, @var{regnum}, struct type *@var{type})
3460@findex gdbarch_convert_register_p
83acabca
DJ
3461Return non-zero if register @var{regnum} represents data values of type
3462@var{type} in a non-standard form.
13d01224
AC
3463@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3464
4a9bb1df
UW
3465@item CORE_ADDR gdbarch_decr_pc_after_break (@var{gdbarch})
3466@findex gdbarch_decr_pc_after_break
3467This function shall return the amount by which to decrement the PC after the
c906108c 3468program encounters a breakpoint. This is often the number of bytes in
56caf160 3469@code{BREAKPOINT}, though not always. For most targets this value will be 0.
c906108c 3470
56caf160
EZ
3471@item DISABLE_UNSETTABLE_BREAK (@var{addr})
3472@findex DISABLE_UNSETTABLE_BREAK
c906108c
SS
3473If defined, this should evaluate to 1 if @var{addr} is in a shared
3474library in which breakpoints cannot be set and so should be disabled.
3475
5fc14d0a 3476@item void gdbarch_print_float_info (@var{gdbarch}, @var{file}, @var{frame}, @var{args})
4a9bb1df 3477@findex gdbarch_print_float_info
5e74b15c
RE
3478If defined, then the @samp{info float} command will print information about
3479the processor's floating point unit.
3480
4a9bb1df
UW
3481@item void gdbarch_print_registers_info (@var{gdbarch}, @var{frame}, @var{regnum}, @var{all})
3482@findex gdbarch_print_registers_info
0ab7a791
AC
3483If defined, pretty print the value of the register @var{regnum} for the
3484specified @var{frame}. If the value of @var{regnum} is -1, pretty print
3485either all registers (@var{all} is non zero) or a select subset of
3486registers (@var{all} is zero).
3487
3488The default method prints one register per line, and if @var{all} is
3489zero omits floating-point registers.
3490
4a9bb1df
UW
3491@item int gdbarch_print_vector_info (@var{gdbarch}, @var{file}, @var{frame}, @var{args})
3492@findex gdbarch_print_vector_info
e76f1f2e
AC
3493If defined, then the @samp{info vector} command will call this function
3494to print information about the processor's vector unit.
3495
3496By default, the @samp{info vector} command will print all vector
3497registers (the register's type having the vector attribute).
3498
4a9bb1df
UW
3499@item int gdbarch_dwarf_reg_to_regnum (@var{gdbarch}, @var{dwarf_regnr})
3500@findex gdbarch_dwarf_reg_to_regnum
3501Convert DWARF register number @var{dwarf_regnr} into @value{GDBN} regnum. If
3502not defined, no conversion will be performed.
0dcedd82 3503
4a9bb1df
UW
3504@item int gdbarch_dwarf2_reg_to_regnum (@var{gdbarch}, @var{dwarf2_regnr})
3505@findex gdbarch_dwarf2_reg_to_regnum
3506Convert DWARF2 register number @var{dwarf2_regnr} into @value{GDBN} regnum.
3507If not defined, no conversion will be performed.
0dcedd82 3508
4a9bb1df
UW
3509@item int gdbarch_ecoff_reg_to_regnum (@var{gdbarch}, @var{ecoff_regnr})
3510@findex gdbarch_ecoff_reg_to_regnum
3511Convert ECOFF register number @var{ecoff_regnr} into @value{GDBN} regnum. If
3512not defined, no conversion will be performed.
c906108c 3513
0ba6dca9
AC
3514@item DEPRECATED_FP_REGNUM
3515@findex DEPRECATED_FP_REGNUM
cce74817
JM
3516If the virtual frame pointer is kept in a register, then define this
3517macro to be the number (greater than or equal to zero) of that register.
3518
0ba6dca9
AC
3519This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP}
3520is not defined.
c906108c 3521
19772a2c
AC
3522@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi})
3523@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION
392a587b
JM
3524Define this to an expression that returns 1 if the function invocation
3525represented by @var{fi} does not have a stack frame associated with it.
3526Otherwise return 0.
c906108c 3527
4a9bb1df 3528@item CORE_ADDR frame_align (@var{gdbarch}, @var{address})
790eb8f5
AC
3529@anchor{frame_align}
3530@findex frame_align
3531Define this to adjust @var{address} so that it meets the alignment
3532requirements for the start of a new stack frame. A stack frame's
3533alignment requirements are typically stronger than a target processors
5fc14d0a 3534stack alignment requirements.
790eb8f5
AC
3535
3536This function is used to ensure that, when creating a dummy frame, both
3537the initial stack pointer and (if needed) the address of the return
3538value are correctly aligned.
3539
5fc14d0a
EZ
3540This function always adjusts the address in the direction of stack
3541growth.
790eb8f5
AC
3542
3543By default, no frame based stack alignment is performed.
3544
4a9bb1df
UW
3545@item int gdbarch_frame_red_zone_size (@var{gdbarch})
3546@findex gdbarch_frame_red_zone_size
8b148df9
AC
3547The number of bytes, beyond the innermost-stack-address, reserved by the
3548@sc{abi}. A function is permitted to use this scratch area (instead of
3549allocating extra stack space).
3550
3551When performing an inferior function call, to ensure that it does not
3552modify this area, @value{GDBN} adjusts the innermost-stack-address by
4a9bb1df 3553@var{gdbarch_frame_red_zone_size} bytes before pushing parameters onto the
8b148df9
AC
3554stack.
3555
3556By default, zero bytes are allocated. The value must be aligned
3557(@pxref{frame_align}).
3558
3559The @sc{amd64} (nee x86-64) @sc{abi} documentation refers to the
3560@emph{red zone} when describing this scratch area.
3561@cindex red zone
3562
618ce49f
AC
3563@item DEPRECATED_FRAME_CHAIN(@var{frame})
3564@findex DEPRECATED_FRAME_CHAIN
c906108c
SS
3565Given @var{frame}, return a pointer to the calling frame.
3566
618ce49f
AC
3567@item DEPRECATED_FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
3568@findex DEPRECATED_FRAME_CHAIN_VALID
95f90d25
DJ
3569Define this to be an expression that returns zero if the given frame is an
3570outermost frame, with no caller, and nonzero otherwise. Most normal
3571situations can be handled without defining this macro, including @code{NULL}
3572chain pointers, dummy frames, and frames whose PC values are inside the
3573startup file (e.g.@: @file{crt0.o}), inside @code{main}, or inside
3574@code{_start}.
c906108c 3575
f30ee0bc
AC
3576@item DEPRECATED_FRAME_INIT_SAVED_REGS(@var{frame})
3577@findex DEPRECATED_FRAME_INIT_SAVED_REGS
c906108c
SS
3578See @file{frame.h}. Determines the address of all registers in the
3579current stack frame storing each in @code{frame->saved_regs}. Space for
3580@code{frame->saved_regs} shall be allocated by
f30ee0bc
AC
3581@code{DEPRECATED_FRAME_INIT_SAVED_REGS} using
3582@code{frame_saved_regs_zalloc}.
c906108c 3583
fb8f8949 3584@code{FRAME_FIND_SAVED_REGS} is deprecated.
c906108c 3585
4a9bb1df
UW
3586@item int gdbarch_frame_num_args (@var{gdbarch}, @var{frame})
3587@findex gdbarch_frame_num_args
3588For the frame described by @var{frame} return the number of arguments that
392a587b
JM
3589are being passed. If the number of arguments is not known, return
3590@code{-1}.
c906108c 3591
8bedc050
AC
3592@item DEPRECATED_FRAME_SAVED_PC(@var{frame})
3593@findex DEPRECATED_FRAME_SAVED_PC
3594@anchor{DEPRECATED_FRAME_SAVED_PC} Given @var{frame}, return the pc
3595saved there. This is the return address.
12cc2063 3596
4a9bb1df 3597This method is deprecated. @xref{gdbarch_unwind_pc}.
12cc2063 3598
4a9bb1df
UW
3599@item CORE_ADDR gdbarch_unwind_pc (@var{next_frame})
3600@findex gdbarch_unwind_pc
3601@anchor{gdbarch_unwind_pc} Return the instruction address, in
3602@var{next_frame}'s caller, at which execution will resume after
3603@var{next_frame} returns. This is commonly referred to as the return address.
12cc2063
AC
3604
3605The implementation, which must be frame agnostic (work with any frame),
3606is typically no more than:
3607
3608@smallexample
3609ULONGEST pc;
11411de3 3610pc = frame_unwind_register_unsigned (next_frame, S390_PC_REGNUM);
4a9bb1df 3611return gdbarch_addr_bits_remove (gdbarch, pc);
12cc2063
AC
3612@end smallexample
3613
3614@noindent
8bedc050 3615@xref{DEPRECATED_FRAME_SAVED_PC}, which this method replaces.
c906108c 3616
4a9bb1df
UW
3617@item CORE_ADDR gdbarch_unwind_sp (@var{gdbarch}, @var{next_frame})
3618@findex gdbarch_unwind_sp
3619@anchor{gdbarch_unwind_sp} Return the frame's inner most stack address. This is
d3e8051b 3620commonly referred to as the frame's @dfn{stack pointer}.
a9e5fdc2
AC
3621
3622The implementation, which must be frame agnostic (work with any frame),
3623is typically no more than:
3624
3625@smallexample
3626ULONGEST sp;
11411de3 3627sp = frame_unwind_register_unsigned (next_frame, S390_SP_REGNUM);
4a9bb1df 3628return gdbarch_addr_bits_remove (gdbarch, sp);
a9e5fdc2
AC
3629@end smallexample
3630
3631@noindent
3632@xref{TARGET_READ_SP}, which this method replaces.
3633
c906108c 3634@item FUNCTION_EPILOGUE_SIZE
56caf160 3635@findex FUNCTION_EPILOGUE_SIZE
c906108c
SS
3636For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
3637function end symbol is 0. For such targets, you must define
3638@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
3639function's epilogue.
3640
782263ab
AC
3641@item DEPRECATED_FUNCTION_START_OFFSET
3642@findex DEPRECATED_FUNCTION_START_OFFSET
f7cb2b90
JB
3643An integer, giving the offset in bytes from a function's address (as
3644used in the values of symbols, function pointers, etc.), and the
3645function's first genuine instruction.
3646
3647This is zero on almost all machines: the function's address is usually
782263ab
AC
3648the address of its first instruction. However, on the VAX, for
3649example, each function starts with two bytes containing a bitmask
3650indicating which registers to save upon entry to the function. The
3651VAX @code{call} instructions check this value, and save the
3652appropriate registers automatically. Thus, since the offset from the
3653function's address to its first instruction is two bytes,
3654@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
f7cb2b90 3655
c906108c 3656@item GCC_COMPILED_FLAG_SYMBOL
56caf160
EZ
3657@itemx GCC2_COMPILED_FLAG_SYMBOL
3658@findex GCC2_COMPILED_FLAG_SYMBOL
3659@findex GCC_COMPILED_FLAG_SYMBOL
3660If defined, these are the names of the symbols that @value{GDBN} will
3661look for to detect that GCC compiled the file. The default symbols
3662are @code{gcc_compiled.} and @code{gcc2_compiled.},
3663respectively. (Currently only defined for the Delta 68.)
c906108c 3664
4a9bb1df
UW
3665@item gdbarch_get_longjmp_target
3666@findex gdbarch_get_longjmp_target
c906108c
SS
3667For most machines, this is a target-dependent parameter. On the
3668DECstation and the Iris, this is a native-dependent parameter, since
937f164b 3669the header file @file{setjmp.h} is needed to define it.
c906108c 3670
56caf160
EZ
3671This macro determines the target PC address that @code{longjmp} will jump to,
3672assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
3673@code{CORE_ADDR *} as argument, and stores the target PC value through this
c906108c
SS
3674pointer. It examines the current state of the machine as needed.
3675
268e2188
AC
3676@item DEPRECATED_IBM6000_TARGET
3677@findex DEPRECATED_IBM6000_TARGET
3678Shows that we are configured for an IBM RS/6000 system. This
c906108c 3679conditional should be eliminated (FIXME) and replaced by
56caf160 3680feature-specific macros. It was introduced in a haste and we are
c906108c
SS
3681repenting at leisure.
3682
9742079a
EZ
3683@item I386_USE_GENERIC_WATCHPOINTS
3684An x86-based target can define this to use the generic x86 watchpoint
3685support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
3686
4a9bb1df
UW
3687@item int gdbarch_inner_than (@var{gdbarch}, @var{lhs}, @var{rhs})
3688@findex gdbarch_inner_than
c906108c 3689Returns non-zero if stack address @var{lhs} is inner than (nearer to the
4a9bb1df
UW
3690stack top) stack address @var{rhs}. Let the function return
3691@w{@code{lhs < rhs}} if the target's stack grows downward in memory, or
3692@w{@code{lhs > rsh}} if the stack grows upward.
c906108c 3693
4a9bb1df 3694@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{addr})
9e5abb06 3695@findex gdbarch_in_function_epilogue_p
4a9bb1df 3696Returns non-zero if the given @var{addr} is in the epilogue of a function.
9e5abb06
CV
3697The epilogue of a function is defined as the part of a function where
3698the stack frame of the function already has been destroyed up to the
3699final `return from function call' instruction.
3700
4a9bb1df
UW
3701@item int gdbarch_in_solib_return_trampoline (@var{gdbarch}, @var{pc}, @var{name})
3702@findex gdbarch_in_solib_return_trampoline
3703Define this function to return nonzero if the program is stopped in the
c906108c
SS
3704trampoline that returns from a shared library.
3705
56caf160
EZ
3706@item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc})
3707@findex IN_SOLIB_DYNSYM_RESOLVE_CODE
4a9bb1df 3708Define this to return nonzero if the program is stopped in the
d4f3574e
SS
3709dynamic linker.
3710
56caf160
EZ
3711@item SKIP_SOLIB_RESOLVER (@var{pc})
3712@findex SKIP_SOLIB_RESOLVER
d4f3574e
SS
3713Define this to evaluate to the (nonzero) address at which execution
3714should continue to get past the dynamic linker's symbol resolution
3715function. A zero value indicates that it is not important or necessary
3716to set a breakpoint to get through the dynamic linker and that single
3717stepping will suffice.
3718
4a9bb1df
UW
3719@item CORE_ADDR gdbarch_integer_to_address (@var{gdbarch}, @var{type}, @var{buf})
3720@findex gdbarch_integer_to_address
fc0c74b1
AC
3721@cindex converting integers to addresses
3722Define this when the architecture needs to handle non-pointer to address
3723conversions specially. Converts that value to an address according to
3724the current architectures conventions.
3725
3726@emph{Pragmatics: When the user copies a well defined expression from
3727their source code and passes it, as a parameter, to @value{GDBN}'s
3728@code{print} command, they should get the same value as would have been
3729computed by the target program. Any deviation from this rule can cause
3730major confusion and annoyance, and needs to be justified carefully. In
3731other words, @value{GDBN} doesn't really have the freedom to do these
3732conversions in clever and useful ways. It has, however, been pointed
3733out that users aren't complaining about how @value{GDBN} casts integers
3734to pointers; they are complaining that they can't take an address from a
3735disassembly listing and give it to @code{x/i}. Adding an architecture
4a9bb1df 3736method like @code{gdbarch_integer_to_address} certainly makes it possible for
fc0c74b1
AC
3737@value{GDBN} to ``get it right'' in all circumstances.}
3738
3739@xref{Target Architecture Definition, , Pointers Are Not Always
3740Addresses}.
3741
4a9bb1df
UW
3742@item CORE_ADDR gdbarch_pointer_to_address (@var{gdbarch}, @var{type}, @var{buf})
3743@findex gdbarch_pointer_to_address
93e79dbd
JB
3744Assume that @var{buf} holds a pointer of type @var{type}, in the
3745appropriate format for the current architecture. Return the byte
3746address the pointer refers to.
3747@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
3748
4a9bb1df
UW
3749@item void gdbarch_register_to_value(@var{gdbarch}, @var{frame}, @var{regnum}, @var{type}, @var{fur})
3750@findex gdbarch_register_to_value
13d01224
AC
3751Convert the raw contents of register @var{regnum} into a value of type
3752@var{type}.
4281a42e 3753@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
9fb4dd36 3754
617073a9
AC
3755@item register_reggroup_p (@var{gdbarch}, @var{regnum}, @var{reggroup})
3756@findex register_reggroup_p
3757@cindex register groups
3758Return non-zero if register @var{regnum} is a member of the register
3759group @var{reggroup}.
3760
3761By default, registers are grouped as follows:
3762
3763@table @code
3764@item float_reggroup
3765Any register with a valid name and a floating-point type.
3766@item vector_reggroup
3767Any register with a valid name and a vector type.
3768@item general_reggroup
3769Any register with a valid name and a type other than vector or
3770floating-point. @samp{float_reggroup}.
3771@item save_reggroup
3772@itemx restore_reggroup
3773@itemx all_reggroup
3774Any register with a valid name.
3775@end table
3776
f30992d4
AC
3777@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg})
3778@findex DEPRECATED_REGISTER_VIRTUAL_SIZE
b2e75d78
AC
3779Return the virtual size of @var{reg}; defaults to the size of the
3780register's virtual type.
13d01224
AC
3781Return the virtual size of @var{reg}.
3782@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36 3783
2e092625 3784@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})
56caf160 3785@findex REGISTER_VIRTUAL_TYPE
9fb4dd36 3786Return the virtual type of @var{reg}.
13d01224 3787@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36 3788
77e7e267
AC
3789@item struct type *register_type (@var{gdbarch}, @var{reg})
3790@findex register_type
3791If defined, return the type of register @var{reg}. This function
d3e8051b 3792supersedes @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture
77e7e267
AC
3793Definition, , Raw and Virtual Register Representations}.
3794
9fb4dd36 3795@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
56caf160 3796@findex REGISTER_CONVERT_TO_VIRTUAL
9fb4dd36 3797Convert the value of register @var{reg} from its raw form to its virtual
4281a42e 3798form.
13d01224 3799@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36
JB
3800
3801@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
56caf160 3802@findex REGISTER_CONVERT_TO_RAW
9fb4dd36 3803Convert the value of register @var{reg} from its virtual form to its raw
4281a42e 3804form.
13d01224 3805@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36 3806
0ab4b752
MK
3807@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size})
3808@findex regset_from_core_section
3809Return the appropriate register set for a core file section with name
3810@var{sect_name} and size @var{sect_size}.
3811
b0ed3589 3812@item SOFTWARE_SINGLE_STEP_P()
56caf160 3813@findex SOFTWARE_SINGLE_STEP_P
c906108c 3814Define this as 1 if the target does not have a hardware single-step
56caf160 3815mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
c906108c 3816
d3e8051b 3817@item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breakpoints_p})
56caf160
EZ
3818@findex SOFTWARE_SINGLE_STEP
3819A function that inserts or removes (depending on
d3e8051b 3820@var{insert_breakpoints_p}) breakpoints at each possible destinations of
56caf160 3821the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
c906108c
SS
3822for examples.
3823
e35879db
UW
3824@item set_gdbarch_sofun_address_maybe_missing (@var{gdbarch}, @var{set})
3825@findex set_gdbarch_sofun_address_maybe_missing
3826Somebody clever observed that, the more actual addresses you have in the
3827debug information, the more time the linker has to spend relocating
3828them. So whenever there's some other way the debugger could find the
3829address it needs, you should omit it from the debug info, to make
3830linking faster.
3831
3832Calling @code{set_gdbarch_sofun_address_maybe_missing} with a non-zero
3833argument @var{set} indicates that a particular set of hacks of this sort
3834are in use, affecting @code{N_SO} and @code{N_FUN} entries in stabs-format
3835debugging information. @code{N_SO} stabs mark the beginning and ending
3836addresses of compilation units in the text segment. @code{N_FUN} stabs
3837mark the starts and ends of functions.
3838
3839In this case, @value{GDBN} assumes two things:
3840
3841@itemize @bullet
3842@item
3843@code{N_FUN} stabs have an address of zero. Instead of using those
3844addresses, you should find the address where the function starts by
3845taking the function name from the stab, and then looking that up in the
3846minsyms (the linker/assembler symbol table). In other words, the stab
3847has the name, and the linker/assembler symbol table is the only place
3848that carries the address.
3849
3850@item
3851@code{N_SO} stabs have an address of zero, too. You just look at the
3852@code{N_FUN} stabs that appear before and after the @code{N_SO} stab, and
3853guess the starting and ending addresses of the compilation unit from them.
3854@end itemize
3855
4a9bb1df
UW
3856@item int gdbarch_pc_regnum (@var{gdbarch})
3857@findex gdbarch_pc_regnum
3858If the program counter is kept in a register, then let this function return
3859the number (greater than or equal to zero) of that register.
c906108c 3860
4a9bb1df
UW
3861This should only need to be defined if @code{gdbarch_read_pc} and
3862@code{gdbarch_write_pc} are not defined.
2df3850c 3863
4a9bb1df
UW
3864@item int gdbarch_stabs_argument_has_addr (@var{gdbarch}, @var{type})
3865@findex gdbarch_stabs_argument_has_addr
4a9bb1df
UW
3866@anchor{gdbarch_stabs_argument_has_addr} Define this function to return
3867nonzero if a function argument of type @var{type} is passed by reference
3868instead of value.
a38c9fe6 3869
c906108c 3870@item PROCESS_LINENUMBER_HOOK
56caf160 3871@findex PROCESS_LINENUMBER_HOOK
c906108c
SS
3872A hook defined for XCOFF reading.
3873
4a9bb1df
UW
3874@item gdbarch_ps_regnum (@var{gdbarch}
3875@findex gdbarch_ps_regnum
3876If defined, this function returns the number of the processor status
3877register.
3878(This definition is only used in generic code when parsing "$ps".)
c906108c 3879
4a9bb1df
UW
3880@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})
3881@findex gdbarch_push_dummy_call
b81774d8 3882@findex DEPRECATED_PUSH_ARGUMENTS.
4a9bb1df
UW
3883@anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to
3884the inferior function onto the stack. In addition to pushing @var{nargs}, the
3885code should push @var{struct_addr} (when @var{struct_return} is non-zero), and
3886the return address (@var{bp_addr}).
c906108c 3887
86fe4aaa 3888@var{function} is a pointer to a @code{struct value}; on architectures that use
d4b6d575
RC
3889function descriptors, this contains the function descriptor value.
3890
b24da7d0 3891Returns the updated top-of-stack pointer.
b81774d8
AC
3892
3893This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
3894
4a9bb1df
UW
3895@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})
3896@findex gdbarch_push_dummy_code
3897@anchor{gdbarch_push_dummy_code} Given a stack based call dummy, push the
7043d8dc
AC
3898instruction sequence (including space for a breakpoint) to which the
3899called function should return.
3900
3901Set @var{bp_addr} to the address at which the breakpoint instruction
3902should be inserted, @var{real_pc} to the resume address when starting
3903the call sequence, and return the updated inner-most stack address.
3904
3905By default, the stack is grown sufficient to hold a frame-aligned
3906(@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address
3907reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}.
3908
4a9bb1df 3909This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}} and
28954179 3910@code{DEPRECATED_REGISTER_SIZE}.
7043d8dc 3911
4a9bb1df
UW
3912@item const char *gdbarch_register_name (@var{gdbarch}, @var{regnr})
3913@findex gdbarch_register_name
3914Return the name of register @var{regnr} as a string. May return @code{NULL}
3915to indicate that @var{regnr} is not a valid register.
c906108c 3916
b24da7d0
AC
3917@item SAVE_DUMMY_FRAME_TOS (@var{sp})
3918@findex SAVE_DUMMY_FRAME_TOS
3919@anchor{SAVE_DUMMY_FRAME_TOS} Used in @samp{call_function_by_hand} to
3920notify the target dependent code of the top-of-stack value that will be
d3e8051b 3921passed to the inferior code. This is the value of the @code{SP}
b24da7d0 3922after both the dummy frame and space for parameters/results have been
4a9bb1df 3923allocated on the stack. @xref{gdbarch_unwind_dummy_id}.
43ff13b4 3924
4a9bb1df
UW
3925@item int gdbarch_sdb_reg_to_regnum (@var{gdbarch}, @var{sdb_regnr})
3926@findex gdbarch_sdb_reg_to_regnum
3927Use this function to convert sdb register @var{sdb_regnr} into @value{GDBN}
3928regnum. If not defined, no conversion will be done.
c906108c 3929
963e2bb7 3930@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})
92ad9cd9
AC
3931@findex gdbarch_return_value
3932@anchor{gdbarch_return_value} Given a function with a return-value of
3933type @var{rettype}, return which return-value convention that function
3934would use.
3935
3936@value{GDBN} currently recognizes two function return-value conventions:
3937@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found
3938in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return
3939value is found in memory and the address of that memory location is
3940passed in as the function's first parameter.
3941
963e2bb7
AC
3942If the register convention is being used, and @var{writebuf} is
3943non-@code{NULL}, also copy the return-value in @var{writebuf} into
92ad9cd9
AC
3944@var{regcache}.
3945
963e2bb7 3946If the register convention is being used, and @var{readbuf} is
92ad9cd9 3947non-@code{NULL}, also copy the return value from @var{regcache} into
963e2bb7 3948@var{readbuf} (@var{regcache} contains a copy of the registers from the
92ad9cd9
AC
3949just returned function).
3950
92ad9cd9
AC
3951@emph{Maintainer note: This method replaces separate predicate, extract,
3952store methods. By having only one method, the logic needed to determine
3953the return-value convention need only be implemented in one place. If
3954@value{GDBN} were written in an @sc{oo} language, this method would
3955instead return an object that knew how to perform the register
3956return-value extract and store.}
3957
3958@emph{Maintainer note: This method does not take a @var{gcc_p}
3959parameter, and such a parameter should not be added. If an architecture
3960that requires per-compiler or per-function information be identified,
3961then the replacement of @var{rettype} with @code{struct value}
d3e8051b 3962@var{function} should be pursued.}
92ad9cd9
AC
3963
3964@emph{Maintainer note: The @var{regcache} parameter limits this methods
3965to the inner most frame. While replacing @var{regcache} with a
3966@code{struct frame_info} @var{frame} parameter would remove that
3967limitation there has yet to be a demonstrated need for such a change.}
3968
4a9bb1df
UW
3969@item void gdbarch_skip_permanent_breakpoint (@var{gdbarch}, @var{regcache})
3970@findex gdbarch_skip_permanent_breakpoint
25822942 3971Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
c2c6d25f
JM
3972steps over a breakpoint by removing it, stepping one instruction, and
3973re-inserting the breakpoint. However, permanent breakpoints are
3974hardwired into the inferior, and can't be removed, so this strategy
4a9bb1df
UW
3975doesn't work. Calling @code{gdbarch_skip_permanent_breakpoint} adjusts the
3976processor's state so that execution will resume just after the breakpoint.
3977This function does the right thing even when the breakpoint is in the delay slot
c2c6d25f
JM
3978of a branch or jump.
3979
4a9bb1df
UW
3980@item CORE_ADDR gdbarch_skip_prologue (@var{gdbarch}, @var{ip})
3981@findex gdbarch_skip_prologue
3982A function that returns the address of the ``real'' code beyond the
3983function entry prologue found at @var{ip}.
c906108c 3984
4a9bb1df
UW
3985@item CORE_ADDR gdbarch_skip_trampoline_code (@var{gdbarch}, @var{frame}, @var{pc})
3986@findex gdbarch_skip_trampoline_code
c906108c 3987If the target machine has trampoline code that sits between callers and
4a9bb1df 3988the functions being called, then define this function to return a new PC
c906108c
SS
3989that is at the start of the real function.
3990
4a9bb1df
UW
3991@item int gdbarch_sp_regnum (@var{gdbarch})
3992@findex gdbarch_sp_regnum
3993If the stack-pointer is kept in a register, then use this function to return
6c0e89ed
AC
3994the number (greater than or equal to zero) of that register, or -1 if
3995there is no such register.
c906108c 3996
4a9bb1df
UW
3997@item int gdbarch_stab_reg_to_regnum (@var{gdbarch}, @var{stab_regnr})
3998@findex gdbarch_stab_reg_to_regnum
3999Use this function to convert stab register @var{stab_regnr} into @value{GDBN}
4000regnum. If not defined, no conversion will be done.
4001
c906108c 4002@item SYMBOL_RELOADING_DEFAULT
56caf160
EZ
4003@findex SYMBOL_RELOADING_DEFAULT
4004The default value of the ``symbol-reloading'' variable. (Never defined in
c906108c
SS
4005current sources.)
4006
c906108c 4007@item TARGET_CHAR_BIT
56caf160 4008@findex TARGET_CHAR_BIT
c906108c
SS
4009Number of bits in a char; defaults to 8.
4010
4a9bb1df
UW
4011@item int gdbarch_char_signed (@var{gdbarch})
4012@findex gdbarch_char_signed
c3d3ce5b
JB
4013Non-zero if @code{char} is normally signed on this architecture; zero if
4014it should be unsigned.
4015
4016The ISO C standard requires the compiler to treat @code{char} as
4017equivalent to either @code{signed char} or @code{unsigned char}; any
4018character in the standard execution set is supposed to be positive.
4019Most compilers treat @code{char} as signed, but @code{char} is unsigned
4020on the IBM S/390, RS6000, and PowerPC targets.
4021
4a9bb1df
UW
4022@item int gdbarch_double_bit (@var{gdbarch})
4023@findex gdbarch_double_bit
4024Number of bits in a double float; defaults to @w{@code{8 * TARGET_CHAR_BIT}}.
c906108c 4025
4a9bb1df
UW
4026@item int gdbarch_float_bit (@var{gdbarch})
4027@findex gdbarch_float_bit
4028Number of bits in a float; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.
ac9a91a7 4029
4a9bb1df
UW
4030@item int gdbarch_int_bit (@var{gdbarch})
4031@findex gdbarch_int_bit
4032Number of bits in an integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.
c906108c 4033
4a9bb1df
UW
4034@item int gdbarch_long_bit (@var{gdbarch})
4035@findex gdbarch_long_bit
4036Number of bits in a long integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.
c906108c 4037
4a9bb1df
UW
4038@item int gdbarch_long_double_bit (@var{gdbarch})
4039@findex gdbarch_long_double_bit
c906108c 4040Number of bits in a long double float;
4a9bb1df
UW
4041defaults to @w{@code{2 * gdbarch_double_bit (@var{gdbarch})}}.
4042
4043@item int gdbarch_long_long_bit (@var{gdbarch})
4044@findex gdbarch_long_long_bit
4045Number of bits in a long long integer; defaults to
4046@w{@code{2 * gdbarch_long_bit (@var{gdbarch})}}.
4047
4048@item int gdbarch_ptr_bit (@var{gdbarch})
4049@findex gdbarch_ptr_bit
4050Number of bits in a pointer; defaults to
4051@w{@code{gdbarch_int_bit (@var{gdbarch})}}.
4052
4053@item int gdbarch_short_bit (@var{gdbarch})
4054@findex gdbarch_short_bit
4055Number of bits in a short integer; defaults to @w{@code{2 * TARGET_CHAR_BIT}}.
4056
4057@item CORE_ADDR gdbarch_read_pc (@var{gdbarch}, @var{regcache})
4058@findex gdbarch_read_pc
4059@itemx gdbarch_write_pc (@var{gdbarch}, @var{regcache}, @var{val})
4060@findex gdbarch_write_pc
4061@anchor{gdbarch_write_pc}
56caf160
EZ
4062@itemx TARGET_READ_SP
4063@findex TARGET_READ_SP
56caf160
EZ
4064@itemx TARGET_READ_FP
4065@findex TARGET_READ_FP
4a9bb1df
UW
4066@findex gdbarch_read_pc
4067@findex gdbarch_write_pc
56caf160 4068@findex read_sp
56caf160 4069@findex read_fp
4a9bb1df
UW
4070@anchor{TARGET_READ_SP} These change the behavior of @code{gdbarch_read_pc},
4071@code{gdbarch_write_pc}, and @code{read_sp}. For most targets, these may be
9c8dbfa9
AC
4072left undefined. @value{GDBN} will call the read and write register
4073functions with the relevant @code{_REGNUM} argument.
c906108c 4074
4a9bb1df
UW
4075These macros and functions are useful when a target keeps one of these
4076registers in a hard to get at place; for example, part in a segment register
4077and part in an ordinary register.
c906108c 4078
4a9bb1df 4079@xref{gdbarch_unwind_sp}, which replaces @code{TARGET_READ_SP}.
a9e5fdc2 4080
4a9bb1df
UW
4081@item void gdbarch_virtual_frame_pointer (@var{gdbarch}, @var{pc}, @var{frame_regnum}, @var{frame_offset})
4082@findex gdbarch_virtual_frame_pointer
0ba6dca9
AC
4083Returns a @code{(register, offset)} pair representing the virtual frame
4084pointer in use at the code address @var{pc}. If virtual frame pointers
4085are not used, a default definition simply returns
4086@code{DEPRECATED_FP_REGNUM}, with an offset of zero.
c906108c 4087
9742079a
EZ
4088@item TARGET_HAS_HARDWARE_WATCHPOINTS
4089If non-zero, the target has support for hardware-assisted
4090watchpoints. @xref{Algorithms, watchpoints}, for more details and
4091other related macros.
4092
4a9bb1df
UW
4093@item int gdbarch_print_insn (@var{gdbarch}, @var{vma}, @var{info})
4094@findex gdbarch_print_insn
7ccaa899 4095This is the function used by @value{GDBN} to print an assembly
4a9bb1df 4096instruction. It prints the instruction at address @var{vma} in
7ccaa899
EZ
4097debugged memory and returns the length of the instruction, in bytes. If
4098a target doesn't define its own printing routine, it defaults to an
d7a27068
AC
4099accessor function for the global pointer
4100@code{deprecated_tm_print_insn}. This usually points to a function in
4101the @code{opcodes} library (@pxref{Support Libraries, ,Opcodes}).
4102@var{info} is a structure (of type @code{disassemble_info}) defined in
4103@file{include/dis-asm.h} used to pass information to the instruction
4104decoding routine.
7ccaa899 4105
4a9bb1df
UW
4106@item frame_id gdbarch_unwind_dummy_id (@var{gdbarch}, @var{frame})
4107@findex gdbarch_unwind_dummy_id
4108@anchor{gdbarch_unwind_dummy_id} Given @var{frame} return a @w{@code{struct
4109frame_id}} that uniquely identifies an inferior function call's dummy
b24da7d0
AC
4110frame. The value returned must match the dummy frame stack value
4111previously saved using @code{SAVE_DUMMY_FRAME_TOS}.
4112@xref{SAVE_DUMMY_FRAME_TOS}.
6314f104 4113
b5622e8d
AC
4114@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
4115@findex DEPRECATED_USE_STRUCT_CONVENTION
c906108c
SS
4116If defined, this must be an expression that is nonzero if a value of the
4117given @var{type} being returned from a function must have space
4118allocated for it on the stack. @var{gcc_p} is true if the function
4119being considered is known to have been compiled by GCC; this is helpful
4120for systems where GCC is known to use different calling convention than
4121other compilers.
4122
92ad9cd9
AC
4123This method has been deprecated in favour of @code{gdbarch_return_value}
4124(@pxref{gdbarch_return_value}).
4125
4a9bb1df
UW
4126@item void gdbarch_value_to_register (@var{gdbarch}, @var{frame}, @var{type}, @var{buf})
4127@findex gdbarch_value_to_register
4128Convert a value of type @var{type} into the raw contents of a register.
13d01224
AC
4129@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
4130
c906108c
SS
4131@end table
4132
4133Motorola M68K target conditionals.
4134
56caf160 4135@ftable @code
c906108c
SS
4136@item BPT_VECTOR
4137Define this to be the 4-bit location of the breakpoint trap vector. If
4138not defined, it will default to @code{0xf}.
4139
4140@item REMOTE_BPT_VECTOR
4141Defaults to @code{1}.
a23a7bf1 4142
4a9bb1df
UW
4143@item const char *gdbarch_name_of_malloc (@var{gdbarch})
4144@findex gdbarch_name_of_malloc
a23a7bf1
JB
4145A string containing the name of the function to call in order to
4146allocate some memory in the inferior. The default value is "malloc".
4147
56caf160 4148@end ftable
c906108c 4149
b6fd0dfb 4150@node Adding a New Target
c906108c
SS
4151@section Adding a New Target
4152
56caf160 4153@cindex adding a target
af6c57ea 4154The following files add a target to @value{GDBN}:
c906108c
SS
4155
4156@table @file
56caf160 4157@vindex TDEPFILES
c906108c
SS
4158@item gdb/config/@var{arch}/@var{ttt}.mt
4159Contains a Makefile fragment specific to this target. Specifies what
4160object files are needed for target @var{ttt}, by defining
104c1213
JM
4161@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
4162the header file which describes @var{ttt}, by defining @samp{TM_FILE=
4163tm-@var{ttt}.h}.
4164
4165You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
4166but these are now deprecated, replaced by autoconf, and may go away in
25822942 4167future versions of @value{GDBN}.
c906108c 4168
c906108c
SS
4169@item gdb/@var{ttt}-tdep.c
4170Contains any miscellaneous code required for this target machine. On
4171some machines it doesn't exist at all. Sometimes the macros in
4172@file{tm-@var{ttt}.h} become very complicated, so they are implemented
4173as functions here instead, and the macro is simply defined to call the
4174function. This is vastly preferable, since it is easier to understand
4175and debug.
4176
af6c57ea
AC
4177@item gdb/@var{arch}-tdep.c
4178@itemx gdb/@var{arch}-tdep.h
4179This often exists to describe the basic layout of the target machine's
4180processor chip (registers, stack, etc.). If used, it is included by
4181@file{@var{ttt}-tdep.h}. It can be shared among many targets that use
4182the same processor.
4183
4184@item gdb/config/@var{arch}/tm-@var{ttt}.h
4185(@file{tm.h} is a link to this file, created by @code{configure}). Contains
4186macro definitions about the target machine's registers, stack frame
4187format and instructions.
4188
4189New targets do not need this file and should not create it.
4190
c906108c
SS
4191@item gdb/config/@var{arch}/tm-@var{arch}.h
4192This often exists to describe the basic layout of the target machine's
56caf160 4193processor chip (registers, stack, etc.). If used, it is included by
c906108c
SS
4194@file{tm-@var{ttt}.h}. It can be shared among many targets that use the
4195same processor.
4196
af6c57ea
AC
4197New targets do not need this file and should not create it.
4198
c906108c
SS
4199@end table
4200
4201If you are adding a new operating system for an existing CPU chip, add a
4202@file{config/tm-@var{os}.h} file that describes the operating system
4203facilities that are unusual (extra symbol table info; the breakpoint
56caf160 4204instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
c906108c
SS
4205that just @code{#include}s @file{tm-@var{arch}.h} and
4206@file{config/tm-@var{os}.h}.
4207
123dc839
DJ
4208@node Target Descriptions
4209@chapter Target Descriptions
4210@cindex target descriptions
4211
4212The target architecture definition (@pxref{Target Architecture Definition})
4213contains @value{GDBN}'s hard-coded knowledge about an architecture. For
4214some platforms, it is handy to have more flexible knowledge about a specific
4215instance of the architecture---for instance, a processor or development board.
4216@dfn{Target descriptions} provide a mechanism for the user to tell @value{GDBN}
4217more about what their target supports, or for the target to tell @value{GDBN}
4218directly.
4219
4220For details on writing, automatically supplying, and manually selecting
4221target descriptions, see @ref{Target Descriptions, , , gdb,
4222Debugging with @value{GDBN}}. This section will cover some related
4223topics about the @value{GDBN} internals.
4224
4225@menu
4226* Target Descriptions Implementation::
4227* Adding Target Described Register Support::
4228@end menu
4229
4230@node Target Descriptions Implementation
4231@section Target Descriptions Implementation
4232@cindex target descriptions, implementation
4233
4234Before @value{GDBN} connects to a new target, or runs a new program on
4235an existing target, it discards any existing target description and
4236reverts to a default gdbarch. Then, after connecting, it looks for a
4237new target description by calling @code{target_find_description}.
4238
4239A description may come from a user specified file (XML), the remote
4240@samp{qXfer:features:read} packet (also XML), or from any custom
4241@code{to_read_description} routine in the target vector. For instance,
4242the remote target supports guessing whether a MIPS target is 32-bit or
424364-bit based on the size of the @samp{g} packet.
4244
4245If any target description is found, @value{GDBN} creates a new gdbarch
4246incorporating the description by calling @code{gdbarch_update_p}. Any
4247@samp{<architecture>} element is handled first, to determine which
4248architecture's gdbarch initialization routine is called to create the
4249new architecture. Then the initialization routine is called, and has
4250a chance to adjust the constructed architecture based on the contents
4251of the target description. For instance, it can recognize any
4252properties set by a @code{to_read_description} routine. Also
4253see @ref{Adding Target Described Register Support}.
4254
4255@node Adding Target Described Register Support
4256@section Adding Target Described Register Support
4257@cindex target descriptions, adding register support
4258
4259Target descriptions can report additional registers specific to an
4260instance of the target. But it takes a little work in the architecture
4261specific routines to support this.
4262
4263A target description must either have no registers or a complete
4264set---this avoids complexity in trying to merge standard registers
4265with the target defined registers. It is the architecture's
4266responsibility to validate that a description with registers has
4267everything it needs. To keep architecture code simple, the same
4268mechanism is used to assign fixed internal register numbers to
4269standard registers.
4270
4271If @code{tdesc_has_registers} returns 1, the description contains
4272registers. The architecture's @code{gdbarch_init} routine should:
4273
4274@itemize @bullet
4275
4276@item
4277Call @code{tdesc_data_alloc} to allocate storage, early, before
4278searching for a matching gdbarch or allocating a new one.
4279
4280@item
4281Use @code{tdesc_find_feature} to locate standard features by name.
4282
4283@item
4284Use @code{tdesc_numbered_register} and @code{tdesc_numbered_register_choices}
4285to locate the expected registers in the standard features.
4286
4287@item
4288Return @code{NULL} if a required feature is missing, or if any standard
4289feature is missing expected registers. This will produce a warning that
4290the description was incomplete.
4291
4292@item
4293Free the allocated data before returning, unless @code{tdesc_use_registers}
4294is called.
4295
4296@item
4297Call @code{set_gdbarch_num_regs} as usual, with a number higher than any
4298fixed number passed to @code{tdesc_numbered_register}.
4299
4300@item
4301Call @code{tdesc_use_registers} after creating a new gdbarch, before
4302returning it.
4303
4304@end itemize
4305
4306After @code{tdesc_use_registers} has been called, the architecture's
4307@code{register_name}, @code{register_type}, and @code{register_reggroup_p}
4308routines will not be called; that information will be taken from
4309the target description. @code{num_regs} may be increased to account
4310for any additional registers in the description.
4311
4312Pseudo-registers require some extra care:
4313
4314@itemize @bullet
4315
4316@item
4317Using @code{tdesc_numbered_register} allows the architecture to give
4318constant register numbers to standard architectural registers, e.g.@:
4319as an @code{enum} in @file{@var{arch}-tdep.h}. But because
4320pseudo-registers are always numbered above @code{num_regs},
4321which may be increased by the description, constant numbers
4322can not be used for pseudos. They must be numbered relative to
4323@code{num_regs} instead.
4324
4325@item
4326The description will not describe pseudo-registers, so the
4327architecture must call @code{set_tdesc_pseudo_register_name},
4328@code{set_tdesc_pseudo_register_type}, and
4329@code{set_tdesc_pseudo_register_reggroup_p} to supply routines
4330describing pseudo registers. These routines will be passed
4331internal register numbers, so the same routines used for the
4332gdbarch equivalents are usually suitable.
4333
4334@end itemize
4335
4336
c906108c
SS
4337@node Target Vector Definition
4338
4339@chapter Target Vector Definition
56caf160 4340@cindex target vector
c906108c 4341
56caf160
EZ
4342The target vector defines the interface between @value{GDBN}'s
4343abstract handling of target systems, and the nitty-gritty code that
4344actually exercises control over a process or a serial port.
4345@value{GDBN} includes some 30-40 different target vectors; however,
4346each configuration of @value{GDBN} includes only a few of them.
c906108c 4347
52bb452f
DJ
4348@menu
4349* Managing Execution State::
4350* Existing Targets::
4351@end menu
4352
4353@node Managing Execution State
4354@section Managing Execution State
4355@cindex execution state
4356
4357A target vector can be completely inactive (not pushed on the target
4358stack), active but not running (pushed, but not connected to a fully
4359manifested inferior), or completely active (pushed, with an accessible
4360inferior). Most targets are only completely inactive or completely
d3e8051b 4361active, but some support persistent connections to a target even
52bb452f
DJ
4362when the target has exited or not yet started.
4363
4364For example, connecting to the simulator using @code{target sim} does
4365not create a running program. Neither registers nor memory are
4366accessible until @code{run}. Similarly, after @code{kill}, the
4367program can not continue executing. But in both cases @value{GDBN}
4368remains connected to the simulator, and target-specific commands
4369are directed to the simulator.
4370
4371A target which only supports complete activation should push itself
4372onto the stack in its @code{to_open} routine (by calling
4373@code{push_target}), and unpush itself from the stack in its
4374@code{to_mourn_inferior} routine (by calling @code{unpush_target}).
4375
4376A target which supports both partial and complete activation should
4377still call @code{push_target} in @code{to_open}, but not call
4378@code{unpush_target} in @code{to_mourn_inferior}. Instead, it should
4379call either @code{target_mark_running} or @code{target_mark_exited}
4380in its @code{to_open}, depending on whether the target is fully active
4381after connection. It should also call @code{target_mark_running} any
4382time the inferior becomes fully active (e.g.@: in
4383@code{to_create_inferior} and @code{to_attach}), and
4384@code{target_mark_exited} when the inferior becomes inactive (in
4385@code{to_mourn_inferior}). The target should also make sure to call
4386@code{target_mourn_inferior} from its @code{to_kill}, to return the
4387target to inactive state.
4388
4389@node Existing Targets
4390@section Existing Targets
4391@cindex targets
4392
4393@subsection File Targets
c906108c
SS
4394
4395Both executables and core files have target vectors.
4396
52bb452f 4397@subsection Standard Protocol and Remote Stubs
c906108c 4398
56caf160
EZ
4399@value{GDBN}'s file @file{remote.c} talks a serial protocol to code
4400that runs in the target system. @value{GDBN} provides several sample
4401@dfn{stubs} that can be integrated into target programs or operating
4402systems for this purpose; they are named @file{*-stub.c}.
c906108c 4403
56caf160
EZ
4404The @value{GDBN} user's manual describes how to put such a stub into
4405your target code. What follows is a discussion of integrating the
4406SPARC stub into a complicated operating system (rather than a simple
4407program), by Stu Grossman, the author of this stub.
c906108c
SS
4408
4409The trap handling code in the stub assumes the following upon entry to
56caf160 4410@code{trap_low}:
c906108c
SS
4411
4412@enumerate
56caf160
EZ
4413@item
4414%l1 and %l2 contain pc and npc respectively at the time of the trap;
c906108c 4415
56caf160
EZ
4416@item
4417traps are disabled;
c906108c 4418
56caf160
EZ
4419@item
4420you are in the correct trap window.
c906108c
SS
4421@end enumerate
4422
4423As long as your trap handler can guarantee those conditions, then there
56caf160 4424is no reason why you shouldn't be able to ``share'' traps with the stub.
c906108c
SS
4425The stub has no requirement that it be jumped to directly from the
4426hardware trap vector. That is why it calls @code{exceptionHandler()},
4427which is provided by the external environment. For instance, this could
56caf160 4428set up the hardware traps to actually execute code which calls the stub
c906108c
SS
4429first, and then transfers to its own trap handler.
4430
4431For the most point, there probably won't be much of an issue with
56caf160 4432``sharing'' traps, as the traps we use are usually not used by the kernel,
c906108c
SS
4433and often indicate unrecoverable error conditions. Anyway, this is all
4434controlled by a table, and is trivial to modify. The most important
4435trap for us is for @code{ta 1}. Without that, we can't single step or
4436do breakpoints. Everything else is unnecessary for the proper operation
4437of the debugger/stub.
4438
4439From reading the stub, it's probably not obvious how breakpoints work.
25822942 4440They are simply done by deposit/examine operations from @value{GDBN}.
c906108c 4441
52bb452f 4442@subsection ROM Monitor Interface
c906108c 4443
52bb452f 4444@subsection Custom Protocols
c906108c 4445
52bb452f 4446@subsection Transport Layer
c906108c 4447
52bb452f 4448@subsection Builtin Simulator
c906108c
SS
4449
4450
4451@node Native Debugging
4452
4453@chapter Native Debugging
56caf160 4454@cindex native debugging
c906108c 4455
25822942 4456Several files control @value{GDBN}'s configuration for native support:
c906108c
SS
4457
4458@table @file
56caf160 4459@vindex NATDEPFILES
c906108c 4460@item gdb/config/@var{arch}/@var{xyz}.mh
7fd60527 4461Specifies Makefile fragments needed by a @emph{native} configuration on
c906108c
SS
4462machine @var{xyz}. In particular, this lists the required
4463native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
4464Also specifies the header file which describes native support on
4465@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
4466define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
4467@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
4468
7fd60527
AC
4469@emph{Maintainer's note: The @file{.mh} suffix is because this file
4470originally contained @file{Makefile} fragments for hosting @value{GDBN}
4471on machine @var{xyz}. While the file is no longer used for this
937f164b 4472purpose, the @file{.mh} suffix remains. Perhaps someone will
7fd60527
AC
4473eventually rename these fragments so that they have a @file{.mn}
4474suffix.}
4475
c906108c 4476@item gdb/config/@var{arch}/nm-@var{xyz}.h
56caf160 4477(@file{nm.h} is a link to this file, created by @code{configure}). Contains C
c906108c
SS
4478macro definitions describing the native system environment, such as
4479child process control and core file support.
4480
4481@item gdb/@var{xyz}-nat.c
4482Contains any miscellaneous C code required for this native support of
4483this machine. On some machines it doesn't exist at all.
c906108c
SS
4484@end table
4485
4486There are some ``generic'' versions of routines that can be used by
4487various systems. These can be customized in various ways by macros
4488defined in your @file{nm-@var{xyz}.h} file. If these routines work for
4489the @var{xyz} host, you can just include the generic file's name (with
4490@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
4491
4492Otherwise, if your machine needs custom support routines, you will need
4493to write routines that perform the same functions as the generic file.
56caf160 4494Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
c906108c
SS
4495into @code{NATDEPFILES}.
4496
4497@table @file
c906108c
SS
4498@item inftarg.c
4499This contains the @emph{target_ops vector} that supports Unix child
4500processes on systems which use ptrace and wait to control the child.
4501
4502@item procfs.c
4503This contains the @emph{target_ops vector} that supports Unix child
4504processes on systems which use /proc to control the child.
4505
4506@item fork-child.c
56caf160
EZ
4507This does the low-level grunge that uses Unix system calls to do a ``fork
4508and exec'' to start up a child process.
c906108c
SS
4509
4510@item infptrace.c
4511This is the low level interface to inferior processes for systems using
4512the Unix @code{ptrace} call in a vanilla way.
c906108c
SS
4513@end table
4514
4515@section Native core file Support
56caf160 4516@cindex native core files
c906108c
SS
4517
4518@table @file
56caf160 4519@findex fetch_core_registers
c906108c
SS
4520@item core-aout.c::fetch_core_registers()
4521Support for reading registers out of a core file. This routine calls
4522@code{register_addr()}, see below. Now that BFD is used to read core
4523files, virtually all machines should use @code{core-aout.c}, and should
4524just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
4525@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
4526
4527@item core-aout.c::register_addr()
4528If your @code{nm-@var{xyz}.h} file defines the macro
4529@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
25822942 4530set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
c906108c
SS
4531register number @code{regno}. @code{blockend} is the offset within the
4532``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
4533@file{core-aout.c} will define the @code{register_addr()} function and
4534use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
4535you are using the standard @code{fetch_core_registers()}, you will need
4536to define your own version of @code{register_addr()}, put it into your
4537@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
4538the @code{NATDEPFILES} list. If you have your own
4539@code{fetch_core_registers()}, you may not need a separate
4540@code{register_addr()}. Many custom @code{fetch_core_registers()}
4541implementations simply locate the registers themselves.@refill
c906108c
SS
4542@end table
4543
25822942 4544When making @value{GDBN} run native on a new operating system, to make it
c906108c
SS
4545possible to debug core files, you will need to either write specific
4546code for parsing your OS's core files, or customize
4547@file{bfd/trad-core.c}. First, use whatever @code{#include} files your
4548machine uses to define the struct of registers that is accessible
4549(possibly in the u-area) in a core file (rather than
4550@file{machine/reg.h}), and an include file that defines whatever header
c1468174 4551exists on a core file (e.g., the u-area or a @code{struct core}). Then
56caf160 4552modify @code{trad_unix_core_file_p} to use these values to set up the
c906108c
SS
4553section information for the data segment, stack segment, any other
4554segments in the core file (perhaps shared library contents or control
4555information), ``registers'' segment, and if there are two discontiguous
c1468174 4556sets of registers (e.g., integer and float), the ``reg2'' segment. This
c906108c
SS
4557section information basically delimits areas in the core file in a
4558standard way, which the section-reading routines in BFD know how to seek
4559around in.
4560
25822942 4561Then back in @value{GDBN}, you need a matching routine called
56caf160 4562@code{fetch_core_registers}. If you can use the generic one, it's in
c906108c
SS
4563@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
4564It will be passed a char pointer to the entire ``registers'' segment,
4565its length, and a zero; or a char pointer to the entire ``regs2''
4566segment, its length, and a 2. The routine should suck out the supplied
25822942 4567register values and install them into @value{GDBN}'s ``registers'' array.
c906108c
SS
4568
4569If your system uses @file{/proc} to control processes, and uses ELF
4570format core files, then you may be able to use the same routines for
4571reading the registers out of processes and out of core files.
4572
4573@section ptrace
4574
4575@section /proc
4576
4577@section win32
4578
4579@section shared libraries
4580
4581@section Native Conditionals
56caf160 4582@cindex native conditionals
c906108c 4583
56caf160
EZ
4584When @value{GDBN} is configured and compiled, various macros are
4585defined or left undefined, to control compilation when the host and
4586target systems are the same. These macros should be defined (or left
4587undefined) in @file{nm-@var{system}.h}.
c906108c 4588
1f6d4158
AC
4589@table @code
4590
c906108c 4591@item CHILD_PREPARE_TO_STORE
56caf160 4592@findex CHILD_PREPARE_TO_STORE
c906108c
SS
4593If the machine stores all registers at once in the child process, then
4594define this to ensure that all values are correct. This usually entails
4595a read from the child.
4596
4597[Note that this is incorrectly defined in @file{xm-@var{system}.h} files
4598currently.]
4599
4600@item FETCH_INFERIOR_REGISTERS
56caf160 4601@findex FETCH_INFERIOR_REGISTERS
c906108c
SS
4602Define this if the native-dependent code will provide its own routines
4603@code{fetch_inferior_registers} and @code{store_inferior_registers} in
56caf160 4604@file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
c906108c
SS
4605@file{infptrace.c} is included in this configuration, the default
4606routines in @file{infptrace.c} are used for these functions.
4607
4a9bb1df
UW
4608@item int gdbarch_fp0_regnum (@var{gdbarch})
4609@findex gdbarch_fp0_regnum
4610This functions normally returns the number of the first floating
c906108c 4611point register, if the machine has such registers. As such, it would
56caf160 4612appear only in target-specific code. However, @file{/proc} support uses this
c906108c
SS
4613to decide whether floats are in use on this target.
4614
4a9bb1df
UW
4615@item int gdbarch_get_longjmp_target (@var{gdbarch})
4616@findex gdbarch_get_longjmp_target
c906108c
SS
4617For most machines, this is a target-dependent parameter. On the
4618DECstation and the Iris, this is a native-dependent parameter, since
56caf160 4619@file{setjmp.h} is needed to define it.
c906108c 4620
4a9bb1df 4621This function determines the target PC address that @code{longjmp} will jump to,
c906108c 4622assuming that we have just stopped at a longjmp breakpoint. It takes a
56caf160 4623@code{CORE_ADDR *} as argument, and stores the target PC value through this
c906108c
SS
4624pointer. It examines the current state of the machine as needed.
4625
9742079a
EZ
4626@item I386_USE_GENERIC_WATCHPOINTS
4627An x86-based machine can define this to use the generic x86 watchpoint
4628support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
4629
c906108c 4630@item ONE_PROCESS_WRITETEXT
56caf160 4631@findex ONE_PROCESS_WRITETEXT
c906108c
SS
4632Define this to be able to, when a breakpoint insertion fails, warn the
4633user that another process may be running with the same executable.
4634
4635@item PROC_NAME_FMT
56caf160 4636@findex PROC_NAME_FMT
c906108c
SS
4637Defines the format for the name of a @file{/proc} device. Should be
4638defined in @file{nm.h} @emph{only} in order to override the default
4639definition in @file{procfs.c}.
4640
c906108c 4641@item SHELL_COMMAND_CONCAT
56caf160 4642@findex SHELL_COMMAND_CONCAT
c906108c
SS
4643If defined, is a string to prefix on the shell command used to start the
4644inferior.
4645
4646@item SHELL_FILE
56caf160 4647@findex SHELL_FILE
c906108c
SS
4648If defined, this is the name of the shell to use to run the inferior.
4649Defaults to @code{"/bin/sh"}.
4650
990f9fe3 4651@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
56caf160 4652@findex SOLIB_ADD
c906108c 4653Define this to expand into an expression that will cause the symbols in
990f9fe3
FF
4654@var{filename} to be added to @value{GDBN}'s symbol table. If
4655@var{readsyms} is zero symbols are not read but any necessary low level
4656processing for @var{filename} is still done.
c906108c
SS
4657
4658@item SOLIB_CREATE_INFERIOR_HOOK
56caf160 4659@findex SOLIB_CREATE_INFERIOR_HOOK
c906108c
SS
4660Define this to expand into any shared-library-relocation code that you
4661want to be run just after the child process has been forked.
4662
4663@item START_INFERIOR_TRAPS_EXPECTED
56caf160
EZ
4664@findex START_INFERIOR_TRAPS_EXPECTED
4665When starting an inferior, @value{GDBN} normally expects to trap
4666twice; once when
c906108c
SS
4667the shell execs, and once when the program itself execs. If the actual
4668number of traps is something other than 2, then define this macro to
4669expand into the number expected.
4670
c906108c
SS
4671@end table
4672
c906108c
SS
4673@node Support Libraries
4674
4675@chapter Support Libraries
4676
4677@section BFD
56caf160 4678@cindex BFD library
c906108c 4679
25822942 4680BFD provides support for @value{GDBN} in several ways:
c906108c
SS
4681
4682@table @emph
c906108c
SS
4683@item identifying executable and core files
4684BFD will identify a variety of file types, including a.out, coff, and
4685several variants thereof, as well as several kinds of core files.
4686
4687@item access to sections of files
4688BFD parses the file headers to determine the names, virtual addresses,
4689sizes, and file locations of all the various named sections in files
56caf160
EZ
4690(such as the text section or the data section). @value{GDBN} simply
4691calls BFD to read or write section @var{x} at byte offset @var{y} for
4692length @var{z}.
c906108c
SS
4693
4694@item specialized core file support
4695BFD provides routines to determine the failing command name stored in a
4696core file, the signal with which the program failed, and whether a core
56caf160 4697file matches (i.e.@: could be a core dump of) a particular executable
c906108c
SS
4698file.
4699
4700@item locating the symbol information
25822942
DB
4701@value{GDBN} uses an internal interface of BFD to determine where to find the
4702symbol information in an executable file or symbol-file. @value{GDBN} itself
c906108c 4703handles the reading of symbols, since BFD does not ``understand'' debug
25822942 4704symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
c906108c 4705string table, etc.
c906108c
SS
4706@end table
4707
4708@section opcodes
56caf160 4709@cindex opcodes library
c906108c 4710
25822942 4711The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
c906108c
SS
4712library because it's also used in binutils, for @file{objdump}).
4713
4714@section readline
86f04699
EZ
4715@cindex readline library
4716The @code{readline} library provides a set of functions for use by applications
4717that allow users to edit command lines as they are typed in.
c906108c
SS
4718
4719@section libiberty
1eb288ea
EZ
4720@cindex @code{libiberty} library
4721
4722The @code{libiberty} library provides a set of functions and features
4723that integrate and improve on functionality found in modern operating
4724systems. Broadly speaking, such features can be divided into three
4725groups: supplemental functions (functions that may be missing in some
4726environments and operating systems), replacement functions (providing
4727a uniform and easier to use interface for commonly used standard
4728functions), and extensions (which provide additional functionality
4729beyond standard functions).
4730
4731@value{GDBN} uses various features provided by the @code{libiberty}
4732library, for instance the C@t{++} demangler, the @acronym{IEEE}
4733floating format support functions, the input options parser
4734@samp{getopt}, the @samp{obstack} extension, and other functions.
4735
4736@subsection @code{obstacks} in @value{GDBN}
4737@cindex @code{obstacks}
4738
4739The obstack mechanism provides a convenient way to allocate and free
4740chunks of memory. Each obstack is a pool of memory that is managed
4741like a stack. Objects (of any nature, size and alignment) are
4742allocated and freed in a @acronym{LIFO} fashion on an obstack (see
d3e8051b 4743@code{libiberty}'s documentation for a more detailed explanation of
1eb288ea
EZ
4744@code{obstacks}).
4745
4746The most noticeable use of the @code{obstacks} in @value{GDBN} is in
4747object files. There is an obstack associated with each internal
4748representation of an object file. Lots of things get allocated on
4749these @code{obstacks}: dictionary entries, blocks, blockvectors,
4750symbols, minimal symbols, types, vectors of fundamental types, class
4751fields of types, object files section lists, object files section
d3e8051b 4752offset lists, line tables, symbol tables, partial symbol tables,
1eb288ea
EZ
4753string tables, symbol table private data, macros tables, debug
4754information sections and entries, import and export lists (som),
4755unwind information (hppa), dwarf2 location expressions data. Plus
4756various strings such as directory names strings, debug format strings,
4757names of types.
4758
4759An essential and convenient property of all data on @code{obstacks} is
4760that memory for it gets allocated (with @code{obstack_alloc}) at
d3e8051b 4761various times during a debugging session, but it is released all at
1eb288ea
EZ
4762once using the @code{obstack_free} function. The @code{obstack_free}
4763function takes a pointer to where in the stack it must start the
4764deletion from (much like the cleanup chains have a pointer to where to
4765start the cleanups). Because of the stack like structure of the
4766@code{obstacks}, this allows to free only a top portion of the
4767obstack. There are a few instances in @value{GDBN} where such thing
4768happens. Calls to @code{obstack_free} are done after some local data
4769is allocated to the obstack. Only the local data is deleted from the
4770obstack. Of course this assumes that nothing between the
4771@code{obstack_alloc} and the @code{obstack_free} allocates anything
4772else on the same obstack. For this reason it is best and safest to
4773use temporary @code{obstacks}.
4774
4775Releasing the whole obstack is also not safe per se. It is safe only
4776under the condition that we know the @code{obstacks} memory is no
4777longer needed. In @value{GDBN} we get rid of the @code{obstacks} only
4778when we get rid of the whole objfile(s), for instance upon reading a
4779new symbol file.
c906108c
SS
4780
4781@section gnu-regex
56caf160 4782@cindex regular expressions library
c906108c
SS
4783
4784Regex conditionals.
4785
4786@table @code
c906108c
SS
4787@item C_ALLOCA
4788
4789@item NFAILURES
4790
4791@item RE_NREGS
4792
4793@item SIGN_EXTEND_CHAR
4794
4795@item SWITCH_ENUM_BUG
4796
4797@item SYNTAX_TABLE
4798
4799@item Sword
4800
4801@item sparc
c906108c
SS
4802@end table
4803
350da6ee
DJ
4804@section Array Containers
4805@cindex Array Containers
4806@cindex VEC
4807
4808Often it is necessary to manipulate a dynamic array of a set of
4809objects. C forces some bookkeeping on this, which can get cumbersome
d3e8051b 4810and repetitive. The @file{vec.h} file contains macros for defining
350da6ee
DJ
4811and using a typesafe vector type. The functions defined will be
4812inlined when compiling, and so the abstraction cost should be zero.
4813Domain checks are added to detect programming errors.
4814
4815An example use would be an array of symbols or section information.
4816The array can be grown as symbols are read in (or preallocated), and
4817the accessor macros provided keep care of all the necessary
4818bookkeeping. Because the arrays are type safe, there is no danger of
4819accidentally mixing up the contents. Think of these as C++ templates,
4820but implemented in C.
4821
4822Because of the different behavior of structure objects, scalar objects
4823and of pointers, there are three flavors of vector, one for each of
4824these variants. Both the structure object and pointer variants pass
4825pointers to objects around --- in the former case the pointers are
4826stored into the vector and in the latter case the pointers are
4827dereferenced and the objects copied into the vector. The scalar
4828object variant is suitable for @code{int}-like objects, and the vector
4829elements are returned by value.
4830
4831There are both @code{index} and @code{iterate} accessors. The iterator
4832returns a boolean iteration condition and updates the iteration
4833variable passed by reference. Because the iterator will be inlined,
4834the address-of can be optimized away.
4835
4836The vectors are implemented using the trailing array idiom, thus they
4837are not resizeable without changing the address of the vector object
4838itself. This means you cannot have variables or fields of vector type
4839--- always use a pointer to a vector. The one exception is the final
4840field of a structure, which could be a vector type. You will have to
4841use the @code{embedded_size} & @code{embedded_init} calls to create
4842such objects, and they will probably not be resizeable (so don't use
4843the @dfn{safe} allocation variants). The trailing array idiom is used
4844(rather than a pointer to an array of data), because, if we allow
4845@code{NULL} to also represent an empty vector, empty vectors occupy
4846minimal space in the structure containing them.
4847
4848Each operation that increases the number of active elements is
4849available in @dfn{quick} and @dfn{safe} variants. The former presumes
4850that there is sufficient allocated space for the operation to succeed
4851(it dies if there is not). The latter will reallocate the vector, if
4852needed. Reallocation causes an exponential increase in vector size.
4853If you know you will be adding N elements, it would be more efficient
4854to use the reserve operation before adding the elements with the
4855@dfn{quick} operation. This will ensure there are at least as many
4856elements as you ask for, it will exponentially increase if there are
4857too few spare slots. If you want reserve a specific number of slots,
4858but do not want the exponential increase (for instance, you know this
4859is the last allocation), use a negative number for reservation. You
4860can also create a vector of a specific size from the get go.
4861
4862You should prefer the push and pop operations, as they append and
4863remove from the end of the vector. If you need to remove several items
4864in one go, use the truncate operation. The insert and remove
4865operations allow you to change elements in the middle of the vector.
4866There are two remove operations, one which preserves the element
4867ordering @code{ordered_remove}, and one which does not
4868@code{unordered_remove}. The latter function copies the end element
4869into the removed slot, rather than invoke a memmove operation. The
4870@code{lower_bound} function will determine where to place an item in
4871the array using insert that will maintain sorted order.
4872
4873If you need to directly manipulate a vector, then the @code{address}
4874accessor will return the address of the start of the vector. Also the
4875@code{space} predicate will tell you whether there is spare capacity in the
4876vector. You will not normally need to use these two functions.
4877
4878Vector types are defined using a
4879@code{DEF_VEC_@{O,P,I@}(@var{typename})} macro. Variables of vector
4880type are declared using a @code{VEC(@var{typename})} macro. The
4881characters @code{O}, @code{P} and @code{I} indicate whether
4882@var{typename} is an object (@code{O}), pointer (@code{P}) or integral
4883(@code{I}) type. Be careful to pick the correct one, as you'll get an
4884awkward and inefficient API if you use the wrong one. There is a
4885check, which results in a compile-time warning, for the @code{P} and
4886@code{I} versions, but there is no check for the @code{O} versions, as
4887that is not possible in plain C.
4888
4889An example of their use would be,
4890
4891@smallexample
4892DEF_VEC_P(tree); // non-managed tree vector.
4893
4894struct my_struct @{
4895 VEC(tree) *v; // A (pointer to) a vector of tree pointers.
4896@};
4897
4898struct my_struct *s;
4899
4900if (VEC_length(tree, s->v)) @{ we have some contents @}
4901VEC_safe_push(tree, s->v, decl); // append some decl onto the end
4902for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++)
4903 @{ do something with elt @}
4904
4905@end smallexample
4906
4907The @file{vec.h} file provides details on how to invoke the various
4908accessors provided. They are enumerated here:
4909
4910@table @code
4911@item VEC_length
4912Return the number of items in the array,
4913
4914@item VEC_empty
4915Return true if the array has no elements.
4916
4917@item VEC_last
4918@itemx VEC_index
4919Return the last or arbitrary item in the array.
4920
4921@item VEC_iterate
4922Access an array element and indicate whether the array has been
4923traversed.
4924
4925@item VEC_alloc
4926@itemx VEC_free
4927Create and destroy an array.
4928
4929@item VEC_embedded_size
4930@itemx VEC_embedded_init
4931Helpers for embedding an array as the final element of another struct.
4932
4933@item VEC_copy
4934Duplicate an array.
4935
4936@item VEC_space
4937Return the amount of free space in an array.
4938
4939@item VEC_reserve
4940Ensure a certain amount of free space.
4941
4942@item VEC_quick_push
4943@itemx VEC_safe_push
4944Append to an array, either assuming the space is available, or making
4945sure that it is.
4946
4947@item VEC_pop
4948Remove the last item from an array.
4949
4950@item VEC_truncate
4951Remove several items from the end of an array.
4952
4953@item VEC_safe_grow
4954Add several items to the end of an array.
4955
4956@item VEC_replace
4957Overwrite an item in the array.
4958
4959@item VEC_quick_insert
4960@itemx VEC_safe_insert
4961Insert an item into the middle of the array. Either the space must
4962already exist, or the space is created.
4963
4964@item VEC_ordered_remove
4965@itemx VEC_unordered_remove
4966Remove an item from the array, preserving order or not.
4967
4968@item VEC_block_remove
4969Remove a set of items from the array.
4970
4971@item VEC_address
4972Provide the address of the first element.
4973
4974@item VEC_lower_bound
4975Binary search the array.
4976
4977@end table
4978
c906108c
SS
4979@section include
4980
4981@node Coding
4982
4983@chapter Coding
4984
4985This chapter covers topics that are lower-level than the major
25822942 4986algorithms of @value{GDBN}.
c906108c
SS
4987
4988@section Cleanups
56caf160 4989@cindex cleanups
c906108c
SS
4990
4991Cleanups are a structured way to deal with things that need to be done
cc1cb004 4992later.
c906108c 4993
cc1cb004
AC
4994When your code does something (e.g., @code{xmalloc} some memory, or
4995@code{open} a file) that needs to be undone later (e.g., @code{xfree}
4996the memory or @code{close} the file), it can make a cleanup. The
4997cleanup will be done at some future point: when the command is finished
4998and control returns to the top level; when an error occurs and the stack
4999is unwound; or when your code decides it's time to explicitly perform
5000cleanups. Alternatively you can elect to discard the cleanups you
5001created.
c906108c
SS
5002
5003Syntax:
5004
5005@table @code
c906108c
SS
5006@item struct cleanup *@var{old_chain};
5007Declare a variable which will hold a cleanup chain handle.
5008
56caf160 5009@findex make_cleanup
c906108c
SS
5010@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
5011Make a cleanup which will cause @var{function} to be called with
5012@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
cc1cb004
AC
5013handle that can later be passed to @code{do_cleanups} or
5014@code{discard_cleanups}. Unless you are going to call
5015@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result
5016from @code{make_cleanup}.
c906108c 5017
56caf160 5018@findex do_cleanups
c906108c 5019@item do_cleanups (@var{old_chain});
cc1cb004
AC
5020Do all cleanups added to the chain since the corresponding
5021@code{make_cleanup} call was made.
5022
5023@findex discard_cleanups
5024@item discard_cleanups (@var{old_chain});
5025Same as @code{do_cleanups} except that it just removes the cleanups from
5026the chain and does not call the specified functions.
5027@end table
5028
5029Cleanups are implemented as a chain. The handle returned by
5030@code{make_cleanups} includes the cleanup passed to the call and any
5031later cleanups appended to the chain (but not yet discarded or
5032performed). E.g.:
56caf160 5033
474c8240 5034@smallexample
c906108c 5035make_cleanup (a, 0);
cc1cb004
AC
5036@{
5037 struct cleanup *old = make_cleanup (b, 0);
5038 make_cleanup (c, 0)
5039 ...
5040 do_cleanups (old);
5041@}
474c8240 5042@end smallexample
56caf160 5043
c906108c 5044@noindent
cc1cb004
AC
5045will call @code{c()} and @code{b()} but will not call @code{a()}. The
5046cleanup that calls @code{a()} will remain in the cleanup chain, and will
5047be done later unless otherwise discarded.@refill
5048
5049Your function should explicitly do or discard the cleanups it creates.
5050Failing to do this leads to non-deterministic behavior since the caller
5051will arbitrarily do or discard your functions cleanups. This need leads
5052to two common cleanup styles.
5053
5054The first style is try/finally. Before it exits, your code-block calls
5055@code{do_cleanups} with the old cleanup chain and thus ensures that your
5056code-block's cleanups are always performed. For instance, the following
5057code-segment avoids a memory leak problem (even when @code{error} is
5058called and a forced stack unwind occurs) by ensuring that the
5059@code{xfree} will always be called:
c906108c 5060
474c8240 5061@smallexample
cc1cb004
AC
5062struct cleanup *old = make_cleanup (null_cleanup, 0);
5063data = xmalloc (sizeof blah);
5064make_cleanup (xfree, data);
5065... blah blah ...
5066do_cleanups (old);
474c8240 5067@end smallexample
cc1cb004
AC
5068
5069The second style is try/except. Before it exits, your code-block calls
5070@code{discard_cleanups} with the old cleanup chain and thus ensures that
5071any created cleanups are not performed. For instance, the following
5072code segment, ensures that the file will be closed but only if there is
5073an error:
5074
474c8240 5075@smallexample
cc1cb004
AC
5076FILE *file = fopen ("afile", "r");
5077struct cleanup *old = make_cleanup (close_file, file);
5078... blah blah ...
5079discard_cleanups (old);
5080return file;
474c8240 5081@end smallexample
c906108c 5082
c1468174 5083Some functions, e.g., @code{fputs_filtered()} or @code{error()}, specify
c906108c
SS
5084that they ``should not be called when cleanups are not in place''. This
5085means that any actions you need to reverse in the case of an error or
5086interruption must be on the cleanup chain before you call these
5087functions, since they might never return to your code (they
5088@samp{longjmp} instead).
5089
ba8c9337
AC
5090@section Per-architecture module data
5091@cindex per-architecture module data
5092@cindex multi-arch data
5093@cindex data-pointer, per-architecture/per-module
5094
fc989b7a
AC
5095The multi-arch framework includes a mechanism for adding module
5096specific per-architecture data-pointers to the @code{struct gdbarch}
5097architecture object.
5098
5099A module registers one or more per-architecture data-pointers using:
5100
5101@deftypefun struct gdbarch_data *gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init})
5102@var{pre_init} is used to, on-demand, allocate an initial value for a
5103per-architecture data-pointer using the architecture's obstack (passed
5104in as a parameter). Since @var{pre_init} can be called during
5105architecture creation, it is not parameterized with the architecture.
5106and must not call modules that use per-architecture data.
5107@end deftypefun
ba8c9337 5108
fc989b7a
AC
5109@deftypefun struct gdbarch_data *gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init})
5110@var{post_init} is used to obtain an initial value for a
5111per-architecture data-pointer @emph{after}. Since @var{post_init} is
5112always called after architecture creation, it both receives the fully
5113initialized architecture and is free to call modules that use
5114per-architecture data (care needs to be taken to ensure that those
5115other modules do not try to call back to this module as that will
5116create in cycles in the initialization call graph).
5117@end deftypefun
ba8c9337 5118
fc989b7a
AC
5119These functions return a @code{struct gdbarch_data} that is used to
5120identify the per-architecture data-pointer added for that module.
ba8c9337 5121
fc989b7a 5122The per-architecture data-pointer is accessed using the function:
ba8c9337 5123
fc989b7a
AC
5124@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
5125Given the architecture @var{arch} and module data handle
5126@var{data_handle} (returned by @code{gdbarch_data_register_pre_init}
5127or @code{gdbarch_data_register_post_init}), this function returns the
5128current value of the per-architecture data-pointer. If the data
5129pointer is @code{NULL}, it is first initialized by calling the
5130corresponding @var{pre_init} or @var{post_init} method.
ba8c9337
AC
5131@end deftypefun
5132
fc989b7a 5133The examples below assume the following definitions:
ba8c9337
AC
5134
5135@smallexample
e7f16015 5136struct nozel @{ int total; @};
ba8c9337 5137static struct gdbarch_data *nozel_handle;
ba8c9337
AC
5138@end smallexample
5139
fc989b7a
AC
5140A module can extend the architecture vector, adding additional
5141per-architecture data, using the @var{pre_init} method. The module's
5142per-architecture data is then initialized during architecture
5143creation.
ba8c9337 5144
fc989b7a
AC
5145In the below, the module's per-architecture @emph{nozel} is added. An
5146architecture can specify its nozel by calling @code{set_gdbarch_nozel}
5147from @code{gdbarch_init}.
ba8c9337
AC
5148
5149@smallexample
fc989b7a
AC
5150static void *
5151nozel_pre_init (struct obstack *obstack)
ba8c9337 5152@{
fc989b7a
AC
5153 struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
5154 return data;
5155@}
ba8c9337
AC
5156@end smallexample
5157
ba8c9337 5158@smallexample
fc989b7a
AC
5159extern void
5160set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
ba8c9337 5161@{
ba8c9337 5162 struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
fc989b7a 5163 data->total = nozel;
ba8c9337
AC
5164@}
5165@end smallexample
5166
fc989b7a
AC
5167A module can on-demand create architecture dependant data structures
5168using @code{post_init}.
ba8c9337 5169
fc989b7a
AC
5170In the below, the nozel's total is computed on-demand by
5171@code{nozel_post_init} using information obtained from the
5172architecture.
ba8c9337
AC
5173
5174@smallexample
fc989b7a
AC
5175static void *
5176nozel_post_init (struct gdbarch *gdbarch)
ba8c9337 5177@{
fc989b7a
AC
5178 struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
5179 nozel->total = gdbarch@dots{} (gdbarch);
5180 return data;
ba8c9337
AC
5181@}
5182@end smallexample
5183
5184@smallexample
fc989b7a
AC
5185extern int
5186nozel_total (struct gdbarch *gdbarch)
ba8c9337 5187@{
fc989b7a
AC
5188 struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
5189 return data->total;
ba8c9337
AC
5190@}
5191@end smallexample
5192
c906108c 5193@section Wrapping Output Lines
56caf160 5194@cindex line wrap in output
c906108c 5195
56caf160 5196@findex wrap_here
c906108c
SS
5197Output that goes through @code{printf_filtered} or @code{fputs_filtered}
5198or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
5199added in places that would be good breaking points. The utility
5200routines will take care of actually wrapping if the line width is
5201exceeded.
5202
5203The argument to @code{wrap_here} is an indentation string which is
5204printed @emph{only} if the line breaks there. This argument is saved
5205away and used later. It must remain valid until the next call to
5206@code{wrap_here} or until a newline has been printed through the
5207@code{*_filtered} functions. Don't pass in a local variable and then
5208return!
5209
56caf160 5210It is usually best to call @code{wrap_here} after printing a comma or
c906108c
SS
5211space. If you call it before printing a space, make sure that your
5212indentation properly accounts for the leading space that will print if
5213the line wraps there.
5214
5215Any function or set of functions that produce filtered output must
5216finish by printing a newline, to flush the wrap buffer, before switching
56caf160 5217to unfiltered (@code{printf}) output. Symbol reading routines that
c906108c
SS
5218print warnings are a good example.
5219
25822942 5220@section @value{GDBN} Coding Standards
56caf160 5221@cindex coding standards
c906108c 5222
25822942 5223@value{GDBN} follows the GNU coding standards, as described in
c906108c 5224@file{etc/standards.texi}. This file is also available for anonymous
af6c57ea
AC
5225FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
5226of the standard; in general, when the GNU standard recommends a practice
5227but does not require it, @value{GDBN} requires it.
c906108c 5228
56caf160
EZ
5229@value{GDBN} follows an additional set of coding standards specific to
5230@value{GDBN}, as described in the following sections.
c906108c 5231
af6c57ea 5232
b9aa90c9 5233@subsection ISO C
af6c57ea 5234
b9aa90c9
AC
5235@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
5236compiler.
af6c57ea 5237
b9aa90c9 5238@value{GDBN} does not assume an ISO C or POSIX compliant C library.
af6c57ea
AC
5239
5240
5241@subsection Memory Management
5242
5243@value{GDBN} does not use the functions @code{malloc}, @code{realloc},
5244@code{calloc}, @code{free} and @code{asprintf}.
5245
5246@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
5247@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
5248these functions do not return when the memory pool is empty. Instead,
5249they unwind the stack using cleanups. These functions return
5250@code{NULL} when requested to allocate a chunk of memory of size zero.
5251
5252@emph{Pragmatics: By using these functions, the need to check every
5253memory allocation is removed. These functions provide portable
5254behavior.}
5255
5256@value{GDBN} does not use the function @code{free}.
5257
5258@value{GDBN} uses the function @code{xfree} to return memory to the
5259memory pool. Consistent with ISO-C, this function ignores a request to
5260free a @code{NULL} pointer.
5261
5262@emph{Pragmatics: On some systems @code{free} fails when passed a
5263@code{NULL} pointer.}
5264
5265@value{GDBN} can use the non-portable function @code{alloca} for the
5266allocation of small temporary values (such as strings).
5267
5268@emph{Pragmatics: This function is very non-portable. Some systems
5269restrict the memory being allocated to no more than a few kilobytes.}
5270
5271@value{GDBN} uses the string function @code{xstrdup} and the print
b435e160 5272function @code{xstrprintf}.
af6c57ea
AC
5273
5274@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
5275functions such as @code{sprintf} are very prone to buffer overflow
5276errors.}
5277
5278
5279@subsection Compiler Warnings
56caf160 5280@cindex compiler warnings
af6c57ea 5281
aa79a185
DJ
5282With few exceptions, developers should avoid the configuration option
5283@samp{--disable-werror} when building @value{GDBN}. The exceptions
5284are listed in the file @file{gdb/MAINTAINERS}. The default, when
5285building with @sc{gcc}, is @samp{--enable-werror}.
af6c57ea
AC
5286
5287This option causes @value{GDBN} (when built using GCC) to be compiled
5288with a carefully selected list of compiler warning flags. Any warnings
aa79a185 5289from those flags are treated as errors.
af6c57ea
AC
5290
5291The current list of warning flags includes:
5292
5293@table @samp
aa79a185
DJ
5294@item -Wall
5295Recommended @sc{gcc} warnings.
af6c57ea 5296
aa79a185 5297@item -Wdeclaration-after-statement
af6c57ea 5298
aa79a185
DJ
5299@sc{gcc} 3.x (and later) and @sc{c99} allow declarations mixed with
5300code, but @sc{gcc} 2.x and @sc{c89} do not.
af6c57ea 5301
aa79a185 5302@item -Wpointer-arith
af6c57ea 5303
aa79a185
DJ
5304@item -Wformat-nonliteral
5305Non-literal format strings, with a few exceptions, are bugs - they
d3e8051b 5306might contain unintended user-supplied format specifiers.
af6c57ea 5307Since @value{GDBN} uses the @code{format printf} attribute on all
aa79a185 5308@code{printf} like functions this checks not just @code{printf} calls
af6c57ea
AC
5309but also calls to functions such as @code{fprintf_unfiltered}.
5310
7be93b9e
JB
5311@item -Wno-pointer-sign
5312In version 4.0, GCC began warning about pointer argument passing or
5313assignment even when the source and destination differed only in
5314signedness. However, most @value{GDBN} code doesn't distinguish
5315carefully between @code{char} and @code{unsigned char}. In early 2006
5316the @value{GDBN} developers decided correcting these warnings wasn't
5317worth the time it would take.
5318
aa79a185
DJ
5319@item -Wno-unused-parameter
5320Due to the way that @value{GDBN} is implemented many functions have
5321unused parameters. Consequently this warning is avoided. The macro
af6c57ea
AC
5322@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
5323it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
aa79a185
DJ
5324is being used.
5325
5326@item -Wno-unused
5327@itemx -Wno-switch
58b38ee2 5328@itemx -Wno-char-subscripts
aa79a185
DJ
5329These are warnings which might be useful for @value{GDBN}, but are
5330currently too noisy to enable with @samp{-Werror}.
af6c57ea 5331
aa79a185 5332@end table
c906108c
SS
5333
5334@subsection Formatting
5335
56caf160 5336@cindex source code formatting
c906108c
SS
5337The standard GNU recommendations for formatting must be followed
5338strictly.
5339
af6c57ea
AC
5340A function declaration should not have its name in column zero. A
5341function definition should have its name in column zero.
5342
474c8240 5343@smallexample
af6c57ea
AC
5344/* Declaration */
5345static void foo (void);
5346/* Definition */
5347void
5348foo (void)
5349@{
5350@}
474c8240 5351@end smallexample
af6c57ea
AC
5352
5353@emph{Pragmatics: This simplifies scripting. Function definitions can
5354be found using @samp{^function-name}.}
c906108c 5355
af6c57ea
AC
5356There must be a space between a function or macro name and the opening
5357parenthesis of its argument list (except for macro definitions, as
5358required by C). There must not be a space after an open paren/bracket
5359or before a close paren/bracket.
c906108c
SS
5360
5361While additional whitespace is generally helpful for reading, do not use
5362more than one blank line to separate blocks, and avoid adding whitespace
af6c57ea
AC
5363after the end of a program line (as of 1/99, some 600 lines had
5364whitespace after the semicolon). Excess whitespace causes difficulties
5365for @code{diff} and @code{patch} utilities.
5366
5367Pointers are declared using the traditional K&R C style:
5368
474c8240 5369@smallexample
af6c57ea 5370void *foo;
474c8240 5371@end smallexample
af6c57ea
AC
5372
5373@noindent
5374and not:
5375
474c8240 5376@smallexample
af6c57ea
AC
5377void * foo;
5378void* foo;
474c8240 5379@end smallexample
c906108c
SS
5380
5381@subsection Comments
5382
56caf160 5383@cindex comment formatting
c906108c
SS
5384The standard GNU requirements on comments must be followed strictly.
5385
af6c57ea
AC
5386Block comments must appear in the following form, with no @code{/*}- or
5387@code{*/}-only lines, and no leading @code{*}:
c906108c 5388
474c8240 5389@smallexample
c906108c
SS
5390/* Wait for control to return from inferior to debugger. If inferior
5391 gets a signal, we may decide to start it up again instead of
5392 returning. That is why there is a loop in this function. When
5393 this function actually returns it means the inferior should be left
25822942 5394 stopped and @value{GDBN} should read more commands. */
474c8240 5395@end smallexample
c906108c
SS
5396
5397(Note that this format is encouraged by Emacs; tabbing for a multi-line
56caf160 5398comment works correctly, and @kbd{M-q} fills the block consistently.)
c906108c
SS
5399
5400Put a blank line between the block comments preceding function or
5401variable definitions, and the definition itself.
5402
5403In general, put function-body comments on lines by themselves, rather
5404than trying to fit them into the 20 characters left at the end of a
5405line, since either the comment or the code will inevitably get longer
5406than will fit, and then somebody will have to move it anyhow.
5407
5408@subsection C Usage
5409
56caf160 5410@cindex C data types
c906108c
SS
5411Code must not depend on the sizes of C data types, the format of the
5412host's floating point numbers, the alignment of anything, or the order
5413of evaluation of expressions.
5414
56caf160 5415@cindex function usage
c906108c 5416Use functions freely. There are only a handful of compute-bound areas
56caf160
EZ
5417in @value{GDBN} that might be affected by the overhead of a function
5418call, mainly in symbol reading. Most of @value{GDBN}'s performance is
5419limited by the target interface (whether serial line or system call).
c906108c
SS
5420
5421However, use functions with moderation. A thousand one-line functions
5422are just as hard to understand as a single thousand-line function.
5423
af6c57ea 5424@emph{Macros are bad, M'kay.}
9e678452
CF
5425(But if you have to use a macro, make sure that the macro arguments are
5426protected with parentheses.)
af6c57ea
AC
5427
5428@cindex types
c906108c 5429
af6c57ea
AC
5430Declarations like @samp{struct foo *} should be used in preference to
5431declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
5432
5433
5434@subsection Function Prototypes
56caf160 5435@cindex function prototypes
af6c57ea
AC
5436
5437Prototypes must be used when both @emph{declaring} and @emph{defining}
5438a function. Prototypes for @value{GDBN} functions must include both the
5439argument type and name, with the name matching that used in the actual
5440function definition.
c906108c 5441
53a5351d
JM
5442All external functions should have a declaration in a header file that
5443callers include, except for @code{_initialize_*} functions, which must
5444be external so that @file{init.c} construction works, but shouldn't be
5445visible to random source files.
c906108c 5446
af6c57ea
AC
5447Where a source file needs a forward declaration of a static function,
5448that declaration must appear in a block near the top of the source file.
5449
5450
5451@subsection Internal Error Recovery
5452
5453During its execution, @value{GDBN} can encounter two types of errors.
5454User errors and internal errors. User errors include not only a user
5455entering an incorrect command but also problems arising from corrupt
5456object files and system errors when interacting with the target.
937f164b
FF
5457Internal errors include situations where @value{GDBN} has detected, at
5458run time, a corrupt or erroneous situation.
af6c57ea
AC
5459
5460When reporting an internal error, @value{GDBN} uses
5461@code{internal_error} and @code{gdb_assert}.
5462
5463@value{GDBN} must not call @code{abort} or @code{assert}.
5464
5465@emph{Pragmatics: There is no @code{internal_warning} function. Either
5466the code detected a user error, recovered from it and issued a
5467@code{warning} or the code failed to correctly recover from the user
5468error and issued an @code{internal_error}.}
5469
5470@subsection File Names
5471
5472Any file used when building the core of @value{GDBN} must be in lower
5473case. Any file used when building the core of @value{GDBN} must be 8.3
5474unique. These requirements apply to both source and generated files.
5475
5476@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
5477platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
5478is introduced to the build process both @file{Makefile.in} and
5479@file{configure.in} need to be modified accordingly. Compare the
5480convoluted conversion process needed to transform @file{COPYING} into
5481@file{copying.c} with the conversion needed to transform
5482@file{version.in} into @file{version.c}.}
5483
5484Any file non 8.3 compliant file (that is not used when building the core
5485of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
5486
5487@emph{Pragmatics: This is clearly a compromise.}
5488
5489When @value{GDBN} has a local version of a system header file (ex
5490@file{string.h}) the file name based on the POSIX header prefixed with
b4177fca
DJ
5491@file{gdb_} (@file{gdb_string.h}). These headers should be relatively
5492independent: they should use only macros defined by @file{configure},
5493the compiler, or the host; they should include only system headers; they
5494should refer only to system types. They may be shared between multiple
5495programs, e.g.@: @value{GDBN} and @sc{gdbserver}.
af6c57ea
AC
5496
5497For other files @samp{-} is used as the separator.
5498
5499
5500@subsection Include Files
5501
e2b28d04 5502A @file{.c} file should include @file{defs.h} first.
af6c57ea 5503
e2b28d04
AC
5504A @file{.c} file should directly include the @code{.h} file of every
5505declaration and/or definition it directly refers to. It cannot rely on
5506indirect inclusion.
af6c57ea 5507
e2b28d04
AC
5508A @file{.h} file should directly include the @code{.h} file of every
5509declaration and/or definition it directly refers to. It cannot rely on
5510indirect inclusion. Exception: The file @file{defs.h} does not need to
5511be directly included.
af6c57ea 5512
e2b28d04 5513An external declaration should only appear in one include file.
af6c57ea 5514
e2b28d04
AC
5515An external declaration should never appear in a @code{.c} file.
5516Exception: a declaration for the @code{_initialize} function that
5517pacifies @option{-Wmissing-declaration}.
5518
5519A @code{typedef} definition should only appear in one include file.
5520
5521An opaque @code{struct} declaration can appear in multiple @file{.h}
5522files. Where possible, a @file{.h} file should use an opaque
5523@code{struct} declaration instead of an include.
5524
5525All @file{.h} files should be wrapped in:
af6c57ea 5526
474c8240 5527@smallexample
af6c57ea
AC
5528#ifndef INCLUDE_FILE_NAME_H
5529#define INCLUDE_FILE_NAME_H
5530header body
5531#endif
474c8240 5532@end smallexample
af6c57ea 5533
c906108c 5534
dab11f21 5535@subsection Clean Design and Portable Implementation
c906108c 5536
56caf160 5537@cindex design
c906108c 5538In addition to getting the syntax right, there's the little question of
25822942 5539semantics. Some things are done in certain ways in @value{GDBN} because long
c906108c
SS
5540experience has shown that the more obvious ways caused various kinds of
5541trouble.
5542
56caf160 5543@cindex assumptions about targets
c906108c
SS
5544You can't assume the byte order of anything that comes from a target
5545(including @var{value}s, object files, and instructions). Such things
56caf160
EZ
5546must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
5547@value{GDBN}, or one of the swap routines defined in @file{bfd.h},
5548such as @code{bfd_get_32}.
c906108c
SS
5549
5550You can't assume that you know what interface is being used to talk to
5551the target system. All references to the target must go through the
5552current @code{target_ops} vector.
5553
5554You can't assume that the host and target machines are the same machine
5555(except in the ``native'' support modules). In particular, you can't
5556assume that the target machine's header files will be available on the
5557host machine. Target code must bring along its own header files --
5558written from scratch or explicitly donated by their owner, to avoid
5559copyright problems.
5560
56caf160 5561@cindex portability
c906108c
SS
5562Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
5563to write the code portably than to conditionalize it for various
5564systems.
5565
56caf160 5566@cindex system dependencies
c906108c
SS
5567New @code{#ifdef}'s which test for specific compilers or manufacturers
5568or operating systems are unacceptable. All @code{#ifdef}'s should test
5569for features. The information about which configurations contain which
5570features should be segregated into the configuration files. Experience
5571has proven far too often that a feature unique to one particular system
5572often creeps into other systems; and that a conditional based on some
5573predefined macro for your current system will become worthless over
5574time, as new versions of your system come out that behave differently
5575with regard to this feature.
5576
5577Adding code that handles specific architectures, operating systems,
af6c57ea 5578target interfaces, or hosts, is not acceptable in generic code.
c906108c 5579
dab11f21
EZ
5580@cindex portable file name handling
5581@cindex file names, portability
5582One particularly notorious area where system dependencies tend to
5583creep in is handling of file names. The mainline @value{GDBN} code
5584assumes Posix semantics of file names: absolute file names begin with
5585a forward slash @file{/}, slashes are used to separate leading
5586directories, case-sensitive file names. These assumptions are not
5587necessarily true on non-Posix systems such as MS-Windows. To avoid
5588system-dependent code where you need to take apart or construct a file
5589name, use the following portable macros:
5590
5591@table @code
5592@findex HAVE_DOS_BASED_FILE_SYSTEM
5593@item HAVE_DOS_BASED_FILE_SYSTEM
5594This preprocessing symbol is defined to a non-zero value on hosts
5595whose filesystems belong to the MS-DOS/MS-Windows family. Use this
5596symbol to write conditional code which should only be compiled for
5597such hosts.
5598
5599@findex IS_DIR_SEPARATOR
4be31470 5600@item IS_DIR_SEPARATOR (@var{c})
dab11f21
EZ
5601Evaluates to a non-zero value if @var{c} is a directory separator
5602character. On Unix and GNU/Linux systems, only a slash @file{/} is
5603such a character, but on Windows, both @file{/} and @file{\} will
5604pass.
5605
5606@findex IS_ABSOLUTE_PATH
5607@item IS_ABSOLUTE_PATH (@var{file})
5608Evaluates to a non-zero value if @var{file} is an absolute file name.
5609For Unix and GNU/Linux hosts, a name which begins with a slash
5610@file{/} is absolute. On DOS and Windows, @file{d:/foo} and
5611@file{x:\bar} are also absolute file names.
5612
5613@findex FILENAME_CMP
5614@item FILENAME_CMP (@var{f1}, @var{f2})
5615Calls a function which compares file names @var{f1} and @var{f2} as
5616appropriate for the underlying host filesystem. For Posix systems,
5617this simply calls @code{strcmp}; on case-insensitive filesystems it
5618will call @code{strcasecmp} instead.
5619
5620@findex DIRNAME_SEPARATOR
5621@item DIRNAME_SEPARATOR
5622Evaluates to a character which separates directories in
5623@code{PATH}-style lists, typically held in environment variables.
5624This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
5625
5626@findex SLASH_STRING
5627@item SLASH_STRING
5628This evaluates to a constant string you should use to produce an
5629absolute filename from leading directories and the file's basename.
5630@code{SLASH_STRING} is @code{"/"} on most systems, but might be
5631@code{"\\"} for some Windows-based ports.
5632@end table
5633
5634In addition to using these macros, be sure to use portable library
5635functions whenever possible. For example, to extract a directory or a
5636basename part from a file name, use the @code{dirname} and
5637@code{basename} library functions (available in @code{libiberty} for
5638platforms which don't provide them), instead of searching for a slash
5639with @code{strrchr}.
5640
25822942
DB
5641Another way to generalize @value{GDBN} along a particular interface is with an
5642attribute struct. For example, @value{GDBN} has been generalized to handle
56caf160
EZ
5643multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
5644by defining the @code{target_ops} structure and having a current target (as
c906108c
SS
5645well as a stack of targets below it, for memory references). Whenever
5646something needs to be done that depends on which remote interface we are
56caf160
EZ
5647using, a flag in the current target_ops structure is tested (e.g.,
5648@code{target_has_stack}), or a function is called through a pointer in the
c906108c 5649current target_ops structure. In this way, when a new remote interface
56caf160 5650is added, only one module needs to be touched---the one that actually
c906108c
SS
5651implements the new remote interface. Other examples of
5652attribute-structs are BFD access to multiple kinds of object file
25822942 5653formats, or @value{GDBN}'s access to multiple source languages.
c906108c 5654
56caf160
EZ
5655Please avoid duplicating code. For example, in @value{GDBN} 3.x all
5656the code interfacing between @code{ptrace} and the rest of
5657@value{GDBN} was duplicated in @file{*-dep.c}, and so changing
5658something was very painful. In @value{GDBN} 4.x, these have all been
5659consolidated into @file{infptrace.c}. @file{infptrace.c} can deal
5660with variations between systems the same way any system-independent
5661file would (hooks, @code{#if defined}, etc.), and machines which are
5662radically different don't need to use @file{infptrace.c} at all.
c906108c 5663
af6c57ea
AC
5664All debugging code must be controllable using the @samp{set debug
5665@var{module}} command. Do not use @code{printf} to print trace
5666messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
5667@code{#ifdef DEBUG}.
5668
c906108c 5669
8487521e 5670@node Porting GDB
c906108c 5671
25822942 5672@chapter Porting @value{GDBN}
56caf160 5673@cindex porting to new machines
c906108c 5674
56caf160
EZ
5675Most of the work in making @value{GDBN} compile on a new machine is in
5676specifying the configuration of the machine. This is done in a
5677dizzying variety of header files and configuration scripts, which we
5678hope to make more sensible soon. Let's say your new host is called an
5679@var{xyz} (e.g., @samp{sun4}), and its full three-part configuration
5680name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g.,
5681@samp{sparc-sun-sunos4}). In particular:
c906108c 5682
56caf160
EZ
5683@itemize @bullet
5684@item
c906108c
SS
5685In the top level directory, edit @file{config.sub} and add @var{arch},
5686@var{xvend}, and @var{xos} to the lists of supported architectures,
5687vendors, and operating systems near the bottom of the file. Also, add
5688@var{xyz} as an alias that maps to
5689@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
5690running
5691
474c8240 5692@smallexample
c906108c 5693./config.sub @var{xyz}
474c8240 5694@end smallexample
56caf160 5695
c906108c
SS
5696@noindent
5697and
56caf160 5698
474c8240 5699@smallexample
c906108c 5700./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
474c8240 5701@end smallexample
56caf160 5702
c906108c
SS
5703@noindent
5704which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
5705and no error messages.
5706
56caf160 5707@noindent
c906108c
SS
5708You need to port BFD, if that hasn't been done already. Porting BFD is
5709beyond the scope of this manual.
5710
56caf160 5711@item
25822942 5712To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
c906108c
SS
5713your system and set @code{gdb_host} to @var{xyz}, and (unless your
5714desired target is already available) also edit @file{gdb/configure.tgt},
5715setting @code{gdb_target} to something appropriate (for instance,
5716@var{xyz}).
5717
7fd60527
AC
5718@emph{Maintainer's note: Work in progress. The file
5719@file{gdb/configure.host} originally needed to be modified when either a
5720new native target or a new host machine was being added to @value{GDBN}.
5721Recent changes have removed this requirement. The file now only needs
5722to be modified when adding a new native configuration. This will likely
5723changed again in the future.}
5724
56caf160 5725@item
25822942 5726Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
c906108c
SS
5727target-dependent @file{.h} and @file{.c} files used for your
5728configuration.
56caf160 5729@end itemize
c906108c 5730
d52fe014
AC
5731@node Versions and Branches
5732@chapter Versions and Branches
8973da3a 5733
d52fe014 5734@section Versions
8973da3a 5735
d52fe014
AC
5736@value{GDBN}'s version is determined by the file
5737@file{gdb/version.in} and takes one of the following forms:
fb0ff88f 5738
d52fe014
AC
5739@table @asis
5740@item @var{major}.@var{minor}
5741@itemx @var{major}.@var{minor}.@var{patchlevel}
53531fc1
AC
5742an official release (e.g., 6.2 or 6.2.1)
5743@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}
5744a snapshot taken at @var{YYYY}-@var{MM}-@var{DD}-gmt (e.g.,
57456.1.50.20020302, 6.1.90.20020304, or 6.1.0.20020308)
5746@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}-cvs
5747a @sc{cvs} check out drawn on @var{YYYY}-@var{MM}-@var{DD} (e.g.,
57486.1.50.20020302-cvs, 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
5749@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} (@var{vendor})
d52fe014 5750a vendor specific release of @value{GDBN}, that while based on@*
53531fc1
AC
5751@var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD},
5752may include additional changes
d52fe014 5753@end table
fb0ff88f 5754
d52fe014
AC
5755@value{GDBN}'s mainline uses the @var{major} and @var{minor} version
5756numbers from the most recent release branch, with a @var{patchlevel}
53531fc1
AC
5757of 50. At the time each new release branch is created, the mainline's
5758@var{major} and @var{minor} version numbers are updated.
fb0ff88f 5759
53531fc1
AC
5760@value{GDBN}'s release branch is similar. When the branch is cut, the
5761@var{patchlevel} is changed from 50 to 90. As draft releases are
5762drawn from the branch, the @var{patchlevel} is incremented. Once the
5763first release (@var{major}.@var{minor}) has been made, the
5764@var{patchlevel} is set to 0 and updates have an incremented
5765@var{patchlevel}.
5766
5767For snapshots, and @sc{cvs} check outs, it is also possible to
5768identify the @sc{cvs} origin:
5769
5770@table @asis
5771@item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD}
5772drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302)
5773@item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD}
5774@itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{}
5775drawn from a release branch prior to the release (e.g.,
57766.1.90.20020304)
5777@item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD}
5778@itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{}
5779drawn from a release branch after the release (e.g., 6.2.0.20020308)
5780@end table
fb0ff88f 5781
d52fe014
AC
5782If the previous @value{GDBN} version is 6.1 and the current version is
57836.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor},
5784here's an illustration of a typical sequence:
fb0ff88f 5785
d52fe014
AC
5786@smallexample
5787 <HEAD>
5788 |
53531fc1 57896.1.50.20020302-cvs
d52fe014 5790 |
53531fc1 5791 +--------------------------.
d52fe014 5792 | <gdb_6_2-branch>
d52fe014 5793 | |
53531fc1
AC
57946.2.50.20020303-cvs 6.1.90 (draft #1)
5795 | |
57966.2.50.20020304-cvs 6.1.90.20020304-cvs
5797 | |
57986.2.50.20020305-cvs 6.1.91 (draft #2)
d52fe014 5799 | |
53531fc1
AC
58006.2.50.20020306-cvs 6.1.91.20020306-cvs
5801 | |
58026.2.50.20020307-cvs 6.2 (release)
5803 | |
58046.2.50.20020308-cvs 6.2.0.20020308-cvs
5805 | |
58066.2.50.20020309-cvs 6.2.1 (update)
5807 | |
58086.2.50.20020310-cvs <branch closed>
d52fe014 5809 |
53531fc1 58106.2.50.20020311-cvs
d52fe014 5811 |
53531fc1 5812 +--------------------------.
d52fe014 5813 | <gdb_6_3-branch>
53531fc1
AC
5814 | |
58156.3.50.20020312-cvs 6.2.90 (draft #1)
5816 | |
d52fe014 5817@end smallexample
fb0ff88f 5818
d52fe014
AC
5819@section Release Branches
5820@cindex Release Branches
fb0ff88f 5821
d52fe014
AC
5822@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a
5823single release branch, and identifies that branch using the @sc{cvs}
5824branch tags:
fb0ff88f 5825
d52fe014
AC
5826@smallexample
5827gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint
5828gdb_@var{major}_@var{minor}-branch
5829gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release
5830@end smallexample
5831
5832@emph{Pragmatics: To help identify the date at which a branch or
5833release is made, both the branchpoint and release tags include the
5834date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The
5835branch tag, denoting the head of the branch, does not need this.}
5836
5837@section Vendor Branches
5838@cindex vendor branches
fb0ff88f
AC
5839
5840To avoid version conflicts, vendors are expected to modify the file
5841@file{gdb/version.in} to include a vendor unique alphabetic identifier
5842(an official @value{GDBN} release never uses alphabetic characters in
d3e8051b 5843its version identifier). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit
d52fe014
AC
5844Inc Patch 2)}.
5845
5846@section Experimental Branches
5847@cindex experimental branches
5848
5849@subsection Guidelines
5850
5851@value{GDBN} permits the creation of branches, cut from the @sc{cvs}
5852repository, for experimental development. Branches make it possible
5853for developers to share preliminary work, and maintainers to examine
5854significant new developments.
fb0ff88f 5855
d52fe014 5856The following are a set of guidelines for creating such branches:
fb0ff88f 5857
d52fe014
AC
5858@table @emph
5859
5860@item a branch has an owner
5861The owner can set further policy for a branch, but may not change the
5862ground rules. In particular, they can set a policy for commits (be it
5863adding more reviewers or deciding who can commit).
5864
5865@item all commits are posted
5866All changes committed to a branch shall also be posted to
5867@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches
5868mailing list}. While commentary on such changes are encouraged, people
5869should remember that the changes only apply to a branch.
5870
5871@item all commits are covered by an assignment
5872This ensures that all changes belong to the Free Software Foundation,
5873and avoids the possibility that the branch may become contaminated.
5874
5875@item a branch is focused
5876A focused branch has a single objective or goal, and does not contain
5877unnecessary or irrelevant changes. Cleanups, where identified, being
5878be pushed into the mainline as soon as possible.
5879
5880@item a branch tracks mainline
5881This keeps the level of divergence under control. It also keeps the
5882pressure on developers to push cleanups and other stuff into the
5883mainline.
5884
5885@item a branch shall contain the entire @value{GDBN} module
5886The @value{GDBN} module @code{gdb} should be specified when creating a
5887branch (branches of individual files should be avoided). @xref{Tags}.
5888
5889@item a branch shall be branded using @file{version.in}
5890The file @file{gdb/version.in} shall be modified so that it identifies
5891the branch @var{owner} and branch @var{name}, e.g.,
53531fc1 5892@samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}.
d52fe014
AC
5893
5894@end table
fb0ff88f 5895
d52fe014
AC
5896@subsection Tags
5897@anchor{Tags}
fb0ff88f 5898
d52fe014
AC
5899To simplify the identification of @value{GDBN} branches, the following
5900branch tagging convention is strongly recommended:
fb0ff88f 5901
d52fe014 5902@table @code
fb0ff88f 5903
d52fe014
AC
5904@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
5905@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch
5906The branch point and corresponding branch tag. @var{YYYYMMDD} is the
5907date that the branch was created. A branch is created using the
5908sequence: @anchor{experimental branch tags}
474c8240 5909@smallexample
d52fe014
AC
5910cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb
5911cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
5912 @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb
474c8240 5913@end smallexample
fb0ff88f 5914
d52fe014
AC
5915@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
5916The tagged point, on the mainline, that was used when merging the branch
5917on @var{yyyymmdd}. To merge in all changes since the branch was cut,
5918use a command sequence like:
474c8240 5919@smallexample
d52fe014
AC
5920cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb
5921cvs update \
5922 -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
5923 -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
474c8240 5924@end smallexample
d52fe014
AC
5925@noindent
5926Similar sequences can be used to just merge in changes since the last
5927merge.
5928
5929@end table
fb0ff88f 5930
d52fe014
AC
5931@noindent
5932For further information on @sc{cvs}, see
5933@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
5934
55f6ca0f
JB
5935@node Start of New Year Procedure
5936@chapter Start of New Year Procedure
5937@cindex new year procedure
5938
5939At the start of each new year, the following actions should be performed:
5940
5941@itemize @bullet
5942@item
5943Rotate the ChangeLog file
5944
5945The current @file{ChangeLog} file should be renamed into
5946@file{ChangeLog-YYYY} where YYYY is the year that has just passed.
5947A new @file{ChangeLog} file should be created, and its contents should
5948contain a reference to the previous ChangeLog. The following should
5949also be preserved at the end of the new ChangeLog, in order to provide
5950the appropriate settings when editing this file with Emacs:
5951@smallexample
5952Local Variables:
5953mode: change-log
5954left-margin: 8
5955fill-column: 74
5956version-control: never
5957End:
5958@end smallexample
5959
7f893741
JB
5960@item
5961Add an entry for the newly created ChangeLog file (@file{ChangeLog-YYYY})
5962in @file{gdb/config/djgpp/fnchange.lst}.
5963
55f6ca0f
JB
5964@item
5965Update the copyright year in the startup message
5966
5967Update the copyright year in file @file{top.c}, function
5968@code{print_gdb_version}.
6ec2edbe
JB
5969
5970@item
5971Add the new year in the copyright notices of all source and documentation
5972files. This can be done semi-automatically by running the @code{copyright.sh}
5973script. This script requires Emacs 22 or later to be installed.
5974
55f6ca0f
JB
5975@end itemize
5976
d52fe014 5977@node Releasing GDB
fb0ff88f 5978
d52fe014
AC
5979@chapter Releasing @value{GDBN}
5980@cindex making a new release of gdb
fb0ff88f 5981
9bb0a4d8
AC
5982@section Branch Commit Policy
5983
5984The branch commit policy is pretty slack. @value{GDBN} releases 5.0,
59855.1 and 5.2 all used the below:
5986
5987@itemize @bullet
5988@item
5989The @file{gdb/MAINTAINERS} file still holds.
5990@item
5991Don't fix something on the branch unless/until it is also fixed in the
5992trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}
4be31470 5993file is better than committing a hack.
9bb0a4d8
AC
5994@item
5995When considering a patch for the branch, suggested criteria include:
5996Does it fix a build? Does it fix the sequence @kbd{break main; run}
5997when debugging a static binary?
5998@item
5999The further a change is from the core of @value{GDBN}, the less likely
6000the change will worry anyone (e.g., target specific code).
6001@item
6002Only post a proposal to change the core of @value{GDBN} after you've
6003sent individual bribes to all the people listed in the
6004@file{MAINTAINERS} file @t{;-)}
6005@end itemize
6006
6007@emph{Pragmatics: Provided updates are restricted to non-core
6008functionality there is little chance that a broken change will be fatal.
6009This means that changes such as adding a new architectures or (within
6010reason) support for a new host are considered acceptable.}
6011
6012
cbb09e6a 6013@section Obsoleting code
8973da3a 6014
8642bc8f 6015Before anything else, poke the other developers (and around the source
4be31470
EZ
6016code) to see if there is anything that can be removed from @value{GDBN}
6017(an old target, an unused file).
8973da3a 6018
8642bc8f 6019Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
cbb09e6a
AC
6020line. Doing this means that it is easy to identify something that has
6021been obsoleted when greping through the sources.
8973da3a 6022
cbb09e6a
AC
6023The process is done in stages --- this is mainly to ensure that the
6024wider @value{GDBN} community has a reasonable opportunity to respond.
6025Remember, everything on the Internet takes a week.
8973da3a 6026
cbb09e6a 6027@enumerate
8973da3a 6028@item
cbb09e6a
AC
6029Post the proposal on @email{gdb@@sources.redhat.com, the GDB mailing
6030list} Creating a bug report to track the task's state, is also highly
6031recommended.
8973da3a 6032@item
cbb09e6a 6033Wait a week or so.
8973da3a 6034@item
cbb09e6a
AC
6035Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB
6036Announcement mailing list}.
8973da3a 6037@item
cbb09e6a 6038Wait a week or so.
8973da3a 6039@item
cbb09e6a
AC
6040Go through and edit all relevant files and lines so that they are
6041prefixed with the word @code{OBSOLETE}.
6042@item
6043Wait until the next GDB version, containing this obsolete code, has been
6044released.
6045@item
6046Remove the obsolete code.
6047@end enumerate
6048
6049@noindent
6050@emph{Maintainer note: While removing old code is regrettable it is
6051hopefully better for @value{GDBN}'s long term development. Firstly it
6052helps the developers by removing code that is either no longer relevant
6053or simply wrong. Secondly since it removes any history associated with
6054the file (effectively clearing the slate) the developer has a much freer
6055hand when it comes to fixing broken files.}
8973da3a 6056
8973da3a 6057
9ae8b82c
AC
6058
6059@section Before the Branch
8973da3a 6060
8642bc8f
AC
6061The most important objective at this stage is to find and fix simple
6062changes that become a pain to track once the branch is created. For
6063instance, configuration problems that stop @value{GDBN} from even
6064building. If you can't get the problem fixed, document it in the
6065@file{gdb/PROBLEMS} file.
8973da3a 6066
9ae8b82c 6067@subheading Prompt for @file{gdb/NEWS}
8973da3a 6068
9ae8b82c
AC
6069People always forget. Send a post reminding them but also if you know
6070something interesting happened add it yourself. The @code{schedule}
6071script will mention this in its e-mail.
8973da3a 6072
9ae8b82c 6073@subheading Review @file{gdb/README}
8973da3a 6074
9ae8b82c
AC
6075Grab one of the nightly snapshots and then walk through the
6076@file{gdb/README} looking for anything that can be improved. The
6077@code{schedule} script will mention this in its e-mail.
8642bc8f
AC
6078
6079@subheading Refresh any imported files.
8973da3a 6080
8642bc8f 6081A number of files are taken from external repositories. They include:
8973da3a 6082
8642bc8f
AC
6083@itemize @bullet
6084@item
6085@file{texinfo/texinfo.tex}
6086@item
9ae8b82c
AC
6087@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}
6088file)
6089@item
6090@file{etc/standards.texi}, @file{etc/make-stds.texi}
8642bc8f
AC
6091@end itemize
6092
9ae8b82c 6093@subheading Check the ARI
8642bc8f 6094
9ae8b82c
AC
6095@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script
6096(Awk Regression Index ;-) that checks for a number of errors and coding
6097conventions. The checks include things like using @code{malloc} instead
6098of @code{xmalloc} and file naming problems. There shouldn't be any
6099regressions.
8642bc8f 6100
9ae8b82c 6101@subsection Review the bug data base
8642bc8f 6102
9ae8b82c 6103Close anything obviously fixed.
8642bc8f 6104
9ae8b82c 6105@subsection Check all cross targets build
8642bc8f 6106
9ae8b82c 6107The targets are listed in @file{gdb/MAINTAINERS}.
8642bc8f 6108
8642bc8f 6109
30107679 6110@section Cut the Branch
8642bc8f 6111
30107679 6112@subheading Create the branch
8642bc8f 6113
474c8240 6114@smallexample
30107679
AC
6115$ u=5.1
6116$ v=5.2
6117$ V=`echo $v | sed 's/\./_/g'`
6118$ D=`date -u +%Y-%m-%d`
6119$ echo $u $V $D
61205.1 5_2 2002-03-03
6121$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
b247355e 6122-D $D-gmt gdb_$V-$D-branchpoint insight
30107679 6123cvs -f -d :ext:sources.redhat.com:/cvs/src rtag
b247355e 6124-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
30107679
AC
6125$ ^echo ^^
6126...
6127$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
b247355e 6128-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
30107679 6129cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
b247355e 6130-b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
30107679
AC
6131$ ^echo ^^
6132...
8642bc8f 6133$
474c8240 6134@end smallexample
8642bc8f
AC
6135
6136@itemize @bullet
6137@item
b247355e 6138By using @kbd{-D YYYY-MM-DD-gmt}, the branch is forced to an exact
30107679
AC
6139date/time.
6140@item
b247355e 6141The trunk is first tagged so that the branch point can easily be found.
30107679 6142@item
b247355e 6143Insight, which includes @value{GDBN}, is tagged at the same time.
8642bc8f 6144@item
b247355e 6145@file{version.in} gets bumped to avoid version number conflicts.
8642bc8f 6146@item
b247355e 6147The reading of @file{.cvsrc} is disabled using @file{-f}.
30107679
AC
6148@end itemize
6149
6150@subheading Update @file{version.in}
6151
6152@smallexample
6153$ u=5.1
6154$ v=5.2
6155$ V=`echo $v | sed 's/\./_/g'`
6156$ echo $u $v$V
61575.1 5_2
6158$ cd /tmp
6159$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \
6160-r gdb_$V-branch src/gdb/version.in
6161cvs -f -d :ext:sources.redhat.com:/cvs/src co
6162 -r gdb_5_2-branch src/gdb/version.in
6163$ ^echo ^^
6164U src/gdb/version.in
6165$ cd src/gdb
6166$ echo $u.90-0000-00-00-cvs > version.in
6167$ cat version.in
61685.1.90-0000-00-00-cvs
6169$ cvs -f commit version.in
6170@end smallexample
6171
6172@itemize @bullet
6173@item
6174@file{0000-00-00} is used as a date to pump prime the version.in update
b247355e 6175mechanism.
30107679
AC
6176@item
6177@file{.90} and the previous branch version are used as fairly arbitrary
b247355e 6178initial branch version number.
8642bc8f
AC
6179@end itemize
6180
8642bc8f
AC
6181
6182@subheading Update the web and news pages
6183
30107679
AC
6184Something?
6185
8642bc8f
AC
6186@subheading Tweak cron to track the new branch
6187
30107679
AC
6188The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table.
6189This file needs to be updated so that:
6190
6191@itemize @bullet
6192@item
b247355e 6193A daily timestamp is added to the file @file{version.in}.
30107679 6194@item
b247355e 6195The new branch is included in the snapshot process.
30107679
AC
6196@end itemize
6197
6198@noindent
6199See the file @file{gdbadmin/cron/README} for how to install the updated
6200cron table.
6201
6202The file @file{gdbadmin/ss/README} should also be reviewed to reflect
6203any changes. That file is copied to both the branch/ and current/
6204snapshot directories.
6205
6206
6207@subheading Update the NEWS and README files
6208
6209The @file{NEWS} file needs to be updated so that on the branch it refers
6210to @emph{changes in the current release} while on the trunk it also
6211refers to @emph{changes since the current release}.
6212
6213The @file{README} file needs to be updated so that it refers to the
6214current release.
6215
6216@subheading Post the branch info
6217
6218Send an announcement to the mailing lists:
6219
6220@itemize @bullet
6221@item
6222@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
6223@item
d3e8051b
EZ
6224@email{gdb@@sources.redhat.com, GDB Discussion mailing list} and
6225@email{gdb-testers@@sources.redhat.com, GDB Testers mailing list}
16737d73 6226@end itemize
30107679
AC
6227
6228@emph{Pragmatics: The branch creation is sent to the announce list to
6229ensure that people people not subscribed to the higher volume discussion
6230list are alerted.}
6231
6232The announcement should include:
6233
6234@itemize @bullet
6235@item
b247355e 6236The branch tag.
30107679 6237@item
b247355e 6238How to check out the branch using CVS.
30107679 6239@item
b247355e 6240The date/number of weeks until the release.
30107679 6241@item
b247355e 6242The branch commit policy still holds.
16737d73 6243@end itemize
30107679 6244
8642bc8f
AC
6245@section Stabilize the branch
6246
6247Something goes here.
6248
6249@section Create a Release
6250
0816590b
AC
6251The process of creating and then making available a release is broken
6252down into a number of stages. The first part addresses the technical
6253process of creating a releasable tar ball. The later stages address the
6254process of releasing that tar ball.
8973da3a 6255
0816590b
AC
6256When making a release candidate just the first section is needed.
6257
6258@subsection Create a release candidate
6259
6260The objective at this stage is to create a set of tar balls that can be
6261made available as a formal release (or as a less formal release
6262candidate).
6263
6264@subsubheading Freeze the branch
6265
6266Send out an e-mail notifying everyone that the branch is frozen to
6267@email{gdb-patches@@sources.redhat.com}.
6268
6269@subsubheading Establish a few defaults.
8973da3a 6270
474c8240 6271@smallexample
0816590b
AC
6272$ b=gdb_5_2-branch
6273$ v=5.2
8642bc8f
AC
6274$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
6275$ echo $t/$b/$v
0816590b 6276/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
8642bc8f
AC
6277$ mkdir -p $t/$b/$v
6278$ cd $t/$b/$v
6279$ pwd
0816590b 6280/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
8973da3a
AC
6281$ which autoconf
6282/home/gdbadmin/bin/autoconf
8642bc8f 6283$
474c8240 6284@end smallexample
8973da3a 6285
0816590b
AC
6286@noindent
6287Notes:
8973da3a 6288
0816590b
AC
6289@itemize @bullet
6290@item
6291Check the @code{autoconf} version carefully. You want to be using the
4a2b4636
JB
6292version taken from the @file{binutils} snapshot directory, which can be
6293found at @uref{ftp://sources.redhat.com/pub/binutils/}. It is very
0816590b
AC
6294unlikely that a system installed version of @code{autoconf} (e.g.,
6295@file{/usr/bin/autoconf}) is correct.
6296@end itemize
6297
6298@subsubheading Check out the relevant modules:
8973da3a 6299
474c8240 6300@smallexample
b247355e 6301$ for m in gdb insight
8642bc8f 6302do
8973da3a
AC
6303( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
6304done
8642bc8f 6305$
474c8240 6306@end smallexample
8973da3a 6307
0816590b
AC
6308@noindent
6309Note:
8642bc8f 6310
0816590b
AC
6311@itemize @bullet
6312@item
6313The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't
6314any confusion between what is written here and what your local
6315@code{cvs} really does.
6316@end itemize
6317
6318@subsubheading Update relevant files.
8973da3a 6319
0816590b
AC
6320@table @file
6321
6322@item gdb/NEWS
8642bc8f
AC
6323
6324Major releases get their comments added as part of the mainline. Minor
6325releases should probably mention any significant bugs that were fixed.
6326
0816590b 6327Don't forget to include the @file{ChangeLog} entry.
8973da3a 6328
474c8240 6329@smallexample
8642bc8f
AC
6330$ emacs gdb/src/gdb/NEWS
6331...
6332c-x 4 a
6333...
6334c-x c-s c-x c-c
6335$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
6336$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
474c8240 6337@end smallexample
8973da3a 6338
0816590b
AC
6339@item gdb/README
6340
6341You'll need to update:
8973da3a 6342
0816590b
AC
6343@itemize @bullet
6344@item
b247355e 6345The version.
0816590b 6346@item
b247355e 6347The update date.
0816590b 6348@item
b247355e 6349Who did it.
0816590b 6350@end itemize
8973da3a 6351
474c8240 6352@smallexample
8642bc8f
AC
6353$ emacs gdb/src/gdb/README
6354...
8973da3a 6355c-x 4 a
8642bc8f 6356...
8973da3a 6357c-x c-s c-x c-c
8642bc8f
AC
6358$ cp gdb/src/gdb/README insight/src/gdb/README
6359$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
474c8240 6360@end smallexample
8973da3a 6361
0816590b
AC
6362@emph{Maintainer note: Hopefully the @file{README} file was reviewed
6363before the initial branch was cut so just a simple substitute is needed
6364to get it updated.}
8973da3a 6365
8642bc8f
AC
6366@emph{Maintainer note: Other projects generate @file{README} and
6367@file{INSTALL} from the core documentation. This might be worth
6368pursuing.}
8973da3a 6369
0816590b 6370@item gdb/version.in
8973da3a 6371
474c8240 6372@smallexample
8642bc8f 6373$ echo $v > gdb/src/gdb/version.in
0816590b
AC
6374$ cat gdb/src/gdb/version.in
63755.2
8642bc8f 6376$ emacs gdb/src/gdb/version.in
8973da3a
AC
6377...
6378c-x 4 a
0816590b 6379... Bump to version ...
8973da3a 6380c-x c-s c-x c-c
8642bc8f
AC
6381$ cp gdb/src/gdb/version.in insight/src/gdb/version.in
6382$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
474c8240 6383@end smallexample
8973da3a 6384
0816590b
AC
6385@end table
6386
6387@subsubheading Do the dirty work
6388
6389This is identical to the process used to create the daily snapshot.
8973da3a 6390
4ce8657e
MC
6391@smallexample
6392$ for m in gdb insight
6393do
6394( cd $m/src && gmake -f src-release $m.tar )
6395done
4ce8657e
MC
6396@end smallexample
6397
6398If the top level source directory does not have @file{src-release}
6399(@value{GDBN} version 5.3.1 or earlier), try these commands instead:
6400
474c8240 6401@smallexample
0816590b 6402$ for m in gdb insight
8642bc8f 6403do
0816590b 6404( cd $m/src && gmake -f Makefile.in $m.tar )
8973da3a 6405done
474c8240 6406@end smallexample
8973da3a 6407
0816590b 6408@subsubheading Check the source files
8642bc8f 6409
0816590b 6410You're looking for files that have mysteriously disappeared.
8642bc8f
AC
6411@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
6412for the @file{version.in} update @kbd{cronjob}.
8973da3a 6413
474c8240 6414@smallexample
8642bc8f
AC
6415$ ( cd gdb/src && cvs -f -q -n update )
6416M djunpack.bat
0816590b 6417? gdb-5.1.91.tar
8642bc8f 6418? proto-toplev
0816590b 6419@dots{} lots of generated files @dots{}
8642bc8f
AC
6420M gdb/ChangeLog
6421M gdb/NEWS
6422M gdb/README
6423M gdb/version.in
0816590b 6424@dots{} lots of generated files @dots{}
8642bc8f 6425$
474c8240 6426@end smallexample
8973da3a 6427
0816590b 6428@noindent
8642bc8f
AC
6429@emph{Don't worry about the @file{gdb.info-??} or
6430@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1}
6431was also generated only something strange with CVS means that they
d3e8051b 6432didn't get suppressed). Fixing it would be nice though.}
8973da3a 6433
0816590b 6434@subsubheading Create compressed versions of the release
8973da3a 6435
474c8240 6436@smallexample
0816590b
AC
6437$ cp */src/*.tar .
6438$ cp */src/*.bz2 .
6439$ ls -F
b247355e 6440gdb/ gdb-5.2.tar insight/ insight-5.2.tar
0816590b
AC
6441$ for m in gdb insight
6442do
6443bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
6444gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
6445done
6446$
474c8240 6447@end smallexample
8973da3a 6448
0816590b
AC
6449@noindent
6450Note:
6451
6452@itemize @bullet
6453@item
6454A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since,
6455in that mode, @code{gzip} does not know the name of the file and, hence,
6456can not include it in the compressed file. This is also why the release
6457process runs @code{tar} and @code{bzip2} as separate passes.
6458@end itemize
6459
6460@subsection Sanity check the tar ball
8973da3a 6461
0816590b 6462Pick a popular machine (Solaris/PPC?) and try the build on that.
8973da3a 6463
0816590b
AC
6464@smallexample
6465$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
6466$ cd gdb-5.2
6467$ ./configure
6468$ make
6469@dots{}
6470$ ./gdb/gdb ./gdb/gdb
6471GNU gdb 5.2
6472@dots{}
6473(gdb) b main
6474Breakpoint 1 at 0x80732bc: file main.c, line 734.
6475(gdb) run
6476Starting program: /tmp/gdb-5.2/gdb/gdb
6477
6478Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
6479734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
6480(gdb) print args
6481$1 = @{argc = 136426532, argv = 0x821b7f0@}
6482(gdb)
6483@end smallexample
8973da3a 6484
0816590b 6485@subsection Make a release candidate available
8973da3a 6486
0816590b 6487If this is a release candidate then the only remaining steps are:
8642bc8f 6488
0816590b
AC
6489@enumerate
6490@item
6491Commit @file{version.in} and @file{ChangeLog}
6492@item
6493Tweak @file{version.in} (and @file{ChangeLog} to read
6494@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update
6495process can restart.
6496@item
6497Make the release candidate available in
6498@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch}
6499@item
6500Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and
6501@email{gdb-testers@@sources.redhat.com} that the candidate is available.
6502@end enumerate
8642bc8f 6503
0816590b 6504@subsection Make a formal release available
8642bc8f 6505
0816590b 6506(And you thought all that was required was to post an e-mail.)
8642bc8f 6507
0816590b 6508@subsubheading Install on sware
8642bc8f 6509
0816590b 6510Copy the new files to both the release and the old release directory:
8642bc8f 6511
474c8240 6512@smallexample
0816590b 6513$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
8642bc8f 6514$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
474c8240 6515@end smallexample
8642bc8f 6516
0816590b
AC
6517@noindent
6518Clean up the releases directory so that only the most recent releases
6519are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
6520
6521@smallexample
6522$ cd ~ftp/pub/gdb/releases
6523$ rm @dots{}
6524@end smallexample
6525
6526@noindent
6527Update the file @file{README} and @file{.message} in the releases
6528directory:
6529
6530@smallexample
6531$ vi README
6532@dots{}
6533$ rm -f .message
6534$ ln README .message
6535@end smallexample
8642bc8f 6536
0816590b 6537@subsubheading Update the web pages.
8973da3a 6538
0816590b
AC
6539@table @file
6540
6541@item htdocs/download/ANNOUNCEMENT
6542This file, which is posted as the official announcement, includes:
8973da3a
AC
6543@itemize @bullet
6544@item
b247355e 6545General announcement.
8642bc8f 6546@item
0816590b
AC
6547News. If making an @var{M}.@var{N}.1 release, retain the news from
6548earlier @var{M}.@var{N} release.
8973da3a 6549@item
b247355e 6550Errata.
0816590b
AC
6551@end itemize
6552
6553@item htdocs/index.html
6554@itemx htdocs/news/index.html
6555@itemx htdocs/download/index.html
6556These files include:
6557@itemize @bullet
8642bc8f 6558@item
b247355e 6559Announcement of the most recent release.
8642bc8f 6560@item
b247355e 6561News entry (remember to update both the top level and the news directory).
8973da3a 6562@end itemize
0816590b 6563These pages also need to be regenerate using @code{index.sh}.
8973da3a 6564
0816590b 6565@item download/onlinedocs/
8642bc8f
AC
6566You need to find the magic command that is used to generate the online
6567docs from the @file{.tar.bz2}. The best way is to look in the output
0816590b 6568from one of the nightly @code{cron} jobs and then just edit accordingly.
8642bc8f
AC
6569Something like:
6570
474c8240 6571@smallexample
8642bc8f 6572$ ~/ss/update-web-docs \
0816590b 6573 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
8642bc8f 6574 $PWD/www \
0816590b 6575 /www/sourceware/htdocs/gdb/download/onlinedocs \
8642bc8f 6576 gdb
474c8240 6577@end smallexample
8642bc8f 6578
0816590b
AC
6579@item download/ari/
6580Just like the online documentation. Something like:
8642bc8f 6581
0816590b
AC
6582@smallexample
6583$ /bin/sh ~/ss/update-web-ari \
6584 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
6585 $PWD/www \
6586 /www/sourceware/htdocs/gdb/download/ari \
6587 gdb
6588@end smallexample
6589
6590@end table
6591
6592@subsubheading Shadow the pages onto gnu
6593
6594Something goes here.
6595
6596
6597@subsubheading Install the @value{GDBN} tar ball on GNU
6598
6599At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
6600@file{~ftp/gnu/gdb}.
6601
6602@subsubheading Make the @file{ANNOUNCEMENT}
6603
6604Post the @file{ANNOUNCEMENT} file you created above to:
8642bc8f
AC
6605
6606@itemize @bullet
6607@item
6608@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
6609@item
0816590b
AC
6610@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a
6611day or so to let things get out)
6612@item
6613@email{bug-gdb@@gnu.org, GDB Bug Report mailing list}
8642bc8f
AC
6614@end itemize
6615
0816590b 6616@subsection Cleanup
8642bc8f 6617
0816590b 6618The release is out but you're still not finished.
8642bc8f 6619
0816590b 6620@subsubheading Commit outstanding changes
8642bc8f 6621
0816590b 6622In particular you'll need to commit any changes to:
8642bc8f
AC
6623
6624@itemize @bullet
6625@item
6626@file{gdb/ChangeLog}
6627@item
6628@file{gdb/version.in}
6629@item
6630@file{gdb/NEWS}
6631@item
6632@file{gdb/README}
6633@end itemize
6634
0816590b 6635@subsubheading Tag the release
8642bc8f
AC
6636
6637Something like:
6638
474c8240 6639@smallexample
8642bc8f
AC
6640$ d=`date -u +%Y-%m-%d`
6641$ echo $d
66422002-01-24
6643$ ( cd insight/src/gdb && cvs -f -q update )
0816590b 6644$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
474c8240 6645@end smallexample
8642bc8f 6646
0816590b 6647Insight is used since that contains more of the release than
b247355e 6648@value{GDBN}.
0816590b
AC
6649
6650@subsubheading Mention the release on the trunk
8642bc8f 6651
0816590b
AC
6652Just put something in the @file{ChangeLog} so that the trunk also
6653indicates when the release was made.
6654
6655@subsubheading Restart @file{gdb/version.in}
8642bc8f
AC
6656
6657If @file{gdb/version.in} does not contain an ISO date such as
6658@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having
6659committed all the release changes it can be set to
0816590b 6660@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
8642bc8f
AC
6661is important - it affects the snapshot process).
6662
6663Don't forget the @file{ChangeLog}.
6664
0816590b 6665@subsubheading Merge into trunk
8973da3a 6666
8642bc8f
AC
6667The files committed to the branch may also need changes merged into the
6668trunk.
8973da3a 6669
0816590b
AC
6670@subsubheading Revise the release schedule
6671
6672Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB
6673Discussion List} with an updated announcement. The schedule can be
6674generated by running:
6675
6676@smallexample
6677$ ~/ss/schedule `date +%s` schedule
6678@end smallexample
6679
6680@noindent
6681The first parameter is approximate date/time in seconds (from the epoch)
6682of the most recent release.
6683
6684Also update the schedule @code{cronjob}.
6685
8642bc8f 6686@section Post release
8973da3a 6687
8642bc8f 6688Remove any @code{OBSOLETE} code.
8973da3a 6689
085dd6e6
JM
6690@node Testsuite
6691
6692@chapter Testsuite
56caf160 6693@cindex test suite
085dd6e6 6694
56caf160
EZ
6695The testsuite is an important component of the @value{GDBN} package.
6696While it is always worthwhile to encourage user testing, in practice
6697this is rarely sufficient; users typically use only a small subset of
6698the available commands, and it has proven all too common for a change
6699to cause a significant regression that went unnoticed for some time.
085dd6e6 6700
b247355e
NR
6701The @value{GDBN} testsuite uses the DejaGNU testing framework. The
6702tests themselves are calls to various @code{Tcl} procs; the framework
6703runs all the procs and summarizes the passes and fails.
085dd6e6
JM
6704
6705@section Using the Testsuite
6706
56caf160 6707@cindex running the test suite
25822942 6708To run the testsuite, simply go to the @value{GDBN} object directory (or to the
085dd6e6
JM
6709testsuite's objdir) and type @code{make check}. This just sets up some
6710environment variables and invokes DejaGNU's @code{runtest} script. While
6711the testsuite is running, you'll get mentions of which test file is in use,
6712and a mention of any unexpected passes or fails. When the testsuite is
6713finished, you'll get a summary that looks like this:
56caf160 6714
474c8240 6715@smallexample
085dd6e6
JM
6716 === gdb Summary ===
6717
6718# of expected passes 6016
6719# of unexpected failures 58
6720# of unexpected successes 5
6721# of expected failures 183
6722# of unresolved testcases 3
6723# of untested testcases 5
474c8240 6724@end smallexample
56caf160 6725
a9f158ec
JB
6726To run a specific test script, type:
6727@example
6728make check RUNTESTFLAGS='@var{tests}'
6729@end example
6730where @var{tests} is a list of test script file names, separated by
6731spaces.
6732
085dd6e6
JM
6733The ideal test run consists of expected passes only; however, reality
6734conspires to keep us from this ideal. Unexpected failures indicate
56caf160
EZ
6735real problems, whether in @value{GDBN} or in the testsuite. Expected
6736failures are still failures, but ones which have been decided are too
6737hard to deal with at the time; for instance, a test case might work
6738everywhere except on AIX, and there is no prospect of the AIX case
6739being fixed in the near future. Expected failures should not be added
6740lightly, since you may be masking serious bugs in @value{GDBN}.
6741Unexpected successes are expected fails that are passing for some
6742reason, while unresolved and untested cases often indicate some minor
6743catastrophe, such as the compiler being unable to deal with a test
6744program.
6745
6746When making any significant change to @value{GDBN}, you should run the
6747testsuite before and after the change, to confirm that there are no
6748regressions. Note that truly complete testing would require that you
6749run the testsuite with all supported configurations and a variety of
6750compilers; however this is more than really necessary. In many cases
6751testing with a single configuration is sufficient. Other useful
6752options are to test one big-endian (Sparc) and one little-endian (x86)
6753host, a cross config with a builtin simulator (powerpc-eabi,
6754mips-elf), or a 64-bit host (Alpha).
6755
6756If you add new functionality to @value{GDBN}, please consider adding
6757tests for it as well; this way future @value{GDBN} hackers can detect
6758and fix their changes that break the functionality you added.
6759Similarly, if you fix a bug that was not previously reported as a test
6760failure, please add a test case for it. Some cases are extremely
6761difficult to test, such as code that handles host OS failures or bugs
6762in particular versions of compilers, and it's OK not to try to write
6763tests for all of those.
085dd6e6 6764
e7dc800a
MC
6765DejaGNU supports separate build, host, and target machines. However,
6766some @value{GDBN} test scripts do not work if the build machine and
6767the host machine are not the same. In such an environment, these scripts
6768will give a result of ``UNRESOLVED'', like this:
6769
6770@smallexample
6771UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
6772@end smallexample
6773
085dd6e6
JM
6774@section Testsuite Organization
6775
56caf160 6776@cindex test suite organization
085dd6e6
JM
6777The testsuite is entirely contained in @file{gdb/testsuite}. While the
6778testsuite includes some makefiles and configury, these are very minimal,
6779and used for little besides cleaning up, since the tests themselves
25822942 6780handle the compilation of the programs that @value{GDBN} will run. The file
085dd6e6 6781@file{testsuite/lib/gdb.exp} contains common utility procs useful for
25822942 6782all @value{GDBN} tests, while the directory @file{testsuite/config} contains
085dd6e6
JM
6783configuration-specific files, typically used for special-purpose
6784definitions of procs like @code{gdb_load} and @code{gdb_start}.
6785
6786The tests themselves are to be found in @file{testsuite/gdb.*} and
6787subdirectories of those. The names of the test files must always end
6788with @file{.exp}. DejaGNU collects the test files by wildcarding
6789in the test directories, so both subdirectories and individual files
6790get chosen and run in alphabetical order.
6791
6792The following table lists the main types of subdirectories and what they
6793are for. Since DejaGNU finds test files no matter where they are
6794located, and since each test file sets up its own compilation and
6795execution environment, this organization is simply for convenience and
6796intelligibility.
6797
56caf160 6798@table @file
085dd6e6 6799@item gdb.base
085dd6e6 6800This is the base testsuite. The tests in it should apply to all
25822942 6801configurations of @value{GDBN} (but generic native-only tests may live here).
085dd6e6 6802The test programs should be in the subset of C that is valid K&R,
49efadf5 6803ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance
085dd6e6
JM
6804for prototypes).
6805
6806@item gdb.@var{lang}
56caf160 6807Language-specific tests for any language @var{lang} besides C. Examples are
af6cf26d 6808@file{gdb.cp} and @file{gdb.java}.
085dd6e6
JM
6809
6810@item gdb.@var{platform}
085dd6e6
JM
6811Non-portable tests. The tests are specific to a specific configuration
6812(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
6813HP-UX.
6814
6815@item gdb.@var{compiler}
085dd6e6
JM
6816Tests specific to a particular compiler. As of this writing (June
68171999), there aren't currently any groups of tests in this category that
6818couldn't just as sensibly be made platform-specific, but one could
56caf160
EZ
6819imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC
6820extensions.
085dd6e6
JM
6821
6822@item gdb.@var{subsystem}
25822942 6823Tests that exercise a specific @value{GDBN} subsystem in more depth. For
085dd6e6
JM
6824instance, @file{gdb.disasm} exercises various disassemblers, while
6825@file{gdb.stabs} tests pathways through the stabs symbol reader.
085dd6e6
JM
6826@end table
6827
6828@section Writing Tests
56caf160 6829@cindex writing tests
085dd6e6 6830
25822942 6831In many areas, the @value{GDBN} tests are already quite comprehensive; you
085dd6e6
JM
6832should be able to copy existing tests to handle new cases.
6833
6834You should try to use @code{gdb_test} whenever possible, since it
6835includes cases to handle all the unexpected errors that might happen.
6836However, it doesn't cost anything to add new test procedures; for
6837instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
6838calls @code{gdb_test} multiple times.
6839
6840Only use @code{send_gdb} and @code{gdb_expect} when absolutely
8a3dae3e
DJ
6841necessary. Even if @value{GDBN} has several valid responses to
6842a command, you can use @code{gdb_test_multiple}. Like @code{gdb_test},
6843@code{gdb_test_multiple} recognizes internal errors and unexpected
6844prompts.
6845
6846Do not write tests which expect a literal tab character from @value{GDBN}.
6847On some operating systems (e.g.@: OpenBSD) the TTY layer expands tabs to
6848spaces, so by the time @value{GDBN}'s output reaches expect the tab is gone.
085dd6e6
JM
6849
6850The source language programs do @emph{not} need to be in a consistent
25822942 6851style. Since @value{GDBN} is used to debug programs written in many different
085dd6e6 6852styles, it's worth having a mix of styles in the testsuite; for
25822942 6853instance, some @value{GDBN} bugs involving the display of source lines would
085dd6e6
JM
6854never manifest themselves if the programs used GNU coding style
6855uniformly.
6856
c906108c
SS
6857@node Hints
6858
6859@chapter Hints
6860
6861Check the @file{README} file, it often has useful information that does not
6862appear anywhere else in the directory.
6863
6864@menu
25822942 6865* Getting Started:: Getting started working on @value{GDBN}
33e16fad 6866* Debugging GDB:: Debugging @value{GDBN} with itself
c906108c
SS
6867@end menu
6868
6869@node Getting Started,,, Hints
6870
6871@section Getting Started
6872
25822942 6873@value{GDBN} is a large and complicated program, and if you first starting to
c906108c
SS
6874work on it, it can be hard to know where to start. Fortunately, if you
6875know how to go about it, there are ways to figure out what is going on.
6876
25822942
DB
6877This manual, the @value{GDBN} Internals manual, has information which applies
6878generally to many parts of @value{GDBN}.
c906108c
SS
6879
6880Information about particular functions or data structures are located in
6881comments with those functions or data structures. If you run across a
6882function or a global variable which does not have a comment correctly
25822942 6883explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
c906108c
SS
6884free to submit a bug report, with a suggested comment if you can figure
6885out what the comment should say. If you find a comment which is
6886actually wrong, be especially sure to report that.
6887
6888Comments explaining the function of macros defined in host, target, or
6889native dependent files can be in several places. Sometimes they are
6890repeated every place the macro is defined. Sometimes they are where the
6891macro is used. Sometimes there is a header file which supplies a
6892default definition of the macro, and the comment is there. This manual
6893also documents all the available macros.
6894@c (@pxref{Host Conditionals}, @pxref{Target
6895@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
6896@c Conditionals})
6897
56caf160
EZ
6898Start with the header files. Once you have some idea of how
6899@value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},
6900@file{gdbtypes.h}), you will find it much easier to understand the
6901code which uses and creates those symbol tables.
c906108c
SS
6902
6903You may wish to process the information you are getting somehow, to
6904enhance your understanding of it. Summarize it, translate it to another
25822942 6905language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
c906108c
SS
6906the code to predict what a test case would do and write the test case
6907and verify your prediction, etc. If you are reading code and your eyes
6908are starting to glaze over, this is a sign you need to use a more active
6909approach.
6910
25822942 6911Once you have a part of @value{GDBN} to start with, you can find more
c906108c
SS
6912specifically the part you are looking for by stepping through each
6913function with the @code{next} command. Do not use @code{step} or you
6914will quickly get distracted; when the function you are stepping through
6915calls another function try only to get a big-picture understanding
6916(perhaps using the comment at the beginning of the function being
6917called) of what it does. This way you can identify which of the
6918functions being called by the function you are stepping through is the
6919one which you are interested in. You may need to examine the data
6920structures generated at each stage, with reference to the comments in
6921the header files explaining what the data structures are supposed to
6922look like.
6923
6924Of course, this same technique can be used if you are just reading the
6925code, rather than actually stepping through it. The same general
6926principle applies---when the code you are looking at calls something
6927else, just try to understand generally what the code being called does,
6928rather than worrying about all its details.
6929
56caf160
EZ
6930@cindex command implementation
6931A good place to start when tracking down some particular area is with
6932a command which invokes that feature. Suppose you want to know how
6933single-stepping works. As a @value{GDBN} user, you know that the
6934@code{step} command invokes single-stepping. The command is invoked
6935via command tables (see @file{command.h}); by convention the function
6936which actually performs the command is formed by taking the name of
6937the command and adding @samp{_command}, or in the case of an
6938@code{info} subcommand, @samp{_info}. For example, the @code{step}
6939command invokes the @code{step_command} function and the @code{info
6940display} command invokes @code{display_info}. When this convention is
6941not followed, you might have to use @code{grep} or @kbd{M-x
6942tags-search} in emacs, or run @value{GDBN} on itself and set a
6943breakpoint in @code{execute_command}.
6944
6945@cindex @code{bug-gdb} mailing list
c906108c
SS
6946If all of the above fail, it may be appropriate to ask for information
6947on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
6948wondering if anyone could give me some tips about understanding
25822942 6949@value{GDBN}''---if we had some magic secret we would put it in this manual.
c906108c
SS
6950Suggestions for improving the manual are always welcome, of course.
6951
33e16fad 6952@node Debugging GDB,,,Hints
c906108c 6953
25822942 6954@section Debugging @value{GDBN} with itself
56caf160 6955@cindex debugging @value{GDBN}
c906108c 6956
25822942 6957If @value{GDBN} is limping on your machine, this is the preferred way to get it
c906108c
SS
6958fully functional. Be warned that in some ancient Unix systems, like
6959Ultrix 4.2, a program can't be running in one process while it is being
56caf160 6960debugged in another. Rather than typing the command @kbd{@w{./gdb
c906108c 6961./gdb}}, which works on Suns and such, you can copy @file{gdb} to
56caf160 6962@file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.
c906108c 6963
25822942 6964When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
c906108c
SS
6965@file{.gdbinit} file that sets up some simple things to make debugging
6966gdb easier. The @code{info} command, when executed without a subcommand
25822942 6967in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
c906108c
SS
6968gdb. See @file{.gdbinit} for details.
6969
6970If you use emacs, you will probably want to do a @code{make TAGS} after
6971you configure your distribution; this will put the machine dependent
6972routines for your local machine where they will be accessed first by
6973@kbd{M-.}
6974
25822942 6975Also, make sure that you've either compiled @value{GDBN} with your local cc, or
c906108c
SS
6976have run @code{fixincludes} if you are compiling with gcc.
6977
6978@section Submitting Patches
6979
56caf160 6980@cindex submitting patches
c906108c 6981Thanks for thinking of offering your changes back to the community of
25822942 6982@value{GDBN} users. In general we like to get well designed enhancements.
c906108c
SS
6983Thanks also for checking in advance about the best way to transfer the
6984changes.
6985
25822942
DB
6986The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
6987This manual summarizes what we believe to be clean design for @value{GDBN}.
c906108c
SS
6988
6989If the maintainers don't have time to put the patch in when it arrives,
6990or if there is any question about a patch, it goes into a large queue
6991with everyone else's patches and bug reports.
6992
56caf160 6993@cindex legal papers for code contributions
c906108c
SS
6994The legal issue is that to incorporate substantial changes requires a
6995copyright assignment from you and/or your employer, granting ownership
6996of the changes to the Free Software Foundation. You can get the
9e0b60a8
JM
6997standard documents for doing this by sending mail to @code{gnu@@gnu.org}
6998and asking for it. We recommend that people write in "All programs
6999owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
56caf160
EZ
7000changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
7001etc) can be
9e0b60a8 7002contributed with only one piece of legalese pushed through the
be9c6c35 7003bureaucracy and filed with the FSF. We can't start merging changes until
9e0b60a8
JM
7004this paperwork is received by the FSF (their rules, which we follow
7005since we maintain it for them).
c906108c
SS
7006
7007Technically, the easiest way to receive changes is to receive each
56caf160
EZ
7008feature as a small context diff or unidiff, suitable for @code{patch}.
7009Each message sent to me should include the changes to C code and
7010header files for a single feature, plus @file{ChangeLog} entries for
7011each directory where files were modified, and diffs for any changes
7012needed to the manuals (@file{gdb/doc/gdb.texinfo} or
7013@file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a
7014single feature, they can be split down into multiple messages.
9e0b60a8
JM
7015
7016In this way, if we read and like the feature, we can add it to the
c906108c 7017sources with a single patch command, do some testing, and check it in.
56caf160
EZ
7018If you leave out the @file{ChangeLog}, we have to write one. If you leave
7019out the doc, we have to puzzle out what needs documenting. Etc., etc.
c906108c 7020
9e0b60a8
JM
7021The reason to send each change in a separate message is that we will not
7022install some of the changes. They'll be returned to you with questions
7023or comments. If we're doing our job correctly, the message back to you
c906108c 7024will say what you have to fix in order to make the change acceptable.
9e0b60a8
JM
7025The reason to have separate messages for separate features is so that
7026the acceptable changes can be installed while one or more changes are
7027being reworked. If multiple features are sent in a single message, we
7028tend to not put in the effort to sort out the acceptable changes from
7029the unacceptable, so none of the features get installed until all are
7030acceptable.
7031
7032If this sounds painful or authoritarian, well, it is. But we get a lot
7033of bug reports and a lot of patches, and many of them don't get
7034installed because we don't have the time to finish the job that the bug
c906108c
SS
7035reporter or the contributor could have done. Patches that arrive
7036complete, working, and well designed, tend to get installed on the day
9e0b60a8
JM
7037they arrive. The others go into a queue and get installed as time
7038permits, which, since the maintainers have many demands to meet, may not
7039be for quite some time.
c906108c 7040
56caf160 7041Please send patches directly to
47b95330 7042@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}.
c906108c
SS
7043
7044@section Obsolete Conditionals
56caf160 7045@cindex obsolete code
c906108c 7046
25822942 7047Fragments of old code in @value{GDBN} sometimes reference or set the following
c906108c
SS
7048configuration macros. They should not be used by new code, and old uses
7049should be removed as those parts of the debugger are otherwise touched.
7050
7051@table @code
c906108c
SS
7052@item STACK_END_ADDR
7053This macro used to define where the end of the stack appeared, for use
7054in interpreting core file formats that don't record this address in the
25822942
DB
7055core file itself. This information is now configured in BFD, and @value{GDBN}
7056gets the info portably from there. The values in @value{GDBN}'s configuration
c906108c 7057files should be moved into BFD configuration files (if needed there),
25822942 7058and deleted from all of @value{GDBN}'s config files.
c906108c
SS
7059
7060Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
7061is so old that it has never been converted to use BFD. Now that's old!
7062
c906108c
SS
7063@end table
7064
bcd7e15f 7065@include observer.texi
2154891a 7066@raisesections
aab4e0ec 7067@include fdl.texi
2154891a 7068@lowersections
aab4e0ec 7069
56caf160
EZ
7070@node Index
7071@unnumbered Index
7072
7073@printindex cp
7074
c906108c 7075@bye
This page took 1.058241 seconds and 4 git commands to generate.