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

@node MotorPC
@section Motorola PowerPC targets 
@cindex Motorola PowerPC targets

Cygnus currently supports

@menu
* PCtools::                     What to call the tools
* PCcompile::                   Compiling on the Motorola PowerPC target family   
* PCdebug::                     Debugging on the Motorola PowerPC target family
* PCI/O::                       I/O for specific target architectures
* PCload::                      Loading on specific target architectures
* PCdoc::                       Further documentation
@end menu

@node PCtools
@subsection What to call the tools
@cindex naming Motorola PowerPC tools
@cindex tools, naming, Motorola PowerPC

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:

@kindex XXXXX-gcc
@kindex XXXXX-gcc
@smallexample
XXXXX-gcc
XXXXX-gcc
@end smallexample

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

@kindex XXXXX-gdb
@smallexample
XXXXX-gdb
@end smallexample

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

@c @xref{}.

@node PCcompile
@subsection Compiling on Motorola PowerPC targets
@cindex compiling, Motorola PowerPC targets

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

@menu
* PCcopts::                      Compiler options
* PCpopts::                      Preprocessor macros
* PCaopts::                      Assembler options
* PClopts::                      Linker options
* PCcall::                       Calling conventions
@end menu    

@node PCcopts
@subsubsection Compiler options
@cindex compiler options, Motorola PowerPC
@cindex options, compiler, Motorola PowerPC

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

@subheading GCC options for floating point
@cindex floating point options, Motorola PowerPC
@cindex options, floating point, Motorola PowerPC

@subheading Floating point subroutines 
@cindex floating point subroutines, Motorola PowerPC
@cindex subroutines, floating point, Motorola PowerPC

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 PCpopts
@subsubsection Predefined preprocessor macros
@cindex preprocessor macros, Motorola PowerPC
@cindex macros, preprocessor, Motorola PowerPC

@node PCaopts
@subsubsection Assembler options
@cindex assembler options, Motorola PowerPC
@cindex options, assembler, Motorola PowerPC

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

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

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

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

@kindex .sbttl, Motorola PowerPC
@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 PClopts
@subsubsection Linker options
@cindex linker options, Motorola PowerPC
@cindex options, linker, Motorola PowerPC

@node PCcall
@subsubsection Calling conventions
@cindex calling conventions, Motorola PowerPC
@cindex conventions, calling, Motorola PowerPC
@cindex register handling, Motorola PowerPC

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

@node PCdebug
@subsection Debugging on Motorola PowerPC targets
@cindex debugging, Motorola PowerPC targets
@cindex @sc{gdb}, using on Motorola PowerPC targets

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

@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 Motorola PowerPC 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 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}, Motorola PowerPC
@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 PCI/O
@subsection I/O for specific target architectures
@cindex I/O on Motorola PowerPC targets


@menu
* PCI/O1::                 I/O for Motorola PowerPC arch #1
* PCI/O2::                 I/O for Motorola PowerPC arch #2
@end menu

@node PCI/O1
@subsubsection arch #1

@node PCI/O2
@subsubsection arch #2

@node PCload
@subsection Loading on specific target architectures
@cindex loading on Motorola PowerPC targets


@menu
* PCload1::                 Loading on Motorola PowerPC arch #1
* PCload2::                 Loading on Motorola PowerPC arch #2
@end menu

@node PCload1
@subsubsection arch #1

@node PCload2
@subsubsection arch #2

@node PCdoc
@subsection Further documentation
@cindex documentation on Motorola PowerPC targets



