* NEWS: Add information on compressed debug sections.
[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
31fffb02
CS
2204@subsection Compressed DWARF 2
2205
2206@cindex Compressed DWARF 2 debugging info
2207Compressed DWARF 2 is not technically a separate debugging format, but
2208merely DWARF 2 debug information that has been compressed. In this
2209format, every object-file section holding DWARF 2 debugging
2210information is compressed and prepended with a header. (The section
2211is also typically renamed, so a section called @code{.debug_info} in a
2212DWARF 2 binary would be called @code{.zdebug_info} in a compressed
2213DWARF 2 binary.) The header is 12 bytes long:
2214
2215@itemize @bullet
2216@item
22174 bytes: the literal string ``ZLIB''
2218@item
22198 bytes: the uncompressed size of the section, in big-endian byte
2220order.
2221@end itemize
2222
2223The same reader is used for both compressed an normal DWARF 2 info.
2224Section decompression is done in @code{zlib_decompress_section} in
2225@file{dwarf2read.c}.
2226
c906108c
SS
2227@subsection SOM
2228
56caf160 2229@cindex SOM debugging info
c906108c
SS
2230Like COFF, the SOM definition includes debugging information.
2231
25822942 2232@section Adding a New Symbol Reader to @value{GDBN}
c906108c 2233
56caf160
EZ
2234@cindex adding debugging info reader
2235If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
c906108c
SS
2236there is probably little to be done.
2237
2238If you need to add a new object file format, you must first add it to
2239BFD. This is beyond the scope of this document.
2240
2241You must then arrange for the BFD code to provide access to the
25822942 2242debugging symbols. Generally @value{GDBN} will have to call swapping routines
c906108c 2243from BFD and a few other BFD internal routines to locate the debugging
25822942 2244information. As much as possible, @value{GDBN} should not depend on the BFD
c906108c
SS
2245internal data structures.
2246
2247For some targets (e.g., COFF), there is a special transfer vector used
2248to call swapping routines, since the external data structures on various
2249platforms have different sizes and layouts. Specialized routines that
2250will only ever be implemented by one object file format may be called
2251directly. This interface should be described in a file
56caf160 2252@file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
c906108c 2253
c91d38aa
DJ
2254@section Memory Management for Symbol Files
2255
2256Most memory associated with a loaded symbol file is stored on
2257its @code{objfile_obstack}. This includes symbols, types,
2258namespace data, and other information produced by the symbol readers.
2259
2260Because this data lives on the objfile's obstack, it is automatically
2261released when the objfile is unloaded or reloaded. Therefore one
2262objfile must not reference symbol or type data from another objfile;
2263they could be unloaded at different times.
2264
2265User convenience variables, et cetera, have associated types. Normally
2266these types live in the associated objfile. However, when the objfile
2267is unloaded, those types are deep copied to global memory, so that
2268the values of the user variables and history items are not lost.
2269
c906108c
SS
2270
2271@node Language Support
2272
2273@chapter Language Support
2274
56caf160
EZ
2275@cindex language support
2276@value{GDBN}'s language support is mainly driven by the symbol reader,
2277although it is possible for the user to set the source language
2278manually.
c906108c 2279
56caf160
EZ
2280@value{GDBN} chooses the source language by looking at the extension
2281of the file recorded in the debug info; @file{.c} means C, @file{.f}
2282means Fortran, etc. It may also use a special-purpose language
2283identifier if the debug format supports it, like with DWARF.
c906108c 2284
25822942 2285@section Adding a Source Language to @value{GDBN}
c906108c 2286
56caf160
EZ
2287@cindex adding source language
2288To add other languages to @value{GDBN}'s expression parser, follow the
2289following steps:
c906108c
SS
2290
2291@table @emph
2292@item Create the expression parser.
2293
56caf160 2294@cindex expression parser
c906108c 2295This should reside in a file @file{@var{lang}-exp.y}. Routines for
56caf160 2296building parsed expressions into a @code{union exp_element} list are in
c906108c
SS
2297@file{parse.c}.
2298
56caf160 2299@cindex language parser
c906108c
SS
2300Since we can't depend upon everyone having Bison, and YACC produces
2301parsers that define a bunch of global names, the following lines
56caf160 2302@strong{must} be included at the top of the YACC parser, to prevent the
c906108c
SS
2303various parsers from defining the same global names:
2304
474c8240 2305@smallexample
56caf160
EZ
2306#define yyparse @var{lang}_parse
2307#define yylex @var{lang}_lex
2308#define yyerror @var{lang}_error
2309#define yylval @var{lang}_lval
2310#define yychar @var{lang}_char
2311#define yydebug @var{lang}_debug
2312#define yypact @var{lang}_pact
2313#define yyr1 @var{lang}_r1
2314#define yyr2 @var{lang}_r2
2315#define yydef @var{lang}_def
2316#define yychk @var{lang}_chk
2317#define yypgo @var{lang}_pgo
2318#define yyact @var{lang}_act
2319#define yyexca @var{lang}_exca
2320#define yyerrflag @var{lang}_errflag
2321#define yynerrs @var{lang}_nerrs
474c8240 2322@end smallexample
c906108c
SS
2323
2324At the bottom of your parser, define a @code{struct language_defn} and
2325initialize it with the right values for your language. Define an
2326@code{initialize_@var{lang}} routine and have it call
25822942 2327@samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
c906108c
SS
2328that your language exists. You'll need some other supporting variables
2329and functions, which will be used via pointers from your
2330@code{@var{lang}_language_defn}. See the declaration of @code{struct
2331language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
2332for more information.
2333
2334@item Add any evaluation routines, if necessary
2335
56caf160
EZ
2336@cindex expression evaluation routines
2337@findex evaluate_subexp
2338@findex prefixify_subexp
2339@findex length_of_subexp
c906108c
SS
2340If you need new opcodes (that represent the operations of the language),
2341add them to the enumerated type in @file{expression.h}. Add support
56caf160
EZ
2342code for these operations in the @code{evaluate_subexp} function
2343defined in the file @file{eval.c}. Add cases
c906108c 2344for new opcodes in two functions from @file{parse.c}:
56caf160 2345@code{prefixify_subexp} and @code{length_of_subexp}. These compute
c906108c
SS
2346the number of @code{exp_element}s that a given operation takes up.
2347
2348@item Update some existing code
2349
2350Add an enumerated identifier for your language to the enumerated type
2351@code{enum language} in @file{defs.h}.
2352
2353Update the routines in @file{language.c} so your language is included.
2354These routines include type predicates and such, which (in some cases)
2355are language dependent. If your language does not appear in the switch
2356statement, an error is reported.
2357
56caf160 2358@vindex current_language
c906108c
SS
2359Also included in @file{language.c} is the code that updates the variable
2360@code{current_language}, and the routines that translate the
2361@code{language_@var{lang}} enumerated identifier into a printable
2362string.
2363
56caf160 2364@findex _initialize_language
c906108c
SS
2365Update the function @code{_initialize_language} to include your
2366language. This function picks the default language upon startup, so is
25822942 2367dependent upon which languages that @value{GDBN} is built for.
c906108c 2368
56caf160 2369@findex allocate_symtab
c906108c
SS
2370Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
2371code so that the language of each symtab (source file) is set properly.
2372This is used to determine the language to use at each stack frame level.
2373Currently, the language is set based upon the extension of the source
2374file. If the language can be better inferred from the symbol
2375information, please set the language of the symtab in the symbol-reading
2376code.
2377
56caf160
EZ
2378@findex print_subexp
2379@findex op_print_tab
2380Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
c906108c
SS
2381expression opcodes you have added to @file{expression.h}. Also, add the
2382printed representations of your operators to @code{op_print_tab}.
2383
2384@item Add a place of call
2385
56caf160 2386@findex parse_exp_1
c906108c 2387Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
56caf160 2388@code{parse_exp_1} (defined in @file{parse.c}).
c906108c
SS
2389
2390@item Use macros to trim code
2391
56caf160 2392@cindex trimming language-dependent code
25822942
DB
2393The user has the option of building @value{GDBN} for some or all of the
2394languages. If the user decides to build @value{GDBN} for the language
c906108c
SS
2395@var{lang}, then every file dependent on @file{language.h} will have the
2396macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
2397leave out large routines that the user won't need if he or she is not
2398using your language.
2399
25822942 2400Note that you do not need to do this in your YACC parser, since if @value{GDBN}
c906108c 2401is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
25822942 2402compiled form of your parser) is not linked into @value{GDBN} at all.
c906108c 2403
56caf160
EZ
2404See the file @file{configure.in} for how @value{GDBN} is configured
2405for different languages.
c906108c
SS
2406
2407@item Edit @file{Makefile.in}
2408
2409Add dependencies in @file{Makefile.in}. Make sure you update the macro
2410variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
2411not get linked in, or, worse yet, it may not get @code{tar}red into the
2412distribution!
c906108c
SS
2413@end table
2414
2415
2416@node Host Definition
2417
2418@chapter Host Definition
2419
56caf160 2420With the advent of Autoconf, it's rarely necessary to have host
7fd60527
AC
2421definition machinery anymore. The following information is provided,
2422mainly, as an historical reference.
c906108c
SS
2423
2424@section Adding a New Host
2425
56caf160
EZ
2426@cindex adding a new host
2427@cindex host, adding
7fd60527
AC
2428@value{GDBN}'s host configuration support normally happens via Autoconf.
2429New host-specific definitions should not be needed. Older hosts
2430@value{GDBN} still use the host-specific definitions and files listed
2431below, but these mostly exist for historical reasons, and will
56caf160 2432eventually disappear.
c906108c 2433
c906108c 2434@table @file
c906108c 2435@item gdb/config/@var{arch}/@var{xyz}.mh
7fd60527
AC
2436This file once contained both host and native configuration information
2437(@pxref{Native Debugging}) for the machine @var{xyz}. The host
2438configuration information is now handed by Autoconf.
2439
2440Host configuration information included a definition of
2441@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC},
7708fa01
AC
2442@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},
2443@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.
c906108c 2444
7fd60527
AC
2445New host only configurations do not need this file.
2446
c906108c 2447@item gdb/config/@var{arch}/xm-@var{xyz}.h
7fd60527
AC
2448This file once contained definitions and includes required when hosting
2449gdb on machine @var{xyz}. Those definitions and includes are now
2450handled by Autoconf.
2451
2452New host and native configurations do not need this file.
2453
2454@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h}
2455file to define the macros @var{HOST_FLOAT_FORMAT},
2456@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}. That code
2457also needs to be replaced with either an Autoconf or run-time test.}
c906108c 2458
c906108c
SS
2459@end table
2460
2461@subheading Generic Host Support Files
2462
56caf160 2463@cindex generic host support
c906108c
SS
2464There are some ``generic'' versions of routines that can be used by
2465various systems. These can be customized in various ways by macros
2466defined in your @file{xm-@var{xyz}.h} file. If these routines work for
2467the @var{xyz} host, you can just include the generic file's name (with
2468@samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
2469
2470Otherwise, if your machine needs custom support routines, you will need
2471to write routines that perform the same functions as the generic file.
2472Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
2473into @code{XDEPFILES}.
2474
2475@table @file
56caf160
EZ
2476@cindex remote debugging support
2477@cindex serial line support
c906108c
SS
2478@item ser-unix.c
2479This contains serial line support for Unix systems. This is always
2480included, via the makefile variable @code{SER_HARDWIRE}; override this
2481variable in the @file{.mh} file to avoid it.
2482
2483@item ser-go32.c
2484This contains serial line support for 32-bit programs running under DOS,
56caf160 2485using the DJGPP (a.k.a.@: GO32) execution environment.
c906108c 2486
56caf160 2487@cindex TCP remote support
c906108c
SS
2488@item ser-tcp.c
2489This contains generic TCP support using sockets.
c906108c
SS
2490@end table
2491
2492@section Host Conditionals
2493
56caf160
EZ
2494When @value{GDBN} is configured and compiled, various macros are
2495defined or left undefined, to control compilation based on the
2496attributes of the host system. These macros and their meanings (or if
2497the meaning is not documented here, then one of the source files where
2498they are used is indicated) are:
c906108c 2499
56caf160 2500@ftable @code
25822942 2501@item @value{GDBN}INIT_FILENAME
56caf160
EZ
2502The default name of @value{GDBN}'s initialization file (normally
2503@file{.gdbinit}).
c906108c 2504
cce74817
JM
2505@item NO_STD_REGS
2506This macro is deprecated.
2507
c906108c
SS
2508@item SIGWINCH_HANDLER
2509If your host defines @code{SIGWINCH}, you can define this to be the name
2510of a function to be called if @code{SIGWINCH} is received.
2511
2512@item SIGWINCH_HANDLER_BODY
2513Define this to expand into code that will define the function named by
2514the expansion of @code{SIGWINCH_HANDLER}.
2515
c906108c 2516@item CRLF_SOURCE_FILES
56caf160 2517@cindex DOS text files
c906108c
SS
2518Define this if host files use @code{\r\n} rather than @code{\n} as a
2519line terminator. This will cause source file listings to omit @code{\r}
56caf160
EZ
2520characters when printing and it will allow @code{\r\n} line endings of files
2521which are ``sourced'' by gdb. It must be possible to open files in binary
c906108c
SS
2522mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
2523
2524@item DEFAULT_PROMPT
56caf160 2525@cindex prompt
c906108c
SS
2526The default value of the prompt string (normally @code{"(gdb) "}).
2527
2528@item DEV_TTY
56caf160 2529@cindex terminal device
c906108c
SS
2530The name of the generic TTY device, defaults to @code{"/dev/tty"}.
2531
c906108c
SS
2532@item FOPEN_RB
2533Define this if binary files are opened the same way as text files.
2534
c906108c 2535@item HAVE_MMAP
56caf160 2536@findex mmap
c906108c
SS
2537In some cases, use the system call @code{mmap} for reading symbol
2538tables. For some machines this allows for sharing and quick updates.
2539
c906108c
SS
2540@item HAVE_TERMIO
2541Define this if the host system has @code{termio.h}.
2542
c906108c 2543@item INT_MAX
9742079a
EZ
2544@itemx INT_MIN
2545@itemx LONG_MAX
2546@itemx UINT_MAX
2547@itemx ULONG_MAX
c906108c
SS
2548Values for host-side constants.
2549
2550@item ISATTY
2551Substitute for isatty, if not available.
2552
2553@item LONGEST
2554This is the longest integer type available on the host. If not defined,
2555it will default to @code{long long} or @code{long}, depending on
2556@code{CC_HAS_LONG_LONG}.
2557
2558@item CC_HAS_LONG_LONG
56caf160
EZ
2559@cindex @code{long long} data type
2560Define this if the host C compiler supports @code{long long}. This is set
2561by the @code{configure} script.
c906108c
SS
2562
2563@item PRINTF_HAS_LONG_LONG
2564Define this if the host can handle printing of long long integers via
56caf160
EZ
2565the printf format conversion specifier @code{ll}. This is set by the
2566@code{configure} script.
c906108c
SS
2567
2568@item HAVE_LONG_DOUBLE
56caf160
EZ
2569Define this if the host C compiler supports @code{long double}. This is
2570set by the @code{configure} script.
c906108c
SS
2571
2572@item PRINTF_HAS_LONG_DOUBLE
2573Define this if the host can handle printing of long double float-point
56caf160
EZ
2574numbers via the printf format conversion specifier @code{Lg}. This is
2575set by the @code{configure} script.
c906108c
SS
2576
2577@item SCANF_HAS_LONG_DOUBLE
2578Define this if the host can handle the parsing of long double
56caf160
EZ
2579float-point numbers via the scanf format conversion specifier
2580@code{Lg}. This is set by the @code{configure} script.
c906108c
SS
2581
2582@item LSEEK_NOT_LINEAR
2583Define this if @code{lseek (n)} does not necessarily move to byte number
2584@code{n} in the file. This is only used when reading source files. It
2585is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
2586
2587@item L_SET
56caf160
EZ
2588This macro is used as the argument to @code{lseek} (or, most commonly,
2589@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
2590which is the POSIX equivalent.
c906108c 2591
c906108c
SS
2592@item NORETURN
2593If defined, this should be one or more tokens, such as @code{volatile},
2594that can be used in both the declaration and definition of functions to
2595indicate that they never return. The default is already set correctly
2596if compiling with GCC. This will almost never need to be defined.
2597
2598@item ATTR_NORETURN
2599If defined, this should be one or more tokens, such as
2600@code{__attribute__ ((noreturn))}, that can be used in the declarations
2601of functions to indicate that they never return. The default is already
2602set correctly if compiling with GCC. This will almost never need to be
2603defined.
2604
c906108c 2605@item SEEK_CUR
9742079a 2606@itemx SEEK_SET
56caf160 2607Define these to appropriate value for the system @code{lseek}, if not already
c906108c
SS
2608defined.
2609
2610@item STOP_SIGNAL
56caf160
EZ
2611This is the signal for stopping @value{GDBN}. Defaults to
2612@code{SIGTSTP}. (Only redefined for the Convex.)
c906108c 2613
c906108c
SS
2614@item USG
2615Means that System V (prior to SVR4) include files are in use. (FIXME:
7ca9f392
AC
2616This symbol is abused in @file{infrun.c}, @file{regex.c}, and
2617@file{utils.c} for other things, at the moment.)
c906108c
SS
2618
2619@item lint
56caf160 2620Define this to help placate @code{lint} in some situations.
c906108c
SS
2621
2622@item volatile
2623Define this to override the defaults of @code{__volatile__} or
2624@code{/**/}.
56caf160 2625@end ftable
c906108c
SS
2626
2627
2628@node Target Architecture Definition
2629
2630@chapter Target Architecture Definition
2631
56caf160
EZ
2632@cindex target architecture definition
2633@value{GDBN}'s target architecture defines what sort of
2634machine-language programs @value{GDBN} can work with, and how it works
2635with them.
c906108c 2636
af6c57ea
AC
2637The target architecture object is implemented as the C structure
2638@code{struct gdbarch *}. The structure, and its methods, are generated
93c2c750 2639using the Bourne shell script @file{gdbarch.sh}.
c906108c 2640
b6fd0dfb
NR
2641@menu
2642* OS ABI Variant Handling::
2643* Initialize New Architecture::
2644* Registers and Memory::
2645* Pointers and Addresses::
2646* Address Classes::
2647* Raw and Virtual Registers::
2648* Register and Memory Data::
2649* Frame Interpretation::
2650* Inferior Call Setup::
2651* Compiler Characteristics::
2652* Target Conditionals::
2653* Adding a New Target::
b6fd0dfb
NR
2654@end menu
2655
2656@node OS ABI Variant Handling
70f80edf
JT
2657@section Operating System ABI Variant Handling
2658@cindex OS ABI variants
2659
2660@value{GDBN} provides a mechanism for handling variations in OS
2661ABIs. An OS ABI variant may have influence over any number of
2662variables in the target architecture definition. There are two major
2663components in the OS ABI mechanism: sniffers and handlers.
2664
2665A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair
2666(the architecture may be wildcarded) in an attempt to determine the
2667OS ABI of that file. Sniffers with a wildcarded architecture are considered
2668to be @dfn{generic}, while sniffers for a specific architecture are
2669considered to be @dfn{specific}. A match from a specific sniffer
2670overrides a match from a generic sniffer. Multiple sniffers for an
2671architecture/flavour may exist, in order to differentiate between two
2672different operating systems which use the same basic file format. The
2673OS ABI framework provides a generic sniffer for ELF-format files which
2674examines the @code{EI_OSABI} field of the ELF header, as well as note
2675sections known to be used by several operating systems.
2676
2677@cindex fine-tuning @code{gdbarch} structure
2678A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the
2679selected OS ABI. There may be only one handler for a given OS ABI
2680for each BFD architecture.
2681
f4b3909f 2682The following OS ABI variants are defined in @file{defs.h}:
70f80edf
JT
2683
2684@table @code
2685
f4b3909f
EZ
2686@findex GDB_OSABI_UNINITIALIZED
2687@item GDB_OSABI_UNINITIALIZED
2688Used for struct gdbarch_info if ABI is still uninitialized.
2689
70f80edf
JT
2690@findex GDB_OSABI_UNKNOWN
2691@item GDB_OSABI_UNKNOWN
2692The ABI of the inferior is unknown. The default @code{gdbarch}
2693settings for the architecture will be used.
2694
2695@findex GDB_OSABI_SVR4
2696@item GDB_OSABI_SVR4
f4b3909f 2697UNIX System V Release 4.
70f80edf
JT
2698
2699@findex GDB_OSABI_HURD
2700@item GDB_OSABI_HURD
f4b3909f 2701GNU using the Hurd kernel.
70f80edf
JT
2702
2703@findex GDB_OSABI_SOLARIS
2704@item GDB_OSABI_SOLARIS
f4b3909f 2705Sun Solaris.
70f80edf
JT
2706
2707@findex GDB_OSABI_OSF1
2708@item GDB_OSABI_OSF1
f4b3909f 2709OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
70f80edf
JT
2710
2711@findex GDB_OSABI_LINUX
2712@item GDB_OSABI_LINUX
f4b3909f 2713GNU using the Linux kernel.
70f80edf
JT
2714
2715@findex GDB_OSABI_FREEBSD_AOUT
2716@item GDB_OSABI_FREEBSD_AOUT
f4b3909f 2717FreeBSD using the @code{a.out} executable format.
70f80edf
JT
2718
2719@findex GDB_OSABI_FREEBSD_ELF
2720@item GDB_OSABI_FREEBSD_ELF
f4b3909f 2721FreeBSD using the ELF executable format.
70f80edf
JT
2722
2723@findex GDB_OSABI_NETBSD_AOUT
2724@item GDB_OSABI_NETBSD_AOUT
f4b3909f 2725NetBSD using the @code{a.out} executable format.
70f80edf
JT
2726
2727@findex GDB_OSABI_NETBSD_ELF
2728@item GDB_OSABI_NETBSD_ELF
f4b3909f
EZ
2729NetBSD using the ELF executable format.
2730
2731@findex GDB_OSABI_OPENBSD_ELF
2732@item GDB_OSABI_OPENBSD_ELF
2733OpenBSD using the ELF executable format.
70f80edf
JT
2734
2735@findex GDB_OSABI_WINCE
2736@item GDB_OSABI_WINCE
f4b3909f 2737Windows CE.
70f80edf 2738
1029b7fa
MK
2739@findex GDB_OSABI_GO32
2740@item GDB_OSABI_GO32
f4b3909f 2741DJGPP.
1029b7fa 2742
f4b3909f
EZ
2743@findex GDB_OSABI_IRIX
2744@item GDB_OSABI_IRIX
2745Irix.
2746
f4b3909f
EZ
2747@findex GDB_OSABI_INTERIX
2748@item GDB_OSABI_INTERIX
2749Interix (Posix layer for MS-Windows systems).
1029b7fa 2750
f4b3909f
EZ
2751@findex GDB_OSABI_HPUX_ELF
2752@item GDB_OSABI_HPUX_ELF
2753HP/UX using the ELF executable format.
70f80edf 2754
f4b3909f
EZ
2755@findex GDB_OSABI_HPUX_SOM
2756@item GDB_OSABI_HPUX_SOM
2757HP/UX using the SOM executable format.
70f80edf 2758
f4b3909f
EZ
2759@findex GDB_OSABI_QNXNTO
2760@item GDB_OSABI_QNXNTO
2761QNX Neutrino.
2762
2763@findex GDB_OSABI_CYGWIN
2764@item GDB_OSABI_CYGWIN
2765Cygwin.
2766
2767@findex GDB_OSABI_AIX
2768@item GDB_OSABI_AIX
2769AIX.
70f80edf
JT
2770
2771@end table
2772
2773Here are the functions that make up the OS ABI framework:
2774
2775@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi})
2776Return the name of the OS ABI corresponding to @var{osabi}.
2777@end deftypefun
2778
c133ab7a 2779@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 2780Register the OS ABI handler specified by @var{init_osabi} for the
c133ab7a
MK
2781architecture, machine type and OS ABI specified by @var{arch},
2782@var{machine} and @var{osabi}. In most cases, a value of zero for the
2783machine type, which implies the architecture's default machine type,
2784will suffice.
70f80edf
JT
2785@end deftypefun
2786
2787@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd}))
2788Register the OS ABI file sniffer specified by @var{sniffer} for the
2789BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.
2790If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to
2791be generic, and is allowed to examine @var{flavour}-flavoured files for
2792any architecture.
2793@end deftypefun
2794
2795@deftypefun enum gdb_osabi gdbarch_lookup_osabi (bfd *@var{abfd})
2796Examine the file described by @var{abfd} to determine its OS ABI.
2797The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot
2798be determined.
2799@end deftypefun
2800
2801@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi})
2802Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the
2803@code{gdbarch} structure specified by @var{gdbarch}. If a handler
2804corresponding to @var{osabi} has not been registered for @var{gdbarch}'s
2805architecture, a warning will be issued and the debugging session will continue
2806with the defaults already established for @var{gdbarch}.
2807@end deftypefun
2808
f4b3909f
EZ
2809@deftypefun void generic_elf_osabi_sniff_abi_tag_sections (bfd *@var{abfd}, asection *@var{sect}, void *@var{obj})
2810Helper routine for ELF file sniffers. Examine the file described by
2811@var{abfd} and look at ABI tag note sections to determine the OS ABI
2812from the note. This function should be called via
2813@code{bfd_map_over_sections}.
2814@end deftypefun
2815
b6fd0dfb 2816@node Initialize New Architecture
7a107747
DJ
2817@section Initializing a New Architecture
2818
2819Each @code{gdbarch} is associated with a single @sc{bfd} architecture,
2820via a @code{bfd_arch_@var{arch}} constant. The @code{gdbarch} is
2821registered by a call to @code{register_gdbarch_init}, usually from
2822the file's @code{_initialize_@var{filename}} routine, which will
2823be automatically called during @value{GDBN} startup. The arguments
2824are a @sc{bfd} architecture constant and an initialization function.
2825
2826The initialization function has this type:
2827
2828@smallexample
2829static struct gdbarch *
2830@var{arch}_gdbarch_init (struct gdbarch_info @var{info},
2831 struct gdbarch_list *@var{arches})
2832@end smallexample
2833
2834The @var{info} argument contains parameters used to select the correct
2835architecture, and @var{arches} is a list of architectures which
2836have already been created with the same @code{bfd_arch_@var{arch}}
2837value.
2838
2839The initialization function should first make sure that @var{info}
2840is acceptable, and return @code{NULL} if it is not. Then, it should
2841search through @var{arches} for an exact match to @var{info}, and
2842return one if found. Lastly, if no exact match was found, it should
2843create a new architecture based on @var{info} and return it.
2844
2845Only information in @var{info} should be used to choose the new
2846architecture. Historically, @var{info} could be sparse, and
2847defaults would be collected from the first element on @var{arches}.
2848However, @value{GDBN} now fills in @var{info} more thoroughly,
2849so new @code{gdbarch} initialization functions should not take
2850defaults from @var{arches}.
2851
b6fd0dfb 2852@node Registers and Memory
c906108c
SS
2853@section Registers and Memory
2854
56caf160
EZ
2855@value{GDBN}'s model of the target machine is rather simple.
2856@value{GDBN} assumes the machine includes a bank of registers and a
2857block of memory. Each register may have a different size.
c906108c 2858
56caf160
EZ
2859@value{GDBN} does not have a magical way to match up with the
2860compiler's idea of which registers are which; however, it is critical
2861that they do match up accurately. The only way to make this work is
2862to get accurate information about the order that the compiler uses,
4a9bb1df 2863and to reflect that in the @code{gdbarch_register_name} and related functions.
c906108c 2864
25822942 2865@value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
c906108c 2866
b6fd0dfb 2867@node Pointers and Addresses
93e79dbd
JB
2868@section Pointers Are Not Always Addresses
2869@cindex pointer representation
2870@cindex address representation
2871@cindex word-addressed machines
2872@cindex separate data and code address spaces
2873@cindex spaces, separate data and code address
2874@cindex address spaces, separate data and code
2875@cindex code pointers, word-addressed
2876@cindex converting between pointers and addresses
2877@cindex D10V addresses
2878
2879On almost all 32-bit architectures, the representation of a pointer is
2880indistinguishable from the representation of some fixed-length number
2881whose value is the byte address of the object pointed to. On such
56caf160 2882machines, the words ``pointer'' and ``address'' can be used interchangeably.
93e79dbd
JB
2883However, architectures with smaller word sizes are often cramped for
2884address space, so they may choose a pointer representation that breaks this
2885identity, and allows a larger code address space.
2886
172c2a43 2887For example, the Renesas D10V is a 16-bit VLIW processor whose
93e79dbd
JB
2888instructions are 32 bits long@footnote{Some D10V instructions are
2889actually pairs of 16-bit sub-instructions. However, since you can't
2890jump into the middle of such a pair, code addresses can only refer to
2891full 32 bit instructions, which is what matters in this explanation.}.
2892If the D10V used ordinary byte addresses to refer to code locations,
2893then the processor would only be able to address 64kb of instructions.
2894However, since instructions must be aligned on four-byte boundaries, the
56caf160
EZ
2895low two bits of any valid instruction's byte address are always
2896zero---byte addresses waste two bits. So instead of byte addresses,
2897the D10V uses word addresses---byte addresses shifted right two bits---to
93e79dbd
JB
2898refer to code. Thus, the D10V can use 16-bit words to address 256kb of
2899code space.
2900
2901However, this means that code pointers and data pointers have different
2902forms on the D10V. The 16-bit word @code{0xC020} refers to byte address
2903@code{0xC020} when used as a data address, but refers to byte address
2904@code{0x30080} when used as a code address.
2905
2906(The D10V also uses separate code and data address spaces, which also
2907affects the correspondence between pointers and addresses, but we're
2908going to ignore that here; this example is already too long.)
2909
56caf160
EZ
2910To cope with architectures like this---the D10V is not the only
2911one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
93e79dbd
JB
2912byte numbers, and @dfn{pointers}, which are the target's representation
2913of an address of a particular type of data. In the example above,
2914@code{0xC020} is the pointer, which refers to one of the addresses
2915@code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
2916@value{GDBN} provides functions for turning a pointer into an address
2917and vice versa, in the appropriate way for the current architecture.
2918
2919Unfortunately, since addresses and pointers are identical on almost all
2920processors, this distinction tends to bit-rot pretty quickly. Thus,
2921each time you port @value{GDBN} to an architecture which does
2922distinguish between pointers and addresses, you'll probably need to
2923clean up some architecture-independent code.
2924
2925Here are functions which convert between pointers and addresses:
2926
2927@deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
2928Treat the bytes at @var{buf} as a pointer or reference of type
2929@var{type}, and return the address it represents, in a manner
2930appropriate for the current architecture. This yields an address
2931@value{GDBN} can use to read target memory, disassemble, etc. Note that
2932@var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2933inferior's.
2934
2935For example, if the current architecture is the Intel x86, this function
2936extracts a little-endian integer of the appropriate length from
2937@var{buf} and returns it. However, if the current architecture is the
2938D10V, this function will return a 16-bit integer extracted from
2939@var{buf}, multiplied by four if @var{type} is a pointer to a function.
2940
2941If @var{type} is not a pointer or reference type, then this function
2942will signal an internal error.
2943@end deftypefun
2944
2945@deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
2946Store the address @var{addr} in @var{buf}, in the proper format for a
2947pointer of type @var{type} in the current architecture. Note that
2948@var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2949inferior's.
2950
2951For example, if the current architecture is the Intel x86, this function
2952stores @var{addr} unmodified as a little-endian integer of the
2953appropriate length in @var{buf}. However, if the current architecture
2954is the D10V, this function divides @var{addr} by four if @var{type} is
2955a pointer to a function, and then stores it in @var{buf}.
2956
2957If @var{type} is not a pointer or reference type, then this function
2958will signal an internal error.
2959@end deftypefun
2960
f23631e4 2961@deftypefun CORE_ADDR value_as_address (struct value *@var{val})
93e79dbd
JB
2962Assuming that @var{val} is a pointer, return the address it represents,
2963as appropriate for the current architecture.
2964
2965This function actually works on integral values, as well as pointers.
2966For pointers, it performs architecture-specific conversions as
2967described above for @code{extract_typed_address}.
2968@end deftypefun
2969
2970@deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
2971Create and return a value representing a pointer of type @var{type} to
2972the address @var{addr}, as appropriate for the current architecture.
2973This function performs architecture-specific conversions as described
2974above for @code{store_typed_address}.
2975@end deftypefun
2976
4a9bb1df 2977Here are two functions which architectures can define to indicate the
93e79dbd
JB
2978relationship between pointers and addresses. These have default
2979definitions, appropriate for architectures on which all pointers are
fc0c74b1 2980simple unsigned byte addresses.
93e79dbd 2981
4a9bb1df 2982@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{current_gdbarch}, struct type *@var{type}, char *@var{buf})
93e79dbd
JB
2983Assume that @var{buf} holds a pointer of type @var{type}, in the
2984appropriate format for the current architecture. Return the byte
2985address the pointer refers to.
2986
2987This function may safely assume that @var{type} is either a pointer or a
56caf160 2988C@t{++} reference type.
4a9bb1df 2989@end deftypefun
93e79dbd 2990
4a9bb1df 2991@deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{current_gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
93e79dbd
JB
2992Store in @var{buf} a pointer of type @var{type} representing the address
2993@var{addr}, in the appropriate format for the current architecture.
2994
2995This function may safely assume that @var{type} is either a pointer or a
56caf160 2996C@t{++} reference type.
4a9bb1df 2997@end deftypefun
93e79dbd 2998
b6fd0dfb 2999@node Address Classes
b5b0480a
KB
3000@section Address Classes
3001@cindex address classes
3002@cindex DW_AT_byte_size
3003@cindex DW_AT_address_class
3004
3005Sometimes information about different kinds of addresses is available
3006via the debug information. For example, some programming environments
3007define addresses of several different sizes. If the debug information
3008distinguishes these kinds of address classes through either the size
3009info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit
3010address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the
3011following macros should be defined in order to disambiguate these
3012types within @value{GDBN} as well as provide the added information to
3013a @value{GDBN} user when printing type expressions.
3014
4a9bb1df 3015@deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class})
b5b0480a
KB
3016Returns the type flags needed to construct a pointer type whose size
3017is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.
3018This function is normally called from within a symbol reader. See
3019@file{dwarf2read.c}.
4a9bb1df 3020@end deftypefun
b5b0480a 3021
4a9bb1df 3022@deftypefun char *gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{current_gdbarch}, int @var{type_flags})
b5b0480a
KB
3023Given the type flags representing an address class qualifier, return
3024its name.
4a9bb1df
UW
3025@end deftypefun
3026@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{name}, int *var{type_flags_ptr})
d3e8051b 3027Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags
b5b0480a 3028for that address class qualifier.
4a9bb1df 3029@end deftypefun
b5b0480a
KB
3030
3031Since the need for address classes is rather rare, none of
4a9bb1df
UW
3032the address class functions are defined by default. Predicate
3033functions are provided to detect when they are defined.
b5b0480a
KB
3034
3035Consider a hypothetical architecture in which addresses are normally
303632-bits wide, but 16-bit addresses are also supported. Furthermore,
3037suppose that the @w{DWARF 2} information for this architecture simply
3038uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one
3039of these "short" pointers. The following functions could be defined
4a9bb1df 3040to implement the address class functions:
b5b0480a
KB
3041
3042@smallexample
3043somearch_address_class_type_flags (int byte_size,
3044 int dwarf2_addr_class)
f2abfe65 3045@{
b5b0480a
KB
3046 if (byte_size == 2)
3047 return TYPE_FLAG_ADDRESS_CLASS_1;
3048 else
3049 return 0;
f2abfe65 3050@}
b5b0480a
KB
3051
3052static char *
3053somearch_address_class_type_flags_to_name (int type_flags)
f2abfe65 3054@{
b5b0480a
KB
3055 if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
3056 return "short";
3057 else
3058 return NULL;
f2abfe65 3059@}
b5b0480a
KB
3060
3061int
3062somearch_address_class_name_to_type_flags (char *name,
3063 int *type_flags_ptr)
f2abfe65 3064@{
b5b0480a 3065 if (strcmp (name, "short") == 0)
f2abfe65 3066 @{
b5b0480a
KB
3067 *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
3068 return 1;
f2abfe65 3069 @}
b5b0480a
KB
3070 else
3071 return 0;
f2abfe65 3072@}
b5b0480a
KB
3073@end smallexample
3074
3075The qualifier @code{@@short} is used in @value{GDBN}'s type expressions
3076to indicate the presence of one of these "short" pointers. E.g, if
3077the debug information indicates that @code{short_ptr_var} is one of these
3078short pointers, @value{GDBN} might show the following behavior:
3079
3080@smallexample
3081(gdb) ptype short_ptr_var
3082type = int * @@short
3083@end smallexample
3084
93e79dbd 3085
b6fd0dfb 3086@node Raw and Virtual Registers
13d01224
AC
3087@section Raw and Virtual Register Representations
3088@cindex raw register representation
3089@cindex virtual register representation
3090@cindex representations, raw and virtual registers
3091
3092@emph{Maintainer note: This section is pretty much obsolete. The
3093functionality described here has largely been replaced by
3094pseudo-registers and the mechanisms described in @ref{Target
3095Architecture Definition, , Using Different Register and Memory Data
3096Representations}. See also @uref{http://www.gnu.org/software/gdb/bugs/,
3097Bug Tracking Database} and
3098@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more
3099up-to-date information.}
af6c57ea 3100
9fb4dd36
JB
3101Some architectures use one representation for a value when it lives in a
3102register, but use a different representation when it lives in memory.
25822942 3103In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
9fb4dd36 3104the target registers, and the @dfn{virtual} representation is the one
25822942 3105used in memory, and within @value{GDBN} @code{struct value} objects.
9fb4dd36 3106
13d01224
AC
3107@emph{Maintainer note: Notice that the same mechanism is being used to
3108both convert a register to a @code{struct value} and alternative
3109register forms.}
3110
9fb4dd36
JB
3111For almost all data types on almost all architectures, the virtual and
3112raw representations are identical, and no special handling is needed.
3113However, they do occasionally differ. For example:
3114
3115@itemize @bullet
9fb4dd36 3116@item
56caf160 3117The x86 architecture supports an 80-bit @code{long double} type. However, when
9fb4dd36
JB
3118we store those values in memory, they occupy twelve bytes: the
3119floating-point number occupies the first ten, and the final two bytes
3120are unused. This keeps the values aligned on four-byte boundaries,
3121allowing more efficient access. Thus, the x86 80-bit floating-point
3122type is the raw representation, and the twelve-byte loosely-packed
3123arrangement is the virtual representation.
3124
3125@item
25822942
DB
3126Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit
3127registers, with garbage in their upper bits. @value{GDBN} ignores the top 32
9fb4dd36
JB
3128bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the
3129raw representation, and the trimmed 32-bit representation is the
3130virtual representation.
9fb4dd36
JB
3131@end itemize
3132
3133In general, the raw representation is determined by the architecture, or
25822942
DB
3134@value{GDBN}'s interface to the architecture, while the virtual representation
3135can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file,
56caf160
EZ
3136@code{registers}, holds the register contents in raw format, and the
3137@value{GDBN} remote protocol transmits register values in raw format.
9fb4dd36 3138
56caf160
EZ
3139Your architecture may define the following macros to request
3140conversions between the raw and virtual format:
9fb4dd36
JB
3141
3142@deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
3143Return non-zero if register number @var{reg}'s value needs different raw
3144and virtual formats.
6f6ef15a
EZ
3145
3146You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
3147unless this macro returns a non-zero value for that register.
9fb4dd36
JB
3148@end deftypefn
3149
12c266ea 3150@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg})
9fb4dd36 3151The size of register number @var{reg}'s raw value. This is the number
25822942 3152of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
9fb4dd36
JB
3153remote protocol packet.
3154@end deftypefn
3155
f30992d4 3156@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg})
9fb4dd36
JB
3157The size of register number @var{reg}'s value, in its virtual format.
3158This is the size a @code{struct value}'s buffer will have, holding that
3159register's value.
3160@end deftypefn
3161
2e092625 3162@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg})
9fb4dd36
JB
3163This is the type of the virtual representation of register number
3164@var{reg}. Note that there is no need for a macro giving a type for the
25822942 3165register's raw form; once the register's value has been obtained, @value{GDBN}
9fb4dd36
JB
3166always uses the virtual form.
3167@end deftypefn
3168
3169@deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
3170Convert the value of register number @var{reg} to @var{type}, which
2e092625 3171should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
9fb4dd36
JB
3172at @var{from} holds the register's value in raw format; the macro should
3173convert the value to virtual format, and place it at @var{to}.
3174
6f6ef15a
EZ
3175Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and
3176@code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
3177arguments in different orders.
3178
3179You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
3180for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
3181value.
9fb4dd36
JB
3182@end deftypefn
3183
3184@deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
3185Convert the value of register number @var{reg} to @var{type}, which
2e092625 3186should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
9fb4dd36
JB
3187at @var{from} holds the register's value in raw format; the macro should
3188convert the value to virtual format, and place it at @var{to}.
3189
3190Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
3191their @var{reg} and @var{type} arguments in different orders.
3192@end deftypefn
3193
3194
b6fd0dfb 3195@node Register and Memory Data
13d01224
AC
3196@section Using Different Register and Memory Data Representations
3197@cindex register representation
3198@cindex memory representation
3199@cindex representations, register and memory
3200@cindex register data formats, converting
3201@cindex @code{struct value}, converting register contents to
3202
3203@emph{Maintainer's note: The way GDB manipulates registers is undergoing
d3e8051b 3204significant change. Many of the macros and functions referred to in this
13d01224
AC
3205section are likely to be subject to further revision. See
3206@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and
3207@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for
3208further information. cagney/2002-05-06.}
3209
3210Some architectures can represent a data object in a register using a
3211form that is different to the objects more normal memory representation.
3212For example:
3213
3214@itemize @bullet
3215
3216@item
3217The Alpha architecture can represent 32 bit integer values in
3218floating-point registers.
3219
3220@item
3221The x86 architecture supports 80-bit floating-point registers. The
3222@code{long double} data type occupies 96 bits in memory but only 80 bits
3223when stored in a register.
3224
3225@end itemize
3226
3227In general, the register representation of a data type is determined by
3228the architecture, or @value{GDBN}'s interface to the architecture, while
3229the memory representation is determined by the Application Binary
3230Interface.
3231
3232For almost all data types on almost all architectures, the two
3233representations are identical, and no special handling is needed.
3234However, they do occasionally differ. Your architecture may define the
3235following macros to request conversions between the register and memory
3236representations of a data type:
3237
4a9bb1df 3238@deftypefun int gdbarch_convert_register_p (struct gdbarch *@var{gdbarch}, int @var{reg})
13d01224
AC
3239Return non-zero if the representation of a data value stored in this
3240register may be different to the representation of that same data value
3241when stored in memory.
3242
4a9bb1df
UW
3243When non-zero, the macros @code{gdbarch_register_to_value} and
3244@code{value_to_register} are used to perform any necessary conversion.
83acabca
DJ
3245
3246This function should return zero for the register's native type, when
3247no conversion is necessary.
4a9bb1df 3248@end deftypefun
13d01224 3249
4a9bb1df 3250@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
3251Convert the value of register number @var{reg} to a data object of type
3252@var{type}. The buffer at @var{from} holds the register's value in raw
3253format; the converted value should be placed in the buffer at @var{to}.
3254
4a9bb1df
UW
3255Note that @code{gdbarch_register_to_value} and @code{gdbarch_value_to_register}
3256take their @var{reg} and @var{type} arguments in different orders.
13d01224 3257
4a9bb1df
UW
3258You should only use @code{gdbarch_register_to_value} with registers for which
3259the @code{gdbarch_convert_register_p} function returns a non-zero value.
3260@end deftypefun
13d01224 3261
4a9bb1df 3262@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
3263Convert a data value of type @var{type} to register number @var{reg}'
3264raw format.
3265
4a9bb1df
UW
3266Note that @code{gdbarch_register_to_value} and @code{gdbarch_value_to_register}
3267take their @var{reg} and @var{type} arguments in different orders.
13d01224 3268
4a9bb1df
UW
3269You should only use @code{gdbarch_value_to_register} with registers for which
3270the @code{gdbarch_convert_register_p} function returns a non-zero value.
3271@end deftypefun
13d01224
AC
3272
3273@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf})
3274See @file{mips-tdep.c}. It does not do what you want.
3275@end deftypefn
3276
b6fd0dfb 3277@node Frame Interpretation
c906108c
SS
3278@section Frame Interpretation
3279
b6fd0dfb 3280@node Inferior Call Setup
c906108c
SS
3281@section Inferior Call Setup
3282
b6fd0dfb 3283@node Compiler Characteristics
c906108c
SS
3284@section Compiler Characteristics
3285
b6fd0dfb 3286@node Target Conditionals
c906108c
SS
3287@section Target Conditionals
3288
4a9bb1df
UW
3289This section describes the macros and functions that you can use to define the
3290target machine.
c906108c
SS
3291
3292@table @code
3293
4a9bb1df
UW
3294@item CORE_ADDR gdbarch_addr_bits_remove (@var{gdbarch}, @var{addr})
3295@findex gdbarch_addr_bits_remove
adf40b2e 3296If a raw machine instruction address includes any bits that are not
4a9bb1df
UW
3297really part of the address, then this function is used to zero those bits in
3298@var{addr}. This is only used for addresses of instructions, and even then not
3299in all contexts.
adf40b2e
JM
3300
3301For example, the two low-order bits of the PC on the Hewlett-Packard PA
33022.0 architecture contain the privilege level of the corresponding
3303instruction. Since instructions must always be aligned on four-byte
3304boundaries, the processor masks out these bits to generate the actual
4a9bb1df
UW
3305address of the instruction. @code{gdbarch_addr_bits_remove} would then for
3306example look like that:
3307@smallexample
3308arch_addr_bits_remove (CORE_ADDR addr)
3309@{
3310 return (addr &= ~0x3);
3311@}
3312@end smallexample
c906108c 3313
4a9bb1df
UW
3314@item int address_class_name_to_type_flags (@var{gdbarch}, @var{name}, @var{type_flags_ptr})
3315@findex address_class_name_to_type_flags
b5b0480a
KB
3316If @var{name} is a valid address class qualifier name, set the @code{int}
3317referenced by @var{type_flags_ptr} to the mask representing the qualifier
3318and return 1. If @var{name} is not a valid address class qualifier name,
3319return 0.
3320
3321The value for @var{type_flags_ptr} should be one of
3322@code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or
3323possibly some combination of these values or'd together.
3324@xref{Target Architecture Definition, , Address Classes}.
3325
4a9bb1df
UW
3326@item int address_class_name_to_type_flags_p (@var{gdbarch})
3327@findex address_class_name_to_type_flags_p
3328Predicate which indicates whether @code{address_class_name_to_type_flags}
b5b0480a
KB
3329has been defined.
3330
4a9bb1df
UW
3331@item int gdbarch_address_class_type_flags (@var{gdbarch}, @var{byte_size}, @var{dwarf2_addr_class})
3332@findex gdbarch_address_class_type_flags
b5b0480a
KB
3333Given a pointers byte size (as described by the debug information) and
3334the possible @code{DW_AT_address_class} value, return the type flags
3335used by @value{GDBN} to represent this address class. The value
3336returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1},
3337@code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these
3338values or'd together.
3339@xref{Target Architecture Definition, , Address Classes}.
3340
4a9bb1df
UW
3341@item int gdbarch_address_class_type_flags_p (@var{gdbarch})
3342@findex gdbarch_address_class_type_flags_p
3343Predicate which indicates whether @code{gdbarch_address_class_type_flags_p} has
b5b0480a
KB
3344been defined.
3345
4a9bb1df
UW
3346@item const char *gdbarch_address_class_type_flags_to_name (@var{gdbarch}, @var{type_flags})
3347@findex gdbarch_address_class_type_flags_to_name
b5b0480a
KB
3348Return the name of the address class qualifier associated with the type
3349flags given by @var{type_flags}.
3350
4a9bb1df
UW
3351@item int gdbarch_address_class_type_flags_to_name_p (@var{gdbarch})
3352@findex gdbarch_address_class_type_flags_to_name_p
3353Predicate which indicates whether @code{gdbarch_address_class_type_flags_to_name} has been defined.
b5b0480a
KB
3354@xref{Target Architecture Definition, , Address Classes}.
3355
4a9bb1df
UW
3356@item void gdbarch_address_to_pointer (@var{gdbarch}, @var{type}, @var{buf}, @var{addr})
3357@findex gdbarch_address_to_pointer
93e79dbd
JB
3358Store in @var{buf} a pointer of type @var{type} representing the address
3359@var{addr}, in the appropriate format for the current architecture.
4a9bb1df 3360This function may safely assume that @var{type} is either a pointer or a
56caf160 3361C@t{++} reference type.
93e79dbd
JB
3362@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
3363
4a9bb1df
UW
3364@item int gdbarch_believe_pcc_promotion (@var{gdbarch})
3365@findex gdbarch_believe_pcc_promotion
3366Used to notify if the compiler promotes a @code{short} or @code{char}
56caf160
EZ
3367parameter to an @code{int}, but still reports the parameter as its
3368original type, rather than the promoted type.
c906108c 3369
32c9a795
MD
3370@item gdbarch_bits_big_endian (@var{gdbarch})
3371@findex gdbarch_bits_big_endian
3372This is used if the numbering of bits in the targets does @strong{not} match
3373the endianness of the target byte order. A value of 1 means that the bits
56caf160 3374are numbered in a big-endian bit order, 0 means little-endian.
c906108c 3375
32c9a795
MD
3376@item set_gdbarch_bits_big_endian (@var{gdbarch}, @var{bits_big_endian})
3377@findex set_gdbarch_bits_big_endian
3378Calling set_gdbarch_bits_big_endian with a value of 1 indicates that the
3379bits in the target are numbered in a big-endian bit order, 0 indicates
3380little-endian.
3381
c906108c 3382@item BREAKPOINT
56caf160 3383@findex BREAKPOINT
c906108c
SS
3384This is the character array initializer for the bit pattern to put into
3385memory where a breakpoint is set. Although it's common to use a trap
3386instruction for a breakpoint, it's not required; for instance, the bit
3387pattern could be an invalid instruction. The breakpoint must be no
3388longer than the shortest instruction of the architecture.
3389
56caf160 3390@code{BREAKPOINT} has been deprecated in favor of
4a9bb1df 3391@code{gdbarch_breakpoint_from_pc}.
7a292a7a 3392
c906108c 3393@item BIG_BREAKPOINT
56caf160
EZ
3394@itemx LITTLE_BREAKPOINT
3395@findex LITTLE_BREAKPOINT
3396@findex BIG_BREAKPOINT
c906108c
SS
3397Similar to BREAKPOINT, but used for bi-endian targets.
3398
56caf160 3399@code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
4a9bb1df 3400favor of @code{gdbarch_breakpoint_from_pc}.
7a292a7a 3401
4a9bb1df
UW
3402@item const gdb_byte *gdbarch_breakpoint_from_pc (@var{gdbarch}, @var{pcptr}, @var{lenptr})
3403@findex gdbarch_breakpoint_from_pc
3404@anchor{gdbarch_breakpoint_from_pc} Use the program counter to determine the
2dd0da42
AC
3405contents and size of a breakpoint instruction. It returns a pointer to
3406a string of bytes that encode a breakpoint instruction, stores the
3407length of the string to @code{*@var{lenptr}}, and adjusts the program
3408counter (if necessary) to point to the actual memory location where the
3409breakpoint should be inserted.
c906108c
SS
3410
3411Although it is common to use a trap instruction for a breakpoint, it's
3412not required; for instance, the bit pattern could be an invalid
3413instruction. The breakpoint must be no longer than the shortest
3414instruction of the architecture.
3415
7a292a7a
SS
3416Replaces all the other @var{BREAKPOINT} macros.
3417
4a9bb1df
UW
3418@item int gdbarch_memory_insert_breakpoint (@var{gdbarch}, @var{bp_tgt})
3419@itemx gdbarch_memory_remove_breakpoint (@var{gdbarch}, @var{bp_tgt})
3420@findex gdbarch_memory_remove_breakpoint
3421@findex gdbarch_memory_insert_breakpoint
917317f4
JM
3422Insert or remove memory based breakpoints. Reasonable defaults
3423(@code{default_memory_insert_breakpoint} and
3424@code{default_memory_remove_breakpoint} respectively) have been
4a9bb1df
UW
3425provided so that it is not necessary to set these for most
3426architectures. Architectures which may want to set
3427@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
3428conventional manner.
3429
3430It may also be desirable (from an efficiency standpoint) to define
3431custom breakpoint insertion and removal routines if
4a9bb1df 3432@code{gdbarch_breakpoint_from_pc} needs to read the target's memory for some
917317f4
JM
3433reason.
3434
4a9bb1df
UW
3435@item CORE_ADDR gdbarch_adjust_breakpoint_address (@var{gdbarch}, @var{bpaddr})
3436@findex gdbarch_adjust_breakpoint_address
1485d690
KB
3437@cindex breakpoint address adjusted
3438Given an address at which a breakpoint is desired, return a breakpoint
3439address adjusted to account for architectural constraints on
3440breakpoint placement. This method is not needed by most targets.
3441
3442The FR-V target (see @file{frv-tdep.c}) requires this method.
3443The FR-V is a VLIW architecture in which a number of RISC-like
3444instructions are grouped (packed) together into an aggregate
3445instruction or instruction bundle. When the processor executes
3446one of these bundles, the component instructions are executed
3447in parallel.
3448
3449In the course of optimization, the compiler may group instructions
3450from distinct source statements into the same bundle. The line number
3451information associated with one of the latter statements will likely
3452refer to some instruction other than the first one in the bundle. So,
3453if the user attempts to place a breakpoint on one of these latter
3454statements, @value{GDBN} must be careful to @emph{not} place the break
3455instruction on any instruction other than the first one in the bundle.
3456(Remember though that the instructions within a bundle execute
3457in parallel, so the @emph{first} instruction is the instruction
3458at the lowest address and has nothing to do with execution order.)
3459
4a9bb1df 3460The FR-V's @code{gdbarch_adjust_breakpoint_address} method will adjust a
1485d690
KB
3461breakpoint's address by scanning backwards for the beginning of
3462the bundle, returning the address of the bundle.
3463
3464Since the adjustment of a breakpoint may significantly alter a user's
3465expectation, @value{GDBN} prints a warning when an adjusted breakpoint
3466is initially set and each time that that breakpoint is hit.
3467
4a9bb1df
UW
3468@item int gdbarch_call_dummy_location (@var{gdbarch})
3469@findex gdbarch_call_dummy_location
56caf160 3470See the file @file{inferior.h}.
7a292a7a 3471
4a9bb1df
UW
3472This method has been replaced by @code{gdbarch_push_dummy_code}
3473(@pxref{gdbarch_push_dummy_code}).
7043d8dc 3474
4a9bb1df
UW
3475@item int gdbarch_cannot_fetch_register (@var{gdbarch}, @var{regum})
3476@findex gdbarch_cannot_fetch_register
3477This function should return nonzero if @var{regno} cannot be fetched
c906108c
SS
3478from an inferior process. This is only relevant if
3479@code{FETCH_INFERIOR_REGISTERS} is not defined.
3480
4a9bb1df
UW
3481@item int gdbarch_cannot_store_register (@var{gdbarch}, @var{regnum})
3482@findex gdbarch_cannot_store_register
3483This function should return nonzero if @var{regno} should not be
c906108c 3484written to the target. This is often the case for program counters,
4a9bb1df
UW
3485status words, and other special registers. This function returns 0 as
3486default so that @value{GDBN} will assume that all registers may be written.
c906108c 3487
4a9bb1df
UW
3488@item int gdbarch_convert_register_p (@var{gdbarch}, @var{regnum}, struct type *@var{type})
3489@findex gdbarch_convert_register_p
83acabca
DJ
3490Return non-zero if register @var{regnum} represents data values of type
3491@var{type} in a non-standard form.
13d01224
AC
3492@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3493
4a9bb1df
UW
3494@item CORE_ADDR gdbarch_decr_pc_after_break (@var{gdbarch})
3495@findex gdbarch_decr_pc_after_break
3496This function shall return the amount by which to decrement the PC after the
c906108c 3497program encounters a breakpoint. This is often the number of bytes in
56caf160 3498@code{BREAKPOINT}, though not always. For most targets this value will be 0.
c906108c 3499
56caf160
EZ
3500@item DISABLE_UNSETTABLE_BREAK (@var{addr})
3501@findex DISABLE_UNSETTABLE_BREAK
c906108c
SS
3502If defined, this should evaluate to 1 if @var{addr} is in a shared
3503library in which breakpoints cannot be set and so should be disabled.
3504
5fc14d0a 3505@item void gdbarch_print_float_info (@var{gdbarch}, @var{file}, @var{frame}, @var{args})
4a9bb1df 3506@findex gdbarch_print_float_info
5e74b15c
RE
3507If defined, then the @samp{info float} command will print information about
3508the processor's floating point unit.
3509
4a9bb1df
UW
3510@item void gdbarch_print_registers_info (@var{gdbarch}, @var{frame}, @var{regnum}, @var{all})
3511@findex gdbarch_print_registers_info
0ab7a791
AC
3512If defined, pretty print the value of the register @var{regnum} for the
3513specified @var{frame}. If the value of @var{regnum} is -1, pretty print
3514either all registers (@var{all} is non zero) or a select subset of
3515registers (@var{all} is zero).
3516
3517The default method prints one register per line, and if @var{all} is
3518zero omits floating-point registers.
3519
4a9bb1df
UW
3520@item int gdbarch_print_vector_info (@var{gdbarch}, @var{file}, @var{frame}, @var{args})
3521@findex gdbarch_print_vector_info
e76f1f2e
AC
3522If defined, then the @samp{info vector} command will call this function
3523to print information about the processor's vector unit.
3524
3525By default, the @samp{info vector} command will print all vector
3526registers (the register's type having the vector attribute).
3527
4a9bb1df
UW
3528@item int gdbarch_dwarf_reg_to_regnum (@var{gdbarch}, @var{dwarf_regnr})
3529@findex gdbarch_dwarf_reg_to_regnum
3530Convert DWARF register number @var{dwarf_regnr} into @value{GDBN} regnum. If
3531not defined, no conversion will be performed.
0dcedd82 3532
4a9bb1df
UW
3533@item int gdbarch_dwarf2_reg_to_regnum (@var{gdbarch}, @var{dwarf2_regnr})
3534@findex gdbarch_dwarf2_reg_to_regnum
3535Convert DWARF2 register number @var{dwarf2_regnr} into @value{GDBN} regnum.
3536If not defined, no conversion will be performed.
0dcedd82 3537
4a9bb1df
UW
3538@item int gdbarch_ecoff_reg_to_regnum (@var{gdbarch}, @var{ecoff_regnr})
3539@findex gdbarch_ecoff_reg_to_regnum
3540Convert ECOFF register number @var{ecoff_regnr} into @value{GDBN} regnum. If
3541not defined, no conversion will be performed.
c906108c 3542
0ba6dca9
AC
3543@item DEPRECATED_FP_REGNUM
3544@findex DEPRECATED_FP_REGNUM
cce74817
JM
3545If the virtual frame pointer is kept in a register, then define this
3546macro to be the number (greater than or equal to zero) of that register.
3547
0ba6dca9
AC
3548This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP}
3549is not defined.
c906108c 3550
19772a2c
AC
3551@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi})
3552@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION
392a587b
JM
3553Define this to an expression that returns 1 if the function invocation
3554represented by @var{fi} does not have a stack frame associated with it.
3555Otherwise return 0.
c906108c 3556
4a9bb1df 3557@item CORE_ADDR frame_align (@var{gdbarch}, @var{address})
790eb8f5
AC
3558@anchor{frame_align}
3559@findex frame_align
3560Define this to adjust @var{address} so that it meets the alignment
3561requirements for the start of a new stack frame. A stack frame's
3562alignment requirements are typically stronger than a target processors
5fc14d0a 3563stack alignment requirements.
790eb8f5
AC
3564
3565This function is used to ensure that, when creating a dummy frame, both
3566the initial stack pointer and (if needed) the address of the return
3567value are correctly aligned.
3568
5fc14d0a
EZ
3569This function always adjusts the address in the direction of stack
3570growth.
790eb8f5
AC
3571
3572By default, no frame based stack alignment is performed.
3573
4a9bb1df
UW
3574@item int gdbarch_frame_red_zone_size (@var{gdbarch})
3575@findex gdbarch_frame_red_zone_size
8b148df9
AC
3576The number of bytes, beyond the innermost-stack-address, reserved by the
3577@sc{abi}. A function is permitted to use this scratch area (instead of
3578allocating extra stack space).
3579
3580When performing an inferior function call, to ensure that it does not
3581modify this area, @value{GDBN} adjusts the innermost-stack-address by
4a9bb1df 3582@var{gdbarch_frame_red_zone_size} bytes before pushing parameters onto the
8b148df9
AC
3583stack.
3584
3585By default, zero bytes are allocated. The value must be aligned
3586(@pxref{frame_align}).
3587
3588The @sc{amd64} (nee x86-64) @sc{abi} documentation refers to the
3589@emph{red zone} when describing this scratch area.
3590@cindex red zone
3591
618ce49f
AC
3592@item DEPRECATED_FRAME_CHAIN(@var{frame})
3593@findex DEPRECATED_FRAME_CHAIN
c906108c
SS
3594Given @var{frame}, return a pointer to the calling frame.
3595
618ce49f
AC
3596@item DEPRECATED_FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
3597@findex DEPRECATED_FRAME_CHAIN_VALID
95f90d25
DJ
3598Define this to be an expression that returns zero if the given frame is an
3599outermost frame, with no caller, and nonzero otherwise. Most normal
3600situations can be handled without defining this macro, including @code{NULL}
3601chain pointers, dummy frames, and frames whose PC values are inside the
3602startup file (e.g.@: @file{crt0.o}), inside @code{main}, or inside
3603@code{_start}.
c906108c 3604
f30ee0bc
AC
3605@item DEPRECATED_FRAME_INIT_SAVED_REGS(@var{frame})
3606@findex DEPRECATED_FRAME_INIT_SAVED_REGS
c906108c
SS
3607See @file{frame.h}. Determines the address of all registers in the
3608current stack frame storing each in @code{frame->saved_regs}. Space for
3609@code{frame->saved_regs} shall be allocated by
f30ee0bc
AC
3610@code{DEPRECATED_FRAME_INIT_SAVED_REGS} using
3611@code{frame_saved_regs_zalloc}.
c906108c 3612
fb8f8949 3613@code{FRAME_FIND_SAVED_REGS} is deprecated.
c906108c 3614
4a9bb1df
UW
3615@item int gdbarch_frame_num_args (@var{gdbarch}, @var{frame})
3616@findex gdbarch_frame_num_args
3617For the frame described by @var{frame} return the number of arguments that
392a587b
JM
3618are being passed. If the number of arguments is not known, return
3619@code{-1}.
c906108c 3620
8bedc050
AC
3621@item DEPRECATED_FRAME_SAVED_PC(@var{frame})
3622@findex DEPRECATED_FRAME_SAVED_PC
3623@anchor{DEPRECATED_FRAME_SAVED_PC} Given @var{frame}, return the pc
3624saved there. This is the return address.
12cc2063 3625
4a9bb1df 3626This method is deprecated. @xref{gdbarch_unwind_pc}.
12cc2063 3627
4a9bb1df
UW
3628@item CORE_ADDR gdbarch_unwind_pc (@var{next_frame})
3629@findex gdbarch_unwind_pc
3630@anchor{gdbarch_unwind_pc} Return the instruction address, in
3631@var{next_frame}'s caller, at which execution will resume after
3632@var{next_frame} returns. This is commonly referred to as the return address.
12cc2063
AC
3633
3634The implementation, which must be frame agnostic (work with any frame),
3635is typically no more than:
3636
3637@smallexample
3638ULONGEST pc;
11411de3 3639pc = frame_unwind_register_unsigned (next_frame, S390_PC_REGNUM);
4a9bb1df 3640return gdbarch_addr_bits_remove (gdbarch, pc);
12cc2063
AC
3641@end smallexample
3642
3643@noindent
8bedc050 3644@xref{DEPRECATED_FRAME_SAVED_PC}, which this method replaces.
c906108c 3645
4a9bb1df
UW
3646@item CORE_ADDR gdbarch_unwind_sp (@var{gdbarch}, @var{next_frame})
3647@findex gdbarch_unwind_sp
3648@anchor{gdbarch_unwind_sp} Return the frame's inner most stack address. This is
d3e8051b 3649commonly referred to as the frame's @dfn{stack pointer}.
a9e5fdc2
AC
3650
3651The implementation, which must be frame agnostic (work with any frame),
3652is typically no more than:
3653
3654@smallexample
3655ULONGEST sp;
11411de3 3656sp = frame_unwind_register_unsigned (next_frame, S390_SP_REGNUM);
4a9bb1df 3657return gdbarch_addr_bits_remove (gdbarch, sp);
a9e5fdc2
AC
3658@end smallexample
3659
3660@noindent
3661@xref{TARGET_READ_SP}, which this method replaces.
3662
c906108c 3663@item FUNCTION_EPILOGUE_SIZE
56caf160 3664@findex FUNCTION_EPILOGUE_SIZE
c906108c
SS
3665For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
3666function end symbol is 0. For such targets, you must define
3667@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
3668function's epilogue.
3669
782263ab
AC
3670@item DEPRECATED_FUNCTION_START_OFFSET
3671@findex DEPRECATED_FUNCTION_START_OFFSET
f7cb2b90
JB
3672An integer, giving the offset in bytes from a function's address (as
3673used in the values of symbols, function pointers, etc.), and the
3674function's first genuine instruction.
3675
3676This is zero on almost all machines: the function's address is usually
782263ab
AC
3677the address of its first instruction. However, on the VAX, for
3678example, each function starts with two bytes containing a bitmask
3679indicating which registers to save upon entry to the function. The
3680VAX @code{call} instructions check this value, and save the
3681appropriate registers automatically. Thus, since the offset from the
3682function's address to its first instruction is two bytes,
3683@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
f7cb2b90 3684
c906108c 3685@item GCC_COMPILED_FLAG_SYMBOL
56caf160
EZ
3686@itemx GCC2_COMPILED_FLAG_SYMBOL
3687@findex GCC2_COMPILED_FLAG_SYMBOL
3688@findex GCC_COMPILED_FLAG_SYMBOL
3689If defined, these are the names of the symbols that @value{GDBN} will
3690look for to detect that GCC compiled the file. The default symbols
3691are @code{gcc_compiled.} and @code{gcc2_compiled.},
3692respectively. (Currently only defined for the Delta 68.)
c906108c 3693
4a9bb1df
UW
3694@item gdbarch_get_longjmp_target
3695@findex gdbarch_get_longjmp_target
c906108c
SS
3696For most machines, this is a target-dependent parameter. On the
3697DECstation and the Iris, this is a native-dependent parameter, since
937f164b 3698the header file @file{setjmp.h} is needed to define it.
c906108c 3699
56caf160
EZ
3700This macro determines the target PC address that @code{longjmp} will jump to,
3701assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
3702@code{CORE_ADDR *} as argument, and stores the target PC value through this
c906108c
SS
3703pointer. It examines the current state of the machine as needed.
3704
268e2188
AC
3705@item DEPRECATED_IBM6000_TARGET
3706@findex DEPRECATED_IBM6000_TARGET
3707Shows that we are configured for an IBM RS/6000 system. This
c906108c 3708conditional should be eliminated (FIXME) and replaced by
56caf160 3709feature-specific macros. It was introduced in a haste and we are
c906108c
SS
3710repenting at leisure.
3711
9742079a
EZ
3712@item I386_USE_GENERIC_WATCHPOINTS
3713An x86-based target can define this to use the generic x86 watchpoint
3714support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
3715
4a9bb1df
UW
3716@item int gdbarch_inner_than (@var{gdbarch}, @var{lhs}, @var{rhs})
3717@findex gdbarch_inner_than
c906108c 3718Returns non-zero if stack address @var{lhs} is inner than (nearer to the
4a9bb1df
UW
3719stack top) stack address @var{rhs}. Let the function return
3720@w{@code{lhs < rhs}} if the target's stack grows downward in memory, or
3721@w{@code{lhs > rsh}} if the stack grows upward.
c906108c 3722
4a9bb1df 3723@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{addr})
9e5abb06 3724@findex gdbarch_in_function_epilogue_p
4a9bb1df 3725Returns non-zero if the given @var{addr} is in the epilogue of a function.
9e5abb06
CV
3726The epilogue of a function is defined as the part of a function where
3727the stack frame of the function already has been destroyed up to the
3728final `return from function call' instruction.
3729
4a9bb1df
UW
3730@item int gdbarch_in_solib_return_trampoline (@var{gdbarch}, @var{pc}, @var{name})
3731@findex gdbarch_in_solib_return_trampoline
3732Define this function to return nonzero if the program is stopped in the
c906108c
SS
3733trampoline that returns from a shared library.
3734
56caf160
EZ
3735@item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc})
3736@findex IN_SOLIB_DYNSYM_RESOLVE_CODE
4a9bb1df 3737Define this to return nonzero if the program is stopped in the
d4f3574e
SS
3738dynamic linker.
3739
56caf160
EZ
3740@item SKIP_SOLIB_RESOLVER (@var{pc})
3741@findex SKIP_SOLIB_RESOLVER
d4f3574e
SS
3742Define this to evaluate to the (nonzero) address at which execution
3743should continue to get past the dynamic linker's symbol resolution
3744function. A zero value indicates that it is not important or necessary
3745to set a breakpoint to get through the dynamic linker and that single
3746stepping will suffice.
3747
4a9bb1df
UW
3748@item CORE_ADDR gdbarch_integer_to_address (@var{gdbarch}, @var{type}, @var{buf})
3749@findex gdbarch_integer_to_address
fc0c74b1
AC
3750@cindex converting integers to addresses
3751Define this when the architecture needs to handle non-pointer to address
3752conversions specially. Converts that value to an address according to
3753the current architectures conventions.
3754
3755@emph{Pragmatics: When the user copies a well defined expression from
3756their source code and passes it, as a parameter, to @value{GDBN}'s
3757@code{print} command, they should get the same value as would have been
3758computed by the target program. Any deviation from this rule can cause
3759major confusion and annoyance, and needs to be justified carefully. In
3760other words, @value{GDBN} doesn't really have the freedom to do these
3761conversions in clever and useful ways. It has, however, been pointed
3762out that users aren't complaining about how @value{GDBN} casts integers
3763to pointers; they are complaining that they can't take an address from a
3764disassembly listing and give it to @code{x/i}. Adding an architecture
4a9bb1df 3765method like @code{gdbarch_integer_to_address} certainly makes it possible for
fc0c74b1
AC
3766@value{GDBN} to ``get it right'' in all circumstances.}
3767
3768@xref{Target Architecture Definition, , Pointers Are Not Always
3769Addresses}.
3770
4a9bb1df
UW
3771@item CORE_ADDR gdbarch_pointer_to_address (@var{gdbarch}, @var{type}, @var{buf})
3772@findex gdbarch_pointer_to_address
93e79dbd
JB
3773Assume that @var{buf} holds a pointer of type @var{type}, in the
3774appropriate format for the current architecture. Return the byte
3775address the pointer refers to.
3776@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
3777
4a9bb1df
UW
3778@item void gdbarch_register_to_value(@var{gdbarch}, @var{frame}, @var{regnum}, @var{type}, @var{fur})
3779@findex gdbarch_register_to_value
13d01224
AC
3780Convert the raw contents of register @var{regnum} into a value of type
3781@var{type}.
4281a42e 3782@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
9fb4dd36 3783
617073a9
AC
3784@item register_reggroup_p (@var{gdbarch}, @var{regnum}, @var{reggroup})
3785@findex register_reggroup_p
3786@cindex register groups
3787Return non-zero if register @var{regnum} is a member of the register
3788group @var{reggroup}.
3789
3790By default, registers are grouped as follows:
3791
3792@table @code
3793@item float_reggroup
3794Any register with a valid name and a floating-point type.
3795@item vector_reggroup
3796Any register with a valid name and a vector type.
3797@item general_reggroup
3798Any register with a valid name and a type other than vector or
3799floating-point. @samp{float_reggroup}.
3800@item save_reggroup
3801@itemx restore_reggroup
3802@itemx all_reggroup
3803Any register with a valid name.
3804@end table
3805
f30992d4
AC
3806@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg})
3807@findex DEPRECATED_REGISTER_VIRTUAL_SIZE
b2e75d78
AC
3808Return the virtual size of @var{reg}; defaults to the size of the
3809register's virtual type.
13d01224
AC
3810Return the virtual size of @var{reg}.
3811@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36 3812
2e092625 3813@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})
56caf160 3814@findex REGISTER_VIRTUAL_TYPE
9fb4dd36 3815Return the virtual type of @var{reg}.
13d01224 3816@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36 3817
77e7e267
AC
3818@item struct type *register_type (@var{gdbarch}, @var{reg})
3819@findex register_type
3820If defined, return the type of register @var{reg}. This function
d3e8051b 3821supersedes @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture
77e7e267
AC
3822Definition, , Raw and Virtual Register Representations}.
3823
9fb4dd36 3824@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
56caf160 3825@findex REGISTER_CONVERT_TO_VIRTUAL
9fb4dd36 3826Convert the value of register @var{reg} from its raw form to its virtual
4281a42e 3827form.
13d01224 3828@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36
JB
3829
3830@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
56caf160 3831@findex REGISTER_CONVERT_TO_RAW
9fb4dd36 3832Convert the value of register @var{reg} from its virtual form to its raw
4281a42e 3833form.
13d01224 3834@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
9fb4dd36 3835
0ab4b752
MK
3836@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size})
3837@findex regset_from_core_section
3838Return the appropriate register set for a core file section with name
3839@var{sect_name} and size @var{sect_size}.
3840
b0ed3589 3841@item SOFTWARE_SINGLE_STEP_P()
56caf160 3842@findex SOFTWARE_SINGLE_STEP_P
c906108c 3843Define this as 1 if the target does not have a hardware single-step
56caf160 3844mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
c906108c 3845
d3e8051b 3846@item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breakpoints_p})
56caf160
EZ
3847@findex SOFTWARE_SINGLE_STEP
3848A function that inserts or removes (depending on
d3e8051b 3849@var{insert_breakpoints_p}) breakpoints at each possible destinations of
56caf160 3850the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
c906108c
SS
3851for examples.
3852
e35879db
UW
3853@item set_gdbarch_sofun_address_maybe_missing (@var{gdbarch}, @var{set})
3854@findex set_gdbarch_sofun_address_maybe_missing
3855Somebody clever observed that, the more actual addresses you have in the
3856debug information, the more time the linker has to spend relocating
3857them. So whenever there's some other way the debugger could find the
3858address it needs, you should omit it from the debug info, to make
3859linking faster.
3860
3861Calling @code{set_gdbarch_sofun_address_maybe_missing} with a non-zero
3862argument @var{set} indicates that a particular set of hacks of this sort
3863are in use, affecting @code{N_SO} and @code{N_FUN} entries in stabs-format
3864debugging information. @code{N_SO} stabs mark the beginning and ending
3865addresses of compilation units in the text segment. @code{N_FUN} stabs
3866mark the starts and ends of functions.
3867
3868In this case, @value{GDBN} assumes two things:
3869
3870@itemize @bullet
3871@item
3872@code{N_FUN} stabs have an address of zero. Instead of using those
3873addresses, you should find the address where the function starts by
3874taking the function name from the stab, and then looking that up in the
3875minsyms (the linker/assembler symbol table). In other words, the stab
3876has the name, and the linker/assembler symbol table is the only place
3877that carries the address.
3878
3879@item
3880@code{N_SO} stabs have an address of zero, too. You just look at the
3881@code{N_FUN} stabs that appear before and after the @code{N_SO} stab, and
3882guess the starting and ending addresses of the compilation unit from them.
3883@end itemize
3884
4a9bb1df
UW
3885@item int gdbarch_pc_regnum (@var{gdbarch})
3886@findex gdbarch_pc_regnum
3887If the program counter is kept in a register, then let this function return
3888the number (greater than or equal to zero) of that register.
c906108c 3889
4a9bb1df
UW
3890This should only need to be defined if @code{gdbarch_read_pc} and
3891@code{gdbarch_write_pc} are not defined.
2df3850c 3892
4a9bb1df
UW
3893@item int gdbarch_stabs_argument_has_addr (@var{gdbarch}, @var{type})
3894@findex gdbarch_stabs_argument_has_addr
4a9bb1df
UW
3895@anchor{gdbarch_stabs_argument_has_addr} Define this function to return
3896nonzero if a function argument of type @var{type} is passed by reference
3897instead of value.
a38c9fe6 3898
c906108c 3899@item PROCESS_LINENUMBER_HOOK
56caf160 3900@findex PROCESS_LINENUMBER_HOOK
c906108c
SS
3901A hook defined for XCOFF reading.
3902
4a9bb1df
UW
3903@item gdbarch_ps_regnum (@var{gdbarch}
3904@findex gdbarch_ps_regnum
3905If defined, this function returns the number of the processor status
3906register.
3907(This definition is only used in generic code when parsing "$ps".)
c906108c 3908
4a9bb1df
UW
3909@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})
3910@findex gdbarch_push_dummy_call
b81774d8 3911@findex DEPRECATED_PUSH_ARGUMENTS.
4a9bb1df
UW
3912@anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to
3913the inferior function onto the stack. In addition to pushing @var{nargs}, the
3914code should push @var{struct_addr} (when @var{struct_return} is non-zero), and
3915the return address (@var{bp_addr}).
c906108c 3916
86fe4aaa 3917@var{function} is a pointer to a @code{struct value}; on architectures that use
d4b6d575
RC
3918function descriptors, this contains the function descriptor value.
3919
b24da7d0 3920Returns the updated top-of-stack pointer.
b81774d8
AC
3921
3922This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
3923
4a9bb1df
UW
3924@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})
3925@findex gdbarch_push_dummy_code
3926@anchor{gdbarch_push_dummy_code} Given a stack based call dummy, push the
7043d8dc
AC
3927instruction sequence (including space for a breakpoint) to which the
3928called function should return.
3929
3930Set @var{bp_addr} to the address at which the breakpoint instruction
3931should be inserted, @var{real_pc} to the resume address when starting
3932the call sequence, and return the updated inner-most stack address.
3933
3934By default, the stack is grown sufficient to hold a frame-aligned
3935(@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address
3936reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}.
3937
4a9bb1df 3938This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}} and
28954179 3939@code{DEPRECATED_REGISTER_SIZE}.
7043d8dc 3940
4a9bb1df
UW
3941@item const char *gdbarch_register_name (@var{gdbarch}, @var{regnr})
3942@findex gdbarch_register_name
3943Return the name of register @var{regnr} as a string. May return @code{NULL}
3944to indicate that @var{regnr} is not a valid register.
c906108c 3945
b24da7d0
AC
3946@item SAVE_DUMMY_FRAME_TOS (@var{sp})
3947@findex SAVE_DUMMY_FRAME_TOS
3948@anchor{SAVE_DUMMY_FRAME_TOS} Used in @samp{call_function_by_hand} to
3949notify the target dependent code of the top-of-stack value that will be
d3e8051b 3950passed to the inferior code. This is the value of the @code{SP}
b24da7d0 3951after both the dummy frame and space for parameters/results have been
4a9bb1df 3952allocated on the stack. @xref{gdbarch_unwind_dummy_id}.
43ff13b4 3953
4a9bb1df
UW
3954@item int gdbarch_sdb_reg_to_regnum (@var{gdbarch}, @var{sdb_regnr})
3955@findex gdbarch_sdb_reg_to_regnum
3956Use this function to convert sdb register @var{sdb_regnr} into @value{GDBN}
3957regnum. If not defined, no conversion will be done.
c906108c 3958
963e2bb7 3959@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
3960@findex gdbarch_return_value
3961@anchor{gdbarch_return_value} Given a function with a return-value of
3962type @var{rettype}, return which return-value convention that function
3963would use.
3964
3965@value{GDBN} currently recognizes two function return-value conventions:
3966@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found
3967in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return
3968value is found in memory and the address of that memory location is
3969passed in as the function's first parameter.
3970
963e2bb7
AC
3971If the register convention is being used, and @var{writebuf} is
3972non-@code{NULL}, also copy the return-value in @var{writebuf} into
92ad9cd9
AC
3973@var{regcache}.
3974
963e2bb7 3975If the register convention is being used, and @var{readbuf} is
92ad9cd9 3976non-@code{NULL}, also copy the return value from @var{regcache} into
963e2bb7 3977@var{readbuf} (@var{regcache} contains a copy of the registers from the
92ad9cd9
AC
3978just returned function).
3979
92ad9cd9
AC
3980@emph{Maintainer note: This method replaces separate predicate, extract,
3981store methods. By having only one method, the logic needed to determine
3982the return-value convention need only be implemented in one place. If
3983@value{GDBN} were written in an @sc{oo} language, this method would
3984instead return an object that knew how to perform the register
3985return-value extract and store.}
3986
3987@emph{Maintainer note: This method does not take a @var{gcc_p}
3988parameter, and such a parameter should not be added. If an architecture
3989that requires per-compiler or per-function information be identified,
3990then the replacement of @var{rettype} with @code{struct value}
d3e8051b 3991@var{function} should be pursued.}
92ad9cd9
AC
3992
3993@emph{Maintainer note: The @var{regcache} parameter limits this methods
3994to the inner most frame. While replacing @var{regcache} with a
3995@code{struct frame_info} @var{frame} parameter would remove that
3996limitation there has yet to be a demonstrated need for such a change.}
3997
4a9bb1df
UW
3998@item void gdbarch_skip_permanent_breakpoint (@var{gdbarch}, @var{regcache})
3999@findex gdbarch_skip_permanent_breakpoint
25822942 4000Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
c2c6d25f
JM
4001steps over a breakpoint by removing it, stepping one instruction, and
4002re-inserting the breakpoint. However, permanent breakpoints are
4003hardwired into the inferior, and can't be removed, so this strategy
4a9bb1df
UW
4004doesn't work. Calling @code{gdbarch_skip_permanent_breakpoint} adjusts the
4005processor's state so that execution will resume just after the breakpoint.
4006This function does the right thing even when the breakpoint is in the delay slot
c2c6d25f
JM
4007of a branch or jump.
4008
4a9bb1df
UW
4009@item CORE_ADDR gdbarch_skip_prologue (@var{gdbarch}, @var{ip})
4010@findex gdbarch_skip_prologue
4011A function that returns the address of the ``real'' code beyond the
4012function entry prologue found at @var{ip}.
c906108c 4013
4a9bb1df
UW
4014@item CORE_ADDR gdbarch_skip_trampoline_code (@var{gdbarch}, @var{frame}, @var{pc})
4015@findex gdbarch_skip_trampoline_code
c906108c 4016If the target machine has trampoline code that sits between callers and
4a9bb1df 4017the functions being called, then define this function to return a new PC
c906108c
SS
4018that is at the start of the real function.
4019
4a9bb1df
UW
4020@item int gdbarch_sp_regnum (@var{gdbarch})
4021@findex gdbarch_sp_regnum
4022If the stack-pointer is kept in a register, then use this function to return
6c0e89ed
AC
4023the number (greater than or equal to zero) of that register, or -1 if
4024there is no such register.
c906108c 4025
4a9bb1df
UW
4026@item int gdbarch_stab_reg_to_regnum (@var{gdbarch}, @var{stab_regnr})
4027@findex gdbarch_stab_reg_to_regnum
4028Use this function to convert stab register @var{stab_regnr} into @value{GDBN}
4029regnum. If not defined, no conversion will be done.
4030
c906108c 4031@item SYMBOL_RELOADING_DEFAULT
56caf160
EZ
4032@findex SYMBOL_RELOADING_DEFAULT
4033The default value of the ``symbol-reloading'' variable. (Never defined in
c906108c
SS
4034current sources.)
4035
c906108c 4036@item TARGET_CHAR_BIT
56caf160 4037@findex TARGET_CHAR_BIT
c906108c
SS
4038Number of bits in a char; defaults to 8.
4039
4a9bb1df
UW
4040@item int gdbarch_char_signed (@var{gdbarch})
4041@findex gdbarch_char_signed
c3d3ce5b
JB
4042Non-zero if @code{char} is normally signed on this architecture; zero if
4043it should be unsigned.
4044
4045The ISO C standard requires the compiler to treat @code{char} as
4046equivalent to either @code{signed char} or @code{unsigned char}; any
4047character in the standard execution set is supposed to be positive.
4048Most compilers treat @code{char} as signed, but @code{char} is unsigned
4049on the IBM S/390, RS6000, and PowerPC targets.
4050
4a9bb1df
UW
4051@item int gdbarch_double_bit (@var{gdbarch})
4052@findex gdbarch_double_bit
4053Number of bits in a double float; defaults to @w{@code{8 * TARGET_CHAR_BIT}}.
c906108c 4054
4a9bb1df
UW
4055@item int gdbarch_float_bit (@var{gdbarch})
4056@findex gdbarch_float_bit
4057Number of bits in a float; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.
ac9a91a7 4058
4a9bb1df
UW
4059@item int gdbarch_int_bit (@var{gdbarch})
4060@findex gdbarch_int_bit
4061Number of bits in an integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.
c906108c 4062
4a9bb1df
UW
4063@item int gdbarch_long_bit (@var{gdbarch})
4064@findex gdbarch_long_bit
4065Number of bits in a long integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.
c906108c 4066
4a9bb1df
UW
4067@item int gdbarch_long_double_bit (@var{gdbarch})
4068@findex gdbarch_long_double_bit
c906108c 4069Number of bits in a long double float;
4a9bb1df
UW
4070defaults to @w{@code{2 * gdbarch_double_bit (@var{gdbarch})}}.
4071
4072@item int gdbarch_long_long_bit (@var{gdbarch})
4073@findex gdbarch_long_long_bit
4074Number of bits in a long long integer; defaults to
4075@w{@code{2 * gdbarch_long_bit (@var{gdbarch})}}.
4076
4077@item int gdbarch_ptr_bit (@var{gdbarch})
4078@findex gdbarch_ptr_bit
4079Number of bits in a pointer; defaults to
4080@w{@code{gdbarch_int_bit (@var{gdbarch})}}.
4081
4082@item int gdbarch_short_bit (@var{gdbarch})
4083@findex gdbarch_short_bit
4084Number of bits in a short integer; defaults to @w{@code{2 * TARGET_CHAR_BIT}}.
4085
4086@item CORE_ADDR gdbarch_read_pc (@var{gdbarch}, @var{regcache})
4087@findex gdbarch_read_pc
4088@itemx gdbarch_write_pc (@var{gdbarch}, @var{regcache}, @var{val})
4089@findex gdbarch_write_pc
4090@anchor{gdbarch_write_pc}
56caf160
EZ
4091@itemx TARGET_READ_SP
4092@findex TARGET_READ_SP
56caf160
EZ
4093@itemx TARGET_READ_FP
4094@findex TARGET_READ_FP
4a9bb1df
UW
4095@findex gdbarch_read_pc
4096@findex gdbarch_write_pc
56caf160 4097@findex read_sp
56caf160 4098@findex read_fp
4a9bb1df
UW
4099@anchor{TARGET_READ_SP} These change the behavior of @code{gdbarch_read_pc},
4100@code{gdbarch_write_pc}, and @code{read_sp}. For most targets, these may be
9c8dbfa9
AC
4101left undefined. @value{GDBN} will call the read and write register
4102functions with the relevant @code{_REGNUM} argument.
c906108c 4103
4a9bb1df
UW
4104These macros and functions are useful when a target keeps one of these
4105registers in a hard to get at place; for example, part in a segment register
4106and part in an ordinary register.
c906108c 4107
4a9bb1df 4108@xref{gdbarch_unwind_sp}, which replaces @code{TARGET_READ_SP}.
a9e5fdc2 4109
4a9bb1df
UW
4110@item void gdbarch_virtual_frame_pointer (@var{gdbarch}, @var{pc}, @var{frame_regnum}, @var{frame_offset})
4111@findex gdbarch_virtual_frame_pointer
0ba6dca9
AC
4112Returns a @code{(register, offset)} pair representing the virtual frame
4113pointer in use at the code address @var{pc}. If virtual frame pointers
4114are not used, a default definition simply returns
4115@code{DEPRECATED_FP_REGNUM}, with an offset of zero.
c906108c 4116
9742079a
EZ
4117@item TARGET_HAS_HARDWARE_WATCHPOINTS
4118If non-zero, the target has support for hardware-assisted
4119watchpoints. @xref{Algorithms, watchpoints}, for more details and
4120other related macros.
4121
4a9bb1df
UW
4122@item int gdbarch_print_insn (@var{gdbarch}, @var{vma}, @var{info})
4123@findex gdbarch_print_insn
7ccaa899 4124This is the function used by @value{GDBN} to print an assembly
4a9bb1df 4125instruction. It prints the instruction at address @var{vma} in
7ccaa899
EZ
4126debugged memory and returns the length of the instruction, in bytes. If
4127a target doesn't define its own printing routine, it defaults to an
d7a27068
AC
4128accessor function for the global pointer
4129@code{deprecated_tm_print_insn}. This usually points to a function in
4130the @code{opcodes} library (@pxref{Support Libraries, ,Opcodes}).
4131@var{info} is a structure (of type @code{disassemble_info}) defined in
4132@file{include/dis-asm.h} used to pass information to the instruction
4133decoding routine.
7ccaa899 4134
4a9bb1df
UW
4135@item frame_id gdbarch_unwind_dummy_id (@var{gdbarch}, @var{frame})
4136@findex gdbarch_unwind_dummy_id
4137@anchor{gdbarch_unwind_dummy_id} Given @var{frame} return a @w{@code{struct
4138frame_id}} that uniquely identifies an inferior function call's dummy
b24da7d0
AC
4139frame. The value returned must match the dummy frame stack value
4140previously saved using @code{SAVE_DUMMY_FRAME_TOS}.
4141@xref{SAVE_DUMMY_FRAME_TOS}.
6314f104 4142
b5622e8d
AC
4143@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
4144@findex DEPRECATED_USE_STRUCT_CONVENTION
c906108c
SS
4145If defined, this must be an expression that is nonzero if a value of the
4146given @var{type} being returned from a function must have space
4147allocated for it on the stack. @var{gcc_p} is true if the function
4148being considered is known to have been compiled by GCC; this is helpful
4149for systems where GCC is known to use different calling convention than
4150other compilers.
4151
92ad9cd9
AC
4152This method has been deprecated in favour of @code{gdbarch_return_value}
4153(@pxref{gdbarch_return_value}).
4154
4a9bb1df
UW
4155@item void gdbarch_value_to_register (@var{gdbarch}, @var{frame}, @var{type}, @var{buf})
4156@findex gdbarch_value_to_register
4157Convert a value of type @var{type} into the raw contents of a register.
13d01224
AC
4158@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
4159
c906108c
SS
4160@end table
4161
4162Motorola M68K target conditionals.
4163
56caf160 4164@ftable @code
c906108c
SS
4165@item BPT_VECTOR
4166Define this to be the 4-bit location of the breakpoint trap vector. If
4167not defined, it will default to @code{0xf}.
4168
4169@item REMOTE_BPT_VECTOR
4170Defaults to @code{1}.
a23a7bf1 4171
4a9bb1df
UW
4172@item const char *gdbarch_name_of_malloc (@var{gdbarch})
4173@findex gdbarch_name_of_malloc
a23a7bf1
JB
4174A string containing the name of the function to call in order to
4175allocate some memory in the inferior. The default value is "malloc".
4176
56caf160 4177@end ftable
c906108c 4178
b6fd0dfb 4179@node Adding a New Target
c906108c
SS
4180@section Adding a New Target
4181
56caf160 4182@cindex adding a target
af6c57ea 4183The following files add a target to @value{GDBN}:
c906108c
SS
4184
4185@table @file
56caf160 4186@vindex TDEPFILES
c906108c
SS
4187@item gdb/config/@var{arch}/@var{ttt}.mt
4188Contains a Makefile fragment specific to this target. Specifies what
4189object files are needed for target @var{ttt}, by defining
104c1213
JM
4190@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
4191the header file which describes @var{ttt}, by defining @samp{TM_FILE=
4192tm-@var{ttt}.h}.
4193
4194You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
4195but these are now deprecated, replaced by autoconf, and may go away in
25822942 4196future versions of @value{GDBN}.
c906108c 4197
c906108c
SS
4198@item gdb/@var{ttt}-tdep.c
4199Contains any miscellaneous code required for this target machine. On
4200some machines it doesn't exist at all. Sometimes the macros in
4201@file{tm-@var{ttt}.h} become very complicated, so they are implemented
4202as functions here instead, and the macro is simply defined to call the
4203function. This is vastly preferable, since it is easier to understand
4204and debug.
4205
af6c57ea
AC
4206@item gdb/@var{arch}-tdep.c
4207@itemx gdb/@var{arch}-tdep.h
4208This often exists to describe the basic layout of the target machine's
4209processor chip (registers, stack, etc.). If used, it is included by
4210@file{@var{ttt}-tdep.h}. It can be shared among many targets that use
4211the same processor.
4212
4213@item gdb/config/@var{arch}/tm-@var{ttt}.h
4214(@file{tm.h} is a link to this file, created by @code{configure}). Contains
4215macro definitions about the target machine's registers, stack frame
4216format and instructions.
4217
4218New targets do not need this file and should not create it.
4219
c906108c
SS
4220@item gdb/config/@var{arch}/tm-@var{arch}.h
4221This often exists to describe the basic layout of the target machine's
56caf160 4222processor chip (registers, stack, etc.). If used, it is included by
c906108c
SS
4223@file{tm-@var{ttt}.h}. It can be shared among many targets that use the
4224same processor.
4225
af6c57ea
AC
4226New targets do not need this file and should not create it.
4227
c906108c
SS
4228@end table
4229
4230If you are adding a new operating system for an existing CPU chip, add a
4231@file{config/tm-@var{os}.h} file that describes the operating system
4232facilities that are unusual (extra symbol table info; the breakpoint
56caf160 4233instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
c906108c
SS
4234that just @code{#include}s @file{tm-@var{arch}.h} and
4235@file{config/tm-@var{os}.h}.
4236
123dc839
DJ
4237@node Target Descriptions
4238@chapter Target Descriptions
4239@cindex target descriptions
4240
4241The target architecture definition (@pxref{Target Architecture Definition})
4242contains @value{GDBN}'s hard-coded knowledge about an architecture. For
4243some platforms, it is handy to have more flexible knowledge about a specific
4244instance of the architecture---for instance, a processor or development board.
4245@dfn{Target descriptions} provide a mechanism for the user to tell @value{GDBN}
4246more about what their target supports, or for the target to tell @value{GDBN}
4247directly.
4248
4249For details on writing, automatically supplying, and manually selecting
4250target descriptions, see @ref{Target Descriptions, , , gdb,
4251Debugging with @value{GDBN}}. This section will cover some related
4252topics about the @value{GDBN} internals.
4253
4254@menu
4255* Target Descriptions Implementation::
4256* Adding Target Described Register Support::
4257@end menu
4258
4259@node Target Descriptions Implementation
4260@section Target Descriptions Implementation
4261@cindex target descriptions, implementation
4262
4263Before @value{GDBN} connects to a new target, or runs a new program on
4264an existing target, it discards any existing target description and
4265reverts to a default gdbarch. Then, after connecting, it looks for a
4266new target description by calling @code{target_find_description}.
4267
4268A description may come from a user specified file (XML), the remote
4269@samp{qXfer:features:read} packet (also XML), or from any custom
4270@code{to_read_description} routine in the target vector. For instance,
4271the remote target supports guessing whether a MIPS target is 32-bit or
427264-bit based on the size of the @samp{g} packet.
4273
4274If any target description is found, @value{GDBN} creates a new gdbarch
4275incorporating the description by calling @code{gdbarch_update_p}. Any
4276@samp{<architecture>} element is handled first, to determine which
4277architecture's gdbarch initialization routine is called to create the
4278new architecture. Then the initialization routine is called, and has
4279a chance to adjust the constructed architecture based on the contents
4280of the target description. For instance, it can recognize any
4281properties set by a @code{to_read_description} routine. Also
4282see @ref{Adding Target Described Register Support}.
4283
4284@node Adding Target Described Register Support
4285@section Adding Target Described Register Support
4286@cindex target descriptions, adding register support
4287
4288Target descriptions can report additional registers specific to an
4289instance of the target. But it takes a little work in the architecture
4290specific routines to support this.
4291
4292A target description must either have no registers or a complete
4293set---this avoids complexity in trying to merge standard registers
4294with the target defined registers. It is the architecture's
4295responsibility to validate that a description with registers has
4296everything it needs. To keep architecture code simple, the same
4297mechanism is used to assign fixed internal register numbers to
4298standard registers.
4299
4300If @code{tdesc_has_registers} returns 1, the description contains
4301registers. The architecture's @code{gdbarch_init} routine should:
4302
4303@itemize @bullet
4304
4305@item
4306Call @code{tdesc_data_alloc} to allocate storage, early, before
4307searching for a matching gdbarch or allocating a new one.
4308
4309@item
4310Use @code{tdesc_find_feature} to locate standard features by name.
4311
4312@item
4313Use @code{tdesc_numbered_register} and @code{tdesc_numbered_register_choices}
4314to locate the expected registers in the standard features.
4315
4316@item
4317Return @code{NULL} if a required feature is missing, or if any standard
4318feature is missing expected registers. This will produce a warning that
4319the description was incomplete.
4320
4321@item
4322Free the allocated data before returning, unless @code{tdesc_use_registers}
4323is called.
4324
4325@item
4326Call @code{set_gdbarch_num_regs} as usual, with a number higher than any
4327fixed number passed to @code{tdesc_numbered_register}.
4328
4329@item
4330Call @code{tdesc_use_registers} after creating a new gdbarch, before
4331returning it.
4332
4333@end itemize
4334
4335After @code{tdesc_use_registers} has been called, the architecture's
4336@code{register_name}, @code{register_type}, and @code{register_reggroup_p}
4337routines will not be called; that information will be taken from
4338the target description. @code{num_regs} may be increased to account
4339for any additional registers in the description.
4340
4341Pseudo-registers require some extra care:
4342
4343@itemize @bullet
4344
4345@item
4346Using @code{tdesc_numbered_register} allows the architecture to give
4347constant register numbers to standard architectural registers, e.g.@:
4348as an @code{enum} in @file{@var{arch}-tdep.h}. But because
4349pseudo-registers are always numbered above @code{num_regs},
4350which may be increased by the description, constant numbers
4351can not be used for pseudos. They must be numbered relative to
4352@code{num_regs} instead.
4353
4354@item
4355The description will not describe pseudo-registers, so the
4356architecture must call @code{set_tdesc_pseudo_register_name},
4357@code{set_tdesc_pseudo_register_type}, and
4358@code{set_tdesc_pseudo_register_reggroup_p} to supply routines
4359describing pseudo registers. These routines will be passed
4360internal register numbers, so the same routines used for the
4361gdbarch equivalents are usually suitable.
4362
4363@end itemize
4364
4365
c906108c
SS
4366@node Target Vector Definition
4367
4368@chapter Target Vector Definition
56caf160 4369@cindex target vector
c906108c 4370
56caf160
EZ
4371The target vector defines the interface between @value{GDBN}'s
4372abstract handling of target systems, and the nitty-gritty code that
4373actually exercises control over a process or a serial port.
4374@value{GDBN} includes some 30-40 different target vectors; however,
4375each configuration of @value{GDBN} includes only a few of them.
c906108c 4376
52bb452f
DJ
4377@menu
4378* Managing Execution State::
4379* Existing Targets::
4380@end menu
4381
4382@node Managing Execution State
4383@section Managing Execution State
4384@cindex execution state
4385
4386A target vector can be completely inactive (not pushed on the target
4387stack), active but not running (pushed, but not connected to a fully
4388manifested inferior), or completely active (pushed, with an accessible
4389inferior). Most targets are only completely inactive or completely
d3e8051b 4390active, but some support persistent connections to a target even
52bb452f
DJ
4391when the target has exited or not yet started.
4392
4393For example, connecting to the simulator using @code{target sim} does
4394not create a running program. Neither registers nor memory are
4395accessible until @code{run}. Similarly, after @code{kill}, the
4396program can not continue executing. But in both cases @value{GDBN}
4397remains connected to the simulator, and target-specific commands
4398are directed to the simulator.
4399
4400A target which only supports complete activation should push itself
4401onto the stack in its @code{to_open} routine (by calling
4402@code{push_target}), and unpush itself from the stack in its
4403@code{to_mourn_inferior} routine (by calling @code{unpush_target}).
4404
4405A target which supports both partial and complete activation should
4406still call @code{push_target} in @code{to_open}, but not call
4407@code{unpush_target} in @code{to_mourn_inferior}. Instead, it should
4408call either @code{target_mark_running} or @code{target_mark_exited}
4409in its @code{to_open}, depending on whether the target is fully active
4410after connection. It should also call @code{target_mark_running} any
4411time the inferior becomes fully active (e.g.@: in
4412@code{to_create_inferior} and @code{to_attach}), and
4413@code{target_mark_exited} when the inferior becomes inactive (in
4414@code{to_mourn_inferior}). The target should also make sure to call
4415@code{target_mourn_inferior} from its @code{to_kill}, to return the
4416target to inactive state.
4417
4418@node Existing Targets
4419@section Existing Targets
4420@cindex targets
4421
4422@subsection File Targets
c906108c
SS
4423
4424Both executables and core files have target vectors.
4425
52bb452f 4426@subsection Standard Protocol and Remote Stubs
c906108c 4427
56caf160
EZ
4428@value{GDBN}'s file @file{remote.c} talks a serial protocol to code
4429that runs in the target system. @value{GDBN} provides several sample
4430@dfn{stubs} that can be integrated into target programs or operating
4431systems for this purpose; they are named @file{*-stub.c}.
c906108c 4432
56caf160
EZ
4433The @value{GDBN} user's manual describes how to put such a stub into
4434your target code. What follows is a discussion of integrating the
4435SPARC stub into a complicated operating system (rather than a simple
4436program), by Stu Grossman, the author of this stub.
c906108c
SS
4437
4438The trap handling code in the stub assumes the following upon entry to
56caf160 4439@code{trap_low}:
c906108c
SS
4440
4441@enumerate
56caf160
EZ
4442@item
4443%l1 and %l2 contain pc and npc respectively at the time of the trap;
c906108c 4444
56caf160
EZ
4445@item
4446traps are disabled;
c906108c 4447
56caf160
EZ
4448@item
4449you are in the correct trap window.
c906108c
SS
4450@end enumerate
4451
4452As long as your trap handler can guarantee those conditions, then there
56caf160 4453is no reason why you shouldn't be able to ``share'' traps with the stub.
c906108c
SS
4454The stub has no requirement that it be jumped to directly from the
4455hardware trap vector. That is why it calls @code{exceptionHandler()},
4456which is provided by the external environment. For instance, this could
56caf160 4457set up the hardware traps to actually execute code which calls the stub
c906108c
SS
4458first, and then transfers to its own trap handler.
4459
4460For the most point, there probably won't be much of an issue with
56caf160 4461``sharing'' traps, as the traps we use are usually not used by the kernel,
c906108c
SS
4462and often indicate unrecoverable error conditions. Anyway, this is all
4463controlled by a table, and is trivial to modify. The most important
4464trap for us is for @code{ta 1}. Without that, we can't single step or
4465do breakpoints. Everything else is unnecessary for the proper operation
4466of the debugger/stub.
4467
4468From reading the stub, it's probably not obvious how breakpoints work.
25822942 4469They are simply done by deposit/examine operations from @value{GDBN}.
c906108c 4470
52bb452f 4471@subsection ROM Monitor Interface
c906108c 4472
52bb452f 4473@subsection Custom Protocols
c906108c 4474
52bb452f 4475@subsection Transport Layer
c906108c 4476
52bb452f 4477@subsection Builtin Simulator
c906108c
SS
4478
4479
4480@node Native Debugging
4481
4482@chapter Native Debugging
56caf160 4483@cindex native debugging
c906108c 4484
25822942 4485Several files control @value{GDBN}'s configuration for native support:
c906108c
SS
4486
4487@table @file
56caf160 4488@vindex NATDEPFILES
c906108c 4489@item gdb/config/@var{arch}/@var{xyz}.mh
7fd60527 4490Specifies Makefile fragments needed by a @emph{native} configuration on
c906108c
SS
4491machine @var{xyz}. In particular, this lists the required
4492native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
4493Also specifies the header file which describes native support on
4494@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
4495define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
4496@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
4497
7fd60527
AC
4498@emph{Maintainer's note: The @file{.mh} suffix is because this file
4499originally contained @file{Makefile} fragments for hosting @value{GDBN}
4500on machine @var{xyz}. While the file is no longer used for this
937f164b 4501purpose, the @file{.mh} suffix remains. Perhaps someone will
7fd60527
AC
4502eventually rename these fragments so that they have a @file{.mn}
4503suffix.}
4504
c906108c 4505@item gdb/config/@var{arch}/nm-@var{xyz}.h
56caf160 4506(@file{nm.h} is a link to this file, created by @code{configure}). Contains C
c906108c
SS
4507macro definitions describing the native system environment, such as
4508child process control and core file support.
4509
4510@item gdb/@var{xyz}-nat.c
4511Contains any miscellaneous C code required for this native support of
4512this machine. On some machines it doesn't exist at all.
c906108c
SS
4513@end table
4514
4515There are some ``generic'' versions of routines that can be used by
4516various systems. These can be customized in various ways by macros
4517defined in your @file{nm-@var{xyz}.h} file. If these routines work for
4518the @var{xyz} host, you can just include the generic file's name (with
4519@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
4520
4521Otherwise, if your machine needs custom support routines, you will need
4522to write routines that perform the same functions as the generic file.
56caf160 4523Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
c906108c
SS
4524into @code{NATDEPFILES}.
4525
4526@table @file
c906108c
SS
4527@item inftarg.c
4528This contains the @emph{target_ops vector} that supports Unix child
4529processes on systems which use ptrace and wait to control the child.
4530
4531@item procfs.c
4532This contains the @emph{target_ops vector} that supports Unix child
4533processes on systems which use /proc to control the child.
4534
4535@item fork-child.c
56caf160
EZ
4536This does the low-level grunge that uses Unix system calls to do a ``fork
4537and exec'' to start up a child process.
c906108c
SS
4538
4539@item infptrace.c
4540This is the low level interface to inferior processes for systems using
4541the Unix @code{ptrace} call in a vanilla way.
c906108c
SS
4542@end table
4543
4544@section Native core file Support
56caf160 4545@cindex native core files
c906108c
SS
4546
4547@table @file
56caf160 4548@findex fetch_core_registers
c906108c
SS
4549@item core-aout.c::fetch_core_registers()
4550Support for reading registers out of a core file. This routine calls
4551@code{register_addr()}, see below. Now that BFD is used to read core
4552files, virtually all machines should use @code{core-aout.c}, and should
4553just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
4554@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
4555
4556@item core-aout.c::register_addr()
4557If your @code{nm-@var{xyz}.h} file defines the macro
4558@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
25822942 4559set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
c906108c
SS
4560register number @code{regno}. @code{blockend} is the offset within the
4561``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
4562@file{core-aout.c} will define the @code{register_addr()} function and
4563use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
4564you are using the standard @code{fetch_core_registers()}, you will need
4565to define your own version of @code{register_addr()}, put it into your
4566@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
4567the @code{NATDEPFILES} list. If you have your own
4568@code{fetch_core_registers()}, you may not need a separate
4569@code{register_addr()}. Many custom @code{fetch_core_registers()}
4570implementations simply locate the registers themselves.@refill
c906108c
SS
4571@end table
4572
25822942 4573When making @value{GDBN} run native on a new operating system, to make it
c906108c
SS
4574possible to debug core files, you will need to either write specific
4575code for parsing your OS's core files, or customize
4576@file{bfd/trad-core.c}. First, use whatever @code{#include} files your
4577machine uses to define the struct of registers that is accessible
4578(possibly in the u-area) in a core file (rather than
4579@file{machine/reg.h}), and an include file that defines whatever header
c1468174 4580exists on a core file (e.g., the u-area or a @code{struct core}). Then
56caf160 4581modify @code{trad_unix_core_file_p} to use these values to set up the
c906108c
SS
4582section information for the data segment, stack segment, any other
4583segments in the core file (perhaps shared library contents or control
4584information), ``registers'' segment, and if there are two discontiguous
c1468174 4585sets of registers (e.g., integer and float), the ``reg2'' segment. This
c906108c
SS
4586section information basically delimits areas in the core file in a
4587standard way, which the section-reading routines in BFD know how to seek
4588around in.
4589
25822942 4590Then back in @value{GDBN}, you need a matching routine called
56caf160 4591@code{fetch_core_registers}. If you can use the generic one, it's in
c906108c
SS
4592@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
4593It will be passed a char pointer to the entire ``registers'' segment,
4594its length, and a zero; or a char pointer to the entire ``regs2''
4595segment, its length, and a 2. The routine should suck out the supplied
25822942 4596register values and install them into @value{GDBN}'s ``registers'' array.
c906108c
SS
4597
4598If your system uses @file{/proc} to control processes, and uses ELF
4599format core files, then you may be able to use the same routines for
4600reading the registers out of processes and out of core files.
4601
4602@section ptrace
4603
4604@section /proc
4605
4606@section win32
4607
4608@section shared libraries
4609
4610@section Native Conditionals
56caf160 4611@cindex native conditionals
c906108c 4612
56caf160
EZ
4613When @value{GDBN} is configured and compiled, various macros are
4614defined or left undefined, to control compilation when the host and
4615target systems are the same. These macros should be defined (or left
4616undefined) in @file{nm-@var{system}.h}.
c906108c 4617
1f6d4158
AC
4618@table @code
4619
c906108c 4620@item CHILD_PREPARE_TO_STORE
56caf160 4621@findex CHILD_PREPARE_TO_STORE
c906108c
SS
4622If the machine stores all registers at once in the child process, then
4623define this to ensure that all values are correct. This usually entails
4624a read from the child.
4625
4626[Note that this is incorrectly defined in @file{xm-@var{system}.h} files
4627currently.]
4628
4629@item FETCH_INFERIOR_REGISTERS
56caf160 4630@findex FETCH_INFERIOR_REGISTERS
c906108c
SS
4631Define this if the native-dependent code will provide its own routines
4632@code{fetch_inferior_registers} and @code{store_inferior_registers} in
56caf160 4633@file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
c906108c
SS
4634@file{infptrace.c} is included in this configuration, the default
4635routines in @file{infptrace.c} are used for these functions.
4636
4a9bb1df
UW
4637@item int gdbarch_fp0_regnum (@var{gdbarch})
4638@findex gdbarch_fp0_regnum
4639This functions normally returns the number of the first floating
c906108c 4640point register, if the machine has such registers. As such, it would
56caf160 4641appear only in target-specific code. However, @file{/proc} support uses this
c906108c
SS
4642to decide whether floats are in use on this target.
4643
4a9bb1df
UW
4644@item int gdbarch_get_longjmp_target (@var{gdbarch})
4645@findex gdbarch_get_longjmp_target
c906108c
SS
4646For most machines, this is a target-dependent parameter. On the
4647DECstation and the Iris, this is a native-dependent parameter, since
56caf160 4648@file{setjmp.h} is needed to define it.
c906108c 4649
4a9bb1df 4650This function determines the target PC address that @code{longjmp} will jump to,
c906108c 4651assuming that we have just stopped at a longjmp breakpoint. It takes a
56caf160 4652@code{CORE_ADDR *} as argument, and stores the target PC value through this
c906108c
SS
4653pointer. It examines the current state of the machine as needed.
4654
9742079a
EZ
4655@item I386_USE_GENERIC_WATCHPOINTS
4656An x86-based machine can define this to use the generic x86 watchpoint
4657support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
4658
c906108c 4659@item ONE_PROCESS_WRITETEXT
56caf160 4660@findex ONE_PROCESS_WRITETEXT
c906108c
SS
4661Define this to be able to, when a breakpoint insertion fails, warn the
4662user that another process may be running with the same executable.
4663
4664@item PROC_NAME_FMT
56caf160 4665@findex PROC_NAME_FMT
c906108c
SS
4666Defines the format for the name of a @file{/proc} device. Should be
4667defined in @file{nm.h} @emph{only} in order to override the default
4668definition in @file{procfs.c}.
4669
990f9fe3 4670@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
56caf160 4671@findex SOLIB_ADD
c906108c 4672Define this to expand into an expression that will cause the symbols in
990f9fe3
FF
4673@var{filename} to be added to @value{GDBN}'s symbol table. If
4674@var{readsyms} is zero symbols are not read but any necessary low level
4675processing for @var{filename} is still done.
c906108c
SS
4676
4677@item SOLIB_CREATE_INFERIOR_HOOK
56caf160 4678@findex SOLIB_CREATE_INFERIOR_HOOK
c906108c
SS
4679Define this to expand into any shared-library-relocation code that you
4680want to be run just after the child process has been forked.
4681
4682@item START_INFERIOR_TRAPS_EXPECTED
56caf160
EZ
4683@findex START_INFERIOR_TRAPS_EXPECTED
4684When starting an inferior, @value{GDBN} normally expects to trap
4685twice; once when
c906108c
SS
4686the shell execs, and once when the program itself execs. If the actual
4687number of traps is something other than 2, then define this macro to
4688expand into the number expected.
4689
c906108c
SS
4690@end table
4691
c906108c
SS
4692@node Support Libraries
4693
4694@chapter Support Libraries
4695
4696@section BFD
56caf160 4697@cindex BFD library
c906108c 4698
25822942 4699BFD provides support for @value{GDBN} in several ways:
c906108c
SS
4700
4701@table @emph
c906108c
SS
4702@item identifying executable and core files
4703BFD will identify a variety of file types, including a.out, coff, and
4704several variants thereof, as well as several kinds of core files.
4705
4706@item access to sections of files
4707BFD parses the file headers to determine the names, virtual addresses,
4708sizes, and file locations of all the various named sections in files
56caf160
EZ
4709(such as the text section or the data section). @value{GDBN} simply
4710calls BFD to read or write section @var{x} at byte offset @var{y} for
4711length @var{z}.
c906108c
SS
4712
4713@item specialized core file support
4714BFD provides routines to determine the failing command name stored in a
4715core file, the signal with which the program failed, and whether a core
56caf160 4716file matches (i.e.@: could be a core dump of) a particular executable
c906108c
SS
4717file.
4718
4719@item locating the symbol information
25822942
DB
4720@value{GDBN} uses an internal interface of BFD to determine where to find the
4721symbol information in an executable file or symbol-file. @value{GDBN} itself
c906108c 4722handles the reading of symbols, since BFD does not ``understand'' debug
25822942 4723symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
c906108c 4724string table, etc.
c906108c
SS
4725@end table
4726
4727@section opcodes
56caf160 4728@cindex opcodes library
c906108c 4729
25822942 4730The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
c906108c
SS
4731library because it's also used in binutils, for @file{objdump}).
4732
4733@section readline
86f04699
EZ
4734@cindex readline library
4735The @code{readline} library provides a set of functions for use by applications
4736that allow users to edit command lines as they are typed in.
c906108c
SS
4737
4738@section libiberty
1eb288ea
EZ
4739@cindex @code{libiberty} library
4740
4741The @code{libiberty} library provides a set of functions and features
4742that integrate and improve on functionality found in modern operating
4743systems. Broadly speaking, such features can be divided into three
4744groups: supplemental functions (functions that may be missing in some
4745environments and operating systems), replacement functions (providing
4746a uniform and easier to use interface for commonly used standard
4747functions), and extensions (which provide additional functionality
4748beyond standard functions).
4749
4750@value{GDBN} uses various features provided by the @code{libiberty}
4751library, for instance the C@t{++} demangler, the @acronym{IEEE}
4752floating format support functions, the input options parser
4753@samp{getopt}, the @samp{obstack} extension, and other functions.
4754
4755@subsection @code{obstacks} in @value{GDBN}
4756@cindex @code{obstacks}
4757
4758The obstack mechanism provides a convenient way to allocate and free
4759chunks of memory. Each obstack is a pool of memory that is managed
4760like a stack. Objects (of any nature, size and alignment) are
4761allocated and freed in a @acronym{LIFO} fashion on an obstack (see
d3e8051b 4762@code{libiberty}'s documentation for a more detailed explanation of
1eb288ea
EZ
4763@code{obstacks}).
4764
4765The most noticeable use of the @code{obstacks} in @value{GDBN} is in
4766object files. There is an obstack associated with each internal
4767representation of an object file. Lots of things get allocated on
4768these @code{obstacks}: dictionary entries, blocks, blockvectors,
4769symbols, minimal symbols, types, vectors of fundamental types, class
4770fields of types, object files section lists, object files section
d3e8051b 4771offset lists, line tables, symbol tables, partial symbol tables,
1eb288ea
EZ
4772string tables, symbol table private data, macros tables, debug
4773information sections and entries, import and export lists (som),
4774unwind information (hppa), dwarf2 location expressions data. Plus
4775various strings such as directory names strings, debug format strings,
4776names of types.
4777
4778An essential and convenient property of all data on @code{obstacks} is
4779that memory for it gets allocated (with @code{obstack_alloc}) at
d3e8051b 4780various times during a debugging session, but it is released all at
1eb288ea
EZ
4781once using the @code{obstack_free} function. The @code{obstack_free}
4782function takes a pointer to where in the stack it must start the
4783deletion from (much like the cleanup chains have a pointer to where to
4784start the cleanups). Because of the stack like structure of the
4785@code{obstacks}, this allows to free only a top portion of the
4786obstack. There are a few instances in @value{GDBN} where such thing
4787happens. Calls to @code{obstack_free} are done after some local data
4788is allocated to the obstack. Only the local data is deleted from the
4789obstack. Of course this assumes that nothing between the
4790@code{obstack_alloc} and the @code{obstack_free} allocates anything
4791else on the same obstack. For this reason it is best and safest to
4792use temporary @code{obstacks}.
4793
4794Releasing the whole obstack is also not safe per se. It is safe only
4795under the condition that we know the @code{obstacks} memory is no
4796longer needed. In @value{GDBN} we get rid of the @code{obstacks} only
4797when we get rid of the whole objfile(s), for instance upon reading a
4798new symbol file.
c906108c
SS
4799
4800@section gnu-regex
56caf160 4801@cindex regular expressions library
c906108c
SS
4802
4803Regex conditionals.
4804
4805@table @code
c906108c
SS
4806@item C_ALLOCA
4807
4808@item NFAILURES
4809
4810@item RE_NREGS
4811
4812@item SIGN_EXTEND_CHAR
4813
4814@item SWITCH_ENUM_BUG
4815
4816@item SYNTAX_TABLE
4817
4818@item Sword
4819
4820@item sparc
c906108c
SS
4821@end table
4822
350da6ee
DJ
4823@section Array Containers
4824@cindex Array Containers
4825@cindex VEC
4826
4827Often it is necessary to manipulate a dynamic array of a set of
4828objects. C forces some bookkeeping on this, which can get cumbersome
d3e8051b 4829and repetitive. The @file{vec.h} file contains macros for defining
350da6ee
DJ
4830and using a typesafe vector type. The functions defined will be
4831inlined when compiling, and so the abstraction cost should be zero.
4832Domain checks are added to detect programming errors.
4833
4834An example use would be an array of symbols or section information.
4835The array can be grown as symbols are read in (or preallocated), and
4836the accessor macros provided keep care of all the necessary
4837bookkeeping. Because the arrays are type safe, there is no danger of
4838accidentally mixing up the contents. Think of these as C++ templates,
4839but implemented in C.
4840
4841Because of the different behavior of structure objects, scalar objects
4842and of pointers, there are three flavors of vector, one for each of
4843these variants. Both the structure object and pointer variants pass
4844pointers to objects around --- in the former case the pointers are
4845stored into the vector and in the latter case the pointers are
4846dereferenced and the objects copied into the vector. The scalar
4847object variant is suitable for @code{int}-like objects, and the vector
4848elements are returned by value.
4849
4850There are both @code{index} and @code{iterate} accessors. The iterator
4851returns a boolean iteration condition and updates the iteration
4852variable passed by reference. Because the iterator will be inlined,
4853the address-of can be optimized away.
4854
4855The vectors are implemented using the trailing array idiom, thus they
4856are not resizeable without changing the address of the vector object
4857itself. This means you cannot have variables or fields of vector type
4858--- always use a pointer to a vector. The one exception is the final
4859field of a structure, which could be a vector type. You will have to
4860use the @code{embedded_size} & @code{embedded_init} calls to create
4861such objects, and they will probably not be resizeable (so don't use
4862the @dfn{safe} allocation variants). The trailing array idiom is used
4863(rather than a pointer to an array of data), because, if we allow
4864@code{NULL} to also represent an empty vector, empty vectors occupy
4865minimal space in the structure containing them.
4866
4867Each operation that increases the number of active elements is
4868available in @dfn{quick} and @dfn{safe} variants. The former presumes
4869that there is sufficient allocated space for the operation to succeed
4870(it dies if there is not). The latter will reallocate the vector, if
4871needed. Reallocation causes an exponential increase in vector size.
4872If you know you will be adding N elements, it would be more efficient
4873to use the reserve operation before adding the elements with the
4874@dfn{quick} operation. This will ensure there are at least as many
4875elements as you ask for, it will exponentially increase if there are
4876too few spare slots. If you want reserve a specific number of slots,
4877but do not want the exponential increase (for instance, you know this
4878is the last allocation), use a negative number for reservation. You
4879can also create a vector of a specific size from the get go.
4880
4881You should prefer the push and pop operations, as they append and
4882remove from the end of the vector. If you need to remove several items
4883in one go, use the truncate operation. The insert and remove
4884operations allow you to change elements in the middle of the vector.
4885There are two remove operations, one which preserves the element
4886ordering @code{ordered_remove}, and one which does not
4887@code{unordered_remove}. The latter function copies the end element
4888into the removed slot, rather than invoke a memmove operation. The
4889@code{lower_bound} function will determine where to place an item in
4890the array using insert that will maintain sorted order.
4891
4892If you need to directly manipulate a vector, then the @code{address}
4893accessor will return the address of the start of the vector. Also the
4894@code{space} predicate will tell you whether there is spare capacity in the
4895vector. You will not normally need to use these two functions.
4896
4897Vector types are defined using a
4898@code{DEF_VEC_@{O,P,I@}(@var{typename})} macro. Variables of vector
4899type are declared using a @code{VEC(@var{typename})} macro. The
4900characters @code{O}, @code{P} and @code{I} indicate whether
4901@var{typename} is an object (@code{O}), pointer (@code{P}) or integral
4902(@code{I}) type. Be careful to pick the correct one, as you'll get an
4903awkward and inefficient API if you use the wrong one. There is a
4904check, which results in a compile-time warning, for the @code{P} and
4905@code{I} versions, but there is no check for the @code{O} versions, as
4906that is not possible in plain C.
4907
4908An example of their use would be,
4909
4910@smallexample
4911DEF_VEC_P(tree); // non-managed tree vector.
4912
4913struct my_struct @{
4914 VEC(tree) *v; // A (pointer to) a vector of tree pointers.
4915@};
4916
4917struct my_struct *s;
4918
4919if (VEC_length(tree, s->v)) @{ we have some contents @}
4920VEC_safe_push(tree, s->v, decl); // append some decl onto the end
4921for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++)
4922 @{ do something with elt @}
4923
4924@end smallexample
4925
4926The @file{vec.h} file provides details on how to invoke the various
4927accessors provided. They are enumerated here:
4928
4929@table @code
4930@item VEC_length
4931Return the number of items in the array,
4932
4933@item VEC_empty
4934Return true if the array has no elements.
4935
4936@item VEC_last
4937@itemx VEC_index
4938Return the last or arbitrary item in the array.
4939
4940@item VEC_iterate
4941Access an array element and indicate whether the array has been
4942traversed.
4943
4944@item VEC_alloc
4945@itemx VEC_free
4946Create and destroy an array.
4947
4948@item VEC_embedded_size
4949@itemx VEC_embedded_init
4950Helpers for embedding an array as the final element of another struct.
4951
4952@item VEC_copy
4953Duplicate an array.
4954
4955@item VEC_space
4956Return the amount of free space in an array.
4957
4958@item VEC_reserve
4959Ensure a certain amount of free space.
4960
4961@item VEC_quick_push
4962@itemx VEC_safe_push
4963Append to an array, either assuming the space is available, or making
4964sure that it is.
4965
4966@item VEC_pop
4967Remove the last item from an array.
4968
4969@item VEC_truncate
4970Remove several items from the end of an array.
4971
4972@item VEC_safe_grow
4973Add several items to the end of an array.
4974
4975@item VEC_replace
4976Overwrite an item in the array.
4977
4978@item VEC_quick_insert
4979@itemx VEC_safe_insert
4980Insert an item into the middle of the array. Either the space must
4981already exist, or the space is created.
4982
4983@item VEC_ordered_remove
4984@itemx VEC_unordered_remove
4985Remove an item from the array, preserving order or not.
4986
4987@item VEC_block_remove
4988Remove a set of items from the array.
4989
4990@item VEC_address
4991Provide the address of the first element.
4992
4993@item VEC_lower_bound
4994Binary search the array.
4995
4996@end table
4997
c906108c
SS
4998@section include
4999
5000@node Coding
5001
5002@chapter Coding
5003
5004This chapter covers topics that are lower-level than the major
25822942 5005algorithms of @value{GDBN}.
c906108c
SS
5006
5007@section Cleanups
56caf160 5008@cindex cleanups
c906108c
SS
5009
5010Cleanups are a structured way to deal with things that need to be done
cc1cb004 5011later.
c906108c 5012
cc1cb004
AC
5013When your code does something (e.g., @code{xmalloc} some memory, or
5014@code{open} a file) that needs to be undone later (e.g., @code{xfree}
5015the memory or @code{close} the file), it can make a cleanup. The
5016cleanup will be done at some future point: when the command is finished
5017and control returns to the top level; when an error occurs and the stack
5018is unwound; or when your code decides it's time to explicitly perform
5019cleanups. Alternatively you can elect to discard the cleanups you
5020created.
c906108c
SS
5021
5022Syntax:
5023
5024@table @code
c906108c
SS
5025@item struct cleanup *@var{old_chain};
5026Declare a variable which will hold a cleanup chain handle.
5027
56caf160 5028@findex make_cleanup
c906108c
SS
5029@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
5030Make a cleanup which will cause @var{function} to be called with
5031@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
cc1cb004
AC
5032handle that can later be passed to @code{do_cleanups} or
5033@code{discard_cleanups}. Unless you are going to call
5034@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result
5035from @code{make_cleanup}.
c906108c 5036
56caf160 5037@findex do_cleanups
c906108c 5038@item do_cleanups (@var{old_chain});
cc1cb004
AC
5039Do all cleanups added to the chain since the corresponding
5040@code{make_cleanup} call was made.
5041
5042@findex discard_cleanups
5043@item discard_cleanups (@var{old_chain});
5044Same as @code{do_cleanups} except that it just removes the cleanups from
5045the chain and does not call the specified functions.
5046@end table
5047
5048Cleanups are implemented as a chain. The handle returned by
5049@code{make_cleanups} includes the cleanup passed to the call and any
5050later cleanups appended to the chain (but not yet discarded or
5051performed). E.g.:
56caf160 5052
474c8240 5053@smallexample
c906108c 5054make_cleanup (a, 0);
cc1cb004
AC
5055@{
5056 struct cleanup *old = make_cleanup (b, 0);
5057 make_cleanup (c, 0)
5058 ...
5059 do_cleanups (old);
5060@}
474c8240 5061@end smallexample
56caf160 5062
c906108c 5063@noindent
cc1cb004
AC
5064will call @code{c()} and @code{b()} but will not call @code{a()}. The
5065cleanup that calls @code{a()} will remain in the cleanup chain, and will
5066be done later unless otherwise discarded.@refill
5067
5068Your function should explicitly do or discard the cleanups it creates.
5069Failing to do this leads to non-deterministic behavior since the caller
5070will arbitrarily do or discard your functions cleanups. This need leads
5071to two common cleanup styles.
5072
5073The first style is try/finally. Before it exits, your code-block calls
5074@code{do_cleanups} with the old cleanup chain and thus ensures that your
5075code-block's cleanups are always performed. For instance, the following
5076code-segment avoids a memory leak problem (even when @code{error} is
5077called and a forced stack unwind occurs) by ensuring that the
5078@code{xfree} will always be called:
c906108c 5079
474c8240 5080@smallexample
cc1cb004
AC
5081struct cleanup *old = make_cleanup (null_cleanup, 0);
5082data = xmalloc (sizeof blah);
5083make_cleanup (xfree, data);
5084... blah blah ...
5085do_cleanups (old);
474c8240 5086@end smallexample
cc1cb004
AC
5087
5088The second style is try/except. Before it exits, your code-block calls
5089@code{discard_cleanups} with the old cleanup chain and thus ensures that
5090any created cleanups are not performed. For instance, the following
5091code segment, ensures that the file will be closed but only if there is
5092an error:
5093
474c8240 5094@smallexample
cc1cb004
AC
5095FILE *file = fopen ("afile", "r");
5096struct cleanup *old = make_cleanup (close_file, file);
5097... blah blah ...
5098discard_cleanups (old);
5099return file;
474c8240 5100@end smallexample
c906108c 5101
c1468174 5102Some functions, e.g., @code{fputs_filtered()} or @code{error()}, specify
c906108c
SS
5103that they ``should not be called when cleanups are not in place''. This
5104means that any actions you need to reverse in the case of an error or
5105interruption must be on the cleanup chain before you call these
5106functions, since they might never return to your code (they
5107@samp{longjmp} instead).
5108
ba8c9337
AC
5109@section Per-architecture module data
5110@cindex per-architecture module data
5111@cindex multi-arch data
5112@cindex data-pointer, per-architecture/per-module
5113
fc989b7a
AC
5114The multi-arch framework includes a mechanism for adding module
5115specific per-architecture data-pointers to the @code{struct gdbarch}
5116architecture object.
5117
5118A module registers one or more per-architecture data-pointers using:
5119
5120@deftypefun struct gdbarch_data *gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init})
5121@var{pre_init} is used to, on-demand, allocate an initial value for a
5122per-architecture data-pointer using the architecture's obstack (passed
5123in as a parameter). Since @var{pre_init} can be called during
5124architecture creation, it is not parameterized with the architecture.
5125and must not call modules that use per-architecture data.
5126@end deftypefun
ba8c9337 5127
fc989b7a
AC
5128@deftypefun struct gdbarch_data *gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init})
5129@var{post_init} is used to obtain an initial value for a
5130per-architecture data-pointer @emph{after}. Since @var{post_init} is
5131always called after architecture creation, it both receives the fully
5132initialized architecture and is free to call modules that use
5133per-architecture data (care needs to be taken to ensure that those
5134other modules do not try to call back to this module as that will
5135create in cycles in the initialization call graph).
5136@end deftypefun
ba8c9337 5137
fc989b7a
AC
5138These functions return a @code{struct gdbarch_data} that is used to
5139identify the per-architecture data-pointer added for that module.
ba8c9337 5140
fc989b7a 5141The per-architecture data-pointer is accessed using the function:
ba8c9337 5142
fc989b7a
AC
5143@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
5144Given the architecture @var{arch} and module data handle
5145@var{data_handle} (returned by @code{gdbarch_data_register_pre_init}
5146or @code{gdbarch_data_register_post_init}), this function returns the
5147current value of the per-architecture data-pointer. If the data
5148pointer is @code{NULL}, it is first initialized by calling the
5149corresponding @var{pre_init} or @var{post_init} method.
ba8c9337
AC
5150@end deftypefun
5151
fc989b7a 5152The examples below assume the following definitions:
ba8c9337
AC
5153
5154@smallexample
e7f16015 5155struct nozel @{ int total; @};
ba8c9337 5156static struct gdbarch_data *nozel_handle;
ba8c9337
AC
5157@end smallexample
5158
fc989b7a
AC
5159A module can extend the architecture vector, adding additional
5160per-architecture data, using the @var{pre_init} method. The module's
5161per-architecture data is then initialized during architecture
5162creation.
ba8c9337 5163
fc989b7a
AC
5164In the below, the module's per-architecture @emph{nozel} is added. An
5165architecture can specify its nozel by calling @code{set_gdbarch_nozel}
5166from @code{gdbarch_init}.
ba8c9337
AC
5167
5168@smallexample
fc989b7a
AC
5169static void *
5170nozel_pre_init (struct obstack *obstack)
ba8c9337 5171@{
fc989b7a
AC
5172 struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
5173 return data;
5174@}
ba8c9337
AC
5175@end smallexample
5176
ba8c9337 5177@smallexample
fc989b7a
AC
5178extern void
5179set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
ba8c9337 5180@{
ba8c9337 5181 struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
fc989b7a 5182 data->total = nozel;
ba8c9337
AC
5183@}
5184@end smallexample
5185
fc989b7a
AC
5186A module can on-demand create architecture dependant data structures
5187using @code{post_init}.
ba8c9337 5188
fc989b7a
AC
5189In the below, the nozel's total is computed on-demand by
5190@code{nozel_post_init} using information obtained from the
5191architecture.
ba8c9337
AC
5192
5193@smallexample
fc989b7a
AC
5194static void *
5195nozel_post_init (struct gdbarch *gdbarch)
ba8c9337 5196@{
fc989b7a
AC
5197 struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
5198 nozel->total = gdbarch@dots{} (gdbarch);
5199 return data;
ba8c9337
AC
5200@}
5201@end smallexample
5202
5203@smallexample
fc989b7a
AC
5204extern int
5205nozel_total (struct gdbarch *gdbarch)
ba8c9337 5206@{
fc989b7a
AC
5207 struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
5208 return data->total;
ba8c9337
AC
5209@}
5210@end smallexample
5211
c906108c 5212@section Wrapping Output Lines
56caf160 5213@cindex line wrap in output
c906108c 5214
56caf160 5215@findex wrap_here
c906108c
SS
5216Output that goes through @code{printf_filtered} or @code{fputs_filtered}
5217or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
5218added in places that would be good breaking points. The utility
5219routines will take care of actually wrapping if the line width is
5220exceeded.
5221
5222The argument to @code{wrap_here} is an indentation string which is
5223printed @emph{only} if the line breaks there. This argument is saved
5224away and used later. It must remain valid until the next call to
5225@code{wrap_here} or until a newline has been printed through the
5226@code{*_filtered} functions. Don't pass in a local variable and then
5227return!
5228
56caf160 5229It is usually best to call @code{wrap_here} after printing a comma or
c906108c
SS
5230space. If you call it before printing a space, make sure that your
5231indentation properly accounts for the leading space that will print if
5232the line wraps there.
5233
5234Any function or set of functions that produce filtered output must
5235finish by printing a newline, to flush the wrap buffer, before switching
56caf160 5236to unfiltered (@code{printf}) output. Symbol reading routines that
c906108c
SS
5237print warnings are a good example.
5238
25822942 5239@section @value{GDBN} Coding Standards
56caf160 5240@cindex coding standards
c906108c 5241
25822942 5242@value{GDBN} follows the GNU coding standards, as described in
c906108c 5243@file{etc/standards.texi}. This file is also available for anonymous
af6c57ea
AC
5244FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
5245of the standard; in general, when the GNU standard recommends a practice
5246but does not require it, @value{GDBN} requires it.
c906108c 5247
56caf160
EZ
5248@value{GDBN} follows an additional set of coding standards specific to
5249@value{GDBN}, as described in the following sections.
c906108c 5250
af6c57ea 5251
b9aa90c9 5252@subsection ISO C
af6c57ea 5253
b9aa90c9
AC
5254@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
5255compiler.
af6c57ea 5256
b9aa90c9 5257@value{GDBN} does not assume an ISO C or POSIX compliant C library.
af6c57ea
AC
5258
5259
5260@subsection Memory Management
5261
5262@value{GDBN} does not use the functions @code{malloc}, @code{realloc},
5263@code{calloc}, @code{free} and @code{asprintf}.
5264
5265@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
5266@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
5267these functions do not return when the memory pool is empty. Instead,
5268they unwind the stack using cleanups. These functions return
5269@code{NULL} when requested to allocate a chunk of memory of size zero.
5270
5271@emph{Pragmatics: By using these functions, the need to check every
5272memory allocation is removed. These functions provide portable
5273behavior.}
5274
5275@value{GDBN} does not use the function @code{free}.
5276
5277@value{GDBN} uses the function @code{xfree} to return memory to the
5278memory pool. Consistent with ISO-C, this function ignores a request to
5279free a @code{NULL} pointer.
5280
5281@emph{Pragmatics: On some systems @code{free} fails when passed a
5282@code{NULL} pointer.}
5283
5284@value{GDBN} can use the non-portable function @code{alloca} for the
5285allocation of small temporary values (such as strings).
5286
5287@emph{Pragmatics: This function is very non-portable. Some systems
5288restrict the memory being allocated to no more than a few kilobytes.}
5289
5290@value{GDBN} uses the string function @code{xstrdup} and the print
b435e160 5291function @code{xstrprintf}.
af6c57ea
AC
5292
5293@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
5294functions such as @code{sprintf} are very prone to buffer overflow
5295errors.}
5296
5297
5298@subsection Compiler Warnings
56caf160 5299@cindex compiler warnings
af6c57ea 5300
aa79a185
DJ
5301With few exceptions, developers should avoid the configuration option
5302@samp{--disable-werror} when building @value{GDBN}. The exceptions
5303are listed in the file @file{gdb/MAINTAINERS}. The default, when
5304building with @sc{gcc}, is @samp{--enable-werror}.
af6c57ea
AC
5305
5306This option causes @value{GDBN} (when built using GCC) to be compiled
5307with a carefully selected list of compiler warning flags. Any warnings
aa79a185 5308from those flags are treated as errors.
af6c57ea
AC
5309
5310The current list of warning flags includes:
5311
5312@table @samp
aa79a185
DJ
5313@item -Wall
5314Recommended @sc{gcc} warnings.
af6c57ea 5315
aa79a185 5316@item -Wdeclaration-after-statement
af6c57ea 5317
aa79a185
DJ
5318@sc{gcc} 3.x (and later) and @sc{c99} allow declarations mixed with
5319code, but @sc{gcc} 2.x and @sc{c89} do not.
af6c57ea 5320
aa79a185 5321@item -Wpointer-arith
af6c57ea 5322
aa79a185
DJ
5323@item -Wformat-nonliteral
5324Non-literal format strings, with a few exceptions, are bugs - they
d3e8051b 5325might contain unintended user-supplied format specifiers.
af6c57ea 5326Since @value{GDBN} uses the @code{format printf} attribute on all
aa79a185 5327@code{printf} like functions this checks not just @code{printf} calls
af6c57ea
AC
5328but also calls to functions such as @code{fprintf_unfiltered}.
5329
7be93b9e
JB
5330@item -Wno-pointer-sign
5331In version 4.0, GCC began warning about pointer argument passing or
5332assignment even when the source and destination differed only in
5333signedness. However, most @value{GDBN} code doesn't distinguish
5334carefully between @code{char} and @code{unsigned char}. In early 2006
5335the @value{GDBN} developers decided correcting these warnings wasn't
5336worth the time it would take.
5337
aa79a185
DJ
5338@item -Wno-unused-parameter
5339Due to the way that @value{GDBN} is implemented many functions have
5340unused parameters. Consequently this warning is avoided. The macro
af6c57ea
AC
5341@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
5342it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
aa79a185
DJ
5343is being used.
5344
5345@item -Wno-unused
5346@itemx -Wno-switch
58b38ee2 5347@itemx -Wno-char-subscripts
aa79a185
DJ
5348These are warnings which might be useful for @value{GDBN}, but are
5349currently too noisy to enable with @samp{-Werror}.
af6c57ea 5350
aa79a185 5351@end table
c906108c
SS
5352
5353@subsection Formatting
5354
56caf160 5355@cindex source code formatting
c906108c
SS
5356The standard GNU recommendations for formatting must be followed
5357strictly.
5358
af6c57ea
AC
5359A function declaration should not have its name in column zero. A
5360function definition should have its name in column zero.
5361
474c8240 5362@smallexample
af6c57ea
AC
5363/* Declaration */
5364static void foo (void);
5365/* Definition */
5366void
5367foo (void)
5368@{
5369@}
474c8240 5370@end smallexample
af6c57ea
AC
5371
5372@emph{Pragmatics: This simplifies scripting. Function definitions can
5373be found using @samp{^function-name}.}
c906108c 5374
af6c57ea
AC
5375There must be a space between a function or macro name and the opening
5376parenthesis of its argument list (except for macro definitions, as
5377required by C). There must not be a space after an open paren/bracket
5378or before a close paren/bracket.
c906108c
SS
5379
5380While additional whitespace is generally helpful for reading, do not use
5381more than one blank line to separate blocks, and avoid adding whitespace
af6c57ea
AC
5382after the end of a program line (as of 1/99, some 600 lines had
5383whitespace after the semicolon). Excess whitespace causes difficulties
5384for @code{diff} and @code{patch} utilities.
5385
5386Pointers are declared using the traditional K&R C style:
5387
474c8240 5388@smallexample
af6c57ea 5389void *foo;
474c8240 5390@end smallexample
af6c57ea
AC
5391
5392@noindent
5393and not:
5394
474c8240 5395@smallexample
af6c57ea
AC
5396void * foo;
5397void* foo;
474c8240 5398@end smallexample
c906108c
SS
5399
5400@subsection Comments
5401
56caf160 5402@cindex comment formatting
c906108c
SS
5403The standard GNU requirements on comments must be followed strictly.
5404
af6c57ea
AC
5405Block comments must appear in the following form, with no @code{/*}- or
5406@code{*/}-only lines, and no leading @code{*}:
c906108c 5407
474c8240 5408@smallexample
c906108c
SS
5409/* Wait for control to return from inferior to debugger. If inferior
5410 gets a signal, we may decide to start it up again instead of
5411 returning. That is why there is a loop in this function. When
5412 this function actually returns it means the inferior should be left
25822942 5413 stopped and @value{GDBN} should read more commands. */
474c8240 5414@end smallexample
c906108c
SS
5415
5416(Note that this format is encouraged by Emacs; tabbing for a multi-line
56caf160 5417comment works correctly, and @kbd{M-q} fills the block consistently.)
c906108c
SS
5418
5419Put a blank line between the block comments preceding function or
5420variable definitions, and the definition itself.
5421
5422In general, put function-body comments on lines by themselves, rather
5423than trying to fit them into the 20 characters left at the end of a
5424line, since either the comment or the code will inevitably get longer
5425than will fit, and then somebody will have to move it anyhow.
5426
5427@subsection C Usage
5428
56caf160 5429@cindex C data types
c906108c
SS
5430Code must not depend on the sizes of C data types, the format of the
5431host's floating point numbers, the alignment of anything, or the order
5432of evaluation of expressions.
5433
56caf160 5434@cindex function usage
c906108c 5435Use functions freely. There are only a handful of compute-bound areas
56caf160
EZ
5436in @value{GDBN} that might be affected by the overhead of a function
5437call, mainly in symbol reading. Most of @value{GDBN}'s performance is
5438limited by the target interface (whether serial line or system call).
c906108c
SS
5439
5440However, use functions with moderation. A thousand one-line functions
5441are just as hard to understand as a single thousand-line function.
5442
af6c57ea 5443@emph{Macros are bad, M'kay.}
9e678452
CF
5444(But if you have to use a macro, make sure that the macro arguments are
5445protected with parentheses.)
af6c57ea
AC
5446
5447@cindex types
c906108c 5448
af6c57ea
AC
5449Declarations like @samp{struct foo *} should be used in preference to
5450declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
5451
5452
5453@subsection Function Prototypes
56caf160 5454@cindex function prototypes
af6c57ea
AC
5455
5456Prototypes must be used when both @emph{declaring} and @emph{defining}
5457a function. Prototypes for @value{GDBN} functions must include both the
5458argument type and name, with the name matching that used in the actual
5459function definition.
c906108c 5460
53a5351d
JM
5461All external functions should have a declaration in a header file that
5462callers include, except for @code{_initialize_*} functions, which must
5463be external so that @file{init.c} construction works, but shouldn't be
5464visible to random source files.
c906108c 5465
af6c57ea
AC
5466Where a source file needs a forward declaration of a static function,
5467that declaration must appear in a block near the top of the source file.
5468
5469
5470@subsection Internal Error Recovery
5471
5472During its execution, @value{GDBN} can encounter two types of errors.
5473User errors and internal errors. User errors include not only a user
5474entering an incorrect command but also problems arising from corrupt
5475object files and system errors when interacting with the target.
937f164b
FF
5476Internal errors include situations where @value{GDBN} has detected, at
5477run time, a corrupt or erroneous situation.
af6c57ea
AC
5478
5479When reporting an internal error, @value{GDBN} uses
5480@code{internal_error} and @code{gdb_assert}.
5481
5482@value{GDBN} must not call @code{abort} or @code{assert}.
5483
5484@emph{Pragmatics: There is no @code{internal_warning} function. Either
5485the code detected a user error, recovered from it and issued a
5486@code{warning} or the code failed to correctly recover from the user
5487error and issued an @code{internal_error}.}
5488
5489@subsection File Names
5490
5491Any file used when building the core of @value{GDBN} must be in lower
5492case. Any file used when building the core of @value{GDBN} must be 8.3
5493unique. These requirements apply to both source and generated files.
5494
5495@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
5496platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
5497is introduced to the build process both @file{Makefile.in} and
5498@file{configure.in} need to be modified accordingly. Compare the
5499convoluted conversion process needed to transform @file{COPYING} into
5500@file{copying.c} with the conversion needed to transform
5501@file{version.in} into @file{version.c}.}
5502
5503Any file non 8.3 compliant file (that is not used when building the core
5504of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
5505
5506@emph{Pragmatics: This is clearly a compromise.}
5507
5508When @value{GDBN} has a local version of a system header file (ex
5509@file{string.h}) the file name based on the POSIX header prefixed with
b4177fca
DJ
5510@file{gdb_} (@file{gdb_string.h}). These headers should be relatively
5511independent: they should use only macros defined by @file{configure},
5512the compiler, or the host; they should include only system headers; they
5513should refer only to system types. They may be shared between multiple
5514programs, e.g.@: @value{GDBN} and @sc{gdbserver}.
af6c57ea
AC
5515
5516For other files @samp{-} is used as the separator.
5517
5518
5519@subsection Include Files
5520
e2b28d04 5521A @file{.c} file should include @file{defs.h} first.
af6c57ea 5522
e2b28d04
AC
5523A @file{.c} file should directly include the @code{.h} file of every
5524declaration and/or definition it directly refers to. It cannot rely on
5525indirect inclusion.
af6c57ea 5526
e2b28d04
AC
5527A @file{.h} file should directly include the @code{.h} file of every
5528declaration and/or definition it directly refers to. It cannot rely on
5529indirect inclusion. Exception: The file @file{defs.h} does not need to
5530be directly included.
af6c57ea 5531
e2b28d04 5532An external declaration should only appear in one include file.
af6c57ea 5533
e2b28d04
AC
5534An external declaration should never appear in a @code{.c} file.
5535Exception: a declaration for the @code{_initialize} function that
5536pacifies @option{-Wmissing-declaration}.
5537
5538A @code{typedef} definition should only appear in one include file.
5539
5540An opaque @code{struct} declaration can appear in multiple @file{.h}
5541files. Where possible, a @file{.h} file should use an opaque
5542@code{struct} declaration instead of an include.
5543
5544All @file{.h} files should be wrapped in:
af6c57ea 5545
474c8240 5546@smallexample
af6c57ea
AC
5547#ifndef INCLUDE_FILE_NAME_H
5548#define INCLUDE_FILE_NAME_H
5549header body
5550#endif
474c8240 5551@end smallexample
af6c57ea 5552
c906108c 5553
dab11f21 5554@subsection Clean Design and Portable Implementation
c906108c 5555
56caf160 5556@cindex design
c906108c 5557In addition to getting the syntax right, there's the little question of
25822942 5558semantics. Some things are done in certain ways in @value{GDBN} because long
c906108c
SS
5559experience has shown that the more obvious ways caused various kinds of
5560trouble.
5561
56caf160 5562@cindex assumptions about targets
c906108c
SS
5563You can't assume the byte order of anything that comes from a target
5564(including @var{value}s, object files, and instructions). Such things
56caf160
EZ
5565must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
5566@value{GDBN}, or one of the swap routines defined in @file{bfd.h},
5567such as @code{bfd_get_32}.
c906108c
SS
5568
5569You can't assume that you know what interface is being used to talk to
5570the target system. All references to the target must go through the
5571current @code{target_ops} vector.
5572
5573You can't assume that the host and target machines are the same machine
5574(except in the ``native'' support modules). In particular, you can't
5575assume that the target machine's header files will be available on the
5576host machine. Target code must bring along its own header files --
5577written from scratch or explicitly donated by their owner, to avoid
5578copyright problems.
5579
56caf160 5580@cindex portability
c906108c
SS
5581Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
5582to write the code portably than to conditionalize it for various
5583systems.
5584
56caf160 5585@cindex system dependencies
c906108c
SS
5586New @code{#ifdef}'s which test for specific compilers or manufacturers
5587or operating systems are unacceptable. All @code{#ifdef}'s should test
5588for features. The information about which configurations contain which
5589features should be segregated into the configuration files. Experience
5590has proven far too often that a feature unique to one particular system
5591often creeps into other systems; and that a conditional based on some
5592predefined macro for your current system will become worthless over
5593time, as new versions of your system come out that behave differently
5594with regard to this feature.
5595
5596Adding code that handles specific architectures, operating systems,
af6c57ea 5597target interfaces, or hosts, is not acceptable in generic code.
c906108c 5598
dab11f21
EZ
5599@cindex portable file name handling
5600@cindex file names, portability
5601One particularly notorious area where system dependencies tend to
5602creep in is handling of file names. The mainline @value{GDBN} code
5603assumes Posix semantics of file names: absolute file names begin with
5604a forward slash @file{/}, slashes are used to separate leading
5605directories, case-sensitive file names. These assumptions are not
5606necessarily true on non-Posix systems such as MS-Windows. To avoid
5607system-dependent code where you need to take apart or construct a file
5608name, use the following portable macros:
5609
5610@table @code
5611@findex HAVE_DOS_BASED_FILE_SYSTEM
5612@item HAVE_DOS_BASED_FILE_SYSTEM
5613This preprocessing symbol is defined to a non-zero value on hosts
5614whose filesystems belong to the MS-DOS/MS-Windows family. Use this
5615symbol to write conditional code which should only be compiled for
5616such hosts.
5617
5618@findex IS_DIR_SEPARATOR
4be31470 5619@item IS_DIR_SEPARATOR (@var{c})
dab11f21
EZ
5620Evaluates to a non-zero value if @var{c} is a directory separator
5621character. On Unix and GNU/Linux systems, only a slash @file{/} is
5622such a character, but on Windows, both @file{/} and @file{\} will
5623pass.
5624
5625@findex IS_ABSOLUTE_PATH
5626@item IS_ABSOLUTE_PATH (@var{file})
5627Evaluates to a non-zero value if @var{file} is an absolute file name.
5628For Unix and GNU/Linux hosts, a name which begins with a slash
5629@file{/} is absolute. On DOS and Windows, @file{d:/foo} and
5630@file{x:\bar} are also absolute file names.
5631
5632@findex FILENAME_CMP
5633@item FILENAME_CMP (@var{f1}, @var{f2})
5634Calls a function which compares file names @var{f1} and @var{f2} as
5635appropriate for the underlying host filesystem. For Posix systems,
5636this simply calls @code{strcmp}; on case-insensitive filesystems it
5637will call @code{strcasecmp} instead.
5638
5639@findex DIRNAME_SEPARATOR
5640@item DIRNAME_SEPARATOR
5641Evaluates to a character which separates directories in
5642@code{PATH}-style lists, typically held in environment variables.
5643This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
5644
5645@findex SLASH_STRING
5646@item SLASH_STRING
5647This evaluates to a constant string you should use to produce an
5648absolute filename from leading directories and the file's basename.
5649@code{SLASH_STRING} is @code{"/"} on most systems, but might be
5650@code{"\\"} for some Windows-based ports.
5651@end table
5652
5653In addition to using these macros, be sure to use portable library
5654functions whenever possible. For example, to extract a directory or a
5655basename part from a file name, use the @code{dirname} and
5656@code{basename} library functions (available in @code{libiberty} for
5657platforms which don't provide them), instead of searching for a slash
5658with @code{strrchr}.
5659
25822942
DB
5660Another way to generalize @value{GDBN} along a particular interface is with an
5661attribute struct. For example, @value{GDBN} has been generalized to handle
56caf160
EZ
5662multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
5663by defining the @code{target_ops} structure and having a current target (as
c906108c
SS
5664well as a stack of targets below it, for memory references). Whenever
5665something needs to be done that depends on which remote interface we are
56caf160
EZ
5666using, a flag in the current target_ops structure is tested (e.g.,
5667@code{target_has_stack}), or a function is called through a pointer in the
c906108c 5668current target_ops structure. In this way, when a new remote interface
56caf160 5669is added, only one module needs to be touched---the one that actually
c906108c
SS
5670implements the new remote interface. Other examples of
5671attribute-structs are BFD access to multiple kinds of object file
25822942 5672formats, or @value{GDBN}'s access to multiple source languages.
c906108c 5673
56caf160
EZ
5674Please avoid duplicating code. For example, in @value{GDBN} 3.x all
5675the code interfacing between @code{ptrace} and the rest of
5676@value{GDBN} was duplicated in @file{*-dep.c}, and so changing
5677something was very painful. In @value{GDBN} 4.x, these have all been
5678consolidated into @file{infptrace.c}. @file{infptrace.c} can deal
5679with variations between systems the same way any system-independent
5680file would (hooks, @code{#if defined}, etc.), and machines which are
5681radically different don't need to use @file{infptrace.c} at all.
c906108c 5682
af6c57ea
AC
5683All debugging code must be controllable using the @samp{set debug
5684@var{module}} command. Do not use @code{printf} to print trace
5685messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
5686@code{#ifdef DEBUG}.
5687
c906108c 5688
8487521e 5689@node Porting GDB
c906108c 5690
25822942 5691@chapter Porting @value{GDBN}
56caf160 5692@cindex porting to new machines
c906108c 5693
56caf160
EZ
5694Most of the work in making @value{GDBN} compile on a new machine is in
5695specifying the configuration of the machine. This is done in a
5696dizzying variety of header files and configuration scripts, which we
5697hope to make more sensible soon. Let's say your new host is called an
5698@var{xyz} (e.g., @samp{sun4}), and its full three-part configuration
5699name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g.,
5700@samp{sparc-sun-sunos4}). In particular:
c906108c 5701
56caf160
EZ
5702@itemize @bullet
5703@item
c906108c
SS
5704In the top level directory, edit @file{config.sub} and add @var{arch},
5705@var{xvend}, and @var{xos} to the lists of supported architectures,
5706vendors, and operating systems near the bottom of the file. Also, add
5707@var{xyz} as an alias that maps to
5708@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
5709running
5710
474c8240 5711@smallexample
c906108c 5712./config.sub @var{xyz}
474c8240 5713@end smallexample
56caf160 5714
c906108c
SS
5715@noindent
5716and
56caf160 5717
474c8240 5718@smallexample
c906108c 5719./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
474c8240 5720@end smallexample
56caf160 5721
c906108c
SS
5722@noindent
5723which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
5724and no error messages.
5725
56caf160 5726@noindent
c906108c
SS
5727You need to port BFD, if that hasn't been done already. Porting BFD is
5728beyond the scope of this manual.
5729
56caf160 5730@item
25822942 5731To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
c906108c
SS
5732your system and set @code{gdb_host} to @var{xyz}, and (unless your
5733desired target is already available) also edit @file{gdb/configure.tgt},
5734setting @code{gdb_target} to something appropriate (for instance,
5735@var{xyz}).
5736
7fd60527
AC
5737@emph{Maintainer's note: Work in progress. The file
5738@file{gdb/configure.host} originally needed to be modified when either a
5739new native target or a new host machine was being added to @value{GDBN}.
5740Recent changes have removed this requirement. The file now only needs
5741to be modified when adding a new native configuration. This will likely
5742changed again in the future.}
5743
56caf160 5744@item
25822942 5745Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
c906108c
SS
5746target-dependent @file{.h} and @file{.c} files used for your
5747configuration.
56caf160 5748@end itemize
c906108c 5749
d52fe014
AC
5750@node Versions and Branches
5751@chapter Versions and Branches
8973da3a 5752
d52fe014 5753@section Versions
8973da3a 5754
d52fe014
AC
5755@value{GDBN}'s version is determined by the file
5756@file{gdb/version.in} and takes one of the following forms:
fb0ff88f 5757
d52fe014
AC
5758@table @asis
5759@item @var{major}.@var{minor}
5760@itemx @var{major}.@var{minor}.@var{patchlevel}
53531fc1
AC
5761an official release (e.g., 6.2 or 6.2.1)
5762@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}
5763a snapshot taken at @var{YYYY}-@var{MM}-@var{DD}-gmt (e.g.,
57646.1.50.20020302, 6.1.90.20020304, or 6.1.0.20020308)
5765@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}-cvs
5766a @sc{cvs} check out drawn on @var{YYYY}-@var{MM}-@var{DD} (e.g.,
57676.1.50.20020302-cvs, 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
5768@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} (@var{vendor})
d52fe014 5769a vendor specific release of @value{GDBN}, that while based on@*
53531fc1
AC
5770@var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD},
5771may include additional changes
d52fe014 5772@end table
fb0ff88f 5773
d52fe014
AC
5774@value{GDBN}'s mainline uses the @var{major} and @var{minor} version
5775numbers from the most recent release branch, with a @var{patchlevel}
53531fc1
AC
5776of 50. At the time each new release branch is created, the mainline's
5777@var{major} and @var{minor} version numbers are updated.
fb0ff88f 5778
53531fc1
AC
5779@value{GDBN}'s release branch is similar. When the branch is cut, the
5780@var{patchlevel} is changed from 50 to 90. As draft releases are
5781drawn from the branch, the @var{patchlevel} is incremented. Once the
5782first release (@var{major}.@var{minor}) has been made, the
5783@var{patchlevel} is set to 0 and updates have an incremented
5784@var{patchlevel}.
5785
5786For snapshots, and @sc{cvs} check outs, it is also possible to
5787identify the @sc{cvs} origin:
5788
5789@table @asis
5790@item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD}
5791drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302)
5792@item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD}
5793@itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{}
5794drawn from a release branch prior to the release (e.g.,
57956.1.90.20020304)
5796@item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD}
5797@itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{}
5798drawn from a release branch after the release (e.g., 6.2.0.20020308)
5799@end table
fb0ff88f 5800
d52fe014
AC
5801If the previous @value{GDBN} version is 6.1 and the current version is
58026.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor},
5803here's an illustration of a typical sequence:
fb0ff88f 5804
d52fe014
AC
5805@smallexample
5806 <HEAD>
5807 |
53531fc1 58086.1.50.20020302-cvs
d52fe014 5809 |
53531fc1 5810 +--------------------------.
d52fe014 5811 | <gdb_6_2-branch>
d52fe014 5812 | |
53531fc1
AC
58136.2.50.20020303-cvs 6.1.90 (draft #1)
5814 | |
58156.2.50.20020304-cvs 6.1.90.20020304-cvs
5816 | |
58176.2.50.20020305-cvs 6.1.91 (draft #2)
d52fe014 5818 | |
53531fc1
AC
58196.2.50.20020306-cvs 6.1.91.20020306-cvs
5820 | |
58216.2.50.20020307-cvs 6.2 (release)
5822 | |
58236.2.50.20020308-cvs 6.2.0.20020308-cvs
5824 | |
58256.2.50.20020309-cvs 6.2.1 (update)
5826 | |
58276.2.50.20020310-cvs <branch closed>
d52fe014 5828 |
53531fc1 58296.2.50.20020311-cvs
d52fe014 5830 |
53531fc1 5831 +--------------------------.
d52fe014 5832 | <gdb_6_3-branch>
53531fc1
AC
5833 | |
58346.3.50.20020312-cvs 6.2.90 (draft #1)
5835 | |
d52fe014 5836@end smallexample
fb0ff88f 5837
d52fe014
AC
5838@section Release Branches
5839@cindex Release Branches
fb0ff88f 5840
d52fe014
AC
5841@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a
5842single release branch, and identifies that branch using the @sc{cvs}
5843branch tags:
fb0ff88f 5844
d52fe014
AC
5845@smallexample
5846gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint
5847gdb_@var{major}_@var{minor}-branch
5848gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release
5849@end smallexample
5850
5851@emph{Pragmatics: To help identify the date at which a branch or
5852release is made, both the branchpoint and release tags include the
5853date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The
5854branch tag, denoting the head of the branch, does not need this.}
5855
5856@section Vendor Branches
5857@cindex vendor branches
fb0ff88f
AC
5858
5859To avoid version conflicts, vendors are expected to modify the file
5860@file{gdb/version.in} to include a vendor unique alphabetic identifier
5861(an official @value{GDBN} release never uses alphabetic characters in
d3e8051b 5862its version identifier). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit
d52fe014
AC
5863Inc Patch 2)}.
5864
5865@section Experimental Branches
5866@cindex experimental branches
5867
5868@subsection Guidelines
5869
5870@value{GDBN} permits the creation of branches, cut from the @sc{cvs}
5871repository, for experimental development. Branches make it possible
5872for developers to share preliminary work, and maintainers to examine
5873significant new developments.
fb0ff88f 5874
d52fe014 5875The following are a set of guidelines for creating such branches:
fb0ff88f 5876
d52fe014
AC
5877@table @emph
5878
5879@item a branch has an owner
5880The owner can set further policy for a branch, but may not change the
5881ground rules. In particular, they can set a policy for commits (be it
5882adding more reviewers or deciding who can commit).
5883
5884@item all commits are posted
5885All changes committed to a branch shall also be posted to
5886@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches
5887mailing list}. While commentary on such changes are encouraged, people
5888should remember that the changes only apply to a branch.
5889
5890@item all commits are covered by an assignment
5891This ensures that all changes belong to the Free Software Foundation,
5892and avoids the possibility that the branch may become contaminated.
5893
5894@item a branch is focused
5895A focused branch has a single objective or goal, and does not contain
5896unnecessary or irrelevant changes. Cleanups, where identified, being
5897be pushed into the mainline as soon as possible.
5898
5899@item a branch tracks mainline
5900This keeps the level of divergence under control. It also keeps the
5901pressure on developers to push cleanups and other stuff into the
5902mainline.
5903
5904@item a branch shall contain the entire @value{GDBN} module
5905The @value{GDBN} module @code{gdb} should be specified when creating a
5906branch (branches of individual files should be avoided). @xref{Tags}.
5907
5908@item a branch shall be branded using @file{version.in}
5909The file @file{gdb/version.in} shall be modified so that it identifies
5910the branch @var{owner} and branch @var{name}, e.g.,
53531fc1 5911@samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}.
d52fe014
AC
5912
5913@end table
fb0ff88f 5914
d52fe014
AC
5915@subsection Tags
5916@anchor{Tags}
fb0ff88f 5917
d52fe014
AC
5918To simplify the identification of @value{GDBN} branches, the following
5919branch tagging convention is strongly recommended:
fb0ff88f 5920
d52fe014 5921@table @code
fb0ff88f 5922
d52fe014
AC
5923@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
5924@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch
5925The branch point and corresponding branch tag. @var{YYYYMMDD} is the
5926date that the branch was created. A branch is created using the
5927sequence: @anchor{experimental branch tags}
474c8240 5928@smallexample
d52fe014
AC
5929cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb
5930cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
5931 @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb
474c8240 5932@end smallexample
fb0ff88f 5933
d52fe014
AC
5934@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
5935The tagged point, on the mainline, that was used when merging the branch
5936on @var{yyyymmdd}. To merge in all changes since the branch was cut,
5937use a command sequence like:
474c8240 5938@smallexample
d52fe014
AC
5939cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb
5940cvs update \
5941 -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
5942 -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
474c8240 5943@end smallexample
d52fe014
AC
5944@noindent
5945Similar sequences can be used to just merge in changes since the last
5946merge.
5947
5948@end table
fb0ff88f 5949
d52fe014
AC
5950@noindent
5951For further information on @sc{cvs}, see
5952@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
5953
55f6ca0f
JB
5954@node Start of New Year Procedure
5955@chapter Start of New Year Procedure
5956@cindex new year procedure
5957
5958At the start of each new year, the following actions should be performed:
5959
5960@itemize @bullet
5961@item
5962Rotate the ChangeLog file
5963
5964The current @file{ChangeLog} file should be renamed into
5965@file{ChangeLog-YYYY} where YYYY is the year that has just passed.
5966A new @file{ChangeLog} file should be created, and its contents should
5967contain a reference to the previous ChangeLog. The following should
5968also be preserved at the end of the new ChangeLog, in order to provide
5969the appropriate settings when editing this file with Emacs:
5970@smallexample
5971Local Variables:
5972mode: change-log
5973left-margin: 8
5974fill-column: 74
5975version-control: never
5976End:
5977@end smallexample
5978
7f893741
JB
5979@item
5980Add an entry for the newly created ChangeLog file (@file{ChangeLog-YYYY})
5981in @file{gdb/config/djgpp/fnchange.lst}.
5982
55f6ca0f
JB
5983@item
5984Update the copyright year in the startup message
5985
5986Update the copyright year in file @file{top.c}, function
5987@code{print_gdb_version}.
6ec2edbe
JB
5988
5989@item
5990Add the new year in the copyright notices of all source and documentation
5991files. This can be done semi-automatically by running the @code{copyright.sh}
5992script. This script requires Emacs 22 or later to be installed.
5993
55f6ca0f
JB
5994@end itemize
5995
d52fe014 5996@node Releasing GDB
fb0ff88f 5997
d52fe014
AC
5998@chapter Releasing @value{GDBN}
5999@cindex making a new release of gdb
fb0ff88f 6000
9bb0a4d8
AC
6001@section Branch Commit Policy
6002
6003The branch commit policy is pretty slack. @value{GDBN} releases 5.0,
60045.1 and 5.2 all used the below:
6005
6006@itemize @bullet
6007@item
6008The @file{gdb/MAINTAINERS} file still holds.
6009@item
6010Don't fix something on the branch unless/until it is also fixed in the
6011trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}
4be31470 6012file is better than committing a hack.
9bb0a4d8
AC
6013@item
6014When considering a patch for the branch, suggested criteria include:
6015Does it fix a build? Does it fix the sequence @kbd{break main; run}
6016when debugging a static binary?
6017@item
6018The further a change is from the core of @value{GDBN}, the less likely
6019the change will worry anyone (e.g., target specific code).
6020@item
6021Only post a proposal to change the core of @value{GDBN} after you've
6022sent individual bribes to all the people listed in the
6023@file{MAINTAINERS} file @t{;-)}
6024@end itemize
6025
6026@emph{Pragmatics: Provided updates are restricted to non-core
6027functionality there is little chance that a broken change will be fatal.
6028This means that changes such as adding a new architectures or (within
6029reason) support for a new host are considered acceptable.}
6030
6031
cbb09e6a 6032@section Obsoleting code
8973da3a 6033
8642bc8f 6034Before anything else, poke the other developers (and around the source
4be31470
EZ
6035code) to see if there is anything that can be removed from @value{GDBN}
6036(an old target, an unused file).
8973da3a 6037
8642bc8f 6038Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
cbb09e6a
AC
6039line. Doing this means that it is easy to identify something that has
6040been obsoleted when greping through the sources.
8973da3a 6041
cbb09e6a
AC
6042The process is done in stages --- this is mainly to ensure that the
6043wider @value{GDBN} community has a reasonable opportunity to respond.
6044Remember, everything on the Internet takes a week.
8973da3a 6045
cbb09e6a 6046@enumerate
8973da3a 6047@item
cbb09e6a
AC
6048Post the proposal on @email{gdb@@sources.redhat.com, the GDB mailing
6049list} Creating a bug report to track the task's state, is also highly
6050recommended.
8973da3a 6051@item
cbb09e6a 6052Wait a week or so.
8973da3a 6053@item
cbb09e6a
AC
6054Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB
6055Announcement mailing list}.
8973da3a 6056@item
cbb09e6a 6057Wait a week or so.
8973da3a 6058@item
cbb09e6a
AC
6059Go through and edit all relevant files and lines so that they are
6060prefixed with the word @code{OBSOLETE}.
6061@item
6062Wait until the next GDB version, containing this obsolete code, has been
6063released.
6064@item
6065Remove the obsolete code.
6066@end enumerate
6067
6068@noindent
6069@emph{Maintainer note: While removing old code is regrettable it is
6070hopefully better for @value{GDBN}'s long term development. Firstly it
6071helps the developers by removing code that is either no longer relevant
6072or simply wrong. Secondly since it removes any history associated with
6073the file (effectively clearing the slate) the developer has a much freer
6074hand when it comes to fixing broken files.}
8973da3a 6075
8973da3a 6076
9ae8b82c
AC
6077
6078@section Before the Branch
8973da3a 6079
8642bc8f
AC
6080The most important objective at this stage is to find and fix simple
6081changes that become a pain to track once the branch is created. For
6082instance, configuration problems that stop @value{GDBN} from even
6083building. If you can't get the problem fixed, document it in the
6084@file{gdb/PROBLEMS} file.
8973da3a 6085
9ae8b82c 6086@subheading Prompt for @file{gdb/NEWS}
8973da3a 6087
9ae8b82c
AC
6088People always forget. Send a post reminding them but also if you know
6089something interesting happened add it yourself. The @code{schedule}
6090script will mention this in its e-mail.
8973da3a 6091
9ae8b82c 6092@subheading Review @file{gdb/README}
8973da3a 6093
9ae8b82c
AC
6094Grab one of the nightly snapshots and then walk through the
6095@file{gdb/README} looking for anything that can be improved. The
6096@code{schedule} script will mention this in its e-mail.
8642bc8f
AC
6097
6098@subheading Refresh any imported files.
8973da3a 6099
8642bc8f 6100A number of files are taken from external repositories. They include:
8973da3a 6101
8642bc8f
AC
6102@itemize @bullet
6103@item
6104@file{texinfo/texinfo.tex}
6105@item
9ae8b82c
AC
6106@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}
6107file)
6108@item
6109@file{etc/standards.texi}, @file{etc/make-stds.texi}
8642bc8f
AC
6110@end itemize
6111
9ae8b82c 6112@subheading Check the ARI
8642bc8f 6113
9ae8b82c
AC
6114@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script
6115(Awk Regression Index ;-) that checks for a number of errors and coding
6116conventions. The checks include things like using @code{malloc} instead
6117of @code{xmalloc} and file naming problems. There shouldn't be any
6118regressions.
8642bc8f 6119
9ae8b82c 6120@subsection Review the bug data base
8642bc8f 6121
9ae8b82c 6122Close anything obviously fixed.
8642bc8f 6123
9ae8b82c 6124@subsection Check all cross targets build
8642bc8f 6125
9ae8b82c 6126The targets are listed in @file{gdb/MAINTAINERS}.
8642bc8f 6127
8642bc8f 6128
30107679 6129@section Cut the Branch
8642bc8f 6130
30107679 6131@subheading Create the branch
8642bc8f 6132
474c8240 6133@smallexample
30107679
AC
6134$ u=5.1
6135$ v=5.2
6136$ V=`echo $v | sed 's/\./_/g'`
6137$ D=`date -u +%Y-%m-%d`
6138$ echo $u $V $D
61395.1 5_2 2002-03-03
6140$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
b247355e 6141-D $D-gmt gdb_$V-$D-branchpoint insight
30107679 6142cvs -f -d :ext:sources.redhat.com:/cvs/src rtag
b247355e 6143-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
30107679
AC
6144$ ^echo ^^
6145...
6146$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
b247355e 6147-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
30107679 6148cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
b247355e 6149-b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
30107679
AC
6150$ ^echo ^^
6151...
8642bc8f 6152$
474c8240 6153@end smallexample
8642bc8f
AC
6154
6155@itemize @bullet
6156@item
b247355e 6157By using @kbd{-D YYYY-MM-DD-gmt}, the branch is forced to an exact
30107679
AC
6158date/time.
6159@item
b247355e 6160The trunk is first tagged so that the branch point can easily be found.
30107679 6161@item
b247355e 6162Insight, which includes @value{GDBN}, is tagged at the same time.
8642bc8f 6163@item
b247355e 6164@file{version.in} gets bumped to avoid version number conflicts.
8642bc8f 6165@item
b247355e 6166The reading of @file{.cvsrc} is disabled using @file{-f}.
30107679
AC
6167@end itemize
6168
6169@subheading Update @file{version.in}
6170
6171@smallexample
6172$ u=5.1
6173$ v=5.2
6174$ V=`echo $v | sed 's/\./_/g'`
6175$ echo $u $v$V
61765.1 5_2
6177$ cd /tmp
6178$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \
6179-r gdb_$V-branch src/gdb/version.in
6180cvs -f -d :ext:sources.redhat.com:/cvs/src co
6181 -r gdb_5_2-branch src/gdb/version.in
6182$ ^echo ^^
6183U src/gdb/version.in
6184$ cd src/gdb
6185$ echo $u.90-0000-00-00-cvs > version.in
6186$ cat version.in
61875.1.90-0000-00-00-cvs
6188$ cvs -f commit version.in
6189@end smallexample
6190
6191@itemize @bullet
6192@item
6193@file{0000-00-00} is used as a date to pump prime the version.in update
b247355e 6194mechanism.
30107679
AC
6195@item
6196@file{.90} and the previous branch version are used as fairly arbitrary
b247355e 6197initial branch version number.
8642bc8f
AC
6198@end itemize
6199
8642bc8f
AC
6200
6201@subheading Update the web and news pages
6202
30107679
AC
6203Something?
6204
8642bc8f
AC
6205@subheading Tweak cron to track the new branch
6206
30107679
AC
6207The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table.
6208This file needs to be updated so that:
6209
6210@itemize @bullet
6211@item
b247355e 6212A daily timestamp is added to the file @file{version.in}.
30107679 6213@item
b247355e 6214The new branch is included in the snapshot process.
30107679
AC
6215@end itemize
6216
6217@noindent
6218See the file @file{gdbadmin/cron/README} for how to install the updated
6219cron table.
6220
6221The file @file{gdbadmin/ss/README} should also be reviewed to reflect
6222any changes. That file is copied to both the branch/ and current/
6223snapshot directories.
6224
6225
6226@subheading Update the NEWS and README files
6227
6228The @file{NEWS} file needs to be updated so that on the branch it refers
6229to @emph{changes in the current release} while on the trunk it also
6230refers to @emph{changes since the current release}.
6231
6232The @file{README} file needs to be updated so that it refers to the
6233current release.
6234
6235@subheading Post the branch info
6236
6237Send an announcement to the mailing lists:
6238
6239@itemize @bullet
6240@item
6241@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
6242@item
d3e8051b
EZ
6243@email{gdb@@sources.redhat.com, GDB Discussion mailing list} and
6244@email{gdb-testers@@sources.redhat.com, GDB Testers mailing list}
16737d73 6245@end itemize
30107679
AC
6246
6247@emph{Pragmatics: The branch creation is sent to the announce list to
6248ensure that people people not subscribed to the higher volume discussion
6249list are alerted.}
6250
6251The announcement should include:
6252
6253@itemize @bullet
6254@item
b247355e 6255The branch tag.
30107679 6256@item
b247355e 6257How to check out the branch using CVS.
30107679 6258@item
b247355e 6259The date/number of weeks until the release.
30107679 6260@item
b247355e 6261The branch commit policy still holds.
16737d73 6262@end itemize
30107679 6263
8642bc8f
AC
6264@section Stabilize the branch
6265
6266Something goes here.
6267
6268@section Create a Release
6269
0816590b
AC
6270The process of creating and then making available a release is broken
6271down into a number of stages. The first part addresses the technical
6272process of creating a releasable tar ball. The later stages address the
6273process of releasing that tar ball.
8973da3a 6274
0816590b
AC
6275When making a release candidate just the first section is needed.
6276
6277@subsection Create a release candidate
6278
6279The objective at this stage is to create a set of tar balls that can be
6280made available as a formal release (or as a less formal release
6281candidate).
6282
6283@subsubheading Freeze the branch
6284
6285Send out an e-mail notifying everyone that the branch is frozen to
6286@email{gdb-patches@@sources.redhat.com}.
6287
6288@subsubheading Establish a few defaults.
8973da3a 6289
474c8240 6290@smallexample
0816590b
AC
6291$ b=gdb_5_2-branch
6292$ v=5.2
8642bc8f
AC
6293$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
6294$ echo $t/$b/$v
0816590b 6295/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
8642bc8f
AC
6296$ mkdir -p $t/$b/$v
6297$ cd $t/$b/$v
6298$ pwd
0816590b 6299/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
8973da3a
AC
6300$ which autoconf
6301/home/gdbadmin/bin/autoconf
8642bc8f 6302$
474c8240 6303@end smallexample
8973da3a 6304
0816590b
AC
6305@noindent
6306Notes:
8973da3a 6307
0816590b
AC
6308@itemize @bullet
6309@item
6310Check the @code{autoconf} version carefully. You want to be using the
4a2b4636
JB
6311version taken from the @file{binutils} snapshot directory, which can be
6312found at @uref{ftp://sources.redhat.com/pub/binutils/}. It is very
0816590b
AC
6313unlikely that a system installed version of @code{autoconf} (e.g.,
6314@file{/usr/bin/autoconf}) is correct.
6315@end itemize
6316
6317@subsubheading Check out the relevant modules:
8973da3a 6318
474c8240 6319@smallexample
b247355e 6320$ for m in gdb insight
8642bc8f 6321do
8973da3a
AC
6322( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
6323done
8642bc8f 6324$
474c8240 6325@end smallexample
8973da3a 6326
0816590b
AC
6327@noindent
6328Note:
8642bc8f 6329
0816590b
AC
6330@itemize @bullet
6331@item
6332The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't
6333any confusion between what is written here and what your local
6334@code{cvs} really does.
6335@end itemize
6336
6337@subsubheading Update relevant files.
8973da3a 6338
0816590b
AC
6339@table @file
6340
6341@item gdb/NEWS
8642bc8f
AC
6342
6343Major releases get their comments added as part of the mainline. Minor
6344releases should probably mention any significant bugs that were fixed.
6345
0816590b 6346Don't forget to include the @file{ChangeLog} entry.
8973da3a 6347
474c8240 6348@smallexample
8642bc8f
AC
6349$ emacs gdb/src/gdb/NEWS
6350...
6351c-x 4 a
6352...
6353c-x c-s c-x c-c
6354$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
6355$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
474c8240 6356@end smallexample
8973da3a 6357
0816590b
AC
6358@item gdb/README
6359
6360You'll need to update:
8973da3a 6361
0816590b
AC
6362@itemize @bullet
6363@item
b247355e 6364The version.
0816590b 6365@item
b247355e 6366The update date.
0816590b 6367@item
b247355e 6368Who did it.
0816590b 6369@end itemize
8973da3a 6370
474c8240 6371@smallexample
8642bc8f
AC
6372$ emacs gdb/src/gdb/README
6373...
8973da3a 6374c-x 4 a
8642bc8f 6375...
8973da3a 6376c-x c-s c-x c-c
8642bc8f
AC
6377$ cp gdb/src/gdb/README insight/src/gdb/README
6378$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
474c8240 6379@end smallexample
8973da3a 6380
0816590b
AC
6381@emph{Maintainer note: Hopefully the @file{README} file was reviewed
6382before the initial branch was cut so just a simple substitute is needed
6383to get it updated.}
8973da3a 6384
8642bc8f
AC
6385@emph{Maintainer note: Other projects generate @file{README} and
6386@file{INSTALL} from the core documentation. This might be worth
6387pursuing.}
8973da3a 6388
0816590b 6389@item gdb/version.in
8973da3a 6390
474c8240 6391@smallexample
8642bc8f 6392$ echo $v > gdb/src/gdb/version.in
0816590b
AC
6393$ cat gdb/src/gdb/version.in
63945.2
8642bc8f 6395$ emacs gdb/src/gdb/version.in
8973da3a
AC
6396...
6397c-x 4 a
0816590b 6398... Bump to version ...
8973da3a 6399c-x c-s c-x c-c
8642bc8f
AC
6400$ cp gdb/src/gdb/version.in insight/src/gdb/version.in
6401$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
474c8240 6402@end smallexample
8973da3a 6403
0816590b
AC
6404@end table
6405
6406@subsubheading Do the dirty work
6407
6408This is identical to the process used to create the daily snapshot.
8973da3a 6409
4ce8657e
MC
6410@smallexample
6411$ for m in gdb insight
6412do
6413( cd $m/src && gmake -f src-release $m.tar )
6414done
4ce8657e
MC
6415@end smallexample
6416
6417If the top level source directory does not have @file{src-release}
6418(@value{GDBN} version 5.3.1 or earlier), try these commands instead:
6419
474c8240 6420@smallexample
0816590b 6421$ for m in gdb insight
8642bc8f 6422do
0816590b 6423( cd $m/src && gmake -f Makefile.in $m.tar )
8973da3a 6424done
474c8240 6425@end smallexample
8973da3a 6426
0816590b 6427@subsubheading Check the source files
8642bc8f 6428
0816590b 6429You're looking for files that have mysteriously disappeared.
8642bc8f
AC
6430@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
6431for the @file{version.in} update @kbd{cronjob}.
8973da3a 6432
474c8240 6433@smallexample
8642bc8f
AC
6434$ ( cd gdb/src && cvs -f -q -n update )
6435M djunpack.bat
0816590b 6436? gdb-5.1.91.tar
8642bc8f 6437? proto-toplev
0816590b 6438@dots{} lots of generated files @dots{}
8642bc8f
AC
6439M gdb/ChangeLog
6440M gdb/NEWS
6441M gdb/README
6442M gdb/version.in
0816590b 6443@dots{} lots of generated files @dots{}
8642bc8f 6444$
474c8240 6445@end smallexample
8973da3a 6446
0816590b 6447@noindent
8642bc8f
AC
6448@emph{Don't worry about the @file{gdb.info-??} or
6449@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1}
6450was also generated only something strange with CVS means that they
d3e8051b 6451didn't get suppressed). Fixing it would be nice though.}
8973da3a 6452
0816590b 6453@subsubheading Create compressed versions of the release
8973da3a 6454
474c8240 6455@smallexample
0816590b
AC
6456$ cp */src/*.tar .
6457$ cp */src/*.bz2 .
6458$ ls -F
b247355e 6459gdb/ gdb-5.2.tar insight/ insight-5.2.tar
0816590b
AC
6460$ for m in gdb insight
6461do
6462bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
6463gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
6464done
6465$
474c8240 6466@end smallexample
8973da3a 6467
0816590b
AC
6468@noindent
6469Note:
6470
6471@itemize @bullet
6472@item
6473A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since,
6474in that mode, @code{gzip} does not know the name of the file and, hence,
6475can not include it in the compressed file. This is also why the release
6476process runs @code{tar} and @code{bzip2} as separate passes.
6477@end itemize
6478
6479@subsection Sanity check the tar ball
8973da3a 6480
0816590b 6481Pick a popular machine (Solaris/PPC?) and try the build on that.
8973da3a 6482
0816590b
AC
6483@smallexample
6484$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
6485$ cd gdb-5.2
6486$ ./configure
6487$ make
6488@dots{}
6489$ ./gdb/gdb ./gdb/gdb
6490GNU gdb 5.2
6491@dots{}
6492(gdb) b main
6493Breakpoint 1 at 0x80732bc: file main.c, line 734.
6494(gdb) run
6495Starting program: /tmp/gdb-5.2/gdb/gdb
6496
6497Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
6498734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
6499(gdb) print args
6500$1 = @{argc = 136426532, argv = 0x821b7f0@}
6501(gdb)
6502@end smallexample
8973da3a 6503
0816590b 6504@subsection Make a release candidate available
8973da3a 6505
0816590b 6506If this is a release candidate then the only remaining steps are:
8642bc8f 6507
0816590b
AC
6508@enumerate
6509@item
6510Commit @file{version.in} and @file{ChangeLog}
6511@item
6512Tweak @file{version.in} (and @file{ChangeLog} to read
6513@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update
6514process can restart.
6515@item
6516Make the release candidate available in
6517@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch}
6518@item
6519Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and
6520@email{gdb-testers@@sources.redhat.com} that the candidate is available.
6521@end enumerate
8642bc8f 6522
0816590b 6523@subsection Make a formal release available
8642bc8f 6524
0816590b 6525(And you thought all that was required was to post an e-mail.)
8642bc8f 6526
0816590b 6527@subsubheading Install on sware
8642bc8f 6528
0816590b 6529Copy the new files to both the release and the old release directory:
8642bc8f 6530
474c8240 6531@smallexample
0816590b 6532$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
8642bc8f 6533$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
474c8240 6534@end smallexample
8642bc8f 6535
0816590b
AC
6536@noindent
6537Clean up the releases directory so that only the most recent releases
6538are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
6539
6540@smallexample
6541$ cd ~ftp/pub/gdb/releases
6542$ rm @dots{}
6543@end smallexample
6544
6545@noindent
6546Update the file @file{README} and @file{.message} in the releases
6547directory:
6548
6549@smallexample
6550$ vi README
6551@dots{}
6552$ rm -f .message
6553$ ln README .message
6554@end smallexample
8642bc8f 6555
0816590b 6556@subsubheading Update the web pages.
8973da3a 6557
0816590b
AC
6558@table @file
6559
6560@item htdocs/download/ANNOUNCEMENT
6561This file, which is posted as the official announcement, includes:
8973da3a
AC
6562@itemize @bullet
6563@item
b247355e 6564General announcement.
8642bc8f 6565@item
0816590b
AC
6566News. If making an @var{M}.@var{N}.1 release, retain the news from
6567earlier @var{M}.@var{N} release.
8973da3a 6568@item
b247355e 6569Errata.
0816590b
AC
6570@end itemize
6571
6572@item htdocs/index.html
6573@itemx htdocs/news/index.html
6574@itemx htdocs/download/index.html
6575These files include:
6576@itemize @bullet
8642bc8f 6577@item
b247355e 6578Announcement of the most recent release.
8642bc8f 6579@item
b247355e 6580News entry (remember to update both the top level and the news directory).
8973da3a 6581@end itemize
0816590b 6582These pages also need to be regenerate using @code{index.sh}.
8973da3a 6583
0816590b 6584@item download/onlinedocs/
8642bc8f
AC
6585You need to find the magic command that is used to generate the online
6586docs from the @file{.tar.bz2}. The best way is to look in the output
0816590b 6587from one of the nightly @code{cron} jobs and then just edit accordingly.
8642bc8f
AC
6588Something like:
6589
474c8240 6590@smallexample
8642bc8f 6591$ ~/ss/update-web-docs \
0816590b 6592 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
8642bc8f 6593 $PWD/www \
0816590b 6594 /www/sourceware/htdocs/gdb/download/onlinedocs \
8642bc8f 6595 gdb
474c8240 6596@end smallexample
8642bc8f 6597
0816590b
AC
6598@item download/ari/
6599Just like the online documentation. Something like:
8642bc8f 6600
0816590b
AC
6601@smallexample
6602$ /bin/sh ~/ss/update-web-ari \
6603 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
6604 $PWD/www \
6605 /www/sourceware/htdocs/gdb/download/ari \
6606 gdb
6607@end smallexample
6608
6609@end table
6610
6611@subsubheading Shadow the pages onto gnu
6612
6613Something goes here.
6614
6615
6616@subsubheading Install the @value{GDBN} tar ball on GNU
6617
6618At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
6619@file{~ftp/gnu/gdb}.
6620
6621@subsubheading Make the @file{ANNOUNCEMENT}
6622
6623Post the @file{ANNOUNCEMENT} file you created above to:
8642bc8f
AC
6624
6625@itemize @bullet
6626@item
6627@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
6628@item
0816590b
AC
6629@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a
6630day or so to let things get out)
6631@item
6632@email{bug-gdb@@gnu.org, GDB Bug Report mailing list}
8642bc8f
AC
6633@end itemize
6634
0816590b 6635@subsection Cleanup
8642bc8f 6636
0816590b 6637The release is out but you're still not finished.
8642bc8f 6638
0816590b 6639@subsubheading Commit outstanding changes
8642bc8f 6640
0816590b 6641In particular you'll need to commit any changes to:
8642bc8f
AC
6642
6643@itemize @bullet
6644@item
6645@file{gdb/ChangeLog}
6646@item
6647@file{gdb/version.in}
6648@item
6649@file{gdb/NEWS}
6650@item
6651@file{gdb/README}
6652@end itemize
6653
0816590b 6654@subsubheading Tag the release
8642bc8f
AC
6655
6656Something like:
6657
474c8240 6658@smallexample
8642bc8f
AC
6659$ d=`date -u +%Y-%m-%d`
6660$ echo $d
66612002-01-24
6662$ ( cd insight/src/gdb && cvs -f -q update )
0816590b 6663$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
474c8240 6664@end smallexample
8642bc8f 6665
0816590b 6666Insight is used since that contains more of the release than
b247355e 6667@value{GDBN}.
0816590b
AC
6668
6669@subsubheading Mention the release on the trunk
8642bc8f 6670
0816590b
AC
6671Just put something in the @file{ChangeLog} so that the trunk also
6672indicates when the release was made.
6673
6674@subsubheading Restart @file{gdb/version.in}
8642bc8f
AC
6675
6676If @file{gdb/version.in} does not contain an ISO date such as
6677@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having
6678committed all the release changes it can be set to
0816590b 6679@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
8642bc8f
AC
6680is important - it affects the snapshot process).
6681
6682Don't forget the @file{ChangeLog}.
6683
0816590b 6684@subsubheading Merge into trunk
8973da3a 6685
8642bc8f
AC
6686The files committed to the branch may also need changes merged into the
6687trunk.
8973da3a 6688
0816590b
AC
6689@subsubheading Revise the release schedule
6690
6691Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB
6692Discussion List} with an updated announcement. The schedule can be
6693generated by running:
6694
6695@smallexample
6696$ ~/ss/schedule `date +%s` schedule
6697@end smallexample
6698
6699@noindent
6700The first parameter is approximate date/time in seconds (from the epoch)
6701of the most recent release.
6702
6703Also update the schedule @code{cronjob}.
6704
8642bc8f 6705@section Post release
8973da3a 6706
8642bc8f 6707Remove any @code{OBSOLETE} code.
8973da3a 6708
085dd6e6
JM
6709@node Testsuite
6710
6711@chapter Testsuite
56caf160 6712@cindex test suite
085dd6e6 6713
56caf160
EZ
6714The testsuite is an important component of the @value{GDBN} package.
6715While it is always worthwhile to encourage user testing, in practice
6716this is rarely sufficient; users typically use only a small subset of
6717the available commands, and it has proven all too common for a change
6718to cause a significant regression that went unnoticed for some time.
085dd6e6 6719
b247355e
NR
6720The @value{GDBN} testsuite uses the DejaGNU testing framework. The
6721tests themselves are calls to various @code{Tcl} procs; the framework
6722runs all the procs and summarizes the passes and fails.
085dd6e6
JM
6723
6724@section Using the Testsuite
6725
56caf160 6726@cindex running the test suite
25822942 6727To run the testsuite, simply go to the @value{GDBN} object directory (or to the
085dd6e6
JM
6728testsuite's objdir) and type @code{make check}. This just sets up some
6729environment variables and invokes DejaGNU's @code{runtest} script. While
6730the testsuite is running, you'll get mentions of which test file is in use,
6731and a mention of any unexpected passes or fails. When the testsuite is
6732finished, you'll get a summary that looks like this:
56caf160 6733
474c8240 6734@smallexample
085dd6e6
JM
6735 === gdb Summary ===
6736
6737# of expected passes 6016
6738# of unexpected failures 58
6739# of unexpected successes 5
6740# of expected failures 183
6741# of unresolved testcases 3
6742# of untested testcases 5
474c8240 6743@end smallexample
56caf160 6744
a9f158ec
JB
6745To run a specific test script, type:
6746@example
6747make check RUNTESTFLAGS='@var{tests}'
6748@end example
6749where @var{tests} is a list of test script file names, separated by
6750spaces.
6751
085dd6e6
JM
6752The ideal test run consists of expected passes only; however, reality
6753conspires to keep us from this ideal. Unexpected failures indicate
56caf160
EZ
6754real problems, whether in @value{GDBN} or in the testsuite. Expected
6755failures are still failures, but ones which have been decided are too
6756hard to deal with at the time; for instance, a test case might work
6757everywhere except on AIX, and there is no prospect of the AIX case
6758being fixed in the near future. Expected failures should not be added
6759lightly, since you may be masking serious bugs in @value{GDBN}.
6760Unexpected successes are expected fails that are passing for some
6761reason, while unresolved and untested cases often indicate some minor
6762catastrophe, such as the compiler being unable to deal with a test
6763program.
6764
6765When making any significant change to @value{GDBN}, you should run the
6766testsuite before and after the change, to confirm that there are no
6767regressions. Note that truly complete testing would require that you
6768run the testsuite with all supported configurations and a variety of
6769compilers; however this is more than really necessary. In many cases
6770testing with a single configuration is sufficient. Other useful
6771options are to test one big-endian (Sparc) and one little-endian (x86)
6772host, a cross config with a builtin simulator (powerpc-eabi,
6773mips-elf), or a 64-bit host (Alpha).
6774
6775If you add new functionality to @value{GDBN}, please consider adding
6776tests for it as well; this way future @value{GDBN} hackers can detect
6777and fix their changes that break the functionality you added.
6778Similarly, if you fix a bug that was not previously reported as a test
6779failure, please add a test case for it. Some cases are extremely
6780difficult to test, such as code that handles host OS failures or bugs
6781in particular versions of compilers, and it's OK not to try to write
6782tests for all of those.
085dd6e6 6783
e7dc800a
MC
6784DejaGNU supports separate build, host, and target machines. However,
6785some @value{GDBN} test scripts do not work if the build machine and
6786the host machine are not the same. In such an environment, these scripts
6787will give a result of ``UNRESOLVED'', like this:
6788
6789@smallexample
6790UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
6791@end smallexample
6792
085dd6e6
JM
6793@section Testsuite Organization
6794
56caf160 6795@cindex test suite organization
085dd6e6
JM
6796The testsuite is entirely contained in @file{gdb/testsuite}. While the
6797testsuite includes some makefiles and configury, these are very minimal,
6798and used for little besides cleaning up, since the tests themselves
25822942 6799handle the compilation of the programs that @value{GDBN} will run. The file
085dd6e6 6800@file{testsuite/lib/gdb.exp} contains common utility procs useful for
25822942 6801all @value{GDBN} tests, while the directory @file{testsuite/config} contains
085dd6e6
JM
6802configuration-specific files, typically used for special-purpose
6803definitions of procs like @code{gdb_load} and @code{gdb_start}.
6804
6805The tests themselves are to be found in @file{testsuite/gdb.*} and
6806subdirectories of those. The names of the test files must always end
6807with @file{.exp}. DejaGNU collects the test files by wildcarding
6808in the test directories, so both subdirectories and individual files
6809get chosen and run in alphabetical order.
6810
6811The following table lists the main types of subdirectories and what they
6812are for. Since DejaGNU finds test files no matter where they are
6813located, and since each test file sets up its own compilation and
6814execution environment, this organization is simply for convenience and
6815intelligibility.
6816
56caf160 6817@table @file
085dd6e6 6818@item gdb.base
085dd6e6 6819This is the base testsuite. The tests in it should apply to all
25822942 6820configurations of @value{GDBN} (but generic native-only tests may live here).
085dd6e6 6821The test programs should be in the subset of C that is valid K&R,
49efadf5 6822ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance
085dd6e6
JM
6823for prototypes).
6824
6825@item gdb.@var{lang}
56caf160 6826Language-specific tests for any language @var{lang} besides C. Examples are
af6cf26d 6827@file{gdb.cp} and @file{gdb.java}.
085dd6e6
JM
6828
6829@item gdb.@var{platform}
085dd6e6
JM
6830Non-portable tests. The tests are specific to a specific configuration
6831(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
6832HP-UX.
6833
6834@item gdb.@var{compiler}
085dd6e6
JM
6835Tests specific to a particular compiler. As of this writing (June
68361999), there aren't currently any groups of tests in this category that
6837couldn't just as sensibly be made platform-specific, but one could
56caf160
EZ
6838imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC
6839extensions.
085dd6e6
JM
6840
6841@item gdb.@var{subsystem}
25822942 6842Tests that exercise a specific @value{GDBN} subsystem in more depth. For
085dd6e6
JM
6843instance, @file{gdb.disasm} exercises various disassemblers, while
6844@file{gdb.stabs} tests pathways through the stabs symbol reader.
085dd6e6
JM
6845@end table
6846
6847@section Writing Tests
56caf160 6848@cindex writing tests
085dd6e6 6849
25822942 6850In many areas, the @value{GDBN} tests are already quite comprehensive; you
085dd6e6
JM
6851should be able to copy existing tests to handle new cases.
6852
6853You should try to use @code{gdb_test} whenever possible, since it
6854includes cases to handle all the unexpected errors that might happen.
6855However, it doesn't cost anything to add new test procedures; for
6856instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
6857calls @code{gdb_test} multiple times.
6858
6859Only use @code{send_gdb} and @code{gdb_expect} when absolutely
8a3dae3e
DJ
6860necessary. Even if @value{GDBN} has several valid responses to
6861a command, you can use @code{gdb_test_multiple}. Like @code{gdb_test},
6862@code{gdb_test_multiple} recognizes internal errors and unexpected
6863prompts.
6864
6865Do not write tests which expect a literal tab character from @value{GDBN}.
6866On some operating systems (e.g.@: OpenBSD) the TTY layer expands tabs to
6867spaces, so by the time @value{GDBN}'s output reaches expect the tab is gone.
085dd6e6
JM
6868
6869The source language programs do @emph{not} need to be in a consistent
25822942 6870style. Since @value{GDBN} is used to debug programs written in many different
085dd6e6 6871styles, it's worth having a mix of styles in the testsuite; for
25822942 6872instance, some @value{GDBN} bugs involving the display of source lines would
085dd6e6
JM
6873never manifest themselves if the programs used GNU coding style
6874uniformly.
6875
c906108c
SS
6876@node Hints
6877
6878@chapter Hints
6879
6880Check the @file{README} file, it often has useful information that does not
6881appear anywhere else in the directory.
6882
6883@menu
25822942 6884* Getting Started:: Getting started working on @value{GDBN}
33e16fad 6885* Debugging GDB:: Debugging @value{GDBN} with itself
c906108c
SS
6886@end menu
6887
6888@node Getting Started,,, Hints
6889
6890@section Getting Started
6891
25822942 6892@value{GDBN} is a large and complicated program, and if you first starting to
c906108c
SS
6893work on it, it can be hard to know where to start. Fortunately, if you
6894know how to go about it, there are ways to figure out what is going on.
6895
25822942
DB
6896This manual, the @value{GDBN} Internals manual, has information which applies
6897generally to many parts of @value{GDBN}.
c906108c
SS
6898
6899Information about particular functions or data structures are located in
6900comments with those functions or data structures. If you run across a
6901function or a global variable which does not have a comment correctly
25822942 6902explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
c906108c
SS
6903free to submit a bug report, with a suggested comment if you can figure
6904out what the comment should say. If you find a comment which is
6905actually wrong, be especially sure to report that.
6906
6907Comments explaining the function of macros defined in host, target, or
6908native dependent files can be in several places. Sometimes they are
6909repeated every place the macro is defined. Sometimes they are where the
6910macro is used. Sometimes there is a header file which supplies a
6911default definition of the macro, and the comment is there. This manual
6912also documents all the available macros.
6913@c (@pxref{Host Conditionals}, @pxref{Target
6914@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
6915@c Conditionals})
6916
56caf160
EZ
6917Start with the header files. Once you have some idea of how
6918@value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},
6919@file{gdbtypes.h}), you will find it much easier to understand the
6920code which uses and creates those symbol tables.
c906108c
SS
6921
6922You may wish to process the information you are getting somehow, to
6923enhance your understanding of it. Summarize it, translate it to another
25822942 6924language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
c906108c
SS
6925the code to predict what a test case would do and write the test case
6926and verify your prediction, etc. If you are reading code and your eyes
6927are starting to glaze over, this is a sign you need to use a more active
6928approach.
6929
25822942 6930Once you have a part of @value{GDBN} to start with, you can find more
c906108c
SS
6931specifically the part you are looking for by stepping through each
6932function with the @code{next} command. Do not use @code{step} or you
6933will quickly get distracted; when the function you are stepping through
6934calls another function try only to get a big-picture understanding
6935(perhaps using the comment at the beginning of the function being
6936called) of what it does. This way you can identify which of the
6937functions being called by the function you are stepping through is the
6938one which you are interested in. You may need to examine the data
6939structures generated at each stage, with reference to the comments in
6940the header files explaining what the data structures are supposed to
6941look like.
6942
6943Of course, this same technique can be used if you are just reading the
6944code, rather than actually stepping through it. The same general
6945principle applies---when the code you are looking at calls something
6946else, just try to understand generally what the code being called does,
6947rather than worrying about all its details.
6948
56caf160
EZ
6949@cindex command implementation
6950A good place to start when tracking down some particular area is with
6951a command which invokes that feature. Suppose you want to know how
6952single-stepping works. As a @value{GDBN} user, you know that the
6953@code{step} command invokes single-stepping. The command is invoked
6954via command tables (see @file{command.h}); by convention the function
6955which actually performs the command is formed by taking the name of
6956the command and adding @samp{_command}, or in the case of an
6957@code{info} subcommand, @samp{_info}. For example, the @code{step}
6958command invokes the @code{step_command} function and the @code{info
6959display} command invokes @code{display_info}. When this convention is
6960not followed, you might have to use @code{grep} or @kbd{M-x
6961tags-search} in emacs, or run @value{GDBN} on itself and set a
6962breakpoint in @code{execute_command}.
6963
6964@cindex @code{bug-gdb} mailing list
c906108c
SS
6965If all of the above fail, it may be appropriate to ask for information
6966on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
6967wondering if anyone could give me some tips about understanding
25822942 6968@value{GDBN}''---if we had some magic secret we would put it in this manual.
c906108c
SS
6969Suggestions for improving the manual are always welcome, of course.
6970
33e16fad 6971@node Debugging GDB,,,Hints
c906108c 6972
25822942 6973@section Debugging @value{GDBN} with itself
56caf160 6974@cindex debugging @value{GDBN}
c906108c 6975
25822942 6976If @value{GDBN} is limping on your machine, this is the preferred way to get it
c906108c
SS
6977fully functional. Be warned that in some ancient Unix systems, like
6978Ultrix 4.2, a program can't be running in one process while it is being
56caf160 6979debugged in another. Rather than typing the command @kbd{@w{./gdb
c906108c 6980./gdb}}, which works on Suns and such, you can copy @file{gdb} to
56caf160 6981@file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.
c906108c 6982
25822942 6983When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
c906108c
SS
6984@file{.gdbinit} file that sets up some simple things to make debugging
6985gdb easier. The @code{info} command, when executed without a subcommand
25822942 6986in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
c906108c
SS
6987gdb. See @file{.gdbinit} for details.
6988
6989If you use emacs, you will probably want to do a @code{make TAGS} after
6990you configure your distribution; this will put the machine dependent
6991routines for your local machine where they will be accessed first by
6992@kbd{M-.}
6993
25822942 6994Also, make sure that you've either compiled @value{GDBN} with your local cc, or
c906108c
SS
6995have run @code{fixincludes} if you are compiling with gcc.
6996
6997@section Submitting Patches
6998
56caf160 6999@cindex submitting patches
c906108c 7000Thanks for thinking of offering your changes back to the community of
25822942 7001@value{GDBN} users. In general we like to get well designed enhancements.
c906108c
SS
7002Thanks also for checking in advance about the best way to transfer the
7003changes.
7004
25822942
DB
7005The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
7006This manual summarizes what we believe to be clean design for @value{GDBN}.
c906108c
SS
7007
7008If the maintainers don't have time to put the patch in when it arrives,
7009or if there is any question about a patch, it goes into a large queue
7010with everyone else's patches and bug reports.
7011
56caf160 7012@cindex legal papers for code contributions
c906108c
SS
7013The legal issue is that to incorporate substantial changes requires a
7014copyright assignment from you and/or your employer, granting ownership
7015of the changes to the Free Software Foundation. You can get the
9e0b60a8
JM
7016standard documents for doing this by sending mail to @code{gnu@@gnu.org}
7017and asking for it. We recommend that people write in "All programs
7018owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
56caf160
EZ
7019changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
7020etc) can be
9e0b60a8 7021contributed with only one piece of legalese pushed through the
be9c6c35 7022bureaucracy and filed with the FSF. We can't start merging changes until
9e0b60a8
JM
7023this paperwork is received by the FSF (their rules, which we follow
7024since we maintain it for them).
c906108c
SS
7025
7026Technically, the easiest way to receive changes is to receive each
56caf160
EZ
7027feature as a small context diff or unidiff, suitable for @code{patch}.
7028Each message sent to me should include the changes to C code and
7029header files for a single feature, plus @file{ChangeLog} entries for
7030each directory where files were modified, and diffs for any changes
7031needed to the manuals (@file{gdb/doc/gdb.texinfo} or
7032@file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a
7033single feature, they can be split down into multiple messages.
9e0b60a8
JM
7034
7035In this way, if we read and like the feature, we can add it to the
c906108c 7036sources with a single patch command, do some testing, and check it in.
56caf160
EZ
7037If you leave out the @file{ChangeLog}, we have to write one. If you leave
7038out the doc, we have to puzzle out what needs documenting. Etc., etc.
c906108c 7039
9e0b60a8
JM
7040The reason to send each change in a separate message is that we will not
7041install some of the changes. They'll be returned to you with questions
7042or comments. If we're doing our job correctly, the message back to you
c906108c 7043will say what you have to fix in order to make the change acceptable.
9e0b60a8
JM
7044The reason to have separate messages for separate features is so that
7045the acceptable changes can be installed while one or more changes are
7046being reworked. If multiple features are sent in a single message, we
7047tend to not put in the effort to sort out the acceptable changes from
7048the unacceptable, so none of the features get installed until all are
7049acceptable.
7050
7051If this sounds painful or authoritarian, well, it is. But we get a lot
7052of bug reports and a lot of patches, and many of them don't get
7053installed because we don't have the time to finish the job that the bug
c906108c
SS
7054reporter or the contributor could have done. Patches that arrive
7055complete, working, and well designed, tend to get installed on the day
9e0b60a8
JM
7056they arrive. The others go into a queue and get installed as time
7057permits, which, since the maintainers have many demands to meet, may not
7058be for quite some time.
c906108c 7059
56caf160 7060Please send patches directly to
47b95330 7061@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}.
c906108c
SS
7062
7063@section Obsolete Conditionals
56caf160 7064@cindex obsolete code
c906108c 7065
25822942 7066Fragments of old code in @value{GDBN} sometimes reference or set the following
c906108c
SS
7067configuration macros. They should not be used by new code, and old uses
7068should be removed as those parts of the debugger are otherwise touched.
7069
7070@table @code
c906108c
SS
7071@item STACK_END_ADDR
7072This macro used to define where the end of the stack appeared, for use
7073in interpreting core file formats that don't record this address in the
25822942
DB
7074core file itself. This information is now configured in BFD, and @value{GDBN}
7075gets the info portably from there. The values in @value{GDBN}'s configuration
c906108c 7076files should be moved into BFD configuration files (if needed there),
25822942 7077and deleted from all of @value{GDBN}'s config files.
c906108c
SS
7078
7079Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
7080is so old that it has never been converted to use BFD. Now that's old!
7081
c906108c
SS
7082@end table
7083
36af4ef6
MD
7084@section Build Script
7085
7086@cindex build script
7087
7088The script @file{gdb_buildall.sh} builds @value{GDBN} with flag
7089@option{--enable-targets=all} set. This builds @value{GDBN} with all supported
7090targets activated. This helps testing @value{GDBN} when doing changes that
7091affect more than one architecture and is much faster than using
7092@file{gdb_mbuild.sh}.
7093
7094After building @value{GDBN} the script checks which architectures are
7095supported and then switches the current architecture to each of those to get
7096information about the architecture. The test results are stored in log files
7097in the directory the script was called from.
7098
bcd7e15f 7099@include observer.texi
2154891a 7100@raisesections
aab4e0ec 7101@include fdl.texi
2154891a 7102@lowersections
aab4e0ec 7103
56caf160
EZ
7104@node Index
7105@unnumbered Index
7106
7107@printindex cp
7108
c906108c 7109@bye
This page took 1.001851 seconds and 4 git commands to generate.