Revision as of 14:37, 3 March 2011

Summary

X-Loader, an initial program loader for Embedded boards based on OMAP processors.

Features and Limitations

Improvements & Modifications

• Malloc/free functionality.
• Mtd framework and onenand support, removed the old onenand drivers.
• Jffs2 support using mtd & onenand support (Read Only).
• Crc32 and zlib.
• Jffs2 zlib compression support (Read Only).
• Dual boot mmc & onenand with mmc highest priority.
• Linux kernel boot directly (Support for 2.6.22 and highest version kernels)
• Linux kernel supported images: vmlinuz, bzImage and zImage.
• Support for loading Linux Ram disk (EXPERIMENTAL)
• "ini" files parser.
• The configuration resides in a plain txt (ini format file).
• Support Windows & Linux formating ini files.
• Boot from mmc, onenand, or mix with mmc highest priority.
• Codeblocks project and compilation rules.
• Support for gcc 4.5.1.
  

Limitations

• The ini configuration file it's limited to max size: 16 KiB
• Kernel Command line parameters it's limited to: 4 KiB
• Malloc it's limited to 32 MiB.
• Cannot write comments in lines with tag=value
  

TODO

• Support for IGEP0030 - Family boards.
• Support for other OMAP/DM/AM processor boards.
• Remove compilation warnings.
• Comments in tag lines
  

STATUS

• Support IGEP0020 Revision B & C family boards.
• Tested with IGEPv2 (DM3730@1Ghz and 512/512 MB Ram/Onenand)
• Tested with IGEPv2 (AM3703@1Ghz and 512/512 MB Ram/Onenand)
• Tested with IGEPv2 (OMAP3530@720Mhz and 512/512 MB Ram/Onenand)
  

Build Procedure

Build with Ubuntu Cross Compiler gcc 4.5.1

EnviromentUbuntu 10.10

Install the cross compiler if you not do it before.

apt-get install cpp-4.5-arm-linux-gnueabi g++-4.5-arm-linux-gnueabi

Setup the board settings

make igep0020-sdcard_config

Build

make

Sign the binary x-loader

You should execute contrib/signGP for sign the xloader.

contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

Build with IGEP SDK

Setup the Enviroment

source /usr/local/poky/eabi-glibc/environment-setup-arm-none-linux-gnueabi

Setup the board settings

make igep0020-sdcard_config

Build

make CROSS_COMPILE=arm-none-linux-gnueabi-

Sign the binary x-loader

You should execute contrib/signGP for sign the xloader.

contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

Build Native

Configure the board settings

make igep0020-sdcard_config

Edit the variable CFLAGS and add the option: -fno-stack-protector
CFLAGS := $(CPPFLAGS) -Wall -Wstrict-prototypes -fno-stack-protector

Build

make CROSS_COMPILE=arm-none-linux-gnueabi-

Sign the binary x-loader

You should execute contrib/signGP for sign the xloader.

contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

BOOT

The IGEP X-Loader must reside in the microSD card or in the OneNand.

MMC Boot

Prepare the microsd card

You can follow this howto about how prepare the microsd card.

Get a new mmc and create two partitions, the first one must be fat and the second one can be formated in any format type supported by linux kernel.

Copy the files in the first (FAT) partition

In the first partition you must copy in this order:

