Index: doc/rgdb_specs/Makefile
===================================================================
--- doc/rgdb_specs/Makefile	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/Makefile	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -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
+
+
Index: doc/rgdb_specs/comm.t
===================================================================
--- doc/rgdb_specs/comm.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/comm.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -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
+
+
+
Index: doc/rgdb_specs/conclusion.t
===================================================================
--- doc/rgdb_specs/conclusion.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/conclusion.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -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
+
Index: doc/rgdb_specs/daemon.t
===================================================================
--- doc/rgdb_specs/daemon.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/daemon.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -0,0 +1,420 @@
+@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 RTEMS Debugger Server Daemon
+
+We will describe in this section how this debugger server will be
+implemented on RTEMS environment. Our initial target is based on Intel Pentium
+and we will use an Ethernet link to communicate between the host and the target.
+
+The RTEMS remote debugger will be composed by several tasks and exception
+handlers :
+
+@itemize @b
+@item an initialization task which opens the sockets and runs the SUN RPC
+server. This task will also connect the interrupt handlers and launch the communication
+task
+@item a communication task which receives the SUN RPC commands, executes
+them and sends the result to the GDB client,
+@item A debuggee event management task which waits for events. We need a different
+task than the command management task in order to be able to still accept commands
+while no event has yet occurred for the debuggee. An example could be a continue
+command from GDB and then hitting to DEL key to see what is currently going
+on on the target side because an expected breakpoint is not caught...
+@item a debug exception handler which manages the hardware breakpoint and
+single step exceptions (INT 1 on Intel x86),
+@item a breakpoint exception handler which manages the software breakpoints
+exceptions (INT 3 on Intel x86),
+@item a default exception handler used to catch every possible errors make on the
+target system,
+@end itemize
+
+@c XXX figure reference
+@c XXX references to other sections
+Figure @b{remote debugger tasks and handlers} represents these
+different tasks and handlers. The synchronization between the different task
+and exception handlers will be described below in the section
+@b{Synchronization Among Tasks and Exception Handlers}.
+Some open issues we have faced for a prototype implementation are described
+in the section @b{Open Issues}. The temporary workaround we chose are described
+in chapter @b{Workarounds for Open Issues in Prototype}.
+
+
+@subsection The INITIALIZATION task
+
+This is the task that must be executed at the boot phase of RTEMS.
+It initializes the debug context. It must :
+
+@itemize @b
+@item open the UDP sockets,
+@item run the SUN RPC server main loop,
+@item create the COMMAND MANAGEMENT task,
+@item connect the DEBUG EXCEPTION handler,
+@item connect the SOFTWARE BREAKPOINT handler,
+@item delete itself.
+@end itemize
+If an error occurs at any step of the execution, the connections established
+before the error will be closed, before the initialization task deletes itself.
+
+
+@subsection The COMMAND_MNGT task
+
+This task is in charge of receiving the SUN RPC messages and executing
+the associated commands. This task must have an important priority because it
+must be executed each time a command message comes from the debugger. It must
+be executed even if one or both exception handlers are executed. But the COMMAND
+MANAGEMENT task must not block the TCP/IP module without which no message can
+be received.
+
+When not executing a command, this task is waiting for a SUN RPC message
+on the primary port. This idle state blocks the task, so the other active tasks
+can run. Once a message comes from Ethernet via the primary port, the COMMAND
+MANAGEMENT task wakes up and receives the message which is a request from GDB.
+This request is sent to the SUN RPC server code which extracts the command and
+its arguments, executes it and, if needed, sends a result to GDB. After having
+performed these actions, the task sleeps, waiting for another message. 
+
+A particular case is the reception of the ATTACH command : in this
+case the COMMAND_MNGT task creates the EVENT_MNGT task described below before
+going to wait on UDP socket again.
+
+
+@subsection The EVENT_MNGT task
+
+This task is in charge of managing events happening on the debuggee such as
+breakpoint, exceptions. This task does a basic simple loop waiting for event
+on a synchronization variable. It is waken up by exception handlers code. It
+then signals GDB that an event occurred and then go sleeping again as further
+requests will be processed by the COMMAND_MNGT task.
+
+
+@subsection The DEBUG EXCEPTION handler
+
+This handler is connected to the DEBUG exception (INT 1 on Intel ix86).
+This exception is entered when :
+
+@itemize @b
+@item executing a single-step instruction,
+@item hardware breakpoint condition is true,
+@end itemize
+These events will be treated by the debugger because they are the
+primary event used when debugging a software for instruction stepping. In both
+cases, the DEBUG EXCEPTION handler code is executed. Please note that the execution
+context of the exception handler is the supervisor stack of the task that generated
+the exception . This implies :
+
+@itemize @b
+@item We may sleep in this context,
+@item We have as many possible execution context for the DEBUG EXCEPTION handler as
+we need to,
+@item When we enter the high level exception handler code, a normalized exception
+context has been pushed on the system stack and a pointer to this context is
+available as the first argument (cf c/src/exec/score/cpu/i386/cpu.c for more
+details),
+@end itemize
+First the exception handler wakeup the EVENT_MNGT task. Then it will
+cause the faulting thread to sleep on a synchronization object. As soon as GDB
+receives the event notifying that the debuggee status has changed, it will start
+sending requests to get the debuggee status (registers set, faulty task id,
+...). These requests are handled by the COMMAND MANAGEMENT task. When this task
+receive a PTRACE_CONT command it will resume the execution of the task that
+caused the exception by doing a V on the synchronization object. 
+
+
+@subsection The BREAKPOINT EXCEPTION handler
+
+This handler is connected to the BREAKPOINT exception (INT3 on Intel
+Ix86). Each time the debugger wants to place a software breakpoint in the debuggee,
+a debuggee opcode is temporarily replaced by an instruction causing BREAKPOINT
+exception (the ``INT 3'' instruction on Intel ix86). When ``INT 3'' is executed,
+the BREAKPOINT handler is executed. Otherwise, the exception processing is the
+same than the one described in previous section.
+
+
+@subsection Synchronization Among Tasks and Exception Handlers
+
+The previous chapters have presented a simplified and static view of the various
+tasks and exceptions handlers. This chapter is more focussed on synchronization
+requirements about the various pieces of code executed when RGDBSD is operating.
+
+
+@subsubsection Implicit Synchronization Using Task Priorities
+
+This chapter is relevant on Uniprocessor System (UP) only. However, it will
+also list the requirements for explicit synchronization on Multi-processor Systems
+(MP). Below are the task priorities sorted by high priority. They are not supposed
+to be equal :
+
+@enumerate
+@item Network Input Task. This is the highest priority task. This can be regarded
+as a software interrupt task for FreeBSD code,
+@item RGDBSD command task. As this task waits on UDP sockets, it shall not prevent
+the previous task from running. As the main debug entry point, it should preempt
+any other task in the system,
+@item RGDBSD event task. This task should preempt any task but the two mentionned
+before to signal a debug event to GDB. The command task shall be able to preempt
+this task for emergency command such as DEL, or REBOOT,
+@item Applications tasks (task we are able to debug),
+@end enumerate
+Using theses priorities eliminates the need for adding more synchronization
+objects in the next section. My belief is that symmetric MP support will require
+more important change in the RTEMS than RGDBSD itself like multiple scheduler
+queues, task to processor binding for non symmetric IO, use a different implementation
+for @emph{task_disable_preemption}, ...
+
+
+@subsubsection Explicit Synchronization
+
+This chapter will describe the synchronization variables that need to be implemented
+in order to sequence debug events in a way that is compatible with what GDB
+code expects. The root of the problem is that GDB code mainly expects that once
+a debug event has occurred on the debuggee, the entire debuggee is frozen and
+no other event will occur before the CONTINUE command is issued. This behavior
+is hard to achieve in our case as once we hit a breakpoint, only the task that
+hits the breakpoint will be asleep on a synchronization object. Other tasks
+may hit other breakpoints while we are waiting commands from GDB generating
+potential unexpected events. There is a solutions if RGDBSD itself use RTEMS
+threads to fix this problem by creating a task that loops forever at a priority
+superior to any debugged task but below RGDBSD task priorities. Unfortunately
+this will not work for the case we use the nano-kernel implementation and we
+think it is better to study synchronization problems now. We also expects that
+multi-thread debug support hardening in GDB will remove some event serializations
+requirements. Here is the list of synchronization variables we plan to use and
+their usage. They are all regular semaphores. They are not binary semaphores
+because the task that does V is not the task that has done the P.
+
+@itemize @b
+@item @emph{WakeUpEventTask} : used by exception handler code to wake up the EVENT_MNGT
+task by doing a V operation on this object. When target code is running normally
+the EVENT_MNGT task sleeps due to a P operation on this semaphore,
+@item @emph{SerializeDebugEvent} : used to serialize events in a way compatible to
+what GDB expects. Before doing a V operation on @emph{WakeUpEventTask,} the
+exception handler does a P on this semaphore to be sure processing of another
+exception is not in progress. Upon reception of a CONTINUE command, the COMMAND_MNGT
+task will issue a V operation so that the exception code can wake up EVENT_MNGT
+task using the mechanism described above,
+@item @emph{RestartFromException} : (in fact one semaphore per task) used by exception
+handling code to put a faulty task to sleep once it has generated an exception
+by doing a P operation on this semaphore. In the case the exception was generated
+due to a breakpoint, GDB command will modify back the BREAKPOINT opcode to the
+original value before doing the CONTINUE command. This command will perform
+a V on this semaphore. In the case it is a real non restartable exception (faulty
+memory reference via invalid pointer for example), GDB will not allow to restart
+the program avoiding any loop. So not special analysis of cause of exception
+is foreseen as far as RGDBSD code is concerned,
+@end itemize
+
+@subsection Open Issues
+
+Here are some problems we have faced while implementing our prototype :
+
+@table @b
+@item [Protected ReadMem/WriteMem (I1)]:
+A GDB user can request to see the content
+of a corrupted pointer. The request PEEK_DATA will be performed by the COMMAND_MNGT
+task. It shall not enter the default exception handler set by RGDBSD or it will
+cause a dead lock in the RGDBSD code. Replacing the default exception vector
+before calling @b{readMem/writeMem} can be temporarily sufficient but :
+
+@itemize @b
+@item It will never work on MP system as it will rely on task priorities to insure
+that other task will not cause exceptions while we have removed the default
+exception handler,
+
+@item This feature should not be usable in RGDBSD only but also by an embedded debugger
+that may run without any task. It is also unavoidable in case of protected memory
+and in this case no priority mechanism can be used,
+
+@item In the case of using RGDBSD code on a dedicated nano kernel, this code will
+be called from interrupt level and we need a way to be sure we can debug other
+interrupts that may also cause exceptions,
+@end itemize
+
+@item [ATTACH Command Implementation (I2)]:
+After the @emph{target rtems symbolic_ip_target_name}
+command, the normal operation is to issue an @emph{attach lid} command where
+@emph{lid} represents a valid execution context. For Unix this is a process
+id, for other multi-tasking system this is the id of a thread. After the attach
+command, GDB expects to be waken up in the same manner as it is for normal events.
+Once waken up it expects to have a complete register context available and also
+that the target task is in a stopped state and that it can restart it using
+the regular CONTINUE command. In RTEMS there is a way to get force a thread
+to become inactive via @emph{rtems_task_suspend} but no way to get the full
+registers set for the thread. A partial context can be retrieved from the task
+@emph{Registers} data structure. On the other hand, relying on @emph{rtems_task_suspend
+will be a problem for the nano-kernel implementation.
+
+@item [Stopping Target System (I3)]:
+Allthough it might not be obvious, most of the
+actions made by a GDB user assume the target is not running. If you modify a
+variable via the @emph{set variable = value} command you expect that the value
+is the one you have put when restarting. If a still running task modifies the
+same value in the mean time, this may be false. On the other hand, stopping
+all the tasks on the target system impose to have a very deep knowledge of the
+system. Using an interrupt driven RGDBSD, may facilitate the implementation
+on the nano-kernel. 
+
+@item [Getting Tasks Contexts (I4)]:
+As previously mentionned there is no way to get
+tasks execution contexts via the RTEMS API. This is needed when debugging for
+example via this classical sequence :
+
+@enumerate
+
+@item @emph{(gdb) target rtems symbolic_ip_target_name}
+
+@item @emph{(gdb) info threads <=} get a thread list on screen
+
+@item @emph{(gdb)} @emph{attach thread_id} <= thread_id is one of the thread in
+the list
+
+@item @emph{(gdb) b a_function_of_interest }
+
+@item @emph{(gdb) continue}
+
+@item @emph{(gdb)} @emph{backtrace} <= print the call stack on the screen once we
+have hit the breakpoint
+
+@item @emph{(gdb) thread target another_thread_li <=} change implicit current thread
+value for gdb commands
+
+@item @emph{(gdb)} @emph{backtrace <=} should print the backtrace for the chosen thread
+@end enumerate
+In our execution model, we have a valid context only for the threads that hits
+the breakpoint as it has been pushed by the exception handler code. The other
+thread is still running and during the various RPC requesting memory access,
+it even changes as the COMMAND_MNGT thread is going to sleep. So the backtrace
+command will fail. We must find a way to make this work as it is very usefull
+when debugging multi-threaded programs,
+
+
+@item [Backtrace Stop convention (I5)]:
+The backtrace command on RTEMS task does not
+gracefully terminate as GDB does not find some backtrace termination condition
+it expects.
+@end table
+
+@subsection Workarounds for Open Issues in Prototype
+
+@table @b
+
+@item [(I1)]:
+Not implemented.We would rather like to work on the formalization of
+per thread flags and global flags that are much more general than any kludge
+we could implement,
+
+@item [(I2)]:
+We have tried two solutions in our prototype. The first one was to use
+the @emph{idle} thread context contained in the @emph{Registers} task control
+block field. The drawback of this solution was that we had to implement specific
+code for the continue operation immediately following the attach command. We
+then decided to create a dedicated task that will only exist during the attach
+phase. This task will call the ``ENTER_RGDB'' exception. This call will execute
+the Exception Handler that saves a valid context and that notifies a change
+to GDB. After the first CONTINUE command from GDB, this task will continue its
+execution and delete itself,
+
+@item [(I3)]:
+As explained above in the synchronization chapter, we choose to serialize
+events in a way that makes GDB think the system is frozen,
+
+@item [(I4)]:
+As a temporary fix, we have called @emph{rtems_task_suspend} and used
+the context switch contex for tasks that are unknown to RGDBSD,
+
+@item [(I5)]:
+Not Implemented yet. If I remember correctly, setting the frame pointer
+to 0 at task initialization for CISC processor solves this problem (ebp = 0x0
+on Intel or a6 = 0x0 on 680x0). This should be done in rtems_task_create function
+in the path to really starts the task for the first time. The processor/system
+specific stop condition can be found as macros in the GDB source tree.
+@end table
+
+@subsection Output of a Debug Session with the Prototype
+
+@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=i386-rtems".
+Attaching remote machine across net...
+Connected to net-test. 
+Now the "run" command will start a remote process.
+Setting up the environment for debugging gdb. 
+(gdb) attach 1 
+Attaching program: /build-rtems/pc386/tests/debug.exe pid 1 
+0x230715 in enterRdbg () 
+(gdb) info threads 
+There are 8 threads: 
+Id.       Name   Detached   Suspended
+134283273 Rini   No         No <= current target thread 
+0x230715 in enterRdbg () 
+134283272 Evnt   No         No 
+_Thread_Dispatch () at /rtems/c/src/exec/score/src/thread.c:315 
+134283271 SPE2   No         No 
+_Thread_Dispatch () at /rtems/c/src/exec/score/src/thread.c:315 
+134283270 SPE1   No         No 
+_Thread_Handler  () at /rtems/c/src/exec/score/src/thread.c:1107 
+134283269 RDBG   No         No 
+0x230715 in enterRdbg () 
+134283268 SCrx   No         No 
+_Thread_Dispatch () at /rtems/c/src/exec/score/src/thread.c:315 
+134283267 SCtx   No         No 
+_Thread_Dispatch () at /rtems/c/src/exec/score/src/thread.c:315 
+134283266 ntwk   No         No 
+_Thread_Dispatch () at /rtems/c/src/exec/score/src/thread.c:315 
+(gdb) b init.c:89 
+Breakpoint 1 at 0x200180: file /rtems/c/src/tests/samples/debug/init.c, line 89.
+(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 /rtems/c/src/tests/samples/debug/init.c:89 
+89          tuto += tuti; 
+(gdb) s 
+90          if (print_enable2) 
+(gdb) c 
+Continuing.
+Breakpoint 1, example2 (argument=4) at /rtems/c/src/tests/samples/debug/init.c:89 
+89          tuto += tuti; 
+(gdb) b init.c:66 
+Breakpoint 2 at 0x200128: file /rtems/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 /rtems/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 /rtems/c/src/tests/samples/debug/init.c:89 
+89          tuto += tuti; 
+(gdb) bt 
+#0  example2 (argument=4) 
+    at /rtems/c/src/tests/samples/debug/init.c:89 
+#1  0xf0009bd0 in ?? () 
+(gdb) thread target 134283270
+thread 134283270 [SPE1], _Thread_Dispatch () at /rtems/c/src/exec/score/src/thread.c:315 
+315         executing = _Thread_Executing; 
+(gdb) c 
+Continuing.
+Breakpoint 2, example1 (argument=4) at /rtems/c/src/tests/samples/debug/init.c:66 
+66          toto += titi; 
+(gdb) detach 
+Detaching program: /build-rtems/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) 
+@end example
+
+
Index: doc/rgdb_specs/gdbinternals.t
===================================================================
--- doc/rgdb_specs/gdbinternals.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/gdbinternals.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -0,0 +1,214 @@
+@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 descrip-
+                                   tion (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 @b
+@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
+
+
+@example
+XXX Figure seg_init.eps
+XXX Debug session initialization
+@end example
+
+@example
+XXX Figure seq_break.eps
+XXX Breakpoint and process execution
+@end example
+
+@example
+XXX Figure seq_detach.eps
+XXX Detach a process and close a connection
+@end example
+
Index: doc/rgdb_specs/interfacing.t
===================================================================
--- doc/rgdb_specs/interfacing.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/interfacing.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -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.
+
+
Index: doc/rgdb_specs/intro.t
===================================================================
--- doc/rgdb_specs/intro.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/intro.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -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.
+
+
Index: doc/rgdb_specs/objectives.t
===================================================================
--- doc/rgdb_specs/objectives.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/objectives.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -0,0 +1,307 @@
+@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 Objectives
+
+@C XXX reference
+This section is intended to clearly define the current objectives of our work.
+First, we will try here to list some ambitious requirements for the debugger
+in section @b{List of Requirements}. These requirements will deliberately be much more
+ambitious than what we will provide directly ourselves in the hope that the
+Internet development model will enable others to implement some features we
+rejected for man-power reasons in the first step. We are committed to do the
+core work and redistribute it but would appreciate any comment and enhancement.
+Then, in section @b{Requirements Analysis} we will analyze each requirement to see
+what technical problem must be solved if we want to fullfill it. After this
+analysis, we will determine in section @b{Requirements Selection} the requirements we
+chose to implement and the ones we will not. We will then clearly identify the
+limits of our solution in section @b{Implied Restrictions}.
+
+
+@subsection List of Requirements
+
+We will identify here possible requirements for the type of debug that may be
+provided :
+
+@table @b
+
+@item [(R1)]:
+We want to use GDB as the front-end debugger,
+
+@item [(R2)]:
+We want to support at least Intel and PowerPC as target processor architecture,
+
+@item [(R3)]:
+We want to use the GDB thread debugging interface,
+
+@item [(R4)]:
+We want to be able to debug a remote target over a serial line,
+
+@item [(R5)]:
+We want to be able to debug a remote target over Ethernet,
+
+@item [(R6)]:
+The set of target code path we will be able to debug using RGDBSD must
+be clearly identified. It will be called Debug Path Set (@emph{DPS}) in the
+remaining of this document,
+
+@item [(R7)]:
+@emph{DPS} must include the RTEMS core executive itself,
+
+@item [(R8)]:
+@emph{DPS} must include the FreeBSD stack, 
+
+@item [(R9)]:
+@emph{DPS} must include anything but the FreeBSD stack and the RTEMS
+core executive,
+
+@item [(R10)]:
+We want to enable several persons to debug different parts of the code
+running on the target,
+
+@item [(R11)]:
+As much as possible the system must be frozen during a debug session
+so that debugging a particular portion of code does not prevent another part
+from functioning,
+@end table
+
+@subsection Requirements Analysis
+
+@table @b
+
+@item [(R1)]:
+Worth recalling it. It mainly imposes few restrictions on the binary
+files type, target processor type as :
+
+@itemize @b
+
+@item the binary format must be understood by GDB (to find debugging information).
+Elf, Coff and A.out are the main formats currently supported. Elf/Dwarf 2.0
+binary support will be our main target as they are the preferred format for
+Intel and PowerPC processors. No change in GDB will be required for other binaries
+except may be a new configuration file changing the binary/debug file format,
+
+@item the processor must be supported for disassemble/step instruction command,
+
+@item the target system must be supported. As far as I know RTEMS is not currently
+@emph{officially} supported anyway,
+@end itemize
+
+@item [(R2)]:
+Our primary targets are Intel and PowerPC. We however do not think implementing
+RGDBSD for other processors will be a heavy task. It will mainly require :
+
+@enumerate
+@item Implementing exception handling for the target processor, 
+
+@item Interfacing the generic part of RGDBSD with the low level exception handling
+and make RGDBSD aware of exception used for debugging (usually illegal instruction
+or dedicated trap, single step),
+
+@item Making GDB aware of the frame layout pushed on exceptions,
+
+@item Implement the code for data transfer for the exception frame,
+
+@item Implement code to copy data cache back to main memory and invalidate instruction
+cache. This is needed in order to be sure opcode modification used to set breakpoint
+that use the data cache will be proagated to the instruction cache,
+@end enumerate
+
+As soon as we will have completed the first core work a document describing
+how to port it to a new processor should be written. So far we will organize
+the source tree with processor dependent directories so that port will be as
+easy as possible. May be a bare processor support should be created,
+
+
+@item [(R3)]:
+GDB already has an interface for manipulating multi-threaded programs.
+This interface is rather weak at the moment but it will certainly be improved
+in the future with the generalization of POSIX thread API on Linux and other
+operating systems. This implies that either GDB or RGDBSD is able to obtain
+the list of threads currently executing. The choice of implementing this in
+GDB or RGDBSD is a tradeof between target code size and simplicity,
+
+@item [(R4)]:
+Regular GDB code contains clients code for debugging over a serial line.
+However only few functions are implemented. We would like to provide a better
+support and to uniformize serial line debugging with debugging over Ethernet
+via the use of SLIP,
+
+@item [(R5)]:
+Regular GDB code contains client code for debugging over Ethernet for
+VxWorks via the SUN RPC library. So there will be at least one starting point
+to implement remote debugging over Ethernet via SUN RPC. The Chorus remote debugging
+code has been disclosed under GPL and also contains code for debugging suing
+SUN RPC,
+
+@item [(R6)]:
+Due to a classical chicken and egg problems, the remote debugging daemon
+cannot be used to debug code it uses to function. Thus depending on the API
+used by RGDBSD, some parts of the target system will not be debuggable via GDB.
+The most important point is documentation because my feeling is that implementing
+RGDBSD on a totally different @emph{dedicated} nano kernel should be possible,
+
+@item [(R7)]:
+RTEMS core executive is a real-time OS which implements priority level
+scheduling, synchronization objects, and interrupt handling. As mentioned in
+previous item, we may not debug theses features if RGDBSD uses them. This requirement
+is thus very strong because it impose that :
+
+@enumerate
+
+@item RGDBSD is totally interrupt driven (no thread API available),
+
+@item But it does not use RTEMS interrupt management,
+
+@item Nor does not use RTEMS exception management,
+
+@item RGDBSD must provide its own UDP/IP stack as the current FreeBSD code rely on
+tasks switching and RTEMS provided synchronization object for input path handling,
+@end enumerate
+
+So our feeling is that the @b{(R7)} more or less requires to write a @emph{dedicated}
+nano kernel with a very small dedicated UDP/IP stack.
+
+
+@item [(R8)]:
+GDB remote debugging over Ethernet code communicates with the remote
+target via the SUN RPC protocol. This requires a UDP/IP protocol and a minimal
+socket like interface. In RTEMS environment, this feature is currently provided
+by the FreeBSD stack. Again, if we use the FreeBSD stack itself for remote communication,
+it will be impossible to debug this stack as a breakpoint in the stack code
+will stop its execution and there would be no more way to communicate with the
+target. A solution consists in implementing a minimal, dedicated UDP/IP stack
+(with at least IP and UDP protocols, a minimal BSD sockets) and a simple SUN
+RPC library, which will be both dedicated to the debug. We can use RTEMS API
+to implement it if @b{(R7)} is not required. As the two stack will need
+to share the same chip, a kind of shared filter must be implemented at the bottom
+of the two stacks so that Ethernet frames can be dynamically directed either
+to the dedicated UDP/IP debug stack or to the regular FreeBSD stack. The fact
+that in the current design, the low level ethernet input routine mainly signal
+a thread should facilitate the design of this filter. The output path is less
+complicated as it is run by a task and thus can sleep on a synchronization object,
+
+@item [(R9)]:
+This requirement represents what we find reasonable as a first target.
+However, we can still present to the final user this kind of debugging via different
+model. RTEMS can be represented as a single threaded system or, because RTEMS
+is a multitasking system, as an ensemble of separate tasks. In the first representation,
+the debugger sees only 1 ``task'' without distinguishing the core executive
+part from the applicative part. This is the simplest way to implement the debugger
+but also implies that there is no way to protect the core executive. Some of
+these tasks are system tasks (tasks form the core executive and from the FreeBSD
+stack), the other ones are tasks implemented by the developer. The developer
+wants to debug his tasks, and sometimes only one of his tasks. We can provide
+a way to debug not the entire system but only the concerned task by testing
+if the current running task is a debugged task (test on the task identifier).
+GDB offers an API to ``detach'' thread so that if a detached thread hits a
+breakpoint it is automatically restarted without user intervention,
+
+@item [(R10)]:
+Several developers can work on a large project, each on a specific
+module. Sometimes only one target is available for everyone. This requirements
+is not really meaningfull until RTEMS supports dynamic code loading,
+
+@item [(R11)]:
+This requirement heavily depends on the @b{(R7)} and @b{(R8)}
+requirements.
+@end table
+
+@subsection Requirements Selection
+
+
+@subsubsection Requirement We Will Take Into Account For the First Implementation
+
+@table @b
+
+@item [(R1)]:
+Obviously.
+
+@item [(R2)]:
+As these are our targets. Of course other will be free to contribute.
+We will however document the works that needs to be done in order to port the
+debug code to other processors,
+
+@item [(R3)]:
+We think it is feasible with only few RTEMS modifications,
+
+@item [(R5)]:
+We think serial line debugging is nowadays too restrictive as most equipment
+are now connected via Ethernet,
+
+@item [(R6)]:
+This is a documentation problem and should be fairly easy to describe
+once we have the RGDBSD code,
+
+@item [(R9)]:
+We will try to provide the multi-thread target system presentation,
+@end table
+
+@subsubsection Requirements We Will Not Implement
+
+@table @b
+
+@item [(R4)]:
+it will not be implemented for the moment. It is just a matter on implementing
+SLIP in the FreeBSD stack and alternative solutions already exist in the meantime,
+
+@item [(R7)]:
+To simplify the first developments, we don't plan to implement a @emph{dedicated}
+nano-kernel to allow the RTEMS kernel to be debugged. It means that, if any
+breakpoint is set in the kernel, unpredictable behaviors can occur. So, developers
+must keep in mind to avoid stopping the kernel. They must also keep in mind,
+in order to not stop the kernel, that the user's tasks must have a lower priority
+than the tasks used for debug. The solution is to use a specific very-high priority
+level for the system tasks used directly or indirectly by RGDBSD. The SYSTEM_TASK
+attribute that already exists should be fine.
+
+@item [(R8)]:
+To avoid increasing the code size and the used memory and because the
+FreeBSD stack doesn't need to be debug any more, we choose not to implement
+a minimal TCP/IP stack but rather to use the FreeBSD one as communication protocol,
+
+@item [(R10)]:
+We will see later when a file system will be available and we can implement
+@b{exec} system call,
+
+@item [(R11)]:
+Without a separate TCP/IP stack it will be hard to freeze the system
+as some interrupts must occur in order to enable the FreeBSD stack to function,
+@end table
+
+@subsection Implied Restrictions
+
+High priority level must be used for these features :
+
+@itemize @b
+
+@item FreeBSD interrupt handling thread,
+
+@item Debugger threads.
+@end itemize
+
+This will allows these tasks not to be stopped when a process is stopped
+in debug mode 
+
+If we don't want to use a ``specific'' priority level, we must affect
+priority to each of these tasks as follow :
+
+@itemize @b
+
+@item FreeBSD stack (high priority)
+
+@item Debugger (less high priority)
+@end itemize
+
+The user must remember the higher priority level he can use for his
+software in order not to block one of the previous threads and to not put breakpoints
+in part of the code executed by RGDBSD.
+
+
Index: doc/rgdb_specs/revision.t
===================================================================
--- doc/rgdb_specs/revision.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/revision.t	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -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
+
Index: doc/rgdb_specs/rgdb-rtems.tex
===================================================================
--- doc/rgdb_specs/rgdb-rtems.tex	(revision bea606aee5cf835a8917d022d596f04ac16104df)
+++ doc/rgdb_specs/rgdb-rtems.tex	(revision bea606aee5cf835a8917d022d596f04ac16104df)
@@ -0,0 +1,1224 @@
+%% This LaTeX-file was created by <valette> Mon Feb 15 17:47:54 1999
+%% LyX 1.0 (C) 1995-1999 by Matthias Ettrich and the LyX Team
+
+%% Do not edit this file unless you know what you are doing.
+\documentclass[10pt,american]{article}
+\usepackage[T1]{fontenc}
+\usepackage{a4wide}
+\pagestyle{plain}
+\usepackage{babel}
+\usepackage[dvips]{graphics}
+
+\makeatletter
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
+\newcommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
+\newenvironment{lyxcode}
+  {\begin{list}{}{
+    \setlength{\rightmargin}{\leftmargin}
+    \raggedright
+    \setlength{\itemsep}{0pt}
+    \setlength{\parsep}{0pt}
+    \ttfamily}%
+   \item[]}
+  {\end{list}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
+\usepackage[dvips]{epsfig}
+
+\makeatother
+
+\begin{document}
+
+\vspace{0.3cm}
+{\par\centering \resizebox*{1\textwidth}{!}{\includegraphics{garde.eps}} \par}
+
+{\par\centering \newpage\par}
+\vspace{0.3cm}
+
+\bigskip{}
+{\par\centering \textbf{\Huge RTEMS Remote Debugger}\Huge \par}
+\bigskip{}
+
+\tableofcontents
+
+\listoffigures \newpage
+
+
+\section{\noindent Introduction}
+
+\noindent 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,~...). \\
+
+
+\noindent 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.\\
+
+
+\noindent 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.
+
+
+\section{\noindent Document Revision History}
+
+\noindent \underbar{Current release} : 
+
+\begin{itemize}
+\item \noindent Current applicable release is 2.0.
+\end{itemize}
+\noindent \underbar{Existing releases} :
+
+\begin{itemize}
+\item \noindent 0.1 : Released the 29/09/98. First draft of this document.
+\item \noindent 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}
+\noindent \underbar{Planned releases} :
+
+\begin{itemize}
+\item \noindent 2.1 Final specification release intended to include a second round
+of comments,
+\end{itemize}
+
+\section{\noindent Objectives}
+
+This section is intended to clearly define the current objectives of our work.
+First, we will try here to list some ambitious requirements for the debugger
+in section \ref{req_ref}. These requirements will deliberately be much more
+ambitious than what we will provide directly ourselves in the hope that the
+Internet development model will enable others to implement some features we
+rejected for man-power reasons in the first step. We are committed to do the
+core work and redistribute it but would appreciate any comment and enhancement.
+Then, in section \ref{req_anal_ref} we will analyze each requirement to see
+what technical problem must be solved if we want to fullfill it. After this
+analysis, we will determine in section \ref{Sel_req_ref} the requirements we
+chose to implement and the ones we will not. We will then clearly identify the
+limits of our solution in section \ref{REstric_ref}.
+
+
+\subsection{\noindent \label{req_ref}List of Requirements}
+
+We will identify here possible requirements for the type of debug that may be
+provided :
+
+\begin{description}
+\item [(R1)]: We want to use GDB as the front-end debugger,
+\item [(R2)]: We want to support at least Intel and PowerPC as target processor architecture,
+\item [(R3)]: We want to use the GDB thread debugging interface,
+\item [(R4)]: We want to be able to debug a remote target over a serial line,
+\item [(R5)]: We want to be able to debug a remote target over Ethernet,
+\item [(R6)]: The set of target code path we will be able to debug using RGDBSD must
+be clearly identified. It will be called Debug Path Set (\emph{DPS}) in the
+remaining of this document,
+\item [(R7)]: \emph{DPS} must include the RTEMS core executive itself,
+\item [(R8)]: \emph{DPS} must include the FreeBSD stack, 
+\item [(R9)]: \emph{DPS} must include anything but the FreeBSD stack and the RTEMS
+core executive,
+\item [(R10)]: We want to enable several persons to debug different parts of the code
+running on the target,
+\item [(R11)]: As much as possible the system must be frozen during a debug session
+so that debugging a particular portion of code does not prevent another part
+from functioning,
+\end{description}
+
+\subsection{\noindent \label{req_anal_ref}Requirements Analysis}
+
+\begin{description}
+\item [(R1)]: Worth recalling it. It mainly imposes few restrictions on the binary
+files type, target processor type as :
+
+\begin{itemize}
+\item the binary format must be understood by GDB (to find debugging information).
+Elf, Coff and A.out are the main formats currently supported. Elf/Dwarf 2.0
+binary support will be our main target as they are the preferred format for
+Intel and PowerPC processors. No change in GDB will be required for other binaries
+except may be a new configuration file changing the binary/debug file format,
+\item the processor must be supported for disassemble/step instruction command,
+\item the target system must be supported. As far as I know RTEMS is not currently
+\emph{officially} supported anyway,
+\end{itemize}
+\item [(R2)]: Our primary targets are Intel and PowerPC. We however do not think implementing
+RGDBSD for other processors will be a heavy task. It will mainly require :
+
+\begin{enumerate}
+\item Implementing exception handling for the target processor, 
+\item Interfacing the generic part of RGDBSD with the low level exception handling
+and make RGDBSD aware of exception used for debugging (usually illegal instruction
+or dedicated trap, single step),
+\item Making GDB aware of the frame layout pushed on exceptions,
+\item Implement the code for data transfer for the exception frame,
+\item Implement code to copy data cache back to main memory and invalidate instruction
+cache. This is needed in order to be sure opcode modification used to set breakpoint
+that use the data cache will be proagated to the instruction cache,
+\end{enumerate}
+As soon as we will have completed the first core work a document describing
+how to port it to a new processor should be written. So far we will organize
+the source tree with processor dependent directories so that port will be as
+easy as possible. May be a bare processor support should be created,
+
+\item [(R3)]: GDB already has an interface for manipulating multi-threaded programs.
+This interface is rather weak at the moment but it will certainly be improved
+in the future with the generalization of POSIX thread API on Linux and other
+operating systems. This implies that either GDB or RGDBSD is able to obtain
+the list of threads currently executing. The choice of implementing this in
+GDB or RGDBSD is a tradeof between target code size and simplicity,
+\item [(R4)]: Regular GDB code contains clients code for debugging over a serial line.
+However only few functions are implemented. We would like to provide a better
+support and to uniformize serial line debugging with debugging over Ethernet
+via the use of SLIP,
+\item [(R5)]: Regular GDB code contains client code for debugging over Ethernet for
+VxWorks via the SUN RPC library. So there will be at least one starting point
+to implement remote debugging over Ethernet via SUN RPC. The Chorus remote debugging
+code has been disclosed under GPL and also contains code for debugging suing
+SUN RPC,
+\item [(R6)]: Due to a classical chicken and egg problems, the remote debugging daemon
+cannot be used to debug code it uses to function. Thus depending on the API
+used by RGDBSD, some parts of the target system will not be debuggable via GDB.
+The most important point is documentation because my feeling is that implementing
+RGDBSD on a totally different \emph{dedicated} nano kernel should be possible,
+\item [(R7)]: RTEMS core executive is a real-time OS which implements priority level
+scheduling, synchronization objects, and interrupt handling. As mentioned in
+previous item, we may not debug theses features if RGDBSD uses them. This requirement
+is thus very strong because it impose that :
+
+\begin{enumerate}
+\item RGDBSD is totally interrupt driven (no thread API available),
+\item But it does not use RTEMS interrupt management,
+\item Nor does not use RTEMS exception management,
+\item RGDBSD must provide its own UDP/IP stack as the current FreeBSD code rely on
+tasks switching and RTEMS provided synchronization object for input path handling,
+\end{enumerate}
+So our feeling is that the \textbf{(R7)} more or less requires to write a \emph{dedicated}
+nano kernel with a very small dedicated UDP/IP stack.
+
+\item [(R8)]: GDB remote debugging over Ethernet code communicates with the remote
+target via the SUN RPC protocol. This requires a UDP/IP protocol and a minimal
+socket like interface. In RTEMS environment, this feature is currently provided
+by the FreeBSD stack. Again, if we use the FreeBSD stack itself for remote communication,
+it will be impossible to debug this stack as a breakpoint in the stack code
+will stop its execution and there would be no more way to communicate with the
+target. A solution consists in implementing a minimal, dedicated UDP/IP stack
+(with at least IP and UDP protocols, a minimal BSD sockets) and a simple SUN
+RPC library, which will be both dedicated to the debug. We can use RTEMS API
+to implement it if \textbf{(R7)} is not required. As the two stack will need
+to share the same chip, a kind of shared filter must be implemented at the bottom
+of the two stacks so that Ethernet frames can be dynamically directed either
+to the dedicated UDP/IP debug stack or to the regular FreeBSD stack. The fact
+that in the current design, the low level ethernet input routine mainly signal
+a thread should facilitate the design of this filter. The output path is less
+complicated as it is run by a task and thus can sleep on a synchronization object,
+\item [(R9)]: This requirement represents what we find reasonable as a first target.
+However, we can still present to the final user this kind of debugging via different
+model. RTEMS can be represented as a single threaded system or, because RTEMS
+is a multitasking system, as an ensemble of separate tasks. In the first representation,
+the debugger sees only 1 ``task'' without distinguishing the core executive
+part from the applicative part. This is the simplest way to implement the debugger
+but also implies that there is no way to protect the core executive. Some of
+these tasks are system tasks (tasks form the core executive and from the FreeBSD
+stack), the other ones are tasks implemented by the developer. The developer
+wants to debug his tasks, and sometimes only one of his tasks. We can provide
+a way to debug not the entire system but only the concerned task by testing
+if the current running task is a debugged task (test on the task identifier).
+GDB offers an API to ``detach'' thread so that if a detached thread hits a
+breakpoint it is automatically restarted without user intervention,
+\item [(R10)]: Several developers can work on a large project, each on a specific
+module. Sometimes only one target is available for everyone. This requirements
+is not really meaningfull until RTEMS supports dynamic code loading,
+\item [(R11)]: This requirement heavily depends on the \textbf{(R7)} and \textbf{(R8)}
+requirements.
+\end{description}
+
+\subsection{\label{Sel_req_ref}Requirements Selection}
+
+
+\subsubsection{Requirement We Will Take Into Account For the First Implementation}
+
+\begin{description}
+\item [(R1)]: Obviously.
+\item [(R2)]: As these are our targets. Of course other will be free to contribute.
+We will however document the works that needs to be done in order to port the
+debug code to other processors,
+\item [(R3)]: We think it is feasible with only few RTEMS modifications,
+\item [(R5)]: We think serial line debugging is nowadays too restrictive as most equipment
+are now connected via Ethernet,
+\item [(R6)]: This is a documentation problem and should be fairly easy to describe
+once we have the RGDBSD code,
+\item [(R9)]: We will try to provide the multi-thread target system presentation,
+\end{description}
+
+\subsubsection{Requirements We Will Not Implement}
+
+\begin{description}
+\item [(R4)]: it will not be implemented for the moment. It is just a matter on implementing
+SLIP in the FreeBSD stack and alternative solutions already exist in the meantime,
+\item [(R7)]: To simplify the first developments, we don't plan to implement a \emph{dedicated}
+nano-kernel to allow the RTEMS kernel to be debugged. It means that, if any
+breakpoint is set in the kernel, unpredictable behaviors can occur. So, developers
+must keep in mind to avoid stopping the kernel. They must also keep in mind,
+in order to not stop the kernel, that the user's tasks must have a lower priority
+than the tasks used for debug. The solution is to use a specific very-high priority
+level for the system tasks used directly or indirectly by RGDBSD. The SYSTEM\_TASK
+attribute that already exists should be fine.
+\item [(R8)]: To avoid increasing the code size and the used memory and because the
+FreeBSD stack doesn't need to be debug any more, we choose not to implement
+a minimal TCP/IP stack but rather to use the FreeBSD one as communication protocol,
+\item [(R10)]: We will see later when a file system will be available and we can implement
+\textbf{exec} system call,
+\item [(R11)]: Without a separate TCP/IP stack it will be hard to freeze the system
+as some interrupts must occur in order to enable the FreeBSD stack to function,
+\end{description}
+
+\subsection{\noindent \label{REstric_ref}Implied Restrictions}
+
+\noindent High priority level must be used for these features :
+
+\begin{itemize}
+\item \noindent FreeBSD interrupt handling thread,
+\item \noindent Debugger threads.
+\end{itemize}
+\noindent This will allows these tasks not to be stopped when a process is stopped
+in debug mode 
+
+\noindent If we don't want to use a ``specific'' priority level, we must affect
+priority to each of these tasks as follow :
+
+\begin{itemize}
+\item \noindent FreeBSD stack (high priority)
+\item \noindent Debugger (less high priority)
+\end{itemize}
+\noindent The user must remember the higher priority level he can use for his
+software in order not to block one of the previous threads and to not put breakpoints
+in part of the code executed by RGDBSD.
+
+
+\section{\noindent A Rapid Tour of GDB Internals}
+
+\noindent 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.\\
+
+
+\noindent 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 : 
+
+\begin{lyxcode}
+{\par\noindent struct~target\_ops\par}
+
+{\par\noindent \{\par}
+
+{\par\noindent ~~char~~~~~~~~~{*}to\_shortname;~~~/{*}~Name~this~target~type~{*}/\par}
+
+{\par\noindent ~~char~~~~~~~~~{*}to\_longname;~~~~/{*}~Name~for~printing~{*}/\par}
+
+{\par\noindent ~~char~~~~~~~~~{*}to\_doc;~~~~~~~~~/{*}~Documentation.~~Does~not~include~trailing\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~newline,~and~starts~with~a~one-line~descrip-\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~tion~(probably~similar~to~to\_longname).~{*}/\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_open)~PARAMS~((char~{*},~int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_close)~PARAMS~((int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_attach)~PARAMS~((char~{*},~int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_detach)~PARAMS~((char~{*},~int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_resume)~PARAMS~((int,~int,~enum~target\_signal));\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_wait)~PARAMS~((int,~struct~target\_waitstatus~{*}));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_fetch\_registers)~PARAMS~((int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_store\_registers)~PARAMS~((int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_prepare\_to\_store)~PARAMS~((void));\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~/{*}~Transfer~LEN~bytes~of~memory~between~GDB~address~MYADDR~and\par}
+
+{\par\noindent ~~~~~target~address~MEMADDR.~~If~WRITE,~transfer~them~to~the~target,~else\par}
+
+{\par\noindent ~~~~~transfer~them~from~the~target.~~TARGET~is~the~target~from~which~we\par}
+
+{\par\noindent ~~~~~get~this~function.\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~~~~Return~value,~N,~is~one~of~the~following:\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~~~~0~means~that~we~can't~handle~this.~~If~errno~has~been~set,~it~is~the\par}
+
+{\par\noindent ~~~~~error~which~prevented~us~from~doing~it~(FIXME:~What~about~bfd\_error?).\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~~~~positive~(call~it~N)~means~that~we~have~transferred~N~bytes\par}
+
+{\par\noindent ~~~~~starting~at~MEMADDR.~~We~might~be~able~to~handle~more~bytes\par}
+
+{\par\noindent ~~~~~beyond~this~length,~but~no~promises.\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~~~~negative~(call~its~absolute~value~N)~means~that~we~cannot\par}
+
+{\par\noindent ~~~~~transfer~right~at~MEMADDR,~but~we~could~transfer~at~least\par}
+
+{\par\noindent ~~~~~something~at~MEMADDR~+~N.~~{*}/\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_xfer\_memory)~PARAMS~((CORE\_ADDR~memaddr,~char~{*}myaddr,\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~int~len,~int~write,\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~struct~target\_ops~{*}~target));\par}
+
+{\par\noindent ~\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_files\_info)~PARAMS~((struct~target\_ops~{*}));\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_insert\_breakpoint)~PARAMS~((CORE\_ADDR,~char~{*}));\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_remove\_breakpoint)~PARAMS~((CORE\_ADDR,~char~{*}));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_terminal\_init)~PARAMS~((void));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_terminal\_inferior)~PARAMS~((void));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_terminal\_ours\_for\_output)~PARAMS~((void));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_terminal\_ours)~PARAMS~((void));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_terminal\_info)~PARAMS~((char~{*},~int));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_kill)~PARAMS~((void));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_load)~PARAMS~((char~{*},~int));\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_lookup\_symbol)~PARAMS~((char~{*},~CORE\_ADDR~{*}));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_create\_inferior)~PARAMS~((char~{*},~char~{*},~char~{*}{*}));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_mourn\_inferior)~PARAMS~((void));\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_can\_run)~PARAMS~((void));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_notice\_signals)~PARAMS~((int~pid));\par}
+
+{\par\noindent ~~int~~~~~~~~~({*}to\_thread\_alive)~PARAMS~((int~pid));\par}
+
+{\par\noindent ~~void~~~~~~~~({*}to\_stop)~PARAMS~((void));\par}
+
+{\par\noindent ~~enum~strata~~~to\_stratum;\par}
+
+{\par\noindent ~~struct~target\_ops\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~~{*}DONT\_USE;~~~~~~/{*}~formerly~to\_next~{*}/\par}
+
+{\par\noindent ~~int~~~~~~~~~~~to\_has\_all\_memory;\par}
+
+{\par\noindent ~~int~~~~~~~~~~~to\_has\_memory;\par}
+
+{\par\noindent ~~int~~~~~~~~~~~to\_has\_stack;\par}
+
+{\par\noindent ~~int~~~~~~~~~~~to\_has\_registers;\par}
+
+{\par\noindent ~~int~~~~~~~~~~~to\_has\_execution;\par}
+
+{\par\noindent ~~struct~section\_table\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~{*}to\_sections;\par}
+
+{\par\noindent ~~struct~section\_table\par}
+
+{\par\noindent ~~~~~~~~~~~~~~~{*}to\_sections\_end;\par}
+
+{\par\noindent ~~int~~~~~~~~~~~to\_magic;\par}
+
+{\par\noindent ~~/{*}~Need~sub-structure~for~target~machine~related~rather~than~comm~related?~{*}/\par}
+
+{\par\noindent \};\par}
+\end{lyxcode}
+\noindent 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 :
+
+\begin{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 \textbf{run}, \textbf{attach}, \textbf{detach}. Several
+figures will now be described showing the main steps of a debug session. \newline
+
+\noindent Figure \ref{init_seq} explains how the debugger connects to the target
+:
+
+\begin{enumerate}
+\item \noindent 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 \noindent The targets checks if it can accept or reject this connection,
+\item \noindent If the connection is accepted, the host ``attaches'' the process,
+\item \noindent the target stops the process, notifies a child's stop to the host
+and waits for command,
+\item \noindent the host can ask information about the debugged process (name, registers,...)
+or perform some action like setting breakpoints, ...
+\end{enumerate}
+\noindent Figure \ref{breakpoint seq} explains how the debugger manages the
+breakpoints and controls the execution of a process :
+
+\begin{enumerate}
+\item \noindent The host asks the debuggee what is the opcode at the concerned address
+in order for GDB to memorize this instruction,
+\item \noindent 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 \noindent then the host waits for events,
+\item \noindent after the change of instruction, the target resumes the execution
+of the debuggee,
+\item \noindent 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 \noindent the host asks the target to re-write the right opcode instead of the
+''DEBUG'' opcode and then can ask information
+\end{enumerate}
+\noindent Figure \ref{breakpoint seq} also shows the case of other ``CONTINUE''
+commands (remember that the ``DEBUG'' opcode has been replaced by the right
+instruction): 
+
+\begin{enumerate}
+\item \noindent Host sends first a ``single step'' command to execute the debugged
+instruction,
+\item \noindent It then waits for ``single step`` exception event,
+\item \noindent 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 \noindent the host asks the target to re-write the ``DEBUG'' opcode (breakpoint
+trap) instead of the debugged one.
+\item \noindent then the host sends a ``CONTINUE'' command in order the target to
+resume the process execution to the next breakpoint.
+\end{enumerate}
+\noindent Figure \ref{detach seq} explains how the debugger disconnects from
+a target :
+
+\begin{enumerate}
+\item \noindent the host sends a detach command to the target.
+\item \noindent the target detaches the concerned process, notifies the detachment
+and resumes the process execution.
+\item \noindent once notified, the host sends a close connection command.
+\item \noindent the target closes the connection.
+\end{enumerate}
+\noindent 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 :
+
+\begin{itemize}
+\item \noindent read/write code,
+\item \noindent read/write data,
+\item \noindent read/write registers,
+\item \noindent manage exceptions,
+\item \noindent send/receive messages to/from the host. 
+\begin{figure}
+{\par\centering \resizebox*{1\textwidth}{0.7\textheight}{\includegraphics{seg_init.eps}} \par}
+
+
+\caption{\label{init_seq}Debug session initialization}
+\end{figure}
+\begin{figure}
+{\par\centering \resizebox*{0.8\textwidth}{1\textheight}{\includegraphics{seq_break.eps}} \par}
+
+
+\caption{\label{breakpoint seq}Breakpoint and process execution}
+\end{figure}
+\begin{figure}
+{\par\centering \resizebox*{0.7\textwidth}{0.3\textheight}{\includegraphics{seq_detach.eps}} \par}
+
+
+\caption{\label{detach seq}Detach a process and close a connection}
+\end{figure}
+
+\end{itemize}
+
+\section{\noindent Interfacing GDB with RTEMS as a Target}
+
+\noindent 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 \ref{RPC}).
+
+\noindent 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 \textbf{waitpid}, \textbf{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~:
+
+\begin{itemize}
+\item \noindent set up a connection with a target,
+\item \noindent close a connection,
+\item \noindent send a signal to the specified process,
+\item \noindent get a list of process/thread/connection running,
+\item \noindent control process under debug,
+\item \noindent ...
+\end{itemize}
+\noindent 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)~:
+
+\begin{itemize}
+\item \noindent PTRACE\_PEEKTEXT, PTRACE\_PEEKDATA : read word at address,
+\item \noindent PTRACE\_POKETEXT, PTRACE\_POKEDATA :write word at address,
+\item \noindent PTRACE\_CONT : restart after signal,
+\item \noindent PTRACE\_KILL : send the child a SIGKILL to make it exit,
+\item \noindent PTRACE\_SINGLESTEP : set the trap flag for single stepping,
+\item \noindent PTRACE\_ATTACH : attach to the process specified,
+\item \noindent PTRACE\_DETACH : detach a process that was previously attached.\newpage
+\end{itemize}
+\noindent 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~:
+
+\begin{itemize}
+\item \noindent get current task registers,
+\item \noindent set current task registers,
+\item \noindent list of the threads,
+\item \noindent identifier of the target thread,
+\item \noindent restart to address,
+\item \noindent set breakpoint at address,
+\item \noindent clear breakpoint,
+\item \noindent get breakpoints,
+\item \noindent load dynamically a task,
+\item \noindent ...
+\end{itemize}
+\noindent 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.
+
+
+\section{\noindent \label{RPC}Communication with GDB}
+
+\noindent 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.\\
+
+
+\noindent 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 :
+
+\begin{lyxcode}
+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{lyxcode}
+\noindent 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. 
+
+\begin{enumerate}
+\item \noindent 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 \noindent 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}
+\noindent 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 \ref{layer} shows the different
+layers we need to implement. 
+
+\begin{figure}
+{\par\centering \includegraphics{layers.eps} \par}
+
+
+\caption{\label{layer}Communication layers}
+\end{figure}
+
+
+
+\section{\noindent RTEMS Debugger Server Daemon}
+
+\noindent We will describe in this section how this debugger server will be
+implemented on RTEMS environment. Our initial target is based on Intel Pentium
+and we will use an Ethernet link to communicate between the host and the target.
+
+\noindent The RTEMS remote debugger will be composed by several tasks and exception
+handlers :
+
+\begin{itemize}
+\item \noindent an initialization task which opens the sockets and runs the SUN RPC
+server. This task will also connect the interrupt handlers and launch the communication
+task
+\item \noindent a communication task which receives the SUN RPC commands, executes
+them and sends the result to the GDB client,
+\item A debuggee event management task which waits for events. We need a different
+task than the command management task in order to be able to still accept commands
+while no event has yet occurred for the debuggee. An example could be a continue
+command from GDB and then hitting to DEL key to see what is currently going
+on on the target side because an expected breakpoint is not caught...
+\item \noindent a debug exception handler which manages the hardware breakpoint and
+single step exceptions (INT 1 on Intel x86),
+\item \noindent a breakpoint exception handler which manages the software breakpoints
+exceptions (INT 3 on Intel x86),
+\item a default exception handler used to catch every possible errors make on the
+target system,
+\end{itemize}
+\noindent Figure \ref{remote debugger tasks and handlers} represents these
+different tasks and handlers. The synchronization between the different task
+and exception handlers will be described below in chapter \ref{Synchro_ref}.
+Some open issues we have faced for a prototype implementation are described
+in chapter \ref{Open_issue_ref}. The temporary workaround we chose are described
+in chapter \ref{Workaround_ref}.
+
+
+\subsection{\noindent The INITIALIZATION task}
+
+\noindent This is the task that must be executed at the boot phase of RTEMS.
+It initializes the debug context. It must :
+
+\begin{itemize}
+\item \noindent open the UDP sockets,
+\item \noindent run the SUN RPC server main loop,
+\item \noindent create the COMMAND MANAGEMENT task,
+\item \noindent connect the DEBUG EXCEPTION handler,
+\item \noindent connect the SOFTWARE BREAKPOINT handler,
+\item \noindent delete itself.
+\end{itemize}
+\noindent If an error occurs at any step of the execution, the connections established
+before the error will be closed, before the initialization task deletes itself.
+
+
+\subsection{\noindent The COMMAND\_MNGT task}
+
+\noindent This task is in charge of receiving the SUN RPC messages and executing
+the associated commands. This task must have an important priority because it
+must be executed each time a command message comes from the debugger. It must
+be executed even if one or both exception handlers are executed. But the COMMAND
+MANAGEMENT task must not block the TCP/IP module without which no message can
+be received.
+
+\noindent When not executing a command, this task is waiting for a SUN RPC message
+on the primary port. This idle state blocks the task, so the other active tasks
+can run. Once a message comes from Ethernet via the primary port, the COMMAND
+MANAGEMENT task wakes up and receives the message which is a request from GDB.
+This request is sent to the SUN RPC server code which extracts the command and
+its arguments, executes it and, if needed, sends a result to GDB. After having
+performed these actions, the task sleeps, waiting for another message. 
+
+\noindent A particular case is the reception of the ATTACH command : in this
+case the COMMAND\_MNGT task creates the EVENT\_MNGT task described below before
+going to wait on UDP socket again.
+
+
+\subsection{The EVENT\_MNGT task}
+
+This task is in charge of managing events happening on the debuggee such as
+breakpoint, exceptions. This task does a basic simple loop waiting for event
+on a synchronization variable. It is waken up by exception handlers code. It
+then signals GDB that an event occurred and then go sleeping again as further
+requests will be processed by the COMMAND\_MNGT task.
+
+
+\subsection{\noindent The DEBUG EXCEPTION handler}
+
+\noindent This handler is connected to the DEBUG exception (INT 1 on Intel ix86).
+This exception is entered when :
+
+\begin{itemize}
+\item \noindent executing a single-step instruction,
+\item \noindent hardware breakpoint condition is true,
+\end{itemize}
+\noindent These events will be treated by the debugger because they are the
+primary event used when debugging a software for instruction stepping. In both
+cases, the DEBUG EXCEPTION handler code is executed. Please note that the execution
+context of the exception handler is the supervisor stack of the task that generated
+the exception . This implies :
+
+\begin{itemize}
+\item \noindent We may sleep in this context,
+\item We have as many possible execution context for the DEBUG EXCEPTION handler as
+we need to,
+\item When we enter the high level exception handler code, a normalized exception
+context has been pushed on the system stack and a pointer to this context is
+available as the first argument (cf c/src/exec/score/cpu/i386/cpu.c for more
+details),
+\end{itemize}
+\noindent First the exception handler wakeup the EVENT\_MNGT task. Then it will
+cause the faulting thread to sleep on a synchronization object. As soon as GDB
+receives the event notifying that the debuggee status has changed, it will start
+sending requests to get the debuggee status (registers set, faulty task id,
+...). These requests are handled by the COMMAND MANAGEMENT task. When this task
+receive a PTRACE\_CONT command it will resume the execution of the task that
+caused the exception by doing a V on the synchronization object. 
+
+
+\subsection{\noindent The BREAKPOINT EXCEPTION handler}
+
+\noindent This handler is connected to the BREAKPOINT exception (INT3 on Intel
+Ix86). Each time the debugger wants to place a software breakpoint in the debuggee,
+a debuggee opcode is temporarily replaced by an instruction causing BREAKPOINT
+exception (the ``INT 3'' instruction on Intel ix86). When ``INT 3'' is executed,
+the BREAKPOINT handler is executed. Otherwise, the exception processing is the
+same than the one described in previous section.
+
+
+\subsection{\label{Synchro_ref}Synchronization Among Tasks and Exception Handlers}
+
+The previous chapters have presented a simplified and static view of the various
+tasks and exceptions handlers. This chapter is more focussed on synchronization
+requirements about the various pieces of code executed when RGDBSD is operating.
+
+
+\subsubsection{Implicit Synchronization Using Task Priorities}
+
+This chapter is relevant on Uniprocessor System (UP) only. However, it will
+also list the requirements for explicit synchronization on Multi-processor Systems
+(MP). Below are the task priorities sorted by high priority. They are not supposed
+to be equal :
+
+\begin{enumerate}
+\item Network Input Task. This is the highest priority task. This can be regarded
+as a software interrupt task for FreeBSD code,
+\item RGDBSD command task. As this task waits on UDP sockets, it shall not prevent
+the previous task from running. As the main debug entry point, it should preempt
+any other task in the system,
+\item RGDBSD event task. This task should preempt any task but the two mentionned
+before to signal a debug event to GDB. The command task shall be able to preempt
+this task for emergency command such as DEL, or REBOOT,
+\item Applications tasks (task we are able to debug),
+\end{enumerate}
+Using theses priorities eliminates the need for adding more synchronization
+objects in the next section. My belief is that symmetric MP support will require
+more important change in the RTEMS than RGDBSD itself like multiple scheduler
+queues, task to processor binding for non symmetric IO, use a different implementation
+for \emph{task\_disable\_preemption}, ...
+
+
+\subsubsection{Explicit Synchronization}
+
+This chapter will describe the synchronization variables that need to be implemented
+in order to sequence debug events in a way that is compatible with what GDB
+code expects. The root of the problem is that GDB code mainly expects that once
+a debug event has occurred on the debuggee, the entire debuggee is frozen and
+no other event will occur before the CONTINUE command is issued. This behavior
+is hard to achieve in our case as once we hit a breakpoint, only the task that
+hits the breakpoint will be asleep on a synchronization object. Other tasks
+may hit other breakpoints while we are waiting commands from GDB generating
+potential unexpected events. There is a solutions if RGDBSD itself use RTEMS
+threads to fix this problem by creating a task that loops forever at a priority
+superior to any debugged task but below RGDBSD task priorities. Unfortunately
+this will not work for the case we use the nano-kernel implementation and we
+think it is better to study synchronization problems now. We also expects that
+multi-thread debug support hardening in GDB will remove some event serializations
+requirements. Here is the list of synchronization variables we plan to use and
+their usage. They are all regular semaphores. They are not binary semaphores
+because the task that does V is not the task that has done the P.
+
+\begin{itemize}
+\item \emph{WakeUpEventTask} : used by exception handler code to wake up the EVENT\_MNGT
+task by doing a V operation on this object. When target code is running normally
+the EVENT\_MNGT task sleeps due to a P operation on this semaphore,
+\item \emph{SerializeDebugEvent} : used to serialize events in a way compatible to
+what GDB expects. Before doing a V operation on \emph{WakeUpEventTask,} the
+exception handler does a P on this semaphore to be sure processing of another
+exception is not in progress. Upon reception of a CONTINUE command, the COMMAND\_MNGT
+task will issue a V operation so that the exception code can wake up EVENT\_MNGT
+task using the mechanism described above,
+\item \emph{RestartFromException} : (in fact one semaphore per task) used by exception
+handling code to put a faulty task to sleep once it has generated an exception
+by doing a P operation on this semaphore. In the case the exception was generated
+due to a breakpoint, GDB command will modify back the BREAKPOINT opcode to the
+original value before doing the CONTINUE command. This command will perform
+a V on this semaphore. In the case it is a real non restartable exception (faulty
+memory reference via invalid pointer for example), GDB will not allow to restart
+the program avoiding any loop. So not special analysis of cause of exception
+is foreseen as far as RGDBSD code is concerned,
+\end{itemize}
+
+\subsection{\label{Open_issue_ref}Open Issues}
+
+Here are some problems we have faced while implementing our prototype :
+
+\begin{description}
+\item [Protected~ReadMem/WriteMem~(I1)]: A GDB user can request to see the content
+of a corrupted pointer. The request PEEK\_DATA will be performed by the COMMAND\_MNGT
+task. It shall not enter the default exception handler set by RGDBSD or it will
+cause a dead lock in the RGDBSD code. Replacing the default exception vector
+before calling \textbf{readMem/writeMem} can be temporarily sufficient but :
+
+\begin{itemize}
+\item It will never work on MP system as it will rely on task priorities to insure
+that other task will not cause exceptions while we have removed the default
+exception handler,
+\item This feature should not be usable in RGDBSD only but also by an embedded debugger
+that may run without any task. It is also unavoidable in case of protected memory
+and in this case no priority mechanism can be used,
+\item In the case of using RGDBSD code on a dedicated nano kernel, this code will
+be called from interrupt level and we need a way to be sure we can debug other
+interrupts that may also cause exceptions,
+\end{itemize}
+\item [ATTACH~Command~Implementation~(I2)]: After the \emph{target rtems symbolic\_ip\_target\_name}
+command, the normal operation is to issue an \emph{attach lid} command where
+\emph{lid} represents a valid execution context. For Unix this is a process
+id, for other multi-tasking system this is the id of a thread. After the attach
+command, GDB expects to be waken up in the same manner as it is for normal events.
+Once waken up it expects to have a complete register context available and also
+that the target task is in a stopped state and that it can restart it using
+the regular CONTINUE command. In RTEMS there is a way to get force a thread
+to become inactive via \emph{rtems\_task\_suspend} but no way to get the full
+registers set for the thread. A partial context can be retrieved from the task
+\emph{Registers} data structure. On the other hand, relying on \emph{rtems\_task\_suspend}
+will be a problem for the nano-kernel implementation.
+\item [Stopping~Target~System~(I3)]: Allthough it might not be obvious, most of the
+actions made by a GDB user assume the target is not running. If you modify a
+variable via the \emph{set variable = value} command you expect that the value
+is the one you have put when restarting. If a still running task modifies the
+same value in the mean time, this may be false. On the other hand, stopping
+all the tasks on the target system impose to have a very deep knowledge of the
+system. Using an interrupt driven RGDBSD, may facilitate the implementation
+on the nano-kernel. 
+\item [Getting~Tasks~Contexts~(I4)]: As previously mentionned there is no way to get
+tasks execution contexts via the RTEMS API. This is needed when debugging for
+example via this classical sequence :
+
+\begin{enumerate}
+\item \emph{(gdb) target rtems symbolic\_ip\_target\_name}
+\item \emph{(gdb) info threads <=} get a thread list on screen
+\item \emph{(gdb)} \emph{attach thread\_id} <= thread\_id is one of the thread in
+the list
+\item \emph{(gdb) b a\_function\_of\_interest }
+\item \emph{(gdb) continue}
+\item \emph{(gdb)} \emph{backtrace} <= print the call stack on the screen once we
+have hit the breakpoint
+\item \emph{(gdb) thread target another\_thread\_li <=} change implicit current thread
+value for gdb commands
+\item \emph{(gdb)} \emph{backtrace <=} should print the backtrace for the chosen thread
+\end{enumerate}
+In our execution model, we have a valid context only for the threads that hits
+the breakpoint as it has been pushed by the exception handler code. The other
+thread is still running and during the various RPC requesting memory access,
+it even changes as the COMMAND\_MNGT thread is going to sleep. So the backtrace
+command will fail. We must find a way to make this work as it is very usefull
+when debugging multi-threaded programs,
+
+\item [Backtrace~Stop~convention~(I5)]: The backtrace command on RTEMS task does not
+gracefully terminate as GDB does not find some backtrace termination condition
+it expects.
+\end{description}
+
+\subsection{\label{Workaround_ref}Workarounds for Open Issues in Prototype}
+
+\begin{description}
+\item [(I1)]: Not implemented.We would rather like to work on the formalization of
+per thread flags and global flags that are much more general than any kludge
+we could implement,
+\item [(I2)]: We have tried two solutions in our prototype. The first one was to use
+the \emph{idle} thread context contained in the \emph{Registers} task control
+block field. The drawback of this solution was that we had to implement specific
+code for the continue operation immediately following the attach command. We
+then decided to create a dedicated task that will only exist during the attach
+phase. This task will call the ``ENTER\_RGDB'' exception. This call will execute
+the Exception Handler that saves a valid context and that notifies a change
+to GDB. After the first CONTINUE command from GDB, this task will continue its
+execution and delete itself,
+\item [(I3)]: As explained above in the synchronization chapter, we choose to serialize
+events in a way that makes GDB think the system is frozen,
+\item [(I4)]: As a temporary fix, we have called \emph{rtems\_task\_suspend} and used
+the context switch contex for tasks that are unknown to RGDBSD,
+\item [(I5)]: Not Implemented yet. If I remember correctly, setting the frame pointer
+to 0 at task initialization for CISC processor solves this problem (ebp = 0x0
+on Intel or a6 = 0x0 on 680x0). This should be done in rtems\_task\_create function
+in the path to really starts the task for the first time. The processor/system
+specific stop condition can be found as macros in the GDB source tree.
+\end{description}
+
+\subsection{Output of a Debug Session with the Prototype}
+
+\begin{lyxcode}
+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~\char`\"{}show~copying\char`\"{}~to~see~the~
+
+conditions.~There~is~absolutely~no~warranty~for~GDB.~Type~\char`\"{}show~warranty\char`\"{}~for~
+
+details.~This~GDB~was~configured~as~\char`\"{}-{}-host=i686-pc-linux-gnu~-{}-target=i386rtems\char`\"{}.
+
+Attaching~remote~machine~across~net...
+
+Connected~to~net-test.~
+
+\ 
+
+Now~the~\char`\"{}run\char`\"{}~command~will~start~a~remote~process.
+
+\ 
+
+Setting~up~the~environment~for~debugging~gdb.~
+
+(gdb)~attach~1~
+
+Attaching~program:~/build-rtems/pc386/tests/debug.exe~pid~1~
+
+0x230715~in~enterRdbg~()~
+
+(gdb)~info~threads~
+
+There~are~8~threads:~
+
+Id.~~~~~~~Name~~~Detached~~~Suspended
+
+\ 
+
+134283273~Rini~~~No~~~~~~~~~No~<=~current~target~thread~
+
+0x230715~in~enterRdbg~()~
+
+134283272~Evnt~~~No~~~~~~~~~No~
+
+\_Thread\_Dispatch~()~at~/rtems/c/src/exec/score/src/thread.c:315~
+
+134283271~SPE2~~~No~~~~~~~~~No~
+
+\_Thread\_Dispatch~()~at~/rtems/c/src/exec/score/src/thread.c:315~
+
+134283270~SPE1~~~No~~~~~~~~~No~
+
+\_Thread\_Handler~~()~at~/rtems/c/src/exec/score/src/thread.c:1107~
+
+134283269~RDBG~~~No~~~~~~~~~No~
+
+0x230715~in~enterRdbg~()~
+
+134283268~SCrx~~~No~~~~~~~~~No~
+
+\_Thread\_Dispatch~()~at~/rtems/c/src/exec/score/src/thread.c:315~
+
+134283267~SCtx~~~No~~~~~~~~~No~
+
+\_Thread\_Dispatch~()~at~/rtems/c/src/exec/score/src/thread.c:315~
+
+134283266~ntwk~~~No~~~~~~~~~No~
+
+\_Thread\_Dispatch~()~at~/rtems/c/src/exec/score/src/thread.c:315~
+
+(gdb)~b~init.c:89~
+
+Breakpoint~1~at~0x200180:~file~/rtems/c/src/tests/samples/debug/init.c,~line~89.~
+
+(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~/rtems/c/src/tests/samples/debug/init.c:89~
+
+89~~~~~~~~~~tuto~+=~tuti;~
+
+(gdb)~s~
+
+90~~~~~~~~~~if~(print\_enable2)~
+
+(gdb)~c~
+
+Continuing.
+
+\ 
+
+Breakpoint~1,~example2~(argument=4)~at~/rtems/c/src/tests/samples/debug/init.c:89~
+
+89~~~~~~~~~~tuto~+=~tuti;~
+
+(gdb)~b~init.c:66~
+
+Breakpoint~2~at~0x200128:~file~/rtems/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~/rtems/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~/rtems/c/src/tests/samples/debug/init.c:89~
+
+89~~~~~~~~~~tuto~+=~tuti;~
+
+(gdb)~bt~
+
+\#0~~example2~(argument=4)~
+
+~~~~at~/rtems/c/src/tests/samples/debug/init.c:89~
+
+\#1~~0xf0009bd0~in~??~()~
+
+(gdb)~thread~target~134283270
+
+\ 
+
+thread~134283270~{[}SPE1{]},~\_Thread\_Dispatch~()~at~/rtems/c/src/exec/score/src/thread.c:315~
+
+315~~~~~~~~~executing~=~\_Thread\_Executing;~
+
+(gdb)~c~
+
+Continuing.
+
+\ 
+
+Breakpoint~2,~example1~(argument=4)~at~/rtems/c/src/tests/samples/debug/init.c:66~
+
+66~~~~~~~~~~toto~+=~titi;~
+
+(gdb)~detach~
+
+Detaching~program:~/build-rtems/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)~
+\end{lyxcode}
+
+\section{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.
+
+\begin{figure}
+{\par\centering \resizebox*{!}{0.98\textheight}{\rotatebox{90}{\includegraphics{process.eps}}} \par}
+
+
+\caption{\label{remote debugger tasks and handlers}remote debugger tasks and handlers}
+\end{figure}
+
+
+\end{document}
