diff options
Diffstat (limited to 'gdb/gdb-int.texinfo')
| -rwxr-xr-x | gdb/gdb-int.texinfo | 242 |
1 files changed, 0 insertions, 242 deletions
diff --git a/gdb/gdb-int.texinfo b/gdb/gdb-int.texinfo deleted file mode 100755 index cc1b188..0000000 --- a/gdb/gdb-int.texinfo +++ /dev/null @@ -1,242 +0,0 @@ -\input texinfo -@setfilename gdb-internals -@ifinfo -This file documents the internals of the GNU debugger GDB. - -Copyright (C) 1990, 1991 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by John Gilmore. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). -@end ifinfo - -@setchapternewpage odd -@settitle GDB Internals -@titlepage -@title{Working in GDB} -@subtitle{A guide to the internals of the GNU debugger} -@author John Gilmore -@author Cygnus Support -@page -@tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision$} % For use in headers, footers too -{\parskip=0pt -\hfill Cygnus Support\par -\hfill \manvers\par -\hfill \TeX{}info \texinfoversion\par -} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@end titlepage - -@node Top, Cleanups, (dir), (dir) - -@menu -* Cleanups:: Cleanups -* Wrapping:: Wrapping output lines -* Releases:: Configuring GDB for release -* README:: The README file -* New Architectures:: Defining a new host or target architecture -* Host versus Targt:: What features are in which files - -@end menu - -@node Cleanups, Wrapping, Top, Top -@chapter 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: - -@table @code -@item 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. - - -@item 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. - -@item 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. - -@end table - -Some functions, e.g. @code{fputs_filtered()} or @code{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 @samp{longjmp} instead). - - -@node Wrapping, Releases, Cleanups, Top -@chapter 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. - - -@node Releases, README, Wrapping, Top -@chapter Configuring GDB for release - - -GDB should be released after doing @samp{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 @samp{make gdb.tar.Z}@dots{} 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. - -@samp{config.gdb none} is also a good way to rebuild the top level Makefile -after changing Makefile.dist, alldeps.mak, etc. - - - -@node README, New Architectures, Releases, Top -@chapter The README file - - -Check the README file, it often has useful information that does not -appear anywhere else in the directory. - - - -@node New Architectures, Host versus Target, README, Top -@chapter 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. @var{ARCH} stands for the -architecture involved. - -Object files needed when the host system is an @var{ARCH} are listed in -the file @file{xconfig/@var{ARCH}}, in the Makefile macro @samp{XDEPFILES -= }@dots{}. 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 @var{ARCH} host, -you can just include the generic file's name (with .o, not .c) in -@code{XDEPFILES}. Otherwise, you will need to write routines that -perform the same functions as the generic file, put them into -@code{@var{ARCH}-xdep.c}, and put @code{@var{ARCH}-xdep.o} into -@code{XDEPFILES}. These generic host support files include: - -@example - coredep.c, coredep.o -@end example - -@table @code -@item fetch_core_registers() -Support for reading registers out of a core file. This routine calls -@code{register_addr(}), see below. - -@item register_addr() -If your @code{xm-@var{ARCH}.h} file defines the macro @code{REGISTER_U_ADDR(reg)} to be the -offset within the @samp{user} struct of a register (represented as a GDB -register number), @file{coredep.c} will define the @code{register_addr()} function -and use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but -you are using the standard @code{fetch_core_registers}, you -will need to define your own version of @code{register_addr}, put it into -your @code{@var{ARCH}-xdep.c} file, and be sure @code{@var{ARCH}-xdep.o} is in the @code{XDEPFILES} list. -If you have your own @code{fetch_core_registers}, you only need to define -@code{register_addr} if your @code{fetch_core_registers} calls it. Many custom -@code{fetch_core_registers} implementations simply locate the registers -themselves. -@end table - -Files needed when the target system is an @var{ARCH} are listed in the file -@file{tconfig/@var{ARCH}}, in the @code{Makefile} macro @samp{TDEPFILES = }@dots{}. You can also -define XXXXXX in there. - -Similar generic support files for target systems are: - -@example - exec.c, exec.o: -@end example - -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. - -@node Host versus Target, , README, Top -@chapter What is considered ``host-dependent'' versus ``target-dependent''? - -The xconfig/*, xm-*.h and *-xdep.c files are for host support. The -question is, what features or aspects of a debugging or cross-debugging -environment are considered to be ``host'' support. - -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. - -Unix child process support is considered an aspect of the host. Since -when you fork on the host you are still on the host, the various macros -needed for finding the registers in the upage, running ptrace, and such -are all in the host-dependent files. - -This is still somewhat of a grey area; I (John Gilmore) didn't do the -xm- and tm- split for gdb (it was done by Jim Kingdon) so I have had to -figure out the grounds on which it was split, and make my own choices -as I evolve it. I have moved many things out of the xdep files -actually, partly as a result of BFD and partly by removing duplicated -code. - -@contents -@bye - |