Title: README for K-Product Cross-Compiler 
Author: Olivier Carmona
Last Revision: 22/02/01

All K-Products are based on the Motorola MC683XX family. The following package 
provides a complete cross compiler chain for three software environments.
This package also provides a freeware C library (newlib) as well as 
the necessary glue for the appropriate K-Product hardware. All K-Products
share a common operating system: the K-Team Operating System (KOS). KOS is
a modular operating system with a scheduler that features a 5 ms time 
resolution. There is no priority or aging. The particularity of KOS
is that it is based on place-independent modules. All modules are loaded at 
startup and only need to know the base address.

For Windows users: you can also use KTProject, a simple Graphical Interface
to the cross compiler using a common freeware Integrated Development Environment
(Source Navigator).
ftp://koala1.k-team.com/pub/outgoing/KTProject.exe


INSTALLATION 
------------

First, you should download the latest distribution of the kros compiler for 
your machine at the following address:

ftp://koala1.k-team.com/pub/outgoing/kros-xxx-xxx-xxx.tgz

Choose kros-xxx-xxx-xxx.tgz according to your environment:
- i686-pc-cygwin: for Win32 environment, i.e., Windows 95/98/NT (needs Cygwin)
- i686-pc-linux-gnu21: for Linux Environment (needs glibc 2.1)
- sparc-sun-solaris25: for Solaris (should work on any version of Solaris)

To install the cross-compiler for the K-Products (Khepera, Koala or Kameleon),
you just need to uncompress it to an approriate directory.

MACHINE SPECIFIC REQUIREMENTS
-----------------------------


For Linux:

You need Glibc 2.1
You need GNU Make Version > 3.77.

You need to add this to the canonical makefile (described above):
LD_LIBRARY_PATH := ${LD_LIBRARY_PATH}:${prefix}lib


For Windows NT/95/98:

You need to modify cygwion.bat to set correctly the following line:
SET PATH=".;c:\path\to\cygwin;%PATH%"
according to the place where cygwin directory is. To use the environment
launch cygwin.bat and use the make command as in a standard Unix development
environment.

You can find more information on cygwin at:
http://sources.redhat.com/cygwin/ 


For Sun Solaris:

You need GNU Make Version > 3.77.

You need to add to the canonical makefile (described above):
LD_LIBRARY_PATH := ${LD_LIBRARY_PATH}:${prefix}lib

USE
---

The root tree contains:

kros-xxx-xxx-xxx: contains gcc and binary utilities.
khepackxxx: contains package for Khepera.
koapackxxx: contains package for Koala.
rebpackxxx: contains package for Kameleon with or without REB extension.
kteam: contains files shared by the different packs. 
cygwin (only cygwin version): basic cygwin configuration.

All the hardware packages (xxxpackxxx) contain:
/etc: linker scripts for different configurations (do not edit).
/examples: a set of examples to demonstrate the use of your hardware.
/include: include files specific to the hardware (do not edit).
/lib: library files specific to the hardware (do not edit).

The examples directory contains a canonical makefile (Makefile), a canonical 
advanced makefile (Makefile_Advanced), and many directories within containing
simple self-explanatory C files. 

Here we will only describe the canonical makefile (as you do not need to touch
the advanced makefile):

-prefix: You must set this variable to the full path of /kros-xxx-xxx-xxx.
-sft_pack: You must set this variable to the full path of /kteam.
-hdw_pack: You must set this variable to the full path of /xxxpackxxx.
-port: unneeded (variable for KTProject environment).
-speed: unneeded (variable for KTProject environment).

If you prefer, you may separate the source, object, and binary files as
follows (DO NOT forget the / at the end):
-srcdir  = ./
-asmdir = ./
-includedir = ./
-objdir = ./
-libdir = ./
-bindir = ./

Please do not modify the following:
-include $(sft_pack)etc/Makefile

