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

@node Intel 386
@section Intel 386 targets
@cindex Intel 386 targets
 
Cygnus currently supports 

@menu
* I386tools::                     What to call the tools
* I386compile::                   Compiling on the Intel 386 target family   
* I386debug::                     Debugging on the Intel 386 target family
* I386I/O::                       I/O for specific target architectures
* I386load::                      Loading on specific target architectures
* I386doc::                       Further documentation
@end menu

@node I386tools
@subsection What to call the tools
@cindex naming Intel 386 tools
@cindex tools, naming, Intel 386

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-hms-gcc
@item XXXXX-gcc
@end table

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

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

@c @xref{}.

@node I386compile
@subsection Compiling on Intel 386 targets
@cindex compiling, Intel 386 targets

The Intel 386 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 Intel 386 machine instructions,
and whether to generate code for hardware or software floating point.

@menu
* I386copts::                      Compiler options
* I386popts::                      Preprocessor macros
* I386aopts::                      Assembler options
* I386lopts::                      Linker options
* I386call::                       Calling conventions
@end menu    

@node I386copts
@subsubsection Compiler options
@cindex compiler options, Intel 386
@cindex options, compiler, Intel 386

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, Intel 386
@cindex options, architecture and code generation, Intel 386

@subheading GCC options for floating point
@cindex floating point options, Intel 386
@cindex options, floating point, Intel 386

@subheading Floating point subroutines 
@cindex floating point subroutines, Intel 386
@cindex subroutines, floating point, Intel 386

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 I386popts
@subsubsection Predefined preprocessor macros
@cindex preprocessor macros, Intel 386
@cindex macros, preprocessor, Intel 386

@node I386aopts
@subsubsection Assembler options
@cindex assembler options, Intel 386
@cindex options, assembler, Intel 386

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

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

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

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

@kindex .sbttl, Intel 386
@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 I386lopts
@subsubsection Linker options
@cindex linker options, Intel 386
@cindex options, linker, Intel 386

@node I386call
@subsubsection Calling conventions
@cindex calling conventions, Intel 386
@cindex conventions, calling, Intel 386
@cindex register handling, Intel 386

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

@node I386debug
@subsection Debugging on Intel 386 targets
@cindex debugging, Intel 386 targets
@cindex @sc{gdb}, using on Intel 386 targets

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

@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 Intel 386 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}, Intel 386
@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 I386I/O
@subsection I/O for specific target architectures
@cindex I/O on Intel 386 targets

@menu
* I386I/O1::                 I/O for Intel arch #1
* I386I/O2::                 I/O for Intel arch #2
@end menu

@node I386I/O1
@subsubsection arch #1

@node I386I/O2
@subsubsection arch #2

@node I386load
@subsection Loading on specific target architectures
@cindex loading on Intel 386 targets

@menu
* I386load1::                 Loading on Intel arch #1
* I386load2::                 Loading on Intel arch #2
@end menu

@node I386load1
@subsubsection arch #1

@node I386load2
@subsubsection arch #2


@node I386doc
@subsection Further documentation
@cindex documentation on Intel 386 targets

