From 387f41adcd32dff7b7de7fe34a8637692ee7c7b1 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 10 Feb 1999 18:33:15 +0000 Subject: Base version. --- doc/rtems_gdb/Makefile | 92 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/rtems_gdb/commands.t | 51 +++++++++++++++++++++++++++ doc/rtems_gdb/example.t | 76 +++++++++++++++++++++++++++++++++++++++ doc/rtems_gdb/intro.t | 18 ++++++++++ doc/rtems_gdb/started.t | 57 ++++++++++++++++++++++++++++++ doc/rtems_gdb/swarch.t | 32 +++++++++++++++++ doc/rtems_gdb/trouble.t | 48 +++++++++++++++++++++++++ 7 files changed, 374 insertions(+) create mode 100644 doc/rtems_gdb/Makefile create mode 100644 doc/rtems_gdb/commands.t create mode 100644 doc/rtems_gdb/example.t create mode 100644 doc/rtems_gdb/intro.t create mode 100644 doc/rtems_gdb/started.t create mode 100644 doc/rtems_gdb/swarch.t create mode 100644 doc/rtems_gdb/trouble.t (limited to 'doc/rtems_gdb') diff --git a/doc/rtems_gdb/Makefile b/doc/rtems_gdb/Makefile new file mode 100644 index 0000000000..42e5da6b4f --- /dev/null +++ b/doc/rtems_gdb/Makefile @@ -0,0 +1,92 @@ +# +# COPYRIGHT (c) 1988-1998. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# +# $Id$ +# + +PROJECT=rtems_gdb +DISTRIBUTION_LEVEL=public + +include ../Make.config + +all: html info ps + +dirs: + $(make-dirs) + +COMMON_FILES=../common/cpright.texi ../common/setup.texi + +GENERATED_FILES= \ + intro.t swarch.t started.t commands.t trouble.t example.t + + +FILES=$(PROJECT).texi $(GENERATED_FILES) + +INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) + +info: dirs $(PROJECT) + #cp $(wildcard $(PROJECT) $(PROJECT)-*) $(INFO_INSTALL) + # cp $(PROJECT) $(INFO_INSTALL) + +$(PROJECT): $(FILES) + $(MAKEINFO) $(PROJECT).texi + +dvi: $(PROJECT).dvi +ps: dirs $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +# run texi2dvi twice to generate the xref's properly. +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + texi2dvi $(PROJECT).texi + +html: dirs $(FILES) + -mkdir -p $(WWW_INSTALL)/$(PROJECT) + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ + $(PROJECT).texi + +clean: + rm -f *.o $(PROG) *.txt core + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES) + rm -f *.fixed _* network.t + +# +# Process Automatically Generated Files +# + +intro.texi: intro.t Makefile + $(BMENU) -p "Top" \ + -u "Top" \ + -n "" ${*}.t + +swarch.texi: swarch.t Makefile + $(BMENU) -p "Top" \ + -u "Top" \ + -n "" ${*}.t + +started.texi: started.t Makefile + $(BMENU) -p "Top" \ + -u "Top" \ + -n "" ${*}.t + +commands.texi: commands.t Makefile + $(BMENU) -p "Top" \ + -u "Top" \ + -n "" ${*}.t + +trouble.texi: trouble.t Makefile + $(BMENU) -p "Top" \ + -u "Top" \ + -n "" ${*}.t + +example.texi: example.t Makefile + $(BMENU) -p "Top" \ + -u "Top" \ + -n "" ${*}.t + diff --git a/doc/rtems_gdb/commands.t b/doc/rtems_gdb/commands.t new file mode 100644 index 0000000000..fa2d27f8ff --- /dev/null +++ b/doc/rtems_gdb/commands.t @@ -0,0 +1,51 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@section Commands + +The usual GDB commands are available to display or modify data structures and +machine registers, disassemble code, display source listings, set and reset +breakpoints, control the debuggee execution, etc. Refer to Debugging with GDB +for a complete documentation of the standard GDB commands. + +GDB 4.17 has been extended with a number of commands specifically +for multi-threaded debugging within a RTEMS host-target environment. These commands +are described in this section. + + +@subsection Host-target connection control + +@itemize +@item (gdb) setrpcmode sun : specifies the SUN RPC type. +@item (gdb) setdaemontype rdbg : specifies the RDBG debug server type. +@item (gdb) target rtems target-name : specifies the target type. +@end itemize + +@subsection System status information + +@itemize +@item (gdb) info threads : gives a list of all threads in the debuggee, +their names, identifiers and states. It also indicates which thread is +the target thread. +@end itemize + + +@subsection Thread control + +@itemize +@item (gdb) thread target [id] : allows the user to get/set the target thread. +The argument id is either the thread's symbolic name or its local identifier. +@item (gdb) thread detach [id...] : all stops (breakpoints) of some specified +thread(s) can be ignored using the thread detach command. Each time a detached +thread hits a breakpoint, RTEMS/GDB will automatically restart the debuggee +without passing control to the user. +@item (gdb) thread attach [id...] : (re)attach specified thread(s). +@end itemize + + + diff --git a/doc/rtems_gdb/example.t b/doc/rtems_gdb/example.t new file mode 100644 index 0000000000..e1f0ea4cbd --- /dev/null +++ b/doc/rtems_gdb/example.t @@ -0,0 +1,76 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@section Debug Session Example + +@example +GNU gdb 4.17 +Copyright 1998 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, and you are +welcome to change it and/or 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. +This GDB was configured as --host=i686-pc-linux-gnu --target=i386RTEMS". +(gdb) setrpcmode sun +(gdb) setdaemontype rdbg +(gdb) target rtems usnet-test +Attaching remote machine across net... +Connected to usnet-test. +Now the "run" command will start a remote process. +(gdb) file /buildr4/pc386/tests/debug.exe +Reading symbols from /buildr4/pc386/tests/debug.exe...done. +(gdb) attach 1 +Attaching program: /buildr4/pc386/tests/debug.exe pid 1 +0x22fe65 in enterRdbg () +(gdb) info threads +There are 8 threads: +Id. Name Detached Suspended +134283273 Rini No No <= current target thread +0x22fe65 in enterRdbg () +134283272 Evnt No No +_Thread_Dispatch () at /rtems4/c/src/exec/score/src/thread.c:315 +134283271 SPE2 No No +_Thread_Dispatch () at /rtems4/c/src/exec/score/src/thread.c:315 +134283270 SPE1 No No +_Thread_Handler () at /rtems4/c/src/exec/score/src/thread.c:1107 +134283269 RDBG No No +0x22fe65 in enterRdbg () +134283268 SCrx No No +_Thread_Dispatch () at /rtems4/c/src/exec/score/src/thread.c:315 +134283267 SCtx No No +_Thread_Dispatch () at /rtems4/c/src/exec/score/src/thread.c:315 +134283266 ntwk No No +_Thread_Dispatch () at /rtems4/c/src/exec/score/src/thread.c:315 +(gdb) b init.c:92 +Breakpoint 1 at 0x200180: file /rtems4/c/src/tests/samples/debug/init.c, line 92. +(gdb) c +Continuing. +Thread 134283273 (Rini) has been deleted. +[Switching to Rtems thread 134283271 (Not suspended) ( <= current target thread )] +Breakpoint 1, example2 (argument=4) at /rtems4/c/src/tests/samples/debug/init.c:92 +92 tuto += tuti; +(gdb) b init.c:66 +Breakpoint 2 at 0x200128: file /rtems4/c/src/tests/samples/debug/init.c, line 66. +(gdb) c +Continuing. +[Switching to Rtems thread 134283270 (Not suspended) ( <= current target thread )] +Breakpoint 2, example1 (argument=4) at /rtems4/c/src/tests/samples/debug/init.c:66 +66 toto += titi; +(gdb) c +Continuing. +[Switching to Rtems thread 134283271 (Not suspended) ( <= current target thread )] +Breakpoint 1, example2 (argument=4) at /rtems4/c/src/tests/samples/debug/init.c:92 +92 tuto += tuti; +(gdb) s +93 if (print_enable2) +(gdb) detach +Detaching program: /buildr4/pc386/tests/debug.exe pid 1 +Warning: the next command will be done localy! +If you want to restart another remote program, reuse the target command +(gdb) quit +@end example diff --git a/doc/rtems_gdb/intro.t b/doc/rtems_gdb/intro.t new file mode 100644 index 0000000000..f0c907ec76 --- /dev/null +++ b/doc/rtems_gdb/intro.t @@ -0,0 +1,18 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Introduction + +GDB 4.17 is a source-level symbolic debugger for RTEMS environment. +This version is an extension of GNU GDB version 4.17, adapted for the debugging +of RTEMS applications in a heterogeneous host-target environment. + +This paper documents @b{only} the RTEMS/GDB extensions to GNU +GDB 4.17, as well as its use in the RTEMS environment. The reader is assumed +to be familiar with GNU GDB. + diff --git a/doc/rtems_gdb/started.t b/doc/rtems_gdb/started.t new file mode 100644 index 0000000000..e2b80b6c36 --- /dev/null +++ b/doc/rtems_gdb/started.t @@ -0,0 +1,57 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + + +@section Getting Started + +This section describes the steps which are necessary to set up a +debugging session with RTEMS/GDB. + + +@subsection Compiling The System Components + +The components that need to be debugged have to be compiled with the -g option +in order the generated file to contain the required information for the debug +session. + + +@subsection Starting a debugging session + +After having launched GDB, the user must connect to the RTEMS target with the +following commands: + +@example + +(gdb) setrpcmode sun + +(gdb) setdaemontype rdbg + +(gdb) target rtems target-name + +@end example + +Then he can use the file GDB command to specify the binary to be debugged. + +This initialization phase can be written in a @code{``.gdbinit''} +file. Each time, the user will launch GDB, it will execute this initialization +sequence. + + +@subsection Attaching To The System + +The entire target system is viewed as a single multi-threaded process, +the identifier of which is 1. To attach, use: + +@example +(gdb) attach 1 +@end example + +When successfully attached, the user can control the execution of +the target system from the debugger. + + diff --git a/doc/rtems_gdb/swarch.t b/doc/rtems_gdb/swarch.t new file mode 100644 index 0000000000..ce86cf52bf --- /dev/null +++ b/doc/rtems_gdb/swarch.t @@ -0,0 +1,32 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + + +@chapter Software Architecture + +RTEMS/GDB host-target debugger is architectured around: + +@itemize @bullet +@item One debugger, running on the host. +@item One debug server, running on the target. +@end itemize + +The host debugger communicates with the debug server using Sun RPC +over UDP/IP (Ethernet). + +When opening a debugging session, the user takes the control over +the entire target system. The target system is viewed as a single multi-threaded +process. + +The debugger can observe the state of the system objects, without +stopping the entire system. However, breakpoints and stepping affect (stop) +the entire system. + +For a given target, only one single system debugging session is possible +at a time. + diff --git a/doc/rtems_gdb/trouble.t b/doc/rtems_gdb/trouble.t new file mode 100644 index 0000000000..28999aac67 --- /dev/null +++ b/doc/rtems_gdb/trouble.t @@ -0,0 +1,48 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + + +@section Troubleshooting + +This section describes symptoms in some situations where the debugger does not +work correctly, and it gives guidelines for resolving the problems encountered. + + +@subsection Target machine name unknown on the host + +RTEMS/GDB fails to connect to target machine named my_target: + +@example +(gdb) target rtems my_target + +Attaching remote machine across net... Invalid hostname. Couldn't find remote +host address. +@end example + +@i{==> Ask your system administrator to add an entry with the +Internet number of machine my_target in the file /etc/hosts on your host machine. } + + +@subsection{Debug server not present + +The target rtems command fails: + +@example + +(gdb) target rtems my\_target + +Attaching remote machine across net... RPC timed out. Couldn't connect +to remote target + +@end example + + +@i{==> Verify that the target system is properly configured, +and is running the debugging daemon and communication stack.} + + -- cgit v1.2.3