This document provides an overview of porting Linux to a new ARM platform. It discusses setting up the GNU toolchain, kernel prerequisites and configuration, creating machine-specific files and code, initializing drivers and boot options. Key steps include registering the new machine, adding architecture-specific code and configuration files, initializing I/O mapping and IRQs, and creating an initramfs image to test bootability. References for further information on ARM Linux boot sequences and porting are also provided.

1. Linux Porting
for new ARM platform
Champ Yen
http://champyen.blogspot.com
champ.yen@gmail.com

2. OutLine
GNU Toolchain
Linux Kernel Prerequisites and Assumptions
Images
Boot Sequence
Kernel Configuration & Compilation
Kernel Porting
Device Drivers
Boot Options
initramfs vs initrd
References

3. GNU Toolchains
 CodeSourcery gnu toolchain
http://www.codesourcery.com/sgpp/lite/arm/download.html
 Buildroot
http://buildroot.uclibc.org/
 Scratchbox
http://www.scratchbox.org/
 OpenEmbedded
http://wiki.openembedded.net/index.php/Main_Page
 Ptxdist
http://www.pengutronix.de/software/ptxdist/index_en.html

4. GNU Toolchains - buildroot
 linux kernel like configuration interface
ncurse UI, .config file
 uClibc generate linux 2.6 compatible small footprint
applications
 for most platform remember to enable software float
 output: toolchain/uClibc/busybox/rootfs

5. Linux Kernel Prerequisites and Assumptions
 DRAM is initialized
 Hardware-related initialization tasks are done
 MMU/Cache is disabled
 specific values should be saved in registers
r1: Machine ID, r2: pointer of ATAG list (optional)

6. Images and intermediate files
piggy.o
image
vmlinuz objcopy (binary gzip piggy.gz asm
(ELF object) object)
misc.o
compressed head.o
stripped image binary kernel
binary kernel bootable
kernel image
kernel proper (zImage)

7. Boot Sequence
start
arch/arm/boot/ start
compressed/
head.S start_kernel
arch/arm/kernel/
head.S
bootstrap loader init/main.c
(uncompress)
ARM-specific
kernel code
kernel code
detail boot sequence is listed in [9]

8. Kernel Porting – Kernel Memory Map
0xFFFF_FFFF
CPU vector page/copy_user_page(),clear_user_page()
0xFFFF_0000
DMA memory mapping
0xFF00_0000
free for platform use
VMALLOC_END
vmalloc()/ioremap() space
VMALLOC_START
kernel direct-mapped RAM region
PAGE_OFFSET
kernel module space
TASK_SIZE
user space mapping
0x0000_1000
CPU vector page/null pointer trap
0x0000_0000

9. Kernel Porting – Directories
 mm/
memory-handling related code
 boot/
bootstrap loader code
 kernel/
ARM architecture dependent code
 mach-XXXXXX/
specific machine dependent code
 configs/
each machine’s default kernel configurations

10. Kernel Porting – new machine items
refer to other machine to create or modify items(ex: foo, fxx)
 register the new machine
arch/arm/tools/mach-types
 Create machine folder
arch/arm/mach-fxx
arch/arm/mach-fxx/include/mach
 Modify or Create Kconfig & Makefile
arch/arm/Kconfig (usually add config ARCH_FXX for architecture)
arch/arm/Makefile
arch/arm/mm/Kconfig
arch/arm/mach-fxx/Kconfig (config MACH_FOO for machine)
arch/arm/mach-fxx/Makefile
arch/arm/mach-fxx/Makefile.boot (set zreladdr-y for image location)

11. Kernel Porting – new machine items
register the new machine
 Add an entry in arch/arm/tools/mach-types
ex: foo MACH_FOO FOO 65535
 For official registration, should register here, also.
http://www.arm.linux.org.uk/developer/machines/

12. Kernel Porting – new machine items
create machine folders
 arm/arch/mach-fxx
for machine dependent source code
 arm/arm/mach-fxx/include/mach
for machine dependent headers/assembly
debug-macro.S: adduart, senduart, busyuart, waituart
dma.h
entry-macro.S: macro get_irqnr_and_base
hardware.h system.h: arch_idle(), arch_reset()
io.h timex.h: CLOCK_TICK_RATE
irqs.h: NR_IRQS uncompress.h: putc()
memory.h: PHYS_OFFSET vmalloc.h: VMALLOC_END

13. Kernel Porting – new machine items
modify or create Kconfig & Makefile
 arch/arm/Kconfig
config ARCH_FXX
bool “FXX family processors“
help
This enables support for systems based on the fxx processors.
………
source "arch/arm/mach-fxx/Kconfig"
 arch/arm/Makefile
machine-$(CONFIG_ARCH_FXX) := fxx
 arch/arm/mm/Kconfig (ex: ARM926-based)
config CPU_ARM926T
bool "Support ARM926T processor"
depends on ARCH_INTEGRATOR || ARCH_VERSATILE_PB ||
… || ARCH_FXX
default y if ARCH_VERSATILE_PB || ARCH_VERSATILE_AB ||
… || ARCH_FXX

14. Kernel Porting – new machine items
modify or create Kconfig & Makefile
 arch/arm/mach-fxx/Kconfig
menu "FXX platform type“
depends on ARCH_FXX
config MACH_FOO
bool "Support FOO platform"
default y
help
Include support for the FOO platform.
endmenu
 arch/arm/mach-fxx/Makefile
