C Library Retargeting For ARM Linux
===================================

This example directory contains source code for a library which
retargets the ARM C library to run under ARM Linux.

To build the library, you will need a copy of the Linux kernel
sources (or, more specifically, the Linux kernel include files), and
GNU make. You can build the library linux.a by typing

  make KERNELINC=/path/to/kernel/sources/linux-2.6.6/include

with the value of KERNELINC replaced by the location of your Linux
kernel include files.

Once you have linux.a, you should be able to compile ordinary ANSI C
programs to run as ARM Linux native applications, simply by
including linux.a on the linker command line and supplying the
--sysv parameter. For example, the application "test.c" provided in
this example directory:

  armcc -c test.c
  armlink --sysv -o linuxtest test.o linux.a

If you copy the resulting binary to an ARM Linux system, use "chmod
+x" to make it executable, and run it, you should find that all the
system calls and OS interactions work:

 - stdin, stdout and stderr are correctly directed to file
   descriptors 0, 1 and 2

 - argc and argv are correctly set up to give the argument list
   passed in by exec()

 - the environment is available to getenv(), and also available in
   full if you define main() to take a third argument "char **envp"

 - time() and clock() both work

 - stdio in general works: you can open, close, read and write files

 - rename(), remove() and system() work.

Things that do _not_ work:

 - Full error reporting in errno from any system call, in the manner
   a POSIX application would expect, is not supported. (This would
   require the RVDS <errno.h> to define a full set of Linux error
   numbers.)

 - This example code does not supply Linux system calls as callable
   C functions, or other standard Unix library functions such as
   getcwd(). The code is designed to enable pure ANSI C programs
   compiled using the RVDS C library to run on Linux in the same way
   they would run under semihosting, not to enable general Linux
   applications to be written using RVDS.

 - Linux signal handling is not supported. You can still use the ARM
   signal() implementation to trap the signals generated by the ARM
   C library (SIGFPE, SIGABRT, SIGRTMEM), but it does not connect to
   the Linux OS signals; so if you try to use it to trap (say)
   SIGINT then this will not work.
