===========================
     APEX Boot Loader
        Regions
===========================

APEX uses a common notation when describing regions of memory, data
sources, and data sinks.  While similar to the way that the kernel
refers to regions of memory, the APEX notation is not compatible with
the kernel form.

  REGION := [DRIVER:][@]START[+LENGTH]
  REGION := [DRIVER:][[//LOCATION][/PATH]][[@START][+LENGTH]]
  REGION := REGION%REGION[%REGION...]

The DRIVER is the name of an IO driver that handles the requests.
Without an explicit driver, the 'memory:' driver is the default.
Driver names may be shortened to any unambiguous prefix.  If there is
only one driver that begins with the letter 'm', then 'm:' uniquely
identifies that driver.  If there are two 'nor' drivers, APEX will
require a driver name long enough to distinguish which one to use.
The command 'drvinfo' lists the available drivers.

The START address is the beginning of the region relative to the
driver's domain.  In the case of the memory driver, this is the start
of addressable memory.  For other devices such as flash memory, the
first memory location in the device is zero.  Thus, for a flash part
mapped at 0x40000000, nor:0 to the first byte at physical address
0x40000000.

The LENGTH is a count of bytes.  It may be omitted when the length is
either self-evident or when there is a reasonable default.  For
example, when dumping a region, the default length is 64.  When
erasing flash, the default length is 1.  The marker '+' replaces the
original '#' which is deprecated though still supported.  The #
character is more useful as a comment character.

START and LENGTH may be specifed as a decimal number, a hexadecimal
number, and may followed by a suffix 'm' for for megabytes (1024*1024),
'k' for kilobytes (1024) or 's' for sectors (512).

  nor:16k+4k	 - 4096 bytes, 16384 bytes from the start of NOR flash
  nand:0	 - Starting with the first byte using the only NAND driver
  nand-eb501:0   - Starting with the first byte using a specific NAND driver

Drivers that accept pathnames, such as fat:, have an extended syntax
to allow selection of a LOCATION and a PATH.  The form of the LOCATION
depends on the driver.  The fat: driver accepts a partition number
from 1 to 4.  The PATH is a valid filesystem path.  Note that because
the descriptor may still be modified by a @START or +LENGTH modifier,
filenames may not contain '@' or '+'.

There is a further ambiguity in the region syntax where a PATH may be
present.  In the absence of either a leading '/' or '@', the parser
must choose to interpret the first word as either a path, or a
starting offset.  It does so by inspecting the first character of the
field.  If it is a number, the field is assumed to be a START value.
Otherwise, it is assumed to be a PATH.

The % special character allows merging of two or more REGION
specifiers.  This is a convenience for situations where a REGION is
composed by combining a driver with an offset and extent.  Drivers
that define a driver basis, e.g. fat and ext2, work this way.
Appending these REGION strings would require that the syntax of the
REGIONs be properly matched.  The % operator forms a REGION specifier
where the first portion is parsed and then the second.  Elements of
the region defined in the second and successive REGIONs override those
of the first.  Appending "ata://1" to "+1s" requires an intervening
"/".  Appending "ata" to "+1s" requires an intervening ":".  The '%'
operator smooths over this difference such that inserting it between
either set of REGIONSs produces a proper result, "ata://1%+1s" or
"ata%+1s".


Filesystem Drivers
------------------

The filesystem drivers such as ext2 and fat support the pathname
region form.

  [DRIVER:][[//LOCATION][/PATH]][[@START][+LENGTH]]

The LOCATION field is the MSDOS partition number, numbered from 1.
Typical usage looks like the following:

  ext2://1/boot/zImage

The START and LENGTH fields are optional and may be used to qualify
the region.  Without them, the region describes the whole file.

  ext2://1/boot/zImage@1k+32k

This refers to 32KiB of the file /boot/zImage in the first partition
starting 1KiB from the start of the file.


Partition Drivers
-----------------

The partition drivers, of which there is only the fis driver,
translate a partition name or number into a region on the source
medium.  These drivers make this translation when the region is
opened.

The FIS driver takes an underlying region covering the FIS partition
table.  The LOCATION field of an fis region is the case insensitive
name of the partition.

  fis://kernel

Like the filesystem drivers, the START and LENGTH fields are optional
and may be used to qualify the region.  Without then, the region
describes the whole partition.

