readme

Linux Kernel 2.6.9 for OMAP1710

                  README for ARM based OMAP processor from TI
                  ===========================================

This is the README for Linux 2.6 on ARM based TI OMAP processors.

In the first section it gives some general hints how to start with OMAP Linux.
 
When successfully build a OMAP Linux kernel with help of first section and no 
bootloader is already on the board, section 2 gives some tips how to use
commercial JTAG tools. 

In March 2004 the Linux Kernel 2.6 for ARM based TI OMAP processors was cleaned.
The goal was to send clean patches to RMK's official ARM tree and to make it 
easier to add new OMAP processors or boards to the kernel tree. To keep the
kernel tree clean now, this document describes also some steps how 
to add code for a new OMAP processor or OMAP based board to the OMAP Linux 2.6 
kernel tree. This is what the third section of this document is about.

Section 4 of this README reports some rules to be followed to write 
clean code to make it ready for easy inclusion into public OMAP Linux kernel.

For more information also see TI's 'Linux Community for Texas Instruments OMAP
Processors' web page:

http://linux.omap.com

There, various downloads and resources can be found (e.g. documentation how
to build the kernel, how to use u-boot with OMAP Linux, pre-built tool chain
etc.).

The mailing list for OMAP Linux is hosted there, too:

http://linux.omap.com/mailman/listinfo


1. General hints how to start with OMAP Linux
--------------------------------------------------------------

The minimal setup is a arm-linux-gcc cross compiler, make, and some editor.
You will also most likely need a JTAG to flash the bootloader for the first
time.

The first step is to get a bootloader for your board, u-boot is the
recommended one:

http://sourceforge.net/projects/uboot/

Then you need to compile it with the same cross compiler as you would use
for the Linux kernel. Then you need to flash it to the board either via the
serial port, or by using a JTAG.

Once you have the bootloader running, you can compile the kernel.

You can get the OMAP sources either from the BitKeeper tree, or by
applying patches. The BitKeeper tree has the most up to date sources
and is the recommended one.

- Using BitKeeper:
 
You need to download the bk tool from:

http://www.bitmover.com/

Download the dynamic one (x86-glibc22-linux) instead of the static 
(x86-static-linux). Some users reported problems with the static version.

After bk tool is installed, to learn more about bitkeeper you can follow the
tutorial at:

http://www.bitkeeper.com/UG/

Then you can clone OMAP Linux by:

bk clone http://linux-omap.bkbits.net/main

Now, you have a copy (clone) of the reprository. To work with it and to
compile the kernel you have to check out the files from your local 
repository by:

bk -r get (or: bk -r edit)

For kernel related BitKeeper information see also kernel documentation in:

Documentation/BK-usage/bk-kernel-howto.txt

Hint: If you are sitting behind a firewall and have to use a proxy for 
internet access, you can access BitKeeper by http by setting the 
http_proxy envirionment variable:

http_proxy=http://proxy_username:proxy_password@proxy_name:proxy_port/

If you use bash shell, then this might look like:

export http_proxy=http://foo:[e-mail]:8080/

with:

foo: Your user name for the proxy
123: Your password for the proxy
abc.host.com: The name of your proxy you use for internet access
8080: The port used on to access the proxy


- Using Patches:

If you don't want to use BitKeeper, then you can do the same thing with patch.

Download the latest OMAP Linux patch from:

http://www.muru.com/linux/omap/

Get a matching Linux kernel from:

ftp://ftp.kernel.org/pub/linux/kernel/v2.6/

For example, if you download Linux-2.6.4-omap1 from muru.com, then you need
linux-2.6.4 kernel from kernel.org:

$ wget ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.4.tar.bz2
$ tar xjf linux-2.6.4.tar.bz2
$ cd linux-2.6.4
$ cat ../Linux-2.6.4-omap1 | patch -p1

Note: If OMAP patch from muru.com is against a kernel release candidate, 
marked by -rcX, then kernel can be found on kernel.org under v2.6/testing/

Now, if you have a local kernel tree, either by BitKeeper or by patch, you 
should look into arch/arm/config/ to see which of the various omap_xxx
configurations there you want to use. For example, if you have a OMAP1510
based Innovator board, you select omap_innovator_1510_defconfig by 

$ make omap_innovator_1510_defconfig

at top level directory (linux-2.6.4 in the example above).

Then you can compile the kernel with

$ make vmlinux

Or make Image or make zImage or make uImage.

Once you have the kernel compiled, you can upload it to the board via serial
port or JTAG (see below).

Then you need a root file system either as initrd or on the flash.

Once you have the system booting to Linux, you can use pretty much any Linux
applications cross compiled for ARM.


2. JTAG usage
--------------------------------------------------------------

If the flash of your board is really 'empty' and no bootloader is on the board
(e.g. u-boot) then you need a JTAG connection. With JTAG you can write
a bootloader to board's flash or download OMAP Linux kernel. For OMAP
commercial JTAG tools are available, so you have to pay for it.

Examples are TI's Code Composer Studio (CCS) or Lauterbach's TRACE32 JTAG.

- Linux kernel download with CCS

You can use CCS to directly load an ELF file to your board. For example, use  
arch/arm/boot/compressed/vmlinux. zImage isn't suited because it is not an ELF
file. CCS looks for .out files, so copy arch/arm/boot/compressed/vmlinux 
to vmlinux.out and load it using CCS. Or use the filter *.* to select
vmlinux directly. Remember to run arm-linux-strip on ELF file first as CCS 
get stroppy about unstripped ELF files.

If you want vmlinux to be linked to run at a specific address, you can use 
the CONFIG_ZBOOT options in the kernel build. But first try without
CONFIG_ZBOOT as the compressed image should be able to run from address
zero (if your CCS .gel files map address zero.)

Otherwise, use something like this:

CONFIG_ZBOOT_ROM=y
CONFIG_ZBOOT_ROM_TEXT=10408000
CONFIG_ZBOOT_ROM_BSS=10800000

Also note that CCS is pretty useless for debugging Linux as it doesn't
properly handle virtual memory. In other words, once the MMU is
turned on and Linux is using virtual memory, CCS can no longer
properly disassemble, set breakpoints or read memory.


- Linux kernel download with Lauterbach TRACE32

To be done.


3. How to add new processor or board to OMAP Linux kernel tree
--------------------------------------------------------------

It is assumed that the OMAP processor to be added is based on an already 
supported ARM core (e.g. ARM925 or ARM926). How to add support for new ARM 
processor core that is not supported by ARM Linux is not scope of this document.

1. If a new OMAP processor should be added, identify the ARM core of this 
processor. E.g. at time of writing this document in March 2004 OMAP730 (ARM926 
core), OMAP1510 (ARM925 core) and OMAP1610 (ARM926 core) are supported.

For a new board or device, identify the OMAP processor on the board. E.g. at 
time of writing this document in March 2004 four boards are supported: 
Innovator1510 (OMAP1510 processor), Innovator1610 (OMAP1610 processor), 
Perseus2 (OMAP730 processor) and H2 (OMAP1610 processor).

/* Discussion needed: How to handle the tons of compatible processors? 
E.g. what to do if OMAP16xx is mainly identical with OMAP16yy? */

2. Start with arch/arm/mach-omap/Kconfig and add a new processor or board 
option.

To add a new processor add a new config option to the "OMAP Core Type" choice. 
See examples for the syntax. The config option has to be called "ARCH_OMAPxxxx" 
where xxxx is the number of OMAP processor. Don't forget to select a existing
clock frequency or to add a new one in "OMAP Feature Selections" section for
your new processor.