@c This documents the Sparc target family,
@c as @included in targets.texi
@c
@c FIXME: Find all XXXXX's and replace with target names!

@node Sparc
@section Sparc targets
@cindex Sparc targets

The Cygnus Developer's Kit supports the Fujitsu @w{@code{SPARClite}} 
family as a variant of the support for @sc{sparc}.  For the compiler in 
particular, special configuration options allow you to use special software
floating-point code (for the Sparc MB86930 chip), as well as
defaulting command-line options to use special Fujitsu @w{@code{SPARClite}} 
features.

Cgynus currently supports the Fujitsu @w{@code{SPARClite}} ex930, ex931, 
ex932, ex933, ex934, and the ex936 boards. 

@menu
* Stools::                     What to call the tools
* Scompile::                   Compiling on the Sparc target family   
* Sdebug::                     Debugging on the Sparc target family
* Sload::                      Loading on specific target architectures
* Sdoc::                       Documentation on the Sparc target family                
@end menu
@c * SI/O::                       I/O for specific target architectures

@node Stools
@subsection What to call the tools
@cindex naming Sparclite tools
@cindex tools, naming, Sparclite

Cross-development tools in the Cygnus Developer's Kit are normally
installed with names that reflect the target machine, so that you can
install more than one set of tools in the same binary directory.

The target name, constructed with the @code{--target} option to 
@code{configure}, is used as a prefix to the program name.  
 For example, the compiler (called simply @code{gcc} in native 
configurations) is called by one of these names for @w{@code{SPARClite}} 
cross-development, depending on which configuration you have installed:

@smallexample
@kindex sparclite-aout-gcc
sparclite-aout-gcc
@kindex sparclite-coff-gcc
sparclite-coff-gcc
@end smallexample

Likewise, the @w{@code{SPARClite}}-configured @sc{gdb} is called:

@kindex sparclite-gdb
@w{@code{sparclite-gdb}}

For @sc{dos}-hosted toolchains, the tools are simply called by their
standard names, e.g., @code{gcc}, @code{gdb}, etc.

@ignore
@xref{SPLITEGCC Configuration,,Setting up GCC for the @w{SPARClite}}, for
explanations of the alternative @w{@code{SPARClite}} configurations.
@end ignore

@ignore
@subheading Setting up GCC for the Fujitsu @w{SPARClite}

There are two variants of Fujitsu @w{@code{SPARClite}} support in
@code{@value{GCC}} configurations.  These variants reflect the different
file formats supported.

@table @code
@item --target=sparclite-aout
Generate @w{@code{SPARClite}} code (including use of additional
instructions), for the @code{a.out} file format.

@item --target=sparclite-coff
Generate @w{@code{SPARClite}} code (including use of additional
instructions), for the @code{coff} file format.
@end table

There are two configurations for @sc{sparc} chips
without the addititional @w{@code{SPARClite}} instructions:
@samp{--target=sparc-aout} and @samp{--target=sparc-coff}.

@end ignore

@node Scompile
@subsection Compiling on Fujitsu @w{SPARClite} targets
@cindex compiling, Sparc targets

The Fujitsu @w{@code{SPARClite}} target family toolchain controls variances in 
code generation directly from the command line.

When you run @code{@value{GCC}}, you can use command-line options to 
choose whether to take advantage of the extra @w{@code{SPARClite}} machine 
instructions, and whether to generate code for hardware or software floating 
point.

@menu
* Scopts::                      Compiler options
* Saopts::                      Assembler options
* Scall::                       Calling Conventions
@end menu    
@c * Spopts::                      Preprocessor macros
@c * Slopts::                      Linker options


@node Scopts
@subsubsection Compiler options
@cindex compiler options, Sparc
@cindex options, compiler, Sparc

When you run @code{@value{GCC}}, you can use command-line options to choose
machine-specific details.  For information on all the @code{@value{GCC}} 
command-line options, see 
@ref{Invoking GCC,,GNU CC Command Options,gcc.info,Using GNU CC}.

@ignore
@node SPLITEArchitecture
@section Fujitsu SPARClite options for architecture and code generation
@end ignore

