Introduction

Since BORPH builds on top of a standard Linux kernel, it can be run on top of any standard Linux root file system. Debian is the system of choice because of its ease of use and the fact that it supports all of the (embedded) processors that BORPH intends to support.

The main processor on BEE2 and ROACH are both PowerPC variants. BEE2 spots an embedded PowerPC 405 core in the control FPGA, while the ROACH is powered by an AMCC PowerPC 440Epx processors. As a result, the Debian root file system will need to be from the Debian "powerpc" port. However, since most of us have an Intel-based host machine, a somewhat more complicated method is needed to bootstrap the target root file system.

Although this guide uses sid as an example, it should also work with Debian etch as well. sid is the current "unstable" version of Debian. It contains all the cutting-edge software packages, but may lack enough testing to be fully stable. etch contains relatively new software that are well tested in the packaging system. Also, security update is available to etch but not sid. A lot of these information have been collected from The EmDebian wiki and here.

Easiest way: download it

The easiest way to set up the needed root file system is to download a pre-built file. A Debian (etch) root file system for powerpc can be found here: etch.

Using debootstrap on target hardware

The conceptually easiest way to install a Debian system on the target is, of course, to install it directly from the target. This works as long as the target can be bootstrapped to a bare minimum system that can execute Debian's "debootstrap" program. For example, if your board can already boot to a ramdisk that runs BusyBox, you can use this method.

The following outline the steps involved:

Boot your target system.
Download wget, ar from the Internet. (Your target base system may already have them installed.)
Download debootstrap from Debian. (http://ftp.debian.org/debian/pool/main/d/debootstrap/).
Since it is a Debian package, you have to extract the content. From the Debian Installation Guide:
```
# ar -x debootstrap_0.X.X_all.deb
# cd /
# zcat /full-path-to-work/work/data.tar.gz | tar xv
```

From within your target system, run the command:

# mkdir new_root
# debootstrap sid new_root <your_local_mirror>

Once debootstrap has finished, you will have your new root file system at new_root
You need to perform some basic book-keeping on the new root file system too. See some basic setup on your new root file system.

Two stages set-up using debootstrap

The above method is conceptually simplest. However, as your target system is usually much slower than your host PC, it takes quite some time for debootstrap to download and setup all files.

This method splits the debootstrap process into two stages. First, Debian packages are downloaded and setup by the host (first_stage). All the necessary files will be located in a new root (new_root). At the second stage, the target system is booted using new_root as root and finish the setup using debootstrap. The target may also chroot to new_root if needed.

The following outline the steps involved:

Install debootstrap on your host system.

On your host, execute the following commands:

# mkdir new_root
# debootstrap --foreign --arch powerpc \
              sid new_root <your_local_mirror>

Note the --foreign switch. It stops the debootstrap process before it starts configuring the package, which requires executing target binaries.

Once that is setup, you have to boot your target so that it will nfs mount on new_root. Alternatively, you can make all these files under new_root available to your target via USB, NFS, etc.

If you have opt of the second option, before you can continue debootstrap, you have to make your target system change its current root file system to new_root by using the following command:

# chroot new_root

Once you have changed root, you will find that the first run of debootstrap has already created a directory called debootstrap in which it stores all its information. To continue the process from your target, use the following command:

# /debootstrap/debootstrap --second-stage

That's it. It will finish installing all the downloaded packages and you now have a clean Debian root. Of coures, you need to do some more setup before your new system can be fully functional.

Configuring your new system

Before you can use your new root file system you have to set it up for your target environment. A lot of the set up are described in Section D.3 of Debian Installation Guide. They are highlighted here:

Mount Partitions

You want your target to mount the correct file systems at boot time. It is acheived by editing the file /etc/fstab. Apart from the actual root, you most likely want to mount the proc and the tmp file systems. Below is a sample you can work with:

# /etc/fstab: static file system information.
#
# file system    mount point   type    options    dump pass
proc             /proc         proc    defaults   0    0
tmpfs            /tmp          tmpfs   defaults   0    0

Time and Timezone

Use tzconfig to configure timezone for your target. Since most embedded system, including BEE2 and ROACH do not have a hardware clock, you should also use ntpdate or ntpd to synchronize your system with the rest of the world.

Network

You need to edit /etc/network/interfaces, /etc/resolv.conf, /etc/hostname and /etc/hosts. The Debian Installation Guide has great examples and I am not repeating there here.

Configure Apt

One of the best thing offered by the Debian system is its package management system. To begin, you need to tell apt and other package management software where to find the packages by editing the file /etc/apt/sources.list. For a minimal setup for sid, you want to put down:

deb-src http://ftp.us.debian.org/debian sid main

Note that Debian sid, being the latest version of Debian, does not have regular security update. If security is your concern, use Debian etch instead, i.e., replace all occurance of "sid" in this guide to "etch". Once you have done that, you can also include security updates in your /etc/apt/sources.list file:

deb http://security.debian.org/ etch/updates main
deb-src http://security.debian.org/ etch/updates main

Debian Mirrors

Note that not all Debian mirrors have the powerpc port hosted. For example, the default server used by debootstrap (http://ftp.debian.org/debian) does not host the powerpc port. See the official list of Debian mirrors.

Setting Up a Debian Root File System for BEE2/ROACH