* remote.texi: Add documentation for target Sparclet.

gdb/doc/ChangeLog

@@ -1,3 +1,7 @@
+Fri Jun 28 22:17:10 1996  Dawn Perchik  <dawn@cygnus.com>
+
+	* remote.texi: Add documentation for target Sparclet.
+
 Mon Jun 24 18:12:22 1996  Jason Molenda  (crash@godzilla.cygnus.co.jp)
 
 	* Makefile.in (srcdir, VPATH, prefix, infodir, INSTALL, 

gdb/doc/remote.texi

@@ -980,44 +980,44 @@ sequences gets you back to the @value{GDBN} command prompt:
 @end ifset
 
 @ifset VXWORKS
-@node VxWorks Remote
+@node Sparclet Remote
-@subsection @value{GDBN} and VxWorks
+@subsection @value{GDBN} and Sparclet
-@cindex VxWorks
+@cindex Sparclet
 
 @value{GDBN} enables developers to spawn and debug tasks running on networked
-VxWorks targets from a Unix host.  Already-running tasks spawned from
+Sparclet targets from a Unix host.  Already-running tasks spawned from
-the VxWorks shell can also be debugged.  @value{GDBN} uses code that runs on
+the Sparclet shell can also be debugged.  @value{GDBN} uses code that runs on
-both the Unix host and on the VxWorks target.  The program
+both the Unix host and on the Sparclet target.  The program
 @code{gdb} is installed and executed on the Unix host.  (It may be
 installed with the name @code{vxgdb}, to distinguish it from a
 @value{GDBN} for debugging programs on the host itself.)
 
 @table @code
-@item VxWorks-timeout @var{args}
+@item Sparclet-timeout @var{args}
 @kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.  
+All Sparclet-based targets now support the option @code{vxworks-timeout}.  
 This option is set by the user, and  @var{args} represents the number of 
 seconds @value{GDBN} waits for responses to rpc's.  You might use this if 
-your VxWorks target is a slow software simulator or is on the far side 
+your Sparclet target is a slow software simulator or is on the far side 
 of a thin network line.
 @end table
 
-The following information on connecting to VxWorks was current when
+The following information on connecting to Sparclet was current when
-this manual was produced; newer releases of VxWorks may use revised
+this manual was produced; newer releases of Sparclet may use revised
 procedures.
 
 @kindex INCLUDE_RDB
-To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
+To use @value{GDBN} with Sparclet, you must rebuild your Sparclet kernel
-to include the remote debugging interface routines in the VxWorks
+to include the remote debugging interface routines in the Sparclet
 library @file{rdb.a}.  To do this, define @code{INCLUDE_RDB} in the
-VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
+Sparclet configuration file @file{configAll.h} and rebuild your Sparclet
 kernel.  The resulting kernel contains @file{rdb.a}, and spawns the
-source debugging task @code{tRdbTask} when VxWorks is booted.  For more
+source debugging task @code{tRdbTask} when Sparclet is booted.  For more
-information on configuring and remaking VxWorks, see the manufacturer's
+information on configuring and remaking Sparclet, see the manufacturer's
 manual.
-@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
+@c Sparclet, see the @cite{Sparclet Programmer's Guide}.
 
-Once you have included @file{rdb.a} in your VxWorks system image and set
+Once you have included @file{rdb.a} in your Sparclet system image and set
 your Unix execution search path to find @value{GDBN}, you are ready to
 run @value{GDBN}.  From your Unix host, run @code{gdb} (or @code{vxgdb},
 depending on your installation).
@@ -1029,15 +1029,15 @@ depending on your installation).
 @end example
 
 @menu
-* VxWorks Connection::          Connecting to VxWorks
+* Sparclet Connection::          Connecting to Sparclet
-* VxWorks Download::            VxWorks download
+* Sparclet Download::            Sparclet download
-* VxWorks Attach::              Running tasks
+* Sparclet Attach::              Running tasks
 @end menu
 
-@node VxWorks Connection
+@node Sparclet Connection
-@subsubsection Connecting to VxWorks
+@subsubsection Connecting to Sparclet
 
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target on the
 network.  To connect to a target whose host name is ``@code{tt}'', type:
 
 @example
@@ -1054,7 +1054,7 @@ Connected to tt.
 
 @need 1000
 @value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted.  @value{GDBN} locates
+loaded into the Sparclet target since it was last booted.  @value{GDBN} locates
 these files by searching the directories listed in the command search
 path (@pxref{Environment, ,Your program's environment}); if it fails
 to find an object file, it displays a message such as:
@@ -1067,15 +1067,15 @@ When this happens, add the appropriate directory to the search path with
 the @value{GDBN} command @code{path}, and execute the @code{target}
 command again.
 
-@node VxWorks Download
+@node Sparclet Download
-@subsubsection VxWorks download
+@subsubsection Sparclet download
 
-@cindex download to VxWorks
+@cindex download to Sparclet
-If you have connected to the VxWorks target and you want to debug an
+If you have connected to the Sparclet target and you want to debug an
 object that has not yet been loaded, you can use the @value{GDBN}
-@code{load} command to download a file from Unix to VxWorks
+@code{load} command to download a file from Unix to Sparclet
 incrementally.  The object file given as an argument to the @code{load}
-command is actually opened twice: first by the VxWorks target in order
+command is actually opened twice: first by the Sparclet target in order
 to download the code, then by @value{GDBN} in order to read the symbol
 table.  This can lead to problems if the current working directories on
 the two systems differ.  If both systems have NFS mounted the same
@@ -1083,9 +1083,9 @@ filesystems, you can avoid these problems by using absolute paths.
 Otherwise, it is simplest to set the working directory on both systems
 to the directory in which the object file resides, and then to reference
 the file by its name, without any path.  For instance, a program
-@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
+@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in Sparclet
 and in @file{@var{hostpath}/vw/demo/rdb} on the host.  To load this
-program, type this on VxWorks:
+program, type this on Sparclet:
 
 @example
 -> cd "@var{vxpath}/vw/demo/rdb"
@@ -1112,10 +1112,10 @@ history.  (This is necessary in order to preserve the integrity of
 debugger data structures that reference the target system's symbol
 table.)
 
-@node VxWorks Attach
+@node Sparclet Attach
 @subsubsection Running tasks
 
-@cindex running VxWorks tasks
+@cindex running Sparclet tasks
 You can also attach to an existing task using the @code{attach} command as
 follows:
 
@@ -1124,11 +1124,163 @@ follows:
 @end example
 
 @noindent
-where @var{task} is the VxWorks hexadecimal task ID.  The task can be running
+where @var{task} is the Sparclet hexadecimal task ID.  The task can be running
 or suspended when you attach to it.  Running tasks are suspended at
 the time of attachment.
 @end ifset
 
+@ifset SPARCLET
+@node Sparclet Remote
+@subsection @value{GDBN} and Sparclet
+@cindex Sparclet
+
+@value{GDBN} enables developers to debug tasks running on 
+Sparclet targets from a Unix host.  
+@value{GDBN} uses code that runs on
+both the Unix host and on the Sparclet target.  The program
+@code{gdb} is installed and executed on the Unix host.  
+
+@table @code
+@item timeout @var{args}
+@kindex remotetimeout
+@value{GDBN} now supports the option @code{remotetimeout}.  
+This option is set by the user, and  @var{args} represents the number of 
+seconds @value{GDBN} waits for responses.  
+@end table
+
+@kindex Compiling
+When compiling for debugging, include the options "-g" to get debug 
+information and "-Ttext" to relocate the program to where you wish to
+load it on the target.  You may also want to add the options "-n" or 
+"-N" in order to reduce the size of the sections.
+
+@example
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end example
+
+You can use objdump to verify that the addresses are what you intended.
+
+@example
+sparclet-aout-objdump --headers --syms prog
+@end example
+
+@kindex Running
+Once you have set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}.  From your Unix host, run @code{gdb} 
+(or @code{sparclet-aout-gdb}, depending on your installation).
+
+@value{GDBN} comes up showing the prompt:
+
+@example
+(gdbslet)
+@end example
+
+@menu
+* Sparclet File::                Setting the file to debug
+* Sparclet Connection::          Connecting to Sparclet
+* Sparclet Download::            Sparclet download
+* Sparclet Execution::           Running and debugging 
+@end menu
+
+@node Sparclet File
+@subsubsection Setting file to debug
+
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
+
+@example
+(gdbslet) file prog
+@end example
+
+@need 1000
+@value{GDBN} then attempts to read the symbol table of @file{prog}.
+@value{GDBN} locates
+the file by searching the directories listed in the command search
+path.
+If the file was compiled with debug information (option "-g"), source
+files will be searched as well.
+@value{GDBN} locates
+the source files by searching the directories listed in the directory search
+path (@pxref{Environment, ,Your program's environment}).
+If it fails
+to find a file, it displays a message such as:
+
+@example
+prog: No such file or directory.
+@end example
+
+When this happens, add the appropriate directories to the search paths with
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the 
+@code{target} command again.
+
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
+
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
+
+@example
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3 
+@end example
+
+@need 750
+@value{GDBN} displays messages like these:
+
+@smallexample
+Connected to ttya.
+@end smallexample
+
+@node Sparclet Download
+@subsubsection Sparclet download
+
+@cindex download to Sparclet
+Once connected to the Sparclet target, 
+you can use the @value{GDBN}
+@code{load} command to download the file from the host to the target.
+The file name and load offset should be given as arguments to the @code{load}
+command.
+Since the file format is aout, the program must be loaded to the starting 
+address.  You can use objdump to find out what this value is.  The load
+offset is an offset which is added to the VMA (virtual memory address)
+of each of the file's sections.
+For instance, if the program
+@file{prog} was linked to text address 0x1201000, with data at 0x12010160
+and bss at 0x12010170, in @value{GDBN}, type:
+
+@example
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end example
+
+If the code is loaded at a diferent address then what the program was linked 
+to, you may need to use the @code{section} and @code{add-symbol-file} commands 
+to tell @value{GDBN} where to map the symbol table.
+
+@node Sparclet Execution
+@subsubsection Running and debugging
+
+@cindex running and debugging Sparclet programs
+You can now begin debugging the task using @value{GDBN}'s execution control
+commands, @code{b}, @code{step}, @code{run}, etc.  See the @value{GDBN} 
+manual for the list of commands.
+
+@example
+(gdbslet) b main
+Breakpoint 1 at 0x12010000: file prog.c, line 3.
+(gdbslet) run 
+Starting program: prog
+Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
+3        char *symarg = 0;
+(gdbslet) step
+4        char *execarg = "hello!";
+(gdbslet)                           
+@end example
+
+@end ifset
+
 @ifset H8
 @node Hitachi Remote
 @subsection @value{GDBN} and Hitachi microprocessors