Installing Debian Sarge on a Linksys NSLU2

Index

• News
• Introduction
• Why?
• Requirements
• Big/Little Endian
• Cross Compiler
• Kernel Patch
• Kernel Compilation
• Testing the Kernel
• Debian Installation
• Boot From USB
• Installing Modules
• Writing the Kernel to Flash
• Conclusion

News

Introduction

• Intel IXP420 (ARMv5TE) CPU running at 266MHz (*)
• 32MB SDRAM
• 8MB NOR flash
• 10/100 ethernet (builtin)
• 2x USB 2.0 host

Notice that the NSLU2 is underclocked to 133MHz from the factory, but this can easily be resolved by removing a resistor. See OverClockTheSlug for details.

The original Linksys software is based on a 2.4.22 Linux kernel and uses RedBoot as bootloader.

Why?

• Packaged software: There already exist specialized distributions for the NSLU2 (OpenSlug and Unslung), but they are either quite restricted or in early development. The amount of packaged software is furthermore quite limited compared to Debian's 16K packages.
• Familiarity: I run Debian on my other machines, so it's easier to maintain the NSLU2 if it's just another Debian machine instead of learning another distribution.

Requirements

• A Linksys NSLU2 with a serial port modification. NEWS: Serial port no longer needed, see SerialLessInstallation for details
• USB hard drive or memory stick large enough to install Debian (256MB+)
• USB ethernet adapter (D-Link DUB-E100, Linksys USB200M, .. - See AddEthernetAdapter or linux-usb.org for a list of adapters known to work)
• A Linux box to compile the kernel on (preferable running Debian)
• A TFTP server to serve the installation images (apt-get install tftpd-hpa)

Big/Little Endian

• The CPU core can run in both big and little endian modes, but the peripherals are connected big endian
• The original Linksys software is running in big endian mode, including the RedBoot bootloader
• Debian only supports little endian mode on ARM

The kernel image furthermore needs to be byteswapped before upload as it is loaded into memory by RedBoot running in big endian mode, but needs to be read by the Linux kernel running in little endian mode.

This can be done with the following little python script:

== byteswap.py snip start ==
#!/usr/bin/python
# swap every 32bit word in input and write it to output

import array, sys

if len(sys.argv) != 3:
  sys.stderr.write('Invalid arguments.\n')
  sys.stderr.write('Usage: %s <input> <output>\n' % sys.argv[0])
  sys.exit(1)

if sys.argv[1] == '-':
  file = sys.stdin
else:
  file = open(sys.argv[1], 'rb')

input = file.read()
a = array.array('I')
# add padding if needed
a.fromstring(input + '\0' * (4-len(input)&3))
a.byteswap()

if sys.argv[2] == '-':
  file = sys.stdout
else:
  file = open(sys.argv[2], 'wb')

a.tofile(file)
== byteswap.py snip end ==

Cross Compiler

When the script finishes you should have an armv5b-softfloat-linux-gcc in /opt/crosstool/armv5b-softfloat-linux/gcc-3.3.4-glibc-2.2.5/bin/.

Alternatively you can download a precompiled version of it:

• crosstool-armv5b-softfloat-gcc-3.3.4-glibc-2.2.5.tar.gz (40M)

Kernel Patch

• Use the correct linker script even if the compiler defaults to big endian
• Switch the processor into little endian mode at startup
• Access the (big endian-connected) flash
• Access the PCI controller in little endian mode

• openslug1.2-2.6.11.12.patch (91K)
• nslu2-le-2.6.11.12.patch (7K)

Kernel Compilation

wget ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.11.12.tar.bz2
tar jxvf linux-2.6.11.12.tar.bz2

Enter the directory and apply the patches:

cd linux-2.6.11.12
patch -p1 <../openslug1.2-2.6.11.12.patch
patch -p1 <../nslu2-le-2.6.11.12.patch

Configure the kernel for the NSLU2:

make ARCH=arm CROSS_COMPILE=armv5b-softfloat-linux- nslu2_defconfig

And build it:

make ARCH=arm CROSS_COMPILE=armv5b-softfloat-linux- zImage

Byteswap the kernel image and copy it to your tftp directory:

sudo byteswap.py arch/arm/boot/zImage /var/lib/tftpboot/zImage-swap

• zImage-swap (962K)

Testing the Kernel

IP: 192.168.0.1/255.255.255.0, Gateway: 192.168.0.1
Default server: 0.0.0.0, DNS server IP: 0.0.0.0

