Emdebian

This is currently a work in progress. The objective is to make a reliable set of instructions that can be used to provide a directly bootable Emdebian system. See the "Further Work" section for areas of improvement.

Emdebian is a project that provides cross-compilation toolchains, tools for cross-building packages, and tools for making root filesystems for deployment on devices, particularly embedded devices with "foreign" architectures. Such tools permit the time-consuming and resource-intensive work of preparing a system image to be done on "normal" personal computers and workstations, with the finished result then being deployed on the target device.

Where Emdebian differs from other projects and toolchains is in its relationship to Debian. It is able to draw upon the extensive selection of Debian packages that are already available, up-to-date, and maintained for a selection of architectures. This means that it should be possible to benefit from the considerable effort invested in Debian packaging by the community and be able to obtain usable packages for specific technologies without being obliged to take on the work of tracking upstream development, dependency relationships, fixing portability issues, and performing packaging work just to be able to use some particular piece of software.

The Workflow

Making an installable Emdebian system involves the following steps:

1. Obtain the necessary tools.
2. Obtain a kernel image and modules.
3. Choose a suitable configuration.
4. Prepare a root filesystem.
5. Configure the installation.
6. Format the boot medium.
7. Complete the installation.
8. Boot into the new system.

Obtaining the Emdebian Tools

To prepare a root filesystem, the multistrap tool is needed. On Debian-based systems, this tool should be available from the usual package repository, and can thus be installed as follows:

apt-get install multistrap

Since multistrap is under active development, it may be the case that a later version of the tool is required. If this proves to be the case when following these instructions, you may need to enable the appropriate "backports" repository (using /etc/apt/sources.list and/or /etc/apt/sources.d), update the packaging system...

apt-get update

...and then try to install such a newer version. If no readily available newer version exists in a usable repository, you may need to backport the package from a later Debian release. Such an activity is currently outside the scope of this document.

Obtaining a Kernel Image and Modules

It can be easier to obtain an existing kernel image prepared by the OpenWrt-based toolchain, typically called openwrt-xburst-qi_lb60-uImage.bin and found in the software image release folders.

Currently, the easiest way of obtaining kernel modules is to copy them from an existing NanoNote installation. However, the intention is to provide a more reliable way of obtaining the kernel and modules using the appropriate Debian packages.

The modules should reside in a directory called, for example, configfiles, with the expected filesystem layout preserved. So, for a kernel version of 3.2.1, such module files should reside in the configfiles/lib/modules/3.2.1 directory.

Choosing a Configuration

The multistrap package and documentation provide several example configurations. However, a specific configuration for the NanoNote should look like this for the Debian Squeeze release:

[General]
arch=mipsel
cleanup=true
noauth=false
bootstrap=Grip Debian
aptsources=Grip Debian

[Grip]
packages=udev busybox-static
source=http://www.emdebian.org/grip
keyring=emdebian-archive-keyring
suite=squeeze

[Debian]
packages=
source=http://ftp.debian.org/debian
keyring=debian-archive-keyring
suite=squeeze

This minimal configuration installs a base system from Emdebian Grip packages, which should be smaller than conventional Debian packages, using such conventional packages for those which are not present in the Grip repository. In addition, the udev and busybox-static packages are added; this latter package is essential for the initial configuration of the system.

Preparing a Root Filesystem

With a suitable configuration file called, for example, multistrap-squeeze-mipsel.conf a root filesystem can be constructed in a location such as rootfs as follows. Note that you should really be root or use sudo for this to work properly:

multistrap -f multistrap-squeeze-mipsel.conf -d rootfs

If this operation fails with errors related to repository public keys, you may need to install a newer version of multistrap as described above.

Configuring the Installation

On its own, multistrap does not provide all the files required for a running system. Moreover, a filesystem prepared by the tool will not be configured, and any attempt to boot into such a filesystem will probably fail. Thus, additional configuration must be performed.

