From 97f3cb72753d6cf3ccedbc4eeb0dbf5c066b8e3e Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Fri, 20 Sep 1991 00:40:36 +0000 Subject: [PATCH] Reorder contents; reorganize new-host, new-target, and new-config chapters; fix minor typos; come closer to usual GNU markup conventions for @file @samp @code @var. --- gdb/doc/gdbint.texinfo | 839 +++++++++++++++++++++-------------------- 1 file changed, 438 insertions(+), 401 deletions(-) diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 3eadfce9d62..e7767aa5a89 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -50,303 +50,249 @@ are preserved on all copies. @end titlepage -@node Top, Cleanups, (dir), (dir) +@node Top, README, (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 +* README:: The README File +* New Architectures:: Defining a New Host or Target Architecture +* Config:: Adding a New Configuration * Host:: Adding a New Host * Target:: Adding a New Target -* Config:: Extending @code{configure} +* Languages:: Defining New Source Languages +* Releases:: Configuring GDB for Release * BFD support for GDB:: How BFD and GDB interface -* Host versus Target:: What features are in which files -* Symbol Reading:: Defining new symbol readers -* Languages:: Defining new source languages +* Symbol Reading:: Defining New Symbol Readers +* Cleanups:: Cleanups +* Wrapping:: Wrapping Output Lines @end menu -@node Cleanups, Wrapping, Top, Top -@chapter Cleanups +@node README, New Architectures, Top, Top +@chapter The @file{README} File -Cleanups are a structured way to deal with things that need to be done -later. When your code does something (like @code{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. +Check the @file{README} file, it often has useful information that does not +appear anywhere else in the directory. -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: +@node New Architectures, Config, README, Top +@chapter Defining a New Host or Target Architecture -@table @code -@item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); -Make a cleanup which will cause @var{function} to be called with @var{arg} -(a @code{char *}) later. The result, @var{old_chain}, is a handle that can be -passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are -going to call @code{do_cleanups} or @code{discard_cleanups} yourself, -you can ignore the result from @code{make_cleanup}. +When building support for a new host and/or target, much of the work you +need to do is handled by specifying configuration files; +@pxref{Config,,Adding a New Configuration}. Further work can be +divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and +``target=dependent'' (@pxref{Target,,Adding a New Target}). The +following discussion is meant to explain the difference between hosts +and targets. +@heading What is considered ``host-dependent'' versus ``target-dependent''? -@item do_cleanups (@var{old_chain}); -Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}. -E.g.: -@example -make_cleanup (a, 0); -old = make_cleanup (b, 0); -do_cleanups (old); -@end example -@noindent -will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain -in the cleanup chain, and will be done later unless otherwise discarded.@refill - -@item discard_cleanups (@var{old_chain}); -Same as @code{do_cleanups} except that it just removes the cleanups from the -chain and does not call the specified functions. +The @file{xconfig/*}, @file{xm-*.h} and @file{*-xdep.c} files are for +host support. Similarly, the @file{tconfig/*}, @file{tm-*.h} and +@file{*-tdep.c} files are for target support. The question is, what +features or aspects of a debugging or cross-debugging environment are +considered to be ``host'' support? -@end table +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. -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). +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 @code{ptrace}, and such +are all in the host-dependent files. +@c FIXME so what kinds of things are target support? -@node Wrapping, Releases, Cleanups, Top -@chapter Wrapping output lines +This is still somewhat of a grey area; I (John Gilmore) didn't do the +@file{xm-*} and @file{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. -Output that goes through @code{printf_filtered} or @code{fputs_filtered} or -@code{fputs_demangled} needs only to have calls to @code{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 @code{wrap_here} is an indentation string which is printed -@emph{only} if the line breaks there. This argument is saved away and used -later. It must remain valid until the next call to @code{wrap_here} or -until a newline has been printed through the @code{*_filtered} functions. -Don't pass in a local variable and then return! +@node Config, Host, New Architectures, Top +@chapter Adding a New Configuration -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. +Most of the work in making GDB compile on a new machine is in specifying +the configuration of the machine. This is done in a dizzying variety of +header files and configuration scripts, which we hope to make more +sensible soon. Let's say your new host is called an @var{xxx} (e.g. +@samp{sun4}), and its full three-part configuration name is +@code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In +particular: + +At the top level, edit @file{config.sub} and add @var{xarch}, +@var{xvend}, and @var{xos} to the lists of supported architectures, +vendors, and operating systems near the bottom of the file. Also, add +@var{xxx} as an alias that maps to +@code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by +running -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. +@example +./config.sub @var{xxx} +@end example +@noindent +and +@example +./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}} +@end example +@noindent +which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}} +and no error messages. +Then edit @file{include/sysdep.h}. Add a new @code{#define} for +@samp{@var{xxx}_SYS}, with a numeric value not already in use. Add a +new section that says -@node Releases, README, Wrapping, Top -@chapter Configuring GDB for release +@example +#if HOST_SYS==@var{xxx}_SYS +#include +#endif +@end example +Now create a new file @file{include/sys/h-@var{xxx}.h}. Examine the +other @file{h-*.h} files as templates, and create one that brings in the +right include files for your system, and defines any host-specific +macros needed by GDB. -GDB should be released after doing @samp{./configure 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. +Now, go to the @file{bfd} directory and edit @file{bfd/configure.in}. +Add shell script code to recognize your +@code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set +@code{bfd_host} to @var{xxx} when you recognize it. Now create a file +@file{bfd/config/hmake-@var{xxx}}, which includes the line: -@samp{./configure none} is also a good way to rebuild the top level Makefile -after changing Makefile.in, alldeps.mak, etc. +@example +HDEFINES=-DHOST_SYS=@var{xxx}_SYS +@end example -@emph{TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION} -@file{gdb.texinfo} is currently marked up using the texinfo-2 macros, -which are not yet a default for anything (but we have to start using -them sometime). +(If you have the binary utilities in the same tree, you'll have to do +the same thing to in the @file{binutils} directory as you've done in the +@file{bfd} directory.) + +It's likely that the @file{libiberty} and @file{readline} directories +won't need any changes for your configuration, but if they do, you can +change the @file{configure.in} file there to recognize your system and +map to an @file{hmake-@var{xxx}} file. Then add @file{hmake-@var{xxx}} +to the @file{config/} subdirectory, to set any makefile variables you +need. The only current options in there are things like @samp{-DSYSV}. + +Aha! Now to configure GDB itself! You shouldn't edit the +@code{configure} script itself to add hosts or targets; instead, edit +the script fragments in the file @code{configure.in}. Modify +@file{gdb/configure.in} to recognize your system and set @code{gdb_host} +to @var{xxx}, and (unless your desired target is already available) also +set @code{gdb_target} to something appropriate (for instance, +@var{xxx}). To handle new hosts, modify the segment after the comment +@samp{# per-host}; to handle new targets, modify after @samp{# +per-target}. +@c Would it be simpler to just use different per-host and per-target +@c *scripts*, and call them from {configure} ? -For making paper, the only thing this implies is the right generation of -texinfo.tex needs to be included in the distribution. +Then fold your changes into the @code{configure} script by using the +@code{+template} option, and specifying @code{configure} itself as the +template: +@example +configure +template=configure +@end example +@c If "configure" is the only workable option value for +template, it's +@c kind of silly to insist that it be provided. If it isn't, somebody +@c please fill in here what are others... (then delete this comment!) -For making info files, however, rather than duplicating the texinfo2 -distribution, generate gdb.texinfo locally, and include the files -gdb.info* in the distribution. Note the plural; -@samp{M-x texinfo-format-buffer} will split the document into one overall file -and five or so include files. +Finally, you'll need to specify and define the host- and +target-dependent files used for your configuration; the next two +chapters discuss those. -@node README, New Architectures, Releases, Top -@chapter The README file +@node Host, Target, Config, Top +@chapter Adding a New Host -Check the README file, it often has useful information that does not -appear anywhere else in the directory. +Once you have specified a new configuration for your host +(@pxref{Config,,Adding a New Configuration}), there are two remaining +pieces to making GDB work on a new machine. First, you have to make it +host on the new machine (compile there, handle that machine's terminals +properly, etc). If you will be cross-debugging to some other kind of +system that's already supported, you are done. +If you want to use GDB to debug programs that run on the new machine, +you have to get it to understand the machine's object files, symbol +files, and interfaces to processes. @pxref{Target}. +Add a file @file{gdb/xconfig/@var{xxx}} which specifies whatever object +files are needed as the makefile macro @samp{XDEPFILES=@dots{}}. In the +same file, specify the header file to describe @var{xxx} as +@samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC}, +@samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS}, +etc. in there; see @file{Makefile.in}. -@node New Architectures, Host, README, Top -@chapter Defining a new host or target architecture +Create @file{gdb/xm-@var{xxx}.h} with the appropriate @code{#define}s +for your system (crib from existing @file{xm-*.h} files). +There are some ``generic'' versions of routines that can be used by +various host systems. These can be customized in various ways by macros +defined in your @file{xm-@var{xxx}.h} file. If these routines work for +the @var{xxx} host, you can just include the generic file's name (with +@samp{.o}, not @samp{.c}) in @code{XDEPFILES}. -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. +Otherwise, if your machine needs custom support routines, you will need +to write routines that perform the same functions as the generic file. +Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o} +into @code{XDEPFILES}. -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{}. The header file that defines the host system should be -called xm-@var{ARCH}.h, and should be specified as the value of @samp{XM_FILE=} -in @file{xconfig/@var{ARCH}}. -You can also define @samp{CC}, @samp{REGEX} and @samp{REGEX1}, -@samp{SYSV_DEFINE}, @samp{XM_CFLAGS}, etc in there; see @file{Makefile.in}. +@subheading Generic Host Support Files -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: +@table @code -@example - coredep.c, coredep.o -@end example +@item infptrace.c +@code{ptrace} support. -@table @code -@item fetch_core_registers() +@item coredep.c: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 +@item coredep.c:register_addr() +If your @code{xm-@var{xxx}.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.@refill +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{xxx}-xdep.c} file, and be sure @code{@var{xxx}-xdep.o} is in +the @code{XDEPFILES} list. If you have your own +@code{fetch_core_registers()}, you may not need a separate +@code{register_addr()}. Many custom @code{fetch_core_registers()} +implementations simply locate the registers themselves.@refill @end table -Object files needed when the target system is an @var{ARCH} are listed in -the file @file{tconfig/@var{ARCH}}, in the Makefile macro @samp{TDEPFILES -= }@dots{}. The header file that defines the target system should be -called tm-@var{ARCH}.h, and should be specified as the value of @samp{TM_FILE} -in @file{tconfig/@var{ARCH}}. -You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, and @samp{TM_CDEPS} -in there; see @file{Makefile.in}. - -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, Target, New Architectures, Top -@chapter Adding a New Host - -There are two halves to making GDB work on a new machine. First, -you have to make it host on the new machine (compile there, handle -that machine's terminals properly, etc). If you will be cross-debugging -to some other kind of system, you are done. - -(If you want to use GDB to debug programs that run on the new machine, -you have to get it to understand the machine's object files, symbol -files, and interfaces to processes. @pxref{Target}.) - -Most of the work in making GDB compile on a new machine is in specifying -the configuration of the machine. This is done in a dizzying variety -of header files and configuration scripts, which we hope to make more -sensible soon. Let's say your new host is called an XXX (e.g. sun4), -and its full three-part configuration name is XARCH-XVEND-XOS (e.g. -sparc-sun-sunos4). In particular: - -At the top level, edit @file{config.sub} and add XARCH, XVEND, and -XOS to the lists of supported architectures, vendors, and operating systems -near the bottom of the file. Also, add XXX as an alias that maps to -XARCH-XVEND-XOS. You can test your changes by running - -@example -./config.sub XXX -@end example -@noindent -and -@example -./config.sub XARCH-XVEND-XOS -@end example -@noindent -which should both respond with XARCH-XVEND-XOS and no error messages. - -Then edit @file{include/sysdep.h}. Add a new #define for XXX_SYS, with -a numeric value not already in use. Add a new section that says - -@example -#if HOST_SYS==XXX_SYS -#include -#endif -@end example - -Now create a new file @file{include/sys/h-XXX.h}. Examine the other -h-*.h files as templates, and create one that brings in the right include -files for your system, and defines any host-specific macros needed by -GDB. - -Now, go to the bfd directory and edit @file{bfd/configure.in}. Add shell -script code to recognize your XARCH-XVEND-XOS configuration, and set -bfd_host to XXX when you recognize it. Now create a file -@file{bfd/config/hmake-XXX}, which includes the line: - -@example -HDEFINES=-DHOST_SYS=XXX_SYS -@end example +Object files needed when the target system is an @var{xxx} are listed +in the file @file{tconfig/@var{xxx}}, in the makefile macro +@samp{TDEPFILES = }@dots{}. The header file that defines the target +system should be called @file{tm-@var{xxx}.h}, and should be specified +as the value of @samp{TM_FILE} in @file{tconfig/@var{xxx}}. You can +also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, and @samp{TM_CDEPS} in +there; see @file{Makefile.in}. -(If you have the binutils in the same tree, you'll have to do the same -thing to in the binutils directory as you've done in the bfd directory.) - -It's likely that the libiberty and readline directories won't need any -changes for your configuration, but if they do, you can change the -@file{configure.in} file there to recognize your system and map to an -hmake-XXX file. Then add @file{hmake-XXX} to the @file{config/} subdirectory, -to set any makefile variables you need. The only current options -in there are things like -DSYSV. - -Aha! Now to configure GDB itself! Modify @file{gdb/configure.in} to -recognize your system and set gdb_host to XXX. Add a file -@file{gdb/xconfig/XXX} which specifies XDEPFILES=(whatever is needed), -and XM_FILE= xm-XXX.h. Create @file{gdb/xm-XXX.h} with the appropriate -#define's for your system (crib from existing xm-*.h files). -If your machine needs custom support routines, you can put them in -a file @file{gdb/XXX-xdep.c}, and add XXX-xdep.o to the XDEPFILES= -line. If not, you can use the generic routines for ptrace support -(infptrace.o) and core files (coredep.o). These can be customized -in various ways by macros defined in your @file{xm-XXX.h} file. - -Now, from the top level (above bfd, gdb, etc), run: +Now, from the top level (above @file{bfd}, @file{gdb}, etc), run: @example ./configure -template=./configure @end example This will rebuild all your configure scripts, using the new -configure.in files that you modified. (You can also run this command +@file{configure.in} files that you modified. (You can also run this command at any subdirectory level.) You are now ready to try configuring GDB to compile for your system. Do: @example -./configure XXX +target=vxworks960 +./configure @var{xxx} +target=vxworks960 @end example This will configure your system to cross-compile for VxWorks on the Intel 960, which is probably not what you really want, but it's a test case that works at this stage. (You haven't set up to be -able to debug programs that run @emph{on} XXX yet.) +able to debug programs that run @emph{on} @var{xxx} yet.) If this succeeds, you can try building it all with: @@ -355,88 +301,222 @@ make @end example Good luck! Comments and suggestions about this section are particularly -welcome; send them to bug-gdb@@prep.ai.mit.edu. - -When hosting GDB on a new operating system, to make it possible -to debug core files, you will need to either -write specific code for parsing your OS's core files, or customize -bfd/trad-core.c. First, use whatever #include files your machine uses -to define the struct of registers that is accessible (possibly in the -upage) in a core file (rather than ), and an include -file that defines whatever header exists on a core file (e.g. the -u-area or a "struct core"). Then modify @samp{trad_unix_core_file_p} -to use these values to set up the section information for the data -segment, stack segment, any other segments in the core file (perhaps -shared library contents or control information), "registers" segment, -and if there are two discontiguous sets of registers (e.g. integer and -float), the "reg2" segment. This section information basically -delimits areas in the core file in a standard way, which the -section-reading routines in BFD know how to seek around in. - -Then back in GDB, you need a matching routine called fetch_core_registers. -If you can use the generic one, it's in core-dep.c; if not, it's in -your foobar-xdep.c file. It will be passed a char pointer -to the entire "registers" segment, its length, and a zero; or a char -pointer to the entire "regs2" segment, its length, and a 2. The +welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}. + +When hosting GDB on a new operating system, to make it possible to debug +core files, you will need to either write specific code for parsing your +OS's core files, or customize @file{bfd/trad-core.c}. First, use +whatever @code{#include} files your machine uses to define the struct of +registers that is accessible (possibly in the u-area) in a core file +(rather than @file{machine/reg.h}), and an include file that defines whatever +header exists on a core file (e.g. the u-area or a @samp{struct core}). Then +modify @code{trad_unix_core_file_p()} to use these values to set up the +section information for the data segment, stack segment, any other +segments in the core file (perhaps shared library contents or control +information), ``registers'' segment, and if there are two discontiguous +sets of registers (e.g. integer and float), the ``reg2'' segment. This +section information basically delimits areas in the core file in a +standard way, which the section-reading routines in BFD know how to seek +around in. + +Then back in GDB, you need a matching routine called @code{fetch_core_registers()}. +If you can use the generic one, it's in @file{core-dep.c}; if not, it's in +your @file{@var{xxx}-xdep.c} file. It will be passed a char pointer +to the entire ``registers'' segment, its length, and a zero; or a char +pointer to the entire ``regs2'' segment, its length, and a 2. The routine should suck out the supplied register values and install them into -gdb's "registers" array. (@xref{New Architectures} +GDB's ``registers'' array. (@xref{New Architectures} for more info about this.) -@node Target, Config, Host, Top + +@node Target, Languages, Host, Top @chapter Adding a New Target +For a new target called @var{ttt}, first specify the configuration as +described in @ref{Config,,Adding a New Configuration}. If your new +target is the same as your new host, you've probably already done that. + +Add a file @file{gdb/tconfig/@var{ttt}} which specifies whatever object +files are needed as the makefile macro @samp{TDEPFILES=@dots{}}. In the +same file, specify the header file to describe @var{ttt} as +@samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{CC}, +@samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS}, +etc. in there; see @file{Makefile.in}. + +Create @file{gdb/tm-@var{ttt}.h} with the appropriate @code{#define}s +for your system (crib from existing @file{tm-*.h} files). + When adding support for a new target machine, there are various areas of support that might need change, or might be OK. +The file @file{exec.c} 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 +target should be able to use the generic exec.c rather than its +own custom code. + If you are using an existing object file format (a.out or COFF), there is probably little to be done. See @file{bfd/doc/bfd.texinfo} for more information on writing new a.out or COFF versions. If you need to add a new object file format, you are beyond the scope of this document right now. Look at the structure of the a.out -and COFF support, build a transfer vector (xvec) for your new format, +and COFF support, build a transfer vector (@code{xvec}) for your new format, and start populating it with routines. Add it to the list in @file{bfd/targets.c}. If you are adding a new existing CPU chip (e.g. m68k family), you'll -need to define an XARCH-opcode.h file, a tm-XARCH.h file that gives -the basic layout of the chip (registers, stack, etc), probably -an XARCH-tdep.c file that has support routines for tm-XARCH.h, etc. - -If you are adding a new operating system for an existing CPU chip, -add a tm-XOS.h file that describes the operating system facilities -that are unusual (extra symbol table info; the breakpoint -instruction needed; etc). Then write a @file{tm-XARCH-XOS.h} -that just #include's tm-XARCH.h and tm-XOS.h. (Now that we have +need to define an @file{@var{xarch}-opcode.h} file, a +@file{tm-@var{xarch}.h} file that gives the basic layout of the chip +(registers, stack, etc), probably an @file{@var{xarch}-tdep.c} file that +has support routines for @file{tm-@var{xarch}.h}, etc. + +If you are adding a new operating system for an existing CPU chip, add a +@file{tm-@var{xos}.h} file that describes the operating system +facilities that are unusual (extra symbol table info; the breakpoint +instruction needed; etc). Then write a +@file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s +@file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have three-part configuration names, this will probably get revised to -separate the OS configuration from the ARCH configuration. FIXME.) - -@node Config, BFD support for GDB, Target, Top -@chapter Extending @code{configure} -Once you have added a new host, target, or both, you'll also need to -extend the @code{configure} script to recognize the new configuration -possibilities. - -You shouldn't edit the @code{configure} script itself to add hosts or -targets; instead, edit the script fragments in the file -@code{configure.in}. To handle new hosts, modify the segment after the -comment @samp{# per-host}; to handle new targets, modify after @samp{# -per-target}. -@c Would it be simpler to just use different per-host and per-target -@c *scripts*, and call them from {configure} ? +separate the @var{xos} configuration from the @var{xarch} +configuration.) + + +@node Languages, Releases, Target, Top +@chapter Adding a Source Language to GDB + +To add other languages to GDB's expression parser, follow the following steps: + +@table @emph +@item Create the expression parser. + +This should reside in a file @file{@var{lang}-exp.y}. Routines for building +parsed expressions into a @samp{union exp_element} list are in @file{parse.c}. + +Since we can't depend upon everyone having Bison, the following lines +@emph{must} be included at the top of the YACC parser: -Then fold your changes into the @code{configure} script by using the -@code{+template} option, and specifying @code{configure} itself as the -template: @example -configure +template=configure +#define yyparse @var{lang}_parse +#define yylex @var{lang}_lex +#define yyerror @var{lang}_error +#define yylval @var{lang}_lval +#define yychar @var{lang}_char +#define yydebug @var{lang}_debug +#define yypact @var{lang}_pact +#define yyr1 @var{lang}_r1 +#define yyr2 @var{lang}_r2 +#define yydef @var{lang}_def +#define yychk @var{lang}_chk +#define yypgo @var{lang}_pgo +#define yyact @var{lang}_act +#define yyexca @var{lang}_exca @end example -@c If "configure" is the only workable option value for +template, it's -@c kind of silly to insist that it be provided. If it isn't, somebody -@c please fill in here what are others... (then delete this comment!) -@node BFD support for GDB, Host versus Target, Config, Top -@chapter Binary File Descriptor library support for GDB +This will prevent name conflicts between the various parsers. + +@item 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 @file{expression.h}. Add support +code for these operations in @code{eval.c:evaluate_subexp()}. Add cases +for new opcodes in two functions from @file{parse.c}: +@code{prefixify_subexp()} and @code{length_of_subexp()}. These compute +the number of @code{exp_element}s that a given operation takes up. + +@item Update some existing code + +Add an enumerated identifier for your language to the enumerated type +@code{enum language} in @file{defs.h}. + +Update the routines in @file{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 @file{language.c} is the code that updates the variable +@code{current_language}, and the routines that translate the +@code{language_@var{lang}} enumerated identifier into a printable +string. + +Update the function @code{_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 @code{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 @code{expprint.c:print_subexp()} to handle any new +expression opcodes you have added to @file{expression.h}. Also, add the +printed representations of your operators to @code{op_print_tab}. + +@item Add a place of call + +Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in +@code{parse.c:parse_exp_1()}. + +@item Use macros to trim code + +The user has the option of building GDB for some or all of the +languages. If the user decides to build GDB for the language +@var{lang}, then every file dependent on @file{language.h} will have the +macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to +leave out large routines that the user won't need if he or she is not +using your language. + +Note that you do not need to do this in your YACC parser, since if GDB +is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the +compiled form of your parser) is not linked into GDB at all. + +See the file @file{configure.in} for how GDB is configured for different +languages. + +@item Edit @file{Makefile.in} + +Add dependencies in @file{Makefile.in}. Make sure you update the macro +variables such as @code{HFILES} and @code{OBJS}, otherwise your code may +not get linked in, or, worse yet, it may not get @code{tar}red into the +distribution! +@end table + + +@node Releases, BFD support for GDB, Languages, Top +@chapter Configuring GDB for Release + +GDB should be released after doing @samp{./configure none} in the top +level directory. This will leave a makefile there, but no @file{tm-*} +or @file{xm-*} files. The makefile is needed, for example, for +@samp{make gdb.tar.Z}@dots{} If you have @file{tm-*} or @file{xm-*} +files in the main source directory, C's include rules cause them to be +used in preference to @file{tm-*} and @file{xm-*} files in the +subdirectories where the user will actually configure and build the +binaries. + +@samp{./configure none} is also a good way to rebuild the top level @file{Makefile} +after changing @file{Makefile.in}, @file{alldeps.mak}, etc. + +@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION + +@file{gdb.texinfo} is currently marked up using the texinfo-2 macros, +which are not yet a default for anything (but we have to start using +them sometime). + +For making paper, the only thing this implies is the right generation of +@file{texinfo.tex} needs to be included in the distribution. + +For making info files, however, rather than duplicating the texinfo2 +distribution, generate @file{gdb-all.texinfo} locally, and include the files +@file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will +split the document into one overall file and five or so included files. + + +@node BFD support for GDB, Symbol Reading, Releases, Top +@chapter Binary File Descriptor Library Support for GDB BFD provides support for GDB in several ways: @@ -465,33 +545,10 @@ symbols, but GDB uses BFD's cached information to find the symbols, string table, etc. @end table -The interface for symbol reading is described in @xref{Symbol Reading}. - -@node Host versus Target, Symbol Reading, BFD support for GDB, Top -@chapter What is considered ``host-dependent'' versus ``target-dependent''? +@c The interface for symbol reading is described in @ref{Symbol Reading}. -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. - - -@node Symbol Reading, Languages, Host versus Target, Top +@node Symbol Reading, Cleanups, BFD support for GDB, Top @chapter Symbol Reading GDB reads symbols from "symbol files". The usual symbol file is the @@ -516,7 +573,7 @@ prefix. The functions supplied by each module are: @table @code -@item XXX_symfile_init(struct sym_fns *sf) +@item @var{xxx}_symfile_init(struct sym_fns *sf) Called from @code{symbol_file_add} when we are about to read a new symbol file. This function should clean up any internal state @@ -526,34 +583,34 @@ 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 @code{XXX_symfile_init} is a newly allocated +The argument to @code{@var{xxx}_symfile_init} is a newly allocated @code{struct sym_fns} whose @code{bfd} field contains the BFD for the new symbol file being read. Its @code{private} field has been zeroed, and can be modified as desired. Typically, a struct of private information will be @code{malloc}'d, and a pointer to it will be placed in the @code{private} field. -There is no result from @code{XXX_symfile_init}, but it can call +There is no result from @code{@var{xxx}_symfile_init}, but it can call @code{error} if it detects an unavoidable problem. -@item XXX_new_init() +@item @var{xxx}_new_init() Called from @code{symbol_file_add} when discarding existing symbols. This function need only handle the symbol-reading module's internal state; the symbol table data structures visible to the rest of GDB will be discarded by @code{symbol_file_add}. It has no arguments and no result. -It may be called after @code{XXX_symfile_init}, if a new symbol +It may be called after @code{@var{xxx}_symfile_init}, if a new symbol table is being read, or may be called alone if all symbols are simply being discarded. -@item XXX_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) +@item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) Called from @code{symbol_file_add} to actually read the symbols from a symbol-file into a set of psymtabs or symtabs. @code{sf} points to the struct sym_fns originally passed to -@code{XXX_sym_init} for possible initialization. @code{addr} is the +@code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the offset between the file's specified start address and its true address in memory. @code{mainline} is 1 if this is the main symbol table being read, and 0 if a secondary symbol file (e.g. shared library or @@ -561,12 +618,12 @@ dynamically loaded file) is being read.@refill @end table In addition, if a symbol-reading module creates psymtabs when -XXX_symfile_read is called, these psymtabs will contain a pointer to -a function @code{XXX_psymtab_to_symtab}, which can be called from +@var{xxx}_symfile_read is called, these psymtabs will contain a pointer to +a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from any point in the GDB symbol-handling code. @table @code -@item XXX_psymtab_to_symtab (struct partial_symtab *pst) +@item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst) Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB macro) if the psymtab has not already been read in and had its @@ -577,100 +634,80 @@ pointer to the new corresponding symtab, or zero if there were no symbols in that part of the symbol file. @end table -@node Languages, , Host versus Target, Top -@chapter Adding a Source Language to GDB - -To add other languages to GDB's expression parser, follow the following steps: - -@table @emph -@item Create the expression parser. - -This should reside in a file called -exp.y. Routines for building -parsed expressions into a (struct exp_elt) list are in parser-code.c. - -Since we can't depend upon everyone having Bison, the following lines -@emph{musg} be included at the top of the YACC parser: - -@example -#define yyparse _parse -#define yylex _lex -#define yyerror _error -#define yylval _lval -#define yychar _char -#define yydebug _debug -#define yypact _pact -#define yyr1 _r1 -#define yyr2 _r2 -#define yydef _def -#define yychk _chk -#define yypgo _pgo -#define yyact _act -#define yyexca _exca -@end example -This will prevent name conflicts between the various parsers. - -@item Add any evaluation routines, if necessary +@node Cleanups, Wrapping, Symbol Reading, Top +@chapter Cleanups -If you need new opcodes (that represent the operations of the language), -add them to the ennumerated type in expression.h. -Add support code for these operations in eval.c:evaluate_subexp() -Add cases for new opcodes in parser-code.c:prefixify_subexp() and -parser-code.c:length_of_subexp(). These compute the number of -exp_elements that a given operation takes up. +Cleanups are a structured way to deal with things that need to be done +later. When your code does something (like @code{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. -@item Update some existing code +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. -Add an ennumerated identifier for your language to the ennumerated type -enum language in symtab.h. +Syntax: -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. +@table @code +@item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); +Make a cleanup which will cause @var{function} to be called with @var{arg} +(a @code{char *}) later. The result, @var{old_chain}, is a handle that can be +passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are +going to call @code{do_cleanups} or @code{discard_cleanups} yourself, +you can ignore the result from @code{make_cleanup}. -Also included in language.c is the code that updates the variable -working_lang, and the routines that translate the language_ -ennumerated identifier into a printable string. -Update the function _intitialize_language to include your language. This -function picks the default language upon startup, so is dependent upon -which languages that GDB is built for. +@item do_cleanups (@var{old_chain}); +Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}. +E.g.: +@example +make_cleanup (a, 0); +old = make_cleanup (b, 0); +do_cleanups (old); +@end example +@noindent +will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain +in the cleanup chain, and will be done later unless otherwise discarded.@refill -Update 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. +@item discard_cleanups (@var{old_chain}); +Same as @code{do_cleanups} except that it just removes the cleanups from the +chain and does not call the specified functions. -Add helper code to expprint.c:print_subexp() to handle any new expression -opcodes you have added to expression.h. Also, add the printed -representations of your operators to op_print_tab. +@end table -@item Add a place of call +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). -Add a call to _parse() and _error in parse.c:parse_exp_1(). -@item Use macros to trim code +@node Wrapping, , Cleanups, Top +@chapter Wrapping Output Lines -The user has the option of building GDB for some or all of the languages. -If the user decides to build GDB for the language , then every file -dependent on language.h will have the macro _LANG_ defined in it. -Use #ifdefs to leave out large routines that the user won't need if -he/she is not using your language. +Output that goes through @code{printf_filtered} or @code{fputs_filtered} or +@code{fputs_demangled} needs only to have calls to @code{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. -Note that you do not need to do this in your YACC parser, since if GDB is -not build for , then -exp.tab.o (the compiled form of your -parser) is not linked into GDB at all. +The argument to @code{wrap_here} is an indentation string which is printed +@emph{only} if the line breaks there. This argument is saved away and used +later. It must remain valid until the next call to @code{wrap_here} or +until a newline has been printed through the @code{*_filtered} functions. +Don't pass in a local variable and then return! -See the file configure.in for how GDB is configured for different languages. +It is usually best to call @code{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. -@item Edit Makefile.in +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 (``@code{printf}'') output. Symbol reading routines that print +warnings are a good example. -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 tarred into the distribution! @contents @bye -- 2.30.2