readme

Linux Kernel 2.6.9 for OMAP1710

To add a new board or device, add a new config option to the "OMAP Board Type" 
choice. See examples for the syntax. The config option for boards has to be 
called "MACH_OMAP_yyyy" where yyyy is the board name. Don't forget to add a 
short help.

Note: Kernel 2.6 Kconfig system will automatically expand the configuration 
names with a leading "CONFIG_". So "ARCH_OMAPxxxx" will be expanded to 
"CONFIG_ARCH_OMAPxxxx" and "MACH_OMAP_yyy" will expand to 
"CONFIG_MACH_OMAP_yyyy". In code this can then be used by macros like 
"#ifdef CONFIG_ARCH_OMAPxxxx" and "#ifdef CONFIG_MACH_OMAP_yyyy".

Note: How to handle boards which are compatible or extensions of other boards? 
See MACH_OMAP_H2 for example. The H2 depends on MACH_OMAP_INNOVATOR and expands 
it. This is done by an additional select MACH_OMAP_INNOVATOR in MACH_OMAP_H2
configuration option. With this the whole MACH_OMAP_INNOVATOR configuration is
selected and an additional symbol CONFIG_MACH_OMAP_H2 is available to
distinguish between INNOVATOR and H2 where necessary. 

3a. Only for new processors: Add the ARCH_OMAPxxxx to the correct ARM core in 
arch/arm/mm/Kconfig. E.g. ARCH_OMAP730 in CPU_ARM926T configuration.

3b. Only for new boards: Register the board within ARM Linux machine 
registration system from RMK. For the CONFIG_ section use the same name like 
in arch/arm/mach-omap/Kconfig. E.g. MACH_OMAP_yyyy. For MACH_TYPE_ section use 
OMAP_yyyy where yyyy is the board name like above.

Note: The elements of RMKs machine registration are used in 
arch/arm/tools/mach-types. While kernel compilation
include/asm-arm/mach-types.h is generated automagically from this file. The
content of mach-types.h then is used for machine identification by kernel
bootcode and can be used for board identification.

Note: The ARM Linux machine registration system from RMK can be found under:

www.arm.linux.org.uk/developer/machines/

Note: Only OMAP based boards should be registered to RMKs registration
system. Not processors.

4. Add a processor or board specific header file in include/asm-arm/arch-omap/. 
Use board-yyyy.h with yyyy board name or omapxxxx.h with xxxx processor number.

5. Add a processor or board specific section into include/asm-arm/arch-omap/
hardware.h. Use examples for syntax and use CONFIG_ names as defined in 
arch/arm/mach-omap/Kconfig.

6. Add processor or board specific macros to board-yyyy.h or omapxxxx.h. The
macros to these specific files have to be named OMAPxxxx_ with xxxx processor
number to make them unique.

7a. Only for new boards: Add a file board-yyyy.c with yyyy board name to 
arch/arm/mach-omap/. Put board specific initialization code and resource 
description into this file. The first element of MACHINE_START must be equal to 
MACH_TYPE_ section of machine registration (see arch/arm/tools/mach-types after 
machine registration at RMKs registration system).

Put only code into this file that is board specific and not common. See other 
board files for examples.

7b. Only for new processors: Add processor specific IO description and
iotable_init() to arch/arm/mach-omap/common.c. See examples for the syntax.

If you have introduced new clock definition in 2., add support for this new
clock in include/asm-arm/arch-omap/clocks.h and arch/arm/mach-omap/clocks.c.

8. Only for new boards: Add "obj-$(CONFIG_MACH_OMAP_yyyy) += board-yyyy.o" with 
yyyy board name to arch/arm/mach-omap/Makefile. This is used to compile your new
board specific initialization code from 7a.

9. Check if other of the existing files have to be adjusted for the new 
processor or board. Things to check:

- Pin multiplexing
- GPIO configuration
- Powermanagement
- Clocking
- Interrupt controller and interrupt configuration
- Additional board specific things (e.g. FPGAs)

If other existing files or device drivers have to be changed, use the following 
mechanism for processor specific things:

#ifdef CONFIG_ARCH_OMAPxxxx
 	if (cpu_is_omapxxxx()) {
 		/* Do the OMAPxxxx processor specific magic */
 	}
#endif

Note: cpu_is_omapxxxx() macro is defined in include/asm-arm/arch-omap/hardware.h
and uses OMAP_ID_REG for runtime processor identifcation.

For board differentiation use board macro from include/asm-arm/mach-types.h:

#ifdef CONFIG_MACH_OMAP_yyyy
 	if (machine_is_omap_yyyy()) {
 		/* Do the board specific magic */
 	}