# Common support (must be linked before board specific support)
obj-y := architecture depend code
# Specific board support
obj-$(CONFIG_MACH_FOO) += core.o machine depend code
 arch/arm/mach-fxx/Makefile.boot
zreladdr-y := 0x01008000

15. Kernel Porting – description structure
MACHINE_START(FOO, "FOO processor")
/* Maintainer: Champ Yen */
.map_io = foo_map_io,
.init_irq = foo_init_irq,
.init_machine = foo_init,
.timer = &foo_timer,
/* for ATAG list is optional */
.boot_params = 0x01000100,
MACHINE_END

16. Kernel Porting – Initialization code
 I/O Memory Mapping Table
 IRQ
 Timer
struct sys_timer
 Initial order: .map_io .initrq .timer .init_machine

17. Kernel Porting – I/O Memory Map
static struct map_desc foo_io_desc[] __initdata =
{
{
/* address after mapping */
.virtual = IO_ADDRESS(CPU_DEV_PHY_BASE),
/* page index of physical address */
.pfn = __phys_to_pfn(CPU_DEV_PHY_BASE),
.length = CPU_DEV_IO_LEN, /* address mapping range */
.type = MT_DEVICE /* I/O type */
},
……
};
….
static void __init foo_map_io(void)
{
iotable_init(foo_io_desc, ARRAY_SIZE(foo_io_desc));
}

18. Kernel Porting – IRQ
 arch/arm/mach-fxx/include/mach/entry-macro.S
get_irqnr_and_base: after calling irqnr: irq number, not equal
condition should be set.
 arch/arm/mach-fxx/include/mach/irqs.h
NR_IRQS (number of irq types) should be defined
 struct irq_chip, irqaction
set_irq_chip(), set_irq_flags(), set_irq_handler(), setup_irq()
………
static struct irq_chip foo_irq_chip = {
for(i = o; i < NR_IRQS; i++){
.ack = foo_int_ack,
set_irq_handler(i, handle_level_irq);
.mask = foo_int_mask,
set_irq_chip(i, &foo_irq_chip);
.unmask = foo_int_unmask,
set_irq_flags(i, IRQF_VALID);
};
}
………

19. Kernel Porting - Timer
struct sys_timer foo_timer = {
.init = foo_timer_init,
.offset = foo_gettimeoffset,
};

20. Kernel Porting – DMA memory (optional)
 Influence to dma_alloc_coherent() usage
 In arch/arm/mach-fxx/include/mach/dma.h
 MAX_DMA_ADDRESS
 In arch/arm/mach-fxx/include/mach/memory.h
 CONSISTENT_DMA_SIZE
 ISA_DMA_THRESHOLD

21. Boot Options – static string
 Boot options -> Default kernel command string
ex: mem=8M@0x01000000 initrd=0x01180000,145762

22. Boot Options – ATAG lists
 ATAG provides dynamic boot option passing
 There are two way to pass pointer of ATAG lists
r2 value passed by bootloader, .boot_params in machine descriptor
 refer to arch/arm/include/asm/setup.h
struct tag_header {
__u32 size; ATAG_CORE
__u32 tag;
};
……
struct tag {
struct tag_header hdr;
union {
struct tag_core core;
struct tag_mem32 mem;
…
} u; ATAG_NONE
};

23. Device Drivers
 platform_device_register(), platform_driver_register()
for some on-chip devices(ex: clock/power control)
 UART subsystem in driver/serial
for startup message, console ,and shell
 Framebuffer subsystem in driver/video

24. initramfs vs initrd
initrd initramfs
image ext2 image + gzip cpio + gzip
implementation block device tmpfs
first execution /linuxrc /init
mount rootfs pivot_root switch_root
initrd requires ext2 and block devices support. It adds 150KB+
to kernel size.

25. initramfs
 create an initramfs image by command:
find . | cpio -o -H newc | gzip > ../initramfs.cpio.gz
 take care of the distance between image and kernel,
otherwise image will be overwritten by kernel.
 /init
ex:
#!/bin/busybox sh
#/bin/busybox --install
mount -t proc proc /proc
exec /bin/busybox sh

26. Debug
 decompression: putc() definiition in include/mach/uncompress.h
 kernel debugging features in kernel hacking of kernel options (and
CONFIG_DEBUG_LL option for low level debugging)
 early debug: printascii/printhex(2,4,8) make use of uart macros in
include/mach/debug-macro.S
 printk()
 CONNFIG_KGDB

27. References
 Embedded Linux Primer, Christopher Hallinan, Prentice Hall
 Building Embedded Linux Systems 2/e, Karim Yaghmour, Oreilly
 linux-2.6.2x-xx/Documentation/arm
 http://heaven.branda.to/~thinker/GinGin_CGI.py/get_afile/166/porting_to_arm.pdf
 http://www.glomationinc.com/PortingLinuxKernel.pdf
 http://www.ens-lyon.fr/LIP/Pub/Rapports/RR/RR2006/RR2006-08.pdf
 http://glt08.linuxtage.at/slides/glt08-kvas_linuxonarm.pdf
 http://www.linux-arm.org/LinuxKernel/LinuxNewPlatformPort
 http://gicl.cs.drexel.edu/people/sevy/linux/ARM_Linux_boot_sequence.html
 http://www.simtec.co.uk/products/SWLINUX/files/booting_article.html
 http://www.ibm.com/developerworks/linux/library/l-initrd.html
 http://blog.linux.org.tw/~jserv/archives/001954.html

28. Q&A