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.

The client implementation can be found in the source files remote.h and remote.c in the gdb subdirectory. These implement a set of target operations, as described in Section 2.4. Each of the standard operations is mapped into a sequence of RSP interactions with the server on the target.

RSP server implementation is a large subject in its own right, and does not form a direct part of the GDB implementation (since it is part of the target, not the debugger).

A comprehensive "Howto" has been written by Embecosm, describing the implementation techniques for RSP servers, illustrated by examples using the OpenRISC 1000 architectural simulator, Or1ksim as RSP target [2].

Figure 2.2 shows the sequence diagram for GDB start up.

Figure 2.2.  Sequence diagram for GDB start up

On start up, the GDB initialization function, gdb_init calls all the _initialize functions, including those for any architectures or remote targets.

Having initialized all the architectures, the first alphabetically is selected as the default architecture by initialize_current_architecture, and its initialization function, (by convention arch_gdbarch_init) is called.

Control returns to gdb_main, which sits in the command interpreter, waiting for commands to execute.

Figure 2.3 shows the high level sequence diagram for GDB in response to the target command.

Figure 2.3.  High level sequence diagram for the GDB target command

The target command maps directly on to the current target to_open. A typical implementation establishes physical connection to the target (for example by opening a TCP/IP link to a remote target). For a remote target, it then typically calls start_remote, which waits for the target to stop (using the current target to_wait function), determines the reason for stopping (handle_inferior_event) and then marks this as a normal stop (normal_stop).

handle_inferior_event is a central function in GDB. Whenever control is returned to GDB, via the target to_wait function, it must determine what has happened and how it should be handled. Figure 2.4 shows the behavior of handle_inferior_event in response to the target command.

Figure 2.4.  handle_inferior_event sequence diagram in response to the GDB target command

handle_inferior_event needs to establish the program counter at which execution stopped, so calls read_pc_pid. Since the program counter is a register, this causes creation of a register cache, for which the type of each register must be determined by gdbarch_register_type (a one-off exercise, since this never changes). Having determined register types, the register cache is populated with the value of the program counter by calling the current target to_fetch_registers for the relevant register.

handle_inferior_event then determines if the stop was due to a breakpoint or watchpoint. The function watchpoints_triggered uses the target target_stopped_by_watchpoint to determine if it was a watchpoint which triggered the stop.

The call to normal_stop also invokes the struct gdbarch functions, calling gdbarch_unwind_pc to establish the current program counter and and frame sniffer functions to establish the frame sniffer stack.

Figure 2.5 shows the high level sequence diagram for GDB in response to the load command. This maps to the current target's to_load function, which in most cases will end up calling the current target's to_xfer_partial function once for each section of the image to load it into memory.

Figure 2.5.  Sequence diagram for the GDB load command

The load function will capture data from the loaded file, most importantly its start address for execution.

Figure 2.6 shows the high level sequence diagram for GDB in response to the break command. This example is for the case where the target of the break is a symbol (i.e. a function name) in the target executable.

Figure 2.6.  Sequence diagram for the GDB break command

Most of the action with breakpoints occurs when the program is set running, at which any active breakpoints are installed. However for any break command, the address for the break must be set up in the breakpoint data structure.

For symbolic addresses, the start of the function can be obtained from the line number information held for debugging purposes in the symbol table (known as symbol-and-line information, or SAL). For a function, this will yield the start address of the code. However the breakpoint must be set after the function prologue. gdbarch_skip_prolog is used to find that address in the code.

Figure 2.7 shows the high level sequence diagram for GDB in response to the run command.

Figure 2.7.  High level sequence diagram for the GDB run command

The run command must create the inferior, insert any active breakpoints and watchpoints, and then start execution of the inferior. Control does not return to GDB until the target reports that it has stopped.

The top level function implementing the run command is run_command. This creates the inferior, but calling the current target's to_create_inferior function. GDB supports targets which can give a dynamic description of their architecture (for example the number of registers available). This is achieved through the to_find_description function of the current target (which is an empty function by default).

Execution is started by the proceed. This must first determine if the code is restarting on an instruction which will need stepping through a delay slot (so that code never stops on a delay slot). If this functionality is required, it is implemented by the gdbarch_single_sep_through_delay function.

