Howto: GDB Remote Serial Protocol

The main user guide for GDB [3] explains how remote debugging works and provides the reference for the various RSP packets.

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. In particular the source code for the RSP client side in gdb/remote.c provides the definitive guide on the expected dynamics of the protocol.

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

This application note complements the Embecosm Application Note 3, "HOWTO: Porting the GNU Debugger" [2]. Details of the OpenRISC 1000 can be found in its Architecture Manual [6]. The OpenRISC 1000 architectural simulator and tool chain is documented in Embecosm Application Note 2 [1].

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.

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

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

Each packet should be acknowledged with a single character. '+' to indicate satisfactory receipt, with valid checksum or '-' to indicate failure and request retransmission.

Retransmission should be requested until a satisfactory packet is received.

The GDB client may wish to interrupt the server (e.g. when the user has pressed ctrl-C). This is indicated by transmitting the character 0x03 between packets.

If the server wishes to handle such interrupts, it should recognize such characters and process as appropriate. However not all servers are capable of handling such requests. The server is free to ignore such out-of-band characters.

The gdbserver command is well documented in the GDB User Guide [3]. This approach is suitable for powerful targets, where it is easy to invoke a program from the command line.

Generally this approach is not suitable for embedded systems.

This is the usual approach for embedded systems, and is the strategy encapsulated in the server stubs supplied with the GDB source code.

There are two key components of the code:

In the stub code, the user must implement the serial connection by supplying functions getDebugChar () and putDebugChar (). The user must supply the function exceptionHandler () to set up exception handling.

The serial connection is usually established on the first call to getDebugChar (). This is standard POSIX code to access either the serial device, or to listen for a TCP/IP or UDP/IP connection. The target may choose to block here, if it does not wish to run without control from a GDB client.

If the serial connection chooses not to block on getDebugChar () then the exception handler should be prepared for this response, allowing the exception to be processed as normal.

	Note
	The stub RSP server code supplied with the GDB source distribution assumes getDebugChar () blocks until the connection is established.

In general the server interacts with the client only when it has received control due to a target exception.

At start up, the first time this occurs, the target will be waiting for the GDB client to send a packet to which it can respond. These dialogs will continue until the client GDB session wishes to continue or step the target (c, C, i, I, s or S packet).

Thereafter control is received only when another exception has occurred, following a continue or step. In this case, the first action of the target RSP server should be to send the reply packet back to the client GDB session.

Caution

The key limitation in the stub RSP server code supplied with the GDB source distribution is that it only deals with the second case. In other words, it always sends a reply packet to the client, even on first execution. This causes two problems. First, the putDebugChar () is called before getDebugChar (), so it must be able to establish the connection. Secondly, the initial reply is sent without a request packet from the client GDB session. As a result this reply will typically be queued and appear as the reply to the first request packet from GDB. The client interface is quite robust and usually quietly rejects unexpected packets, but there is potential for client requests and server responses to get out of step. It certainly does not represent good program design.

The final issue that server code needs to address is the issue of BREAK signaling from the client. This is a raw 0x03 byte sent from the client between packets. Typically this is in response to a ctrl-C from the client GDB session.

If the target server wishes to handle such signaling, it must provide an event driven getDebugChar (), triggered when data is received, which can act on such BREAK signals.

Simulators are commonly integrated separately into GDB, and accessed using the target sim command.

However it can also be useful to connect to them by using the RSP. This allows the GDB experience to be identical whether simulator or real silicon is used.

The general approach is the same as that for implementing code on a target (see Section 2.5.2). However the code forms part of the simulator, not the target. The RSP handler will be attached to the simulators handling of events, rather than the events themselves.

In general the simulator will use the same form of connection as when debugging real silicon. Where the RSP server for real silicon is implemented on the target, or gdbserver is used, connection via a serial device, TCP/IP or UDP/IP is appropriate. Where the RSP interface for real silicon is via a pipe to a program driving JTAG a pipe interface should be used to launch the simulator.

The example used in Chapter 4 is based on a simulator for the OpenRISC 1000.

Many embedded systems will offer JTAG ports for debugging. Most commonly these are connected to a host workstation running GDB via the parallel port or USB.

In the past users would implement a custom target interface in GDB to drive the JTAG interface directly. However with RSP it makes more sense to write a RSP server program, which runs standalone on the host. This program maps RSP commands and responses to the underlying JTAG interface.

Logically this is rather like a custom gdbserver, although it runs on the host rather than the target. The implementation techniques are similar to those required for interfacing to a simulator.

This is one situation, where using the pipe interface is sensible. The pipe interface is used to launch the program which will talk to the JTAG interface. If this approach is used, then debugging via a simulator should also use a pipe interface to launch the simulator, thus allowing the debugging experience to be the same whether real silicon or a simulator is used.

A RSP server supporting standard remote debugging (i.e. using the GDB target remote command) should implement at least the following RSP packets:

