Gdb for LegOS

Introduction

I'm stuck because of a combination of:

• Lack of understanding of gdb internals.
• Limitations of H8/300 instruction set.
• Bugs in the H8/300 tool chain.
• I've run out of ideas for workarounds/hacks for the above.

Even with its many limitations, you might still find this useful. It must be better than inserting 'cputs' everywhere!

Everything here describes the set up for Linux only. I see no reason it shouldn't work just as well (or just as badly!) on Windows.

What Works

• Programmed breakpoints (i.e., a call to BREAKPOINT; inserted into a legOS application drops into gdb).
• Examining code & data as hex-dumps, disassembly listing, and at source level.
• Writing data back to legOS memory.
• Examining stack traces/call frames, including arguments & local (stack) variables.
• Inserting breakpoints at run time, but only ever once!

What Doesn't Work

• Reliably inserting breakpoints at runtime.
• Reliably continuing after a runtime breakpoint is handled.
• Stepping at instruction/source line level.
• Reliably mapping breakpoint addresses to C source code listings.
• Freezing the legOS scheduler while handling a breakpoint.
• Building non-optimized legOS applications.

How its Supposed to Work

Host Side

• A version of gdb targeted at H8/300 is run. This lets you use the normal gdb command line, plus any number of front ends that have been written for it.
• Gdb doesn't understand the usual legOS .lx files, so the application make rules are modified to produce a h8300-coff file. The .lx file is download to the RCX as usual, and the h8300-coff file is loaded into gdb.
• Gdb is told that its target (the RCX) is attached via a TCP/IP host:port. At the other end of this connection lives a small linux server that receives the gdb commands and relays them to legOS, using the IR tower. This server also relays responses from legOS back to gdb.

Target Side

• A small program (the debug stub, rcx-stub.c) is added to the legOS kernel. This listens to commands received on the IR link (using lnp), decodes and actions them, and sends the appropriate response back. Most of this code is ported from the standard gdb remote stubs (i386-stub.c).
• The stub is entered either by the legOS application calling BREAKPOINT (e.g., as the result of the Prgm key being pressed), or as the result of a breakpoint inserted by gdb.
• The H8/300 instruction set doesn't support software trap instructions. Fortunately the RCX firmware has a spare interrupt vector (INT2). This is hijacked as a software trap by inserting the two byte instruction jsr @@0x0c at the breakpoint address. (See here for an alternate way of inserting a breakpoint, suggested by Markus L. Noga).
• The stub handler for INT2 is a piece of assembler that fiddles with the stack & registers to set up information for the remainder of the stub. It is also responsible for returning to the right place after a breakpoint is continued.
• All threads should be suspended while processing a breakpoint.
• While handling a breakpoint, all motors should be stopped. This stops your robot disappearing while you tinker with gdb!

Download

Install

1. cd into your LEGOS_ROOT directory and type tar xf gdblegos.tar. This tar file doesn't overwrite any standard legOS files. This installs the file rcx-stub.c in $LEGOS_ROOT/kernel, rcx-stub.h in $LEGOS_ROOT/include and gdbsrv.py in $LEGOS_ROOT.
2. The debug stub can be run as part of your application by adding it to your Makefile. I prefer to run it as part of the kernel. To do this, add rcx-stub.c to the KSOURCES macro of Makefile.kernel and rebuild the legOS kernel.
3. The stub uses lnp host & RCX ports 0x02. If you want to change these, redefine DBG_HOST_PORT and DBG_TARGET_PORT in rcx-stub.h, then rebuild the kernel.
4. If you have rebuilt your legOS kernel, download it to the RCX in the usual way.
5. To run gdbsrv.py you will need the Python interpreter and the Python lnp extension pylnp. Pylnp can be downloaded from here.

Building Debuggable Programs

Prepare your application for debugging.

