Installing U-Boot for LinkStation V2

For U-Boot port version 1.0.1
20 September 2007

Copyright (c) 2007 Mihai Georgian

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. The full text of the license can be obtained by clicking on the above link.

No liability for the contents of this document can be accepted. The information in this document is provided in good faith but no warranty can be made for its accuracy and the author does not take any responsibility. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system.

Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.



WARNING

Flashing the LinkStation with unauthorised firmare voids your warranty. When installing firmware on an embedded computer things can and, sometimes, do go wrong. The power can go down in the middle of the flash operation or the flash write can fail rendering your LinkStation unusable. Please read this entire page carefully before attempting to install U-Boot.

If you are not prepared to brick your LinkStation, do not attempt to install U-Boot

Introduction

U-Boot for the LinkStation is distributed as a source patch against u-boot-1.1.4. To compile it you will need either a cross toolchain installed on your PC or native development tools installed on your LinkStation. These instructions assume that you are running Linux on a X86 PC and that you are using a cross toolchain.

A kernel module, uloader.o, allows testing U-Boot without burning it into flash. It is strongly recommended that you test U-Boot using a RAM build before attempting to burn it into flash. Once you are satisfied with the RAM build, you can use it to install the ROM version.

Supported Hardware

The LinkStation port of U-Boot described in this document supports the MIPS based Linkstation V2 (model HD-HLAN-2).

This version of U-Boot will certainly not work on the the LinkStation version 1 (model HD-HLAN-1) or on the LinkStation HG (model HD-HGLAN) as these models are based on PowerPC processors. Attempting to flash a LinkStation version 1 or a LinkStation HG with MIPS firmware it is guaranteed to make it completely unusable.

Get Command Prompt Access

To install U-Boot, you will need command prompt access to the LinkStation. For this, the simplest way is to install OpenLink.

U-Boot Consoles

Read about U-Boot consoles to learn how to control U-Boot.

Install the Serial Console

Installing the serial console is not an absolute requirement and it will void your warranty. U-Boot can be installed and controlled without it. However, the serial console will give you the best control over both U-Boot and Linux.

Read The Serial Port for the LinkStation V2 to learn what is special about the serial port and Add a Serial port to the MIPS Linkstation to learn how to install the serial console.

Install netcat (nc)

Netcat is a networking utility which reads and writes data across network connections, using the UDP protocol. It comes standard with most Linux distributions. For more information, visit the netcat home page http://netcat.sourceforge.net for the UNIX version or http://www.vulnwatch.org/netcat for the Windows version.

Get the ELDK

If you don't have a cross toolchain installed, download the DENX Embedded Linux Development Kit (ELDK) from http://ftp.sunet.se/pub/Linux/distributions/eldk/4.0/mips-linux-x86/iso/ install it and spend some time getting familiar with it.

Note: As a final step in the ELDK installation process you will need to create a file that you can source to set up the ELDK environment. The file can be anywhere but the best place is in the directory where you installed the ELDK. I called my file config_4kcle.

ELDK_HOME=<your ELDK installation directory>
PATH=$PATH:$ELDK_HOME/usr/bin:$ELDK_HOME/bin
export CROSS_COMPILE=mips_4KCle-

Preparation

Download the tarball for u-boot-1.1.4 ftp://ftp.denx.de/pub/u-boot/u-boot-1.1.4.tar.bz2
Download the patch for the LinkStation V2 u-boot-1.1.4-list-v2-1.0.1.diff.gz.
Download the uloader module for the LinkStation V2 uloader-ls2.tar.gz
Download the test kernel for the LinkStation V2 vmlinuz.
Note: Vmlinuz has been extracted from the LinkStation flash (firmware version 2.05) and has been converted to gziped ELF format.

Create a directory where to untar the uloader archive. The archive contains the source code, a binary module compiled for the original LinkStation V2 kernel and a simple bash script to load and start a RAM build of U-Boot. Copy the binary module, the bash script and the test kernel to your LinkStation.

