NB: For all users of versions < V0_0_2:  Paramters have changed.  Some
options have different meanings and some now have options where before
they didn't.

YOU SHOULDN'T USE THIS PROGRAM DIRECTLY.  YOU SHOULD USE ONE OF THE
SHELL SCRIPTS DESCRIBED IN README.sh

Reflash is a system for reprogramming flash in bulk from a running
linux system.  The flash on an iPAQ holds the current kernel image (a
copy is running in RAM) and the file system.  Since we are potentially
overwriting the file system, we need to take some precautions to
ensure we don't crash and destroy the system.
First, you should run reflash-prep.sh, which kills non-essential
processes, remounts all mtdblock file systems READ ONLY and makes sure
that other bits of the reflash system are in place.

The safest thing is to download ALL data using the various -i
commands.  Then set up a queue of operations to perform on the flash,
then we send all of the commands down to the kernel module.  The
kernel module does the actual flash manipulation.  Once we enter the
kernel module and begin programming, we don't want to exit kernel mode
since that might cause us to run a process which may need a page from
the file system which is being/has been overwritten.

An example:
# insmod reflash-mod.o
# cat flash*.bin | ./reflash -O0 -o 0x0 -i 0x1000000 -w 0x1000000
# 

This example loads the module and then loads 16M of data (-i
0x1000000) from stdin to offset 0 (-o 0x0).  The reflash "program"
says: override bootldr sector protection (-O0), set offset to 0 (-o
0x0), input data into data buffer at offset set by -o (-i 0x1000000;
0x1000000 is the data len), and write data from the buffer at offset
to offset in flash (-w 0x1000000; 0x1000000 is the data len).

Here is another example that reads a kernel and a jffs2 image:
# ./reflash -E0 -o 0x80000 -e 0xf80000 -i zImage-middle-test-partition -wl -o 0x540000 -i base.jffs2 -wl

The details of the commands are given below.

reflash has a huge data buffer, which is treated as an image of the
flash to be programmed.  Offset 0 in the buffer corresponds to offset
0 in the flash. We deposit data into the buffer at the current offset,
which is set by the -o xxx command.  This command is the only thing
that changes the offset.  It does not auto increment after input or
write operations.  So we can basically seek around in the buffer and
load data into it.  

*******************************************************************
ALL DATA SHOULD BE LOADED BEFORE WRITING TO ENSURE
WE NEVER NEED TO EXIT KERNEL MODE BEFORE ALL FLASH 
PROGRAMMING IS COMPLETE.
*******************************************************************

Once the data are loaded into the buffer, we can program the flash.
All flash commands are queued up in the reflash utility and then the
entire queue is sent to the kernel module and then executed in
sequence in kernel mode.  Each command consists of a command code, the
user buffer address, the buffer len and the offset into the flash.
The current value of the offset, as set by the -o xxx command) is used
as the offset into flash and is added to the start of the buffer.  The
length is specified in each flash command.  A more complex example:

cat flash*.bin | ./reflash -O0 -o 0x0 -i 0x1000000 -o 0x40000 -w 0xfc0000 -o 0 -u 0x40000 -w 0x40000

This sequence loads up the buffer with 16M of data, seeks to just past
the bootldr (0x40000), writes to flash, seeks back to 0 (the bootldr)
unprotects the sector and then overwrites it.  This sequence
overwrites the bootldr last, hopefully minimizing the possibility of
making a brick out of your iPAQ.

If reflash detects an error while executing the queued commands, it
enters a command loop (see -c option below).  Your downloaded data is
still in the buffer.  You may be able to fix things using some other
commands.  Depending on the failure, you may or may not have a
filesystem to use.  In testing, I have been able to use NFS file
systems even after blowing away the root file system.  In the case of
zmodem downloads, it is unlikely that you'll have access to the
executable and to the named pipe that reflash uses to get data from
rz.


The basic commands:
(Option arguments can be separated from the option letter by 0 or more
spaces.  E.g. -wl is the same as -w l.  Reflash uses getopt(3).
Please refer to the manpage for complete details.)

-o <offset>	Set current offset for all subsequent commands until
		changed by another -o command.  If offset is ``+''
		then set offset to its current value plus the value of
		the persistent length.