1. It must be compiled with the -g flag. It also helps to turn off the -fomit-frame-pointer and -O2 options. To prevent a non-optimized kernel from being built, I added the following to Makefile.common

    
   COPTDBG  =-g -fno-builtin
   CFLAGSDBG=$(COPTDBG) $(CWARN) $(CINC)
    

   Then modify the application Makefile .o.c rule to read:

    
   %.o: %.c
   	$(CC) $(CFLAGSDBG) -c $*.c -o $*.o
    

   **BUG** Turning off the optimizer causes compile errors when calling motor_a_dir legOS functions. I think this is something to do with inline directives. Running gdb with the optimizer is not a disaster, but it can get confusing.

2. Your application should call debugInit() near the top of main. This initializes the debugger, and sets up lnp handlers,
3. To build a COFF file that gdb can read, you need to discover the address at which legOS relocates your application code. The only way I know of getting this information is to write an application that displays the address of its first function. Here's an example:

    
   // Print out start address. Used to find offset for generating coff
   // files.
   #include <unistd.h>
   #include <conio.h>
   
   int main(int argc, char *argv[]) {
       cputw((int)main);
       return 0;
   }  
    

   This displays the relocation address on the LCD (0xb054 on my version of the kernel). Fortunately, you only need to this after a kernel change.

   **BUG** There must be an easier way to get the relocation address than this!

4. You need to add a rule to build the COFF file used by gdb. Add these lines to Makefile.user:

    
   # Put this line somewhere near the top
   COFFFLAGS=-T$(LEGOS_ROOT)boot/legOS.lds -relax -L$(LEGOS_ROOT)/lib \
             -Ttext <EDITME> --oformat coff-h8300
   
   # Modify the .ds1.o rule to produce a coff file as well.
   %.ds1: %.o $(DOBJECTS) $(DYNAMIC_LDS)
   	$(LD) $(DLDFLAGS) $*.o $(DOBJECTS) $(LIBS) -o $*.ds1 -Ttext $(BASE1)
   	$(LD) $(COFFFLAGS) $*.o $(DOBJECTS) $(LIBS) -o $*.coff 
   
    

   You need to replace <EDITME> with the relocation address discovered earlier. This should produce a .coff file, in addition to the usual .lx file.
5. Now download the .lx file to the brick in the usual manner.

A Debug Session

1. Build a debuggable program as described above, and download it to the brick as usual.
2. Start the linux lnpd LNP daemon.
3. Run the linux gdb server gdbsrv.py. You must have Python & the LNP extension installed. (**BUG** Someone might like to recode gdbsrv.py as a C program to remove the Python dependency). Gdbsrv.py defaults to TCP/IP port 6789 and LNP host/target ports 2. These can be overridden on the command line. The -v option turns on some debug info. This is handy for finding out what gdb is sending to legOS. If you restart lnpd, you must restart gdbsrv.py. Normally lnpd and gdbsrv.py can be left running in the background.
4. Start the H8/300 targeted gdb program. Version 4.17 works best (this is the one supplied with egcs toolchain). The latest version (4.18) works, but it doesn't print stack frames. (**BUG** This bug needs to be reported to the gdb team). Once started, gdb should display the message:

    
   GNU gdb 4.17
   Copyright 1998 Free Software Foundation, Inc.
   GDB is free software, covered by the GNU General Public License, and you are
   welcome to change it and/or distribute copies of it under certain conditions.
   Type "show copying" to see the conditions.
   There is absolutely no warranty for GDB.  Type "show warranty" for details.
   This GDB was configured as "--host=i686-pc-linux-gnu --target=h8300-hitachi-hms"...
   (gdb) 
    

   Note the --target line.
