summaryrefslogtreecommitdiffstats
path: root/doc/rtems_gdb
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1999-02-10 18:33:15 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1999-02-10 18:33:15 +0000
commit387f41adcd32dff7b7de7fe34a8637692ee7c7b1 (patch)
tree677a23401bc9494034f2e95f9f74f1adcaa78a4b /doc/rtems_gdb
parentc8b5487e87dbf2068b1b751d811dc8348a517166 (diff)
downloadrtems-387f41adcd32dff7b7de7fe34a8637692ee7c7b1.tar.bz2
Base version.
Diffstat (limited to 'doc/rtems_gdb')
-rw-r--r--doc/rtems_gdb/Makefile92
-rw-r--r--doc/rtems_gdb/commands.t51
-rw-r--r--doc/rtems_gdb/example.t76
-rw-r--r--doc/rtems_gdb/intro.t18
-rw-r--r--doc/rtems_gdb/started.t57
-rw-r--r--doc/rtems_gdb/swarch.t32
-rw-r--r--doc/rtems_gdb/trouble.t48
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.}
+
+