@subheading GCC options for architecture and code generation
@cindex architecture and code generation options, Sparc
@cindex options, architecture and code generation, Sparc

@c FIXME: Check this to make sure it covers # of register windows and clarifies@c the two compilation models, FRW and FRWcompat.}

Some special compiler command-line options are available for Fujitsu 
@w{@code{SPARClite}}; in addition, the machine-dependent options already
present for @sc{sparc} in general continue to be available.  Both kinds of
options are described in @ref{SPARC Options,, SPARC Options, gcc.info,
Using GNU CC}.

@table @code
@kindex -msparclite
@item -msparclite
The @sc{sparc} configurations of @code{@value{GCC}} generate code for the 
common subset of the instruction set: the v7 variant of the @sc{sparc} 
architecture.

@samp{-msparclite} (which is on automatically for any of the Fujitsu 
@w{@code{SPARClite}} configurations) gives you @w{@code{SPARClite}} code.  
This adds the integer multiply (@code{smul} and @code{umul}, just as in 
@sc{sparc} v8), integer divide-step (@code{divscc}), and scan (@code{scan}) 
instructions which exist in @w{@code{SPARClite}} but not in @sc{sparc} v7.

Using @samp{-msparclite} when you run the compiler does @emph{not},
however, give you floating point code that uses the entry points for US
Software's @sc{gofast} library.  

@ignore
@c FIXME: this is configuring stuff that JT would like to see in the 
@c configure doc, not here.  -- Victoria
@c
The software floating-point entry
points depend on how you @emph{configure} the compiler; with the normal 
@sc{sparc} configuration, @code{@value{GCC}} generates code that uses the 
conventional @code{@value{GCC}} soft-floating-point library entry points.  
To get the US Software entry points, you must configure the compiler for 
@w{@code{SPARClite}} as described above.
@end ignore

@kindex -mv8
@item -mv8
@samp{-mv8} gives you @sc{sparc} v8 code.  The only difference from v7 code
is that the compiler emits the integer multiply (@code{smul} and
@code{umul}) and integer divide (@code{sdiv} and @code{udiv})
instructions which exist in @sc{sparc} v8 but not in @sc{sparc} v7.

@kindex -mf930
@item -mf930
Generate code specifically intended for the Sparc MB86930, a Fujitsu 
@w{@code{SPARClite}} chip without an FPU.  This option is equivalent to the 
combination @samp{-msparclite -mno-fpu}.

@samp{-mf930} is the default when the compiler is configured
specifically for Fujitsu @w{@code{SPARClite}}.

@kindex -mf934
@item -mf934
Generate code specifically for the Sparc MB86934, a Fujitsu 
@w{@code{SPARClite}} chip @emph{with} an FPU.  This option is equivalent to 
@samp{-msparclite}.

@kindex -mflat
@item -mflat
Does not use register windows in function calls.
This option replaces the previous @code{frw} support for the
@code{sparclitefrw-*} and @code{sparcfrw-*} configurations.
Code generated with @samp{-mflat} is compatible with the normal
register window calling convention.
@end table

The following command line options are available for both Fujitsu 
@w{@code{SPARClite}} and other @sc{sparc} configurations of the compiler.  
@xref{SPARC Options,, SPARC Options, gcc.info, Using GNU CC}.

@ignore
@node SPLITEFloats and GCC
@section Compiler command-line options for floating point
@end ignore

@subheading GCC options for floating point 
@cindex floating point options, Sparc
@cindex options, floating point, Sparc

When you run the compiler, you can specify whether to compile for
hardware or software floating point configurations with these 
@code{@value{GCC}} command-line options:

@table @code
@kindex -mfpu
@kindex -mhard-float
@item -mfpu
@itemx -mhard-float
Generate output containing floating point instructions.  This is the
default.

@kindex -msoft-float
@kindex -mno-fpu
@item -msoft-float
@itemx -mno-fpu
Generate output containing library calls for floating point.
The @sc{sparc} configurations of @file{libgcc} include a collection of
subroutines to implement these library calls.

