iPAQ h6300 Linux Porting Tips


(last updated: 17.5.2005)
The hacking with h6300 requires knowledge from the Linux kernel, h6300 hardware. In addition you will need to have prober build environment. After you have these things up, you can start the fun...

http://monologic.net/h6340-pca.jpg

The picture above is from the h6300 motherboard. It has been taken and sent by the P. Boog to the h6300 mailing list in april 2005. The original bigger picture is available at http://monologic.net/h6340-pca.jpg
If you want to build yourself the Wince part of the bootloader, you will need to have the C/C++ compiler for Wince. For building the Linux part of the bootloader, kernel or other linux software you will need to have the C/C++ Linux Arm crosscompiler.

2. Building with OE

For building the rootfs that has gpe or opie X appications within it, the best alternative is to use open embedded build system.
(http://oe.handhelds.org) Note: The location of servers were changed to new ip address in 23.10.2005, so there may be
dns problems for a couple of days.

We have submitted there patches to get h6300 specific gpe-image with h6300 kernel to build. OE includes also some h6300 specific
patches to blueprobe application that is used for autodetecting the bluetooth.

After setting up the monotone environment you can download the monotone database and start buildiong gpe-image.
In addition of monotone and bitbake you will need to have following kind of local.conf that is put in the build/conf/local.conf in oe system.
(edit paths to be suitable for you)

After setting up the oe environment you can start building gpe-image with following simple commands.

    1) Download the distributed database (note this may take 8 even hours in the first time)
        #mt --db=/opt/h6300/oe/oe.db pull monotone.vanille.de "org.openembedded.{oz354fam083,dev}"
    2) Extract the familar 0.8.3 branch from database to org.openembedded.oz354fam083 directory
        #mt --db=/opt/h6300/oe/oe.db co --branch=org.openembedded.oz354fam083
    3) Update database to get daily updates (should only take couple of minutes after initial pull in step 1)
        #mt --db=/opt/h6300/oe/oe.db pull
        #cd org.openembedded.oz354fam083
        #mt update
    4) build gpe-image
        #export PATH=/opt/h6300/oe/bitbake/bin:$PATH
        #export BBPATH=/opt/h6300/oe/build:/opt/h6300/oe/org.openembedded.oz354fam083
        #bitbake gpe-image
       --> Will take quite long time and requires at least 5 giga of hd.
       - Result will be in the tmp/deploy/images directory.
       - ipk files for individual apps will be in tmp/deploy/ipk directory.
       - gcc crosscompiler will be in tmp/cross/bin directory

3. Wince ARM Compilers

Currently there exist two different bootloaders that can be used for booting the Linux from Wince.
The first one is called to "Loadin" and can be compiled with the Microsoft eVC 4.0.

The second bootloader is uboot_loader and that can be build in Linux by using arm-wince-pe gcc crosscompiler.
(You can build build Wince compatible binaries for h6300 in the Linux desktop computer. --> No need to have access
to Windows computer for performing this)

3.1 Microsoft eVC 4.0 compiler

The microsoft eVC 4.0 Compiler can be downloaded from http://www.microsoft.com/downloads/details.aspx?familyid=1DACDB3D-50D1-41B2-A107-FA75AE960856&displaylang=en

Note that the CD key required for installing the C/C++ compiler can be found from the end of the page.

In addition it is recommended that you download the Service Pack 4 from
http://www.microsoft.com/downloads/details.aspx?FamilyID=4a4ed1f4-91d3-4dbe-986e-a812984318e5&displaylang=en

This compiler can be used for building the loadin.exe bootloader from the sources.

3.2 GCC Wince Crosscompiler

The Wince crosscompiler for ARM processors usually called with name arm-wince-pe
There exist couple of different versions with sources and binaries from the internet.
The details for building these are however not easy to found.
This compiler can be used for building the uboot_loader.exe bootloader from the sources.

4 Linux ARM GCC Crosscompilers

For building the Linux part of the bootloader (bootstrap.bin), Linux kernel or Linux software you need to have Linux arm GCC crosscompiler. GCC crosscompilers which are building working in the ARM processor based linux are often called to
arm-linux compilers.

When you want to build the Linux software for the h6300 you can either use the pre-build arm-linux-gcc binaries or build your own crosscompiler compiler toolchain.

Advantages of using existing crosscompiler binaries are:
Advantages of building your own crosscompiler are:

4.1 Installing Binary version of GCC Crosscompiler

Download the arm-wince GCC binaries and extract them as a root to the root of your filesystem.
   
    1) #cd /
    2) #tar -xvzf arm-linux-gcc-3.3.2.tar.bz2

Note that the compiler binaries needs to extracted exactly same directory that has been used as a prefix when building the crosscompiler. If you try to install it to other directory, you will usually encounter build problems or broken binaries.

At least following prebuild H6300 Crosscompiler binaries are available

4.2 Building your own GCC Crosscompiler

