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

@node Hitachi SH
@section Hitachi SH targets
@cindex Hitachi SH targets
 
@c Cygnus currently supports 

@menu
* HSHtools::                     What to call the tools
* HSHcompile::                   Compiling on the Hitachi SH target family   
* HSHdebug::                     Debugging on the Hitachi SH target family
* HSHdoc::                       Further documentation
@end menu
@c * HSHload::                      Loading on specific target architectures
@c * HSHI/O::                       I/O for specific target architectures

@node HSHtools
@subsection What to call the tools
@cindex naming Hitachi SH tools
@cindex tools, naming, Hitachi SH

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:

@kindex sh-hms-gcc
@w{@code{sh-hms-gcc}}

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

@kindex sh-hms-gdb
@w{@code{sh-hms-gdb}}

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

@node HSHcompile
@subsection Compiling on Hitachi SH targets
@cindex compiling, Hitachi SH targets

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

@menu
* HSHcopts::                      Compiler options
* HSHaopts::                      Assembler options
* HSHcall::                       Calling conventions
@end menu    
@c * HSHpopts::                      Preprocessor macros
@c * HSHlopts::                      Linker options

@node HSHcopts
@subsubsection Compiler options
@cindex compiler options, Hitachi SH
@cindex options, compiler, Hitachi SH

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

@c examples would be totally keen
@table @code
@kindex -m1
@item -m1
Generate code for the Hitachi @sc{sh}-1 chip.  This is the default
behavior for the Hitachi @sc{sh} configuration.

@kindex -m2
@item -m2
Generate code for the Hitachi @sc{sh}-2 chip.

@kindex -m3
@item -m3
Generate code for the Hitachi @sc{sh}-3 chip.

@kindex -mhitachi
@item -mhitachi
Use Hitachi's calling convention rather than that for @code{@value{GCC}}.  The
registers @samp{MACH} and @samp{MACL} are saved with this setting
(@pxref{HSHcall,,Calling conventions}).

@kindex -mspace
@item -mspace
Generate small code rather than fast code.  By default, @sc{gcc} generates 
fast code rather than small code. 

@kindex -mb
@item -mb
Generate big endian code.  This is the default.

@kindex -ml
@item -ml
Generate little endian code.  

@kindex -mrelax
@item -mrelax
Do linker relaxation.  For the Hitachi @sc{sh}, this means the @samp{jsr} 
instruction can be converted to the @samp{bsr} instruction.  @samp{-mrelax} 
replaces @samp{mbsr}.

@kindex -mbigtable
@item -mbigtable
Generate jump tables for switch statements using four-byte offsets
rather than the standard two-byte offset.  This option is necessary when
the code within a switch statement is larger than 32k.  If the option is
needed and not supplied, the assembler will generate errors.
@end table

@ignore
@need 1000
@subheading GCC options for floating point
@cindex floating point options, Hitachi SH
@cindex options, floating point, Hitachi SH
@end ignore

@subheading Floating point subroutines 
@cindex floating point subroutines, Hitachi SH
@cindex subroutines, floating point, Hitachi SH

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 HSHpopts
@subsubsection Predefined preprocessor macros
@cindex preprocessor macros, Hitachi SH
@cindex macros, preprocessor, Hitachi SH
@end ignore

@node HSHaopts
@subsubsection Assembler options
@cindex assembler options, Hitachi SH
@cindex options, assembler, Hitachi SH

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
$ sh-hms-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, Hitachi SH
@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, Hitachi SH
@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, Hitachi SH
@item .nolist
Turn off listings from this point on.

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

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

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

@kindex .sbttl, Hitachi SH
@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 HSHlopts
@subsubsection Linker options
@cindex linker options, Hitachi SH
@cindex options, linker, Hitachi SH
@end ignore

@node HSHcall
@subsubsection Calling conventions
@cindex calling conventions, Hitachi SH
@cindex conventions, calling, Hitachi SH
@cindex register handling, Hitachi SH

The first four words of arguments are passed in registers @samp{R4}
through @samp{R7}.  All remaining 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.  The registers are
always filled, so a double word argument starting in @samp{R7} would
have the most significant word in @samp{R7} and the least significant
word on the stack.

Function return values are stored in @samp{R0}.
Register @samp{R15} has a reserved use.  Registers @samp{R0} through 
@samp{R7}, @samp{T}, @samp{MACH} and @samp{MACL} can be used for temporary 
values.

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

@kindex -mhitachi SH
The @samp{-mhitachi SH} switch makes the @samp{MACH} and @samp{MACL}
registers caller-saved, which is compatible with the Hitachi @sc{sh} tool chain
at the expense of performance.

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

@node HSHdebug
@subsection Debugging on Hitachi SH targets
@cindex debugging, Hitachi SH targets
@cindex @sc{gdb}, using on Hitachi SH targets

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

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

@itemize
@item
@samp{target remote}, the remote debugging interface for the Hitachi @sc{sh} 
microprocessor.
@item 
@samp{target e7000}, the e7000 in-circuit emulator for the Hitachi @sc{sh} and 
the Hitachi @sc{sh @w{300h}}. 
@item
@samp{target hms}, the HMS rom monitor on @sc{sh} and @sc{h8/300} boards.
@item 
@samp{target sim}, the simulator, which allows you to run @sc{gdb} remotely 
without an external device.
@end itemize

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

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

@noindent
The last two pieces of information are not needed for @samp{target sim}, as
the simulator is built in.

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

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

@kindex target hms @var{hostname}:@var{portnumber}
@item target hms @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}, Hitachi SH
@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 HSHI/O
@subsection I/O for specific target architectures
@cindex I/O on Hitachi SH targets

@menu
* HSHI/O1::                 I/O for Hitachi SH arch #1
* HSHI/O2::                 I/O for Hitachi SH arch #2
@end menu

@node HSHI/O1
@subsubsection arch #1

@node HSHI/O2
@subsubsection arch #2
@end ignore

@ignore
@node HSHload
@subsection Loading on specific target architectures
@cindex loading on Hitachi SH targets

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

@menu
* HSHload1::                 Loading on Hitachi SH arch #1
* HSHload2::                 Loading on Hitachi SH arch #2
@end menu

@node HSHload1
@subsubsection arch #1

@node HSHload2
@subsubsection arch #2
@end ignore

@node HSHdoc
@subsection Further documentation
@cindex documentation on Hitachi SH targets

The following manuals provide extensive documentation on the Hitachi @sc{sh}.
They are produced by and available from Hitachi @sc{sh} Microsystems; contact
your friendly Field Application Engineer for details.

@table @cite
@item SH Microcomputer User's Manual
Semiconductor Design & Development Center, 1992

@item Hitachi SH2 Programming Manual
Semiconductor and Integrated Circuit Division, 1994
@end table


