Docs: Update design guide for dynamic config

This patch updates the `firmware-design.rst` document for
changes in ARM-TF for supporting dynamic configuration features
as presented in `Secure Firmware BoF SFO'17`[1].

The patch also updates the user-guide for 2 build options for FVP
pertaining to dynamic config.

[1] https://www.slideshare.net/linaroorg/bof-device-tree-and-secure-firmware-bof-sfo17310

Change-Id: Ic099cf41e7f1a98718c39854e6286d884011d445
Signed-off-by: Soby Mathew <soby.mathew@arm.com>
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst
index c383c5d..5b99d54 100644
--- a/docs/firmware-design.rst
+++ b/docs/firmware-design.rst
@@ -77,11 +77,57 @@
 
 The sections below provide the following details:
 
+-  dynamic configuration of Boot Loader stages
 -  initialization and execution of the first three stages during cold boot
 -  specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
    AArch32) entrypoint requirements for use by alternative Trusted Boot
    Firmware in place of the provided BL1 and BL2
 
+Dynamic Configuration during cold boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each of the Boot Loader stages may be dynamically configured if required by the
+platform. The Boot Loader stage may optionally specify a firmware
+configuration file and/or hardware configuration file as listed below:
+
+-  HW_CONFIG - The hardware configuration file. Can be shared by all Boot Loader
+   stages and also by the Normal World Rich OS.
+-  TB_FW_CONFIG - Trusted Boot Firmware configuration file. Shared between BL1
+   and BL2.
+-  SOC_FW_CONFIG - SoC Firmware configuration file. Used by BL31.
+-  TOS_FW_CONFIG - Trusted OS Firmware configuration file. Used by Trusted OS
+   (BL32).
+-  NT_FW_CONFIG - Non Trusted Firmware configuration file. Used by Non-trusted
+   firmware (BL33).
+
+The Arm development platforms use the Flattened Device Tree format for the
+dynamic configuration files.
+
+Each Boot Loader stage can pass up to 4 arguments via registers to the next
+stage.  BL2 passes the list of the next images to execute to the *EL3 Runtime
+Software* (BL31 for AArch64 and BL32 for AArch32) via `arg0`. All the other
+arguments are platform defined. The Arm development platforms use the following
+convention:
+
+-  BL1 passes the address of a meminfo_t structure to BL2 via ``arg1``. This
+   structure contains the memory layout available to BL2.
+-  When dynamic configuration files are present, the firmware configuration for
+   the next Boot Loader stage is populated in the first available argument and
+   the generic hardware configuration is passed the next available argument.
+   For example,
+
+   -  If TB_FW_CONFIG is loaded by BL1, then its address is passed in ``arg0``
+      to BL2.
+   -  If HW_CONFIG is loaded by BL1, then its address is passed in ``arg2`` to
+      BL2. Note, ``arg1`` is already used for meminfo_t.
+   -  If SOC_FW_CONFIG is loaded by BL2, then its address is passed in ``arg1``
+      to BL31. Note, ``arg0`` is used to pass the list of executable images.
+   -  Similarly, if HW_CONFIG is loaded by BL1 or BL2, then its address is
+      passed in ``arg2`` to BL31.
+   -  For other BL3x images, if the firmware configuration file is loaded by
+      BL2, then its address is passed in ``arg0`` and if HW_CONFIG is loaded
+      then its address is passed in ``arg1``.
+
 BL1
 ~~~
 
@@ -261,6 +307,9 @@
 -  Enable the MMU and map the memory it needs to access.
 -  Configure any required platform storage to load the next bootloader image
    (BL2).
+-  If the BL1 dynamic configuration file, ``TB_FW_CONFIG``, is available, then
+   load it to the platform defined address and make it available to BL2 via
+   ``arg0``.
 
 Firmware Update detection and execution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -287,10 +336,10 @@
 
        "Booting Trusted Firmware"
 
