diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/rgdb_specs/gdbinternals.t | 254 |
1 files changed, 0 insertions, 254 deletions
diff --git a/doc/rgdb_specs/gdbinternals.t b/doc/rgdb_specs/gdbinternals.t deleted file mode 100644 index afb1f39aee..0000000000 --- a/doc/rgdb_specs/gdbinternals.t +++ /dev/null @@ -1,254 +0,0 @@ -@c -@c RTEMS Remote Debugger Server Specifications -@c -@c Written by: Eric Valette <valette@crf.canon.fr> -@c Emmanuel Raguet <raguet@crf.canon.fr> -@c -@c -@c $Id$ -@c - -@chapter A Rapid Tour of GDB Internals - -To help the reader to understand what needs to be implemented, we -will present briefly how GDB works regardless if the target is local or remote. -A debugger is a tool which enables control of the execution of software on a -target system. In most of cases, the debugger connects to a target system, attaches -a process, inserts breakpoints and resumes execution. Then the normal execution -is completely events driven (process execution stopped due to a breakpoint, -process fault, single-step,...) coming from the debuggee. It can also directly -access some parts of the target processor context (registers, data memory, code -memory,...) and change their content. Native GDB debugger can just be seen as -special cases where the host and the target are on the same machine and GDB -can directly access the target system debug API. - - -In our case, the host and the target are not on the same machine and -an Ethernet link is used to communicate between the different machines. Because -GDB needs to be able to support various targets (including Unix core file, ...), -each action that needs to be performed on the debuggee is materialized by a -field of the following @emph{targets_op}s structure : - -@example -struct target_ops -@{ - char *to_shortname; /* Name this target type */ - char *to_longname; /* Name for printing */ - char *to_doc; /* Documentation. Does not include trailing - newline, and starts with a one-line - description (probably similar to - to_longname). */ - void (*to_open) PARAMS ((char *, int)); - void (*to_close) PARAMS ((int)); - void (*to_attach) PARAMS ((char *, int)); - void (*to_detach) PARAMS ((char *, int)); - void (*to_resume) PARAMS ((int, int, enum target_signal)); - int (*to_wait) PARAMS ((int, struct target_waitstatus *)); - void (*to_fetch_registers) PARAMS ((int)); - void (*to_store_registers) PARAMS ((int)); - void (*to_prepare_to_store) PARAMS ((void)); - - /* Transfer LEN bytes of memory between GDB address MYADDR and - target address MEMADDR. If WRITE, transfer them to the target, - else transfer them from the target. TARGET is the target from - which we get this function. - - Return value, N, is one of the following: - - 0 means that we can't handle this. If errno has been set, - it is the error which prevented us from doing it (FIXME: - What about bfd_error?). - - positive (call it N) means that we have transferred N bytes - starting at MEMADDR. We might be able to handle more bytes - beyond this length, but no promises. - - negative (call its absolute value N) means that we cannot - transfer right at MEMADDR, but we could transfer at least - something at MEMADDR + N. */ - - int (*to_xfer_memory) - PARAMS ((CORE_ADDR memaddr, char *myaddr, - int len, int write, - struct target_ops * target)); - - void (*to_files_info) PARAMS ((struct target_ops *)); - int (*to_insert_breakpoint) PARAMS ((CORE_ADDR, char *)); - int (*to_remove_breakpoint) PARAMS ((CORE_ADDR, char *)); - void (*to_terminal_init) PARAMS ((void)); - void (*to_terminal_inferior) PARAMS ((void)); - void (*to_terminal_ours_for_output) PARAMS ((void)); - void (*to_terminal_ours) PARAMS ((void)); - void (*to_terminal_info) PARAMS ((char *, int)); - void (*to_kill) PARAMS ((void)); - void (*to_load) PARAMS ((char *, int)); - int (*to_lookup_symbol) PARAMS ((char *, CORE_ADDR *)); - void (*to_create_inferior) PARAMS ((char *, char *, char **)); - void (*to_mourn_inferior) PARAMS ((void)); - int (*to_can_run) PARAMS ((void)); - void (*to_notice_signals) PARAMS ((int pid)); - int (*to_thread_alive) PARAMS ((int pid)); - void (*to_stop) PARAMS ((void)); - enum strata to_stratum; - struct target_ops - *DONT_USE; /* formerly to_next */ - int to_has_all_memory; - int to_has_memory; - int to_has_stack; - int to_has_registers; - int to_has_execution; - struct section_table - *to_sections; - struct section_table - *to_sections_end; - int to_magic; - /* Need sub-structure for target machine related rather than comm related? */ -@}; -@end example - -This structure contains pointers to functions (in C++, this would -be called a virtual class). Each different target supported by GDB has its own -structure with the relevant implementation of the functions (some functions -may be not implemented). When a user connects GDB to a target via the ``target'' -command, GDB points to the structure corresponding to this target. Then the -user can attache GDB to a specific task via the ``attach'' command. We have -therefore identified two steps to begin a remote debug session : - -@enumerate -@item the choice of the target type (in our case RTEMS), -@item the choice of what to debug (entire system, specific task,...), -@end enumerate -Note that in the case of natives debugger, the choice of the target is implicitly -performed by commands like @b{run}, @b{attach}, @b{detach}. Several -figures will now be described showing the main steps of a debug session. - -@c XXX figure reference -Figure @b{Debug session initialization} explains how the debugger connects to the target -: - -@enumerate -@item The debugger opens a connection to the target. The word ``connection'' -doesn't only mean Ethernet or serial link connection but all the ways by which -a process can communicate with another one (direct function call, messages mailbox, -...), -@item The targets checks if it can accept or reject this connection, -@item If the connection is accepted, the host ``attaches'' the process, -@item the target stops the process, notifies a child's stop to the host -and waits for command, -@item the host can ask information about the debugged process (name, registers,...) -or perform some action like setting breakpoints, ... -@end enumerate - -@c XXX figure reference -Figure @b{Breakpoint and process execution} explains how the debugger manages the -breakpoints and controls the execution of a process : - -@enumerate -@item The host asks the debuggee what is the opcode at the concerned address -in order for GDB to memorize this instruction, -@item the host sends a CONTINUE command : it asks the target to write the -``DEBUG'' opcode (for example, the INTEL ``DEBUG'' opcode is INT3 which -generate a breakpoint trap) instead of the debugged opcode. -@item then the host waits for events, -@item after the change of instruction, the target resumes the execution -of the debuggee, -@item when the ``DEBUG'' opcode is executed, the breakpoint exception -handler is executed and it notifies the host that the process is stopped. Then -it waits for commands (if no command is sent after a certain amount of time, -the connection will be closed by the target). -@item the host asks the target to re-write the right opcode instead of the -''DEBUG'' opcode and then can ask information -@end enumerate - -@c XXX figure reference -Figure @b{Breakpoint and process execution} also shows the case of other ``CONTINUE'' -commands (remember that the ``DEBUG'' opcode has been replaced by the right -instruction): - -@enumerate -@item Host sends first a ``single step'' command to execute the debugged -instruction, -@item It then waits for ``single step`` exception event, -@item the target, once the single step executed, calls the debug exception -handler. It notifies the host that execution is suspended and wait for commands. -@item the host asks the target to re-write the ``DEBUG'' opcode (breakpoint -trap) instead of the debugged one. -@item then the host sends a ``CONTINUE'' command in order the target to -resume the process execution to the next breakpoint. -@end enumerate - -@c XXX figure reference -Figure @b{Detach a process and close a connection} explains how the debugger disconnects from -a target : - -@enumerate -@item the host sends a detach command to the target. -@item the target detaches the concerned process, notifies the detachment -and resumes the process execution. -@item once notified, the host sends a close connection command. -@item the target closes the connection. -@end enumerate -These 3 examples show that the mains actions that are performed by -the host debugger on the target are only simple actions which look like : - -@itemize @bullet -@item read/write code, -@item read/write data, -@item read/write registers, -@item manage exceptions, -@item send/receive messages to/from the host. -@end itemize - - -@c -@c Debug session initialization Figure -@c - -@ifclear use-html -@image{seqinit,,,"Debug session initialization"} -@end ifclear - - -@ifset use-html -@c <IMG SRC="seqinit.jpg" WIDTH=500 HEIGHT=600 ALT="Debug session initialization"> -@html -<IMG SRC="seqinit.jpg" ALT="Debug session initialization"> -@end html -@end ifset - - -@c -@c Breakpoint and process execution Figure -@c - -@ifclear use-html -@image{seqbreak,,9in,"Caption Breakpoint and process execution"} -@end ifclear - -@ifset use-html -@c <IMG SRC="seqbreak.jpg" WIDTH=500 HEIGHT=600 ALT="Breakpoint and process execution"> -@html -<IMG SRC="seqbreak.jpg" ALT="Breakpoint and process execution"> -@end html -@end ifset - - - -@c -@c Detach a process and close a connection Figure -@c - -@ifclear use-html -@image{seqdetach,,,"Detach a process and close a connection"} -@end ifclear - -@ifset use-html -@c <IMG SRC="seqdetach.jpg" WIDTH=500 HEIGHT=600 ALT="Detach a process and close a connection"> -@html -<IMG SRC="seqdetach.jpg" ALT="Detach a process and close a connection"> -@end html -@end ifset - - - - |