This HOWTO is obsolete and is provided here for historical purposes only. Please see this page for updated instructions.
This document describes how to install an OpenWrt kernel and rootfs on the internal NAND flash of the Seagate FreeAgent DockStar™ so that it will boot into OpenWrt at power-on, with no USB storage device required.
The main method presented here does not require opening the case or attaching a serial cable, just using the Linux command line on the DockStar. But I also describe a method that does use a serial cable to interact with the u-boot bootloader. This was the approach I initially used to get OpenWrt working on the DockStar, but it should only be necessary now if the first approach fails for some reason.
If you've never used OpenWrt before,
this guide
is a good starting point.
Further help can be found by searching
the OpenWrt Wiki,
the OpenWrt forums,
or asking on the #openwrt IRC channel on
irc.freenode.net.
Important: if possible, do not connect your DockStar to the outside Internet prior to re-flashing. Otherwise the factory firmware will automatically "phone home" and modify itself, making it more difficult to connect via ssh.
If you don't want to compile your own OpenWrt firmware, you can simply download a pre-built kernel image and root filesystem image.
Obtain the kernel and rootfs images as described above. Copy them to a USB flash drive.
Download the blparam program from Cloud Engines and copy it to the USB drive.
Follow Alexander Holler's instructions to connect to your DockStar via ssh. If you previously connected the DockStar to the Internet, you might have to follow these instructions instead.
The following instructions should be executed on the DockStar.
Kill off some unneeded processes:
# killall -9 hbwd # killall -9 hbplug
Insert the USB drive in the DockStar, mount it somewhere, and change to that directory:
# mount /dev/sda1 /mnt # cd /mnt
Make a backup of the factory firmware onto the USB drive if you think you might want to restore it some day.
Set the magic u-boot parameters. These are case-sensitive, so make sure you type them correctly.
# ./blparam arcNumber=2097 # ./blparam mainlineLinux=yes
Now you're ready to flash the kernel and rootfs images onto your
DockStar. WARNING: perform the following steps in exactly this
order, and double-check everything you type before
hitting return. If you overwrite the u-boot partition by
mistake, you will brick your DockStar and you will have to
use a JTAG cable to recover.
# flash_eraseall /dev/mtd1 # nandwrite /dev/mtd1 dockstar-uImage # flash_eraseall /dev/mtd2 # nandwrite /dev/mtd2 dockstar-rootfs
Erase the rootfs_data partition so that OpenWrt will
create a jffs2 overlay filesystem there when it boots. It's OK if
this step fails with a "read-only filesystem" error.
# flash_eraseall /dev/mtd3
That's all there is to it. Unmount and remove the USB drive and power-cycle the DockStar. It should reboot into OpenWrt.
If you're using my pre-built images, it will request an IP address via
DHCP. If you compiled your own firmware and
didn't change the default configuration, it will use the static
address 192.168.1.1.
After you've installed OpenWrt on your DockStar, configured it to your liking, and used it for a while, you will eventually want to upgrade the firmware (to a new OpenWrt release, or a custom build with additional kernel modules, for example).
I've used the following procedure to upgrade my DockStar from one version of OpenWrt to another.
Make a backup of your DockStar, because you will be re-flashing it to
the default configuration. I use rsync for this.
Copy at least the /etc/config directory. Depending on
your setup you may want to back up additional files. It's also useful
to save the list of additional packages you've installed:
# opkg list_installed
Build or download the new firmware (uImage and rootfs) that you want
to flash. Make sure the files are padded to a 128K multiple.
Transfer them to the /tmp directory on the DockStar using
scp, rsync, or a USB drive.
Login to the DockStar and execute the following. You may need to
install the mtd-utils package on your DockStar if
the flash_eraseall and nandwrite utilities
are not found.
# cd /tmp # md5sum new-uImage new-rootfs (verify that the MD5 checksums match the originals before proceeding) # flash_eraseall /dev/mtd1 # nandwrite /dev/mtd1 new-uImage # flash_eraseall /dev/mtd2 # nandwrite /dev/mtd2 new-rootfs
The /dev/mtd3 partition is in use by a mounted filesystem
(/overlay) so you need to reboot immediately after
erasing it:
# flash_eraseall /dev/mtd3 # reboot
If everything goes well, your DockStar will reboot with the new kernel and root filesystem. Now you can restore the configuration you backed up in the first step.
If you get the dreaded blinking orange LED, I'm afraid you will have to use a serial cable to recover.
Here are some things I've found helpful when using my DockStar with OpenWrt.
You can use the Luci web interface
(under System > LED Configuration)
to set up the LEDs, or edit /etc/config/system.
For example, I have my green LED configured to blink on
network activity using the following settings:
config led option sysfs 'dockstar:green:health' option trigger netdev option dev eth0 option mode 'link tx rx'
If you're not using the top connector for a Seagate FreeAgent Go™ drive, I recommend a female 5-pin mini-USB to female USB adapter (available here or here). They fit well and make the top connector more useful for conventional USB devices. It would be nicer if they came in white, but you can't beat the price.
The instructions in this section are not needed if you use the pre-built images described above.
If you've never built the OpenWrt firmware before, please refer to this HOWTO.
You need to build your own OpenWrt kernel and root filesystem image, because OpenWrt's 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.
Use make kernel_menuconfig to add built-in SCSI disk, USB
EHCI, USB storage, and ext2 filesystem support. (This step isn't
required, but I recommend it. It will allow you to boot from a USB
flash drive if the root filesystem on internal flash is corrupted.)
Do an initial build.
Change to build_dir/linux-kirkwood/linux-2.6.30.10 and
apply the following patches, based on
work done by Alexander Holler <holler@ahsoftware.de>.
Support the DockStar flash layout and the OpenWrt naming scheme:
--- 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
},
Support the DockStar LEDs:
diff --git a/arch/arm/mach-kirkwood/sheevaplug-setup.c b/arch/arm/mach-kirkwood/sheevaplug-setup.c
index 555f7c3..648c741 100644
--- 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
};
Rebuild the kernel with make at the top level. The kernel
image will be in bin/kirkwood/openwrt-kirkwood-uImage.
Pad the kernel image to a multiple of 128K bytes:
# dd if=openwrt-kirkwood-uImage of=dockstar-uImage bs=128k conv=sync
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=dockstar-rootfs bs=128k conv=sync
to pad the (rootfs-only) squashfs file to a 128K multiple.
As mentioned above, this approach should normally not be necessary. But if your DockStar fails to boot with the previous method, this approach may work. See also the "Troubleshooting" section below.
Prepare the kernel and rootfs images as described above. Copy them to a TFTP server on your network.
Open the case and install a serial cable. See Alexander Holler's page for the serial pinout (and how to open the case) and this page for a picture of where to find the connector.
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 see the u-boot output as it boots. Type any character to interrupt the boot sequence:
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)
Now you're ready to flash the kernel and rootfs images onto your
DockStar. WARNING: perform the following steps in exactly this
order, and double-check everything you type before
hitting return. If you overwrite the u-boot partition by
mistake, you will brick your DockStar and you will have to
use a JTAG cable to recover.
CE>> mw 0x800000 0 0x100000 CE>> tftpboot 0x800000 dockstar-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 0x800000 0x100000 0x100000 # or larger size if needed CE>> mw 0x800000 0 0x200000 CE>> tftpboot 0x800000 dockstar-rootfs # as above, make sure 0x200000 is larger than the rootfs image size, or adjust accordingly # CAREFULLY erase the rootfs partition and flash it with new squashfs image CE>> nand erase 0x500000 0x2000000 CE>> nand write.e 0x800000 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
Set some magic u-boot parameters and save them:
CE>> setenv arcNumber 2097 CE>> setenv mainlineLinux yes CE>> saveenv
Type reset, or just power-cycle the DockStar. It should
boot into OpenWrt.
While getting this to work, I occasionally observed incorrect writes to the rootfs partition. If your kernel boots but fails to find the root filesystem due to errors in the squashfs root partition, that might be the problem. (But that symptom can also be caused by flashing a squashfs image that is not 128K-aligned, so check that also.) The following steps may allow you to recover.
If you didn't do the "recommended" part of configuring your kernel (enabling support for USB storage and ext2), do it now, then rebuild the kernel and re-flash it.
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 dockstar-rootfs
image onto the drive (as a regular file).
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.
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.)
Use the mtd-utils commands to flash
the /dev/mtd2 partition:
# flash_eraseall /dev/mtd2 # nandwrite /dev/mtd2 /dockstar-rootfs
Type reboot and hope that your rootfs partition is now correct.
It should be possible to restore the factory firmware by following the instructions in this thread.
