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

@node Motorola m68k
@section Motorola m68k targets 
@cindex Motorola m68k targets

@c Cygnus currently supports

@menu
* Mtools::                     What to call the tools
* Mcompile::                   Compiling on the Motorola m68k target family   
* Mdebug::                     Debugging on the Motorola m68k target family
@end menu
@c * MI/O::                       I/O for specific target architectures
@c * Mload::                      Loading on specific target architectures
@c * Mdoc::                       Further documentation

@node Mtools
@subsection What to call the tools
@cindex naming Motorola m68k tools
@cindex tools, naming, Motorola m68k

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 m68k-coff-gcc
@item m68k-coff-gcc
@kindex m68k-aout-gcc
@item m68k-aout-gcc
@end table

Likewise, the @code{m68k}-configured @sc{gdb} is called by one of these names:

@table @code
@kindex m68k-coff-gdb
@item m68k-coff-gdb
@kindex m68k-aout-gdb
@item m68k-aout-gdb
@end table

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

@c @xref{}.

@node Mcompile
@subsection Compiling on Motorola m68k targets
@cindex compiling, Motorola m68k targets

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

@menu
* Mcopts::                      Compiler options
* Maopts::                      Assembler options
* Mcall::                       Calling conventions
@end menu    
@c * Mpopts::                      Preprocessor macros                         
@c * Mlopts::                      Linker options


@node Mcopts
@subsubsection Compiler options
@cindex compiler options, Motorola m68k
@cindex options, compiler, Motorola m68k

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

@table @code
@kindex -m68000
@item -m68000
Generate code for the Motorola m68000.

@kindex -m68020
@item -m68020
Generate code for the Motorola m68020.

@kindex -m68030
@item -m68030
Generate code for the Motorola m68030.

@kindex -m68040
@item -m68040
Generate code for the Motorola m68040.  Also enables code generation 
for the 68881 FPU by default.

@kindex -m68332
@item -m68332
Generate code for the Motorola cpu32 family, of which the Motorola 
m68332 is a member.  
@end table

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

@table @code
@kindex -msoft-float
@item -msoft-float
Generate output containing library calls for floating point.
The Motorola configurations of @file{libgcc} include a collection of
subroutines to implement these library calls.

@kindex -m68881
@item -m68881
Generate code for the Motorola m68881 FPU.  See compiler option 
@samp{-m68040} above.
@end table

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

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

@ignore
@node Mpopts
@subsubsection Predefined preprocessor macros
@cindex preprocessor macros, Motorola m68k
@cindex macros, preprocessor, Motorola m68k
@end ignore

@node Maopts
@subsubsection Assembler options
@cindex assembler options, Motorola m68k
@cindex options, assembler, Motorola m68k

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{Motorola m68kConfig,,Configuring @sc{gnu} source for IDT/Motorola m68k}
).  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
$ m68k-coff-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 m68k
@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, Motorola m68k
@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, Motorola m68k
@item .nolist
Turn off listings from this point on.

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

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

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

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

@ignore
@node Mlopts
@subsubsection Linker options
@cindex linker options, Motorola m68k
@cindex options, linker, Motorola m68k
@end ignore

@node Mcall
@subsubsection Calling conventions
@cindex calling conventions, Motorola m68k
@cindex conventions, calling, Motorola m68k
@cindex register handling, Motorola m68k

All arguments are pushed onto the stack, last to first, so that the lowest 
numbered argument not passed in a register is at the lowest address in the 
stack.  

Function return values for integers are stored in @samp{D0} and @samp{D1}.  
@samp{A7} has a reserved use.  
Registers @samp{A0}, @samp{A1}, @samp{D0}, @samp{D1} @samp{F0}, and @samp{F1} 
can be used for temporary values.

When a function is compiled with the default options, it must return
with registers @samp{D2} through @samp{D7} and registers @samp{A2} through 
@samp{A6} unchanged.  
If you have floating point registers, then registers @samp{F2} through 
@samp{F7} must also be unchanged.

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

