Adding a New Target

For a new target called ttt, first specify the configuration as described in section Adding a New Configuration. If your new target is the same as your new host, you've probably already done that.

A variety of files specify attributes of the GDB target environment:

`gdb/config/arch/ttt.mt'

Contains a Makefile fragment specific to this target. Specifies what object files are needed for target ttt, by defining `TDEPFILES=...'. Also specifies the header file which describes ttt, by defining `TM_FILE= tm-ttt.h'. You can also define `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', and other Makefile variables here; see `Makefile.in'.

`gdb/config/arch/tm-ttt.h'

(`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 `tm-*.h' files when building a new one.

`gdb/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 `tm-ttt.h' become very complicated, so they are implemented as functions here instead, and the macro is simply defined to call the function.

`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.

`gdb/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 `arch-pinsn.c' rather than `ttt-pinsn.c'.

`gdb/arch-opcode.h'

Contains some large initialized data structures describing the target machine's instructions. This is a bit strange for a `.h' file, but it's OK since it is only included in one place. `arch-opcode.h' is shared between the debugger and the assembler, if the GNU assembler has been ported to the target machine.

`gdb/config/arch/tm-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 `tm-xxx.h'. It can be shared among many targets that use the same processor.

`gdb/arch-tdep.c'

Similarly, there are often common subroutines that are shared by all target machines that use this particular architecture.

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 `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 must first add it to BFD. This is beyond the scope of this document right now. Basically you must build a transfer vector (of type bfd_target), which will mean writing all the required routines, and add it to the list in `bfd/targets.c'.

You must then arrange for the BFD code to provide access to the debugging symbols. Generally GDB will have to call swapping routines from BFD and a few other BFD internal routines to locate the debugging information. As much as possible, GDB should not depend on the BFD internal data structures.

For some targets (e.g., COFF), there is a special transfer vector used to call swapping routines, since the external data structures on various platforms have different sizes and layouts. Specialized routines that will only ever be implemented by one object file format may be called directly. This interface should be described in a file `bfd/libxxx.h', which is included by GDB.

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 `tm-xarch-xos.h' that just #includes `tm-xarch.h' and `tm-xos.h'. (Now that we have three-part configuration names, this will probably get revised to separate the xos configuration from the xarch configuration.)