README

Build:
The boot ROM code can only be built under Linux. Tested build environment is
Ubuntu 14.04.

Environment setup:
The boot ROM build environment is similar to the firmware build for Toshiba
Bridge chip. Please follow
    https://github.com/projectara/Firmware-wiki/wiki/Software-Setup
to setup the build environment.

To build the code, do:
    ./configure <chip_name>
    make

The <chip_name> defaults to "es3tsb" if not specified. This is for the official
ES3 Toshiba UniPro Bridge chips (both APBridge and GPBridge).

Other available configurations include:
    es2tsb  - to build image to run on ES2 chip (in workram)
    fpgatsb - to build image to run on HAPS board, with ES3 FPGA bits

Description:
When the boot ROM starts, it is supposed to setup the environment and load
second stage firmware image from either SPI flash or UniPro.

The image file to be loaded, either from SPI flash or UniPro, is packed into
TFTF file format. The TFTF file format describes each section of data/code in
the second stage firmware, including the location and length of each section.
The TFTF file format also includes signature of the second stage firmware, to
be verified against the root public key built into the boot ROM.

When loading image from SPI flash, there is also FFFF involved. FFFF stands for
Flash Format For Firmware. It works as a "partition table" of the SPI flash,
the boot ROM use it to locate the second stage firmware (in TFTF format) on the
SPI flash.
There is a FFFF table at the very beginning of the SPI flash, and a (supposely)
identical copy of it at the beginning of next erase block of the SPI flash.
The duplicated FFFF tables are used to provide a way to go back to the original
FFFF table if one of the copy got corrupted during image updating.

Memory map (workram):
     ------------------------------------
    | 0x1002FFFF | workram end           |
     ------------------------------------
    | 0x1002FF30 | communication area    |
     ------------------------------------
    |    ...     | stack                 |
     ------------------------------------
    |    ...     | ...                   |
     ------------------------------------
    | 0x1002D000 | .data section         |
     ------------------------------------
    |     ...    | open for 2nd stage FW |
     ------------------------------------
    | 0x10000000 | workram start         |
     ------------------------------------


ES2 vendor/product ids:
We can't read ES2 vendor/product id specific DME attributes. In order to
differentiate module vendors on the same ARA system, we pass user-defined set of
vendor product ids to the AP over firmware protocol. These ids are passed as
arguments to the ./configure command.

./configure es2tsb <vendor-id> <product-id>

After which you can follow general compilation steps. This will affect only ES2
and the greybus core sends firmware request to get vid/pid, only for ES2 chips.