In particular, the Fujitsu @w{@code{SPARClite}} @code{@value{GCC}} 
configurations generate subroutine calls compatible with the US Software 
@file{goFast.a} floating point library, giving you the opportunity to use 
either the @file{libgcc} implementation or the US Software version.

To use the US Software library, simply include @samp{-lgoFast} on the
@code{@value{GCC}} command line.

To use the @file{libgcc} version, you need nothing special; @code{@value{GCC}} 
links with @file{libgcc} automatically after all other object files and
libraries.
@end table

@ignore
@node SPLITEFloat Calls
@section Floating point subroutines
@end ignore

@subheading Floating point subroutines 
@cindex floating point subroutines, Sparc
@cindex subroutines, floating point, Sparc

Two kinds of floating point subroutines are useful with @code{@value{GCC}}:

@enumerate
@item
Software implementations of the basic functions (floating-point
multiply, divide, add, subtract), for use when there is no hardware
floating-point support.

When you indicate that no hardware floating point is available (with
either of the @code{@value{GCC}} options @samp{-msoft-float} or 
@samp{-mno-fpu}), the Fujitsu @w{@code{SPARClite}} configurations of 
@code{@value{GCC}} generate calls compatible with the U.S. Software 
@sc{gofast} library.  If you do not have this library, you can still use 
software floating point; @file{libgcc}, the auxiliary library distributed with 
@code{@value{GCC}}, includes compatible---though slower---subroutines.

@item
General-purpose mathematical subroutines.

The Developer's Kit from Cygnus Support includes an implementation of
the standard C mathematical subroutine library.  @xref{Top,,
Mathematical Functions,libm.info, The Cygnus C Math Library}.
@end enumerate

@ignore
@node SPLITEOptions to Avoid
@section SPARC options for unfinished features

@subheading SPARC options for unfinished features 
@cindex options, unfinished, Sparc

@end ignore

@ignore
@node Spopts
@subsubsection Predefined preprocessor macros
@cindex preprocessor macros, Sparc
@cindex macros, preprocessor, Sparc
@end ignore

@node Saopts
@subsubsection Assembler options
@cindex assembler options, Sparc
@cindex options, assembler, Sparc

You should use @sc{gnu} @code{as} to assemble @code{@value{GCC}} output.  
To ensure this, @code{@value{GCC}} should be configured using the 
@samp{--with-gnu-as} switch (as it is in Cygnus distributions
@c @ ; pxref{MIPSConfig,,Configuring @sc{gnu} source for IDT/MIPS}
).  
Alternatively, you can invoke @code{@value{GCC}} with the @code{-mgas}
option.

If you invoke @code{as} via the @sc{gnu} C compiler (version 2), you can use
the @samp{-Wa} option to pass arguments through to the assembler.  One
common use of this option is to exploit the assembler's listing
features.  Assembler arguments you specify with @code{gcc -Wa} must be
separated from each other (and the @samp{-Wa}) by commas.  For example,
the @samp{-alh} assembler option in the following commandline:

@smallexample
$ sparclite-aout-gcc -c -g -O -Wa,-alh,-L file.c
@end smallexample

@noindent
requests a listing with high-level language and assembly language
interspersed.

The example also illustrates two other convenient options to specify
for assembler listings:

@enumerate
@kindex -g, Sparc
@item
The compiler debugging option @samp{-g} is essential to see interspersed
high-level source statements, since without debugging information the
assembler cannot tie most of the generated code to lines of the original
source file.

@kindex -L, Sparc
@item
The additional assembler option @samp{-L} preserves
local labels, which may make the listing output more intelligible to
humans.
@end enumerate

These are the options to enable listing output from the assembler.  By
itself, @samp{-a} requests listings of high-level language source,
assembly language, and symbols.

You can use other letters to select specific options for the list:
@samp{-ah} requests a high-level language listing, @samp{-al} requests
an output-program assembly listing, and @samp{-as} requests a symbol
table listing.  High-level listings require that a compiler debugging
option like @samp{-g} be used, and that assembly listings (@samp{-al})
be requested also.

You can use the @samp{-ad} option to @emph{omit} debugging directives
from the listing.