Active breakpoints are inserted using the current target's to_insert_breakpoint function. The code is then run using the to_resume function of the current target.

GDB then calls wait_for_inferior, which will wait for the target to stop, and then determine the reason for the stop. Finally normal_stop will remove the breakpoints from the target code and report to the user the current state of the target as appropriate.

Much of the detailed processing takes place in the wait_for_inferior and normal_stop functions (see also their use in Section 2.11.2). These are important functions and it is useful to look at their behavior in more detail.

Figure 2.8 shows the sequence diagram for wait_for_inferior when handling the GDB run command.

Figure 2.8.  Sequence diagram for the GDB wait_for_inferior function as used by the run command

Once again the key work is in handle_inferior_event. The code checks for watchpoints using the to_stopped_by_watchpoint function of the current target. The function also checks breakpoints, but since it already knows the current program counter (set by target_wait when control is returned), it needs no further call to the target operations. target_wait will have reported if it stopped due to an exception that could be due to a breakpoint. handle_inferior_event can then look up the program counter in the list of active breakpoints, to determine which breakpoint was encountered.

Figure 2.9 shows the sequence diagram for normal_stop when handling the GDB run command. In this example the stop was due to the target encountering a breakpoint.

Figure 2.9.  Sequence diagram for the GDB normal_stop function as used by the run command

The first action is to remove breakpoints. This ensures that the target executable is returned to its normal state, without any trap or similar code inserted.

The frame sniffers for the target are identified, using the frame sniffer for the architecture, arch_frame_sniffer. The current stack frame is then printed for the user. This requires use of the frame sniffer to identify the ID (and hence all the other data) of THIS frame from the NEXT frame (arch_frame_this_id here). print_stack_frame will start from the sentinel frame and work inwards until it finds the stack frame containing the current stack pointer and program counter.

Figure 2.10 shows the high level sequence diagram for GDB in response to the backtrace command. This sequence shows the behavior for the first call to backtrace after control has returned to GDB.

Figure 2.10.  High level sequence diagram for the GDB backtrace command

The main command function is backtrace_command, which uses print_frame_info to print the name of each function on the stack with its arguments.

The first frame is already known from the program counter and stack pointer of the stopped target, so is printed out by print_frame. That will ultimately use the current target's to_xfer_partial function to get the local argument values.

Since this is the first backtrace after the program stopped, the stack pointer and program counter are each obtained from the sentinel frame using get_func_type. print_frame is then called for each frame in turn as the stack is unwound until there are no more stack frames. The information in each frame is built up using the architecture's frame sniffers.

It is useful to look at print_frame in more detail. Figure 2.11 shows the sequence diagram for the second series of calls to the print_frame function when handling the GDB backtrace command, used to print out the stack frame.

Figure 2.11.  Sequence diagram for the GDB print_frame function used by the backtrace command

The information about the function on the stack frame can be obtained from the program counter and stack pointer associated with the stack frame. These are obtained by calls to the gdbarch_unwind_pc and gdbarch_unwind_sp functions.

Then for each argument, its value must be printed out. The symbol table debug data will identify the arguments, and enough information for GDB to work out if the value is on the stack or in a register. The frame sniffer function to get registers from the stack frame (in this example arch_frame_prev_register) is used to get the values of any registers as appropriate.

The precise sequence of calls depends on the functions in the stack frame, the arguments they have, and whether those arguments are in registers or on the stack.

The final sequence shows the behavior when execution is resumed after a breakpoint with the continue command. Figure 2.12 shows the high level sequence diagram for GDB in response to the continue command. This sequence shows the behavior for the first call to continue after a run stopped due to a breakpoint.

Figure 2.12.  High level sequence diagram for the GDB continue command after a breakpoint

The command functionality is provided by the continue_command, which calls the proceed function for much of its behavior.

proceed calls the to_resume function of the current target to resume execution. For this first call, the breakpoint(s) removed when execution completed after the run command are not replaced and the target resumption is only for a single instruction step. This allows the target to be stepped past the breakpoint without triggering an exception.

