2 README for ARM based OMAP processor from TI
3 ===========================================
5 This is the README for Linux 2.6 on ARM based TI OMAP processors.
7 In the first section it gives some general hints how to start with OMAP Linux.
9 When successfully build a OMAP Linux kernel with help of first section and no
10 bootloader is already on the board, section 2 gives some tips how to use
11 commercial JTAG tools.
13 In March 2004 the Linux Kernel 2.6 for ARM based TI OMAP processors was cleaned.
14 The goal was to send clean patches to RMK's official ARM tree and to make it
15 easier to add new OMAP processors or boards to the kernel tree. To keep the
16 kernel tree clean now, this document describes also some steps how
17 to add code for a new OMAP processor or OMAP based board to the OMAP Linux 2.6
18 kernel tree. This is what the third section of this document is about.
20 Section 4 of this README reports some rules to be followed to write
21 clean code to make it ready for easy inclusion into public OMAP Linux kernel.
23 For more information also see TI's 'Linux Community for Texas Instruments OMAP
28 There, various downloads and resources can be found (e.g. documentation how
29 to build the kernel, how to use u-boot with OMAP Linux, pre-built tool chain
32 The mailing list for OMAP Linux is hosted there, too:
34 http://linux.omap.com/mailman/listinfo
37 1. General hints how to start with OMAP Linux
38 --------------------------------------------------------------
40 The minimal setup is a arm-linux-gcc cross compiler, make, and some editor.
41 You will also most likely need a JTAG to flash the bootloader for the first
44 The first step is to get a bootloader for your board, u-boot is the
47 http://sourceforge.net/projects/uboot/
49 Then you need to compile it with the same cross compiler as you would use
50 for the Linux kernel. Then you need to flash it to the board either via the
51 serial port, or by using a JTAG.
53 Once you have the bootloader running, you can compile the kernel.
55 You can get the OMAP sources either from the BitKeeper tree, or by
56 applying patches. The BitKeeper tree has the most up to date sources
57 and is the recommended one.
61 You need to download the bk tool from:
63 http://www.bitmover.com/
65 Download the dynamic one (x86-glibc22-linux) instead of the static
66 (x86-static-linux). Some users reported problems with the static version.
68 After bk tool is installed, to learn more about bitkeeper you can follow the
71 http://www.bitkeeper.com/UG/
73 Then you can clone OMAP Linux by:
75 bk clone http://linux-omap.bkbits.net/main
77 Now, you have a copy (clone) of the reprository. To work with it and to
78 compile the kernel you have to check out the files from your local
81 bk -r get (or: bk -r edit)
83 For kernel related BitKeeper information see also kernel documentation in:
85 Documentation/BK-usage/bk-kernel-howto.txt
87 Hint: If you are sitting behind a firewall and have to use a proxy for
88 internet access, you can access BitKeeper by http by setting the
89 http_proxy envirionment variable:
91 http_proxy=http://proxy_username:proxy_password@proxy_name:proxy_port/
93 If you use bash shell, then this might look like:
95 export http_proxy=http://foo:123@abc.host.com:8080/
99 foo: Your user name for the proxy
100 123: Your password for the proxy
101 abc.host.com: The name of your proxy you use for internet access
102 8080: The port used on to access the proxy
107 If you don't want to use BitKeeper, then you can do the same thing with patch.
109 Download the latest OMAP Linux patch from:
111 http://www.muru.com/linux/omap/
113 Get a matching Linux kernel from:
115 ftp://ftp.kernel.org/pub/linux/kernel/v2.6/
117 For example, if you download Linux-2.6.4-omap1 from muru.com, then you need
118 linux-2.6.4 kernel from kernel.org:
120 $ wget ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.4.tar.bz2
121 $ tar xjf linux-2.6.4.tar.bz2
123 $ cat ../Linux-2.6.4-omap1 | patch -p1
125 Note: If OMAP patch from muru.com is against a kernel release candidate,
126 marked by -rcX, then kernel can be found on kernel.org under v2.6/testing/
128 Now, if you have a local kernel tree, either by BitKeeper or by patch, you
129 should look into arch/arm/config/ to see which of the various omap_xxx
130 configurations there you want to use. For example, if you have a OMAP1510
131 based Innovator board, you select omap_innovator_1510_defconfig by
133 $ make omap_innovator_1510_defconfig
135 at top level directory (linux-2.6.4 in the example above).
137 Then you can compile the kernel with
141 Or make Image or make zImage or make uImage.
143 Once you have the kernel compiled, you can upload it to the board via serial
144 port or JTAG (see below).
146 Then you need a root file system either as initrd or on the flash.
148 Once you have the system booting to Linux, you can use pretty much any Linux
149 applications cross compiled for ARM.
153 --------------------------------------------------------------
155 If the flash of your board is really 'empty' and no bootloader is on the board
156 (e.g. u-boot) then you need a JTAG connection. With JTAG you can write
157 a bootloader to board's flash or download OMAP Linux kernel. For OMAP
158 commercial JTAG tools are available, so you have to pay for it.
160 Examples are TI's Code Composer Studio (CCS) or Lauterbach's TRACE32 JTAG.
162 - Linux kernel download with CCS
164 You can use CCS to directly load an ELF file to your board. For example, use
165 arch/arm/boot/compressed/vmlinux. zImage isn't suited because it is not an ELF
166 file. CCS looks for .out files, so copy arch/arm/boot/compressed/vmlinux
167 to vmlinux.out and load it using CCS. Or use the filter *.* to select
168 vmlinux directly. Remember to run arm-linux-strip on ELF file first as CCS
169 get stroppy about unstripped ELF files.
171 If you want vmlinux to be linked to run at a specific address, you can use
172 the CONFIG_ZBOOT options in the kernel build. But first try without
173 CONFIG_ZBOOT as the compressed image should be able to run from address
174 zero (if your CCS .gel files map address zero.)
176 Otherwise, use something like this:
179 CONFIG_ZBOOT_ROM_TEXT=10408000
180 CONFIG_ZBOOT_ROM_BSS=10800000
182 Also note that CCS is pretty useless for debugging Linux as it doesn't
183 properly handle virtual memory. In other words, once the MMU is
184 turned on and Linux is using virtual memory, CCS can no longer
185 properly disassemble, set breakpoints or read memory.
188 - Linux kernel download with Lauterbach TRACE32
193 3. How to add new processor or board to OMAP Linux kernel tree
194 --------------------------------------------------------------
196 It is assumed that the OMAP processor to be added is based on an already
197 supported ARM core (e.g. ARM925 or ARM926). How to add support for new ARM
198 processor core that is not supported by ARM Linux is not scope of this document.
200 1. If a new OMAP processor should be added, identify the ARM core of this
201 processor. E.g. at time of writing this document in March 2004 OMAP730 (ARM926
202 core), OMAP1510 (ARM925 core) and OMAP1610 (ARM926 core) are supported.
204 For a new board or device, identify the OMAP processor on the board. E.g. at
205 time of writing this document in March 2004 four boards are supported:
206 Innovator1510 (OMAP1510 processor), Innovator1610 (OMAP1610 processor),
207 Perseus2 (OMAP730 processor) and H2 (OMAP1610 processor).
209 /* Discussion needed: How to handle the tons of compatible processors?
210 E.g. what to do if OMAP16xx is mainly identical with OMAP16yy? */
212 2. Start with arch/arm/mach-omap/Kconfig and add a new processor or board
215 To add a new processor add a new config option to the "OMAP Core Type" choice.
216 See examples for the syntax. The config option has to be called "ARCH_OMAPxxxx"
217 where xxxx is the number of OMAP processor. Don't forget to select a existing
218 clock frequency or to add a new one in "OMAP Feature Selections" section for
221 To add a new board or device, add a new config option to the "OMAP Board Type"
222 choice. See examples for the syntax. The config option for boards has to be
223 called "MACH_OMAP_yyyy" where yyyy is the board name. Don't forget to add a
226 Note: Kernel 2.6 Kconfig system will automatically expand the configuration
227 names with a leading "CONFIG_". So "ARCH_OMAPxxxx" will be expanded to
228 "CONFIG_ARCH_OMAPxxxx" and "MACH_OMAP_yyy" will expand to
229 "CONFIG_MACH_OMAP_yyyy". In code this can then be used by macros like
230 "#ifdef CONFIG_ARCH_OMAPxxxx" and "#ifdef CONFIG_MACH_OMAP_yyyy".
232 Note: How to handle boards which are compatible or extensions of other boards?
233 See MACH_OMAP_H2 for example. The H2 depends on MACH_OMAP_INNOVATOR and expands
234 it. This is done by an additional select MACH_OMAP_INNOVATOR in MACH_OMAP_H2
235 configuration option. With this the whole MACH_OMAP_INNOVATOR configuration is
236 selected and an additional symbol CONFIG_MACH_OMAP_H2 is available to
237 distinguish between INNOVATOR and H2 where necessary.
239 3a. Only for new processors: Add the ARCH_OMAPxxxx to the correct ARM core in
240 arch/arm/mm/Kconfig. E.g. ARCH_OMAP730 in CPU_ARM926T configuration.
242 3b. Only for new boards: Register the board within ARM Linux machine
243 registration system from RMK. For the CONFIG_ section use the same name like
244 in arch/arm/mach-omap/Kconfig. E.g. MACH_OMAP_yyyy. For MACH_TYPE_ section use
245 OMAP_yyyy where yyyy is the board name like above.
247 Note: The elements of RMKs machine registration are used in
248 arch/arm/tools/mach-types. While kernel compilation
249 include/asm-arm/mach-types.h is generated automagically from this file. The
250 content of mach-types.h then is used for machine identification by kernel
251 bootcode and can be used for board identification.
253 Note: The ARM Linux machine registration system from RMK can be found under:
255 www.arm.linux.org.uk/developer/machines/
257 Note: Only OMAP based boards should be registered to RMKs registration
258 system. Not processors.
260 4. Add a processor or board specific header file in include/asm-arm/arch-omap/.
261 Use board-yyyy.h with yyyy board name or omapxxxx.h with xxxx processor number.
263 5. Add a processor or board specific section into include/asm-arm/arch-omap/
264 hardware.h. Use examples for syntax and use CONFIG_ names as defined in
265 arch/arm/mach-omap/Kconfig.
267 6. Add processor or board specific macros to board-yyyy.h or omapxxxx.h. The
268 macros to these specific files have to be named OMAPxxxx_ with xxxx processor
269 number to make them unique.
271 7a. Only for new boards: Add a file board-yyyy.c with yyyy board name to
272 arch/arm/mach-omap/. Put board specific initialization code and resource
273 description into this file. The first element of MACHINE_START must be equal to
274 MACH_TYPE_ section of machine registration (see arch/arm/tools/mach-types after
275 machine registration at RMKs registration system).
277 Put only code into this file that is board specific and not common. See other
278 board files for examples.
280 7b. Only for new processors: Add processor specific IO description and
281 iotable_init() to arch/arm/mach-omap/common.c. See examples for the syntax.
283 If you have introduced new clock definition in 2., add support for this new
284 clock in include/asm-arm/arch-omap/clocks.h and arch/arm/mach-omap/clocks.c.
286 8. Only for new boards: Add "obj-$(CONFIG_MACH_OMAP_yyyy) += board-yyyy.o" with
287 yyyy board name to arch/arm/mach-omap/Makefile. This is used to compile your new
288 board specific initialization code from 7a.
290 9. Check if other of the existing files have to be adjusted for the new
291 processor or board. Things to check:
297 - Interrupt controller and interrupt configuration
298 - Additional board specific things (e.g. FPGAs)
300 If other existing files or device drivers have to be changed, use the following
301 mechanism for processor specific things:
303 #ifdef CONFIG_ARCH_OMAPxxxx
304 if (cpu_is_omapxxxx()) {
305 /* Do the OMAPxxxx processor specific magic */
309 Note: cpu_is_omapxxxx() macro is defined in include/asm-arm/arch-omap/hardware.h
310 and uses OMAP_ID_REG for runtime processor identifcation.
312 For board differentiation use board macro from include/asm-arm/mach-types.h:
314 #ifdef CONFIG_MACH_OMAP_yyyy
315 if (machine_is_omap_yyyy()) {
316 /* Do the board specific magic */
320 Note: If technically possible and already implemented the OMAP Linux kernel
321 has support for a "one binary fits all" machanism. That is, the goal is to be
322 able to enable support for multiple OMAP processors and/or boards in Kconfig
323 system. Then it is decided by bootparameters and at runtime on which processor
324 and/or board the kernel is actually running on. With this machanism it is
325 possible to use the same kernel binary on different OMAP processors or boards
326 without recompiling. This is achived by the cpu_is_omapxxxx() and
327 machine_is_omap_yyyy() macros.
329 On the other hand, for memory limited embedded systems it should be possible
330 to compile the kernel with support for only one processor/board combination.
331 For this a kernel binary is necessary which isn't bloated with code for all
332 other (unused) processors and boards. This is achived by using the preprocessor
333 CONFIG_ARCH_OMAPxxxx and CONFIG_MACH_OMAP_yyyy macros around the runtime
334 cpu_is_omapxxxx() and machine_is_omap_yyyy() selection.
336 At the moment, the price for this flexibility is a increased number of #ifdef's
339 10. Configure the kernel by make menuconfig or make xconfig and select the new
342 11. Compile the kernel by an appropriate cross compilation toolchain. Make this
343 until the code compiles error and warning free. The kernel should also be
344 compiled with the various debug checking thingies enabled (e.g.
345 CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_PAGEALLOC etc.).
347 /* ToDo: Anything to say about toolchain? */
349 12. Download the kernel image to the board and test it until it works ;-)
351 It's not in the scope of this document how to do this (use a appropriate
352 bootloader or JTAG download).
354 Note: The kernel initialization code expects some special values in the
355 registers R0, R1 and R2 of the ARM processor. These registers have to be
356 written by bootloader or debugger before starting the kernel. R0 has to be
357 zero, R1 has to contain the machine number from machine registration in
358 arch/arm/tools/mach-types. R2 points to the physical address of tagged list
359 in system RAM. For more information see Documentation/arm/Booting.
361 While testing a new processor or board configuration, it is recommended to
362 enable low level debugging. This uses low level output functions to print kernel
363 messages on serial line before console is working. Enable it by
365 Kernel hacking -> Kernel debugging -> Kernel low-level debugging functions
367 in kernel configuration system.
369 13. Check that no other processors or boards are broken by the new code. A first
370 test is to successful compile the other omap_xxx configurations from
371 arch/arm/configs/. Do this by e.g.
374 make omap_innovator_1510_defconfig
377 Even better: Enable support for several processors and boards in Kconfig
378 system and compile kernel successfully.
380 14. Only for new boards: Add a new default board configuration to
381 arch/arm/configs. Use omap_yyyy_xxxx_defconfig with yyyy boardname and xxxx
382 processornumber as filename.
384 15. If the new code works, compiles without warnings and seems to break no other
385 configurations, post a patch to linux-omap-open-source@list.ti.com.
387 With sending a patch to the community, it is reviewed, can be used and tested by
388 other users. It then can be included into the public OMAP kernel tree.
390 16. Then adapt device drivers or write additional drivers for non-existing
391 processor peripherals or board devices. Improve and maintain the code for your
392 new processor or board.
395 4. General guidelines to write clean and OMAP Linux compatible code
396 -------------------------------------------------------------------
398 - For register access use the __REG8/16/32() macros. At the moment, see first
399 example in include/asm-arm/arch-omap/hardware.h.
401 Allegedly __REG() makes at least some versions of GCC emit tighter code
402 than the more direct wrappers. Presumably by making it easier to use certain
405 Make sure that the registers names are clearly marked as being registers
406 (and not addresses of registers). This has to be done by adding a '_REG'
409 #define OMAP_ID_REG (__REG32(0xfffed400))
410 #define DPLL_CTL_REG (__REG16(0xfffecf00))
412 __raw_read[bwl] and __raw_write[bwl] are deprecated. They will converted to
413 __REG8/16/32() syntax, soon. Don't use anything else like own pointer
414 definitions or in[bwl]/out[bwl] etc., too.
416 - Make read-modify-write register access preemption save. Use spin_lock() and
417 spin_unlock() where necessary. If an IRQ handler can access the registers,
418 use spin_lock_irqsave(), too.
420 - Functions declared as __init shouldn't have any references after the kernel
421 initialization phase is complete. Usually they should be static as well.
423 - Don't use return statements at end of void functions.
425 - Use consistent indentation style. Don't use space indentations. Use tab
428 - In general use Linux formatting style. See Documentation/CodingStyle for more
429 information. If you use GNU emacs, see also chapter 8 of that document how to
430 add a linux-c-mode to emacs.
433 ------------------------------------------------------------------
434 Last modified 13. June 2004
435 The OMAP Linux Kernel Team
436 Dirk Behme <dirk.behme@de.bosch.com>