Category:How to - Network Boot

Overview

Network booting can be very convenient during the development cycle for an embedded device. Current Gumstix Overos have a bootloader and kernel ready for network booting if you have an expansion board with an ethernet connector. Older Gumstix Overos can upgrade their version of u-boot to get support for network booting. This procedure also works for Verdex-Pro boards although all the text and links refer to Overo.

The procedures that follow are for setting up a workstation to act as both the tftp server and the nfs server to host the root file system.

The procedure described does not require a dhcp server.

Setup

The following procedure assumes a Linux workstation to host all the services. The workstation for the example is running Ubuntu 9.10.

There are multiple ways to configure the nfs server and the tftpd server. This example tries to keep it simple.

The names of the packages may be different if you are using another Linux distribution.

The example will use the following network configuration.

Workstation IP: 192.168.4.4

Gumstix IP: 192.168.4.50

You will also need a Gumstix Overo kernel and rootfs on the workstation.

You can either build one yourself or download one here.

I'll assume an omap3-console-image custom built with OE located in the standard location. Any image will work though.

Packages

Install the following Ubuntu packages on the workstation

tftp-hpa

nfs-common

nfs-kernel-server

portmap

Create a root filesystem

Create and populate the /exports directory with a kernel and a root filesystem

sudo mkdir -p /exports/overo
sudo tar -C /exports/overo -xvjf ${OVEROTOP}/tmp/deploy/glibc/images/overo/omap3-console-image-overo.tar.bz2

Configure the tftp server

Edit /etc/default/tftpd-hpa

RUN_DAEMON="yes"
OPTIONS="-l -s /exports/overo/boot"

What we are doing here is pointing the tftp daemon at the Gumstix root filesystem we created above. The uImage kernel image sits here.