A RSP server supporting standard remote debugging (i.e. using the GDB target remote command) should implement at least the following RSP packets in addition to those required for standard remote debugging:

The most recent versions of GDB have started to introduce the concept of asynchronous debugging. This is primarily for use with targets capable of "non-stop" execution. Such targets are able to stop the execution of a single thread in a multithreaded environment, allowing it to be debugged while others continue to execute.

This still represents technology under development. In GDB 6.8, the commands target async and target extended-async were provided to specify remote debugging of a non-stop target in asynchronous fashion.

The mechanism will change in the future, with GDB flags set to specify asynchronous interpretation of commands, which are otherwise unchanged. Readers particularly interested in this area should look at the current development version of GDB and the discussions in the various GDB newsgroups.

Asynchronous debugging requires that the target support packets specifying execution of particular threads. The most significant of these are:

In addition, non-stop targets should also support the T response to continue or step commands, so that status of individual threads can be reported.

The RSP packet exchanges to implement the GDB target remote command are shown as a sequence diagram in Figure 3.1.

Figure 3.1.  RSP packet exchanges for the GDB target remote command

This is the initial dialog once the connection has been established. The first thing the client needs to know is what this RSP server supports. The only feature that matters is to report the packet size that is supported. The largest packet that will be needed is to hold a command with the hexadecimal values of all the general registers (for the G packets). In this example, there are a total of 35 32-bit registers, each requiring 8 hex characters + 1 character for the 'G', a total of 281 (hexadecimal 0x119) characters.

The client then asks why the target halted. For a standard remote connection (rather than extended remote connection), the target must be running, even if it has halted for a signal. So the client will verify that the reply is not W (exited) or X (terminated with signal). In this case the target reports it has stopped due to a TRAP exception.

The next packet is an instruction from the client that any future step or continue commands should apply to all threads. This is followed by a request (qC) for information on the thread currently running. In this example the target is "bare metal", so there is no concept of threads. An empty response is interpreted as "use the existing value", which suits in this case—since it is never set explicitly, it will be the NULL thread ID, which is appropriate.

The next packet (qOffsets) requests any offsets for loading binary data. At the minimum this must return offsets for the text, data and BSS sections of an executable—in this example all zero.

	Note
	The BSS component must be specified, contrary to the advice in the GDB User Guide.

The client then fetches the value of all the registers, so it can populate its register cache. It first specifies that operations such as these apply to all threads (Hg-1 packet), then requests the value of all registers (g packet).

Finally the client offers to supply any symbolic data required by the server. In this example, no data is needed, so a reply of "OK" is sent.

Through this exchange, the GDB client shows the following output:

(gdb) target remote :51000
Remote debugging using :51000
0x00000100 in _start ()
(gdb)
	

The RSP packet exchanges to implement the GDB load command are shown as a sequence diagram in Figure 3.2. In this example a program with a text section of 4752 (0x1290) bytes at address 0x0 and data section of 15 (0xe) bytes at address 0x1290 is loaded.

Figure 3.2.  RSP packet exchanges for the GDB load command

The first packet is a binary write of zero bytes (X0,0:). A reply of "OK" indicates the target supports binary writing, an empty reply indicates that binary write is not supported, in which case the data will be loaded using M packets.

	Note
	This initial dialog is 7-bit clean, even though it uses the X packet. It can therefore safely be used with connections that are not 8-bit clean.

	Caution
	The use of a null reply to indicate that X packet transfers are not supported is not documented in the GDB User Guide.

Having established in this case that binary transfers are permitted, each section of the loaded binary is transmitted in blocks of up to 256 binary data bytes.

Had binary transfers not been permitted, the sections would have been transferred using M packets, using pairs of hexadecimal digits for each byte.

Finally the client sets the value of the program counter to the entry point of the code using a P packet. In this example the program counter is general register 33 and the entry point is address 0x100.

Through this exchange, the GDB client shows the following output:

(gdb) load hello
Loading section .text, size 0x1290 lma 0x0
Loading section .rodata, size 0xe lma 0x1290
Start address 0x100, load size 4766
Transfer rate: 5 KB/sec, 238 bytes/write.
(gdb)
	

Examining registers in GDB causes no RSP packets to be exchanged. This is because the GDB client always obtains values for all the registers whenever it halts and caches that data. So for example in the following command sequence, there is no RSP traffic.

(gdb) print $pc
$1 = (void (*)()) 0x1264 <main+16>
(gdb) 
	

All GDB commands which involve examining memory are mapped by the client to a series of m packets. Unlike registers, memory values are not cached by the client, so repeated examination of a memory location will lead to multiple m packets for the same location.

The packet exchanges to implement the GDB disassemble command for a simple function are shown as a sequence diagram in Figure 3.3. In this example the simputc () function is disassembled.

Figure 3.3.  RSP packet exchanges for the GDB disassemble command

