Manual:RB500 Linux SDK

This guide will describe procedures needed to install Debian GNU/Linux distribution on RouterBOARD 500 series computers over network, as well as provide some information needed to use RouterBOARD 500 boards on that GNU/Linux system.

Note that these instruction were tested with Debian 3.0 "Woody" release and might not apply to other releases

Making Debian installer

Kernel image and drivers.tgz

Every architecture has its own rescue.bin floppy image and drivers.tgz. Both of them are used to get kernel with drivers on a system. rescue.bin is a simple ext2 image that contains linux kernel. It is also used as a rescue floppy. drivers.tgz is a tar archive with driver modules. Our MIPS system is not recognised, so it is named "unknown".

Original files are located at: http://ftp.ee.debian.org/debian/dists/woody/main/disks-mipsel/current/. r3k-kn02 architecture was used as an sample.

• rescue.bin contains "/install.sh" that is executed during installation. It should copy kernel to the directory provided as its first argument. It contains "type.txt" file (that has word "rescue" in it). It also creates a simple script "/sbin/delo", to emulate DEC loader, that simply copies "/vmlinux" to "/dev/cfa1".
• drivers.tgz also contains "/install.sh" that is executed during installation. It should copy all the kernel modules (the current one doesn't have any modules). Currently it also creates "/dev/cfa" and "/dev/cfa{1,2,3,4}", since regular Debian /dev system does not have them.

To upgrade kernel, rescue.bin should be mounted and the new kernel should be copied over. Note that "root_fs" kernel parameter should be "/dev/cfa2".

Debian Installer (boot-floppies)

We are using the old woody installer known as boot-floppies. It is contained in root.tgz located at: http://ftp.ee.debian.org/debian/dists/woody/main/disks-mipsel/current/. All of its contents should be copied in to initrd image. initrd should be at least 8Mb (otherwise it won't have enough space).

To create initrd:

dd if=/dev/zero of=initrd bs=1024 count=8192
/sbin/mke2fs -F -b 1024 initrd

Copy all stuff into initrd:

mkdir mnt
mount initrd -o loop=/dev/loop0 mnt
cd mnt
unpack root.tar.gz
mv debian-mipsel-root/* .
rm -rf debian-mipsel-root

Remove unneeded file:

rm linuxrc

Add /dev/cfa:

mknod dev/cfa b 13 0
mknod dev/cfa1 b 13 1
mknod dev/cfa2 b 13 2
mknod dev/cfa3 b 13 3
mknod dev/cfa4 b 13 4

Remove installation of delo:

sed -i s/delo// usr/lib/debootstrap/scripts/woody

Make initrd.gz

cd ..
umount mnt
gzip initrd

Compile kernel patched with the provided patch. A congifuration file ".config" should be present in the kernel directory. The kernel patch may have created it under different name, so you might need to rename it.

make ARCH=mips oldconfig vmlinux

take vmlinux and rename it to linuxrc. Then make a boot TFTP image:

echo "root=/dev/ram0" >kernel.params
mipsel-linux-uclibc-objcopy --add-section kernparm=kernel.params linuxrc
mipsel-linux-uclibc-objcopy --add-section initrd=initrd.gz linuxrc

To make regular boot kernel, take another copy of vmlinux

echo "root=/dev/cfa2" >kernel.params
mipsel-linux-uclibc-objcopy --add-section kernparm=kernel.params vmlinux

Then use DHCP & TFTP to make board boot with etherboot into linuxrc and Debian installation can start.

Setting up the Installation Server

First to install the RouterBOARD system, you need to prepare installation server which will provide initial boot image for the device. A BOOTP/DHCP server and a TFTP server must be installed on the installation server. The RouterBOARD should also receive an IP address which will allow it to use DNS and HTTP protocols to access the Internet.

We used the ATFTPd TFTP server, which does not require configuration (except, perhaps, the TFTP root directory), and ISC DHCPd version 3 DHCP server.

The DHCP configuration used to boot up the RouterBOARD computer that has 00:09:22:22:22:00 MAC address on the Ethernet port, which is connected to the 192.168.0.0/24 network:

default-lease-time 21600;
max-lease-time 2100;

host rb500 {
  hardware ethernet 00:09:22:22:22:00;
  filename "/linuxrc";
  fixed-address 192.168.0.10;
}

subnet 192.168.0.0 netmask 255.255.255.0 {
  option subnet-mask 255.255.255.0;
  next-server 192.168.0.2;
  option broadcast-address 192.168.0.255;
  option routers 192.168.0.1;
}

Note that the DHCP and TFTP server itself has the IP address of 192.168.0.2, and the default gateway for the network is 192.168.0.1

You should place the linuxrc file (which you can get at http://www.routerboard.com/debian/linuxrc) in the TFTP root directory, so that the RouterBOARD would be able to download it.

Preparing the RouterBOARD

The board has to be properly powered. We will use the first Ethernet port for booting the device. Serial console cable must be connected, and you will need some kind of terminal emulator program to interact with the RouterBOARD (like HyperTerminal for Windows or minicom for GNU/Linux). The GNU/Linux will be installed on a CompactFlash drive that you should insert in the appropriate connector on the RouterBOARD. Please note that minimal size of the CompactFlash device for a normal GNU/Linux installation is 128MB

You should also configure its BIOS so it could boot from network:

What do you want to configure?
   d - boot delay
   k - boot key
   s - serial console
   o - boot device
   m - memory test
   u - cpu mode
   f - try cpu frequency
   c - keep cpu frequency
   r - reset configuration
   g - bios upgrade
   a - mac addresses
   p - boot protocol
   t - do memory testing
   x - exit setup
your choice: p - boot protocol

Press 'p' and select the booting protocol:

Choose which boot protocol to use:
 * 1 - bootp protocol
   2 - dhcp protocol
your choice: 2 - dhcp protocol

Select '2' for DHCP

Then press 'o' to select boot device:

Select boot device:
   e - boot over Ethernet
   n - boot from NAND
 * c - boot from CF
   b - boot chosen device
your choice: e - boot over Ethernet

You need to select 'e' here.

Initial installation (first stage)

Now, if the installation server was configured correctly, the "Release Notes" screen should appear on your terminal console. If you do not see the "Release Notes" screen, please check your server configuration (perhaps, log files will be of a help), the linuxrc file and the serial console settings.

Please follow this step-by-step instruction to install the base system on the CompactFlash drive:

• On the "Release Notes" screen press "<Continue>"
• Select "Partition a Hard Disk"
• <ENTER> on "/dev/cfa"
• Configure partitions. The first partition should be 4Mb big with type 27. The second partition will be the root partition, and if you will not have any other data partitions, it should be at least 120MB big, or the installation procedure will fail. You can configure additional partitions (like separate /usr or a swap partition) as required. After you create the partitions, choose "Write", then type "yes" and choose "Quit"
• If no SWAP partition was created, select the alternative "Do Without a Swap Partition" step, and answer "<Yes>" on "Do Without a Swap Partition" question
• Select "Initialize a Linux Partition"
• Select ext2 or ext3. Note: on a 128MB medium there is not enough space for making ext3 filesystem
• On "Scan for Bad Blocks?" it is safe to just say "<No>"
• On "Are You Sure?" say "<Yes>"
• On "Mount as the Root Filesystem?" say "<Yes>"
• Select "Install Kernel and Driver Modules"
• On "Select Installation Medium" say "network"
• On "Network Not Yet Configured" say "<Continue>"
• On "Choose the Hostname" you can leave "debian" (press <Enter>)
• On "Choose Network Interface" select "eth2"
• On "Confirmation" about whether the "eth2" is a PCMCIA card, say "<No>" as it is not a PCMCIA card
• On "Automatic Network Configuration" say "<Yes>" if DHCP server should be used to assign IP address automatically, or "<No>" for static IP address configuration; If DHCP failed or "<No>" was selected, follow the instructions on screen to configure the IP address andmake sure to type correct IP address of the DNS server.
• On "Fetching installation files over the network" select "<Continue>"
• On "Select Installation Server" type "http://www.routerboard.com/debian/" in "Download URL" field. DO NOT LEAVE IT AS DEFAULT. Type in Proxy address if you have one.
• Select "Configure Device Driver Modules"
• On "Note about loaded drivers" select "<Continue>"
• Ignore errors and select "Exit Finished. Return to previous menu."
• Select "Install the Base System"
• On "Select Installation Medium" select "network"
• On "Select Installation Server" type "http://ftp.us.debian.org/debian/" or "http://archive.debian.org/debian-archive/" (or some other Debian mirror) in "Download URL". DO NOT LEAVE IT AS DEFAULT. Type in Proxy address if you have one. NOTE that some mirrors do not have mipsel architecture (for example, in Latvia you would have to use Estonian mirror: http://ftp.ee.debian.org)
• Select "Make System Bootable"
• Select "Reboot the System"
• On "Reboot the system?" say "<Yes>"

Now the first-stage installation ir completed, and you will need to switch the BIOS settings to boot from the newly installed CompactFlash:

What do you want to configure?
   d - boot delay
   k - boot key
   s - serial console
   o - boot device
   m - memory test
   u - cpu mode
   f - try cpu frequency
   c - keep cpu frequency
   r - reset configuration
   g - bios upgrade
   a - mac addresses
   p - boot protocol
   t - do memory testing
   x - exit setup
your choice: o - boot device

Select baud rate for serial console:
 * e - boot over Ethernet
   n - boot from NAND
   c - boot from CF
   b - boot chosen device
your choice: c - boot from CF

Configuring base system (second stage)

Now when the packages are installed, some configuration is needed. As the configuration questions depend on the versions of software that will be current when you will be installing it, and also as you might want not to agree to the proposed configuration, there is no step-by-step instructions given for this stage, just some recommendations:

• It is very unlikely you will need to answer "<Yes>" to the "Do you want to use a PPP connection to install the system?" question, so we suggest to answer "<No>" there
• In "Apt Configuration" question about apt method to access the Debian archive you will need to answer either "http" or "ftp" and later select the correct installation mirror from the list
• For the next questions in case you are installing the system on a small storage device (like 128MB), it is recommended that you do not choose to use non-US and non-free software and not allow security updates from security.debian.org, as you may not have enough space to use them
• It is highly recommended also not to use tasksel and dselect even if you have a storage device as large as 256MB - it is better to install everything later on manually using apt utility
• When prompted to configure exim, you may answer "5" to leave the package unconfigured if you do not plan to use exim. You can complete the configuration or remove the exim later on

Now you have a working system. Some useful recommendations on how to free up some space and how to install something on this system are given in the next section of this manual

Fine-tuning the system (third stage)

This section describe some steps to get more of your system. These steps are most useful when installing on a small medium (like 128MB CompactFlash).

1. First of all, lets remove some unneeded packages. Run "apt-get remove ppp pppconfig tasksel setserial info nvi pppoe pppoeconf ed fdutils bsdmainutils adduser man-db console-common gettext-base groff-base manpages modconf libreadline4 libgdbmg1". If you do not need telnet, you can also remove "telnet" package.
2. Use "nano /etc/apt/sources.list" to comment out all unneeded apt sources. Lines starting with "deb-src" may probably be commented if you do not want to recompile Debian packages yourself. Also change "stable" to "testing" in this file so that more packages would be available for you (the current stable release does not have many useful packages for the mipsel architecture)
3. Run "apt-get update" for apt to update its package cache (and free up some space). On a 128MB module you should now have about 25 to 30 MB free (check with "df"). If not, try doing "apt-get clean; rm -rf /var/lib/dpkg/*-old".
4. Install debconf-english to get rid of Debian configuratio internationalization ant then install localepurge program which will clean up some more by removing unneeded locales and translated man pages. You can do this with "apt-get install debconf-english; apt-get install localepurge debconf-english". This will upgrade some existing packages as well as install some new ones. Do not select any locales, and choose to remove localized man pages. Run "apt-get clean; rm -rf /var/lib/dpkg/*-old" after installation.
5. Previous update may have left one legacy package, so let's remove it: "apt-get remove libnewt0"
6. You may also want to replace a somehow bloated version of nano with a smaller one: "apt-get remove nano; apt-get install nano-tiny"
7. Now you can install other packages you need (like ftp, ssh, mc, ...). For example, we used the additional "apt-get install ftp ssh mc" command before generating our ready-to-use GNU/Linux images. Do not forget doing "apt-get clean; rm -rf /var/lib/dpkg/*-old" each time after installing packages to free up space used by temporary files and package archives
8. If you have more than 60MB left free (i.e., if you are not using 128MB medium, which will still have only 25MB left after all these magic tricks), you are advised to complete upgrade to the testing release by issuing the "apt-get dist-upgrade" command. Also there is a good apt frontend called aptitude, which you can use to further manage the packages.

If you need to configure network later, please edit file called "/etc/network/interfaces". The syntax is selfexplanatory, and you will also be able to find many manuals on how to configure it.

Now you have a standard Debian GNU/Linux system with almost maximum free space it is possible to get. Please note that we do not provide support service or training of any kind for this system - you will just have to find all necessary information how to work with this system by yourself.

Using RouterBOARD 500 specific functions

Usage warning

It is recommended to avoid using NVRAM memory as it may render your system unbootable.

Boot image

The RouterBOOT boot loader can load and execute an ELF image from the selected medium (either onboard NAND, or CompactFlash device). This image must be compiled for "mipsel" (little-endian MIPS) architecture. If you are compiling it on a non-mipsel computer (for example, on an Intel IA-32 PC), you will need a crosscompiler, which you will have to make by yourself (see http://www.mobilab.unina.it/Resources/crosscompilerHOWTO.html, http://www.kegel.com/crosstool/ and http://www.google.com for more information).

In case the ELF image you want to boot is Linux kernel, you should remember the following:

• the boot loader supports ELF images, not compressed with zip, 9-zip, gzip, bzip2 or any other compression algorithm, which does not provide ELF image as its output format
• you might need to set some kernel parameters, so that it knows at least what root file system it should boot from. Use "kernparm" ELF section to embed kernel parameters into the kernel, for example to boot the kernel from a CompactFlash device, try:

echo root=/dev/cfa2 > kernel-parameters
mipsel-linux-objcopy --add-section kernparm=kernel-parameters vmlinux

• You might also want to have the kernel to use an initial RAM disk. To do this, make a gzipped archive of a supported filesystem (like ext2) image, and add it just like kernel parameters in the previous example, but in this case ELF section name would be "initrd"

Loading ELF image from CompactFlash device

RouterBOOT loads contents of first partition with type 39 (0x27). If there is no such partition, it displays message "CF BOOT FAILURE: kernel partition missing!". There is no filesystem on this partition, it contains raw ELF image, so it can be copied using the "dd" utility. The partition may have any size if it is correctly stated in the partition table.

Loading ELF image from NAND device

RouterBOOT treats first 0x400000 bytes (4 megabytes) of the onboard NAND chip as a partition with yaffs filesystem. No partition table is stored on NAND, so location and size of this first partition is hardcoded in the RouterBOOT loader. It searches for a regular file in the root directory, named "kernel". If it is not found, RouterBOOT displays message "kernel not found", otherwise it prints "loading kernel from nand". If there is error loading this file, it displays "data is corrupted".

To access partition that contains kernel:

mount -t yaffs /dev/mtdblock0 /mnt

To access the second NAND partition, that is used by kernel as root filesystem when booting from nand:

mount -t yaffs /dev/mtdblock1 /mnt

Safest way to access NAND is through filesystem. It is not supposed to be accessed by the standard utilities such as "dd" to write directly to /dev/mtd0 and /dev/mtd1, because these utilities do not update ECC, do not check for bad blocks and do not perform other NAND-specific operations. For direct access use "flash_eraseall", "nanddump" and other utilities from linux-mtd toolkit (http://www.linux-mtd.infradead.org/)

The kernel is in a separate partition because to access files on yaffs partition, you need to scan the whole partition. Yaffs is very fast in this respect, but it still takes time and memory (~32 k for every megabyte). Bigger partition means slower booting. Note that if you compile your own yaffs code (not from the linux kernel patch provided on routerboard.com), you must use the same yaffs compilation flags, especially those related to ECC.

What paremeters does RouterBOOT pass to kernel

RouterBOOT appends some kernel parameters that contain information about board and startup configuration. Here is the meaning of some of them:

• gpio - contains value of GPIO register that is read by RouterBOOT during bootup with disabled serial port. It can be used to determine state of S1 button and JP1 jumper. Bit 1 (mask 0x0002) is the state of the S1 button, bit 3 (mask 0x0008) is the state of the JP1 jumper. 1 means open, 0 means closed/pressed. Example: gpio=16383 (neither JP1 nor S1 is closed)
• console - used to pass serial port settings to kernel. This is standard kernel parameter. Example: console=ttyS0,115200
• mem - used to pass amount of on-board RAM. This is a standard kernel parameter. Example: mem=32M

Accessing the User LED

There is a "changeLatchU5" function in the patched kernel, which is defined in "linux/arch/mips/rc32434/rb500/rb.c" and declared in "linux/include/asm-mips/rc32434/rb.h"

• to turn led on: changeLatchU5(LO_ULED, 0);
• to turn led off: changeLatchU5(0, LO_ULED);

Accessing the GPIOs

JP1 is connected to GPIO pin 3, S1 to GPIO pin 1. These are also used for serial port, so it should be disabled before reading GPIO state at runtime. For details on GPIO access consult the IDT manual. The same function of the patched kernel used for changing LED states, can be used to disable serial port:

• To disable serial port: changeLatchU5(0, LO_FOFF);
• to enable serial port: changeLatchU5(LO_FOFF, 0);