The following are automatically created variables.  They only work in a flat 
configuration (binary, source in the same directory) and with ONLY ONE C FILE:
-OBJ = $(addsuffix .o,$(basename $(shell ls -I *.c *.s *.S *.cc 2>null)))
-INC = $(addsuffix .o,$(basename $(shell ls -I *.h 2>null)))
-EXE = $(addsuffix .s37,$(basename $(shell grep -wl main *.c *.s *.S *.cc 2>null)))

The following dependency rules are the base of the makefile:
-all: $(EXE)
-        @echo Compilation done
-        @rm null
-
-$(EXE): $(OBJ)
-
-clean:
-        @echo Cleaning...
-        @rm $(EXE)

Hence if you are in a simple configuration, that is to say: a flat tree
(binary, source in the same directory) and ONLY ONE C FILE, you just need to
type make.
 
Frequently Asked Questions
--------------------------

Q - How do I write C code?

A - The C/C++ uses the newlib library. A description of all the C
functions can be obtained at the following address :

http://www.cygnus.com/pubs/gnupro/4_libs/a_GNUPro_C_Library/libc.html

A description of all the Mathematical functions is at the following
address :

http://www.cygnus.com/pubs/gnupro/4_libs/b_GNUPro_Math_Library/libm.html

If you want to use the K-TEAM Operating System commands, you need to
include:

#include  <sys/kos.h>

The C Application Interface for Kros is described in your BIOS manual.

If you use printf, do not forget to write "\r\n" instead
of "\n". In previous version of the compiler, you needed to use RESERVE_COM before
printf and RELEASE_COM after. This is no longer needed with the current version.

Q - How do I write in Assembler?

A - You can write your code in Motorola Assembler (please consult GAS
documentation). Here is an example:

 /*  Atan(x) look-up table  module */
 /*  ================================= */

.globl atan_lkup1,atan_lkup2

atan_lkup1:
        movem.l                 d2/a2,-(a7)
        move.l                  12(a7),d2
        move.l                  aTabAtan1,a2
        tblu.l                  (a2),d2
        move.l                  d2,d0
        movem.l                 (a7)+,d2/a2
        rts

atan_lkup2:
        movem.l                 d2/a2,-(a7)
        move.l                  12(a7),d2
        move.l                  aTabAtan2,a2
        tblu.l                  (a2),d2
        move.l                  d2,d0
        movem.l                 (a7)+,d2/a2
        rts

        .include "source/atana.i"

where atan_lkup1 can be called from within C with the following convention:

long atan_lkup1 (unsigned int);

Another solution for writing assembler, is to do it directly in your C code:

/* Fixed Point Multiplication in the Range [256,-256] on 32 bts (Signed 9.22) */
asm(".globl mul256");
asm("mul256:");
asm("movem.l d1-d2,-(a7)");
asm("move.l  12(a7),d0");
asm("move.l  16(a7),d1");
asm("muls.l             d0,d2:d1");
asm("asl.l        #8,d2");
asm("asl.l        #1,d2");
asm("rol.l   #8,d1");
asm("rol.l   #1,d1");
asm("and.l                      #0x000001FF,d1");
asm("or.l    d2,d1");
asm("move.l             d1,d0");
asm("movem.l (a7)+,d1-d2");

Q - How do I compile a C / C++ / Assembler file into a
  downloadable file or a ROM-able file for the Khepera or Koala or any
  other K-TEAM products?}

A - TODO

Q - How do I debug the program using the serial line?

A - You should use printf statements and take care that the printf operation is
longer than any other standard operation.

Q - I want to compile by myself without implicit rules

A - If your filename is $(src_dir)/foobar.c type:
    make $(bin_dir)/foobar.s37

Q - How do I compile many C files?

A - If you have many C files, you should modify the canonical makefile.
    First suppress all the existing rules (starting from "all: $(EXE)").
    Second, for a program foobar.o based on foobar.c, foo.c, and bar.c, type:

    all: foobar.S37

    foobar.S37: foobar.c foo.o bar.o
   
    foo.o: foo.c foo.h

    bar.o: bar.c bar.o

    Please take to always leave a blank line after each rule.