RedBoot(tm) bootstrap and debug environment [ROMRAM]
Red Hat certified release, version 1.92 - built 15:16:07, Feb  3 2004

Platform: IXDP425 Development Platform (XScale)
Copyright (C) 2000, 2001, 2002, Red Hat, Inc.

RAM: 0x00000000-0x02000000, 0x000723a0-0x01ff3000 available
FLASH: 0x50000000 - 0x50800000, 64 blocks of 0x00020000 bytes each.
== Executing boot script in 2.000 seconds - enter ^C to abort
^C
RedBoot> ip_address -l 192.168.1.77 -h 192.168.1.100
IP: 192.168.1.77/255.255.255.0, Gateway: 192.168.0.1
Default server: 192.168.1.100, DNS server IP: 0.0.0.0
RedBoot> load -r -v -b 0x01d00000 zImage-swap
Raw file loaded 0x01d00000-0x01defd5f, assumed entry at 0x01d00000
RedBoot> exec 0x01d00000
Using base address 0x01d00000 and length 0x000efd60
Uncompressing Linux...................................................................
done, booting the kernel.
Linux version 2.6.11.12 (jacmet@p4) (gcc version 3.3.4) #1 Sun Jul 17 12:01:02 CEST 2005
CPU: XScale-IXP42x Family [690541f1] revision 1 (ARMv5TE)
CPU0: D VIVT undefined 5 cache
CPU0: I cache: 32768 bytes, associativity 32, 32 byte lines, 32 sets
CPU0: D cache: 32768 bytes, associativity 32, 32 byte lines, 32 sets
Machine: Linksys NSLU2
Warning: bad configuration page, trying to continue
Memory policy: ECC disabled, Data cache writeback
Built 1 zonelists
Kernel command line: root=/dev/ram0 rw rootfstype=ext2 initrd=0x01000000,10M noirqdebug
  init=/linuxrc mem=32M@0x00000000 console=ttyS0,115200n8
PID hash table entries: 256 (order: 8, 4096 bytes)
ixp4xx_timer_init()
Dentry cache hash table entries: 8192 (order: 3, 32768 bytes)
Inode-cache hash table entries: 4096 (order: 2, 16384 bytes)
Memory: 32MB = 32MB total
Memory: 20032KB available (1832K code, 165K data, 96K init)
calibrate_delay (jiffies = 4294937304)
Mount-cache hash table entries: 512 (order: 0, 4096 bytes)
CPU: Testing write buffer coherency: ok
checking if image is initramfs...it isn't (bad gzip magic numbers); looks like an initrd
Freeing initrd memory: 10240K
NET: Registered protocol family 16
nslu2_init()
PCI: IXP4xx is host
PCI: IXP4xx Using indirect access for memory space
PCI: bus0: Fast back to back transfers disabled
dmabounce: registered device 0000:00:01.0 on pci bus
dmabounce: registered device 0000:00:01.1 on pci bus
dmabounce: registered device 0000:00:01.2 on pci bus
SCSI subsystem initialized
usbcore: registered new driver usbfs
usbcore: registered new driver hub
OpenN2 Misc I/O Driver Version 0.1.7
enable_irq(22) unbalanced from c0012188
enable_irq(29) unbalanced from c0012190
NetWinder Floating Point Emulator V0.97 (double precision)
devfs: 2004-01-31 Richard Gooch (rgooch@atnf.csiro.au)
devfs: boot_options: 0x0
JFFS2 version 2.2. (C) 2001-2003 Red Hat, Inc.
IXP4xx Watchdog Timer: heartbeat 60 sec
Serial: 8250/16550 driver $Revision: 1.90 $ 2 ports, IRQ sharing disabled
ttyS0 at MMIO 0xc8000000 (irq = 15) is a XScale
io scheduler noop registered
io scheduler deadline registered
RAMDISK driver initialized: 16 RAM disks of 10240K size 1024 blocksize
IXP4XX-Flash0: Found 1 x16 devices at 0x0 in 16-bit bank
 Intel/Sharp Extended Query Table at 0x0031