# mount -t smbfs -o password="" //<your_linkstation_name_or_ip>/share /mnt
# cp uloader.o /mnt
# cp u-boot-load.sh /mnt
# cp <your-download-directory>/vmlinuz /mnt
# umount /mmt

Telnet to your LinkStation, create the boot directory (/boot) and move the test kernel into it. The examples below assume that you have installed OpenLink where telenet drops you directly to a root command prompt. The commands are shown in bold. Replace lsv2 in the examples with the name / IP address of your LinkStation.

# telnet lsv2
Trying 192.168.0.243...
Connected to 192.168.0.243.
Escape character is '^]'.

bash-2.05a# cd /
bash-2.05a# mkdir boot
bash-2.05a# cd boot
bash-2.05a# mv /mnt/hda/share/vmlinuz .
bash-2.05a# chown root:root vmlinuz
bash-2.05a# chmod 664 vmlinuz
bash-2.05a# exit
exit
Connection closed by foreign host.
#

Go to where you chose to build U-Boot, untar u-boot-1.1.4 and apply the patch. The archive will be untared in ./u-boot-1.1.4/.

# tar xjf <your-download-directory>/u-boot-1.1.4.tar.bz2
# cd u-boot-1.1.4
# gunzip -c <your-download-directory>/u-boot-1.1.4-list-v2-1.0.0.diff.gz | patch -p1

Source your ELDK environment.

# . <your ELDK installation directory>/config_4kcle

Configure

Edit include/configs/ls2.h and set the following variables for your environment:

CONFIG_IPADDR_LS  -  the IP address of your LinkStation while running U-Boot (mandatory). The default address is 192.168.11.150.
CONFIG_SERVERIP_LS  -  the IP address of the NFS/TFTP/DHCP/BOOTP server, normally the address of your Linux PC (mandatory). The default address is 192.168.11.149.
CONFIG_NCIP_LS  -  the address of the computer running netcat (nc), normally the address of your Linux PC (optional). If the define is missing, CONFIG_NCIP_LS will be set to the same value as CONFIG_SERVERIP_LS

RAM Build

# make linkstation_v2_ram_config
# make linkstation_v2_ram

The name of the resulting binary is u-boot-v2-mips.ram.bin

Load and Test

Mount the LinkStation SMB public share and copy the U-Boot binary to it:

# mount -t smbfs -o password="" //<your_linkstation_name_or_ip>/share /mnt
# cp u-boot-v2-mips.ram.bin /mnt
# umount /mmt

If you installed the serial port, open another window and use minicom to connect to your LinkStation serial console. The serial port settings are 57600,8,N,1 the same as the settings used by the original Linux kernel. You need to set the serial port jumper to "on" and to boot with the microcontroller disabled (by pressing and holding the reset button while turning the power on).

Start netcat to communicate with the U-Boot net console. Open another window and run board/linkstation/nc.sh. Nc.sh is a simple script which invokes netcat with the correct options. To quit nc, press ^T (control-T).

# board/linkstation/nc.sh <your_linkstation_name_or_ip>

Where <your_linkstation_name_or_ip> is CONFIG_IPADDR_LS (see Configure U-Boot above). When you run nc.sh nothing will be written to the screen. This is normal as Linux is not using the net console.

From your original window, use telnet to connect to the LinkStation and launch U-Boot.

# telnet lsv2
Trying 192.168.0.243...
Connected to 192.168.0.243.
Escape character is '^]'.

bash-2.05a# cd /mnt/hda/share
bash-2.05a# ./u-boot-load.sh
bash-2.05a# exit
exit
Connection closed by foreign host.
#

In a few moments you should see the U-Boot startup messages on the net console screen.

U-Boot 1.1.4 LiSt V2 (mips) 1.0.0 (Jul 28 2007 - 18:54:52)
IDE:    Bus 0: OK
  Device 0: Model: Maxtor 7Y250P0 Firm: YAR41BW0 Ser#: Y62W8PDE
            Type: Hard Disk
            Supports 48-bit addressing
            Capacity: 239372.4 MB = 233.7 GB (490234752 x 512)
