/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss or reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

/**

@page gnu_install Installation of the GNU tools

This page gives you help to set up the GNU crosscompiler toolchain for
ARM processors. It is assumed that you work on some unix-ish system, that
is, BSD, Linux, MacOS-X or similar.
If you use Microsoft<sup>&reg;</sup> Windows<sup>&reg;</sup>, you are on your
own; my experience with that operating environment is limited to
to Microsoft<sup>&reg;</sup> Word<sup>&reg;</sup> 1.0 and
Minesweeper<sup>&reg;</sup> on Windows<sup>&reg;</sup> 3.1.
<br><br>
The process below tells you how to install the crosscompiler for a
<i>bare metal</i> system. If you want to set up a crosscompiler for
an ARM based Linux system, the process is much more involved and it is
way beyond the scope of this manual.
<br><br>

@section Requirements Requirements

To set up the ARM crosscompiler toolchain, you will need the following
packages to already having been installed on your system:

- <tt>gcc</tt>, the GNU C compiler for your system
- <tt>make</tt>, the build utility
- <tt>bison</tt>, the GNU parser generator
- <tt>flex</tt>, the GNU lexical analyser generator
- <tt>m4</tt>, the GNU macro processor
- <tt>libtool</tt>, a package to manipulate library installations
- <tt>gmp</tt>, the GNU multi-precision library, plus its headers
- <tt>mpfr</tt>, the multiple-precision float-point library, plus its headers
- <tt>texinfo</tt>, the info page formatting package

On a BSD or Linux system the above can usually be installed by simply telling
your package manager to put them on (don't forget that you need the
"development" package for <tt>gmp</tt> and <tt>mpfr</tt>). On MacOS-X it
might be a little more complex than that, but a little research on the Web
will help you through.

@section tool_install_binutils Installing cross-binutils

Download the binutils source from the FSF website or from a mirror. The
following assumes that you have obtained <tt>binutils-2.20.1.tar.bz2</tt>
but the process is the same for any other version.<br>
Unpack the source:
@verbatim
tar xfj binutils-2.20.1.tar.bz2
@endverbatim
Do <b>not</b> go into the source directory. Create a separate build directry
instead, then go there and configure <tt>binutils</tt> for <tt>arm-eabi</tt>
target. If you prefer ELF over EABI, then use <tt>arm-elf</tt> instead of
<tt>arm-eabi</tt>. If you have no idea what ELF and EABI are all about, you
should first read \ref elf_vs_eabi at the end of this page and come back
here.
@verbatim
mkdir build
cd build
../binutils-2.20.1/configure --target=arm-eabi
@endverbatim
If configure did not complain about any missing packages, you can now
build the binary utilities:
@verbatim
make
@endverbatim
The above command should complete without error. Now you can install your
crossassembler, linker, etc. Pretty much all GNU packages install in
<tt>/usr/local</tt> by default, which is usually not writeable by ordinary
users. So, you have to install as root, either by doing
@verbatim
sudo make install
@endverbatim
or if you don't have sudo on your system, by becoming root (and, depending on
your <tt>su</tt> configuration, going back to the build directory) and typing:
@verbatim
make install
exit
@endverbatim
If the installaction succeeds, as it should, you should now get rid of the
build directory:
@verbatim
cd ..
rm -rf build
@endverbatim

@section tool_install_gcc Installing cross-gcc

Now that you have <tt>binutils</tt> installed, you are ready for the
<tt>gcc</tt> installation.<br>Note that you must install binutils before
you can compile gcc as it needs the already existing crossassembler and
other tools to build the run-time library.<br>
Also note that the instructions below allow you to install 4.0.x to 4.4.x
versions of gcc. The 4.5.x or newer versions require additional packages,
like a polyhedra library development package and alike to be installed.
<br><br>
Download the source rom the FSF website or from a mirror. The following
assumes that you have obtained <tt>gcc-4.4.3.tar.bz2</tt> but the process
is the same for any other 4.[0-4].x version.<br>
First, unpack the source:
@verbatim
tar xfj gcc-4.4.3.tar.bz2
@endverbatim
Create a build directory and enter it:
@verbatim
mkdir build
cd build
@endverbatim
Now configure to build a crosscompiler. There are a few configuration options
that you have to pass. It wouldn't fit in a single line, so it is broken to
multiple lines here, but it is a single command. Note that if you used
<tt>arm-elf</tt> for <tt>binutils</tt> then you must use that for
<tt>gcc</tt> as well.
@verbatim
../gcc-4.4.3/configure --target=arm-eabi --enable-interwork --disable-threads \ 
  --disable-tls --disable-libada --disable-libssp --disable-libgomp \
  --enable-languages=c
@endverbatim
The command should finish without an error. If it complains about a package
missing or being a too old revision, you will have to resolve that issue
before being able to build the compiler. Assuming that <tt>configure</tt>
finished successfully, you can build the crosscompiler:
@verbatim
make
@endverbatim
It will take some time, several minutes (or several tens of minutes if you
have some really old hardware) to complete. It should finish without any
errors; although as it advances, you will see warning messages, but you can
safely ignore them. When it's done, you can install it by:
@verbatim
sudo make install
@endverbatim
just like you did with the <tt>binutils</tt> package. Get rid of the build
directory before you forget:
@verbatim
cd ..
rm -rf build
@endverbatim
To test that your install was really successful and everything is fine,
you can try this:
@verbatim
echo 'void foo( void ) {}' > test.c
arm-elf-gcc -c test.c -o /dev/null
@endverbatim
You should just get the prompt back, without any error messages. If that is
the case, you have a working crosscompiler, you can compile the library, and
of course your own stuff.<br><br>
If you can not make up your mind regarding to the ELF vs. EABI issue, then you
can install both, by going through the above configuration, compilation and
installation procedure twice. When you are completely happy with everything,
you can delete the source directories and the tarfiles:
@verbatim
rm -rf gcc-4.4.3* binutils-2.20.1*
@endverbatim

@section elf_vs_eabi ELF versus EABI

EABI stands for Embedded Application Binary Interface. It is basically a
specification about register allocation, alignment rules, object sizes,
calling conventions and so on. If your compiler conforms to the EABI, then
the object code it generates will be usable by any other EABI compliant
toolchain.
<br><br>
ELF stands for Executable and Link Format, a specification of how the object
files and loadable executables are built. Among other things it is also an
EABI, in that it specifies (most of) the conventions described by an EABI.
<br><br>
From your point of view both ELF and EABI are a specification of object
size and alignment rules as well as register allocation and calling
convention rules. Both will work. However, while they serve the same purpose,
there are differences that you should be aware. Based on these differences you
can make an informed decision about which one to use. The list below applies
only to the 32-bit variants of ARM, for other processor architectures the
rules are different!

- <b>Common in both</b><br>
	Both formats save R4-R11 through calls, use R13 as stack pointer, R12
	as sratch, R0-R3 for parameter passing and R0 or R0-R1 for return
	value.<br>
	The object sizes are also the same: <tt>char</tt> is 8 bits, <tt>short</tt>
	is 16 bits, <tt>int</tt>, <tt>long</tt>, <tt>float</tt> and pointers are
	32 bits, <tt>long long</tt> and <tt>double</tt> are 64 bits.<br>
	Both formats align 8, 16 and 32 bit wide basic types on 1, 2 and 4 byte
	boundaries, respectively.<br>
	The stack grows from larger addresses to smaller ones (i.e. when you push,
	the stackpointer gets decremeneted), the stackpointer points to the last
	item pushed onto the stack (decrement before push, increment after pop).<br>
	Object names are as they are in C, the compiler does not add any prefix or
	suffix to it.<br>
	If a function receives a structure or union as argument, then the object
	gets copied onto the stack and the function argument will be changed to a
	pointer to the copy. If a function returns a struct or a union, then space
	will be allocated for the return object on the stack and the function will
	receive and extra argument (which will be the first), a pointer to the
	space where its return value should be stored. It is true even if the
	received or returned object would otherwise fit in a register.

- <b>Endianness of 64-bit types</b><br>
	Both ELF and EABI store a <tt>long long</tt> in the native endianness of
	the processor. However, a <tt>double</tt> is stored in Big-Endian word
	order in ELF and in the native endianness in EABI.<br>
	When 64-bit objects are passed in registers, they are always placed in
	consecutive registers, like R0 and R1 or R4 and R5 but never like R2 and
	R7. The two registers are treated as if they were two consecutive memory
	locations. That is, if your object would be in memory words at <i>addr</i>
	and <i>addr+4</i>, then the word at <i>addr</i> will be in register
	<i>Rn</i> and the word at <i>addr+1</i> will be in register
	<i>Rn+1</i>. This of course means that since on a Little-Endian
	machine the <tt>double</tt> is stored in different order for ELF and EABI,
	it will also be mapped to registers differently.

- <b>Alignment of 64-bit types</b><br>
	64-bit objects are aligned to 4 bytes in ELF and 8 bytes in EABI.<br>
	That means that ELF simply treats them as two consecutive 32-bit words.
	On the other hand, EABI always aligns then on 8-byte boundaries. That
	applies to alignment of structure fields too. If you have a structure
	that contains an <tt>int</tt> followed by a <tt>double</tt>, ELF will
	put the <tt>double</tt> right after the <tt>int</tt> but EABI will
	introduce an additional word between them, to guarantee that the
	<tt>double</tt> starts at an 8-byte boundary.<br>
	Furthermore, EABI always puts 64-byte objects into a register pair
	where the register corresponding to the memory word at the smaller
	address is an even numbered register, while ELF doesn't care. This
	means that if you have a function of which the first argument is
	an <tt>int</tt> and the second is a <tt>long long</tt>, then ELF
	will put the first argument in R0 and the second in R1-R2 while
	EABI will put the first argument in R0 but the second in R2-R3 and
	R1 will not ne used for argument passing. If you have a function
	that has a <tt>long long</tt>, an <tt>int</tt> and an other
	<tt>long long</tt>, then ELF will put the first argument in R0-R1,
	the second in R2 and the third will be split, one word will be in
	R3 and the other on the stack. EABI will pass the first two arguments
	in R0-R1 and R2, will not use R3 and pass the third argument on the
	stack. Eabi never splits a 64-bit object when passing it to functions.<br>
	EABI's requirement of 64-bit objects always being aligned to 8-byte
	boundaries also means that it must maintain the stackpointer being
	8-byte aligned when a function is called, which could lead to extra
	words allocated on the stack.

- <b>Alignment of structures and unions</b><br>
	ELF always aligns structures and unions to 4-byte boundaries and
	pads them to be a multiple of 4-bytes. EABI aligns and pads structures
	and unions according to the requirements of their members. Thus, if you
	have a struct that has a single <tt>char</tt> member, then ELF will
	align it to 4-bytes and put 3 bytes of padding into it. EABI will not pad
	it and will align it on 1-byte boundary. If you have a structure with a
	<tt>double</tt> and an <tt>int</tt> member, then ELF will not pad the
	structure and align it on a 4-byte boundary, while EABI will introduce
	a pad word and align the structure on an 8-byte boundary.

- <b>Alignment of the stack pointer</b><br>
	ELF expects the stack pointer to be aligned a word boundary and
	natually maintains it by always pushing/poping 32-bit registers.<br>
	EABI expects the stack pointer to be aligned on an 8-byte boundary
	and it maintains it accordingly, occasionaly pushing/popping registers
	for no reason other than keeping it aligned. While the processor itself
	would be happy with a 4-byte aligned stack, some built-in routines of gcc
	would not and if you break the 8-byte stack aligment, then stack-passed
	long longs and doubles will be handled incorrectly at runtime.
	The maintaining of the aligment of the stackpointer to a boundary above
	the natural requirement of the processor does not come for free, it costs
	extra code space, stack space and clock cycles.

- <b>Bitfields</b><br>
	EABI defines bitfield treatment rules, but gcc does not conform to
	them (yet). ELF does not define them at all.

- <b>Support</b><br>
	It seems that ELF is treated as a goner by the gcc developers.
	According to the gcc people a CPU core and software where those alignment
	issues matter are, quote, "badly written code on antique hardware" and
	they couldn't care less about fixing bugs and issues specific to the ELF
	format for ARM. The standard response is "you should use EABI".

*/