When you specify one of these options, you can further control listing
output and its appearance using these @dfn{listing-control} assembler
directives:

@table @code
@kindex .nolist, Sparc
@item .nolist
Turn off listings from this point on.

@kindex .list, Sparclite
@item .list
Turn listings back on from here.

@kindex .psize @var{linecount} , @var{columnwidth}, Sparc
@item .psize @var{linecount} , @var{columnwidth}
Describe the page size for your output.  (Default 60, 200.)
The assembler generates form feeds after printing each group of
@var{linecount} lines.  To avoid these automatic form feeds, specify 0
as the @var{linecount}.

@kindex .eject, Sparc
@item .eject
Skip to a new page (issue a form feed).

@kindex .title, Sparc
@item .title
Use @var{heading} as the title (second line, immediately after the
source file name and pagenumber).

@kindex .sbttl, Sparc
@item .sbttl
Use @var{subheading} as the subtitle (third line, immediately after the
title line) when generating assembly listings.
@end table

If you do not request listing output with one of the @samp{-a} options,
these listing-control directives have no effect.  You can also use the
@samp{-an} option to turn off all forms processing.

The letters after @samp{-a} may be combined into one option,
@emph{e.g.}, @samp{-aln}.

The @sc{gnu} assembler, configured for @sc{sparc}, recognizes the additional 
Fujitsu @w{@code{SPARClite}} machine instructions that @code{@value{GCC}} can 
generate.

@table @code
@kindex -Asparclite
@item
-Asparclite 
A flag to the @sc{gnu} assembler (configured for @sc{sparc}) explicitly 
selects this particular @sc{sparc} architecture.  The @sc{sparc} assembler 
automatically selects the Fujitsu @w{@code{SPARClite}} architecture whenever 
it encounters one of the @w{@code{SPARClite}}-only instructions (@code{divscc} 
or @code{scan}).
@end table

@ignore
@node Slopts
@subsubsection Linker options
@cindex linker options, Sparc
@cindex options, linker, Sparc
@end ignore

@node Scall
@subsubsection Calling conventions
@cindex calling conventions, Sparc
@cindex conventions, calling, Sparc
@cindex register handling, Sparc

The first six words of arguments are passed in registers @samp{R8}
through @samp{R13}.  All remaining arguments are stored in a reserved 
block on the stack, last to first, so that the lowest numbered argument not 
passed in a register is at the lowest address in the stack.  The registers are
always filled, so a double word argument starting in @samp{R13} would
have the most significant word in @samp{R13} and the least significant
word on the stack.

Function return values are stored in @samp{R8}.  @samp{R14} and @samp{R15} 
have reserved uses.  @samp{R0} is hardwired so that it always has the value 
@code{0}.  Registers @samp{R1} through @samp{R7} can be used for temporary 
values.

When a function is compiled with the default options, it must return
with registers @samp{R16} through @samp{R29} unchanged.

Note that functions compiled with different calling conventions cannot
be run together without some care.

@node Sdebug
@subsection Debugging on Sparc @w{SPARClite} targets
@cindex debugging, Sparc targets
@cindex @sc{gdb}, using on Sparc targets

@sc{gdb} needs to know these things to talk to your Fujitsu 
@w{@code{SPARClite}}:

@enumerate
@item
that you want to use:

@itemize
@item
@samp{target remote}, the remote debugging interface for the Fujitsu 
@w{@code{SPARClite}} microprocessor.
@end itemize

@item
what serial device connects your host to your Fujitsu @w{@code{SPARClite}} 
board (the first serial device available on your host is the default).

@item
what speed to use over the serial device.
@end enumerate

@noindent
Use one of these @sc{gdb} commands to specify the connection to your target 
board:

@table @code
@kindex target sparclite @var{port}
@item target sparclite @var{port}
To run a program on the board, start up @sc{gdb} with the name of your
program as the argument.  To connect to the board, use the command
@samp{target sparclite @var{port}}, where @var{port} is the name of the
serial port connected to the board.  If the program has not already been
downloaded to the board, use the @code{load} command to download
it.  