proceed then uses wait_for_inferior to wait for control to return after the single step and diagnose the next action. Waiting uses the to_wait function of the current target, then calls handle_inferior_event to analyze the result. In this case, handle_inferior_event determines that a target has just stepped past a breakpoint. It reinserts the breakpoints and calls the target to_resume function again, this time to run continuously.

wait_for_inferior will use the current target to_wait function again to wait for the target to stop executing, then again call the handle_inferior_event to process the result. This time, control should return to GDB, so breakpoints are removed, and handle_inferior_event and wait_for_inferior return. proceed calls normal_stop to tidy up and print out a message about the current stack frame location where execution has stopped (see Section 2.11.5.).

It is useful to examine the behavior of the first call to handle_inferior_event, to see the sequence for completing the single step and resuming continuous execution. Figure 2.13 shows the sequence diagram for the first call to handle_inferior_event.

Figure 2.13.  Sequence diagram for the GDB handle_inferior_event function after single stepping an instruction for the continue command

handle_inferior_event first determines if a watchpoint has now been triggered. If this is not the case, it checks if the processor is now in the delay slot of an instruction (requiring another single-step immediately). Having determined that continuous execution is appropriate, it calls the function keep_going to reinsert active breakpoints (using the to_insert_breakpoint function of the current target). Finally it calls the to_resume function of the current target without the single-step flag set to resume continuous execution.

gdbarch_register is called for BFD type bfd_arch_or32 with the initialization function or1k_gdbarch_init and the target specific dump function, or1k_dump_tdep.

Future implementations may make additional calls to use the same function to create a 64-bit version of the architecture.

gdbarch_init receives the struct gdbarch_info created from the BFD entries and the list of existing architectures. That list is first checked, using gdbarch_list_lookup_by_info to see if there is already an architecture defined suitable for the given struct gdbarch_info and if so it is returned.

Otherwise a new struct gdbarch is created. For that the target dependencies are saved in an OpenRISC 1000 specific struct gdbarch_tdep, defined in or1k-tdep.h.

struct gdbarch_tdep
{
  unsigned int  num_matchpoints;
  unsigned int  num_gpr_regs;
  int           bytes_per_word;
  int           bytes_per_address;
};
	  

This is information beyond that which is held in the struct gdbarch. By using this structure, the GDB implementation for OpenRISC 1000 can be made flexible enough to deal with both 32 and 64-bit implementations and with variable numbers of registers and matchpoints.

	Caution
	Although this flexibility is built in to the code, the current implementation has only been tested with 32-bit OpenRISC 32 registers.

The new architecture is then created by gdbarch_alloc, passing in the struct gdbarch_info and the struct gdbarch_tdep. The struct gdbarch is populated using the various set_gdbarch_ functions, and OpenRISC 1000 Frame sniffers are associated with the architecture.

When creating a new struct gdbarch a function must be provided to dump the target specific definitions in struct gdbarch_tdep to a file. This is provided in or1k_dump_tdep. It is passed a pointer to the struct gdbarch and a file handle and simply writes out the fields in the struct gdbarch_tdep with suitable explanatory text.

The first entries in struct gdbarch initialize the size and format of all the standard data types.

set_gdbarch_short_bit             (gdbarch, 16);
set_gdbarch_int_bit               (gdbarch, 32);
set_gdbarch_long_bit              (gdbarch, 32);
set_gdbarch_long_long_bit         (gdbarch, 64);
set_gdbarch_float_bit             (gdbarch, 32);
set_gdbarch_float_format          (gdbarch, floatformats_ieee_single);
set_gdbarch_double_bit            (gdbarch, 64);
set_gdbarch_double_format         (gdbarch, floatformats_ieee_double);
set_gdbarch_long_double_bit       (gdbarch, 64);
set_gdbarch_long_double_format    (gdbarch, floatformats_ieee_double);
set_gdbarch_ptr_bit               (gdbarch, binfo->bits_per_address);
set_gdbarch_addr_bit              (gdbarch, binfo->bits_per_address);
set_gdbarch_char_signed           (gdbarch, 1);
	  

These struct gdbarch functions provide information about the architecture.

set_gdbarch_return_value          (gdbarch, or1k_return_value);
set_gdbarch_breakpoint_from_pc    (gdbarch, or1k_breakpoint_from_pc);
set_gdbarch_single_step_through_delay
                                  (gdbarch, or1k_single_step_through_delay);