-#. BL1 determines the amount of free trusted SRAM memory available by
-   calculating the extent of its own data section, which also resides in
-   trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a
-   platform-specific base address. If the BL2 image file is not present or if
+#. BL1 loads a BL2 raw binary image from platform storage, at a
+   platform-specific base address. Prior to the load, BL1 invokes
+   ``bl1_plat_handle_pre_image_load()`` which allows the platform to update or
+   use the image information. If the BL2 image file is not present or if
    there is not enough free trusted SRAM the following error message is
    printed:
 
@@ -298,18 +347,15 @@
 
        "Failed to load BL2 firmware."
 
-   BL1 calculates the amount of Trusted SRAM that can be used by the BL2
-   image. The exact load location of the image is provided as a base address
-   in the platform header. Further description of the memory layout can be
-   found later in this document.
+#. BL1 invokes ``bl1_plat_handle_post_image_load()`` which again is intended
+   for platforms to take further action after image load. This function must
+   populate the necessary arguments for BL2, which may also include the memory
+   layout. Further description of the memory layout can be found later
+   in this document.
 
 #. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at
    Secure SVC mode (for AArch32), starting from its load address.
 
-#. BL1 also passes information about the amount of trusted SRAM used and
-   available for use. This information is populated at a platform-specific
-   memory address.
-
 BL2
 ~~~
 
@@ -344,6 +390,8 @@
    EL3 Runtime Software and populate it.
 -  Define the extents of memory available for loading each subsequent
    bootloader image.
+-  If BL1 has passed TB_FW_CONFIG dynamic configuration file in ``arg0``,
+   then parse it.
 
 Image loading in BL2
 ^^^^^^^^^^^^^^^^^^^^
@@ -356,6 +404,12 @@
 platform to the next handover BL image. By default, this flag is disabled for
 AArch64 and the AArch32 build is supported only if this flag is enabled.
 
+The list of loadable images provided by the platform may also contain
+dynamic configuration files. The files are loaded and can be parsed as
+needed in the ``bl2_plat_handle_post_image_load()`` function. These
+configuration files can be passed to next Boot Loader stages as arguments
+by updating the corresponding entrypoint information in this function.
+
 SCP\_BL2 (System Control Processor Firmware) image load
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1791,32 +1845,44 @@
                | BL1 (ro) |
     0x00000000 +----------+
 
-**FVP with TSP in Trusted DRAM:**
+**FVP with TSP in Trusted DRAM with TB_FW_CONFIG and HW_CONFIG :**
 
 ::
 
-               Trusted DRAM
-    0x08000000 +----------+
-               |  BL32   |
-    0x06000000 +----------+
+                     DRAM
+    0xffffffff +--------------+
+               :              :
+               |--------------|
+               |  HW_CONFIG   |
+    0x83000000 |--------------|  (non-secure)
+               |              |
+    0x80000000 +--------------+
 
-               Trusted SRAM
-    0x04040000 +----------+  loaded by BL2  ------------------
-               | BL1 (rw) |  <<<<<<<<<<<<<  |  BL31 NOBITS   |
-               |----------|  <<<<<<<<<<<<<  |----------------|
-               |          |  <<<<<<<<<<<<<  | BL31 PROGBITS  |
-               |----------|                 ------------------
-               |   BL2    |
-               |----------|
-               |          |
-    0x04001000 +----------+
-               |  Shared  |
-    0x04000000 +----------+
+                Trusted DRAM
+    0x08000000 +--------------+
+               |     BL32     |
+    0x06000000 +--------------+
 
-               Trusted ROM
-    0x04000000 +----------+
-               | BL1 (ro) |
-    0x00000000 +----------+
+                 Trusted SRAM
+    0x04040000 +--------------+  loaded by BL2  ------------------
+               |   BL1 (rw)   |  <<<<<<<<<<<<<  |  BL31 NOBITS   |
+               |--------------|  <<<<<<<<<<<<<  |----------------|
+               |              |  <<<<<<<<<<<<<  | BL31 PROGBITS  |
+               |--------------|                 ------------------
+               |     BL2      |
+               |--------------|
+               |              |
+               |--------------|
+               | TB_FW_CONFIG |
+               |--------------|
+    0x04001000 +--------------+
+               |    Shared    |
+    0x04000000 +--------------+
+
+                 Trusted ROM
+    0x04000000 +--------------+
+               |   BL1 (ro)   |
+    0x00000000 +--------------+
 
 **FVP with TSP in TZC-Secured DRAM:**
 
