From aeb62c7b5071ac3e4dd98d43b5a04b79744bc276 Mon Sep 17 00:00:00 2001 From: John Gilmore Date: Sat, 21 Sep 1991 01:50:26 +0000 Subject: [PATCH] Roll in information from README. --- gdb/doc/gdbint.texinfo | 132 +++++++++++++++++++++++++++++------------ 1 file changed, 93 insertions(+), 39 deletions(-) diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index e7767aa5a89..02d59d9f07f 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -81,7 +81,7 @@ 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 +``target-dependent'' (@pxref{Target,,Adding a New Target}). The following discussion is meant to explain the difference between hosts and targets. @@ -217,17 +217,31 @@ 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}. +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 +Several files control GDB's configuration for host systems: + +@table @file +@item gdb/xconfig/@var{xxx} +Specifies what object files are needed when hosting on machine @var{xxx}, +by defining the makefile macro @samp{XDEPFILES=@dots{}}. Also +specifies the header file which describes @var{xxx}, by defining @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}. - -Create @file{gdb/xm-@var{xxx}.h} with the appropriate @code{#define}s -for your system (crib from existing @file{xm-*.h} files). +@samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS}, +etc.; see @file{Makefile.in}. + +@item gdb/xm-@var{xxx}.h +(@file{xm.h} is a link to this file, created by configure). +Contains C macro definitions describing the host system environment, +such as byte order, host C compiler and library, ptrace support, +and core file structure. Crib from existing @file{xm-*.h} files +to create a new one. + +@item gdb/@var{xxx}-xdep.c +Contains any miscellaneous C code required for this machine +as a host. On some machines it doesn't exist at all. +@end table There are some ``generic'' versions of routines that can be used by various host systems. These can be customized in various ways by macros @@ -242,16 +256,20 @@ into @code{XDEPFILES}. @subheading Generic Host Support Files -@table @code +@table @file @item infptrace.c -@code{ptrace} support. +This is the low level interface to inferior processes for systems +using the Unix @code{ptrace} call in a vanilla way. -@item coredep.c: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. +@code{register_addr()}, see below. +Now that BFD is used to read core files, virtually all machines should +use @code{coredep.c}, and should just provide @code{fetch_core_registers} in +@code{@var{xxx}-xdep.c}. -@item coredep.c:register_addr() +@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), @@ -336,26 +354,66 @@ 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. +A variety of files specify attributes of the target environment: -The file @file{exec.c} defines functions for accessing files that are +@table @file +@item gdb/tconfig/@var{ttt} +Specifies what object files are needed for target @var{ttt}, by +defining the makefile macro @samp{TDEPFILES=@dots{}}. +Also specifies the header file which describes @var{ttt}, by defining +@samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{CC}, +@samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{TM_CFLAGS}, +and other Makefile variables here; see @file{Makefile.in}. + +@item gdb/tm-@var{ttt}.h +(@file{tm.h} is a link to this file, created by configure). +Contains macro definitions about the target machine's +registers, stack frame format and instructions. +Crib from existing @file{tm-*.h} files when building a new one. + +@item gdb/@var{ttt}-tdep.c +Contains any miscellaneous code required for this target machine. +On some machines it doesn't exist at all. Sometimes the macros +in @file{tm-@var{ttt}.h} become very complicated, so they are +implemented as functions here instead, and the macro is simply +defined to call the function. + +@item gdb/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. +@item gdb/@var{arch}-pinsn.c +Prints (disassembles) the target machine's instructions. +This file is usually shared with other target machines which use the +same processor, which is why it is @file{@var{arch}-pinsn.c} rather +than @file{@var{ttt}-pinsn.c}. + +@item gdb/@var{arch}-opcode.h +Contains some large initialized +data structures describing the target machine's instructions. +This is a bit strange for a @file{.h} file, but it's OK since +it is only included in one place. @file{@var{arch}-opcode.h} is shared +between the debugger and the assembler, if the GNU assembler has been +ported to the target machine. + +@item gdb/tm-@var{arch}.h +This often exists to describe the basic layout of the target machine's +processor chip (registers, stack, etc). +If used, it is included by @file{tm-@var{xxx}.h}. It can +be shared among many targets that use the same processor. + +@item gdb/@var{arch}-tdep.c +Similarly, there are often common subroutines that are shared by all +target machines that use this particular architecture. +@end table + +When adding support for a new target machine, there are various areas +of support that might need change, or might be OK. + 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. @@ -363,15 +421,9 @@ 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 (@code{xvec}) for your new format, -and start populating it with routines. Add it to the list in +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 @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 @@ -394,12 +446,14 @@ To add other languages to GDB's expression parser, follow the following steps: 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: +Since we can't depend upon everyone having Bison, and YACC produces +parsers that define a bunch of global names, the following lines +@emph{must} be included at the top of the YACC parser, to prevent +the various parsers from defining the same global names: @example #define yyparse @var{lang}_parse -#define yylex @var{lang}_lex +#define yylex @var{lang}_lex #define yyerror @var{lang}_error #define yylval @var{lang}_lval #define yychar @var{lang}_char @@ -412,10 +466,10 @@ Since we can't depend upon everyone having Bison, the following lines #define yypgo @var{lang}_pgo #define yyact @var{lang}_act #define yyexca @var{lang}_exca +#define yyerrflag @var{lang}_errflag +#define yynerrs @var{lang}_nerrs @end example -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), -- 2.30.2