Interface Between Boot Code and Application Code
------------------------------------------------

o There are two independent pieces of code involved in the virtex4
  booting process: the "boot code" will be loaded into readonly (from
  the powerPC perspective) BRAM along with the FPGA fabric from xilinx
  Platform Flash.  This code will in turn load the samsung flash
  "application" image selected by a hardware dipswitch (in the case of a
  hard reset) or the image selected by the transfer control register
  defined by MEH (in the case of a soft reset).

o The format of the application image in the samsung flash is not
  currently defined, but the most straightforward option would be a
  direct copy of the memory after the elf-executable has been loaded.

o All flash related mtdcr/mfdcr instructions will be located
  in the readonly BRAM.  This a partial, but certainly not bulletproot,
  protection mechanism for the flash.

o The publicly exported flash control functions will be

  unsigned readFile(unsigned fileNum);
  unsigned readPage(unsigned pageNum);
  unsigned readPageNoECC(unsigned pageNum);
  unsigned writePage(unsigned pageNum);
  unsigned imageSelect(unsigned imageNum);
  unsigned eraseBlock(unsigned blockNum);

  where "page" is the smallest possible data transfer unit that
  can be transferred to and from flash, and "block"
  is the larger size that the chip uses to erase memory.

o Return values will be 0 if the operation is successful, otherwise
  it will return a non-zero error code to be specified by the boot code.

o Application code will call the flash control functions using a
  well-known pointer to an agreed-upon structure of jump instructions
  (i.e. PowerPC unconditional "B" branch instructions).  These jump
  instructions will transfer control to the "real" BRAM-based routines.

o The boot code will poll to determine when flash operations are
  completed.  Application code will have the same behaviour, since
  it calls the boot code for flash operations.  This isn't as efficient
  as an interrupt-driven interface, but it simplifies 

o Transfer control from boot code to application code will be done
  with a branch to the transfer address defined by MEH in his
  file-system description.  At the time of the branch, the processor
  should be in a state identical to the one after soft-reset described
  in the xilinx document "PowerPC Processor Reference Guide".  We can't
  do a soft-reset directly because the powerPC first-instruction address
  is in write protected BRAM, so we can't do a write to that address.

o Application code is responsible for managing re-entrancy issues
  associated with the flash filesystem.

o Application code is responsible for ensuring that the image-number
  selected by the dipswitch is always usable, so that control of the
  system is not lost.

Application Code File System Interface
--------------------------------------

Application code is responsible for maintaining the flash
file/directory structure, including the list of bad-blocks.  The boot
code will have knowledge of the filesystem structure, however, since
it needs to use the readFile function in the powerPC booting process.

unsigned status readfile(fileNum, memAddr);
unsigned status readfile(fileNum, memAddr, offset, size); /* read in chunks */

unsigned status writefile(fileNum, memAddr, size);
unsigned status writefile(fileNum, memAddr, size, bootoptions);
unsigned status extendfile(fileNum, memAddr, size); /* write in chunks */

unsigned status filesize(fileNum, &size);
unsigned status deletefile(fileNum);
unsigned status allocatefile(&fileNum);
unsigned status imageSelect(imagenum);

unsigned status format(&badBlockList);

bootoptions = flags,loadaddr,xferaddr

The "format" function will be hidden from the public interface, since
it will only be used once to initialize the flash filesystem.

Possible later additions to File System Interface:
--------------------------------------------------

Right now all of these feel like overkill for our particular application:

o add seek(offset)/read(offset)/write(offset)
o could do readelf for more efficient executable storage.  would require
  some elf-awareness on eric's side which is perhaps too cumbersome.
o could do RTEMS official filesystem driver
o could abstract the idea of memAddr above, and instead pass a class
  that could read a file from, for example, a network.