@node Mdebug
@subsection Debugging on Motorola m68k targets
@cindex debugging, Motorola m68k targets
@cindex @sc{gdb}, using on Motorola m68k targets

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

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

@itemize
@item
@samp{target ROM68k}, the rom monitor for the IDP board.
@item
@samp{target cpu32bug}, the rom monitor for other Motorola boards, such as 
the Motorola Business Card Computer, BCC.
@item
@samp{target est}, the EST Net/300 emulator.
@item
@samp{target remote}, the remote debugging interface for the Motorola 
@code{m68k} microprocessor.    
@end itemize

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

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

@ignore
@code{m68k-coff-gdb} does what?
@end ignore

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

@table @code
@kindex target m68k @var{port}
@item target m68k @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 m68k @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$ m68k-coff-gdb @var{prog}
GDB is free software and @dots{}
(gdb) target cpu32bug /dev/ttyb
@dots{}
(gdb) load
@dots{}
(gdb) run
@end smallexample

@kindex target m68k @var{hostname}:@var{portnumber}
@item target m68k @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 m68k
@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
@strong{JT:} The following is from Rob's Embed:

All of the Motorola @code{m68k} VME boards run @code{bug}, a @code{ROM}-based 
debug monitor.  @code{Bug} uses user-level traps to do I/O, so this code 
should be portable to other MVME boards with little, if any, change. 
@c The startup file can remain unchanged. 

There is GDB support for this target environment in the GDB source tree. 
The relevant files are @file{gdb/monitor.c}, @file{monitor.h}, and 
@file{rom58k-rom.c}. 
@c @xref{GDB,,GDB}.
@end ignore

@ignore
@node MI/O
@subsection I/O for specific target architectures
@cindex I/O on Motorola m68k targets

@strong{JT:} The following is from Rob's Embed:

In the Motorola @code{m68k}'s @code{m68k}-based cpu32 processor family,
Libgloss currently supports the Motorola @code{m68k} MVME line of 6U VME 
boards and IDP line of eval boards. 
@c
@c FIXME: Intermetrics or ISI wrote @code{ROM68k} ?
@c
There is also support for the @code{ROM68k} monitor as shipped on
Motorola @code{m68k}'s IDP eval board line. This code should be portable across the
range of CPU's that the board supports. 
The crt0 startup file should be usable with any target environment.
@xref{Crt0,,Crt0 the main startup file}.

Some of the I/O code and linker scripts may vary, depending on the target.
The major difference is the address where the text section begins, and 
this can be changed either in the linker script or on the command line
using @samp{-Ttext [@var{address}]}.  
@xref{Linker Scripts,,The linker script}.  
@xref{Invoking GCC,,,,Using and Porting GNU GCC}, also.
@end ignore

@ignore
@menu
* MI/O1::                 I/O for the MVME line of 6U VME boards
* MI/O2::                 I/O for the IDP line of eval boards
* MI/O3::                 I/O for the ROM68k monitor as shipped on the IDP line of eval boards
@end menu

@node MI/O1
@subsubsection MVME 6U VME boards
@cindex I/O on MVME 6U VME boards

@node MI/O2
@subsubsection IDP eval boards
@cindex I/O on IDP eval boards

@node MI/O3
@subsubsection ROM68k monitors
@cindex I/O on ROM68k minitors
@end ignore

@ignore
@node Mload
@subsection Loading on specific target architectures
@cindex loading on Motorola m68k targets

@menu
* Mload1::                 Loading on the MVME line of 6U VME boards
* Mload2::                 Loading on the IDP line of eval boards
* Mload3::                 Loading on the ROM68k monitor as shipped on the IDP line of eval boards
@end menu

@node Mload1
@subsubsection MVME 6U VME boards
@cindex loading on MVME 6U VME boards

@node Mload2
@subsubsection IDP eval boards
@cindex loading on IDP eval boards

@node Mload3
@subsubsection ROM68k monitors
@cindex loading on ROM68k monitors
@end ignore

@ignore
@node Mdoc
@subsection Further documentation
@cindex documentation on Motorola m68k targets
@end ignore
