# Introduction

The GNUPro® Toolkit for eCos is a complete solution for C and C++ development for the ARM7TM, ARM9TM and StrongARM® processor families, using both the 32-bit ARM® instruction-set and the 16-bit Thumb® instruction-set extensions (where supported by the specific processor).

The tools include the compiler, assembler, linker, and interactive debugger.

This document consists of the following sections:

- Introduction

> An introduction to the features of the GNUPro Toolkit for eCos.

- Reference

> Describes the ARM and Thumb ABIs and attributes of the main GNUPro tools.

- Reducing Code Size on ARM/Thumb processors
- Multi-processor EmbeddedICETM Interface Unit
- CygMon: The Cygnus ROM Monitor
- Bibliography

Note: In addition to this manual, please read Getting started with eCos.

## Tool naming conventions

Cross-development tools in the Cygnus GNUPro Toolkit normally have names that reflect the target processor and the object file format output by the tools (for example, ELF). This makes it possible to install more than one set of tools in the same binary directory, including both native and cross-development tools.

The complete tool name is a three-part hyphenated string. The first part indicates either a 32-bit ARM tool ('`arm`'), or a 16-bit Thumb tool ('`thumb`'). The second part indicates the file format output by the tool ('`elf`'). The third part is the generic tool name ('`gcc`'). For example, the GCC compiler for the ARM is '`arm-elf-gcc`' and the GCC compiler for the Thumb is '`thumb-elf-gcc`'.

The ARM/Thumb package includes one or both of the following supported toolchains. Thumb support is dependent upon chip architecture.

Tool Description | Tool Name
| ARM | Thumb
GCC compiler | `arm-elf-gcc` | `thumb-elf-gcc`
C++ compiler | `arm-elf-g++` | `thumb-elf-g++`
GAS assembler | `arm-elf-as` | `thumb-elf-as`
GLD linker | `arm-elf-ld` | `thumb-elf-ld`
Binary Utilities | `arm-elf-ar` `arm-elf-nm` `arm-elf-objcopy` `arm-elf-objdump` `arm-elf-ranlib` `arm-elf-readelf` `arm-elf-size` `arm-elf-strings` `arm-elf-strip` | `thumb-elf-ar` `thumb-elf-nm` `thumb-elf-objcopy` `thumb-elf-objdump` `thumb-elf-ranlib` `thumb-elf-readelf` `thumb-elf-size` `thumb-elf-strings` `thumb-elf-strip`
GDB debugger | `arm-elf-gdb` | `thumb-elf-gdb`

The binaries for a Windows NT hosted toolchain are installed with an '`.exe`' suffix. However, the '`.exe`' suffix does not need to be specified when running the executable.

## Toolkit features

The following describes features of the GNUPro Toolkit for the ARM.

### Processor version(s)

ARM6, ARM7, ARM8, ARM9, StrongARM and their derivatives.

### Hosts Supported

CPU | Operating System | Vendor
x86 | Redhat 6.x | Redhat
SPARC | Solaris 2.6 | Sun
x86 | Windows NT 4.0 | Microsoft

### Object file format

The ARM tools support the ELF object file format. Refer to Chapter 4, System V Application Binary Interface (Prentice Hall, 1990.). Use '`ld`' (refer to Using LD in GNUPro Utilities ) or '`objcopy`' (refer to The GNU Binary Utilities in GNUPro Utilities ) to produce S-records.

### Special features

Installation and usage instructions have been included for the Multi-processor EmbeddedICETM Interface Unit (In Circuit Emulator).

## GNUPro on Windows NT

### Windows environment settings

The Windows NT hosted toolchain requires the following environmental settings to function properly. Assuming the release is installed in: C:\cygnus\gnupro\i686-cygwin32\arm-elf\<release>

> SET PROOT=C:\cygnus\gnupro\i686-cygwin32\arm-elf\<release>
> SET PATH=%PROOT%\H-i686-cygwin32\bin;%PATH%
> SET INFOPATH=%PROOT%\info
> REM Set TMPDIR to point to a ramdisk if you have one
> SET TMPDIR=C:\TEMP

> Note: The variable '<release>' indicates the release directory name found on the CD.

A working environment can be established by using the following shortcut from the Windows Start menu:

> Programs->Cygnus eCos->eCos Development Environment

This will bring up a window running "bash", and your Windows environment will be automatically set up.

### Rebuilding from source

If you wish to rebuild the tools from the source code, see the section Rebuilding the GNUPro tools from source ,

### Case Sensitivity

The following strings are case sensitive under Windows NT:

- command line options
- assembler labels
- linker script commands
- section names
- file names within makefiles

The following strings are not case sensitive under Windows NT:

- gdb commands
- assembler instructions and register names

Case sensitivity for Windows NT is dependent on system configuration. By default, file names under Windows NT are not case sensitive.

