U-boot bootloader

Das U-Boot

U-Boot is a universal boot loader released with full source code under the Gnu Public License (GPL).

For an overview of U-Boot, you can read Introduction to Das U-Boot, the universal open source bootloader. LinkStation port version 2.0 2 September 2006

http://www.linuxnotincluded.pwp.blueyonder.co.uk/linkstation/u-boot.html Copyright (c) 2006 Mihai Georgian E-mail your questions and comments at u-boot (at) linuxnotincluded (dot) org (dot) uk.

Supported Hardware
The LinkStation port of U-Boot described here supports the following PowerPC models:
 * 1) LinkStation version 1 (model HD-HLAN-1)
 * 2) LinkStation HG (model HD-HGLAN)
 * 3) LinkStation HS (model HS-HGLAN)
 * 4) KuroBox standard
 * 5) KuroBox HG

To find out more about the different LinkStation and KuroBox models, visit: Buffalo/Melco Network Attached Storage Variants.

Features
pTPrrUYd8O8
 * supports serial console and net console (nc)
 * supports erasing and programming of the on-board flash ROM
 * supports file downloading
 * over the serial line
 * over the network (tftp, bootp, dhcp, nfs)
 * from the hard drive (supports both normal ext2 and LinkStation modified "ext2" file systems)
 * boots Linux (supports both U-Boot images and LinkStation "flashimg" images, including the original kernel from flash)
 * boots in EM mode
 * uses the LinkStation buttons as a minimal console
 * the power button (the big button at the front) to stop / start the boot process and to select the image to boot
 * the reset button to switch between consoles

=Supported Commands= ?      - alias for 'help' base   - print or set address offset bdinfo - print Board Info structure boot   - boot default, i.e., run 'bootcmd' bootd  - boot default, i.e., run 'bootcmd' bootm  - boot application image from memory bootp  - boot image via network using BootP/TFTP protocol cmp    - memory compare coninfo - print console devices and information cp     - memory copy crc32  - checksum calculation dhcp   - invoke DHCP client to obtain IP/boot params diskboot- boot from IDE device echo   - echo args to console erase  - erase FLASH memory ext2load- load binary file from a Ext2 filesystem ext2ls - list files in a directory (default /) flinfo - print FLASH memory information go     - start application at address 'addr' help   - print online help ide    - IDE sub-system loadb  - load binary file over serial line (kermit mode) loads  - load S-Record file over serial line loop   - infinite loop on address range md     - memory display mm     - memory modify (auto-incrementing) mtest  - simple RAM test mw     - memory write (fill) nfs    - boot image via network using NFS protocol nm     - memory modify (constant address) pci    - list and access PCI Configuration Space ping   - send ICMP ECHO_REQUEST to network host printenv- print environment variables protect - enable or disable FLASH write protection rarpboot- boot image via network using RARP/TFTP protocol reset  - Perform RESET of the CPU run    - run commands in an environment variable saveenv - save environment variables to persistent storage setenv - set environment variables tftpboot- boot image via network using TFTP protocol version - print monitor version

A useful document on u-boot is the u-Boot Refence Guide produced by FreeScale. This guide is targetted at a different processor to the one used in Buffalo products, but many of the commands are common and this document gives detailed examples of the syntax of those commands

RAM Build and Uloader
Normally, U-Boot resides in the on-board flash and starts executing at reset. It initialises the CPU, the memory controller and the serial port and then relocates itself at the upper end of the RAM area. After relocation, U-Boot completes the hardware initialisation and then it either proceeds to boot the OS kernel or displays a command prompt and waits for operator input.

U-Boot for the LinkStation can be configured for a RAM build. The only differences between the ROM and RAM builds are the absence of the basic initialisation code (which can only run from ROM) and the link address. You can test your RAM build using uloader.o which is a kernel module that was written specifically for the purpose of loading and starting a RAM build of U-Boot.

Even for the same model, there are hardware differences between the individual LinkStations and, due to these differences, U-Boot might not work properly in some instances. For example, your flash chip might not be supported by the current version of the U-Boot port. It is strongly recommend you test thoroughly U-Boot on your LinkStation using a RAM build before building the ROM version and attempting to burn it into flash. Once you have the RAM build up and running you can use it to install (burn) the ROM version.

