Howto: Porting the GNU Debugger

The main user guide for GDB [3] provides a great deal of context about how GDB is intended to work.

The GDB Internals document [4] is essential reading before and during any porting exercise. It is not complete, nor is it always up to date, but it provides the first place to look for explanation of what a particular function does.

GDB relies on a separate specification of the Binary file format; for each architecture. That has its own comprehensive user guide [5].

The main GDB code base is generally well commented, particularly in the headers for the major interfaces. Inevitably this must be the definitive place to find out exactly how a particular function behaves.

The files making up the port for the OpenRISC 1000 are comprehensively commented, and can be processed with Doxygen [7]. Each function's behavior, its parameters and any return value is described.

The main GDB website is at sourceware.org/gdb/. It is supplemented by the less formal GDB Wiki at sourceware.org/gdb/wiki/.

The GDB developer community communicate through the GDB mailing lists and using IRC chat. These are always good places to find solutions to problems.

The main mailing list for discussion is gdb@sourceware.org, although for detailed understanding, the patches mailing list, gdb-patches@sourceware.org. See the main GDB website for details of subscribing to these mailing lists.

IRC is channel #gdb on irc.freenode.net.

BFD is a package which allows applications to use the same routines to operate on object files whatever the object file format. A new object file format can be supported simply by creating a new BFD back end and adding it to the library.

The BFD library back end creates a number of data structures describing the data held in a particular type of object file. Ultimately a unique enumerated constant (of type enum bfd_architecture) is defined for each individual architecture. This constant is then used to access the various data structures associated with the BFD of the particular architecture.

In the case of the OpenRISC 1000, 32-bit implementation (which may be a COFF or ELF binary), the enumerated constant is bfd_arch_or32.

BFD is part of the binutils package. A binutils implementation must be provided for any architecture intending to support the GNU tool chain.

The OpenRISC 1000 is supported by the GNU tool chain. BFD back ends already exist which are suitable for use with 32-bit OpenRISC 1000 images in ELF or COFF format as used with either the RTEMS or Linux operating systems.

Any architecture to be debugged by GDB is described in a struct gdbarch. When an object file is to be debugged, GDB will select the correct struct gdbarch using information about the object file captured in its BFD.

The data in struct gdbarch facilitates both the symbol side processing (for which it also uses the BFD information) and the target side processing (in combination with the frame and target operation information).

struct gdbarch is a mixture of data values (number of bytes in an integer for example) and functions to perform standard operations (e.g. to print the registers). The major functional groups are:

An architecture will need to specify most of the contents of struct gdbarch, for which a set of functions (all starting set_gdbarch_) are provided. Defaults are provided for all entries, and in a small number of cases these will be suitable.

Analysis of the stack frames of executing programs is complex with different approaches needed for different circumstances. A set of functions to identify stack frames and analyze their contents is associated with each struct gdbarch.

A set of utility functions are provided to access the members of struct gdbarch. Element xyz of a struct gdbarch pointed to by g may be accessed by using gdbarch_xyz (g, ...). This will check, using gdb_assert that g is defined, and in the case of functions that g->x is not NULL and return either the value g->xyz (for values) or the result of calling g->xyz (...) (for functions). This saves the user testing for existence before each function call, and ensures any errors are handled cleanly.

A set of operations is required to access a program using the target architecture described by struct gdbarch in order to implement the target side functionality. For any given architecture there may be multiple ways of connecting to the target, specified using the GDB target command. For example with the OpenRISC 1000 architecture, the connection may be directly to a JTAG interface connected through the host computer's parallel port, or through the OpenRISC 1000 Remote JTAG Protocol over TCP/IP.

These target operations are described in a struct target_ops. As with struct gdbarch this comprises a mixture of data and functions. The major functional groups are:

As with struct gdbarch, defaults are provided for the struct target_ops values. In many cases these are sufficient, so need not be provided.

GDB's command handling is intended to be extensible. A set of functions (defined in cli-decode.h) provide that extensibility.