For example, this sequence connects to the target board through a serial
port, and loads and runs a program called @var{prog} through the
debugger:

@smallexample
(gdb) target sparclite com1
[SPARClite appears to be alive]
(gdb) load
[Loading section .text at 0x40000000 (9160 bytes)]
[Loading section .data at 0x400023c8 (96 bytes)]
[Starting hello at 0x40000020]
@end smallexample

@noindent @code{target sparclite} allows loading, but no other operations.
This sequence uses @code{target remote} to debug:

@smallexample
(gdb) target remote com1
Remote debugging using com1
breakinst () ../sparcl-stub.c:975
975     @}
(gdb) s
main () hello.c:50
50        writez(1, "Got to here\n");
(gdb) 
@end smallexample

@kindex target sparclite @var{hostname}:@var{portnumber}
@item target sparclite @var{hostname}:@var{portnumber}
@c If your @sc{gdb} is configured to run from a SunOS or SGI host, y
You can specify a TCP/IP connection instead of a serial port, using the syntax
@code{@var{hostname}:@var{portnumber}} (assuming your @w{@code{SPARClite}} 
board is connected so that this makes sense; for instance, to a serial line
managed by a terminal concentrator).
@end table

@need 1000
@noindent @sc{gdb} also supports:

@table @code
@kindex set remotedebug @var{n}, Sparc
@item set remotedebug @var{n}
You can see some debugging information about communications with the board
by setting the @code{remotedebug} variable. 
@end table

@ignore
@node SI/O
@subsection I/O for specific target architectures
@cindex I/O on Sparc targets

@menu
* SI/O1::                 I/O for the ex930, 932, 933, 934, and 936 boards
* SI/O2::                 I/O for the ex931 board
@end menu

@node SI/O1
@subsubsection ex930, 932, 933, 934, and 936 boards
@cindex I/O on ex 930, 932, 933, 934, and 936 boards

@node SI/O2
@subsubsection ex931 boards
@cindex I/O on ex931 boards
@end ignore

@node Sload
@subsection Loading on specific target architectures
@cindex loading on Sparc targets

The Sparc eval boards use a host-based terminal program to load and
execute programs on the target. This program, @code{pciuh}, is relatively
new 
@c (in 1994) 
and it replaces the previous @code{ROM} monitor, which had the
shell in the @code{ROM}.  

@ignore
@menu
* Sload1::                 Loading on the ex930, 932, 933, 934, and 936 boards
* Sload2::                 Loading on the ex931 board
@end menu

@node Sload1
@subsubsection ex930, 932, 933, 934, and 936 boards
@cindex loading on ex 930, 933, 934, 936 boards
@end ignore

To use the @sc{gdb} remote serial protocol to communicate with a Fujitsu 
@w{@code{SPARClite}} board, link your programs with the
``stub'' module @file{sparc-stub.c}; this module manages the
communication with @sc{gdb}.  @xref{Remote Serial,, The GDB remote
serial protocol, gdb.info, Debugging with GDB}, for more details.

@ignore
To download a program to your board from inside @sc{gdb},
do one of the following:

@smallexample
target sparclite @var{port@dots{}}
load
target remote @var{port@dots{}}
@end smallexample
@noindent
where @var{port} is the port to which your board is connected:
@code{com1}, @code{com2}, etc.  

OR

@smallexample
target sparclite @var{hostname@dots{}}@var{:portnumber@dots{}}
load
target remote @var{hostname@dots{}}@var{:portnumber@dots{}}
@end smallexample
@noindent
where @var{hostname} is the host on which you run the GNU tools 
and @var{portnumber} is the number of the port to which your board is 
connected.
@end ignore

@ignore
@node Sload2
@subsubsection ex931 boards
@cindex loading on ex931 boards
@end ignore

@node Sdoc
@subsection Further documentation
@cindex documentation on Sparc targets

See @cite{@w{SPARClite} User's Manual} (Fujitsu Microelectronics, Inc.
Semiconductor Division, 1993) for full documentation of the
@w{@code{SPARClite}} family, architecture, and instruction set.







