Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / doc / gdbint.texinfo
CommitLineData
5796c8dc
SS
1\input texinfo @c -*- texinfo -*-
2@setfilename gdbint.info
3@include gdb-cfg.texi
cf7f2e2d
JM
4@settitle @value{GDBN} Internals
5@setchapternewpage off
5796c8dc
SS
6@dircategory Software development
7@direntry
8* Gdb-Internals: (gdbint). The GNU debugger's internals.
9@end direntry
10
11@copying
ef5ccd6c 12Copyright @copyright{} 1990-2013 Free Software Foundation, Inc.
5796c8dc
SS
13Contributed by Cygnus Solutions. Written by John Gilmore.
14Second Edition by Stan Shebs.
15
16Permission is granted to copy, distribute and/or modify this document
cf7f2e2d 17under the terms of the GNU Free Documentation License, Version 1.3 or
5796c8dc
SS
18any later version published by the Free Software Foundation; with no
19Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
20Texts. A copy of the license is included in the section entitled ``GNU
21Free Documentation License''.
22@end copying
23
24@ifnottex
25This file documents the internals of the GNU debugger @value{GDBN}.
26
27@insertcopying
28@end ifnottex
29
ef5ccd6c 30@syncodeindex vr fn
5796c8dc
SS
31
32@titlepage
33@title @value{GDBN} Internals
ef5ccd6c 34@subtitle A guide to the internals of the GNU debugger
5796c8dc
SS
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
62This document documents the internals of the GNU debugger, @value{GDBN}. It
63includes description of @value{GDBN}'s key algorithms and operations, as well
64as 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::
c50c785c
JM
82* Coding Standards::
83* Misc Guidelines::
5796c8dc
SS
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
ef5ccd6c
JM
93* Concept Index::
94* Function and Variable Index::
5796c8dc
SS
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
109Before diving into the internals, you should understand the formal
110requirements and other expectations for @value{GDBN}. Although some
111of these may seem obvious, there have been proposals for @value{GDBN}
112that have run counter to these requirements.
113
114First of all, @value{GDBN} is a debugger. It's not designed to be a
115front panel for embedded systems. It's not a text editor. It's not a
116shell. It's not a programming environment.
117
118@value{GDBN} is an interactive tool. Although a batch mode is
119available, @value{GDBN}'s primary role is to interact with a human
120programmer.
121
122@value{GDBN} should be responsive to the user. A programmer hot on
123the trail of a nasty bug, and operating under a looming deadline, is
124going to be very impatient of everything, including the response time
125to debugger commands.
126
127@value{GDBN} should be relatively permissive, such as for expressions.
128While the compiler should be picky (or have the option to be made
129picky), since source code lives for a long time usually, the
130programmer doing debugging shouldn't be spending time figuring out to
131mollify the debugger.
132
133@value{GDBN} will be called upon to deal with really large programs.
134Executable sizes of 50 to 100 megabytes occur regularly, and we've
135heard reports of programs approaching 1 gigabyte in size.
136
137@value{GDBN} should be able to run everywhere. No other debugger is
138available for even half as many configurations as @value{GDBN}
139supports.
140
141@node Contributors
142@section Contributors
143
144The first edition of this document was written by John Gilmore of
145Cygnus Solutions. The current second edition was written by Stan Shebs
146of Cygnus Solutions, who continues to update the manual.
147
148Over the years, many others have made additions and changes to this
149document. This section attempts to record the significant contributors
150to that effort. One of the virtues of free software is that everyone
151is free to contribute to it; with regret, we cannot actually
152acknowledge everyone here.
153
154@quotation
155@emph{Plea:} This section has only been added relatively recently (four
156years after publication of the second edition). Additions to this
157section are particularly welcome. If you or your friends (or enemies,
158to be evenhanded) have been unfairly omitted from this list, we would
159like to add your names!
160@end quotation
161
162A document such as this relies on being kept up to date by numerous
163small updates by contributing engineers as they make changes to the
164code base. The file @file{ChangeLog} in the @value{GDBN} distribution
165approximates a blow-by-blow account. The most prolific contributors to
166this important, but low profile task are Andrew Cagney (responsible
167for over half the entries), Daniel Jacobowitz, Mark Kettenis, Jim
168Blandy and Eli Zaretskii.
169
170Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting
171watchpoints.
172
173Jeremy Bennett updated the sections on initializing a new architecture
174and 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,
182symbol handling (the @dfn{symbol side}), and target system handling (the
183@dfn{target side}).
184
185The user interface consists of several actual interfaces, plus
186supporting code.
187
188The symbol side consists of object file readers, debugging info
189interpreters, symbol table management, source language expression
190parsing, type and value printing.
191
192The target side consists of execution control, stack frame analysis, and
193physical target manipulation.
194
195The target side/symbol side division is not formal, and there are a
196number of exceptions. For instance, core file support involves symbolic
197elements (the basic core file reader is in BFD) and target elements (it
198supplies the contents of memory and the values of registers). Instead,
199this division is useful for understanding how the minor subsystems
200should fit together.
201
202@section The Symbol Side
203
204The symbolic side of @value{GDBN} can be thought of as ``everything
205you can do in @value{GDBN} without having a live program running''.
206For instance, you can look at the types of variables, and evaluate
207many kinds of expressions.
208
209@section The Target Side
210
211The target side of @value{GDBN} is the ``bits and bytes manipulator''.
212Although it may make reference to symbolic info here and there, most
213of the target side will run with only a stripped executable
214available---or even no executable at all, in remote debugging cases.
215
216Operations such as disassembly, stack frame crawls, and register
217display, are able to work with no symbolic info at all. In some cases,
218such as disassembly, @value{GDBN} will use symbolic info to present addresses
219relative to symbols rather than as raw numbers, but it will work either
220way.
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
228executes. In most cases they are the same machine, in which case a
229third type of @dfn{Native} attributes come into play.
230
231Defines and include files needed to build on the host are host
232support. Examples are tty support, system defined types, host byte
233order, host float format. These are all calculated by @code{autoconf}
234when the debugger is built.
235
236Defines and information needed to handle the target format are target
237dependent. Examples are the stack frame format, instruction set,
238breakpoint instruction, registers, and how to set up and tear down the stack
239to call a function.
240
241Information that is only needed when the host and target are the same,
242is native dependent. One example is Unix child process support; if the
243host and target are not the same, calling @code{fork} to start the target
244process is a bad idea. The various macros needed for finding the
245registers in the @code{upage}, running @code{ptrace}, and such are all
246in the native-dependent files.
247
248Another example of native-dependent code is support for features that
249are really part of the target environment, but which require
250@code{#include} files that are only available on the host system. Core
251file handling and @code{setjmp} handling are two common cases.
252
253When you want to make @value{GDBN} work as the traditional native debugger
254on 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
259The @value{GDBN} source directory has a mostly flat structure---there
260are only a few subdirectories. A file's name usually gives a hint as
261to what it does; for example, @file{stabsread.c} reads stabs,
262@file{dwarf2read.c} reads @sc{DWARF 2}, etc.
263
264Files that are related to some common task have names that share
265common substrings. For example, @file{*-thread.c} files deal with
266debugging threads on various platforms; @file{*read.c} files deal with
267reading various kinds of symbol and object files; @file{inf*.c} files
268deal with direct control of the @dfn{inferior program} (@value{GDBN}
269parlance for the program being debugged).
270
271There are several dozens of files in the @file{*-tdep.c} family.
272@samp{tdep} stands for @dfn{target-dependent code}---each of these
273files implements debug support for a specific target architecture
274(sparc, mips, etc). Usually, only one of these will be used in a
275specific @value{GDBN} configuration (sometimes two, closely related).
276
277Similarly, there are many @file{*-nat.c} files, each one for native
278debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for
279native debugging of Sparc machines running the Linux kernel).
280
281The few subdirectories of the source tree are:
282
283@table @file
284@item cli
285Code that implements @dfn{CLI}, the @value{GDBN} Command-Line
286Interpreter. @xref{User Interface, Command Interpreter}.
287
288@item gdbserver
289Code for the @value{GDBN} remote server.
290
291@item gdbtk
292Code for Insight, the @value{GDBN} TK-based GUI front-end.
293
294@item mi
295The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter.
296
297@item signals
298Target signal translation code.
299
300@item tui
301Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User
302Interface. @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
311often not very complicated, but get lost in the thicket of special
312cases and real-world issues. This chapter describes the basic
313algorithms and mentions some of the specific target definitions that
314they use.
315
316@section Prologue Analysis
317
318@cindex prologue analysis
319@cindex call frame information
320@cindex CFI (call frame information)
321To produce a backtrace and allow the user to manipulate older frames'
322variables and arguments, @value{GDBN} needs to find the base addresses
323of older frames, and discover where those frames' registers have been
324saved. Since a frame's ``callee-saves'' registers get saved by
325younger frames if and when they're reused, a frame's registers may be
326scattered unpredictably across younger frames. This means that
327changing the value of a register-allocated variable in an older frame
328may actually entail writing to a save slot in some younger frame.
329
330Modern versions of GCC emit Dwarf call frame information (``CFI''),
331which describes how to find frame base addresses and saved registers.
332But CFI is not always available, so as a fallback @value{GDBN} uses a
333technique called @dfn{prologue analysis} to find frame sizes and saved
334registers. A prologue analyzer disassembles the function's machine
335code starting from its entry point, and looks for instructions that
336allocate frame space, save the stack pointer in a frame pointer
337register, save registers, and so on. Obviously, this can't be done
338accurately in general, but it's tractable to do well enough to be very
339helpful. Prologue analysis predates the GNU toolchain's support for
340CFI; at one time, prologue analysis was the only mechanism
341@value{GDBN} used for stack unwinding at all, when the function
342calling conventions didn't specify a fixed frame layout.
343
344In the olden days, function prologues were generated by hand-written,
345target-specific code in GCC, and treated as opaque and untouchable by
346optimizers. Looking at this code, it was usually straightforward to
347write a prologue analyzer for @value{GDBN} that would accurately
348understand all the prologues GCC would generate. However, over time
349GCC became more aggressive about instruction scheduling, and began to
350understand more about the semantics of the prologue instructions
351themselves; in response, @value{GDBN}'s analyzers became more complex
352and fragile. Keeping the prologue analyzers working as GCC (and the
353instruction 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
358To try to address this problem, the code in @file{prologue-value.h}
359and @file{prologue-value.c} provides a general framework for writing
360prologue analyzers that are simpler and more robust than ad-hoc
361analyzers. When we analyze a prologue using the prologue-value
362framework, we're really doing ``abstract interpretation'' or
363``pseudo-evaluation'': running the function's code in simulation, but
364using conservative approximations of the values registers and memory
365would hold when the code actually runs. For example, if our function
366starts with the instruction:
367
368@example
369addi r1, 42 # add 42 to r1
370@end example
371@noindent
372we don't know exactly what value will be in @code{r1} after executing
373this instruction, but we do know it'll be 42 greater than its original
374value.
375
376If we then see an instruction like:
377
378@example
379addi r1, 22 # add 22 to r1
380@end example
381@noindent
382we still don't know what @code{r1's} value is, but again, we can say
383it is now 64 greater than its original value.
384
385If the next instruction were:
386
387@example
388mov r2, r1 # set r2 to r1's value
389@end example
390@noindent
391then we can say that @code{r2's} value is now the original value of
392@code{r1} plus 64.
393
394It's common for prologues to save registers on the stack, so we'll
395need to track the values of stack frame slots, as well as the
396registers. So after an instruction like this:
397
398@example
399mov (fp+4), r2
400@end example
401@noindent
402then we'd know that the stack slot four bytes above the frame pointer
403holds the original value of @code{r1} plus 64.
404
405And so on.
406
407Of course, this can only go so far before it gets unreasonable. If we
408wanted to be able to say anything about the value of @code{r1} after
409the instruction:
410
411@example
412xor r1, r3 # exclusive-or r1 and r3, place result in r1
413@end example
414@noindent
415then things would get pretty complex. But remember, we're just doing
416a conservative approximation; if exclusive-or instructions aren't
417relevant 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
419information is acceptable for our application.
420
421So when we say ``conservative approximation'' here, what we mean is an
422approximation that is either accurate, or marked ``unknown'', but
423never inaccurate.
424
425Using this framework, a prologue analyzer is simply an interpreter for
426machine code, but one that uses conservative approximations for the
427contents of registers and memory instead of actual values. Starting
428from the function's entry point, you simulate instructions up to the
429current PC, or an instruction that you don't know how to simulate.
430Now you can examine the state of the registers and stack slots you've
431kept track of.
432
433@itemize @bullet
434
435@item
436To see how large your stack frame is, just check the value of the
437stack pointer register; if it's the original value of the SP
438minus a constant, then that constant is the stack frame's size.
439If the SP's value has been marked as ``unknown'', then that means
440the prologue has done something too complex for us to track, and
441we don't know the frame size.
442
443@item
444To see where we've saved the previous frame's registers, we just
445search the values we've tracked --- stack slots, usually, but
446registers, too, if you want --- for something equal to the register's
447original value. If the calling conventions suggest a standard place
448to save a given register, then we can check there first, but really,
449anything that will get us back the original value will probably work.
450@end itemize
451
452This does take some work. But prologue analyzers aren't
453quick-and-simple pattern patching to recognize a few fixed prologue
454forms any more; they're big, hairy functions. Along with inferior
455function calls, prologue analysis accounts for a substantial portion
456of the time needed to stabilize a @value{GDBN} port. So it's
457worthwhile to look for an approach that will be easier to understand
458and maintain. In the approach described above:
459
460@itemize @bullet
461
462@item
463It's easier to see that the analyzer is correct: you just see
464whether the analyzer properly (albeit conservatively) simulates
465the effect of each instruction.
466
467@item
468It's easier to extend the analyzer: you can add support for new
469instructions, and know that you haven't broken anything that
470wasn't already broken before.
471
472@item
473It's orthogonal: to gather new information, you don't need to
474complicate the code for each instruction. As long as your domain
475of conservative values is already detailed enough to tell you
476what you need, then all the existing instruction simulations are
477already gathering the right data for you.
478
479@end itemize
480
481The file @file{prologue-value.h} contains detailed comments explaining
482the framework and how to use it.
483
484
485@section Breakpoint Handling
486
487@cindex breakpoints
488In general, a breakpoint is a user-designated location in the program
489where the user wants to regain control if program execution ever reaches
490that location.
491
492There are two main ways to implement breakpoints; either as ``hardware''
493breakpoints or as ``software'' breakpoints.
494
495@cindex hardware breakpoints
496@cindex program counter
497Hardware breakpoints are sometimes available as a builtin debugging
498features with some chips. Typically these work by having dedicated
499register into which the breakpoint address may be stored. If the PC
500(shorthand for @dfn{program counter})
501ever matches a value in a breakpoint registers, the CPU raises an
502exception and reports it to @value{GDBN}.
503
504Another possibility is when an emulator is in use; many emulators
505include circuitry that watches the address lines coming out from the
506processor, and force it to stop if the address matches a breakpoint's
507address.
508
509A third possibility is that the target already has the ability to do
510breakpoints somehow; for instance, a ROM monitor may do its own
511software breakpoints. So although these are not literally ``hardware
512breakpoints'', 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
514for something to happen.
515
516Since they depend on hardware resources, hardware breakpoints may be
517limited in number; when the user asks for more, @value{GDBN} will
518start trying to set software breakpoints. (On some architectures,
519notably the 32-bit x86 platforms, @value{GDBN} cannot always know
520whether there's enough hardware resources to insert all the hardware
521breakpoints and watchpoints. On those platforms, @value{GDBN} prints
522an error message only when the program being debugged is continued.)
523
524@cindex software breakpoints
525Software breakpoints require @value{GDBN} to do somewhat more work.
526The basic theory is that @value{GDBN} will replace a program
527instruction with a trap, illegal divide, or some other instruction
528that will cause an exception, and then when it's encountered,
529@value{GDBN} will take the exception and stop the program. When the
530user says to continue, @value{GDBN} will restore the original
531instruction, single-step, re-insert the trap, and continue on.
532
533Since it literally overwrites the program being tested, the program area
534must be writable, so this technique won't work on programs in ROM. It
535can also distort the behavior of programs that examine themselves,
536although such a situation would be highly unusual.
537
538Also, the software breakpoint instruction should be the smallest size of
539instruction, so it doesn't overwrite an instruction that might be a jump
540target, and cause disaster when the program jumps into the middle of the
541breakpoint instruction. (Strictly speaking, the breakpoint must be no
542larger than the smallest interval between instructions that may be jump
543targets; perhaps there is an architecture where only even-numbered
544instructions may jumped to.) Note that it's possible for an instruction
545set not to have any instructions usable for a software breakpoint,
546although in practice only the ARC has failed to define such an
547instruction.
548
549Basic breakpoint object handling is in @file{breakpoint.c}. However,
550much 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})
558Insert or remove a software breakpoint at address
559@code{@var{bp_tgt}->placed_address}. Returns zero for success,
560non-zero for failure. On input, @var{bp_tgt} contains the address of the
561breakpoint, and is otherwise initialized to zero. The fields of the
562@code{struct bp_target_info} pointed to by @var{bp_tgt} are updated
563to contain other information about the breakpoint on output. The field
564@code{placed_address} may be updated if the breakpoint was placed at a
565related address; the field @code{shadow_contents} contains the real
566contents of the bytes where the breakpoint has been inserted,
567if reading memory would return the breakpoint instead of the
568underlying memory; the field @code{shadow_len} is the length of
569memory cached in @code{shadow_contents}, if any; and the field
570@code{placed_size} is optionally set and used by the target, if
571it could differ from @code{shadow_len}.
572
573For example, the remote target @samp{Z0} packet does not require
574shadowing memory, so @code{shadow_len} is left at zero. However,
575the length reported by @code{gdbarch_breakpoint_from_pc} is cached in
576@code{placed_size}, so that a matching @samp{z0} packet can be
577used 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})
584Insert or remove a hardware-assisted breakpoint at address
585@code{@var{bp_tgt}->placed_address}. Returns zero for success,
586non-zero for failure. See @code{target_insert_breakpoint} for
587a 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,
590but @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
606stepping. This is done with a few specialized internal breakpoints,
607which are visible in the output of the @samp{maint info breakpoint}
608command.
609
610@findex gdbarch_get_longjmp_target
611To 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.
614Since @code{jmp_buf} is target specific and typically defined in a
615target header not available to @value{GDBN}, you will need to
616determine the offset of the PC manually and return that; many targets
617define a @code{jb_pc_offset} field in the tdep structure to save the
618value once calculated.
619
620@section Watchpoints
621@cindex watchpoints
622
623Watchpoints are a special kind of breakpoints (@pxref{Algorithms,
624breakpoints}) which break when data is accessed rather than when some
625instruction is executed. When you have data which changes without
626your knowing what code does that, watchpoints are the silver bullet to
627hunt down and kill such bugs.
628
629@cindex hardware watchpoints
630@cindex software watchpoints
631Watchpoints can be either hardware-assisted or not; the latter type is
632known as ``software watchpoints.'' @value{GDBN} always uses
633hardware-assisted watchpoints if they are available, and falls back on
634software watchpoints otherwise. Typical situations where @value{GDBN}
635will use software watchpoints are:
636
637@itemize @bullet
638@item
639The watched memory region is too large for the underlying hardware
640watchpoint support. For example, each x86 debug register can watch up
641to 4 bytes of memory, so trying to watch data structures whose size is
642more than 16 bytes will cause @value{GDBN} to use software
643watchpoints.
644
645@item
646The value of the expression to be watched depends on data held in
647registers (as opposed to memory).
648
649@item
650Too many different watchpoints requested. (On some architectures,
651this situation is impossible to detect until the debugged program is
652resumed.) Note that x86 debug registers are used both for hardware
653breakpoints and for watchpoints, so setting too many hardware
654breakpoints might cause watchpoint insertion to fail.
655
656@item
657No hardware-assisted watchpoints provided by the target
658implementation.
659@end itemize
660
661Software watchpoints are very slow, since @value{GDBN} needs to
662single-step the program being debugged and test the value of the
663watched expression(s) after each instruction. The rest of this
664section is mostly irrelevant for software watchpoints.
665
666When the inferior stops, @value{GDBN} tries to establish, among other
667possible reasons, whether it stopped due to a watchpoint being hit.
668It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint
669was hit. If not, all watchpoint checking is skipped.
670
671Then @value{GDBN} calls @code{target_stopped_data_address} exactly
672once. This method returns the address of the watchpoint which
673triggered, if the target can determine it. If the triggered address
674is available, @value{GDBN} compares the address returned by this
675method with each watched memory address in each active watchpoint.
676For data-read and data-access watchpoints, @value{GDBN} announces
677every watchpoint that watches the triggered address as being hit.
678For this reason, data-read and data-access watchpoints
679@emph{require} that the triggered address be available; if not, read
680and access watchpoints will never be considered hit. For data-write
681watchpoints, if the triggered address is available, @value{GDBN}
682considers only those watchpoints which match that address;
683otherwise, @value{GDBN} considers all data-write watchpoints. For
684each data-write watchpoint that @value{GDBN} considers, it evaluates
685the expression whose value is being watched, and tests whether the
686watched value has changed. Watchpoints whose watched values have
687changed 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
692watchpoints:
693
694@table @code
695@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
696@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
697Return the number of hardware watchpoints of type @var{type} that are
698possible to be set. The value is positive if @var{count} watchpoints
699of this type can be set, zero if setting watchpoints of this type is
700not supported, and negative if @var{count} is more than the maximum
701number of watchpoints of type @var{type} that can be set. @var{other}
702is non-zero if other types of watchpoints are currently enabled (there
703are architectures which cannot set watchpoints of different types at
704the same time).
705
706@findex TARGET_REGION_OK_FOR_HW_WATCHPOINT
707@item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len})
708Return non-zero if hardware watchpoints can be used to watch a region
709whose 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})
716Insert or remove a hardware watchpoint starting at @var{addr}, for
717@var{len} bytes. @var{type} is the watchpoint type, one of the
718possible values of the enumerated data type @code{target_hw_bp_type},
719defined 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
732These 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})
736If the inferior has some watchpoint that triggered, place the address
737associated with the watchpoint at the location pointed to by
738@var{addr_p} and return non-zero. Otherwise, return zero. This
739is required for data-read and data-access watchpoints. It is
740not required for data-write watchpoints, but @value{GDBN} uses
741it to improve handling of those also.
742
743@value{GDBN} will only call this method once per watchpoint stop,
744immediately after calling @code{STOPPED_BY_WATCHPOINT}. If the
745target's watchpoint indication is sticky, i.e., stays set after
746resuming, this method should clear it. For instance, the x86 debug
747control 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})
751Check whether @var{addr} (as returned by @code{target_stopped_data_address})
752lies within the hardware-defined watchpoint region described by
753@var{start} and @var{length}. This only needs to be provided if the
754granularity of a watchpoint is greater than one byte, i.e., if the
755watchpoint can also trigger on nearby addresses outside of the watched
756region.
757
758@findex HAVE_STEPPABLE_WATCHPOINT
759@item HAVE_STEPPABLE_WATCHPOINT
760If defined to a non-zero value, it is not necessary to disable a
761watchpoint to step over it. Like @code{gdbarch_have_nonsteppable_watchpoint},
762this is usually set when watchpoints trigger at the instruction
763which will perform an interesting read or write. It should be
764set if there is a temporary disable bit which allows the processor
765to step over the interesting instruction without raising the
766watchpoint exception again.
767
768@findex gdbarch_have_nonsteppable_watchpoint
769@item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch})
770If it returns a non-zero value, @value{GDBN} should disable a
771watchpoint to step the inferior over it. This is usually set when
772watchpoints trigger at the instruction which will perform an
773interesting read or write.
774
775@findex HAVE_CONTINUABLE_WATCHPOINT
776@item HAVE_CONTINUABLE_WATCHPOINT
777If defined to a non-zero value, it is possible to continue the
778inferior after a watchpoint has been hit. This is usually set
779when watchpoints trigger at the instruction following an interesting
780read or write.
781
5796c8dc
SS
782@findex STOPPED_BY_WATCHPOINT
783@item STOPPED_BY_WATCHPOINT (@var{wait_status})
784Return non-zero if stopped by a watchpoint. @var{wait_status} is of
785the type @code{struct target_waitstatus}, defined by @file{target.h}.
786Normally, this macro is defined to invoke the function pointed to by
787the @code{to_stopped_by_watchpoint} member of the structure (of the
788type @code{target_ops}, defined on @file{target.h}) that describes the
789target-specific operations; @code{to_stopped_by_watchpoint} ignores
790the @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
794determine for sure whether the inferior stopped due to a watchpoint,
795it 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
802in all threads. @value{GDBN} uses the thread ID to make watchpoints
803act as if they were thread-specific, but it cannot set hardware
804watchpoints that only trigger in a specific thread. Therefore, even
805if the target supports threads, per-thread debug registers, and
806watchpoints which only affect a single thread, it should set the
807per-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
812threads.
813
814@value{GDBN}'s @sc{gnu}/Linux support only reports a single event
815at a time, although multiple events can trigger simultaneously for
816multi-threaded programs. When multiple events occur, @file{linux-nat.c}
817queues subsequent events and returns them the next time the program
818is resumed. This means that @code{STOPPED_BY_WATCHPOINT} and
819@code{target_stopped_data_address} only need to consult the current
820thread's state---the thread indicated by @code{inferior_ptid}. If
821two threads have hit watchpoints simultaneously, those routines
822will 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
828The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug
829registers designed to facilitate debugging. @value{GDBN} provides a
830generic library of functions that x86-based ports can use to implement
831support for watchpoints and hardware-assisted breakpoints. This
832subsection documents the x86 watchpoint facilities in @value{GDBN}.
833
834(At present, the library functions read and write debug registers directly, and are
835thus only available for native configurations.)
836
837To use the generic x86 watchpoint support, a port should do the
838following:
839
840@itemize @bullet
841@findex I386_USE_GENERIC_WATCHPOINTS
842@item
843Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the
844target-dependent headers.
845
846@item
847Include the @file{config/i386/nm-i386.h} header file @emph{after}
848defining @code{I386_USE_GENERIC_WATCHPOINTS}.
849
850@item
851Add @file{i386-nat.o} to the value of the Make variable
852@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}).
853
854@item
855Provide implementations for the @code{I386_DR_LOW_*} macros described
856below. Typically, each macro should call a target-specific function
857which does the real work.
858@end itemize
859
860The x86 watchpoint support works by maintaining mirror images of the
861debug registers. Values are copied between the mirror images and the
862real debug registers via a set of macros which each target needs to
863provide:
864
865@table @code
866@findex I386_DR_LOW_SET_CONTROL
867@item I386_DR_LOW_SET_CONTROL (@var{val})
868Set 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})
872Put 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})
876Reset (i.e.@: zero out) the address stored in the debug register
877number @var{idx}.
878
879@findex I386_DR_LOW_GET_STATUS
880@item I386_DR_LOW_GET_STATUS
881Return the value of the Debug Status (DR6) register. This value is
882used immediately after it is returned by
883@code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status
884register values.
885@end table
886
887For each one of the 4 debug registers (whose indices are from 0 to 3)
888that store addresses, a reference count is maintained by @value{GDBN},
889to allow sharing of debug registers by several watchpoints. This
890allows users to define several watchpoints that watch the same
891expression, but with different conditions and/or commands, without
892wasting debug registers which are in short supply. @value{GDBN}
893maintains the reference counts internally, targets don't have to do
894anything to use this feature.
895
896The x86 debug registers can each watch a region that is 1, 2, or 4
897bytes long. The ia32 architecture requires that each watched region
898be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte
899region on 4-byte boundary. However, the x86 watchpoint support in
900@value{GDBN} can watch unaligned regions and regions larger than 4
901bytes (up to 16 bytes) by allocating several debug registers to watch
902a single region. This allocation of several registers per a watched
903region is also done automatically without target code intervention.
904
905The 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})
911The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call
912this function. It counts the number of debug registers required to
913watch a given region, and returns a non-zero value if that number is
914less than 4, the number of debug registers available to x86
915processors.
916
917@findex i386_stopped_data_address
918@item i386_stopped_data_address (@var{addr_p})
919The target function
920@code{target_stopped_data_address} is set to call this function.
921This
922function examines the breakpoint condition bits in the DR6 Debug
923Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
924macro, and returns the address associated with the first bit that is
925set in DR6.
926
927@findex i386_stopped_by_watchpoint
928@item i386_stopped_by_watchpoint (void)
929The macro @code{STOPPED_BY_WATCHPOINT}
930is set to call this function. The
931argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
932function examines the breakpoint condition bits in the DR6 Debug
933Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
934macro, and returns true if any bit is set. Otherwise, false is
935returned.
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})
941Insert or remove a watchpoint. The macros
942@code{target_insert_watchpoint} and @code{target_remove_watchpoint}
943are set to call these functions. @code{i386_insert_watchpoint} first
944looks for a debug register which is already set to watch the same
945region for the same access types; if found, it just increments the
946reference count of that debug register, thus implementing debug
947register sharing between watchpoints. If no such register is found,
948the function looks for a vacant debug register, sets its mirrored
949value to @var{addr}, sets the mirrored value of DR7 Debug Control
950register as appropriate for the @var{len} and @var{type} parameters,
951and then passes the new values of the debug register and DR7 to the
952inferior by calling @code{I386_DR_LOW_SET_ADDR} and
953@code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is
954required to cover the given region, the above process is repeated for
955each debug register.
956
957@code{i386_remove_watchpoint} does the opposite: it resets the address
958in the mirrored value of the debug register and its read/write and
959length bits in the mirrored value of DR7, then passes these new
960values 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
962watchpoints, each time a @code{i386_remove_watchpoint} is called, it
963decrements the reference count, and only calls
964@code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when
965the 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})
971These functions insert and remove hardware-assisted breakpoints. The
972macros @code{target_insert_hw_breakpoint} and
973@code{target_remove_hw_breakpoint} are set to call these functions.
974The argument is a @code{struct bp_target_info *}, as described in
975the documentation for @code{target_insert_breakpoint}.
976These functions work like @code{i386_insert_watchpoint} and
977@code{i386_remove_watchpoint}, respectively, except that they set up
978the debug registers to watch instruction execution, and each
979hardware-assisted breakpoint always requires exactly one debug
980register.
981
5796c8dc
SS
982@findex i386_cleanup_dregs
983@item i386_cleanup_dregs (void)
984This function clears all the reference counts, addresses, and control
985bits in the mirror images of the debug registers. It doesn't affect
986the actual debug registers in the inferior process.
987@end table
988
989@noindent
990@strong{Notes:}
991@enumerate 1
992@item
993x86 processors support setting watchpoints on I/O reads or writes.
994However, 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
996watchpoints, this feature is not yet available to @value{GDBN} running
997on x86.
998
999@item
1000x86 processors can enable watchpoints locally, for the current task
1001only, or globally, for all the tasks. For each debug register,
1002there's a bit in the DR7 Debug Control register that determines
1003whether the associated address is watched locally or globally. The
1004current implementation of x86 watchpoint support in @value{GDBN}
1005always sets watchpoints to be locally enabled, since global
1006watchpoints might interfere with the underlying OS and are probably
1007unavailable in many platforms.
1008@end enumerate
1009
1010@section Checkpoints
1011@cindex checkpoints
1012@cindex restart
1013In the abstract, a checkpoint is a point in the execution history of
1014the program, which the user may wish to return to at some later time.
1015
1016Internally, a checkpoint is a saved copy of the program state, including
1017whatever information is required in order to restore the program to that
1018state at a later time. This can be expected to include the state of
1019registers and memory, and may include external state such as the state
1020of open files and devices.
1021
1022There are a number of ways in which checkpoints may be implemented
1023in gdb, e.g.@: as corefiles, as forked processes, and as some opaque
1024method implemented on the target side.
1025
1026A corefile can be used to save an image of target memory and register
1027state, which can in principle be restored later --- but corefiles do
1028not typically include information about external entities such as
1029open files. Currently this method is not implemented in gdb.
1030
1031A forked process can save the state of user memory and registers,
1032as well as some subset of external (kernel) state. This method
1033is used to implement checkpoints on Linux, and in principle might
1034be used on other systems.
1035
1036Some targets, e.g.@: simulators, might have their own built-in
1037method for saving checkpoints, and gdb might be able to take
1038advantage of that capability without necessarily knowing any
1039details 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
1046In order to function properly, several modules need to be notified when
1047some changes occur in the @value{GDBN} internals. Traditionally, these
1048modules have relied on several paradigms, the most common ones being
1049hooks and gdb-events. Unfortunately, none of these paradigms was
1050versatile enough to become the standard notification mechanism in
1051@value{GDBN}. The fact that they only supported one ``client'' was also
1052a strong limitation.
1053
1054A new paradigm, based on the Observer pattern of the @cite{Design
1055Patterns} book, has therefore been implemented. The goal was to provide
1056a new interface overcoming the issues with the notification mechanisms
1057previously available. This new interface needed to be strongly typed,
1058easy to extend, and versatile enough to be used as the standard
1059interface when adding new notifications.
1060
1061See @ref{GDB Observers} for a brief description of the observers
1062currently implemented in GDB. The rationale for the current
1063implementation 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
1070command-line interface is perhaps the most familiar.
1071
1072@section Command Interpreter
1073
1074@cindex command interpreter
1075@cindex CLI
1076The command interpreter in @value{GDBN} is fairly simple. It is designed to
1077allow for the set of commands to be augmented dynamically, and also
1078has a recursive subcommand capability, where the first argument to
1079a command may itself direct a lookup on a different command list.
1080
1081For instance, the @samp{set} command just starts a lookup on the
1082@code{setlist} command list, while @samp{set thread} recurses
1083to the @code{set_thread_cmd_list}.
1084
1085@findex add_cmd
1086@findex add_com
1087To add commands in general, use @code{add_cmd}. @code{add_com} adds to
1088the main command list, and should be used for those commands. The usual
1089place to add commands is in the @code{_initialize_@var{xyz}} routines at
1090the ends of most source files.
1091
1092@findex add_setshow_cmd
1093@findex add_setshow_cmd_full
1094To add paired @samp{set} and @samp{show} commands, use
1095@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is
1096a slightly simpler interface which is useful when you don't need to
1097further modify the new command structures, while the latter returns
1098the new command structures for manipulation.
1099
1100@cindex deprecating commands
1101@findex deprecate_cmd
1102Before removing commands from the command set it is a good idea to
1103deprecate them for some time. Use @code{deprecate_cmd} on commands or
1104aliases 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
1106return value from @code{add_com} or @code{add_cmd} to deprecate the
1107command immediately after it is created.
1108
1109The first time a command is used the user will be warned and offered a
1110replacement (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
1112entire 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
1120The @code{ui_out} functions present an abstraction level for the
1121@value{GDBN} output code. They hide the specifics of different user
1122interfaces supported by @value{GDBN}, and thus free the programmer
1123from the need to write several versions of the same code, one each for
1124every UI, to produce output.
1125
1126@subsection Overview and Terminology
1127
1128In general, execution of each @value{GDBN} command produces some sort
1129of output, and can even generate an input request.
1130
1131Output can be generated for the following purposes:
1132
1133@itemize @bullet
1134@item
1135to display a @emph{result} of an operation;
1136
1137@item
1138to convey @emph{info} or produce side-effects of a requested
1139operation;
1140
1141@item
1142to provide a @emph{notification} of an asynchronous event (including
1143progress indication of a prolonged asynchronous operation);
1144
1145@item
1146to display @emph{error messages} (including warnings);
1147
1148@item
1149to show @emph{debug data};
1150
1151@item
1152to @emph{query} or prompt a user for input (a special case).
1153@end itemize
1154
1155@noindent
1156This section mainly concentrates on how to build result output,
1157although some of it also applies to other kinds of output.
1158
1159Generation of output that displays the results of an operation
1160involves one or more of the following:
1161
1162@itemize @bullet
1163@item
1164output of the actual data
1165
1166@item
1167formatting the output as appropriate for console output, to make it
1168easily readable by humans
1169
1170@item
1171machine oriented formatting--a more terse formatting to allow for easy
1172parsing by programs which read @value{GDBN}'s output
1173
1174@item
1175annotation, whose purpose is to help legacy GUIs to identify interesting
1176parts in the output
1177@end itemize
1178
1179The @code{ui_out} routines take care of the first three aspects.
1180Annotations are provided by separate annotation routines. Note that use
1181of annotations for an interface between a GUI and @value{GDBN} is
1182deprecated.
1183
1184Output can be in the form of a single item, which we call a @dfn{field};
1185a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
1186non-identical fields; or a @dfn{table}, which is a tuple consisting of a
1187header 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
1203Most @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
1205object) and the @code{make_cleanup} routines.
1206
1207The first parameter is always the @code{ui_out} vector object, a pointer
1208to a @code{struct ui_out}.
1209
1210The @var{format} parameter is like in @code{printf} family of functions.
1211When it is present, there must also be a variable list of arguments
1212sufficient used to satisfy the @code{%} specifiers in the supplied
1213format.
1214
1215When a character string argument is not used in a @code{ui_out} function
1216call, 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
1224This section introduces @code{ui_out} routines for building lists,
1225tuples and tables. The routines to output the actual data items
1226(fields) are presented in the next section.
1227
1228To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
1229containing information about an object; a @dfn{list} is a sequence of
1230fields where each field describes an identical object.
1231
1232Use the @dfn{table} functions when your output consists of a list of
1233rows (tuples) and the console output should include a heading. Use this
1234even when you are listing just one object but you still want the header.
1235
1236@cindex nesting level in @code{ui_out} functions
1237Tables can not be nested. Tuples and lists can be nested up to a
1238maximum of five levels.
1239
1240The 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
1255Here is the description of table-, tuple- and list-related @code{ui_out}
1256functions:
1257
1258@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
1259The function @code{ui_out_table_begin} marks the beginning of the output
1260of a table. It should always be called before any other @code{ui_out}
1261function for a given table. @var{nbrofcols} is the number of columns in
1262the table. @var{nr_rows} is the number of rows in the table.
1263@var{tblid} is an optional string identifying the table. The string
1264pointed 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
1266was @code{malloc}ed.
1267
1268The companion function @code{ui_out_table_end}, described below, marks
1269the 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
1274table column. You call this function several times, one each for every
1275column of the table, after @code{ui_out_table_begin}, but before
1276@code{ui_out_table_body}.
1277
1278The value of @var{width} gives the column width in characters. The
1279value of @var{alignment} is one of @code{left}, @code{center}, and
1280@code{right}, and it specifies how to align the header: left-justify,
1281center, or right-justify it. @var{colhdr} points to a string that
1282specifies the column header; the implementation copies that string, so
1283column header strings in @code{malloc}ed storage can be freed after the
1284call.
1285@end deftypefun
1286
1287@deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
1288This 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})
1292This function signals the end of a table's output. It should be called
1293after the table body has been produced by the list and field output
1294functions.
1295
1296There should be exactly one call to @code{ui_out_table_end} for each
1297call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
1298will signal an internal error.
1299@end deftypefun
1300
1301The output of the tuples that represent the table rows must follow the
1302call 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
1305calls 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})
1308This function marks the beginning of a tuple output. @var{id} points
1309to an optional string that identifies the tuple; it is copied by the
1310implementation, and so strings in @code{malloc}ed storage can be freed
1311after the call.
1312@end deftypefun
1313
1314@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
1315This function signals an end of a tuple output. There should be exactly
1316one call to @code{ui_out_tuple_end} for each call to
1317@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
1318be 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})
1322This function first opens the tuple and then establishes a cleanup
c50c785c
JM
1323(@pxref{Misc Guidelines, Cleanups}) to close the tuple.
1324It provides a convenient and correct implementation of the
1325non-portable@footnote{The function cast is not portable ISO C.} code sequence:
5796c8dc
SS
1326@smallexample
1327struct cleanup *old_cleanup;
1328ui_out_tuple_begin (uiout, "...");
1329old_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})
1335This function marks the beginning of a list output. @var{id} points to
1336an optional string that identifies the list; it is copied by the
1337implementation, and so strings in @code{malloc}ed storage can be freed
1338after the call.
1339@end deftypefun
1340
1341@deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
1342This function signals an end of a list output. There should be exactly
1343one call to @code{ui_out_list_end} for each call to
1344@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
1345be 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})
1349Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
c50c785c
JM
1350opens a list and then establishes cleanup
1351(@pxref{Misc Guidelines, Cleanups})
5796c8dc
SS
1352that 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
1360The functions described below produce output for the actual data
1361items, or fields, which contain information about the object.
1362
1363Choose 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}, ...)
1366This is the most general output function. It produces the
1367representation of the data in the variable-length argument list
1368according to formatting specifications in @var{format}, a
1369@code{printf}-like format string. The optional argument @var{fldname}
1370supplies the name of the field. The data items themselves are
1371supplied as additional arguments after @var{format}.
1372
1373This generic function should be used only when it is not possible to
1374use 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})
1378This function outputs a value of an @code{int} variable. It uses the
1379@code{"%d"} output conversion specification. @var{fldname} specifies
1380the 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})
1384This 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
1387the 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})
1391This 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})
1395This function outputs a string using the @code{"%s"} conversion
1396specification.
1397@end deftypefun
1398
1399Sometimes, there's a need to compose your output piece by piece using
1400functions that operate on a stream, such as @code{value_print} or
1401@code{fprintf_symbol_filtered}. These functions accept an argument of
1402the type @code{struct ui_file *}, a pointer to a @code{ui_file} object
1403used to store the data stream used for the output. When you use one
1404of 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,
1406you 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,
1409and finally call @code{ui_out_field_stream} to output the field you
1410constructed. When the @code{ui_stream} object is no longer needed,
1411you 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})
1415This function creates a new @code{ui_stream} object which uses the
1416same output methods as the @code{ui_out} object whose pointer is
1417passed 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})
1422This 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})
1427This 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
1431the 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
1435out before completing output generation and reaching the point where
1436@code{ui_out_stream_delete} is called, it is necessary to set up a
1437cleanup, to avoid leaking memory and other resources. Here's a
1438skeleton 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
1447If the function already has the old cleanup chain set (for other kinds
1448of 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
1455Note that with cleanups in place, you should not call
1456@code{ui_out_stream_delete} directly, or you would attempt to free the
1457same 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})
1462This function skips a field in a table. Use it if you have to leave
1463an 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})
1468This function outputs the text in @var{string} in a way that makes it
1469easy to be read by humans. For example, the console implementation of
1470this method filters the text through a built-in pager, to prevent it
1471from scrolling off the visible portion of the screen.
1472
1473Use this function for printing relatively long chunks of text around
1474the actual field data: the text it produces is not aligned according
1475to the table's format. Use @code{ui_out_field_string} to output a
1476string field, and use @code{ui_out_message}, described below, to
1477output short messages.
1478@end deftypefun
1479
1480@deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})
1481This function outputs @var{nspaces} spaces. It is handy to align the
1482text produced by @code{ui_out_text} with the rest of the table or
1483list.
1484@end deftypefun
1485
1486@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
1487This function produces a formatted message, provided that the current
1488verbosity level is at least as large as given by @var{verbosity}. The
1489current verbosity level is specified by the user with the @samp{set
1490verbositylevel} command.@footnote{As of this writing (April 2001),
1491setting verbosity level is not yet implemented, and is always returned
1492as zero. So calling @code{ui_out_message} with a @var{verbosity}
1493argument 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})
1497This function gives the console output filter (a paging filter) a hint
1498of where to break lines which are too long. Ignored for all other
1499output consumers. @var{indent}, if non-@code{NULL}, is the string to
1500be printed to indent the wrapped text on the next line; it must remain
1501accessible until the next call to @code{ui_out_wrap_hint}, or until an
1502explicit 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})
1507This function flushes whatever output has been accumulated so far, if
1508the 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
1516This section gives some practical examples of using the @code{ui_out}
1517functions 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
1521This example, from the @code{breakpoint_1} function, shows how to
1522produce a table.
1523
1524The 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
1551Here'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
1592This example, from the @code{print_one_breakpoint} function, shows how
1593to produce the actual data for the table whose structure was defined
1594in 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
1613This 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
1633This example, also from @code{print_one_breakpoint}, shows how to
1634produce a complicated output field using the @code{print_expression}
1635functions which requires a stream to be passed. It also shows how to
1636automate 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
1643The 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
1654This 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
1656was:
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
1666It 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
1683The following example from @code{print_one_breakpoint} shows how to
1684use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
1685code 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
1693It 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
1705Here's an example of using @code{ui_out_field_string}. The original
1706code 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
1714It 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
1726Finally, 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
1734It 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
1753to 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
1758better able to support graphical and other environments.
1759
1760Since @code{libgdb} development is on-going, its architecture is still
1761evolving. The following components have so far been identified:
1762
1763@itemize @bullet
1764@item
1765Observer - @file{gdb-events.h}.
1766@item
1767Builder - @file{ui-out.h}
1768@item
1769Event Loop - @file{event-loop.h}
1770@item
1771Library - @file{gdb.h}
1772@end itemize
1773
1774The model that ties these components together is described below.
1775
1776@section The @code{libgdb} Model
1777
1778A client of @code{libgdb} interacts with the library in two ways.
1779
1780@itemize @bullet
1781@item
1782As an observer (using @file{gdb-events}) receiving notifications from
1783@code{libgdb} of any internal state changes (break point changes, run
1784state, etc).
1785@item
1786As a client querying @code{libgdb} (using the @file{ui-out} builder) to
1787obtain various status values from @value{GDBN}.
1788@end itemize
1789
1790Since @code{libgdb} could have multiple clients (e.g., a GUI supporting
1791the existing @value{GDBN} CLI), those clients must co-operate when
1792controlling @code{libgdb}. In particular, a client must ensure that
1793@code{libgdb} is idle (i.e.@: no other client is using @code{libgdb})
1794before responding to a @file{gdb-event} by making a query.
1795
1796@section CLI support
1797
1798At 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
1800their interface needs to carefully co-ordinate its own and the CLI's
1801requirements.
1802
1803It 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
1805out the theory:
1806
1807@itemize @bullet
1808@item
1809The client registers itself as an observer of @code{libgdb}.
1810@item
1811The client create and install @code{cli-out} builder using its own
1812versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and
1813@code{gdb_stdout} streams.
1814@item
1815The client creates a separate custom @code{ui-out} builder that is only
1816used while making direct queries to @code{libgdb}.
1817@end itemize
1818
1819When the client receives input intended for the CLI, it simply passes it
1820along. Since the @code{cli-out} builder is installed by default, all
1821the CLI output in response to that command is routed (pronounced rooted)
1822through to the client controlled @code{gdb_stdout} et.@: al.@: streams.
1823At the same time, the client is kept abreast of internal changes by
1824virtue of being a @code{libgdb} observer.
1825
1826The only restriction on the client is that it must wait until
1827@code{libgdb} becomes idle before initiating any queries (using the
1828client'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
1834be used to implement an observer. At present it only allows for one
1835observer and that observer must, internally, handle the need to delay
1836the processing of any event notifications until after @code{libgdb} has
1837finished the current command.
1838
1839@subheading Builder - @file{ui-out.h}
1840@file{ui-out} provides the infrastructure necessary for a client to
1841create a builder. That builder is then passed down to @code{libgdb}
1842when 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
1847loop. A client would need to either plug its self into this loop or,
1848implement a new event-loop that @value{GDBN} would use.
1849
1850The event-loop will eventually be made re-entrant. This is so that
1851@value{GDBN} can better handle the problem of some commands blocking
1852instead of returning.
1853
1854@subheading Library - @file{gdb.h}
1855@file{libgdb} is the most obvious component of this system. It provides
1856the query interface. Each function is parameterized by a @code{ui-out}
1857builder. The result of the query is constructed using that builder
1858before 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
1867abstraction for the representation of a variety of inferior objects
1868and @value{GDBN} convenience objects.
1869
1870Values have an associated @code{struct type}, that describes a virtual
1871view of the raw data or object stored in or accessed through the
1872value.
1873
1874A 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}
1880This value is not an lval. It can't be assigned to.
1881
1882@item @code{lval_memory}
1883This value represents an object in memory.
1884
1885@item @code{lval_register}
1886This value represents an object that lives in a register.
1887
1888@item @code{lval_internalvar}
1889Represents the value of an internal variable.
1890
1891@item @code{lval_internalvar_component}
1892Represents part of a @value{GDBN} internal variable. E.g., a
1893structure field.
1894
1895@cindex computed values
1896@item @code{lval_computed}
1897These are ``computed'' values. They allow creating specialized value
1898objects for specific purposes, all abstracted away from the core value
1899support code. The creator of such a value writes specialized
1900functions to handle the reading and writing to/from the value's
1901backend data, and optionally, a ``copy operator'' and a
1902``destructor''.
1903
1904Pointers to these functions are stored in a @code{struct lval_funcs}
1905instance (declared in @file{value.h}), and passed to the
1906@code{allocate_computed_value} function, as in the example below.
1907
1908@smallexample
1909static void
1910nil_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
1921static void
1922nil_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
1931static struct lval_funcs nil_value_funcs =
1932 @{
1933 nil_value_read,
1934 nil_value_write
1935 @};
1936
1937struct value *
1938make_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
1950See 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
1960A frame is a construct that @value{GDBN} uses to keep track of calling
1961and called functions.
1962
1963@cindex unwind frame
1964@value{GDBN}'s frame model, a fresh design, was implemented with the
1965need to support @sc{dwarf}'s Call Frame Information in mind. In fact,
1966the term ``unwind'' is taken directly from that specification.
1967Developers wishing to learn more about unwinders, are encouraged to
1968read 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
1976frame #1 (the next-to-youngest frame), is implemented by calling frame
1977#0's @code{frame_register_unwind} (the youngest frame). But then the
1978obvious question is: how do you access the registers of the youngest
1979frame itself?
1980
1981@cindex sentinel frame
1982@findex get_frame_type
1983@vindex SENTINEL_FRAME
1984To answer this question, @value{GDBN} has the @dfn{sentinel} frame, the
1985``-1st'' frame. Unwinding registers from the sentinel frame gives you
1986the current values of the youngest real frame's registers. If @var{f}
1987is a sentinel frame, then @code{get_frame_type (@var{f}) @equiv{}
1988SENTINEL_FRAME}.
1989
1990@section Selecting an Unwinder
1991
1992@findex frame_unwind_prepend_unwinder
1993@findex frame_unwind_append_unwinder
1994The architecture registers a list of frame unwinders (@code{struct
1995frame_unwind}), using the functions
1996@code{frame_unwind_prepend_unwinder} and
1997@code{frame_unwind_append_unwinder}. Each unwinder includes a
1998sniffer. Whenever @value{GDBN} needs to unwind a frame (to fetch the
1999previous frame's registers or the current frame's ID), it calls
2000registered sniffers in order to find one which recognizes the frame.
2001The first time a sniffer returns non-zero, the corresponding unwinder
2002is assigned to the frame.
2003
2004@section Unwinding the Frame ID
2005@cindex frame ID
2006
2007Every frame has an associated ID, of type @code{struct frame_id}.
2008The ID includes the stack base and function start address for
2009the frame. The ID persists through the entire life of the frame,
2010including while other called frames are running; it is used to
2011locate an appropriate @code{struct frame_info} from the cache.
2012
2013Every time the inferior stops, and at various other times, the frame
2014cache is flushed. Because of this, parts of @value{GDBN} which need
2015to keep track of individual frames cannot use pointers to @code{struct
2016frame_info}. A frame ID provides a stable reference to a frame, even
2017when the unwinder must be run again to generate a new @code{struct
2018frame_info} for the same frame.
2019
2020The frame's unwinder's @code{this_id} method is called to find the ID.
2021Note that this is different from register unwinding, where the next
2022frame's @code{prev_register} is called to unwind this frame's
2023registers.
2024
2025Both stack base and function address are required to identify the
2026frame, because a recursive function has the same function address for
2027two consecutive frames and a leaf function may have the same stack
2028address as its caller. On some platforms, a third address is part of
2029the ID to further disambiguate frames---for instance, on IA-64
2030the separate register stack address is included in the ID.
2031
2032An 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
2036when there is no frame. For instance, certain breakpoints are attached
2037to 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
2040that the breakpoint is not specific to any frame. The @code{this_id}
2041method should never return @code{null_frame_id}.
2042
2043@section Unwinding Registers
2044
2045Each unwinder includes a @code{prev_register} method. This method
2046takes a frame, an associated cache pointer, and a register number.
2047It returns a @code{struct value *} describing the requested register,
2048as saved by this frame. This is the value of the register that is
2049current in this frame's caller.
2050
2051The returned value must have the same type as the register. It may
2052have any lvalue type. In most circumstances one of these routines
2053will generate the appropriate value:
2054
2055@table @code
2056@item frame_unwind_got_optimized
2057@findex frame_unwind_got_optimized
2058This register was not saved.
2059
2060@item frame_unwind_got_register
2061@findex frame_unwind_got_register
2062This register was copied into another register in this frame. This
2063is also used for unchanged registers; they are ``copied'' into the
2064same register.
2065
2066@item frame_unwind_got_memory
2067@findex frame_unwind_got_memory
2068This register was saved in memory.
2069
2070@item frame_unwind_got_constant
2071@findex frame_unwind_got_constant
2072This register was not saved, but the unwinder can compute the previous
2073value some other way.
2074
2075@item frame_unwind_got_address
2076@findex frame_unwind_got_address
2077Same as @code{frame_unwind_got_constant}, except that the value is a target
2078address. This is frequently used for the stack pointer, which is not
2079explicitly saved but has a known offset from this frame's stack
2080pointer. For architectures with a flat unified address space, this is
2081generally the same as @code{frame_unwind_got_constant}.
2082@end table
2083
2084@node Symbol Handling
2085
2086@chapter Symbol Handling
2087
2088Symbols are a key part of @value{GDBN}'s operation. Symbols include
2089variables, functions, and types.
2090
2091Symbol information for a large program can be truly massive, and
2092reading of symbol information is one of the major performance
2093bottlenecks in @value{GDBN}; it can take many minutes to process it
2094all. Studies have shown that nearly all the time spent is
2095computational, rather than file reading.
2096
2097One of the ways for @value{GDBN} to provide a good user experience is
2098to start up quickly, taking no more than a few seconds. It is simply
2099not possible to process all of a program's debugging info in that
2100time, and so we attempt to handle symbols incrementally. For instance,
2101we create @dfn{partial symbol tables} consisting of only selected
2102symbols, 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
2110file is the file containing the program which @value{GDBN} is
2111debugging. @value{GDBN} can be directed to use a different file for
2112symbols (with the @samp{symbol-file} command), and it can also read
2113more symbols via the @samp{add-file} and @samp{load} commands. In
2114addition, it may bring in more symbols while loading shared
2115libraries.
2116
2117@findex find_sym_fns
2118Symbol files are initially opened by code in @file{symfile.c} using
2119the BFD library (@pxref{Support Libraries}). BFD identifies the type
2120of the file by examining its header. @code{find_sym_fns} then uses
2121this 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
2126Symbol-reading modules identify themselves to @value{GDBN} by calling
2127@code{add_symtab_fns} during their module initialization. The argument
2128to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
2129name (or name prefix) of the symbol format, the length of the prefix,
2130and pointers to four functions. These functions are called at various
2131times to process symbol files whose identification matches the specified
2132prefix.
2133
2134The 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
2140Called from @code{symbol_file_add} when we are about to read a new
2141symbol file. This function should clean up any internal state (possibly
2142resulting from half-read previous files, for example) and prepare to
2143read a new symbol file. Note that the symbol file which we are reading
2144might be a new ``main'' symbol file, or might be a secondary symbol file
2145whose symbols are being added to the existing symbol table.
2146
2147The 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
2149new symbol file being read. Its @code{private} field has been zeroed,
2150and can be modified as desired. Typically, a struct of private
2151information will be @code{malloc}'d, and a pointer to it will be placed
2152in the @code{private} field.
2153
2154There 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
2159Called from @code{symbol_file_add} when discarding existing symbols.
2160This function needs only handle the symbol-reading module's internal
2161state; the symbol table data structures visible to the rest of
2162@value{GDBN} will be discarded by @code{symbol_file_add}. It has no
2163arguments and no result. It may be called after
2164@code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
2165may 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
2169Called from @code{symbol_file_add} to actually read the symbols from a
2170symbol-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
2174the offset between the file's specified start address and its true
2175address in memory. @code{mainline} is 1 if this is the main symbol
2176table being read, and 0 if a secondary symbol file (e.g., shared library
2177or dynamically loaded file) is being read.@refill
2178@end table
2179
2180In addition, if a symbol-reading module creates psymtabs when
2181@var{xyz}_symfile_read is called, these psymtabs will contain a pointer
2182to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
2183from 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
2188Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
2189the psymtab has not already been read in and had its @code{pst->symtab}
2190pointer set. The argument is the psymtab to be fleshed-out into a
2191symtab. 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
2193zero 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
2204Full symbol tables (@dfn{symtabs}). These contain the main
2205information about symbols and addresses.
2206
2207@cindex psymtabs
2208@item
2209Partial symbol tables (@dfn{psymtabs}). These contain enough
2210information to know when to read the corresponding part of the full
2211symbol table.
2212
2213@cindex minimal symbol table
2214@cindex minsymtabs
2215@item
2216Minimal symbol tables (@dfn{msymtabs}). These contain information
2217gleaned from non-debugging symbols.
2218@end itemize
2219
2220@cindex partial symbol table
2221This section describes partial symbol tables.
2222
2223A psymtab is constructed by doing a very quick pass over an executable
2224file's debugging information. Small amounts of information are
2225extracted---enough to identify which parts of the symbol table will
2226need to be re-read and fully digested later, when the user needs the
2227information. The speed of this pass causes @value{GDBN} to start up very
2228quickly. Later, as the detailed rereading occurs, it occurs in small
2229pieces, at various times, and the delay therefrom is mostly invisible to
2230the user.
2231@c (@xref{Symbol Reading}.)
2232
2233The symbols that show up in a file's psymtab should be, roughly, those
2234visible to the debugger's user when the program is not running code from
2235that file. These include external symbols and types, static symbols and
2236types, and @code{enum} values declared at file scope.
2237
2238The psymtab also contains the range of instruction addresses that the
2239full symbol table would represent.
2240
2241@cindex finding a symbol
2242@cindex symbol lookup
2243The idea is that there are only two ways for the user (or much of the
2244code in the debugger) to reference a symbol:
2245
2246@itemize @bullet
2247@findex find_pc_function
2248@findex find_pc_line
2249@item
2250By its address (e.g., execution stops at some address which is inside a
2251function in this file). The address will be noticed to be in the
2252range 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
2258By its name
2259(e.g., the user asks to print a variable, or set a breakpoint on a
2260function). Global names and file-scope names will be found in the
2261psymtab, which will cause the symtab to be pulled in. Local names will
2262have to be qualified by a global name, or a file-scope name, in which
2263case we will have already read in the symtab as we evaluated the
2264qualifier. Or, a local symbol can be referenced when we are ``in'' a
2265local scope, in which case the first case applies. @code{lookup_symbol}
2266does most of the work here.
2267@end itemize
2268
2269The only reason that psymtabs exist is to cause a symtab to be read in
2270at the right moment. Any symbol that can be elided from a psymtab,
2271while still causing that to happen, should not appear in it. Since
2272psymtabs don't have the idea of scope, you can't put local symbols in
2273them anyway. Psymtabs don't have the idea of the type of a symbol,
2274either, so types need not appear, unless they will be referenced by
2275name.
2276
2277It is a bug for @value{GDBN} to behave one way when only a psymtab has
2278been read, and another way if the corresponding symtab has been read
2279in. Such bugs are typically caused by a psymtab that does not contain
2280all the visible symbols, or which has the wrong instruction address
2281ranges.
2282
2283The psymtab for a particular section of a symbol file (objfile) could be
2284thrown away after the symtab has been read in. The symtab should always
2285be searched before the psymtab, so the psymtab will never be used (in a
2286bug-free environment). Currently, psymtabs are allocated on an obstack,
2287and all the psymbols themselves are allocated in a pair of large arrays
2288on an obstack, so there is little to be gained by trying to free them
2289unless you want to do a lot more work.
2290
cf7f2e2d
JM
2291Whether or not psymtabs are created depends on the objfile's symbol
2292reader. The core of @value{GDBN} hides the details of partial symbols
2293and partial symbol tables behind a set of function pointers known as
2294the @dfn{quick symbol functions}. These are documented in
2295@file{symfile.h}.
2296
5796c8dc
SS
2297@section Types
2298
2299@unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).
2300
2301@cindex fundamental types
2302These are the fundamental types that @value{GDBN} uses internally. Fundamental
2303types from the various debugging formats (stabs, ELF, etc) are mapped
2304into one of these. They are basically a union of all fundamental types
2305that @value{GDBN} knows about for all the languages that @value{GDBN}
2306knows about.
2307
2308@unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).
2309
2310@cindex type codes
2311Each time @value{GDBN} builds an internal type, it marks it with one
2312of 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}
2314which is a pointer to another type. Typically, several @code{FT_*}
2315types map to one @code{TYPE_CODE_*} type, and are distinguished by
2316other members of the type struct, such as whether the type is signed
2317or unsigned, and how many bits it uses.
2318
2319@unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).
2320
2321These are instances of type structs that roughly correspond to
2322fundamental types and are created as global types for @value{GDBN} to
2323use for various ugly historical reasons. We eventually want to
2324eliminate these. Note for example that @code{builtin_type_int}
2325initialized 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
2327an @code{FT_INTEGER} fundamental type. The difference is that the
2328@code{builtin_type} is not associated with any particular objfile, and
2329only one instance exists, while @file{c-lang.c} builds as many
2330@code{TYPE_CODE_INT} types as needed, with each one associated with
2331some 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
2339The @code{a.out} format is the original file format for Unix. It
2340consists of three sections: @code{text}, @code{data}, and @code{bss},
2341which are for program code, initialized data, and uninitialized data,
2342respectively.
2343
2344The @code{a.out} format is so simple that it doesn't have any reserved
2345place for debugging information. (Hey, the original Unix hackers used
2346@samp{adb}, which is a machine-language debugger!) The only debugging
2347format for @code{a.out} is stabs, which is encoded as a set of normal
2348symbols with distinctive attributes.
2349
2350The basic @code{a.out} reader is in @file{dbxread.c}.
2351
2352@subsection COFF
2353
2354@cindex COFF format
2355The COFF format was introduced with System V Release 3 (SVR3) Unix.
2356COFF files may have multiple sections, each prefixed by a header. The
2357number of sections is limited.
2358
2359The COFF specification includes support for debugging. Although this
2360was a step forward, the debugging information was woefully limited.
2361For instance, it was not possible to represent code that came from an
2362included file. GNU's COFF-using configs often use stabs-type info,
2363encapsulated in special sections.
2364
2365The COFF reader is in @file{coffread.c}.
2366
2367@subsection ECOFF
2368
2369@cindex ECOFF format
2370ECOFF is an extended COFF originally introduced for Mips and Alpha
2371workstations.
2372
2373The basic ECOFF reader is in @file{mipsread.c}.
2374
2375@subsection XCOFF
2376
2377@cindex XCOFF format
2378The IBM RS/6000 running AIX uses an object file format called XCOFF.
2379The COFF sections, symbols, and line numbers are used, but debugging
2380symbols are @code{dbx}-style stabs whose strings are located in the
2381@code{.debug} section (rather than the string table). For more
2382information, see @ref{Top,,,stabs,The Stabs Debugging Format}.
2383
2384The shared library scheme has a clean interface for figuring out what
2385shared libraries are in use, but the catch is that everything which
2386refers to addresses (symbol tables and breakpoints at least) needs to be
2387relocated for both shared libraries and the main executable. At least
2388using the standard mechanism this can only be done once the program has
2389been run (or the core file has been read).
2390
2391@subsection PE
2392
2393@cindex PE-COFF format
2394Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their
2395executables. PE is basically COFF with additional headers.
2396
2397While BFD includes special PE support, @value{GDBN} needs only the basic
2398COFF reader.
2399
2400@subsection ELF
2401
2402@cindex ELF format
2403The ELF format came with System V Release 4 (SVR4) Unix. ELF is
2404similar to COFF in being organized into a number of sections, but it
2405removes many of COFF's limitations. Debugging info may be either stabs
2406encapsulated in ELF sections, or more commonly these days, DWARF.
2407
2408The basic ELF reader is in @file{elfread.c}.
2409
2410@subsection SOM
2411
2412@cindex SOM format
2413SOM is HP's object file and debug format (not to be confused with IBM's
2414SOM, which is a cross-language ABI).
2415
2416The SOM reader is in @file{somread.c}.
2417
2418@section Debugging File Formats
2419
2420This section describes characteristics of debugging information that
2421are 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}
2427format. Since then, it has been encapsulated into other file
2428formats, such as COFF and ELF.
2429
2430While @file{dbxread.c} does some of the basic stab processing,
2431including for encapsulated versions, @file{stabsread.c} does
2432the real work.
2433
2434@subsection COFF
2435
2436@cindex COFF debugging info
2437The basic COFF definition includes debugging information. The level
2438of support is minimal and non-extensible, and is not often used.
2439
2440@subsection Mips debug (Third Eye)
2441
2442@cindex ECOFF debugging info
2443ECOFF includes a definition of a special debug format.
2444
2445The 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
2452DWARF 2 is an improved but incompatible version of DWARF 1.
2453
2454The DWARF 2 reader is in @file{dwarf2read.c}.
2455
2456@subsection Compressed DWARF 2
2457
2458@cindex Compressed DWARF 2 debugging info
2459Compressed DWARF 2 is not technically a separate debugging format, but
2460merely DWARF 2 debug information that has been compressed. In this
2461format, every object-file section holding DWARF 2 debugging
2462information is compressed and prepended with a header. (The section
2463is also typically renamed, so a section called @code{.debug_info} in a
2464DWARF 2 binary would be called @code{.zdebug_info} in a compressed
2465DWARF 2 binary.) The header is 12 bytes long:
2466
2467@itemize @bullet
2468@item
24694 bytes: the literal string ``ZLIB''
2470@item
24718 bytes: the uncompressed size of the section, in big-endian byte
2472order.
2473@end itemize
2474
2475The same reader is used for both compressed an normal DWARF 2 info.
2476Section 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
2482DWARF 3 is an improved version of DWARF 2.
2483
2484@subsection SOM
2485
2486@cindex SOM debugging info
2487Like 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
2492If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
2493there is probably little to be done.
2494
2495If you need to add a new object file format, you must first add it to
2496BFD. This is beyond the scope of this document.
2497
2498You must then arrange for the BFD code to provide access to the
2499debugging symbols. Generally @value{GDBN} will have to call swapping
2500routines from BFD and a few other BFD internal routines to locate the
2501debugging information. As much as possible, @value{GDBN} should not
2502depend on the BFD internal data structures.
2503
2504For some targets (e.g., COFF), there is a special transfer vector used
2505to call swapping routines, since the external data structures on various
2506platforms have different sizes and layouts. Specialized routines that
2507will only ever be implemented by one object file format may be called
2508directly. 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
2513Most memory associated with a loaded symbol file is stored on
2514its @code{objfile_obstack}. This includes symbols, types,
2515namespace data, and other information produced by the symbol readers.
2516
2517Because this data lives on the objfile's obstack, it is automatically
2518released when the objfile is unloaded or reloaded. Therefore one
2519objfile must not reference symbol or type data from another objfile;
2520they could be unloaded at different times.
2521
2522User convenience variables, et cetera, have associated types. Normally
2523these types live in the associated objfile. However, when the objfile
2524is unloaded, those types are deep copied to global memory, so that
2525the 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,
2534although it is possible for the user to set the source language
2535manually.
2536
2537@value{GDBN} chooses the source language by looking at the extension
2538of the file recorded in the debug info; @file{.c} means C, @file{.f}
2539means Fortran, etc. It may also use a special-purpose language
2540identifier 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
2545To add other languages to @value{GDBN}'s expression parser, follow the
2546following steps:
2547
2548@table @emph
2549@item Create the expression parser.
2550
2551@cindex expression parser
2552This should reside in a file @file{@var{lang}-exp.y}. Routines for
2553building parsed expressions into a @code{union exp_element} list are in
2554@file{parse.c}.
2555
2556@cindex language parser
2557Since we can't depend upon everyone having Bison, and YACC produces
2558parsers 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
2560various 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
2581At the bottom of your parser, define a @code{struct language_defn} and
2582initialize 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}
2585that your language exists. You'll need some other supporting variables
2586and functions, which will be used via pointers from your
2587@code{@var{lang}_language_defn}. See the declaration of @code{struct
2588language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
2589for 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
2597If you need new opcodes (that represent the operations of the language),
2598add them to the enumerated type in @file{expression.h}. Add support
2599code for these operations in the @code{evaluate_subexp} function
2600defined in the file @file{eval.c}. Add cases
2601for new opcodes in two functions from @file{parse.c}:
2602@code{prefixify_subexp} and @code{length_of_subexp}. These compute
2603the number of @code{exp_element}s that a given operation takes up.
2604
2605@item Update some existing code
2606
2607Add an enumerated identifier for your language to the enumerated type
2608@code{enum language} in @file{defs.h}.
2609
2610Update the routines in @file{language.c} so your language is included.
2611These routines include type predicates and such, which (in some cases)
2612are language dependent. If your language does not appear in the switch
2613statement, an error is reported.
2614
2615@vindex current_language
2616Also 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
2619string.
2620
2621@findex _initialize_language
2622Update the function @code{_initialize_language} to include your
2623language. This function picks the default language upon startup, so is
2624dependent upon which languages that @value{GDBN} is built for.
2625
2626@findex allocate_symtab
2627Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
2628code so that the language of each symtab (source file) is set properly.
2629This is used to determine the language to use at each stack frame level.
2630Currently, the language is set based upon the extension of the source
2631file. If the language can be better inferred from the symbol
2632information, please set the language of the symtab in the symbol-reading
2633code.
2634
2635@findex print_subexp
2636@findex op_print_tab
2637Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
2638expression opcodes you have added to @file{expression.h}. Also, add the
2639printed representations of your operators to @code{op_print_tab}.
2640
2641@item Add a place of call
2642
2643@findex parse_exp_1
2644Add 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
2649Add dependencies in @file{Makefile.in}. Make sure you update the macro
2650variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
2651not get linked in, or, worse yet, it may not get @code{tar}red into the
2652distribution!
2653@end table
2654
2655
2656@node Host Definition
2657
2658@chapter Host Definition
2659
2660With the advent of Autoconf, it's rarely necessary to have host
2661definition machinery anymore. The following information is provided,
2662mainly, 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.
2669New host-specific definitions should not be needed. Older hosts
2670@value{GDBN} still use the host-specific definitions and files listed
2671below, but these mostly exist for historical reasons, and will
2672eventually disappear.
2673
2674@table @file
2675@item gdb/config/@var{arch}/@var{xyz}.mh
2676This file is a Makefile fragment that once contained both host and
2677native configuration information (@pxref{Native Debugging}) for the
2678machine @var{xyz}. The host configuration information is now handled
2679by Autoconf.
2680
2681Host 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
2685New 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
2690used to define host-specific macros, but were no longer needed and
2691have all been removed.)
2692
2693@subheading Generic Host Support Files
2694
2695@cindex generic host support
2696There are some ``generic'' versions of routines that can be used by
2697various systems.
2698
2699@table @file
2700@cindex remote debugging support
2701@cindex serial line support
2702@item ser-unix.c
2703This contains serial line support for Unix systems. It is included by
2704default on all Unix-like hosts.
2705
2706@item ser-pipe.c
2707This contains serial pipe support for Unix systems. It is included by
2708default on all Unix-like hosts.
2709
2710@item ser-mingw.c
2711This contains serial line support for 32-bit programs running under
2712Windows using MinGW.
2713
2714@item ser-go32.c
2715This contains serial line support for 32-bit programs running under DOS,
2716using the DJGPP (a.k.a.@: GO32) execution environment.
2717
2718@cindex TCP remote support
2719@item ser-tcp.c
2720This contains generic TCP support using sockets. It is included by
2721default on all Unix-like hosts and with MinGW.
2722@end table
2723
2724@section Host Conditionals
2725
2726When @value{GDBN} is configured and compiled, various macros are
2727defined or left undefined, to control compilation based on the
2728attributes of the host system. While formerly they could be set in
2729host-specific header files, at present they can be changed only by
2730setting @code{CFLAGS} when building, or by editing the source code.
2731
2732These macros and their meanings (or if the meaning is not documented
2733here, then one of the source files where they are used is indicated)
2734are:
2735
2736@ftable @code
2737@item @value{GDBN}INIT_FILENAME
2738The default name of @value{GDBN}'s initialization file (normally
2739@file{.gdbinit}).
2740
5796c8dc
SS
2741@item CRLF_SOURCE_FILES
2742@cindex DOS text files
2743Define this if host files use @code{\r\n} rather than @code{\n} as a
2744line terminator. This will cause source file listings to omit @code{\r}
2745characters when printing and it will allow @code{\r\n} line endings of files
2746which are ``sourced'' by gdb. It must be possible to open files in binary
2747mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
2748
2749@item DEFAULT_PROMPT
2750@cindex prompt
2751The default value of the prompt string (normally @code{"(gdb) "}).
2752
2753@item DEV_TTY
2754@cindex terminal device
2755The name of the generic TTY device, defaults to @code{"/dev/tty"}.
2756
2757@item ISATTY
2758Substitute for isatty, if not available.
2759
2760@item FOPEN_RB
2761Define this if binary files are opened the same way as text files.
2762
5796c8dc
SS
2763@item PRINTF_HAS_LONG_LONG
2764Define this if the host can handle printing of long long integers via
2765the printf format conversion specifier @code{ll}. This is set by the
2766@code{configure} script.
2767
2768@item LSEEK_NOT_LINEAR
2769Define 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
2771is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
2772
5796c8dc
SS
2773@item lint
2774Define this to help placate @code{lint} in some situations.
2775
2776@item volatile
2777Define 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
2788machine-language programs @value{GDBN} can work with, and how it works
2789with them.
2790
2791The target architecture object is implemented as the C structure
2792@code{struct gdbarch *}. The structure, and its methods, are generated
2793using 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
2814ABIs. An OS ABI variant may have influence over any number of
2815variables in the target architecture definition. There are two major
2816components in the OS ABI mechanism: sniffers and handlers.
2817
2818A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair
2819(the architecture may be wildcarded) in an attempt to determine the
2820OS ABI of that file. Sniffers with a wildcarded architecture are considered
2821to be @dfn{generic}, while sniffers for a specific architecture are
2822considered to be @dfn{specific}. A match from a specific sniffer
2823overrides a match from a generic sniffer. Multiple sniffers for an
2824architecture/flavour may exist, in order to differentiate between two
2825different operating systems which use the same basic file format. The
2826OS ABI framework provides a generic sniffer for ELF-format files which
2827examines the @code{EI_OSABI} field of the ELF header, as well as note
2828sections known to be used by several operating systems.
2829
2830@cindex fine-tuning @code{gdbarch} structure
2831A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the
2832selected OS ABI. There may be only one handler for a given OS ABI
2833for each BFD architecture.
2834
2835The 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
2841Used for struct gdbarch_info if ABI is still uninitialized.
2842
2843@findex GDB_OSABI_UNKNOWN
2844@item GDB_OSABI_UNKNOWN
2845The ABI of the inferior is unknown. The default @code{gdbarch}
2846settings for the architecture will be used.
2847
2848@findex GDB_OSABI_SVR4
2849@item GDB_OSABI_SVR4
2850UNIX System V Release 4.
2851
2852@findex GDB_OSABI_HURD
2853@item GDB_OSABI_HURD
2854GNU using the Hurd kernel.
2855
2856@findex GDB_OSABI_SOLARIS
2857@item GDB_OSABI_SOLARIS
2858Sun Solaris.
2859
2860@findex GDB_OSABI_OSF1
2861@item GDB_OSABI_OSF1
2862OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
2863
2864@findex GDB_OSABI_LINUX
2865@item GDB_OSABI_LINUX
2866GNU using the Linux kernel.
2867
2868@findex GDB_OSABI_FREEBSD_AOUT
2869@item GDB_OSABI_FREEBSD_AOUT
2870FreeBSD using the @code{a.out} executable format.
2871
2872@findex GDB_OSABI_FREEBSD_ELF
2873@item GDB_OSABI_FREEBSD_ELF
2874FreeBSD using the ELF executable format.
2875
2876@findex GDB_OSABI_NETBSD_AOUT
2877@item GDB_OSABI_NETBSD_AOUT
2878NetBSD using the @code{a.out} executable format.
2879
2880@findex GDB_OSABI_NETBSD_ELF
2881@item GDB_OSABI_NETBSD_ELF
2882NetBSD using the ELF executable format.
2883
2884@findex GDB_OSABI_OPENBSD_ELF
2885@item GDB_OSABI_OPENBSD_ELF
2886OpenBSD using the ELF executable format.
2887
2888@findex GDB_OSABI_WINCE
2889@item GDB_OSABI_WINCE
2890Windows CE.
2891
2892@findex GDB_OSABI_GO32
2893@item GDB_OSABI_GO32
2894DJGPP.
2895
2896@findex GDB_OSABI_IRIX
2897@item GDB_OSABI_IRIX
2898Irix.
2899
2900@findex GDB_OSABI_INTERIX
2901@item GDB_OSABI_INTERIX
2902Interix (Posix layer for MS-Windows systems).
2903
2904@findex GDB_OSABI_HPUX_ELF
2905@item GDB_OSABI_HPUX_ELF
2906HP/UX using the ELF executable format.
2907
2908@findex GDB_OSABI_HPUX_SOM
2909@item GDB_OSABI_HPUX_SOM
2910HP/UX using the SOM executable format.
2911
2912@findex GDB_OSABI_QNXNTO
2913@item GDB_OSABI_QNXNTO
2914QNX Neutrino.
2915
2916@findex GDB_OSABI_CYGWIN
2917@item GDB_OSABI_CYGWIN
2918Cygwin.
2919
2920@findex GDB_OSABI_AIX
2921@item GDB_OSABI_AIX
2922AIX.
2923
2924@end table
2925
2926Here are the functions that make up the OS ABI framework:
2927
2928@deftypefun {const char *} gdbarch_osabi_name (enum gdb_osabi @var{osabi})
2929Return 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}))
2933Register the OS ABI handler specified by @var{init_osabi} for the
2934architecture, machine type and OS ABI specified by @var{arch},
2935@var{machine} and @var{osabi}. In most cases, a value of zero for the
2936machine type, which implies the architecture's default machine type,
2937will 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}))
2941Register the OS ABI file sniffer specified by @var{sniffer} for the
2942BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.
2943If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to
2944be generic, and is allowed to examine @var{flavour}-flavoured files for
2945any architecture.
2946@end deftypefun
2947
2948@deftypefun {enum gdb_osabi} gdbarch_lookup_osabi (bfd *@var{abfd})
2949Examine the file described by @var{abfd} to determine its OS ABI.
2950The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot
2951be 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})
2955Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the
2956@code{gdbarch} structure specified by @var{gdbarch}. If a handler
2957corresponding to @var{osabi} has not been registered for @var{gdbarch}'s
2958architecture, a warning will be issued and the debugging session will continue
2959with 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})
2963Helper 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
2965from 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
2983Each @code{gdbarch} is associated with a single @sc{bfd} architecture,
2984via a @code{bfd_arch_@var{arch}} in the @code{bfd_architecture}
2985enumeration. 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
2988called during @value{GDBN} startup. The arguments are a @sc{bfd}
2989architecture constant and an initialization function.
2990
2991@findex _initialize_@var{arch}_tdep
2992@cindex @file{@var{arch}-tdep.c}
2993A @value{GDBN} description for a new architecture, @var{arch} is created by
2994defining a global function @code{_initialize_@var{arch}_tdep}, by
2995convention in the source file @file{@var{arch}-tdep.c}. For example,
2996in 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
3003The 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
3006pattern matching against the @code{--target} option of the
3007@code{configure} script. The new @code{struct gdbarch} is created
3008within the @code{_initialize_@var{arch}_tdep} function by calling
3009@code{gdbarch_register}:
3010
3011@smallexample
3012void 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
3017The @var{architecture} will identify the unique @sc{bfd} to be
3018associated with this @code{gdbarch}. The @var{init_func} funciton is
3019called to create and return the new @code{struct gdbarch}. The
3020@var{tdep_dump_func} function will dump the target specific details
3021associated with this architecture.
3022
3023For example the function @code{_initialize_or1k_tdep} creates its
3024architecture for 32-bit OpenRISC 1000 architectures by calling:
3025
3026@smallexample
3027gdbarch_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
3034The initialization function has this prototype:
3035
3036@smallexample
3037static struct gdbarch *
3038@var{arch}_gdbarch_init (struct gdbarch_info @var{info},
3039 struct gdbarch_list *@var{arches})
3040@end smallexample
3041
3042The @var{info} argument contains parameters used to select the correct
3043architecture, and @var{arches} is a list of architectures which
3044have already been created with the same @code{bfd_arch_@var{arch}}
3045value.
3046
3047The initialization function should first make sure that @var{info}
3048is acceptable, and return @code{NULL} if it is not. Then, it should
3049search through @var{arches} for an exact match to @var{info}, and
3050return one if found. Lastly, if no exact match was found, it should
3051create a new architecture based on @var{info} and return it.
3052
3053@findex gdbarch_list_lookup_by_info
3054@cindex @code{gdbarch_info}
3055The lookup is done using @code{gdbarch_list_lookup_by_info}. It is
3056passed the list of existing architectures, @var{arches}, and the
3057@code{struct gdbarch_info}, @var{info}, and returns the first matching
3058architecture it finds, or @code{NULL} if none are found. If an
3059architecture is found it can be returned as the result from the
3060initialization function, otherwise a new @code{struct gdbach} will need
3061to be created.
3062
3063The struct gdbarch_info has the following components:
3064
3065@smallexample
3066struct 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
3078The @code{bfd_arch_info} member holds the key details about the
3079architecture. The @code{byte_order} member is a value in an
3080enumeration indicating the endianism. The @code{abfd} member is a
3081pointer to the full @sc{bfd}, the @code{tdep_info} member is
3082additional custom target specific information, @code{osabi} identifies
3083which (if any) of a number of operating specific ABIs are used by this
3084architecture and the @code{target_desc} member is a set of name-value
3085pairs with information about register usage in this target.
3086
3087When the @code{struct gdbarch} initialization function is called, not
3088all 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
3090look-up key with the list of existing architectures, @var{arches} to
3091see if a suitable architecture already exists. The @var{tdep_info},
3092@var{osabi} and @var{target_desc} fields may be added before this
3093lookup to refine the search.
3094
3095Only information in @var{info} should be used to choose the new
3096architecture. Historically, @var{info} could be sparse, and
3097defaults would be collected from the first element on @var{arches}.
3098However, @value{GDBN} now fills in @var{info} more thoroughly,
3099so new @code{gdbarch} initialization functions should not take
3100defaults 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}
3108If no architecture is found, then a new architecture must be created,
3109by calling @code{gdbarch_alloc} using the supplied @code{@w{struct
3110gdbarch_info}} and any additional custom target specific
3111information in a @code{struct gdbarch_tdep}. The prototype for
3112@code{gdbarch_alloc} is:
3113
3114@smallexample
3115struct 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
3121The newly created struct gdbarch must then be populated. Although
3122there are default values, in most cases they are not what is
3123required.
3124
3125For each element, @var{X}, there is are a pair of corresponding accessor
3126functions, one to set the value of that element,
3127@code{set_gdbarch_@var{X}}, the second to either get the value of an
3128element (if it is a variable) or to apply the element (if it is a
3129function), @code{gdbarch_@var{X}}. Note that both accessor functions
3130take a pointer to the @code{@w{struct gdbarch}} as first
3131argument. Populating the new @code{gdbarch} should use the
3132@code{set_gdbarch} functions.
3133
3134The following sections identify the main elements that should be set
3135in this way. This is not the complete list, but represents the
3136functions and elements that must commonly be specified for a new
3137architecture. Many of the functions and variables are described in the
3138header file @file{gdbarch.h}.
3139
3140This is the main work in defining a new architecture. Implementing the
3141set 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
3145to the user to define this struct if it is needed to hold custom target
3146information that is not covered by the standard @code{@w{struct
3147gdbarch}}. For example with the OpenRISC 1000 architecture it is used to
3148hold the number of matchpoints available in the target (along with other
3149information).
3150
3151If 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
3159block of memory. Each register may have a different size.
3160
3161@value{GDBN} does not have a magical way to match up with the
3162compiler's idea of which registers are which; however, it is critical
3163that they do match up accurately. The only way to make this work is
3164to get accurate information about the order that the compiler uses,
3165and 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
3181On almost all 32-bit architectures, the representation of a pointer is
3182indistinguishable from the representation of some fixed-length number
3183whose value is the byte address of the object pointed to. On such
3184machines, the words ``pointer'' and ``address'' can be used interchangeably.
3185However, architectures with smaller word sizes are often cramped for
3186address space, so they may choose a pointer representation that breaks this
3187identity, and allows a larger code address space.
3188
3189@c D10V is gone from sources - more current example?
3190
3191For example, the Renesas D10V is a 16-bit VLIW processor whose
3192instructions are 32 bits long@footnote{Some D10V instructions are
3193actually pairs of 16-bit sub-instructions. However, since you can't
3194jump into the middle of such a pair, code addresses can only refer to
3195full 32 bit instructions, which is what matters in this explanation.}.
3196If the D10V used ordinary byte addresses to refer to code locations,
3197then the processor would only be able to address 64kb of instructions.
3198However, since instructions must be aligned on four-byte boundaries, the
3199low two bits of any valid instruction's byte address are always
3200zero---byte addresses waste two bits. So instead of byte addresses,
3201the D10V uses word addresses---byte addresses shifted right two bits---to
3202refer to code. Thus, the D10V can use 16-bit words to address 256kb of
3203code space.
3204
3205However, this means that code pointers and data pointers have different
3206forms 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
3211affects the correspondence between pointers and addresses, but we're
3212going to ignore that here; this example is already too long.)
3213
3214To cope with architectures like this---the D10V is not the only
3215one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
3216byte numbers, and @dfn{pointers}, which are the target's representation
3217of 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
3221and vice versa, in the appropriate way for the current architecture.
3222
3223Unfortunately, since addresses and pointers are identical on almost all
3224processors, this distinction tends to bit-rot pretty quickly. Thus,
3225each time you port @value{GDBN} to an architecture which does
3226distinguish between pointers and addresses, you'll probably need to
3227clean up some architecture-independent code.
3228
3229Here are functions which convert between pointers and addresses:
3230
3231@deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
3232Treat the bytes at @var{buf} as a pointer or reference of type
3233@var{type}, and return the address it represents, in a manner
3234appropriate 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
3237inferior's.
3238
3239For example, if the current architecture is the Intel x86, this function
3240extracts a little-endian integer of the appropriate length from
3241@var{buf} and returns it. However, if the current architecture is the
3242D10V, 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
3245If @var{type} is not a pointer or reference type, then this function
3246will 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})
3250Store the address @var{addr} in @var{buf}, in the proper format for a
3251pointer of type @var{type} in the current architecture. Note that
3252@var{buf} refers to a buffer in @value{GDBN}'s memory, not the
3253inferior's.
3254
3255For example, if the current architecture is the Intel x86, this function
3256stores @var{addr} unmodified as a little-endian integer of the
3257appropriate length in @var{buf}. However, if the current architecture
3258is the D10V, this function divides @var{addr} by four if @var{type} is
3259a pointer to a function, and then stores it in @var{buf}.
3260
3261If @var{type} is not a pointer or reference type, then this function
3262will signal an internal error.
3263@end deftypefun
3264
3265@deftypefun CORE_ADDR value_as_address (struct value *@var{val})
3266Assuming that @var{val} is a pointer, return the address it represents,
3267as appropriate for the current architecture.
3268
3269This function actually works on integral values, as well as pointers.
3270For pointers, it performs architecture-specific conversions as
3271described 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})
3275Create and return a value representing a pointer of type @var{type} to
3276the address @var{addr}, as appropriate for the current architecture.
3277This function performs architecture-specific conversions as described
3278above for @code{store_typed_address}.
3279@end deftypefun
3280
3281Here are two functions which architectures can define to indicate the
3282relationship between pointers and addresses. These have default
3283definitions, appropriate for architectures on which all pointers are
3284simple unsigned byte addresses.
3285
3286@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf})
3287Assume that @var{buf} holds a pointer of type @var{type}, in the
3288appropriate format for the current architecture. Return the byte
3289address the pointer refers to.
3290
3291This function may safely assume that @var{type} is either a pointer or a
3292C@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})
3296Store in @var{buf} a pointer of type @var{type} representing the address
3297@var{addr}, in the appropriate format for the current architecture.
3298
3299This function may safely assume that @var{type} is either a pointer or a
3300C@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
3309Sometimes information about different kinds of addresses is available
3310via the debug information. For example, some programming environments
3311define addresses of several different sizes. If the debug information
3312distinguishes these kinds of address classes through either the size
3313info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit
3314address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the
3315following macros should be defined in order to disambiguate these
3316types within @value{GDBN} as well as provide the added information to
3317a @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})
3320Returns the type flags needed to construct a pointer type whose size
3321is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.
3322This 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})
3327Given the type flags representing an address class qualifier, return
3328its 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})
3331Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags
3332for that address class qualifier.
3333@end deftypefun
3334
3335Since the need for address classes is rather rare, none of
3336the address class functions are defined by default. Predicate
3337functions are provided to detect when they are defined.
3338
3339Consider a hypothetical architecture in which addresses are normally
334032-bits wide, but 16-bit addresses are also supported. Furthermore,
3341suppose that the @w{DWARF 2} information for this architecture simply
3342uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one
3343of these "short" pointers. The following functions could be defined
3344to implement the address class functions:
3345
3346@smallexample
3347somearch_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
3356static char *
3357somearch_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
3365int
3366somearch_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
3379The qualifier @code{@@short} is used in @value{GDBN}'s type expressions
3380to indicate the presence of one of these ``short'' pointers. For
3381example if the debug information indicates that @code{short_ptr_var} is
3382one of these short pointers, @value{GDBN} might show the following
3383behavior:
3384
3385@smallexample
3386(gdb) ptype short_ptr_var
3387type = 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
3409linearly from 0 upwards. The first part of that set corresponds to real
3410physical registers, the second part to any @dfn{pseudo-registers}.
3411Pseudo-registers have no independent physical existence, but are useful
3412representations of information within the architecture. For example the
3413OpenRISC 1000 architecture has up to 32 general purpose registers, which
3414are typically represented as 32-bit (or 64-bit) integers. However the
3415GPRs are also used as operands to the floating point operations, and it
3416could be convenient to define a set of pseudo-registers, to show the
3417GPRs represented as floating point values.
3418
3419For any architecture, the implementer will decide on a mapping from
3420hardware to @value{GDBN} register numbers. The registers corresponding to real
3421hardware are referred to as @dfn{raw} registers, the remaining registers are
3422@dfn{pseudo-registers}. The total register set (raw and pseudo) is called
3423the @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
3430These @code{struct gdbarch} functions and variables specify the number
3431and 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
3437Read or write the program counter. The default value of both
3438functions is @code{NULL} (no function available). If the program
3439counter is just an ordinary register, it can be specified in
3440@code{struct gdbarch} instead (see @code{pc_regnum} below) and it will
3441be read or written using the standard routines to access registers. This
3442function need only be specified if the program counter is not an
3443ordinary register.
3444
3445Any register information can be obtained using the supplied register
3446cache, @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
3454These functions should be defined if there are any pseudo-registers.
3455The default value is @code{NULL}. @var{regnum} is the number of the
3456register to read or write (which will be a @dfn{cooked} register
3457number) and @var{buf} is the buffer where the value read will be
3458placed, or from which the value to be written will be taken. The
3459value in the buffer may be converted to or from a signed or unsigned
3460integral value using one of the utility functions (@pxref{Register and
3461Memory Data, , Using Different Register and Memory Data
3462Representations}).
3463
3464The access should be for the specified architecture,
3465@var{gdbarch}. Any register information can be obtained using the
3466supplied register cache, @var{regcache}. @xref{Register Caching, ,
3467Register 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
3476This specifies the register holding the stack pointer, which may be a
3477raw or pseudo-register. It defaults to -1 (not defined), but it is an
3478error for it not to be defined.
3479
3480The 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
3490This specifies the register holding the program counter, which may be a
3491raw 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
3495The value of the program counter (whether defined as a register, or
3496through @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
3507This specifies the register holding the processor status (often called
3508the status register), which may be a raw or pseudo-register. It
3509defaults to -1 (not defined).
3510
3511If 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
3520This specifies the first floating point register. It defaults to
35210. @code{fp0_regnum} is not needed unless the target offers support
3522for 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
3530These functions return information about registers.
3531
3532@deftypefn {Architecture Function} {const char *} register_name (struct gdbarch *@var{gdbarch}, int @var{regnum})
3533
3534This function should convert a register number (raw or pseudo) to a
3535register name (as a C @code{const char *}). This is used both to
3536determine the name of a register for output and to work out the meaning
3537of 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
3540For example with the OpenRISC 1000, @value{GDBN} registers 0-31 are the
3541General Purpose Registers, register 32 is the program counter and
3542register 33 is the supervision register (i.e.@: the processor status
3543register), which map to the strings @code{"gpr00"} through
3544@code{"gpr31"}, @code{"pc"} and @code{"sr"} respectively. This means
3545that the @value{GDBN} command @kbd{print $gpr5} should print the value of
3546the OR1K general purpose register 5@footnote{
3547@cindex frame pointer
3548@cindex @kbd{$fp}
3549Historically, @value{GDBN} always had a concept of a frame pointer
3550register, which could be accessed via the @value{GDBN} variable,
3551@kbd{$fp}. That concept is now deprecated, recognizing that not all
3552architectures have a frame pointer. However if an architecture does
3553have a frame pointer register, and defines a register or
3554pseudo-register with the name @code{"fp"}, then that register will be
3555used as the value of the @kbd{$fp} variable.}.
3556
3557The default value for this function is @code{NULL}, meaning
3558undefined. It should always be defined.
3559
3560The 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
3566Given a register number, this function identifies the type of data it
3567may be holding, specified as a @code{struct type}. @value{GDBN} allows
3568creation of arbitrary types, but a number of built in types are
3569provided (@code{builtin_type_void}, @code{builtin_type_int32} etc),
3570together with functions to derive types from these.
3571
3572Typically the program counter will have a type of ``pointer to
3573function'' (it points to code), the frame pointer and stack pointer
3574will have types of ``pointer to void'' (they point to data on the stack)
3575and all other integer registers will have a type of 32-bit integer or
357664-bit integer.
3577
3578This information guides the formatting when displaying register
3579information. The default value is @code{NULL} meaning no information is
3580available 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
3586Define 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
3588function @code{default_print_registers_info}, which uses the register
3589type information (see @code{register_type} above) to determine how each
3590register should be printed. Define a custom version of this function
3591for fuller control over how the registers are displayed.
3592
3593The access should be for the specified architecture, @var{gdbarch},
a45ae5f8 3594with output to the file specified by the User Interface
5796c8dc
SS
3595Independent Output file handle, @var{file} (@pxref{UI-Independent
3596Output, , UI-Independent Output---the @code{ui_out}
3597Functions}).
3598
3599The 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
3601the ``significant'' registers should be shown (the implementer should
3602decide which registers are ``significant''). Otherwise only the value of
3603the 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
3605all registers should be shown.
3606
3607By default @code{default_print_registers_info} prints one register per
3608line, 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
3614Define this function to provide output about the floating point unit and
3615registers for the @value{GDBN} @kbd{info float} command respectively.
3616The default value is @code{NULL} (not defined), meaning no information
3617will be provided.
3618
3619The @var{gdbarch} and @var{file} and @var{frame} arguments have the same
3620meaning as in the @code{print_registers_info} function above. The string
3621@var{args} contains any supplementary arguments to the @kbd{info float}
3622command.
3623
3624Define 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
3630Define this function to provide output about the vector unit and
3631registers for the @value{GDBN} @kbd{info vector} command respectively.
3632The default value is @code{NULL} (not defined), meaning no information
3633will be provided.
3634
3635The @var{gdbarch}, @var{file} and @var{frame} arguments have the
3636same meaning as in the @code{print_registers_info} function above. The
3637string @var{args} contains any supplementary arguments to the @kbd{info
3638vector} command.
3639
3640Define 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,
3647vector, floating point etc). This function, given a register,
3648@var{regnum}, and group, @var{group}, returns 1 (true) if the register
3649is in the group and 0 (false) otherwise.
3650
3651The information should be for the specified architecture,
3652@var{gdbarch}
3653
3654The default value is the function @code{default_register_reggroup_p}
3655which will do a reasonable job based on the type of the register (see
3656the function @code{register_type} above), with groups for general
3657purpose 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
3670Some architectures have different representations of data objects,
3671depending whether the object is held in a register or memory. For
3672example:
3673
3674@itemize @bullet
3675
3676@item
3677The Alpha architecture can represent 32 bit integer values in
3678floating-point registers.
3679
3680@item
3681The x86 architecture supports 80-bit floating-point registers. The
3682@code{long double} data type occupies 96 bits in memory but only 80
3683bits when stored in a register.
3684
3685@end itemize
3686
3687In general, the register representation of a data type is determined by
3688the architecture, or @value{GDBN}'s interface to the architecture, while
3689the memory representation is determined by the Application Binary
3690Interface.
3691
3692For almost all data types on almost all architectures, the two
3693representations are identical, and no special handling is needed.
3694However, they do occasionally differ. An architecture may define the
3695following @code{struct gdbarch} functions to request conversions
3696between 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
3700Return non-zero (true) if the representation of a data value stored in
3701this register may be different to the representation of that same data
3702value when stored in memory. The default value is @code{NULL}
3703(undefined).
3704
3705If this function is defined and returns non-zero, the @code{struct
3706gdbarch} functions @code{gdbarch_register_to_value} and
3707@code{gdbarch_value_to_register} (see below) should be used to perform
3708any necessary conversion.
3709
3710If defined, this function should return zero for the register's native
3711type, 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
3716Convert the value of register number @var{reg} to a data object of
3717type @var{type}. The buffer at @var{from} holds the register's value
3718in 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}
3724arguments in different orders.
3725@end quotation
3726
3727@code{gdbarch_register_to_value} should only be used with registers
3728for which the @code{gdbarch_convert_register_p} function returns a
3729non-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
3735Convert a data value of type @var{type} to register number @var{reg}'
3736raw 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}
3741arguments in different orders.
3742@end quotation
3743
3744@code{gdbarch_value_to_register} should only be used with registers
3745for which the @code{gdbarch_convert_register_p} function returns a
3746non-zero value.
3747
3748@end deftypefn
3749
3750@node Register Caching
3751@subsection Register Caching
3752@cindex register caching
3753
3754Caching of registers is used, so that the target does not need to be
3755accessed and reanalyzed multiple times for each register in
3756circumstances where the register value cannot have changed.
3757
3758@cindex @code{struct regcache}
3759@value{GDBN} provides @code{struct regcache}, associated with a
3760particular @code{struct gdbarch} to hold the cached values of the raw
3761registers. A set of functions is provided to access both the raw
3762registers (with @code{raw} in their name) and the full set of cooked
3763registers (with @code{cooked} in their name). Functions are provided
3764to ensure the register cache is kept synchronized with the values of
3765the actual registers in the target.
3766
3767Accessing registers through the @code{struct regcache} routines will
3768ensure that the appropriate @code{struct gdbarch} functions are called
3769when necessary to access the underlying target architecture. In general
3770users 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
3780The two key functions are @code{regcache_cooked_read} and
3781@code{regcache_cooked_write} which read or write a register from or to
3782a byte buffer (type @code{gdb_byte *}). For convenience the wrapper
3783functions @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
3787write the value using the buffer and convert to or from an integral
3788value 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)
3806variables are stored. The area of the stack containing all the local
3807variables for a function invocation is known as the @dfn{stack frame}
3808for that function (or colloquially just as the @dfn{frame}). In turn the
3809function that called the function will have its stack frame, and so on
3810back through the chain of functions that have been called.
3811
3812Almost all architectures have one register dedicated to point to the
3813end of the stack (the @dfn{stack pointer}). Many have a second register
3814which points to the start of the currently active stack frame (the
3815@dfn{frame pointer}). The specific arrangements for an architecture are
3816a key part of the ABI.
3817
3818A diagram helps to explain this. Here is a simple program to compute
3819factorials:
3820
3821@smallexample
3822#include <stdio.h>
3823int 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
3835main ()
3836@{
3837 int i;