Boot in 10 seconds ('s' to stop)...

Press 's' on your keyboard to stop the boot process.

If you want to use the serial console, you will have to switch to it from the net console. Run:

=> run ser

from the net console prompt. Remember that you have to have the console jumper "on" and boot with the microcontroller watchdog disabled if you want to use the serial console. U-Boot reads the state of the jumper and does not use the serial console if the jumper is off.

Using u-boot-load.sh leads to the above results on devices with standard OpenLink installed. On some LinkStations reboot has been modified to send a reboot command to the microcontroller. This is indicated by the fast blinking of the power LED immediately after running u-boot-load.sh. Once the microcontroller receives a reboot command, the reboot process cannot be stopped. The microcontroller will reboot the LinkStation 5 min after receiving the reboot command.

If you find yourself in the above situation you can only test the RAM build of U-Boot by booting your LinkStation with the microcontroller watchdog disabled. Now you can use the procedure described above with one caveat: when the microcontroller watchdog is disabled, pressing the buttons will have no effect so you will not be able to test the behaviour of the minimal console. When you finish testing, press and hold the power button and the LinkStation will power off.

Once you get the U-Boot command prompt, start testing it. Read the U-Boot documentation and try each command you are interested in.

Keep in mind that U-Boot interprets all input number as hex numbers. If, for example, you type 256, U-Boot will interpret it as 598 decimal.

When you are testing memory write commands, do not attempt to write to the last 4 MB of memory (0x83C00000 to 0x83FFFFFF) as you will be overwriting U-Boot itself and remember that addresses in the range 0xBFC00000 to 0xBFCFFFFF are flash address. Moreover, U-Boot doesn't initialise the TLBs so addresses in KSEG0, KSEG2 and KSEG3 cannot be used. If you try to write to or read from any of the addresses above, U-Boot will freeze as the access will generate a TLB exception and U-Boot doesn't have code to service it.

An important command is flinfo which displays information about the flash chip. If the information displayed is correct for your flash, test the flash erase and flash write commands. To do this, you will need to find an empty sector, one for which each byte is 0xFF. Hint: check the last flash sector first, chances are that it's empty. When you are testing commands that write to the flash, always remember that you can write a single byte but you can only erase whole sectors.

Be very careful not to write to the flash memory range 0xBFC00000 to 0xBFFBFFFF. This area contains the the bootloder, the Linux kernel (with embedded RAM disk used for EM), the ethernet MAC address and kernel command line. The range 0xBFFC0000 to 0xBFFFFFFF is the user area and stored the configuration files. The configuration files don't take up too much space so there is a sizable amount of unused space at the end of the flash. Always check using the U-Boot command md (memory display) if the flash area you intend to use is empty (all bytes are 0xFF). For more information about the flash organisation, read Information/MIPSelFlashROM

ROM Build

Once you are happy with the RAM build, you are ready for the ROM build.

# make linkstation_v2_config
# make linkstation_v2

The name of the resulting binary is u-boot-v2-mips.flash.bin

Install

Flashing U-Boot from U-Boot

The RAM build of U-Boot can be used to load and flash the ROM build. This is the preferred method.

Boot your LinkStation normally. Open a telnet session and create a directory to hold the U-Boot flash image and copy the U-Boot flash image to your LinkStation SMB share in the directory u-boot.

# telnet lsv2
Trying 192.168.0.243...
Connected to 192.168.0.243.
Escape character is '^]'.

bash-2.05a# cd /mnt/hda/share
bash-2.05a# mkdir u-boot
bash-2.05a# exit
exit
Connection closed by foreign host.
# mount -t smbfs -o password="" //lsv2/share /mnt
# cp u-boot-v2-mips.flash.bin /mnt/u-boot
# umount /mmt

Load the RAM build of U-Boot and at the U-Boot command prompt type:

=> run upgrade

U-Boot will attempt to load the ROM build from the directory share/u-boot/ on the third partition of the hard drive. If the load is successful, it will do the following:

  1. unprotect the bootloader area;
  2. erase the bootloader area;
  3. copy the loaded file to the bootloader area;
  4. verify the copy;

