Notes on configuring network flash download and upload support in the
Stargate bootloader.  The various "load" and "upload" commands have been
modified to take an optional filename parameter when appropriate.  That
filename is the filename on a TFTP server to read or write.  For downloading
the flash partitions the commands are:

	load bootldr [ filename ]
	load params [ filename ]
	load kernel [ filename ]
	load root [ filename ]

for uploading, just replace "load" with "upload".

The main hook in the code is CONFIG_NETWORK which should be set to 1 in
config.mk.  Comment this line out if you want the non-network version
(shrinks bootloader from ~100KB to ~77KB).

HOW TO DOWNLOAD WITH TFTP:

1. Put the flash images out on your TFTP server.

The code is hardwired to download from /tftpboot/stargate, and any specified
filename is relative to that.  By default the filenames used are "bootldr",
"params", "zImage", and "root.jffs2" respectively.  You only need to put out
the files you plan to download, it is not necessary to have all of the files
present.

2. Configure the Stargate with network parameters.

   You can configure the IP parameters either manually or with DHCP.
   Either way you will first need to assign a MAC address to the Stargate.
   At the boot loader prompt:

	set macaddr 10:00:00:01:02:03
	params save
	loadmacaddr

   This sets the address, saves it to the flash parameter area and loads the
   chip with the indicated address.  You will only need to do this once.
   After this, every reboot will automatically load the MAC from flash and
   program the chip.

   If you want to manually setup your IP info something like:

	set ipaddr 192.168.1.2
	set netmask 255.255.255.0
	set gateway 192.168.1.1
	set serverip 192.168.1.3
	set netcfg manual
	params save

   where the first three are the usual address, netmask and default gateway
   as appropriate for your network.  "serverip" is the address of the TFTP
   server.  It does not need to be on the same network as the Stargate.
   Again, you should only need to do this once.

   If you want to use DHCP instead, do this:

	set netcfg dhcp
	params save

   only once.  The bootloader will automatically DHCP if needed whenever
   you attempt to TFTP a file.  If you want to make sure DHCP works you
   can do:

	ipconfig

   This will DHCP and set all the parameters.  If you wanted to, you could
   then do a "params save" to make the DHCP-provided params permanent.

3. Download via TFTP.

   Once you have all the IP parameters setup, you declare your intent to
   use TFTP with:

	set loadmethod tftp

   when "loadmethod" is not set, or is set to "xmodem", the load command
   will continue to use xmodem on the serial port for downloading.  Again
   you can do "params save" to make this permanent.  Now you just do the
   usual:

	load kernel

   (or "load bootldr" or "load root").  Buried at the end of the output for
   the TFTP transaction is a checksum:

	Loaded 634596 bytes
	BSD checksum: 48172

   which you can compare with a "sum" of the corresponding files on the server.
   Note that the bootldr image has an embedded checksum (which is verified
   after the download and before writing flash) and sum'ing the file should
   give a value of 0.

Sorry this is all so complicated right now.  At this early stage I wanted
to keep as much as possible off the default boot path to avoid turning your
Stargate into a brick due to some idiosyncrasy in the network code or
your network configuration.


UPLOADING WITH TFTP:

1. Prepare your TFTP server.

   Make sure your TFTP server allows uploading of files.  Some, like
   hpa-tftp, only allow you to write to existing files.  So make sure
   the correct options are given or that the correct files exist in
   /tftpboot/stargate and are world writable.  The default filenames
   for the four flash partitions are: "bootldr.bak", "params.bak",
   "zImage.bak" and "root.jffs2.bak".  Again, if you use the optional
   filename, it will be relative to /tftpboot/stargate.

2. Configure the Stargate with network parameters.

   Same as for downloading.

3. Upload via TFTP.

   Make sure your loadmethod parameter is set to TFTP.  Then use the
   upload command with optional filename argument.  Note that the upload
   saves the entire partition which is typically larger than the image
   you originally downloaded.  So don't expect the sizes or checksums
   of the uploaded files to necessarily match those of the download.


RECIPES:

1. You want to continue down loading with xmodem but want to fix your
   MAC address for Linux:

   One time only:
	set macaddr <MAC-addr>
	params save
	loadmacaddr

2. You want to download with TFTP using static IP information set once:

   One time only:
	set macaddr <MAC-addr>
	set ipaddr <IP-addr>
	set netmask <IP-addr>
	set gateway <IP-addr>
	set serverip <IP-addr>
	set loadmethod tftp
	set netcfg manual
	params save
	loadmacaddr

   Every reboot:
	load <bootldr|kernel|root>

3. You want to download with TFTP using dynamic IP information provided
   every time by DHCP:

   One time only:
	set macaddr <MAC-addr>
	set loadmethod tftp
	set netcfg dhcp
	params save
	loadmacaddr

   Every reboot:
	load <bootldr|kernel|root>

4. Your network is already configured and you want to save your current
   flash partitions before you screw something up:

        upload bootldr bootldr-20031207.bak
	upload params params-20031207.bak
	upload kernel zImage-20031207.bak
	upload root root.jffs2-20031207.bak


SOURCE STRUCTURE:

In the main directory, all changes are ifdefed with CONFIG_NETWORK.
The bulk of the network code is in the libnet subdirectory.  The
subdirectories under that, are pretty much lifted straight from the
current armboot CVS tree (http://cvs.sourceforge.net/viewcvs.py/armboot/)
which is different from their latest official release (armboot-1.1).
In libnet itself are various "glue" files to make the code work in the
Stargate bootloader environment.

I included the armboot versions of all the string and memory operations
because I was starting to run into problems with alignment assumptions
in the glibc versions in the cross-build environment.

BTW, I have only built this with GCC 3.2.


Mike Hibler
mike@cs.utah.edu
12/04/2003