5. Gdb needs to be told about its target. Type the command target remote localhost:6789. This sends a message to the debug stub on the brick, via gdbsrv.py and lnpd. The port number (6789) must match that used by gdbsrv.py.
6. The legOS application needs to respond to the message from gdb. There are a couple of ways of doing this:
   • Add a call to the macro BREAKPOINT; at interesting points in your program.
   • Call BREAKPOINT; as the result of a key press. I like to to this from a separate task like this:

      
     wakeup_t KeyCheck(wakeup_t data) {
       if (dkey == KEY_PRGM) {
         return 1;
       }
       return 0;
     }
     
     int waitForKey(int argc, char** argv) {
       int kv;
       while (1) {
         if ((kv = wait_event(KeyCheck, 0))) {
           if (kv == 1) {
     	BREAKPOINT;
           }
         }
       }
     }
     
     int main(int argc, char **argv) {
         debugInit();
         execi(waitForKey, 0, 0, PRIO_NORMAL, DEFAULT_STACK_SIZE);
         ...  
     }
      

     Every time the Prgm key is pressed, gdb drops into a breakpoint.
7. When you hit a breakpoint, gdb should wake up and tell you where your program is. Bingo! Gdb is now talking to the debug stub in legOS, which is waiting for commands from gdb. You can examine memory, print the stack frame, set breakpoints & watches, all the usual things (but see the Known Bugs section below before getting too excited). Be patient, the IR tower only runs as 2400 baud, and there'e a fair bit of traffic flowing between gdb & legOS.

If It Doesn't Work

• Make sure theres a call to BREAKPOINT; in your application, and that it is getting executed. There's no way for gdb to interrupt a running legOS program, so you must co-operate with gdb to get its attention.
• Make sure you've obtained the correct relocation address for your kernel, and that you've rebuilt your application COFF files with it.
• Use the -v flag on gdbsrv.py. This should show all traffic between gdb and legOS.
• Type set remotedebug 1 in gdb. This shows its version of the legOS traffic.

Known Bugs/TODO List

• Gdb sometimes/often reports the wrong line number at a breakpoint. I think this is a h8/300 toolchain bug. Dumping the coff symbols for an application also report the wrong line numbers (try running /usr/local/bin/h8300-hitachi-hms-objdump --debugging and look at the line numbers). This needs to be isolated and reported to the toolchain developers.
• Continuing after a breakpoint inserted by gdb crashes legOS. Breakpoints coded using BREAKPOINT; are fine, its just those inserted at run time by gdb that fail. I'm sure this is caused by the debug stub code. What's needed is a better understanding of how gdb inserts & restores breakpoints.
• The debug stub doesn't implement the gdb next/step command. This is non-trivial, as the stub needs to work out the where the next instruction is, and the targets for branch instructions.
• Gdb is supposed to insert breakpoints after the function prolog. Sometimes it gets this wrong. The fix to to set the breakpoint at the first line of executable code.
• The setup for debugging is over-complicated & error-prone.
• Some unoptimized code (compiled without the -O flag) cannot be compiled. I think this is caused by inline functions in the kernel. A solution might be to wrap these inside normal functions built into the kernel.
• An easier way to get relocation addresses is required.
• Gdbsrv.py needs to be recoded in C to remove the Python dependency.
• The latest gdb Version (4.18) doesn't report stack frames. This needs to be isolated and reported to the gdb team.
• Gdbsrv.py needs to be restarted if lnpd is.
• Gdbsrv.py connects permanently to IR Tower, burning out the battery.
• Tasks other than the breakpoint task are still scheduled when the breakpoint is hit. This means multi-tasking robots still run, even inside a breakpoint. This is probably not a good thing. The fix for this is to recode the debug stub lnp calls to be non-interrupt driven, so that semaphore calls are no longer required. That is, the IR I/O ports must be polled. The payoff for doing this is that large parts of the kernel become debuggable!
• A gdb interrupt handler in legOS required. This will allow a legOS application to be attached to at run time.
• The gdb 'kill' command doesn't work properly.
• The deug stub should save & restore the state of the motors while talking to gdb.

An Alternate Way of Inserting Breakpoints