==================
 APEX Boot Loader
 README_overview
==================

When browsing the code, it is helpful to have an overview of the
program organization.  

Linker Script
-------------

APEX is designed to be easy to extend and port.  Much of the heavy
lifting is done by the linker.  Code and data are assigned section
names to coerce them to link in the correctl place.  To understand how
the program is assembled, start by reading the linker script. 

  src/arch-*/entry/apex.lds.S

The whole program is linked at the target virtual memory address, VMA,
which is a misnomer in this case since APEX doesn't enable the MMU.

Bootstrap
---------

Execution begin at the start of the .entry section which uses the
.bootstrap section to initialize SDRAM and move the program from
nonvolatile storage to the place where it can execute.  None of this
code uses the stack.

The whole bootstrap may be customized for a particular target.  This
is discouraged and should be unnecessary on ARM targets.  The
relocate_apex () function, for example, may be defined by the target
to replace the default relocator.  This technique is used by NAND
flash implementations since the relocation is hardware specific.


Exception Vectors
-----------------

Some rudimentary work has gone into enabling exception vectors.  The
framework is in place, but it is not know to work.  Unlike other
loaders, these vectors do *not* live at the top of the program.
Instead, APEX relocates SDRAM to 0x0 and copies the vectors there.

Services and Drivers
--------------------

Instead of using a single piece of code to call initialization
functions, APEX uses a linker section to aggregate control structures
for each service and driver.  At various times such as initialization
and cleanup, APEX scans these structures from start the finish.

Initialization ordering is guaranteed by assiging each object an
appropriate index within the group.  Drivers in the .driver.0
sub-section are guaranteed to be initialized before drivers in the
.driver.1 sub-section.  Drivers within a section are initialized in an
unpredictable order.

Memory Image
------------

APEX copies the whole of itself from non-volatile storage to SDRAM.
It depends on strings being immutable and it does not use static
variables other than those in BSS.  These assumptions allow the loader
to be copied from SDRAM directly to non-volatile storage.