Q - I want to debug the assembler produced by the compiler: how
  can I read the resulting assembler code?

A - If you want only to read only your own code in assembler type:
    make $(src_dir)/foobar.s
    
    If you want to read the final code sent to the Khepera type:
    make $(src_dir)/foobar.lst 

Q - What is tim_install_task or bios_restart?

A - These functions are part of the K-TEAM Operating System.  You
need to read the K-TEAM documentation provided with your device (see
also http://www.k-team.com/download ).

Q - I do not understand how the Makefile works, is there another way?

A - No, but Makefiles for KrOS are very easy to use. You can find
information on makefiles in the GNU Makefile documentation for
instance at the following address :

http://www.cygnus.com/pubs/gnupro/5\_ut/d\_UsingMake/make.html
 
Q - No matter what I compile, I get the following message :

m68k-none-kos-gcc: file path prefix 
`/home/egcs/b-sparc-sun-solaris2-x-m68k-kos/lib/gcc-lib/m68k-none-kos/egcs-2.90.27/'
never used

A - This warning message means that you are not using the compiler
builtin path, i.e. the one declared during the compilation of the
compiler, : THIS IS NOT HARMFUL.


Q - How do I build a cross-compiler?

If K-Team does not support your cross-compiler, you will have to
install the cross-compiler on your machine yourself. You need to have the
standard public domain GNU C compiler package and your machine must be
supported by GNU. The GNU sub-packages that you need are
binutils2.9.1.tar.gz (or later version) and gcc2.95.2.tar.gz (or later
version).

If you do not have these GNU packages, you can obtain them on 
  http://sourceware.cygnus.com/gcc/ and 
  http://sourceware.cygnus.com/binutils/ . If you do not have access
to the Internet, please contact your distributor. To know if your machine
is supported, read the INSTALL file of the GNU package.

To start, follow these instructions:
- Create a directory in which you will install the cross-compiler.
  This directory needs roughly 200 MegaBytes. In this document we will refer
  to this directory as /path/to/kros. Every time that you see /path/to/kros,
  please replace it with the path of your directory.
- Unpack the corresponding hardware package (khepack5.tgz for example)
  to /path/to/kros/.
- Uncompress binutilsXXX.tar.gz and gccXXX.tar.gz to this directory.
  
To compile the binary utilities (mainly the assembler and the linker):
- Go to the binutilsXXX directory:
   cd /path/to/kros/binutilsXXX}.
- ./configure --target=m68k-none-elf --prefix=/path/to/kros
  If the configure script can't determine your type of computer, give
  it the name as an argument, for instance: 
  ./configure --target=m68k-none-aout --host=sparc-sun-sunos4.1.3
    --prefix=/path/to/kros
  The host option consists of a triplet including processor, company
  and OS, like sparc-sun-sunos4.1.3 (read point 3 and the section
  "Configurations Supported by GNU CC" in the file INSTALL in the
  directory gccXXX).
-  make install

To compile the cross-compiler:
- Go to the gccXXX directory.
- ./configure --target=m68k-none-aout --prefix=/path/to/kros
  Similarly, if the configure script can't determine your type of
  computer, give it the name as an argument, as described in the previous point.
- 'cp -r ../khepack5/include ../m68k-none-elf/include'
- make LANGUAGES=''c c++'' all
- make LANGUAGES=''c c++'' install

If everything works fine, you have now a working version of the
cross-compiler. If you have problems during these compilations, please
consult http://www.objsw.com/CrossGCC and 
http://sourceware.cygnus.com/ml/crossgcc/.

Q - My old khepera package does not work with my gcc compiled version.

The old package used the AOUT binary format and KrOS uses the ELF format. 
Compatibility is not ensured.


Known Bugs:
----------

C++ does not work properly.