@@ -1824,7 +1890,7 @@
 
                    DRAM
     0xffffffff +----------+
-               |  BL32   |  (secure)
+               |  BL32    |  (secure)
     0xff000000 +----------+
                |          |
                :          :  (non-secure)
@@ -1881,7 +1947,7 @@
 
                    DRAM
     0xFFE00000 +----------+
-               |  BL32   |  (secure)
+               |  BL32    |  (secure)
     0xFF000000 |----------|
                |          |
                :          :  (non-secure)
@@ -2663,7 +2729,7 @@
 
 --------------
 
-*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.*
+*Copyright (c) 2013-2018, ARM Limited and Contributors. All rights reserved.*
 
 .. _Reset Design: ./reset-design.rst
 .. _Porting Guide: ./porting-guide.rst
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
index 21db86b..c35c526 100644
--- a/docs/porting-guide.rst
+++ b/docs/porting-guide.rst
@@ -1076,20 +1076,16 @@
                             allocation to BL2
        meminfo.free_size  = Size of secure RAM available for allocation to BL2
 
-   BL1 places this ``meminfo`` structure at the beginning of the free memory
-   available for its use. Since BL1 cannot allocate memory dynamically at the
-   moment, its free memory will be available for BL2's use as-is. However, this
-   means that BL2 must read the ``meminfo`` structure before it starts using its
-   free memory (this is discussed in Section 3.2).
+   By default, BL1 places this ``meminfo`` structure at the beginning of the
+   free memory available for its use. Since BL1 cannot allocate memory
+   dynamically at the moment, its free memory will be available for BL2's use
+   as-is. However, this means that BL2 must read the ``meminfo`` structure
+   before it starts using its free memory (this is discussed in Section 3.2).
 
-   In future releases of the ARM Trusted Firmware it will be possible for
-   the platform to decide where it wants to place the ``meminfo`` structure for
-   BL2.
-
-   BL1 implements the ``bl1_init_bl2_mem_layout()`` function to populate the
-   BL2 ``meminfo`` structure. The platform may override this implementation, for
-   example if the platform wants to restrict the amount of memory visible to
-   BL2. Details of how to do this are given below.
+   It is possible for the platform to decide where it wants to place the
+   ``meminfo`` structure for BL2 or restrict the amount of memory visible to
+   BL2 by overriding the weak default implementation of
+   ``bl1_plat_handle_post_image_load`` API.
 
 The following functions need to be implemented by the platform port to enable
 BL1 to perform the above tasks.
@@ -1264,6 +1260,12 @@
 corresponding to ``image_id``. This function is invoked in BL1, both in cold
 boot and FWU code path, after loading and authenticating the image.
 
+The default weak implementation of this function calculates the amount of
+Trusted SRAM that can be used by BL2 and allocates a ``meminfo_t``
+structure at the beginning of this free memory and populates it. The address
+of ``meminfo_t`` structure is updated in ``arg1`` of the entrypoint
+information to BL2.
+
 Function : bl1\_plat\_fwu\_done() [optional]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 9e23711..ebca4ec 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -776,6 +776,19 @@
    for functions that wait for an arbitrary time length (udelay and mdelay).
    The default value is 0.
 
+-  ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled
+   to DTB and packaged in FIP as the HW_CONFIG. See `Firmware Design`_ for
+   details on HW_CONFIG. By default, this is initialized to a sensible DTS
+   file in ``fdts/`` folder depending on other build options. But some cases,
+   like shifted affinity format for MPIDR, cannot be detected at build time
+   and this option is needed to specify the appropriate DTS file.
+
+-  ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in
+   FIP. See `Firmware Design`_ for details on HW_CONFIG. This option is
+   similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the
+   HW_CONFIG blob instead of the DTS file. This option is useful to override
+   the default HW_CONFIG selected by the build system.
+
 Debugging options
 ~~~~~~~~~~~~~~~~~