151 lines
5.8 KiB
Text
151 lines
5.8 KiB
Text
GDB Internals documentation
|
|
Copyright 1990, 1991 Free Software Foundation, Inc.
|
|
Contributed by Cygnus Support. Written by John Gilmore.
|
|
|
|
This needs to be wrapped in texinfo stuff...
|
|
|
|
Cleanups
|
|
|
|
Cleanups are a structured way to deal with things that need to be done
|
|
later. When your code does something (like malloc some memory, or open
|
|
a file) that needs to be undone later (e.g. free the memory or close
|
|
the file), it can make a cleanup. The cleanup will be done at some
|
|
future point: when the command is finished, when an error occurs, or
|
|
when your code decides it's time to do cleanups.
|
|
|
|
You can also discard cleanups, that is, throw them away without doing
|
|
what they say. This is only done if you ask that it be done.
|
|
|
|
Syntax:
|
|
|
|
old_chain = make_cleanup (function, arg);
|
|
|
|
This makes a cleanup which will cause FUNCTION to be called with ARG
|
|
(a char *) later. The result, OLD_CHAIN, is a handle that can be
|
|
passed to do_cleanups or discard_cleanups later. Unless you are
|
|
going to call do_cleanups or discard_cleanups yourself,
|
|
you can ignore the result from make_cleanup.
|
|
|
|
do_cleanups (old_chain);
|
|
|
|
Performs all cleanups done since make_cleanup returned OLD_CHAIN.
|
|
E.g.: make_cleanup (a, 0); old = make_cleanup (b, 0); do_cleanups (old);
|
|
will call b() but will not call a(). The cleanup that calls a() will remain
|
|
in the cleanup chain, and will be done later unless otherwise discarded.
|
|
|
|
discard_cleanups (old_chain);
|
|
|
|
Same as do_cleanups except that it just removes the cleanups from the
|
|
chain and does not call the specified functions.
|
|
|
|
|
|
Some functions, e.g. fputs_filtered() or error(), specify that they
|
|
"should not be called when cleanups are not in place". This means
|
|
that any actions you need to reverse in the case of an error or
|
|
interruption must be on the cleanup chain before you call these functions,
|
|
since they might never return to your code (they "longjmp" instead).
|
|
|
|
|
|
|
|
Wrapping output lines
|
|
|
|
Output that goes through printf_filtered or fputs_filtered or
|
|
fputs_demangled needs only to have calls to wrap_here() added
|
|
in places that would be good breaking points. The utility routines
|
|
will take care of actually wrapping if the line width is exceeded.
|
|
|
|
The argument to wrap_here() is an indentation string which is printed
|
|
ONLY if the line breaks there. This argument is saved away and used
|
|
later. It must remain valid until the next call to wrap_here() or
|
|
until a newline has been printed through the *_filtered functions.
|
|
Don't pass in a local variable and then return!
|
|
|
|
It is usually best to call wrap_here() after printing a comma or space.
|
|
If you call it before printing a space, make sure that your indentation
|
|
properly accounts for the leading space that will print if the line wraps
|
|
there.
|
|
|
|
Any function or set of functions that produce filtered output must finish
|
|
by printing a newline, to flush the wrap buffer, before switching to
|
|
unfiltered ("printf") output. Symbol reading routines that print
|
|
warnings are a good example.
|
|
|
|
|
|
|
|
Configuring GDB for release
|
|
|
|
|
|
GDB should be released after doing "config.gdb none" in the top level
|
|
directory. This will leave a makefile there, but no tm- or xm- files.
|
|
The makefile is needed, for example, for "make gdb.tar.Z"... If you
|
|
have tm- or xm-files in the main source directory, C's include rules
|
|
cause them to be used in preference to tm- and xm-files in the
|
|
subdirectories where the user will actually configure and build the
|
|
binaries.
|
|
|
|
"config.gdb none" is also a good way to rebuild the top level Makefile
|
|
after changing Makefile.dist, alldeps.mak, etc.
|
|
|
|
|
|
|
|
|
|
The README file
|
|
|
|
|
|
Check the README file, it often has useful information that does not
|
|
appear anywhere else in the directory.
|
|
|
|
|
|
|
|
|
|
Defining a new host or target architecture
|
|
|
|
|
|
When building support for a new host and/or target, this will help you
|
|
organize where to put the various parts. ARCH stands for the
|
|
architecture involved.
|
|
|
|
Object files needed when the host system is an ARCH are listed in the file
|
|
xconfig/ARCH, in the Makefile macro "XDEPFILES = ...". You can also
|
|
define XXXXXX in there.
|
|
|
|
There are some "generic" versions of routines that can be used by
|
|
various host systems. If these routines work for the ARCH host, you
|
|
can just include the generic file's name (with .o, not .c) in
|
|
XDEPFILES. Otherwise, you will need to write routines that perform the
|
|
same functions as the generic file, put them into ARCH-xdep.c, and put
|
|
ARCH-xdep.o into XDEPFILES. These generic host support files include:
|
|
|
|
coredep.c, coredep.o
|
|
|
|
fetch_core_registers():
|
|
Support for reading registers out of a core file. This routine calls
|
|
register_addr(), see below.
|
|
|
|
register_addr():
|
|
If your xm-ARCH.h file defines the macro REGISTER_U_ADDR(reg) to be the
|
|
offset within the "user" struct of a register (represented as a GDB
|
|
register number), coredep.c will define the register_addr() function
|
|
and use the macro in it. If you do not define REGISTER_U_ADDR, but
|
|
you are using the standard fetch_core_registers, you
|
|
will need to define your own version of register_addr, put it into
|
|
your ARCH-xdep.c file, and be sure ARCH-xdep.o is in the XDEPFILES list.
|
|
If you have your own fetch_core_registers, you only need to define
|
|
register_addr if your fetch_core_registers calls it. Many custom
|
|
fetch_core_registers implementations simply locate the registers
|
|
themselves.
|
|
|
|
|
|
Files needed when the target system is an ARCH are listed in the file
|
|
tconfig/ARCH, in the Makefile macro "TDEPFILES = ...". You can also
|
|
define XXXXXX in there.
|
|
|
|
Similar generic support files for target systems are:
|
|
|
|
exec.c, exec.o:
|
|
|
|
This file defines functions for accessing files that are executable
|
|
on the target system. These functions open and examine an exec file,
|
|
extract data from one, write data to one, print information about one,
|
|
etc. Now that executable files are handled with BFD, every architecture
|
|
should be able to use the generic exec.c rather than its own custom code.
|