Source Code
U-Boot for the LinkStation is distributed as a patch for U-Boot version 1.1.4. You can compile it using either a cross toolchain or, if you have a development environment installed, natively on your LinkStation. I used the DENX Embedded Linux Development Kit (ELDK) version 3.1.1 which comes with gcc 3.3.3 (gcc version 3.3.3 20040412 (Red Hat Linux 3.3.3-7)) with specific patches for PowerPC.

Uloader is distributed as a gzip-ed tar archive which contains the full source code, the binary module, uloader.o, compiled for the original LinkStation kernel and a simple bash script which uses uloader to load a RAM build of U-Boot and start it. Two tar archives are provided. The source code is the same in both archives. The binary module in the first archive has been compiled for the original LinkStation kernel 2.4.17_mvl21-sandpoint. The binary module in the second archive has been compiled for the original LinkStation HG kernel 2.4.20_mvl31-ppc_linkstation.

=Installing U-Boot for LinkStation=

Introduction
U-Boot for the LinkStation is distributed primarily as a source patch against u-boot-1.1.4. It is also possible to get pre-compiled versions for many of the Buffalo boxes from the NAS-Central downloads area.

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.

To allow testing of U-Boot on your LinkStation without burning it into flash, a kernel module named uloader.o is provided. Uloader allows you to use Linux to load a RAM build of U-Boot and start it. The RAM build of U-Boot is very close to the ROM build. The only differences are the absence of the basic initialisation code (which cannot run from RAM) and the link address. It is strongly recommended that you test U-Boot on your LinkStation using a RAM build before building the ROM version and attempting to burn it into flash. Once you have the RAM build up and running you can use it to install (burn) the ROM version.

Get telnet Access
To be able to make use of U-Boot you are going to need to be able to telnet into your LinkStation/KurBox using a user that has  level privileges.

Try to connect to your LinkStation using telnet. If you see the telnet command prompt, read CGI Exploit (PowerPC) original method of Hacking the LinkStation about how to get telnet access.

If the above method doesn't work for you, read Turn your LinkStation into a Kuro Box (PowerPC) for other methods to get telnet access.

The above methods do not work for the LinkStation HG. For this model, the only solution is to load a telnet-enabled version of the firmware. Read the pages about OpenLink and the firmware flasher

You can also try to flash a modified version of the original firmware.

Install the Serial Console
Read Add a Serial port to the PowerPC Linkstation to learn how to install the serial console.

Install nc
If you haven't installed the serial console you will need to install nc (net console) on your workstation (not on the LinkStation). This will be the most convenient way forward for most users as it is not necessary to open up or modify your LinkStation/Kurobox to use. Nc comes standard with most Linux distributions, and is also available for Windows. For more information, visit the netcat home page http://netcat.sourceforge.net or http://www.vulnwatch.org/netcat for the Windows version.

The standard pre-ompiled builds of U-Boot for the LinkStation/Kurbox assume that for  purposes you have your Pworkstation set to an IP address of 192.168.11.149 with a sub-net mask of 255.255.255.0. Any firewall should either be disabled on configured to allow  full access to the network.

If you then start  on your workstation with the following command: and then start up the LinkStation/Kurbox running U-Boot almost immediately (within seconds) you should start seeing messages from U-Boot. Many people may find it easier to store this command in a script file (Linux) or a batch file (Windows) to avoid typing it in full every time.

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/3.1.1/ppc-linux-x86/iso/ppc-2005-03-07.iso, install it and spend some time getting familiar with it.

It's a good idea to verify it's md5sum: http://ftp.sunet.se/pub/Linux/distributions/eldk/3.1.1/ppc-linux-x86/iso/MD5SUM [code]9a5e5869d8061f962274d41713b0610e ppc-2005-03-07.iso[/code]

ELDK Installation
Mount the ELDK ISO

Install at say /home/ELDK directory. And install the necssary tool chain for the PPC:

In preparation for building, export directories /home/ELDK/usr/bin, /home/ELDK/bin and /home/ELDK/ppc-linux/usr/bin as follows:

Preparation
Create the build directory and set the environment variable UBOOT_BUILD to the path to it