A number of configuration files, missing from the root filesystem, must be defined for the installation:

• /etc/fstab
• /etc/modules
• /etc/network/interfaces

Such files can be placed in a directory called, for example, configfiles while retaining the necessary filesystem structure, so that fstab would reside at configfiles/etc/fstab, and so on. This directory should also hold the kernel modules as described above.

With the missing files now defined, a script written to automate the remaining configuration activity can be run as follows. Again, it may help to be root or to use sudo to be able to copy the necessary files into the root filesystem:

qi-emdebian-postsetup rootfs openwrt-xburst-qi_lb60-uImage.bin configfiles

Here, rootfs is the root filesystem created above, openwrt-xburst-qi_lb60-uImage.bin is the kernel image obtained above, and configfiles is the directory containing the kernel modules and missing configuration files.

(In addition to the above missing files, a special file called /etc/preinit will be defined in the root filesystem so that the OpenWrt-based kernel can perform initial configuration on the device and then hand over control to the normal Emdebian init system. The installation of this file should take place automatically, as should the configuration process on the device, but it may be useful to know that this file exists should additional customisation be required.)

Formatting the Boot Medium

Currently, only booting from a microSD card is described in these instructions. Eventually, installation to NAND may also be covered.

The microSD card should first be made available to the computer performing this work. On a Linux-based system, it should then appear as a device like /dev/sdb. You should check and make absolutely sure that you know which device has been assigned to the microSD card, perhaps using the dmesg command to see what is reported when plugging in the card. For example:

[25942.832101] sd 20:0:0:0: [sdb] Attached SCSI removable disk
[25942.832148] sd 20:0:0:0: Attached scsi generic sg2 type 0

With this information, you can now partition the card using fdisk. First, as root or using sudo, run the following to look for existing partitions:

fdisk -l /dev/sdb

To add a new partition, run fdisk, use the n command to make a primary partition, and then the w command to write the partition table.

Completing the Installation

With a partition in place (/dev/sdb1 in this case), you can now run the following helper script (as root or using sudo):

qi-emdebian-install rootfs /dev/sdb1 --mkfs

This will make a filesystem in the partition and copy the root filesystem to the card.

Booting into the New System

To boot into the newly prepared system, insert the microSD card into the NanoNote's card slot, then hold down the M key while pressing the power button. The device should now report that it is loading "/boot/uImage" from mmc device. With the conventional OpenWrt-based kernel, the boot splash-screen (or bootsplash) will take up most of the display, but messages will appear at the bottom of the screen.

If everything goes according to plan, a few minutes will be required for the configuration of the system to be done by the device - this is an issue with installing and booting Debian for the first time - but eventually, a message at the bottom of the screen should read something like...

(none) login:

This indicates that the system is now ready to allow you to log in. You should be able to do so as root without providing a password. It is then your responsibility to set a password using the passwd command.

Further Work

Things to be added include...

• The scripts mentioned for configuration and installation
• Suitable preinit-related files
• A proper way of getting kernel modules
• A selection of sample configuration files
• Eventually, a Debian-centric way of obtaining a kernel
• Information about essential packages already provided by the existing software image
• Network configuration
• Package fixes, such as the use of integer-only libraries for Vorbis decoding, for example

The initial configuration process should be improved to either give better visual feedback, perhaps removing the bootsplash, or to eliminate time-consuming processes by restricting the packages that are initially configured before a login can be obtained.

Use of a separate initial root filesystem has been suggested. Installing a "normal" Debian ARMEL Linux on the Kindle provides one recipe for making such a filesystem. There is also a Debian package - initramfs-tools - which might be of interest. There is also a comparison between initramfs-tools and yaird. Another related tool is debirf.

A document somewhat similar to this one, but employing debootstrap is How to Cross Compile a Kernel and Create the Debian Root File Store. Another similar document describing an initial root filesystem is How to run Debian or Ubuntu GNU/Linux on your Android.