#include <oskit/gdb.h>int gdb_trap(struct trap_state *trap_state);
This function is intended to be installed as the kernel trap handler for all traps by setting each of the entries in the base_trap_handlers array to point to it (see Section 10.8.4), when remote GDB debugging is desired. (Alternatively, the client OS can use its own trap handlers which chain to gdb_trap when appropriate.) This function converts the contents of the trap_state structure saved by the base trap entrypoint code into the gdb_state structure used by GDB. It also converts the architecture-specific processor trap vector number into a suitable machine-independent signal number which can be interpreted by the remote debugger.After converting the register state and trap vector appropriately, this function calls the appropriate protocol-specific GDB stub through the gdb_signal function pointer variable (see Section 10.17.9). Finally, it converts the final register state, possibly modified by the remote debugger, back into the original trap_state format and returns an appropriate success or failure code as described below.
On architectures that don't provide a way for the kernel to ``validate'' memory accesses before performing them, such as the x86, this function also provides support for ``recovering'' from faulting memory accesses during calls to gdb_copyin or gdb_copyout (see Sections 10.17.6 and 10.17.7). This is typically implemented using a ``recovery pointer'' which is set before a ``safe'' memory access and cleared afterwards; gdb_trap checks this recovery pointer, and if set, modifies the trap state appropriately and returns from the trap without invoking the protocol-specific GDB stub.
If the client OS uses its own trap entrypoint code which saves register state in a different format when handling traps, then the client OS will also need to override the gdb_trap function with a version that understands its custom saved state format.
- trap_state
- A pointer to the saved register state representing the processor state at the time the trap occurred. The saved state must be in the default format defined by the OSKit's base environment.
The gdb_trap function returns success (zero) when the remote debugger instructs the local stub to resume execution at the place it was stopped and ``consume'' the trap that caused the debugger to be invoked; this is the normal case.This function returns failure (nonzero) if the remote debugger passed the same or a different signal back to the local GDB stub, instructing the local kernel to handle the trap (signal) itself. If the default trap entrypoint mechanism provided by the base environment in use, then this simply causes the kernel to panic with a register dump, since the default trap code does not know how to ``handle'' signals by itself. However, if the client OS uses its own trap entrypoint mechanism or interposes its own trap handler over gdb_trap, then it may wish to interpret a nonzero return code from gdb_trap as a request for the trap to be handled using the ``normal'' mechanism, (e.g., dispatched to the application being debugged).
- trap_state
- 10.8.1
- gdb_state
- 10.17.4
- gdb_signal
- 10.17.9
- gdb_trap_recover
- 10.17.8