Debugging with GDB

Node:Hitachi Boards, Next:Hitachi ICE, Up:H8/300

##### Connecting to Hitachi boards

Use the special `GDB` command `device` port`` if you need to explicitly set the serial device. The default port is the first available port on your host. This is only necessary on Unix hosts, where it is typically something like `/dev/ttya`.

`GDB` has another special command to set the communications speed: `speed` bps``. This command also is only used from Unix hosts; on DOS hosts, set the line speed as usual from outside GDB with the DOS `mode` command (for instance, `mode com2:9600,n,8,1,p` for a 9600bps connection).

The `device` and `speed` commands are available only when you use a Unix host to debug your Hitachi microprocessor programs. If you use a DOS host, GDB depends on an auxiliary terminate-and-stay-resident program called `asynctsr` to communicate with the development board through a PC serial port. You must also use the DOS `mode` command to set up the serial port on the DOS side.

The following sample session illustrates the steps needed to start a program under GDB control on an H8/300. The example uses a sample H8/300 program called `t.x`. The procedure is the same for the Hitachi SH and the H8/500.

First hook up your development board. In this example, we use a board attached to serial port `COM2`; if you use a different serial port, substitute its name in the argument of the `mode` command. When you call `asynctsr`, the auxiliary comms program used by the debugger, you give it just the numeric part of the serial port's name; for example, `asyncstr 2` below runs `asyncstr` on `COM2`.

         C:\H8300\TEST> asynctsr 2
         C:\H8300\TEST> mode com2:9600,n,8,1,p

         Resident portion of MODE loaded

         COM2: 9600, n, 8, 1, p

> Warning: We have noticed a bug in PC-NFS that conflicts with `asynctsr`. If you also run PC-NFS on your DOS host, you may need to disable it, or even boot without it, to use `asynctsr` to control your development board.

Now that serial communications are set up, and the development board is connected, you can start up GDB. Call `gdb` with the name of your program as the argument. `GDB` prompts you, as usual, with the prompt `(gdb)`. Use two special commands to begin your debugging session: `target hms` to specify cross-debugging to the Hitachi board, and the `load` command to download your program to the board. `load` displays the names of the program's sections, and a `*` for each 2K of data downloaded. (If you want to refresh GDB data on symbols or on the executable file without downloading, use the GDB commands `file` or `symbol-file`. These commands, and `load` itself, are described in Commands to specify files.)

         (eg-C:\H8300\TEST) gdb t.x
         GDB is free software and you are welcome to 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.
         GDB 5.2.1, Copyright 1992 Free Software Foundation, Inc...
         (gdb) target hms
         Connected to remote H8/300 HMS system.
         (gdb) load t.x
         .text   : 0x8000 .. 0xabde ***********
         .data   : 0xabde .. 0xad30 *
         .stack  : 0xf000 .. 0xf014 *

At this point, you're ready to run or debug your program. From here on, you can use all the usual GDB commands. The `break` command sets breakpoints; the `run` command starts your program; `print` or `x` display data; the `continue` command resumes execution after stopping at a breakpoint. You can use the `help` command at any time to find out more about GDB commands.

Remember, however, that operating system facilities aren't available on your development board; for example, if your program hangs, you can't send an interrupt--but you can press the RESET switch!

Use the RESET button on the development board

- to interrupt your program (don't use `ctl-C` on the DOS host--it has no way to pass an interrupt signal to the development board); and
- to return to the GDB command prompt after your program finishes normally. The communications protocol provides no other way for GDB to detect program completion.

In either case, GDB sees the effect of a RESET on the development board as a "normal exit" of your program.