GDB groups its commands into a number of command lists (of struct cmd_list_element), pointed to by a number of global variables (defined in cli-cmds.h). Of these, cmdlist is the list of all defined commands. Separate lists define sub-commands of various top level commands. For example infolist is the list of all info sub-commands.

Commands are also classified according the the area they address, for example commands that provide support, commands that examine data, commands for file handling etc. These classes are specified by enum command_class, defined in command.h. These classes provide the top level categories in which help will be given.

The first argument to the architecture initialization function is a struct gdbarch_info containing all the known information about this architecture (deduced from the BFD enumeration provided to gdbarch_register). The second argument is a list of the currently defined architectures within GDB.

The lookup is done using gdbarch_list_lookup_by_info. It is passed the list of existing architectures and the struct gdbarch_info (possibly updated) and returns the first matching architecture it finds, or NULL if none are found. If an architecture is found, the initialization function can finish, returning the found architecture as result.

struct gdbarch_info
{
  const struct bfd_arch_info *bfd_arch_info;
  int                         byte_order;
  bfd                        *abfd;
  struct gdbarch_tdep_info   *tdep_info;
  enum gdb_osabi              osabi;
  const struct target_desc   *target_desc;
};
	    

If no architecture is found, then a new architecture must be created, by calling gdbarch_alloc using the supplied struct gdbarch_info and and any additional custom target specific information in a struct gdbarch_tdep.

The newly created struct gdbarch must then be populated. Although there are default values, in most cases they are not what is required. For each element, X, there is a corresponding accessor function to set the value of that element, set_gdbarch_X.

The following sections identify the main elements that should be set in this way. This is not the complete list, but represents the functions and elements that must commonly be specified for a new architecture. Many of the functions are described in the header file, gdbarch.h and many may be found in the GDB Internals document [4].

struct gdbarch *gdbarch_alloc (const struct gdbarch_info *info,
                               struct gdbarch_tdep       *tdep);
	    

A set of values in struct gdbarch define how different data types are represented within the architecture.

A set of function members of struct gdbarch define aspects of the architecture and its ABI. For some of these functions, defaults are provided which will be suitable for most architectures.

GDB considers registers to be a set with members numbered linearly from 0 upwards. The first part of that set corresponds to real physical registers, the second part to any "pseudo-registers". Pseudo-registers have no independent physical existence, but are useful representations of information within the architecture. For example the OpenRISC 1000 architecture has up to 32 general purpose registers, which are typically represented as 32-bit (or 64-bit) integers. However it could be convenient to define a set of pseudo-registers, to show the GPRs represented as floating point registers.

For any architecture, the implementer will decide on a mapping from hardware to GDB register numbers. The registers corresponding to real hardware are referred to as raw registers, the remaining registers are pseudo-registers. The total register set (raw and pseudo) is called the cooked register set.

GDB needs to understand the stack on which local (automatic) variables are stored. The area of the stack containing all the local variables for a function invocation is known as the stack frame for that function (or colloquially just as the "frame"). In turn the function that called the function will have its stack frame, and so on back through the chain of functions that have been called.

Almost all architectures have one register dedicated to point to the end of the stack (the stack pointer). Many have a second register which points to the start of the currently active stack frame (the frame pointer). The specific arrangements for an architecture are a key part of the ABI.

A diagram helps to explain this. Here is a simple program to compute factorials:

 1:   #include <stdio.h>
 2:   
 3:   int fact( int  n )
 4:   {
 5:     if( 0 == n ) {
 6:       return 1;
 7:     }
 8:     else {
 9:       return n * fact( n - 1 );
10:     }
11:   }
12:   
13:   main()
14:   {
15:     int  i;
16:   
17:     for( i = 0 ; i < 10 ; i++ ) {
18:       int   f = fact( i );
19:       printf( "%d! = %d\n", i, f );
20:     }
21:   }
	  