1. x-loader.bin.ift (you must rename this file to MLO) / This is a signed image using contrib/signGP tool
2. x-loader configuration file igep.ini also you can change the configuration file name editing the file: igep0020-sdcard.h (#define IGEP_BOOT_CFG_INI_FILE "igep.ini")
3. Your desired kernel image.

Load Order:

  48 /* Linux Images */
  49 const char* LinuxImageNames [] = {
  50         "kparam"   /* Use kparam first */
  51         "zImage",   /* jffs2 it's case sensitive */
  52         "zimage",   /* fat name it's not case sentitive */
  53         "vmlinuz",
  54         "bzImage",
  55         "bzimage",
  56         0,
  57 };

or you can set the name for your kernel in the configuration file using the tag: kImageName

Don't use a uImage kernel format (from uboot), only standard kernel formats it's supported.

kernel build command example:

$make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- zImage modules

Second Partition

Copy all your rootfs in this second partition.

Also you can use the linaro 10.11 minimal image download the image and untar (as root) in your microsd card second partition.

Remember install the kernel modules in this partition.

Example:

sudo make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- modules_install INSTALL_MOD_PATH=[path to your target rootfs]

OneNand Boot

OneNand Partitions

We suggest use minimum 3 partitions on the OneNand.

MTD partitions on "omap2-onenand":
(a) 0x000000000000-0x000000080000 : "X-Loader"
(b) 0x000000080000-0x000000c80000 : "Boot"
(c) 0x000000c80000-0x000020000000 : "File System"

X-Loader Partition

• Not fs formated (onenand raw)
• Suggested size: 0x80000 (512 KiB)
• The xloader must be signed before copy it into the flash memory.

You should copy the x-loader in the firsts 4 blocks (first 512 KiB), this is not a formated partition due the ROM not permits boot from a formated partition in flash, you should use flash_eraseall and nandwrite for copy x-loader in the first blocks.

<u>Suggested procedure:
</u>
Erase and copy the x-loader into the first flash partition:
$nand_eraseall /dev/mtd0
$nandwrite -p /dev/mtd0 <x-loader>

Sign x-loader:
You should execute contrib/signGP for sign the xloader that resides inside the flash memory.
contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

Due the Onenand 512 MiB has two dies it's necessary split the x-loader and convert it to a 1 die binary.
This is a know OMAP/DM/AM OneNand/Nand boot limitation.

This is the procedure for create the x-loader OneNand binary:
You should execute: (You can use copy paste in your console)
split -b 2K x-load.bin.ift split-
for file in `ls split-a?`; do cat $file >> x-load-ddp.bin.ift; cat $file >> x-load-ddp.bin.ift; done

This last command generate a file named x-load-ddp.bin.ift this is the x-loader for copy it in the OneNand.

 Boot Partition

• fs used jffs2 zlib compressed filesystem.
• Suggested size: 0xC00000 (12 MiB).

X-Loader only support jffs2 partitions for boot partition.

Prepare the boot partition for the first use:

You should follow the same procedure used for copy the x-loader in the first partition.

Suggested procedure:
Erase and copy the x-loader into the first flash partition:
$nand_eraseall /dev/mtd0
$nandwrite -p /dev/mtd0 <your_boot_initial_jffs2_file>


Your initial boot partition can be a empty file the first time.

Next uses:

You can mount the partition over your boot directory in the rootfs

$mount /dev/mtdblck1 /boot

And you can use the cp command for copy your kernel and igep.ini configuration file.

$cp igep.ini /boot

Rootfs Partition

• fs (your prefered fs supported by linux, maybe a good choice it should be ubifs)
• Size, all or you can create more partitions if you wish ...

Boot Priority

XLoader first try load from mmc and if it fails then try from OneNand.

MLO (x-loader), igep.ini, zImage from MMC
If all it's present in the mmc it don't try to boot from Onenand.

MLO (x-loader) in MMC, igep.ini and zImage in Onenand.
If only MLO it's provided this one try to load the other information from the Onenand.

It means that XLoader always try to load the information from MMC and if it fails then try to load from OneNand.

Configuration file: igep.ini

This entry in wikipedia can help you how a ini file it's structured.

The actual XLoader can handle two kind tags:

[kernel] Used for internal XLoader setup.

[kparams] Used for pass the linux kernel parameters.

TAG: [kernel] 

# kaddress (Kernel copy destination address)

kaddress=0x80008000

# rdaddress (RamDisk copy destination address)

<span style="color: rgb(255, 0, 0);"rdaddress=0x84000000</span>

# Serial Hardware ID

serial.low=00000001

serial.high=00000000

# Revision Hardware ID

revision=0001

# Kernel Image Name

<span style="color: rgb(255, 0, 0);"kImageName=zImage-test</span>

# Kernel Ramdisk Name

<span style="color: rgb(255, 0, 0);" />kRdImageName=rdImage-test

4.2 Setup igep.ini file
------------------------
# Note this format permits use the characters
# '#' and ';' as comment check file size restrictions

[kernel]
kaddress=0x80008000
;rdaddress=0x84000000
serial.low=00000001
serial.high=00000000
revision=0001
;kImageName=
;kRdImageName=

[kparams]
console=ttyS2,115200n8
;earlyprintk=serial,ttyS2,115200
mem=512M
boot_delay=0
;mpurate=800
;loglevel=7
omapfb.mode=dvi:1024x768MR-16@60
smsc911x.mac=0xb2,0xb0,0x14,0xb5,0xcd,0xde
;ubi.mtd=2
;root=ubi0:igep0020-rootfs
;rootfstype=ubifs
root=/dev/mmcblk0p2 rw rootwait

Tags Supported
---------------

[kernel] ----
* kaddress=0x80008000

Kernel copy address, you should use the same address used in kernel image
configuration. If you don't know what it means maybe it's better don't change it.

• rdaddress=0x84000000
  Kernel RAM disk copy address.
  If you don't know what it means maybe it's better don't change it.

• serial.low=00000001
  * serial.high=00000000
  Board serial Number, you can read this information using /proc/cpuinfo

• revision=0001
  Board Revision ID, you can read this information using /proc/cpuinfo

• kImageName=zImage
  Kernel file name, if you don't provide this tag it try to load these others:
  // DEFAULT IMAGES
  "zImage"
  "zimage"
  "vmlinuz"
  "bzImage"
  "bzimage"

• kRdImageName=rdimage
  Kernel RAM Disk file, if you don't provide this tag it try to load these others:
  // DEFAULT IMAGES
  "initrd"

[kparams] ----
Kernel parameters, all these parameters are passed directly to the kernel using the
kernel command line.

kernel parameters documentation:
http://www.kernel.org/doc/Documentation/kernel-parameters.txt
http://www.kernel.org/pub/linux/kernel/people/gregkh/lkn/lkn_pdf/ch09.pdf

4.3 Boot Priority
-----------------
First try mmc and if it fails then try from OneNand.

Examples:
a) MLO (x-loader), igep.ini, zImage from MMC
If all it's present in the mmc it don't try to boot from Onenand.