Here is the output of run upgrade

=> run upgrade
Loading 0:3:share/u-boot/u-boot-v2-mips.flash.bin

164604 bytes read
Un-Protected 3 sectors

Flash erase: first = 0 @ 0xbfc00000
             last  = 2 @ 0xbfc20000
Flash erase: Done
Erased 3 sectors
Copy to Flash... done
Total of 164604 bytes were the same
=> 

When the above sequence finishes, U-Boot returns to the command prompt (=>).

Depending on your flash chip, the flash operation can take a long time. Wait patiently and do not try to power down or otherwise interrupt the flash or you will end up with a brick.

Reboot:

=> reset

Note: The reset command will not work if you have booted with the microcontroller disabled.

The power LED should start blinking slowly and you should see the U-Boot startup messages in the net console. Your LinkStation is now running U-Boot.

Flashing U-Boot from Linux

Connect to your LinkStation using either the serial port or telnet.

# telnet lsv2
Trying 192.168.0.243...
Connected to 192.168.0.243.
Escape character is '^]'.

bash-2.05a# cd /mnt/hda/share/u-boot
bash-2.05a# dd if=u-boot-v2-mips.flash.bin of=/dev/mtd0 bs=1k
bash-2.05a# cmp u-boot-v2-mips.flash.bin /dev/mtd0

If the Flash Fails

If the flash was not written correctly but U-Boot returns at the command prompt, try to re-run run upgrade.

If the same happens when you attempt to install U-Boot from Linux, try to dd again.

If your flash fails completely, for example due to a power failure, all is not completely lost. You can still use a JTAG cable to re-flash your Linkstation. Unfortunately, this is a relatively complicated and expensive solution as it involves acquiring or building the JTAG cable and soldering the header for it on the LinkStation motherboard. For more information on how to use a JTAG cable with the LinkStation you can visit www.nas-central.org.

EM Mode

EM mode is entered by setting the root device to the initial RAM disk (initrd). This is done with the command line option root=/dev/ram0. The original LinkStation kernel is compiled with a small initrd embedded and it is looking for the kernel parameters in flash at address 0xbffb0000. The kernel parameter root is normally set to /dev/hda1 but if the kernel cannot mount /dev/hda1 in the course of a normal boot, it will set root to /dev/ram0 which will force the LinkStation into EM mode at next boot.

The above behaviour was chosen probably because the original boot loader cannot be controlled. It just initialises the hardware and boots the kernel. U-Boot, however, is capable of passing parameters to the kernel and it is recommendable that you replace the original kernel with one capable of reading the parameters passed by the kernel instead of reading them from flash. In fact, with U-Boot installed, you don't need to boot in EM mode anymore. You can simply boot over nfs and use a nfs-mounted root filesystem to restore the system. The ELDK comes with a full nfs environment and instructions for using it.

Advanced configuration

The initial U-Boot configuration can be changed by editing the file include/configs/linkstation.h.

In all the examples below, please note the backslash-zero (\0) at the end of the strings and the space-backslash ( \) at the end of each lines and do not change them.

Change the name of the default boot file

Search for the lines containing:

"hdpart=0:1\0" \
"hdfile=boot/vmlinux.UBoot\0" \

and change them to the values you want. Partition 0:1 means disk 0, partition 1. Obviously, you can only change the partition number as there is only one disk. The name of the file must be given relative to the root of the partition.

Change the default console to the serial console

Search for the lines containing:

"stdin=nc\0" \
"stdout=nc\0" \
"stderr=nc\0" \

and change them to:

"stdin=serial\0" \
"stdout=serial\0" \
"stderr=serial\0" \

Change the default boot command to boot from flash

Search for the lines containing:

"bootcmd1=run hdboot;run flboot\0" \
"bootcmd2=run flboot\0" \

and change them to:

"bootcmd1=run flboot\0" \
"bootcmd2=run hdboot;run flboot\0" \