This chapter explains how to upgrade the firmware to a newer version. To determine which version of the firmware you have, watch the screen when you power up your machine. There are three major releases of firmware currently `out there': the present series (2.0.x), the old stuff (1.3), and the really old stuff (less than 1.3). Anything pre-2.0 should be updated immediately. Depending on the existing firmware version number, the process for updating will vary slightly: consult the appropriate section below.
Please note that reprogramming the firmware is an inherently dangerous activity that could potentially render your NetWinder completely inoperative. Without the firmware, a NetWinder will not be able to boot itself. Before attempting to reprogram the firmware, back up all important files and prepare yourself for the possibility of having to return your machine for repair. Needless to say, firmware upgrades are done entirely at your own risk!
In practice the flash updating process is really quite safe. Follow the directions given here and things should work out fine. If this is your first attempt to update the firmware, please read this chapter completely before you begin. If you still have problems, you can ask for help on the mailing lists or newsgroups ( news://news.netwinder.org). Statistically speaking, the likelyhood of toasting your machine is less than 1%, based on the number of units returned with dead flashes in the last year.
New versions of the firmware can be obtained anonymously from
ftp://ftp.netwinder.org/pub/netwinder/firmware/ and have filenames of
the form nettrom-X.Y.Z.bin
where X.Y.Z
is the version
number. Be sure to use binary mode when downloading the file. At the time
of this writing, the current stable nettrom version is 2.1.24. More recent
development versions can also be found elsewhere on the ftp site
(hint: look in Rod Stewart's or Andrew Mileski's directory), but beware that
these may not have been extensively tested - and you probably don't own JTAG
equipment (just thought I'd remind you).
Some of the nettrom
binaries are available with an attached
`rescue' filesystem. Especially for those people with small hard disks in
their NetWinders, this rescue filesystem is helpful for restoring or
updating the disk image. Therefore it is recommended that you use a
nettrom+rescue
image when one is available. The only times you'd
really want to use a non-rescue image is when you plan to create your own
flashroot filesystem (see the `Advanced booting' chapter for details).
You may wish to use the md5sum
command to generate a checksum of
the nettrom
image you've downloaded to ensure there were no errors
in the process. This is important because the flash writing program has no
way of knowing if the nettrom
binary is valid or not - it simply
copies the file into the flash memory. To compute the checksum, issue the
command
md5sum nettrom-2.0.X.bin
where nettrom-2.0.X.bin
should be replaced with the name of the file
you've downloaded. Very old NetWinders may not have the md5sum
program, in which case you cross your fingers and hope for the best.
Otherwise, the computed checksum should be compared against those listed in
ftp://ftp.netwinder.org/pub/netwinder/firmware/md5sums. If the
checksums don't match exactly, delete the nettrom.bin
and transfer
it again. Check that your FTP client is doing a binary transfer, not an
ASCII or text transfer.
The next step is to transfer the nettrom.bin
to the actual flash
memory chip. This is done using a program called flashwrite
, which
in turn depends on a kernel module called nwflash.o
(on older
systems, it was called flash.o
). The exact process varies slightly
depending on the age of the software on your machine; consult the
appropriate sub-section.
You must be logged in as root
to reprogram the flash, and should
not be running any unecessary programs at the time. The flash writing
process is very sensitive to timing and might fail if an interrupt occurs at
the wrong moment. Before you begin, it is suggested that you unplug any
network cables or peripherals, and terminate any active tasks. In other
words, the machine should be loaded as lightly as possible.
Once the flash writing process has been started, it should not be interrupted. Should an error be detected, it is important that you do not reboot the machine under any circumstances, since the contents of the flash memory are uncertain. Repeat the flash writing process until it succeeds. Consult the troubleshooting section, below, if any errors are encountered.
Recent disk images already contain all the tools necessary to update the
flash memory. Simply download a nettrom
binary from the ftp site
and then run the following commands to update the flash memory:
insmod nwflash flashwrite -base64 nettrom-2.0.X.bin 0
Replace nettrom-2.0.X.bin
with the name of the nettrom file you
downloaded. By convention, the nettrom
binary is normally stored
in the /boot
directory but you can put it wherever you wish -
you'll have to specify the path accordingly in the flashwrite
command. Remember that once the flashwrite has started, it must complete
successfully before you reboot the machine.
Also note that the final character in the flashwrite
command line
is a zero, not the letter `o'. This parameter specifies the offset from the
beginning of the flash memory - in this case, the data is being written to
the beginning of the flash.
The process for older machines is pretty similar to that of recent machines
(see preceeding section), except the nwflash
driver is called
flash
and it uses different major/minor numbers. The commands to
be typed are therefore:
insmod flash flashwrite -base64 nettrom-2.0.X.bin 0
The older flash driver is more susceptible to failure, so be sure to repeat
the flashwrite
command if it fails to write the whole nettrom image.
Consult the troubleshooting section below if you have any problems.
On really old machines, the flashwrite
program and the
flash
driver are not included, since they were changing so often at
that time. In this case, it is recommened that you download
nettrom-1.3pl4.tar.gz
in addition to the nettrom-2.0.X.bin
file. The tar.gz
file contains all the necessary programs for
writing the flash, along with the 1.3pl4 version of nettrom
.
This old nettrom
should be deleted and the 2.0.X version used
in its place:
tar zxvf nettrom-1.3pl4.tar.gz cd nettrom-1.3pl4 rm nettrom cp ../nettrom-2.0.X.bin nettrom.bin
Now the flash can be written in much the same manner as before. The only
difference really is that the commands are not on the normal search path, so
they must be preceded with `./
' so they can be found:
./insmod flash.o ./flashwrite -base64 nettrom.bin 0
As in the case for `older machines', this version of flashwrite is not very rubust and several tries may be necessary until the entire flash image is successfully written.
Problems during the flash writing process can be attributed to either the
insmod
or the flashwrite
commands. Obviously, a failure
in the former command will also lead to failure of the latter. If the error
message doesn't make it clear, you can use the lsmod
command to
verify what modules are loaded. If the nwflash
or flash
device is not listed, then the insmod
failed. Otherwise, check the
flashwrite
command.
Problems with insmod
fall in two categories: either the executable
cannot be found, or the flash
module can't be found. In the former
case, try including the full path, ie. /sbin/insmod
. Otherwise,
the problem is with the flash
module. Try both flash
and
nwflash
as the module name. Failing that, try looking for the
flash module with a command like find /lib/modules -name
'*flash.o'
and then use the resulting full path name as the module
name.
It's also possible to get an error from insmod
about a kernel
version mismatch. This means that the specified flash
module is
not compatible with the kernel. Check to see if any other flash
modules are available, using the find
command described above. If
not, you can try using the -f
flag to insmod
, to force
loading of the module. If all else fails, download the
nettrom-1.3pl4.tar.gz
file and consult the instructions for `Really
old machines' above.
The most common problem with flashwrite
is typing in the command
incorrectly, or not specifying the name of the nettrom.bin
file
correctly. If the nettrom.bin
file is not in the current
directory, then the relative or absolute pathname must be specified. And
following the filename, there must be a zero (as shown in the previous
section's examples).
An error message along the lines of `Can't open /dev/flash' indicates that
either the flash
module wasn't loaded correctly (you can check this
with the lsmod
command), or there is a problem with the device
entries. The proper value for the device entries depends on which module
you are using: for flash
the major/minor numbers are 101 and 0,
whereas for nwflash
the numbers are 10 and 160. To set the device
nodes up, use the following commands, substituting the appropriate numbers
for MAJOR
and MINOR
, respectively.
cd /dev rm *flash mknod -m644 flash c MAJOR MINOR ln -s flash nwflash
Any other errors from flashwrite
indicate a real problem writing to
the flash memory. If this condition persists, try loading the flash driver
with debugging turned on: first do rmmod flash
, then repeat the
insmod
command with flashdebug=1
suffixed on.
Once the flashwrite
program completes, the update is pretty much
done. Ensure that the number of bytes written matches the size of the
nettrom.bin
file you were writing. If the numbers do not match,
repeat the flashwrite process again. Otherwise, it is safe to shut down the
machine (using CTRL-ALT-DEL for example) and upon reboot the new firmware
will be active.
If you are paranoid, you can perform one more test before you reboot. The
data can be read back from the flash memory and be compared with the
original nettrom.bin
file. It's pretty unlikely for any
discrepancies to turn up, since flashwrite
already performs such
checking, but it doesn't hurt either. You need to know the size in bytes of
the nettrom.bin
file you just flashed.
dd if=/dev/nwflash of=actual.nettrom bs=1 count=BYTESIZE cmp nettrom-2.0.X.bin actual.nettrom
Replace /dev/nwflash
with /dev/flash
if you've got an
`older' system, and substitute the actual file size for BYTESIZE
.
There should be no output from the cmp
command; if there is, go
back and repeat the entire flash writing process. Keep in mind that this
test only verifies that the file was written correctly to the flash, but it
cannot protect against having an invalid file in the first place.
Now it's time to perform ancient tribal rituals (or just cross your fingers) and reboot your machine. With luck, you'll see the white banner screen with the new firmware version number displayed. Shortly thereafter you should see the `Press any key to abort autoboot' message. Getting that far indicates that your flash reprogramming was successful.
The first time you boot a new version of firmware, it is a good idea to
issue the commands load-defaults
followed by save-all
.
If you don't do this, your old settings will be preserved, but you may see a
warning message whenever you enter the firmware menu, and it is possible for
there to be some odd side-effects.
If you've just upgraded from pre-2.0 firmware, then some special
considerations apply. The default parameters in 2.0 firmware assume that
the disk is partitioned with /dev/hda1
as the root filesystem, and
that the kernel is also contained on that partition. However, the 1.3
firmware used a different setup - /dev/hda1
was a dedicated kernel
partition, and the root filesystem resided on /dev/hda2
. It is
recommeded to update to the new layout, but that is outside the scope of
this document. In order to boot the old-style layout with 2.0 firmware, the
following command sequence should be issued the first time you boot up:
load-defaults setenv kernconfig partition setenv rootdev /dev/hda2 save-all boot
It is recommended that you stop using this partition-based boot method,
since it is difficult to recover from a bad kernel. If you don't want to
repartition and re-install your whole system, you can still switch to the
new boot method. Simply install a NetWinder kernel into the /boot
directory on your system and instruct the firmware to boot it:
load-defaults setenv kernconfig fs setenv kerndev /dev/hda2 setenv kernfile /boot/vmlinux setenv rootdev /dev/hda2 save-all boot
With this setup, you can install many different kernels in /boot
and switch between them by changing the kernfile
parameter.
... Don't panic! In some cases you may still be able to rescue the machine. If the first 32 kB of flash are still intact, then it is possible to serially download a kernel and boot it. Then the flash memory can be reprogrammed again, hopefully with a working image this time!
A second computer is required, along with a null-modem cable. Such a cable can be had at most computer stores, or you can make your own (see the Serial-HOWTO for details). The cable should connect between the serial port on the NetWinder and the serial port on the rescue system.
Next, a terminal program should be launched on the rescue system. It should be configured for 19200 bps, 8 data bits, no parity, and 1 stop bit (For firmware 2.0.8h and beyond, the speed is 115200 bps). Be sure to turn off any handshaking, both hardware and software. Then turn on or reboot the NetWinder - a number of diagnostic messages should be printed on the serial terminal. If you see nothing, check the cables and the COM port settings. If you really don't get any output, then you flash is truly wrecked, and you'll have to return your machine for repair. Sorry.
Otherwise, you should see the message `Press * TWICE to abort autoboot' or similar. Some older versions of the firmware used ALT-D instead of an asterisk character. Press the appropriate key, and a Nettrom control menu will appear. You can press `?' for a brief listing of available commands.
The next step is to obtain a NetWinder kernel and put it on the rescue system. If you have older firmware and a 2.0 kernel, please skip down to the next sub-section for further instructions. The "z" option described below is also available in newer firmware versions, but the new "x" option is considerably nicer.
x c000
The firmware is now expecting a kernel to be transmitted in Xmodem format.
Use your terminal program to transmit the file (in minicom the command is
ALT-S). You may have to repeat the x
command since it times out
after a short period.
The kernel should download in about 2 minutes at 115200 bps. Once it is
done, use the command j c000
to start the kernel. If you wish to
change the root device from the default of /dev/hda1
(major 3,
minor 1), it must be done before the "j" command. Use d 100
and
note that location 110 contains 0301. Change this to the value you want
using the e 110
command.
The official 2.0.x kernels from the ftp site cannot be used directly because
they are in ELF format - but the firmware only knows how to deal with an
a.out kernel. The vmelf
utility program (
ftp://ftp.netwinder.org/pub/netwinder/kernel/misc/vmelf.c) can be
used to convert an ELF kernel into a.out form (well, close enough
anyways). Just type make vmelf
to build an executable from the
vmelf.c
source code. It's a hack.
Record the size of the kernel file - it will typically be somewhere between
870000 and 1250000 bytes. Convert the size from decimal into hexadecimal
(sorry, that's all the nettrom menu knows about) and write it down. Now, at
the Nettrom prompt, use the `z' command to load the kernel. The arguments
are two hexadecimal numbers - the first is always c000
, and the
second should be the size in hex of the kernel file. Don't include the
`0x' or `$' symbols in the size value.
z c000 HEXSIZE
Use the `upload' feature of your terminal program to actually transmit the kernel file. Notice that the file must be transmitted `plain binary', meaning that there is no protocol (like xmodem, zmodem, or kermit). It just a raw stream of bytes. This also means there is no error checking. Note that as of firmware 2.0.8, Xmodem is supported; see above for details.
The transmission will take about 10 minutes at 19200 baud. A series of asterisks will be printed as the transfer proceeds. (Yes, there is an option to change the baud rate, but it doesn't work as you would expect. It's best just to stick with the standard rate and wait. After all you should only ever need to do this once). Upon completion of the download, the Nettrom prompt should re-appear. If there is no prompt, or there are lots of extra characters after the Nettrom prompt, then something got out-of-sync during the download. In this case, you'll probably have to repeat the whole process. But it doesn't hurt to try to boot the kernel anyhow - you might get lucky. The following command will boot the kernel:
j c000
Hopefully your machine should boot up fine now, and you can go and reprogram
the firmware properly. There is no way to pass a command line to the
kernel, so the compiled-in default values will be used. Usually the
defaults are 16 megs of RAM and a root device of /dev/hda1
- this
should boot most machines. If your setup differs, you can hack different
values into the kernel file before you send it down the serial cable.
Kernels as of 990121 use a param_struct
(defined in
include/asm-arm/setup.h
) for passing in the various boot-time
parameters. It is possible to modify this structure using the Nettrom
debugger commands (type `?
' for help at the nettrom prompt). The
structure is stored at memory location 0x100.