===========================
     APEX Boot Loader
       FIS Driver
===========================

This README explains some of the features and implementation details
of the FIS driver.  FIS is also sometimes called the RedBoot partition
format.  This driver supports the flash partition format with an
extension that allows targets to more easily be upgraded.


Using FIS Partitions
--------------------

The form of fis partition regions is

  fis://PARTITION@OFFSET+LENGTH

Offset defaults to 0 and the length defaults to the whole length of
the partition.  Partition names are case insensitive.  The names of
the partitions may be shown with the version command.


Underlying Region
-----------------

The CONFIG_DRIVER_FIS_BLOCKDEVICE region describes the underlying
region for the FIS partitioned data.  Due to the way that the
partitions map onto flash, this region may only include the driver.
No offset or extent will be used.

As far as I know, FIS is only used on NOR flash, but there is no
reason it couldn't be used on NAND flash.  As such, there is little
reason for the underlying driver to be anything but "nor:".


Skip Descriptors
----------------

APEX supports an extension to the partition format that describes
portions of flash to be skipped over during IO.  The FIS partition
table entries are each 256 bytes long, but only 44 bytes of each is
in-use.  APEX scans the padding area for fis_skip_descriptors

  struct fis_skip_descriptor {
    char magic[4];		/* 's' 'k' 'i' 'p' */
    unsigned long offset;	/* Offset from partition start */
    unsigned long length;	/* Size of skip in bytes */
  };

The driver supports up to 4 skip descriptors per partition and they
may appear in any order and any aligned location within the padding
area.  A skip offset of zero indicates that the skip is at the
beginning of the partition.

Skip descriptors were introduced to allow one partition to overlay two
others and where the start of the second partition has bytes that are
not part of the valid data in the whole.  In the example below, the
sercomm header at the start of kernel2 is necessary to mollify RedBoot
which thinks that that address is the start of the ramdisk partition.
Essentially, RedBoot ignores the partition table and uses hard-coded
addresses for the partitions, but we want to use a kernel that is
larger than the partition size defined in RedBoot.


	       +----------------+
    kernel1 ^  | sercomm header | ^ kernel
	    |  |----------------| |
	    |  | First part of  | |
	    v  | kernel         | |
	       +----------------+ |
    kernel2 ^  | sercomm header | |
	    |  |----------------| |
	    |  | Second part of | |
	    v  | kernel         | v
	       +----------------+

The kernel partition will have a skip descriptor that skips the
SERCOMM header that appears at the start of kernel2 and allows the
following command to properly copy the whole kernel to SDRAM, skipping
both of the SERCOMM headers.

  apex> copy fis://kernel@16 $bootaddr