The disassemble command in the GDB client generates a series of RSP m packets, to obtain the instructions required one at a time.

Through this exchange, the GDB client shows the following output:

(gdb) disas simputc
Dump of assembler code for function simputc:
0x00001020 <simputc+0>: l.addi   r1,r1,-8
0x00001024 <simputc+4>: l.sw     0(r1),r2
0x00001028 <simputc+8>: l.addi   r2,r1,8
0x0000102c <simputc+12>:        l.sw     -4(r2),r3
0x00001030 <simputc+16>:        l.nop    4
0x00001034 <simputc+20>:        l.lwz    r2,0(r1)
0x00001038 <simputc+24>:        l.jr     r9
0x0000103c <simputc+28>:        l.addi   r1,r1,8
End of assembler dump.
(gdb)
	

The RSP offers two mechanisms for stepping and continuing programs. The original mechanism has the thread concerned specified with a Hc packet, and then the thread stepped or continued with a s, S, c or C packet.

The newer mechanism uses the vCont: packet to specify the command and the thread ID in a single packet. The availability of the vCont: packet is established using the vCont? packet.

The simplest GDB execution command is the stepi command to step the target a single machine instruction. The RSP packet exchanges to implement the GDB stepi command are shown as a sequence diagram in Figure 3.4. In this example the instruction at address 0x100 is executed.

Figure 3.4.  RSP packet exchanges for the GDB stepi command

The first exchange is related to the definition of the architecture used in this example. Before stepping any instruction, GDB needs to know if there is any special behavior due to this instruction occupying a delay slot. This is achieved by calling the gdbarch_single_step_through_delay () function. In this example, that function reads the instruction at the previous program counter (in this case address 0x0) to see if it was an instruction with a delay slot. This is achieved by using the m packet to obtain the 4 bytes of instruction at that address.

The next packet, vCont? from the client seeks to establish if the server supports the vCont packet. A null response indicates that it is not.

	Note
	The vCont? packet is used only once, and the result cached by the GDB client. Subsequent step or continue commands will not result in this packet being reissued.

The client then establishes the thread to be used for the step with the Hc0 packet. The value 0 indicates that any thread may be used by the server.

	Note
	Note the difference to the earlier use of the Hc packet (see Section 3.2.1), where a value of -1 was used to mean all threads.

	Note
	The GDB client remembers the thread currently in use. It does not issue further Hc packets unless the thread has to change.

The actual step is invoked by the s packet. This does not return a result to the GDB client until it has completed. The reply indicates that the server stopped for signal 5 (TRAP exception).

	Caution
	In the RSP, the s packet indicates stepping of a single machine instruction, not a high level statement. In this way it maps to GDB's stepi command, not its step command (which confusingly can be abbreviated to just s).

The last two exchanges are a g and m packet. These allow GDB to reload its register cache and note the instruction just executed.

Through this exchange, the GDB client shows the following output:

(gdb) stepi
0x00000104 in _start ()
(gdb)
	

The GDB step command to step the target a single high level instruction is similar to the stepi instruction, and works by using multiple s packets. However additional packet exchanges are also required to provide information to be displayed about the high level data structures, such as the stack.

The RSP packet exchanges to implement the GDB step command are shown as a sequence diagram in Figure 3.5. In this example the first instruction of a C main () function is executed.

Figure 3.5.  RSP packet exchanges for the GDB step command

The exchanges start similarly to the stepi, although, since this is not the first step, there are no vCont? or Hc packets.

The high level language step is mapped by the client GDB session into a series of s packets, after each of which the register cache is refreshed by a g packet.

After the step, are a series of reads of data words, using m packets. The first group are from the code. This is the first execution in a new function, and the frame analysis functions of the GDB client are analyzing the function prologue, to establish the location of key values (stack pointer, frame pointer, return address).

The second group access the stack frame to obtain information required by GDB. In this example the return address from the current stack frame.

Through this exchange, the GDB client shows the following output:

(gdb) step
main () at hello.c:41
41        simputs( "Hello World!\n" );
(gdb) 
	

The packet exchange for the GDB continue is very similar to that for the step (see Section 3.2.6). The difference is that in the absence of a breakpoint, the target program may complete execution. A simple implementation need not trap the exit—GDB will handle the loss of connection quite cleanly.

The RSP packet exchanges to implement the GDB continue command are shown as a sequence diagram in Figure 3.6. In this example the target executes to completion and exits, without returning a reply packet to the GDB client.

Figure 3.6.  RSP packet exchanges for the GDB continue command

The packet exchange is initially the same as that for a GDB step or stepi command (see Figure 3.4).

In this example the gdbarch_single_step_through_delay () function finds that the previously executed instruction is a jump instruction (m packet). Since the target may be in a delay slot, it executes a single step (s packet) to step past that slot, followed by notification of the TRAP exception (S05 packet) and register cache reload (g packet).

