vrflash - install new software on an Agenda VR handheld computer

vrflash [-l] [-r] [-s serialport] [-t tempdir] [-C] [-D] [-R] [-X] file offset ...

vrflash [-v]

vrflash [-h]

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.

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

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.

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

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.

See /usr/share/doc/vrflash/troubleshooting.txt for instructions on reporting bugs in vrflash.

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.

http://sourceforge.net/projects/agos for information about the Agenda tools, and /usr/share/doc/vrflash/*.txt for more information about VRFlash.