Chris Jones

chris@black-sun.co.uk

2002, 2003 Chris Jones Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no invariant sections, with no Front-Cover Texts or Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". Version: 0.6 $Header: /cvs/intimate/docs/install-howto.sgml,v 1.6 2003/06/24 11:58:35 cmsj Exp $ Installation and configuration of Intimate Linux on a Compaq iPAQ handheld PC. This is a very new install process and has not seen a great deal of testing yet. We would welcome any feedback you have, but please don't be too disappointed if it doesn't work, there are probably some bugs still to iron out! The Compaq iPAQ is a highly versatile handheld PC that features a 240x320 colour LCD screen and a vast array of peripherals, thanks to Compact Flash and PCMCIA expansion jackets. This guide attempts to simplify the process of installing Intimate onto an iPAQ, however, further work needs to be done to automate the process, probably through use of scripting. Since the original Intimate installer was written, significant development has taken place on bootldr, the program used to boot Linux on the iPAQ. These developments include recognising some of the iPAQ expansion sleeves (e.g. the Compact Flash and PCMCIA sleeves), reading from IDE devices and the ability to read MS-DOS formatted partitions. It is also now capable of booting PocketPC, making it entirely possible to have a dual-boot system, with either PocketPC or Familiar Linux in flash memory, and an OS such as Intimate Linux on an external storage device. It is this dual-boot ability that we will be taking advantage of. The boot process for Intimate loads a kernel image and an 'initial ram disk' (or 'initrd') from an MS-DOS formatted partition and then executes the kernel. The initrd (a gzipped cramfs image) is then mounted and provides a small selection of programs required to mount the main Intimate disk partition and start it booting. While this is not necessarily the cleanest way to boot an operating system, it does mean that none of the precious flash is used, so you can install another OS there, be it Familiar Linux or PocketPC. To limit the size of this document, several assumptions are made - you MUST meet these before beginning any of the tasks described here. Failure to do so is very unlikely to cause any damage, but it might lead to data loss as it involves formatting certain devices. You have a Compaq iPAQ. Currently the 36xx models are best supported, and 38xx models should now be supported. You have installed bootldr 2.18.54. If you have a previous version of bootldr installed, upgrade instructions can be found here (only the "Installing the Bootldr" section). If you have not yet installed any version of bootldr, installation instructions can be found here. We have found that newer versions of bootldr (e.g. 2.19.x and 2.20.x) have some issues booting our initrd's. Investigations are ongoing. You have some kind of storage device on which to install Intimate. Intimate will not fit in the 16MB/32MB Flash ROM in a typical iPAQ, you will need an external storage device of some kind. This could either be a large Compact Flash device, such as an IBM Microdrive, or a PCMCIA IDE hard disk. These devices are typically available in anything up to 5GB sizes. Your storage device is partitioned as follows: Primary Partition 1: 10MB FAT16 Primary Partition 2: ext3 (the ext3 partition should fill whatever space is left after addition of the FAT16 partition. A typical Intimate install will need this partition to be around 300MB) Both partitions should be pre-formatted. You can do this either with another machine (e.g. a laptop or other machine with pcmcia slots) or from the iPAQ itself if you have Familiar Linux installed. Whatever system you are using, once you have partitioned the device (using fdisk, parted, etc.), you can use the command mkdosfs /dev/discs/discX/part1 to make the FAT16 partition and mkfs.ext3 -j /dev/discs/discX/part2 for the ext3 partition (you should replace the block device '/dev/discs/discX/' with the correct path to the block device that represents your storage device). If you are performing these tasks from within Familiar, you will need to install the mkfs commands, which are in the e2fsprogs ipk (e.g. ipkg install e2fsprogs). For now, yes. ext3is more widely accessible than reiserfs, which in our view makes it more useful for a device like an iPAQ. It is also very important that you create ext3's journal inodes on the partition. Passing "-j" to mkfs.ext3 (as above) will do this automatically, or, if you want to do it seperately, tune2fs -j /dev/discs/discX/part2 will do the trick As of time of writing, some of the Intimate packages are out of date. Efforts are being made to update these. Contributions are very welcome! Before installation can take place, you will need to perform a few tasks on your freshly formatted storage partitions. Either from Familiar, or a laptop, mount the MS-DOS partition (e.g. mount /dev/discs/disc0/part1 /mnt/vfat -tmsdos) and change directory to the mounted partition (e.g. cd /mnt/vfat). Create a directory called 'boot' and change directory to it. It is this directory that bootldr will examine to find the kernel image and initrd. Download the following files into the 'boot' directory: The kernel image, zimage On a typical Linux system, the kernel file would be called 'zImage', however, bootldr does not currently understand uppercase letters, so the Intimate kernel file is called 'zimage'. The initrd image, initrd A bootldr configuration file, params. This file tells bootldr to use the zimage and initrd listed above. Unmount the DOS partition. Reboot your iPAQ, insert the storage device and from the bootldr screen, choose the "Boot VFAT HDD/CF" option (normally mapped to the 'Q' button). If you have a serial console connected to the iPAQ you should now see a series of messages scrolling past that indicate the kernel is booting. During the boot sequence of the initrd, it checks for the intimate partition and if it finds that it is empty, it will load a minimal XFree86 based environment, giving you a shell and an on-screen keyboard (see Figure 1). The initrd image is mounted read-only on boot, so you will not be able to make any changes to the system once it has booted. To do this you will need to create a new initrd, but fortunately that process is very simple and is documented in Appendix A. At this point you will need to connect your iPAQ to some kind of network, be it Ethernet, Wireless or USBnet - the installation process needs to download packages from the Internet. If you are using a PCMCIA card for network access, it should ideally be a card that is supported by the standard PCMCIA drivers as they are included in the initrd. However, cardmgr is not running as a daemon after the initrd boots, so you will need to insert the card before booting the initrd, or if you insert it after booting, you will need to run cardmgr manually (the command cardmgr -o will do this). Once the card's driver is loaded, you can use standard tools such as ifconfig to configure the interface, although ideally you should install a DHCP server on a seperate machine to configure the iPAQ's network connection automatically. If your chosen method of connecting it to the internet isn't supported by the initrd (ie it doesn't work), let us know, we will try to help get it working. While is is entirely possible to run the following commands/files via the terminal/keyboard onscreen, it is considerably easier to use a serial cable if you have one (the serial console is set to run as 115200 8N1 with no flow control). Run the command intimate-install - the script will mount your Intimate partition and begin downloading the base packages. It will then attempt to perform some minor configuration tasks on the partition and then go into a second stage install which downloads useful packages like an X server from the Intimate feed. When the install has completed, reboot your iPAQ, again selecting the HDD bootldr option. This time, instead of booting to the X/terminal/keyboard setup you saw previously, Intimate should boot to an X server and run a window manager and terminal. You should now have Intimate completely installed and, as far as this document is concerned, you are on your own. At this point, you can install applications, tools, etc. as you would on any Debian machine - usually with apt-get. The Intimate mailing list (see http://intimate.handhelds.org) and/or IRC channel can help you progress from here. The initrd image is incredibly easy to make - simply download the existing initrd image (see Section 2) and rename it to initrd.cramfs.gz. Unzip it (gunzip initrd.cramfs.gz) and then mount it using the loopback device (e.g. mount -t cramfs -o loop initrd.cramfs /mnt/initrd). Since the cramfs image is read-only, you will need to copy out all of the files before changing/adding any (e.g. cp -av /mnt/initrd/* /tmp/initrd/). Now make any changes you want and run the following commands to remake the image: chmod -R root.root /tmp/initrd - files must be owned by root.root in the initrd mkcramfs /tmp/initrd/ /tmp/initrd.cramfs - this makes a new cramfs image from the working directory (you may need to install mkcramfs for this to work) gzip /tmp/initrd.cramfs - zip the cramfs image to reduce its size You can now rename the new image to initrd, remove the existing initrd from the vfat partitions /boot directory and put the new one in its place. This is not yet a simple process - you will need to put new kernel modules into the initrd, put a new zimage for your kernel into the vfat partition and put the new kernel modules into /lib/modules on your ext3 Intimate partition. We are working on automating this process This document was written by Chris Jones (Ng), with help from Jim Conner (Tangent). Originally based on a textfile by Ron Wolfe The Intimate install script was written by Chris Jones, with help from Paul Hedderly (prh).