set_gdbarch_have_nonsteppable_watchpoint
                                  (gdbarch, 1);
switch (gdbarch_byte_order (gdbarch))
  {
  case BFD_ENDIAN_BIG:
    set_gdbarch_print_insn        (gdbarch, print_insn_big_or32);
    break;

  case BFD_ENDIAN_LITTLE:
    set_gdbarch_print_insn        (gdbarch, print_insn_little_or32);
    break;

  case BFD_ENDIAN_UNKNOWN:
    error ("or1k_gdbarch_init: Unknown endianism");
    break;
    }
	  

The register architecture is defined by two groups of struct gdbarch functions and fields. The first group specifies the number of registers (both raw and pseudo) and the register numbers of some "special" registers.

set_gdbarch_pseudo_register_read  (gdbarch, or1k_pseudo_register_read);
set_gdbarch_pseudo_register_write (gdbarch, or1k_pseudo_register_write);
set_gdbarch_num_regs              (gdbarch, OR1K_NUM_REGS);
set_gdbarch_num_pseudo_regs       (gdbarch, OR1K_NUM_PSEUDO_REGS);
set_gdbarch_sp_regnum             (gdbarch, OR1K_SP_REGNUM);
set_gdbarch_pc_regnum             (gdbarch, OR1K_PC_REGNUM);
set_gdbarch_ps_regnum             (gdbarch, OR1K_SR_REGNUM);
set_gdbarch_deprecated_fp_regnum  (gdbarch, OR1K_FP_REGNUM);
	  

The second group of functions provides information about registers.

set_gdbarch_register_name         (gdbarch, or1k_register_name);
set_gdbarch_register_type         (gdbarch, or1k_register_type);
set_gdbarch_print_registers_info  (gdbarch, or1k_registers_info);
set_gdbarch_register_reggroup_p   (gdbarch, or1k_register_reggroup_p);
	  

The representation of the raw registers (see Section 2.3.5.3) is: registers 0-31 are the corresponding GPRs, register 32 is the previous program counter, 33 is the next program counter (often just called the program counter) and register 34 is the supervision register. For convenience, constants are defined in the header, or1k_tdep.h, for all the special registers.

#define OR1K_SP_REGNUM         1
#define OR1K_FP_REGNUM         2
#define OR1K_FIRST_ARG_REGNUM  3
#define OR1K_LAST_ARG_REGNUM   8
#define OR1K_LR_REGNUM         9
#define OR1K_RV_REGNUM        11
#define OR1K_PC_REGNUM       (OR1K_MAX_GPR_REGS + 0)
#define OR1K_SR_REGNUM       (OR1K_MAX_GPR_REGS + 1)
	  

In this implementation there are no pseudo-registers. A set could have been provided to represent the GPRs in floating point format (for use with the floating point instructions), but this has not been implemented. Constants are defined for the various totals

#define OR1K_MAX_GPR_REGS    32
#define OR1K_NUM_PSEUDO_REGS  0
#define OR1K_NUM_REGS        (OR1K_MAX_GPR_REGS + 3)
#define OR1K_TOTAL_NUM_REGS  (OR1K_NUM_REGS + OR1K_NUM_PSEUDO_REGS)
	  

	Caution
	These totals are currently hard-coded constants. They should really draw on the data in the struct gdbarch_tdep, providing support for architectures which have less than the full complement of 32 registers. This functionality will be provided in a future implementation.

One consequence of providing no pseudo-registers is that the frame pointer variable, $fp in GDB will not have its correct value. The provision of this register as an intrinsic part of GDB is no longer supported. If it is wanted then it should be defined as a register or pseudo-register.

However if there is no register with this name, GDB will use either the value of the deprecated_fp_regnum value in struct gdbarch or the current frame base, as reported by the frame base sniffer.

For the time being, the deprecated_fp_regnum is set. However the longer term plan will be to represent the frame-pointer as a pseudo-register, taking the value of GPR 2.

The register architecture is mostly a matter of setting the values required in struct gdbarch. However two functions, or1k_pseudo_register_read and or1k_pseudo_register_write are defined to provide access to any pseudo-register. These functions are defined to provide hooks for the future, but in the absence of any pseudo-registers they do nothing.

