Merge pull request #184 from jcastillo-arm/jc/tf-issues/100

FVP: make usage of Trusted DRAM optional at build time

3 files changed, 97 insertions, 34 deletions

diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 23cae19..e98c4fa 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -955,22 +955,95 @@ PROGBITS sections then the resulting binary file would contain a bunch of zero
 bytes at the location of this NOBITS section, making the image unnecessarily
 bigger. Smaller images allow faster loading from the FIP to the main memory.
 
-On FVP platforms, we use the Trusted ROM and Trusted SRAM to store the trusted
-firmware binaries.
+On FVP platforms, we use the Trusted ROM, Trusted SRAM and, optionally, Trusted
+DRAM to store the trusted firmware binaries and shared data.
+
+ *    A 4KB page of shared memory is used to store the entrypoint mailboxes
+      and the parameters passed between bootloaders. The shared memory can be
+      allocated either at the top of Trusted SRAM or at the base of Trusted
+      DRAM at build time. When allocated in Trusted SRAM, the amount of Trusted
+      SRAM available to load the bootloader images will be reduced by the size
+      of the shared memory.
 
  *    BL1 is originally sitting in the Trusted ROM at address `0x0`. Its
       read-write data are relocated at the top of the Trusted SRAM at runtime.
+      If the shared memory is allocated in Trusted SRAM, the BL1 read-write data
+      is relocated just below the shared memory.
 
  *    BL3-1 is loaded at the top of the Trusted SRAM, such that its NOBITS
       sections will overwrite BL1 R/W data.
 
  *    BL2 is loaded below BL3-1.
 
- *    The TSP is loaded as the BL3-2 image at the base of the Trusted SRAM. Its
-      NOBITS sections are allowed to overlay BL2.
+ *    The TSP is loaded as the BL3-2 image at the base of either the Trusted
+      SRAM or Trusted DRAM. When loaded into Trusted SRAM, its NOBITS sections
+      are allowed to overlay BL2. When loaded into Trusted DRAM, an offset
+      corresponding to the size of the shared memory is applied to avoid
+      overlap.
 
 This memory layout is designed to give the BL3-2 image as much memory as
-possible. It is illustrated by the following diagram.
+possible when it is loaded into Trusted SRAM. Depending on the location of the
+shared memory page and the TSP, it will result in different memory maps,
+illustrated by the following diagrams.
+
+** Shared data & TSP in Trusted SRAM (default option): **
+
+               Trusted SRAM
+    0x04040000 +----------+
+               |  Shared  |
+    0x0403F000 +----------+  loaded by BL2  ------------------
+               | BL1 (rw) |  <<<<<<<<<<<<<  |  BL3-1 NOBITS  |
+               |----------|  <<<<<<<<<<<<<  |----------------|
+               |          |  <<<<<<<<<<<<<  | BL3-1 PROGBITS |
+               |----------|                 ------------------
+               |   BL2    |  <<<<<<<<<<<<<  |  BL3-2 NOBITS  |
+               |----------|  <<<<<<<<<<<<<  |----------------|
+               |          |  <<<<<<<<<<<<<  | BL3-2 PROGBITS |
+    0x04000000 +----------+                 ------------------
+
+               Trusted ROM
+    0x04000000 +----------+
+               | BL1 (ro) |
+    0x00000000 +----------+
+
+
+** Shared data & TSP in Trusted DRAM: **
+
+               Trusted DRAM
+    0x08000000 +----------+
+               |          |
+               |  BL3-2   |
+               |          |
+    0x06001000 |----------|
+               |  Shared  |
+    0x06000000 +----------+
+
+               Trusted SRAM
+    0x04040000 +----------+  loaded by BL2  ------------------
+               | BL1 (rw) |  <<<<<<<<<<<<<  |  BL3-1 NOBITS  |
+               |----------|  <<<<<<<<<<<<<  |----------------|
+               |          |  <<<<<<<<<<<<<  | BL3-1 PROGBITS |
+               |----------|                 ------------------
+               |   BL2    |
+               |----------|
+               |          |
+    0x04000000 +----------+
+
+               Trusted ROM
+    0x04000000 +----------+
+               | BL1 (ro) |
+    0x00000000 +----------+
+
+** Shared data in Trusted DRAM, TSP in Trusted SRAM: **
+
+               Trusted DRAM
+    0x08000000 +----------+
+               |          |
+               |          |
+               |          |
+    0x06001000 |----------|
+               |  Shared  |
+    0x06000000 +----------+
 
                Trusted SRAM
     0x04040000 +----------+  loaded by BL2  ------------------