$ ls -all /exports/overo/boot/*
lrwxrwxrwx 1 root root      13 2010-01-13 11:50 /exports/overo/boot/uImage -> uImage-2.6.32
-rw-r--r-- 1 root root 3147516 2010-01-10 11:12 /exports/overo/boot/uImage-2.6.32

Configure the nfs server

Add the following line to /etc/exports

/exports/overo	192.168.4.50(rw,no_root_squash,no_subtree_check)

This tells the nfs server what directories to export as an nfs mountpoint and what machines have access to it. Use man exports to get the documentation for /etc/exports.

Restart the servers

sudo /etc/init.d/tftpd-hpa restart
sudo service portmap restart
sudo /etc/init.d/nfs-kernel-server

Configure u-boot

Establish a serial console connection with the gumstix.

Power the gumstix unit and hit a key to stop the process in uboot.

Add some environment variables to u-boot.

Overo # setenv ipaddr 192.168.4.50
Overo # setenv netmask 255.255.255.0
Overo # setenv serverip 192.168.4.4
Overo # setenv gatewayip 192.168.4.1
Overo # setenv hostname overo

Overo # setenv ip ${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:eth0:none
Overo # setenv nfsroot /exports/overo
Overo # setenv nfsargs setenv bootargs console=\${console} root=/dev/nfs rootfstype=nfs ip=\${ip} nfsroot=\${nfsroot} rootwait
Overo # setenv loadnfskernel tftp \${loadaddr} uImage

Save what you've entered in the u-boot environment so far. None of these variables are used by the default boot process so there will be no booting behavior changes yet.

Overo # saveenv

Testing

The next step is to test the network boot by running each step manually. Later we will modify u-boot to run this automatically.

1. First tftp load the kernel into the overo memory

Overo # print loadaddr
loadaddr=0x82000000

Overo # tftp ${loadaddr} uImage
smc911x: detected LAN9221 controller
smc911x: phy initialized
smc911x: MAC 00:15:c9:28:c1:78
Using smc911x-0 device
TFTP from server 192.168.4.4; our IP address is 192.168.4.50
Filename 'uImage'.
Load address: 0x82000000
Loading: T ######################################################
           ######################################################
           ######################################################
           #####################################################
done
Bytes transferred = 3147516 (3006fc hex)

Okay, if that worked, make sure the loadnfskernel variable we created doesn't have a typo by running the same process again using the u-boot run command.

Overo # run loadnfskernel

You should get the same results, a kernel tftp loaded into memory.

If it did not work, use a network monitoring tool like tcpdump or wireshark to see if you are getting any traffic.

See the Notes section for some troubleshooting tips.

2. Test the loading of the boot arguments.

Overo # print bootargs
## Error: "bootargs" not defined
Overo # print nfsargs
nfsargs=setenv bootargs console=${console} root=/dev/nfs rootfstype=nfs ip=${ip} nfsroot=${nfsroot} rootwait
Overo # run nfsargs
Overo # print bootargs
bootargs=console=ttyS2,115200n8 root=/dev/nfs rootfstype=nfs ip=192.168.4.50:192.168.4.4:192.168.4.1:255.255.255.0:overo:eth0:none nfsroot=/exports/overo rootwait

Make sure that bootargs looks correct.

3. Boot the kernel

With a kernel of the correct format loaded into memory, the u-boot command bootm will transfer control of the processor to this kernel.

Overo # bootm ${loadaddr}

...normal kernel boot messages here, then...
net eth0: SMSC911x/921x identified at 0xd08c8000, IRQ: 336
IP-Config: Complete:
    device=eth0, addr=192.168.4.50, mask=255.255.255.0, gw=192.168.4.1,
    host=overo, domain=, nis-domain=(none),
    bootserver=192.168.4.4, rootserver=192.168.4.4, rootpath=
Looking up port of RPC 100003/2 on 192.168.4.4
Looking up port of RPC 100005/1 on 192.168.4.4
VFS: Mounted root (nfs filesystem) on device 0:13.
Freeing init memory: 928K
INIT: version 2.86 booting
...
The Angstrom Distribution overo ttyS2
Angstrom 2009.X-test-20100110 overo ttyS2
overo login:

Making it automatic

So if everything worked and you want to boot this way every time you need to modify the bootcmd u-boot variable.

Reboot the gumstix and hit a key to stop it in u-boot again.

Overo # print bootcmd
bootcmd=if mmc init; then if run loadbootscript; then run bootscript; else if run loaduimage; then run mmcboot; else run nandboot; fi; fi; else run nandboot; fi

You may want to save this for the future or see the Notes section for where it is defined in the build.

Make a new bootcmd using the u-boot environment variables that we created.

Overo # setenv bootcmd echo Booting nfs ...\; run loadnfskernel\; run nfsargs\; bootm \${loadaddr}

Overo # saveenv

Now reboot and the gumstix should nfsboot by default.

Overo # reset

Notes

1. The default u-boot environment variables are defined in the u-boot source tree under include/configs/omap3-overo.h

2. The documentation for linux kernel parameters for nfs booting can be found in the linux source tree under Documentation/filesystems/nfsroot.txt and Documentation/kernel-parameters.txt.

3. tftp listens over udp on port 69

$ grep tftp /etc/services
tftp		69/udp

You can check if it is listening with the following command.

$ netstat -an | grep udp
udp        0      0 0.0.0.0:111             0.0.0.0:*                          
udp        0      0 0.0.0.0:880             0.0.0.0:*                          
udp        0      0 0.0.0.0:39921           0.0.0.0:*                          
udp        0      0 0.0.0.0:56957           0.0.0.0:*                          
udp        0      0 0.0.0.0:2049            0.0.0.0:*                          
udp        0      0 0.0.0.0:59435           0.0.0.0:*                          
udp        0      0 0.0.0.0:69              0.0.0.0:*                          

4. nfs listens on port 2049 both tcp and udp. The nfs root process uses only udp.

$ grep nfs /etc/services
nfs		2049/tcp			# Network File System
nfs		2049/udp			# Network File System

5. The following is a tcpdump command for watching the gumstix boot traffic. Choose the appropriate interface for your workstation.

$ sudo tcpdump -i eth1 -l -n udp

6. A cross-over ethernet cable connected between the workstation and the gumstix works well if you can't host services on your regular network. You may want to check before starting a tftp server on a shared network. A dedicated switch/hub will also work to keep things isolated.

7. You can check for running firewall rules with this command

$ sudo iptables --list
Chain INPUT (policy ACCEPT)
target     prot opt source               destination         
Chain FORWARD (policy ACCEPT)
target     prot opt source               destination         
Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination       

If you get output different then this (nothing running) and you are having problems booting, then you should ensure you are not blocking any of the required traffic.

8. I removed the kernel parameters for the kernel display configuration for wiki formatting reasons. You should add the settings you require to the bootcmd variable in the example.

9. There is a patch to u-boot in the current gumstix overo-oe tree that improves the ethernet network speeds on the overos. You can save about 10 seconds on an nfs boot using a u-boot built with this patch as well as get better ethernet performance after booting. When you do a network boot without a microSD card, you are using the u-boot on the NAND flash which was probably built without this patch. Build a newer version of u-boot following the standard build procedures. (U-boot is built whenever you build an image.) Then copy it to NAND using the instructions here.

10. If the gumstix seems unwilling to connect to your NFS server, ensure you've enabled NFS options in your kernel. You'll need to include (directly, not as modules) CONFIG_NFS_FS, CONFIG_ROOT_NFS, CONFIG_NET_ETHERNET, and, the appropriate Ethernet chip driver, in my case, CONFIG_SMC911X.