Base version.

7 files changed, 374 insertions, 0 deletions

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.}
+
+