9058 lines
391 KiB
Plaintext
9058 lines
391 KiB
Plaintext
This is gdbint.info, produced by makeinfo version 4.13 from
|
||
./gdbint.texinfo.
|
||
|
||
INFO-DIR-SECTION Software development
|
||
START-INFO-DIR-ENTRY
|
||
* Gdb-Internals: (gdbint). The GNU debugger's internals.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
Copyright (C) 1990-2013 Free Software Foundation, Inc. Contributed
|
||
by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan
|
||
Shebs.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with no
|
||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
||
Texts. A copy of the license is included in the section entitled "GNU
|
||
Free Documentation License".
|
||
|
||
This file documents the internals of the GNU debugger GDB.
|
||
|
||
Copyright (C) 1990-2013 Free Software Foundation, Inc. Contributed
|
||
by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan
|
||
Shebs.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with no
|
||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
||
Texts. A copy of the license is included in the section entitled "GNU
|
||
Free Documentation License".
|
||
|
||
|
||
File: gdbint.info, Node: Top, Next: Summary, Up: (dir)
|
||
|
||
Scope of this Document
|
||
**********************
|
||
|
||
This document documents the internals of the GNU debugger, GDB. It
|
||
includes description of GDB's key algorithms and operations, as well as
|
||
the mechanisms that adapt GDB to specific hosts and targets.
|
||
|
||
* Menu:
|
||
|
||
* Summary::
|
||
* Overall Structure::
|
||
* Algorithms::
|
||
* User Interface::
|
||
* libgdb::
|
||
* Values::
|
||
* Stack Frames::
|
||
* Symbol Handling::
|
||
* Language Support::
|
||
* Host Definition::
|
||
* Target Architecture Definition::
|
||
* Target Descriptions::
|
||
* Target Vector Definition::
|
||
* Native Debugging::
|
||
* Support Libraries::
|
||
* Coding Standards::
|
||
* Misc Guidelines::
|
||
* Porting GDB::
|
||
* Versions and Branches::
|
||
* Start of New Year Procedure::
|
||
* Releasing GDB::
|
||
* Testsuite::
|
||
* Hints::
|
||
|
||
* GDB Observers:: GDB Currently available observers
|
||
* GNU Free Documentation License:: The license for this documentation
|
||
* Concept Index::
|
||
* Function and Variable Index::
|
||
|
||
|
||
File: gdbint.info, Node: Summary, Next: Overall Structure, Prev: Top, Up: Top
|
||
|
||
1 Summary
|
||
*********
|
||
|
||
* Menu:
|
||
|
||
* Requirements::
|
||
* Contributors::
|
||
|
||
|
||
File: gdbint.info, Node: Requirements, Next: Contributors, Up: Summary
|
||
|
||
1.1 Requirements
|
||
================
|
||
|
||
Before diving into the internals, you should understand the formal
|
||
requirements and other expectations for GDB. Although some of these
|
||
may seem obvious, there have been proposals for GDB that have run
|
||
counter to these requirements.
|
||
|
||
First of all, GDB is a debugger. It's not designed to be a front
|
||
panel for embedded systems. It's not a text editor. It's not a shell.
|
||
It's not a programming environment.
|
||
|
||
GDB is an interactive tool. Although a batch mode is available,
|
||
GDB's primary role is to interact with a human programmer.
|
||
|
||
GDB should be responsive to the user. A programmer hot on the trail
|
||
of a nasty bug, and operating under a looming deadline, is going to be
|
||
very impatient of everything, including the response time to debugger
|
||
commands.
|
||
|
||
GDB should be relatively permissive, such as for expressions. While
|
||
the compiler should be picky (or have the option to be made picky),
|
||
since source code lives for a long time usually, the programmer doing
|
||
debugging shouldn't be spending time figuring out to mollify the
|
||
debugger.
|
||
|
||
GDB will be called upon to deal with really large programs.
|
||
Executable sizes of 50 to 100 megabytes occur regularly, and we've
|
||
heard reports of programs approaching 1 gigabyte in size.
|
||
|
||
GDB should be able to run everywhere. No other debugger is
|
||
available for even half as many configurations as GDB supports.
|
||
|
||
|
||
File: gdbint.info, Node: Contributors, Prev: Requirements, Up: Summary
|
||
|
||
1.2 Contributors
|
||
================
|
||
|
||
The first edition of this document was written by John Gilmore of
|
||
Cygnus Solutions. The current second edition was written by Stan Shebs
|
||
of Cygnus Solutions, who continues to update the manual.
|
||
|
||
Over the years, many others have made additions and changes to this
|
||
document. This section attempts to record the significant contributors
|
||
to that effort. One of the virtues of free software is that everyone is
|
||
free to contribute to it; with regret, we cannot actually acknowledge
|
||
everyone here.
|
||
|
||
_Plea:_ This section has only been added relatively recently (four
|
||
years after publication of the second edition). Additions to this
|
||
section are particularly welcome. If you or your friends (or
|
||
enemies, to be evenhanded) have been unfairly omitted from this
|
||
list, we would like to add your names!
|
||
|
||
A document such as this relies on being kept up to date by numerous
|
||
small updates by contributing engineers as they make changes to the
|
||
code base. The file `ChangeLog' in the GDB distribution approximates a
|
||
blow-by-blow account. The most prolific contributors to this important,
|
||
but low profile task are Andrew Cagney (responsible for over half the
|
||
entries), Daniel Jacobowitz, Mark Kettenis, Jim Blandy and Eli
|
||
Zaretskii.
|
||
|
||
Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting
|
||
watchpoints.
|
||
|
||
Jeremy Bennett updated the sections on initializing a new
|
||
architecture and register representation, and added the section on
|
||
Frame Interpretation.
|
||
|
||
|
||
File: gdbint.info, Node: Overall Structure, Next: Algorithms, Prev: Summary, Up: Top
|
||
|
||
2 Overall Structure
|
||
*******************
|
||
|
||
GDB consists of three major subsystems: user interface, symbol handling
|
||
(the "symbol side"), and target system handling (the "target side").
|
||
|
||
The user interface consists of several actual interfaces, plus
|
||
supporting code.
|
||
|
||
The symbol side consists of object file readers, debugging info
|
||
interpreters, symbol table management, source language expression
|
||
parsing, type and value printing.
|
||
|
||
The target side consists of execution control, stack frame analysis,
|
||
and physical target manipulation.
|
||
|
||
The target side/symbol side division is not formal, and there are a
|
||
number of exceptions. For instance, core file support involves symbolic
|
||
elements (the basic core file reader is in BFD) and target elements (it
|
||
supplies the contents of memory and the values of registers). Instead,
|
||
this division is useful for understanding how the minor subsystems
|
||
should fit together.
|
||
|
||
2.1 The Symbol Side
|
||
===================
|
||
|
||
The symbolic side of GDB can be thought of as "everything you can do in
|
||
GDB without having a live program running". For instance, you can look
|
||
at the types of variables, and evaluate many kinds of expressions.
|
||
|
||
2.2 The Target Side
|
||
===================
|
||
|
||
The target side of GDB is the "bits and bytes manipulator". Although
|
||
it may make reference to symbolic info here and there, most of the
|
||
target side will run with only a stripped executable available--or even
|
||
no executable at all, in remote debugging cases.
|
||
|
||
Operations such as disassembly, stack frame crawls, and register
|
||
display, are able to work with no symbolic info at all. In some cases,
|
||
such as disassembly, GDB will use symbolic info to present addresses
|
||
relative to symbols rather than as raw numbers, but it will work either
|
||
way.
|
||
|
||
2.3 Configurations
|
||
==================
|
||
|
||
"Host" refers to attributes of the system where GDB runs. "Target"
|
||
refers to the system where the program being debugged executes. In
|
||
most cases they are the same machine, in which case a third type of
|
||
"Native" attributes come into play.
|
||
|
||
Defines and include files needed to build on the host are host
|
||
support. Examples are tty support, system defined types, host byte
|
||
order, host float format. These are all calculated by `autoconf' when
|
||
the debugger is built.
|
||
|
||
Defines and information needed to handle the target format are target
|
||
dependent. Examples are the stack frame format, instruction set,
|
||
breakpoint instruction, registers, and how to set up and tear down the
|
||
stack to call a function.
|
||
|
||
Information that is only needed when the host and target are the
|
||
same, is native dependent. One example is Unix child process support;
|
||
if the host and target are not the same, calling `fork' to start the
|
||
target process is a bad idea. The various macros needed for finding the
|
||
registers in the `upage', running `ptrace', and such are all in the
|
||
native-dependent files.
|
||
|
||
Another example of native-dependent code is support for features that
|
||
are really part of the target environment, but which require `#include'
|
||
files that are only available on the host system. Core file handling
|
||
and `setjmp' handling are two common cases.
|
||
|
||
When you want to make GDB work as the traditional native debugger on
|
||
a system, you will need to supply both target and native information.
|
||
|
||
2.4 Source Tree Structure
|
||
=========================
|
||
|
||
The GDB source directory has a mostly flat structure--there are only a
|
||
few subdirectories. A file's name usually gives a hint as to what it
|
||
does; for example, `stabsread.c' reads stabs, `dwarf2read.c' reads
|
||
DWARF 2, etc.
|
||
|
||
Files that are related to some common task have names that share
|
||
common substrings. For example, `*-thread.c' files deal with debugging
|
||
threads on various platforms; `*read.c' files deal with reading various
|
||
kinds of symbol and object files; `inf*.c' files deal with direct
|
||
control of the "inferior program" (GDB parlance for the program being
|
||
debugged).
|
||
|
||
There are several dozens of files in the `*-tdep.c' family. `tdep'
|
||
stands for "target-dependent code"--each of these files implements
|
||
debug support for a specific target architecture (sparc, mips, etc).
|
||
Usually, only one of these will be used in a specific GDB configuration
|
||
(sometimes two, closely related).
|
||
|
||
Similarly, there are many `*-nat.c' files, each one for native
|
||
debugging on a specific system (e.g., `sparc-linux-nat.c' is for native
|
||
debugging of Sparc machines running the Linux kernel).
|
||
|
||
The few subdirectories of the source tree are:
|
||
|
||
`cli'
|
||
Code that implements "CLI", the GDB Command-Line Interpreter.
|
||
*Note Command Interpreter: User Interface.
|
||
|
||
`gdbserver'
|
||
Code for the GDB remote server.
|
||
|
||
`gdbtk'
|
||
Code for Insight, the GDB TK-based GUI front-end.
|
||
|
||
`mi'
|
||
The "GDB/MI", the GDB Machine Interface interpreter.
|
||
|
||
`signals'
|
||
Target signal translation code.
|
||
|
||
`tui'
|
||
Code for "TUI", the GDB Text-mode full-screen User Interface.
|
||
*Note TUI: User Interface.
|
||
|
||
|
||
File: gdbint.info, Node: Algorithms, Next: User Interface, Prev: Overall Structure, Up: Top
|
||
|
||
3 Algorithms
|
||
************
|
||
|
||
GDB uses a number of debugging-specific algorithms. They are often not
|
||
very complicated, but get lost in the thicket of special cases and
|
||
real-world issues. This chapter describes the basic algorithms and
|
||
mentions some of the specific target definitions that they use.
|
||
|
||
3.1 Prologue Analysis
|
||
=====================
|
||
|
||
To produce a backtrace and allow the user to manipulate older frames'
|
||
variables and arguments, GDB needs to find the base addresses of older
|
||
frames, and discover where those frames' registers have been saved.
|
||
Since a frame's "callee-saves" registers get saved by younger frames if
|
||
and when they're reused, a frame's registers may be scattered
|
||
unpredictably across younger frames. This means that changing the
|
||
value of a register-allocated variable in an older frame may actually
|
||
entail writing to a save slot in some younger frame.
|
||
|
||
Modern versions of GCC emit Dwarf call frame information ("CFI"),
|
||
which describes how to find frame base addresses and saved registers.
|
||
But CFI is not always available, so as a fallback GDB uses a technique
|
||
called "prologue analysis" to find frame sizes and saved registers. A
|
||
prologue analyzer disassembles the function's machine code starting
|
||
from its entry point, and looks for instructions that allocate frame
|
||
space, save the stack pointer in a frame pointer register, save
|
||
registers, and so on. Obviously, this can't be done accurately in
|
||
general, but it's tractable to do well enough to be very helpful.
|
||
Prologue analysis predates the GNU toolchain's support for CFI; at one
|
||
time, prologue analysis was the only mechanism GDB used for stack
|
||
unwinding at all, when the function calling conventions didn't specify
|
||
a fixed frame layout.
|
||
|
||
In the olden days, function prologues were generated by hand-written,
|
||
target-specific code in GCC, and treated as opaque and untouchable by
|
||
optimizers. Looking at this code, it was usually straightforward to
|
||
write a prologue analyzer for GDB that would accurately understand all
|
||
the prologues GCC would generate. However, over time GCC became more
|
||
aggressive about instruction scheduling, and began to understand more
|
||
about the semantics of the prologue instructions themselves; in
|
||
response, GDB's analyzers became more complex and fragile. Keeping the
|
||
prologue analyzers working as GCC (and the instruction sets themselves)
|
||
evolved became a substantial task.
|
||
|
||
To try to address this problem, the code in `prologue-value.h' and
|
||
`prologue-value.c' provides a general framework for writing prologue
|
||
analyzers that are simpler and more robust than ad-hoc analyzers. When
|
||
we analyze a prologue using the prologue-value framework, we're really
|
||
doing "abstract interpretation" or "pseudo-evaluation": running the
|
||
function's code in simulation, but using conservative approximations of
|
||
the values registers and memory would hold when the code actually runs.
|
||
For example, if our function starts with the instruction:
|
||
|
||
addi r1, 42 # add 42 to r1
|
||
we don't know exactly what value will be in `r1' after executing
|
||
this instruction, but we do know it'll be 42 greater than its original
|
||
value.
|
||
|
||
If we then see an instruction like:
|
||
|
||
addi r1, 22 # add 22 to r1
|
||
we still don't know what `r1's' value is, but again, we can say it
|
||
is now 64 greater than its original value.
|
||
|
||
If the next instruction were:
|
||
|
||
mov r2, r1 # set r2 to r1's value
|
||
then we can say that `r2's' value is now the original value of `r1'
|
||
plus 64.
|
||
|
||
It's common for prologues to save registers on the stack, so we'll
|
||
need to track the values of stack frame slots, as well as the
|
||
registers. So after an instruction like this:
|
||
|
||
mov (fp+4), r2
|
||
then we'd know that the stack slot four bytes above the frame pointer
|
||
holds the original value of `r1' plus 64.
|
||
|
||
And so on.
|
||
|
||
Of course, this can only go so far before it gets unreasonable. If
|
||
we wanted to be able to say anything about the value of `r1' after the
|
||
instruction:
|
||
|
||
xor r1, r3 # exclusive-or r1 and r3, place result in r1
|
||
then things would get pretty complex. But remember, we're just doing
|
||
a conservative approximation; if exclusive-or instructions aren't
|
||
relevant to prologues, we can just say `r1''s value is now "unknown".
|
||
We can ignore things that are too complex, if that loss of information
|
||
is acceptable for our application.
|
||
|
||
So when we say "conservative approximation" here, what we mean is an
|
||
approximation that is either accurate, or marked "unknown", but never
|
||
inaccurate.
|
||
|
||
Using this framework, a prologue analyzer is simply an interpreter
|
||
for machine code, but one that uses conservative approximations for the
|
||
contents of registers and memory instead of actual values. Starting
|
||
from the function's entry point, you simulate instructions up to the
|
||
current PC, or an instruction that you don't know how to simulate. Now
|
||
you can examine the state of the registers and stack slots you've kept
|
||
track of.
|
||
|
||
* To see how large your stack frame is, just check the value of the
|
||
stack pointer register; if it's the original value of the SP minus
|
||
a constant, then that constant is the stack frame's size. If the
|
||
SP's value has been marked as "unknown", then that means the
|
||
prologue has done something too complex for us to track, and we
|
||
don't know the frame size.
|
||
|
||
* To see where we've saved the previous frame's registers, we just
|
||
search the values we've tracked -- stack slots, usually, but
|
||
registers, too, if you want -- for something equal to the
|
||
register's original value. If the calling conventions suggest a
|
||
standard place to save a given register, then we can check there
|
||
first, but really, anything that will get us back the original
|
||
value will probably work.
|
||
|
||
This does take some work. But prologue analyzers aren't
|
||
quick-and-simple pattern patching to recognize a few fixed prologue
|
||
forms any more; they're big, hairy functions. Along with inferior
|
||
function calls, prologue analysis accounts for a substantial portion of
|
||
the time needed to stabilize a GDB port. So it's worthwhile to look
|
||
for an approach that will be easier to understand and maintain. In the
|
||
approach described above:
|
||
|
||
* It's easier to see that the analyzer is correct: you just see
|
||
whether the analyzer properly (albeit conservatively) simulates
|
||
the effect of each instruction.
|
||
|
||
* It's easier to extend the analyzer: you can add support for new
|
||
instructions, and know that you haven't broken anything that
|
||
wasn't already broken before.
|
||
|
||
* It's orthogonal: to gather new information, you don't need to
|
||
complicate the code for each instruction. As long as your domain
|
||
of conservative values is already detailed enough to tell you what
|
||
you need, then all the existing instruction simulations are
|
||
already gathering the right data for you.
|
||
|
||
|
||
The file `prologue-value.h' contains detailed comments explaining
|
||
the framework and how to use it.
|
||
|
||
3.2 Breakpoint Handling
|
||
=======================
|
||
|
||
In general, a breakpoint is a user-designated location in the program
|
||
where the user wants to regain control if program execution ever reaches
|
||
that location.
|
||
|
||
There are two main ways to implement breakpoints; either as
|
||
"hardware" breakpoints or as "software" breakpoints.
|
||
|
||
Hardware breakpoints are sometimes available as a builtin debugging
|
||
features with some chips. Typically these work by having dedicated
|
||
register into which the breakpoint address may be stored. If the PC
|
||
(shorthand for "program counter") ever matches a value in a breakpoint
|
||
registers, the CPU raises an exception and reports it to GDB.
|
||
|
||
Another possibility is when an emulator is in use; many emulators
|
||
include circuitry that watches the address lines coming out from the
|
||
processor, and force it to stop if the address matches a breakpoint's
|
||
address.
|
||
|
||
A third possibility is that the target already has the ability to do
|
||
breakpoints somehow; for instance, a ROM monitor may do its own
|
||
software breakpoints. So although these are not literally "hardware
|
||
breakpoints", from GDB's point of view they work the same; GDB need not
|
||
do anything more than set the breakpoint and wait for something to
|
||
happen.
|
||
|
||
Since they depend on hardware resources, hardware breakpoints may be
|
||
limited in number; when the user asks for more, GDB will start trying
|
||
to set software breakpoints. (On some architectures, notably the
|
||
32-bit x86 platforms, GDB cannot always know whether there's enough
|
||
hardware resources to insert all the hardware breakpoints and
|
||
watchpoints. On those platforms, GDB prints an error message only when
|
||
the program being debugged is continued.)
|
||
|
||
Software breakpoints require GDB to do somewhat more work. The
|
||
basic theory is that GDB will replace a program instruction with a
|
||
trap, illegal divide, or some other instruction that will cause an
|
||
exception, and then when it's encountered, GDB will take the exception
|
||
and stop the program. When the user says to continue, GDB will restore
|
||
the original instruction, single-step, re-insert the trap, and continue
|
||
on.
|
||
|
||
Since it literally overwrites the program being tested, the program
|
||
area must be writable, so this technique won't work on programs in ROM.
|
||
It can also distort the behavior of programs that examine themselves,
|
||
although such a situation would be highly unusual.
|
||
|
||
Also, the software breakpoint instruction should be the smallest
|
||
size of instruction, so it doesn't overwrite an instruction that might
|
||
be a jump target, and cause disaster when the program jumps into the
|
||
middle of the breakpoint instruction. (Strictly speaking, the
|
||
breakpoint must be no larger than the smallest interval between
|
||
instructions that may be jump targets; perhaps there is an architecture
|
||
where only even-numbered instructions may jumped to.) Note that it's
|
||
possible for an instruction set not to have any instructions usable for
|
||
a software breakpoint, although in practice only the ARC has failed to
|
||
define such an instruction.
|
||
|
||
Basic breakpoint object handling is in `breakpoint.c'. However,
|
||
much of the interesting breakpoint action is in `infrun.c'.
|
||
|
||
`target_remove_breakpoint (BP_TGT)'
|
||
`target_insert_breakpoint (BP_TGT)'
|
||
Insert or remove a software breakpoint at address
|
||
`BP_TGT->placed_address'. Returns zero for success, non-zero for
|
||
failure. On input, BP_TGT contains the address of the breakpoint,
|
||
and is otherwise initialized to zero. The fields of the `struct
|
||
bp_target_info' pointed to by BP_TGT are updated to contain other
|
||
information about the breakpoint on output. The field
|
||
`placed_address' may be updated if the breakpoint was placed at a
|
||
related address; the field `shadow_contents' contains the real
|
||
contents of the bytes where the breakpoint has been inserted, if
|
||
reading memory would return the breakpoint instead of the
|
||
underlying memory; the field `shadow_len' is the length of memory
|
||
cached in `shadow_contents', if any; and the field `placed_size'
|
||
is optionally set and used by the target, if it could differ from
|
||
`shadow_len'.
|
||
|
||
For example, the remote target `Z0' packet does not require
|
||
shadowing memory, so `shadow_len' is left at zero. However, the
|
||
length reported by `gdbarch_breakpoint_from_pc' is cached in
|
||
`placed_size', so that a matching `z0' packet can be used to
|
||
remove the breakpoint.
|
||
|
||
`target_remove_hw_breakpoint (BP_TGT)'
|
||
`target_insert_hw_breakpoint (BP_TGT)'
|
||
Insert or remove a hardware-assisted breakpoint at address
|
||
`BP_TGT->placed_address'. Returns zero for success, non-zero for
|
||
failure. See `target_insert_breakpoint' for a description of the
|
||
`struct bp_target_info' pointed to by BP_TGT; the
|
||
`shadow_contents' and `shadow_len' members are not used for
|
||
hardware breakpoints, but `placed_size' may be.
|
||
|
||
3.3 Single Stepping
|
||
===================
|
||
|
||
3.4 Stepping over runtime loader dynamic symbol resolution code
|
||
===============================================================
|
||
|
||
If the program uses ELF-style shared libraries, then calls to functions
|
||
in shared libraries go through stubs, which live in a table called the
|
||
PLT ("Procedure Linkage Table"). The first time the function is
|
||
called, the stub sends control to the dynamic linker, which looks up
|
||
the function's real address, patches the stub so that future calls will
|
||
go directly to the function, and then passes control to the function.
|
||
|
||
If we are stepping at the source level, we don't want to see any of
|
||
this -- we just want to skip over the stub and the dynamic linker. The
|
||
simple approach is to single-step until control leaves the dynamic
|
||
linker.
|
||
|
||
However, on some systems (e.g., Red Hat's 5.2 distribution) the
|
||
dynamic linker calls functions in the shared C library, so you can't
|
||
tell from the PC alone whether the dynamic linker is still running. In
|
||
this case, we use a step-resume breakpoint to get us past the dynamic
|
||
linker, as if we were using `next' to step over a function call.
|
||
|
||
The `in_solib_dynsym_resolve_code' function says whether we're in
|
||
the dynamic linker code or not. Normally, this means we single-step.
|
||
However, if `gdbarch_skip_solib_resolver' then returns non-zero, then
|
||
its value is an address where we can place a step-resume breakpoint to
|
||
get past the linker's symbol resolution function.
|
||
|
||
The `in_dynsym_resolve_code' hook of the `target_so_ops' vector can
|
||
generally be implemented in a pretty portable way, by comparing the PC
|
||
against the address ranges of the dynamic linker's sections.
|
||
|
||
The `gdbarch_skip_solib_resolver' implementation is generally going
|
||
to be system-specific, since it depends on internal details of the
|
||
dynamic linker. It's usually not too hard to figure out where to put a
|
||
breakpoint, but it certainly isn't portable.
|
||
`gdbarch_skip_solib_resolver' should do plenty of sanity checking. If
|
||
it can't figure things out, returning zero and getting the (possibly
|
||
confusing) stepping behavior is better than signaling an error, which
|
||
will obscure the change in the inferior's state. */
|
||
|
||
3.5 Signal Handling
|
||
===================
|
||
|
||
3.6 Thread Handling
|
||
===================
|
||
|
||
3.7 Inferior Function Calls
|
||
===========================
|
||
|
||
3.8 Longjmp Support
|
||
===================
|
||
|
||
GDB has support for figuring out that the target is doing a `longjmp'
|
||
and for stopping at the target of the jump, if we are stepping. This
|
||
is done with a few specialized internal breakpoints, which are visible
|
||
in the output of the `maint info breakpoint' command.
|
||
|
||
To make this work, you need to define a function called
|
||
`gdbarch_get_longjmp_target', which will examine the `jmp_buf'
|
||
structure and extract the `longjmp' target address. Since `jmp_buf' is
|
||
target specific and typically defined in a target header not available
|
||
to GDB, you will need to determine the offset of the PC manually and
|
||
return that; many targets define a `jb_pc_offset' field in the tdep
|
||
structure to save the value once calculated.
|
||
|
||
3.9 Watchpoints
|
||
===============
|
||
|
||
Watchpoints are a special kind of breakpoints (*note breakpoints:
|
||
Algorithms.) which break when data is accessed rather than when some
|
||
instruction is executed. When you have data which changes without your
|
||
knowing what code does that, watchpoints are the silver bullet to hunt
|
||
down and kill such bugs.
|
||
|
||
Watchpoints can be either hardware-assisted or not; the latter type
|
||
is known as "software watchpoints." GDB always uses hardware-assisted
|
||
watchpoints if they are available, and falls back on software
|
||
watchpoints otherwise. Typical situations where GDB will use software
|
||
watchpoints are:
|
||
|
||
* The watched memory region is too large for the underlying hardware
|
||
watchpoint support. For example, each x86 debug register can
|
||
watch up to 4 bytes of memory, so trying to watch data structures
|
||
whose size is more than 16 bytes will cause GDB to use software
|
||
watchpoints.
|
||
|
||
* The value of the expression to be watched depends on data held in
|
||
registers (as opposed to memory).
|
||
|
||
* Too many different watchpoints requested. (On some architectures,
|
||
this situation is impossible to detect until the debugged program
|
||
is resumed.) Note that x86 debug registers are used both for
|
||
hardware breakpoints and for watchpoints, so setting too many
|
||
hardware breakpoints might cause watchpoint insertion to fail.
|
||
|
||
* No hardware-assisted watchpoints provided by the target
|
||
implementation.
|
||
|
||
Software watchpoints are very slow, since GDB needs to single-step
|
||
the program being debugged and test the value of the watched
|
||
expression(s) after each instruction. The rest of this section is
|
||
mostly irrelevant for software watchpoints.
|
||
|
||
When the inferior stops, GDB tries to establish, among other
|
||
possible reasons, whether it stopped due to a watchpoint being hit. It
|
||
first uses `STOPPED_BY_WATCHPOINT' to see if any watchpoint was hit.
|
||
If not, all watchpoint checking is skipped.
|
||
|
||
Then GDB calls `target_stopped_data_address' exactly once. This
|
||
method returns the address of the watchpoint which triggered, if the
|
||
target can determine it. If the triggered address is available, GDB
|
||
compares the address returned by this method with each watched memory
|
||
address in each active watchpoint. For data-read and data-access
|
||
watchpoints, GDB announces every watchpoint that watches the triggered
|
||
address as being hit. For this reason, data-read and data-access
|
||
watchpoints _require_ that the triggered address be available; if not,
|
||
read and access watchpoints will never be considered hit. For
|
||
data-write watchpoints, if the triggered address is available, GDB
|
||
considers only those watchpoints which match that address; otherwise,
|
||
GDB considers all data-write watchpoints. For each data-write
|
||
watchpoint that GDB considers, it evaluates the expression whose value
|
||
is being watched, and tests whether the watched value has changed.
|
||
Watchpoints whose watched values have changed are announced as hit.
|
||
|
||
GDB uses several macros and primitives to support hardware
|
||
watchpoints:
|
||
|
||
`TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'
|
||
Return the number of hardware watchpoints of type TYPE that are
|
||
possible to be set. The value is positive if COUNT watchpoints of
|
||
this type can be set, zero if setting watchpoints of this type is
|
||
not supported, and negative if COUNT is more than the maximum
|
||
number of watchpoints of type TYPE that can be set. OTHER is
|
||
non-zero if other types of watchpoints are currently enabled (there
|
||
are architectures which cannot set watchpoints of different types
|
||
at the same time).
|
||
|
||
`TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'
|
||
Return non-zero if hardware watchpoints can be used to watch a
|
||
region whose address is ADDR and whose length in bytes is LEN.
|
||
|
||
`target_insert_watchpoint (ADDR, LEN, TYPE)'
|
||
`target_remove_watchpoint (ADDR, LEN, TYPE)'
|
||
Insert or remove a hardware watchpoint starting at ADDR, for LEN
|
||
bytes. TYPE is the watchpoint type, one of the possible values of
|
||
the enumerated data type `target_hw_bp_type', defined by
|
||
`breakpoint.h' as follows:
|
||
|
||
enum target_hw_bp_type
|
||
{
|
||
hw_write = 0, /* Common (write) HW watchpoint */
|
||
hw_read = 1, /* Read HW watchpoint */
|
||
hw_access = 2, /* Access (read or write) HW watchpoint */
|
||
hw_execute = 3 /* Execute HW breakpoint */
|
||
};
|
||
|
||
These two macros should return 0 for success, non-zero for failure.
|
||
|
||
`target_stopped_data_address (ADDR_P)'
|
||
If the inferior has some watchpoint that triggered, place the
|
||
address associated with the watchpoint at the location pointed to
|
||
by ADDR_P and return non-zero. Otherwise, return zero. This is
|
||
required for data-read and data-access watchpoints. It is not
|
||
required for data-write watchpoints, but GDB uses it to improve
|
||
handling of those also.
|
||
|
||
GDB will only call this method once per watchpoint stop,
|
||
immediately after calling `STOPPED_BY_WATCHPOINT'. If the
|
||
target's watchpoint indication is sticky, i.e., stays set after
|
||
resuming, this method should clear it. For instance, the x86 debug
|
||
control register has sticky triggered flags.
|
||
|
||
`target_watchpoint_addr_within_range (TARGET, ADDR, START, LENGTH)'
|
||
Check whether ADDR (as returned by `target_stopped_data_address')
|
||
lies within the hardware-defined watchpoint region described by
|
||
START and LENGTH. This only needs to be provided if the
|
||
granularity of a watchpoint is greater than one byte, i.e., if the
|
||
watchpoint can also trigger on nearby addresses outside of the
|
||
watched region.
|
||
|
||
`HAVE_STEPPABLE_WATCHPOINT'
|
||
If defined to a non-zero value, it is not necessary to disable a
|
||
watchpoint to step over it. Like
|
||
`gdbarch_have_nonsteppable_watchpoint', this is usually set when
|
||
watchpoints trigger at the instruction which will perform an
|
||
interesting read or write. It should be set if there is a
|
||
temporary disable bit which allows the processor to step over the
|
||
interesting instruction without raising the watchpoint exception
|
||
again.
|
||
|
||
`int gdbarch_have_nonsteppable_watchpoint (GDBARCH)'
|
||
If it returns a non-zero value, GDB should disable a watchpoint to
|
||
step the inferior over it. This is usually set when watchpoints
|
||
trigger at the instruction which will perform an interesting read
|
||
or write.
|
||
|
||
`HAVE_CONTINUABLE_WATCHPOINT'
|
||
If defined to a non-zero value, it is possible to continue the
|
||
inferior after a watchpoint has been hit. This is usually set
|
||
when watchpoints trigger at the instruction following an
|
||
interesting read or write.
|
||
|
||
`STOPPED_BY_WATCHPOINT (WAIT_STATUS)'
|
||
Return non-zero if stopped by a watchpoint. WAIT_STATUS is of the
|
||
type `struct target_waitstatus', defined by `target.h'. Normally,
|
||
this macro is defined to invoke the function pointed to by the
|
||
`to_stopped_by_watchpoint' member of the structure (of the type
|
||
`target_ops', defined on `target.h') that describes the
|
||
target-specific operations; `to_stopped_by_watchpoint' ignores the
|
||
WAIT_STATUS argument.
|
||
|
||
GDB does not require the non-zero value returned by
|
||
`STOPPED_BY_WATCHPOINT' to be 100% correct, so if a target cannot
|
||
determine for sure whether the inferior stopped due to a
|
||
watchpoint, it could return non-zero "just in case".
|
||
|
||
3.9.1 Watchpoints and Threads
|
||
-----------------------------
|
||
|
||
GDB only supports process-wide watchpoints, which trigger in all
|
||
threads. GDB uses the thread ID to make watchpoints act as if they
|
||
were thread-specific, but it cannot set hardware watchpoints that only
|
||
trigger in a specific thread. Therefore, even if the target supports
|
||
threads, per-thread debug registers, and watchpoints which only affect
|
||
a single thread, it should set the per-thread debug registers for all
|
||
threads to the same value. On GNU/Linux native targets, this is
|
||
accomplished by using `ALL_LWPS' in `target_insert_watchpoint' and
|
||
`target_remove_watchpoint' and by using `linux_set_new_thread' to
|
||
register a handler for newly created threads.
|
||
|
||
GDB's GNU/Linux support only reports a single event at a time,
|
||
although multiple events can trigger simultaneously for multi-threaded
|
||
programs. When multiple events occur, `linux-nat.c' queues subsequent
|
||
events and returns them the next time the program is resumed. This
|
||
means that `STOPPED_BY_WATCHPOINT' and `target_stopped_data_address'
|
||
only need to consult the current thread's state--the thread indicated
|
||
by `inferior_ptid'. If two threads have hit watchpoints
|
||
simultaneously, those routines will be called a second time for the
|
||
second thread.
|
||
|
||
3.9.2 x86 Watchpoints
|
||
---------------------
|
||
|
||
The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug
|
||
registers designed to facilitate debugging. GDB provides a generic
|
||
library of functions that x86-based ports can use to implement support
|
||
for watchpoints and hardware-assisted breakpoints. This subsection
|
||
documents the x86 watchpoint facilities in GDB.
|
||
|
||
(At present, the library functions read and write debug registers
|
||
directly, and are thus only available for native configurations.)
|
||
|
||
To use the generic x86 watchpoint support, a port should do the
|
||
following:
|
||
|
||
* Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the
|
||
target-dependent headers.
|
||
|
||
* Include the `config/i386/nm-i386.h' header file _after_ defining
|
||
`I386_USE_GENERIC_WATCHPOINTS'.
|
||
|
||
* Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'
|
||
(*note NATDEPFILES: Native Debugging.).
|
||
|
||
* Provide implementations for the `I386_DR_LOW_*' macros described
|
||
below. Typically, each macro should call a target-specific
|
||
function which does the real work.
|
||
|
||
The x86 watchpoint support works by maintaining mirror images of the
|
||
debug registers. Values are copied between the mirror images and the
|
||
real debug registers via a set of macros which each target needs to
|
||
provide:
|
||
|
||
`I386_DR_LOW_SET_CONTROL (VAL)'
|
||
Set the Debug Control (DR7) register to the value VAL.
|
||
|
||
`I386_DR_LOW_SET_ADDR (IDX, ADDR)'
|
||
Put the address ADDR into the debug register number IDX.
|
||
|
||
`I386_DR_LOW_RESET_ADDR (IDX)'
|
||
Reset (i.e. zero out) the address stored in the debug register
|
||
number IDX.
|
||
|
||
`I386_DR_LOW_GET_STATUS'
|
||
Return the value of the Debug Status (DR6) register. This value is
|
||
used immediately after it is returned by `I386_DR_LOW_GET_STATUS',
|
||
so as to support per-thread status register values.
|
||
|
||
For each one of the 4 debug registers (whose indices are from 0 to 3)
|
||
that store addresses, a reference count is maintained by GDB, to allow
|
||
sharing of debug registers by several watchpoints. This allows users
|
||
to define several watchpoints that watch the same expression, but with
|
||
different conditions and/or commands, without wasting debug registers
|
||
which are in short supply. GDB maintains the reference counts
|
||
internally, targets don't have to do anything to use this feature.
|
||
|
||
The x86 debug registers can each watch a region that is 1, 2, or 4
|
||
bytes long. The ia32 architecture requires that each watched region be
|
||
appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region
|
||
on 4-byte boundary. However, the x86 watchpoint support in GDB can
|
||
watch unaligned regions and regions larger than 4 bytes (up to 16
|
||
bytes) by allocating several debug registers to watch a single region.
|
||
This allocation of several registers per a watched region is also done
|
||
automatically without target code intervention.
|
||
|
||
The generic x86 watchpoint support provides the following API for the
|
||
GDB's application code:
|
||
|
||
`i386_region_ok_for_watchpoint (ADDR, LEN)'
|
||
The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this
|
||
function. It counts the number of debug registers required to
|
||
watch a given region, and returns a non-zero value if that number
|
||
is less than 4, the number of debug registers available to x86
|
||
processors.
|
||
|
||
`i386_stopped_data_address (ADDR_P)'
|
||
The target function `target_stopped_data_address' is set to call
|
||
this function. This function examines the breakpoint condition
|
||
bits in the DR6 Debug Status register, as returned by the
|
||
`I386_DR_LOW_GET_STATUS' macro, and returns the address associated
|
||
with the first bit that is set in DR6.
|
||
|
||
`i386_stopped_by_watchpoint (void)'
|
||
The macro `STOPPED_BY_WATCHPOINT' is set to call this function.
|
||
The argument passed to `STOPPED_BY_WATCHPOINT' is ignored. This
|
||
function examines the breakpoint condition bits in the DR6 Debug
|
||
Status register, as returned by the `I386_DR_LOW_GET_STATUS'
|
||
macro, and returns true if any bit is set. Otherwise, false is
|
||
returned.
|
||
|
||
`i386_insert_watchpoint (ADDR, LEN, TYPE)'
|
||
`i386_remove_watchpoint (ADDR, LEN, TYPE)'
|
||
Insert or remove a watchpoint. The macros
|
||
`target_insert_watchpoint' and `target_remove_watchpoint' are set
|
||
to call these functions. `i386_insert_watchpoint' first looks for
|
||
a debug register which is already set to watch the same region for
|
||
the same access types; if found, it just increments the reference
|
||
count of that debug register, thus implementing debug register
|
||
sharing between watchpoints. If no such register is found, the
|
||
function looks for a vacant debug register, sets its mirrored
|
||
value to ADDR, sets the mirrored value of DR7 Debug Control
|
||
register as appropriate for the LEN and TYPE parameters, and then
|
||
passes the new values of the debug register and DR7 to the
|
||
inferior by calling `I386_DR_LOW_SET_ADDR' and
|
||
`I386_DR_LOW_SET_CONTROL'. If more than one debug register is
|
||
required to cover the given region, the above process is repeated
|
||
for each debug register.
|
||
|
||
`i386_remove_watchpoint' does the opposite: it resets the address
|
||
in the mirrored value of the debug register and its read/write and
|
||
length bits in the mirrored value of DR7, then passes these new
|
||
values to the inferior via `I386_DR_LOW_RESET_ADDR' and
|
||
`I386_DR_LOW_SET_CONTROL'. If a register is shared by several
|
||
watchpoints, each time a `i386_remove_watchpoint' is called, it
|
||
decrements the reference count, and only calls
|
||
`I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the
|
||
count goes to zero.
|
||
|
||
`i386_insert_hw_breakpoint (BP_TGT)'
|
||
`i386_remove_hw_breakpoint (BP_TGT)'
|
||
These functions insert and remove hardware-assisted breakpoints.
|
||
The macros `target_insert_hw_breakpoint' and
|
||
`target_remove_hw_breakpoint' are set to call these functions.
|
||
The argument is a `struct bp_target_info *', as described in the
|
||
documentation for `target_insert_breakpoint'. These functions
|
||
work like `i386_insert_watchpoint' and `i386_remove_watchpoint',
|
||
respectively, except that they set up the debug registers to watch
|
||
instruction execution, and each hardware-assisted breakpoint
|
||
always requires exactly one debug register.
|
||
|
||
`i386_cleanup_dregs (void)'
|
||
This function clears all the reference counts, addresses, and
|
||
control bits in the mirror images of the debug registers. It
|
||
doesn't affect the actual debug registers in the inferior process.
|
||
|
||
*Notes:*
|
||
1. x86 processors support setting watchpoints on I/O reads or writes.
|
||
However, since no target supports this (as of March 2001), and
|
||
since `enum target_hw_bp_type' doesn't even have an enumeration
|
||
for I/O watchpoints, this feature is not yet available to GDB
|
||
running on x86.
|
||
|
||
2. x86 processors can enable watchpoints locally, for the current task
|
||
only, or globally, for all the tasks. For each debug register,
|
||
there's a bit in the DR7 Debug Control register that determines
|
||
whether the associated address is watched locally or globally. The
|
||
current implementation of x86 watchpoint support in GDB always
|
||
sets watchpoints to be locally enabled, since global watchpoints
|
||
might interfere with the underlying OS and are probably
|
||
unavailable in many platforms.
|
||
|
||
3.10 Checkpoints
|
||
================
|
||
|
||
In the abstract, a checkpoint is a point in the execution history of
|
||
the program, which the user may wish to return to at some later time.
|
||
|
||
Internally, a checkpoint is a saved copy of the program state,
|
||
including whatever information is required in order to restore the
|
||
program to that state at a later time. This can be expected to include
|
||
the state of registers and memory, and may include external state such
|
||
as the state of open files and devices.
|
||
|
||
There are a number of ways in which checkpoints may be implemented
|
||
in gdb, e.g. as corefiles, as forked processes, and as some opaque
|
||
method implemented on the target side.
|
||
|
||
A corefile can be used to save an image of target memory and register
|
||
state, which can in principle be restored later -- but corefiles do not
|
||
typically include information about external entities such as open
|
||
files. Currently this method is not implemented in gdb.
|
||
|
||
A forked process can save the state of user memory and registers, as
|
||
well as some subset of external (kernel) state. This method is used to
|
||
implement checkpoints on Linux, and in principle might be used on other
|
||
systems.
|
||
|
||
Some targets, e.g. simulators, might have their own built-in method
|
||
for saving checkpoints, and gdb might be able to take advantage of that
|
||
capability without necessarily knowing any details of how it is done.
|
||
|
||
3.11 Observing changes in GDB internals
|
||
=======================================
|
||
|
||
In order to function properly, several modules need to be notified when
|
||
some changes occur in the GDB internals. Traditionally, these modules
|
||
have relied on several paradigms, the most common ones being hooks and
|
||
gdb-events. Unfortunately, none of these paradigms was versatile
|
||
enough to become the standard notification mechanism in GDB. The fact
|
||
that they only supported one "client" was also a strong limitation.
|
||
|
||
A new paradigm, based on the Observer pattern of the `Design
|
||
Patterns' book, has therefore been implemented. The goal was to provide
|
||
a new interface overcoming the issues with the notification mechanisms
|
||
previously available. This new interface needed to be strongly typed,
|
||
easy to extend, and versatile enough to be used as the standard
|
||
interface when adding new notifications.
|
||
|
||
See *note GDB Observers:: for a brief description of the observers
|
||
currently implemented in GDB. The rationale for the current
|
||
implementation is also briefly discussed.
|
||
|
||
|
||
File: gdbint.info, Node: User Interface, Next: libgdb, Prev: Algorithms, Up: Top
|
||
|
||
4 User Interface
|
||
****************
|
||
|
||
GDB has several user interfaces, of which the traditional command-line
|
||
interface is perhaps the most familiar.
|
||
|
||
4.1 Command Interpreter
|
||
=======================
|
||
|
||
The command interpreter in GDB is fairly simple. It is designed to
|
||
allow for the set of commands to be augmented dynamically, and also has
|
||
a recursive subcommand capability, where the first argument to a
|
||
command may itself direct a lookup on a different command list.
|
||
|
||
For instance, the `set' command just starts a lookup on the
|
||
`setlist' command list, while `set thread' recurses to the
|
||
`set_thread_cmd_list'.
|
||
|
||
To add commands in general, use `add_cmd'. `add_com' adds to the
|
||
main command list, and should be used for those commands. The usual
|
||
place to add commands is in the `_initialize_XYZ' routines at the ends
|
||
of most source files.
|
||
|
||
To add paired `set' and `show' commands, use `add_setshow_cmd' or
|
||
`add_setshow_cmd_full'. The former is a slightly simpler interface
|
||
which is useful when you don't need to further modify the new command
|
||
structures, while the latter returns the new command structures for
|
||
manipulation.
|
||
|
||
Before removing commands from the command set it is a good idea to
|
||
deprecate them for some time. Use `deprecate_cmd' on commands or
|
||
aliases to set the deprecated flag. `deprecate_cmd' takes a `struct
|
||
cmd_list_element' as it's first argument. You can use the return value
|
||
from `add_com' or `add_cmd' to deprecate the command immediately after
|
||
it is created.
|
||
|
||
The first time a command is used the user will be warned and offered
|
||
a replacement (if one exists). Note that the replacement string passed
|
||
to `deprecate_cmd' should be the full name of the command, i.e., the
|
||
entire string the user should type at the command line.
|
||
|
||
4.2 UI-Independent Output--the `ui_out' Functions
|
||
=================================================
|
||
|
||
The `ui_out' functions present an abstraction level for the GDB output
|
||
code. They hide the specifics of different user interfaces supported
|
||
by GDB, and thus free the programmer from the need to write several
|
||
versions of the same code, one each for every UI, to produce output.
|
||
|
||
4.2.1 Overview and Terminology
|
||
------------------------------
|
||
|
||
In general, execution of each GDB command produces some sort of output,
|
||
and can even generate an input request.
|
||
|
||
Output can be generated for the following purposes:
|
||
|
||
* to display a _result_ of an operation;
|
||
|
||
* to convey _info_ or produce side-effects of a requested operation;
|
||
|
||
* to provide a _notification_ of an asynchronous event (including
|
||
progress indication of a prolonged asynchronous operation);
|
||
|
||
* to display _error messages_ (including warnings);
|
||
|
||
* to show _debug data_;
|
||
|
||
* to _query_ or prompt a user for input (a special case).
|
||
|
||
This section mainly concentrates on how to build result output,
|
||
although some of it also applies to other kinds of output.
|
||
|
||
Generation of output that displays the results of an operation
|
||
involves one or more of the following:
|
||
|
||
* output of the actual data
|
||
|
||
* formatting the output as appropriate for console output, to make it
|
||
easily readable by humans
|
||
|
||
* machine oriented formatting-a more terse formatting to allow for
|
||
easy parsing by programs which read GDB's output
|
||
|
||
* annotation, whose purpose is to help legacy GUIs to identify
|
||
interesting parts in the output
|
||
|
||
The `ui_out' routines take care of the first three aspects.
|
||
Annotations are provided by separate annotation routines. Note that use
|
||
of annotations for an interface between a GUI and GDB is deprecated.
|
||
|
||
Output can be in the form of a single item, which we call a "field";
|
||
a "list" consisting of identical fields; a "tuple" consisting of
|
||
non-identical fields; or a "table", which is a tuple consisting of a
|
||
header and a body. In a BNF-like form:
|
||
|
||
`<table> ==>'
|
||
`<header> <body>'
|
||
|
||
`<header> ==>'
|
||
`{ <column> }'
|
||
|
||
`<column> ==>'
|
||
`<width> <alignment> <title>'
|
||
|
||
`<body> ==>'
|
||
`{<row>}'
|
||
|
||
4.2.2 General Conventions
|
||
-------------------------
|
||
|
||
Most `ui_out' routines are of type `void', the exceptions are
|
||
`ui_out_stream_new' (which returns a pointer to the newly created
|
||
object) and the `make_cleanup' routines.
|
||
|
||
The first parameter is always the `ui_out' vector object, a pointer
|
||
to a `struct ui_out'.
|
||
|
||
The FORMAT parameter is like in `printf' family of functions. When
|
||
it is present, there must also be a variable list of arguments
|
||
sufficient used to satisfy the `%' specifiers in the supplied format.
|
||
|
||
When a character string argument is not used in a `ui_out' function
|
||
call, a `NULL' pointer has to be supplied instead.
|
||
|
||
4.2.3 Table, Tuple and List Functions
|
||
-------------------------------------
|
||
|
||
This section introduces `ui_out' routines for building lists, tuples
|
||
and tables. The routines to output the actual data items (fields) are
|
||
presented in the next section.
|
||
|
||
To recap: A "tuple" is a sequence of "fields", each field containing
|
||
information about an object; a "list" is a sequence of fields where
|
||
each field describes an identical object.
|
||
|
||
Use the "table" functions when your output consists of a list of
|
||
rows (tuples) and the console output should include a heading. Use this
|
||
even when you are listing just one object but you still want the header.
|
||
|
||
Tables can not be nested. Tuples and lists can be nested up to a
|
||
maximum of five levels.
|
||
|
||
The overall structure of the table output code is something like
|
||
this:
|
||
|
||
ui_out_table_begin
|
||
ui_out_table_header
|
||
...
|
||
ui_out_table_body
|
||
ui_out_tuple_begin
|
||
ui_out_field_*
|
||
...
|
||
ui_out_tuple_end
|
||
...
|
||
ui_out_table_end
|
||
|
||
Here is the description of table-, tuple- and list-related `ui_out'
|
||
functions:
|
||
|
||
-- Function: void ui_out_table_begin (struct ui_out *UIOUT, int
|
||
NBROFCOLS, int NR_ROWS, const char *TBLID)
|
||
The function `ui_out_table_begin' marks the beginning of the output
|
||
of a table. It should always be called before any other `ui_out'
|
||
function for a given table. NBROFCOLS is the number of columns in
|
||
the table. NR_ROWS is the number of rows in the table. TBLID is
|
||
an optional string identifying the table. The string pointed to
|
||
by TBLID is copied by the implementation of `ui_out_table_begin',
|
||
so the application can free the string if it was `malloc'ed.
|
||
|
||
The companion function `ui_out_table_end', described below, marks
|
||
the end of the table's output.
|
||
|
||
-- Function: void ui_out_table_header (struct ui_out *UIOUT, int
|
||
WIDTH, enum ui_align ALIGNMENT, const char *COLHDR)
|
||
`ui_out_table_header' provides the header information for a single
|
||
table column. You call this function several times, one each for
|
||
every column of the table, after `ui_out_table_begin', but before
|
||
`ui_out_table_body'.
|
||
|
||
The value of WIDTH gives the column width in characters. The
|
||
value of ALIGNMENT is one of `left', `center', and `right', and it
|
||
specifies how to align the header: left-justify, center, or
|
||
right-justify it. COLHDR points to a string that specifies the
|
||
column header; the implementation copies that string, so column
|
||
header strings in `malloc'ed storage can be freed after the call.
|
||
|
||
-- Function: void ui_out_table_body (struct ui_out *UIOUT)
|
||
This function delimits the table header from the table body.
|
||
|
||
-- Function: void ui_out_table_end (struct ui_out *UIOUT)
|
||
This function signals the end of a table's output. It should be
|
||
called after the table body has been produced by the list and
|
||
field output functions.
|
||
|
||
There should be exactly one call to `ui_out_table_end' for each
|
||
call to `ui_out_table_begin', otherwise the `ui_out' functions
|
||
will signal an internal error.
|
||
|
||
The output of the tuples that represent the table rows must follow
|
||
the call to `ui_out_table_body' and precede the call to
|
||
`ui_out_table_end'. You build a tuple by calling `ui_out_tuple_begin'
|
||
and `ui_out_tuple_end', with suitable calls to functions which actually
|
||
output fields between them.
|
||
|
||
-- Function: void ui_out_tuple_begin (struct ui_out *UIOUT, const char
|
||
*ID)
|
||
This function marks the beginning of a tuple output. ID points to
|
||
an optional string that identifies the tuple; it is copied by the
|
||
implementation, and so strings in `malloc'ed storage can be freed
|
||
after the call.
|
||
|
||
-- Function: void ui_out_tuple_end (struct ui_out *UIOUT)
|
||
This function signals an end of a tuple output. There should be
|
||
exactly one call to `ui_out_tuple_end' for each call to
|
||
`ui_out_tuple_begin', otherwise an internal GDB error will be
|
||
signaled.
|
||
|
||
-- Function: struct cleanup * make_cleanup_ui_out_tuple_begin_end
|
||
(struct ui_out *UIOUT, const char *ID)
|
||
This function first opens the tuple and then establishes a cleanup
|
||
(*note Cleanups: Misc Guidelines.) to close the tuple. It
|
||
provides a convenient and correct implementation of the
|
||
non-portable(1) code sequence:
|
||
struct cleanup *old_cleanup;
|
||
ui_out_tuple_begin (uiout, "...");
|
||
old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
|
||
uiout);
|
||
|
||
-- Function: void ui_out_list_begin (struct ui_out *UIOUT, const char
|
||
*ID)
|
||
This function marks the beginning of a list output. ID points to
|
||
an optional string that identifies the list; it is copied by the
|
||
implementation, and so strings in `malloc'ed storage can be freed
|
||
after the call.
|
||
|
||
-- Function: void ui_out_list_end (struct ui_out *UIOUT)
|
||
This function signals an end of a list output. There should be
|
||
exactly one call to `ui_out_list_end' for each call to
|
||
`ui_out_list_begin', otherwise an internal GDB error will be
|
||
signaled.
|
||
|
||
-- Function: struct cleanup * make_cleanup_ui_out_list_begin_end
|
||
(struct ui_out *UIOUT, const char *ID)
|
||
Similar to `make_cleanup_ui_out_tuple_begin_end', this function
|
||
opens a list and then establishes cleanup (*note Cleanups: Misc
|
||
Guidelines.) that will close the list.
|
||
|
||
4.2.4 Item Output Functions
|
||
---------------------------
|
||
|
||
The functions described below produce output for the actual data items,
|
||
or fields, which contain information about the object.
|
||
|
||
Choose the appropriate function accordingly to your particular needs.
|
||
|
||
-- Function: void ui_out_field_fmt (struct ui_out *UIOUT, char
|
||
*FLDNAME, char *FORMAT, ...)
|
||
This is the most general output function. It produces the
|
||
representation of the data in the variable-length argument list
|
||
according to formatting specifications in FORMAT, a `printf'-like
|
||
format string. The optional argument FLDNAME supplies the name of
|
||
the field. The data items themselves are supplied as additional
|
||
arguments after FORMAT.
|
||
|
||
This generic function should be used only when it is not possible
|
||
to use one of the specialized versions (see below).
|
||
|
||
-- Function: void ui_out_field_int (struct ui_out *UIOUT, const char
|
||
*FLDNAME, int VALUE)
|
||
This function outputs a value of an `int' variable. It uses the
|
||
`"%d"' output conversion specification. FLDNAME specifies the
|
||
name of the field.
|
||
|
||
-- Function: void ui_out_field_fmt_int (struct ui_out *UIOUT, int
|
||
WIDTH, enum ui_align ALIGNMENT, const char *FLDNAME, int
|
||
VALUE)
|
||
This function outputs a value of an `int' variable. It differs
|
||
from `ui_out_field_int' in that the caller specifies the desired
|
||
WIDTH and ALIGNMENT of the output. FLDNAME specifies the name of
|
||
the field.
|
||
|
||
-- Function: void ui_out_field_core_addr (struct ui_out *UIOUT, const
|
||
char *FLDNAME, struct gdbarch *GDBARCH, CORE_ADDR ADDRESS)
|
||
This function outputs an address as appropriate for GDBARCH.
|
||
|
||
-- Function: void ui_out_field_string (struct ui_out *UIOUT, const
|
||
char *FLDNAME, const char *STRING)
|
||
This function outputs a string using the `"%s"' conversion
|
||
specification.
|
||
|
||
Sometimes, there's a need to compose your output piece by piece using
|
||
functions that operate on a stream, such as `value_print' or
|
||
`fprintf_symbol_filtered'. These functions accept an argument of the
|
||
type `struct ui_file *', a pointer to a `ui_file' object used to store
|
||
the data stream used for the output. When you use one of these
|
||
functions, you need a way to pass their results stored in a `ui_file'
|
||
object to the `ui_out' functions. To this end, you first create a
|
||
`ui_stream' object by calling `ui_out_stream_new', pass the `stream'
|
||
member of that `ui_stream' object to `value_print' and similar
|
||
functions, and finally call `ui_out_field_stream' to output the field
|
||
you constructed. When the `ui_stream' object is no longer needed, you
|
||
should destroy it and free its memory by calling `ui_out_stream_delete'.
|
||
|
||
-- Function: struct ui_stream * ui_out_stream_new (struct ui_out
|
||
*UIOUT)
|
||
This function creates a new `ui_stream' object which uses the same
|
||
output methods as the `ui_out' object whose pointer is passed in
|
||
UIOUT. It returns a pointer to the newly created `ui_stream'
|
||
object.
|
||
|
||
-- Function: void ui_out_stream_delete (struct ui_stream *STREAMBUF)
|
||
This functions destroys a `ui_stream' object specified by
|
||
STREAMBUF.
|
||
|
||
-- Function: void ui_out_field_stream (struct ui_out *UIOUT, const
|
||
char *FIELDNAME, struct ui_stream *STREAMBUF)
|
||
This function consumes all the data accumulated in
|
||
`streambuf->stream' and outputs it like `ui_out_field_string'
|
||
does. After a call to `ui_out_field_stream', the accumulated data
|
||
no longer exists, but the stream is still valid and may be used
|
||
for producing more fields.
|
||
|
||
*Important:* If there is any chance that your code could bail out
|
||
before completing output generation and reaching the point where
|
||
`ui_out_stream_delete' is called, it is necessary to set up a cleanup,
|
||
to avoid leaking memory and other resources. Here's a skeleton code to
|
||
do that:
|
||
|
||
struct ui_stream *mybuf = ui_out_stream_new (uiout);
|
||
struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
|
||
...
|
||
do_cleanups (old);
|
||
|
||
If the function already has the old cleanup chain set (for other
|
||
kinds of cleanups), you just have to add your cleanup to it:
|
||
|
||
mybuf = ui_out_stream_new (uiout);
|
||
make_cleanup (ui_out_stream_delete, mybuf);
|
||
|
||
Note that with cleanups in place, you should not call
|
||
`ui_out_stream_delete' directly, or you would attempt to free the same
|
||
buffer twice.
|
||
|
||
4.2.5 Utility Output Functions
|
||
------------------------------
|
||
|
||
-- Function: void ui_out_field_skip (struct ui_out *UIOUT, const char
|
||
*FLDNAME)
|
||
This function skips a field in a table. Use it if you have to
|
||
leave an empty field without disrupting the table alignment. The
|
||
argument FLDNAME specifies a name for the (missing) filed.
|
||
|
||
-- Function: void ui_out_text (struct ui_out *UIOUT, const char
|
||
*STRING)
|
||
This function outputs the text in STRING in a way that makes it
|
||
easy to be read by humans. For example, the console
|
||
implementation of this method filters the text through a built-in
|
||
pager, to prevent it from scrolling off the visible portion of the
|
||
screen.
|
||
|
||
Use this function for printing relatively long chunks of text
|
||
around the actual field data: the text it produces is not aligned
|
||
according to the table's format. Use `ui_out_field_string' to
|
||
output a string field, and use `ui_out_message', described below,
|
||
to output short messages.
|
||
|
||
-- Function: void ui_out_spaces (struct ui_out *UIOUT, int NSPACES)
|
||
This function outputs NSPACES spaces. It is handy to align the
|
||
text produced by `ui_out_text' with the rest of the table or list.
|
||
|
||
-- Function: void ui_out_message (struct ui_out *UIOUT, int VERBOSITY,
|
||
const char *FORMAT, ...)
|
||
This function produces a formatted message, provided that the
|
||
current verbosity level is at least as large as given by
|
||
VERBOSITY. The current verbosity level is specified by the user
|
||
with the `set verbositylevel' command.(2)
|
||
|
||
-- Function: void ui_out_wrap_hint (struct ui_out *UIOUT, char *INDENT)
|
||
This function gives the console output filter (a paging filter) a
|
||
hint of where to break lines which are too long. Ignored for all
|
||
other output consumers. INDENT, if non-`NULL', is the string to
|
||
be printed to indent the wrapped text on the next line; it must
|
||
remain accessible until the next call to `ui_out_wrap_hint', or
|
||
until an explicit newline is produced by one of the other
|
||
functions. If INDENT is `NULL', the wrapped text will not be
|
||
indented.
|
||
|
||
-- Function: void ui_out_flush (struct ui_out *UIOUT)
|
||
This function flushes whatever output has been accumulated so far,
|
||
if the UI buffers output.
|
||
|
||
4.2.6 Examples of Use of `ui_out' functions
|
||
-------------------------------------------
|
||
|
||
This section gives some practical examples of using the `ui_out'
|
||
functions to generalize the old console-oriented code in GDB. The
|
||
examples all come from functions defined on the `breakpoints.c' file.
|
||
|
||
This example, from the `breakpoint_1' function, shows how to produce
|
||
a table.
|
||
|
||
The original code was:
|
||
|
||
if (!found_a_breakpoint++)
|
||
{
|
||
annotate_breakpoints_headers ();
|
||
|
||
annotate_field (0);
|
||
printf_filtered ("Num ");
|
||
annotate_field (1);
|
||
printf_filtered ("Type ");
|
||
annotate_field (2);
|
||
printf_filtered ("Disp ");
|
||
annotate_field (3);
|
||
printf_filtered ("Enb ");
|
||
if (addressprint)
|
||
{
|
||
annotate_field (4);
|
||
printf_filtered ("Address ");
|
||
}
|
||
annotate_field (5);
|
||
printf_filtered ("What\n");
|
||
|
||
annotate_breakpoints_table ();
|
||
}
|
||
|
||
Here's the new version:
|
||
|
||
nr_printable_breakpoints = ...;
|
||
|
||
if (addressprint)
|
||
ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
|
||
else
|
||
ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
|
||
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_breakpoints_headers ();
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_field (0);
|
||
ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_field (1);
|
||
ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_field (2);
|
||
ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_field (3);
|
||
ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
|
||
if (addressprint)
|
||
{
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_field (4);
|
||
if (print_address_bits <= 32)
|
||
ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
|
||
else
|
||
ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
|
||
}
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_field (5);
|
||
ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
|
||
ui_out_table_body (uiout);
|
||
if (nr_printable_breakpoints > 0)
|
||
annotate_breakpoints_table ();
|
||
|
||
This example, from the `print_one_breakpoint' function, shows how to
|
||
produce the actual data for the table whose structure was defined in
|
||
the above example. The original code was:
|
||
|
||
annotate_record ();
|
||
annotate_field (0);
|
||
printf_filtered ("%-3d ", b->number);
|
||
annotate_field (1);
|
||
if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
|
||
|| ((int) b->type != bptypes[(int) b->type].type))
|
||
internal_error ("bptypes table does not describe type #%d.",
|
||
(int)b->type);
|
||
printf_filtered ("%-14s ", bptypes[(int)b->type].description);
|
||
annotate_field (2);
|
||
printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
|
||
annotate_field (3);
|
||
printf_filtered ("%-3c ", bpenables[(int)b->enable]);
|
||
...
|
||
|
||
This is the new version:
|
||
|
||
annotate_record ();
|
||
ui_out_tuple_begin (uiout, "bkpt");
|
||
annotate_field (0);
|
||
ui_out_field_int (uiout, "number", b->number);
|
||
annotate_field (1);
|
||
if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
|
||
|| ((int) b->type != bptypes[(int) b->type].type))
|
||
internal_error ("bptypes table does not describe type #%d.",
|
||
(int) b->type);
|
||
ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
|
||
annotate_field (2);
|
||
ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
|
||
annotate_field (3);
|
||
ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
|
||
...
|
||
|
||
This example, also from `print_one_breakpoint', shows how to produce
|
||
a complicated output field using the `print_expression' functions which
|
||
requires a stream to be passed. It also shows how to automate stream
|
||
destruction with cleanups. The original code was:
|
||
|
||
annotate_field (5);
|
||
print_expression (b->exp, gdb_stdout);
|
||
|
||
The new version is:
|
||
|
||
struct ui_stream *stb = ui_out_stream_new (uiout);
|
||
struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
|
||
...
|
||
annotate_field (5);
|
||
print_expression (b->exp, stb->stream);
|
||
ui_out_field_stream (uiout, "what", local_stream);
|
||
|
||
This example, also from `print_one_breakpoint', shows how to use
|
||
`ui_out_text' and `ui_out_field_string'. The original code was:
|
||
|
||
annotate_field (5);
|
||
if (b->dll_pathname == NULL)
|
||
printf_filtered ("<any library> ");
|
||
else
|
||
printf_filtered ("library \"%s\" ", b->dll_pathname);
|
||
|
||
It became:
|
||
|
||
annotate_field (5);
|
||
if (b->dll_pathname == NULL)
|
||
{
|
||
ui_out_field_string (uiout, "what", "<any library>");
|
||
ui_out_spaces (uiout, 1);
|
||
}
|
||
else
|
||
{
|
||
ui_out_text (uiout, "library \"");
|
||
ui_out_field_string (uiout, "what", b->dll_pathname);
|
||
ui_out_text (uiout, "\" ");
|
||
}
|
||
|
||
The following example from `print_one_breakpoint' shows how to use
|
||
`ui_out_field_int' and `ui_out_spaces'. The original code was:
|
||
|
||
annotate_field (5);
|
||
if (b->forked_inferior_pid != 0)
|
||
printf_filtered ("process %d ", b->forked_inferior_pid);
|
||
|
||
It became:
|
||
|
||
annotate_field (5);
|
||
if (b->forked_inferior_pid != 0)
|
||
{
|
||
ui_out_text (uiout, "process ");
|
||
ui_out_field_int (uiout, "what", b->forked_inferior_pid);
|
||
ui_out_spaces (uiout, 1);
|
||
}
|
||
|
||
Here's an example of using `ui_out_field_string'. The original code
|
||
was:
|
||
|
||
annotate_field (5);
|
||
if (b->exec_pathname != NULL)
|
||
printf_filtered ("program \"%s\" ", b->exec_pathname);
|
||
|
||
It became:
|
||
|
||
annotate_field (5);
|
||
if (b->exec_pathname != NULL)
|
||
{
|
||
ui_out_text (uiout, "program \"");
|
||
ui_out_field_string (uiout, "what", b->exec_pathname);
|
||
ui_out_text (uiout, "\" ");
|
||
}
|
||
|
||
Finally, here's an example of printing an address. The original
|
||
code:
|
||
|
||
annotate_field (4);
|
||
printf_filtered ("%s ",
|
||
hex_string_custom ((unsigned long) b->address, 8));
|
||
|
||
It became:
|
||
|
||
annotate_field (4);
|
||
ui_out_field_core_addr (uiout, "Address", b->address);
|
||
|
||
4.3 Console Printing
|
||
====================
|
||
|
||
4.4 TUI
|
||
=======
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) The function cast is not portable ISO C.
|
||
|
||
(2) As of this writing (April 2001), setting verbosity level is not
|
||
yet implemented, and is always returned as zero. So calling
|
||
`ui_out_message' with a VERBOSITY argument more than zero will cause
|
||
the message to never be printed.
|
||
|
||
|
||
File: gdbint.info, Node: libgdb, Next: Values, Prev: User Interface, Up: Top
|
||
|
||
5 libgdb
|
||
********
|
||
|
||
5.1 libgdb 1.0
|
||
==============
|
||
|
||
`libgdb' 1.0 was an abortive project of years ago. The theory was to
|
||
provide an API to GDB's functionality.
|
||
|
||
5.2 libgdb 2.0
|
||
==============
|
||
|
||
`libgdb' 2.0 is an ongoing effort to update GDB so that is better able
|
||
to support graphical and other environments.
|
||
|
||
Since `libgdb' development is on-going, its architecture is still
|
||
evolving. The following components have so far been identified:
|
||
|
||
* Observer - `gdb-events.h'.
|
||
|
||
* Builder - `ui-out.h'
|
||
|
||
* Event Loop - `event-loop.h'
|
||
|
||
* Library - `gdb.h'
|
||
|
||
The model that ties these components together is described below.
|
||
|
||
5.3 The `libgdb' Model
|
||
======================
|
||
|
||
A client of `libgdb' interacts with the library in two ways.
|
||
|
||
* As an observer (using `gdb-events') receiving notifications from
|
||
`libgdb' of any internal state changes (break point changes, run
|
||
state, etc).
|
||
|
||
* As a client querying `libgdb' (using the `ui-out' builder) to
|
||
obtain various status values from GDB.
|
||
|
||
Since `libgdb' could have multiple clients (e.g., a GUI supporting
|
||
the existing GDB CLI), those clients must co-operate when controlling
|
||
`libgdb'. In particular, a client must ensure that `libgdb' is idle
|
||
(i.e. no other client is using `libgdb') before responding to a
|
||
`gdb-event' by making a query.
|
||
|
||
5.4 CLI support
|
||
===============
|
||
|
||
At present GDB's CLI is very much entangled in with the core of
|
||
`libgdb'. Consequently, a client wishing to include the CLI in their
|
||
interface needs to carefully co-ordinate its own and the CLI's
|
||
requirements.
|
||
|
||
It is suggested that the client set `libgdb' up to be bi-modal
|
||
(alternate between CLI and client query modes). The notes below sketch
|
||
out the theory:
|
||
|
||
* The client registers itself as an observer of `libgdb'.
|
||
|
||
* The client create and install `cli-out' builder using its own
|
||
versions of the `ui-file' `gdb_stderr', `gdb_stdtarg' and
|
||
`gdb_stdout' streams.
|
||
|
||
* The client creates a separate custom `ui-out' builder that is only
|
||
used while making direct queries to `libgdb'.
|
||
|
||
When the client receives input intended for the CLI, it simply
|
||
passes it along. Since the `cli-out' builder is installed by default,
|
||
all the CLI output in response to that command is routed (pronounced
|
||
rooted) through to the client controlled `gdb_stdout' et. al. streams.
|
||
At the same time, the client is kept abreast of internal changes by
|
||
virtue of being a `libgdb' observer.
|
||
|
||
The only restriction on the client is that it must wait until
|
||
`libgdb' becomes idle before initiating any queries (using the client's
|
||
custom builder).
|
||
|
||
5.5 `libgdb' components
|
||
=======================
|
||
|
||
Observer - `gdb-events.h'
|
||
-------------------------
|
||
|
||
`gdb-events' provides the client with a very raw mechanism that can be
|
||
used to implement an observer. At present it only allows for one
|
||
observer and that observer must, internally, handle the need to delay
|
||
the processing of any event notifications until after `libgdb' has
|
||
finished the current command.
|
||
|
||
Builder - `ui-out.h'
|
||
--------------------
|
||
|
||
`ui-out' provides the infrastructure necessary for a client to create a
|
||
builder. That builder is then passed down to `libgdb' when doing any
|
||
queries.
|
||
|
||
Event Loop - `event-loop.h'
|
||
---------------------------
|
||
|
||
`event-loop', currently non-re-entrant, provides a simple event loop.
|
||
A client would need to either plug its self into this loop or,
|
||
implement a new event-loop that GDB would use.
|
||
|
||
The event-loop will eventually be made re-entrant. This is so that
|
||
GDB can better handle the problem of some commands blocking instead of
|
||
returning.
|
||
|
||
Library - `gdb.h'
|
||
-----------------
|
||
|
||
`libgdb' is the most obvious component of this system. It provides the
|
||
query interface. Each function is parameterized by a `ui-out' builder.
|
||
The result of the query is constructed using that builder before the
|
||
query function returns.
|
||
|
||
|
||
File: gdbint.info, Node: Values, Next: Stack Frames, Prev: libgdb, Up: Top
|
||
|
||
6 Values
|
||
********
|
||
|
||
6.1 Values
|
||
==========
|
||
|
||
GDB uses `struct value', or "values", as an internal abstraction for
|
||
the representation of a variety of inferior objects and GDB convenience
|
||
objects.
|
||
|
||
Values have an associated `struct type', that describes a virtual
|
||
view of the raw data or object stored in or accessed through the value.
|
||
|
||
A value is in addition discriminated by its lvalue-ness, given its
|
||
`enum lval_type' enumeration type:
|
||
|
||
``not_lval''
|
||
This value is not an lval. It can't be assigned to.
|
||
|
||
``lval_memory''
|
||
This value represents an object in memory.
|
||
|
||
``lval_register''
|
||
This value represents an object that lives in a register.
|
||
|
||
``lval_internalvar''
|
||
Represents the value of an internal variable.
|
||
|
||
``lval_internalvar_component''
|
||
Represents part of a GDB internal variable. E.g., a structure
|
||
field.
|
||
|
||
``lval_computed''
|
||
These are "computed" values. They allow creating specialized value
|
||
objects for specific purposes, all abstracted away from the core
|
||
value support code. The creator of such a value writes specialized
|
||
functions to handle the reading and writing to/from the value's
|
||
backend data, and optionally, a "copy operator" and a "destructor".
|
||
|
||
Pointers to these functions are stored in a `struct lval_funcs'
|
||
instance (declared in `value.h'), and passed to the
|
||
`allocate_computed_value' function, as in the example below.
|
||
|
||
static void
|
||
nil_value_read (struct value *v)
|
||
{
|
||
/* This callback reads data from some backend, and stores it in V.
|
||
In this case, we always read null data. You'll want to fill in
|
||
something more interesting. */
|
||
|
||
memset (value_contents_all_raw (v),
|
||
value_offset (v),
|
||
TYPE_LENGTH (value_type (v)));
|
||
}
|
||
|
||
static void
|
||
nil_value_write (struct value *v, struct value *fromval)
|
||
{
|
||
/* Takes the data from FROMVAL and stores it in the backend of V. */
|
||
|
||
to_oblivion (value_contents_all_raw (fromval),
|
||
value_offset (v),
|
||
TYPE_LENGTH (value_type (fromval)));
|
||
}
|
||
|
||
static struct lval_funcs nil_value_funcs =
|
||
{
|
||
nil_value_read,
|
||
nil_value_write
|
||
};
|
||
|
||
struct value *
|
||
make_nil_value (void)
|
||
{
|
||
struct type *type;
|
||
struct value *v;
|
||
|
||
type = make_nils_type ();
|
||
v = allocate_computed_value (type, &nil_value_funcs, NULL);
|
||
|
||
return v;
|
||
}
|
||
|
||
See the implementation of the `$_siginfo' convenience variable in
|
||
`infrun.c' as a real example use of lval_computed.
|
||
|
||
|
||
|
||
File: gdbint.info, Node: Stack Frames, Next: Symbol Handling, Prev: Values, Up: Top
|
||
|
||
7 Stack Frames
|
||
**************
|
||
|
||
A frame is a construct that GDB uses to keep track of calling and
|
||
called functions.
|
||
|
||
GDB's frame model, a fresh design, was implemented with the need to
|
||
support DWARF's Call Frame Information in mind. In fact, the term
|
||
"unwind" is taken directly from that specification. Developers wishing
|
||
to learn more about unwinders, are encouraged to read the DWARF
|
||
specification, available from `http://www.dwarfstd.org'.
|
||
|
||
GDB's model is that you find a frame's registers by "unwinding" them
|
||
from the next younger frame. That is, `get_frame_register' which
|
||
returns the value of a register in frame #1 (the next-to-youngest
|
||
frame), is implemented by calling frame #0's `frame_register_unwind'
|
||
(the youngest frame). But then the obvious question is: how do you
|
||
access the registers of the youngest frame itself?
|
||
|
||
To answer this question, GDB has the "sentinel" frame, the "-1st"
|
||
frame. Unwinding registers from the sentinel frame gives you the
|
||
current values of the youngest real frame's registers. If F is a
|
||
sentinel frame, then `get_frame_type (F) == SENTINEL_FRAME'.
|
||
|
||
7.1 Selecting an Unwinder
|
||
=========================
|
||
|
||
The architecture registers a list of frame unwinders (`struct
|
||
frame_unwind'), using the functions `frame_unwind_prepend_unwinder' and
|
||
`frame_unwind_append_unwinder'. Each unwinder includes a sniffer.
|
||
Whenever GDB needs to unwind a frame (to fetch the previous frame's
|
||
registers or the current frame's ID), it calls registered sniffers in
|
||
order to find one which recognizes the frame. The first time a sniffer
|
||
returns non-zero, the corresponding unwinder is assigned to the frame.
|
||
|
||
7.2 Unwinding the Frame ID
|
||
==========================
|
||
|
||
Every frame has an associated ID, of type `struct frame_id'. The ID
|
||
includes the stack base and function start address for the frame. The
|
||
ID persists through the entire life of the frame, including while other
|
||
called frames are running; it is used to locate an appropriate `struct
|
||
frame_info' from the cache.
|
||
|
||
Every time the inferior stops, and at various other times, the frame
|
||
cache is flushed. Because of this, parts of GDB which need to keep
|
||
track of individual frames cannot use pointers to `struct frame_info'.
|
||
A frame ID provides a stable reference to a frame, even when the
|
||
unwinder must be run again to generate a new `struct frame_info' for
|
||
the same frame.
|
||
|
||
The frame's unwinder's `this_id' method is called to find the ID.
|
||
Note that this is different from register unwinding, where the next
|
||
frame's `prev_register' is called to unwind this frame's registers.
|
||
|
||
Both stack base and function address are required to identify the
|
||
frame, because a recursive function has the same function address for
|
||
two consecutive frames and a leaf function may have the same stack
|
||
address as its caller. On some platforms, a third address is part of
|
||
the ID to further disambiguate frames--for instance, on IA-64 the
|
||
separate register stack address is included in the ID.
|
||
|
||
An invalid frame ID (`outer_frame_id') returned from the `this_id'
|
||
method means to stop unwinding after this frame.
|
||
|
||
`null_frame_id' is another invalid frame ID which should be used
|
||
when there is no frame. For instance, certain breakpoints are attached
|
||
to a specific frame, and that frame is identified through its frame ID
|
||
(we use this to implement the "finish" command). Using `null_frame_id'
|
||
as the frame ID for a given breakpoint means that the breakpoint is not
|
||
specific to any frame. The `this_id' method should never return
|
||
`null_frame_id'.
|
||
|
||
7.3 Unwinding Registers
|
||
=======================
|
||
|
||
Each unwinder includes a `prev_register' method. This method takes a
|
||
frame, an associated cache pointer, and a register number. It returns
|
||
a `struct value *' describing the requested register, as saved by this
|
||
frame. This is the value of the register that is current in this
|
||
frame's caller.
|
||
|
||
The returned value must have the same type as the register. It may
|
||
have any lvalue type. In most circumstances one of these routines will
|
||
generate the appropriate value:
|
||
|
||
`frame_unwind_got_optimized'
|
||
This register was not saved.
|
||
|
||
`frame_unwind_got_register'
|
||
This register was copied into another register in this frame. This
|
||
is also used for unchanged registers; they are "copied" into the
|
||
same register.
|
||
|
||
`frame_unwind_got_memory'
|
||
This register was saved in memory.
|
||
|
||
`frame_unwind_got_constant'
|
||
This register was not saved, but the unwinder can compute the
|
||
previous value some other way.
|
||
|
||
`frame_unwind_got_address'
|
||
Same as `frame_unwind_got_constant', except that the value is a
|
||
target address. This is frequently used for the stack pointer,
|
||
which is not explicitly saved but has a known offset from this
|
||
frame's stack pointer. For architectures with a flat unified
|
||
address space, this is generally the same as
|
||
`frame_unwind_got_constant'.
|
||
|
||
|
||
File: gdbint.info, Node: Symbol Handling, Next: Language Support, Prev: Stack Frames, Up: Top
|
||
|
||
8 Symbol Handling
|
||
*****************
|
||
|
||
Symbols are a key part of GDB's operation. Symbols include variables,
|
||
functions, and types.
|
||
|
||
Symbol information for a large program can be truly massive, and
|
||
reading of symbol information is one of the major performance
|
||
bottlenecks in GDB; it can take many minutes to process it all.
|
||
Studies have shown that nearly all the time spent is computational,
|
||
rather than file reading.
|
||
|
||
One of the ways for GDB to provide a good user experience is to
|
||
start up quickly, taking no more than a few seconds. It is simply not
|
||
possible to process all of a program's debugging info in that time, and
|
||
so we attempt to handle symbols incrementally. For instance, we create
|
||
"partial symbol tables" consisting of only selected symbols, and only
|
||
expand them to full symbol tables when necessary.
|
||
|
||
8.1 Symbol Reading
|
||
==================
|
||
|
||
GDB reads symbols from "symbol files". The usual symbol file is the
|
||
file containing the program which GDB is debugging. GDB can be
|
||
directed to use a different file for symbols (with the `symbol-file'
|
||
command), and it can also read more symbols via the `add-file' and
|
||
`load' commands. In addition, it may bring in more symbols while
|
||
loading shared libraries.
|
||
|
||
Symbol files are initially opened by code in `symfile.c' using the
|
||
BFD library (*note Support Libraries::). BFD identifies the type of
|
||
the file by examining its header. `find_sym_fns' then uses this
|
||
identification to locate a set of symbol-reading functions.
|
||
|
||
Symbol-reading modules identify themselves to GDB by calling
|
||
`add_symtab_fns' during their module initialization. The argument to
|
||
`add_symtab_fns' is a `struct sym_fns' which contains the name (or name
|
||
prefix) of the symbol format, the length of the prefix, and pointers to
|
||
four functions. These functions are called at various times to process
|
||
symbol files whose identification matches the specified prefix.
|
||
|
||
The functions supplied by each module are:
|
||
|
||
`XYZ_symfile_init(struct sym_fns *sf)'
|
||
Called from `symbol_file_add' when we are about to read a new
|
||
symbol file. This function should clean up any internal state
|
||
(possibly resulting from half-read previous files, for example)
|
||
and prepare to read a new symbol file. Note that the symbol file
|
||
which we are reading might be a new "main" symbol file, or might
|
||
be a secondary symbol file whose symbols are being added to the
|
||
existing symbol table.
|
||
|
||
The argument to `XYZ_symfile_init' is a newly allocated `struct
|
||
sym_fns' whose `bfd' field contains the BFD for the new symbol
|
||
file being read. Its `private' field has been zeroed, and can be
|
||
modified as desired. Typically, a struct of private information
|
||
will be `malloc''d, and a pointer to it will be placed in the
|
||
`private' field.
|
||
|
||
There is no result from `XYZ_symfile_init', but it can call
|
||
`error' if it detects an unavoidable problem.
|
||
|
||
`XYZ_new_init()'
|
||
Called from `symbol_file_add' when discarding existing symbols.
|
||
This function needs only handle the symbol-reading module's
|
||
internal state; the symbol table data structures visible to the
|
||
rest of GDB will be discarded by `symbol_file_add'. It has no
|
||
arguments and no result. It may be called after
|
||
`XYZ_symfile_init', if a new symbol table is being read, or may be
|
||
called alone if all symbols are simply being discarded.
|
||
|
||
`XYZ_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)'
|
||
Called from `symbol_file_add' to actually read the symbols from a
|
||
symbol-file into a set of psymtabs or symtabs.
|
||
|
||
`sf' points to the `struct sym_fns' originally passed to
|
||
`XYZ_sym_init' for possible initialization. `addr' is the offset
|
||
between the file's specified start address and its true address in
|
||
memory. `mainline' is 1 if this is the main symbol table being
|
||
read, and 0 if a secondary symbol file (e.g., shared library or
|
||
dynamically loaded file) is being read.
|
||
|
||
In addition, if a symbol-reading module creates psymtabs when
|
||
XYZ_symfile_read is called, these psymtabs will contain a pointer to a
|
||
function `XYZ_psymtab_to_symtab', which can be called from any point in
|
||
the GDB symbol-handling code.
|
||
|
||
`XYZ_psymtab_to_symtab (struct partial_symtab *pst)'
|
||
Called from `psymtab_to_symtab' (or the `PSYMTAB_TO_SYMTAB' macro)
|
||
if the psymtab has not already been read in and had its
|
||
`pst->symtab' pointer set. The argument is the psymtab to be
|
||
fleshed-out into a symtab. Upon return, `pst->readin' should have
|
||
been set to 1, and `pst->symtab' should contain a pointer to the
|
||
new corresponding symtab, or zero if there were no symbols in that
|
||
part of the symbol file.
|
||
|
||
8.2 Partial Symbol Tables
|
||
=========================
|
||
|
||
GDB has three types of symbol tables:
|
||
|
||
* Full symbol tables ("symtabs"). These contain the main
|
||
information about symbols and addresses.
|
||
|
||
* Partial symbol tables ("psymtabs"). These contain enough
|
||
information to know when to read the corresponding part of the full
|
||
symbol table.
|
||
|
||
* Minimal symbol tables ("msymtabs"). These contain information
|
||
gleaned from non-debugging symbols.
|
||
|
||
This section describes partial symbol tables.
|
||
|
||
A psymtab is constructed by doing a very quick pass over an
|
||
executable file's debugging information. Small amounts of information
|
||
are extracted--enough to identify which parts of the symbol table will
|
||
need to be re-read and fully digested later, when the user needs the
|
||
information. The speed of this pass causes GDB to start up very
|
||
quickly. Later, as the detailed rereading occurs, it occurs in small
|
||
pieces, at various times, and the delay therefrom is mostly invisible to
|
||
the user.
|
||
|
||
The symbols that show up in a file's psymtab should be, roughly,
|
||
those visible to the debugger's user when the program is not running
|
||
code from that file. These include external symbols and types, static
|
||
symbols and types, and `enum' values declared at file scope.
|
||
|
||
The psymtab also contains the range of instruction addresses that the
|
||
full symbol table would represent.
|
||
|
||
The idea is that there are only two ways for the user (or much of the
|
||
code in the debugger) to reference a symbol:
|
||
|
||
* By its address (e.g., execution stops at some address which is
|
||
inside a function in this file). The address will be noticed to
|
||
be in the range of this psymtab, and the full symtab will be read
|
||
in. `find_pc_function', `find_pc_line', and other `find_pc_...'
|
||
functions handle this.
|
||
|
||
* By its name (e.g., the user asks to print a variable, or set a
|
||
breakpoint on a function). Global names and file-scope names will
|
||
be found in the psymtab, which will cause the symtab to be pulled
|
||
in. Local names will have to be qualified by a global name, or a
|
||
file-scope name, in which case we will have already read in the
|
||
symtab as we evaluated the qualifier. Or, a local symbol can be
|
||
referenced when we are "in" a local scope, in which case the first
|
||
case applies. `lookup_symbol' does most of the work here.
|
||
|
||
The only reason that psymtabs exist is to cause a symtab to be read
|
||
in at the right moment. Any symbol that can be elided from a psymtab,
|
||
while still causing that to happen, should not appear in it. Since
|
||
psymtabs don't have the idea of scope, you can't put local symbols in
|
||
them anyway. Psymtabs don't have the idea of the type of a symbol,
|
||
either, so types need not appear, unless they will be referenced by
|
||
name.
|
||
|
||
It is a bug for GDB to behave one way when only a psymtab has been
|
||
read, and another way if the corresponding symtab has been read in.
|
||
Such bugs are typically caused by a psymtab that does not contain all
|
||
the visible symbols, or which has the wrong instruction address ranges.
|
||
|
||
The psymtab for a particular section of a symbol file (objfile)
|
||
could be thrown away after the symtab has been read in. The symtab
|
||
should always be searched before the psymtab, so the psymtab will never
|
||
be used (in a bug-free environment). Currently, psymtabs are allocated
|
||
on an obstack, and all the psymbols themselves are allocated in a pair
|
||
of large arrays on an obstack, so there is little to be gained by
|
||
trying to free them unless you want to do a lot more work.
|
||
|
||
Whether or not psymtabs are created depends on the objfile's symbol
|
||
reader. The core of GDB hides the details of partial symbols and
|
||
partial symbol tables behind a set of function pointers known as the
|
||
"quick symbol functions". These are documented in `symfile.h'.
|
||
|
||
8.3 Types
|
||
=========
|
||
|
||
Fundamental Types (e.g., `FT_VOID', `FT_BOOLEAN').
|
||
--------------------------------------------------
|
||
|
||
These are the fundamental types that GDB uses internally. Fundamental
|
||
types from the various debugging formats (stabs, ELF, etc) are mapped
|
||
into one of these. They are basically a union of all fundamental types
|
||
that GDB knows about for all the languages that GDB knows about.
|
||
|
||
Type Codes (e.g., `TYPE_CODE_PTR', `TYPE_CODE_ARRAY').
|
||
------------------------------------------------------
|
||
|
||
Each time GDB builds an internal type, it marks it with one of these
|
||
types. The type may be a fundamental type, such as `TYPE_CODE_INT', or
|
||
a derived type, such as `TYPE_CODE_PTR' which is a pointer to another
|
||
type. Typically, several `FT_*' types map to one `TYPE_CODE_*' type,
|
||
and are distinguished by other members of the type struct, such as
|
||
whether the type is signed or unsigned, and how many bits it uses.
|
||
|
||
Builtin Types (e.g., `builtin_type_void', `builtin_type_char').
|
||
---------------------------------------------------------------
|
||
|
||
These are instances of type structs that roughly correspond to
|
||
fundamental types and are created as global types for GDB to use for
|
||
various ugly historical reasons. We eventually want to eliminate
|
||
these. Note for example that `builtin_type_int' initialized in
|
||
`gdbtypes.c' is basically the same as a `TYPE_CODE_INT' type that is
|
||
initialized in `c-lang.c' for an `FT_INTEGER' fundamental type. The
|
||
difference is that the `builtin_type' is not associated with any
|
||
particular objfile, and only one instance exists, while `c-lang.c'
|
||
builds as many `TYPE_CODE_INT' types as needed, with each one
|
||
associated with some particular objfile.
|
||
|
||
8.4 Object File Formats
|
||
=======================
|
||
|
||
8.4.1 a.out
|
||
-----------
|
||
|
||
The `a.out' format is the original file format for Unix. It consists
|
||
of three sections: `text', `data', and `bss', which are for program
|
||
code, initialized data, and uninitialized data, respectively.
|
||
|
||
The `a.out' format is so simple that it doesn't have any reserved
|
||
place for debugging information. (Hey, the original Unix hackers used
|
||
`adb', which is a machine-language debugger!) The only debugging
|
||
format for `a.out' is stabs, which is encoded as a set of normal
|
||
symbols with distinctive attributes.
|
||
|
||
The basic `a.out' reader is in `dbxread.c'.
|
||
|
||
8.4.2 COFF
|
||
----------
|
||
|
||
The COFF format was introduced with System V Release 3 (SVR3) Unix.
|
||
COFF files may have multiple sections, each prefixed by a header. The
|
||
number of sections is limited.
|
||
|
||
The COFF specification includes support for debugging. Although this
|
||
was a step forward, the debugging information was woefully limited.
|
||
For instance, it was not possible to represent code that came from an
|
||
included file. GNU's COFF-using configs often use stabs-type info,
|
||
encapsulated in special sections.
|
||
|
||
The COFF reader is in `coffread.c'.
|
||
|
||
8.4.3 ECOFF
|
||
-----------
|
||
|
||
ECOFF is an extended COFF originally introduced for Mips and Alpha
|
||
workstations.
|
||
|
||
The basic ECOFF reader is in `mipsread.c'.
|
||
|
||
8.4.4 XCOFF
|
||
-----------
|
||
|
||
The IBM RS/6000 running AIX uses an object file format called XCOFF.
|
||
The COFF sections, symbols, and line numbers are used, but debugging
|
||
symbols are `dbx'-style stabs whose strings are located in the `.debug'
|
||
section (rather than the string table). For more information, see
|
||
*note Top: (stabs)Top.
|
||
|
||
The shared library scheme has a clean interface for figuring out what
|
||
shared libraries are in use, but the catch is that everything which
|
||
refers to addresses (symbol tables and breakpoints at least) needs to be
|
||
relocated for both shared libraries and the main executable. At least
|
||
using the standard mechanism this can only be done once the program has
|
||
been run (or the core file has been read).
|
||
|
||
8.4.5 PE
|
||
--------
|
||
|
||
Windows 95 and NT use the PE ("Portable Executable") format for their
|
||
executables. PE is basically COFF with additional headers.
|
||
|
||
While BFD includes special PE support, GDB needs only the basic COFF
|
||
reader.
|
||
|
||
8.4.6 ELF
|
||
---------
|
||
|
||
The ELF format came with System V Release 4 (SVR4) Unix. ELF is
|
||
similar to COFF in being organized into a number of sections, but it
|
||
removes many of COFF's limitations. Debugging info may be either stabs
|
||
encapsulated in ELF sections, or more commonly these days, DWARF.
|
||
|
||
The basic ELF reader is in `elfread.c'.
|
||
|
||
8.4.7 SOM
|
||
---------
|
||
|
||
SOM is HP's object file and debug format (not to be confused with IBM's
|
||
SOM, which is a cross-language ABI).
|
||
|
||
The SOM reader is in `somread.c'.
|
||
|
||
8.5 Debugging File Formats
|
||
==========================
|
||
|
||
This section describes characteristics of debugging information that
|
||
are independent of the object file format.
|
||
|
||
8.5.1 stabs
|
||
-----------
|
||
|
||
`stabs' started out as special symbols within the `a.out' format.
|
||
Since then, it has been encapsulated into other file formats, such as
|
||
COFF and ELF.
|
||
|
||
While `dbxread.c' does some of the basic stab processing, including
|
||
for encapsulated versions, `stabsread.c' does the real work.
|
||
|
||
8.5.2 COFF
|
||
----------
|
||
|
||
The basic COFF definition includes debugging information. The level of
|
||
support is minimal and non-extensible, and is not often used.
|
||
|
||
8.5.3 Mips debug (Third Eye)
|
||
----------------------------
|
||
|
||
ECOFF includes a definition of a special debug format.
|
||
|
||
The file `mdebugread.c' implements reading for this format.
|
||
|
||
8.5.4 DWARF 2
|
||
-------------
|
||
|
||
DWARF 2 is an improved but incompatible version of DWARF 1.
|
||
|
||
The DWARF 2 reader is in `dwarf2read.c'.
|
||
|
||
8.5.5 Compressed DWARF 2
|
||
------------------------
|
||
|
||
Compressed DWARF 2 is not technically a separate debugging format, but
|
||
merely DWARF 2 debug information that has been compressed. In this
|
||
format, every object-file section holding DWARF 2 debugging information
|
||
is compressed and prepended with a header. (The section is also
|
||
typically renamed, so a section called `.debug_info' in a DWARF 2
|
||
binary would be called `.zdebug_info' in a compressed DWARF 2 binary.)
|
||
The header is 12 bytes long:
|
||
|
||
* 4 bytes: the literal string "ZLIB"
|
||
|
||
* 8 bytes: the uncompressed size of the section, in big-endian byte
|
||
order.
|
||
|
||
The same reader is used for both compressed an normal DWARF 2 info.
|
||
Section decompression is done in `zlib_decompress_section' in
|
||
`dwarf2read.c'.
|
||
|
||
8.5.6 DWARF 3
|
||
-------------
|
||
|
||
DWARF 3 is an improved version of DWARF 2.
|
||
|
||
8.5.7 SOM
|
||
---------
|
||
|
||
Like COFF, the SOM definition includes debugging information.
|
||
|
||
8.6 Adding a New Symbol Reader to GDB
|
||
=====================================
|
||
|
||
If you are using an existing object file format (`a.out', COFF, ELF,
|
||
etc), there is probably little to be done.
|
||
|
||
If you need to add a new object file format, you must first add it to
|
||
BFD. This is beyond the scope of this document.
|
||
|
||
You must then arrange for the BFD code to provide access to the
|
||
debugging symbols. Generally GDB will have to call swapping routines
|
||
from BFD and a few other BFD internal routines to locate the debugging
|
||
information. As much as possible, GDB should not depend on the BFD
|
||
internal data structures.
|
||
|
||
For some targets (e.g., COFF), there is a special transfer vector
|
||
used to call swapping routines, since the external data structures on
|
||
various platforms have different sizes and layouts. Specialized
|
||
routines that will only ever be implemented by one object file format
|
||
may be called directly. This interface should be described in a file
|
||
`bfd/libXYZ.h', which is included by GDB.
|
||
|
||
8.7 Memory Management for Symbol Files
|
||
======================================
|
||
|
||
Most memory associated with a loaded symbol file is stored on its
|
||
`objfile_obstack'. This includes symbols, types, namespace data, and
|
||
other information produced by the symbol readers.
|
||
|
||
Because this data lives on the objfile's obstack, it is automatically
|
||
released when the objfile is unloaded or reloaded. Therefore one
|
||
objfile must not reference symbol or type data from another objfile;
|
||
they could be unloaded at different times.
|
||
|
||
User convenience variables, et cetera, have associated types.
|
||
Normally these types live in the associated objfile. However, when the
|
||
objfile is unloaded, those types are deep copied to global memory, so
|
||
that the values of the user variables and history items are not lost.
|
||
|
||
|
||
File: gdbint.info, Node: Language Support, Next: Host Definition, Prev: Symbol Handling, Up: Top
|
||
|
||
9 Language Support
|
||
******************
|
||
|
||
GDB's language support is mainly driven by the symbol reader, although
|
||
it is possible for the user to set the source language manually.
|
||
|
||
GDB chooses the source language by looking at the extension of the
|
||
file recorded in the debug info; `.c' means C, `.f' means Fortran, etc.
|
||
It may also use a special-purpose language identifier if the debug
|
||
format supports it, like with DWARF.
|
||
|
||
9.1 Adding a Source Language to GDB
|
||
===================================
|
||
|
||
To add other languages to GDB's expression parser, follow the following
|
||
steps:
|
||
|
||
_Create the expression parser._
|
||
This should reside in a file `LANG-exp.y'. Routines for building
|
||
parsed expressions into a `union exp_element' list are in
|
||
`parse.c'.
|
||
|
||
Since we can't depend upon everyone having Bison, and YACC produces
|
||
parsers that define a bunch of global names, the following lines
|
||
*must* be included at the top of the YACC parser, to prevent the
|
||
various parsers from defining the same global names:
|
||
|
||
#define yyparse LANG_parse
|
||
#define yylex LANG_lex
|
||
#define yyerror LANG_error
|
||
#define yylval LANG_lval
|
||
#define yychar LANG_char
|
||
#define yydebug LANG_debug
|
||
#define yypact LANG_pact
|
||
#define yyr1 LANG_r1
|
||
#define yyr2 LANG_r2
|
||
#define yydef LANG_def
|
||
#define yychk LANG_chk
|
||
#define yypgo LANG_pgo
|
||
#define yyact LANG_act
|
||
#define yyexca LANG_exca
|
||
#define yyerrflag LANG_errflag
|
||
#define yynerrs LANG_nerrs
|
||
|
||
At the bottom of your parser, define a `struct language_defn' and
|
||
initialize it with the right values for your language. Define an
|
||
`initialize_LANG' routine and have it call
|
||
`add_language(LANG_language_defn)' to tell the rest of GDB that
|
||
your language exists. You'll need some other supporting variables
|
||
and functions, which will be used via pointers from your
|
||
`LANG_language_defn'. See the declaration of `struct
|
||
language_defn' in `language.h', and the other `*-exp.y' files, for
|
||
more information.
|
||
|
||
_Add any evaluation routines, if necessary_
|
||
If you need new opcodes (that represent the operations of the
|
||
language), add them to the enumerated type in `expression.h'. Add
|
||
support code for these operations in the `evaluate_subexp' function
|
||
defined in the file `eval.c'. Add cases for new opcodes in two
|
||
functions from `parse.c': `prefixify_subexp' and
|
||
`length_of_subexp'. These compute the number of `exp_element's
|
||
that a given operation takes up.
|
||
|
||
_Update some existing code_
|
||
Add an enumerated identifier for your language to the enumerated
|
||
type `enum language' in `defs.h'.
|
||
|
||
Update the routines in `language.c' so your language is included.
|
||
These routines include type predicates and such, which (in some
|
||
cases) are language dependent. If your language does not appear
|
||
in the switch statement, an error is reported.
|
||
|
||
Also included in `language.c' is the code that updates the variable
|
||
`current_language', and the routines that translate the
|
||
`language_LANG' enumerated identifier into a printable string.
|
||
|
||
Update the function `_initialize_language' to include your
|
||
language. This function picks the default language upon startup,
|
||
so is dependent upon which languages that GDB is built for.
|
||
|
||
Update `allocate_symtab' in `symfile.c' and/or symbol-reading code
|
||
so that the language of each symtab (source file) is set properly.
|
||
This is used to determine the language to use at each stack frame
|
||
level. Currently, the language is set based upon the extension of
|
||
the source file. If the language can be better inferred from the
|
||
symbol information, please set the language of the symtab in the
|
||
symbol-reading code.
|
||
|
||
Add helper code to `print_subexp' (in `expprint.c') to handle any
|
||
new expression opcodes you have added to `expression.h'. Also,
|
||
add the printed representations of your operators to
|
||
`op_print_tab'.
|
||
|
||
_Add a place of call_
|
||
Add a call to `LANG_parse()' and `LANG_error' in `parse_exp_1'
|
||
(defined in `parse.c').
|
||
|
||
_Edit `Makefile.in'_
|
||
Add dependencies in `Makefile.in'. Make sure you update the macro
|
||
variables such as `HFILES' and `OBJS', otherwise your code may not
|
||
get linked in, or, worse yet, it may not get `tar'red into the
|
||
distribution!
|
||
|
||
|
||
File: gdbint.info, Node: Host Definition, Next: Target Architecture Definition, Prev: Language Support, Up: Top
|
||
|
||
10 Host Definition
|
||
******************
|
||
|
||
With the advent of Autoconf, it's rarely necessary to have host
|
||
definition machinery anymore. The following information is provided,
|
||
mainly, as an historical reference.
|
||
|
||
10.1 Adding a New Host
|
||
======================
|
||
|
||
GDB's host configuration support normally happens via Autoconf. New
|
||
host-specific definitions should not be needed. Older hosts GDB still
|
||
use the host-specific definitions and files listed below, but these
|
||
mostly exist for historical reasons, and will eventually disappear.
|
||
|
||
`gdb/config/ARCH/XYZ.mh'
|
||
This file is a Makefile fragment that once contained both host and
|
||
native configuration information (*note Native Debugging::) for the
|
||
machine XYZ. The host configuration information is now handled by
|
||
Autoconf.
|
||
|
||
Host configuration information included definitions for `CC',
|
||
`SYSV_DEFINE', `XM_CFLAGS', `XM_ADD_FILES', `XM_CLIBS',
|
||
`XM_CDEPS', etc.; see `Makefile.in'.
|
||
|
||
New host-only configurations do not need this file.
|
||
|
||
|
||
(Files named `gdb/config/ARCH/xm-XYZ.h' were once used to define
|
||
host-specific macros, but were no longer needed and have all been
|
||
removed.)
|
||
|
||
Generic Host Support Files
|
||
--------------------------
|
||
|
||
There are some "generic" versions of routines that can be used by
|
||
various systems.
|
||
|
||
`ser-unix.c'
|
||
This contains serial line support for Unix systems. It is
|
||
included by default on all Unix-like hosts.
|
||
|
||
`ser-pipe.c'
|
||
This contains serial pipe support for Unix systems. It is
|
||
included by default on all Unix-like hosts.
|
||
|
||
`ser-mingw.c'
|
||
This contains serial line support for 32-bit programs running under
|
||
Windows using MinGW.
|
||
|
||
`ser-go32.c'
|
||
This contains serial line support for 32-bit programs running
|
||
under DOS, using the DJGPP (a.k.a. GO32) execution environment.
|
||
|
||
`ser-tcp.c'
|
||
This contains generic TCP support using sockets. It is included by
|
||
default on all Unix-like hosts and with MinGW.
|
||
|
||
10.2 Host Conditionals
|
||
======================
|
||
|
||
When GDB is configured and compiled, various macros are defined or left
|
||
undefined, to control compilation based on the attributes of the host
|
||
system. While formerly they could be set in host-specific header
|
||
files, at present they can be changed only by setting `CFLAGS' when
|
||
building, or by editing the source code.
|
||
|
||
These macros and their meanings (or if the meaning is not documented
|
||
here, then one of the source files where they are used is indicated)
|
||
are:
|
||
|
||
`GDBINIT_FILENAME'
|
||
The default name of GDB's initialization file (normally
|
||
`.gdbinit').
|
||
|
||
`CRLF_SOURCE_FILES'
|
||
Define this if host files use `\r\n' rather than `\n' as a line
|
||
terminator. This will cause source file listings to omit `\r'
|
||
characters when printing and it will allow `\r\n' line endings of
|
||
files which are "sourced" by gdb. It must be possible to open
|
||
files in binary mode using `O_BINARY' or, for fopen, `"rb"'.
|
||
|
||
`DEFAULT_PROMPT'
|
||
The default value of the prompt string (normally `"(gdb) "').
|
||
|
||
`DEV_TTY'
|
||
The name of the generic TTY device, defaults to `"/dev/tty"'.
|
||
|
||
`ISATTY'
|
||
Substitute for isatty, if not available.
|
||
|
||
`FOPEN_RB'
|
||
Define this if binary files are opened the same way as text files.
|
||
|
||
`PRINTF_HAS_LONG_LONG'
|
||
Define this if the host can handle printing of long long integers
|
||
via the printf format conversion specifier `ll'. This is set by
|
||
the `configure' script.
|
||
|
||
`LSEEK_NOT_LINEAR'
|
||
Define this if `lseek (n)' does not necessarily move to byte number
|
||
`n' in the file. This is only used when reading source files. It
|
||
is normally faster to define `CRLF_SOURCE_FILES' when possible.
|
||
|
||
`lint'
|
||
Define this to help placate `lint' in some situations.
|
||
|
||
`volatile'
|
||
Define this to override the defaults of `__volatile__' or `/**/'.
|
||
|
||
|
||
File: gdbint.info, Node: Target Architecture Definition, Next: Target Descriptions, Prev: Host Definition, Up: Top
|
||
|
||
11 Target Architecture Definition
|
||
*********************************
|
||
|
||
GDB's target architecture defines what sort of machine-language
|
||
programs GDB can work with, and how it works with them.
|
||
|
||
The target architecture object is implemented as the C structure
|
||
`struct gdbarch *'. The structure, and its methods, are generated
|
||
using the Bourne shell script `gdbarch.sh'.
|
||
|
||
* Menu:
|
||
|
||
* OS ABI Variant Handling::
|
||
* Initialize New Architecture::
|
||
* Registers and Memory::
|
||
* Pointers and Addresses::
|
||
* Address Classes::
|
||
* Register Representation::
|
||
* Frame Interpretation::
|
||
* Inferior Call Setup::
|
||
* Adding support for debugging core files::
|
||
* Defining Other Architecture Features::
|
||
* Adding a New Target::
|
||
|
||
|
||
File: gdbint.info, Node: OS ABI Variant Handling, Next: Initialize New Architecture, Up: Target Architecture Definition
|
||
|
||
11.1 Operating System ABI Variant Handling
|
||
==========================================
|
||
|
||
GDB provides a mechanism for handling variations in OS ABIs. An OS ABI
|
||
variant may have influence over any number of variables in the target
|
||
architecture definition. There are two major components in the OS ABI
|
||
mechanism: sniffers and handlers.
|
||
|
||
A "sniffer" examines a file matching a BFD architecture/flavour pair
|
||
(the architecture may be wildcarded) in an attempt to determine the OS
|
||
ABI of that file. Sniffers with a wildcarded architecture are
|
||
considered to be "generic", while sniffers for a specific architecture
|
||
are considered to be "specific". A match from a specific sniffer
|
||
overrides a match from a generic sniffer. Multiple sniffers for an
|
||
architecture/flavour may exist, in order to differentiate between two
|
||
different operating systems which use the same basic file format. The
|
||
OS ABI framework provides a generic sniffer for ELF-format files which
|
||
examines the `EI_OSABI' field of the ELF header, as well as note
|
||
sections known to be used by several operating systems.
|
||
|
||
A "handler" is used to fine-tune the `gdbarch' structure for the
|
||
selected OS ABI. There may be only one handler for a given OS ABI for
|
||
each BFD architecture.
|
||
|
||
The following OS ABI variants are defined in `defs.h':
|
||
|
||
`GDB_OSABI_UNINITIALIZED'
|
||
Used for struct gdbarch_info if ABI is still uninitialized.
|
||
|
||
`GDB_OSABI_UNKNOWN'
|
||
The ABI of the inferior is unknown. The default `gdbarch'
|
||
settings for the architecture will be used.
|
||
|
||
`GDB_OSABI_SVR4'
|
||
UNIX System V Release 4.
|
||
|
||
`GDB_OSABI_HURD'
|
||
GNU using the Hurd kernel.
|
||
|
||
`GDB_OSABI_SOLARIS'
|
||
Sun Solaris.
|
||
|
||
`GDB_OSABI_OSF1'
|
||
OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
|
||
|
||
`GDB_OSABI_LINUX'
|
||
GNU using the Linux kernel.
|
||
|
||
`GDB_OSABI_FREEBSD_AOUT'
|
||
FreeBSD using the `a.out' executable format.
|
||
|
||
`GDB_OSABI_FREEBSD_ELF'
|
||
FreeBSD using the ELF executable format.
|
||
|
||
`GDB_OSABI_NETBSD_AOUT'
|
||
NetBSD using the `a.out' executable format.
|
||
|
||
`GDB_OSABI_NETBSD_ELF'
|
||
NetBSD using the ELF executable format.
|
||
|
||
`GDB_OSABI_OPENBSD_ELF'
|
||
OpenBSD using the ELF executable format.
|
||
|
||
`GDB_OSABI_WINCE'
|
||
Windows CE.
|
||
|
||
`GDB_OSABI_GO32'
|
||
DJGPP.
|
||
|
||
`GDB_OSABI_IRIX'
|
||
Irix.
|
||
|
||
`GDB_OSABI_INTERIX'
|
||
Interix (Posix layer for MS-Windows systems).
|
||
|
||
`GDB_OSABI_HPUX_ELF'
|
||
HP/UX using the ELF executable format.
|
||
|
||
`GDB_OSABI_HPUX_SOM'
|
||
HP/UX using the SOM executable format.
|
||
|
||
`GDB_OSABI_QNXNTO'
|
||
QNX Neutrino.
|
||
|
||
`GDB_OSABI_CYGWIN'
|
||
Cygwin.
|
||
|
||
`GDB_OSABI_AIX'
|
||
AIX.
|
||
|
||
|
||
Here are the functions that make up the OS ABI framework:
|
||
|
||
-- Function: const char * gdbarch_osabi_name (enum gdb_osabi OSABI)
|
||
Return the name of the OS ABI corresponding to OSABI.
|
||
|
||
-- Function: void gdbarch_register_osabi (enum bfd_architecture ARCH,
|
||
unsigned long MACHINE, enum gdb_osabi OSABI, void
|
||
(*INIT_OSABI)(struct gdbarch_info INFO, struct gdbarch
|
||
*GDBARCH))
|
||
Register the OS ABI handler specified by INIT_OSABI for the
|
||
architecture, machine type and OS ABI specified by ARCH, MACHINE
|
||
and OSABI. In most cases, a value of zero for the machine type,
|
||
which implies the architecture's default machine type, will
|
||
suffice.
|
||
|
||
-- Function: void gdbarch_register_osabi_sniffer (enum
|
||
bfd_architecture ARCH, enum bfd_flavour FLAVOUR, enum
|
||
gdb_osabi (*SNIFFER)(bfd *ABFD))
|
||
Register the OS ABI file sniffer specified by SNIFFER for the BFD
|
||
architecture/flavour pair specified by ARCH and FLAVOUR. If ARCH
|
||
is `bfd_arch_unknown', the sniffer is considered to be generic,
|
||
and is allowed to examine FLAVOUR-flavoured files for any
|
||
architecture.
|
||
|
||
-- Function: enum gdb_osabi gdbarch_lookup_osabi (bfd *ABFD)
|
||
Examine the file described by ABFD to determine its OS ABI. The
|
||
value `GDB_OSABI_UNKNOWN' is returned if the OS ABI cannot be
|
||
determined.
|
||
|
||
-- Function: void gdbarch_init_osabi (struct gdbarch info INFO, struct
|
||
gdbarch *GDBARCH, enum gdb_osabi OSABI)
|
||
Invoke the OS ABI handler corresponding to OSABI to fine-tune the
|
||
`gdbarch' structure specified by GDBARCH. If a handler
|
||
corresponding to OSABI has not been registered for GDBARCH's
|
||
architecture, a warning will be issued and the debugging session
|
||
will continue with the defaults already established for GDBARCH.
|
||
|
||
-- Function: void generic_elf_osabi_sniff_abi_tag_sections (bfd *ABFD,
|
||
asection *SECT, void *OBJ)
|
||
Helper routine for ELF file sniffers. Examine the file described
|
||
by ABFD and look at ABI tag note sections to determine the OS ABI
|
||
from the note. This function should be called via
|
||
`bfd_map_over_sections'.
|
||
|
||
|
||
File: gdbint.info, Node: Initialize New Architecture, Next: Registers and Memory, Prev: OS ABI Variant Handling, Up: Target Architecture Definition
|
||
|
||
11.2 Initializing a New Architecture
|
||
====================================
|
||
|
||
* Menu:
|
||
|
||
* How an Architecture is Represented::
|
||
* Looking Up an Existing Architecture::
|
||
* Creating a New Architecture::
|
||
|
||
|
||
File: gdbint.info, Node: How an Architecture is Represented, Next: Looking Up an Existing Architecture, Up: Initialize New Architecture
|
||
|
||
11.2.1 How an Architecture is Represented
|
||
-----------------------------------------
|
||
|
||
Each `gdbarch' is associated with a single BFD architecture, via a
|
||
`bfd_arch_ARCH' in the `bfd_architecture' enumeration. The `gdbarch'
|
||
is registered by a call to `register_gdbarch_init', usually from the
|
||
file's `_initialize_FILENAME' routine, which will be automatically
|
||
called during GDB startup. The arguments are a BFD architecture
|
||
constant and an initialization function.
|
||
|
||
A GDB description for a new architecture, ARCH is created by
|
||
defining a global function `_initialize_ARCH_tdep', by convention in
|
||
the source file `ARCH-tdep.c'. For example, in the case of the
|
||
OpenRISC 1000, this function is called `_initialize_or1k_tdep' and is
|
||
found in the file `or1k-tdep.c'.
|
||
|
||
The resulting object files containing the implementation of the
|
||
`_initialize_ARCH_tdep' function are specified in the GDB
|
||
`configure.tgt' file, which includes a large case statement pattern
|
||
matching against the `--target' option of the `configure' script. The
|
||
new `struct gdbarch' is created within the `_initialize_ARCH_tdep'
|
||
function by calling `gdbarch_register':
|
||
|
||
void gdbarch_register (enum bfd_architecture ARCHITECTURE,
|
||
gdbarch_init_ftype *INIT_FUNC,
|
||
gdbarch_dump_tdep_ftype *TDEP_DUMP_FUNC);
|
||
|
||
The ARCHITECTURE will identify the unique BFD to be associated with
|
||
this `gdbarch'. The INIT_FUNC funciton is called to create and return
|
||
the new `struct gdbarch'. The TDEP_DUMP_FUNC function will dump the
|
||
target specific details associated with this architecture.
|
||
|
||
For example the function `_initialize_or1k_tdep' creates its
|
||
architecture for 32-bit OpenRISC 1000 architectures by calling:
|
||
|
||
gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep);
|
||
|
||
|
||
File: gdbint.info, Node: Looking Up an Existing Architecture, Next: Creating a New Architecture, Prev: How an Architecture is Represented, Up: Initialize New Architecture
|
||
|
||
11.2.2 Looking Up an Existing Architecture
|
||
------------------------------------------
|
||
|
||
The initialization function has this prototype:
|
||
|
||
static struct gdbarch *
|
||
ARCH_gdbarch_init (struct gdbarch_info INFO,
|
||
struct gdbarch_list *ARCHES)
|
||
|
||
The INFO argument contains parameters used to select the correct
|
||
architecture, and ARCHES is a list of architectures which have already
|
||
been created with the same `bfd_arch_ARCH' value.
|
||
|
||
The initialization function should first make sure that INFO is
|
||
acceptable, and return `NULL' if it is not. Then, it should search
|
||
through ARCHES for an exact match to INFO, and return one if found.
|
||
Lastly, if no exact match was found, it should create a new
|
||
architecture based on INFO and return it.
|
||
|
||
The lookup is done using `gdbarch_list_lookup_by_info'. It is
|
||
passed the list of existing architectures, ARCHES, and the `struct
|
||
gdbarch_info', INFO, and returns the first matching architecture it
|
||
finds, or `NULL' if none are found. If an architecture is found it can
|
||
be returned as the result from the initialization function, otherwise a
|
||
new `struct gdbach' will need to be created.
|
||
|
||
The struct gdbarch_info has the following components:
|
||
|
||
struct gdbarch_info
|
||
{
|
||
const struct bfd_arch_info *bfd_arch_info;
|
||
int byte_order;
|
||
bfd *abfd;
|
||
struct gdbarch_tdep_info *tdep_info;
|
||
enum gdb_osabi osabi;
|
||
const struct target_desc *target_desc;
|
||
};
|
||
|
||
The `bfd_arch_info' member holds the key details about the
|
||
architecture. The `byte_order' member is a value in an enumeration
|
||
indicating the endianism. The `abfd' member is a pointer to the full
|
||
BFD, the `tdep_info' member is additional custom target specific
|
||
information, `osabi' identifies which (if any) of a number of operating
|
||
specific ABIs are used by this architecture and the `target_desc'
|
||
member is a set of name-value pairs with information about register
|
||
usage in this target.
|
||
|
||
When the `struct gdbarch' initialization function is called, not all
|
||
the fields are provided--only those which can be deduced from the BFD.
|
||
The `struct gdbarch_info', INFO is used as a look-up key with the list
|
||
of existing architectures, ARCHES to see if a suitable architecture
|
||
already exists. The TDEP_INFO, OSABI and TARGET_DESC fields may be
|
||
added before this lookup to refine the search.
|
||
|
||
Only information in INFO should be used to choose the new
|
||
architecture. Historically, INFO could be sparse, and defaults would
|
||
be collected from the first element on ARCHES. However, GDB now fills
|
||
in INFO more thoroughly, so new `gdbarch' initialization functions
|
||
should not take defaults from ARCHES.
|
||
|
||
|
||
File: gdbint.info, Node: Creating a New Architecture, Prev: Looking Up an Existing Architecture, Up: Initialize New Architecture
|
||
|
||
11.2.3 Creating a New Architecture
|
||
----------------------------------
|
||
|
||
If no architecture is found, then a new architecture must be created,
|
||
by calling `gdbarch_alloc' using the supplied `struct gdbarch_info' and
|
||
any additional custom target specific information in a `struct
|
||
gdbarch_tdep'. The prototype for `gdbarch_alloc' is:
|
||
|
||
struct gdbarch *gdbarch_alloc (const struct gdbarch_info *INFO,
|
||
struct gdbarch_tdep *TDEP);
|
||
|
||
The newly created struct gdbarch must then be populated. Although
|
||
there are default values, in most cases they are not what is required.
|
||
|
||
For each element, X, there is are a pair of corresponding accessor
|
||
functions, one to set the value of that element, `set_gdbarch_X', the
|
||
second to either get the value of an element (if it is a variable) or
|
||
to apply the element (if it is a function), `gdbarch_X'. Note that
|
||
both accessor functions take a pointer to the `struct gdbarch' as first
|
||
argument. Populating the new `gdbarch' should use the `set_gdbarch'
|
||
functions.
|
||
|
||
The following sections identify the main elements that should be set
|
||
in this way. This is not the complete list, but represents the
|
||
functions and elements that must commonly be specified for a new
|
||
architecture. Many of the functions and variables are described in the
|
||
header file `gdbarch.h'.
|
||
|
||
This is the main work in defining a new architecture. Implementing
|
||
the set of functions to populate the `struct gdbarch'.
|
||
|
||
`struct gdbarch_tdep' is not defined within GDB--it is up to the
|
||
user to define this struct if it is needed to hold custom target
|
||
information that is not covered by the standard `struct gdbarch'. For
|
||
example with the OpenRISC 1000 architecture it is used to hold the
|
||
number of matchpoints available in the target (along with other
|
||
information).
|
||
|
||
If there is no additional target specific information, it can be set
|
||
to `NULL'.
|
||
|
||
|
||
File: gdbint.info, Node: Registers and Memory, Next: Pointers and Addresses, Prev: Initialize New Architecture, Up: Target Architecture Definition
|
||
|
||
11.3 Registers and Memory
|
||
=========================
|
||
|
||
GDB's model of the target machine is rather simple. GDB assumes the
|
||
machine includes a bank of registers and a block of memory. Each
|
||
register may have a different size.
|
||
|
||
GDB does not have a magical way to match up with the compiler's idea
|
||
of which registers are which; however, it is critical that they do
|
||
match up accurately. The only way to make this work is to get accurate
|
||
information about the order that the compiler uses, and to reflect that
|
||
in the `gdbarch_register_name' and related functions.
|
||
|
||
GDB can handle big-endian, little-endian, and bi-endian
|
||
architectures.
|
||
|
||
|
||
File: gdbint.info, Node: Pointers and Addresses, Next: Address Classes, Prev: Registers and Memory, Up: Target Architecture Definition
|
||
|
||
11.4 Pointers Are Not Always Addresses
|
||
======================================
|
||
|
||
On almost all 32-bit architectures, the representation of a pointer is
|
||
indistinguishable from the representation of some fixed-length number
|
||
whose value is the byte address of the object pointed to. On such
|
||
machines, the words "pointer" and "address" can be used interchangeably.
|
||
However, architectures with smaller word sizes are often cramped for
|
||
address space, so they may choose a pointer representation that breaks
|
||
this identity, and allows a larger code address space.
|
||
|
||
For example, the Renesas D10V is a 16-bit VLIW processor whose
|
||
instructions are 32 bits long(1). If the D10V used ordinary byte
|
||
addresses to refer to code locations, then the processor would only be
|
||
able to address 64kb of instructions. However, since instructions must
|
||
be aligned on four-byte boundaries, the low two bits of any valid
|
||
instruction's byte address are always zero--byte addresses waste two
|
||
bits. So instead of byte addresses, the D10V uses word addresses--byte
|
||
addresses shifted right two bits--to refer to code. Thus, the D10V can
|
||
use 16-bit words to address 256kb of code space.
|
||
|
||
However, this means that code pointers and data pointers have
|
||
different forms on the D10V. The 16-bit word `0xC020' refers to byte
|
||
address `0xC020' when used as a data address, but refers to byte address
|
||
`0x30080' when used as a code address.
|
||
|
||
(The D10V also uses separate code and data address spaces, which also
|
||
affects the correspondence between pointers and addresses, but we're
|
||
going to ignore that here; this example is already too long.)
|
||
|
||
To cope with architectures like this--the D10V is not the only
|
||
one!--GDB tries to distinguish between "addresses", which are byte
|
||
numbers, and "pointers", which are the target's representation of an
|
||
address of a particular type of data. In the example above, `0xC020'
|
||
is the pointer, which refers to one of the addresses `0xC020' or
|
||
`0x30080', depending on the type imposed upon it. GDB provides
|
||
functions for turning a pointer into an address and vice versa, in the
|
||
appropriate way for the current architecture.
|
||
|
||
Unfortunately, since addresses and pointers are identical on almost
|
||
all processors, this distinction tends to bit-rot pretty quickly. Thus,
|
||
each time you port GDB to an architecture which does distinguish
|
||
between pointers and addresses, you'll probably need to clean up some
|
||
architecture-independent code.
|
||
|
||
Here are functions which convert between pointers and addresses:
|
||
|
||
-- Function: CORE_ADDR extract_typed_address (void *BUF, struct type
|
||
*TYPE)
|
||
Treat the bytes at BUF as a pointer or reference of type TYPE, and
|
||
return the address it represents, in a manner appropriate for the
|
||
current architecture. This yields an address GDB can use to read
|
||
target memory, disassemble, etc. Note that BUF refers to a buffer
|
||
in GDB's memory, not the inferior's.
|
||
|
||
For example, if the current architecture is the Intel x86, this
|
||
function extracts a little-endian integer of the appropriate
|
||
length from BUF and returns it. However, if the current
|
||
architecture is the D10V, this function will return a 16-bit
|
||
integer extracted from BUF, multiplied by four if TYPE is a
|
||
pointer to a function.
|
||
|
||
If TYPE is not a pointer or reference type, then this function
|
||
will signal an internal error.
|
||
|
||
-- Function: CORE_ADDR store_typed_address (void *BUF, struct type
|
||
*TYPE, CORE_ADDR ADDR)
|
||
Store the address ADDR in BUF, in the proper format for a pointer
|
||
of type TYPE in the current architecture. Note that BUF refers to
|
||
a buffer in GDB's memory, not the inferior's.
|
||
|
||
For example, if the current architecture is the Intel x86, this
|
||
function stores ADDR unmodified as a little-endian integer of the
|
||
appropriate length in BUF. However, if the current architecture
|
||
is the D10V, this function divides ADDR by four if TYPE is a
|
||
pointer to a function, and then stores it in BUF.
|
||
|
||
If TYPE is not a pointer or reference type, then this function
|
||
will signal an internal error.
|
||
|
||
-- Function: CORE_ADDR value_as_address (struct value *VAL)
|
||
Assuming that VAL is a pointer, return the address it represents,
|
||
as appropriate for the current architecture.
|
||
|
||
This function actually works on integral values, as well as
|
||
pointers. For pointers, it performs architecture-specific
|
||
conversions as described above for `extract_typed_address'.
|
||
|
||
-- Function: CORE_ADDR value_from_pointer (struct type *TYPE,
|
||
CORE_ADDR ADDR)
|
||
Create and return a value representing a pointer of type TYPE to
|
||
the address ADDR, as appropriate for the current architecture.
|
||
This function performs architecture-specific conversions as
|
||
described above for `store_typed_address'.
|
||
|
||
Here are two functions which architectures can define to indicate the
|
||
relationship between pointers and addresses. These have default
|
||
definitions, appropriate for architectures on which all pointers are
|
||
simple unsigned byte addresses.
|
||
|
||
-- Function: CORE_ADDR gdbarch_pointer_to_address (struct gdbarch
|
||
*GDBARCH, struct type *TYPE, char *BUF)
|
||
Assume that BUF holds a pointer of type TYPE, in the appropriate
|
||
format for the current architecture. Return the byte address the
|
||
pointer refers to.
|
||
|
||
This function may safely assume that TYPE is either a pointer or a
|
||
C++ reference type.
|
||
|
||
-- Function: void gdbarch_address_to_pointer (struct gdbarch *GDBARCH,
|
||
struct type *TYPE, char *BUF, CORE_ADDR ADDR)
|
||
Store in BUF a pointer of type TYPE representing the address ADDR,
|
||
in the appropriate format for the current architecture.
|
||
|
||
This function may safely assume that TYPE is either a pointer or a
|
||
C++ reference type.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) Some D10V instructions are actually pairs of 16-bit
|
||
sub-instructions. However, since you can't jump into the middle of
|
||
such a pair, code addresses can only refer to full 32 bit instructions,
|
||
which is what matters in this explanation.
|
||
|
||
|
||
File: gdbint.info, Node: Address Classes, Next: Register Representation, Prev: Pointers and Addresses, Up: Target Architecture Definition
|
||
|
||
11.5 Address Classes
|
||
====================
|
||
|
||
Sometimes information about different kinds of addresses is available
|
||
via the debug information. For example, some programming environments
|
||
define addresses of several different sizes. If the debug information
|
||
distinguishes these kinds of address classes through either the size
|
||
info (e.g, `DW_AT_byte_size' in DWARF 2) or through an explicit address
|
||
class attribute (e.g, `DW_AT_address_class' in DWARF 2), the following
|
||
macros should be defined in order to disambiguate these types within
|
||
GDB as well as provide the added information to a GDB user when
|
||
printing type expressions.
|
||
|
||
-- Function: int gdbarch_address_class_type_flags (struct gdbarch
|
||
*GDBARCH, int BYTE_SIZE, int DWARF2_ADDR_CLASS)
|
||
Returns the type flags needed to construct a pointer type whose
|
||
size is BYTE_SIZE and whose address class is DWARF2_ADDR_CLASS.
|
||
This function is normally called from within a symbol reader. See
|
||
`dwarf2read.c'.
|
||
|
||
-- Function: char * gdbarch_address_class_type_flags_to_name (struct
|
||
gdbarch *GDBARCH, int TYPE_FLAGS)
|
||
Given the type flags representing an address class qualifier,
|
||
return its name.
|
||
|
||
-- Function: int gdbarch_address_class_name_to_type_flags (struct
|
||
gdbarch *GDBARCH, int NAME, int *TYPE_FLAGS_PTR)
|
||
Given an address qualifier name, set the `int' referenced by
|
||
TYPE_FLAGS_PTR to the type flags for that address class qualifier.
|
||
|
||
Since the need for address classes is rather rare, none of the
|
||
address class functions are defined by default. Predicate functions
|
||
are provided to detect when they are defined.
|
||
|
||
Consider a hypothetical architecture in which addresses are normally
|
||
32-bits wide, but 16-bit addresses are also supported. Furthermore,
|
||
suppose that the DWARF 2 information for this architecture simply uses
|
||
a `DW_AT_byte_size' value of 2 to indicate the use of one of these
|
||
"short" pointers. The following functions could be defined to
|
||
implement the address class functions:
|
||
|
||
somearch_address_class_type_flags (int byte_size,
|
||
int dwarf2_addr_class)
|
||
{
|
||
if (byte_size == 2)
|
||
return TYPE_FLAG_ADDRESS_CLASS_1;
|
||
else
|
||
return 0;
|
||
}
|
||
|
||
static char *
|
||
somearch_address_class_type_flags_to_name (int type_flags)
|
||
{
|
||
if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
|
||
return "short";
|
||
else
|
||
return NULL;
|
||
}
|
||
|
||
int
|
||
somearch_address_class_name_to_type_flags (char *name,
|
||
int *type_flags_ptr)
|
||
{
|
||
if (strcmp (name, "short") == 0)
|
||
{
|
||
*type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
|
||
return 1;
|
||
}
|
||
else
|
||
return 0;
|
||
}
|
||
|
||
The qualifier `@short' is used in GDB's type expressions to indicate
|
||
the presence of one of these "short" pointers. For example if the
|
||
debug information indicates that `short_ptr_var' is one of these short
|
||
pointers, GDB might show the following behavior:
|
||
|
||
(gdb) ptype short_ptr_var
|
||
type = int * @short
|
||
|
||
|
||
File: gdbint.info, Node: Register Representation, Next: Frame Interpretation, Prev: Address Classes, Up: Target Architecture Definition
|
||
|
||
11.6 Register Representation
|
||
============================
|
||
|
||
* Menu:
|
||
|
||
* Raw and Cooked Registers::
|
||
* Register Architecture Functions & Variables::
|
||
* Register Information Functions::
|
||
* Register and Memory Data::
|
||
* Register Caching::
|
||
|
||
|
||
File: gdbint.info, Node: Raw and Cooked Registers, Next: Register Architecture Functions & Variables, Up: Register Representation
|
||
|
||
11.6.1 Raw and Cooked Registers
|
||
-------------------------------
|
||
|
||
GDB considers registers to be a set with members numbered linearly from
|
||
0 upwards. The first part of that set corresponds to real physical
|
||
registers, the second part to any "pseudo-registers". Pseudo-registers
|
||
have no independent physical existence, but are useful representations
|
||
of information within the architecture. For example the OpenRISC 1000
|
||
architecture has up to 32 general purpose registers, which are
|
||
typically represented as 32-bit (or 64-bit) integers. However the GPRs
|
||
are also used as operands to the floating point operations, and it
|
||
could be convenient to define a set of pseudo-registers, to show the
|
||
GPRs represented as floating point values.
|
||
|
||
For any architecture, the implementer will decide on a mapping from
|
||
hardware to GDB register numbers. The registers corresponding to real
|
||
hardware are referred to as "raw" registers, the remaining registers are
|
||
"pseudo-registers". The total register set (raw and pseudo) is called
|
||
the "cooked" register set.
|
||
|
||
|
||
File: gdbint.info, Node: Register Architecture Functions & Variables, Next: Register Information Functions, Prev: Raw and Cooked Registers, Up: Register Representation
|
||
|
||
11.6.2 Functions and Variables Specifying the Register Architecture
|
||
-------------------------------------------------------------------
|
||
|
||
These `struct gdbarch' functions and variables specify the number and
|
||
type of registers in the architecture.
|
||
|
||
-- Architecture Function: CORE_ADDR read_pc (struct regcache *REGCACHE)
|
||
|
||
-- Architecture Function: void write_pc (struct regcache *REGCACHE,
|
||
CORE_ADDR VAL)
|
||
Read or write the program counter. The default value of both
|
||
functions is `NULL' (no function available). If the program
|
||
counter is just an ordinary register, it can be specified in
|
||
`struct gdbarch' instead (see `pc_regnum' below) and it will be
|
||
read or written using the standard routines to access registers.
|
||
This function need only be specified if the program counter is not
|
||
an ordinary register.
|
||
|
||
Any register information can be obtained using the supplied
|
||
register cache, REGCACHE. *Note Register Caching: Register
|
||
Caching.
|
||
|
||
|
||
-- Architecture Function: void pseudo_register_read (struct gdbarch
|
||
*GDBARCH, struct regcache *REGCACHE, int REGNUM, const
|
||
gdb_byte *BUF)
|
||
|
||
-- Architecture Function: void pseudo_register_write (struct gdbarch
|
||
*GDBARCH, struct regcache *REGCACHE, int REGNUM, const
|
||
gdb_byte *BUF)
|
||
These functions should be defined if there are any
|
||
pseudo-registers. The default value is `NULL'. REGNUM is the
|
||
number of the register to read or write (which will be a "cooked"
|
||
register number) and BUF is the buffer where the value read will be
|
||
placed, or from which the value to be written will be taken. The
|
||
value in the buffer may be converted to or from a signed or
|
||
unsigned integral value using one of the utility functions (*note
|
||
Using Different Register and Memory Data Representations: Register
|
||
and Memory Data.).
|
||
|
||
The access should be for the specified architecture, GDBARCH. Any
|
||
register information can be obtained using the supplied register
|
||
cache, REGCACHE. *Note Register Caching: Register Caching.
|
||
|
||
|
||
-- Architecture Variable: int sp_regnum
|
||
This specifies the register holding the stack pointer, which may
|
||
be a raw or pseudo-register. It defaults to -1 (not defined), but
|
||
it is an error for it not to be defined.
|
||
|
||
The value of the stack pointer register can be accessed withing
|
||
GDB as the variable `$sp'.
|
||
|
||
|
||
-- Architecture Variable: int pc_regnum
|
||
This specifies the register holding the program counter, which may
|
||
be a raw or pseudo-register. It defaults to -1 (not defined). If
|
||
`pc_regnum' is not defined, then the functions `read_pc' and
|
||
`write_pc' (see above) must be defined.
|
||
|
||
The value of the program counter (whether defined as a register, or
|
||
through `read_pc' and `write_pc') can be accessed withing GDB as
|
||
the variable `$pc'.
|
||
|
||
|
||
-- Architecture Variable: int ps_regnum
|
||
This specifies the register holding the processor status (often
|
||
called the status register), which may be a raw or
|
||
pseudo-register. It defaults to -1 (not defined).
|
||
|
||
If defined, the value of this register can be accessed withing GDB
|
||
as the variable `$ps'.
|
||
|
||
|
||
-- Architecture Variable: int fp0_regnum
|
||
This specifies the first floating point register. It defaults to
|
||
0. `fp0_regnum' is not needed unless the target offers support
|
||
for floating point.
|
||
|
||
|
||
|
||
File: gdbint.info, Node: Register Information Functions, Next: Register and Memory Data, Prev: Register Architecture Functions & Variables, Up: Register Representation
|
||
|
||
11.6.3 Functions Giving Register Information
|
||
--------------------------------------------
|
||
|
||
These functions return information about registers.
|
||
|
||
-- Architecture Function: const char * register_name (struct gdbarch
|
||
*GDBARCH, int REGNUM)
|
||
This function should convert a register number (raw or pseudo) to a
|
||
register name (as a C `const char *'). This is used both to
|
||
determine the name of a register for output and to work out the
|
||
meaning of any register names used as input. The function may
|
||
also return `NULL', to indicate that REGNUM is not a valid
|
||
register.
|
||
|
||
For example with the OpenRISC 1000, GDB registers 0-31 are the
|
||
General Purpose Registers, register 32 is the program counter and
|
||
register 33 is the supervision register (i.e. the processor status
|
||
register), which map to the strings `"gpr00"' through `"gpr31"',
|
||
`"pc"' and `"sr"' respectively. This means that the GDB command
|
||
`print $gpr5' should print the value of the OR1K general purpose
|
||
register 5(1).
|
||
|
||
The default value for this function is `NULL', meaning undefined.
|
||
It should always be defined.
|
||
|
||
The access should be for the specified architecture, GDBARCH.
|
||
|
||
|
||
-- Architecture Function: struct type * register_type (struct gdbarch
|
||
*GDBARCH, int REGNUM)
|
||
Given a register number, this function identifies the type of data
|
||
it may be holding, specified as a `struct type'. GDB allows
|
||
creation of arbitrary types, but a number of built in types are
|
||
provided (`builtin_type_void', `builtin_type_int32' etc), together
|
||
with functions to derive types from these.
|
||
|
||
Typically the program counter will have a type of "pointer to
|
||
function" (it points to code), the frame pointer and stack pointer
|
||
will have types of "pointer to void" (they point to data on the
|
||
stack) and all other integer registers will have a type of 32-bit
|
||
integer or 64-bit integer.
|
||
|
||
This information guides the formatting when displaying register
|
||
information. The default value is `NULL' meaning no information is
|
||
available to guide formatting when displaying registers.
|
||
|
||
|
||
-- Architecture Function: void print_registers_info (struct gdbarch
|
||
*GDBARCH, struct ui_file *FILE, struct frame_info *FRAME, int
|
||
REGNUM, int ALL)
|
||
Define this function to print out one or all of the registers for
|
||
the GDB `info registers' command. The default value is the
|
||
function `default_print_registers_info', which uses the register
|
||
type information (see `register_type' above) to determine how each
|
||
register should be printed. Define a custom version of this
|
||
function for fuller control over how the registers are displayed.
|
||
|
||
The access should be for the specified architecture, GDBARCH, with
|
||
output to the file specified by the User Interface Independent
|
||
Output file handle, FILE (*note UI-Independent Output--the
|
||
`ui_out' Functions: UI-Independent Output.).
|
||
|
||
The registers should show their values in the frame specified by
|
||
FRAME. If REGNUM is -1 and ALL is zero, then all the
|
||
"significant" registers should be shown (the implementer should
|
||
decide which registers are "significant"). Otherwise only the
|
||
value of the register specified by REGNUM should be output. If
|
||
REGNUM is -1 and ALL is non-zero (true), then the value of all
|
||
registers should be shown.
|
||
|
||
By default `default_print_registers_info' prints one register per
|
||
line, and if ALL is zero omits floating-point registers.
|
||
|
||
|
||
-- Architecture Function: void print_float_info (struct gdbarch
|
||
*GDBARCH, struct ui_file *FILE, struct frame_info *FRAME,
|
||
const char *ARGS)
|
||
Define this function to provide output about the floating point
|
||
unit and registers for the GDB `info float' command respectively.
|
||
The default value is `NULL' (not defined), meaning no information
|
||
will be provided.
|
||
|
||
The GDBARCH and FILE and FRAME arguments have the same meaning as
|
||
in the `print_registers_info' function above. The string ARGS
|
||
contains any supplementary arguments to the `info float' command.
|
||
|
||
Define this function if the target supports floating point
|
||
operations.
|
||
|
||
|
||
-- Architecture Function: void print_vector_info (struct gdbarch
|
||
*GDBARCH, struct ui_file *FILE, struct frame_info *FRAME,
|
||
const char *ARGS)
|
||
Define this function to provide output about the vector unit and
|
||
registers for the GDB `info vector' command respectively. The
|
||
default value is `NULL' (not defined), meaning no information will
|
||
be provided.
|
||
|
||
The GDBARCH, FILE and FRAME arguments have the same meaning as in
|
||
the `print_registers_info' function above. The string ARGS
|
||
contains any supplementary arguments to the `info vector' command.
|
||
|
||
Define this function if the target supports vector operations.
|
||
|
||
|
||
-- Architecture Function: int register_reggroup_p (struct gdbarch
|
||
*GDBARCH, int REGNUM, struct reggroup *GROUP)
|
||
GDB groups registers into different categories (general, vector,
|
||
floating point etc). This function, given a register, REGNUM, and
|
||
group, GROUP, returns 1 (true) if the register is in the group and
|
||
0 (false) otherwise.
|
||
|
||
The information should be for the specified architecture, GDBARCH
|
||
|
||
The default value is the function `default_register_reggroup_p'
|
||
which will do a reasonable job based on the type of the register
|
||
(see the function `register_type' above), with groups for general
|
||
purpose registers, floating point registers, vector registers and
|
||
raw (i.e not pseudo) registers.
|
||
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) Historically, GDB always had a concept of a frame pointer
|
||
register, which could be accessed via the GDB variable, `$fp'. That
|
||
concept is now deprecated, recognizing that not all architectures have
|
||
a frame pointer. However if an architecture does have a frame pointer
|
||
register, and defines a register or pseudo-register with the name
|
||
`"fp"', then that register will be used as the value of the `$fp'
|
||
variable.
|
||
|
||
|
||
File: gdbint.info, Node: Register and Memory Data, Next: Register Caching, Prev: Register Information Functions, Up: Register Representation
|
||
|
||
11.6.4 Using Different Register and Memory Data Representations
|
||
---------------------------------------------------------------
|
||
|
||
Some architectures have different representations of data objects,
|
||
depending whether the object is held in a register or memory. For
|
||
example:
|
||
|
||
* The Alpha architecture can represent 32 bit integer values in
|
||
floating-point registers.
|
||
|
||
* The x86 architecture supports 80-bit floating-point registers. The
|
||
`long double' data type occupies 96 bits in memory but only 80
|
||
bits when stored in a register.
|
||
|
||
|
||
In general, the register representation of a data type is determined
|
||
by the architecture, or GDB's interface to the architecture, while the
|
||
memory representation is determined by the Application Binary Interface.
|
||
|
||
For almost all data types on almost all architectures, the two
|
||
representations are identical, and no special handling is needed.
|
||
However, they do occasionally differ. An architecture may define the
|
||
following `struct gdbarch' functions to request conversions between the
|
||
register and memory representations of a data type:
|
||
|
||
-- Architecture Function: int gdbarch_convert_register_p (struct
|
||
gdbarch *GDBARCH, int REG)
|
||
Return non-zero (true) if the representation of a data value
|
||
stored in this register may be different to the representation of
|
||
that same data value when stored in memory. The default value is
|
||
`NULL' (undefined).
|
||
|
||
If this function is defined and returns non-zero, the `struct
|
||
gdbarch' functions `gdbarch_register_to_value' and
|
||
`gdbarch_value_to_register' (see below) should be used to perform
|
||
any necessary conversion.
|
||
|
||
If defined, this function should return zero for the register's
|
||
native type, when no conversion is necessary.
|
||
|
||
-- Architecture Function: void gdbarch_register_to_value (struct
|
||
gdbarch *GDBARCH, int REG, struct type *TYPE, char *FROM,
|
||
char *TO)
|
||
Convert the value of register number REG to a data object of type
|
||
TYPE. The buffer at FROM holds the register's value in raw
|
||
format; the converted value should be placed in the buffer at TO.
|
||
|
||
_Note:_ `gdbarch_register_to_value' and
|
||
`gdbarch_value_to_register' take their REG and TYPE arguments
|
||
in different orders.
|
||
|
||
`gdbarch_register_to_value' should only be used with registers for
|
||
which the `gdbarch_convert_register_p' function returns a non-zero
|
||
value.
|
||
|
||
|
||
-- Architecture Function: void gdbarch_value_to_register (struct
|
||
gdbarch *GDBARCH, struct type *TYPE, int REG, char *FROM,
|
||
char *TO)
|
||
Convert a data value of type TYPE to register number REG' raw
|
||
format.
|
||
|
||
_Note:_ `gdbarch_register_to_value' and
|
||
`gdbarch_value_to_register' take their REG and TYPE arguments
|
||
in different orders.
|
||
|
||
`gdbarch_value_to_register' should only be used with registers for
|
||
which the `gdbarch_convert_register_p' function returns a non-zero
|
||
value.
|
||
|
||
|
||
|
||
File: gdbint.info, Node: Register Caching, Prev: Register and Memory Data, Up: Register Representation
|
||
|
||
11.6.5 Register Caching
|
||
-----------------------
|
||
|
||
Caching of registers is used, so that the target does not need to be
|
||
accessed and reanalyzed multiple times for each register in
|
||
circumstances where the register value cannot have changed.
|
||
|
||
GDB provides `struct regcache', associated with a particular `struct
|
||
gdbarch' to hold the cached values of the raw registers. A set of
|
||
functions is provided to access both the raw registers (with `raw' in
|
||
their name) and the full set of cooked registers (with `cooked' in
|
||
their name). Functions are provided to ensure the register cache is
|
||
kept synchronized with the values of the actual registers in the target.
|
||
|
||
Accessing registers through the `struct regcache' routines will
|
||
ensure that the appropriate `struct gdbarch' functions are called when
|
||
necessary to access the underlying target architecture. In general
|
||
users should use the "cooked" functions, since these will map to the
|
||
"raw" functions automatically as appropriate.
|
||
|
||
The two key functions are `regcache_cooked_read' and
|
||
`regcache_cooked_write' which read or write a register from or to a
|
||
byte buffer (type `gdb_byte *'). For convenience the wrapper functions
|
||
`regcache_cooked_read_signed', `regcache_cooked_read_unsigned',
|
||
`regcache_cooked_write_signed' and `regcache_cooked_write_unsigned' are
|
||
provided, which read or write the value using the buffer and convert to
|
||
or from an integral value as appropriate.
|
||
|
||
|
||
File: gdbint.info, Node: Frame Interpretation, Next: Inferior Call Setup, Prev: Register Representation, Up: Target Architecture Definition
|
||
|
||
11.7 Frame Interpretation
|
||
=========================
|
||
|
||
* Menu:
|
||
|
||
* All About Stack Frames::
|
||
* Frame Handling Terminology::
|
||
* Prologue Caches::
|
||
* Functions and Variable to Analyze Frames::
|
||
* Functions to Access Frame Data::
|
||
* Analyzing Stacks---Frame Sniffers::
|
||
|
||
|
||
File: gdbint.info, Node: All About Stack Frames, Next: Frame Handling Terminology, Up: Frame Interpretation
|
||
|
||
11.7.1 All About Stack Frames
|
||
-----------------------------
|
||
|
||
GDB needs to understand the stack on which local (automatic) variables
|
||
are stored. The area of the stack containing all the local variables
|
||
for a function invocation is known as the "stack frame" for that
|
||
function (or colloquially just as the "frame"). In turn the function
|
||
that called the function will have its stack frame, and so on back
|
||
through the chain of functions that have been called.
|
||
|
||
Almost all architectures have one register dedicated to point to the
|
||
end of the stack (the "stack pointer"). Many have a second register
|
||
which points to the start of the currently active stack frame (the
|
||
"frame pointer"). The specific arrangements for an architecture are a
|
||
key part of the ABI.
|
||
|
||
A diagram helps to explain this. Here is a simple program to compute
|
||
factorials:
|
||
|
||
#include <stdio.h>
|
||
int fact (int n)
|
||
{
|
||
if (0 == n)
|
||
{
|
||
return 1;
|
||
}
|
||
else
|
||
{
|
||
return n * fact (n - 1);
|
||
}
|
||
}
|
||
|
||
main ()
|
||
{
|
||
int i;
|
||
|
||
for (i = 0; i < 10; i++)
|
||
{
|
||
int f = fact (i);
|
||
printf ("%d! = %d\n", i, f);
|
||
}
|
||
}
|
||
|
||
Consider the state of the stack when the code reaches line 6 after
|
||
the main program has called `fact (3)'. The chain of function calls
|
||
will be `main ()', `fact (3)', `fact (2)', `fact (1)' and `fact (0)'.
|
||
|
||
In this illustration the stack is falling (as used for example by the
|
||
OpenRISC 1000 ABI). The stack pointer (SP) is at the end of the stack
|
||
(lowest address) and the frame pointer (FP) is at the highest address
|
||
in the current stack frame. The following diagram shows how the stack
|
||
looks.
|
||
|
||
|