Using buffer write method
cfi_cmdset_0001: Erase suspend on write enabled
Searching for RedBoot partition table in IXP4XX-Flash0 at offset 0x7e0000
6 RedBoot partitions found on MTD device IXP4XX-Flash0
Creating 6 MTD partitions on "IXP4XX-Flash0":
0x00000000-0x00040000 : "RedBoot"
0x00040000-0x00060000 : "SysConf"
0x00060000-0x00160000 : "Kernel"
0x00160000-0x00180000 : "Ramdisk"
0x00180000-0x007e0000 : "Flashdisk"
0x007e0000-0x00800000 : "FIS directory"
PCI: enabling device 0000:00:01.2 (0140 -> 0142)
ehci_hcd 0000:00:01.2: EHCI Host Controller
ehci_hcd 0000:00:01.2: irq 26, pci mem 0x48002000
ehci_hcd 0000:00:01.2: new USB bus registered, assigned bus number 1
ehci_hcd 0000:00:01.2: park 0
ehci_hcd 0000:00:01.2: USB 2.0 initialized, EHCI 1.00, driver 10 Dec 2004
hub 1-0:1.0: USB hub found
hub 1-0:1.0: 5 ports detected
PCI: enabling device 0000:00:01.0 (0140 -> 0142)
ohci_hcd 0000:00:01.0: OHCI Host Controller
ohci_hcd 0000:00:01.0: irq 28, pci mem 0x48000000
ohci_hcd 0000:00:01.0: new USB bus registered, assigned bus number 2
hub 2-0:1.0: USB hub found
hub 2-0:1.0: 3 ports detected
PCI: enabling device 0000:00:01.1 (0140 -> 0142)
ohci_hcd 0000:00:01.1: OHCI Host Controller
ohci_hcd 0000:00:01.1: irq 27, pci mem 0x48001000
ohci_hcd 0000:00:01.1: new USB bus registered, assigned bus number 3
hub 3-0:1.0: USB hub found
hub 3-0:1.0: 2 ports detected
Initializing USB Mass Storage driver...
usb 1-2: new high speed USB device using ehci_hcd and address 2
usbcore: registered new driver usb-storage
USB Mass Storage support registered.
eth0: register usbnet at usb-0000:00:01.2-2, DLink DUB-E100 USB Ethernet
usbcore: registered new driver usbnet
i2c /dev entries driver
LOADED Xicor x1205 RTC Dvr v0.9.3.3NPW
get status = 0x00
NET: Registered protocol family 2
IP: routing cache hash table of 512 buckets, 4Kbytes
TCP established hash table entries: 2048 (order: 2, 16384 bytes)
TCP bind hash table entries: 2048 (order: 1, 8192 bytes)
TCP: Hash tables configured (established 2048 bind 2048)
NET: Registered protocol family 1
RAMDISK: Couldn't find valid RAM disk image starting at 0.
Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(1,0)

Debian Installation

We can E.G. use the initrd for the LART platform. This also needs to be byteswapped like the kernel image:

wget ftp://ftp.debian.org/debian/dists/sarge/main/installer-arm/current/images/lart/netboot/initrd.gz
sudo byteswap.py initrd.gz /var/lib/tftpboot/initrd-debian.gz-swap

• initrd-debian.gz-swap (1.6M)

This can then be loaded into Redboot together with the kernel. Remember to connect your USB ethernet adapter and USB hard drive:

IP: 192.168.0.1/255.255.255.0, Gateway: 192.168.0.1
Default server: 0.0.0.0, DNS server IP: 0.0.0.0

RedBoot(tm) bootstrap and debug environment [ROMRAM]
Red Hat certified release, version 1.92 - built 15:16:07, Feb  3 2004

Platform: IXDP425 Development Platform (XScale)
Copyright (C) 2000, 2001, 2002, Red Hat, Inc.

RAM: 0x00000000-0x02000000, 0x000723a0-0x01ff3000 available
FLASH: 0x50000000 - 0x50800000, 64 blocks of 0x00020000 bytes each.
== Executing boot script in 2.000 seconds - enter ^C to abort
^C
RedBoot> ip_address -l 192.168.1.77 -h 192.168.1.100
IP: 192.168.1.77/255.255.255.0, Gateway: 192.168.0.1
Default server: 192.168.1.100, DNS server IP: 0.0.0.0
RedBoot> load -r -v -b 0x01d00000 zImage-swap
Raw file loaded 0x01d00000-0x01defd5f, assumed entry at 0x01d00000
RedBoot> load -r -v -b 0x01000000 initrd-debian.gz-swap
Raw file loaded 0x01000000-0x01187b83, assumed entry at 0x01000000
RedBoot> exec 0x01d00000
...

The installer will complain about low memory, but it will continue:

Later after configuring network and Debian mirror it will also complain about missing kernel modules. Ignore this and continue without selecting any additional installer components:

Next step is partitioning. You don't have to use the same setup, but it's easier if you also have /dev/sda2 as rootfs, as you can then use the precompiled kernel:

Follow the rest of the installation through and you will finally get a warning that the installer didn't recognize the bootloader:

Ignore the warning and continue to reboot the system.

Boot From USB

Unfortunately it isn't possibly to directly boot of an USB mass storage device as the detection and partition scan happens after the kernel tries to mount the rootfs.

Luckily there is a kernel cmdline option called 'rootdelay' which forces the kernel to wait the requested number of seconds before mounting the rootfs. Using rootdelay=10 seems to do it for me, but you might need to increase it for slow disks.

We can then recompile the kernel with the proper cmdline and boot on the USB disk to finish the Debian installation.

Download:

• sda2.config (27K)
• zImage-sda2.swap (951K)

After selecting time zone, root passwd, mirror configuration and any additional packages the installation is finally completed:

Installing Modules

First make sure that the modules are built:

make ARCH=arm CROSS_COMPILE=armv5b-softfloat-linux-

sudo mount /dev/sda2 /mnt/usb

sudo make ARCH=arm CROSS_COMPILE=armv5b-softfloat-linux- INSTALL_MOD_PATH=/mnt/usb modules_install

• linux-2.6.11.12-modules.tar.bz2 (1.2M)

Writing the Kernel to Flash

The RedBoot on the NSLU2 expects to find the kernel in the flash at address 0x50060000 (/dev/mtd2). It also expects to find a 16 byte header before the kernel image. Notice that the kernel cannot be bigger than 1MB!

The format of this header is:

• Byte 0-3: Size of kernel in bytes (big endian format)
• Byte 4-15: Zeros

This can be done with the following little python script:

== flashimage.py snip start ==
#!/usr/bin/python
# Prepends RedBoot/Sercomm header to kernel image

import array, sys

if len(sys.argv) != 3:
  sys.stderr.write('Invalid arguments.\n')
  sys.stderr.write('Usage: %s <input> <output>\n' % sys.argv[0])
  sys.exit(1)

input = open(sys.argv[1], 'rb').read()

header = array.array('I',[0]*4)
# byte 0..3 = image size
header[0] = len(input)

# header in big endian format
if sys.byteorder != 'big':
  header.byteswap()

output = open(sys.argv[2], 'wb')
header.tofile(output)
output.write(input)
== flashimage.py snip end ==

Remember to first byteswap your kernel image with byteswap.py before running flashimage.py on it! E.G.:

flashimage.py zImage-sda2-swap kernel.img

Alternatively you can download a precompiled version of it:

• kernel.img (951K)

This can then be put on the tftp server and loaded into RAM by RedBoot and from there written to flash:

RedBoot(tm) bootstrap and debug environment [ROMRAM]
Red Hat certified release, version 1.92 - built 15:16:07, Feb  3 2004

Platform: IXDP425 Development Platform (XScale)
Copyright (C) 2000, 2001, 2002, Red Hat, Inc.

RAM: 0x00000000-0x02000000, 0x000723a0-0x01ff3000 available
FLASH: 0x50000000 - 0x50800000, 64 blocks of 0x00020000 bytes each.
== Executing boot script in 2.000 seconds - enter ^C to abort
^C
RedBoot> ip_address -l 192.168.1.77 -h 192.168.1.100
IP: 192.168.1.77/255.255.255.0, Gateway: 192.168.0.1
Default server: 192.168.1.100, DNS server IP: 0.0.0.0
RedBoot> load -r -v -b 0x01d00000 kernel.img
Raw file loaded 0x01d00000-0x01defd4f, assumed entry at 0x01d00000
RedBoot> fis write -f 0x50060000 -b 0x01d00000 -l 0x100000
* CAUTION * about to program FLASH
            at 0x50060000..0x5015ffff from 0x01d00000 - continue (y/n)? y
... Erase from 0x50060000-0x50160000: ........
RedBoot> reset

The kernel is now automatically loaded by the standard RedBoot bootscript.

Conclusion

It would be interesting to be able to install Debian without the serial port hack. Several methods could be possible: DONE

• Use the preseed support in the Debian-installer to create an installer which doesn't need user interaction. See DebianInstallerPreseed for more info.
• Get the network-console support in Debian-installer running so the installation can be performed over ssh. See DebianInstallerNetworkConsole for more info.
• Simply provide a disk image of an installed base system with ssh running which can be written to USB stick / drive.

I would like to thank the nice people behind the nslu2-linux project - a lot of the information here is based on their work.

A DebianSlug project has been started on nslu2-linux.org to create an easy to install firmware image for running Debian on the NSLU2. Stay tuned for more information.

If you have any comments or questions you are welcome to contact me.