It is pretty easy to build your own arm-linux crosscompiler by using crosstools. Note that the build will usually require
about two giga of disk space. Most of the space can be later freed by destroying temporiraly files.

When building the working arm-linux crosscompiler for h6300 you need to make sure that the crosscompiler
will be configured to use arm arch4 architecture compler instruction set.

1) Download and extract crosstool 0.35 from http://kegel.com/crosstool/crosstool-0.35.tar.gz
2) Copy demo-arm-omap1510.sh and arm-omap1510.dat to crosstool directory
     downloads/src/gcc/crosstool/crosstool_build_config__2005_06_23.tar.bz2
3) Edit the demo-arm-omap1510.sh so that your target and cache dirs are ok.

   RESULT_TOP=/opt/h6300/gcc/4.0.0
   export PREFIX=/opt/h6300/gcc/4.0.0
   TARBALLS_DIR=$HOME/downloads/gcc/crosstool/cache

(TARBALLS_DIR is defines the cache location where crosstool downloads and stores the sources requires for building crosscompiler toolchain.

For building gcc 4.0 version of compiler with the glibc 2.3.5 you can use following line in the arm-omap1510.dat file.
   eval `cat arm-omap1510.dat gcc-4.0.0-glibc-2.3.5-hdrs-2.6.11.2.dat` sh all.sh -

4) Unset LD_LIBRARY_PATH with
export LD_LIBRARY_PATH=
otherwise glibc will refuse to build
5) Start building by executing the demo-arm-omap1510.sh

4.3 Usage of GCC Crosscompilers

1) Add crosscompiler's bin directory  to the beginning of the path.

    #export PATH=/usr/local/arm/3.3.2/bin:$PATH

2) Make sure that the application Makefiles you are using uses uses crosscompiler specific compiler names.
"arm-linux-pe-gcc" instead of "gcc", etc. The method how this is done varies from application to application.
Some uses autoconfig for specifying this, some others like kernel build expects certain variables while starting the make.

5. Building Bootloaders

As you are interested in from building the bootloader, you are probaply also interested in to know the overview from it's functionality. After you launch the first of the bootloaders from Wince (loadin.exe) following will happen.

1. Loadin reads the boot options from file, disable MMU, puts the bootoptions to memory and then load second bootloader "bootstrap", and then start bootstrap by jumping to the first location
2. Bootstrap will relocate it self to the end of the memory location and then set up MMU with the liner "One-to-One" mapping and configure interrupt vector
3. Bootstrap will configure video driver and MMC and then scan the MMC for existing FAT partition
4. Bootstrap is ready and to load initrd and kernel images from the FAT partition
5) Bootstap try to boot the kernel with the correct parameters.

5.1 Building Wince Bootloader Loading.exe

1) Install eVC 4.0 and eVC 4.0 SP4 to Windows. (See download instructions above)
2) Extract the sources from the archive h6340/downloads/src/bootloaders/loadin/loadin_src_2005_06_17.tar.bz2
3) Open dos prompt in Windows
4) Build the assembly part of the bootloader by giving command:
    ARMASM -arch 4 start.S
5) Open the eVC project from the sources directory
6) Rebuild project
7) loadin.exe is build to loadin\ARMV4Rel directory

5.2 Building Alternative Wince Bootloader uboot_loader.exe

1) Install arm-wince-pe crosscompiler to Linux
2) Extract the sources from the archive h6340/downloads/src/bootloaders/uboot_load/uboot_load_src_2005_06_17.tar.bz2
3) export arm-wince-pe crosscompilers bin directory beginning of your PATH
4) Verify that the Makefile is correct
5) Execute make command

5.3 Building Second Phase Bootstrap.bin Bootloader

1) Install arm-linux crosscompiler
2) Extract the sources from the archive downloads/src/bootloaders/bootstrap/bootstrap_src_2005_06_17.tar.bz2
    (tar -xvjf bootstrap_src_2005_06_17.tar.bz2)
3) export arm-linux crosscompilers bin directory beginning of your PATH
4) Verify that the Makefile is correct
5) Execute make command
6) bootstrap.bin is rebuild

6 Building Kernel

6.1 About the iPAQ h6300 Kernel Sources

iPAQ h6300 kernel sources are based on the omap-linux kernel sources. Once things are ready we want to merge
the h6300 specific things to mainline kernel via omap-linux kernel. 

6.2 Getting Generic Linux-omap kernel sources

Currently (28.5.2006) the h6300 specific patches are not yet integrated to omap-linux kernel sources or to mainline kernel.
But if you want to checkout the latest omap-linux kernel sources you will need to install git and then use following command

    git-clone git://www.kernel.org/pub/scm/linux/kernel/git/tmlind/linux-omap-2.6.git

OMAP-linux maintainer Tony Lindegren is also releasing snapshots that are available in
   
    http://www.muru.com/linux/omap/