Download the tarball for u-boot-1.1.4 from ftp://ftp.denx.de/pub/u-boot/u-boot-1.1.4.tar.bz2 Download the LinkStation patch, u-boot-1.1.4-list-2.01.diff.gz Download the uloader module for your LinkStation / KuroBox model.


 * For the LinkStation 1 / KuroBox standard, download uloader-2.4.17.tar.gz
 * For the LinkStation HG / KuroBox HG, download uloader-2.4.20.tar.gz

Both tar files contain the same sources but the binary has been compiled against the corresponding version of the kernel.

Untar u-boot-1.1.4 and apply the patch.

Note: To use the vanilla 2.6 standard kernels (lyakh's mainline kernels) for the Linkstation 1, Linkstation HG, Kurobox Standard, Kurobox HG, one must a forward patched version of LNI's u-boot (ver 1.2.0) which contains dtc support. Please follow the directions found here: http://buffalo.nas-central.org/index.php/Kurobox_support_in_stock_2.6_kernels

Untar the uloader archive. The archive contains the source code, a binary module compiled for the original LinkStation kernel and a simple bash script to load and start a RAM build of U-Boot. The binary in uloader-2.4.17.tar.gz has been compiled against 2.4.17_mvl21-sandpoint and the binary in uloader-2.4.20.tar.gz has been compiled against 2.4.20_mvl31-ppc_linkstation. If you have a different kernel version, you may need to recompile the module for your kernel. Compiling the module requires a fully configured LinkStation kernel tree and gcc 2.95 (cross compiler).

LinkStation 1 / KuroBox standard

LinkStation HG / KuroBox HG

Source your ELDK environment

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

RAM Build
When using make be sure the version of make is 3.80

For LinkStation 1 / KuroBox standard run:

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

For LinkStation HG / KuroBox HG run:

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

Minimal Console
This port of U-Boot to the LinkStation is designed to allow some control over the boot process even in the absence of a console. For this, it uses the power button (the big button at the front) and the reset button (the small red button at the back).

When the LinkStation is switched on, the power LED starts blinking and, very quickly, it starts booting the kernel from flash. If U-Boot is installed, the power LED will change from blinking quickly to blinking very slowly. This means that U-Boot has taken over and it is counting down the boot delay before booting the kernel. The default boot delay is 10 sec. From the moment when the power LED starts blinking slowly and for the duration of the boot delay, you can control the boot process with the power and reset buttons.

The Power Button
If you push the power button and keep it pressed for more than 1 sec, the boot process will stop and the LinkStation will wait for a command. A stopped boot process is indicated by the power LED being lit solid. The effect is the same a pressing 's' on the console.

A long push of the power button acts as a toggle. If the boot delay count down is in progress, a long push of the power button stops the boot process. If the boot process is stopped (U-Boot is at the command prompt, even if you can't see it), a long push of the power button restarts the boot process resetting the boot delay to its original value.

By default U-Boot supports three pre-configured boot commands:

Please note that the original kernel for the LinkStation 1 / KuroBox standard has a bug in the function that calibrates the decrementer and it will stop for up to 180 sec during boot. This bug is not an U-Boot bug but a kernel bug which is uncovered by the fact that U-Boot activates the decrementer where the original boot loader does not. The original kernel for LinkStation HG / KuroBox HG does not suffer from the above problem. '' LinkStation / LinkStation HG owners should avoid booting in EM mode as the root password for this mode on the LinkStation is unknown. '' The original kernel for the LinkStation / KuroBox standard and for some of the earlier LinkStation HG / KuroBox HG models ignores the root argument. These models will boot normally from the on-board flash when the EM boot command is used. Read the section on EM mode if your LinkStation HG / KuroBox HG has a kernel that doesn't boot in EM mode using this boot command.
 * 1) The first boot command will attempt to load and boot a file named boot/vmlinux.UBoot from the first hard disk partition, /dev/hda1. The file can be in any of the U-Boot bootable formats but uImage is the preferred format. If the file is missing or corrupted, U-Boot will fall back to booting the original kernel from flash.
 * 2) The second boot command will boot the original kernel from flash.
 * 1) The third boot command will attempt to boot in emergency mode (EM). It does this by passing the argument root=/dev/ram0 to the kernel.

You can cycle through the boot commands with the power button.

To see which of the three commands U-Boot is going to execute, press the power button quickly. The HDD LED (the third from the top) will start blinking. The number of times the LED blinks, shows the number of the active boot command. For example, a pattern short on - short off - short on - long off, means that the boot command number 2 is active. U-Boot will repeat the blinking cycle for a total duration of about 5 sec counting from the moment the power button is released.

