NAME
vrflash - install new software on an Agenda VR handheld computer
SYNOPSIS
vrflash [-l] [-r] [-s serialport] [-t tempdir] [-C] [-D] [-R] [-X] file
offset ...
vrflash [-v]
vrflash [-h]
DESCRIPTION
VRFlash is a utility for flashing software such as kernels and root
images to the Agenda VR (a handheld computer that runs Linux). VRFlash
communicates with the Agenda’s boot monitor (PMON) over a serial line.
It takes image you specified as the file argument and uploads it to the
Agenda, where it is stored in dynamic RAM. When the upload is
complete, VRFlash directs the PMON to store the image in flash memory
at the specified offset.
The offset argument can have the special values
kernel - default kernel offset
romdisk or rootdisk - default root image offset
pmon - default boot loader offset
cramfs - default root image offset when using cramfs
or it can be specified as a hexadecimal offset starting with 0x.
Multiple files and offsets can be specified in pairs. vrflash will
upload each of them in the order they are given.
Flash procedure:
1. Make sure the Agenda has a fresh set of batteries. Flashing
takes a long time and uses a lot of power.
2. Make a backup of the user information on the Agenda, if needed.
3. Connect the Agenda to your computer’s serial port, using the
QuickSync cable.
4. Start vrflash with the options you need.
5. Reset the Agenda by pressing the button at the back (below the
battery case). vrflash will respond to the PMON’s boot prompt
and start the procedure.
OPTIONS
-h Show usage information.
-l Capture traffic on the serial port to ./capture.log.
-r Restart the Agenda after loading.
-s serial port
The serial device to open. The default is ttyS0. The device
must be in /dev.
-t tempdir
Use tempdir as the temporary directory for split files. The
default is /tmp.
-v Show version and usage information.
-C Option for experts to disable the kernel/romdisk size check.
Normally vrflash refuses to upload a kernel or romdisk that is
too large to fit in the space reserved for it in the default
Agenda memory map. With the -C option you can upload oversize
images, which will probably not work unless you made special
arrangements.
-D Option for experts to disable the PMON overwrite check.
Normally vrflash refuses to upload images that would overwrite
the Agenda’s boot monitor, because damage to the boot monitor
could make further flashing impossible. You can use this option
if you with to replace the boot monitor, but be aware that that
has a significant chance of turning your Agenda into a
paperweight.
-R Restore defaults after flashing. This clears the user
information area of the Agenda, and is often a necessary step
before using a new kernel and root image. It erases all the
user information such as contacts and to-do entries, so make
sure you have a backup.
-X Do not load xmodem-load.srec. Normally vrflash first uploads
xmodem code to the Agenda (into RAM) to speed up the rest of the
transfer. This step can be skipped if you know the code is
already there from a previous vrflash command.
NOTES
VRFlash expects the images to be in straight binary format. Sometimes
images are distributed in SREC format, in which case you must first
convert them with a command like:
mipsel-linux-objcopy -Isrec -Obinary file.srec file
Make sure the serial device is free for VRFlash’s use. Minicom or pppd
(or any other serial application) should not be running.
EXAMPLES
Suppose you want to install a kernel image ’vmlinux’ and a root image
’romdisk’, and your Agenda is connected to serial port /dev/ttyS1, and
you want to capture all the input and output to ./capture.log, and then
you want to restart the Agenda with the new kernel and root image.
This can be done with the vrflash command:
vrflash -s ttyS1 -l -r ./vmlinux kernel ./romdisk romdisk
TROUBLESHOOTING
If you run into trouble, try some of the following things:
Check your command line. Especially check the offset you provided.
The number of zeroes in the offset field is easy to get wrong.
Make sure that nothing else is running on the serial port. Common
culprits include minicom and pppd.
If your command is right, try running vrflash again. Sometimes the
PMON prompt is left in such a state that VRFlash can’t cope on startup.
Running it a second time almost always fixes this.
Power off your Agenda, and use minicom to get to the PMON prompt. Then
exit minicom and run your vrflash command.
Make sure you load xmodem-load.srec at least once after each reset of
your Agenda. Do this by not using the -X option.
Check the permissions on the serial port. You need read and write
access. On Debian systems you can do this by adding yourself to the
tty group in /etc/group, and then logging in again or running newgrp.
BUGS
See /usr/share/doc/vrflash/troubleshooting.txt for instructions on
reporting bugs in vrflash.
AUTHOR
The primary author is Jeff Carneal. See /usr/share/doc/vrflash/THANKS
for others.
This manual page was provided by Richard Braakman <dark@xs4all.nl>,
with text based on existing documentation.
SEE ALSO
http://sourceforge.net/projects/agos for information about the Agenda
tools, and /usr/share/doc/vrflash/*.txt for more information about
VRFlash.
11 December 2002 vrflash(1)