Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / doc / gdbint.texinfo
1 \input texinfo   @c -*- texinfo -*-
2 @setfilename gdbint.info
3 @include gdb-cfg.texi
4 @settitle @value{GDBN} Internals
5 @setchapternewpage off
6 @dircategory Software development
7 @direntry
8 * Gdb-Internals: (gdbint).      The GNU debugger's internals.
9 @end direntry
10
11 @copying
12 Copyright @copyright{} 1990-2013 Free Software Foundation, Inc.
13 Contributed by Cygnus Solutions.  Written by John Gilmore.
14 Second Edition by Stan Shebs.
15
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
20 Texts.  A copy of the license is included in the section entitled ``GNU
21 Free Documentation License''.
22 @end copying
23
24 @ifnottex
25 This file documents the internals of the GNU debugger @value{GDBN}.
26
27 @insertcopying
28 @end ifnottex
29
30 @syncodeindex vr fn
31
32 @titlepage
33 @title @value{GDBN} Internals
34 @subtitle A guide to the internals of the GNU debugger
35 @author John Gilmore
36 @author Cygnus Solutions
37 @author Second Edition:
38 @author Stan Shebs
39 @author Cygnus Solutions
40 @page
41 @tex
42 \def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
43 \xdef\manvers{\$Revision$}  % For use in headers, footers too
44 {\parskip=0pt
45 \hfill Cygnus Solutions\par
46 \hfill \manvers\par
47 \hfill \TeX{}info \texinfoversion\par
48 }
49 @end tex
50
51 @vskip 0pt plus 1filll
52 @insertcopying
53 @end titlepage
54
55 @contents
56
57 @node Top
58 @c Perhaps this should be the title of the document (but only for info,
59 @c not for TeX).  Existing GNU manuals seem inconsistent on this point.
60 @top Scope of this Document
61
62 This document documents the internals of the GNU debugger, @value{GDBN}.  It
63 includes description of @value{GDBN}'s key algorithms and operations, as well
64 as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
65
66 @menu
67 * Summary::
68 * Overall Structure::
69 * Algorithms::
70 * User Interface::
71 * libgdb::
72 * Values::
73 * Stack Frames::
74 * Symbol Handling::
75 * Language Support::
76 * Host Definition::
77 * Target Architecture Definition::
78 * Target Descriptions::
79 * Target Vector Definition::
80 * Native Debugging::
81 * Support Libraries::
82 * Coding Standards::
83 * Misc Guidelines::
84 * Porting GDB::
85 * Versions and Branches::
86 * Start of New Year Procedure::
87 * Releasing GDB::
88 * Testsuite::
89 * Hints::
90
91 * GDB Observers::  @value{GDBN} Currently available observers
92 * GNU Free Documentation License::  The license for this documentation
93 * Concept Index::
94 * Function and Variable Index::
95 @end menu
96
97 @node Summary
98 @chapter Summary
99
100 @menu
101 * Requirements::
102 * Contributors::
103 @end menu
104
105 @node Requirements
106 @section Requirements
107 @cindex requirements for @value{GDBN}
108
109 Before diving into the internals, you should understand the formal
110 requirements and other expectations for @value{GDBN}.  Although some
111 of these may seem obvious, there have been proposals for @value{GDBN}
112 that have run counter to these requirements.
113
114 First of all, @value{GDBN} is a debugger.  It's not designed to be a
115 front panel for embedded systems.  It's not a text editor.  It's not a
116 shell.  It's not a programming environment.
117
118 @value{GDBN} is an interactive tool.  Although a batch mode is
119 available, @value{GDBN}'s primary role is to interact with a human
120 programmer.
121
122 @value{GDBN} should be responsive to the user.  A programmer hot on
123 the trail of a nasty bug, and operating under a looming deadline, is
124 going to be very impatient of everything, including the response time
125 to debugger commands.
126
127 @value{GDBN} should be relatively permissive, such as for expressions.
128 While the compiler should be picky (or have the option to be made
129 picky), since source code lives for a long time usually, the
130 programmer doing debugging shouldn't be spending time figuring out to
131 mollify the debugger.
132
133 @value{GDBN} will be called upon to deal with really large programs.
134 Executable sizes of 50 to 100 megabytes occur regularly, and we've
135 heard reports of programs approaching 1 gigabyte in size.
136
137 @value{GDBN} should be able to run everywhere.  No other debugger is
138 available for even half as many configurations as @value{GDBN}
139 supports.
140
141 @node Contributors
142 @section Contributors
143
144 The first edition of this document was written by John Gilmore of
145 Cygnus Solutions. The current second edition was written by Stan Shebs
146 of Cygnus Solutions, who continues to update the manual.
147
148 Over the years, many others have made additions and changes to this
149 document. This section attempts to record the significant contributors
150 to that effort. One of the virtues of free software is that everyone
151 is free to contribute to it; with regret, we cannot actually
152 acknowledge everyone here.
153
154 @quotation
155 @emph{Plea:} This section has only been added relatively recently (four
156 years after publication of the second edition). Additions to this
157 section are particularly welcome.  If you or your friends (or enemies,
158 to be evenhanded) have been unfairly omitted from this list, we would
159 like to add your names!
160 @end quotation
161
162 A document such as this relies on being kept up to date by numerous
163 small updates by contributing engineers as they make changes to the
164 code base. The file @file{ChangeLog} in the @value{GDBN} distribution
165 approximates a blow-by-blow account. The most prolific contributors to
166 this important, but low profile task are Andrew Cagney (responsible
167 for over half the entries), Daniel Jacobowitz, Mark Kettenis, Jim
168 Blandy and Eli Zaretskii.
169
170 Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting
171 watchpoints.
172
173 Jeremy Bennett updated the sections on initializing a new architecture
174 and register representation, and added the section on Frame Interpretation.
175
176
177 @node Overall Structure
178
179 @chapter Overall Structure
180
181 @value{GDBN} consists of three major subsystems: user interface,
182 symbol handling (the @dfn{symbol side}), and target system handling (the
183 @dfn{target side}).
184
185 The user interface consists of several actual interfaces, plus
186 supporting code.
187
188 The symbol side consists of object file readers, debugging info
189 interpreters, symbol table management, source language expression
190 parsing, type and value printing.
191
192 The target side consists of execution control, stack frame analysis, and
193 physical target manipulation.
194
195 The target side/symbol side division is not formal, and there are a
196 number of exceptions.  For instance, core file support involves symbolic
197 elements (the basic core file reader is in BFD) and target elements (it
198 supplies the contents of memory and the values of registers).  Instead,
199 this division is useful for understanding how the minor subsystems
200 should fit together.
201
202 @section The Symbol Side
203
204 The symbolic side of @value{GDBN} can be thought of as ``everything
205 you can do in @value{GDBN} without having a live program running''.
206 For instance, you can look at the types of variables, and evaluate
207 many kinds of expressions.
208
209 @section The Target Side
210
211 The target side of @value{GDBN} is the ``bits and bytes manipulator''.
212 Although it may make reference to symbolic info here and there, most
213 of the target side will run with only a stripped executable
214 available---or even no executable at all, in remote debugging cases.
215
216 Operations such as disassembly, stack frame crawls, and register
217 display, are able to work with no symbolic info at all.  In some cases,
218 such as disassembly, @value{GDBN} will use symbolic info to present addresses
219 relative to symbols rather than as raw numbers, but it will work either
220 way.
221
222 @section Configurations
223
224 @cindex host
225 @cindex target
226 @dfn{Host} refers to attributes of the system where @value{GDBN} runs.
227 @dfn{Target} refers to the system where the program being debugged
228 executes.  In most cases they are the same machine, in which case a
229 third type of @dfn{Native} attributes come into play.
230
231 Defines and include files needed to build on the host are host
232 support.  Examples are tty support, system defined types, host byte
233 order, host float format.  These are all calculated by @code{autoconf}
234 when the debugger is built.
235
236 Defines and information needed to handle the target format are target
237 dependent.  Examples are the stack frame format, instruction set,
238 breakpoint instruction, registers, and how to set up and tear down the stack
239 to call a function.
240
241 Information that is only needed when the host and target are the same,
242 is native dependent.  One example is Unix child process support; if the
243 host and target are not the same, calling @code{fork} to start the target
244 process is a bad idea.  The various macros needed for finding the
245 registers in the @code{upage}, running @code{ptrace}, and such are all
246 in the native-dependent files.
247
248 Another example of native-dependent code is support for features that
249 are really part of the target environment, but which require
250 @code{#include} files that are only available on the host system.  Core
251 file handling and @code{setjmp} handling are two common cases.
252
253 When you want to make @value{GDBN} work as the traditional native debugger
254 on a system, you will need to supply both target and native information.
255
256 @section Source Tree Structure
257 @cindex @value{GDBN} source tree structure
258
259 The @value{GDBN} source directory has a mostly flat structure---there
260 are only a few subdirectories.  A file's name usually gives a hint as
261 to what it does; for example, @file{stabsread.c} reads stabs,
262 @file{dwarf2read.c} reads @sc{DWARF 2}, etc.
263
264 Files that are related to some common task have names that share
265 common substrings.  For example, @file{*-thread.c} files deal with
266 debugging threads on various platforms; @file{*read.c} files deal with
267 reading various kinds of symbol and object files; @file{inf*.c} files
268 deal with direct control of the @dfn{inferior program} (@value{GDBN}
269 parlance for the program being debugged).
270
271 There are several dozens of files in the @file{*-tdep.c} family.
272 @samp{tdep} stands for @dfn{target-dependent code}---each of these
273 files implements debug support for a specific target architecture
274 (sparc, mips, etc).  Usually, only one of these will be used in a
275 specific @value{GDBN} configuration (sometimes two, closely related).
276
277 Similarly, there are many @file{*-nat.c} files, each one for native
278 debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for
279 native debugging of Sparc machines running the Linux kernel).
280
281 The few subdirectories of the source tree are:
282
283 @table @file
284 @item cli
285 Code that implements @dfn{CLI}, the @value{GDBN} Command-Line
286 Interpreter.  @xref{User Interface, Command Interpreter}.
287
288 @item gdbserver
289 Code for the @value{GDBN} remote server.
290
291 @item gdbtk
292 Code for Insight, the @value{GDBN} TK-based GUI front-end.
293
294 @item mi
295 The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter.
296
297 @item signals
298 Target signal translation code.
299
300 @item tui
301 Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User
302 Interface.  @xref{User Interface, TUI}.
303 @end table
304
305 @node Algorithms
306
307 @chapter Algorithms
308 @cindex algorithms
309
310 @value{GDBN} uses a number of debugging-specific algorithms.  They are
311 often not very complicated, but get lost in the thicket of special
312 cases and real-world issues.  This chapter describes the basic
313 algorithms and mentions some of the specific target definitions that
314 they use.
315
316 @section Prologue Analysis
317
318 @cindex prologue analysis
319 @cindex call frame information
320 @cindex CFI (call frame information)
321 To produce a backtrace and allow the user to manipulate older frames'
322 variables and arguments, @value{GDBN} needs to find the base addresses
323 of older frames, and discover where those frames' registers have been
324 saved.  Since a frame's ``callee-saves'' registers get saved by
325 younger frames if and when they're reused, a frame's registers may be
326 scattered unpredictably across younger frames.  This means that
327 changing the value of a register-allocated variable in an older frame
328 may actually entail writing to a save slot in some younger frame.
329
330 Modern versions of GCC emit Dwarf call frame information (``CFI''),
331 which describes how to find frame base addresses and saved registers.
332 But CFI is not always available, so as a fallback @value{GDBN} uses a
333 technique called @dfn{prologue analysis} to find frame sizes and saved
334 registers.  A prologue analyzer disassembles the function's machine
335 code starting from its entry point, and looks for instructions that
336 allocate frame space, save the stack pointer in a frame pointer
337 register, save registers, and so on.  Obviously, this can't be done
338 accurately in general, but it's tractable to do well enough to be very
339 helpful.  Prologue analysis predates the GNU toolchain's support for
340 CFI; at one time, prologue analysis was the only mechanism
341 @value{GDBN} used for stack unwinding at all, when the function
342 calling conventions didn't specify a fixed frame layout.
343
344 In the olden days, function prologues were generated by hand-written,
345 target-specific code in GCC, and treated as opaque and untouchable by
346 optimizers.  Looking at this code, it was usually straightforward to
347 write a prologue analyzer for @value{GDBN} that would accurately
348 understand all the prologues GCC would generate.  However, over time
349 GCC became more aggressive about instruction scheduling, and began to
350 understand more about the semantics of the prologue instructions
351 themselves; in response, @value{GDBN}'s analyzers became more complex
352 and fragile.  Keeping the prologue analyzers working as GCC (and the
353 instruction sets themselves) evolved became a substantial task.
354
355 @cindex @file{prologue-value.c}
356 @cindex abstract interpretation of function prologues
357 @cindex pseudo-evaluation of function prologues
358 To try to address this problem, the code in @file{prologue-value.h}
359 and @file{prologue-value.c} provides a general framework for writing
360 prologue analyzers that are simpler and more robust than ad-hoc
361 analyzers.  When we analyze a prologue using the prologue-value
362 framework, we're really doing ``abstract interpretation'' or
363 ``pseudo-evaluation'': running the function's code in simulation, but
364 using conservative approximations of the values registers and memory
365 would hold when the code actually runs.  For example, if our function
366 starts with the instruction:
367
368 @example
369 addi r1, 42     # add 42 to r1
370 @end example
371 @noindent
372 we don't know exactly what value will be in @code{r1} after executing
373 this instruction, but we do know it'll be 42 greater than its original
374 value.
375
376 If we then see an instruction like:
377
378 @example
379 addi r1, 22     # add 22 to r1
380 @end example
381 @noindent
382 we still don't know what @code{r1's} value is, but again, we can say
383 it is now 64 greater than its original value.
384
385 If the next instruction were:
386
387 @example
388 mov r2, r1      # set r2 to r1's value
389 @end example
390 @noindent
391 then we can say that @code{r2's} value is now the original value of
392 @code{r1} plus 64.
393
394 It's common for prologues to save registers on the stack, so we'll
395 need to track the values of stack frame slots, as well as the
396 registers.  So after an instruction like this:
397
398 @example
399 mov (fp+4), r2
400 @end example
401 @noindent
402 then we'd know that the stack slot four bytes above the frame pointer
403 holds the original value of @code{r1} plus 64.
404
405 And so on.
406
407 Of course, this can only go so far before it gets unreasonable.  If we
408 wanted to be able to say anything about the value of @code{r1} after
409 the instruction:
410
411 @example
412 xor r1, r3      # exclusive-or r1 and r3, place result in r1
413 @end example
414 @noindent
415 then things would get pretty complex.  But remember, we're just doing
416 a conservative approximation; if exclusive-or instructions aren't
417 relevant to prologues, we can just say @code{r1}'s value is now
418 ``unknown''.  We can ignore things that are too complex, if that loss of
419 information is acceptable for our application.
420
421 So when we say ``conservative approximation'' here, what we mean is an
422 approximation that is either accurate, or marked ``unknown'', but
423 never inaccurate.
424
425 Using this framework, a prologue analyzer is simply an interpreter for
426 machine code, but one that uses conservative approximations for the
427 contents of registers and memory instead of actual values.  Starting
428 from the function's entry point, you simulate instructions up to the
429 current PC, or an instruction that you don't know how to simulate.
430 Now you can examine the state of the registers and stack slots you've
431 kept track of.
432
433 @itemize @bullet
434
435 @item
436 To see how large your stack frame is, just check the value of the
437 stack pointer register; if it's the original value of the SP
438 minus a constant, then that constant is the stack frame's size.
439 If the SP's value has been marked as ``unknown'', then that means
440 the prologue has done something too complex for us to track, and
441 we don't know the frame size.
442
443 @item
444 To see where we've saved the previous frame's registers, we just
445 search the values we've tracked --- stack slots, usually, but
446 registers, too, if you want --- for something equal to the register's
447 original value.  If the calling conventions suggest a standard place
448 to save a given register, then we can check there first, but really,
449 anything that will get us back the original value will probably work.
450 @end itemize
451
452 This does take some work.  But prologue analyzers aren't
453 quick-and-simple pattern patching to recognize a few fixed prologue
454 forms any more; they're big, hairy functions.  Along with inferior
455 function calls, prologue analysis accounts for a substantial portion
456 of the time needed to stabilize a @value{GDBN} port.  So it's
457 worthwhile to look for an approach that will be easier to understand
458 and maintain.  In the approach described above:
459
460 @itemize @bullet
461
462 @item
463 It's easier to see that the analyzer is correct: you just see
464 whether the analyzer properly (albeit conservatively) simulates
465 the effect of each instruction.
466
467 @item
468 It's easier to extend the analyzer: you can add support for new
469 instructions, and know that you haven't broken anything that
470 wasn't already broken before.
471
472 @item
473 It's orthogonal: to gather new information, you don't need to
474 complicate the code for each instruction.  As long as your domain
475 of conservative values is already detailed enough to tell you
476 what you need, then all the existing instruction simulations are
477 already gathering the right data for you.
478
479 @end itemize
480
481 The file @file{prologue-value.h} contains detailed comments explaining
482 the framework and how to use it.
483
484
485 @section Breakpoint Handling
486
487 @cindex breakpoints
488 In general, a breakpoint is a user-designated location in the program
489 where the user wants to regain control if program execution ever reaches
490 that location.
491
492 There are two main ways to implement breakpoints; either as ``hardware''
493 breakpoints or as ``software'' breakpoints.
494
495 @cindex hardware breakpoints
496 @cindex program counter
497 Hardware breakpoints are sometimes available as a builtin debugging
498 features with some chips.  Typically these work by having dedicated
499 register into which the breakpoint address may be stored.  If the PC
500 (shorthand for @dfn{program counter})
501 ever matches a value in a breakpoint registers, the CPU raises an
502 exception and reports it to @value{GDBN}.
503
504 Another possibility is when an emulator is in use; many emulators
505 include circuitry that watches the address lines coming out from the
506 processor, and force it to stop if the address matches a breakpoint's
507 address.
508
509 A third possibility is that the target already has the ability to do
510 breakpoints somehow; for instance, a ROM monitor may do its own
511 software breakpoints.  So although these are not literally ``hardware
512 breakpoints'', from @value{GDBN}'s point of view they work the same;
513 @value{GDBN} need not do anything more than set the breakpoint and wait
514 for something to happen.
515
516 Since they depend on hardware resources, hardware breakpoints may be
517 limited in number; when the user asks for more, @value{GDBN} will
518 start trying to set software breakpoints.  (On some architectures,
519 notably the 32-bit x86 platforms, @value{GDBN} cannot always know
520 whether there's enough hardware resources to insert all the hardware
521 breakpoints and watchpoints.  On those platforms, @value{GDBN} prints
522 an error message only when the program being debugged is continued.)
523
524 @cindex software breakpoints
525 Software breakpoints require @value{GDBN} to do somewhat more work.
526 The basic theory is that @value{GDBN} will replace a program
527 instruction with a trap, illegal divide, or some other instruction
528 that will cause an exception, and then when it's encountered,
529 @value{GDBN} will take the exception and stop the program.  When the
530 user says to continue, @value{GDBN} will restore the original
531 instruction, single-step, re-insert the trap, and continue on.
532
533 Since it literally overwrites the program being tested, the program area
534 must be writable, so this technique won't work on programs in ROM.  It
535 can also distort the behavior of programs that examine themselves,
536 although such a situation would be highly unusual.
537
538 Also, the software breakpoint instruction should be the smallest size of
539 instruction, so it doesn't overwrite an instruction that might be a jump
540 target, and cause disaster when the program jumps into the middle of the
541 breakpoint instruction.  (Strictly speaking, the breakpoint must be no
542 larger than the smallest interval between instructions that may be jump
543 targets; perhaps there is an architecture where only even-numbered
544 instructions may jumped to.)  Note that it's possible for an instruction
545 set not to have any instructions usable for a software breakpoint,
546 although in practice only the ARC has failed to define such an
547 instruction.
548
549 Basic breakpoint object handling is in @file{breakpoint.c}.  However,
550 much of the interesting breakpoint action is in @file{infrun.c}.
551
552 @table @code
553 @cindex insert or remove software breakpoint
554 @findex target_remove_breakpoint
555 @findex target_insert_breakpoint
556 @item target_remove_breakpoint (@var{bp_tgt})
557 @itemx target_insert_breakpoint (@var{bp_tgt})
558 Insert or remove a software breakpoint at address
559 @code{@var{bp_tgt}->placed_address}.  Returns zero for success,
560 non-zero for failure.  On input, @var{bp_tgt} contains the address of the
561 breakpoint, and is otherwise initialized to zero.  The fields of the
562 @code{struct bp_target_info} pointed to by @var{bp_tgt} are updated
563 to contain other information about the breakpoint on output.  The field
564 @code{placed_address} may be updated if the breakpoint was placed at a
565 related address; the field @code{shadow_contents} contains the real
566 contents of the bytes where the breakpoint has been inserted,
567 if reading memory would return the breakpoint instead of the
568 underlying memory; the field @code{shadow_len} is the length of
569 memory cached in @code{shadow_contents}, if any; and the field
570 @code{placed_size} is optionally set and used by the target, if
571 it could differ from @code{shadow_len}.
572
573 For example, the remote target @samp{Z0} packet does not require
574 shadowing memory, so @code{shadow_len} is left at zero.  However,
575 the length reported by @code{gdbarch_breakpoint_from_pc} is cached in
576 @code{placed_size}, so that a matching @samp{z0} packet can be
577 used to remove the breakpoint.
578
579 @cindex insert or remove hardware breakpoint
580 @findex target_remove_hw_breakpoint
581 @findex target_insert_hw_breakpoint
582 @item target_remove_hw_breakpoint (@var{bp_tgt})
583 @itemx target_insert_hw_breakpoint (@var{bp_tgt})
584 Insert or remove a hardware-assisted breakpoint at address
585 @code{@var{bp_tgt}->placed_address}.  Returns zero for success,
586 non-zero for failure.  See @code{target_insert_breakpoint} for
587 a description of the @code{struct bp_target_info} pointed to by
588 @var{bp_tgt}; the @code{shadow_contents} and
589 @code{shadow_len} members are not used for hardware breakpoints,
590 but @code{placed_size} may be.
591 @end table
592
593 @section Single Stepping
594
595 @section Signal Handling
596
597 @section Thread Handling
598
599 @section Inferior Function Calls
600
601 @section Longjmp Support
602
603 @cindex @code{longjmp} debugging
604 @value{GDBN} has support for figuring out that the target is doing a
605 @code{longjmp} and for stopping at the target of the jump, if we are
606 stepping.  This is done with a few specialized internal breakpoints,
607 which are visible in the output of the @samp{maint info breakpoint}
608 command.
609
610 @findex gdbarch_get_longjmp_target
611 To make this work, you need to define a function called
612 @code{gdbarch_get_longjmp_target}, which will examine the
613 @code{jmp_buf} structure and extract the @code{longjmp} target address.
614 Since @code{jmp_buf} is target specific and typically defined in a
615 target header not available to @value{GDBN}, you will need to
616 determine the offset of the PC manually and return that; many targets
617 define a @code{jb_pc_offset} field in the tdep structure to save the
618 value once calculated.
619
620 @section Watchpoints
621 @cindex watchpoints
622
623 Watchpoints are a special kind of breakpoints (@pxref{Algorithms,
624 breakpoints}) which break when data is accessed rather than when some
625 instruction is executed.  When you have data which changes without
626 your knowing what code does that, watchpoints are the silver bullet to
627 hunt down and kill such bugs.
628
629 @cindex hardware watchpoints
630 @cindex software watchpoints
631 Watchpoints can be either hardware-assisted or not; the latter type is
632 known as ``software watchpoints.''  @value{GDBN} always uses
633 hardware-assisted watchpoints if they are available, and falls back on
634 software watchpoints otherwise.  Typical situations where @value{GDBN}
635 will use software watchpoints are:
636
637 @itemize @bullet
638 @item
639 The watched memory region is too large for the underlying hardware
640 watchpoint support.  For example, each x86 debug register can watch up
641 to 4 bytes of memory, so trying to watch data structures whose size is
642 more than 16 bytes will cause @value{GDBN} to use software
643 watchpoints.
644
645 @item
646 The value of the expression to be watched depends on data held in
647 registers (as opposed to memory).
648
649 @item
650 Too many different watchpoints requested.  (On some architectures,
651 this situation is impossible to detect until the debugged program is
652 resumed.)  Note that x86 debug registers are used both for hardware
653 breakpoints and for watchpoints, so setting too many hardware
654 breakpoints might cause watchpoint insertion to fail.
655
656 @item
657 No hardware-assisted watchpoints provided by the target
658 implementation.
659 @end itemize
660
661 Software watchpoints are very slow, since @value{GDBN} needs to
662 single-step the program being debugged and test the value of the
663 watched expression(s) after each instruction.  The rest of this
664 section is mostly irrelevant for software watchpoints.
665
666 When the inferior stops, @value{GDBN} tries to establish, among other
667 possible reasons, whether it stopped due to a watchpoint being hit.
668 It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint
669 was hit.  If not, all watchpoint checking is skipped.
670
671 Then @value{GDBN} calls @code{target_stopped_data_address} exactly
672 once.  This method returns the address of the watchpoint which
673 triggered, if the target can determine it.  If the triggered address
674 is available, @value{GDBN} compares the address returned by this
675 method with each watched memory address in each active watchpoint.
676 For data-read and data-access watchpoints, @value{GDBN} announces
677 every watchpoint that watches the triggered address as being hit.
678 For this reason, data-read and data-access watchpoints
679 @emph{require} that the triggered address be available; if not, read
680 and access watchpoints will never be considered hit.  For data-write
681 watchpoints, if the triggered address is available, @value{GDBN}
682 considers only those watchpoints which match that address;
683 otherwise, @value{GDBN} considers all data-write watchpoints.  For
684 each data-write watchpoint that @value{GDBN} considers, it evaluates
685 the expression whose value is being watched, and tests whether the
686 watched value has changed.  Watchpoints whose watched values have
687 changed are announced as hit.
688
689 @c FIXME move these to the main lists of target/native defns
690
691 @value{GDBN} uses several macros and primitives to support hardware
692 watchpoints:
693
694 @table @code
695 @findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
696 @item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
697 Return the number of hardware watchpoints of type @var{type} that are
698 possible to be set.  The value is positive if @var{count} watchpoints
699 of this type can be set, zero if setting watchpoints of this type is
700 not supported, and negative if @var{count} is more than the maximum
701 number of watchpoints of type @var{type} that can be set.  @var{other}
702 is non-zero if other types of watchpoints are currently enabled (there
703 are architectures which cannot set watchpoints of different types at
704 the same time).
705
706 @findex TARGET_REGION_OK_FOR_HW_WATCHPOINT
707 @item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len})
708 Return non-zero if hardware watchpoints can be used to watch a region
709 whose address is @var{addr} and whose length in bytes is @var{len}.
710
711 @cindex insert or remove hardware watchpoint
712 @findex target_insert_watchpoint
713 @findex target_remove_watchpoint
714 @item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
715 @itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type})
716 Insert or remove a hardware watchpoint starting at @var{addr}, for
717 @var{len} bytes.  @var{type} is the watchpoint type, one of the
718 possible values of the enumerated data type @code{target_hw_bp_type},
719 defined by @file{breakpoint.h} as follows:
720
721 @smallexample
722  enum target_hw_bp_type
723    @{
724      hw_write   = 0, /* Common (write) HW watchpoint */
725      hw_read    = 1, /* Read    HW watchpoint */
726      hw_access  = 2, /* Access (read or write) HW watchpoint */
727      hw_execute = 3  /* Execute HW breakpoint */
728    @};
729 @end smallexample
730
731 @noindent
732 These two macros should return 0 for success, non-zero for failure.
733
734 @findex target_stopped_data_address
735 @item target_stopped_data_address (@var{addr_p})
736 If the inferior has some watchpoint that triggered, place the address
737 associated with the watchpoint at the location pointed to by
738 @var{addr_p} and return non-zero.  Otherwise, return zero.  This
739 is required for data-read and data-access watchpoints.  It is
740 not required for data-write watchpoints, but @value{GDBN} uses
741 it to improve handling of those also.
742
743 @value{GDBN} will only call this method once per watchpoint stop,
744 immediately after calling @code{STOPPED_BY_WATCHPOINT}.  If the
745 target's watchpoint indication is sticky, i.e., stays set after
746 resuming, this method should clear it.  For instance, the x86 debug
747 control register has sticky triggered flags.
748
749 @findex target_watchpoint_addr_within_range
750 @item target_watchpoint_addr_within_range (@var{target}, @var{addr}, @var{start}, @var{length})
751 Check whether @var{addr} (as returned by @code{target_stopped_data_address})
752 lies within the hardware-defined watchpoint region described by
753 @var{start} and @var{length}.  This only needs to be provided if the
754 granularity of a watchpoint is greater than one byte, i.e., if the
755 watchpoint can also trigger on nearby addresses outside of the watched
756 region.
757
758 @findex HAVE_STEPPABLE_WATCHPOINT
759 @item HAVE_STEPPABLE_WATCHPOINT
760 If defined to a non-zero value, it is not necessary to disable a
761 watchpoint to step over it.  Like @code{gdbarch_have_nonsteppable_watchpoint},
762 this is usually set when watchpoints trigger at the instruction
763 which will perform an interesting read or write.  It should be
764 set if there is a temporary disable bit which allows the processor
765 to step over the interesting instruction without raising the
766 watchpoint exception again.
767
768 @findex gdbarch_have_nonsteppable_watchpoint 
769 @item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch})
770 If it returns a non-zero value, @value{GDBN} should disable a
771 watchpoint to step the inferior over it.  This is usually set when
772 watchpoints trigger at the instruction which will perform an
773 interesting read or write.
774
775 @findex HAVE_CONTINUABLE_WATCHPOINT
776 @item HAVE_CONTINUABLE_WATCHPOINT
777 If defined to a non-zero value, it is possible to continue the
778 inferior after a watchpoint has been hit.  This is usually set
779 when watchpoints trigger at the instruction following an interesting
780 read or write.
781
782 @findex STOPPED_BY_WATCHPOINT
783 @item STOPPED_BY_WATCHPOINT (@var{wait_status})
784 Return non-zero if stopped by a watchpoint.  @var{wait_status} is of
785 the type @code{struct target_waitstatus}, defined by @file{target.h}.
786 Normally, this macro is defined to invoke the function pointed to by
787 the @code{to_stopped_by_watchpoint} member of the structure (of the
788 type @code{target_ops}, defined on @file{target.h}) that describes the
789 target-specific operations; @code{to_stopped_by_watchpoint} ignores
790 the @var{wait_status} argument.
791
792 @value{GDBN} does not require the non-zero value returned by
793 @code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot
794 determine for sure whether the inferior stopped due to a watchpoint,
795 it could return non-zero ``just in case''.
796 @end table
797
798 @subsection Watchpoints and Threads
799 @cindex watchpoints, with threads
800
801 @value{GDBN} only supports process-wide watchpoints, which trigger
802 in all threads.  @value{GDBN} uses the thread ID to make watchpoints
803 act as if they were thread-specific, but it cannot set hardware
804 watchpoints that only trigger in a specific thread.  Therefore, even
805 if the target supports threads, per-thread debug registers, and
806 watchpoints which only affect a single thread, it should set the
807 per-thread debug registers for all threads to the same value.  On
808 @sc{gnu}/Linux native targets, this is accomplished by using
809 @code{ALL_LWPS} in @code{target_insert_watchpoint} and
810 @code{target_remove_watchpoint} and by using
811 @code{linux_set_new_thread} to register a handler for newly created
812 threads.
813
814 @value{GDBN}'s @sc{gnu}/Linux support only reports a single event
815 at a time, although multiple events can trigger simultaneously for
816 multi-threaded programs.  When multiple events occur, @file{linux-nat.c}
817 queues subsequent events and returns them the next time the program
818 is resumed.  This means that @code{STOPPED_BY_WATCHPOINT} and
819 @code{target_stopped_data_address} only need to consult the current
820 thread's state---the thread indicated by @code{inferior_ptid}.  If
821 two threads have hit watchpoints simultaneously, those routines
822 will be called a second time for the second thread.
823
824 @subsection x86 Watchpoints
825 @cindex x86 debug registers
826 @cindex watchpoints, on x86
827
828 The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug
829 registers designed to facilitate debugging.  @value{GDBN} provides a
830 generic library of functions that x86-based ports can use to implement
831 support for watchpoints and hardware-assisted breakpoints.  This
832 subsection documents the x86 watchpoint facilities in @value{GDBN}.
833
834 (At present, the library functions read and write debug registers directly, and are
835 thus only available for native configurations.)
836
837 To use the generic x86 watchpoint support, a port should do the
838 following:
839
840 @itemize @bullet
841 @findex I386_USE_GENERIC_WATCHPOINTS
842 @item
843 Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the
844 target-dependent headers.
845
846 @item
847 Include the @file{config/i386/nm-i386.h} header file @emph{after}
848 defining @code{I386_USE_GENERIC_WATCHPOINTS}.
849
850 @item
851 Add @file{i386-nat.o} to the value of the Make variable
852 @code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}).
853
854 @item
855 Provide implementations for the @code{I386_DR_LOW_*} macros described
856 below.  Typically, each macro should call a target-specific function
857 which does the real work.
858 @end itemize
859
860 The x86 watchpoint support works by maintaining mirror images of the
861 debug registers.  Values are copied between the mirror images and the
862 real debug registers via a set of macros which each target needs to
863 provide:
864
865 @table @code
866 @findex I386_DR_LOW_SET_CONTROL
867 @item I386_DR_LOW_SET_CONTROL (@var{val})
868 Set the Debug Control (DR7) register to the value @var{val}.
869
870 @findex I386_DR_LOW_SET_ADDR
871 @item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr})
872 Put the address @var{addr} into the debug register number @var{idx}.
873
874 @findex I386_DR_LOW_RESET_ADDR
875 @item I386_DR_LOW_RESET_ADDR (@var{idx})
876 Reset (i.e.@: zero out) the address stored in the debug register
877 number @var{idx}.
878
879 @findex I386_DR_LOW_GET_STATUS
880 @item I386_DR_LOW_GET_STATUS
881 Return the value of the Debug Status (DR6) register.  This value is
882 used immediately after it is returned by
883 @code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status
884 register values.
885 @end table
886
887 For each one of the 4 debug registers (whose indices are from 0 to 3)
888 that store addresses, a reference count is maintained by @value{GDBN},
889 to allow sharing of debug registers by several watchpoints.  This
890 allows users to define several watchpoints that watch the same
891 expression, but with different conditions and/or commands, without
892 wasting debug registers which are in short supply.  @value{GDBN}
893 maintains the reference counts internally, targets don't have to do
894 anything to use this feature.
895
896 The x86 debug registers can each watch a region that is 1, 2, or 4
897 bytes long.  The ia32 architecture requires that each watched region
898 be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte
899 region on 4-byte boundary.  However, the x86 watchpoint support in
900 @value{GDBN} can watch unaligned regions and regions larger than 4
901 bytes (up to 16 bytes) by allocating several debug registers to watch
902 a single region.  This allocation of several registers per a watched
903 region is also done automatically without target code intervention.
904
905 The generic x86 watchpoint support provides the following API for the
906 @value{GDBN}'s application code:
907
908 @table @code
909 @findex i386_region_ok_for_watchpoint
910 @item i386_region_ok_for_watchpoint (@var{addr}, @var{len})
911 The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call
912 this function.  It counts the number of debug registers required to
913 watch a given region, and returns a non-zero value if that number is
914 less than 4, the number of debug registers available to x86
915 processors.
916
917 @findex i386_stopped_data_address
918 @item i386_stopped_data_address (@var{addr_p})
919 The target function
920 @code{target_stopped_data_address} is set to call this function.
921 This
922 function examines the breakpoint condition bits in the DR6 Debug
923 Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
924 macro, and returns the address associated with the first bit that is
925 set in DR6.
926
927 @findex i386_stopped_by_watchpoint
928 @item i386_stopped_by_watchpoint (void)
929 The macro @code{STOPPED_BY_WATCHPOINT}
930 is set to call this function.  The
931 argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored.  This
932 function examines the breakpoint condition bits in the DR6 Debug
933 Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
934 macro, and returns true if any bit is set.  Otherwise, false is
935 returned.
936
937 @findex i386_insert_watchpoint
938 @findex i386_remove_watchpoint
939 @item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
940 @itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type})
941 Insert or remove a watchpoint.  The macros
942 @code{target_insert_watchpoint} and @code{target_remove_watchpoint}
943 are set to call these functions.  @code{i386_insert_watchpoint} first
944 looks for a debug register which is already set to watch the same
945 region for the same access types; if found, it just increments the
946 reference count of that debug register, thus implementing debug
947 register sharing between watchpoints.  If no such register is found,
948 the function looks for a vacant debug register, sets its mirrored
949 value to @var{addr}, sets the mirrored value of DR7 Debug Control
950 register as appropriate for the @var{len} and @var{type} parameters,
951 and then passes the new values of the debug register and DR7 to the
952 inferior by calling @code{I386_DR_LOW_SET_ADDR} and
953 @code{I386_DR_LOW_SET_CONTROL}.  If more than one debug register is
954 required to cover the given region, the above process is repeated for
955 each debug register.
956
957 @code{i386_remove_watchpoint} does the opposite: it resets the address
958 in the mirrored value of the debug register and its read/write and
959 length bits in the mirrored value of DR7, then passes these new
960 values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and
961 @code{I386_DR_LOW_SET_CONTROL}.  If a register is shared by several
962 watchpoints, each time a @code{i386_remove_watchpoint} is called, it
963 decrements the reference count, and only calls
964 @code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when
965 the count goes to zero.
966
967 @findex i386_insert_hw_breakpoint
968 @findex i386_remove_hw_breakpoint
969 @item i386_insert_hw_breakpoint (@var{bp_tgt})
970 @itemx i386_remove_hw_breakpoint (@var{bp_tgt})
971 These functions insert and remove hardware-assisted breakpoints.  The
972 macros @code{target_insert_hw_breakpoint} and
973 @code{target_remove_hw_breakpoint} are set to call these functions.
974 The argument is a @code{struct bp_target_info *}, as described in
975 the documentation for @code{target_insert_breakpoint}.
976 These functions work like @code{i386_insert_watchpoint} and
977 @code{i386_remove_watchpoint}, respectively, except that they set up
978 the debug registers to watch instruction execution, and each
979 hardware-assisted breakpoint always requires exactly one debug
980 register.
981
982 @findex i386_cleanup_dregs
983 @item i386_cleanup_dregs (void)
984 This function clears all the reference counts, addresses, and control
985 bits in the mirror images of the debug registers.  It doesn't affect
986 the actual debug registers in the inferior process.
987 @end table
988
989 @noindent
990 @strong{Notes:}
991 @enumerate 1
992 @item
993 x86 processors support setting watchpoints on I/O reads or writes.
994 However, since no target supports this (as of March 2001), and since
995 @code{enum target_hw_bp_type} doesn't even have an enumeration for I/O
996 watchpoints, this feature is not yet available to @value{GDBN} running
997 on x86.
998
999 @item
1000 x86 processors can enable watchpoints locally, for the current task
1001 only, or globally, for all the tasks.  For each debug register,
1002 there's a bit in the DR7 Debug Control register that determines
1003 whether the associated address is watched locally or globally.  The
1004 current implementation of x86 watchpoint support in @value{GDBN}
1005 always sets watchpoints to be locally enabled, since global
1006 watchpoints might interfere with the underlying OS and are probably
1007 unavailable in many platforms.
1008 @end enumerate
1009
1010 @section Checkpoints
1011 @cindex checkpoints
1012 @cindex restart
1013 In the abstract, a checkpoint is a point in the execution history of
1014 the program, which the user may wish to return to at some later time.
1015
1016 Internally, a checkpoint is a saved copy of the program state, including
1017 whatever information is required in order to restore the program to that
1018 state at a later time.  This can be expected to include the state of 
1019 registers and memory, and may include external state such as the state
1020 of open files and devices.
1021
1022 There are a number of ways in which checkpoints may be implemented
1023 in gdb, e.g.@: as corefiles, as forked processes, and as some opaque
1024 method implemented on the target side.
1025
1026 A corefile can be used to save an image of target memory and register
1027 state, which can in principle be restored later --- but corefiles do
1028 not typically include information about external entities such as 
1029 open files.  Currently this method is not implemented in gdb.
1030
1031 A forked process can save the state of user memory and registers, 
1032 as well as some subset of external (kernel) state.  This method 
1033 is used to implement checkpoints on Linux, and in principle might
1034 be used on other systems.
1035
1036 Some targets, e.g.@: simulators, might have their own built-in 
1037 method for saving checkpoints, and gdb might be able to take
1038 advantage of that capability without necessarily knowing any
1039 details of how it is done.
1040
1041
1042 @section Observing changes in @value{GDBN} internals
1043 @cindex observer pattern interface
1044 @cindex notifications about changes in internals
1045
1046 In order to function properly, several modules need to be notified when
1047 some changes occur in the @value{GDBN} internals.  Traditionally, these
1048 modules have relied on several paradigms, the most common ones being
1049 hooks and gdb-events.  Unfortunately, none of these paradigms was
1050 versatile enough to become the standard notification mechanism in
1051 @value{GDBN}.  The fact that they only supported one ``client'' was also
1052 a strong limitation.
1053
1054 A new paradigm, based on the Observer pattern of the @cite{Design
1055 Patterns} book, has therefore been implemented.  The goal was to provide
1056 a new interface overcoming the issues with the notification mechanisms
1057 previously available.  This new interface needed to be strongly typed,
1058 easy to extend, and versatile enough to be used as the standard
1059 interface when adding new notifications.
1060
1061 See @ref{GDB Observers} for a brief description of the observers
1062 currently implemented in GDB. The rationale for the current
1063 implementation is also briefly discussed.
1064
1065 @node User Interface
1066
1067 @chapter User Interface
1068
1069 @value{GDBN} has several user interfaces, of which the traditional
1070 command-line interface is perhaps the most familiar.
1071
1072 @section Command Interpreter
1073
1074 @cindex command interpreter
1075 @cindex CLI
1076 The command interpreter in @value{GDBN} is fairly simple.  It is designed to
1077 allow for the set of commands to be augmented dynamically, and also
1078 has a recursive subcommand capability, where the first argument to
1079 a command may itself direct a lookup on a different command list.
1080
1081 For instance, the @samp{set} command just starts a lookup on the
1082 @code{setlist} command list, while @samp{set thread} recurses
1083 to the @code{set_thread_cmd_list}.
1084
1085 @findex add_cmd
1086 @findex add_com
1087 To add commands in general, use @code{add_cmd}.  @code{add_com} adds to
1088 the main command list, and should be used for those commands.  The usual
1089 place to add commands is in the @code{_initialize_@var{xyz}} routines at
1090 the ends of most source files.
1091
1092 @findex add_setshow_cmd
1093 @findex add_setshow_cmd_full
1094 To add paired @samp{set} and @samp{show} commands, use
1095 @code{add_setshow_cmd} or @code{add_setshow_cmd_full}.  The former is
1096 a slightly simpler interface which is useful when you don't need to
1097 further modify the new command structures, while the latter returns
1098 the new command structures for manipulation.
1099
1100 @cindex deprecating commands
1101 @findex deprecate_cmd
1102 Before removing commands from the command set it is a good idea to
1103 deprecate them for some time.  Use @code{deprecate_cmd} on commands or
1104 aliases to set the deprecated flag.  @code{deprecate_cmd} takes a
1105 @code{struct cmd_list_element} as it's first argument.  You can use the
1106 return value from @code{add_com} or @code{add_cmd} to deprecate the
1107 command immediately after it is created.
1108
1109 The first time a command is used the user will be warned and offered a
1110 replacement (if one exists). Note that the replacement string passed to
1111 @code{deprecate_cmd} should be the full name of the command, i.e., the
1112 entire string the user should type at the command line.
1113
1114 @anchor{UI-Independent Output}
1115 @section UI-Independent Output---the @code{ui_out} Functions
1116 @c This section is based on the documentation written by Fernando
1117 @c Nasser <fnasser@redhat.com>.
1118
1119 @cindex @code{ui_out} functions
1120 The @code{ui_out} functions present an abstraction level for the
1121 @value{GDBN} output code.  They hide the specifics of different user
1122 interfaces supported by @value{GDBN}, and thus free the programmer
1123 from the need to write several versions of the same code, one each for
1124 every UI, to produce output.
1125
1126 @subsection Overview and Terminology
1127
1128 In general, execution of each @value{GDBN} command produces some sort
1129 of output, and can even generate an input request.
1130
1131 Output can be generated for the following purposes:
1132
1133 @itemize @bullet
1134 @item
1135 to display a @emph{result} of an operation;
1136
1137 @item
1138 to convey @emph{info} or produce side-effects of a requested
1139 operation;
1140
1141 @item
1142 to provide a @emph{notification} of an asynchronous event (including
1143 progress indication of a prolonged asynchronous operation);
1144
1145 @item
1146 to display @emph{error messages} (including warnings);
1147
1148 @item
1149 to show @emph{debug data};
1150
1151 @item
1152 to @emph{query} or prompt a user for input (a special case).
1153 @end itemize
1154
1155 @noindent
1156 This section mainly concentrates on how to build result output,
1157 although some of it also applies to other kinds of output.
1158
1159 Generation of output that displays the results of an operation
1160 involves one or more of the following:
1161
1162 @itemize @bullet
1163 @item
1164 output of the actual data
1165
1166 @item
1167 formatting the output as appropriate for console output, to make it
1168 easily readable by humans
1169
1170 @item
1171 machine oriented formatting--a more terse formatting to allow for easy
1172 parsing by programs which read @value{GDBN}'s output
1173
1174 @item
1175 annotation, whose purpose is to help legacy GUIs to identify interesting
1176 parts in the output
1177 @end itemize
1178
1179 The @code{ui_out} routines take care of the first three aspects.
1180 Annotations are provided by separate annotation routines.  Note that use
1181 of annotations for an interface between a GUI and @value{GDBN} is
1182 deprecated.
1183
1184 Output can be in the form of a single item, which we call a @dfn{field};
1185 a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
1186 non-identical fields; or a @dfn{table}, which is a tuple consisting of a
1187 header and a body.  In a BNF-like form:
1188
1189 @table @code
1190 @item <table> @expansion{}
1191 @code{<header> <body>}
1192 @item <header> @expansion{}
1193 @code{@{ <column> @}}
1194 @item <column> @expansion{}
1195 @code{<width> <alignment> <title>}
1196 @item <body> @expansion{}
1197 @code{@{<row>@}}
1198 @end table
1199
1200
1201 @subsection General Conventions
1202
1203 Most @code{ui_out} routines are of type @code{void}, the exceptions are
1204 @code{ui_out_stream_new} (which returns a pointer to the newly created
1205 object) and the @code{make_cleanup} routines.
1206
1207 The first parameter is always the @code{ui_out} vector object, a pointer
1208 to a @code{struct ui_out}.
1209
1210 The @var{format} parameter is like in @code{printf} family of functions.
1211 When it is present, there must also be a variable list of arguments
1212 sufficient used to satisfy the @code{%} specifiers in the supplied
1213 format.
1214
1215 When a character string argument is not used in a @code{ui_out} function
1216 call, a @code{NULL} pointer has to be supplied instead.
1217
1218
1219 @subsection Table, Tuple and List Functions
1220
1221 @cindex list output functions
1222 @cindex table output functions
1223 @cindex tuple output functions
1224 This section introduces @code{ui_out} routines for building lists,
1225 tuples and tables.  The routines to output the actual data items
1226 (fields) are presented in the next section.
1227
1228 To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
1229 containing information about an object; a @dfn{list} is a sequence of
1230 fields where each field describes an identical object.
1231
1232 Use the @dfn{table} functions when your output consists of a list of
1233 rows (tuples) and the console output should include a heading.  Use this
1234 even when you are listing just one object but you still want the header.
1235
1236 @cindex nesting level in @code{ui_out} functions
1237 Tables can not be nested.  Tuples and lists can be nested up to a
1238 maximum of five levels.
1239
1240 The overall structure of the table output code is something like this:
1241
1242 @smallexample
1243   ui_out_table_begin
1244     ui_out_table_header
1245     @dots{}
1246     ui_out_table_body
1247       ui_out_tuple_begin
1248         ui_out_field_*
1249         @dots{}
1250       ui_out_tuple_end
1251       @dots{}
1252   ui_out_table_end
1253 @end smallexample
1254
1255 Here is the description of table-, tuple- and list-related @code{ui_out}
1256 functions:
1257
1258 @deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
1259 The function @code{ui_out_table_begin} marks the beginning of the output
1260 of a table.  It should always be called before any other @code{ui_out}
1261 function for a given table.  @var{nbrofcols} is the number of columns in
1262 the table. @var{nr_rows} is the number of rows in the table.
1263 @var{tblid} is an optional string identifying the table.  The string
1264 pointed to by @var{tblid} is copied by the implementation of
1265 @code{ui_out_table_begin}, so the application can free the string if it
1266 was @code{malloc}ed.
1267
1268 The companion function @code{ui_out_table_end}, described below, marks
1269 the end of the table's output.
1270 @end deftypefun
1271
1272 @deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})
1273 @code{ui_out_table_header} provides the header information for a single
1274 table column.  You call this function several times, one each for every
1275 column of the table, after @code{ui_out_table_begin}, but before
1276 @code{ui_out_table_body}.
1277
1278 The value of @var{width} gives the column width in characters.  The
1279 value of @var{alignment} is one of @code{left}, @code{center}, and
1280 @code{right}, and it specifies how to align the header: left-justify,
1281 center, or right-justify it.  @var{colhdr} points to a string that
1282 specifies the column header; the implementation copies that string, so
1283 column header strings in @code{malloc}ed storage can be freed after the
1284 call.
1285 @end deftypefun
1286
1287 @deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
1288 This function delimits the table header from the table body.
1289 @end deftypefun
1290
1291 @deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
1292 This function signals the end of a table's output.  It should be called
1293 after the table body has been produced by the list and field output
1294 functions.
1295
1296 There should be exactly one call to @code{ui_out_table_end} for each
1297 call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
1298 will signal an internal error.
1299 @end deftypefun
1300
1301 The output of the tuples that represent the table rows must follow the
1302 call to @code{ui_out_table_body} and precede the call to
1303 @code{ui_out_table_end}.  You build a tuple by calling
1304 @code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
1305 calls to functions which actually output fields between them.
1306
1307 @deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})
1308 This function marks the beginning of a tuple output.  @var{id} points
1309 to an optional string that identifies the tuple; it is copied by the
1310 implementation, and so strings in @code{malloc}ed storage can be freed
1311 after the call.
1312 @end deftypefun
1313
1314 @deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
1315 This function signals an end of a tuple output.  There should be exactly
1316 one call to @code{ui_out_tuple_end} for each call to
1317 @code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
1318 be signaled.
1319 @end deftypefun
1320
1321 @deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
1322 This function first opens the tuple and then establishes a cleanup
1323 (@pxref{Misc Guidelines, Cleanups}) to close the tuple.
1324 It provides a convenient and correct implementation of the
1325 non-portable@footnote{The function cast is not portable ISO C.} code sequence:
1326 @smallexample
1327 struct cleanup *old_cleanup;
1328 ui_out_tuple_begin (uiout, "...");
1329 old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
1330                             uiout);
1331 @end smallexample
1332 @end deftypefun
1333
1334 @deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})
1335 This function marks the beginning of a list output.  @var{id} points to
1336 an optional string that identifies the list; it is copied by the
1337 implementation, and so strings in @code{malloc}ed storage can be freed
1338 after the call.
1339 @end deftypefun
1340
1341 @deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
1342 This function signals an end of a list output.  There should be exactly
1343 one call to @code{ui_out_list_end} for each call to
1344 @code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
1345 be signaled.
1346 @end deftypefun
1347
1348 @deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
1349 Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
1350 opens a list and then establishes cleanup
1351 (@pxref{Misc Guidelines, Cleanups})
1352 that will close the list.
1353 @end deftypefun
1354
1355 @subsection Item Output Functions
1356
1357 @cindex item output functions
1358 @cindex field output functions
1359 @cindex data output
1360 The functions described below produce output for the actual data
1361 items, or fields, which contain information about the object.
1362
1363 Choose the appropriate function accordingly to your particular needs.
1364
1365 @deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...)
1366 This is the most general output function.  It produces the
1367 representation of the data in the variable-length argument list
1368 according to formatting specifications in @var{format}, a
1369 @code{printf}-like format string.  The optional argument @var{fldname}
1370 supplies the name of the field.  The data items themselves are
1371 supplied as additional arguments after @var{format}.
1372
1373 This generic function should be used only when it is not possible to
1374 use one of the specialized versions (see below).
1375 @end deftypefun
1376
1377 @deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
1378 This function outputs a value of an @code{int} variable.  It uses the
1379 @code{"%d"} output conversion specification.  @var{fldname} specifies
1380 the name of the field.
1381 @end deftypefun
1382
1383 @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})
1384 This function outputs a value of an @code{int} variable.  It differs from
1385 @code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output.
1386 @var{fldname} specifies
1387 the name of the field.
1388 @end deftypefun
1389
1390 @deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address})
1391 This function outputs an address as appropriate for @var{gdbarch}.
1392 @end deftypefun
1393
1394 @deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
1395 This function outputs a string using the @code{"%s"} conversion
1396 specification.
1397 @end deftypefun
1398
1399 Sometimes, there's a need to compose your output piece by piece using
1400 functions that operate on a stream, such as @code{value_print} or
1401 @code{fprintf_symbol_filtered}.  These functions accept an argument of
1402 the type @code{struct ui_file *}, a pointer to a @code{ui_file} object
1403 used to store the data stream used for the output.  When you use one
1404 of these functions, you need a way to pass their results stored in a
1405 @code{ui_file} object to the @code{ui_out} functions.  To this end,
1406 you first create a @code{ui_stream} object by calling
1407 @code{ui_out_stream_new}, pass the @code{stream} member of that
1408 @code{ui_stream} object to @code{value_print} and similar functions,
1409 and finally call @code{ui_out_field_stream} to output the field you
1410 constructed.  When the @code{ui_stream} object is no longer needed,
1411 you should destroy it and free its memory by calling
1412 @code{ui_out_stream_delete}.
1413
1414 @deftypefun {struct ui_stream *} ui_out_stream_new (struct ui_out *@var{uiout})
1415 This function creates a new @code{ui_stream} object which uses the
1416 same output methods as the @code{ui_out} object whose pointer is
1417 passed in @var{uiout}.  It returns a pointer to the newly created
1418 @code{ui_stream} object.
1419 @end deftypefun
1420
1421 @deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf})
1422 This functions destroys a @code{ui_stream} object specified by
1423 @var{streambuf}.
1424 @end deftypefun
1425
1426 @deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
1427 This function consumes all the data accumulated in
1428 @code{streambuf->stream} and outputs it like
1429 @code{ui_out_field_string} does.  After a call to
1430 @code{ui_out_field_stream}, the accumulated data no longer exists, but
1431 the stream is still valid and may be used for producing more fields.
1432 @end deftypefun
1433
1434 @strong{Important:} If there is any chance that your code could bail
1435 out before completing output generation and reaching the point where
1436 @code{ui_out_stream_delete} is called, it is necessary to set up a
1437 cleanup, to avoid leaking memory and other resources.  Here's a
1438 skeleton code to do that:
1439
1440 @smallexample
1441  struct ui_stream *mybuf = ui_out_stream_new (uiout);
1442  struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
1443  ...
1444  do_cleanups (old);
1445 @end smallexample
1446
1447 If the function already has the old cleanup chain set (for other kinds
1448 of cleanups), you just have to add your cleanup to it:
1449
1450 @smallexample
1451   mybuf = ui_out_stream_new (uiout);
1452   make_cleanup (ui_out_stream_delete, mybuf);
1453 @end smallexample
1454
1455 Note that with cleanups in place, you should not call
1456 @code{ui_out_stream_delete} directly, or you would attempt to free the
1457 same buffer twice.
1458
1459 @subsection Utility Output Functions
1460
1461 @deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
1462 This function skips a field in a table.  Use it if you have to leave
1463 an empty field without disrupting the table alignment.  The argument
1464 @var{fldname} specifies a name for the (missing) filed.
1465 @end deftypefun
1466
1467 @deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
1468 This function outputs the text in @var{string} in a way that makes it
1469 easy to be read by humans.  For example, the console implementation of
1470 this method filters the text through a built-in pager, to prevent it
1471 from scrolling off the visible portion of the screen.
1472
1473 Use this function for printing relatively long chunks of text around
1474 the actual field data: the text it produces is not aligned according
1475 to the table's format.  Use @code{ui_out_field_string} to output a
1476 string field, and use @code{ui_out_message}, described below, to
1477 output short messages.
1478 @end deftypefun
1479
1480 @deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})
1481 This function outputs @var{nspaces} spaces.  It is handy to align the
1482 text produced by @code{ui_out_text} with the rest of the table or
1483 list.
1484 @end deftypefun
1485
1486 @deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
1487 This function produces a formatted message, provided that the current
1488 verbosity level is at least as large as given by @var{verbosity}.  The
1489 current verbosity level is specified by the user with the @samp{set
1490 verbositylevel} command.@footnote{As of this writing (April 2001),
1491 setting verbosity level is not yet implemented, and is always returned
1492 as zero.  So calling @code{ui_out_message} with a @var{verbosity}
1493 argument more than zero will cause the message to never be printed.}
1494 @end deftypefun
1495
1496 @deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent})
1497 This function gives the console output filter (a paging filter) a hint
1498 of where to break lines which are too long.  Ignored for all other
1499 output consumers.  @var{indent}, if non-@code{NULL}, is the string to
1500 be printed to indent the wrapped text on the next line; it must remain
1501 accessible until the next call to @code{ui_out_wrap_hint}, or until an
1502 explicit newline is produced by one of the other functions.  If
1503 @var{indent} is @code{NULL}, the wrapped text will not be indented.
1504 @end deftypefun
1505
1506 @deftypefun void ui_out_flush (struct ui_out *@var{uiout})
1507 This function flushes whatever output has been accumulated so far, if
1508 the UI buffers output.
1509 @end deftypefun
1510
1511
1512 @subsection Examples of Use of @code{ui_out} functions
1513
1514 @cindex using @code{ui_out} functions
1515 @cindex @code{ui_out} functions, usage examples
1516 This section gives some practical examples of using the @code{ui_out}
1517 functions to generalize the old console-oriented code in
1518 @value{GDBN}.  The examples all come from functions defined on the
1519 @file{breakpoints.c} file.
1520
1521 This example, from the @code{breakpoint_1} function, shows how to
1522 produce a table.
1523
1524 The original code was:
1525
1526 @smallexample
1527  if (!found_a_breakpoint++)
1528    @{
1529      annotate_breakpoints_headers ();
1530
1531      annotate_field (0);
1532      printf_filtered ("Num ");
1533      annotate_field (1);
1534      printf_filtered ("Type           ");
1535      annotate_field (2);
1536      printf_filtered ("Disp ");
1537      annotate_field (3);
1538      printf_filtered ("Enb ");
1539      if (addressprint)
1540        @{
1541          annotate_field (4);
1542          printf_filtered ("Address    ");
1543        @}
1544      annotate_field (5);
1545      printf_filtered ("What\n");
1546
1547      annotate_breakpoints_table ();
1548    @}
1549 @end smallexample
1550
1551 Here's the new version:
1552
1553 @smallexample
1554   nr_printable_breakpoints = @dots{};
1555
1556   if (addressprint)
1557     ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
1558   else
1559     ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
1560
1561   if (nr_printable_breakpoints > 0)
1562     annotate_breakpoints_headers ();
1563   if (nr_printable_breakpoints > 0)
1564     annotate_field (0);
1565   ui_out_table_header (uiout, 3, ui_left, "number", "Num");             /* 1 */
1566   if (nr_printable_breakpoints > 0)
1567     annotate_field (1);
1568   ui_out_table_header (uiout, 14, ui_left, "type", "Type");             /* 2 */
1569   if (nr_printable_breakpoints > 0)
1570     annotate_field (2);
1571   ui_out_table_header (uiout, 4, ui_left, "disp", "Disp");              /* 3 */
1572   if (nr_printable_breakpoints > 0)
1573     annotate_field (3);
1574   ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb");    /* 4 */
1575   if (addressprint)
1576     @{
1577      if (nr_printable_breakpoints > 0)
1578        annotate_field (4);
1579      if (print_address_bits <= 32)
1580        ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
1581      else
1582        ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
1583     @}
1584   if (nr_printable_breakpoints > 0)
1585     annotate_field (5);
1586   ui_out_table_header (uiout, 40, ui_noalign, "what", "What");  /* 6 */
1587   ui_out_table_body (uiout);
1588   if (nr_printable_breakpoints > 0)
1589     annotate_breakpoints_table ();
1590 @end smallexample
1591
1592 This example, from the @code{print_one_breakpoint} function, shows how
1593 to produce the actual data for the table whose structure was defined
1594 in the above example.  The original code was:
1595
1596 @smallexample
1597    annotate_record ();
1598    annotate_field (0);
1599    printf_filtered ("%-3d ", b->number);
1600    annotate_field (1);
1601    if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
1602        || ((int) b->type != bptypes[(int) b->type].type))
1603      internal_error ("bptypes table does not describe type #%d.",
1604                      (int)b->type);
1605    printf_filtered ("%-14s ", bptypes[(int)b->type].description);
1606    annotate_field (2);
1607    printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
1608    annotate_field (3);
1609    printf_filtered ("%-3c ", bpenables[(int)b->enable]);
1610    @dots{}
1611 @end smallexample
1612
1613 This is the new version:
1614
1615 @smallexample
1616    annotate_record ();
1617    ui_out_tuple_begin (uiout, "bkpt");
1618    annotate_field (0);
1619    ui_out_field_int (uiout, "number", b->number);
1620    annotate_field (1);
1621    if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
1622        || ((int) b->type != bptypes[(int) b->type].type))
1623      internal_error ("bptypes table does not describe type #%d.",
1624                      (int) b->type);
1625    ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
1626    annotate_field (2);
1627    ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
1628    annotate_field (3);
1629    ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
1630    @dots{}
1631 @end smallexample
1632
1633 This example, also from @code{print_one_breakpoint}, shows how to
1634 produce a complicated output field using the @code{print_expression}
1635 functions which requires a stream to be passed.  It also shows how to
1636 automate stream destruction with cleanups.  The original code was:
1637
1638 @smallexample
1639     annotate_field (5);
1640     print_expression (b->exp, gdb_stdout);
1641 @end smallexample
1642
1643 The new version is:
1644
1645 @smallexample
1646   struct ui_stream *stb = ui_out_stream_new (uiout);
1647   struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
1648   ...
1649   annotate_field (5);
1650   print_expression (b->exp, stb->stream);
1651   ui_out_field_stream (uiout, "what", local_stream);
1652 @end smallexample
1653
1654 This example, also from @code{print_one_breakpoint}, shows how to use
1655 @code{ui_out_text} and @code{ui_out_field_string}.  The original code
1656 was:
1657
1658 @smallexample
1659   annotate_field (5);
1660   if (b->dll_pathname == NULL)
1661     printf_filtered ("<any library> ");
1662   else
1663     printf_filtered ("library \"%s\" ", b->dll_pathname);
1664 @end smallexample
1665
1666 It became:
1667
1668 @smallexample
1669   annotate_field (5);
1670   if (b->dll_pathname == NULL)
1671     @{
1672       ui_out_field_string (uiout, "what", "<any library>");
1673       ui_out_spaces (uiout, 1);
1674     @}
1675   else
1676     @{
1677       ui_out_text (uiout, "library \"");
1678       ui_out_field_string (uiout, "what", b->dll_pathname);
1679       ui_out_text (uiout, "\" ");
1680     @}
1681 @end smallexample
1682
1683 The following example from @code{print_one_breakpoint} shows how to
1684 use @code{ui_out_field_int} and @code{ui_out_spaces}.  The original
1685 code was:
1686
1687 @smallexample
1688   annotate_field (5);
1689   if (b->forked_inferior_pid != 0)
1690     printf_filtered ("process %d ", b->forked_inferior_pid);
1691 @end smallexample
1692
1693 It became:
1694
1695 @smallexample
1696   annotate_field (5);
1697   if (b->forked_inferior_pid != 0)
1698     @{
1699       ui_out_text (uiout, "process ");
1700       ui_out_field_int (uiout, "what", b->forked_inferior_pid);
1701       ui_out_spaces (uiout, 1);
1702     @}
1703 @end smallexample
1704
1705 Here's an example of using @code{ui_out_field_string}.  The original
1706 code was:
1707
1708 @smallexample
1709   annotate_field (5);
1710   if (b->exec_pathname != NULL)
1711     printf_filtered ("program \"%s\" ", b->exec_pathname);
1712 @end smallexample
1713
1714 It became:
1715
1716 @smallexample
1717   annotate_field (5);
1718   if (b->exec_pathname != NULL)
1719     @{
1720       ui_out_text (uiout, "program \"");
1721       ui_out_field_string (uiout, "what", b->exec_pathname);
1722       ui_out_text (uiout, "\" ");
1723     @}
1724 @end smallexample
1725
1726 Finally, here's an example of printing an address.  The original code:
1727
1728 @smallexample
1729   annotate_field (4);
1730   printf_filtered ("%s ",
1731         hex_string_custom ((unsigned long) b->address, 8));
1732 @end smallexample
1733
1734 It became:
1735
1736 @smallexample
1737   annotate_field (4);
1738   ui_out_field_core_addr (uiout, "Address", b->address);
1739 @end smallexample
1740
1741
1742 @section Console Printing
1743
1744 @section TUI
1745
1746 @node libgdb
1747
1748 @chapter libgdb
1749
1750 @section libgdb 1.0
1751 @cindex @code{libgdb}
1752 @code{libgdb} 1.0 was an abortive project of years ago.  The theory was
1753 to provide an API to @value{GDBN}'s functionality.
1754
1755 @section libgdb 2.0
1756 @cindex @code{libgdb}
1757 @code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is
1758 better able to support graphical and other environments.
1759
1760 Since @code{libgdb} development is on-going, its architecture is still
1761 evolving.  The following components have so far been identified:
1762
1763 @itemize @bullet
1764 @item
1765 Observer - @file{gdb-events.h}.  
1766 @item
1767 Builder - @file{ui-out.h}
1768 @item
1769 Event Loop - @file{event-loop.h}
1770 @item
1771 Library - @file{gdb.h}
1772 @end itemize
1773
1774 The model that ties these components together is described below.
1775
1776 @section The @code{libgdb} Model
1777
1778 A client of @code{libgdb} interacts with the library in two ways.
1779
1780 @itemize @bullet
1781 @item
1782 As an observer (using @file{gdb-events}) receiving notifications from
1783 @code{libgdb} of any internal state changes (break point changes, run
1784 state, etc).
1785 @item
1786 As a client querying @code{libgdb} (using the @file{ui-out} builder) to
1787 obtain various status values from @value{GDBN}.
1788 @end itemize
1789
1790 Since @code{libgdb} could have multiple clients (e.g., a GUI supporting
1791 the existing @value{GDBN} CLI), those clients must co-operate when
1792 controlling @code{libgdb}.  In particular, a client must ensure that
1793 @code{libgdb} is idle (i.e.@: no other client is using @code{libgdb})
1794 before responding to a @file{gdb-event} by making a query.
1795
1796 @section CLI support
1797
1798 At present @value{GDBN}'s CLI is very much entangled in with the core of
1799 @code{libgdb}.  Consequently, a client wishing to include the CLI in
1800 their interface needs to carefully co-ordinate its own and the CLI's
1801 requirements.
1802
1803 It is suggested that the client set @code{libgdb} up to be bi-modal
1804 (alternate between CLI and client query modes).  The notes below sketch
1805 out the theory:
1806
1807 @itemize @bullet
1808 @item
1809 The client registers itself as an observer of @code{libgdb}.
1810 @item
1811 The client create and install @code{cli-out} builder using its own
1812 versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and
1813 @code{gdb_stdout} streams.
1814 @item
1815 The client creates a separate custom @code{ui-out} builder that is only
1816 used while making direct queries to @code{libgdb}.
1817 @end itemize
1818
1819 When the client receives input intended for the CLI, it simply passes it
1820 along.  Since the @code{cli-out} builder is installed by default, all
1821 the CLI output in response to that command is routed (pronounced rooted)
1822 through to the client controlled @code{gdb_stdout} et.@: al.@: streams.
1823 At the same time, the client is kept abreast of internal changes by
1824 virtue of being a @code{libgdb} observer.
1825
1826 The only restriction on the client is that it must wait until
1827 @code{libgdb} becomes idle before initiating any queries (using the
1828 client's custom builder).
1829
1830 @section @code{libgdb} components
1831
1832 @subheading Observer - @file{gdb-events.h}
1833 @file{gdb-events} provides the client with a very raw mechanism that can
1834 be used to implement an observer.  At present it only allows for one
1835 observer and that observer must, internally, handle the need to delay
1836 the processing of any event notifications until after @code{libgdb} has
1837 finished the current command.
1838
1839 @subheading Builder - @file{ui-out.h}
1840 @file{ui-out} provides the infrastructure necessary for a client to
1841 create a builder.  That builder is then passed down to @code{libgdb}
1842 when doing any queries.
1843
1844 @subheading Event Loop - @file{event-loop.h}
1845 @c There could be an entire section on the event-loop
1846 @file{event-loop}, currently non-re-entrant, provides a simple event
1847 loop.  A client would need to either plug its self into this loop or,
1848 implement a new event-loop that @value{GDBN} would use.
1849
1850 The event-loop will eventually be made re-entrant.  This is so that
1851 @value{GDBN} can better handle the problem of some commands blocking
1852 instead of returning.
1853
1854 @subheading Library - @file{gdb.h}
1855 @file{libgdb} is the most obvious component of this system.  It provides
1856 the query interface.  Each function is parameterized by a @code{ui-out}
1857 builder.  The result of the query is constructed using that builder
1858 before the query function returns.
1859
1860 @node Values
1861 @chapter Values
1862 @section Values
1863
1864 @cindex values
1865 @cindex @code{value} structure
1866 @value{GDBN} uses @code{struct value}, or @dfn{values}, as an internal
1867 abstraction for the representation of a variety of inferior objects
1868 and @value{GDBN} convenience objects.
1869
1870 Values have an associated @code{struct type}, that describes a virtual
1871 view of the raw data or object stored in or accessed through the
1872 value.
1873
1874 A value is in addition discriminated by its lvalue-ness, given its
1875 @code{enum lval_type} enumeration type:
1876
1877 @cindex @code{lval_type} enumeration, for values.
1878 @table @code
1879 @item @code{not_lval}
1880 This value is not an lval.  It can't be assigned to.
1881
1882 @item @code{lval_memory}
1883 This value represents an object in memory.
1884
1885 @item @code{lval_register}
1886 This value represents an object that lives in a register.
1887
1888 @item @code{lval_internalvar}
1889 Represents the value of an internal variable.
1890
1891 @item @code{lval_internalvar_component}
1892 Represents part of a @value{GDBN} internal variable.  E.g., a
1893 structure field.
1894
1895 @cindex computed values
1896 @item @code{lval_computed}
1897 These are ``computed'' values.  They allow creating specialized value
1898 objects for specific purposes, all abstracted away from the core value
1899 support code.  The creator of such a value writes specialized
1900 functions to handle the reading and writing to/from the value's
1901 backend data, and optionally, a ``copy operator'' and a
1902 ``destructor''.
1903
1904 Pointers to these functions are stored in a @code{struct lval_funcs}
1905 instance (declared in @file{value.h}), and passed to the
1906 @code{allocate_computed_value} function, as in the example below.
1907
1908 @smallexample
1909 static void
1910 nil_value_read (struct value *v)
1911 @{
1912   /* This callback reads data from some backend, and stores it in V.
1913      In this case, we always read null data.  You'll want to fill in
1914      something more interesting.  */
1915
1916   memset (value_contents_all_raw (v),
1917           value_offset (v),
1918           TYPE_LENGTH (value_type (v)));
1919 @}
1920
1921 static void
1922 nil_value_write (struct value *v, struct value *fromval)
1923 @{
1924   /* Takes the data from FROMVAL and stores it in the backend of V.  */
1925
1926   to_oblivion (value_contents_all_raw (fromval),
1927                value_offset (v),
1928                TYPE_LENGTH (value_type (fromval)));
1929 @}
1930
1931 static struct lval_funcs nil_value_funcs =
1932   @{
1933     nil_value_read,
1934     nil_value_write
1935   @};
1936
1937 struct value *
1938 make_nil_value (void)
1939 @{
1940    struct type *type;
1941    struct value *v;
1942
1943    type = make_nils_type ();
1944    v = allocate_computed_value (type, &nil_value_funcs, NULL);
1945
1946    return v;
1947 @}
1948 @end smallexample
1949
1950 See the implementation of the @code{$_siginfo} convenience variable in
1951 @file{infrun.c} as a real example use of lval_computed.
1952
1953 @end table
1954
1955 @node Stack Frames
1956 @chapter Stack Frames
1957
1958 @cindex frame
1959 @cindex call stack frame
1960 A frame is a construct that @value{GDBN} uses to keep track of calling
1961 and called functions.
1962
1963 @cindex unwind frame
1964 @value{GDBN}'s frame model, a fresh design, was implemented with the
1965 need to support @sc{dwarf}'s Call Frame Information in mind.  In fact,
1966 the term ``unwind'' is taken directly from that specification.
1967 Developers wishing to learn more about unwinders, are encouraged to
1968 read the @sc{dwarf} specification, available from
1969 @url{http://www.dwarfstd.org}.
1970
1971 @findex frame_register_unwind
1972 @findex get_frame_register
1973 @value{GDBN}'s model is that you find a frame's registers by
1974 ``unwinding'' them from the next younger frame.  That is,
1975 @samp{get_frame_register} which returns the value of a register in
1976 frame #1 (the next-to-youngest frame), is implemented by calling frame
1977 #0's @code{frame_register_unwind} (the youngest frame).  But then the
1978 obvious question is: how do you access the registers of the youngest
1979 frame itself?
1980
1981 @cindex sentinel frame
1982 @findex get_frame_type
1983 @vindex SENTINEL_FRAME
1984 To answer this question, @value{GDBN} has the @dfn{sentinel} frame, the
1985 ``-1st'' frame.  Unwinding registers from the sentinel frame gives you
1986 the current values of the youngest real frame's registers.  If @var{f}
1987 is a sentinel frame, then @code{get_frame_type (@var{f}) @equiv{}
1988 SENTINEL_FRAME}.
1989
1990 @section Selecting an Unwinder
1991
1992 @findex frame_unwind_prepend_unwinder
1993 @findex frame_unwind_append_unwinder
1994 The architecture registers a list of frame unwinders (@code{struct
1995 frame_unwind}), using the functions
1996 @code{frame_unwind_prepend_unwinder} and
1997 @code{frame_unwind_append_unwinder}.  Each unwinder includes a
1998 sniffer.  Whenever @value{GDBN} needs to unwind a frame (to fetch the
1999 previous frame's registers or the current frame's ID), it calls
2000 registered sniffers in order to find one which recognizes the frame.
2001 The first time a sniffer returns non-zero, the corresponding unwinder
2002 is assigned to the frame.
2003
2004 @section Unwinding the Frame ID
2005 @cindex frame ID
2006
2007 Every frame has an associated ID, of type @code{struct frame_id}.
2008 The ID includes the stack base and function start address for
2009 the frame.  The ID persists through the entire life of the frame,
2010 including while other called frames are running; it is used to
2011 locate an appropriate @code{struct frame_info} from the cache.
2012
2013 Every time the inferior stops, and at various other times, the frame
2014 cache is flushed.  Because of this, parts of @value{GDBN} which need
2015 to keep track of individual frames cannot use pointers to @code{struct
2016 frame_info}.  A frame ID provides a stable reference to a frame, even
2017 when the unwinder must be run again to generate a new @code{struct
2018 frame_info} for the same frame.
2019
2020 The frame's unwinder's @code{this_id} method is called to find the ID.
2021 Note that this is different from register unwinding, where the next
2022 frame's @code{prev_register} is called to unwind this frame's
2023 registers.
2024
2025 Both stack base and function address are required to identify the
2026 frame, because a recursive function has the same function address for
2027 two consecutive frames and a leaf function may have the same stack
2028 address as its caller.  On some platforms, a third address is part of
2029 the ID to further disambiguate frames---for instance, on IA-64
2030 the separate register stack address is included in the ID.
2031
2032 An invalid frame ID (@code{outer_frame_id}) returned from the
2033 @code{this_id} method means to stop unwinding after this frame.
2034
2035 @code{null_frame_id} is another invalid frame ID which should be used
2036 when there is no frame.  For instance, certain breakpoints are attached
2037 to a specific frame, and that frame is identified through its frame ID
2038 (we use this to implement the "finish" command).  Using
2039 @code{null_frame_id} as the frame ID for a given breakpoint means
2040 that the breakpoint is not specific to any frame.  The @code{this_id}
2041 method should never return @code{null_frame_id}.
2042
2043 @section Unwinding Registers
2044
2045 Each unwinder includes a @code{prev_register} method.  This method
2046 takes a frame, an associated cache pointer, and a register number.
2047 It returns a @code{struct value *} describing the requested register,
2048 as saved by this frame.  This is the value of the register that is
2049 current in this frame's caller.
2050
2051 The returned value must have the same type as the register.  It may
2052 have any lvalue type.  In most circumstances one of these routines
2053 will generate the appropriate value:
2054
2055 @table @code
2056 @item frame_unwind_got_optimized
2057 @findex frame_unwind_got_optimized
2058 This register was not saved.
2059
2060 @item frame_unwind_got_register
2061 @findex frame_unwind_got_register
2062 This register was copied into another register in this frame.  This
2063 is also used for unchanged registers; they are ``copied'' into the
2064 same register.
2065
2066 @item frame_unwind_got_memory
2067 @findex frame_unwind_got_memory
2068 This register was saved in memory.
2069
2070 @item frame_unwind_got_constant
2071 @findex frame_unwind_got_constant
2072 This register was not saved, but the unwinder can compute the previous
2073 value some other way.
2074
2075 @item frame_unwind_got_address
2076 @findex frame_unwind_got_address
2077 Same as @code{frame_unwind_got_constant}, except that the value is a target
2078 address.  This is frequently used for the stack pointer, which is not
2079 explicitly saved but has a known offset from this frame's stack
2080 pointer.  For architectures with a flat unified address space, this is
2081 generally the same as @code{frame_unwind_got_constant}.
2082 @end table
2083
2084 @node Symbol Handling
2085
2086 @chapter Symbol Handling
2087
2088 Symbols are a key part of @value{GDBN}'s operation.  Symbols include
2089 variables, functions, and types.
2090
2091 Symbol information for a large program can be truly massive, and
2092 reading of symbol information is one of the major performance
2093 bottlenecks in @value{GDBN}; it can take many minutes to process it
2094 all.  Studies have shown that nearly all the time spent is
2095 computational, rather than file reading.
2096
2097 One of the ways for @value{GDBN} to provide a good user experience is
2098 to start up quickly, taking no more than a few seconds.  It is simply
2099 not possible to process all of a program's debugging info in that
2100 time, and so we attempt to handle symbols incrementally.  For instance,
2101 we create @dfn{partial symbol tables} consisting of only selected
2102 symbols, and only expand them to full symbol tables when necessary.
2103
2104 @section Symbol Reading
2105
2106 @cindex symbol reading
2107 @cindex reading of symbols
2108 @cindex symbol files
2109 @value{GDBN} reads symbols from @dfn{symbol files}.  The usual symbol
2110 file is the file containing the program which @value{GDBN} is
2111 debugging.  @value{GDBN} can be directed to use a different file for
2112 symbols (with the @samp{symbol-file} command), and it can also read
2113 more symbols via the @samp{add-file} and @samp{load} commands. In
2114 addition, it may bring in more symbols while loading shared
2115 libraries.
2116
2117 @findex find_sym_fns
2118 Symbol files are initially opened by code in @file{symfile.c} using
2119 the BFD library (@pxref{Support Libraries}).  BFD identifies the type
2120 of the file by examining its header.  @code{find_sym_fns} then uses
2121 this identification to locate a set of symbol-reading functions.
2122
2123 @findex add_symtab_fns
2124 @cindex @code{sym_fns} structure
2125 @cindex adding a symbol-reading module
2126 Symbol-reading modules identify themselves to @value{GDBN} by calling
2127 @code{add_symtab_fns} during their module initialization.  The argument
2128 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
2129 name (or name prefix) of the symbol format, the length of the prefix,
2130 and pointers to four functions.  These functions are called at various
2131 times to process symbol files whose identification matches the specified
2132 prefix.
2133
2134 The functions supplied by each module are:
2135
2136 @table @code
2137 @item @var{xyz}_symfile_init(struct sym_fns *sf)
2138
2139 @cindex secondary symbol file
2140 Called from @code{symbol_file_add} when we are about to read a new
2141 symbol file.  This function should clean up any internal state (possibly
2142 resulting from half-read previous files, for example) and prepare to
2143 read a new symbol file.  Note that the symbol file which we are reading
2144 might be a new ``main'' symbol file, or might be a secondary symbol file
2145 whose symbols are being added to the existing symbol table.
2146
2147 The argument to @code{@var{xyz}_symfile_init} is a newly allocated
2148 @code{struct sym_fns} whose @code{bfd} field contains the BFD for the
2149 new symbol file being read.  Its @code{private} field has been zeroed,
2150 and can be modified as desired.  Typically, a struct of private
2151 information will be @code{malloc}'d, and a pointer to it will be placed
2152 in the @code{private} field.
2153
2154 There is no result from @code{@var{xyz}_symfile_init}, but it can call
2155 @code{error} if it detects an unavoidable problem.
2156
2157 @item @var{xyz}_new_init()
2158
2159 Called from @code{symbol_file_add} when discarding existing symbols.
2160 This function needs only handle the symbol-reading module's internal
2161 state; the symbol table data structures visible to the rest of
2162 @value{GDBN} will be discarded by @code{symbol_file_add}.  It has no
2163 arguments and no result.  It may be called after
2164 @code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
2165 may be called alone if all symbols are simply being discarded.
2166
2167 @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
2168
2169 Called from @code{symbol_file_add} to actually read the symbols from a
2170 symbol-file into a set of psymtabs or symtabs.
2171
2172 @code{sf} points to the @code{struct sym_fns} originally passed to
2173 @code{@var{xyz}_sym_init} for possible initialization.  @code{addr} is
2174 the offset between the file's specified start address and its true
2175 address in memory.  @code{mainline} is 1 if this is the main symbol
2176 table being read, and 0 if a secondary symbol file (e.g., shared library
2177 or dynamically loaded file) is being read.@refill
2178 @end table
2179
2180 In addition, if a symbol-reading module creates psymtabs when
2181 @var{xyz}_symfile_read is called, these psymtabs will contain a pointer
2182 to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
2183 from any point in the @value{GDBN} symbol-handling code.
2184
2185 @table @code
2186 @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
2187
2188 Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
2189 the psymtab has not already been read in and had its @code{pst->symtab}
2190 pointer set.  The argument is the psymtab to be fleshed-out into a
2191 symtab.  Upon return, @code{pst->readin} should have been set to 1, and
2192 @code{pst->symtab} should contain a pointer to the new corresponding symtab, or
2193 zero if there were no symbols in that part of the symbol file.
2194 @end table
2195
2196 @section Partial Symbol Tables
2197
2198 @value{GDBN} has three types of symbol tables:
2199
2200 @itemize @bullet
2201 @cindex full symbol table
2202 @cindex symtabs
2203 @item
2204 Full symbol tables (@dfn{symtabs}).  These contain the main
2205 information about symbols and addresses.
2206
2207 @cindex psymtabs
2208 @item
2209 Partial symbol tables (@dfn{psymtabs}).  These contain enough
2210 information to know when to read the corresponding part of the full
2211 symbol table.
2212
2213 @cindex minimal symbol table
2214 @cindex minsymtabs
2215 @item
2216 Minimal symbol tables (@dfn{msymtabs}).  These contain information
2217 gleaned from non-debugging symbols.
2218 @end itemize
2219
2220 @cindex partial symbol table
2221 This section describes partial symbol tables.
2222
2223 A psymtab is constructed by doing a very quick pass over an executable
2224 file's debugging information.  Small amounts of information are
2225 extracted---enough to identify which parts of the symbol table will
2226 need to be re-read and fully digested later, when the user needs the
2227 information.  The speed of this pass causes @value{GDBN} to start up very
2228 quickly.  Later, as the detailed rereading occurs, it occurs in small
2229 pieces, at various times, and the delay therefrom is mostly invisible to
2230 the user.
2231 @c (@xref{Symbol Reading}.)
2232
2233 The symbols that show up in a file's psymtab should be, roughly, those
2234 visible to the debugger's user when the program is not running code from
2235 that file.  These include external symbols and types, static symbols and
2236 types, and @code{enum} values declared at file scope.
2237
2238 The psymtab also contains the range of instruction addresses that the
2239 full symbol table would represent.
2240
2241 @cindex finding a symbol
2242 @cindex symbol lookup
2243 The idea is that there are only two ways for the user (or much of the
2244 code in the debugger) to reference a symbol:
2245
2246 @itemize @bullet
2247 @findex find_pc_function
2248 @findex find_pc_line
2249 @item
2250 By its address (e.g., execution stops at some address which is inside a
2251 function in this file).  The address will be noticed to be in the
2252 range of this psymtab, and the full symtab will be read in.
2253 @code{find_pc_function}, @code{find_pc_line}, and other
2254 @code{find_pc_@dots{}} functions handle this.
2255
2256 @cindex lookup_symbol
2257 @item
2258 By its name
2259 (e.g., the user asks to print a variable, or set a breakpoint on a
2260 function).  Global names and file-scope names will be found in the
2261 psymtab, which will cause the symtab to be pulled in.  Local names will
2262 have to be qualified by a global name, or a file-scope name, in which
2263 case we will have already read in the symtab as we evaluated the
2264 qualifier.  Or, a local symbol can be referenced when we are ``in'' a
2265 local scope, in which case the first case applies.  @code{lookup_symbol}
2266 does most of the work here.
2267 @end itemize
2268
2269 The only reason that psymtabs exist is to cause a symtab to be read in
2270 at the right moment.  Any symbol that can be elided from a psymtab,
2271 while still causing that to happen, should not appear in it.  Since
2272 psymtabs don't have the idea of scope, you can't put local symbols in
2273 them anyway.  Psymtabs don't have the idea of the type of a symbol,
2274 either, so types need not appear, unless they will be referenced by
2275 name.
2276
2277 It is a bug for @value{GDBN} to behave one way when only a psymtab has
2278 been read, and another way if the corresponding symtab has been read
2279 in.  Such bugs are typically caused by a psymtab that does not contain
2280 all the visible symbols, or which has the wrong instruction address
2281 ranges.
2282
2283 The psymtab for a particular section of a symbol file (objfile) could be
2284 thrown away after the symtab has been read in.  The symtab should always
2285 be searched before the psymtab, so the psymtab will never be used (in a
2286 bug-free environment).  Currently, psymtabs are allocated on an obstack,
2287 and all the psymbols themselves are allocated in a pair of large arrays
2288 on an obstack, so there is little to be gained by trying to free them
2289 unless you want to do a lot more work.
2290
2291 Whether or not psymtabs are created depends on the objfile's symbol
2292 reader.  The core of @value{GDBN} hides the details of partial symbols
2293 and partial symbol tables behind a set of function pointers known as
2294 the @dfn{quick symbol functions}.  These are documented in
2295 @file{symfile.h}.
2296
2297 @section Types
2298
2299 @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).
2300
2301 @cindex fundamental types
2302 These are the fundamental types that @value{GDBN} uses internally.  Fundamental
2303 types from the various debugging formats (stabs, ELF, etc) are mapped
2304 into one of these.  They are basically a union of all fundamental types
2305 that @value{GDBN} knows about for all the languages that @value{GDBN}
2306 knows about.
2307
2308 @unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).
2309
2310 @cindex type codes
2311 Each time @value{GDBN} builds an internal type, it marks it with one
2312 of these types.  The type may be a fundamental type, such as
2313 @code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR}
2314 which is a pointer to another type.  Typically, several @code{FT_*}
2315 types map to one @code{TYPE_CODE_*} type, and are distinguished by
2316 other members of the type struct, such as whether the type is signed
2317 or unsigned, and how many bits it uses.
2318
2319 @unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).
2320
2321 These are instances of type structs that roughly correspond to
2322 fundamental types and are created as global types for @value{GDBN} to
2323 use for various ugly historical reasons.  We eventually want to
2324 eliminate these.  Note for example that @code{builtin_type_int}
2325 initialized in @file{gdbtypes.c} is basically the same as a
2326 @code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for
2327 an @code{FT_INTEGER} fundamental type.  The difference is that the
2328 @code{builtin_type} is not associated with any particular objfile, and
2329 only one instance exists, while @file{c-lang.c} builds as many
2330 @code{TYPE_CODE_INT} types as needed, with each one associated with
2331 some particular objfile.
2332
2333 @section Object File Formats
2334 @cindex object file formats
2335
2336 @subsection a.out
2337
2338 @cindex @code{a.out} format
2339 The @code{a.out} format is the original file format for Unix.  It
2340 consists of three sections: @code{text}, @code{data}, and @code{bss},
2341 which are for program code, initialized data, and uninitialized data,
2342 respectively.
2343
2344 The @code{a.out} format is so simple that it doesn't have any reserved
2345 place for debugging information.  (Hey, the original Unix hackers used
2346 @samp{adb}, which is a machine-language debugger!)  The only debugging
2347 format for @code{a.out} is stabs, which is encoded as a set of normal
2348 symbols with distinctive attributes.
2349
2350 The basic @code{a.out} reader is in @file{dbxread.c}.
2351
2352 @subsection COFF
2353
2354 @cindex COFF format
2355 The COFF format was introduced with System V Release 3 (SVR3) Unix.
2356 COFF files may have multiple sections, each prefixed by a header.  The
2357 number of sections is limited.
2358
2359 The COFF specification includes support for debugging.  Although this
2360 was a step forward, the debugging information was woefully limited.
2361 For instance, it was not possible to represent code that came from an
2362 included file.  GNU's COFF-using configs often use stabs-type info,
2363 encapsulated in special sections.
2364
2365 The COFF reader is in @file{coffread.c}.
2366
2367 @subsection ECOFF
2368
2369 @cindex ECOFF format
2370 ECOFF is an extended COFF originally introduced for Mips and Alpha
2371 workstations.
2372
2373 The basic ECOFF reader is in @file{mipsread.c}.
2374
2375 @subsection XCOFF
2376
2377 @cindex XCOFF format
2378 The IBM RS/6000 running AIX uses an object file format called XCOFF.
2379 The COFF sections, symbols, and line numbers are used, but debugging
2380 symbols are @code{dbx}-style stabs whose strings are located in the
2381 @code{.debug} section (rather than the string table).  For more
2382 information, see @ref{Top,,,stabs,The Stabs Debugging Format}.
2383
2384 The shared library scheme has a clean interface for figuring out what
2385 shared libraries are in use, but the catch is that everything which
2386 refers to addresses (symbol tables and breakpoints at least) needs to be
2387 relocated for both shared libraries and the main executable.  At least
2388 using the standard mechanism this can only be done once the program has
2389 been run (or the core file has been read).
2390
2391 @subsection PE
2392
2393 @cindex PE-COFF format
2394 Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their
2395 executables.  PE is basically COFF with additional headers.
2396
2397 While BFD includes special PE support, @value{GDBN} needs only the basic
2398 COFF reader.
2399
2400 @subsection ELF
2401
2402 @cindex ELF format
2403 The ELF format came with System V Release 4 (SVR4) Unix.  ELF is
2404 similar to COFF in being organized into a number of sections, but it
2405 removes many of COFF's limitations.  Debugging info may be either stabs
2406 encapsulated in ELF sections, or more commonly these days, DWARF.
2407
2408 The basic ELF reader is in @file{elfread.c}.
2409
2410 @subsection SOM
2411
2412 @cindex SOM format
2413 SOM is HP's object file and debug format (not to be confused with IBM's
2414 SOM, which is a cross-language ABI).
2415
2416 The SOM reader is in @file{somread.c}.
2417
2418 @section Debugging File Formats
2419
2420 This section describes characteristics of debugging information that
2421 are independent of the object file format.
2422
2423 @subsection stabs
2424
2425 @cindex stabs debugging info
2426 @code{stabs} started out as special symbols within the @code{a.out}
2427 format.  Since then, it has been encapsulated into other file
2428 formats, such as COFF and ELF.
2429
2430 While @file{dbxread.c} does some of the basic stab processing,
2431 including for encapsulated versions, @file{stabsread.c} does
2432 the real work.
2433
2434 @subsection COFF
2435
2436 @cindex COFF debugging info
2437 The basic COFF definition includes debugging information.  The level
2438 of support is minimal and non-extensible, and is not often used.
2439
2440 @subsection Mips debug (Third Eye)
2441
2442 @cindex ECOFF debugging info
2443 ECOFF includes a definition of a special debug format.
2444
2445 The file @file{mdebugread.c} implements reading for this format.
2446
2447 @c mention DWARF 1 as a formerly-supported format
2448
2449 @subsection DWARF 2
2450
2451 @cindex DWARF 2 debugging info
2452 DWARF 2 is an improved but incompatible version of DWARF 1.
2453
2454 The DWARF 2 reader is in @file{dwarf2read.c}.
2455
2456 @subsection Compressed DWARF 2
2457
2458 @cindex Compressed DWARF 2 debugging info
2459 Compressed DWARF 2 is not technically a separate debugging format, but
2460 merely DWARF 2 debug information that has been compressed.  In this
2461 format, every object-file section holding DWARF 2 debugging
2462 information is compressed and prepended with a header.  (The section
2463 is also typically renamed, so a section called @code{.debug_info} in a
2464 DWARF 2 binary would be called @code{.zdebug_info} in a compressed
2465 DWARF 2 binary.)  The header is 12 bytes long:
2466
2467 @itemize @bullet
2468 @item
2469 4 bytes: the literal string ``ZLIB''
2470 @item
2471 8 bytes: the uncompressed size of the section, in big-endian byte
2472 order.
2473 @end itemize
2474
2475 The same reader is used for both compressed an normal DWARF 2 info.
2476 Section decompression is done in @code{zlib_decompress_section} in
2477 @file{dwarf2read.c}.
2478
2479 @subsection DWARF 3
2480
2481 @cindex DWARF 3 debugging info
2482 DWARF 3 is an improved version of DWARF 2.
2483
2484 @subsection SOM
2485
2486 @cindex SOM debugging info
2487 Like COFF, the SOM definition includes debugging information.
2488
2489 @section Adding a New Symbol Reader to @value{GDBN}
2490
2491 @cindex adding debugging info reader
2492 If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
2493 there is probably little to be done.
2494
2495 If you need to add a new object file format, you must first add it to
2496 BFD.  This is beyond the scope of this document.
2497
2498 You must then arrange for the BFD code to provide access to the
2499 debugging symbols.  Generally @value{GDBN} will have to call swapping
2500 routines from BFD and a few other BFD internal routines to locate the
2501 debugging information.  As much as possible, @value{GDBN} should not
2502 depend on the BFD internal data structures.
2503
2504 For some targets (e.g., COFF), there is a special transfer vector used
2505 to call swapping routines, since the external data structures on various
2506 platforms have different sizes and layouts.  Specialized routines that
2507 will only ever be implemented by one object file format may be called
2508 directly.  This interface should be described in a file
2509 @file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
2510
2511 @section Memory Management for Symbol Files
2512
2513 Most memory associated with a loaded symbol file is stored on
2514 its @code{objfile_obstack}.  This includes symbols, types,
2515 namespace data, and other information produced by the symbol readers.
2516
2517 Because this data lives on the objfile's obstack, it is automatically
2518 released when the objfile is unloaded or reloaded.  Therefore one
2519 objfile must not reference symbol or type data from another objfile;
2520 they could be unloaded at different times.
2521
2522 User convenience variables, et cetera, have associated types.  Normally
2523 these types live in the associated objfile.  However, when the objfile
2524 is unloaded, those types are deep copied to global memory, so that
2525 the values of the user variables and history items are not lost.
2526
2527
2528 @node Language Support
2529
2530 @chapter Language Support
2531
2532 @cindex language support
2533 @value{GDBN}'s language support is mainly driven by the symbol reader,
2534 although it is possible for the user to set the source language
2535 manually.
2536
2537 @value{GDBN} chooses the source language by looking at the extension
2538 of the file recorded in the debug info; @file{.c} means C, @file{.f}
2539 means Fortran, etc.  It may also use a special-purpose language
2540 identifier if the debug format supports it, like with DWARF.
2541
2542 @section Adding a Source Language to @value{GDBN}
2543
2544 @cindex adding source language
2545 To add other languages to @value{GDBN}'s expression parser, follow the
2546 following steps:
2547
2548 @table @emph
2549 @item Create the expression parser.
2550
2551 @cindex expression parser
2552 This should reside in a file @file{@var{lang}-exp.y}.  Routines for
2553 building parsed expressions into a @code{union exp_element} list are in
2554 @file{parse.c}.
2555
2556 @cindex language parser
2557 Since we can't depend upon everyone having Bison, and YACC produces
2558 parsers that define a bunch of global names, the following lines
2559 @strong{must} be included at the top of the YACC parser, to prevent the
2560 various parsers from defining the same global names:
2561
2562 @smallexample
2563 #define yyparse         @var{lang}_parse
2564 #define yylex           @var{lang}_lex
2565 #define yyerror         @var{lang}_error
2566 #define yylval          @var{lang}_lval
2567 #define yychar          @var{lang}_char
2568 #define yydebug         @var{lang}_debug
2569 #define yypact          @var{lang}_pact 
2570 #define yyr1            @var{lang}_r1   
2571 #define yyr2            @var{lang}_r2   
2572 #define yydef           @var{lang}_def  
2573 #define yychk           @var{lang}_chk  
2574 #define yypgo           @var{lang}_pgo  
2575 #define yyact           @var{lang}_act  
2576 #define yyexca          @var{lang}_exca
2577 #define yyerrflag       @var{lang}_errflag
2578 #define yynerrs         @var{lang}_nerrs
2579 @end smallexample
2580
2581 At the bottom of your parser, define a @code{struct language_defn} and
2582 initialize it with the right values for your language.  Define an
2583 @code{initialize_@var{lang}} routine and have it call
2584 @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
2585 that your language exists.  You'll need some other supporting variables
2586 and functions, which will be used via pointers from your
2587 @code{@var{lang}_language_defn}.  See the declaration of @code{struct
2588 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
2589 for more information.
2590
2591 @item Add any evaluation routines, if necessary
2592
2593 @cindex expression evaluation routines
2594 @findex evaluate_subexp
2595 @findex prefixify_subexp
2596 @findex length_of_subexp
2597 If you need new opcodes (that represent the operations of the language),
2598 add them to the enumerated type in @file{expression.h}.  Add support
2599 code for these operations in the @code{evaluate_subexp} function
2600 defined in the file @file{eval.c}.  Add cases
2601 for new opcodes in two functions from @file{parse.c}:
2602 @code{prefixify_subexp} and @code{length_of_subexp}.  These compute
2603 the number of @code{exp_element}s that a given operation takes up.
2604
2605 @item Update some existing code
2606
2607 Add an enumerated identifier for your language to the enumerated type
2608 @code{enum language} in @file{defs.h}.
2609
2610 Update the routines in @file{language.c} so your language is included.
2611 These routines include type predicates and such, which (in some cases)
2612 are language dependent.  If your language does not appear in the switch
2613 statement, an error is reported.
2614
2615 @vindex current_language
2616 Also included in @file{language.c} is the code that updates the variable
2617 @code{current_language}, and the routines that translate the
2618 @code{language_@var{lang}} enumerated identifier into a printable
2619 string.
2620
2621 @findex _initialize_language
2622 Update the function @code{_initialize_language} to include your
2623 language.  This function picks the default language upon startup, so is
2624 dependent upon which languages that @value{GDBN} is built for.
2625
2626 @findex allocate_symtab
2627 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
2628 code so that the language of each symtab (source file) is set properly.
2629 This is used to determine the language to use at each stack frame level.
2630 Currently, the language is set based upon the extension of the source
2631 file.  If the language can be better inferred from the symbol
2632 information, please set the language of the symtab in the symbol-reading
2633 code.
2634
2635 @findex print_subexp
2636 @findex op_print_tab
2637 Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
2638 expression opcodes you have added to @file{expression.h}.  Also, add the
2639 printed representations of your operators to @code{op_print_tab}.
2640
2641 @item Add a place of call
2642
2643 @findex parse_exp_1
2644 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
2645 @code{parse_exp_1} (defined in @file{parse.c}).
2646
2647 @item Edit @file{Makefile.in}
2648
2649 Add dependencies in @file{Makefile.in}.  Make sure you update the macro
2650 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
2651 not get linked in, or, worse yet, it may not get @code{tar}red into the
2652 distribution!
2653 @end table
2654
2655
2656 @node Host Definition
2657
2658 @chapter Host Definition
2659
2660 With the advent of Autoconf, it's rarely necessary to have host
2661 definition machinery anymore.  The following information is provided,
2662 mainly, as an historical reference.
2663
2664 @section Adding a New Host
2665
2666 @cindex adding a new host
2667 @cindex host, adding
2668 @value{GDBN}'s host configuration support normally happens via Autoconf.
2669 New host-specific definitions should not be needed.  Older hosts
2670 @value{GDBN} still use the host-specific definitions and files listed
2671 below, but these mostly exist for historical reasons, and will
2672 eventually disappear.
2673
2674 @table @file
2675 @item gdb/config/@var{arch}/@var{xyz}.mh
2676 This file is a Makefile fragment that once contained both host and
2677 native configuration information (@pxref{Native Debugging}) for the
2678 machine @var{xyz}.  The host configuration information is now handled
2679 by Autoconf.
2680
2681 Host configuration information included definitions for @code{CC},
2682 @code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},
2683 @code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.
2684
2685 New host-only configurations do not need this file.
2686
2687 @end table
2688
2689 (Files named @file{gdb/config/@var{arch}/xm-@var{xyz}.h} were once
2690 used to define host-specific macros, but were no longer needed and
2691 have all been removed.)
2692
2693 @subheading Generic Host Support Files
2694
2695 @cindex generic host support
2696 There are some ``generic'' versions of routines that can be used by
2697 various systems.
2698
2699 @table @file
2700 @cindex remote debugging support
2701 @cindex serial line support
2702 @item ser-unix.c
2703 This contains serial line support for Unix systems.  It is included by
2704 default on all Unix-like hosts.
2705
2706 @item ser-pipe.c
2707 This contains serial pipe support for Unix systems.  It is included by
2708 default on all Unix-like hosts.
2709
2710 @item ser-mingw.c
2711 This contains serial line support for 32-bit programs running under
2712 Windows using MinGW.
2713
2714 @item ser-go32.c
2715 This contains serial line support for 32-bit programs running under DOS,
2716 using the DJGPP (a.k.a.@: GO32) execution environment.
2717
2718 @cindex TCP remote support
2719 @item ser-tcp.c
2720 This contains generic TCP support using sockets.  It is included by
2721 default on all Unix-like hosts and with MinGW.
2722 @end table
2723
2724 @section Host Conditionals
2725
2726 When @value{GDBN} is configured and compiled, various macros are
2727 defined or left undefined, to control compilation based on the
2728 attributes of the host system.  While formerly they could be set in
2729 host-specific header files, at present they can be changed only by
2730 setting @code{CFLAGS} when building, or by editing the source code.
2731
2732 These macros and their meanings (or if the meaning is not documented
2733 here, then one of the source files where they are used is indicated)
2734 are:
2735
2736 @ftable @code
2737 @item @value{GDBN}INIT_FILENAME
2738 The default name of @value{GDBN}'s initialization file (normally
2739 @file{.gdbinit}).
2740
2741 @item CRLF_SOURCE_FILES
2742 @cindex DOS text files
2743 Define this if host files use @code{\r\n} rather than @code{\n} as a
2744 line terminator.  This will cause source file listings to omit @code{\r}
2745 characters when printing and it will allow @code{\r\n} line endings of files
2746 which are ``sourced'' by gdb.  It must be possible to open files in binary
2747 mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
2748
2749 @item DEFAULT_PROMPT
2750 @cindex prompt
2751 The default value of the prompt string (normally @code{"(gdb) "}).
2752
2753 @item DEV_TTY
2754 @cindex terminal device
2755 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
2756
2757 @item ISATTY
2758 Substitute for isatty, if not available.
2759
2760 @item FOPEN_RB
2761 Define this if binary files are opened the same way as text files.
2762
2763 @item PRINTF_HAS_LONG_LONG
2764 Define this if the host can handle printing of long long integers via
2765 the printf format conversion specifier @code{ll}.  This is set by the
2766 @code{configure} script.
2767
2768 @item LSEEK_NOT_LINEAR
2769 Define this if @code{lseek (n)} does not necessarily move to byte number
2770 @code{n} in the file.  This is only used when reading source files.  It
2771 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
2772
2773 @item lint
2774 Define this to help placate @code{lint} in some situations.
2775
2776 @item volatile
2777 Define this to override the defaults of @code{__volatile__} or
2778 @code{/**/}.
2779 @end ftable
2780
2781
2782 @node Target Architecture Definition
2783
2784 @chapter Target Architecture Definition
2785
2786 @cindex target architecture definition
2787 @value{GDBN}'s target architecture defines what sort of
2788 machine-language programs @value{GDBN} can work with, and how it works
2789 with them.
2790
2791 The target architecture object is implemented as the C structure
2792 @code{struct gdbarch *}.  The structure, and its methods, are generated
2793 using the Bourne shell script @file{gdbarch.sh}.
2794
2795 @menu
2796 * OS ABI Variant Handling::
2797 * Initialize New Architecture::
2798 * Registers and Memory::
2799 * Pointers and Addresses::
2800 * Address Classes::
2801 * Register Representation::
2802 * Frame Interpretation::
2803 * Inferior Call Setup::
2804 * Adding support for debugging core files::
2805 * Defining Other Architecture Features::
2806 * Adding a New Target::
2807 @end menu
2808
2809 @node  OS ABI Variant Handling
2810 @section Operating System ABI Variant Handling
2811 @cindex OS ABI variants
2812
2813 @value{GDBN} provides a mechanism for handling variations in OS
2814 ABIs.  An OS ABI variant may have influence over any number of
2815 variables in the target architecture definition.  There are two major
2816 components in the OS ABI mechanism: sniffers and handlers.
2817
2818 A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair
2819 (the architecture may be wildcarded) in an attempt to determine the
2820 OS ABI of that file.  Sniffers with a wildcarded architecture are considered
2821 to be @dfn{generic}, while sniffers for a specific architecture are
2822 considered to be @dfn{specific}.  A match from a specific sniffer
2823 overrides a match from a generic sniffer.  Multiple sniffers for an
2824 architecture/flavour may exist, in order to differentiate between two
2825 different operating systems which use the same basic file format.  The
2826 OS ABI framework provides a generic sniffer for ELF-format files which
2827 examines the @code{EI_OSABI} field of the ELF header, as well as note
2828 sections known to be used by several operating systems.
2829
2830 @cindex fine-tuning @code{gdbarch} structure
2831 A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the
2832 selected OS ABI.  There may be only one handler for a given OS ABI
2833 for each BFD architecture.
2834
2835 The following OS ABI variants are defined in @file{defs.h}:
2836
2837 @table @code
2838
2839 @findex GDB_OSABI_UNINITIALIZED
2840 @item GDB_OSABI_UNINITIALIZED
2841 Used for struct gdbarch_info if ABI is still uninitialized.
2842
2843 @findex GDB_OSABI_UNKNOWN
2844 @item GDB_OSABI_UNKNOWN
2845 The ABI of the inferior is unknown.  The default @code{gdbarch}
2846 settings for the architecture will be used.
2847
2848 @findex GDB_OSABI_SVR4
2849 @item GDB_OSABI_SVR4
2850 UNIX System V Release 4.
2851
2852 @findex GDB_OSABI_HURD
2853 @item GDB_OSABI_HURD
2854 GNU using the Hurd kernel.
2855
2856 @findex GDB_OSABI_SOLARIS
2857 @item GDB_OSABI_SOLARIS
2858 Sun Solaris.
2859
2860 @findex GDB_OSABI_OSF1
2861 @item GDB_OSABI_OSF1
2862 OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
2863
2864 @findex GDB_OSABI_LINUX
2865 @item GDB_OSABI_LINUX
2866 GNU using the Linux kernel.
2867
2868 @findex GDB_OSABI_FREEBSD_AOUT
2869 @item GDB_OSABI_FREEBSD_AOUT
2870 FreeBSD using the @code{a.out} executable format.
2871
2872 @findex GDB_OSABI_FREEBSD_ELF
2873 @item GDB_OSABI_FREEBSD_ELF
2874 FreeBSD using the ELF executable format.
2875
2876 @findex GDB_OSABI_NETBSD_AOUT
2877 @item GDB_OSABI_NETBSD_AOUT
2878 NetBSD using the @code{a.out} executable format.
2879
2880 @findex GDB_OSABI_NETBSD_ELF
2881 @item GDB_OSABI_NETBSD_ELF
2882 NetBSD using the ELF executable format.
2883
2884 @findex GDB_OSABI_OPENBSD_ELF
2885 @item GDB_OSABI_OPENBSD_ELF
2886 OpenBSD using the ELF executable format.
2887
2888 @findex GDB_OSABI_WINCE
2889 @item GDB_OSABI_WINCE
2890 Windows CE.
2891
2892 @findex GDB_OSABI_GO32
2893 @item GDB_OSABI_GO32
2894 DJGPP.
2895
2896 @findex GDB_OSABI_IRIX
2897 @item GDB_OSABI_IRIX
2898 Irix.
2899
2900 @findex GDB_OSABI_INTERIX
2901 @item GDB_OSABI_INTERIX
2902 Interix (Posix layer for MS-Windows systems).
2903
2904 @findex GDB_OSABI_HPUX_ELF
2905 @item GDB_OSABI_HPUX_ELF
2906 HP/UX using the ELF executable format.
2907
2908 @findex GDB_OSABI_HPUX_SOM
2909 @item GDB_OSABI_HPUX_SOM
2910 HP/UX using the SOM executable format.
2911
2912 @findex GDB_OSABI_QNXNTO
2913 @item GDB_OSABI_QNXNTO
2914 QNX Neutrino.
2915
2916 @findex GDB_OSABI_CYGWIN
2917 @item GDB_OSABI_CYGWIN
2918 Cygwin.
2919
2920 @findex GDB_OSABI_AIX
2921 @item GDB_OSABI_AIX
2922 AIX.
2923
2924 @end table
2925
2926 Here are the functions that make up the OS ABI framework:
2927
2928 @deftypefun {const char *} gdbarch_osabi_name (enum gdb_osabi @var{osabi})
2929 Return the name of the OS ABI corresponding to @var{osabi}.
2930 @end deftypefun
2931
2932 @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}))
2933 Register the OS ABI handler specified by @var{init_osabi} for the
2934 architecture, machine type and OS ABI specified by @var{arch},
2935 @var{machine} and @var{osabi}.  In most cases, a value of zero for the
2936 machine type, which implies the architecture's default machine type,
2937 will suffice.
2938 @end deftypefun
2939
2940 @deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd}))
2941 Register the OS ABI file sniffer specified by @var{sniffer} for the
2942 BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.
2943 If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to
2944 be generic, and is allowed to examine @var{flavour}-flavoured files for
2945 any architecture.
2946 @end deftypefun
2947
2948 @deftypefun {enum gdb_osabi} gdbarch_lookup_osabi (bfd *@var{abfd})
2949 Examine the file described by @var{abfd} to determine its OS ABI.
2950 The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot
2951 be determined.
2952 @end deftypefun
2953
2954 @deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi})
2955 Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the
2956 @code{gdbarch} structure specified by @var{gdbarch}.  If a handler
2957 corresponding to @var{osabi} has not been registered for @var{gdbarch}'s
2958 architecture, a warning will be issued and the debugging session will continue
2959 with the defaults already established for @var{gdbarch}.
2960 @end deftypefun
2961
2962 @deftypefun void generic_elf_osabi_sniff_abi_tag_sections (bfd *@var{abfd}, asection *@var{sect}, void *@var{obj})
2963 Helper routine for ELF file sniffers.  Examine the file described by
2964 @var{abfd} and look at ABI tag note sections to determine the OS ABI
2965 from the note.  This function should be called via
2966 @code{bfd_map_over_sections}.
2967 @end deftypefun
2968
2969 @node Initialize New Architecture
2970 @section Initializing a New Architecture
2971
2972 @menu
2973 * How an Architecture is Represented::
2974 * Looking Up an Existing Architecture::
2975 * Creating a New Architecture::
2976 @end menu
2977
2978 @node How an Architecture is Represented
2979 @subsection How an Architecture is Represented
2980 @cindex architecture representation
2981 @cindex representation of architecture
2982
2983 Each @code{gdbarch} is associated with a single @sc{bfd} architecture,
2984 via a @code{bfd_arch_@var{arch}} in the @code{bfd_architecture}
2985 enumeration.  The @code{gdbarch} is registered by a call to
2986 @code{register_gdbarch_init}, usually from the file's
2987 @code{_initialize_@var{filename}} routine, which will be automatically
2988 called during @value{GDBN} startup.  The arguments are a @sc{bfd}
2989 architecture constant and an initialization function.
2990
2991 @findex _initialize_@var{arch}_tdep
2992 @cindex @file{@var{arch}-tdep.c}
2993 A @value{GDBN} description for a new architecture, @var{arch} is created by
2994 defining a global function @code{_initialize_@var{arch}_tdep}, by
2995 convention in the source file @file{@var{arch}-tdep.c}.  For example,
2996 in the case of the OpenRISC 1000, this function is called
2997 @code{_initialize_or1k_tdep} and is found in the file
2998 @file{or1k-tdep.c}.
2999
3000 @cindex @file{configure.tgt}
3001 @cindex @code{gdbarch}
3002 @findex gdbarch_register
3003 The resulting object files containing the implementation of the
3004 @code{_initialize_@var{arch}_tdep} function are specified in the @value{GDBN}
3005 @file{configure.tgt} file, which includes a large case statement
3006 pattern matching against the @code{--target} option of the
3007 @code{configure} script.  The new @code{struct gdbarch} is created
3008 within the @code{_initialize_@var{arch}_tdep} function by calling
3009 @code{gdbarch_register}:
3010
3011 @smallexample
3012 void gdbarch_register (enum bfd_architecture    @var{architecture},
3013                        gdbarch_init_ftype      *@var{init_func},
3014                        gdbarch_dump_tdep_ftype *@var{tdep_dump_func});
3015 @end smallexample
3016
3017 The @var{architecture} will identify the unique @sc{bfd} to be
3018 associated with this @code{gdbarch}.  The @var{init_func} funciton is
3019 called to create and return the new @code{struct gdbarch}.  The
3020 @var{tdep_dump_func} function will dump the target specific details
3021 associated with this architecture.
3022
3023 For example the function @code{_initialize_or1k_tdep} creates its
3024 architecture for 32-bit OpenRISC 1000 architectures by calling:
3025
3026 @smallexample
3027 gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep);
3028 @end smallexample
3029
3030 @node Looking Up an Existing Architecture
3031 @subsection Looking Up an Existing Architecture
3032 @cindex @code{gdbarch} lookup
3033
3034 The initialization function has this prototype:
3035
3036 @smallexample
3037 static struct gdbarch *
3038 @var{arch}_gdbarch_init (struct gdbarch_info @var{info},
3039                          struct gdbarch_list *@var{arches})
3040 @end smallexample
3041
3042 The @var{info} argument contains parameters used to select the correct
3043 architecture, and @var{arches} is a list of architectures which
3044 have already been created with the same @code{bfd_arch_@var{arch}}
3045 value.
3046
3047 The initialization function should first make sure that @var{info}
3048 is acceptable, and return @code{NULL} if it is not.  Then, it should
3049 search through @var{arches} for an exact match to @var{info}, and
3050 return one if found.  Lastly, if no exact match was found, it should
3051 create a new architecture based on @var{info} and return it.
3052
3053 @findex gdbarch_list_lookup_by_info
3054 @cindex @code{gdbarch_info}
3055 The lookup is done using @code{gdbarch_list_lookup_by_info}.  It is
3056 passed the list of existing architectures, @var{arches}, and the
3057 @code{struct gdbarch_info}, @var{info}, and returns the first matching
3058 architecture it finds, or @code{NULL} if none are found.  If an
3059 architecture is found it can be returned as the result from the
3060 initialization function, otherwise a new @code{struct gdbach} will need
3061 to be created.
3062
3063 The struct gdbarch_info has the following components:
3064
3065 @smallexample
3066 struct gdbarch_info
3067 @{
3068    const struct bfd_arch_info *bfd_arch_info;
3069    int                         byte_order;
3070    bfd                        *abfd;
3071    struct gdbarch_tdep_info   *tdep_info;
3072    enum gdb_osabi              osabi;
3073    const struct target_desc   *target_desc;
3074 @};
3075 @end smallexample
3076
3077 @vindex bfd_arch_info
3078 The @code{bfd_arch_info} member holds the key details about the
3079 architecture.  The @code{byte_order} member is a value in an
3080 enumeration indicating the endianism.  The @code{abfd} member is a
3081 pointer to the full @sc{bfd}, the @code{tdep_info} member is
3082 additional custom target specific information, @code{osabi} identifies
3083 which (if any) of a number of operating specific ABIs are used by this
3084 architecture and the @code{target_desc} member is a set of name-value
3085 pairs with information about register usage in this target.
3086
3087 When the @code{struct gdbarch} initialization function is called, not
3088 all the fields are provided---only those which can be deduced from the
3089 @sc{bfd}.  The @code{struct gdbarch_info}, @var{info} is used as a
3090 look-up key with the list of existing architectures, @var{arches} to
3091 see if a suitable architecture already exists.  The @var{tdep_info},
3092 @var{osabi} and @var{target_desc} fields may be added before this
3093 lookup to refine the search.
3094
3095 Only information in @var{info} should be used to choose the new
3096 architecture.  Historically, @var{info} could be sparse, and
3097 defaults would be collected from the first element on @var{arches}.
3098 However, @value{GDBN} now fills in @var{info} more thoroughly,
3099 so new @code{gdbarch} initialization functions should not take
3100 defaults from @var{arches}.
3101
3102 @node Creating a New Architecture
3103 @subsection Creating a New Architecture
3104 @cindex @code{struct gdbarch} creation
3105
3106 @findex gdbarch_alloc
3107 @cindex @code{gdbarch_tdep} when allocating new @code{gdbarch}
3108 If no architecture is found, then a new architecture must be created,
3109 by calling @code{gdbarch_alloc} using the supplied @code{@w{struct
3110 gdbarch_info}} and any additional custom target specific
3111 information in a @code{struct gdbarch_tdep}.  The prototype for
3112 @code{gdbarch_alloc} is:
3113
3114 @smallexample
3115 struct gdbarch *gdbarch_alloc (const struct gdbarch_info *@var{info},
3116                                struct gdbarch_tdep       *@var{tdep}); 
3117 @end smallexample
3118
3119 @cindex @code{set_gdbarch} functions
3120 @cindex @code{gdbarch} accessor functions
3121 The newly created struct gdbarch must then be populated.  Although
3122 there are default values, in most cases they are not what is
3123 required.
3124
3125 For each element, @var{X}, there is are a pair of corresponding accessor
3126 functions, one to set the value of that element,
3127 @code{set_gdbarch_@var{X}}, the second to either get the value of an
3128 element (if it is a variable) or to apply the element (if it is a
3129 function), @code{gdbarch_@var{X}}.  Note that both accessor functions
3130 take a pointer to the @code{@w{struct gdbarch}} as first
3131 argument.  Populating the new @code{gdbarch} should use the
3132 @code{set_gdbarch} functions.
3133
3134 The following sections identify the main elements that should be set
3135 in this way.  This is not the complete list, but represents the
3136 functions and elements that must commonly be specified for a new
3137 architecture.  Many of the functions and variables are described in the
3138 header file @file{gdbarch.h}.
3139
3140 This is the main work in defining a new architecture.  Implementing the
3141 set of functions to populate the @code{struct gdbarch}.
3142
3143 @cindex @code{gdbarch_tdep} definition
3144 @code{struct gdbarch_tdep} is not defined within @value{GDBN}---it is up
3145 to the user to define this struct if it is needed to hold custom target
3146 information that is not covered by the standard @code{@w{struct
3147 gdbarch}}. For example with the OpenRISC 1000 architecture it is used to
3148 hold the number of matchpoints available in the target (along with other
3149 information).
3150
3151 If there is no additional target specific information, it can be set to
3152 @code{NULL}.
3153
3154 @node Registers and Memory
3155 @section Registers and Memory
3156
3157 @value{GDBN}'s model of the target machine is rather simple.
3158 @value{GDBN} assumes the machine includes a bank of registers and a
3159 block of memory.  Each register may have a different size.
3160
3161 @value{GDBN} does not have a magical way to match up with the
3162 compiler's idea of which registers are which; however, it is critical
3163 that they do match up accurately.  The only way to make this work is
3164 to get accurate information about the order that the compiler uses,
3165 and to reflect that in the @code{gdbarch_register_name} and related functions.
3166
3167 @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
3168
3169 @node Pointers and Addresses
3170 @section Pointers Are Not Always Addresses
3171 @cindex pointer representation
3172 @cindex address representation
3173 @cindex word-addressed machines
3174 @cindex separate data and code address spaces
3175 @cindex spaces, separate data and code address
3176 @cindex address spaces, separate data and code
3177 @cindex code pointers, word-addressed
3178 @cindex converting between pointers and addresses
3179 @cindex D10V addresses
3180
3181 On almost all 32-bit architectures, the representation of a pointer is
3182 indistinguishable from the representation of some fixed-length number
3183 whose value is the byte address of the object pointed to.  On such
3184 machines, the words ``pointer'' and ``address'' can be used interchangeably.
3185 However, architectures with smaller word sizes are often cramped for
3186 address space, so they may choose a pointer representation that breaks this
3187 identity, and allows a larger code address space.
3188
3189 @c D10V is gone from sources - more current example?
3190
3191 For example, the Renesas D10V is a 16-bit VLIW processor whose
3192 instructions are 32 bits long@footnote{Some D10V instructions are
3193 actually pairs of 16-bit sub-instructions.  However, since you can't
3194 jump into the middle of such a pair, code addresses can only refer to
3195 full 32 bit instructions, which is what matters in this explanation.}.
3196 If the D10V used ordinary byte addresses to refer to code locations,
3197 then the processor would only be able to address 64kb of instructions.
3198 However, since instructions must be aligned on four-byte boundaries, the
3199 low two bits of any valid instruction's byte address are always
3200 zero---byte addresses waste two bits.  So instead of byte addresses,
3201 the D10V uses word addresses---byte addresses shifted right two bits---to
3202 refer to code.  Thus, the D10V can use 16-bit words to address 256kb of
3203 code space.
3204
3205 However, this means that code pointers and data pointers have different
3206 forms on the D10V.  The 16-bit word @code{0xC020} refers to byte address
3207 @code{0xC020} when used as a data address, but refers to byte address
3208 @code{0x30080} when used as a code address.
3209
3210 (The D10V also uses separate code and data address spaces, which also
3211 affects the correspondence between pointers and addresses, but we're
3212 going to ignore that here; this example is already too long.)
3213
3214 To cope with architectures like this---the D10V is not the only
3215 one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
3216 byte numbers, and @dfn{pointers}, which are the target's representation
3217 of an address of a particular type of data.  In the example above,
3218 @code{0xC020} is the pointer, which refers to one of the addresses
3219 @code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
3220 @value{GDBN} provides functions for turning a pointer into an address
3221 and vice versa, in the appropriate way for the current architecture.
3222
3223 Unfortunately, since addresses and pointers are identical on almost all
3224 processors, this distinction tends to bit-rot pretty quickly.  Thus,
3225 each time you port @value{GDBN} to an architecture which does
3226 distinguish between pointers and addresses, you'll probably need to
3227 clean up some architecture-independent code.
3228
3229 Here are functions which convert between pointers and addresses:
3230
3231 @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
3232 Treat the bytes at @var{buf} as a pointer or reference of type
3233 @var{type}, and return the address it represents, in a manner
3234 appropriate for the current architecture.  This yields an address
3235 @value{GDBN} can use to read target memory, disassemble, etc.  Note that
3236 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
3237 inferior's.
3238
3239 For example, if the current architecture is the Intel x86, this function
3240 extracts a little-endian integer of the appropriate length from
3241 @var{buf} and returns it.  However, if the current architecture is the
3242 D10V, this function will return a 16-bit integer extracted from
3243 @var{buf}, multiplied by four if @var{type} is a pointer to a function.
3244
3245 If @var{type} is not a pointer or reference type, then this function
3246 will signal an internal error.
3247 @end deftypefun
3248
3249 @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
3250 Store the address @var{addr} in @var{buf}, in the proper format for a
3251 pointer of type @var{type} in the current architecture.  Note that
3252 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
3253 inferior's.
3254
3255 For example, if the current architecture is the Intel x86, this function
3256 stores @var{addr} unmodified as a little-endian integer of the
3257 appropriate length in @var{buf}.  However, if the current architecture
3258 is the D10V, this function divides @var{addr} by four if @var{type} is
3259 a pointer to a function, and then stores it in @var{buf}.
3260
3261 If @var{type} is not a pointer or reference type, then this function
3262 will signal an internal error.
3263 @end deftypefun
3264
3265 @deftypefun CORE_ADDR value_as_address (struct value *@var{val})
3266 Assuming that @var{val} is a pointer, return the address it represents,
3267 as appropriate for the current architecture.
3268
3269 This function actually works on integral values, as well as pointers.
3270 For pointers, it performs architecture-specific conversions as
3271 described above for @code{extract_typed_address}.
3272 @end deftypefun
3273
3274 @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
3275 Create and return a value representing a pointer of type @var{type} to
3276 the address @var{addr}, as appropriate for the current architecture.
3277 This function performs architecture-specific conversions as described
3278 above for @code{store_typed_address}.
3279 @end deftypefun
3280
3281 Here are two functions which architectures can define to indicate the
3282 relationship between pointers and addresses.  These have default
3283 definitions, appropriate for architectures on which all pointers are
3284 simple unsigned byte addresses.
3285
3286 @deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf})
3287 Assume that @var{buf} holds a pointer of type @var{type}, in the
3288 appropriate format for the current architecture.  Return the byte
3289 address the pointer refers to.
3290
3291 This function may safely assume that @var{type} is either a pointer or a
3292 C@t{++} reference type.
3293 @end deftypefun
3294
3295 @deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
3296 Store in @var{buf} a pointer of type @var{type} representing the address
3297 @var{addr}, in the appropriate format for the current architecture.
3298
3299 This function may safely assume that @var{type} is either a pointer or a
3300 C@t{++} reference type.
3301 @end deftypefun
3302
3303 @node Address Classes
3304 @section Address Classes
3305 @cindex address classes
3306 @cindex DW_AT_byte_size
3307 @cindex DW_AT_address_class
3308
3309 Sometimes information about different kinds of addresses is available
3310 via the debug information.  For example, some programming environments
3311 define addresses of several different sizes.  If the debug information
3312 distinguishes these kinds of address classes through either the size
3313 info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit
3314 address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the
3315 following macros should be defined in order to disambiguate these
3316 types within @value{GDBN} as well as provide the added information to
3317 a @value{GDBN} user when printing type expressions.
3318
3319 @deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class})
3320 Returns the type flags needed to construct a pointer type whose size
3321 is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.
3322 This function is normally called from within a symbol reader.  See
3323 @file{dwarf2read.c}.
3324 @end deftypefun
3325
3326 @deftypefun {char *} gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{gdbarch}, int @var{type_flags})
3327 Given the type flags representing an address class qualifier, return
3328 its name.
3329 @end deftypefun
3330 @deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{gdbarch}, int @var{name}, int *@var{type_flags_ptr})
3331 Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags
3332 for that address class qualifier.
3333 @end deftypefun
3334
3335 Since the need for address classes is rather rare, none of
3336 the address class functions are defined by default.  Predicate
3337 functions are provided to detect when they are defined.
3338
3339 Consider a hypothetical architecture in which addresses are normally
3340 32-bits wide, but 16-bit addresses are also supported.  Furthermore,
3341 suppose that the @w{DWARF 2} information for this architecture simply
3342 uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one
3343 of these "short" pointers.  The following functions could be defined
3344 to implement the address class functions:
3345
3346 @smallexample
3347 somearch_address_class_type_flags (int byte_size,
3348                                    int dwarf2_addr_class)
3349 @{
3350   if (byte_size == 2)
3351     return TYPE_FLAG_ADDRESS_CLASS_1;
3352   else
3353     return 0;
3354 @}
3355
3356 static char *
3357 somearch_address_class_type_flags_to_name (int type_flags)
3358 @{
3359   if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
3360     return "short";
3361   else
3362     return NULL;
3363 @}
3364
3365 int
3366 somearch_address_class_name_to_type_flags (char *name,
3367                                            int *type_flags_ptr)
3368 @{
3369   if (strcmp (name, "short") == 0)
3370     @{
3371       *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
3372       return 1;
3373     @}
3374   else
3375     return 0;
3376 @}
3377 @end smallexample
3378
3379 The qualifier @code{@@short} is used in @value{GDBN}'s type expressions
3380 to indicate the presence of one of these ``short'' pointers.  For
3381 example if the debug information indicates that @code{short_ptr_var} is
3382 one of these short pointers, @value{GDBN} might show the following
3383 behavior:
3384
3385 @smallexample
3386 (gdb) ptype short_ptr_var
3387 type = int * @@short
3388 @end smallexample
3389
3390
3391 @node Register Representation
3392 @section Register Representation
3393
3394 @menu
3395 * Raw and Cooked Registers::
3396 * Register Architecture Functions & Variables::
3397 * Register Information Functions::
3398 * Register and Memory Data::
3399 * Register Caching::
3400 @end menu
3401
3402 @node Raw and Cooked Registers
3403 @subsection Raw and Cooked Registers
3404 @cindex raw register representation
3405 @cindex cooked register representation
3406 @cindex representations, raw and cooked registers
3407
3408 @value{GDBN} considers registers to be a set with members numbered
3409 linearly from 0 upwards.  The first part of that set corresponds to real
3410 physical registers, the second part to any @dfn{pseudo-registers}.
3411 Pseudo-registers have no independent physical existence, but are useful
3412 representations of information within the architecture.  For example the
3413 OpenRISC 1000 architecture has up to 32 general purpose registers, which
3414 are typically represented as 32-bit (or 64-bit) integers.  However the
3415 GPRs are also used as operands to the floating point operations, and it
3416 could be convenient to define a set of pseudo-registers, to show the
3417 GPRs represented as floating point values.
3418
3419 For any architecture, the implementer will decide on a mapping from
3420 hardware to @value{GDBN} register numbers.  The registers corresponding to real
3421 hardware are referred to as @dfn{raw} registers, the remaining registers are
3422 @dfn{pseudo-registers}.  The total register set (raw and pseudo) is called
3423 the @dfn{cooked} register set.
3424
3425
3426 @node Register Architecture Functions & Variables
3427 @subsection Functions and Variables Specifying the Register Architecture
3428 @cindex @code{gdbarch} register architecture functions
3429
3430 These @code{struct gdbarch} functions and variables specify the number
3431 and type of registers in the architecture.
3432
3433 @deftypefn {Architecture Function} CORE_ADDR read_pc (struct regcache *@var{regcache})
3434 @end deftypefn
3435 @deftypefn {Architecture Function} void write_pc (struct regcache *@var{regcache}, CORE_ADDR @var{val})
3436
3437 Read or write the program counter.  The default value of both
3438 functions is @code{NULL} (no function available).  If the program
3439 counter is just an ordinary register, it can be specified in
3440 @code{struct gdbarch} instead (see @code{pc_regnum} below) and it will
3441 be read or written using the standard routines to access registers.  This
3442 function need only be specified if the program counter is not an
3443 ordinary register.
3444
3445 Any register information can be obtained using the supplied register
3446 cache, @var{regcache}.  @xref{Register Caching, , Register Caching}.
3447
3448 @end deftypefn
3449
3450 @deftypefn {Architecture Function} void pseudo_register_read (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf})
3451 @end deftypefn
3452 @deftypefn {Architecture Function} void pseudo_register_write (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf})
3453
3454 These functions should be defined if there are any pseudo-registers.
3455 The default value is @code{NULL}.  @var{regnum} is the number of the
3456 register to read or write (which will be a @dfn{cooked} register
3457 number) and @var{buf} is the buffer where the value read will be
3458 placed, or from which the value to be written will be taken.  The
3459 value in the buffer may be converted to or from a signed or unsigned
3460 integral value using one of the utility functions (@pxref{Register and
3461 Memory Data, , Using Different Register and Memory Data
3462 Representations}).
3463
3464 The access should be for the specified architecture,
3465 @var{gdbarch}.  Any register information can be obtained using the
3466 supplied register cache, @var{regcache}.  @xref{Register Caching, ,
3467 Register Caching}.
3468
3469 @end deftypefn
3470
3471 @deftypevr {Architecture Variable} int sp_regnum
3472 @vindex sp_regnum
3473 @cindex stack pointer
3474 @cindex @kbd{$sp}
3475
3476 This specifies the register holding the stack pointer, which may be a
3477 raw or pseudo-register.  It defaults to -1 (not defined), but it is an
3478 error for it not to be defined.
3479
3480 The value of the stack pointer register can be accessed withing
3481 @value{GDBN} as the variable @kbd{$sp}.
3482
3483 @end deftypevr
3484
3485 @deftypevr {Architecture Variable} int pc_regnum
3486 @vindex pc_regnum
3487 @cindex program counter
3488 @cindex @kbd{$pc}
3489
3490 This specifies the register holding the program counter, which may be a
3491 raw or pseudo-register.  It defaults to -1 (not defined).  If
3492 @code{pc_regnum} is not defined, then the functions @code{read_pc} and
3493 @code{write_pc} (see above) must be defined.
3494
3495 The value of the program counter (whether defined as a register, or
3496 through @code{read_pc} and @code{write_pc}) can be accessed withing
3497 @value{GDBN} as the variable @kbd{$pc}.
3498
3499 @end deftypevr
3500
3501 @deftypevr {Architecture Variable} int ps_regnum
3502 @vindex ps_regnum
3503 @cindex processor status register
3504 @cindex status register
3505 @cindex @kbd{$ps}
3506
3507 This specifies the register holding the processor status (often called
3508 the status register), which may be a raw or pseudo-register.  It
3509 defaults to -1 (not defined).
3510
3511 If defined, the value of this register can be accessed withing
3512 @value{GDBN} as the variable @kbd{$ps}.
3513
3514 @end deftypevr
3515
3516 @deftypevr {Architecture Variable} int fp0_regnum
3517 @vindex fp0_regnum
3518 @cindex first floating point register
3519
3520 This specifies the first floating point register.  It defaults to
3521 0.  @code{fp0_regnum} is not needed unless the target offers support
3522 for floating point.
3523
3524 @end deftypevr
3525
3526 @node Register Information Functions
3527 @subsection Functions Giving Register Information
3528 @cindex @code{gdbarch} register information functions
3529
3530 These functions return information about registers.
3531
3532 @deftypefn {Architecture Function} {const char *} register_name (struct gdbarch *@var{gdbarch}, int @var{regnum})
3533
3534 This function should convert a register number (raw or pseudo) to a
3535 register name (as a C @code{const char *}).  This is used both to
3536 determine the name of a register for output and to work out the meaning
3537 of any register names used as input.  The function may also return
3538 @code{NULL}, to indicate that @var{regnum} is not a valid register.
3539
3540 For example with the OpenRISC 1000, @value{GDBN} registers 0-31 are the
3541 General Purpose Registers, register 32 is the program counter and
3542 register 33 is the supervision register (i.e.@: the processor status
3543 register), which map to the strings @code{"gpr00"} through
3544 @code{"gpr31"}, @code{"pc"} and @code{"sr"} respectively. This means
3545 that the @value{GDBN} command @kbd{print $gpr5} should print the value of
3546 the OR1K general purpose register 5@footnote{
3547 @cindex frame pointer
3548 @cindex @kbd{$fp}
3549 Historically, @value{GDBN} always had a concept of a frame pointer
3550 register, which could be accessed via the @value{GDBN} variable,
3551 @kbd{$fp}.  That concept is now deprecated, recognizing that not all
3552 architectures have a frame pointer.  However if an architecture does
3553 have a frame pointer register, and defines a register or
3554 pseudo-register with the name @code{"fp"}, then that register will be
3555 used as the value of the @kbd{$fp} variable.}.
3556
3557 The default value for this function is @code{NULL}, meaning
3558 undefined. It should always be defined.
3559
3560 The access should be for the specified architecture, @var{gdbarch}.
3561
3562 @end deftypefn
3563
3564 @deftypefn {Architecture Function} {struct type *} register_type (struct gdbarch *@var{gdbarch}, int @var{regnum})
3565
3566 Given a register number, this function identifies the type of data it
3567 may be holding, specified as a @code{struct type}.  @value{GDBN} allows
3568 creation of arbitrary types, but a number of built in types are
3569 provided (@code{builtin_type_void}, @code{builtin_type_int32} etc),
3570 together with functions to derive types from these.
3571
3572 Typically the program counter will have a type of ``pointer to
3573 function'' (it points to code), the frame pointer and stack pointer
3574 will have types of ``pointer to void'' (they point to data on the stack)
3575 and all other integer registers will have a type of 32-bit integer or
3576 64-bit integer.
3577
3578 This information guides the formatting when displaying register
3579 information.  The default value is @code{NULL} meaning no information is
3580 available to guide formatting when displaying registers.
3581
3582 @end deftypefn
3583
3584 @deftypefn {Architecture Function} void print_registers_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, int @var{regnum}, int @var{all})
3585
3586 Define this function to print out one or all of the registers for the
3587 @value{GDBN} @kbd{info registers} command.  The default value is the
3588 function @code{default_print_registers_info}, which uses the register
3589 type information (see @code{register_type} above) to determine how each
3590 register should be printed.  Define a custom version of this function
3591 for fuller control over how the registers are displayed.
3592
3593 The access should be for the specified architecture, @var{gdbarch},
3594 with output to the file specified by the User Interface
3595 Independent Output file handle, @var{file} (@pxref{UI-Independent
3596 Output, , UI-Independent Output---the @code{ui_out}
3597 Functions}).
3598
3599 The registers should show their values in the frame specified by
3600 @var{frame}.  If @var{regnum} is -1 and @var{all} is zero, then all
3601 the ``significant'' registers should be shown (the implementer should
3602 decide which registers are ``significant''). Otherwise only the value of
3603 the register specified by @var{regnum} should be output.  If
3604 @var{regnum} is -1 and @var{all} is non-zero (true), then the value of
3605 all registers should be shown.
3606
3607 By default @code{default_print_registers_info} prints one register per
3608 line, and if @var{all} is zero omits floating-point registers.
3609
3610 @end deftypefn
3611
3612 @deftypefn {Architecture Function} void print_float_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args})
3613
3614 Define this function to provide output about the floating point unit and
3615 registers for the @value{GDBN} @kbd{info float} command respectively.
3616 The default value is @code{NULL} (not defined), meaning no information
3617 will be provided.
3618
3619 The @var{gdbarch} and @var{file} and @var{frame} arguments have the same
3620 meaning as in the @code{print_registers_info} function above. The string
3621 @var{args} contains any supplementary arguments to the @kbd{info float}
3622 command.
3623
3624 Define this function if the target supports floating point operations.
3625
3626 @end deftypefn
3627
3628 @deftypefn {Architecture Function} void print_vector_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args})
3629
3630 Define this function to provide output about the vector unit and
3631 registers for the @value{GDBN} @kbd{info vector} command respectively.
3632 The default value is @code{NULL} (not defined), meaning no information
3633 will be provided.
3634
3635 The @var{gdbarch}, @var{file} and @var{frame} arguments have the
3636 same meaning as in the @code{print_registers_info} function above.  The
3637 string @var{args} contains any supplementary arguments to the @kbd{info
3638 vector} command.
3639
3640 Define this function if the target supports vector operations.
3641
3642 @end deftypefn
3643
3644 @deftypefn {Architecture Function} int register_reggroup_p (struct gdbarch *@var{gdbarch}, int @var{regnum}, struct reggroup *@var{group})
3645
3646 @value{GDBN} groups registers into different categories (general,
3647 vector, floating point etc).  This function, given a register,
3648 @var{regnum}, and group, @var{group}, returns 1 (true) if the register
3649 is in the group and 0 (false) otherwise.
3650
3651 The information should be for the specified architecture,
3652 @var{gdbarch}
3653
3654 The default value is the function @code{default_register_reggroup_p}
3655 which will do a reasonable job based on the type of the register (see
3656 the function @code{register_type} above), with groups for general
3657 purpose registers, floating point registers, vector registers and raw
3658 (i.e not pseudo) registers.
3659
3660 @end deftypefn
3661
3662 @node Register and Memory Data
3663 @subsection Using Different Register and Memory Data Representations
3664 @cindex register representation
3665 @cindex memory representation
3666 @cindex representations, register and memory
3667 @cindex register data formats, converting
3668 @cindex @code{struct value}, converting register contents to
3669
3670 Some architectures have different representations of data objects,
3671 depending whether the object is held in a register or memory.  For
3672 example:
3673
3674 @itemize @bullet
3675
3676 @item
3677 The Alpha architecture can represent 32 bit integer values in
3678 floating-point registers.
3679
3680 @item
3681 The x86 architecture supports 80-bit floating-point registers.  The
3682 @code{long double} data type occupies 96 bits in memory but only 80
3683 bits when stored in a register.
3684
3685 @end itemize
3686
3687 In general, the register representation of a data type is determined by
3688 the architecture, or @value{GDBN}'s interface to the architecture, while
3689 the memory representation is determined by the Application Binary
3690 Interface.
3691
3692 For almost all data types on almost all architectures, the two
3693 representations are identical, and no special handling is needed.
3694 However, they do occasionally differ.  An architecture may define the
3695 following @code{struct gdbarch} functions to request conversions
3696 between the register and memory representations of a data type:
3697
3698 @deftypefn {Architecture Function} int gdbarch_convert_register_p (struct gdbarch *@var{gdbarch}, int @var{reg})
3699
3700 Return non-zero (true) if the representation of a data value stored in
3701 this register may be different to the representation of that same data
3702 value when stored in memory.  The default value is @code{NULL}
3703 (undefined).
3704
3705 If this function is defined and returns non-zero, the @code{struct
3706 gdbarch} functions @code{gdbarch_register_to_value} and
3707 @code{gdbarch_value_to_register} (see below) should be used to perform
3708 any necessary conversion.
3709
3710 If defined, this function should return zero for the register's native
3711 type, when no conversion is necessary.
3712 @end deftypefn
3713
3714 @deftypefn {Architecture Function} void gdbarch_register_to_value (struct gdbarch *@var{gdbarch}, int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
3715
3716 Convert the value of register number @var{reg} to a data object of
3717 type @var{type}.  The buffer at @var{from} holds the register's value
3718 in raw format; the converted value should be placed in the buffer at
3719 @var{to}.
3720
3721 @quotation
3722 @emph{Note:} @code{gdbarch_register_to_value} and
3723 @code{gdbarch_value_to_register} take their @var{reg} and @var{type}
3724 arguments in different orders.
3725 @end quotation
3726
3727 @code{gdbarch_register_to_value} should only be used with registers
3728 for which the @code{gdbarch_convert_register_p} function returns a
3729 non-zero value.
3730
3731 @end deftypefn
3732
3733 @deftypefn {Architecture Function} void gdbarch_value_to_register (struct gdbarch *@var{gdbarch}, struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
3734
3735 Convert a data value of type @var{type} to register number @var{reg}'
3736 raw format.
3737
3738 @quotation
3739 @emph{Note:} @code{gdbarch_register_to_value} and
3740 @code{gdbarch_value_to_register} take their @var{reg} and @var{type}
3741 arguments in different orders.
3742 @end quotation
3743
3744 @code{gdbarch_value_to_register} should only be used with registers
3745 for which the @code{gdbarch_convert_register_p} function returns a
3746 non-zero value.
3747
3748 @end deftypefn
3749
3750 @node Register Caching
3751 @subsection Register Caching
3752 @cindex register caching
3753
3754 Caching of registers is used, so that the target does not need to be
3755 accessed and reanalyzed multiple times for each register in
3756 circumstances where the register value cannot have changed.
3757
3758 @cindex @code{struct regcache}
3759 @value{GDBN} provides @code{struct regcache}, associated with a
3760 particular @code{struct gdbarch} to hold the cached values of the raw
3761 registers.  A set of functions is provided to access both the raw
3762 registers (with @code{raw} in their name) and the full set of cooked
3763 registers (with @code{cooked} in their name).  Functions are provided
3764 to ensure the register cache is kept synchronized with the values of
3765 the actual registers in the target.
3766
3767 Accessing registers through the @code{struct regcache} routines will
3768 ensure that the appropriate @code{struct gdbarch} functions are called
3769 when necessary to access the underlying target architecture.  In general
3770 users should use the @dfn{cooked} functions, since these will map to the
3771 @dfn{raw} functions automatically as appropriate.
3772
3773 @findex regcache_cooked_read
3774 @findex regcache_cooked_write
3775 @cindex @code{gdb_byte}
3776 @findex regcache_cooked_read_signed
3777 @findex regcache_cooked_read_unsigned
3778 @findex regcache_cooked_write_signed
3779 @findex regcache_cooked_write_unsigned
3780 The two key functions are @code{regcache_cooked_read} and
3781 @code{regcache_cooked_write} which read or write a register from or to
3782 a byte buffer (type @code{gdb_byte *}).  For convenience the wrapper
3783 functions @code{regcache_cooked_read_signed},
3784 @code{regcache_cooked_read_unsigned},
3785 @code{regcache_cooked_write_signed} and
3786 @code{regcache_cooked_write_unsigned} are provided, which read or
3787 write the value using the buffer and convert to or from an integral
3788 value as appropriate.
3789
3790 @node Frame Interpretation
3791 @section Frame Interpretation
3792
3793 @menu
3794 * All About Stack Frames::
3795 * Frame Handling Terminology::
3796 * Prologue Caches::
3797 * Functions and Variable to Analyze Frames::
3798 * Functions to Access Frame Data::
3799 * Analyzing Stacks---Frame Sniffers::
3800 @end menu
3801
3802 @node All About Stack Frames
3803 @subsection All About Stack Frames
3804
3805 @value{GDBN} needs to understand the stack on which local (automatic)
3806 variables are stored.  The area of the stack containing all the local
3807 variables for a function invocation is known as the @dfn{stack frame}
3808 for that function (or colloquially just as the @dfn{frame}).  In turn the
3809 function that called the function will have its stack frame, and so on
3810 back through the chain of functions that have been called.
3811
3812 Almost all architectures have one register dedicated to point to the
3813 end of the stack (the @dfn{stack pointer}).  Many have a second register
3814 which points to the start of the currently active stack frame (the
3815 @dfn{frame pointer}).  The specific arrangements for an architecture are
3816 a key part of the ABI.
3817
3818 A diagram helps to explain this.  Here is a simple program to compute
3819 factorials:
3820
3821 @smallexample
3822 #include <stdio.h>
3823 int fact (int n)
3824 @{
3825   if (0 == n)
3826     @{
3827       return 1;
3828     @}
3829   else
3830     @{
3831       return n * fact (n - 1);
3832     @}
3833 @}
3834
3835 main ()
3836 @{
3837   int i;
3838
3839   for (i = 0; i < 10; i++)
3840     @{
3841       int   f = fact (i);
3842       printf ("%d! = %d\n", i, f);
3843     @}
3844 @}
3845 @end smallexample
3846
3847 Consider the state of the stack when the code reaches line 6 after the
3848 main program has called @code{fact@w{ }(3)}.  The chain of function
3849 calls will be @code{main ()}, @code{fact@w{ }(3)}, @code{fact@w{
3850 }(2)}, @code{@w{fact (1)}} and @code{fact@w{ }(0)}.
3851
3852 In this illustration the stack is falling (as used for example by the
3853 OpenRISC 1000 ABI).  The stack pointer (SP) is at the end of the stack
3854 (lowest address) and the frame pointer (FP) is at the highest address
3855 in the current stack frame.  The following diagram shows how the stack
3856 looks.
3857
3858 @center @image{stack_frame,14cm}
3859
3860 In each stack frame, offset 0 from the stack pointer is the frame
3861 pointer of the previous frame and offset 4 (this is illustrating a
3862 32-bit architecture) from the stack pointer is the return address.
3863 Local variables are indexed from the frame pointer, with negative
3864 indexes.  In the function @code{fact}, offset -4 from the frame
3865 pointer is the argument @var{n}.  In the @code{main} function, offset
3866 -4 from the frame pointer is the local variable @var{i} and offset -8
3867 from the frame pointer is the local variable @var{f}@footnote{This is
3868 a simplified example for illustrative purposes only.  Good optimizing
3869 compilers would not put anything on the stack for such simple
3870 functions.  Indeed they might eliminate the recursion and use of the
3871 stack entirely!}.
3872
3873 It is very easy to get confused when examining stacks.  @value{GDBN}
3874 has terminology it uses rigorously throughout.  The stack frame of the
3875 function currently executing, or where execution stopped is numbered
3876 zero.  In this example frame #0 is the stack frame of the call to
3877 @code{fact@w{ }(0)}.  The stack frame of its calling function
3878 (@code{fact@w{ }(1)} in this case) is numbered #1 and so on back
3879 through the chain of calls.
3880
3881 The main @value{GDBN} data structure describing frames is
3882  @code{@w{struct frame_info}}.  It is not used directly, but only via
3883 its accessor functions.  @code{frame_info} includes information about
3884 the registers in the frame and a pointer to the code of the function
3885 with which the frame is associated.  The entire stack is represented as
3886 a linked list of @code{frame_info} structs.
3887
3888 @node Frame Handling Terminology
3889 @subsection Frame Handling Terminology
3890
3891 It is easy to get confused when referencing stack frames.  @value{GDBN}
3892 uses some precise terminology.
3893
3894 @itemize @bullet
3895
3896 @item
3897 @cindex THIS frame
3898 @cindex stack frame, definition of THIS frame
3899 @cindex frame, definition of THIS frame
3900 @dfn{THIS} frame is the frame currently under consideration.
3901
3902 @item
3903 @cindex NEXT frame
3904 @cindex stack frame, definition of NEXT frame
3905 @cindex frame, definition of NEXT frame
3906 The @dfn{NEXT} frame, also sometimes called the inner or newer frame is the
3907 frame of the function called by the function of THIS frame.
3908
3909 @item
3910 @cindex PREVIOUS frame
3911 @cindex stack frame, definition of PREVIOUS frame
3912 @cindex frame, definition of PREVIOUS frame
3913 The @dfn{PREVIOUS} frame, also sometimes called the outer or older frame is
3914 the frame of the function which called the function of THIS frame.
3915
3916 @end itemize
3917
3918 So in the example in the previous section (@pxref{All About Stack
3919 Frames, , All About Stack Frames}), if THIS frame is #3 (the call to
3920 @code{fact@w{ }(3)}), the NEXT frame is frame #2 (the call to
3921 @code{fact@w{ }(2)}) and the PREVIOUS frame is frame #4 (the call to
3922 @code{main@w{ }()}).
3923
3924 @cindex innermost frame
3925 @cindex stack frame, definition of innermost frame
3926 @cindex frame, definition of innermost frame
3927 The @dfn{innermost} frame is the frame of the current executing
3928 function, or where the program stopped, in this example, in the middle
3929 of the call to @code{@w{fact (0))}}.  It is always numbered frame #0.
3930
3931 @cindex base of a frame
3932 @cindex stack frame, definition of base of a frame
3933 @cindex frame, definition of base of a frame
3934 The @dfn{base} of a frame is the address immediately before the start
3935 of the NEXT frame.  For a stack which grows down in memory (a
3936 @dfn{falling} stack) this will be the lowest address and for a stack
3937 which grows up in memory (a @dfn{rising} stack) this will be the
3938 highest address in the frame.
3939
3940 @value{GDBN} functions to analyze the stack are typically given a
3941 pointer to the NEXT frame to determine information about THIS
3942 frame.  Information about THIS frame includes data on where the
3943 registers of the PREVIOUS frame are stored in this stack frame.  In
3944 this example the frame pointer of the PREVIOUS frame is stored at
3945 offset 0 from the stack pointer of THIS frame.
3946
3947 @cindex unwinding
3948 @cindex stack frame, definition of unwinding
3949 @cindex frame, definition of unwinding
3950 The process whereby a function is given a pointer to the NEXT
3951 frame to work out information about THIS frame is referred to as
3952 @dfn{unwinding}.  The @value{GDBN} functions involved in this typically
3953 include unwind in their name.
3954
3955 @cindex sniffing
3956 @cindex stack frame, definition of sniffing
3957 @cindex frame, definition of sniffing
3958 The process of analyzing a target to determine the information that
3959 should go in struct frame_info is called @dfn{sniffing}.  The functions
3960 that carry this out are called sniffers and typically include sniffer
3961 in their name.  More than one sniffer may be required to extract all
3962 the information for a particular frame.
3963
3964 @cindex sentinel frame
3965 @cindex stack frame, definition of sentinel frame
3966 @cindex frame, definition of sentinel frame
3967 Because so many functions work using the NEXT frame, there is an issue
3968 about addressing the innermost frame---it has no NEXT frame.  To solve
3969 this @value{GDBN} creates a dummy frame #-1, known as the
3970 @dfn{sentinel} frame.
3971
3972 @node Prologue Caches
3973 @subsection Prologue Caches
3974
3975 @cindex function prologue
3976 @cindex prologue of a function
3977 All the frame sniffing functions typically examine the code at the
3978 start of the corresponding function, to determine the state of
3979 registers.  The ABI will save old values and set new values of key
3980 registers at the start of each function in what is known as the
3981 function @dfn{prologue}.
3982
3983 @cindex prologue cache
3984 For any particular stack frame this data does not change, so all the
3985 standard unwinding functions, in addition to receiving a pointer to
3986 the NEXT frame as their first argument, receive a pointer to a
3987 @dfn{prologue cache} as their second argument.  This can be used to store
3988 values associated with a particular frame, for reuse on subsequent
3989 calls involving the same frame.
3990
3991 It is up to the user to define the structure used (it is a
3992 @code{void@w{ }*} pointer) and arrange allocation and deallocation of
3993 storage.  However for general use, @value{GDBN} provides
3994 @code{@w{struct trad_frame_cache}}, with a set of accessor
3995 routines.  This structure holds the stack and code address of
3996 THIS frame, the base address of the frame, a pointer to the
3997 struct @code{frame_info} for the NEXT frame and details of
3998 where the registers of the PREVIOUS frame may be found in THIS
3999 frame.
4000
4001 Typically the first time any sniffer function is called with NEXT
4002 frame, the prologue sniffer for THIS frame will be @code{NULL}.  The
4003 sniffer will analyze the frame, allocate a prologue cache structure
4004 and populate it.  Subsequent calls using the same NEXT frame will
4005 pass in this prologue cache, so the data can be returned with no
4006 additional analysis.
4007
4008 @node Functions and Variable to Analyze Frames
4009 @subsection Functions and Variable to Analyze Frames
4010
4011 These struct @code{gdbarch} functions and variable should be defined
4012 to provide analysis of the stack frame and allow it to be adjusted as
4013 required.
4014
4015 @deftypefn {Architecture Function} CORE_ADDR skip_prologue (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{pc})
4016
4017 The prologue of a function is the code at the beginning of the
4018 function which sets up the stack frame, saves the return address
4019 etc.  The code representing the behavior of the function starts after
4020 the prologue.
4021
4022 This function skips past the prologue of a function if the program
4023 counter, @var{pc}, is within the prologue of a function.  The result is
4024 the program counter immediately after the prologue.  With modern
4025 optimizing compilers, this may be a far from trivial exercise.  However
4026 the required information may be within the binary as DWARF2 debugging
4027 information, making the job much easier.
4028
4029 The default value is @code{NULL} (not defined).  This function should always
4030 be provided, but can take advantage of DWARF2 debugging information,
4031 if that is available.
4032
4033 @end deftypefn
4034
4035 @deftypefn {Architecture Function} int inner_than (CORE_ADDR @var{lhs}, CORE_ADDR @var{rhs})
4036 @findex core_addr_lessthan
4037 @findex core_addr_greaterthan
4038
4039 Given two frame or stack pointers, return non-zero (true) if the first
4040 represents the @dfn{inner} stack frame and 0 (false) otherwise.  This
4041 is used to determine whether the target has a stack which grows up in
4042 memory (rising stack) or grows down in memory (falling stack).
4043 @xref{All About Stack Frames, , All About Stack Frames}, for an
4044 explanation of @dfn{inner} frames.
4045
4046 The default value of this function is @code{NULL} and it should always
4047 be defined.  However for almost all architectures one of the built-in
4048 functions can be used: @code{core_addr_lessthan} (for stacks growing
4049 down in memory) or @code{core_addr_greaterthan} (for stacks growing up
4050 in memory).
4051
4052 @end deftypefn
4053
4054 @anchor{frame_align}
4055 @deftypefn {Architecture Function} CORE_ADDR frame_align (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address})
4056 @findex align_down
4057 @findex align_up
4058
4059 The architecture may have constraints on how its frames are
4060 aligned.  For example the OpenRISC 1000 ABI requires stack frames to be
4061 double-word aligned, but 32-bit versions of the architecture allocate
4062 single-word values to the stack.  Thus extra padding may be needed at
4063 the end of a stack frame.
4064
4065 Given a proposed address for the stack pointer, this function
4066 returns a suitably aligned address (by expanding the stack frame).
4067
4068 The default value is @code{NULL} (undefined).  This function should be defined
4069 for any architecture where it is possible the stack could become
4070 misaligned.  The utility functions @code{align_down} (for falling
4071 stacks) and @code{align_up} (for rising stacks) will facilitate the
4072 implementation of this function.
4073
4074 @end deftypefn
4075
4076 @deftypevr {Architecture Variable} int frame_red_zone_size
4077
4078 Some ABIs reserve space beyond the end of the stack for use by leaf
4079 functions without prologue or epilogue or by exception handlers (for
4080 example the OpenRISC 1000).
4081
4082 This is known as a @dfn{red zone} (AMD terminology).  The @sc{amd64}
4083 (nee x86-64) ABI documentation refers to the @dfn{red zone} when
4084 describing this scratch area.
4085
4086 The default value is 0.  Set this field if the architecture has such a
4087 red zone.  The value must be aligned as required by the ABI (see
4088 @code{frame_align} above for an explanation of stack frame alignment).
4089
4090 @end deftypevr
4091
4092 @node Functions to Access Frame Data
4093 @subsection Functions to Access Frame Data
4094
4095 These functions provide access to key registers and arguments in the
4096 stack frame.
4097
4098 @deftypefn {Architecture Function} CORE_ADDR unwind_pc (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame})
4099
4100 This function is given a pointer to the NEXT stack frame (@pxref{All
4101 About Stack Frames, , All About Stack Frames}, for how frames are
4102 represented) and returns the value of the program counter in the
4103 PREVIOUS frame (i.e.@: the frame of the function that called THIS
4104 one).  This is commonly referred to as the @dfn{return address}.
4105
4106 The implementation, which must be frame agnostic (work with any frame),
4107 is typically no more than:
4108
4109 @smallexample
4110 ULONGEST pc;
4111 pc = frame_unwind_register_unsigned (next_frame, @var{ARCH}_PC_REGNUM);
4112 return gdbarch_addr_bits_remove (gdbarch, pc);
4113 @end smallexample
4114
4115 @end deftypefn
4116
4117 @deftypefn {Architecture Function} CORE_ADDR unwind_sp (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame})
4118
4119 This function is given a pointer to the NEXT stack frame
4120 (@pxref{All About Stack Frames, , All About Stack Frames} for how
4121 frames are represented) and returns the value of the stack pointer in
4122 the PREVIOUS frame (i.e.@: the frame of the function that called
4123 THIS one).
4124
4125 The implementation, which must be frame agnostic (work with any frame),
4126 is typically no more than:
4127
4128 @smallexample
4129 ULONGEST sp;
4130 sp = frame_unwind_register_unsigned (next_frame, @var{ARCH}_SP_REGNUM);
4131 return gdbarch_addr_bits_remove (gdbarch, sp);
4132 @end smallexample
4133
4134 @end deftypefn
4135
4136 @deftypefn {Architecture Function} int frame_num_args (struct gdbarch *@var{gdbarch}, struct frame_info *@var{this_frame})
4137
4138 This function is given a pointer to THIS stack frame (@pxref{All
4139 About Stack Frames, , All About Stack Frames} for how frames are
4140 represented), and returns the number of arguments that are being
4141 passed, or -1 if not known.
4142
4143 The default value is @code{NULL} (undefined), in which case the number of
4144 arguments passed on any stack frame is always unknown.  For many
4145 architectures this will be a suitable default.
4146
4147 @end deftypefn
4148
4149 @node Analyzing Stacks---Frame Sniffers
4150 @subsection Analyzing Stacks---Frame Sniffers
4151
4152 When a program stops, @value{GDBN} needs to construct the chain of
4153 struct @code{frame_info} representing the state of the stack using
4154 appropriate @dfn{sniffers}.
4155
4156 Each architecture requires appropriate sniffers, but they do not form
4157 entries in @code{@w{struct gdbarch}}, since more than one sniffer may
4158 be required and a sniffer may be suitable for more than one
4159 @code{@w{struct gdbarch}}.  Instead sniffers are associated with
4160 architectures using the following functions.
4161
4162 @itemize @bullet
4163
4164 @item
4165 @findex frame_unwind_append_sniffer
4166 @code{frame_unwind_append_sniffer} is used to add a new sniffer to
4167 analyze THIS frame when given a pointer to the NEXT frame.
4168
4169 @item
4170 @findex frame_base_append_sniffer
4171 @code{frame_base_append_sniffer} is used to add a new sniffer
4172 which can determine information about the base of a stack frame.
4173
4174 @item
4175 @findex frame_base_set_default
4176 @code{frame_base_set_default} is used to specify the default base
4177 sniffer.
4178
4179 @end itemize
4180
4181 These functions all take a reference to @code{@w{struct gdbarch}}, so
4182 they are associated with a specific architecture.  They are usually
4183 called in the @code{gdbarch} initialization function, after the
4184 @code{gdbarch} struct has been set up.  Unless a default has been set, the
4185 most recently appended sniffer will be tried first.
4186
4187 The main frame unwinding sniffer (as set by
4188 @code{frame_unwind_append_sniffer)} returns a structure specifying
4189 a set of sniffing functions:
4190
4191 @cindex @code{frame_unwind}
4192 @smallexample
4193 struct frame_unwind
4194 @{
4195    enum frame_type            type;
4196    frame_this_id_ftype       *this_id;
4197    frame_prev_register_ftype *prev_register;
4198    const struct frame_data   *unwind_data;
4199    frame_sniffer_ftype       *sniffer;
4200    frame_prev_pc_ftype       *prev_pc;
4201    frame_dealloc_cache_ftype *dealloc_cache;
4202 @};
4203 @end smallexample
4204
4205 The @code{type} field indicates the type of frame this sniffer can
4206 handle: normal, dummy (@pxref{Functions Creating Dummy Frames, ,
4207 Functions Creating Dummy Frames}), signal handler or sentinel.  Signal
4208 handlers sometimes have their own simplified stack structure for
4209 efficiency, so may need their own handlers.
4210
4211 The @code{unwind_data} field holds additional information which may be
4212 relevant to particular types of frame.  For example it may hold
4213 additional information for signal handler frames.
4214
4215 The remaining fields define functions that yield different types of
4216 information when given a pointer to the NEXT stack frame.  Not all
4217 functions need be provided.  If an entry is @code{NULL}, the next sniffer will
4218 be tried instead.
4219
4220 @itemize @bullet
4221
4222 @item
4223 @code{this_id} determines the stack pointer and function (code
4224 entry point) for THIS stack frame.
4225
4226 @item
4227 @code{prev_register} determines where the values of registers for
4228 the PREVIOUS stack frame are stored in THIS stack frame.
4229
4230 @item
4231 @code{sniffer} takes a look at THIS frame's registers to
4232 determine if this is the appropriate unwinder.
4233
4234 @item
4235 @code{prev_pc} determines the program counter for THIS
4236 frame.  Only needed if the program counter is not an ordinary register
4237 (@pxref{Register Architecture Functions & Variables,
4238 , Functions and Variables Specifying the Register Architecture}).
4239
4240 @item
4241 @code{dealloc_cache} frees any additional memory associated with
4242 the prologue cache for this frame (@pxref{Prologue Caches, , Prologue
4243 Caches}).
4244
4245 @end itemize
4246
4247 In general it is only the @code{this_id} and @code{prev_register}
4248 fields that need be defined for custom sniffers.
4249
4250 The frame base sniffer is much simpler.  It is a @code{@w{struct
4251 frame_base}}, which refers to the corresponding @code{frame_unwind}
4252 struct and whose fields refer to functions yielding various addresses
4253 within the frame.
4254
4255 @cindex @code{frame_base}
4256 @smallexample
4257 struct frame_base
4258 @{
4259    const struct frame_unwind *unwind;
4260    frame_this_base_ftype     *this_base;
4261    frame_this_locals_ftype   *this_locals;
4262    frame_this_args_ftype     *this_args;
4263 @};
4264 @end smallexample
4265
4266 All the functions referred to take a pointer to the NEXT frame as
4267 argument. The function referred to by @code{this_base} returns the
4268 base address of THIS frame, the function referred to by
4269 @code{this_locals} returns the base address of local variables in THIS
4270 frame and the function referred to by @code{this_args} returns the
4271 base address of the function arguments in this frame.
4272
4273 As described above, the base address of a frame is the address
4274 immediately before the start of the NEXT frame.  For a falling
4275 stack, this is the lowest address in the frame and for a rising stack
4276 it is the highest address in the frame.  For most architectures the
4277 same address is also the base address for local variables and
4278 arguments, in which case the same function can be used for all three
4279 entries@footnote{It is worth noting that if it cannot be determined in any
4280 other way (for example by there being a register with the name
4281 @code{"fp"}), then the result of the @code{this_base} function will be
4282 used as the value of the frame pointer variable @kbd{$fp} in
4283 @value{GDBN}.  This is very often not correct (for example with the
4284 OpenRISC 1000, this value is the stack pointer, @kbd{$sp}).  In this
4285 case a register (raw or pseudo) with the name @code{"fp"} should be
4286 defined.  It will be used in preference as the value of @kbd{$fp}.}.
4287
4288 @node Inferior Call Setup
4289 @section Inferior Call Setup
4290 @cindex calls to the inferior
4291
4292 @menu
4293 * About Dummy Frames::
4294 * Functions Creating Dummy Frames::
4295 @end menu
4296
4297 @node About Dummy Frames
4298 @subsection About Dummy Frames
4299 @cindex dummy frames
4300
4301 @value{GDBN} can call functions in the target code (for example by
4302 using the @kbd{call} or @kbd{print} commands).  These functions may be
4303 breakpointed, and it is essential that if a function does hit a
4304 breakpoint, commands like @kbd{backtrace} work correctly.
4305
4306 This is achieved by making the stack look as though the function had
4307 been called from the point where @value{GDBN} had previously stopped.
4308 This requires that @value{GDBN} can set up stack frames appropriate for
4309 such function calls.
4310
4311 @node Functions Creating Dummy Frames
4312 @subsection Functions Creating Dummy Frames
4313
4314 The following functions provide the functionality to set up such
4315 @dfn{dummy} stack frames.
4316
4317 @deftypefn {Architecture Function} CORE_ADDR push_dummy_call (struct gdbarch *@var{gdbarch}, struct value *@var{function}, struct regcache *@var{regcache}, CORE_ADDR @var{bp_addr}, int  @var{nargs}, struct value **@var{args}, CORE_ADDR @var{sp}, int  @var{struct_return}, CORE_ADDR @var{struct_addr})
4318
4319 This function sets up a dummy stack frame for the function about to be
4320 called.  @code{push_dummy_call} is given the arguments to be passed
4321 and must copy them into registers or push them on to the stack as
4322 appropriate for the ABI.
4323
4324 @var{function} is a pointer to the function
4325 that will be called and @var{regcache} the register cache from which
4326 values should be obtained.  @var{bp_addr} is the address to which the
4327 function should return (which is breakpointed, so @value{GDBN} can
4328 regain control, hence the name).  @var{nargs} is the number of
4329 arguments to pass and @var{args} an array containing the argument
4330 values.  @var{struct_return} is non-zero (true) if the function returns
4331 a structure, and if so @var{struct_addr} is the address in which the
4332 structure should be returned.
4333
4334  After calling this function, @value{GDBN} will pass control to the
4335 target at the address of the function, which will find the stack and
4336 registers set up just as expected.
4337
4338 The default value of this function is @code{NULL} (undefined).  If the
4339 function is not defined, then @value{GDBN} will not allow the user to
4340 call functions within the target being debugged.
4341
4342 @end deftypefn
4343
4344 @deftypefn {Architecture Function} {struct frame_id} unwind_dummy_id (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) 
4345
4346 This is the inverse of @code{push_dummy_call} which restores the stack
4347 pointer and program counter after a call to evaluate a function using
4348 a dummy stack frame.  The result is a @code{@w{struct frame_id}}, which
4349 contains the value of the stack pointer and program counter to be
4350 used.
4351
4352 The NEXT frame pointer is provided as argument,
4353 @var{next_frame}.  THIS frame is the frame of the dummy function,
4354 which can be unwound, to yield the required stack pointer and program
4355 counter from the PREVIOUS frame.
4356
4357 The default value is @code{NULL} (undefined).  If @code{push_dummy_call} is
4358 defined, then this function should also be defined.
4359
4360 @end deftypefn
4361
4362 @deftypefn {Architecture Function} CORE_ADDR push_dummy_code (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{sp}, CORE_ADDR @var{funaddr}, struct value **@var{args}, int  @var{nargs}, struct type *@var{value_type}, CORE_ADDR *@var{real_pc}, CORE_ADDR *@var{bp_addr}, struct regcache *@var{regcache})
4363
4364 If this function is not defined (its default value is @code{NULL}), a dummy
4365 call will use the entry point of the currently loaded code on the
4366 target as its return address.  A temporary breakpoint will be set
4367 there, so the location must be writable and have room for a
4368 breakpoint.
4369
4370 It is possible that this default is not suitable.  It might not be
4371 writable (in ROM possibly), or the ABI might require code to be
4372 executed on return from a call to unwind the stack before the
4373 breakpoint is encountered.
4374