There are set of functions which yield information about the name and type of registers and which provide the output for the GDB info registers command.

The OpenRISC 1000 frame structure is described in its ABI [8]. Some of the detail is slightly different in current OpenRISC implementations—this is described in Section 3.3.

The key to frame handling is understanding the prologue (and possibly epilogue) in each function which is responsible for initializing the stack frame. For the OpenRISC 1000, GPR 1 is used as the stack pointer, GPR 2 as the frame pointer and GPR 9 as the return address. The prologue sequence is:

The OpenRISC 1000 stack frame accommodates any local (automatic) variables and temporary values, then the return address, then the old frame pointer and finally any stack based arguments to functions called by this function. This last rule means that the return address and old frame pointer are not necessarily at the end of the stack frame - enough space will be left to build up any arguments for called functions that must go on the stack. Figure 4.1 shows how the stack looks at the end of the prologue.

Figure 4.1.  The OpenRISC 1000 stack frame at the end of the prologue

Not all fields are always present. The function need not save its return address to stack, and there may be no callee-saved registers (i.e. GPRs 12, 14, 16, 18, 20, 22, 24, 26, 28 and 30) which require saving. Leaf functions are not required to set up a new stack frame at all.

The epilogue is the inverse. Callee-saved registers are restored, the return address placed in GPR 9 and the stack and frame pointers restored before jumping to the address in GPR 9.

Only those parts of the epilogue which correspond to the prologue need actually appear. The OpenRISC 1000 has a delay slot after branch instructions, so for efficiency the stack restoration can be placed after the l.jr instruction.

set_gdbarch_skip_prologue         (gdbarch, or1k_skip_prologue);
set_gdbarch_inner_than            (gdbarch, core_addr_lessthan);
set_gdbarch_frame_align           (gdbarch, or1k_frame_align);
set_gdbarch_frame_red_zone_size   (gdbarch, OR1K_FRAME_RED_ZONE_SIZE);
	    

set_gdbarch_unwind_pc             (gdbarch, or1k_unwind_pc);
set_gdbarch_unwind_sp             (gdbarch, or1k_unwind_sp);
	    

set_gdbarch_push_dummy_call       (gdbarch, or1k_push_dummy_call);
set_gdbarch_unwind_dummy_id       (gdbarch, or1k_unwind_dummy_id);
	    

or1k_frame_base.unwind      = or1k_frame_sniffer (NULL);
or1k_frame_base.this_base   = or1k_frame_base_address;
or1k_frame_base.this_locals = or1k_frame_base_address;
or1k_frame_base.this_args   = or1k_frame_base_address;
frame_base_set_default            (gdbarch, &or1k_frame_base);
	    

4.2.5.6.  OpenRISC 1000 Low Level Frame Sniffers

The function or1k_frame_sniffer returns a pointer to struct frame_unwind with entries for the functions defined by this sniffer. For the OpenRISC 1000, this defines a custom function to construct the frame ID of THIS frame given a pointer to the NEXT frame (or1k_frame_this_id) and a custom function to give the value of a register in THIS frame given a pointer to the NEXT frame (or1k_frame_prev_register).

• or1k_frame_this_id. This function's inputs are a pointer to the NEXT frame and the prologue cache (if any exists) for THIS frame. It uses the main OpenRISC 1000 frame analyzer, or1k_frame_unwind_cache to generate the prologue cache if it does not exist (see below).

  From the cached data, the function returns the frame ID. This comprises two values, the stack pointer for this frame and the address of the code (typically the entry point) for the function using this stack frame

  	Note
  	Strictly speaking frame IDs can have a third value, the special address for use with architectures which have more complex frame structures. However this is rarely used.

  The result is returned in a struct frame_id passed by reference as a third argument. Since the implementation uses the built in struct trad_frame_cache for its register cache, the code can use the trad_frame_get_id function to decode the frame ID from the cache.

