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

A workstation running Ubuntu 9.10 is used for the example.

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

There are multiple ways to configure the nfs server and the tftpd server. This is just one method.

Here is the network configuration.

Workstation IP: 192.168.4.4

Gumstix IP: 192.168.4.50

You will also need a Gumstix Overo 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

Disable inetd control of tftpd which is the default for Ubuntu. Either comment the line in /etc/inetd.conf that references tftpd by adding a # to the start of the tftp line

# tftp  dgram  udp  wait  root  /usr/sbin/in.tftpd  /usr/sbin/int.tftpd -s /var/lib/tftpboot

or if you don't need inetd for any other service, which a Ubuntu desktop install typically doesn't, disable inetd completely this way

sudo mv /etc/rc2.d/S20openbsd-inetd /etc/rc2.d/s20openbsd-inetd 

See the NOTES(1) section.

Edit /etc/default/tftpd-hpa

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

What we are doing is pointing the tftp daemon at the Gumstix root filesystem we created above so that it will find the uImage kernel that sits there.

$ 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 restart

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 default, so the boot behavior is still unchanged.

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. The format of the ip kernel command line argument is found in the kernel documentation under filesystems/nfsroot.txt

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. tftp and inetd. You can use inetd to run tftp if you want. Just edit the -s option for tftp appropriately in /etc/inetd.conf

tftp  dgram  udp  wait  root  /usr/sbin/in.tftpd  /usr/sbin/in.tftpd -s /exports/overo/boot

and instead of this restart command

sudo /etc/init.d/tftpd-hpa restart

use this one

sudo /etc/init.d/openbsd-inetd restart

And finally, prevent tftpd-hpa from starting by

sudo mv /etc/rc2.d/S20tftpd-hpa /etc/rc2.d/s20tftpd-hpa

2. The default u-boot environment variables for the overo are defined in the u-boot source tree under include/configs/omap3-overo.h if you wanted to customize or go back to defaults.

3. 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.

4. 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:*                          

5. 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

6. 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

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

8. 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.

9. 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.

10. 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.

11. 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.