17.4.1 What the Stub Can Do for You

The debugging stub for your architecture supplies these three subroutines:

set_debug_traps

This routine arranges for handle_exception to run when your program stops. You must call this subroutine explicitly near the beginning of your program.

handle_exception

This is the central workhorse, but your program never calls it explicitly—the setup code arranges for handle_exception to run when a trap is triggered.

handle_exception takes control when your program stops during execution (for example, on a breakpoint), and mediates communications with No value for GDBN on the host machine. This is where the communications protocol is implemented; handle_exception acts as the No value for GDBN representative on the target machine. It begins by sending summary information on the state of your program, then continues to execute, retrieving and transmitting any information No value for GDBN needs, until you execute a No value for GDBN command that makes your program resume; at that point, handle_exception returns control to your own code on the target machine.

breakpoint

Use this auxiliary subroutine to make your program contain a breakpoint. Depending on the particular situation, this may be the only way for No value for GDBN to get control. For instance, if your target machine has some sort of interrupt button, you won't need to call this; pressing the interrupt button transfers control to handle_exception—in effect, to No value for GDBN. On some machines, simply receiving characters on the serial port may also trigger a trap; again, in that situation, you don't need to call breakpoint from your own program—simply running ‘target remote’ from the host No value for GDBN session gets control.

Call breakpoint if none of these is true, or if you simply want to make certain your program stops at a predetermined point for the start of your debugging session.