• or1k_frame_prev_register. This function's inputs are a pointer to the NEXT frame, the prologue cache (if any exists) for THIS frame and a register number. It uses the main OpenRISC 1000 frame analyzer, or1k_frame_unwind_cache to generate the prologue cache if it does not exist (see below).

  From the cached data, a flag is returned indicating if the register has been optimized out (this is never the case), what sort of l-value the register represents (a register, memory or not an l-value), the address where it is saved in memory (if it is saved in memory), the number of a different register which holds the value of this register (if that is the case) and if a buffer is provided the actual value as obtained from memory or the register cache.

  Since the implementation uses the built in struct trad_frame_cache for its register cache, the code can use the trad_frame_get_register function to decode all this information from the cache.

The OpenRISC 1000 low level sniffers rely on or1k_frame_unwind_cache. This is the heart of the sniffer. It must determine the frame ID for THIS frame given a pointer to the NEXT frame and then the information in THIS frame about the values of registers in the PREVIOUS frame.

All this data is returned in a prologue cache (see Section 2.3.6), a reference to which is passed as an argument. If the cache already exists for THIS frame it can be returned immediately as the result.

If the cache does not yet exist, it is allocated (using trad_frame_cache_zalloc). The first step is to unwind the start address of this function from the NEXT frame. The DWARF2 information in the object file can be used to find the end of the prologue (using skip_prologue_using_sal).

The code then works through each instruction of the prologue to find the data required.

	Caution
	The analysis must only consider prologue instructions that have actually been executed. It is quite possible the program counter is in the prologue code, and only instructions that have actually been executed should be analyzed.

The stack pointer and program counter are found by simply unwinding the NEXT frame. The stack pointer is the base of THIS frame, and is added to the cache data using trad_frame_set_this_base.

end_iaddr marks the end of the code we should analyze. Only instructions with addresses less than this will be considered.

The l.addi instruction should be first and its immediate constant field is the size of the stack. If it is missing, then this is a frameless call to a function. If the program counter is right at the start of the function, before the stack and frame pointers are set up, then it will also look like a frameless function.

Unless it is subsequently found to have been saved on the stack, the program counter of the PREVIOUS frame is the link register of THIS frame and can be recorded in the register cache.

Tip

It is essential to save the register data using the correct function. Use trad_frame_set_reg_realreg when a register in the PREVIOUS frame is obtained from a register in THIS frame. Use trad_frame_set_reg_addr when a register in the PREVIOUS frame is obtained from an address in THIS frame. Use trad_frame_set_reg_value when a register in the PREVIOUS frame is a particular value in THIS frame. The default entry for each register is that its value in the PREVIOUS frame is obtained from the same register in THIS frame.

For a frameless call, there is no more information to be found, so the rest of the code analysis only applies if the frame size was non-zero.

The second instruction in the prologue is where the frame pointer of the PREVIOUS frame is saved. It is an error if this is missing. The address where it is saved (the stack pointer of THIS frame plus the offset in the l.sw instruction) is saved in the cache using trad_frame_set_reg_addr.

The third instruction should be an l.addi instruction which sets the frame pointer. The frame size set in this instruction should match the frame size set in the first instruction. Once this has been set up, the frame pointer can be used to yield the stack pointer of the previous frame. This information is recorded in the register cache.

The fourth instruction is optional and saves the return address to the stack. If this instruction is found, the entry in the register cache for the program counter in the PREVIOUS frame must be changed using trad_frame_set_reg_addr to indicate it is found at an address in this frame.

All the subsequent instructions in the prolong should be saves of callee-savable registers. These are checked for until the code address has reached the end of the prologue. For each instruction that is found, the save location of the register is recorded in the cache using trad_frame_set_reg_addr.

The detailed analysis in or1k_frame_unwind_cache uses a series of helper functions: or1k_frame_size, or1k_frame_fp_loc, or1k_frame_size_check, or1k_link_address and or1k_get_saved_reg. These helper routines check each of the instructions in the prologue. By breaking out this code into separate functions, they can be reused by or1k_skip_prologue.

The remote target is created by defining the function _initialize_remote_or1k. A new struct target_ops, or1k_jtag_target is populated and added as a target by calling add_target.

The majority of the target operations are generic to OpenRISC 1000, and independent of the actual low level interface. This is achieved by abstracting the low level interface through the interface functions described in Section 4.3.

Having established all the target functions, the target is added by calling add_target

