Putting it all together

In summary, when your program is ready to debug, you must follow these steps.

1. Make sure you have defined the supporting low-level routines (see section What you must do for the stub):

   getDebugChar, putDebugChar,
   flush_i_cache, memset, exceptionHandler.
   

2. Insert these lines near the top of your program:

   set_debug_traps();
   breakpoint();
   

3. For the 680x0 stub only, you need to provide a variable called exceptionHook. Normally you just use:

   void (*exceptionHook)() = 0;
   

   but if before calling set_debug_traps, you set it to point to a function in your program, that function is called when continues after stopping on a trap (for example, bus error). The function indicated by exceptionHook is called with one parameter: an int which is the exception number.
4. Compile and link together: your program, the debugging stub for your target architecture, and the supporting subroutines.
5. Make sure you have a serial connection between your target machine and the host, and identify the serial port on the host.
6. Download your program to your target machine (or get it there by whatever means the manufacturer provides), and start it.
7. To start remote debugging, run on the host machine, and specify as an executable file the program that is running in the remote machine. This tells how to find your program's symbols and the contents of its pure text.
8. Establish communication using the target remote command. Its argument specifies how to communicate with the target machine--either via a devicename attached to a direct serial line, or a TCP port (usually to a terminal server which in turn has a serial line to the target). For example, to use a serial line connected to the device named `/dev/ttyb':

   target remote /dev/ttyb
   

   To use a TCP connection, use an argument of the form host:port. For example, to connect to port 2828 on a terminal server named manyfarms:

   target remote manyfarms:2828
   

Now you can use all the usual commands to examine and change data and to step and continue the remote program.

To resume the remote program and stop debugging it, use the detach command.

Whenever is waiting for the remote program, if you type the interrupt character (often C-C), attempts to stop the program. This may or may not succeed, depending in part on the hardware and the serial drivers the remote system uses. If you type the interrupt character once again, displays this prompt:

Interrupted while waiting for the program.
Give up (and stop debugging it)?  (y or n)

If you type y, abandons the remote debugging session. (If you decide you want to try again later, you can use `target remote' again to connect once more.) If you type n, goes back to waiting.

Go to the first, previous, next, last section, table of contents.