Consider the state of the stack when the code reaches line 6 after the main program has called fact (3). The chain of function calls will be main, fact (3), fact (2), fact (1) and fact (0). In this example the stack is falling (as used by the OpenRISC 1000 ABI). The stack pointer (SP) is at the end of the stack (lowest address) and the frame pointer (FP) is at the highest address in the current stack frame. Figure 2.1 shows how the stack looks.

Figure 2.1.  An example stack frame

In each stack frame, offset 0 from the stack pointer is the frame pointer of the previous frame and offset 4 (this is illustrating a 32-bit architecture) from the stack pointer is the return address. Local variables are indexed from the frame pointer, with negative indexes. In the function fact, offset -4 from the frame pointer is the argument n. In the main function, offset -4 from the frame pointer is the local variable i and offset -8 from the frame pointer is the local variable f.

	Note
	This is a simplified example for illustrative purposes only. Good optimizing compilers would not put anything on the stack for such simple functions. Indeed they might eliminate the recursion and use of the stack entirely!

It is very easy to get confused when examining stacks. GDB has terminology it uses rigorously throughout. The stack frame of the function currently executing, or where execution stopped is numbered zero. In this example frame #0 is the stack frame of the call to fact (0). The stack frame of its calling function (fact(1) in this case) is numbered #1 and so on back through the chain of calls.

The main GDB data structure describing frames is struct frame_info. It is not used directly, but only via its accessor functions. struct frame_info includes information about the registers in the frame and a pointer to the code of the function with which the frame is associated. The entire stack is represented as a linked list of struct frame_info.

struct frame_unwind
{
  enum frame_type            type;
  frame_this_id_ftype       *this_id;
  frame_prev_register_ftype *prev_register;
  const struct frame_data   *unwind_data;
  frame_sniffer_ftype       *sniffer;
  frame_prev_pc_ftype       *prev_pc;
  frame_dealloc_cache_ftype *dealloc_cache;
};
	    

struct frame_base
{
  const struct frame_unwind *unwind;
  frame_this_base_ftype     *this_base;
  frame_this_locals_ftype   *this_locals;
  frame_this_args_ftype     *this_args;
};
	    

GDB has several different types of target: executable files, core dumps, executing processes etc. At any time, GDB may have several sets of target operations in use. For example target operations for use with an executing process (which can run code) might be different from the operations used when inspecting a core dump.

All the targets GDB knows about are held in a stack. GDB walks down the stack to find the set of target operations suitable for use. The stack is organized as a series of strata of decreasing importance: target operations for threads, then target operations suitable for processes, target operations to download remote targets, target operations for core dumps, target operations for executable files and at the bottom target operations for dummy targets. So GDB when debugging a running process will always select target operations from the process_stratum if available, over target operations from the file stratum, even if the target operations from the file stratum were pushed onto the stack more recently.

At any particular time, there is a current target, held in the global variable current_target. This can never be NULL—if there is no other target available, it will point to the dummy target.

target.h defines a set of convenience macros to access functions and values in the current_target. Thus current_target->to_xyz can be accessed as target_xyz.

Some targets (sets of target operations in a struct target_ops) are set up automatically by GDB—these include the operations to drive simulators (see Section 2.6 and the operations to drive the GDB Remote Serial Protocol (RSP) (see Section 2.7).

Other targets must be set up explicitly by the implementer, using the add_target function. By far the most common is the native target for native debugging of the host. Less common is to set up a non-native target, such as the JTAG target used with the OpenRISC 1000^[1].

These functions and variables provide information about the target. The first group identifies the name of the target and provides help information for the user.

The second group of variables provides information about the current state of the target.

These functions control the connection to the target. For remote targets this may mean establishing and tearing down links using protocols such as TCP/IP. For native targets, these functions will be more concerned with setting flags describing the state.

These functions transfer data to and from the target registers and memory.

For all targets, GDB can implement breakpoints and write access watchpoints in software, by inserting code in the target. However many targets provide hardware assistance for these functions which is far more efficient, and in addition may implement read access watchpoints.

These functions in struct target_ops provide a mechanism to access such functionality if it is available.

for targets capable of execution, these functions provide the mechanisms to start and stop execution.