@c @chapter Sliced Bread Project GNU Toolset

@menu
* SBP Names::         What the tools are called for the SBP ARC
* SBP GCC::           Compiling code for the SBP ARC
* SBP Gplus::         Using C++ for the SBP ARC
* SBP GAS::           Assembling code for the SBP ARC
* SBP GDB::           Debugging code for the SBP ARC
* SBP Biendian::      Dual Endian Support
* SBP CPU Mangling::  Function name mangling by CPU
* SBP Startup code::  Startup code and linker scripts
* SBP PIC::           Position Independent Code
* SBP ABI::           SBP Application Binary Interface
* SBP Refs::          SBP ARC documentation
@end menu

@node SBP Names
@chapter What the tools are called for the SBP @sc{ARC}.

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 names are constructed by using as a prefix the @samp{--target}
argument to @code{configure}.  For example, the compiler (called simply
@code{gcc} in native configurations) is called by the name for SBP
@sc{ARC} cross-development, @w{@code{arc-sbp-elf-gcc}}.  Likewise, the
@sc{ARC}-configured @code{gdb} is called by the name
@w{@code{arc-sbp-elf-gdb}}.

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

@node SBP GCC
@chapter Compiling for the SBP @sc{ARC}

Once the toolchain is configured to generate code for the @sc{ARC}, you
can control variances in code generation directly from the command line.

@subheading General Options

@c examples would be totally keen
@table @code
@item -EL
Generate code for a little-endian @sc{ARC} chip.
This is the default.
@item -EB
Generate code for a big-endian @sc{ARC} chip.
@item -mcpu=@{base,host,graphics,audio@}
Generate code for the indicated cpu variant.
The default is @samp{base}.
@item -fpic
Generate position independent code.
This option is not supported yet.
@end table

For a complete list of options, refer to the relevant sections of the
GCC, GAS (assembler), and GLD (linker) manuals.

@subheading Predefined Preprocessor Symbols

The following @sc{ARC} specific symbols are predefined by the preprocessor
and are available for programs to use.

@table @code
@item __arc__
This symbol is always defined.
@item __base__
This symbol is defined when no special CPU variant is selected
@item __host__
This symbol is defined when the @samp{host} CPU is selected.
@item __graphics__
This symbol is defined when the @samp{graphics} CPU is selected.
@item __audio__
This symbol is defined when the @samp{audio} CPU is selected.
@item __big_endian__
This symbol is defined when big-endian support is selected.
@end table

@node SBP Gplus
@chapter Using C++ for the SBP @sc{ARC}

This release includes support for the C++ language.

Big-endian support is not complete yet.  The necessary
C++ libraries have also not been compiled for big-endian mode.

You must compile with @samp{-mcpu=base}, the default, because the
necessary C++ libraries for the other CPU variants have not been built.

@node SBP GAS
@chapter Assembling code for the SBP @sc{ARC}

The GNU assembler follows the syntax in the programmer's reference
manual as close as possible.  There are no known divergences but
that does not mean there will not ever be.  Of course such divergences
will not be done without reason.

@subheading ARC specific features

The best way to determine what the assembler syntax for a particular
construct is is to write the equivalent in C and see what GCC generates.

@table @code
@item .cpu directive
The @sc{CPU} type must be specified in the source file with the @code{.cpu}
directive.  The syntax is @code{.cpu type} where @code{type} is one of
@samp{base,host,graphics,audio}.
@item %st pseudo-op
@sc{ARC} function addresses are right shifted by two.
To represent this in assembler, use the @code{%st} pseudo-op.

Example:

@smallexample
C code                                  Assembler code
extern void foo (void);
void (*fnptr) (void) = foo;             .word %st(foo)
@end smallexample
@end table

@subheading Incomplete

@table @code
@item norm
The @code{norm} instruction is not implemented.
It will be in the next release.
@item jcc with flags
The @code{jcc} instruction does not accept a @code{flags} argument.
@end table

@node SBP GDB
@chapter Debugging code for the SBP @sc{ARC}

GDB is currently incomplete and has not been provided in this release.

@node SBP Biendian
@chapter Dual Endian Support

This release is capable of supporting big endian or little endian
processors, or both simultaneously.  The default will always be
little endian.

Prebuilt @sc{DOS} hosted toolchains from Cygnus only support little
endian processors.  The @code{-EB} @code{GCC} option is recognized,
but the requisite libraries have not been built.
Prebuilt @code{mips-sgi-irix5} hosted toolchains support both big
endian and little endian processors simultaneously.  The requisite
C libraries have been built.  However, the requisite C++ libraries
only exist for little endian processors.

To configure the toolchain to support both endian flavors,
use the @samp{--enable-biendian} option when you run
@samp{configure}.

@node SBP CPU Mangling
@chapter Function name mangling by CPU

Function and variable names are "mangled" akin to the mangling
that is done for C++ objects to provide type-safe linking.
This prevents code compiled for one CPU variant to be linked
with code compiled for another variant.  The mangling is done
by prepending the name of the cpu to the real name.  So, for example,
the @code{main} function for the @samp{host} CPU is called
@code{_host_main}.  All symbols have @samp{_} prepended to avoid
potential collision with register names.  Code compiled for the
@samp{base} CPU has no mangling.