When a target is selected (with the GDB target jtag command), the set of target operations chosen for use with the OpenRISC 1000 architecture will be referred to by the global variable, or1k_target, defined in or1k-tdep.c.

	Note
	GDB has its own global variable, current_target, which refers to the current set of target operations. However this is not sufficient, since even though a target may be connected via the OpenRISC remote interface, it may not be the current target. The use of strata by GDB means there could possibly be another target which is active at the same time.

Much of the operation of the target interface involves manipulating the debug SPRs. Rather than continually writing them out to the target, a cache of their values is maintained in or1k_dbgcache, which is flushed prior to any operation that will unstall the target (thus causing it to execute).

A group of variables and functions give the name of the interface and different types of information.

OpenRISC remote targets are always executable, with full access to memory, stack, registers etc once the connection is established. A set of variables in struct target_ops for OpenRISC 1000 records this.

These functions control the connection to the target. For remote targets this involves setting up and closing down a TCP/IP socket link to the server driving the hardware. For local targets it involves opening and closing the device.

These are a group of functions to access the registers and memory of the target.

The OpenRISC 1000 can support hardware breakpoints and watchpoints, if matchpoints are free in the debug unit.

Note

Beware of confusion over the term "watchpoint". It is used in GDB to mean a location, being watched for read or write activity. These may be implemented in hardware or software. If implemented in hardware, they may make use of the OpenRISC 1000 Debug Unit mechanism, which also uses the term watchpoint. This document uses the terms "GDB watchpoint" and "OpenRISC 1000 watchpoint" where there is any risk of confusion.

When the run command is used to start execution with GDB it needs to establish the executable on the inferior, and then start execution. This is done using the to_create_inferior and to_resume functions of the target respectively.

Once execution has started, GDB waits until the target to_wait function returns control.

In addition the target provides operations to stop execution.

The OpenRISC 1000 target does not really have a way to execute commands. However implementing SPR access as remote commands provides a mechanism for access, which is independent of the target access protocol. In particular the GDB architecture need know nothing about the actual remote protocol used.

SPR access is implemented as though the target were able to run two commands, readspr to get a value from a SPR and writespr to set a value in a SPR. Each takes a first argument, specified in hexadecimal, which is the SPR number. writespr takes a second argument, specified in hexadecimal, which is the value to be written. readspr returns the value read as a number in hexadecimal.

When access is needed to the SPRs it is achieved by passing one of these commands as argument to the to_rcmd function of the target.

The interface to the OpenRISC JTAG system is found in gdb/or1k-jtag.c and gdb/or1k-jtag.h. The details are not directly relevant to porting GDB so only an overview is given here. Full details are found in the commenting within the source code.

The interface is layered, to maximize use. In particular much of the functionality is the same whether the target is connected remotely over TCP/IP or directly via a JP1 header connected to the parallel port.

Errors are either dealt with silently or (if fatal) via the GDB error function.

	Caution
	Few people now use the JP1 direct connection, and there is no confidence that this code works at all!

The new sub-command for info is added using add_info

add_info ("spr", or1k_info_spr_command,
          "Show the value of a special purpose register");
	  

The functionality is provided in or1k_info_spr_command. The user can specify a group by name or number (the value of all registers in that group is displayed), or a register name (the value of that register is displayed) or a group name/number and register name/number (the value of that register in the group is displayed).

The arguments are broken out from the text of the command using or1k_parse_params, which also handles any errors in syntax or semantics. If the arguments are successfully parsed the results are then printed out using the UI independent function, ui_out_field_fmt.

The SPR is read using the convenience function or1k_read_spr. This converts the access to a call of the command readspr, which can be passed to the target usings its to_rcmd target operation (see Section 4.3.7). This will allow the SPR to be accessed in the way most appropriate to the current target access method.

This new top level command is added, classified as a support command (class_support), using the add_com command.

The functionality is provided in or1k_spr_command. This also uses or1k_parse_spr_params to parse the arguments, although there is now one more (the value to set). The new value is written into the relevant SPR and the change recorded using ui_out_field_fmt.

The SPR is written using the convenience function or1k_write_spr. This converts the access to a call of the command writespr, which can be passed to the target usings its to_rcmd target operation (see Section 4.3.7). This will allow the SPR to be accessed in the way most appropriate to the current target access method.