From 1dbe1ef7972fbe92df39930709ba755b2a4e5f9f Mon Sep 17 00:00:00 2001 From: John Gilmore Date: Fri, 23 Aug 1991 23:13:03 +0000 Subject: [PATCH] Add info about porting to new hosts and targets. --- gdb/doc/gdbint.texinfo | 164 +++++++++++++++++++++++++++++++++++------ 1 file changed, 140 insertions(+), 24 deletions(-) diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index f22a635490f..516341f714e 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -274,30 +274,6 @@ symbols, but GDB uses BFD's cached information to find the symbols, string table, etc. @end table -When porting GDB to a new operating system, 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 xm-foobar.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} -for more info about this.) - The interface for symbol reading is described in @xref{Symbol Reading}. @node Host versus Target, Symbol Reading, BFD support for GDB, Top @@ -332,9 +308,149 @@ code. @node New Host, New Target, Host versus Target, Host versus Target @section 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{New 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 + + ./config.sub XXX +and ./config.sub XARCH-XVEND-XOS + +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 + + #if HOST_SYS==XXX_SYS + #include + #endif + +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: + + HDEFINES=-DHOST_SYS=XXX_SYS + +(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: + + ./configure -template=./configure + +This will rebuild all your configure scripts, using the new +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: + + ./configure XXX +target=vxworks960 + +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.) + +If this succeeds, you can try building it all with: + + make + +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 +routine should suck out the supplied register values and install them into +gdb's "registers" array. (@xref{New Architectures} +for more info about this.) + @node New Target, New Config, New Host, Host versus Target @section Adding a New Target +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. + +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 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 +three-part configuration names, this will probably get revised to +separate the OS configuration from the ARCH configuration. FIXME.) + @node New Config, , New Target, Host versus Target @section Extending @code{configure} Once you have added a new host, target, or both, you'll also need to -- 2.30.2