So for example to get the linux-2.6.16-omap2 kernel you would need to do following commands:
  1. wget -c http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.16.tar.bz2
  2. wget -c http://www.muru.com/linux/omap/patches/patch-2.6.16-omap2.bz2
  3. tar -xvjf linux-2.6.16.tar.bz2
  4. bunzip2 patch-2.6.16-omap2.bz2
  5. cd linux-2.6.16
  6. patch -p1 < patch-2.6.16-omap2

6.2 Getting iPAQ h6300 Kernel Sources

If you are interested in getting the latest h6300 kernel sources checkout it by using subversion. (svn)
In subversion we have stable (sometimes a little bit old) version of the kernels in

    svn://fuzzyneural.net/h6300/omap-linux/trunk

while more newer development kernels are usually in directory

    svn://fuzzyneural.net/h6300/omap-linux/branches/h6300_dev

So for getting the latest development kernel. you can use the command

6.3 Building Kernel Sources

1) Install arm-linux crosscompiler
2) Insert MMC card to the MMC card reader and mount the ext2 partition to /mnt/removable1
3) Check out the kernel sources from the subversion repository
    svn co svn://fuzzyneural.net/h6300/omap-linux/branches/h6300_dev
4) export arm-linux crosscompilers bin directory beginning of your PATH
    #export PATH=/usr/local/arm/3.3.2/bin:$PATH
5) Verify that the version information is correct in your <base>/omap-linux/Makefile
    (EXTRAVERSION tag which appears in two different locations)
6) Create separate build directory <path/to>/build_dev
    #mkdir build_dev
7) Copy h6300 specific default config file from the arch/arm/configs/omap_h6300_defconfig to your .config
    #cp h6300_dev/arch/arm/configs/arch/arm/configs/omap_h6300_defconfig build_dev/.config
8) Change to source directory
    #cd h6300_dev
9) Configure kernel options. (.config is already ok in the omap-linux__2005_06_17.tar.bz2)
    #make xconfig O=<path/to/>build_dev ARCH=arm CROSS_COMPILE=arm-linux- oldconfig
10) Save your kernel config changes in xconfig
11) Build kernel
    #make O=<path/to/>build_dev ARCH=arm CROSS_COMPILE=arm-linux-
12) Change to root user for installing kernel to MMC card
    #su
    <password...>
13) Install kernel to MMC card mounted to /mnt/removable1
    #export PATH=/usr/local/arm/3.3.2/bin:$PATH
    #export INSTALL_MOD_PATH=/mnt/removable1
    #make O=<path/to>/build_dev ARCH=arm CROSS_COMPILE=arm-linux- modules_install

7. Helping to Improve the Development

Following are the core locations where exist kernel sources:

Location Description
arch/arm/mach-omap Omap specific core source files
arch/arm/mach-omap/omap1 H6300 init, UART initializations, etc.

7.1 Current Development Status

See http://handhelds.org/moin/moin.cgi/HpIpaqH6315

7.2 USB Network Gadget Driver

This is working and allows us to create TCP/IP link over USB port to the internet. Rootfs initializes this automatically to port 192.168.2.2 and expects Linux Desktop to use port 192.168.2.1 for it's USB Network interface.

7.3 UART Configuration

H6300 has 3 different UARTs. UART1 is used for the bluetooth communication, UART2 is used for the GSM/GPRS AT interface and UART3 is used for the iRDA.

line "static int __initdata h6300_serial_ports[OMAP_MAX_NR_PORTS] = {1, 1, 1};" in the board-h6300.c defines that
all three UART ports must be initialized. The initialization itself is done in the serial.c of the same directory.

Even the UART1, UART2 and UART3 are itself initialized ok, they will only provide the communication route
from userspace to the hardware. The thing needed to do next is to make the drivers that babelfish the communication between UART and hardware communication between each others.

See examples from the functions like omap_write* and omap_read* from the existing drivers.

8. Source Files

Following source file tarballs which has been verified to work are available.

Name/Location Description
svn://fuzzyneural.net/h6300/omap-linux/branches/bt_kernel (2.6.14-rc5)
svn://fuzzyneural.net/h6300/omap-linux/trunk
 Kernel sources, you can find the .config used for building branches/bt_kernel from a file called "defconfig"
svn://fuzzyneural.net/h6300/uboot_load/trunk Sources for the first phase of the bootloader (wince executable)
Can be build with the wince gcc crosscompiler.
svn://fuzzyneural.net/h6300/loadin/trunk Alternative for the uboot_loader. Can be compiled by using eVC 4.0 compiler.

svn://fuzzyneural.net/h6300/bootstrap/trunk
 Source code for the bootstap that which is the second part of the functional bootloader.
downloads/src/gcc/crosstool/crosstool_build_config__2005_06_17.tar.bz2 Patch for the crosstool-0.35 for building arm-linux-pe crosscompiler for h6300.