This post describes how to install an OpenWrt kernel and rootfs on the internal NAND flash of the Seagate Dockstar so that it will boot into OpenWrt at power-on, with no USB storage device required.

Update: I've consolidated this HOWTO and the following one into a single guide to installing OpenWrt on the Dockstar.

WARNING: this approach requires you to open the case and install a serial cable, and completely replaces the factory-installed software with OpenWrt. No one has tried to restore the factory firmware yet, so we don't know whether that's possible. Proceed at your own risk.

1. Open the case and install a serial cable. See this page for the serial pinout (and how to open the case) and this page for a picture of where to find the connector.

2. You need to build your own OpenWrt kernel and root filesystem image, because the Marvell Kirkwood target currently supports only the Sheevaplug, which has a different NAND flash layout.

Use "make menuconfig" to configure the build system for a kirkwood target. Add squashfs in the target images section. Also select built-in luci and ntpclient packages.

(This step isn't required, but I recommend it for easier recovery from bad flash writes below.) Use "make kernel_menuconfig" to add built-in SCSI disk, USB EHCI, USB storage, and ext2 filesystem support.

Do an initial build.

3. Change to build_dir/linux-kirkwood/linux-2.6.30.10 and apply the following patch:

--- a/arch/arm/mach-kirkwood/sheevaplug-setup.c
+++ b/arch/arm/mach-kirkwood/sheevaplug-setup.c
@@ -33,7 +33,11 @@ static struct mtd_partition sheevaplug_nand_parts[] = {
                .offset = MTDPART_OFS_NXTBLK,
                .size = SZ_4M
        }, {
-               .name = "root",
+               .name = "rootfs",
+               .offset = MTDPART_OFS_NXTBLK,
+               .size = SZ_32M
+       }, {
+               .name = "rootfs_data",
                .offset = MTDPART_OFS_NXTBLK,
                .size = MTDPART_SIZ_FULL
        },

If you want to stop the LED from blinking, also apply this patch:

--- a/arch/arm/mach-kirkwood/sheevaplug-setup.c
+++ b/arch/arm/mach-kirkwood/sheevaplug-setup.c
@@ -62,9 +62,15 @@ static struct mvsdio_platform_data sheeva_esata_mvsdio_data = {
 
 static struct gpio_led sheevaplug_led_pins[] = {
        {
-               .name                   = "plug:green:health",
+               .name                   = "dockstar:green:health",
                .default_trigger        = "default-on",
-               .gpio                   = 49,
+               .gpio                   = 46, /* green */
+               .active_low             = 1,
+       },
+       {
+               .name                   = "dockstar:orange:misc",
+               .default_trigger        = "none",
+               .gpio                   = 47, /* orange */
                .active_low             = 1,
        },
 };
@@ -84,7 +90,8 @@ static struct platform_device sheevaplug_leds = {
 
 static unsigned int sheevaplug_mpp_config[] __initdata = {
        MPP29_GPIO,     /* USB Power Enable */
-       MPP49_GPIO,     /* LED */
+       MPP46_GPIO,     /* LED green */
+       MPP47_GPIO,     /* LED orange */
        0
 };

(Both of the above patches are based on work done by Alexander Holler <holler@ahsoftware.de>)

Rebuild the kernel with "make" at the top level.  The build system will only need to rebuild the kernel.

4. Copy the kernel image from bin/kirkwood/openwrt-kirkwood-uImage to a TFTP server on your network.

5. Prepare the rootfs image. Do not use the squashfs file in bin/kirkwood. (It is a combined image with both the kernel and the root filesystem.) Instead, cd to build_dir/linux-kirkwood and run the command

dd if=root.squashfs of=openwrt-kirkwood-rootfs.squashfs conv=sync bs=128k

This pads the (rootfs-only) squashfs file to a 128K multiple. Copy the resulting openwrt-kirkwood-rootfs.squashfs to the TFTP server.

6. Connect your Dockstar to your network and use a terminal program like minicom to connect to it (speed 115200, no flow control). Power-on the Dockstar. You should be able to see the output of the u-boot bootloader as it boots, and if you type any character you can interrupt the boot sequence and interact with u-boot.  You should see something like this:

U-Boot 1.1.4 (Jul 16 2009 - 21:02:16) Cloud Engines (3.4.16)

U-Boot code: 00600000 -> 0067FFF0  BSS: -> 00690D60

Soc: 88F6281 A0 (DDR2)
CPU running @ 1200Mhz L2 running @ 400Mhz
SysClock = 400Mhz , TClock = 200Mhz

DRAM CAS Latency = 5 tRP = 5 tRAS = 18 tRCD=6
DRAM CS[0] base 0x00000000   size 128MB
DRAM Total size 128MB  16bit width
Flash:  0 kB
Addresses 8M - 0M are saved for the U-Boot usage.
Mem malloc Initialization (8M - 7M): Done
NAND:256 MB

CPU : Marvell Feroceon (Rev 1)
CLOUD ENGINES BOARD: REDSTONE:1.0

Streaming disabled
Write allocate disabled


USB 0: host mode
PEX 0: interface detected no Link.
Net:   egiga0 [PRIME], egiga1
Hit any key to stop autoboot:  0
CE>>

Use the "setenv" command in u-boot to set the ipaddr and netmask variables for the Dockstar's IP address, and the serverip variable to the IP address of your TFTP server.  Check that you have connectivity by doing

CE>> ping $(serverip)

7. Now you're ready to flash the kernel and rootfs images onto your Dockstar. Warning: double-check everything you type before hitting "return".  If you overwrite the u-boot partition by mistake, you will brick your Dockstar.

CE>> mw 0x1000000 0 0x100000
CE>> tftpboot 0x1000000 openwrt-kirkwood-uImage
# take note of the "bytes transferred in hex and make sure that it's less than 0x100000
# if not, redo the "mw" command above with a larger size, and use that size in the commands below

# CAREFULLY erase the uImage partition and flash it with the new kernel
CE>> nand erase 0x100000 0x400000
CE>> nand write.e 0x1000000 0x100000 0x100000  # or larger size if needed

CE>> mw 0x1000000 0 0x200000
CE>> tftpboot 0x1000000 openwrt-kirkwood-rootfs.squashfs
# as above, make sure 0x200000 is larger than the rootfs image size, and adjust accordingly

# CAREFULLY erase the rootfs partition and flash it with new squashfs image
CE>> nand erase 0x500000 0x2000000
CE>> nand write.e 0x1000000 0x500000 0x200000  # or larger size if needed

# CAREFULLY erase the rootfs_data partition so openwrt will create a jffs2 overlay filesystem
CE>> nand erase 0x2500000 0xdb00000

8. Set some magic u-boot parameters and save them:

CE>> setenv arcNumber 2097
CE>> setenv mainlineLinux yes
CE>> saveenv

9. Try it!  Type "reset", or just power-cycle the Dockstar.  It should boot into OpenWrt.

Troubleshooting

I have had problems with incorrect flash writes for the second (rootfs) partition.  If your kernel boots but prints error messages about errors in the squashfs root partition, that might be the problem.  Here's how I recovered from that.

1. If you didn't do the "recommended" part of step 2 (enabling support for USB storage and ext2 in the kernel), do it now. Rebuild the kernel and re-flash it.

2. Format a USB drive with one partition containing an ext2 filesystem. As root, un-tar the contents of bin/kirkwood/openwrt-kirkwood-rootfs.tar.gz onto the USB drive, and also copy the openwrt-kirkwood-rootfs.squashfs image onto the drive (as a regular file).

3. In u-boot, do

CE>> setenv bootargs_root root=/dev/sda1 rootdelay=10 rootfstype=ext2
CE>> boot

Your Dockstar should boot with the USB drive as its root filesystem.

4. Configure OpenWrt so that it can network to the outside world. Then do:

# opkg update
# opkg install mtd-utils

(Alternatively, you can copy the mtd-utils package, or its commands, onto the USB drive before booting the Dockstar.)

5. Use the mtd-utils commands to flash the mtd2 partition:

# flash_eraseall /dev/mtd2
# nandwrite /dev/mtd2 /openwrt-kirkwood-rootfs.squashfs

6. Type "reboot" and hope that your rootfs partition is now correct.

(Last edited by ecc on 10 Jul 2010, 01:20)

This post describes how to install OpenWrt on the Dockstar without opening the case (no serial cable required unless something goes wrong).

Update: I've consolidated this HOWTO and the previous one into a single guide to installing OpenWrt on the Dockstar.

WARNING: this approach completely replaces the factory-installed software with OpenWrt. No one has tried to restore the factory firmware yet, so we don't know whether that's possible. Proceed at your own risk.

Follow Alexander Holler's instructions to connect to your Dockstar via ssh. Make a backup of the factory firmware if desired.

Kill off some unneeded processes:

# killall -9 hbwd
# killall -9 hbplug

Follow steps 2 through 5 of the previous version of this HOWTO. (You can skip the part about copying the images to a TFTP server, since this approach uses a local USB flash drive instead.)

Make sure the kernel image is 128K-aligned:

# dd if=openwrt-kirkwood-uImage of=uImage bs=128k conv=sync
# mv uImage openwrt-kirkwood-uImage

Copy the kernel uImage and rootfs.squashfs files to a USB flash drive. Also download and copy the blparam program from Cloud Engines onto the USB drive.

Insert the USB drive in the Dockstar and mount it somewhere:

# mount /dev/sda1 /mnt

Set the magic u-boot parameters and flash the kernel and rootfs images:

# cd /mnt # or wherever you mounted the USB drive
# ./blparam arcNumber=2097
# ./blparam mainlineLinux=yes
# flash_eraseall /dev/mtd1
# nandwrite /dev/mtd1 openwrt-kirkwood-uImage
# flash_eraseall /dev/mtd2
# nandwrite /dev/mtd2 openwrt-kirkwood-rootfs.squashfs
# flash_eraseall /dev/mtd3  # (it's OK if this step fails with a "read-only filesystem" error)

That's all there is to it.  Remove the USB drive and power-cycle the Dockstar.  It should reboot into OpenWrt with the usual 192.168.1.1 IP address.

(Last edited by ecc on 10 Jul 2010, 01:21)

Many thanks for such excellent works!

If I understood you correctly, your hack is to flash the 1st 32MB NAND partition (completely wiping off the original DockStar firmware) and still leave the 2nd 224MB NAND partition untouched. Can you confirm this?

The patches to the kernel cause the NAND partitions to be as follows:

0x000000000000-0x000000100000 : "u-boot"
0x000000100000-0x000000500000 : "uImage"
0x000000500000-0x000002500000 : "rootfs"
0x000002500000-0x000010000000 : "rootfs_data"

The final partition (actually 219MB) is initially erased, but OpenWrt automatically creates a jffs2 filesystem there (because it's named "rootfs_data") and uses this as the writeable overlay on top of the read-only root.  See this page for some more details.

If I understood you correctly, a DockStar device will make use of the whole 256MB NAND space after performing your hack. If so, that is excellent.

Nice work!  I'd forgotten about those patches, fixing the led gpio control would be nice.

I think it might be a good idea to emphasize somewhere near your first warning disclaimer that it's currently not possible to restore the dockstar OS after erasing the kernel block.

One other suggestion - I'm pretty sure it's possible to do all the kernel configuration needed from within the buildroot config.  The kmod-scsi-core support is automatically selected when you pick usb mass storage, and I believe ehci is called kmod-usb2.

No, I built this against trunk: "KAMIKAZE (bleeding edge, r22087)" But I think they should apply to either tree (it's just one file in the 2.6.30.10 kernel).

I don't have any interest in trying, but why wouldn't the same approach restore the factory software (assuming one took backups of it before flashing)?  I.e., flash_eraseall and nandwrite from the running OpenWrt system?

I may have been doing something wrong, but when I did this I only got those components built as modules, not compiled into the kernel as required.  I think at the "make menuconfig" level, the only choices are "don't build", "build as module in the root image", or "build as separate ipkg".

I don't either, but someone will inevitably want to right after they've blasted the kernel.  I've tried a couple different methods of reading the kernel block with dd and none of the resultant files would pass the initial CRC check when I attempted to boot them.  But maybe I was doing something wrong.  The rootfs could be tarred up from the dockstar shell, so that shouldn't be an issue.

You may be correct.  I'm building an image now so I'll try booting from USB and see what happens.
EDIT: You are correct, my bad!

(Last edited by phat_bastard on 8 Jul 2010, 20:15)

I can't seem to get the patches to apply, I tried backfire and R22115

I suspect the tabs got replaced by spaces.  You can try "patch -l", which ignores white space, or use the patches in my updated HOWTO.

Is the LED patch supposed to make the LED turn solid green once the device has finished booting and is ready?

The kernel patch just makes the LEDs available to be controlled from user space:

# ls /sys/class/leds/
dockstar:green:health  dockstar:orange:misc

The default settings are:

# cd /sys/class/leds
# cat dockstar:green:health/trigger 
none nand-disk timer heartbeat [default-on] netdev 
# cat dockstar:orange:misc/trigger 
[none] nand-disk timer heartbeat default-on netdev

which means that by default the LED is solid green after the kernel boots.

To make it green when the Ethernet is connected, and blink with network activity, you can do this:

# cd dockstar:green:health
# echo netdev > trigger
# echo eth0 > device_name
# echo link tx rx > mode

This can also be configured via the luci web interface, under "System > LED Configuration".

Excellent! I have my DockStar LED flash to indicate netdev activity. I sure would like the LED to emit a blue color like the LEDS on a Linksys PAP2. Can you tell us what value represents a blue color to replace for the LED to emit in the following code:

.gpio                   = 46, /* green */

BTW, the 1st patch for rootfs_data MTD partition seemed to have caused the rootfs mounted as RO. Any changes to the filesystem is done on the RAM space and won't sustain a reboot. Can you please confirm this?

(Last edited by mazilo on 12 Jul 2010, 14:13)

The "46" is the GPIO pin.  The color is determined by the hardware, and I'm pretty sure the DockStar doesn't have a blue LED. (Too bad, I like them too.)

If the rootfs_data (mtd3) partition was set up correctly, OpenWrt should mount it as an overlay:

# mount
/dev/root on /rom type squashfs (ro,relatime)
[...]
/dev/mtdblock3 on /overlay type jffs2 (rw,relatime)
mini_fo:/overlay on / type mini_fo (rw,relatime)

If you see this, then the changes are being written to the /overlay partition -- mini_fo is a lightweight "union filesystem".  So changes should be permanent across reboots.

If there is no overlay, or it shows up as a tmpfs filesystem rather than a jffs2 filesystem, then check your boot log (dmesg) output -- chances are OpenWrt is not able to mount the mtdblock3 device for some reason.  In that case you should be able to use "flash_eraseall /dev/mtd3" and reboot.

Oh well. So much for that.

I think perhaps the problem I encountered was due to the fact that I have my OpenWRT OS on an external USB partition and not on the original NAND/Flash drive.

I've attempted to follow the directions here:  http://www.cs.cmu.edu/~ecc/dockstar-howto.html

After I have done

./scripts/feeds update -a
svn up

I did "make menuconfig" according to the directions. 

I next did "make kernel_menuconfig".  When I exited the configuration application, it started compiling (or doing something), and put out many errors saying, "arm-openwrt-linux-uclibcgnueabi-gcc: Command not found".

I've no doubt omitted something simple--any idea what it would be?

I believe these are harmless error messages.

As mazilo said, these might be harmless (let us know if the subsequent build goes OK.) If not, you might have to perform an initial build (= "make" at the top level) to make the cross-tools first, and then do the "make kernel_menuconfig", and then do another build.  I probably never tried it in a truly "clean" environment.

That means you did not build your toolchain properly. Restart from scratch

1) Make distclean

2) Make menuconfig

3) Make world V=99

Even I built my OpenWRT firmware after a make distclean, it still shows the error messages, yet the firmware produced from this compilation works just fine. Honestly, I have no idea why it happens, except it works!

I actually have the same problem with the "arm-openwrt-linux-uclibcgnueabi-gcc: Command not found" in my built openSUSE 11.2 host, so I did the

make V=99 toolchain/install

and found out the error messages in the development packages GMP or MPFR, so I used "yast" to install the missing gmp-devel and mpfr-devel packages and then re-execute the "make" command to try again.  It seems to fix the problem with the missing development packages which do not exist in my host PC.

On my OpenSuSE v11.2, I have both gmp-devel and mpfr-devel packages already installed when I got those messages.

I think you better copy the error messages to this forum so that someone might be able to help you out.

I wanted to share my instructions if they can help anyone. They do require a serial cable to view the console, but they do not require any compiling. (You can just copy and paste basically) I also skip messing around with the mtd partitions and just use jffs2 on the whole thing:

http://wiki.xkyle.com/Install_Openwrt_o … e_Dockstar