The next call to gdbarch_single_step_through_delay () determines that the previous instruction did not have a delay slot (m packet), so the c packet can be used to resume execution of the target.

Since the target exits, there is no reply to the GDB client. However it correctly interprets the loss of connection to the server as target execution. Through this exchange, the GDB client shows the following output:

(gdb) continue
Continuing.
Remote connection closed
(gdb)
	

The GDB command to set breakpoints, break does not immediately cause a RSP interaction. GDB only actually sets breakpoints immediately before execution (for example by a continue or step command) and immediately clears them when a breakpoint is hit. This minimizes the risk of a program being left with breakpoints inserted, for example when a serial link fails.

The RSP packet exchanges to implement the GDB break command and a subsequent continue are shown as a sequence diagram in Figure 3.7. In this example a breakpoint is set at the start of the function simputs ().

Figure 3.7.  RSP packet exchanges for the GDB break and continue commands

The command sequence is very similar to that of the plain continue command (see Section 3.2.7). With two key differences.

First, immediately before the c packet, the breakpoint is set with a Z0 packet. Secondly, as soon as the register cache has been refreshed (g packet) when control returns, the program counter is stepped back to re-execute the instruction at the location of the TRAP with a P packet and the breakpoint is cleared with a z0 packet. In this case only a single breakpoint (at location 0x1150, the start of function simputs ()) is set. If there were multiple breakpoints, they would all be set immediately before the c packet and cleared immediately after the g packet.

In this example, the client ensures that the program counter is set to point to the TRAP instruction just executed, not the instruction following.

An alternative to adjusting the program counter in the target is to use the GDB architecture value decr_pc_after_break () value to specify that the program counter should be wound back. In this case an additional P packet would be used to reset the program counter register. Whichever approach is used, it means that when execution resumes, the instruction which was replaced by a trap instruction will be executed first.

	Note
	Perhaps rather surprisingly, it is the responsibility of the target RSP server, not the GDB client to keep track of the substituted instructions.

Through this exchange, the GDB client shows the following output:

(gdb) break simputs
Breakpoint 1 at 0x1150: file utils.c, line 90.
(gdb) c
Continuing.