A short press of the power button while the HDD LED is blinking will advance the boot command to the next one.

The Reset Button
Two consoles are currently configured, the serial console and the net console. The first console is the net console (nc) and the second console is the serial console.

The reset button can be used, similarly to the power button, to switch consoles. A press on the reset button (here, it doesn't matter how long you keep the button pressed) displays the currently active console using the HDD LED. Repeatedly pressing the reset button while the HDD LED is blinking will toggle between the two consoles. The blinking pattern is different from the one showing the boot command. The pattern which shows that the second (serial) console is active is short off - short on - short off - long on. U-Boot will repeat the blinking cycle for a total duration of about 5 sec counting from the moment the reset button is released.

Load and Test
Mount the LinkStation SMB public share and copy the following files to it:

For LinkStation 1 / KuroBox standard

For LinkStation HG / KuroBox HG

Most people don't have the serial port installed and this is why the net console is the default console. If you installed the serial port, open another window and use minicom</tt> to connect to your LinkStation serial console. The serial port settings are 57600,N,8, the same as the settings used by the original Linux kernel.

The net console is the default console so you need to have nc installed. Open another window and run board/linkstation/nc.sh</tt>. To quit nc, press ^T (control-T).

Where <ip_of_your_linkstation> is CONFIG_IPADDR_LS</tt> (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. Replace lshg</tt> in the example below with the name / IP address of your LinkStation. Replace myroot</tt> with the login you created when you gained telnet access. Type the commands shown in bold below.

If you have a serial console you should see the initial U-Boot startup messages. Even if the default console is the net console, U-Boot sends startup messages to the serial port until it initialises the network controller.

Watch the net console window. After a few seconds, time needed by U-Boot to initialise the network controller and the IDE controller you should see the U-Boot messages.

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

If you want to use only the serial console, watch the power LED of your LinkStation. When it starts blinking very slowly, use the power button to stop the boot process. Wait for the power LED to go dim and press and hold the power button until the LED lights up brightly indicating that the boot process has stopped. Now press the reset button twice and you should see the U-Boot command prompt (=>) in your minicom window. You can now control U-Boot from the minicom window.

'' When using nc on the LinkStation 1 / KuroBox standard, you will notice that the console is quite unresponsive and loses characters quite often. This is due to the way U-Boot implements the net console. U-Boot calls the net console driver in the main command loop. The driver starts the network controller, and waits for a net console packet. If no packet is received within 1 msec, the driver shuts down the network controller. I have increased the the net console driver timeout from the original 1 msec to 50 msec and, as a result, the net console has become somewhat usable. If a character is not echoed back to you, it was lost. Keep typing it until you see it echoed to the screen. After a while you will get a feel of the best typing speed to minimise the character loss. ''

Once you get the U-Boot command prompt, start testing it. Read the documentation and try each command you are interested in. A very important command is flinfo</tt> which displays information about the flash chip. If the information displayed is correct for your flash, check 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.

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

For LinkStation 1 / KuroBox standard run:

The name of the resulting binary is u-boot-hd.flash.bin</tt>

For LinkStation HG / KuroBox HG run:

The name of the resulting binary is u-boot-hg.flash.bin</tt>

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.

Copy the U-Boot flash image to your LinkStation SMB share in the directory u-boot</tt>.

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

U-Boot will attempt to load the ROM build from the directory share/u-boot/</tt> 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</tt>

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:

The power LED should start blinking slowly and, if you have a serial console, you should see the U-Boot startup messages. Your LinkStation is now running U-Boot.

Flashing U-Boot from Linux
Connect to your LinkStation using either the serial port or telnet.

For LinkStation 1 / KuroBox standard run:

For LinkStation HG / KuroBox HG run:

The above commands for LinkStation HG / KuroBox HG will work on devices with the original kernel version 2.4.20 and may work on earlier devices using kernel version 2.4.17. Please check which device corresponds to the bootloader partition on your hardware.

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</tt>.

If the same happens when you attempt to install U-Boot from Linux, try to dd</tt> 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: Add a Jtag Port.

EM Mode
Once you have U-Boot installed in the on-board flash, you can boot in EM mode even if the third boot command described above doesn't work.

Stop the boot countdown by pressing 's' in your net console window and, at the U-Boot command prompt, run:

The above commands write "NGNG" to 0xFFF70000 and boot from the on-board flash. To revert to normal boot by writing "OKOK" to 0xFFF70000, run:

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

'' 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:

and change them to the values you want. Partition 0:1 means disk 0, partition 1. Obviously, you can only change the partition number. 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:

and change them to:

Change the default boot command to boot from flash
Search for the lines containing:

and change them to:

=U-Boot in action=

This section covers U-Boot in action

Standard Boot Sequence
If you have installed U-Boot as described above, and connect to it it via  to watch the default boot, and you have a suitable kernel image installed at /boot/uImage on the hard disk, you will see messages along the lines of the following:

Useful U-Boot commands
If you press ' ' and  at the appropriate point to stop U-Boot from attempting to load a kernel, then examples of commands that may prove to be useful shown below:

This will list out all the environment variables. Many of them will contain useful information as to how this particular version of U-Boot has been customised, and include preset command sequences that might be useful.

Run the commands that are stored in environment variable command It is well worth examining the environment variables for examples of commands and their syntax.

This will list the files for the /boot folder on partition 1 of an IDE drive formatted with ext2/ext3 format. This will allow you to see files on your system drive. If you used 0:3 instead of 0:1 it would look at your data partition.

Load a file (e.g. a u-boot image) into memory at the specified address. Take note of the size of the file loaded as it will be needed in other commands (converted to hex). The size will also be stored (in hex) in the ${filesize} environment variable which may be a more convenient way to reference it in later commands.

This is preset to run the following series of commands Unprotect the part of the flash to hold the u-boot loader Erase the part of the flash to hold the u-boot loader Write the image to the flash Check that the image was written correctly

Load a file (e.g. a openlink kernel image) into memory at the specified address. Take note of the size of the file loaded as it will be needed in other commands (converted to hex), and it will also be stored (in hex) in the ${filesize} environment variable. Unprotect the part of the flash to hold the kernel image Erase the part of the flash to hold the kernel image Write the kernel image to the flash Check that the kernel image was written correctly

= Links =
 * http://www.kurobox.com/revolution/bounty.html
 * Linuxdevices.com - Introduction to Das U-Boot, the universal open source bootloader
 * http://u-boot.sourceforge.net/
 * Kurobox U-Boot - using a patch English Translation written by a Japanese Kuro owner nijino. Sylver has written up instructions on the Kurobox Wiki:  HOWTO U-Boot

Forum Discussions

 * Kuro Box User Community Forum Index -> General Development : JTAG support
 * Kuro Box User Community Forum Index -> General Development : U-Boot for Linkstation HG/Kuro HG with network support
 * The NAS-Central Community Forum / Linkstation HG (ppc) / u-boot status
 * The NAS-Central Community Forum / General Development / U-Boot for LinkStation HLAN ppc available
 * The NAS-Central Community Forum / General Development / U-Boot for LinkStation HG / KuroBox HG available

Resources

 * DENX Embedded Linux Development Kit (ELDK) on-line documentation - http://www.denx.de/wiki/DULG/ELDK
 * DENX Embedded Linux Development Kit (ELDK) version 3.1.1 - http://ftp.sunet.se/pub/Linux/distributions/eldk/3.1.1/ppc-linux-x86/iso/
 * U-Boot version 1.1.4 sources - ftp://ftp.denx.de/pub/u-boot/u-boot-1.1.4.tar.bz2
 * U-Boot for the LinkStation patch version 2.01 - u-boot-1.1.4-list-2.01.diff.gz
 * Uloader version 1.0 compiled for kernel 2.4.17 -uloader-2.4.17.tar.gz
 * Uloader version 1.0 compiled for kernel 2.4.20 -uloader-2.4.20.tar.gz

Old versions

 * U-Boot for the LinkStation patch version 2.0 - u-boot-1.1.4-list-2.0.diff.gz
 * U-Boot for the LinkStation patch version 1.0 - u-boot-1.1.4-ls-hlan-1.0.diff.gz
 * Uloader version 1.0 - uloader-1.0.tar.gz
 * Installation Instructions for the LinkStation port version 1.0 - u-bootinstall_1.0.html
 * Previous version of this page - u-boot_1.0.html