## GNUPro on Solaris/Redhat Linux

In the following examples two variables have been used. The variable '<version>' should be replaced with the directory name that the installer made when the GNUPro tools were installed (or eCos was installed). For example, something like `'ecos-99r1-991015`' or '`gnupro-99r1p1`'. The variable '<host>' should be replaced with the "host triplet" of your build system. You can determine the host triplet by running the script '`config.guess`' at the top of the source tree. Typical examples include '`i686-cygwin32`', '`i686-pc-linux-gnu`' or '`sparc-sun-solaris2.6`'.

### eCos Developer's Kit users

The eCos Developer's Kit is supplied with tested prebuilt development tools for this host and target. By default, the installation script supplied in the tools distribution will install the tools in

> /usr/cygnus/<version>/H-<host>/bin.

### Sourceware distribution users

The GNUPro Tools for Sourceware users are supplied in a ZIP format file. Detailed instructions for installation can be found on the eCos sourceware site:

> http://sourceware.cygnus.com/ecos/

By following the instructions there, you should have the sources installed in:

> /usr/cygnus/<version>/src

and the tools built in:

> /usr/cygnus/<version>/H-<host>/bin

### Unix environment settings

After the tools have been built (if applicable) and installed, we recommend you have the following settings in your appropriate shell startup script, assuming the tools were installed in '/usr/cygnus/<version>'.

For Bourne shell compatible shells:

> PROOT=/usr/cygnus/<version>
> PATH=$PROOT/H-<host>/bin:$PATH
> INFOPATH=$PROOT/info:${INFOPATH-/usr/local/info:/usr/info}
> MANPATH=$PROOT/man:${MANPATH-/usr/local/man:/usr/man}
> export PATH INFOPATH MANPATH

For C-shell compatible shells:

> setenv PROOT /usr/cygnus/<version>
> if ( "$?MANPATH" == "0" ) then
> setenv MANPATH "/usr/local/man:/usr/man"
> endif
> if ( "$?INFOPATH" == "0" ) then
> setenv INFOPATH "/usr/local/info:/usr/info"
> endif
> setenv MANPATH $PROOT/man:$MANPATH
> setenv INFOPATH $PROOT/info:$INFOPATH
> set path = ( $PROOT/H-<host>/bin $path )

## Rebuilding the GNUPro tools from source

This section outlines the steps to rebuild the GNUPro tools from source code.

In the following examples two variables have been used. The variable '<version>' should be replaced with the directory name that the installer made when the GNUPro tools were installed (or eCos was installed). For example, something like `'ecos-99r1-991015`' or '`gnupro-99r1p1`'. The variable '<host>' should be replaced with the "host triplet" of your build system. You can determine the host triplet by running the script '`config.guess`' at the top of the source tree. Typical examples include '`i686-cygwin32`', '`i686-pc-linux-gnu`' or '`sparc-sun-solaris2.6`'.

If you wish to rebuild the tools from the sources, then assuming the sources have been installed into '/usr/cygnus/<version>/src', the steps to take are as follows:

1. On Windows hosts, you must start a Cygwin bash shell. Customers with the eCos Developer's Kit can invoke a bash shell using the following shortcut:

> Start->Programs->Cygnus eCos->eCos Development Environment

2. You must have a native GNU compiler ('`gcc`') installed on your system.

> On Windows hosts this will be part of your Cygwin tools installation.

> On Unix hosts, if you have not been provided with a native GNU compiler, you will need to build one from the sources provided. You can do this by following these instructions but omitting the '`--target`' parameter in step 4, and altering step 5 to:

> > make -w all-gcc install LANGUAGES=c > make.out 2>&1

Warning: If you have '`.`' in your PATH environment variable, make sure that it comes after the GNU native compiler tools directory. The following build procedure will fail if '`.`' is ahead of the GNU native compiler tools in the path.

3. Create an object directory for your builds:

> mkdir /tmp/build
> cd /tmp/build

4. Configure the tools, saving the output to configure.out. Users of the '`csh`' and '`tcsh`' shells should replace
'`> filename.out 2>&1`' with '`>& filename.out`' throughout:

> /usr/cygnus/<version>/src/configure -v \
> --prefix=INSTALLDIR \
> --exec-prefix=INSTALLDIR/H-<host> \
> --target=TARGET > configure.out 2>&1

> 'INSTALLDIR' is the installation directory into which the tools should be installed. If the old tools were to be replaced completely, this could be set to '/usr/cygnus/<version>', although if this is done we strongly recommend moving the old tools to a safe place beforehand.

> 'TARGET' is the "target triplet" you are compiling for. This is the same as the tool name prefix given in the earlier section Tool naming conventions.

5. Build and install the tools, saving the output to make.out:

> > make -w all install LANGUAGES="c c++" > make.out 2>&1