Angstrom Linux Quick Installation Procedure for WindowsCE-ARM based devices

ie.  iPAQ H3970 and H3975 Pocket PC ROM  http://www.angstrom-distribution.org/releases/2007.12/images/h3900/

  

(c)2007-8 by Paul Sokolovsky  

This document is licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported license.  It is contributed to the documentation set of the Angstrom project.  Image courtesy of Michael Opdenacker.   

These instructions describe how to get started with Angstrom quickly on WindowsCE-based ARM devices, like PocketPCs and WindowsMobiles. This guide is intended for novice users, and thus does not describe all available options and omits technical details which are otherwise good to know. Make sure you read more comprehensive documentation once you get up to speed with Angstrom!   

---

  

1. Prerequisites

  

1.1. HaRET support

To use tools described in this doc, your device must be supported and recognized by the Haret bootloader. By now, it includes support for many devices, including ones which have only alpha-quality Linux support. All devices supported by Angstrom are supported by HaRET, so if you have an image for your device, you’re done. If you’re a newcomer with an unsupported device, you’re out of luck unless you’re brave enough to become a device hacker. This is an exciting and knowledge-rich way, and the first and relatively easy thing you will want to do is to make HaRET recognize your device.  

1.2. Backup, Backup, Backup!

  

Linux, once booted, uses the entire device RAM for its operation. That means that when booting, you lose all of the previous contents of the RAM. As pre-WinCE5 devices used RAM as kind of RAMdisk to store important settings and user data, they will be lost after booting Linux. Or in other words, booting Linux is the equivalent of hard resetting the device (and often to boot, you need to perform a hard reset first, as boot procedure requires some deal of free memory, which not every user has all the time). With post-WinCE5 devices, the situation is less clear: they store most of the data in flash; and still, they are known to keep at least some settings in RAM.  

So, in either case, the golden rule of any computer user applies here too: “Backup!”. Backup before doing any big change to the system, like trying Linux. Backup regularly anyway. Many PDAs include backup software preinstalled in their FlashROM (for example, most HP iPaqs have iPaq Backup); some ship it on accompanying CD; you may look for 3rd-party solutions on the net; finally, as a default solution, you can use the backup feature of ActiveSync – that’s available for any device . [#activesync *] 

So, we’ll not return to this again, but: BACKUP YOUR DEVICE EACH TIME BEFORE YOU BOOT LINUX.

1.3. Knowing Other Risks

If you do backups as described above, there is virtually zero chance of data loss. The procedures described in this document also pose near-zero risk of causing harm to device hardware or firmware (“brick” device). Still, there always may be obscure bugs and circumstances leading to unpredictable results. So, as usual, PERFORM LINUX INSTALLATION AT YOUR OWN RISK. This applies to anything you do with your device, of course.

Make sure that you know well how to perform a *hard* reset of your device (many devices require obscure button combinations to be pressed together with the usual “peephole” or reset button).

---

2. Preview First

Want to have a look at Angstrom? You don’t need to install anything! Angstrom is a modern distribution offering all state-of-the-art features, including LiveCD. Well, we don’t have CDs here, so the thing is called LiveRamdisk instead. It appears as a single big executable file; you download that file, put it somewhere so you can start it on the device, and do just that! Somewhere above is usually a memory card (doesn’t matter if it’s CF or SD), but users with big internal flash may also use the flash disk. Finally, users without a flashdisk and lacking a card can try to copy it to RAM with ActiveSync and start from there. Caveat: a LiveRamdisk is big, and requires as much big memory to startup. So, even 64Mb devices may have troubles running in such way (due to some under-functional OS taking control of that RAM, you guessed right  ).

Once you boot, you can preview all standard Angstrom features. You can access memory cards and change files on them. You can even install some small packages from the feeds; but the root filesystem of this setup is located on ramdisk, so all newly installed packages and configuration changes will be lost on reboot. LiveRamdisks as of now are more intended as a quick demo, not as a method to have production install. Don’t expect the same results as you get in the latest Knoppix! 

Downloads:

• Select directory for your machine
• Download the file: Angstrom-x11-image-liveramdisk-<angstrom_version>-<machine>.exe

---

3. Installing using a Loopback Image

To install Angstrom for everyday use, you would need to flash it to the internal FlashROM or create a dedicated partition on a memory card. Based on experiences, both options proved to be a headache for novice users like you!  Besides, flash install is supported only for small subset of older devices (that’s because developers are also afraid of bricking their devices  ). So, to the rescue comes installing using a loopback image. “Installing” is a strong way to say it, as the whole loopback image is prepared for you already. You download it, and uncompress on your card (to the root directory). You also download an Angstrom bootmanager, packaged as an .exe, and put it somewhere you can run it from (the easiest place to put it is the root of the card, too).

Then, you start the bootmanager, and in few seconds it shows you the menu of the boot locations available. You would only have a single, loopback source (ignore NFS and any other options you might have). Once you made your selection (cursor keys, then action button to confirm), Angstrom will start to boot.

Downloads:

• Select the directory for your machine
• Download the following files:
  • Angstrom-x11-image-glibc-ipk-<angstrom_version>-<machine>.rootfs.img.bz2 – compressed ext2 filesystem image, needs uncompression before use
  • Angstrom-boot-<kernel_version>-<machine>.exe – bootmanager

If you don’t know how to uncompress a bz2 file, use 7-zip.

---

4. Additional Info and Troubleshooting

To be able to solve problems with the processes above, we need to know a few basic facts about the Linux startup process. So, to have Linux booted, one needs 3 things:

• A bootloader
• A kernel
• A rootfs

LiveRamdisks have all of bootloader, kernel and compressed rootfs packaged together into single executable file. So, zero chance of component mismatch, and the only expectable problems can be:

• Lack of free memory to load entire package into memory.
• Lack of free memory to unpack internal components.
• Issue with hardware support for particular device model or specific device instance that the user has.

The first type of OOM (out-of-memory) error should be reported on the initial load stage. The second OOM error is more grave, and can lead to a silent lockup with a black screen during kernel startup. Fortunately, this can happen only if the LiveRamdisk is made too big, and the size parameter is under control of the developers.

Hardware support issues and incompatibilities are the most unpleasant issues: they can manifest in various, unpredictable ways, like for example, the touchscreen having calibration issues for a particular device or lockup during boot due to highly-unusual card inserted in the slot during boot. Fortunately, these issues are really rare. But if you face something like that, you should perform additional testing to figure out how to reproduce the issue, how frequently it happens, if there are ways to work around it, etc., and communicate it to the kernel maintainer of your device.

Proceeding to loopback install, here we split the rootfs out of the single package. So, the bootmanager exe actually contains bootloader and kernel, while rootfs lives in a separate file (and is uncompressed, so it can be writable). One important thing to know about such a setup is that the rootfs is dependent on the kernel: rootfs contains the kernel modules, and their version must match the actual kernel used. As the kernel resides in a bootmanager executable, that means that the bootmanager and rootfs must be built against the same kernel version. So, if you upgrade rootfs (i.e. install new RC), make sure that the download directory contains an updated bootmanager and if so, use the new version for the new rootfs – and the old bootmanager for the old rootfs. Failing to do so will still usually cause Angstrom to boot, but there will be issues with hardware, etc. support – for example, lack of sound, bluetooth, network support, various errors during booting, etc. Note that “same version” applies to the main kernel version (“2.6.21-hh20”), not a kernel package release (“-r2”). It is OK if a bootmanager with an older kernel revision is shipped with a zImage file of newer revision.