@@ -988,8 +1061,8 @@ possible. It is illustrated by the following diagram.
                | BL1 (ro) |
     0x00000000 +----------+
 
-The TSP image may be loaded in Trusted DRAM instead. This doesn't change the
-memory layout of the other boot loader images in Trusted SRAM.
+Loading the TSP image in Trusted DRAM doesn't change the memory layout of the
+other boot loader images in Trusted SRAM.
 
 Each bootloader stage image layout is described by its own linker script. The
 linker scripts export some symbols into the program symbol table. Their values
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index db2bad8..eb3b86d 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -150,31 +150,6 @@ file is found in [plat/fvp/include/platform_def.h].
     Defines the total number of nodes in the affinity heirarchy at all affinity
     levels used by the platform.
 
-*   **#define : TZROM_BASE**
-
-    Defines the base address of secure ROM on the platform, where the BL1 binary
-    is loaded. This constant is used by the linker scripts to ensure that the
-    BL1 image fits into the available memory.
-
-*   **#define : TZROM_SIZE**
-
-    Defines the size of secure ROM on the platform. This constant is used by the
-    linker scripts to ensure that the BL1 image fits into the available memory.
-
-*   **#define : TZRAM_BASE**
-
-    Defines the base address of the secure RAM on platform, where the data
-    section of the BL1 binary is loaded. The BL2 and BL3-1 images are also
-    loaded in this secure RAM region. This constant is used by the linker
-    scripts to ensure that the BL1 data section and BL2/BL3-1 binary images fit
-    into the available memory.
-
-*   **#define : TZRAM_SIZE**
-
-    Defines the size of the secure RAM on the platform. This constant is used by
-    the linker scripts to ensure that the BL1 data section and BL2/BL3-1 binary
-    images fit into the available memory.
-
 *   **#define : BL1_RO_BASE**
 
     Defines the base address in secure ROM where BL1 originally lives. Must be
diff --git a/docs/user-guide.md b/docs/user-guide.md
index ccb07df..532236a 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -133,6 +133,8 @@ the build system doesn't track dependency for build options. Therefore, if any
 of the build options are changed from a previous build, a clean build must be
 performed.
 
+#### Common build options
+
 *   `BL30`: Path to BL3-0 image in the host file system. This image is optional.
     If a BL3-0 image is present then this option must be passed for the `fip`
     target
@@ -205,6 +207,19 @@ performed.
     synchronous method) or 1 (BL3-2 is initialized using asynchronous method).
     Default is 0.
 
+#### FVP specific build options
+
+*   `FVP_SHARED_DATA_LOCATION`: location of the shared memory page. Available
+    options:
+      - 'tsram' (default) : top of Trusted SRAM
+      - 'tdram' : base of Trusted DRAM
+
+*   `FVP_TSP_RAM_LOCATION`: location of the TSP binary. Options:
+      - 'tsram' (default) : base of Trusted SRAM
+      - 'tdram' : Trusted DRAM (above shared data)
+
+For a better understanding of FVP options, the FVP memory map is detailed in
+[Firmware Design].
 
 ### Creating a Firmware Image Package
 
@@ -327,11 +342,11 @@ The Firmware Package contains this new image:
 
 On FVP, the TSP binary runs from Trusted SRAM by default. It is also possible
 to run it from Trusted DRAM. This is controlled by the build configuration
-`TSP_RAM_LOCATION`:
+`FVP_TSP_RAM_LOCATION`:
 
     CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
     BL33=<path-to>/<bl33_image>                               \
-    make PLAT=fvp SPD=tspd TSP_RAM_LOCATION=tdram all fip
+    make PLAT=fvp SPD=tspd FVP_TSP_RAM_LOCATION=tdram all fip
 
 
 ### Checking source code style