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

@node Sun
@section Sun targets 
@cindex Sun targets

Cygnus currently supports
 
@menu
* Suntools::                     What to call the tools
* Suncompile::                   Compiling on the Sun target family   
* Sundebug::                     Debugging on the Sun target family
* SunI/O::                       I/O for specific target architectures
* Sunload::                      Loading on specific target architectures
* Sundoc::                       Further documentation
@end menu

@node Suntools
@subsection What to call the tools
@cindex naming Sun tools
@cindex tools, naming, Sun

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:

@table @code
@kindex XXXXX-gcc
@item XXXXX-gcc

@kindex XXXXX-gcc
@item XXXXX-gcc
@end table

Likewise, the XXXXX-configured @sc{gdb} is called by the name:

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

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

@xref{}.

@node Suncompile
@subsection Compiling on Sun targets
@cindex compiling, Sun targets

The Sun target family toolchain controls variances in code generation 
directly from the command line.

@emph{Note:} Much of the code is experimental, and may change in
the future.

@smallexample
  int __main() @{@}
@end smallexample

When you @emph{configure} @code{@value{GCC}} itself, you can control what 
register management strategies to use on the Sun, and what kind of software
floating-point entry points to generate if hardware floating-point is
not available.

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

@menu
* Suncopts::                      Compiler options
* Sunpopts::                      Preprocessor macros
* Sunaopts::                      Assembler options
* Sunlopts::                      Linker options
* Suncall::                       Calling conventions
@end menu    

@node Suncopts
@subsubsection Compiler options
@cindex compiler options, Sun
@cindex options, compiler, Sun

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}.

@subheading GCC options for architecture and code generation
@cindex architecture and code generation options, Sun
@cindex options, architecture and code generations, Sun

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

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

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.

@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

@node Sunpopts
@subsubsection Predefined preprocessor macros
@cindex preprocessor macros, Sun
@cindex macros, preprocessor, Sun

@node Sunacopts
@subsubsection Assembler options
@cindex assembler options, Sun
@cindex options, assembler, Sun

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
$ XXXXX-ecoff-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, Sun
@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.

@item
@kindex -L, Sun
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, Sun
@item .nolist
Turn off listings from this point on.

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

@kindex .psize @var{linecount} , @var{columnwidth}, Sun
@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, Sun
@item .eject
Skip to a new page (issue a form feed).

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

@kindex .sbttl, Sun
@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}.

@node Sunlopts
@subsubsection Linker options
@cindex linker options, Sun
@cindex options, linker, Sun

@node Suncall
@subsubsection Calling conventions
@cindex calling conventions, Sun
@cindex conventions, calling, Sun
@cindex register handling, Sun

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

@node Sundebug
@subsection Debugging on Sun targets
@cindex debugging, Sun targets
@cindex @sc{gdb}, using on Sun targets

@sc{gdb} needs to know these things to talk to your Sun:

@enumerate
@item
that you want to use one of the following:

@itemize
@item 
@samp{target }, .
@item 
@samp{target }, . 
@item 
@samp{target }, .
@end itemize

@item
what serial device connects your host to your Sun board (the first
serial device available on your host is the default).

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

@code{XXXXX-ecoff-gdb} does what?

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

@table @code
@kindex target XXXXX @var{port}
@item target XXXXX @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 XXXXX @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, you may use the @code{load} command to download
it.  You can then use all the usual @sc{gdb} commands.

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
host$ XXXXX-ecoff-gdb @var{prog}
GDB is free software and @dots{}
(gdb) target XXXXX /dev/ttyb
@dots{}
(gdb) load
@dots{}
(gdb) run
@end smallexample

@kindex target XXXXX @var{hostname}:@var{portnumber}
@item target XXXXX @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 board is
connected so that this makes sense; for instance, to a serial line
managed by a terminal concentrator).
@end table

@noindent @sc{gdb} also supports:

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

@node SunI/O
@subsection I/O for specific target architectures
@cindex I/O on Sun targets


@menu
* SunI/O1::                 I/O for Sun arch #1
* SunI/O2::                 I/O for Sun arch #2
@end menu

@node SunI/O1
@subsubsection arch #1

@node SunI/O2
@subsubsection arch #2

@node Sunload
@subsection Loading on specific target architectures
@cindex loading on Sun targets


@menu
* Sunload1::                 Loading on Sun arch #1
* Sunload2::                 Loading on Sun arch #2
@end menu

@node Sunload1
@subsubsection arch #1

@node Sunload2
@subsubsection arch #2


@node Sundoc
@subsection Further documentation 
@cindex documentation on Sun targets



