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://www.denx.de/en/Software/GIT
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 OMAP GIT tree, or by
56 applying patches. The OMAP GIT tree has the most up to date sources
57 and is the recommended one.
59 - Using GIT and cloning OMAP GIT tree please follow the README at:
61 http://www.muru.com/linux/omap/README_OMAP_GIT
63 Hint: If you are sitting behind a firewall and have to use a proxy for
64 internet access, you can access GIT by http by setting the
65 http_proxy envirionment variable:
67 http_proxy=http://proxy_username:proxy_password@proxy_name:proxy_port/
69 If you use bash shell, then this might look like:
71 export http_proxy=http://foo:123@abc.host.com:8080/
75 foo: Your user name for the proxy
76 123: Your password for the proxy
77 abc.host.com: The name of your proxy you use for internet access
78 8080: The port used on to access the proxy
83 If you don't want to use GIT, then you can do the same thing with patch.
85 Download the latest OMAP Linux patch from:
87 http://www.muru.com/linux/omap/
89 Get a matching Linux kernel from:
91 ftp://ftp.kernel.org/pub/linux/kernel/v2.6/
93 For example, if you download Linux-2.6.4-omap1 from muru.com, then you need
94 linux-2.6.4 kernel from kernel.org:
96 $ wget ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.4.tar.bz2
97 $ tar xjf linux-2.6.4.tar.bz2
99 $ cat ../Linux-2.6.4-omap1 | patch -p1
101 Note: If OMAP patch from muru.com is against a kernel release candidate,
102 marked by -rcX, then kernel can be found on kernel.org under v2.6/testing/
104 Now, if you have a local kernel tree, either by GIT or by patch, you
105 should look into arch/arm/configs/ to see which of the various omap_xxx
106 configurations there you want to use. For example, if you have a OMAP1510
107 based Innovator board, you select omap_innovator_1510_defconfig by
109 $ make omap_innovator_1510_defconfig
111 at top level directory (linux-2.6.4 in the example above).
113 Then you can compile the kernel with
117 Or make Image or make zImage or make uImage.
119 Once you have the kernel compiled, you can upload it to the board via serial
120 port or JTAG (see below).
122 Then you need a root file system either as initrd or on the flash.
124 Once you have the system booting to Linux, you can use pretty much any Linux
125 applications cross compiled for ARM.
129 --------------------------------------------------------------
131 If the flash of your board is really 'empty' and no bootloader is on the board
132 (e.g. u-boot) then you need a JTAG connection. With JTAG you can write
133 a bootloader to board's flash or download OMAP Linux kernel. For OMAP
134 commercial JTAG tools are available, so you have to pay for it.
136 Examples are TI's Code Composer Studio (CCS) or Lauterbach's TRACE32 JTAG.
138 - Linux kernel download with CCS
140 You can use CCS to directly load an ELF file to your board. For example, use
141 arch/arm/boot/compressed/vmlinux. zImage isn't suited because it is not an ELF
142 file. CCS looks for .out files, so copy arch/arm/boot/compressed/vmlinux
143 to vmlinux.out and load it using CCS. Or use the filter *.* to select
144 vmlinux directly. Remember to run arm-linux-strip on ELF file first as CCS
145 get stroppy about unstripped ELF files.
147 If you want vmlinux to be linked to run at a specific address, you can use
148 the CONFIG_ZBOOT options in the kernel build. But first try without
149 CONFIG_ZBOOT as the compressed image should be able to run from address
150 zero (if your CCS .gel files map address zero.)
152 Otherwise, use something like this:
155 CONFIG_ZBOOT_ROM_TEXT=10408000
156 CONFIG_ZBOOT_ROM_BSS=10800000
158 Also note that CCS is pretty useless for debugging Linux as it doesn't
159 properly handle virtual memory. In other words, once the MMU is
160 turned on and Linux is using virtual memory, CCS can no longer
161 properly disassemble, set breakpoints or read memory.
164 - Linux kernel download with Lauterbach TRACE32
169 3. How to add new processor or board to OMAP Linux kernel tree
170 --------------------------------------------------------------
172 It is assumed that the OMAP processor to be added is based on an already
173 supported ARM core (e.g. ARM925 or ARM926). How to add support for new ARM
174 processor core that is not supported by ARM Linux is not scope of this document.
176 1. If a new OMAP processor should be added, identify the ARM core of this
177 processor. E.g. at time of writing this document in March 2004 OMAP730 (ARM926
178 core), OMAP1510 (ARM925 core) and OMAP1610 (ARM926 core) are supported.
180 For a new board or device, identify the OMAP processor on the board. E.g. at
181 time of writing this document in March 2004 four boards are supported:
182 Innovator1510 (OMAP1510 processor), Innovator1610 (OMAP1610 processor),
183 Perseus2 (OMAP730 processor) and H2 (OMAP1610 processor).
185 Please refer http://www.muru.com/linux/omap/ to get latest information on the
186 list of boards supported.
188 /* Discussion needed: How to handle the tons of compatible processors?
189 E.g. what to do if OMAP16xx is mainly identical with OMAP16yy? */
191 2. Start with arch/arm/mach-omap[1/2]/Kconfig and add a new processor or board
194 To add a new processor add a new config option to the "OMAP Core Type" choice.
195 See examples for the syntax. The config option has to be called "ARCH_OMAPxxxx"
196 where xxxx is the number of OMAP processor. Don't forget to select a existing
197 clock frequency or to add a new one in "OMAP Feature Selections" section for
200 To add a new board or device, add a new config option to the "OMAP Board Type"
201 choice. See examples for the syntax. The config option for boards has to be
202 called "MACH_OMAP_yyyy" where yyyy is the board name. Don't forget to add a
205 Note: Kernel 2.6 Kconfig system will automatically expand the configuration
206 names with a leading "CONFIG_". So "ARCH_OMAPxxxx" will be expanded to
207 "CONFIG_ARCH_OMAPxxxx" and "MACH_OMAP_yyy" will expand to
208 "CONFIG_MACH_OMAP_yyyy". In code this can then be used by macros like
209 "#ifdef CONFIG_ARCH_OMAPxxxx" and "#ifdef CONFIG_MACH_OMAP_yyyy".
211 Note: How to handle boards which are compatible or extensions of other boards?
212 See MACH_OMAP_H2 for example. The H2 depends on MACH_OMAP_INNOVATOR and expands
213 it. This is done by an additional select MACH_OMAP_INNOVATOR in MACH_OMAP_H2
214 configuration option. With this the whole MACH_OMAP_INNOVATOR configuration is
215 selected and an additional symbol CONFIG_MACH_OMAP_H2 is available to
216 distinguish between INNOVATOR and H2 where necessary.
218 3a. Only for new processors: Add the ARCH_OMAPxxxx to the correct ARM core in
219 arch/arm/mm/Kconfig. E.g. ARCH_OMAP730 in CPU_ARM926T configuration.
221 3b. Only for new boards: Register the board within ARM Linux machine
222 registration system from RMK. For the CONFIG_ section use the same name like
223 in arch/arm/mach-omap[1/2]/Kconfig. E.g. MACH_OMAP_yyyy. For MACH_TYPE_ section use
224 OMAP_yyyy where yyyy is the board name like above.
226 Note: The elements of RMKs machine registration are used in
227 arch/arm/tools/mach-types. While kernel compilation
228 include/asm-arm/mach-types.h is generated automagically from this file. The
229 content of mach-types.h then is used for machine identification by kernel
230 bootcode and can be used for board identification.
232 Note: The ARM Linux machine registration system from RMK can be found under:
234 www.arm.linux.org.uk/developer/machines/
236 Note: Only OMAP based boards should be registered to RMKs registration
237 system. Not processors.
239 4. Add a processor or board specific header file in include/asm-arm/arch-omap/.
240 Use board-yyyy.h with yyyy board name or omapxxxx.h with xxxx processor number.
242 5. Add a processor or board specific section into include/asm-arm/arch-omap/
243 hardware.h. Use examples for syntax and use CONFIG_ names as defined in
244 arch/arm/mach-omap[1/2]/Kconfig.
246 6. Add processor or board specific macros to board-yyyy.h or omapxxxx.h. The
247 macros to these specific files have to be named OMAPxxxx_ with xxxx processor
248 number to make them unique.
250 7a. Only for new boards: Add a file board-yyyy.c with yyyy board name to
251 arch/arm/mach-omap[1/2]/. Put board specific initialization code and resource
252 description into this file. The first element of MACHINE_START must be equal to
253 MACH_TYPE_ section of machine registration (see arch/arm/tools/mach-types after
254 machine registration at RMKs registration system).
256 Put only code into this file that is board specific and not common. See other
257 board files for examples.
259 7b. Only for new processors: Add processor specific IO description and
260 iotable_init() to arch/arm/mach-omap[1/2]/io.c. See examples for the syntax.
262 If you have introduced new clock definition in 2., add support for this new
263 clock in include/asm-arm/arch-omap/clocks.h and arch/arm/mach-omap[1/2]/clocks.c.
265 8. Only for new boards: Add "obj-$(CONFIG_MACH_OMAP_yyyy) += board-yyyy.o" with
266 yyyy board name to arch/arm/mach-omap[1/2]/Makefile. This is used to compile your new
267 board specific initialization code from 7a.
269 9. Check if other of the existing files have to be adjusted for the new
270 processor or board. Things to check:
276 - Interrupt controller and interrupt configuration
277 - Additional board specific things (e.g. FPGAs)
279 If other existing files or device drivers have to be changed, use the following
280 mechanism for processor specific things:
282 #ifdef CONFIG_ARCH_OMAPxxxx
283 if (cpu_is_omapxxxx()) {
284 /* Do the OMAPxxxx processor specific magic */
288 Note: cpu_is_omapxxxx() macro is defined in include/asm-arm/arch-omap/hardware.h
289 and uses OMAP_ID_REG for runtime processor identifcation.
291 For board differentiation use board macro from include/asm-arm/mach-types.h:
293 #ifdef CONFIG_MACH_OMAP_yyyy
294 if (machine_is_omap_yyyy()) {
295 /* Do the board specific magic */
299 Note: If technically possible and already implemented the OMAP Linux kernel
300 has support for a "one binary fits all" machanism. That is, the goal is to be
301 able to enable support for multiple OMAP processors and/or boards in Kconfig
302 system. Then it is decided by bootparameters and at runtime on which processor
303 and/or board the kernel is actually running on. With this machanism it is
304 possible to use the same kernel binary on different OMAP processors or boards
305 without recompiling. This is achived by the cpu_is_omapxxxx() and
306 machine_is_omap_yyyy() macros.
308 On the other hand, for memory limited embedded systems it should be possible
309 to compile the kernel with support for only one processor/board combination.
310 For this a kernel binary is necessary which isn't bloated with code for all
311 other (unused) processors and boards. This is achived by using the preprocessor
312 CONFIG_ARCH_OMAPxxxx and CONFIG_MACH_OMAP_yyyy macros around the runtime
313 cpu_is_omapxxxx() and machine_is_omap_yyyy() selection.
315 At the moment, the price for this flexibility is a increased number of #ifdef's
318 10. Configure the kernel by make menuconfig or make xconfig and select the new
321 11. Compile the kernel by an appropriate cross compilation toolchain. Make this
322 until the code compiles error and warning free. The kernel should also be
323 compiled with the various debug checking thingies enabled (e.g.
324 CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_PAGEALLOC etc.).
326 /* ToDo: Anything to say about toolchain? */
328 12. Download the kernel image to the board and test it until it works ;-)
330 It's not in the scope of this document how to do this (use a appropriate
331 bootloader or JTAG download).
333 Note: The kernel initialization code expects some special values in the
334 registers R0, R1 and R2 of the ARM processor. These registers have to be
335 written by bootloader or debugger before starting the kernel. R0 has to be
336 zero, R1 has to contain the machine number from machine registration in
337 arch/arm/tools/mach-types. R2 points to the physical address of tagged list
338 in system RAM. For more information see Documentation/arm/Booting.
340 While testing a new processor or board configuration, it is recommended to
341 enable low level debugging. This uses low level output functions to print kernel
342 messages on serial line before console is working. Enable it by
344 Kernel hacking -> Kernel debugging -> Kernel low-level debugging functions
346 in kernel configuration system.
348 13. Check that no other processors or boards are broken by the new code. A first
349 test is to successful compile the other omap_xxx configurations from
350 arch/arm/configs/. Do this by e.g.
353 make omap_innovator_1510_defconfig
356 Even better: Enable support for several processors and boards in Kconfig
357 system and compile kernel successfully.
359 14. Only for new boards: Add a new default board configuration to
360 arch/arm/configs. Use omap_yyyy_xxxx_defconfig with yyyy boardname and xxxx
361 processornumber as filename.
363 15. If the new code works, compiles without warnings and seems to break no other
364 configurations, post a patch to linux-omap-open-source@list.ti.com.
366 With sending a patch to the community, it is reviewed, can be used and tested by
367 other users. It then can be included into the public OMAP kernel tree.
369 16. Then adapt device drivers or write additional drivers for non-existing
370 processor peripherals or board devices. Improve and maintain the code for your
371 new processor or board.
374 4. General guidelines to write clean and OMAP Linux compatible code
375 -------------------------------------------------------------------
377 - For register access use the __REG8/16/32() macros. At the moment, see first
378 example in include/asm-arm/arch-omap/hardware.h.
380 Allegedly __REG() makes at least some versions of GCC emit tighter code
381 than the more direct wrappers. Presumably by making it easier to use certain
384 Make sure that the registers names are clearly marked as being registers
385 (and not addresses of registers). This has to be done by adding a '_REG'
388 #define OMAP_ID_REG (__REG32(0xfffed400))
389 #define DPLL_CTL_REG (__REG16(0xfffecf00))
391 __raw_read[bwl] and __raw_write[bwl] are deprecated. They will converted to
392 __REG8/16/32() syntax, soon. Don't use anything else like own pointer
393 definitions or in[bwl]/out[bwl] etc., too.
395 - Make read-modify-write register access preemption save. Use spin_lock() and
396 spin_unlock() where necessary. If an IRQ handler can access the registers,
397 use spin_lock_irqsave(), too.
399 - Functions declared as __init shouldn't have any references after the kernel
400 initialization phase is complete. Usually they should be static as well.
402 - Don't use return statements at end of void functions.
404 - Use consistent indentation style. Don't use space indentations. Use tab
407 - In general use Linux formatting style. See Documentation/CodingStyle for more
408 information. If you use GNU emacs, see also chapter 8 of that document how to
409 add a linux-c-mode to emacs.
412 ------------------------------------------------------------------
413 Last modified 15. March 2006
414 The OMAP Linux Kernel Team
415 Dirk Behme <dirk.behme@de.bosch.com>