Breakpoint 1, simputs (str=0x1290 "Hello World!\n") at utils.c:90
90        for( i = 0; str[i] != '\0' ; i++ ) {
(gdb) 
	

The example here showed the use of a memory breakpoint (also known as a software breakpoint). GDB also supports use of hardware watchpoints explicitly through the hbreak command. These behave analogously to memory breakpoints in RSP, but using z1 and Z1 packets.

If a RSP server implementation does not support hardware breakpoints it should return an empty packet to any request for insertion or deletion.

If hardware watchpoints are supported (the default assumption in GDB), then the setting and clearing of watchpoints is very similar to breakpoints, but using z2 and Z2 packets (for write watchpoints), z3 and Z3 packets (for read watchpoints) and z4 and Z4 packets (for access watchpoints)

GDB also supports software write watchpoints. These are implemented by single stepping the target, and examining the watched value after each step. This is painfully slow when GDB is running native. Under RSP, where each step involves an number of packet exchanges, the performance drops ever further. Software watchpointing should be restricted to the shortest section of code possible.

The rules for detach mandate that it breaks the connection with the target, and allows the target to resume execution. By contrast, the disconnect command simply breaks the connection. A reconnection (using the target remote command) should be able to resume debugging at the point where the previous connection was broken.

The disconnect command just closes the serial connection. It is up to the target server to notice the connection has broken, and to try to re-establish a connection.

The detach command requires a RSP exchange with the target for a clean shutdown. The RSP packet exchanges to implement the command are shown as a sequence diagram in Figure 3.8.

Figure 3.8.  RSP packet exchanges for the GDB detach command

The exchange is a simple D packet to which the target responds with an OK packet, before closing the connection.

Through this exchange, the GDB client shows the following output:

(gdb) detach
Ending remote debugging.
(gdb)
	

The disconnect command has no dialog of itself. The GDB client shows the following output in a typical session. However there are no additional packet exchanges due to the disconnect.

(gdb) target remote :51000
Remote debugging using :51000
0x00000100 in _start ()
(gdb) load hello
Loading section .text, size 0x1290 lma 0x0
Loading section .rodata, size 0xe lma 0x1290
Start address 0x100, load size 4766
Transfer rate: 5 KB/sec, 238 bytes/write.
(gdb) break main
Breakpoint 1 at 0x1264: file hello.c, line 41.
(gdb) c
Continuing.

Breakpoint 1, main () at hello.c:41
41        simputs( "Hello World!\n" );
(gdb) disconnect
Ending remote debugging.
(gdb) target remote :51000
Remote debugging using :51000
main () at hello.c:41
41        simputs( "Hello World!\n" );
(gdb) c
Continuing.
Remote connection closed
(gdb) 
	

Unlike with the detach command, when debugging is reconnected through target remote, the target is still at the point where execution terminated previously.

The RSP packet exchanges to implement the GDB target extended-remote command are shown as a sequence diagram in Figure 3.9.

Figure 3.9.  RSP packet exchanges for the GDB target remote command

The dialog is almost identical to that for standard remote debugging (see Section 3.2.1). The difference is the penultimate ! packet, notifying the target that this is an extended remote connection.

Through this exchange, the GDB client shows the following output:

(gdb) target extended-remote :51000
Remote debugging using :51000
0x00000100 in _start ()
(gdb) 
	

The OpenRISC 1000 architecture defines a family of free, open source RISC processor cores. It is a 32 or 64-bit load and store RISC architecture designed with emphasis on performance, simplicity, low power requirements, scalability and versatility.

The OpenRISC 1000 is fully documented in its Architecture Manual [6].

From a debugging perspective, there are three data areas that are manipulated by the instruction set.

The Special Purpose Registers (SPRs) represent a challenge for GDB, since they represent neither addressable memory, nor have the characteristics of a register set (generally modest in number).

A number of SPRs are of particular significance to the GDB implementation.

Of particular importance are the SPRs in group 6 controlling the debug unit (if present). The debug unit can trigger a trap exception in response to any one of up to 10 watchpoints. Watchpoints are logical expressions built by combining matchpoints, which are simple point tests of particular behavior (has a specified address been accessed for example).

In a physical OpenRISC 1000 chip, debugging would be via the JTAG interface. However since the examples used here are based on the architectural simulator, the JTAG interface is not described further here.

The ABI for the OpenRISC 1000 is described in Chapter 16 of the Architecture Manual [6]. However the actual GCC compiler implementation differs very slightly from the documented ABI. Since precise understanding of the ABI is critical to GDB, those differences are documented here.

Or1ksim is an instruction set simulator (ISS) for the OpenRISC 1000 architecture. At present only the 32-bit architecture is modeled. In addition to modeling the core processor, Or1ksim can model a number of peripherals, to provide the functionality of a complete System-on-Chip (SoC).

Or1ksim implements the RSP server side. It is the implementation of this RSP server which forms the example for this application note.

The external interface to the RSP server code is through three void functions.

The RSP server has one data structure, rsp, shared amongst its implementing functions (and is thus declared static in rsp-server.c).

static struct
{
  int                client_waiting;
  int                proto_num;
  int                server_fd;
  int                client_fd;
  int                sigval;
  unsigned long int  start_addr;
  struct mp_entry   *mp_hash[MP_HASH_SIZE];
} rsp;
	

The fields are:

The RSP server also draws on several Or1ksim data structures. Most notably config for configuration data and cpu_state for all the CPU state data.

enum mp_type {
  BP_MEMORY   = 0,
  BP_HARDWARE = 1,
  WP_WRITE    = 2,
  WP_READ     = 3,
  WP_ACCESS   = 4
};
          

struct mp_entry
{
  enum mp_type       type;
  unsigned long int  addr;
  unsigned long int  instr;
  struct mp_entry   *next;
};
	  

The RSP server initialization, rsp_init () is called from the main simulator initialization, sim_init () in toplevel-support.c.

The main simulation initialization is also modified to start the processor stalled on a TRAP exception if RSP debugging is enabled. This ensures that the handler will be called initially.

The main loop of Or1ksim, called after initialization, is in the function exec_main () in cpu/or32/execute.c.

If RSP debugging is enabled in the Or1ksim configuration, the code to interact with the RSP client (handle_rsp ()) is called at the start of each iteration, but only if the processor is stalled. The handler is called repeatedly until an interaction with the client unstalls the processor (i.e. a step or continue function.

void
exec_main ()
{
  long long time_start;

  while (1)
    {
      time_start = runtime.sim.cycles;
      if (config.debug.enabled)
        {
          while (runtime.cpu.stalled)
            {
              if (config.debug.rsp_enabled)
                {
                  handle_rsp ();
                }

              ...
        

Since interaction with the client can only occur when the processor is stalled, BREAK signals (i.e. ctrl-C) cannot be intercepted.

It would be possible to poll the connection on every instruction iteration, but the performance overhead on the simulator would be unacceptable.

An implementation to pick up BREAK signals should use event driven I/O - i.e. with a signal handler for SIGIO. An alternative is to poll the interface less frequently when the CPU is not stalled. Since Or1ksim executes at several MIPS, polling every 100,000 cycles would mean a response to ctrl-C of less than 100ms, while adding no significant overhead.

int
debug_ignore_exception (unsigned long  except)
{
  int           result = 0;
  unsigned long dsr    = cpu_state.sprs[SPR_DSR];

  switch (except)
    {
    case EXCEPT_RESET:    result = (dsr & SPR_DSR_RSTE);  break;
    case EXCEPT_BUSERR:   result = (dsr & SPR_DSR_BUSEE); break;

  ...

  cpu_state.sprs[SPR_DRR] |= result;
  set_stall_state (result != 0);

  if (config.debug.rsp_enabled && (0 != result))
    {
      rsp_exception (except);
    }

  return  (result != 0);

}       /* debug_ignore_exception () */
	  

      if (config.debug.enabled)
        {
          if (cpu_state.sprs[SPR_DMR1] & SPR_DMR1_ST)
            {
              set_stall_state (1);

              if (config.debug.rsp_enabled)
                {
                  rsp_exception (EXCEPT_TRAP);
                }
            }
        }
	  

A TCP/IP socket to listen on the RSP port is created in rsp_init (), and its file descriptor stored in rsp.server_fd. As a variant, if the port is configured to be 0, the socket uses the port specified for the or1ksim-rsp service.

The setup uses standard POSIX calls to establish the socket and associate it with a TCP/IP port. The interface is set to be non-blocking and marked as a passive port (using a call to listen ()), with at most one outstanding client request. There is no meaning to the server handling more than one client GDB connection.

The main RSP handler function handle_rsp () checks that the server port is still open. This may be closed if there is a serious error. In the present implementation, handle_rsp () gives up at this point, but a richer implementation could try reopening a new server port.

If a client connection is yet to be established, then handle_rsp () blocks until a connection request is made. A valid request is handled by rsp_server_request (), which opens a connection to the client, saving the file descriptor in rsp.client_fd.

This connection is also non-blocking. Nagel's algorithm is also disabled, since all packet bytes should be sent immediately, rather than being queued to build larger blocks.

Having established a client connection if necessary, handle_rsp () blocks until packet data is available. It then calls rsp_client_request () to read the packet, provide the required behavior and generate any reply packets.

Although packets are character based, they cannot simply be represented as strings, since binary packets may contain the end of string character (zero). Packets are therefore represented as a simple struct, rsp_buf:

struct rsp_buf
{
  char  data[GDB_BUF_MAX];
  int   len;
};
	

For convenience, all packets have a zero added at location data[len], allowing the data field of non-binary packets to be printed as a simple string for debugging purposes.

The packet reading function is get_packet (). It looks for a well formed packet, beginning with '$', with '#' at the end of data and a valid 2 byte checksum (see Figure 2.2 in Section 2.3 for packet representation details).

If a valid packet is found, '+' is returned using put_rsp_char () (see Section 4.5.3.1) and the packet is returned as a pointer to a struct rsp_buf. Otherwise '-' is returned and the loop repeated to get a new packet (presumably retransmitted by the client).

The buffer is statically allocated within get_packet (). This is acceptable, since two received packets cannot be in use simultaneously.

In general errors are silently ignored (the connection could be poor quality). However bad checksums are noted in a warning message. In the event of end of file being encountered, get_packet () returns immediately with NULL as result.

The packet writing function is put_packet (). It takes as argument a struct rsp_buf and creates a well formed packet, beginning with '$', with '#' at the end of data and a valid 2 byte checksum (see Figure 2.2 in Section 2.3 for packet representation details).

The acknowledgment character is read using get_rsp_char () (see Section 4.5.2.1). If successful ('+'), the function returns. Otherwise the packet is repeatedly resent until ('+') is received as a response.

Errors on writing are silently ignored. If the read of the acknowledgment returns -1 (indicating failure of the connection or end-of-file), put_packet () returns immediately.

Many response packets take the form of a fixed string. As a convenience put_str_packet () is provided. This takes a constant string argument, from which a struct rsp_buf is constructed. This is then sent using put_packet ().

The function hex () takes an ASCII character which is a valid hexadecimal digit (upper or lower case) and returns its value (0-15 decimal). Any invalid digit returns -1.

The static array hexchars[] declared at the top level in rsp-server.c provides a mapping from a hexadecimal digit value (in the range 0-15 decimal) to its ASCII character representation.

For several packets, register values must be represented as strings of characters in target endian order. For convenience, the functions reg2hex () and hex2reg () are provided. Each takes a pointer to a buffer for the characters. For reg2hex () a value to be converted is passed. For hex2reg () the value represented is returned as a result.

The function rsp_unescape () takes a pointer to a data buffer and a length and "unescapes" the buffer in place. The length is the size of the data after all escape characters have been removed.

The program counter (i.e. the address of the next instruction to be executed) is held in Special Purpose Register 16 (next program counter). Within Or1ksim this is cached in cpu_state.pc.

When changing the next program counter in Or1ksim it is necessary to change associated data which controls the delay slot pipeline. If there is a delayed transfer, the flag cpu_state.delay_insn is set. The address of the next instruction to be executed (which is affected by the delay slot) is held in the global variable, pc_next.

The utility function set_npc () takes an address as argument. If that address is different to the current value of NPC, then the NPC (in cpu_state.pc) is updated to the new address, the delay slot pipeline is cleared (cpu_state.delay_insn is set to zero) and the following instruction (pcnext) is set to cpu_state.pc+4.

Packets requesting functionality that is now deprecated are ignored (possibly with an error response if that is expected) and a warning message printed. The packets affected are: b (set baud rate), B (set a breakpoint), d (disable debug) and r (reset the system).

In each case the warning message indicates the recommended way to achieve the desired functionality.

The development of an interface such as RSP can be incremental, where functionality is added in stages. A number of packets are not supported. In a few cases this is because the functionality is meaningless for the current target, but in the majority of cases, the functionality can be supported as the server is developed further in the future.

The unsupported packets are:

Some packets are very simple to handle, either requiring no response, or a simple fixed text response.

The response to the ? packet is provided by rsp_report_exception (). This is always a S packet. The signal value (as a GDB target signal) is held in rsp.sigval, and is presented as two hexadecimal digits.

The c packet is processed by rsp_continue (). Any address from which to continue is broken out from the packet using sscanf (). If no address is given, execution continues from the current program counter (in cpu_state.pc).

The continue functionality is provided by the function rsp_continue_generic () which takes an address and an Or1ksim exception as arguments, allowing it to be shared with the processing of the C packet (continue with signal) in the future. For the c packet, EXCEPT_NONE is used.

rsp_continue_generic () at present ignores its exception argument (the C packet is not supported). It sets the program counter to the address supplied using set_npc () (see Section 4.6.5).

The control registers of the debug unit must then be set appropriately. The Debug Reason Register and watchpoint generation flags in Debug Mode Register 2 are cleared. The Debug Stop Register is set to trigger on TRAP exceptions (so memory breakpoints are picked up), and the single step flag is cleared in Debug Mode Register 1.

  cpu_state.sprs[SPR_DRR]   = 0;
  cpu_state.sprs[SPR_DMR2] &= ~SPR_DMR2_WGB;
  cpu_state.sprs[SPR_DMR1] &= ~SPR_DMR1_ST;
  cpu_state.sprs[SPR_DSR]  |= SPR_DSR_TE;
	

The processor is then unstalled (set_stall_state (0)) and the client waiting flag (rsp.client_waiting) set. This latter means that when handle_rsp () is next entered, it will know that a reply is outstanding, and return the appropriate stop packet required when the processor stalls after a continue or step command.

The g and G packets respectively read and write all registers, and are handled by the functions rsp_read_all_regs () and rsp_write_all_regs ().

The m and M packets respectively read and write blocks of memory, with the data represented as hexadecimal characters. The processing is provided by rsp_read_mem () and rsp_write_mem ().

4.7.7.1.  Reading Memory

The syntax of the packet is m,addr,len:. sscanf () is used to break out the address and length fields (both in hex).

The reply packet is a stream of bytes, starting from the lowest address, each represented as a pair of hex characters. Each byte is read from memory using the simulator function eval_direct8 (), having first verified the memory area is valid using verify_memoryarea ().

The packet is only sent if all bytes are read satisfactorily. Otherwise an error packet, "E01" is sent. The actual error number does not matter—it is not used by the client.

	Caution
	The use of eval_direct8 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no MMU or cache.

4.7.7.2.  Writing Memory

The syntax of the packet is m,addr,len: followed by the data to be written as a stream of bytes, starting from the lowest address, each represented as a pair of hex characters. sscanf () is used to break out the address and length fields (both in hex).

Each byte is written to memory using set_program8 () (which ignores any read only constraints on the modeled memory), having first verified that the memory address is valid using verify_memoryarea ().

If all bytes are written successfully, a reply packet "OK" is sent. Otherwise an error reply, "E01" is sent. The actual error number does not matter—it is not used by the client.

	Caution
	The use of set_program8 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no MMU or cache.

The p and P packets are implemented respectively by rsp_read_reg () and rsp_write_reg ().

These functions are very similar in implementation to rsp_read_all_regs () and rsp_write_all_regs () (see Section 4.7.6).

The two differences are that the packet data must be parsed to identify the register affected, and (clearly) only one register is read or written.

Query packets all start with q. The functionality is all provided in the function rsp_query ().

4.7.9.4.  Query About Executable Relocation

The qOffsets packet requests a reply string of the format "Text=xx;Data=yy;Bss=zz" to identify the offsets used in relocating the sections of code to be downloaded.

No relocation is used in this target, so the fixed string "Text=0;Data=0;Bss=0" is sent as a reply.

	Caution
	The GDB User Guide ([3]) suggests the final ";Bss=zz" is optional. This is not the case. It must be specified.

Set packets all start with Q. The functionality is all provided in rsp_set ().

The QPassSignals packet is used to pass signals to the target process. This is not supported, and not reported as supported in a qSupported packet (see Section 4.7.9.5), so should never be received.

If a QPassSignals packet is received, an empty response is used to indicate no support.

The functionality for the R packet is provided in rsp_restart (). The start address of the current target is held in rsp.start_addr. The program counter is set to this address using set_npc () (see Section 4.6.5).

The processor is not unstalled, since there would be no way to regain control if this happened. It is up to the GDB client to restart execution (with continue or step if that is what is desired).

This packet should only be used in extended remote debugging.

The step packet (s) requests a single machine instruction step. Its implementation is almost identical to that of the continue (c) packet, but using the functions rsp_step () and rsp_step_generic ().

The sole difference is that the generic function sets, rather than clears the single stepping flag in Debug Mode Register 1. This ensures a TRAP exception is raised after the next instruction completes execution.

  cpu_state.sprs[SPR_DRR]   = 0;
  cpu_state.sprs[SPR_DMR2] &= ~SPR_DMR2_WGB;
  cpu_state.sprs[SPR_DMR1] |= SPR_DMR1_ST;
  cpu_state.sprs[SPR_DSR]  |= SPR_DSR_TE;
	

The v packets provide additional flexibility in controlling execution on the target. Much of this is related to non-stop targets with multithreading support and to flash memory control and need not be supported in a simple implementation.

All the v packet functionality is provided in the function rsp_vpkt ().

      rsp_restart ();
      put_str_packet ("S05");
	  

The X provides for data to be written to the target in binary format. This is the mechanism of choice for program loading (the GDB load command). GDB will first probe the target with an empty X packet (which is 7-bit clean). If an "OK" response is received, subsequent transfers will use the X packet. Otherwise M packets will be used. Thus even 7-bit clean implementations should still support replying to an empty X packet.

The example implementation is found in rsp_write_mem_bin (). Even though the data is binary, it must still be escaped so that '#', '$' and '}' characters are not mistaken for new packets or escaped characters.

Each byte is read, and if escaped, restored to its original value. The data is written using set_program8 (), having first verified the memory location with verify_memoryarea ().

If all bytes are successfully written, a reply packet of "OK" is sent. Otherwise and error packet ("E01") is sent. The error number does not matter—it is ignored by the target.

	Caution
	The use of set_program8 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no instruction MMU or instruction cache.

Matchpoint is the general term used for breakpoints (both memory and hardware) and watchpoints (write, read and access). Matchpoints are removed with zcommand> packets and set with Z packets. The functionality is provided respectively in resp_remove_matchpoint () and resp_insert_matchpoint ().

The current implementation only supports memory (soft) breakpoints controlled by Z0 and Z0 packets. However the OpenRISC 1000 architecture and Or1ksim have hardware breakpoint and watchpoint functionality within the debug unit, which will be supported in the future.

The target is responsible for keeping track of any memory breakpoints set. This is managed through the hash table pointed to by rsp.mp_hash. Each matchpoint is recorded in a matchpoint entry:

struct mp_entry
{
  enum mp_type       type;
  unsigned long int  addr;
  unsigned long int  instr;
  struct mp_entry   *next;
};
	

When an instruction is replaced by l.trap for a memory breakpoint, the replace instruction is recorded in the hash table as a struct mp_entry with type BP_MEMORY. This allows it to be replaced when the the breakpoint is cleared.

The hash table is accessed by the functions mp_hash_init (), mp_hash_add (), mp_hash_lookup () and mp_hash_delete (). These are described in more detail in Section 4.3.2.1

4.7.15.1.  Setting Matchpoints

Only memory (soft) breakpoints are supported. The instruction is read from memory at the location of the breakpoint and stored in the hash table (using mp_hash_add ()). A l.trap instruction (OR1K_TRAP_INSTR) is inserted in its place using set_program32 () and a reply of "OK" sent back.

      mp_hash_add (type, addr, eval_direct32 (addr, 0, 0));
      set_program32 (addr, OR1K_TRAP_INSTR);
      put_str_packet ("OK");
	  

	Caution
	The use of eval_direct32 () with second and third arguments both zero and set_program32 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no instruction MMU or instruction cache.

4.7.15.2.  Clearing Matchpoints

Only memory (soft) breakpoints are supported. The instruction that was substituted by l.trap is retrieved and deleted from the hash table using mp_hash_delete (). The instruction is then put back in its original location using set_program32 ().

mp_hash_delete () returns the struct mp_entry that was removed from the hash table. Once the instruction information has been retrieved, its memory must be returned by calling free ().

It is possible to receive multiple requests to delete a breakpoint if the serial connection is poor (due to retransmissions). By checking that the entry is in the hash table, actual deletion of the breakpoint and restoration of the instruction happens at most once.

      mpe = mp_hash_delete (type, addr);

      if (NULL != mpe)
        {
          set_program32 (addr, mpe->instr);
          free (mpe);
        }

      put_str_packet ("OK");
          

	Caution
	The use of set_program32 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no instruction MMU or instruction cache.