Prebuilt toolchains from Cygnus have all C libraries compiled with CPU name
mangling.  Therefore it is possible to have several copies for
each library function (eg: @code{_host_printf}, @code{_graphics_printf},
and @code{_audio_printf}).  It is expected that the SBP project
will have to recompile the libraries to suit their needs.

To compile code with CPU name mangling turned off, pass the
@samp{-mno-mangle-cpu} option to @sc{GCC}.

@node SBP Startup code
@chapter Startup code and linker scripts

The prebuilt toolchains from Cygnus come with a simple @file{crt0.o}
file which contains the C Run Time startup code.  The source code is
in @file{src/newlib/libc/sys/arc/crt0.S}.

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
; ARC start up file
; In the absence of a custom linker script, go with something
; simple.  We do not support passing arguments to "main", but 
; this is an embedded system anyway.
;
; We call init/fini here without cpu prefixes because there is
; always only one .init/.fini section per image.

	.section .text
	.align 4

	.global	start
start:

	mov	sp,end		; Round "sp" up to page after "end".
	add	sp,sp,4095
	and	sp,sp,-4096

	ld	r8,[stack_size]	; Add stack size to "sp".
	add	sp,sp,r8

	st	sp,[sbrk_start]	; Initialize malloc heap.
	st	sp,[sbrk_loc]

	sub	sp,sp,16	; callee expects 16 bytes already "pushed".
	mov	fp,0		; Top of stack frame indicator.

	mov	r0,edata	; Zero bss.
	mov	r2,end
	sub	r2,r2,r0
	mov	r1,0

#ifdef __base__
	bl.nd	_memset
	bl.nd	init		; .init section entry point.
	mov	r0,%st(fini)	; .fini section entry point.
	bl.nd	_atexit
	mov	r0,0		; argc
	mov	r1,0		; argv
	bl.nd	_main
	bl.nd	_exit
#endif

#ifdef __host__
	bl.nd	_host_memset
	bl.nd	init		; .init section entry point.
	mov	r0,%st(fini)	; .fini section entry point.
	bl.nd	_host_atexit
	mov	r0,0		; argc
	mov	r1,0		; argv
	bl.nd	_host_main
	bl.nd	_host_exit
#endif

#ifdef __graphics__
	bl.nd	_graphics_memset
	bl.nd	init		; .init section entry point.
	mov	r0,%st(fini)	; .fini section entry point.
	bl.nd	_graphics_atexit
	mov	r0,0		; argc
	mov	r1,0		; argv
	bl.nd	_graphics_main
	bl.nd	_graphics_exit
#endif

#ifdef __audio__
	bl.nd	_audio_memset
	bl.nd	init		; .init section entry point.
	mov	r0,%st(fini)	; .fini section entry point.
	bl.nd	_audio_atexit
	mov	r0,0		; argc
	mov	r1,0		; argv
	bl.nd	_audio_main
	bl.nd	_audio_exit
#endif
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

The stack size can be changed by defining the @code{stack_size}
global variable.  Each CPU is expected to have the same stack size.
This may be unrealistic but since the SBP project will be defining
its own startup file anyway, there is no point in getting overly
complicated here.  The variable must be defined like the following
in order to prevent CPU name mangling.

@smallexample
int stack_size asm ("stack_size") = STACK_SIZE;
@end smallexample

The malloc heap size can also be set with:

@smallexample
int sbrk_size asm ("sbrk_size") = SBRK_SIZE;
@end smallexample

The default stack size is 16384 bytes.  The default heap size is
131072 bytes.

The call to @code{__do_global_ctors} is run C++ global static
constructors.  It is not necessary for pure C code, however there
is no harm in leaving the call in.

To link with your own startup file, pass the @samp{-nostartfiles}
option to @sc{GCC}.

@node SBP PIC
@chapter Position Independent Code

The ABI defines how PIC will work with the supplied toolchain.
Support for position independent code is still incomplete so
do not use the @samp{-fpic} @sc{GCC} option.

@node SBP ABI
@chapter SBP Application Binary Interface

An "Application Binary Interface" provides the definition of how the
pieces of a program fit together.  It describes, among other things,

@itemize @bullet
@item
how arguments are passed between functions
@item
how structure elements are laid out
@item
how position independent code (PIC) works
@item
how relocations are done
@item
how functions and data are laid out in an executable image
@end itemize

@include sbp-abi.texi

@node SBP Refs
@chapter SBP @sc{ARC} documentation

The following manuals provide extensive documentation on the @sc{ARC}.

@table @cite
@item ARC Programmers Reference Manual
MultiMedia Technologies
@*
Version 5.02

@item Console Main Application Specific Integrated Circuit (ASIC)
Sliced Bread Project
@*
Design Specification
@*
Version: 1.8.1
@*
SBP Document Number: SBP-D492

@end table