#endif

Note: If technically possible and already implemented the OMAP Linux kernel
has support for a "one binary fits all" machanism. That is, the goal is to be
able to enable support for multiple OMAP processors and/or boards in Kconfig
system. Then it is decided by bootparameters and at runtime on which processor 
and/or board the kernel is actually running on. With this machanism it is 
possible to use the same kernel binary on different OMAP processors or boards 
without recompiling. This is achived by the cpu_is_omapxxxx() and
machine_is_omap_yyyy() macros.

On the other hand, for memory limited embedded systems it should be possible
to compile the kernel with support for only one processor/board combination.
For this a kernel binary is necessary which isn't bloated with code for all
other (unused) processors and boards. This is achived by using the preprocessor
CONFIG_ARCH_OMAPxxxx and CONFIG_MACH_OMAP_yyyy macros around the runtime
cpu_is_omapxxxx() and machine_is_omap_yyyy() selection.

At the moment, the price for this flexibility is a increased number of #ifdef's
throughout the code.

10. Configure the kernel by make menuconfig or make xconfig and select the new 
processor or board.

11. Compile the kernel by an appropriate cross compilation toolchain. Make this
until the code compiles error and warning free. The kernel should also be 
compiled with the various debug checking thingies enabled (e.g.
CONFIG_DEBUG_SPINLOCK,  CONFIG_DEBUG_PAGEALLOC etc.).

/* ToDo: Anything to say about toolchain? */

12. Download the kernel image to the board and test it until it works ;-)

It's not in the scope of this document how to do this (use a appropriate 
bootloader or JTAG download).

Note: The kernel initialization code expects some special values in the
registers R0, R1 and R2 of the ARM processor. These registers have to be
written by bootloader or debugger before starting the kernel. R0 has to be
zero, R1 has to contain the machine number from machine registration in
arch/arm/tools/mach-types. R2 points to the physical address of tagged list
in system RAM. For more information see Documentation/arm/Booting.

While testing a new processor or board configuration, it is recommended to 
enable low level debugging. This uses low level output functions to print kernel
messages on serial line before console is working. Enable it by 

Kernel hacking -> Kernel debugging -> Kernel low-level debugging functions

in kernel configuration system.

13. Check that no other processors or boards are broken by the new code. A first
test is to successful compile the other omap_xxx configurations from 
arch/arm/configs/. Do this by e.g.

cd linux
make omap_innovator_1510_defconfig
Compile the kernel

Even better: Enable support for several processors and boards in Kconfig
system and compile kernel successfully.

14. Only for new boards: Add a new default board configuration to 
arch/arm/configs. Use omap_yyyy_xxxx_defconfig with yyyy boardname and xxxx 
processornumber as filename.

15. If the new code works, compiles without warnings and seems to break no other
configurations, post a patch to [e-mail].

With sending a patch to the community, it is reviewed, can be used and tested by
other users. It then can be included into the public OMAP kernel tree. 

16. Then adapt device drivers or write additional drivers for non-existing 
processor peripherals or board devices. Improve and maintain the code for your 
new processor or board.


4. General guidelines to write clean and OMAP Linux compatible code
-------------------------------------------------------------------

- For register access use the __REG8/16/32() macros. At the moment, see first
example in include/asm-arm/arch-omap/hardware.h.

Allegedly __REG() makes at least some versions of GCC emit tighter code
than the more direct wrappers. Presumably by making it easier to use certain 
addressing modes. 

Make sure that the registers names are clearly marked as being registers
(and not addresses of registers). This has to be done by adding a '_REG'
suffix. E.g.

#define OMAP_ID_REG  (__REG32(0xfffed400))
#define DPLL_CTL_REG (__REG16(0xfffecf00))

__raw_read[bwl] and __raw_write[bwl] are deprecated. They will converted to
__REG8/16/32() syntax, soon. Don't use anything else like own pointer
definitions or in[bwl]/out[bwl] etc., too.

- Make read-modify-write register access preemption save. Use spin_lock() and 
spin_unlock() where necessary. If an IRQ handler can access the registers, 
use spin_lock_irqsave(), too. 

- Functions declared as __init shouldn't have any references after the kernel 
initialization phase is complete. Usually they should be static as well.

- Don't use return statements at end of void functions.

- Use consistent indentation style. Don't use space indentations. Use tab 
indentations.

- In general use Linux formatting style. See Documentation/CodingStyle for more
information. If you use GNU emacs, see also chapter 8 of that document how to
add a linux-c-mode to emacs.


------------------------------------------------------------------
Last modified 13. June 2004
The OMAP Linux Kernel Team
Dirk Behme <[e-mail]>