New files. This manual was ritten by Eric Valette <valette@crf.canon.fr>

and Emmanuel Raguet <raguet@crf.canon.fr>.  It was submitted in LaTeX
and converted to Texinfo by Joel.  At this point, the figures are
largely ignored except to put in an example block to show they are
missing.

The Makefile should be just enough to produce output with no links between
chapters.
This commit is contained in:
Joel Sherrill committed 1999-04-02 17:04:27 +00:00
1 parent 85e24a3237
commit bea606aee5
16 files changed
+12427

No files matched your search

+113
View File
@@ -0,0 +1,113 @@
#
# COPYRIGHT (c) 1988-1998.
# On-Line Applications Research Corporation (OAR).
# All rights reserved.
#
# $Id$
#
PROJECT=rgdb_specs
DISTRIBUTION_LEVEL=public
include ../Make.config
all: html info ps
dirs:
$(make-dirs)
COMMON_FILES=../common/cpright.texi ../common/setup.texi
GENERATED_FILES= \
intro.texi revision.texi objectives.texi gdbinternals.texi \
interfacing.texi comm.texi daemon.texi conclusion.texi
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
#
@include intro.texi
@include revision.texi
@include objectives.texi
@include gdbinternals.texi
@include interfacing.texi
@include comm.texi
@include daemon.texi
@include conclusion.texi
intro.texi: intro.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
revision.texi: revision.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
objectives.texi: objectives.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
gdbinternals.texi: gdbinternals.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
interfacing.texi: interfacing.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
comm.texi: comm.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
daemon.texi: daemon.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
conclusion.texi: conclusion.t Makefile
$(BMENU) -p "Top" \
-u "Top" \
-n "" ${*}.t
+87
View File
@@ -0,0 +1,87 @@
@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 Communication with GDB
The RTEMS remote debugger will be accessed by GDB on a host machine
through a communication link. We will use the TCP/IP stack included in RTEMS
: the FreeBSD stack. The communication link will be based based on the UDP protocol
and the BSD sockets which are parts of the FreeBSD stack. On top of these layers,
we will plug a module which allows a simple communication between different
machines (especially between different endianess machines) : the SUN Remote
Procedure Call (SUN RPC). This code is freely available on the net and comes
with a BSD like license. With this module, a process can invoke a procedure
on a remote system. The RTEMS remote debugger will be seen by GDB as a SUN RPC
server. Commands will be packed by the GDB SUN RPC client and sent to the server.
This server will unpack these commands, execute them and, if needed, return
results to the SUN RPC client.
Only a minimal subset of the SUN RPC library must be implemented.
For example, the portmapper related API which allows a dynamic allocation of
port numbers will not be implemented and some specific UDP port numbers will
be used to establish the communication between the host and the target. The
SUN RPC library implements the XDR module (eXternal Data Representation) which
is a standard way of encoding data in a portable fashion between different endian
systems. Below are figures describing the additional code and data size for
the minimal library implementation we currently have already implemented for
RTEMS :
@example
$ size -x librpc.a
text data bss dec hex filename
0x40e 0x0 0x0 1038 40e rpc_callmsg.o (ex librpc.a)
0x2f1 0x18 0x0 777 309 rpc_prot.o (ex librpc.a)
0x458 0x0 0x0 1112 458 svc.o (ex librpc.a)
0x4f 0x4 0x0 83 53 svc_auth.o (ex librpc.a)
0x75c 0x18 0x0 1908 774 svc_udp.o (ex librpc.a)
0x711 0x4 0x10 1829 725 xdr.o (ex librpc.a)
0x149 0x0 0x0 329 149 xdr_array.o (ex librpc.a)
0x165 0x20 0x0 389 185 xdr_mem.o (ex librpc.a)
@end example
We have a constraint with the use of the UDP protocol. Because this
protocol is connectionless, it is impossible, especially for the target, to
detect if the connection is always active. On the other hand, using the TCP/IP
protocols seems to be heavy especially if we plan to implement a dedicated micro
stack for debug in the future. It can be a real problem to let the debugged
process stopped during a long time even if there is no more debugger connected
to the system. To avoid such a problem, the target must periodically test the
connection with the host on another way than the one used to receive the commands.
We must therefore open two communication ways so we need two fixed UDP port
numbers.
@enumerate
@item One port will be used by the debugger to send its commands to the
debugged process and to receive the result of these commands. View from the
remote debugger, this port will be called primary port. For this one, we choose
arbitrarily the port number 2000.
@item The other socket will be used as secondary port by the target to sometimes
test the connection between the host and the target. These tests will occur
in specific situations, when a process will be stopped on a breakpoint, single
step instruction or other means. This secondary port will also be used by the
target to signal any change in the behavior of a debugged process (stopped,
killed, waiting for,...). For the secondary port, we choose the port number
2010.
@end enumerate
These two port numbers are used by the remote debugger to open the
two communication sockets. GDB will use its own mean to choose its port numbers
(probably the Unix portmapper). The figure layer shows the different
layers we need to implement.
@example
XXXXX reference it in the previous paragraph
XXXXX insert layers.eps
XXXXX Caption Communications Layers
@end example
+27
View File
@@ -0,0 +1,27 @@
@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 Conclusion
In this document we have presented how we envisage to add remote debugging facilities
to RTEMS by implementing a remote debugger daemon for GDB. As any debug implemented
in software, it will have limitation but we are confident that most of them
can be removed by adding separate software components dedicated to debug activity.
We must keep in mind that even with this approach, no software will enable the
debug of code with interrupt entirely masked at processor level and that In
Circuit Emulator (ICE) or use of BDM extension on the target board are the ultimate
way to really debug any portion of an RTOS. BDM support in GDB is still weak
but people are working on it and we may get something better in a near future.
@example
XXXXX insert process.eps
XXXXX Caption remote debugger tasks and handlers
@end example
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+79
View File
@@ -0,0 +1,79 @@
@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 Interfacing GDB with RTEMS as a Target
@C XXX figure reference
So, basically, porting GDB to RTEMS environment requires implementing
the functions contained in the target_ops structure. The native debugger implementation
(where the host machine is also the target one) uses direct function calls.
For our needs (remote debugging), these functions must be implemented to support
the encapsulation in UDP/IP layers and communications between different types
of host machines : the best solution is use the SUN Remote Procedure Calls API
(SUN RPC). This SUN RPC module will be explained below (see paragraph @b{Communication with GDB}).
We can note that the functions described in the target_ops structure
are high-level functions. The main reason is that GDB was designed in order
to be able to use monitor firmware as a debug server. In the case of a Unix
OS target, these high-level functions are implemented themselves using a lower
level POSIX API. Because we want to simplify the code running on the target
and decrease its size of this code, we propose to use the POSIX layer API used
for the debug like @b{waitpid}, @b{ptrace}, ... Due to the GDB working
mode and due to our requirements, we can establish here a non-exhaustive list
of some commands required to implement the previously described functions :
@itemize @b
@item set up a connection with a target,
@item close a connection,
@item send a signal to the specified process,
@item get a list of process/thread/connection running,
@item control process under debug,
@item ...
@end itemize
Control means that, with this function, we can read, write the memory
of the debuggee, insert breakpoint to stop the process and resume the process
execution. This command can be implemented by emulating in the RTEMS environment
a Unix function called ``ptrace''. This function allows the control of a child
process. The ``ptrace'' function has some sub-functions which are described
below (some of these actions and standardized, the others are added due to our
needs) :
@itemize @b
@item PTRACE_PEEKTEXT, PTRACE_PEEKDATA : read word at address,
@item PTRACE_POKETEXT, PTRACE_POKEDATA :write word at address,
@item PTRACE_CONT : restart after signal,
@item PTRACE_KILL : send the child a SIGKILL to make it exit,
@item PTRACE_SINGLESTEP : set the trap flag for single stepping,
@item PTRACE_ATTACH : attach to the process specified,
@item PTRACE_DETACH : detach a process that was previously attached.
@end itemize
This list only contains the command that are described in the ptrace
Unix manpage. For some specific needs (debug of one task among several ones,
register read/write,...), it is possible to create some special ptrace commands
as described after :
@itemize @b
@item get current task registers,
@item set current task registers,
@item list of the threads,
@item identifier of the target thread,
@item restart to address,
@item set breakpoint at address,
@item clear breakpoint,
@item get breakpoints,
@item load dynamically a task,
@item ...
@end itemize
This list is not exhaustive and can be increased due to the needs.
All the described functions will not be implemented in a first version, only
the strictly needed. If some commands are added, the modifications must be implemented
both in RTEMS and in GDB.
+39
View File
@@ -0,0 +1,39 @@
@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 Introduction
The TOOLS project aims to provide a complete development environment
for RTEMS OS. This environment must be as close as possible to the Chorus one
(gnu compiler, gnu linker, gnu debugger, ...), because it is currently the OS
which is the most used at CRF and we want to simplify the migration path from
the ChorusOs environment to the RTEMS environment. One important item of this
development environment is the remote debugger which allows the developer to
debug his software on a target machine from a host machine via a communication
link (Ethernet, serial link, ...).
The choice of GDB as debugger has been made with because in CRF, every
developer, which uses the ChorusOs development environment, debugs his software
using the remote debugging functionality of GDB. Providing a remote GDB debug
server running on RTEMS, will enable the developers to use transparently the
same debugger for a different RTOS. Another reason for the choice of GDB is
its constant evolution, and that it can be interfaced with graphic user interfaces
like DDD providing a very powerfull debugging environment.
The subject of this document is to explain how GDB works and the way
to implement a daemon on RTEMS that will be used as a debugger server for a
GDB client. We will call this daemon Rtems GDB Debug Server Daemon (RGDBSD).
We aim to provide this debugger running at least on 2 host systems : Linux 2.x
and Solaris 2.5.1 as they are the two platforms used for developing Chorus applications
today.
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+36
View File
@@ -0,0 +1,36 @@
@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 Document Revision History
@ubaraccent{Current release} :
@itemize @b
@item Current applicable release is 2.0.
@end itemize
@ubaraccent{Existing releases} :
@itemize @b
@item 0.1 : Released the 29/09/98. First draft of this document.
@item 0.2 : Released the 05/10/98. Second draft version.
@item 1.0 : Released the 08/10/98. Version Approved internally.
@item 1.1 : Released the 13/13/98. Version Distributed for comments.
@item 2.0 : Released the 01/11/98. Version including modifications related
to comments we have got from the RTEMS mailing list. It also contains a
more precise description of RGDBSD as we now have a first prototype,
@end itemize
@ubaraccent{Planned releases} :
@itemize @b
@item 2.1 Final specification release intended to include a second round
of comments,
@end itemize
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+167
View File
@@ -0,0 +1,167 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: seq_detach.eps
%%Creator: fig2dev Version 3.2 Patchlevel 1
%%CreationDate: Tue Oct 13 14:00:31 1998
%%For: valette@tri-yann (Eric Valette,,6891,)
%%Orientation: Portrait
%%BoundingBox: 0 0 427 293
%%Pages: 0
%%BeginSetup
%%EndSetup
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
-72.0 362.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
%%EndProlog
$F2psBegin
10 setmiterlimit
n -1000 7022 m -1000 -1000 l 9307 -1000 l 9307 7022 l cp clip
0.06000 0.06000 sc
/Times-Roman ff 300.00 scf sf
1200 1680 m
gs 1 -1 sc (INDEPENDENT) col0 sh gr
/Times-Roman ff 300.00 scf sf
1800 1950 m
gs 1 -1 sc (PART) col0 sh gr
/Times-Roman ff 300.00 scf sf
1575 1425 m
gs 1 -1 sc (TARGET) col0 sh gr
/Times-Roman ff 300.00 scf sf
6450 1680 m
gs 1 -1 sc (DEPENDENT) col0 sh gr
/Times-Roman ff 300.00 scf sf
6675 1350 m
gs 1 -1 sc (TARGET) col0 sh gr
/Times-Roman ff 300.00 scf sf
6900 1950 m
gs 1 -1 sc (PART) col0 sh gr
% Polyline
15.000 slw
n 3600 2400 m 3600 6000 l gs col0 s gr
% Polyline
n 6000 2400 m 6000 6000 l gs col0 s gr
% Polyline
7.500 slw
gs clippath
5861 3927 m 6000 3975 l 5853 3987 l 6011 4007 l 6019 3947 l cp
clip
n 3600 3675 m 6000 3975 l gs col0 s gr gr
% arrowhead
n 5861 3927 m 6000 3975 l 5853 3987 l 5881 3960 l 5861 3927 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
5861 5427 m 6000 5475 l 5853 5487 l 6011 5507 l 6019 5447 l cp
clip
n 3600 5175 m 6000 5475 l gs col0 s gr gr
% arrowhead
n 5861 5427 m 6000 5475 l 5853 5487 l 5881 5460 l 5861 5427 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
3747 4643 m 3600 4631 l 3739 4583 l 3581 4603 l 3589 4663 l cp
clip
n 6000 4331 m 3600 4631 l gs col0 s gr gr
% arrowhead
n 3747 4643 m 3600 4631 l 3739 4583 l 3719 4616 l 3747 4643 l cp gs 0.00 setgray ef gr col0 s
/Times-Bold ff 300.00 scf sf
4800 2700 m
gs 1 -1 sc (Detach a process) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 300.00 scf sf
2550 3750 m
gs 1 -1 sc (Detach a process) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 300.00 scf sf
7200 4050 m
gs 1 -1 sc (Detach the process) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 300.00 scf sf
6150 4425 m
gs 1 -1 sc (Notify detach) col0 sh gr
/Times-Roman ff 300.00 scf sf
6150 4800 m
gs 1 -1 sc (Resume process) col0 sh gr
/Times-Roman ff 300.00 scf sf
3450 5250 m
gs 1 -1 sc (Close connection) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 300.00 scf sf
8100 5625 m
gs 1 -1 sc (Close connection) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 300.00 scf sf
4800 1650 m
gs 1 -1 sc (messages exchange) dup sw pop 2 div neg 0 rm col0 sh gr
$F2psEnd
rs