b) MLO (x-loader) in MMC, igep.ini and zImage in Onenand.
If only MLO it's provided this one try to load the other information from
the Onenand.

4.4 OneNand Partition settings
-------------------------------
We suggest use minimum 3 partitions on the OneNand.

Creating 3 MTD partitions on "omap2-onenand":
0x000000000000-0x000000080000 : "X-Loader"
0x000000080000-0x000000c80000 : "Boot"
0x000000c80000-0x000020000000 : "File System"

4.4.1) Xloader partition
* Not fs formated (raw)
* Suggested size: 0x80000 (512 KiB)
* The xloader must be signed before copy it in the flash memory.

You should copy the x-loader in the firsts 4 blocks (first 512 KiB), this is not a
formated partition due the ROM not permits boot from there, you should use tools:
flash_eraseall and nandwrite for copy x-loader in the first blocks.

Suggested procedure:

nand_eraseall /dev/mtd0
nandwrite -p /dev/mtd0 <x-loader>

• Sign x-loader
  You should execute contrib/signGP for sign the xloader that resides inside the flash memory.

contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

Due the Onenand 512 MiB has two dies it's necessary split the x-loader and convert it to a 1 die binary.
This is a know OMAP/DM/AM OneNand/Nand boot limitation.

This is the procedure for create the x-loader OneNand binary:
You should execute: (You can use copy paste in your console)

split -b 2K x-load.bin.ift split-
for file in `ls split-a?`; do cat $file >> x-load-ddp.bin.ift; cat $file >> x-load-ddp.bin.ift; done

This last command generate a file named x-load-ddp.bin.ift this is the x-loader for copy it in the OneNand.

4.4.2 Boot Partition
--------------------
* fs used jffs2 zlib compressed filesystem.
* Suggested size: 0xC00000 (12 MiB)

First time creation:
a) Use the same procedure described in point 4.2.1. Copy your jffs2 compressed image in the
partition, it can be a empty file.

b) Erase the partition and mount it as jffs2 filesystem then you can copy with cp command.

Next Times:
Copy the files using cp command, or edit directly.

when kernel boots you can enable mount this partition over /boot directory for access all boot content.

4.4.3 Rootfs
------------
* fs (your prefered fs supported by linux, maybe a good choice it should be ubifs)
* Size, all or you can create more partitions if you wish ...

5 Build procedure
=================

5.1 Build with Ubuntu Cross Compiler gcc 4.5.1

• This is tested with Ubuntu 10.10

a) Install the cross compiler:
apt-get install cpp-4.5-arm-linux-gnueabi g++-4.5-arm-linux-gnueabi

b) Configure the board
make igep0020-sdcard_config

c) Build
make

d) Sign x-loader
You should execute contrib/signGP for sign the xloader that resides inside the flash memory.
contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

5.2 Build with IGEP SDK

a) Source the enviroment
source /usr/local/poky/eabi-glibc/environment-setup-arm-none-linux-gnueabi

b) Edit the file Makefile
Find the define:

And Set the variable as:
CROSS_COMPILE = arm-none-linux-gnueabi-

b) Configure the board
make igep0020-sdcard_config

c) build
make

d) Sign x-loader
You should execute contrib/signGP for sign the xloader that resides inside the flash memory.
contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

5.3 Build Native

a) Configure the board
make igep0020-sdcard_config

b) Modify the config.mk file
Edit the variable CFLAGS and add the option: -fno-stack-protector

CFLAGS := $(CPPFLAGS) -Wall -Wstrict-prototypes -fno-stack-protector

c) build
make CROSS_COMPILE=""

d) Sign x-loader
You should execute contrib/signGP for sign the xloader that resides inside the flash memory.
contrib/signGP x-load.bin
The signed x-loader it's named: x-load.bin.ift

6 Contribution & Support & Report Bugs
======================================
Contributions to this project be welcome and you can send your patches to support@iseebcn.com
or you can use the igep forum for it.
You can access to IGEP-x-Loader repository using our git at git.igep.es
IGEP IRC Channel: http://webchat.freenode.net/?channels=igep