-l <len>	Set the persistent length.  The persistent length can
		be used in commands that use a len by specifying 'l'
		or 'L' in place of a numeric length. Len can be
		specified in any standard 'C' notation.  It can also
		have a suffix that acts as a multiplier: 
		[Kk] --> x1024,
		[Mm] --> x1048576
		[Ss] --> currently set sector size (0x40000 default)
-v <len|l>	Verify buffer at current offset for length len.
-e <len|l>	Erase flash at current offset for length len.  The
		curent implementation seems to have problems is len is
		not a multiple of the flash's sector size.  Therefore
		we round the offset down to a multiple of the sector
		size and round the length up.  See -S below.
-w <len|l>	Write  buffer at current offset for length len.  If
		auto-erase is on, issue an erase command at current
		offset for length len before the write.  If
		auto-verify is on, issue a verify command at current
		offset for length len.
-u <len|l>	Unprotect sector at current offset for lenght len.
-i <len|-|file>	Input data into buffer at current offset.  
		If len is -, read stdin till EOF.  
		If len is a number, read len
		bytes from stdin into the buffer. 
		If len begins with "@rz" then reflash starts
		up a zmodem session to download the data.  Only one
		file can be ownloaded at a time.  If @rz is followed
		by /<filename> (e.g. @rz/zImage) then reflash will
		only accept the filename specified.  If any other file
		is sent, then zmodem  will exit with an error and you
		will be prompted to try again.
		If len is none of the above then it is assumed to be a
		file name. The file is opened and read till EOF. 
		The persistent length is set unless a length is
		specified. 
-r		Do not reset the module's command queue, preserving any
		previous, unexecuted commands. It must be the first
		command or else it is ignored.
-O onoff	Override the offset restriction allowing us to program
		the bootldr region.  0 -> off, !0 -> on.
		On by default.
-V onoff	Set auto-verify after write on or off. 0 -> off, !0 -> on.
		On by default.
-E onoff	Set auto-erase before write on or off. 0 -> off, !0 -> on.
		On by default.
-c file		Read commands from a file.  If file is '-', then enter
		an interactive command loop and read commands until
		EOF.  Commands consist of the corresponding option
		character (no dash) and the optional argument.
		If file is a file, then commands must be specified one
		per line.  Lines beginning with '#' are comments, and
		blank lines are ignored. 
-Q onoff	Set quietude: be vewy vewy qwiet (if 1).
-C		Clear the command queue.
-q		Query the current status.  Display current set
		parameters and display the command queue.
-W num		Set the word MASK.  This affects lengths and offsets.
		They are bitwise ANDed with this mask and a fatal
		error is generated if the value is not aligned.  Set
		to 0 to override.
-S len		Set sector length. Default is 0x40000
-p <len|l>	Protect the region at offset for the give len.
-u <len|l>	Unprotect the region at offset for the give len.
-a nbytes	Make reflash print a period (''.'') every nbytes when
		reading input.
-R		DO NOT Rebooot the system after successfully executing
		the command queue.  Normally, reflash reboots
		automatically after it is done.
-y		Automatically answer yes to all prompts (-P command).
-N level	Set noisiness of system (verbosity).
-F dir		Set name of directory where we find the ZMODEM
		communication FIFOs.
-P prompt	Prompt for continuation.  Print prompt and wait for
		input. ``y'' continues execution, ``n'' causes program
		to exit.  If prompt is ``-'' then print a default
		prompt message.
-m msg		Print the message.  Good for giving instructions.
-X		Execute command queue,
-x		Exit immediately.  Do not pass go, do not collect
		$200.  This is useful for testing.  NB: Any flash
		commands you may have issued will remain in the
		module's queue.  Use the -r option to preserve them on
		the next invocation of reflash.  Otherwise, they are
		deleted when reflash starts up.
-= var val	Set var to val.  Can only be used in scripts (-c x). 


Some esoteric and testing commands:
-t len		Fill buffer at current offset with a test pattern.
-b num		Set test_base, the first number in the test pattern,
		to num.
-d num		Put num into buffer at current offset + data offset.
		Data offset auto increments (offset DOES NOT).
-D off		Set data offset (see -d num)
-f file		Set name of file in /proc to use to communicate to
		module.
-n size		Resize main buffer to size.  Default is 16M.  You must
		do this before putting any data into the buffer and
		before issuing any flash commands.
-h <len|l>	Hexdump the buffer at the current offset.
-j		Do a join by waiting for any spawned processes to
		complete. 
-s cmd		Spawn a process.
-X		Execute the current work queue.
